@storyshelf/core 0.3.1 → 0.5.3

package/README.md

@@ -1,6 +1,6 @@
 # @storyshelf/core
 
-The heart of StoryShelf: the Hono router, adapter interfaces, models, capture pipeline, diff engine, and retention logic. Compose pluggable adapters into a complete self-hosted visual testing server.
+The domain layer of StoryShelf: adapter interfaces, models, capture pipeline, diff engine, and retention logic — with no HTTP dependency, so workers import it without pulling a server. The Hono router lives in `@storyshelf/app`. Compose pluggable adapters into a complete self-hosted visual testing server.
 
 ## Install
 
@@ -17,17 +17,22 @@ npm install @storyshelf/core
 ## Quick start
 
 ```ts
-import { createShelfRouter } from "@storyshelf/core";
+import { createShelfApp } from "@storyshelf/app";
 
-const app = createShelfRouter({
+const app = createShelfApp({
   database, // DatabaseAdapter
   storage, // StorageAdapter
   captureRunner, // CaptureRunner (optional)
-  auth, // AuthAdapter (optional)
+  auth, // Auth from @storyshelf/auth (optional)
   gitHosts, // GitHostProvider[] (optional)
   logger, // pino Logger (optional; built internally if omitted)
   ui: { name: "My Shelf" }, // UIConfig (optional)
-  config: { captureConcurrency: 2, purgeTtlDays: 30 }, // ShelfConfig (optional)
+  config: {
+    captureConcurrency: 2,
+    purgeTtlDays: 30,
+    branchTtlDays: 30,
+    branchGcIntervalMs: 86_400_000,
+  }, // ShelfConfig (optional)
 });
 
 // The returned app is a Hono instance; serve it with any Hono adapter.
@@ -36,21 +41,21 @@ serve({ fetch: app.fetch, port: 3000 });
 
 ## API
 
-### `createShelfRouter(options: ShelfOptions): Hono`
+### `createShelfApp(options: ShelfOptions): Hono`
 
 Assembles the router from the provided adapters. `ShelfOptions`:
 
-| Option          | Type                | Description                                                                              |
-| --------------- | ------------------- | ---------------------------------------------------------------------------------------- |
-| `database`      | `DatabaseAdapter`   | **Required.** Data access.                                                               |
-| `storage`       | `StorageAdapter`    | **Required.** Blob storage for screenshots, diffs, storybook archives.                   |
-| `captureRunner` | `CaptureRunner`     | Optional. Enables the async capture pipeline (pure renderer).                            |
-| `captureQueue`  | `CaptureQueue`      | Optional. Queue adapter; defaults to `InMemoryCaptureQueue`.                             |
-| `auth`          | `AuthAdapter`       | Optional. Enables auth and the login UI.                                                 |
-| `gitHosts`      | `GitHostProvider[]` | Optional. Git-host adapters (GitHub/GitLab) for status checks, merge gates, PR comments. |
-| `logger`        | `Logger` (pino)     | Optional. Shared logger. Construct a fallback via `createShelfLogger()`.                 |
-| `ui`            | `UIConfig`          | Optional. UI branding.                                                                   |
-| `config`        | `ShelfConfig`       | Optional. Server behavior.                                                               |
+| Option          | Type                        | Description                                                                              |
+| --------------- | --------------------------- | ---------------------------------------------------------------------------------------- |
+| `database`      | `DatabaseAdapter`           | **Required.** Data access.                                                               |
+| `storage`       | `StorageAdapter`            | **Required.** Blob storage for screenshots, diffs, storybook archives.                   |
+| `captureRunner` | `CaptureRunner`             | Optional. Enables the async capture pipeline (pure renderer).                            |
+| `captureQueue`  | `CaptureQueue`              | Optional. Queue adapter; defaults to `InMemoryCaptureQueue`.                             |
+| `auth`          | `Auth` (`@storyshelf/auth`) | Optional. Enables auth and the login UI.                                                 |
+| `gitHosts`      | `GitHostProvider[]`         | Optional. Git-host adapters (GitHub/GitLab) for status checks, merge gates, PR comments. |
+| `logger`        | `Logger` (pino)             | Optional. Shared logger. Construct a fallback via `createShelfLogger()`.                 |
+| `ui`            | `UIConfig`                  | Optional. UI branding.                                                                   |
+| `config`        | `ShelfConfig`               | Optional. Server behavior.                                                               |
 
 ### `ShelfConfig`
 
@@ -61,6 +66,8 @@ interface ShelfConfig {
   captureConcurrency?: number; // concurrent capture jobs (default 2)
   scratchDir?: string; // capture working directory (required with captureRunner)
   purgeTtlDays?: number; // purge builds older than N days
+  branchTtlDays?: number | null; // branch baseline TTL, days; null disables GC (default 30)
+  branchGcIntervalMs?: number; // branch GC interval, ms; daily via interval clock (default 86_400_000)
   maxUploadBytes?: number; // single-zip upload cap (default 1 GiB)
   maxInlineUnzipSize?: number; // inline statics extraction cap; unset = capture-only
   viewports?: Viewport[]; // capture viewports
@@ -73,7 +80,7 @@ interface ShelfConfig {
 interface UIConfig {
   name?: string;
   logo?: string;
-  favicon?: string;
+  favicon?: string; // deprecated: ignored, the app serves its own mark
   lightTheme?: BrandTheme;
   darkTheme?: BrandTheme;
 }
@@ -85,25 +92,25 @@ All adapters are constructor-injected (no AsyncLocalStorage). See `docs/architec
 
 - `DatabaseAdapter` (`core/adapter/database`) — `insert`, `update`, `get`, `remove`, `list`, `count`, `all`, `migrate`, `close`. Also exports `ListOptions` and the `createDrizzleAdapter` factory.
 - `StorageAdapter` (`core/adapter/storage`) — `read`, `write`, `delete`, `exists`, `list(prefix)`.
-- `AuthAdapter` (`core/adapter/auth`) — `check(request)`, `createSession(user)`, `destroySession(sessionId)`, optional `handleCallback(callback)`. Also exports `AuthUser`, `AuthCallback`, and the shared `SESSION_COOKIE`.
+- `Auth` (`@storyshelf/auth`) — the shelf authentication singleton: `check(request)`, `handler` (mount at `/api/auth/*`), `loginMethods()`, invites, sessions, passkeys. `AuthUser` and the shared `SESSION_COOKIE` live in `core/types`.
 - `CaptureRunner` (`core/adapter/capture-runner`) — a **pure capture renderer**: `render(input) => RenderResult`, `cancel(buildId)`. Also exports `RenderedSnapshot`, `RenderResult`, `StoryEntry`, `StorySourceAdapter`, `Viewport`.
 - `CaptureQueue` (`core/adapter/capture-queue`) — `enqueue({ buildId, reqId? })`, plus `status`, `active`, `recent`. Also exports `CaptureJob`, `QueueEntry`, `JobStatus`.
 - `GitHostProvider` / `GitHostAdapter` (`core/adapter/git-host`) — set commit status checks, detect merges, and upsert PR comments. Real providers ship in `@storyshelf/git-github` and `@storyshelf/git-gitlab`. Also exports `CheckStatus`.
 
 ### Logging
 
-`core` uses **pino** for structured JSON logging. `createShelfLogger({ level, transports, env })` (from `core/logger`) builds a logger writing to stdout by default, with optional extra pino worker transports (Sentry, PostHog, Datadog, GCP, OTEL collector, etc.). Pass the resulting `Logger` to `createShelfRouter({ logger })` (or construct it at your composition root) so request and background logs share one stream. The capture orchestrator derives a `reqId`-scoped child for background capture work, correlating each capture back to the triggering HTTP request. See ADR 0014.
+`core` uses **pino** for structured JSON logging. `createShelfLogger({ level, transports, env })` (from `core/logger`) builds a logger writing to stdout by default, with optional extra pino worker transports (Sentry, PostHog, Datadog, GCP, OTEL collector, etc.). Pass the resulting `Logger` to `createShelfApp({ logger })` (or construct it at your composition root) so request and background logs share one stream. The capture orchestrator derives a `reqId`-scoped child for background capture work, correlating each capture back to the triggering HTTP request. See ADR 0014.
 
 ### Capture, diff, and retention
 
 Import from `core/capture`, `core/diff`, and the model entries — never from the barrel:
 
-- `executeCaptureJob({ buildId, reqId }, deps)` (`core/capture`) — the capture **orchestrator**: loads the build, marks it `capturing`, extracts the uploaded archive into `scratchDir`, discovers stories, delegates rendering to a pure `CaptureRunner`, and persists. `createShelfRouter` wires it into a `CaptureQueue` when `capture` is supplied (and requires `ShelfConfig.scratchDir`). Also exports `CaptureJobOptions`.
+- `executeCaptureJob({ buildId, reqId }, deps)` (`core/capture`) — the capture **orchestrator**: loads the build, marks it `capturing`, extracts the uploaded archive into `scratchDir`, discovers stories, delegates rendering to a pure `CaptureRunner`, and persists. `createShelfApp` wires it into a `CaptureQueue` when `capture` is supplied (and requires `ShelfConfig.scratchDir`). Also exports `CaptureJobOptions`.
 - `persistCapture(ctx: CaptureContext)` (`core/capture`) — writes screenshots, diffs against the branch baseline, creates snapshots, and finalizes a build from a pure renderer's `captures`. Also exports `CaptureContext`.
 - `StorybookAdapter` (`core/capture`) — reads a built Storybook's `index.json`/`stories.json`.
 - `InMemoryCaptureQueue` (`core/capture`) — in-process, concurrency-limited queue for long-lived hosts; supply a remote queue with a separate worker for serverless.
 - `diffImages(baseline: Buffer, current: Buffer, options: DiffOptions): DiffResult` (`core/diff`) — pixelmatch-based diff. Also exports `DiffOptions`, `DiffResult`.
-- Models, schema, and row types back every entity; retention runs inside the router. (Models are private implementation details with no public entry — reach row types via `core/schema`.)
+- Models, schema, and row types back every entity; retention runs inside the router (`Retention.purge` for builds + `Retention.purgeStaleBranches` for branch GC via `retention-timer.ts` daily sweep). (Models are private implementation details with no public entry — reach row types via `core/schema`.)
 
 ### Helpers
 
@@ -112,7 +119,7 @@ Import from `core/capture`, `core/diff`, and the model entries — never from th
 
 ## How it fits in
 
-`core` is the framework everything else plugs into: `createShelfRouter` takes database, storage, capture, and auth adapters (from the `db-*`, `storage-*`, and `auth-*` packages) and produces a complete Hono server. The web UI is server-rendered `hono/jsx` + HTMX, and custom UIs can consume the JSON API under `/api/v1`.
+`core` is the framework everything else plugs into: `createShelfApp` takes database, storage, capture, and auth adapters (from the `db-*`, `storage-*`, and `auth-*` packages) and produces a complete Hono server. The web UI is server-rendered `hono/jsx` + HTMX, and custom UIs can consume the JSON API under `/api/v1`.
 
 See `docs/architecture.md` and the ADRs in `docs/adr/`.
 
@@ -120,13 +127,13 @@ See `docs/architecture.md` and the ADRs in `docs/adr/`.
 
 The core router is runtime-agnostic (Web `Request`/`Response`, `fetch`, `crypto`, `URL`). The only Node-specific piece is the in-process `InMemoryCaptureQueue`, which suits long-lived Node servers; serverless runtimes swap in a remote `CaptureQueue` (e.g. `@storyshelf/queue-sqs`) plus a separate worker. You assemble a server for any platform — `storyshelf server init` generates a scaffold with the adapters you choose:
 
-| Platform                                   | Database                 | Storage                          | Capture queue                   | Server entry               |
-| ------------------------------------------ | ------------------------ | -------------------------------- | ------------------------------- | -------------------------- |
-| **Vercel**                                 | `@storyshelf/db-turso`   | `@storyshelf/storage-s3` (R2/S3) | Remote `CaptureQueue` + worker  | Hono + `@hono/vercel-edge` |
-| **Cloudflare Workers**                     | `@storyshelf/db-turso`   | `@storyshelf/storage-s3` (R2)    | Workers Queues `CaptureQueue`   | Hono + Workers entry       |
-| **Azure Functions**                        | `@storyshelf/db-turso`   | `@storyshelf/storage-s3` (Blob)  | Azure Queues `CaptureQueue`     | Hono + Azure handler       |
-| **AWS Lambda**                             | `@storyshelf/db-turso`   | `@storyshelf/storage-s3`         | SQS `CaptureQueue`              | Hono + Lambda handler      |
-| **Deno Deploy**                            | `@storyshelf/db-turso`   | `@storyshelf/storage-s3`         | Custom `CaptureQueue` (Deno KV) | Hono + Deno entry          |
-| **Bun / Node (VPS, Fly, Railway, Render)** | `db-sqlite` / `db-turso` | `storage-local` / `storage-s3`   | `InMemoryCaptureQueue`          | `storyshelf-server serve`  |
+| Platform                                   | Database                              | Storage                          | Capture queue                   | Server entry               |
+| ------------------------------------------ | ------------------------------------- | -------------------------------- | ------------------------------- | -------------------------- |
+| **Vercel**                                 | `@storyshelf/db-sqlite/turso`         | `@storyshelf/storage-s3` (R2/S3) | Remote `CaptureQueue` + worker  | Hono + `@hono/vercel-edge` |
+| **Cloudflare Workers**                     | `@storyshelf/db-sqlite/turso`         | `@storyshelf/storage-s3` (R2)    | Workers Queues `CaptureQueue`   | Hono + Workers entry       |
+| **Azure Functions**                        | `@storyshelf/db-sqlite/turso`         | `@storyshelf/storage-s3` (Blob)  | Azure Queues `CaptureQueue`     | Hono + Azure handler       |
+| **AWS Lambda**                             | `@storyshelf/db-sqlite/turso`         | `@storyshelf/storage-s3`         | SQS `CaptureQueue`              | Hono + Lambda handler      |
+| **Deno Deploy**                            | `@storyshelf/db-sqlite/turso`         | `@storyshelf/storage-s3`         | Custom `CaptureQueue` (Deno KV) | Hono + Deno entry          |
+| **Bun / Node (VPS, Fly, Railway, Render)** | `db-sqlite` (+ `./bun-sqlite` on Bun) | `storage-local` / `storage-s3`   | `InMemoryCaptureQueue`          | `storyshelf-server serve`  |
 
 All clouds are equal — pick the adapters that match your infrastructure. See the **Deployment** guide for recipes including a minimal Turso + S3 + `InMemoryCaptureQueue` example.

package/dist/adapter/capture-queue.d.mts

@@ -18,6 +18,20 @@ interface CaptureJob {
   buildId: string;
   /** Request id used to correlate the background job with the request that queued it. */
   reqId?: string;
+  /**
+   * W3C `traceparent` of the enqueueing request. Workers continue this trace
+   * instead of starting a root span; absent means start a new trace.
+   */
+  traceparent?: string;
+}
+/** A job polled from a queue with transport metadata. */
+interface PollableJob extends CaptureJob {
+  /** Transport receipt handle (SQS, Redis pop token, etc.). */
+  receipt?: string;
+  /** Number of delivery attempts already made (0 = first delivery). */
+  attempts?: number;
+  /** Raw transport message for debugging. */
+  raw?: unknown;
 }
 /**
  * A capture job queue, decoupled from the runtime.
@@ -46,6 +60,20 @@ interface CaptureQueue extends Adapter<{
   /** The most recent queue entries, newest first. */
   recent(limit: number): Promise<QueueEntry[]>;
 }
+/** Extension for queues that support worker-side polling. */
+interface PollableCaptureQueue extends CaptureQueue {
+  /** Poll for a single job; returns null if none available within waitMs. */
+  poll(options?: {
+    waitMs?: number;
+  }): Promise<PollableJob | null>;
+  /** Acknowledge successful processing of a polled job. */
+  ack(job: PollableJob): Promise<void>;
+  /** Negatively acknowledge; requeue with optional delay when possible. */
+  nack(job: PollableJob, options?: {
+    requeue?: boolean;
+    delayMs?: number;
+  }): Promise<void>;
+}
 //#endregion
-export { CaptureJob, CaptureQueue, JobStatus, QueueEntry };
+export { CaptureJob, CaptureQueue, JobStatus, PollableCaptureQueue, PollableJob, QueueEntry };
 //# sourceMappingURL=capture-queue.d.mts.map

package/dist/adapter/capture-runner.d.mts

@@ -1,8 +1,8 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { JobStatus } from "./capture-queue.mjs";
 import { StoryEntry, StorySourceAdapter, Viewport } from "../capture/adapter.mjs";
 import { Adapter } from "./metadata.mjs";
+import { JobStatus } from "./capture-queue.mjs";
 import { Logger } from "pino";
 //#region src/adapters/capture-runner.d.ts
 /** A screenshot produced by a capture renderer. */
@@ -11,6 +11,8 @@ interface RenderedSnapshot {
   story: StoryEntry;
   /** Viewport name the screenshot was captured at. */
   viewportName: string;
+  /** Exact viewport dimensions captured at; falls back to the project list lookup in the pipeline. */
+  viewport?: Viewport;
   /** PNG screenshot bytes. */
   screenshot: Buffer;
 }
@@ -41,8 +43,12 @@ interface RenderResult {
  * orchestrator's job (see `capture/orchestrator.ts`), keeping every adapter
  * implementation free of server concerns.
  */
+type BrowserName = "chromium" | "firefox" | "webkit" | "chrome";
+/** Browser names accepted for capture rendering (Chromium default). */
+declare const BROWSER_NAMES: readonly ["chromium", "firefox", "webkit", "chrome"];
 interface CaptureRunner extends Adapter<{
   readonly category: "capture-runner";
+  readonly supportedBrowsers?: readonly BrowserName[];
 }> {
   /**
    * Render configured viewports for the given stories of an extracted
@@ -65,10 +71,20 @@ interface CaptureRunner extends Adapter<{
     executePlay?: boolean;
     /** Timeout for play function execution in ms. */
     playTimeoutMs?: number;
+    /** Whether to run a11y checks (axe) before screenshot; annotated as non-blocking. */
+    runA11y?: boolean;
+    /** Browser to use for rendering (chromium default). */
+    browser?: BrowserName;
+    /**
+     * Test/extension seam: override the story source adapter (defaults to
+     * `StorybookAdapter`). Only the renderer uses it; discovery stays the
+     * orchestrator's job.
+     */
+    adapter?: StorySourceAdapter;
   }): Promise<RenderResult>;
   /** Cancel a pending or in-flight render for a build. */
   cancel(buildId: string): Promise<void>;
 }
 //#endregion
-export { CaptureRunner, type JobStatus, RenderFailure, RenderResult, RenderedSnapshot, type StoryEntry, type StorySourceAdapter, type Viewport };
+export { BROWSER_NAMES, BrowserName, CaptureRunner, type JobStatus, RenderFailure, RenderResult, RenderedSnapshot, type StoryEntry, type StorySourceAdapter, type Viewport };
 //# sourceMappingURL=capture-runner.d.mts.map

package/dist/adapter/capture-runner.mjs

@@ -1,4 +1,15 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-export {};
+//#region src/adapters/capture-runner.ts
+/** Browser names accepted for capture rendering (Chromium default). */
+const BROWSER_NAMES = [
+	"chromium",
+	"firefox",
+	"webkit",
+	"chrome"
+];
+//#endregion
+export { BROWSER_NAMES };
+
+//# sourceMappingURL=capture-runner.mjs.map

package/dist/adapter/capture-runner.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-runner.mjs","names":[],"sources":["../../src/adapters/capture-runner.ts"],"sourcesContent":["/**\n * Capture-runner adapter interface: render story screenshots for a build.\n */\nimport type { Logger } from \"pino\";\nimport type { StoryEntry, StorySourceAdapter, Viewport } from \"../capture/adapter.ts\";\nimport type { Adapter } from \"./metadata.ts\";\n\nexport type { JobStatus } from \"./capture-queue.ts\";\nexport type { StoryEntry, StorySourceAdapter, Viewport } from \"../capture/adapter.ts\";\n\n/** A screenshot produced by a capture renderer. */\nexport interface RenderedSnapshot {\n  /** The rendered story (echoed back from the render request). */\n  story: StoryEntry;\n  /** Viewport name the screenshot was captured at. */\n  viewportName: string;\n  /** Exact viewport dimensions captured at; falls back to the project list lookup in the pipeline. */\n  viewport?: Viewport;\n  /** PNG screenshot bytes. */\n  screenshot: Buffer;\n}\n\n/** A story/viewport that a renderer could not capture. */\nexport interface RenderFailure {\n  /** Story that failed to render. */\n  storyId: string;\n  /** Viewport that failed to render. */\n  viewportName: string;\n  /** Error message. */\n  error: string;\n}\n\n/** The outcome of a render request. */\nexport interface RenderResult {\n  /** Screenshots the renderer produced successfully. */\n  captures: RenderedSnapshot[];\n  /** Story/viewport pairs the renderer could not capture. */\n  failures: RenderFailure[];\n}\n\n/**\n * A pure capture renderer.\n *\n * Adapters implementing `CaptureRunner` render screenshots from an\n * already-extracted Storybook directory and return PNG buffers. They are\n * intentionally pure: they perform **no** database, storage, or build-state\n * management. Loading the build, extracting the uploaded archive, persisting\n * snapshots/baselines/diffs, and advancing build status are the capture\n * orchestrator's job (see `capture/orchestrator.ts`), keeping every adapter\n * implementation free of server concerns.\n */\nexport type BrowserName = \"chromium\" | \"firefox\" | \"webkit\" | \"chrome\";\n\n/** Browser names accepted for capture rendering (Chromium default). */\nexport const BROWSER_NAMES = [\"chromium\", \"firefox\", \"webkit\", \"chrome\"] as const;\n\nexport interface CaptureRunner extends Adapter<{\n  readonly category: \"capture-runner\";\n  readonly supportedBrowsers?: readonly BrowserName[];\n}> {\n  /**\n   * Render configured viewports for the given stories of an extracted\n   * Storybook and return the screenshot buffers.\n   *\n   * @param input - Render request with the extracted Storybook directory.\n   */\n  render(input: {\n    /** Build being captured, used to correlate cancels with in-flight work. */\n    buildId: string;\n    /** Root of the already-extracted Storybook build. */\n    storybookDir: string;\n    /** Stories to render. */\n    stories: StoryEntry[];\n    /** Viewports to capture. */\n    viewports: Viewport[];\n    /** Optional logger for render-time diagnostics. */\n    logger?: Logger;\n    /** Whether to execute Storybook play functions before screenshot. */\n    executePlay?: boolean;\n    /** Timeout for play function execution in ms. */\n    playTimeoutMs?: number;\n    /** Whether to run a11y checks (axe) before screenshot; annotated as non-blocking. */\n    runA11y?: boolean;\n    /** Browser to use for rendering (chromium default). */\n    browser?: BrowserName;\n    /**\n     * Test/extension seam: override the story source adapter (defaults to\n     * `StorybookAdapter`). Only the renderer uses it; discovery stays the\n     * orchestrator's job.\n     */\n    adapter?: StorySourceAdapter;\n  }): Promise<RenderResult>;\n\n  /** Cancel a pending or in-flight render for a build. */\n  cancel(buildId: string): Promise<void>;\n}\n"],"mappings":";;;;;AAsDA,MAAa,gBAAgB;CAAC;CAAY;CAAW;CAAU;AAAQ"}

package/dist/adapter/database.d.mts

@@ -1,9 +1,36 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { Adapter, AdapterMetadata } from "./metadata.mjs";
-import { SQL } from "drizzle-orm";
-import { AnySQLiteTable } from "drizzle-orm/sqlite-core";
+import { SQL, Table } from "drizzle-orm";
 //#region src/adapters/database.d.ts
+/** Type-safe table map enforced on every DatabaseAdapter. */
+interface Tables {
+  projects: Table;
+  projectStatusConfigs: Table;
+  builds: Table;
+  captureAttempts: Table;
+  captureLogs: Table;
+  snapshots: Table;
+  baselines: Table;
+  comments: Table;
+  labelTypes: Table;
+  buildLabels: Table;
+  tokens: Table;
+  webhooks: Table;
+  notificationChannels: Table;
+  notificationSubscriptions: Table;
+  users: Table;
+  userInviteTokens: Table;
+  projectMembers: Table;
+  projectGroupMappings: Table;
+  contentRefs: Table;
+}
+/** Table keys every DatabaseAdapter must expose (contract + validation share this). */
+declare const REQUIRED_TABLE_KEYS: string[];
+/** Largest page any adapter serves in one list call. */
+declare const MAX_LIST_LIMIT = 1000;
+/** Clamp a list limit into [1, MAX_LIST_LIMIT]; undefined stays undefined. */
+declare function clampListLimit(limit?: number): number | undefined;
 /** Options that narrow and page a list query. */
 interface ListOptions {
   /** SQL WHERE condition. */
@@ -15,40 +42,63 @@ interface ListOptions {
   /** Number of rows to skip. */
   offset?: number;
 }
-/** Database abstraction over Drizzle tables, agnostic of the underlying driver. */
+/**
+ * Transactional CRUD subset available inside {@link DatabaseAdapter.transact}.
+ * Mirrors the adapter surface minus metadata, lifecycle, and raw `all`
+ * (opaque to transactions on some drivers).
+ */
+interface TxStore {
+  /** Insert a row and return the inserted record. */
+  insert<T extends Table>(table: T, values: T["$inferInsert"]): Promise<T["$inferSelect"]>;
+  /** Update a row by id and return the updated record. */
+  update<T extends Table>(table: T, id: string, values: Partial<T["$inferInsert"]>): Promise<T["$inferSelect"]>;
+  /** Fetch a single row by id, or null if not found. */
+  get<T extends Table>(table: T, id: string): Promise<T["$inferSelect"] | null>;
+  /** Delete a row by id. */
+  remove(table: Table, id: string): Promise<void>;
+  /** List rows matching the given options. */
+  list<T extends Table>(table: T, opts?: ListOptions): Promise<T["$inferSelect"][]>;
+  /** Count rows matching an optional where condition. */
+  count(table: Table, where?: SQL): Promise<number>;
+}
+/** Database abstraction over Drizzle tables, agnostic of dialect and driver. */
 interface DatabaseAdapter extends Adapter<{
   readonly category: "database";
 }> {
+  /** Table handles for this adapter's dialect, enforced with type safety. */
+  readonly tables: Tables;
   /** Insert a row and return the inserted record. */
-  insert<T extends AnySQLiteTable>(table: T, values: T["$inferInsert"]): Promise<T["$inferSelect"]>;
+  insert<T extends Table>(table: T, values: T["$inferInsert"]): Promise<T["$inferSelect"]>;
   /** Update a row by id and return the updated record. */
-  update<T extends AnySQLiteTable>(table: T, id: string, values: Partial<T["$inferInsert"]>): Promise<T["$inferSelect"]>;
+  update<T extends Table>(table: T, id: string, values: Partial<T["$inferInsert"]>): Promise<T["$inferSelect"]>;
   /** Fetch a single row by id, or null if not found. */
-  get<T extends AnySQLiteTable>(table: T, id: string): Promise<T["$inferSelect"] | null>;
+  get<T extends Table>(table: T, id: string): Promise<T["$inferSelect"] | null>;
   /** Delete a row by id. */
-  remove(table: AnySQLiteTable, id: string): Promise<void>;
+  remove(table: Table, id: string): Promise<void>;
   /** List rows matching the given options. */
-  list<T extends AnySQLiteTable>(table: T, opts?: ListOptions): Promise<T["$inferSelect"][]>;
+  list<T extends Table>(table: T, opts?: ListOptions): Promise<T["$inferSelect"][]>;
   /** Count rows matching an optional where condition. */
-  count(table: AnySQLiteTable, where?: SQL): Promise<number>;
+  count(table: Table, where?: SQL): Promise<number>;
   /** Run an arbitrary SQL query and return typed rows. */
   all<T>(query: SQL): Promise<T[]>;
+  /**
+   * Run `fn` inside a transaction when the driver supports one.
+   * Commits on resolve, rolls back on throw. Drivers without transaction
+   * support omit this; callers must use `?.` and accept sequential execution.
+   */
+  transact?<R>(fn: (tx: TxStore) => Promise<R>): Promise<R>;
 }
 /** Driver-supplied identity plus lifecycle hooks. */
 interface DrizzleAdapterOptions {
   metadata: AdapterMetadata & {
     readonly category: "database";
   };
+  tables: Tables;
   migrate: () => Promise<void> | void;
   close: () => Promise<void> | void;
+  /** Cheap liveness probe (e.g. `SELECT 1`); omitted when the driver has none. */
+  ping?: () => Promise<void> | void;
 }
-/**
- * Build a {@link DatabaseAdapter} over any SQLite-compatible Drizzle
- * dialect. Sync results (node:sqlite) and promises (libSQL) are both
- * awaited, so drivers only supply connection setup, metadata, and the
- * driver-specific migrate/close.
- */
-declare function createDrizzleAdapter(db: unknown, options: DrizzleAdapterOptions): DatabaseAdapter;
 //#endregion
-export { DatabaseAdapter, DrizzleAdapterOptions, ListOptions, createDrizzleAdapter };
+export { DatabaseAdapter, DrizzleAdapterOptions, ListOptions, MAX_LIST_LIMIT, REQUIRED_TABLE_KEYS, Tables, TxStore, clampListLimit };
 //# sourceMappingURL=database.d.mts.map

package/dist/adapter/database.mjs

@@ -1,63 +1,30 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-import { eq, getTableColumns } from "drizzle-orm";
 //#region src/adapters/database.ts
-function idOf(table) {
-	const id = getTableColumns(table)["id"];
-	if (!id) throw new Error("Table has no id column");
-	return id;
-}
-function applyListOptions(query, opts) {
-	let current = query;
-	if (opts.where) current = current.where(opts.where);
-	if (opts.orderBy) current = current.orderBy(opts.orderBy);
-	if (opts.limit !== void 0) current = current.limit(opts.limit);
-	if (opts.offset !== void 0) current = current.offset(opts.offset);
-	return current;
-}
-/**
-* Build the database lifecycle: migrations run in `init`, the connection
-* closes in `close`. Close tolerates repeated calls (drivers may not).
-*/
-function buildLifecycle(options) {
-	let closed = false;
-	return {
-		init: async () => {
-			await options.migrate();
-		},
-		close: async () => {
-			if (closed) return;
-			closed = true;
-			await options.close();
-		}
-	};
-}
-/**
-* Build a {@link DatabaseAdapter} over any SQLite-compatible Drizzle
-* dialect. Sync results (node:sqlite) and promises (libSQL) are both
-* awaited, so drivers only supply connection setup, metadata, and the
-* driver-specific migrate/close.
-*/
-function createDrizzleAdapter(db, options) {
-	const drizzle = db;
-	return {
-		metadata: options.metadata,
-		lifecycle: buildLifecycle(options),
-		insert: async (table, values) => await drizzle.insert(table).values(values).returning().get(),
-		update: async (table, id, values) => await drizzle.update(table).set(values).where(eq(idOf(table), id)).returning().get(),
-		get: async (table, id) => await drizzle.select().from(table).where(eq(idOf(table), id)).limit(1).get() ?? null,
-		remove: async (table, id) => {
-			await drizzle.delete(table).where(eq(idOf(table), id)).run();
-		},
-		list: async (table, opts = {}) => {
-			return await applyListOptions(drizzle.select().from(table), opts).all();
-		},
-		count: async (table, where) => await drizzle.$count(table, where),
-		all: async (query) => await drizzle.all(query)
-	};
+/** Table keys every DatabaseAdapter must expose (contract + validation share this). */
+const REQUIRED_TABLE_KEYS = [
+	"projects",
+	"builds",
+	"snapshots",
+	"baselines",
+	"comments",
+	"labelTypes",
+	"buildLabels",
+	"tokens",
+	"webhooks",
+	"users",
+	"projectMembers"
+];
+/** Largest page any adapter serves in one list call. */
+const MAX_LIST_LIMIT = 1e3;
+/** Clamp a list limit into [1, MAX_LIST_LIMIT]; undefined stays undefined. */
+function clampListLimit(limit) {
+	if (limit === void 0) return;
+	if (!Number.isFinite(limit)) return MAX_LIST_LIMIT;
+	return Math.min(Math.max(Math.floor(limit), 1), MAX_LIST_LIMIT);
 }
 //#endregion
-export { createDrizzleAdapter };
+export { MAX_LIST_LIMIT, REQUIRED_TABLE_KEYS, clampListLimit };
 
 //# sourceMappingURL=database.mjs.map

package/dist/adapter/database.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"database.mjs","names":[],"sources":["../../src/adapters/database.ts"],"sourcesContent":["/**\n * Database adapter interface: query builders over explicitly typed tables.\n */\nimport type { SQL } from \"drizzle-orm\";\nimport { eq, getTableColumns } from \"drizzle-orm\";\nimport type { AnySQLiteTable, SQLiteColumn } from \"drizzle-orm/sqlite-core\";\nimport type { Adapter, AdapterLifecycle, AdapterMetadata } from \"./metadata.ts\";\n\n/** Options that narrow and page a list query. */\nexport interface ListOptions {\n  /** SQL WHERE condition. */\n  where?: SQL;\n  /** SQL ORDER BY condition. */\n  orderBy?: SQL;\n  /** Maximum number of rows to return. */\n  limit?: number;\n  /** Number of rows to skip. */\n  offset?: number;\n}\n\n/** Database abstraction over Drizzle tables, agnostic of the underlying driver. */\nexport interface DatabaseAdapter extends Adapter<{ readonly category: \"database\" }> {\n  /** Insert a row and return the inserted record. */\n  insert<T extends AnySQLiteTable>(table: T, values: T[\"$inferInsert\"]): Promise<T[\"$inferSelect\"]>;\n  /** Update a row by id and return the updated record. */\n  update<T extends AnySQLiteTable>(\n    table: T,\n    id: string,\n    values: Partial<T[\"$inferInsert\"]>,\n  ): Promise<T[\"$inferSelect\"]>;\n  /** Fetch a single row by id, or null if not found. */\n  get<T extends AnySQLiteTable>(table: T, id: string): Promise<T[\"$inferSelect\"] | null>;\n  /** Delete a row by id. */\n  remove(table: AnySQLiteTable, id: string): Promise<void>;\n  /** List rows matching the given options. */\n  list<T extends AnySQLiteTable>(table: T, opts?: ListOptions): Promise<T[\"$inferSelect\"][]>;\n  /** Count rows matching an optional where condition. */\n  count(table: AnySQLiteTable, where?: SQL): Promise<number>;\n  /** Run an arbitrary SQL query and return typed rows. */\n  all<T>(query: SQL): Promise<T[]>;\n}\n\n/** A value or a promise of one (sync node:sqlite vs async libSQL drivers). */\ntype MaybePromise<T> = T | Promise<T>;\n\n/** Chainable select surface shared by the sync and async Drizzle dialects. */\ninterface DrizzleSelectChain {\n  where(where: SQL): DrizzleSelectChain;\n  orderBy(order: SQL): DrizzleSelectChain;\n  limit(n: number): DrizzleSelectChain;\n  offset(n: number): DrizzleSelectChain;\n  get(): MaybePromise<unknown>;\n  all(): MaybePromise<unknown[]>;\n}\n\n/**\n * Minimal Drizzle surface consumed by {@link createDrizzleAdapter}. Drivers\n * pass their dialect instance as `unknown`; the cast lives here, once, so\n * driver packages stay fully typed. Covered by the adapter contract tests.\n */\ninterface DrizzleLike {\n  insert(table: AnySQLiteTable): {\n    values(values: unknown): { returning(): { get(): MaybePromise<unknown> } };\n  };\n  update(table: AnySQLiteTable): {\n    set(values: unknown): { where(where: SQL): { returning(): { get(): MaybePromise<unknown> } } };\n  };\n  select(): { from(table: AnySQLiteTable): DrizzleSelectChain };\n  delete(table: AnySQLiteTable): { where(where: SQL): { run(): MaybePromise<unknown> } };\n  $count(table: AnySQLiteTable, where?: SQL): MaybePromise<number>;\n  all<T>(query: SQL): MaybePromise<T[]>;\n}\n\n/** Driver-supplied identity plus lifecycle hooks. */\nexport interface DrizzleAdapterOptions {\n  metadata: AdapterMetadata & { readonly category: \"database\" };\n  migrate: () => Promise<void> | void;\n  close: () => Promise<void> | void;\n}\n\nfunction idOf(table: AnySQLiteTable): SQLiteColumn {\n  const id = getTableColumns(table)[\"id\"];\n  if (!id) {\n    throw new Error(\"Table has no id column\");\n  }\n  return id;\n}\n\nfunction applyListOptions(query: DrizzleSelectChain, opts: ListOptions): DrizzleSelectChain {\n  let current = query;\n  if (opts.where) {\n    current = current.where(opts.where);\n  }\n  if (opts.orderBy) {\n    current = current.orderBy(opts.orderBy);\n  }\n  if (opts.limit !== undefined) {\n    current = current.limit(opts.limit);\n  }\n  if (opts.offset !== undefined) {\n    current = current.offset(opts.offset);\n  }\n  return current;\n}\n\n/**\n * Build the database lifecycle: migrations run in `init`, the connection\n * closes in `close`. Close tolerates repeated calls (drivers may not).\n */\nfunction buildLifecycle(options: DrizzleAdapterOptions): AdapterLifecycle {\n  let closed = false;\n  return {\n    init: async () => {\n      await options.migrate();\n    },\n    close: async () => {\n      if (closed) {\n        return;\n      }\n      closed = true;\n      await options.close();\n    },\n  };\n}\n\n/**\n * Build a {@link DatabaseAdapter} over any SQLite-compatible Drizzle\n * dialect. Sync results (node:sqlite) and promises (libSQL) are both\n * awaited, so drivers only supply connection setup, metadata, and the\n * driver-specific migrate/close.\n */\nexport function createDrizzleAdapter(db: unknown, options: DrizzleAdapterOptions): DatabaseAdapter {\n  const drizzle = db as DrizzleLike;\n  return {\n    metadata: options.metadata,\n    lifecycle: buildLifecycle(options),\n    insert: async <T extends AnySQLiteTable>(\n      table: T,\n      values: T[\"$inferInsert\"],\n    ): Promise<T[\"$inferSelect\"]> =>\n      (await drizzle.insert(table).values(values).returning().get()) as T[\"$inferSelect\"],\n    update: async <T extends AnySQLiteTable>(\n      table: T,\n      id: string,\n      values: Partial<T[\"$inferInsert\"]>,\n    ): Promise<T[\"$inferSelect\"]> =>\n      (await drizzle\n        .update(table)\n        .set(values)\n        .where(eq(idOf(table), id))\n        .returning()\n        .get()) as T[\"$inferSelect\"],\n    get: async <T extends AnySQLiteTable>(\n      table: T,\n      id: string,\n    ): Promise<T[\"$inferSelect\"] | null> =>\n      ((await drizzle\n        .select()\n        .from(table)\n        .where(eq(idOf(table), id))\n        .limit(1)\n        .get()) as T[\"$inferSelect\"] | undefined) ?? null,\n    remove: async (table: AnySQLiteTable, id: string): Promise<void> => {\n      await drizzle\n        .delete(table)\n        .where(eq(idOf(table), id))\n        .run();\n    },\n    list: async <T extends AnySQLiteTable>(\n      table: T,\n      opts: ListOptions = {},\n    ): Promise<T[\"$inferSelect\"][]> => {\n      const query = applyListOptions(drizzle.select().from(table), opts);\n      const rows: unknown = await query.all();\n      return rows as T[\"$inferSelect\"][];\n    },\n    count: async (table: AnySQLiteTable, where?: SQL): Promise<number> =>\n      await drizzle.$count(table, where),\n    all: async <T>(query: SQL): Promise<T[]> => await drizzle.all(query),\n  };\n}\n"],"mappings":";;;;;AAgFA,SAAS,KAAK,OAAqC;CACjD,MAAM,KAAK,gBAAgB,KAAK,CAAC,CAAC;CAClC,IAAI,CAAC,IACH,MAAM,IAAI,MAAM,wBAAwB;CAE1C,OAAO;AACT;AAEA,SAAS,iBAAiB,OAA2B,MAAuC;CAC1F,IAAI,UAAU;CACd,IAAI,KAAK,OACP,UAAU,QAAQ,MAAM,KAAK,KAAK;CAEpC,IAAI,KAAK,SACP,UAAU,QAAQ,QAAQ,KAAK,OAAO;CAExC,IAAI,KAAK,UAAU,KAAA,GACjB,UAAU,QAAQ,MAAM,KAAK,KAAK;CAEpC,IAAI,KAAK,WAAW,KAAA,GAClB,UAAU,QAAQ,OAAO,KAAK,MAAM;CAEtC,OAAO;AACT;;;;;AAMA,SAAS,eAAe,SAAkD;CACxE,IAAI,SAAS;CACb,OAAO;EACL,MAAM,YAAY;GAChB,MAAM,QAAQ,QAAQ;EACxB;EACA,OAAO,YAAY;GACjB,IAAI,QACF;GAEF,SAAS;GACT,MAAM,QAAQ,MAAM;EACtB;CACF;AACF;;;;;;;AAQA,SAAgB,qBAAqB,IAAa,SAAiD;CACjG,MAAM,UAAU;CAChB,OAAO;EACL,UAAU,QAAQ;EAClB,WAAW,eAAe,OAAO;EACjC,QAAQ,OACN,OACA,WAEC,MAAM,QAAQ,OAAO,KAAK,CAAC,CAAC,OAAO,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI;EAC9D,QAAQ,OACN,OACA,IACA,WAEC,MAAM,QACJ,OAAO,KAAK,CAAC,CACb,IAAI,MAAM,CAAC,CACX,MAAM,GAAG,KAAK,KAAK,GAAG,EAAE,CAAC,CAAC,CAC1B,UAAU,CAAC,CACX,IAAI;EACT,KAAK,OACH,OACA,OAEE,MAAM,QACL,OAAO,CAAC,CACR,KAAK,KAAK,CAAC,CACX,MAAM,GAAG,KAAK,KAAK,GAAG,EAAE,CAAC,CAAC,CAC1B,MAAM,CAAC,CAAC,CACR,IAAI,KAAwC;EACjD,QAAQ,OAAO,OAAuB,OAA8B;GAClE,MAAM,QACH,OAAO,KAAK,CAAC,CACb,MAAM,GAAG,KAAK,KAAK,GAAG,EAAE,CAAC,CAAC,CAC1B,IAAI;EACT;EACA,MAAM,OACJ,OACA,OAAoB,CAAC,MACY;GAGjC,OAAO,MAFO,iBAAiB,QAAQ,OAAO,CAAC,CAAC,KAAK,KAAK,GAAG,IAC7B,CAAC,CAAC,IAAI;EAExC;EACA,OAAO,OAAO,OAAuB,UACnC,MAAM,QAAQ,OAAO,OAAO,KAAK;EACnC,KAAK,OAAU,UAA6B,MAAM,QAAQ,IAAI,KAAK;CACrE;AACF"}
+{"version":3,"file":"database.mjs","names":[],"sources":["../../src/adapters/database.ts"],"sourcesContent":["/**\n * Database adapter interface: query builders over explicitly typed tables.\n *\n * Canonical home of the database contract — {@link DatabaseAdapter},\n * {@link Tables}, {@link TxStore}, {@link ListOptions}, and\n * {@link DrizzleAdapterOptions}. Driver machinery lives in the database\n * packages (`@storyshelf/db-sqlite`, `@storyshelf/db-postgres`).\n */\nimport type { SQL } from \"drizzle-orm\";\nimport type { Table } from \"drizzle-orm\";\nimport type { Adapter, AdapterMetadata } from \"./metadata.ts\";\n\n/** Type-safe table map enforced on every DatabaseAdapter. */\nexport interface Tables {\n  projects: Table;\n  projectStatusConfigs: Table;\n  builds: Table;\n  captureAttempts: Table;\n  captureLogs: Table;\n  snapshots: Table;\n  baselines: Table;\n  comments: Table;\n  labelTypes: Table;\n  buildLabels: Table;\n  tokens: Table;\n  webhooks: Table;\n  notificationChannels: Table;\n  notificationSubscriptions: Table;\n  users: Table;\n  userInviteTokens: Table;\n  projectMembers: Table;\n  projectGroupMappings: Table;\n  contentRefs: Table;\n}\n\n/** Table keys every DatabaseAdapter must expose (contract + validation share this). */\nexport const REQUIRED_TABLE_KEYS = [\n  \"projects\",\n  \"builds\",\n  \"snapshots\",\n  \"baselines\",\n  \"comments\",\n  \"labelTypes\",\n  \"buildLabels\",\n  \"tokens\",\n  \"webhooks\",\n  \"users\",\n  \"projectMembers\",\n];\n\n/** Largest page any adapter serves in one list call. */\nexport const MAX_LIST_LIMIT = 1000;\n\n/** Clamp a list limit into [1, MAX_LIST_LIMIT]; undefined stays undefined. */\nexport function clampListLimit(limit?: number): number | undefined {\n  if (limit === undefined) {\n    return undefined;\n  }\n  if (!Number.isFinite(limit)) {\n    return MAX_LIST_LIMIT;\n  }\n  return Math.min(Math.max(Math.floor(limit), 1), MAX_LIST_LIMIT);\n}\n\n/** Options that narrow and page a list query. */\nexport interface ListOptions {\n  /** SQL WHERE condition. */\n  where?: SQL;\n  /** SQL ORDER BY condition. */\n  orderBy?: SQL;\n  /** Maximum number of rows to return. */\n  limit?: number;\n  /** Number of rows to skip. */\n  offset?: number;\n}\n\n/**\n * Transactional CRUD subset available inside {@link DatabaseAdapter.transact}.\n * Mirrors the adapter surface minus metadata, lifecycle, and raw `all`\n * (opaque to transactions on some drivers).\n */\nexport interface TxStore {\n  /** Insert a row and return the inserted record. */\n  insert<T extends Table>(table: T, values: T[\"$inferInsert\"]): Promise<T[\"$inferSelect\"]>;\n  /** Update a row by id and return the updated record. */\n  update<T extends Table>(\n    table: T,\n    id: string,\n    values: Partial<T[\"$inferInsert\"]>,\n  ): Promise<T[\"$inferSelect\"]>;\n  /** Fetch a single row by id, or null if not found. */\n  get<T extends Table>(table: T, id: string): Promise<T[\"$inferSelect\"] | null>;\n  /** Delete a row by id. */\n  remove(table: Table, id: string): Promise<void>;\n  /** List rows matching the given options. */\n  list<T extends Table>(table: T, opts?: ListOptions): Promise<T[\"$inferSelect\"][]>;\n  /** Count rows matching an optional where condition. */\n  count(table: Table, where?: SQL): Promise<number>;\n}\n\n/** Database abstraction over Drizzle tables, agnostic of dialect and driver. */\nexport interface DatabaseAdapter extends Adapter<{ readonly category: \"database\" }> {\n  /** Table handles for this adapter's dialect, enforced with type safety. */\n  readonly tables: Tables;\n  /** Insert a row and return the inserted record. */\n  insert<T extends Table>(table: T, values: T[\"$inferInsert\"]): Promise<T[\"$inferSelect\"]>;\n  /** Update a row by id and return the updated record. */\n  update<T extends Table>(\n    table: T,\n    id: string,\n    values: Partial<T[\"$inferInsert\"]>,\n  ): Promise<T[\"$inferSelect\"]>;\n  /** Fetch a single row by id, or null if not found. */\n  get<T extends Table>(table: T, id: string): Promise<T[\"$inferSelect\"] | null>;\n  /** Delete a row by id. */\n  remove(table: Table, id: string): Promise<void>;\n  /** List rows matching the given options. */\n  list<T extends Table>(table: T, opts?: ListOptions): Promise<T[\"$inferSelect\"][]>;\n  /** Count rows matching an optional where condition. */\n  count(table: Table, where?: SQL): Promise<number>;\n  /** Run an arbitrary SQL query and return typed rows. */\n  all<T>(query: SQL): Promise<T[]>;\n  /**\n   * Run `fn` inside a transaction when the driver supports one.\n   * Commits on resolve, rolls back on throw. Drivers without transaction\n   * support omit this; callers must use `?.` and accept sequential execution.\n   */\n  transact?<R>(fn: (tx: TxStore) => Promise<R>): Promise<R>;\n}\n\n/** Driver-supplied identity plus lifecycle hooks. */\nexport interface DrizzleAdapterOptions {\n  metadata: AdapterMetadata & { readonly category: \"database\" };\n  tables: Tables;\n  migrate: () => Promise<void> | void;\n  close: () => Promise<void> | void;\n  /** Cheap liveness probe (e.g. `SELECT 1`); omitted when the driver has none. */\n  ping?: () => Promise<void> | void;\n}\n"],"mappings":";;;;;AAoCA,MAAa,sBAAsB;CACjC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAGA,MAAa,iBAAiB;;AAG9B,SAAgB,eAAe,OAAoC;CACjE,IAAI,UAAU,KAAA,GACZ;CAEF,IAAI,CAAC,OAAO,SAAS,KAAK,GACxB,OAAO;CAET,OAAO,KAAK,IAAI,KAAK,IAAI,KAAK,MAAM,KAAK,GAAG,CAAC,GAAG,cAAc;AAChE"}

package/dist/adapter/email-sender.d.mts

@@ -0,0 +1,27 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Adapter } from "./metadata.mjs";
+//#region src/adapters/email-sender.d.ts
+/** A single email message (transport-agnostic). */
+interface EmailMessage {
+  to: string;
+  subject: string;
+  text: string;
+  html?: string;
+  from?: string;
+  replyTo?: string;
+}
+/**
+ * Minimal email transport: implemented once in `@storyshelf/notify-email`,
+ * consumed by notification fan-out and (optionally) the auth engine for
+ * invites and password resets. Best-effort delivery; throws on failure so
+ * callers can log and continue.
+ */
+interface EmailSender extends Adapter<{
+  readonly category: "notifier";
+}> {
+  send(message: EmailMessage): Promise<void>;
+}
+//#endregion
+export { EmailMessage, EmailSender };
+//# sourceMappingURL=email-sender.d.mts.map

package/dist/adapter/email-sender.mjs

@@ -0,0 +1,4 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+export {};