@digimuza/saas-core 0.0.2

package/docs/logger.md

@@ -0,0 +1,269 @@
+# Logger
+
+```ts
+import { logger, createLogger, createConfiguredLogger, setDefaultLogger } from "@digimuza/saas-core/logger";
+```
+
+> Orientation and recipes: [`src/logger/README.md`](../src/logger/README.md).
+
+Structured logging with bound context and redaction. No logging dependency — a
+level check, a field merge and a JSON line do not justify one, and the sink seam
+makes adding pino or a hosted collector an adapter rather than a migration.
+
+---
+
+## Setup
+
+```ts
+import { createConfiguredLogger, setDefaultLogger } from "@digimuza/saas-core/logger";
+
+setDefaultLogger(createConfiguredLogger());
+```
+
+`createConfiguredLogger()` reads the `app` config section: `LOG_LEVEL` for the
+level, `APP_ENV` to choose JSON (production) or human-readable (everything else),
+and binds `app` and `env` so several services shipping to one aggregator stay
+distinguishable.
+
+Until you call it, the core logs at `info` to stdout as JSON. Deliberate:
+importing a core module must never require configuration, or a migration script
+would need `LOG_LEVEL` set to run. That is also why `src/logger/default.ts`
+imports nothing but the logger itself — if it pulled in `config`, every module
+that logs would transitively depend on configuration.
+
+---
+
+## `Logger`
+
+```ts
+interface Logger {
+  readonly level: LogLevel;                                    // "debug" | "info" | "warn" | "error"
+
+  debug(message: string, fields?: LogFields): void;
+  info(message: string, fields?: LogFields): void;
+  warn(message: string, fields?: LogFields): void;
+  error(message: string, fields?: LogFields & { error?: unknown }): void;
+
+  child(fields: LogFields): Logger;
+  isEnabled(level: LogLevel): boolean;
+}
+```
+
+### `child(fields)`
+
+The reason the module exists:
+
+```ts
+const log = logger.child({ requestId, workspaceId: context.workspaceId, userId: user.id });
+
+log.info("project created", { projectId });
+log.warn("slow query", { durationMs });
+```
+
+Bind at the edge and every line beneath is attributable, without threading
+identifiers through call signatures. Children nest, inherit the level, share the
+sink, and never affect their parent.
+
+Per-call fields override bound ones.
+
+### Level checks happen first
+
+A suppressed record is never merged or serialised, and its field object is never
+even evaluated:
+
+```ts
+log.debug("plan", { get expensive() { return explain(); } });   // getter not called
+```
+
+So debug logging is not something you strip out for performance. `isEnabled` is
+there for work you would not want to do regardless — an extra query, a large
+serialisation.
+
+---
+
+## Errors
+
+```ts
+log.error("indexing failed", { projectId, error });
+```
+
+`error` accepts any throwable and is serialised to `{ name, message, stack, code?,
+cause?, errors? }`:
+
+- **`stack`** is capped at 20 lines.
+- **`cause`** is followed up to 4 levels. Dropping it would leave "query failed"
+  with no indication that the connection was refused.
+- **`AggregateError.errors`** is kept, or "Invalid configuration in 3 sections"
+  would say nothing about which.
+- **`code`** is kept when present, so [domain errors](./errors.md) stay filterable.
+- **The message is value-scanned**, because it is the likeliest place for a token
+  to end up by accident.
+
+---
+
+## Redaction
+
+On by default. The core handles API keys, session cookies, invitation tokens and
+webhook secrets; a logger that faithfully serialises whatever it is handed is the
+easiest way to move all of them into an aggregator a wider audience can read.
+
+Two independent passes, because either alone has a hole.
+
+### By key
+
+Case-insensitive **substring** match, so `workosCookiePassword` and
+`cookie_password` are both caught without enumerating spellings.
+
+`DEFAULT_REDACT_KEYS`: `password`, `passwd`, `secret`, `token`, `apikey`,
+`api_key`, `authorization`, `cookie`, `credential`, `privatekey`, `private_key`,
+`signature`, `keyhash`, `key_hash`, `sessiondata`, `bearer`, `otp`, `mfa`.
+
+### By value
+
+Catches a credential under an innocent key — `{ input: "dgk_…" }`:
+
+| Pattern | Source |
+| --- | --- |
+| `<prefix>_<32 hex>_<64 hex>` | this package's [API keys](./api-keys.md) |
+| `whsec_…` | this package's [webhook secrets](./webhooks.md) |
+| `wsk_…` | Revolut webhook secrets |
+| `sk_`/`rk_`/`pk_` + `live`/`test` | Stripe-shaped provider keys |
+| `re_…` | Resend keys |
+| `eyJ….….…` | JWTs, including the sealed session cookie |
+| `Bearer …` | an authorization header value |
+
+Anchored on **prefixes this system and its providers issue**, not on entropy.
+"Looks random" would strip ids, hashes and slugs, and a log with every identifier
+removed is not useful. There is a test asserting UUIDs, slugs, digests and realtime
+channel names all survive.
+
+### Configuring it
+
+```ts
+createLogger({
+  redact: {
+    additionalKeys: ["ssn", "dateOfBirth"],   // added to the defaults
+    // keys: [...],                            // replaces them entirely
+    // disableValueScanning: true,             // key redaction stays on
+  },
+});
+```
+
+**Over-redaction is the intended failure mode.** `tokenCount` is redacted because
+the key contains `token`. Replace `keys` if that matters more than the default
+safety.
+
+### Bounds
+
+A pathological object cannot stall the process or fill a disk: depth 6, 100 array
+items, 8192-character strings, cycles replaced with `[circular]`, functions never
+serialised (their source can embed a literal secret).
+
+### Redacting outside the logger
+
+`createRedactor(options)` returns the same function the logger uses, for anywhere
+else a value crosses a boundary you do not fully trust — an error-tracker
+integration, a support-tool response, a debug endpoint:
+
+```ts
+import { createRedactor } from "@digimuza/saas-core/logger";
+
+const redact = createRedactor({ additionalKeys: ["ssn"] });
+Sentry.setContext("request", redact(payload) as Record<string, unknown>);
+```
+
+It returns a plain, JSON-safe structure with the same bounds and both passes
+applied.
+
+---
+
+## Sinks
+
+```ts
+interface LogSink {
+  readonly name: string;
+  write(record: LogRecord): void;
+}
+```
+
+One method, because that is the whole job. Sampling, buffering and shipping belong
+to whatever you plug in.
+
+| Sink | Use |
+| --- | --- |
+| `createJsonSink({ write? })` | Production. One JSON object per line. |
+| `createPrettySink({ write? })` | Development. Lossy by design. |
+| `createMemorySink()` | Tests. `records`, `at(level)`, `clear()`. |
+| `createNoopSink()` | Silence. |
+| `createMultiSink([...])` | stdout plus an aggregator. |
+
+**Everything goes to stdout**, including errors. Many collectors treat anything on
+stderr as an error regardless of the record's own level, which would double-count
+warnings and mislabel info. Pass `write` to change that.
+
+**Fields cannot shadow `level`, `time` or `message`** — they are spread under the
+reserved keys, so a record cannot lie about itself.
+
+### Plugging in pino
+
+```ts
+import pino from "pino";
+
+const instance = pino();
+const sink: LogSink = {
+  name: "pino",
+  write: (record) => instance[record.level]({ ...record.fields, time: record.time }, record.message),
+};
+
+setDefaultLogger(createLogger({ level: "info", sink }));
+```
+
+---
+
+## Logging never fails the caller
+
+A throwing sink, an unserialisable field, a cyclic object — all swallowed.
+Logging is diagnostic; it is never a reason for the logged operation to fail.
+`createMultiSink` also isolates one broken sink from the rest.
+
+There is deliberately no fallback reporting when a sink throws: there is nowhere
+left to report it.
+
+---
+
+## What the core logs
+
+Very little, on purpose — a library that logs chattily is noise in someone else's
+application. Currently only failures it would otherwise swallow:
+
+| Where | Record |
+| --- | --- |
+| [events](./events.md) | `event handler failed` — a subscriber threw |
+| [realtime](./realtime.md) | `realtime transport error`, `realtime delivery error` |
+
+Both are cases where the operation deliberately succeeds and the failure would
+otherwise be invisible. Pass `onHandlerError` / `onError` to route them yourself.
+
+---
+
+## Testing
+
+```ts
+const sink = createMemorySink();
+const log = createLogger({ sink, level: "debug", now: () => fixedClock });
+
+log.error("failed", { error });
+
+expect(sink.at("error")[0]?.fields.error).toMatchObject({ name: "Error" });
+```
+
+`silenceDefaultLogger()` quiets the core in a test run, and
+`getDefaultLogger()` returns whatever is currently installed — useful for asserting
+that setup ran, or for a module that wants the core's logger without importing
+`config` through the `/logger` entry point.
+
+```ts
+import { getDefaultLogger, setDefaultLogger, silenceDefaultLogger } from "@digimuza/saas-core/logger";
+
+beforeEach(() => silenceDefaultLogger());
+```

package/docs/notifications.md

@@ -0,0 +1,179 @@
+# Notifications
+
+```ts
+import { notifications, createNotificationsService } from "@digimuza/saas-core/notifications";
+```
+
+> Orientation and recipes: [`src/notifications/README.md`](../src/notifications/README.md).
+
+In-app notifications addressed to a person.
+
+---
+
+## The ownership model
+
+A notification **belongs to its recipient**. `workspace_id` only records which
+tenant it concerns.
+
+Every read filters on `user_id`, so one user's notifications can never surface in
+another's list regardless of the workspace filter. That is why `list`, `markRead`
+and `remove` all take a `userId` rather than a `WorkspaceContext`.
+
+---
+
+## `notifications.create(input, tx?)`
+
+```ts
+function create(input: {
+  userId: string;                    // the recipient
+  workspaceId?: string | null;       // null for account-level notices
+  type: string;
+  title: string;                     // max 200 characters
+  body?: string;
+  url?: string;                      // relative, so it survives a domain change
+  data?: Record<string, unknown>;
+  dedupeKey?: string;
+}, tx?: CoreDatabase): Promise<Notification>
+```
+
+```ts
+await notifications.create({
+  userId: member.id,
+  workspaceId: context.workspaceId,
+  type: "project.shared",
+  title: "Apollo was shared with you",
+  url: `/w/${slug}/projects/${projectId}`,
+  dedupeKey: `project.shared:${projectId}:${member.id}`,
+});
+```
+
+**Notifying a non-member throws `NotFoundError`.** The title alone would tell them
+the workspace exists, and something about what happens in it. Verified whenever a
+`workspaces` service is wired — the default export wires it.
+
+## `notifications.createMany(inputs)`
+
+Skips any that duplicate an existing dedupe key, and returns only what was created.
+
+## `notifications.list(userId, options?)`
+
+```ts
+function list(userId: string, options?: {
+  unreadOnly?: boolean;
+  workspaceId?: string | null;   // `null` selects account-level notices
+  types?: readonly string[];
+  limit?: number;                 // default 50, capped at 200
+  before?: Date;                  // keyset pagination
+}): Promise<Notification[]>
+```
+
+`userId` must come from the session.
+
+Note the three-way `workspaceId`: omitted means every workspace, a value means one
+workspace, and explicit `null` means only account-level notices.
+
+## `notifications.countUnread(userId, options?)`
+
+```ts
+function countUnread(userId: string, options?: { workspaceId?: string | null }): Promise<number>
+```
+
+The bell-icon badge. Backed by an index on `(user_id, read_at, created_at desc)`,
+so unread rows are found without scanning a long history.
+
+## `notifications.markRead(userId, ids)` / `markAllRead(userId, options?)`
+
+```ts
+function markRead(userId: string, notificationIds: readonly string[]): Promise<number>
+function markAllRead(userId: string, options?: { workspaceId?: string | null }): Promise<number>
+```
+
+Both return how many rows actually changed, so marking an already-read notification
+returns `0` rather than erroring.
+
+Caller-scoped: another user's id matches nothing rather than raising, because
+raising would confirm it exists.
+
+## `notifications.remove(userId, id)`
+
+Throws `NotFoundError` for an id the caller does not own — same reasoning.
+
+---
+
+## Deduplication
+
+`(user_id, type, dedupe_key)` is a **partial** unique index. `create` returns the
+existing row for a reused key, so the call is safe to retry.
+
+Scoped per recipient *and* per type, deliberately: one underlying fact legitimately
+notifies several people, and two event types may derive a key from the same
+request.
+
+> Because the index is partial (`where dedupe_key is not null`), the `ON CONFLICT`
+> clause carries a matching predicate. PostgreSQL refuses to infer a partial index
+> as the arbiter otherwise, and every insert fails with `42P10`.
+
+---
+
+## Consuming events
+
+```ts
+events.on("workspace.member.created", async (event) => {
+  await notifications.create({
+    userId: event.data.userId,
+    workspaceId: event.workspaceId,
+    type: "workspace.joined",
+    title: "Welcome to the workspace",
+    dedupeKey: event.id,        // handlers can run twice
+  });
+});
+```
+
+**A handler is not durable.** A crash between the commit and the handler loses the
+notification. For anything that must not be missed, create it in the same
+transaction as the change (`create(input, tx)`), or from a
+[Trigger.dev task](./jobs.md) reading the persisted event.
+
+---
+
+## Email notifications are not automatic
+
+Which notifications also warrant an email is a product decision, and per-user
+preferences, digests and quiet hours are product features rather than core ones.
+Compose the two explicitly:
+
+```ts
+const notification = await notifications.create({ /* ... */ });
+
+if (await wantsEmail(member.id, notification.type)) {
+  await email.sendTemplate({
+    to: profile.email,
+    template: "project.shared",
+    data: { projectName },
+    idempotencyKey: notification.id,   // sending is not transactional
+  });
+}
+```
+
+---
+
+## Lifecycle
+
+Notifications **cascade away** when the recipient or the workspace is deleted —
+unlike [audit entries](./audit.md), which must outlive their subject. An inbox is
+disposable; a trail is not.
+
+---
+
+## Custom construction
+
+```ts
+createNotificationsService({
+  db,
+  workspaces,          // omit to skip the membership check
+  now: () => fixedClock,
+});
+```
+
+Omitting `workspaces` disables membership verification, which is only safe when
+every caller already holds a verified context.

package/docs/publishing.md

@@ -0,0 +1,128 @@
+# Publishing
+
+`@digimuza/saas-core` publishes to **npmjs.com with restricted access** — only your
+npm organisation can install it, matching `license: UNLICENSED`.
+
+The workflow is [`.github/workflows/publish.yml`](../.github/workflows/publish.yml).
+
+---
+
+## One-time setup
+
+1. **Create an npm automation token.** npmjs.com → Access Tokens → Generate →
+   *Automation*. Granular tokens work too; the token needs publish rights on the
+   `@digimuza` scope.
+
+2. **Add it as a repository secret** named `NPM_TOKEN`:
+   Settings → Secrets and variables → Actions → New repository secret.
+
+3. **Confirm the org can host restricted packages.** Restricted scoped packages
+   need a paid npm organisation. Publishing fails with a payment error otherwise —
+   at which point the options are a paid plan, going public, or GitHub Packages.
+
+4. **The `repository` field** points at `github.com/digimuza/sass-core` — note the
+   single `a`. The npm package is `@digimuza/saas-core`; only the repository is
+   spelled `sass-core`. npm links a package to its source from this field, so the
+   mismatch is intentional rather than a typo to "fix".
+
+---
+
+## Releasing
+
+```bash
+# 1. Bump the version. This is the only thing that decides what gets published.
+npm version minor          # or patch / major
+
+# 2. Push the commit and the tag it created.
+git push --follow-tags
+
+# 3. Create a GitHub Release for that tag.
+#    Publishing the release triggers the workflow.
+gh release create v0.15.0 --generate-notes
+```
+
+The tag must match `package.json` — the workflow checks, because tagging `v0.15.0`
+while the manifest still says `0.14.0` publishes the wrong version under the right
+tag, and the mistake is invisible afterwards.
+
+### Rehearsing it
+
+`workflow_dispatch` runs every check and packs the tarball without publishing.
+`dry-run` defaults to **true**, so an accidental manual run cannot publish:
+
+Actions → Publish → Run workflow → leave *dry-run* ticked.
+
+---
+
+## What the workflow checks before publishing
+
+Each of these has failed for real at some point, which is why it is a step rather
+than a comment.
+
+| Gate | Guards against |
+| --- | --- |
+| `npm ci` | a lockfile that disagrees with `package.json` |
+| Typecheck | — |
+| Test suite | — |
+| Clean build | a `dist` that only works incrementally |
+| **Migration drift** | shipping types that describe tables no migration creates |
+| **Version not already published** | a confusing mid-publish failure |
+| **Tag matches manifest** | publishing 0.14.0 as v0.15.0 |
+| **Tarball contents** | a missing `drizzle/`, or shipping `src/` and `tests/` |
+| **Loads under raw Node ESM** | a broken `.js` specifier in the built output |
+
+The tarball check asserts both directions. A missing `drizzle/meta/_journal.json`
+would leave consumers unable to migrate and would look fine until someone tried;
+a stray `src/` would double the package size and ship the tests.
+
+The raw-Node check matters because the package ships real ESM with `.js`
+specifiers and is explicitly meant to load without a bundler — see
+[db.md](./db.md) and `src/README.md`. A bad specifier would otherwise surface in
+someone's migration script.
+
+### Scripts are skipped at the publish step
+
+`prepublishOnly` runs `clean && build && test`. The gates already did all three, so
+the publish itself uses `--ignore-scripts` to stay a single fast auditable step
+rather than repeating a two-minute suite.
+
+---
+
+## Notes
+
+**Concurrency is serialised, not cancelled.** Two publishes racing would both try
+to claim the same version and the loser fails halfway through; cancelling one
+mid-flight is worse than queueing it.
+
+**No provenance attestation.** npm provenance requires a public package and a
+public source repository. Going public later means adding `--provenance` and
+`id-token: write`, and replacing `UNLICENSED` with a real licence.
+
+**Publishing is never automatic on merge.** A release is a decision, so it takes
+either a GitHub Release or an explicit manual run.
+
+---
+
+## Switching to GitHub Packages
+
+If a paid npm organisation is not worth it, GitHub Packages hosts private packages
+free on any plan and authenticates with the built-in `GITHUB_TOKEN` — no secret to
+manage:
+
+```yaml
+permissions:
+  contents: read
+  packages: write
+
+- uses: actions/setup-node@v4
+  with:
+    node-version: 22
+    registry-url: https://npm.pkg.github.com
+
+- run: npm publish --ignore-scripts
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+Consumers then need `@digimuza:registry=https://npm.pkg.github.com` in their
+`.npmrc`, which is the real cost of the switch.