@digimuza/saas-core 0.0.2

package/docs/events.md

@@ -0,0 +1,279 @@
+# Events
+
+```ts
+import {
+  coreEvents, createEventsService, defineEvents, mergeEventRegistries,
+} from "@digimuza/saas-core/events";
+```
+
+> Orientation and recipes: [`src/events/README.md`](../src/events/README.md).
+
+
+One durable record of everything that happens, typed at compile time and validated
+at runtime. Realtime delivery, RxJS streams, notifications, audit logs, outgoing
+webhooks and durable jobs all read from here rather than inventing their own
+channel.
+
+---
+
+## The registry
+
+Each event type is paired with a Zod schema, which does double duty: `z.infer`
+gives the compile-time payload type, and the same schema validates before anything
+is written.
+
+A `Record<string, unknown>` payload would give neither. A hand-written TypeScript
+interface would give only the first, leaving the database to accept whatever a
+caller happened to pass.
+
+### `defineEvents(schemas)`
+
+```ts
+function defineEvents<const S extends Record<string, z.ZodType>>(schemas: S): EventRegistry<S>
+```
+
+```ts
+import { z } from "zod";
+
+export const appEvents = defineEvents({
+  "project.created": z.object({ projectId: z.uuid(), name: z.string().min(1) }),
+  "project.deleted": z.object({ projectId: z.uuid() }),
+});
+```
+
+The `const` type parameter preserves the literal keys — that is what makes
+`publish({ type: "project.created", ... })` autocomplete and narrow `data`.
+
+### `mergeEventRegistries(first, second)`
+
+```ts
+function mergeEventRegistries<A, B>(first: EventRegistry<A>, second: EventRegistry<B>): EventRegistry<A & B>
+```
+
+```ts
+// lib/events.ts
+import { getDatabase } from "@digimuza/saas-core/db";
+
+const registry = mergeEventRegistries(coreEvents, appEvents);
+export const events = createEventsService({ db: getDatabase(), registry });
+```
+
+Duplicate keys **throw**. An application that redefined
+`workspace.member.created` with a different payload would make every core consumer
+of that event wrong, and the failure would surface far from the cause.
+
+---
+
+## `events.publish(input)`
+
+```ts
+function publish(input: {
+  type: K;                       // a key of the registry
+  data: z.input<S[K]>;           // narrowed to that key's schema
+  workspaceId?: string | null;
+  actorId?: string | null;
+  idempotencyKey?: string;
+  occurredAt?: Date;
+}): Promise<SaasEvent>
+```
+
+```ts
+await events.publish({
+  type: "project.created",
+  workspaceId: context.workspaceId,
+  actorId: user.id,
+  data: { projectId, name },
+});
+```
+
+Validates, persists, then fans out. The row is committed **before** handlers run,
+so an event is never lost because a subscriber failed.
+
+Passing a payload that does not match its type is a **compile error**. There is a
+test asserting that with `@ts-expect-error`, so the guarantee cannot silently
+regress.
+
+`workspaceId` may be `null` for platform-wide events that precede any workspace,
+such as a user being provisioned. `occurredAt` lets you record when something
+actually happened, which is not always when it was recorded — a webhook may report
+an event minutes after the fact.
+
+Throws `InvalidInputError` for a payload that fails its schema, or an unknown type
+(reachable only from untyped JavaScript).
+
+## `events.scoped(context)`
+
+```ts
+function scoped(context: WorkspaceContext): ScopedPublisher
+```
+
+Binds the verified workspace so callers cannot pass a different one:
+
+```ts
+const scoped = events.scoped(context);
+await scoped.publish({ type: "project.created", actorId: user.id, data });
+```
+
+## `events.record(input, tx?)` and `events.dispatch(event)`
+
+```ts
+function record(input: PublishInput, tx?: CoreDatabase): Promise<{ event: SaasEvent; created: boolean }>
+function dispatch(event: SaasEvent): Promise<void>
+```
+
+The transactional outbox. Write the event in the **same transaction** as the state
+change it describes, then dispatch after the commit:
+
+```ts
+const { event, created } = await db.transaction(async (tx) => {
+  await createProject(tx, input);
+  return events.record({ type: "project.created", data }, tx);
+});
+
+if (created) {
+  await events.dispatch(event);
+}
+```
+
+So there is no state change without its event, and no event for a change that
+rolled back. Both directions are tested.
+
+**Dispatch only when `created` is true.** A deduplicated event was already fanned
+out when first recorded, and firing again would make every handler run twice for
+one real occurrence. This was a real bug: the outbox originally queued deduplicated
+events, which would have re-fired `user.created` handlers on every sign-in.
+
+## `events.on(type, handler)` / `events.onAny(handler)`
+
+```ts
+function on<K>(type: K, handler: (event: SaasEventOf<S, K>) => void | Promise<void>): Unsubscribe
+function onAny(handler: (event: SaasEvent<S>) => void | Promise<void>): Unsubscribe
+```
+
+```ts
+const unsubscribe = events.on("project.created", async (event) => {
+  event.data.name;   // narrowed to this event's schema
+});
+```
+
+### Subscribers are in-process and not durable
+
+A crash between the commit and the handler loses the **reaction**, not the event.
+That is deliberate: durable reactions belong in Trigger.dev (see
+[jobs.md](./jobs.md)), reading the persisted row. Never keep state in a handler
+that must survive a restart.
+
+### Handlers cannot fail a publish
+
+They run concurrently via `Promise.allSettled`; each failure goes to the service's
+error sink and the others still run. The event has happened and is committed, so a
+broken subscriber is a separate operational problem.
+
+```ts
+createEventsService({
+  db, registry,
+  onHandlerError: (error, event) => logger.error({ error, type: event.type }),
+});
+```
+
+Without a sink, failures are logged with `console.error`. Provide one in production
+so they reach your error tracker.
+
+## `events.list(context, options?)`
+
+```ts
+function list(context: WorkspaceContext, options?: {
+  types?: readonly string[];
+  limit?: number;      // default 50, capped at 500
+  before?: Date;       // keyset pagination
+  actorId?: string;
+}): Promise<SaasEvent[]>
+```
+
+Always workspace-scoped: an event feed is tenant data. Newest first, tie-broken on
+id so keyset pagination cannot loop on equal timestamps.
+
+```ts
+const page = await events.list(context, { types: ["project.created"], limit: 20 });
+const next = await events.list(context, { before: page.at(-1)!.occurredAt });
+```
+
+---
+
+## Idempotency
+
+`(type, idempotency_key)` is a **partial** unique index, so a retried operation
+records its event once. Keys are scoped per type — two event types may legitimately
+derive a key from the same request.
+
+`user.created` uses the WorkOS id as its key, which is how a re-login provisions no
+second event without a racy select-then-decide.
+
+> Because the index is partial (`WHERE idempotency_key IS NOT NULL`), the
+> `ON CONFLICT` clause must carry a matching `where` predicate. PostgreSQL refuses
+> to infer a partial index as a conflict arbiter otherwise, and every insert fails
+> with `42P10`. Worth knowing if you add a similar index of your own.
+
+---
+
+## What the core emits
+
+| Event | Payload |
+| --- | --- |
+| `user.created` | `userId`, `workosUserId` |
+| `workspace.created` | `workspaceId`, `slug` |
+| `workspace.updated` | `workspaceId`, `changed: ("name"\|"slug")[]` |
+| `workspace.deleted` | `workspaceId`, `slug` |
+| `workspace.member.created` | `userId`, `roleIds` |
+| `workspace.member.removed` | `userId` |
+| `workspace.member.role.updated` | `userId`, `roleId`, `action` |
+| `workspace.invitation.created` | `invitationId`, `email`, `roleId` |
+| `workspace.invitation.accepted` | `invitationId`, `userId` |
+| `workspace.invitation.revoked` | `invitationId` |
+| `billing.subscription.updated` | `subscriptionId`, `planKey`, `status`, `previousStatus?` |
+| `billing.subscription.canceled` | `subscriptionId`, `planKey`, `atPeriodEnd` |
+| `job.started` | `runId`, `taskId` |
+| `job.progress` | `runId`, `taskId`, `percent?`, `message?`, `step?`, `totalSteps?` |
+| `job.completed` | `runId`, `taskId`, `durationMs?` |
+| `job.failed` | `runId`, `taskId`, `error`, `attempt?` |
+
+Notification and realtime events arrive with the phases that introduce them.
+Declaring them now would ship types nothing publishes — worse than no type, since
+consumers would write handlers that never fire.
+
+### Payload conventions
+
+**Identifiers, not snapshots.** An embedded copy goes stale between publication and
+delivery, and would put mutable user data in an append-only table. A consumer that
+needs current state should read it.
+
+**No credentials.** Invitation events deliberately omit the token: events are
+durable and readable, and the token is a bearer credential. There is a test
+asserting it never appears.
+
+**`workspace.deleted` carries `workspaceId: null`** on the row itself. It is
+recorded before the delete, in the same transaction, because `events.workspace_id`
+cascades — a scoped row would vanish along with the tenant it was recording.
+
+---
+
+## Emission is opt-in
+
+`createWorkspacesService({ db })` emits nothing.
+`createWorkspacesService({ db, events })` does.
+
+The default exports are wired together, so
+`import { workspaces } from "@digimuza/saas-core/workspaces"` already emits to the
+core registry. If you build your own services from a merged registry, pass it in —
+`CoreEventPublisher` is a supertype-friendly slice, so a merged-registry service is
+accepted without the core knowing about your extra event types.
+
+---
+
+## The events table
+
+Append-only. There is no `updated_at`: an event is a statement about the past, and
+revising one would make every derived record untrustworthy.
+
+Indexed for `(workspace_id, occurred_at DESC)` — the activity-feed query — and
+`(type, occurred_at DESC)` for backfills and diagnostics.

package/docs/feature-flags.md

@@ -0,0 +1,237 @@
+# Feature flags
+
+```ts
+import {
+  defineFeatureFlags, createFeaturesService, createConfiguredFeaturesService,
+} from "@digimuza/saas-core/feature-flags";
+```
+
+> Orientation and recipes: [`src/features/README.md`](../src/features/README.md).
+
+Simple flags with four scopes, resolved most-specific-first. **Not** a feature
+management platform — no segments, no rule engines, no audience builders.
+
+---
+
+## Declaring flags
+
+```ts
+export const flags = defineFeatureFlags({
+  "new-editor": { default: false, description: "Rebuilt document editor" },
+  ranking: { default: true, variants: ["control", "v2"], defaultVariant: "control" },
+});
+```
+
+```ts
+interface FeatureFlagDefinition {
+  default: boolean;
+  description?: string;
+  variants?: readonly string[];
+  defaultVariant?: string;
+}
+```
+
+Definitions live in **code**, not the database. So a fresh database behaves the
+same as a configured one, a misspelled key is a compile error, and deleting the
+flag from the code deletes it from the product. Database rows are only *overrides*.
+
+Keys must be lowercase alphanumerics with dots, dashes or underscores — they reach
+URLs, log lines and client payloads, and constraining them here avoids escaping
+them everywhere downstream.
+
+`mergeFeatureFlags(a, b)` combines registries and **throws** on a duplicate: two
+modules defining the same flag would make its behaviour depend on import order.
+
+### Constructing the service
+
+```ts
+createConfiguredFeaturesService(flags);                      // application = APP_NAME
+createFeaturesService({ db, registry: flags, application }); // explicit
+```
+
+There is deliberately **no default `features` export** — flags are
+application-defined, so a service with an empty registry could not answer
+anything.
+
+---
+
+## Scopes
+
+```
+global  <  application  <  workspace  <  user
+```
+
+The most specific matching override wins. `FLAG_SCOPE_PRECEDENCE` is exported, so
+a debug view can show the order.
+
+`global` is every application sharing this database; `application` narrows to one
+product built on the core. That distinction exists because this package is
+explicitly meant to back several SaaS products — without it, turning a flag on for
+one would turn it on for all of them.
+
+An `application`-scoped override only matches when the service was given an
+`application`. Otherwise it is ignored rather than guessed at.
+
+---
+
+## Reading
+
+### `features.all(subject?)`
+
+```ts
+function all(subject?: FlagSubject): Promise<Map<Key, ResolvedFlag>>
+```
+
+Every declared flag, resolved in **one** query. The recommended path: resolve once
+per request and pass the result to the client, rather than querying per
+conditional.
+
+```ts
+const resolved = await features.all({ workspaceId: context.workspaceId, userId: user.id });
+```
+
+### `features.isEnabled(key, subject?)` / `getVariant(key, subject?)`
+
+```ts
+function isEnabled(key: Key, subject?: FlagSubject): Promise<boolean>
+function getVariant<K>(key: K, subject?: FlagSubject): Promise<Variant<K> | undefined>
+```
+
+`getVariant` is typed to the flag's declared variants, so a `switch` is
+exhaustively checkable.
+
+**A disabled flag has no variant** — `undefined`. Returning one would invite code
+that reads the variant without checking `isEnabled` first.
+
+### `features.resolve(key, subject?)`
+
+```ts
+interface ResolvedFlag {
+  key: string;
+  enabled: boolean;
+  variant: string | undefined;
+  source: "global" | "application" | "workspace" | "user" | "default";
+}
+```
+
+`source` answers "why is this on for me", which is the question every flag system
+eventually has to answer.
+
+### `FlagSubject`
+
+```ts
+interface FlagSubject {
+  workspaceId?: string;
+  userId?: string;
+}
+```
+
+Plain ids, **not** a `WorkspaceContext` — the one deliberate exception in the core.
+Flags are read many times per request, and a membership check per read would make
+them expensive enough that people would cache them badly. A flag state is
+configuration, not tenant data.
+
+Pass ids that came from a verified context. The service will not check for you.
+
+### Unknown keys throw
+
+`InvalidInputError`, not `false`. Reachable only from untyped JavaScript, but a
+flag that silently never turns on is far harder to diagnose than one that fails at
+the call site.
+
+---
+
+## Writing
+
+### `features.set(input)`
+
+```ts
+function set(input: {
+  key: Key;
+  scope: FeatureFlagScope;
+  application?: string;    // required for scope: "application"
+  workspaceId?: string;    // required for scope: "workspace"
+  userId?: string;         // required for scope: "user"
+  enabled: boolean;
+  variant?: string | null;
+  rolloutPercentage?: number | null;   // 0-100
+  description?: string;
+}): Promise<FeatureFlagRow>
+```
+
+Idempotent per target — setting the same override twice updates it, which is what
+both an admin UI and a seeding script want.
+
+Two things are rejected rather than tolerated:
+
+- **A variant not declared on the flag.** Better than discovering it when a
+  `switch` silently matches nothing.
+- **A target that contradicts the scope.** `{ scope: "global", workspaceId }` is
+  always a mistake, and ignoring it would look like it had worked.
+
+### `features.unset(input)` / `overrides(key)`
+
+`unset` removes one override, falling back to the next-broadest scope. Throws
+`NotFoundError` if there was none. `overrides` lists every stored override for a
+key, broadest first.
+
+---
+
+## Percentage rollout
+
+```ts
+await features.set({ key: "new-editor", scope: "global", enabled: true, rolloutPercentage: 10 });
+```
+
+**Rollout narrows an override; it never turns one on.** A `rolloutPercentage` on a
+*disabled* override leaves it disabled. On an enabled one it means "on for this
+percentage of the subjects this override covers".
+
+Bucketing is `sha256(key + subjectId) % 100`, so:
+
+- **Stable.** A subject stays on the same side across requests, processes and
+  deploys. A flag that flickered would be worse than no flag — a user would see
+  the new editor, reload, and lose their work.
+- **Salted by flag key.** Otherwise the same unlucky cohort would receive every
+  experiment.
+- **Stateless.** Nothing to store, nothing to keep in sync.
+
+The subject is the **most specific available**: `userId` if present, else
+`workspaceId`. So a per-user rollout is stable per user and a per-workspace one per
+workspace.
+
+With **no subject**, anything below 100 is off. There is nothing stable to hash,
+and guessing would reintroduce the flickering this design exists to prevent.
+
+`bucketOf(key, subjectId)` and `isInRollout(key, percentage, subjectId)` are
+exported, if you need the same bucketing for something the service does not cover.
+
+---
+
+## Storage
+
+One table, `feature_flags`, one row per override per target.
+
+```
+unique nulls not distinct (key, scope, application, workspace_id, user_id)
+```
+
+`NULLS NOT DISTINCT` is load-bearing. PostgreSQL treats NULLs as distinct in a
+unique index by default, so without it every global override — where all three
+target columns are null — would count as unique and you could insert the same one
+endlessly. There is a test for exactly that.
+
+`workspace_id` and `user_id` are real foreign keys with `ON DELETE CASCADE`, so an
+override for a deleted tenant does not accumulate as dead configuration. Contrast
+[audit](./audit.md), where the identifiers are deliberately *not* foreign keys
+because an entry must outlive its subject.
+
+---
+
+## No caching
+
+Every call is a query. `all()` exists so you make one per request rather than one
+per conditional; wrap it in your own cache if you need more.
+
+Deliberate: a library that cached by default would give you stale flags at a moment
+you did not choose, and the right TTL depends on how you deploy.