@davidlee49/launchgate 0.0.0-stage → 0.5.1

package/API.md

@@ -0,0 +1,417 @@
+# API reference — `@davidlee49/launchgate`
+
+Every export, by entry point. The README explains *why* the pieces are shaped this way; this file
+says exactly what each one takes and returns. Types are TypeScript as declared in `src/`.
+
+- [`@davidlee49/launchgate`](#davidlee49launchgate) — the core: registry, resolver, sources, route gate, audit, signing, testing
+- [`@davidlee49/launchgate/next`](#davidlee49launchgatenext) — the Next.js adapter (optional peer `next >= 15`)
+
+The core imports nothing from Node: it runs unchanged on Cloudflare Workers, Node 18+, and the edge
+runtime. Signing uses Web Crypto.
+
+---
+
+## `@davidlee49/launchgate`
+
+### Vocabulary (types)
+
+#### `FlagValue`
+
+```ts
+type FlagValue = boolean | string | number;
+```
+
+What a flag resolves to. Boolean is the common case, not the only one.
+
+#### `FlagDef<T extends FlagValue = FlagValue>`
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `fallback` | `T` | **Required.** The value when no source decides, *and* when a source throws. Per flag, never global: a work-in-progress gate fails to `false`, a kill switch on a shipped feature fails to `true`. |
+| `description` | `string` | **Required.** Why the flag exists. |
+| `overridable` | `boolean` | May a signed visitor cookie force this flag? Default `false`. Only `cookieOverride` reads it. |
+| `byEnv` | `Record<string, T>` | Per-environment value, read by `envDefault`. |
+| `retired` | `Retirement<T>` | Terminal state. Present means: resolve to `retired.value`, consult **no** source, not even `envOverride`. |
+| `[projectField]` | `unknown` | Any extra fields a project wants (`stage`, `tier`, `owner`). The registry keeps their real types; a `Source` sees them as `unknown`. |
+
+**Typing note.** `fallback: false` is widened to `boolean`; strings and numbers keep the declared
+type, so `fallback: "v1" as "v1" | "v2"` gives a checked union at every call site.
+
+#### `Retirement<T>`
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `since` | `string` | `YYYY-MM-DD`, required. The cleanup clock `auditRegistry` reads. |
+| `value` | `T` | What every evaluation returns from now on — the disposition record. Not the same thing as `fallback`. |
+
+#### `FlagRegistry`
+
+```ts
+type FlagRegistry = Record<string, FlagDef>;
+```
+
+#### `FlagValueOf<T extends FlagRegistry, K extends keyof T>`
+
+The resolved type of flag `K` in registry `T` (`boolean` for boolean fallbacks, the declared type
+otherwise). Internal to the typing of `resolve`; exported for consumers who type their own helpers.
+
+#### `EvaluationContext`
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `targetingKey` | `string?` | Who is being evaluated — user id, org id, device id. Optional by design: anonymous visitors have none. |
+| `cookie` | `(name: string) => string \| undefined` | Reads a request cookie. Supplied by a framework adapter (`requestContext` in `/next`). Absent means "no cookies here". |
+| `[key]` | `unknown` | Anything a project-supplied source needs. |
+
+The context **object identity** is the per-request cache key for `subjectStore`. Build one per
+request and pass the same object to every `resolve` / `resolveAll` call in that request.
+
+`Context` is a deprecated alias (renamed in 0.3.0 to match OpenFeature).
+
+#### `Decision`
+
+```ts
+type Decision = FlagValue | undefined;
+```
+
+A source's answer. `undefined` means *undecided — ask the next source*. `false` is a decision.
+
+#### `FlagMeta`
+
+```ts
+interface FlagMeta { key: string; def: FlagDef }
+```
+
+What a source receives: the flag's key and its definition (erased to `FlagDef`).
+
+#### `Source`
+
+```ts
+interface Source {
+  readonly name: string;                                           // reported to onError
+  decide(flag: FlagMeta, ctx: EvaluationContext): Decision | Promise<Decision>;
+}
+```
+
+One link in the chain. Return a value to decide, `undefined` to pass. Throwing aborts the flag to
+its `fallback` (see `createResolver`).
+
+#### `SourceErrorInfo`
+
+```ts
+interface SourceErrorInfo { flag: string; source: string }
+```
+
+---
+
+### Registry and resolver
+
+#### `defineFlags(flags)`
+
+```ts
+function defineFlags<T extends FlagRegistry>(flags: T): T
+```
+
+Identity at runtime. Exists to infer each flag's value type so `resolve()` is typed at the call
+site. The registry lives in the project that reads the flags.
+
+#### `createResolver(options)`
+
+```ts
+function createResolver<T extends FlagRegistry>(options: ResolverOptions<T>): Resolver<T>
+
+interface ResolverOptions<T> {
+  flags: T;
+  sources: Source[];                                   // consulted in order; first definite answer wins
+  onError?: (error: unknown, info: SourceErrorInfo) => void;
+}
+```
+
+Resolution order for one flag:
+
+1. **Unknown key** → throws `Error("launchgate: unknown flag …")`. The only thing that throws; a
+   programming error the types prevent everywhere but an unchecked cast.
+2. **`def.retired` present** → returns `retired.value`. No source runs.
+3. Each source in order:
+   - throws → `onError(error, { flag, source })`, return `def.fallback`. It does **not** fall
+     through to the next source.
+   - returns `undefined` → next source.
+   - returns a value of the wrong type (`typeof` differs from `fallback`) → `onError` with a
+     `TypeError`, return `def.fallback`.
+   - returns a value → that is the answer.
+4. Nothing decided → `def.fallback`.
+
+Recommended source order: `envOverride`, `cookieOverride`, project sources (grants, opt-in,
+entitlement), `envDefault`.
+
+#### `Resolver<T>`
+
+```ts
+interface Resolver<T extends FlagRegistry> {
+  resolve<K extends keyof T & string>(key: K, ctx?: EvaluationContext): Promise<FlagValueOf<T, K>>;
+  resolveAll(ctx?: EvaluationContext): Promise<ResolvedFlags<T>>;
+  readonly flags: T;
+}
+
+type ResolvedFlags<T> = { [K in keyof T]: FlagValueOf<T, K> };
+```
+
+- `resolve(key, ctx)` — one flag. `ctx` defaults to `{}`.
+- `resolveAll(ctx)` — every flag, concurrently, sharing the one `ctx` object (so a `subjectStore`
+  with `loadAll` costs one read for the whole registry). Hand the **values** to a client, never
+  the registry: flag keys name unshipped work.
+- `flags` — the registry, for introspection (the override route uses it).
+
+---
+
+### Built-in sources
+
+All four give up the registry's inferred types and work on `FlagDef` directly.
+
+#### `envOverride(options?)`
+
+```ts
+function envOverride(options?: { read?: (name: string) => string | undefined; prefix?: string }): Source
+```
+
+Slot 1, the operator override and kill switch. Reads `${prefix}${NAME}` where `prefix` defaults to
+`FLAG_` and `NAME` is the flag key in SCREAMING_SNAKE (`newHomepage` → `NEW_HOMEPAGE`; kebab and
+snake keys are tolerated). `read` defaults to `process.env` where it exists (reached through
+`globalThis`, so Workers without `process` work too).
+
+Parsing follows the flag's `fallback` type:
+
+| Flag type | Accepted | Result |
+| --- | --- | --- |
+| boolean | `on` `true` `1` `yes` / `off` `false` `0` `no` (case-insensitive) | `true` / `false` |
+| number | anything `Number()` makes finite | the number |
+| string | anything | trimmed string |
+
+An unset or empty variable is *undecided*. An **unparseable** value throws, which aborts to the
+flag's `fallback` and reports through `onError`: an operator typo is loud. Source name:
+`"envOverride"`.
+
+#### `envDefault(options)`
+
+```ts
+function envDefault(options: { env: string | (() => string) }): Source
+```
+
+Slot 4. Answers `def.byEnv[env]`, or *undecided* when the flag has no entry for the current
+environment. A preview deployment is just a different `env`. Source name: `"envDefault"`.
+
+#### `cookieOverride(options)`
+
+```ts
+function cookieOverride(options: { secret: string; cookieName?: string }): Source
+const DEFAULT_OVERRIDE_COOKIE = "lg_override";
+```
+
+Slot 2, the signed per-visitor override. Reads `ctx.cookie(cookieName)`, verifies the HMAC with
+`secret` (see `readOverrides`), and answers the flag's entry in the token.
+
+- Honours **only** flags with `overridable: true`; any other flag is *undecided* here.
+- A missing, malformed, tampered, or foreign-signed token is *undecided*, never an error.
+- Source name: `"cookieOverride"`.
+
+#### `subjectStore(options)`
+
+```ts
+function subjectStore(options: SubjectStoreOptions): SubjectStore
+
+interface SubjectStoreOptions {
+  load?: (subject: string, key: string, flag: FlagMeta) => SubjectState | undefined | Promise<SubjectState | undefined>;
+  loadAll?: (subject: string) => Map<string, SubjectState> | Record<string, SubjectState> | Promise<…>;
+  requiresOptIn?: (flag: FlagMeta) => boolean;        // default: no flag requires opt-in
+}
+
+interface SubjectState {
+  override?: "enabled" | "disabled";
+  value?: FlagValue;                                   // grant a specific value, for value-typed flags
+  optedIn?: boolean;
+  [projectField: string]: unknown;
+}
+
+interface SubjectStore {
+  kill: Source;          // slot 1 — a 'disabled' row → the flag's off-value
+  requireOptIn: Source;  // slot 3a — flag requires opt-in and the subject hasn't → off-value
+  grant: Source;         // slot 3b — an 'enabled' row → `value`, else `true` for boolean flags
+  state(flag: FlagMeta, ctx: EvaluationContext): Promise<SubjectState | undefined>;
+}
+```
+
+Three sources over one storage read. You own the SQL; the library owns the semantics.
+
+- Throws at construction if neither `load` nor `loadAll` is given. `loadAll` is preferred when
+  both are present.
+- Every source is *undecided* when `ctx.targetingKey` is absent.
+- Reads are cached per **context object** (a `WeakMap` keyed on `ctx`): per subject with
+  `loadAll`, per subject + flag with `load`. One request, one read, however many of the three
+  sources are in the chain.
+- The off-value is `false` for boolean flags and the `fallback` for everything else.
+- `grant` on a non-boolean flag with no `value` is *undecided*.
+- `state(flag, ctx)` exposes the same cached read to a project's own policy source.
+- Source names: `"subjectKill"`, `"subjectOptIn"`, `"subjectGrant"`.
+
+---
+
+### Route gating
+
+#### `createRouteGate(options)`
+
+```ts
+function createRouteGate<T extends FlagRegistry>(options: RouteGateOptions<T>): RouteGate
+
+interface RouteGateOptions<T> {
+  resolver: Resolver<T>;
+  routes: Partial<Record<keyof T & string, readonly string[]>>;   // flag → prefixes it reveals
+  allow?: readonly string[];                                       // served regardless of flags
+  unlisted: "deny" | "allow";                                      // required, no default
+}
+
+interface RouteGate {
+  isPermitted(pathname: string, ctx?: EvaluationContext): Promise<boolean>;
+  revealedPrefixes(ctx?: EvaluationContext): Promise<string[]>;    // prefixes whose flag is on
+  permittedPrefixes(ctx?: EvaluationContext): Promise<string[]>;   // allow + revealed
+}
+```
+
+`isPermitted` decides in this order: on the allowlist → `true` (no flag resolved); under a
+prefix whose flag is on → `true`; under a prefix whose flag is off → `false` regardless of
+`unlisted`; otherwise `unlisted === "allow"`.
+
+**Throws at construction** when a prefix appears in both `allow` and a flag's routes (the flag
+would be dead), or when `routes` names a flag the resolver does not have.
+
+#### `matchesPrefix(pathname, prefixes)`
+
+```ts
+function matchesPrefix(pathname: string, prefixes: readonly string[]): boolean
+```
+
+Exact match or a path segment below it (`/a` matches `/a` and `/a/b`, not `/ab`). `"/"` matches
+only `"/"`. Exported for client-side nav filtering so the menu and the router agree.
+
+---
+
+### Registry hygiene
+
+#### `auditRegistry(flags, options?)`
+
+```ts
+function auditRegistry(flags: FlagRegistry, options?: { today?: Date; retiredAfterDays?: number }): AuditReport
+
+interface AuditReport { problems: string[]; warnings: string[] }
+```
+
+Audits what the library owns: retirements. Defaults: `today = new Date()`, `retiredAfterDays = 40`.
+
+| Finding | Kind |
+| --- | --- |
+| `retired.value` has a different type from `fallback` | problem |
+| `retired.since` is not `YYYY-MM-DD` | problem (and the age check is skipped) |
+| retired flag still declares `overridable` | warning |
+| retired for more than `retiredAfterDays` | warning |
+
+Fail the build on `problems`; print `warnings` every run. Merge with your own lifecycle checks.
+
+---
+
+### Signing
+
+#### `signOverrides(overrides, secret)`
+
+```ts
+function signOverrides(overrides: Record<string, FlagValue>, secret: string): Promise<string>
+```
+
+Mints the token `cookieOverride` reads: `base64url(JSON) + "." + base64url(HMAC-SHA256)`.
+
+#### `readOverrides(token, secret)`
+
+```ts
+function readOverrides(token: string, secret: string): Promise<Record<string, FlagValue> | undefined>
+```
+
+Verifies (timing-safe) and parses. `undefined` for anything not genuinely signed, not an object,
+or not parseable; non-`FlagValue` entries are dropped. Use it directly in a Next `proxy.ts` to
+pick a static variant without opting the page into dynamic rendering.
+
+---
+
+### Testing
+
+#### `withFlags(flags, values?)`
+
+```ts
+function withFlags<T extends FlagRegistry>(flags: T, values?: FlagValues<T>): Resolver<T>
+type FlagValues<T> = Partial<{ [K in keyof T]: FlagValueOf<T, K> }>
+```
+
+A resolver with one source that answers from `values`; anything unset falls back to the flag's
+declared `fallback`. Retirement still applies.
+
+---
+
+## `@davidlee49/launchgate/next`
+
+Requires `next >= 15`. Everything here is cookie plumbing over the core.
+
+#### `requestContext(extra?)`
+
+```ts
+function requestContext(extra?: EvaluationContext): Promise<EvaluationContext>
+```
+
+Returns `{ ...extra, cookie }` where `cookie` reads the incoming request's cookies via
+`next/headers`. **Opts the caller into dynamic rendering** (`cookies()` always does). Fine on
+already-dynamic pages; on a page that must stay static, use `readOverrides` in `proxy.ts` instead.
+
+#### `requireFlag(resolver, key, ctx?)`
+
+```ts
+function requireFlag<T, K extends keyof T & string>(
+  resolver: Resolver<T>, key: K, ctx?: EvaluationContext,
+): Promise<NextResponse | null>
+```
+
+Route-handler guard. Returns a `404 { error: "Not found" }` response when the flag resolves to
+`false` or `undefined`, else `null`. 404 rather than 403: a feature you don't have should not
+advertise its existence.
+
+```ts
+const blocked = await requireFlag(gate, "network", { targetingKey: orgId });
+if (blocked) return blocked;
+```
+
+#### `createOverrideRoute(options)`
+
+```ts
+function createOverrideRoute<T extends FlagRegistry>(options: OverrideRouteOptions<T>): { GET: (request: Request) => Promise<NextResponse> }
+
+interface OverrideRouteOptions<T> {
+  resolver: Resolver<T>;
+  secret: string;        // HMAC secret — the same one cookieOverride has; never in a URL
+  accessToken: string;   // presented as ?token= ; must differ from `secret`
+  cookieName?: string;   // default "lg_override"
+  maxAge?: number;       // cookie lifetime in seconds; default 30 days
+}
+```
+
+A `GET` handler that sets the signed override cookie so you can see hidden work on the live site
+with no account. Mount it at an unadvertised path **outside** your auth gate, and never under a
+`_`-prefixed directory (the App Router silently drops those).
+
+Query parameters:
+
+| Query | Effect |
+| --- | --- |
+| `token=…` | Required. Compared timing-safe to `accessToken`; wrong → `404`. |
+| `flag=KEY&value=V` | Set `KEY` to `V` (parsed by the flag's type: booleans accept `on/true/1` and `off/false/0`). |
+| `flag=KEY` (no `value`) | Clear that one override. |
+| `clear=1` | Drop every override. |
+
+Errors are `400` with `{ error }`: missing `flag`, unknown flag, flag not `overridable`, value
+not parseable for the flag's type. The response body is `{ overrides }` — the full map now in the
+cookie. An empty map deletes the cookie; otherwise it is set `httpOnly`, `sameSite: lax`,
+`secure` on https, `path: /`.