@mordn/chat-widget 0.7.1 → 0.8.0

package/dist/chat-store-DERCPwhl.d.ts

@@ -0,0 +1,278 @@
+import { UIMessage } from 'ai';
+
+/**
+ * Server-core domain types.
+ *
+ * This is the shared vocabulary for the server side of the widget — the
+ * persistence interfaces (`ChatStore`, `StorageAdapter`), the request
+ * router, and the lifecycle hooks all speak in these types.
+ *
+ * Design notes
+ * ------------
+ * 1. These types are deliberately decoupled from any specific database or
+ *    ORM. `ChatStore` is an interface; the Drizzle/Postgres implementation
+ *    that ships as the default is just *one* implementation of it. A hosted
+ *    backend, a Prisma store, or an in-memory test double are equally valid.
+ *
+ * 2. Messages are stored as AI SDK `UIMessage`s — specifically their `parts`
+ *    array — not as a flattened `content` string. The `parts` array is the
+ *    canonical representation the AI SDK round-trips (text, reasoning, tool
+ *    calls, sources, files). Storing anything less loses information on
+ *    rehydration. We keep a denormalised `text` alongside it purely for
+ *    cheap previews / titles / search — never as the source of truth.
+ *
+ * 3. Identity (`userId`) never appears as a *parameter* on read/write
+ *    methods. A `ChatStore` is constructed already bound to one verified
+ *    user (see `ChatStoreFactory`). This makes cross-user access
+ *    unrepresentable at the type level — you cannot ask a store for another
+ *    user's data because no method accepts a foreign id. That is the
+ *    security property, encoded in the shape of the API rather than left to
+ *    each caller's discipline.
+ */
+
+/**
+ * A single attachment as persisted on a message part.
+ *
+ * The `url` is a *freshly signed, short-lived* URL when this object is
+ * handed to the client — never a permanent public link. `storagePath` is
+ * the durable pointer the `StorageAdapter` uses to re-sign on demand when an
+ * old conversation is reloaded. Only `storagePath` is guaranteed stable
+ * across reads; treat `url` as ephemeral.
+ */
+interface StoredAttachment {
+    /** Durable, opaque pointer into the storage backend. Stable across reads. */
+    storagePath: string;
+    /** Freshly-signed, expiring URL for the client to fetch. Ephemeral. */
+    url: string;
+    /** Original filename as uploaded (for display + download). */
+    filename: string;
+    /** MIME type (e.g. `image/png`, `application/pdf`). */
+    mediaType: string;
+    /** Size in bytes. */
+    size: number;
+}
+/**
+ * A conversation row, as the store returns it. Summary-level — does not
+ * include messages. Use `listConversations` for the sidebar/history list and
+ * `getConversation` + `listMessages` to open one.
+ */
+interface StoredConversation {
+    id: string;
+    /**
+     * Human-readable title. Defaults to "New Chat" until the first user
+     * message lands, at which point the router auto-titles from it. Consumers
+     * can override via `renameConversation`.
+     */
+    title: string;
+    /** Free-form metadata bag the host app may stamp (never read by the core). */
+    metadata: Record<string, unknown> | null;
+    createdAt: Date;
+    updatedAt: Date;
+    /**
+     * Number of messages in the conversation. Populated by `listConversations`
+     * for the history list; may be omitted (`undefined`) by single-row reads
+     * where the count isn't needed.
+     */
+    messageCount?: number;
+}
+/**
+ * A message row, as the store returns it.
+ *
+ * `parts` is the canonical AI SDK representation and the source of truth for
+ * rendering. `text` is a denormalised convenience for previews/search and
+ * may be empty for messages whose content is entirely non-text (e.g. a
+ * tool-only assistant turn).
+ */
+interface StoredMessage {
+    id: string;
+    role: 'user' | 'assistant' | 'system';
+    /** Canonical AI SDK parts. Source of truth for rendering + model replay. */
+    parts: UIMessage['parts'];
+    /** Denormalised plain text for previews/titles/search. Not authoritative. */
+    text: string;
+    /** Which model produced this message, when known (assistant turns). */
+    model?: string;
+    createdAt: Date;
+}
+/**
+ * Pagination request for message history. The store returns the most-recent
+ * `limit` messages so a freshly-opened conversation shows the latest turns;
+ * `before` lets the client page backwards into older history.
+ */
+interface ListMessagesOptions {
+    /** Max messages to return. The store clamps this to a sane ceiling. */
+    limit?: number;
+    /**
+     * Return only messages created strictly before this instant. Used for
+     * "load older messages" infinite-scroll. Omit for the most-recent page.
+     */
+    before?: Date;
+}
+/**
+ * What `saveTurn` persists at the end of a streamed response: the final,
+ * complete set of UI messages for the turn (user message + assistant
+ * message, including any tool/reasoning/source parts the SDK emitted).
+ *
+ * The store is responsible for idempotency — re-saving messages whose ids
+ * already exist must be a no-op, never a duplicate. (Replays, retries, and
+ * the AI SDK's own resumability all deliver already-seen ids.)
+ */
+interface SaveTurnInput {
+    conversationId: string;
+    messages: UIMessage[];
+    /** Model that produced the assistant message(s) in this turn. */
+    model?: string;
+}
+
+/**
+ * ChatStore — the persistence contract for chat conversations and messages.
+ *
+ * This is one of the two pluggable backends of the widget (the other is
+ * `StorageAdapter` for attachments). The package ships a Drizzle/Postgres
+ * implementation as the default; a hosted backend or a BYO store (Prisma,
+ * raw SQL, DynamoDB, a test double) is simply another implementation of this
+ * same interface.
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ * The security model is in the shape of this API, not in its callers.
+ * ──────────────────────────────────────────────────────────────────────────
+ *
+ * A `ChatStore` is *bound to one verified user* at construction time (see
+ * `ChatStoreFactory`). None of its methods accept a `userId`. This is
+ * deliberate and it is the core defence against the IDOR class of bug:
+ *
+ *   - You cannot ask the store for "conversation X belonging to user Y",
+ *     because there is no parameter through which a foreign `userId` could
+ *     enter. The only user the store will ever read or write is the one it
+ *     was constructed with.
+ *
+ *   - Every method is therefore *implicitly scoped*. `listConversations()`
+ *     returns only the bound user's conversations. `getConversation(id)`
+ *     returns `null` — not someone else's row — when `id` exists but belongs
+ *     to a different user. `saveTurn(...)` refuses (throws
+ *     `ConversationOwnershipError`) if `conversationId` exists under another
+ *     user.
+ *
+ * The route layer's job shrinks to: authenticate the request, derive the
+ * real `userId` from the *server* session, construct a store bound to it,
+ * and call methods. There is no per-route ownership check to forget, because
+ * the store cannot be made to cross users.
+ *
+ * Implementations MUST uphold the contract documented on each method. The
+ * Drizzle default does; if you write your own, these invariants are the
+ * security boundary — treat them as load-bearing, not advisory.
+ */
+
+/**
+ * Thrown by mutating methods when the target conversation exists but is owned
+ * by a different user than the one this store is bound to. Callers should map
+ * this to an HTTP 403. (Read methods don't throw — they return `null`/`[]` —
+ * so that probing for existence can't distinguish "not found" from
+ * "forbidden", which would itself leak information.)
+ */
+declare class ConversationOwnershipError extends Error {
+    readonly conversationId: string;
+    constructor(conversationId: string);
+}
+interface ChatStore {
+    /**
+     * The user this store instance is bound to. Read-only; set at construction.
+     * Exposed so the router can stamp it onto storage paths, logs, etc. — never
+     * as something a caller can change.
+     */
+    readonly userId: string;
+    /**
+     * List the bound user's conversations, most-recently-updated first.
+     * Returns `messageCount` on each row for the history list. Returns `[]`
+     * (never throws) when the user has none.
+     */
+    listConversations(): Promise<StoredConversation[]>;
+    /**
+     * Fetch a single conversation by id, scoped to the bound user.
+     *
+     * Returns `null` when the conversation does not exist OR exists but belongs
+     * to another user — the two cases are intentionally indistinguishable to
+     * the caller (and thus to an attacker). Never returns another user's row.
+     */
+    getConversation(id: string): Promise<StoredConversation | null>;
+    /**
+     * Ensure a conversation row exists for `id`, owned by the bound user.
+     *
+     * - If no row exists for `id`: creates it, owned by the bound user, and
+     *   returns it.
+     * - If a row exists and is owned by the bound user: returns it unchanged
+     *   (idempotent — safe to call at the top of every request).
+     * - If a row exists but is owned by a *different* user: throws
+     *   `ConversationOwnershipError` and writes nothing.
+     *
+     * This is the single chokepoint that makes "write into someone else's
+     * conversation" impossible: the router calls it before persisting any
+     * message, so a forged conversation id is rejected before any data lands.
+     */
+    ensureConversation(id: string, init?: {
+        title?: string;
+    }): Promise<StoredConversation>;
+    /**
+     * Rename a conversation owned by the bound user. No-op (does not throw) if
+     * the conversation doesn't exist or isn't owned by the user — renaming is
+     * not security-sensitive and silent failure is friendlier here.
+     */
+    renameConversation(id: string, title: string): Promise<void>;
+    /**
+     * Delete a conversation (and cascade its messages + attachment rows) owned
+     * by the bound user. No-op if it doesn't exist or isn't owned by the user.
+     * Returns `true` if a row was actually deleted, `false` otherwise — lets
+     * the route return 404 vs 200 honestly without a separate existence check.
+     *
+     * Note: this deletes message *rows*. Purging the underlying attachment
+     * blobs from storage is the router's job (it has the `StorageAdapter`),
+     * driven off the attachments this method returns having referenced.
+     */
+    deleteConversation(id: string): Promise<boolean>;
+    /**
+     * Load messages for a conversation, scoped to the bound user, newest-first
+     * internally but returned in chronological order (oldest → newest) ready to
+     * render. Returns `[]` if the conversation doesn't exist or isn't owned by
+     * the user — same non-distinguishing contract as `getConversation`.
+     *
+     * Honours `ListMessagesOptions` for pagination. Implementations MUST clamp
+     * `limit` to a ceiling (default ceiling: 100) so a hostile client can't
+     * request an unbounded page.
+     */
+    listMessages(conversationId: string, opts?: ListMessagesOptions): Promise<StoredMessage[]>;
+    /**
+     * Persist the final messages of a completed turn.
+     *
+     * Contract:
+     *  - MUST verify the conversation is owned by the bound user first; throws
+     *    `ConversationOwnershipError` otherwise (defence in depth — the router
+     *    already called `ensureConversation`, but `saveTurn` must not trust
+     *    that).
+     *  - MUST be idempotent on message id: a message whose id already exists is
+     *    skipped, not duplicated. (The AI SDK delivers stable ids; replays and
+     *    retries re-deliver them.)
+     *  - MUST persist each message's full `parts` array as the source of truth,
+     *    plus a denormalised text projection for previews.
+     *  - MUST bump the conversation's `updatedAt`.
+     *
+     * Errors other than ownership (e.g. a transient DB failure) propagate so
+     * the router can log them loudly — a silently-dropped assistant turn is
+     * exactly the bug we're trying to design out.
+     */
+    saveTurn(input: SaveTurnInput): Promise<void>;
+}
+/**
+ * Constructs a `ChatStore` bound to a specific, already-verified user.
+ *
+ * The router calls this *after* it has authenticated the request and derived
+ * `userId` from the server session — never from anything client-supplied.
+ * Passing a client-controlled value here would reintroduce the very IDOR the
+ * bound-store design exists to prevent, so implementations should treat
+ * `userId` as a trusted server secret, not as request input.
+ *
+ * Construction is intended to be cheap (the underlying DB pool/connection is
+ * shared across instances) so a fresh store per request is the norm.
+ */
+type ChatStoreFactory = (userId: string) => ChatStore;
+
+export { type ChatStoreFactory as C, type ListMessagesOptions as L, type StoredAttachment as S, type StoredConversation as a, type StoredMessage as b, type SaveTurnInput as c, type ChatStore as d, ConversationOwnershipError as e };