@digimuza/saas-core 0.0.2

package/docs/streams.md

@@ -0,0 +1,296 @@
+# Streams (RxJS)
+
+```ts
+import { fromEvents, ofType, inWorkspace, latestByKey } from "@digimuza/saas-core/streams";
+import { fromEventStream } from "@digimuza/saas-core/streams/client";
+```
+
+> Orientation and recipes: [`src/streams/README.md`](../src/streams/README.md).
+
+RxJS is a first-class dependency, used for **application-level reactive
+behaviour** — and nothing else:
+
+```
+event sources → application events → Observable → reactor → application/client
+```
+
+`rxjs` is an **optional peer dependency**. Install it only if you use this module.
+
+---
+
+## What this module deliberately is not
+
+| Not | Because |
+| --- | --- |
+| the database | A one-shot read stays a promise. Wrapping it adds a lifecycle to manage for no benefit. |
+| the durable job system | A crash loses a reaction, not an event. Durable work belongs in [jobs.md](./jobs.md). |
+| the realtime transport | That is [realtime.md](./realtime.md); this consumes it. |
+| persistence | State that must survive a restart belongs in PostgreSQL, never in an operator's accumulator. |
+
+The rule throughout the package: **promises for one-time work, Observables for
+sequences over time.**
+
+---
+
+## Server-side
+
+### `fromEvents(events)`
+
+```ts
+function fromEvents<S extends EventSchemaMap>(events: EventsService<S>): Observable<SaasEvent<S>>
+```
+
+An Observable of application events, from the in-process dispatcher.
+
+```ts
+const subscription = fromEvents(events)
+  .pipe(
+    inWorkspace(context.workspaceId),
+    ofType("workspace.member.created"),
+    debounceTime(500),
+    takeUntil(shutdown$),
+  )
+  .subscribe(reindexWorkspace);
+```
+
+**Lifecycle.** The events handler is registered on subscribe and removed on
+unsubscribe. Nothing exists before the first subscriber and nothing lingers after
+the last — so forgetting `takeUntil` leaks one handler, not a growing set. Each
+subscriber gets its own handler; one leaving does not silence another.
+
+**It never completes on its own.** Bound it with `takeUntil` or `take(n)`.
+
+### `fromRealtime(realtime, options)`
+
+```ts
+function fromRealtime(realtime: RealtimeService, options: {
+  userId: string;
+  channels: readonly string[];
+}): Observable<RealtimeMessage>
+```
+
+Authorized realtime messages, for a *server* reacting to delivery. A browser
+should use `fromEventStream` instead.
+
+Authorization runs once, on subscribe. Because that check is asynchronous and the
+Observable constructor is not, a subscriber that unsubscribes mid-check is
+honoured — the transport subscription closes immediately rather than sitting open
+with nobody listening.
+
+---
+
+## Operators
+
+Five helpers. Everything else is plain RxJS, because re-exporting existing
+operators under new names adds vocabulary without adding behaviour.
+
+### `ofType(...types)`
+
+```ts
+function ofType<S, const K extends readonly EventTypeOf<S>[]>(
+  ...types: K
+): OperatorFunction<SaasEvent<S>, SaasEventOf<S, K[number]>>
+```
+
+Narrows in the **type system** as well as at runtime:
+
+```ts
+fromEvents(events).pipe(
+  ofType("project.created", "project.deleted"),
+  map((event) => event.data.projectId),   // narrowed to those two payloads
+);
+```
+
+A plain `filter((e) => e.type === "project.created")` filters correctly but leaves
+`data` as the union of every payload in the registry, so every downstream operator
+needs a cast.
+
+### `inWorkspace(workspaceId)` / `byActor(actorId)`
+
+```ts
+function inWorkspace<T extends { workspaceId: string | null }>(id: string): MonoTypeOperatorFunction<T>
+function byActor<T extends { actorId: string | null }>(id: string): MonoTypeOperatorFunction<T>
+```
+
+The in-process dispatcher is process-wide, so a server stream sees every
+workspace's events. `inWorkspace` is what makes a per-tenant stream out of it.
+
+**Not an authorization boundary.** The caller must already hold a verified
+`WorkspaceContext` — see [workspaces.md](./workspaces.md#workspacecontext).
+
+### `toData()`
+
+```ts
+function toData<E extends { data: unknown }>(): OperatorFunction<E, E["data"]>
+```
+
+Projects each event to its payload. The type parameter is inferred from the
+*source*; declaring it over the registry and event key would leave both unbound at
+the call site and collapse `data` to `unknown`.
+
+### `latestByKey(source, keyOf)`
+
+```ts
+function latestByKey<T>(source: Observable<T>, keyOf: (value: T) => string):
+  Observable<ReadonlyMap<string, T>>
+```
+
+"Newest value per key" — reactive state.
+
+```ts
+const progress$ = latestByKey(jobEvents$, (event) => event.data.runId);
+```
+
+The one state shape worth wrapping, because the sharing is easy to miss: without
+`shareReplay`, every new subscriber re-runs the scan from an empty map and sees
+nothing until the next event.
+
+Each emission is a **new** Map, so a subscriber holding an earlier value is not
+mutated underneath it.
+
+`refCount: true` discards the accumulated map when the last subscriber leaves.
+Deliberate — a cache outliving its subscribers is a leak, and this is a *view* of
+durable data.
+
+---
+
+## Browser: `fromEventStream(options)`
+
+```ts
+function fromEventStream(options: {
+  url: string;
+  channels: readonly string[];
+  types: readonly string[];
+  createSource?: (url: string) => EventSourceLike;
+  initialRetryDelayMs?: number;   // 1_000
+  maxRetryDelayMs?: number;       // 30_000
+  onError?: (error: unknown) => void;
+  setTimeoutImpl?: (handler: () => void, ms: number) => unknown;
+  clearTimeoutImpl?: (handle: unknown) => void;
+}): Observable<ClientRealtimeMessage>
+```
+
+```ts
+const events$ = fromEventStream({
+  url: "/api/realtime",
+  channels: [`workspace:${workspaceId}`],
+  types: ["job.progress", "project.created"],
+});
+
+const subscription = events$
+  .pipe(
+    filter((message) => message.type === "job.progress"),
+    map((message) => message.data as { percent?: number }),
+    distinctUntilChanged((a, b) => a.percent === b.percent),
+  )
+  .subscribe(render);
+
+return () => subscription.unsubscribe();   // React effect cleanup
+```
+
+**`types` is required.** SSE dispatches by event name and the server names each
+frame after the event type, so listening for `message` alone receives nothing.
+
+**One stream, shared.** Every component piping this beats each opening its own
+`EventSource`: one connection, one reconnect policy, one ordering to reason about.
+
+**No server imports.** This module pulls in nothing but RxJS — a test asserts it,
+because a shared import would drag config and the database driver into the bundle.
+
+### Reconnect behaviour
+
+Errors do **not** terminate the stream. A dropped connection is expected, not
+exceptional: it is reported through `onError` and retried, because surfacing it as
+an RxJS error would tear down every downstream operator and lose the subscriber's
+accumulated state on a transient blip.
+
+Backoff doubles from `initialRetryDelayMs`, capped at `maxRetryDelayMs`
+(1s → 2s → 4s → 8s → … → 30s), and **resets once a frame arrives** — a message
+proves the connection is healthy. Unbounded retries would hammer a server that is
+already struggling.
+
+A pending retry is cancelled on unsubscribe, so a torn-down component cannot
+reconnect behind the caller's back.
+
+Only one failure is fatal: being unable to construct a source at all (no
+`EventSource` and no `createSource`). That is a configuration fault, not a blip.
+
+### Handle `truncated`
+
+```ts
+source.addEventListener("project.created", (message) => {
+  const { eventId, data, truncated } = JSON.parse(message.data);
+  if (truncated) return refetchEvent(eventId);
+  applyUpdate(data);
+});
+```
+
+`pg_notify` caps payloads at 8000 bytes; oversized `data` is dropped and `eventId`
+retained so the client can re-read. See
+[realtime.md](./realtime.md#the-default-transport-postgresql-listennotify).
+
+Frames are validated, not cast — this crossed the network.
+
+### `buildStreamUrl(url, channels)`
+
+```ts
+function buildStreamUrl(url: string, channels: readonly string[]): string
+```
+
+How `fromEventStream` builds its endpoint — each channel appended as a repeated
+`channel` parameter. Exported because a caller sometimes needs the same URL: to
+prefetch it, to pass it to a service worker, or to assert on it in a test.
+
+```ts
+buildStreamUrl("/api/realtime", ["workspace:abc", "user:def"]);
+// "/api/realtime?channel=workspace%3Aabc&channel=user%3Adef"
+```
+
+A relative endpoint stays relative — browsers call relative endpoints, and forcing
+an absolute URL would break that.
+
+---
+
+## Errors: the gotcha worth reading twice
+
+**A throwing subscriber is invisible to the events error sink.** RxJS catches an
+exception thrown in a `next` callback and reports it to its *own* global unhandled
+handler. It never propagates back to the events service, so `onHandlerError` never
+sees it. There is a test asserting exactly this so it stays documented.
+
+```ts
+// Wrong: the failure vanishes.
+stream.subscribe((event) => { throw new Error("boom"); });
+
+// Right: handle it, or let the chain raise it.
+stream.subscribe({
+  next: apply,
+  error: (error) => logger.error({ error }),
+});
+```
+
+Publishing is never affected either way — the event is already committed.
+
+---
+
+## Testing streams
+
+Virtual time for anything time-based. Real timers make these tests slow and flaky,
+and the point is the operator's semantics, not the clock's.
+
+```ts
+import { TestScheduler } from "rxjs/testing";
+
+new TestScheduler((actual, expected) => expect(actual).toEqual(expected)).run(
+  ({ cold, expectObservable, expectSubscriptions }) => {
+    const source = cold("a-b-c---|");
+    expectObservable(source.pipe(debounceTime(3))).toBe("-------c|");
+    // Assert the source is actually released, not just that values stop.
+    expectSubscriptions(source.subscriptions).toBe("^-------!");
+  },
+);
+```
+
+For the client stream, inject `createSource`, `setTimeoutImpl` and
+`clearTimeoutImpl` — the core's own tests drive reconnect and assert the exact
+backoff schedule with no waiting.

package/docs/users.md

@@ -0,0 +1,117 @@
+# Users & profiles
+
+```ts
+import { users } from "@digimuza/saas-core/users";
+```
+
+> Orientation and recipes: [`src/users/README.md`](../src/users/README.md).
+
+
+Identity and profile are separate tables but a single concern here, because callers
+almost always want both.
+
+- **`users`** — the link to WorkOS. No email, no credentials.
+- **`user_profiles`** — email, name, avatar. Keyed by `user_id`.
+
+Email lives on the profile because duplicating it on the identity row would create
+two sources of truth that drift. Credentials are never stored: WorkOS owns
+authentication.
+
+---
+
+## `users.getById(userId)`
+
+```ts
+function getById(userId: string): Promise<UserWithProfile | undefined>
+```
+
+```ts
+interface UserWithProfile {
+  id: string;
+  workosUserId: string;
+  createdAt: Date;
+  updatedAt: Date;
+  profile: UserProfile | null;
+}
+```
+
+The profile is nullable because the join is a left join — a user row can exist
+without a profile if a sync was interrupted.
+
+## `users.requireById(userId)`
+
+```ts
+function requireById(userId: string): Promise<UserWithProfile>
+```
+
+Throws `NotFoundError`.
+
+## `users.getByWorkosId(workosUserId)`
+
+```ts
+function getByWorkosId(workosUserId: string): Promise<UserWithProfile | undefined>
+```
+
+Used by the auth module to map a session back to a local user.
+
+## `users.syncFromWorkos(attributes)`
+
+```ts
+function syncFromWorkos(attributes: {
+  workosUserId: string;
+  email: string;
+  firstName?: string | null;
+  lastName?: string | null;
+  profilePictureUrl?: string | null;
+}): Promise<UserWithProfile>
+```
+
+Creates or updates the local record for a WorkOS identity. Called on every
+successful authentication, so it must be idempotent and concurrency-safe — and is:
+
+- Uses `onConflictDoUpdate` rather than select-then-insert. Two concurrent
+  sign-ins for the same identity would otherwise race and one would fail on the
+  unique index. There is a test firing three concurrent syncs.
+- Tracks email changes from the provider.
+- **Never overwrites `display_name`.** The user may have set it themselves, and
+  the identity provider must not clobber it. Also tested.
+
+Emits `user.created` once per identity, keyed on the WorkOS id — a re-login is not
+a new user. See [events.md](./events.md).
+
+## `users.updateProfile(userId, update)`
+
+```ts
+function updateProfile(userId: string, update: {
+  firstName?: string | null;
+  lastName?: string | null;
+  displayName?: string | null;
+  avatarUrl?: string | null;
+}): Promise<UserProfile>
+```
+
+Throws `NotFoundError` if there is no profile row.
+
+---
+
+## Email is indexed, not unique
+
+`user_profiles.email` has a **case-insensitive, non-unique** index. WorkOS owns
+identity uniqueness, and its account-linking flows can transiently present two
+identities sharing an email. A unique constraint here would turn legitimate
+provider state into a failed write inside the core.
+
+If your product needs one email to mean one account, enforce it in WorkOS, or add
+a unique index in your own migration having decided how to handle linking.
+
+---
+
+## Custom construction
+
+```ts
+import { createUsersService } from "@digimuza/saas-core/users";
+
+const users = createUsersService({ db, events });   // events optional
+```
+
+Without `events`, nothing is emitted and behaviour is otherwise identical.

package/docs/webhooks.md

@@ -0,0 +1,272 @@
+# Webhooks
+
+```ts
+import {
+  webhooks, signWebhookPayload, verifyWebhookSignature,
+} from "@digimuza/saas-core/webhooks";
+```
+
+> Orientation and recipes: [`src/webhooks/README.md`](../src/webhooks/README.md).
+
+Both directions, sharing one signature scheme so there is a single implementation
+to audit.
+
+---
+
+## Signing
+
+HMAC-SHA256 over `v1.{timestampMs}.{rawBody}`, presented as `v1=<hex>`. The same
+scheme the core already verifies from Revolut — which means receivers can follow
+instructions Stripe and Revolut users already know.
+
+```ts
+function signWebhookPayload(input: { rawBody: string; secret: string; timestampMs: number }): string
+
+function verifyWebhookSignature(input: {
+  rawBody: string;
+  signature: string;
+  timestamp: string | number;
+  secret: string | readonly string[];   // several during rotation
+  toleranceSeconds?: number;            // 300
+  now?: () => number;
+}): boolean
+```
+
+**Give it the body exactly as received.** Parsing and re-serialising JSON changes
+key order and whitespace, which invalidates the signature.
+
+Stale **and** future timestamps are rejected: a signature is valid forever, so
+without a window a captured request could be replayed indefinitely — and a clock
+skewed forward would widen that window rather than narrow it.
+
+Comparison is constant-time, and comma-separated signatures are accepted so a
+sender can present both secrets while rotating.
+
+Headers the core sends: `x-saas-core-signature`, `x-saas-core-timestamp`, plus
+`X-Saas-Core-Event-Id`, `-Event-Type`, `-Delivery-Id` and `-Attempt`.
+
+### `generateWebhookSecret()`
+
+```ts
+function generateWebhookSecret(): string   // "whsec_<43 base64url chars>"
+```
+
+256 bits, with a recognisable prefix so a leaked secret is identifiable in a log or
+a paste. `endpoints.create` and `rotateSecret` call it for you; it is exported for
+inbound endpoints you register with a sender yourself, where you need to generate
+and store the shared secret on your own side.
+
+`signingPayload(timestampMs, rawBody)` is exported too, if you need to reproduce
+the exact signed string — for a receiver written in another language, say.
+
+---
+
+## Outgoing
+
+### Endpoints
+
+```ts
+webhooks.outgoing.endpoints.create(context, {
+  url: string;
+  description?: string;
+  eventTypes?: readonly string[];   // empty means every type
+}): Promise<{ endpoint: WebhookEndpoint; secret: string }>
+
+webhooks.outgoing.endpoints.list(context): Promise<WebhookEndpoint[]>
+webhooks.outgoing.endpoints.get(context, id): Promise<{ endpoint; secret }>
+webhooks.outgoing.endpoints.update(context, id, patch): Promise<WebhookEndpoint>
+webhooks.outgoing.endpoints.rotateSecret(context, id): Promise<{ endpoint; secret }>
+webhooks.outgoing.endpoints.remove(context, id): Promise<void>
+```
+
+The signing secret is **readable**, unlike an API key. It has to be: the core signs
+with it and the receiver verifies with the same value, so a one-way hash would make
+both impossible. Encryption at rest is the mitigation; `rotateSecret` handles a
+leak without recreating the endpoint.
+
+Re-enabling an endpoint clears its failure state — otherwise it would disable again
+on the next failure regardless of what was fixed.
+
+### URL safety
+
+HTTPS only. A signed payload over plain HTTP still exposes its contents, and the
+signature does not stop an interceptor reading it.
+
+Private and loopback addresses are refused: loopback, RFC1918, link-local
+(`169.254.*`), `.internal`, `.local`. A tenant registering
+`https://169.254.169.254/latest/meta-data` would otherwise have your server fetch
+its own cloud credentials and post them back.
+
+**This is a first pass, not a complete defence.** DNS can resolve a public name to
+a private address at connect time. A production deployment should route webhook
+egress through a proxy that enforces this too — which is why `WebhookSender` is
+injectable.
+
+### `dispatch(event, tx?)`
+
+```ts
+function dispatch(event: SaasEvent, tx?: CoreDatabase): Promise<WebhookDelivery[]>
+```
+
+Queues a delivery per active, subscribed endpoint. **Records rows; sends nothing.**
+
+Idempotent per `(endpoint, event)`: a retried job or a replayed event cannot
+produce a second delivery. The payload is frozen at dispatch, so a later change to
+the event cannot alter what was already queued.
+
+Platform-wide events (null workspace) are skipped — there are no endpoints that
+should receive them, and picking a workspace would leak across tenants.
+
+### Driving delivery
+
+The core runs no loop. Retries must survive a deploy, so that is
+[Trigger.dev's](./jobs.md) job:
+
+```ts
+export const drainWebhooks = schedules.task({
+  id: "drain-webhooks",
+  cron: "* * * * *",
+  run: async () => {
+    for (const delivery of await webhooks.outgoing.claimDue({ limit: 100 })) {
+      await webhooks.outgoing.attempt(delivery);
+    }
+  },
+});
+```
+
+```ts
+function claimDue(options?: { limit?: number }): Promise<WebhookDelivery[]>
+function attempt(delivery: WebhookDelivery): Promise<DeliveryAttemptResult>
+function listDeliveries(context, options?): Promise<WebhookDelivery[]>
+```
+
+### Retries and failure
+
+| Setting | Default |
+| --- | --- |
+| `maxAttempts` | 6 |
+| `initialRetryDelayMs` | 30s, doubling |
+| `maxRetryDelayMs` | 6h |
+| `failureThreshold` | 20 consecutive failures |
+
+A sender that *throws* is a failed attempt, not a crashed worker. An exhausted
+delivery has `next_attempt_at` nulled, so it is never re-claimed.
+
+An endpoint that fails `failureThreshold` times consecutively is set inactive and
+stops receiving dispatches — it should not keep consuming retry budget. Any success
+resets the streak.
+
+### `createFetchWebhookSender(options?)`
+
+```ts
+createFetchWebhookSender({ timeoutMs?: 10_000, fetchImpl?: typeof fetch })
+```
+
+`redirect: "manual"`, because a redirect could land somewhere the URL check
+rejected. The abort signal matters: without a timeout one slow receiver holds a
+worker slot indefinitely.
+
+---
+
+## Inbound
+
+```ts
+function receive(input: {
+  source: string;        // "github"
+  externalId: string;    // the sender's event id
+  type: string;
+  payload: unknown;
+  workspaceId?: string | null;
+}, tx?: CoreDatabase): Promise<ReceiveOutcome>
+
+type ReceiveOutcome =
+  | { status: "claimed"; id: string }
+  | { status: "duplicate"; id: string | undefined };
+```
+
+**The insert is the claim.** `(source, external_id)` is unique, so at-least-once
+delivery and concurrent redeliveries are handled by PostgreSQL rather than by a
+check-then-act two requests could both pass. A test fires three concurrent
+receipts: one claims, two dedupe.
+
+A retry re-claims an event whose previous attempt **failed**, but never one already
+`processed` or currently `pending`. The raw payload is retained so a failed handler
+can be replayed without asking the sender to redeliver.
+
+`source` and `externalId` are required — without them there is nothing to
+deduplicate on, and accepting the event would risk applying it repeatedly.
+
+### `process(input, handler)`
+
+The shape most callers want — claim, handle, record:
+
+```ts
+await webhooks.inbound.process(
+  { source: "github", externalId: eventId, type: eventType, payload },
+  async (webhook) => {
+    await handle(webhook);
+    // return "ignored" for something you deliberately do not handle
+  },
+);
+```
+
+Marks `processed`, or `ignored` if the handler says so, or `failed` **and rethrows**
+so the sender sees a non-2xx and retries. The handler does not run for a duplicate.
+
+### Status meanings
+
+| Status | Means |
+| --- | --- |
+| `pending` | claimed, being handled |
+| `processed` | done |
+| `ignored` | verified but not actionable — unknown tenant, unhandled type |
+| `failed` | needs attention; re-claimable by a redelivery |
+
+`ignored` and `failed` are distinct on purpose. Sharing one provider account across
+environments makes unactionable events routine, and conflating them would bury real
+failures.
+
+```ts
+function markProcessed(id): Promise<void>
+function markFailed(id, error): Promise<void>
+function markIgnored(id): Promise<void>
+function get(source, externalId): Promise<InboundWebhook | undefined>
+function listFailed(options?): Promise<InboundWebhook[]>
+```
+
+---
+
+## Relationship to billing webhooks
+
+[Billing](./billing.md) has its own ingestion against `billing_events`, predating
+this module and using the same claim-on-insert mechanism. It stays separate because
+it also applies subscription state — this module is the general case for everything
+else.
+
+---
+
+## Testing
+
+```ts
+const outgoing = createOutgoingWebhooksService({
+  db,
+  sender: { async send(input) { calls.push(input); return { delivered: true, responseStatus: 200 }; } },
+  now: () => clock,
+  maxAttempts: 3,
+  initialRetryDelayMs: 1000,
+});
+
+const inbound = createInboundWebhooksService({ db, now: () => clock });
+```
+
+`WebhookSender` is one method, so retries, backoff and endpoint disabling are all
+testable with no network. Inject `now` and both retry scheduling and signature
+freshness become deterministic.
+
+The default `webhooks` export composes the two, bound to the configured database
+and a `fetch`-based sender:
+
+```ts
+webhooks.outgoing;   // OutgoingWebhooksService
+webhooks.inbound;    // InboundWebhooksService
+```