@dvina/sdk 3.3.124

package/dist/sync-engine-DVKQO-1-.d.cts

@@ -0,0 +1,423 @@
+import { DocumentNode } from 'graphql';
+import * as dexie from 'dexie';
+import { Dexie, Table } from 'dexie';
+import { D as DvinaError } from './error-CsVoUTY8.cjs';
+import { D as DvinaQueryRef } from './types-2RotD0Ab.cjs';
+
+/** Cached result metadata for a specific query + variables combination */
+interface QueryResultEntry {
+    /** Hash of document name + serialized variables */
+    key: string;
+    /** The entity table these IDs refer to (e.g. 'chats', 'reports') */
+    entityType: string;
+    /** Ordered list of entity IDs returned by this query */
+    entityIds: string[];
+    /** Relay PageInfo for cursor-based pagination */
+    pageInfo?: {
+        hasNextPage: boolean;
+        hasPreviousPage: boolean;
+        startCursor?: string | null;
+        endCursor?: string | null;
+    };
+    /** Total count if the server returned it */
+    totalCount?: number;
+    /** Timestamp of the last server fetch */
+    fetchedAt: number;
+}
+interface PendingMutationEntry {
+    /** Auto-incremented ID */
+    id?: number;
+    /** Mutation operation name */
+    operationName: string;
+    /** Serialized DocumentNode name (to re-resolve at replay time) */
+    documentName: string;
+    /** Serialized variables */
+    variables: Record<string, unknown>;
+    /** Timestamp when the mutation was queued */
+    queuedAt: number;
+    /** Number of retry attempts so far */
+    retries: number;
+}
+interface SyncMetadataEntry {
+    /** Metadata key (e.g. 'lastSyncTimestamp', 'schemaVersion') */
+    key: string;
+    /** Arbitrary value */
+    value: unknown;
+}
+/**
+ * Base entity record stored in Dexie.
+ *
+ * Most entities use `id` as primary key, but some use alternative keys:
+ * - `DataSourceTypeDetails` uses `type` (enum string)
+ * - `ReportMember` uses compound key `[reportId, insightId]`
+ *
+ * Use `getPrimaryKeyField()` / `resolvePrimaryKey()` for PK-safe access.
+ */
+interface EntityRecord {
+    __typename?: string;
+    [key: string]: unknown;
+}
+/**
+ * The Dvina IndexedDB database.
+ *
+ * One database per workspace+user, lazily created on first access.
+ * Entity tables are auto-generated from the GraphQL schema (via `_generated_store.ts`).
+ * Meta tables (`_queryResults`, `_pendingMutations`, `_sync`) support
+ * the SyncEngine's caching and offline mutation queue.
+ *
+ * Uses Dexie v4 — we create an instance with `new Dexie(name)` and define
+ * the schema via `.version().stores()`.
+ */
+declare class DvinaDatabase {
+    readonly db: Dexie;
+    private readonly _dbName;
+    /**
+     * Resolves when the schema-hash check is complete.
+     * Consumers that depend on a consistent schema should await this before
+     * performing reads/writes. The factory function `getOrCreateDatabase`
+     * handles this automatically.
+     */
+    readonly ready: Promise<void>;
+    constructor(workspaceId: string, userId: string);
+    /**
+     * Verify that the stored schema hash matches the current codegen hash.
+     * If the hashes differ the database is deleted and recreated so that
+     * stale indexes / missing tables never cause silent data corruption.
+     *
+     * On a fresh database (no stored hash) the current hash is persisted.
+     */
+    private _ensureSchemaCompatibility;
+    get _queryResults(): Table<QueryResultEntry, string, QueryResultEntry>;
+    get _pendingMutations(): Table<PendingMutationEntry, number, PendingMutationEntry>;
+    get _sync(): Table<SyncMetadataEntry, string, SyncMetadataEntry>;
+    /** Get a table by name (generic accessor for all entity tables) */
+    table<T = unknown, TKey = unknown>(tableName: string): Table<T, TKey>;
+    /** Access all tables */
+    get allTables(): Table[];
+    /** Run a read-write transaction across specified tables */
+    transaction<U>(mode: 'rw' | 'r', tables: Table[], scope: () => PromiseLike<U> | U): dexie.PromiseExtended<U>;
+    /** Close the database connection and evict from the module-level cache. */
+    close(): void;
+    /** Get the last processed sync event ID, or '0' if none. */
+    getLastSyncId(): Promise<string>;
+    /** Persist the last processed sync event ID. */
+    setLastSyncId(syncId: string): Promise<void>;
+}
+/**
+ * Get or create a DvinaDatabase instance.
+ *
+ * Databases are cached by name to avoid opening multiple connections
+ * to the same IndexedDB database. The returned promise resolves once
+ * the schema-hash compatibility check is complete; after that the
+ * database is guaranteed to match the current codegen schema.
+ *
+ * @param token - A valid JWT from which workspaceId and userId are extracted
+ * @returns The DvinaDatabase instance after schema compatibility is ensured
+ */
+declare function getOrCreateDatabase(token: string): Promise<DvinaDatabase>;
+/**
+ * Close and remove a cached database instance.
+ * Useful for logout / workspace switching.
+ */
+declare function closeDatabase(token: string): void;
+/**
+ * Delete the IndexedDB database entirely.
+ * Use with caution — this wipes all cached data for the workspace+user.
+ */
+declare function deleteDatabase(token: string): Promise<void>;
+
+interface HttpTransportOptions {
+    /** Full GraphQL HTTP endpoint URL (e.g. 'https://api.dvina.ai/graphql') */
+    url: string;
+    /**
+     * Returns an auth token.
+     * When called with `{ forceRefresh: true }`, the callback must bypass any
+     * cache and obtain a brand-new token (e.g. via Auth0's silent refresh).
+     */
+    getToken: (options?: {
+        forceRefresh?: boolean;
+    }) => Promise<string>;
+    /** Returns the preferred language, or undefined */
+    getLanguage: () => string | undefined;
+    /**
+     * Optional global error callback. Called with the final error right before
+     * it is thrown to the caller. Useful for centralized error reporting / UI alerts.
+     *
+     * **Not** called for transient errors that are retried internally (e.g.
+     * intermediate 401s that trigger a token refresh, or network retries).
+     * Only invoked for the terminal error that will actually propagate.
+     */
+    onError?: (error: DvinaError) => void;
+}
+interface HttpTransport {
+    /** Execute a GraphQL query or mutation */
+    request: <T>(document: DocumentNode, variables?: Record<string, unknown>) => Promise<T>;
+}
+/**
+ * Create a fetch-based GraphQL HTTP transport with:
+ * - Auth header injection (Bearer token)
+ * - Language header injection
+ * - Retry on network errors (status 0, up to 4 attempts with linear backoff)
+ * - Auth error handling (401/UNAUTHENTICATED → token refresh → retry, with request queuing)
+ */
+declare function createHttpTransport(options: HttpTransportOptions): HttpTransport;
+
+/**
+ * SSE transport for delta sync.
+ *
+ * Connects to the backend SSE endpoint and emits sync events.
+ * Uses EventSource in browser environments and a fetch-based
+ * fallback for environments without native EventSource.
+ *
+ * Features:
+ * - Fetch-based SSE with Authorization header (no query parameter token exposure)
+ * - Automatic reconnection with exponential backoff
+ * - Auth failure detection with short-delay retry for token refresh
+ * - Event listener pattern for processing sync events
+ */
+interface SseSyncEvent {
+    id: string;
+    type: 'upsert' | 'delete';
+    modelName: string;
+    entityId: string;
+    payload: Record<string, unknown> | null;
+}
+interface SseQueryEvent {
+    type: 'add' | 'remove';
+    subscriptionId: string;
+    entityId: string;
+    entityType: string;
+}
+interface SubscriptionDescriptor {
+    id: string;
+    entityType: string;
+    operationName: string;
+    modelName: string;
+    filter?: Record<string, unknown>;
+}
+interface SseTransportOptions {
+    /** Full SSE endpoint URL (e.g. 'https://api.dvina.ai/api/sync/stream') */
+    url: string;
+    /**
+     * Returns an auth token.
+     * When called with `{ forceRefresh: true }`, the callback must bypass any
+     * cache and obtain a brand-new token (e.g. via Auth0's silent refresh).
+     */
+    getToken: (options?: {
+        forceRefresh?: boolean;
+    }) => Promise<string>;
+    /** Called when a sync event is received */
+    onEvent: (event: SseSyncEvent) => void;
+    /** Called when a query event is received (server-driven subscription update) */
+    onQueryEvent?: (event: SseQueryEvent) => void;
+    /** Called when the initial cursor is received (fresh connection) */
+    onCursor?: (syncId: string) => void;
+    /** Called when the server signals that the sync gap is unrecoverable and a full resync is needed */
+    onFullResync?: () => void;
+    /** Called on connection state changes */
+    onStateChange?: (state: 'connecting' | 'connected' | 'disconnected') => void;
+}
+interface SseTransport {
+    /** Start the SSE connection */
+    connect(lastSyncId?: string): Promise<void>;
+    /** Close the SSE connection */
+    disconnect(): void;
+    /** Whether the transport is currently connected */
+    readonly connected: boolean;
+    /** Register a query subscription (fire-and-forget POST) */
+    subscribe(descriptor: SubscriptionDescriptor): void;
+    /** Unregister a query subscription (fire-and-forget POST) */
+    unsubscribe(subscriptionId: string): void;
+}
+/**
+ * Create an SSE transport for delta sync.
+ *
+ * Uses a fetch-based SSE implementation instead of the native EventSource API
+ * so that we can send the auth token via the `Authorization` header. This
+ * avoids exposing tokens in URL query parameters (which end up in server
+ * logs, browser history, and referrer headers).
+ */
+declare function createSseTransport(options: SseTransportOptions): SseTransport;
+
+/**
+ * Convention-based cache rules generated by codegen.
+ * These tell the SyncEngine how to update the local store after a mutation.
+ */
+interface CacheRuleCreate {
+    type: 'create';
+    /** Dexie table name for the created entity (e.g. 'chats') */
+    entityType: string;
+    /** Query result keys to prepend the new entity to (e.g. ['chats']) */
+    connectionFields: string[];
+}
+interface CacheRuleUpdate {
+    type: 'update';
+    /** Dexie table name for the updated entity */
+    entityType: string;
+}
+interface CacheRuleDelete {
+    type: 'delete';
+    /** Dexie table name for the deleted entity */
+    entityType: string;
+    /** Query result keys to remove the entity from */
+    connectionFields: string[];
+    /** Related entity types to cascade-delete (e.g. Resource for a DataSource delete) */
+    cascadeDelete?: string[];
+}
+type CacheRule = CacheRuleCreate | CacheRuleUpdate | CacheRuleDelete;
+interface SyncEngineOptions {
+    /** The Dexie database instance */
+    db: DvinaDatabase;
+    /** HTTP transport for queries and mutations */
+    httpTransport: HttpTransport;
+    /** Optional SSE transport for delta sync (browser-only) */
+    sseTransport?: SseTransport;
+}
+/**
+ * The SyncEngine is the central orchestrator for all data operations in the SDK.
+ *
+ * It sits between the generated SDK classes and the transport/store layers:
+ *
+ * ```
+ * SDK classes → SyncEngine → HTTP Transport (server)
+ *                          → Dexie (local store)
+ *                          → liveQuery (reactivity)
+ * ```
+ *
+ * Responsibilities:
+ * 1. **query()** — Fetch from server → normalize → write to Dexie → return data
+ * 2. **watch()** — Create a Dexie liveQuery, fetch from server on cold start,
+ *    auto-update on any store change
+ * 3. **mutate()** — Optimistic write → server call → commit/rollback
+ * 4. **Cache rules** — Convention-based auto cache updates for CRUD mutations
+ */
+declare class SyncEngine {
+    private _db;
+    private _sse?;
+    private _cache;
+    private _queryExecutor;
+    private _mutationExecutor;
+    /**
+     * Maps subscriptionId → queryKey for routing server-driven query events
+     * to the correct cache entry. Populated by watch() when a subscription
+     * descriptor is provided, cleaned up on dispose().
+     */
+    private _subscriptionToQueryKey;
+    /** Active subscription metadata used for targeted revalidation fallback. */
+    private _subscriptionToQuery;
+    /** Last per-query revalidation timestamp to avoid refetch storms. */
+    private _lastRevalidatedAt;
+    /**
+     * Last mutation/sync touch timestamp by entity type.
+     * Used to detect stale cached query results on watch re-entry.
+     */
+    private _entityTypeTouchedAt;
+    constructor(options: SyncEngineOptions);
+    /**
+     * Start the SSE delta sync connection.
+     * Reads the last sync cursor from Dexie and connects to the SSE endpoint.
+     * Incoming events are automatically written to Dexie, triggering liveQuery updates.
+     */
+    startSync(): Promise<void>;
+    /**
+     * Stop the SSE delta sync connection.
+     */
+    stopSync(): void;
+    /**
+     * Handle a full-resync signal from the server.
+     *
+     * Clears all cached entities and query results, resets the sync cursor,
+     * then restarts the SSE connection so the client gets a fresh cursor.
+     * Active `liveQuery` watchers will re-emit once data is refetched.
+     */
+    handleFullResync(): Promise<void>;
+    /**
+     * Process an incoming SSE sync event.
+     * Writes the entity to Dexie and updates the sync cursor atomically.
+     */
+    processSyncEvent(event: SseSyncEvent): Promise<void>;
+    /**
+     * Execute a query: fetch from server → normalize → write to Dexie → return raw data.
+     *
+     * For connection queries, also writes the ordered entity IDs to `_queryResults`
+     * so that `watch()` can reconstruct the same ordered list from the store.
+     */
+    query<T>(document: DocumentNode, variables?: Record<string, unknown>, operationName?: string): Promise<T>;
+    /**
+     * Create a reactive query that auto-updates when the underlying store changes.
+     *
+     * **Cold start**: The first emission waits for the server fetch to complete.
+     * After that, Dexie's `liveQuery` handles reactivity — any write to a table
+     * accessed by the query factory triggers a re-emission.
+     *
+     * When a `subscriptionDescriptor` is provided, the watch registers a
+     * server-driven subscription via the SSE transport. The server evaluates
+     * Prisma filters on create/update/upsert events and sends targeted
+     * `query-add` / `query-remove`
+     * events back, which this engine routes to the correct cache entry.
+     *
+     * @param document - The GraphQL query document
+     * @param variables - Query variables
+     * @param operationName - The operation name (used as the query result cache key)
+     * @param buildResult - A function that reads from Dexie and returns the raw response shape.
+     * @param subscriptionDescriptor - Optional server-driven subscription metadata for filtered queries.
+     */
+    watch<T>(document: DocumentNode, variables: Record<string, unknown> | undefined, operationName: string, buildResult: (db: DvinaDatabase) => Promise<T> | T, subscriptionDescriptor?: SubscriptionDescriptor): DvinaQueryRef<T>;
+    /**
+     * Execute a mutation with optional optimistic update and automatic cache rule.
+     *
+     * Flow:
+     * 1. **Optimistic write** (if cache rule is create/update/delete) — immediately
+     *    update Dexie so all watchers see the change
+     * 2. **Server call** — send the mutation to the server
+     * 3. **Commit** — normalize server response and write to Dexie (replacing optimistic data)
+     * 4. **Rollback** (on error) — restore the original state in Dexie
+     */
+    mutate<T>(document: DocumentNode, variables?: Record<string, unknown>, cacheRule?: CacheRule, optimisticData?: Record<string, unknown>): Promise<T>;
+    /** Direct access to the Dexie database (for advanced use cases) */
+    get db(): DvinaDatabase;
+    /**
+     * Read a single entity from the store by table name and primary key.
+     *
+     * @param tableName - Dexie table name (e.g. 'chats', 'reportMembers')
+     * @param pk - Primary key value. String for simple keys, string[] for compound keys.
+     */
+    getEntity(tableName: string, pk: string | string[]): Promise<EntityRecord | undefined>;
+    /**
+     * Read query result metadata from the store.
+     */
+    getQueryResult(operationName: string, variables?: Record<string, unknown>): Promise<QueryResultEntry | undefined>;
+    /**
+     * Invalidate (delete) a query result, forcing the next watch() to refetch.
+     */
+    invalidateQuery(operationName: string, variables?: Record<string, unknown>): Promise<void>;
+    /**
+     * Clear all data from the store (but keep the database structure).
+     * Useful for logout scenarios.
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Process a server-driven query event (query-add / query-remove).
+     *
+     * The server evaluates Prisma filters on create/update/upsert events and sends targeted
+     * events to subscriptions that match. This method routes the event to the
+     * correct query result cache entry using the subscriptionId → queryKey map.
+     */
+    processQueryEvent(event: SseQueryEvent): Promise<void>;
+    /**
+     * Handle an upsert sync event: normalize the payload and write to Dexie.
+     *
+     * The updated entity type is marked as touched so cached query results can
+     * be revalidated lazily when those queries become active again.
+     */
+    private _processSyncUpsert;
+    private _markEntityTypeTouched;
+    private _revalidateSubscriptionIfStale;
+    private _revalidateSubscriptionsForEntityType;
+    /**
+     * Handle a delete sync event: remove entity from Dexie and query results.
+     */
+    private _processSyncDelete;
+}
+
+export { type CacheRule as C, DvinaDatabase as D, SyncEngine as S, type CacheRuleCreate as a, type CacheRuleDelete as b, createHttpTransport as c, type CacheRuleUpdate as d, type SseQueryEvent as e, type SseSyncEvent as f, type SseTransport as g, type SseTransportOptions as h, type SubscriptionDescriptor as i, closeDatabase as j, createSseTransport as k, deleteDatabase as l, getOrCreateDatabase as m };