@polymorfa/store 0.1.0-dev.20260922094209

package/dist/store.d.ts

@@ -0,0 +1,168 @@
+import { type StoreReducer } from "./reducers.js";
+import { type Checkpoint, type DataStoreName, type PolymorfaEvent, type StoreChangeListener, type StoredAttachment, type StoredCall, type StoredContact, type StoredConversation, type StoredEvent, type StoredLabel, type StoredMessage, type StoredMessageStatus, type StoredPresence, type StoredSession, type StoredTemplate } from "./types.js";
+export interface RetentionRule {
+    /** Rows whose newest event is older than this are removed. */
+    readonly maxAgeMs?: number;
+    /** Oldest rows beyond this count are removed. */
+    readonly maxRows?: number;
+}
+export type RetentionOptions = Partial<Record<DataStoreName, RetentionRule | false>>;
+export declare const DEFAULT_RETENTION: Readonly<Record<DataStoreName, RetentionRule>>;
+/** Fields sealed by `encrypt` in each store. */
+export declare const SENSITIVE_FIELDS: Readonly<Record<DataStoreName, readonly string[]>>;
+export interface SealContext {
+    readonly store: DataStoreName;
+    readonly id: string;
+}
+export interface RedactRule {
+    /** Exact event type, a `prefix.*` pattern, or `*`. */
+    readonly events: string;
+    /** Dotted payload paths to remove, for example `text` or `conversation.phoneNumber`. */
+    readonly paths: readonly string[];
+}
+export interface BroadcastChannelLike {
+    postMessage(message: unknown): void;
+    close(): void;
+    onmessage: ((event: MessageEvent) => void) | null;
+}
+export interface PolymorfaStoreOptions {
+    /**
+     * Database name. Include the signed-in user and session so data never
+     * crosses accounts, for example `support:user_123`.
+     */
+    readonly name: string;
+    /**
+     * Application data version. When it changes, stored data is wiped on
+     * open, because it is a cache of events the backend still holds.
+     */
+    readonly version?: number;
+    /** Only events for this session are stored. */
+    readonly session?: string;
+    readonly retention?: RetentionOptions;
+    /** How often to sweep, in milliseconds. `0` sweeps only on open. */
+    readonly sweepIntervalMs?: number;
+    /** Defaults to `globalThis.indexedDB`; `null` forces memory mode. */
+    readonly indexedDB?: IDBFactory | null;
+    /** Defaults to `globalThis.BroadcastChannel`; `null` disables tab sync. */
+    readonly broadcastChannel?: ((name: string) => BroadcastChannelLike) | null;
+    /** Seals `SENSITIVE_FIELDS` before they are written. Needs `decrypt`. */
+    readonly encrypt?: (fields: Record<string, unknown>, context: SealContext) => unknown;
+    readonly decrypt?: (sealed: unknown, context: SealContext) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    /** Payload fields removed before an event is reduced or logged. */
+    readonly redact?: readonly RedactRule[];
+    /** Maximum events per write transaction. */
+    readonly batchSize?: number;
+    readonly now?: () => number;
+    /** Reports a failed background sweep. */
+    readonly onError?: (error: unknown) => void;
+}
+export interface IngestResult {
+    readonly accepted: number;
+    readonly duplicates: number;
+    /** Events dropped for a different session or a malformed envelope. */
+    readonly ignored: number;
+}
+export interface MessageListQuery {
+    readonly conversationId: string;
+    /** Only messages created before this epoch-millisecond time. */
+    readonly before?: number;
+    /**
+     * With `before`, also returns messages created exactly at `before` whose
+     * ID sorts before this one. Pass the oldest row of the previous page to
+     * page through messages that share a timestamp.
+     */
+    readonly beforeId?: string;
+    readonly limit?: number;
+    /** Include deleted and revoked messages. */
+    readonly includeDeleted?: boolean;
+}
+export interface MessageInput {
+    readonly id: string;
+    readonly conversationId: string;
+    readonly createdAt: number;
+    readonly fromMe: boolean;
+    readonly text?: string;
+    readonly clientId?: string;
+    /** ID of the message this one replies to. */
+    readonly replyTo?: string;
+    readonly status?: StoredMessageStatus;
+    readonly attachments?: readonly StoredAttachment[];
+}
+export interface ListOptions {
+    readonly limit?: number;
+}
+export interface EventListQuery {
+    readonly types?: readonly string[];
+    /** Epoch milliseconds, inclusive. */
+    readonly since?: number;
+    readonly limit?: number;
+}
+export interface StoreUsage {
+    readonly usage?: number;
+    readonly quota?: number;
+}
+export type StoreMode = "indexeddb" | "memory";
+export interface PolymorfaStore {
+    readonly name: string;
+    /** `memory` when IndexedDB was unavailable; data then lasts for the page. */
+    readonly mode: StoreMode;
+    /** Why the store fell back to memory. */
+    readonly fallbackReason?: string;
+    ingest(events: PolymorfaEvent | readonly PolymorfaEvent[]): Promise<IngestResult>;
+    /** Adds a reducer for `type`. It runs after any built-in reducer. */
+    registerReducer(type: string, reducer: StoreReducer): () => void;
+    readonly conversations: {
+        get(id: string): Promise<StoredConversation | undefined>;
+        /** Most recent activity first. */
+        list(query?: ListOptions & {
+            readonly unreadOnly?: boolean;
+        }): Promise<StoredConversation[]>;
+    };
+    readonly messages: {
+        get(id: string): Promise<StoredMessage | undefined>;
+        /** Newest first. */
+        list(query: MessageListQuery): Promise<StoredMessage[]>;
+        /** Writes messages from a backend history read; newer state wins. */
+        upsert(messages: readonly MessageInput[], options?: {
+            readonly session?: string;
+        }): Promise<void>;
+    };
+    readonly contacts: StoreReader<StoredContact>;
+    readonly presence: StoreReader<StoredPresence>;
+    readonly calls: StoreReader<StoredCall>;
+    readonly labels: StoreReader<StoredLabel>;
+    readonly sessions: StoreReader<StoredSession>;
+    readonly templates: StoreReader<StoredTemplate>;
+    readonly events: {
+        get(id: string): Promise<StoredEvent | undefined>;
+        /** Oldest first. */
+        list(query?: EventListQuery): Promise<StoredEvent[]>;
+    };
+    readonly custom: {
+        get(id: string): Promise<StoredEvent | undefined>;
+        list(query?: EventListQuery): Promise<StoredEvent[]>;
+    };
+    readonly checkpoints: {
+        get(id: string): Promise<Checkpoint | undefined>;
+        set(id: string, cursor: string): Promise<void>;
+    };
+    /** Listens for committed changes in this tab and other tabs. */
+    subscribe(store: DataStoreName | "*", listener: StoreChangeListener): () => void;
+    /** Applies retention now. */
+    sweep(): Promise<void>;
+    /** Removes all stored data, for example on sign-out. */
+    clear(): Promise<void>;
+    close(): void;
+    estimateUsage(): Promise<StoreUsage | undefined>;
+    /** Asks the browser not to evict this origin's storage. */
+    persist(): Promise<boolean>;
+}
+export interface StoreReader<T> {
+    get(id: string): Promise<T | undefined>;
+    /** Most recently updated first. */
+    list(options?: ListOptions): Promise<T[]>;
+}
+/** Removes token-like fields and values anywhere in a payload. */
+export declare function stripSecrets(value: unknown, depth?: number): unknown;
+export declare function createPolymorfaStore(options: PolymorfaStoreOptions): Promise<PolymorfaStore>;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}