From 92b0fffe939ad0401f914e416f082eec77f9b434 Mon Sep 17 00:00:00 2001 From: bntvllnt Date: Mon, 18 May 2026 07:46:22 +0200 Subject: [PATCH 1/2] docs: backfill release readiness files --- AGENTS.md | 52 ++++++++++++++++++ CHANGELOG.md | 28 ++++++++++ CONTRIBUTING.md | 67 +++++++++++++++++++++++ SECURITY.md | 33 ++++++++++++ llms-full.txt | 140 ++++++++++++++++++++++++++++++++++++++++++++++++ llms.txt | 59 ++++++++++++++++++++ 6 files changed, 379 insertions(+) create mode 100644 AGENTS.md create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md create mode 100644 llms-full.txt create mode 100644 llms.txt diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5a08e6e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,52 @@ +# Agent Instructions + +These instructions apply to the entire `vllnt/analytics` repository. + +## Scope + +`@vllnt/analytics` is a lightweight, privacy-first TypeScript analytics package with consent management and React integration. + +## Safety rules + +- Do not release, tag, publish to npm, merge, or announce without explicit maintainer approval. +- Do not change `package.json` version as part of ordinary docs, tests, or implementation work. +- Do not commit secrets, tokens, customer data, private URLs, or internal operating notes. +- Preserve privacy-first behavior: consent checks, Do Not Track handling, SSR safety, and no default external analytics vendor dependency. + +## Development commands + +Use pnpm 9.x. + +```bash +pnpm install --frozen-lockfile +pnpm lint +pnpm exec tsc --noEmit +pnpm test:once +``` + +## Repository map + +- `src/analytics.ts`: core analytics singleton, queueing, identity, page/event/tutorial tracking helpers. +- `src/consent.ts`: consent storage, cookie parsing, Do Not Track detection, consent constructors and validators. +- `src/react.tsx`: React provider and consent hooks. +- `src/types.ts`: public TypeScript types. +- `src/__tests__/`: Vitest coverage for analytics, consent, React, exports, and SSR safety. +- `.github/workflows/ci.yml`: pull-request quality gates. +- `.github/workflows/publish.yml`: canary and manual release workflow. Treat this as release-critical. + +## Release-readiness gate + +Before any PR that prepares release work is merged or any publish/tag action is run, attach this gate with current evidence: + +```json +{ + "branch": "vllnt-oss", + "tenant": "releases", + "aor_fit": true, + "context_read": true, + "evidence_attached": true, + "opsec_checked": true, + "safe_for_next_step": true, + "blocking_findings": [] +} +``` diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..18a03f1 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,28 @@ +# Changelog + +All notable changes to `@vllnt/analytics` are documented in this file. + +This project follows npm package versions and uses GitHub Releases for published release notes. Public release work must pass a maintainer release-review gate before any tag, publish, or announcement. + +## [0.1.1] - 2026-05-18 + +### Fixed + +- Use the configured release checkout token for the release workflow so protected-branch release commits can be created by automation. + +### Release readiness + +- Latest npm tag: `0.1.1`. +- Canary npm tag at the time of this backfill: `0.1.1-canary.106d5aa`. +- Git tag: `v0.1.1`. + +## [0.1.0] - 2026-05-18 + +### Added + +- Published the initial `@vllnt/analytics` package baseline extracted from the VLLNT monorepo. +- Added privacy-first analytics primitives, consent helpers, React provider/hooks, SSR-safe storage/cookie utilities, and tutorial tracking helpers. +- Added test coverage, public package metadata, and CI/publish workflows. + +[0.1.1]: https://github.com/vllnt/analytics/releases/tag/v0.1.1 +[0.1.0]: https://github.com/vllnt/analytics/releases/tag/v0.1.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..83a2f98 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,67 @@ +# Contributing to @vllnt/analytics + +Thanks for helping improve `@vllnt/analytics`. + +This package is a small, privacy-first TypeScript library. Keep changes focused, easy to review, and safe for public npm consumers. + +## Development setup + +1. Install pnpm 9.x. +2. Install dependencies: + +```bash +pnpm install --frozen-lockfile +``` + +3. Run the local quality gates before opening a pull request: + +```bash +pnpm lint +pnpm exec tsc --noEmit +pnpm test:once +``` + +## Pull requests + +- Branch from `main` for ordinary changes. +- Use focused branches such as `docs/...`, `fix/...`, `feat/...`, or `test/...`. +- Keep public documentation, tests, and examples in sync with behavior changes. +- Do not include secrets, customer data, private URLs, or internal operating notes. +- Do not bump `package.json` versions, create git tags, publish to npm, or announce releases from a normal PR. + +## Release-review gate + +Before any release PR is merged, tagged, published, or announced, a maintainer must explicitly review the release readiness evidence: + +```json +{ + "branch": "vllnt-oss", + "tenant": "releases", + "aor_fit": true, + "context_read": true, + "evidence_attached": true, + "opsec_checked": true, + "safe_for_next_step": true, + "blocking_findings": [] +} +``` + +A passing gate means the change is in the VLLNT OSS release-readiness area of responsibility, relevant context has been read, evidence is attached, public-opsec has been checked, and there are no known blocking findings. It does not by itself authorize publishing; release dispatch remains a separate maintainer action. + +## Coding guidelines + +- Prefer TypeScript types over runtime ambiguity. +- Keep browser APIs guarded so SSR imports remain safe. +- Preserve consent-first behavior and Do Not Track handling. +- Avoid adding analytics vendor dependencies to the core package. +- Add or update Vitest coverage for behavior changes. + +## Reporting issues + +Open a GitHub issue with: + +- the package version, +- runtime/framework details, +- expected behavior, +- actual behavior, +- a minimal reproduction when possible. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..ce3dd28 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,33 @@ +# Security Policy + +`@vllnt/analytics` is a public npm package for consent-aware analytics helpers. Security reports should be handled privately before public disclosure. + +## Supported versions + +| Version | Supported | +| --- | --- | +| `0.1.x` | Yes | + +## Reporting a vulnerability + +Please report suspected vulnerabilities through GitHub private vulnerability reporting for this repository when available: + +https://github.com/vllnt/analytics/security/advisories/new + +If private vulnerability reporting is unavailable, open a minimal public issue that says a private security report is needed, without exploit details or sensitive data. + +## Scope + +Security-sensitive areas include: + +- consent persistence and cookie parsing, +- SSR/browser boundary handling, +- user identity and trait handling, +- event queuing behavior, +- package publishing/provenance workflow integrity. + +## Disclosure expectations + +- Do not publicly disclose exploit details until maintainers have had time to investigate and release a fix. +- Include reproduction steps, affected versions, expected impact, and any suggested mitigation. +- Never include real user data, private customer data, tokens, cookies, or credentials in a report. diff --git a/llms-full.txt b/llms-full.txt new file mode 100644 index 0000000..b0d39ea --- /dev/null +++ b/llms-full.txt @@ -0,0 +1,140 @@ +# @vllnt/analytics full context + +`@vllnt/analytics` is a lightweight, privacy-first analytics package with consent management and React integration. It is designed for applications that want a small analytics abstraction without taking a hard dependency on a vendor SDK. + +## Package metadata + +- npm package: `@vllnt/analytics` +- Repository: https://github.com/vllnt/analytics +- License: MIT +- Type: ESM TypeScript package +- Current package version in `package.json`: `0.1.1` +- Peer dependency: `react ^18.0.0 || ^19.0.0` +- Package manager: `pnpm@9.15.4` + +## Public exports + +The root export, `@vllnt/analytics`, re-exports: + +### Analytics functions + +- `initAnalytics(config)`: initialize the singleton analytics state. +- `track(name, properties?)`: track a custom event. +- `trackPage(properties?)`: track a page view. +- `identify(userId, traits?)`: attach user identity and traits after initialization. +- `resetAnalytics()`: clear in-memory identity and traits. +- `enableAnalytics(config)`: enable analytics after consent is granted. +- `disableAnalytics()`: block tracking and clear queued events after consent is revoked. +- `isAnalyticsEnabled()`: report whether tracking is initialized and unblocked. +- `getAnalyticsState()`: inspect advanced/debug state. + +### Tutorial/content tracking helpers + +- `trackTutorialStart(properties)` +- `trackSectionView(properties)` +- `trackSectionComplete(properties)` +- `trackTutorialComplete(properties)` +- `trackTutorialNavigation(properties)` +- `trackTimeSpent(properties)` + +These helpers emit typed tutorial event names such as `tutorial_start`, `tutorial_section_view`, `tutorial_section_complete`, `tutorial_complete`, `tutorial_navigation`, and `tutorial_time_spent`. + +### Consent functions and constants + +- `CONSENT_VERSION` +- `CONSENT_STORAGE_KEY` +- `CONSENT_COOKIE_NAME` +- `loadConsent()` +- `saveConsent(state)` +- `clearConsent()` +- `createAcceptAllConsent()` +- `createDeclineAnalyticsConsent()` +- `updateConsentCategory(current, category, value)` +- `needsRePrompt(consent, currentVersion)` +- `getConsentFromCookie(cookieString)` +- `isDoNotTrackEnabled()` +- `isStorageAvailable()` +- `isValidConsentState(value)` + +### Types + +- `AnalyticsConfig` +- `AnalyticsEvent` +- `ConsentCategory` +- `ConsentState` +- `TutorialEventName` +- `TutorialEventProperties` +- `UseConsentOptions` +- `UseConsentReturn` + +The React subpath, `@vllnt/analytics/react`, exports: + +- `AnalyticsProvider` +- `useAnalytics()` +- `useConsent(options?)` +- `initAnalytics` convenience re-export + +## Behavior model + +1. Browser-only tracking functions return early during SSR. +2. Initialization checks Do Not Track first. +3. Initialization then checks stored consent; declined analytics blocks tracking. +4. Events fired before initialization are queued. +5. Once analytics initializes, queued events are flushed. +6. Consent utilities store state in localStorage and mirror analytics consent as a one-year cookie for SSR detection. +7. Consent versions allow applications to re-prompt by increasing the version. +8. Functional consent cannot be disabled through `updateConsentCategory`. + +## Privacy posture + +The package intentionally avoids a default external analytics dependency. `sendEvent` is the central integration point where an application can wire a custom backend, Vercel Analytics, Google Analytics, or another destination. The React provider coordinates consent and initialization but does not override Do Not Track or declined consent. + +## Repository map + +- `src/index.ts`: public root exports. +- `src/analytics.ts`: singleton state, event queueing, initialization, custom/page/tutorial tracking, identity, reset, enable/disable logic. +- `src/consent.ts`: consent state validation, localStorage/cookie persistence, Do Not Track detection, version re-prompt checks. +- `src/react.tsx`: client React provider and hooks. +- `src/types.ts`: public TypeScript definitions. +- `src/__tests__/analytics.test.ts`: analytics behavior tests. +- `src/__tests__/consent.test.ts`: consent behavior tests. +- `src/__tests__/exports.test.ts`: export-surface tests. +- `src/__tests__/react.test.tsx`: React provider/hook tests. +- `src/__tests__/ssr.test.ts`: SSR safety tests. +- `vitest.config.ts`: Vitest configuration. +- `eslint.config.js`: ESLint configuration using `@vllnt/eslint-config`. +- `.github/workflows/ci.yml`: pull-request lint, typecheck, and test gates. +- `.github/workflows/publish.yml`: canary publishing on main pushes affecting package files and manual release publishing via workflow dispatch. + +## Development commands + +```bash +pnpm install --frozen-lockfile +pnpm lint +pnpm exec tsc --noEmit +pnpm test:once +pnpm test:coverage +``` + +## Release and opsec notes + +- Ordinary changes must not bump the package version. +- Release tags and npm publishing must only happen through approved release workflow actions. +- The manual release workflow bumps `package.json`, commits, tags, publishes to npm with provenance, and creates a GitHub Release. +- Public docs must not include secrets, private customer data, private URLs, or internal operating mechanics. +- Release-preparation work must carry the VLLNT OSS release-review gate before merge, tag, publish, or announcement. + +## Release-review gate template + +```json +{ + "branch": "vllnt-oss", + "tenant": "releases", + "aor_fit": true, + "context_read": true, + "evidence_attached": true, + "opsec_checked": true, + "safe_for_next_step": true, + "blocking_findings": [] +} +``` diff --git a/llms.txt b/llms.txt new file mode 100644 index 0000000..98b4673 --- /dev/null +++ b/llms.txt @@ -0,0 +1,59 @@ +# @vllnt/analytics + +> Lightweight, privacy-first analytics with consent management and React integration. + +This file helps AI coding tools and documentation systems understand the public package surface. For full context, see `llms-full.txt`. + +## Project + +- Package: `@vllnt/analytics` +- Repository: https://github.com/vllnt/analytics +- License: MIT +- Runtime: TypeScript ESM package +- Peer dependency: React `^18.0.0 || ^19.0.0` +- Package manager: pnpm 9.x + +## Install + +```bash +pnpm add @vllnt/analytics +``` + +## Public entry points + +- `@vllnt/analytics`: core analytics and consent APIs. +- `@vllnt/analytics/react`: React provider and hooks. + +## Main capabilities + +- Consent-aware event tracking with pre-initialization queueing. +- Page-view, identity, reset, and tutorial/content tracking helpers. +- Consent persistence in localStorage plus SSR-readable cookie state. +- Do Not Track detection. +- SSR-safe guards around browser APIs. +- React `AnalyticsProvider`, `useAnalytics`, and `useConsent` helpers. + +## Important files + +- `README.md`: install, usage examples, API summary. +- `CHANGELOG.md`: public package history. +- `CONTRIBUTING.md`: development and release-review expectations. +- `SECURITY.md`: vulnerability reporting policy. +- `AGENTS.md`: repository instructions for AI/code agents. +- `src/index.ts`: root exports. +- `src/analytics.ts`: analytics singleton and tracking helpers. +- `src/consent.ts`: consent state utilities. +- `src/react.tsx`: React integration. +- `src/types.ts`: public types. + +## Local quality gates + +```bash +pnpm lint +pnpm exec tsc --noEmit +pnpm test:once +``` + +## Release safety + +Do not tag, publish, merge release work, bump versions, or announce releases without explicit maintainer approval and a release-review gate. From c49aa87c53b98e77fbc7bc2a7038f02d6ad12362 Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Tue, 19 May 2026 01:45:27 +0200 Subject: [PATCH 2/2] docs: correct analytics release dates --- CHANGELOG.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 18a03f1..a298d98 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ All notable changes to `@vllnt/analytics` are documented in this file. This project follows npm package versions and uses GitHub Releases for published release notes. Public release work must pass a maintainer release-review gate before any tag, publish, or announcement. -## [0.1.1] - 2026-05-18 +## [0.1.1] - 2026-03-10 ### Fixed @@ -15,8 +15,9 @@ This project follows npm package versions and uses GitHub Releases for published - Latest npm tag: `0.1.1`. - Canary npm tag at the time of this backfill: `0.1.1-canary.106d5aa`. - Git tag: `v0.1.1`. +- Release date reflects the public npm publish timestamp and GitHub Release publication date. -## [0.1.0] - 2026-05-18 +## [0.1.0] - 2026-03-05 ### Added