{"_id":"@alemm12/testkit","name":"@alemm12/testkit","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@alemm12/testkit","version":"0.1.0","description":"Typed client for reading variantry tests (PostHog multivariate feature flags) in browser and server apps.","license":"MIT","author":{"name":"Alejandro Matta Morales"},"repository":{"type":"git","url":"git+https://github.com/alejandromattamorales-wq/testkit.git"},"type":"module","sideEffects":false,"publishConfig":{"access":"public"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./browser":{"types":"./dist/browser.d.ts","import":"./dist/browser.js","require":"./dist/browser.cjs"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.js","require":"./dist/server.cjs"}},"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","lint":"eslint .","test":"vitest run","prepublishOnly":"npm run typecheck && npm run lint && npm run test && npm run build"},"dependencies":{"posthog-js":"^1.406.2","posthog-node":"^5.46.0"},"devDependencies":{"@eslint/js":"^10.0.1","@types/node":"^22","eslint":"^10.7.0","tsup":"^8.5.1","typescript":"^5","typescript-eslint":"^8.64.0","vitest":"^4.1.10"},"engines":{"node":">=20.20.0"},"_id":"@alemm12/testkit@0.1.0","gitHead":"9e1057cf9113792b6b3285f576ef004abf80e4fb","bugs":{"url":"https://github.com/alejandromattamorales-wq/testkit/issues"},"homepage":"https://github.com/alejandromattamorales-wq/testkit#readme","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-jiWF4YvNG4qhqxCx43jsGjci5qnDPL0cYLN9495KFJYMl9nA4RTsdxQSgw35YvfaUo7O+ER1LPtKFmgfv2bpQg==","shasum":"4820a6345eaba38db6cfe60b317676cce0b901ca","tarball":"https://registry.npmjs.org/@alemm12/testkit/-/testkit-0.1.0.tgz","fileCount":21,"unpackedSize":22963,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICiGsdgbAJWYmYSHzu3lWz6wscfAzRexkxPwRjoDpoKIAiAou5etMZeTwonNLEhp805qVTO0GSEQzlOFlt6rUmNonQ=="}]},"_npmUser":{"name":"alemm12","email":"alejandro.matta.morales@gmail.com"},"directories":{},"maintainers":[{"name":"alemm12","email":"alejandro.matta.morales@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/testkit_0.1.0_1784686880853_0.4312284806708937"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-22T02:21:20.707Z","0.1.0":"2026-07-22T02:21:20.978Z","modified":"2026-07-22T02:21:21.193Z"},"maintainers":[{"name":"alemm12","email":"alejandro.matta.morales@gmail.com"}],"description":"Typed client for reading variantry tests (PostHog multivariate feature flags) in browser and server apps.","homepage":"https://github.com/alejandromattamorales-wq/testkit#readme","repository":{"type":"git","url":"git+https://github.com/alejandromattamorales-wq/testkit.git"},"author":{"name":"Alejandro Matta Morales"},"bugs":{"url":"https://github.com/alejandromattamorales-wq/testkit/issues"},"license":"MIT","readme":"# @alemm12/testkit\n\nTyped client for reading **tests** authored in [variantry](https://github.com/alejandromattamorales-wq/variantry) at runtime, in browser or server apps.\n\nvariantry is a UI for defining tests as PostHog multivariate feature flags — each variant gets a rollout percentage and a typed set of fields (booleans, text, numbers, arrays, objects). testkit is the other half: a small typed wrapper so a consuming app (e.g. soldoutcr) doesn't have to know it's PostHog underneath, or hand-roll `getFeatureFlagResult` calls and untyped payloads.\n\nThis is a standalone package — it does not depend on [eventlens](https://github.com/alejandromattamorales-wq/eventlens) (analytics: track/identify/errors) or on variantry itself. If an app also uses eventlens, testkit initializes its own separate PostHog client rather than sharing eventlens's.\n\n## Install\n\n```sh\nnpm install @alemm12/testkit\n```\n\n## Browser\n\n```ts\nimport { createBrowserTestClient } from \"@alemm12/testkit/browser\";\n\nconst testkit = createBrowserTestClient({\n  apiKey: \"phc_...\",\n  apiHost: \"https://us.i.posthog.com\", // optional, this is the default\n});\n\ninterface CheckoutFields {\n  headline: string;\n  showBanner: boolean;\n}\n\ntestkit.onReady(() => {\n  const result = testkit.getTest<CheckoutFields>(\"checkout-redesign\");\n  if (result?.variant === \"treatment\" && result.payload) {\n    // result.payload is typed as CheckoutFields\n  }\n});\n```\n\nCall `createBrowserTestClient` once during app startup (e.g. a root layout/provider) — later calls reuse the same underlying PostHog instance. `onReady` fires once flags have loaded (and again on reload); calling `getTest` before that returns `undefined`. Call `reset()` on logout to clear the local distinct ID.\n\n## Server\n\n```ts\nimport { createServerTestClient } from \"@alemm12/testkit/server\";\n\nconst testkit = createServerTestClient({ apiKey: \"phc_...\" });\n\nconst result = await testkit.getTest<CheckoutFields>(userId, \"checkout-redesign\");\nif (result?.variant === \"treatment\" && result.payload) {\n  // ...\n}\n\n// Before the process exits (e.g. end of a serverless handler):\nawait testkit.shutdown();\n```\n\nServer clients have no persisted identity, so `getTest` always takes an explicit `distinctId` — the user (or session) the test is being evaluated for.\n\n## What `getTest` returns\n\n```ts\ninterface TestResult<T> {\n  key: string;\n  enabled: boolean;\n  variant: string | undefined;\n  payload: T | undefined;\n}\n```\n\nThis mirrors PostHog's own flag-evaluation result, not variantry's authoring-time model — at runtime you only ever see the variant that was picked for this user and its payload, never the other variants or their rollout percentages. The `T` type parameter is a type assertion, not runtime validation: it's on you to keep it in sync with the fields you defined for that test in variantry.\n\n## Development\n\n```sh\nnpm install\nnpm run typecheck\nnpm run lint\nnpm run test\nnpm run build\n```\n","readmeFilename":"README.md","_rev":"1-5548cd7fc0e20ee06aec47ab7129ebc3"}