@aparte/core 0.2.0-alpha.0

package/dist/conversations/types.d.ts

@@ -0,0 +1,172 @@
+import type { AparteMessage } from '../types/index.js';
+import type { ExportedMessageRepository } from '../runtime/message-repository.js';
+/**
+ * Current schema version for `AparteConversation`. Bump when the persisted
+ * shape evolves so adapters / migrations can branch on it.
+ *
+ * v1: monolithic — `messages[]` inline on the conversation row, attachment
+ *     `url` was a session-scoped blob URL (lost on reload), artifacts inline
+ *     in segments only.
+ * v2: split — meta-only conversation row; messages, attachments (with real
+ *     `Blob`s), artifacts (gallery index), memory facts and settings each
+ *     get their own table. Sidebar can list without loading full payloads.
+ */
+export declare const APARTE_CONVERSATION_SCHEMA_VERSION: 2;
+/**
+ * A single conversation (thread) — framework-agnostic.
+ */
+export interface AparteConversation {
+    id: string;
+    /** Auto-generated from the first user message (≤50 chars). */
+    title: string;
+    createdAt: number;
+    updatedAt: number;
+    messages: AparteMessage[];
+    /**
+     * Full branching tree snapshot. When present, the conversation has branch
+     * history (edits, retries, sibling responses) and is loaded via `importTree`
+     * rather than the flat `messages` array.
+     *
+     * `messages` always mirrors the active path for backward-compatibility
+     * (sidebar previews, title generation, adapters that only read flat arrays).
+     */
+    tree?: ExportedMessageRepository;
+    /** When truthy the conversation is archived (hidden from the main list). */
+    archivedAt?: number;
+    /** When truthy the conversation is pinned at the top of the list. */
+    pinnedAt?: number;
+    /** Optional folder/tag id for organisation (V2+). */
+    folderId?: string;
+    /**
+     * Schema version of this record. Absent on legacy data (pre-versioning):
+     * adapters should treat `undefined` as version 0 and migrate on read.
+     */
+    schemaVersion?: number;
+}
+/**
+ * Lightweight conversation meta — what's needed to render the sidebar without
+ * loading the full message history. Returned by `loadMeta()` and stored as a
+ * dedicated row by split-storage adapters.
+ */
+export interface AparteConversationMeta {
+    id: string;
+    title: string;
+    createdAt: number;
+    updatedAt: number;
+    archivedAt?: number;
+    pinnedAt?: number;
+    folderId?: string;
+    /** Truncated last message body (≤200 chars) — for sidebar previews. */
+    lastMessagePreview?: string;
+    /** Cached message count for the sidebar badge / archive logic. */
+    messageCount?: number;
+    /** Sum of input+output tokens across messages, when available. */
+    totalTokens?: number;
+    /** Persisted schema version of the row. */
+    schemaVersion?: number;
+}
+/**
+ * Memory fact — durable user facts stored across all conversations.
+ * Surfaces in the memory panel and is consulted by the orchestrator to
+ * personalise replies.
+ */
+export interface AparteMemoryFact {
+    id: string;
+    /** Coarse category — drives the icon/colour in the panel. */
+    type: 'identity' | 'fact' | 'preference' | 'tech' | 'project' | 'style';
+    content: string;
+    /** Where the fact came from. `auto` = regex-detected, `manual` = user input. */
+    source?: 'manual' | 'auto' | 'onboarding';
+    addedAt: number;
+    /** Last time the fact was selected as relevant for a reply. */
+    lastUsedAt?: number;
+    /** Conversation that produced an auto-detected fact (for traceability). */
+    sourceConvId?: string;
+    /** Message inside `sourceConvId` that triggered the auto-detection. */
+    sourceMsgId?: string;
+}
+/**
+ * Artifact gallery row — denormalised index of every artifact segment ever
+ * produced, so the gallery can list/filter without scanning every message.
+ * The source of truth remains the artifact segment inside its message; this
+ * row is rebuilt by the storage adapter on every save.
+ */
+export interface AparteArtifactRow {
+    id: string;
+    convId: string;
+    msgId: string;
+    name: string;
+    mimeType: string;
+    artifactType: string;
+    /** Full body — duplicated from the source segment for fast gallery preview. */
+    content: string;
+    title?: string;
+    /** Snapshot of the message timestamp; used for "newest first" gallery sort. */
+    updatedAt: number;
+}
+/**
+ * Persisted attachment with the actual Blob — survives page reloads, unlike
+ * the session-scoped `URL.createObjectURL()` stored on `AparteMessage`.
+ * Adapters that split storage MUST keep the blob here and reconstruct the
+ * `url` on demand.
+ */
+export interface AparteAttachmentRow {
+    id: string;
+    convId: string;
+    msgId: string;
+    name: string;
+    mimeType: string;
+    size: number;
+    blob: Blob;
+}
+/**
+ * Implement this interface to provide persistence for conversations.
+ * All methods are async so any backend (IndexedDB, SQLite WASM, REST API…)
+ * can be used. The ConversationManager never touches storage directly.
+ *
+ * The first three methods (`loadAll`, `save`, `delete`) form the minimum
+ * viable adapter — everything else is optional and lets richer backends
+ * expose split-storage features (fast meta listing, memory, settings,
+ * artifact gallery, attachment blobs).
+ */
+export interface AparteStorageAdapter {
+    /** Return all stored conversations (full payload), ordered by updatedAt desc. */
+    loadAll(): Promise<AparteConversation[]>;
+    /** Upsert a conversation (create or update). */
+    save(conv: AparteConversation): Promise<void>;
+    /** Permanently delete a conversation by id (cascades related rows). */
+    delete(id: string): Promise<void>;
+    /** Archive a conversation (soft-delete). Optional. */
+    archive?(id: string): Promise<void>;
+    /** Restore an archived conversation. Optional. */
+    unarchive?(id: string): Promise<void>;
+    /**
+     * Fast sidebar listing. Returns lightweight meta only (no messages).
+     * Order is `updatedAt` desc. Adapters without split storage can omit
+     * this — callers should fall back to `loadAll()` mapping to meta.
+     */
+    loadMeta?(): Promise<AparteConversationMeta[]>;
+    /** Lazy-load a single conversation's full payload by id. */
+    loadFull?(id: string): Promise<AparteConversation | null>;
+    /** Pin/unpin (`pinnedAt`-aware sidebar sort). */
+    pin?(id: string): Promise<void>;
+    unpin?(id: string): Promise<void>;
+    /** Update only the conversation title (avoids rewriting messages). */
+    rename?(id: string, title: string): Promise<void>;
+    getMemory?(): Promise<AparteMemoryFact[]>;
+    addMemoryFact?(fact: AparteMemoryFact): Promise<void>;
+    updateMemoryFact?(id: string, patch: Partial<AparteMemoryFact>): Promise<void>;
+    deleteMemoryFact?(id: string): Promise<void>;
+    clearMemory?(): Promise<void>;
+    getSetting?<T = unknown>(key: string): Promise<T | undefined>;
+    setSetting?<T = unknown>(key: string, value: T): Promise<void>;
+    deleteSetting?(key: string): Promise<void>;
+    getAllSettings?(): Promise<Record<string, unknown>>;
+    /** List artifacts; optionally scoped to a single conversation. */
+    loadArtifacts?(filter?: {
+        convId?: string;
+    }): Promise<AparteArtifactRow[]>;
+    /** Persisted attachment blobs for a single message. */
+    loadAttachments?(msgId: string): Promise<AparteAttachmentRow[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/conversations/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/conversations/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAElF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kCAAkC,EAAG,CAAU,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,yBAAyB,CAAC;IACjC,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,6DAA6D;IAC7D,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,YAAY,CAAC;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,IAAI,CAAC;CACd;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACjC,iFAAiF;IACjF,OAAO,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACzC,gDAAgD;IAChD,IAAI,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,uEAAuE;IACvE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,sDAAsD;IACtD,OAAO,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,kDAAkD;IAClD,SAAS,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAItC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAAC;IAC/C,4DAA4D;IAC5D,QAAQ,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IAC1D,iDAAiD;IACjD,GAAG,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,KAAK,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,sEAAsE;IACtE,MAAM,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAIlD,SAAS,CAAC,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAC1C,aAAa,CAAC,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,gBAAgB,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E,gBAAgB,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,WAAW,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAI9B,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC9D,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,aAAa,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,cAAc,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAIpD,kEAAkE;IAClE,aAAa,CAAC,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAC3E,uDAAuD;IACvD,eAAe,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;CACnE"}