@dvina/sdk 4.1.111 → 4.1.173

package/dist/{sync-engine-DYHreGOv.d.ts → connection-ClMdDUce.d.ts}

@@ -1,8 +1,8 @@
+import { D as DvinaQueryRef, M as MutationOptions, c as DvinaRequest, P as PageInfoData, C as ConnectionVariables, F as FetchOptions } from './types-BfiQdtra.js';
 import { DocumentNode } from 'graphql';
 import * as dexie from 'dexie';
 import { Dexie, Table } from 'dexie';
-import { D as DvinaError, a as DvinaAuthenticationError } from './error-CsVoUTY8.js';
-import { a as DvinaQueryRef, M as MutationOptions } from './types-Chg8ASmf.js';
+import { b as DvinaError, D as DvinaAuthenticationError, a as DvinaForbiddenError, d as DvinaNetworkError } from './error-Bk0Jmuzd.js';
 
 /** Cached result metadata for a specific query + variables combination */
 interface QueryResultEntry {
@@ -73,6 +73,9 @@ interface EntityRecord {
 declare class DvinaDatabase {
     db: Dexie;
     private readonly _dbName;
+    private _heartbeat;
+    readonly workspaceId: string;
+    readonly userId: string;
     /**
      * Resolves when the schema-hash check is complete.
      * Consumers that depend on a consistent schema should await this before
@@ -81,6 +84,20 @@ declare class DvinaDatabase {
      */
     readonly ready: Promise<void>;
     constructor(workspaceId: string, userId: string);
+    /**
+     * Records this version's database in the registry (first, so it is never taken for a stray one), opens it, and
+     * then removes the workspace+user's stale versions without waiting for that. A long-open tab keeps telling the
+     * registry it is in use.
+     */
+    private _open;
+    private _register;
+    /**
+     * A Dexie instance for this database. When another tab removes it (a sign-out there, or a version opened there
+     * long after this one), this tab closes its connection at once, so the removal is never blocked, and moves to a
+     * fresh, empty database of the same name: its reads keep working, from the network, and the app is told so it
+     * can offer a reload.
+     */
+    private _createDexie;
     /**
      * Verify that the stored schema hash matches the current codegen hash.
      * If the hashes differ the database is deleted and recreated so that
@@ -105,6 +122,10 @@ declare class DvinaDatabase {
     getLastSyncId(): Promise<string>;
     /** Persist the last processed sync event ID. */
     setLastSyncId(syncId: string): Promise<void>;
+    /** When the store was last known to be current (ms since epoch), or null if it never was on this device. */
+    getLiveAt(): Promise<number | null>;
+    /** Persist when the store was last known to be current. */
+    setLiveAt(liveAt: number): Promise<void>;
     /** Get the last applied remote cache epoch, or 0 if none. */
     getCacheEpoch(): Promise<number>;
     /** Persist the last applied remote cache epoch. */
@@ -132,6 +153,12 @@ declare function closeDatabase(token: string): void;
  * Use with caution — this wipes all cached data for the workspace+user.
  */
 declare function deleteDatabase(token: string): Promise<void>;
+/**
+ * Remove everything the user keeps on this device: their databases in every workspace and of every SDK version, and
+ * their registry entries. Call on sign-out and account deletion, so nothing of theirs is left for the next person on
+ * a shared device. Never throws.
+ */
+declare function deleteUserLocalData(userId: string): Promise<void>;
 
 interface HttpTransportOptions {
     /** Full GraphQL HTTP endpoint URL (e.g. 'https://api.dvina.ai/graphql') */
@@ -160,9 +187,13 @@ interface HttpTransportOptions {
      */
     onError?: (error: DvinaError) => void;
 }
+/** How one request reports: `reportErrors: false` keeps its failure from `onError` (a failed sign-in still goes). */
+interface HttpRequestOptions {
+    reportErrors?: boolean;
+}
 interface HttpTransport {
     /** Execute a GraphQL query or mutation */
-    request: <T>(document: DocumentNode, variables?: Record<string, unknown>) => Promise<T>;
+    request: <T>(document: DocumentNode, variables?: Record<string, unknown>, options?: HttpRequestOptions) => Promise<T>;
 }
 /**
  * Create a fetch-based GraphQL HTTP transport with:
@@ -194,12 +225,18 @@ interface SseSyncEvent {
     payload: Record<string, unknown> | null;
 }
 interface SseQueryEvent {
-    type: 'add' | 'remove' | 'resync';
+    /**
+     * `add`/`remove`: an entity entered or left the subscription's set; `resync`: read the list again; `count`: how many
+     * the set holds now (`totalCount`), which the server sends after its adds and removes settle and after a catch-up.
+     */
+    type: 'add' | 'remove' | 'resync' | 'count';
     subscriptionId: string;
     entityId?: string;
     entityType: string;
+    totalCount?: number;
 }
-type RealtimeEventTopic = 'active-chats' | 'active-tabs' | 'desktop-device-presence' | 'token-usage-status';
+declare const REALTIME_EVENT_TOPICS: readonly ["active-chats", "desktop-device-presence", "mcp-auth", "token-usage-status", "user-notification"];
+type RealtimeEventTopic = (typeof REALTIME_EVENT_TOPICS)[number];
 interface SseRealtimeEvent {
     topic: RealtimeEventTopic;
     type: string;
@@ -236,12 +273,20 @@ interface SseTransportOptions {
     onCursor?: (syncId: string) => void;
     /** Called when the server signals that the sync gap is unrecoverable and a full resync is needed */
     onFullResync?: () => void;
+    /**
+     * Called once a connection has caught up: the missed events before it are applied, and every later event is live.
+     * A server too old to send it never calls it.
+     */
+    onSynced?: () => void;
     /** Called after a reconnect successfully re-registers active subscriptions */
     onReconnect?: () => void;
     /** Called on connection state changes */
     onStateChange?: (state: 'connecting' | 'connected' | 'disconnected') => void;
-    /** Called when auth recovery fails permanently */
-    onError?: (error: DvinaAuthenticationError) => void;
+    /**
+     * Called when auth recovery fails permanently, when the API refuses the stream (403), and when the token is
+     * another cell's (421 WRONG_CELL: a DvinaNetworkError with status 421; the stream keeps retrying meanwhile).
+     */
+    onError?: (error: DvinaAuthenticationError | DvinaForbiddenError | DvinaNetworkError) => void;
 }
 interface SseTransport {
     /** Start the SSE connection */
@@ -263,6 +308,63 @@ interface SseTransport {
 }
 declare function createSseTransport(options: SseTransportOptions): SseTransport;
 
+/**
+ * Whether the local store is current: `live` once the delta-sync stream has caught up (the server's `synced`, after
+ * the missed events are applied) and no full resync is running; `syncing` while it connects, catches up or resyncs;
+ * `disconnected` while the stream is down. `liveAt` is when the store was last known to be current: now, while it is
+ * live; the moment it stopped being live, afterwards (kept on the device, so an app opened offline still knows).
+ */
+type SyncState = 'live' | 'syncing' | 'disconnected';
+interface SyncStatus {
+    state: SyncState;
+    liveAt: number | null;
+}
+interface SyncStatusSource {
+    get(): SyncStatus;
+    subscribe(listener: () => void): () => void;
+}
+interface SyncStatusStoreOptions {
+    saveLiveAt: (liveAt: number) => Promise<void>;
+    now?: () => number;
+    fallbackAfterMs?: number;
+}
+/** Follows the stream's state and the server's `synced` into a status the app can show; see SyncStatus. */
+declare class SyncStatusStore implements SyncStatusSource {
+    private readonly _options;
+    private _status;
+    private _connected;
+    private _syncedSinceConnect;
+    private _resyncing;
+    /** Whether the API said its stream marks `synced`: then it is waited for, with no fallback. */
+    private _serverMarksSynced;
+    private _fallbackTimer;
+    private _saveTimer;
+    private readonly _listeners;
+    private readonly _now;
+    constructor(_options: SyncStatusStoreOptions);
+    get(): SyncStatus;
+    subscribe(listener: () => void): () => void;
+    /** The moment kept from an earlier session; a later moment of this one wins. */
+    restoreLiveAt(liveAt: number | null): void;
+    transportState(state: 'connecting' | 'connected' | 'disconnected'): void;
+    /** The server's `synced`: everything before it is applied. */
+    synced(): void;
+    /** What the API's policy says: whether its stream marks `synced` (an older API does not). */
+    serverMarksSynced(marks: boolean): void;
+    resyncStarted(): void;
+    resyncFinished(): void;
+    /** Stops keeping the moment while live (the session is over). */
+    dispose(): void;
+    /** Applies a candidate state; it is live only when connected, caught up and not resyncing. */
+    private _update;
+    private _startFallback;
+    private _stopFallback;
+    private _startSaving;
+    private _stopSaving;
+    private _save;
+    private _set;
+}
+
 /**
  * Convention-based cache rules generated by codegen.
  * These tell the SyncEngine how to update the local store after a mutation.
@@ -304,6 +406,8 @@ interface SyncEngineOptions {
     httpTransport: HttpTransport;
     /** Optional SSE transport for delta sync (browser-only) */
     sseTransport?: SseTransport;
+    /** Where the engine reports whether the store is current; one is made when not given. */
+    syncStatus?: SyncStatusStore;
 }
 interface WatchedRelationMetadata {
     fieldName: string;
@@ -337,6 +441,9 @@ declare class SyncEngine {
     private _cache;
     private _queryExecutor;
     private _mutationExecutor;
+    private _syncStatus;
+    /** Whether the local store is current (live), and since when it is not (see SyncStatus). */
+    get syncStatus(): SyncStatusSource;
     /**
      * Maps subscriptionId → queryKey for routing server-driven query events
      * to the correct cache entry. Populated by watch() when a subscription
@@ -345,10 +452,28 @@ declare class SyncEngine {
     private _subscriptionToQueryKey;
     /** Active subscription metadata used for targeted revalidation fallback. */
     private _subscriptionToQuery;
+    /**
+     * The one server subscription each watched query holds, with how many watches share it: the same query
+     * watched in many places registers once, so a client does not run into the server's per-user limit.
+     */
+    private _serverSubscriptions;
     /** Last per-query revalidation timestamp to avoid refetch storms. */
     private _lastRevalidatedAt;
     /** Retry timers for recovery refetches that failed and need another attempt. */
     private _revalidationRetryTimers;
+    /**
+     * Failures in a row of a query's revalidation, while it is being tried again (revalidation-retry): its first failure
+     * is reported (`onError`), the tries after it are not. Gone once it succeeds, fails for good, or the connection
+     * comes back (handleTransportReconnect).
+     */
+    private _revalidationFailures;
+    /** Tries that came due while the page was hidden: run once it is shown. */
+    private _revalidationsAwaitingVisibility;
+    private _visibilityListener;
+    /** The jitter's source (revalidationRetryDelay); a test fixes it. */
+    private _random;
+    /** A page being read again after an `add` it cannot place: `true` once another `add` asks for one more reading. */
+    private _placementReads;
     /**
      * Last mutation/sync touch timestamp by entity type.
      * Used to detect stale cached query results on watch re-entry.
@@ -362,9 +487,12 @@ declare class SyncEngine {
      */
     startSync(): Promise<void>;
     /**
-     * Stop the SSE delta sync connection.
+     * Stop the SSE delta sync connection. Failed revalidations stop being tried with it (the SDK being destroyed, a
+     * workspace switch, a full resync that reads every list again): their timers, the tries held for a hidden page and
+     * the page's listener go.
      */
     stopSync(): void;
+    private _stopRevalidationRetries;
     /**
      * Handle a full-resync signal from the server.
      *
@@ -376,6 +504,8 @@ declare class SyncEngine {
     /**
      * Ordinary transport reconnects should recover from the sync cursor and
      * server-side subscription state without eagerly refetching every active query.
+     * Only the queries whose revalidation was failing are read again, as from their first try: the connection (or a
+     * lifecycle hint, which reconnects it) may be what they were waiting for.
      */
     handleTransportReconnect(): Promise<void>;
     /**
@@ -417,6 +547,10 @@ declare class SyncEngine {
      * @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, relationMetadata?: WatchedRelationMetadata[]): DvinaQueryRef<T>;
+    /** Registers the query's server subscription, or shares the one it already has; returns its id. */
+    private _retainServerSubscription;
+    /** Unsubscribes the query on the server once the last watch sharing its subscription is gone. */
+    private _releaseServerSubscription;
     private _subscribeWithQuerySyncId;
     /**
      * Execute a mutation with optional optimistic update and automatic cache rule.
@@ -452,13 +586,28 @@ declare class SyncEngine {
      */
     clearAll(): Promise<void>;
     /**
-     * Process a server-driven query event (query-add / query-remove).
+     * Process a server-driven query event (query-add / query-remove / query-resync / query-count).
      *
      * 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.
+     * The list's totalCount is the server's: `count` sets it, and adds and removes move only the list's entities.
      */
     processQueryEvent(event: SseQueryEvent): Promise<void>;
+    /**
+     * Puts an entity the server says now matches a subscription into its cached page. First only where it belongs
+     * first (a newest-first list it heads); in any other order (by name, by kind, oldest first, an old item that
+     * changed) the page is read again, so the list never shows it on top of an order it does not belong to. One the
+     * page already lists (a reconnect's catch-up names every changed entity that matches) stays where it is: its row
+     * is already written, and the page is read again only when its order key moved it past a neighbour.
+     */
+    private _placeAddedEntity;
+    /**
+     * Reads a page again for `add` events it cannot place: one reading at a time per page, and one more after it when
+     * further events came while it ran (the first may have been answered before their changes), so a burst (a
+     * reconnect's catch-up) costs two requests, not one each.
+     */
+    private _rereadForPlacement;
     /**
      * Handle an upsert sync event: normalize the payload and write to Dexie.
      *
@@ -472,10 +621,12 @@ declare class SyncEngine {
     private _revalidateSubscriptions;
     private _revalidateSubscriptionQuery;
     private _scheduleRevalidationRetry;
+    /** A try that came due: run now, or once the page is shown again when it is hidden. */
+    private _runRevalidationRetry;
+    private _listenForVisibility;
     private _clearRevalidationRetry;
     private _getActiveSubscriptionByQueryKey;
     private _hasActiveSubscriptionForQueryKey;
-    private _hasOtherActiveSubscriptionForQueryKey;
     private _getActiveSubscriptionsForEntityType;
     private _materializeWatchedRelations;
     private _resolveStoredRelationFallback;
@@ -489,4 +640,65 @@ declare class SyncEngine {
     private _processSyncDelete;
 }
 
-export { type CacheRule as C, DvinaDatabase as D, type RealtimeEventTopic as R, SyncEngine as S, type SseRealtimeEvent as a, type CacheRuleCreate as b, createHttpTransport as c, type CacheRuleDelete as d, type CacheRuleUpdate as e, type SseQueryEvent as f, type SseSyncEvent as g, type SseTransport as h, type SseTransportOptions as i, type SubscriptionDescriptor as j, closeDatabase as k, createSseTransport as l, deleteDatabase as m, getOrCreateDatabase as n };
+/**
+ * Base class that holds the transport functions.
+ * Every generated model, connection, query, and the root SDK class extend this.
+ *
+ * Operation classes use `_syncEngine` for queries/mutations/watch.
+ * Model classes use `_request` for compatibility (lazy fetch).
+ */
+declare class Request {
+    protected _request: DvinaRequest;
+    protected _syncEngine?: SyncEngine;
+    protected _baseUrl?: string;
+    constructor(request: DvinaRequest, syncEngine?: SyncEngine, baseUrl?: string);
+}
+
+/**
+ * Default connection variables when paginating.
+ * Ensures `first` or `last` is set when a cursor is provided.
+ */
+declare function defaultConnection<V extends ConnectionVariables>(variables: V): V;
+/**
+ * PageInfo model following the Relay spec.
+ */
+declare class PageInfo {
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    startCursor?: string | null;
+    endCursor?: string | null;
+    constructor(data: PageInfoData);
+}
+/**
+ * Abstract base class for connection types.
+ * Holds nodes and page info, used for type checking.
+ */
+declare abstract class AbstractConnection<Node> extends Request {
+    pageInfo: PageInfo;
+    nodes: Node[];
+    totalCount?: number;
+    constructor(request: DvinaRequest);
+}
+/**
+ * Concrete connection class with pagination helpers.
+ * Generated connection subclasses extend this.
+ *
+ * The `_fetch` closure is created by the query class and allows re-fetching
+ * with different pagination variables.
+ */
+declare class Connection<Node> extends AbstractConnection<Node> {
+    private _fetch;
+    constructor(request: DvinaRequest, fetch: (variables?: ConnectionVariables, options?: FetchOptions) => Promise<Connection<Node> | undefined>, nodes: Node[], pageInfo: PageInfo, totalCount?: number);
+    /**
+     * Fetch the next page and append nodes.
+     * Mutates this connection instance in place (nodes are appended, pageInfo updated).
+     */
+    fetchNext(options?: FetchOptions): Promise<this>;
+    /**
+     * Fetch the previous page and prepend nodes.
+     * Mutates this connection instance in place (nodes are prepended, pageInfo updated).
+     */
+    fetchPrevious(options?: FetchOptions): Promise<this>;
+}
+
+export { AbstractConnection as A, type CacheRule as C, DvinaDatabase as D, PageInfo as P, type RealtimeEventTopic as R, type SseRealtimeEvent as S, SyncEngine as a, type CacheRuleCreate as b, createHttpTransport as c, type CacheRuleDelete as d, type CacheRuleUpdate as e, Connection as f, Request as g, type SseQueryEvent as h, type SseSyncEvent as i, type SseTransport as j, type SseTransportOptions as k, type SubscriptionDescriptor as l, type SyncState as m, type SyncStatus as n, type SyncStatusSource as o, closeDatabase as p, createSseTransport as q, defaultConnection as r, deleteDatabase as s, deleteUserLocalData as t, getOrCreateDatabase as u };

package/dist/{error-CsVoUTY8.d.ts → error-Bk0Jmuzd.d.ts}

@@ -27,13 +27,21 @@ declare class DvinaNetworkError extends DvinaError {
     constructor(message: string, status?: number, cause?: Error);
 }
 /**
- * Error thrown when authentication fails (401/403).
+ * Error thrown when authentication fails (401).
  */
 declare class DvinaAuthenticationError extends DvinaError {
     /** The token that was used when the auth error occurred (for stale-token detection). */
     readonly failedToken?: string;
     constructor(message?: string, failedTokenOrCause?: string | Error, cause?: Error);
 }
+/**
+ * Error thrown when the API knows the caller but refuses the request (403), e.g. a workspace they were removed
+ * from. Not a failed sign-in: no token refresh helps, and the session stays.
+ */
+declare class DvinaForbiddenError extends DvinaError {
+    readonly status = 403;
+    constructor(message?: string, cause?: Error);
+}
 /**
  * Known GraphQL error codes returned by the Dvina API in `extensions.code`.
  * Used for programmatic matching in SDK error detection.
@@ -58,7 +66,7 @@ declare class DvinaPlanRestrictionError extends DvinaGraphQLError {
 }
 /**
  * Error thrown when the chat session token limit is reached (SESSION_TOKEN_LIMIT_REACHED).
- * Distinct from inference quota — this is a per-session GraphQL limit.
+ * A per-session GraphQL limit.
  */
 declare class DvinaTokenLimitError extends DvinaGraphQLError {
     constructor(errors: readonly GraphQLErrorEntry[], query?: string, variables?: Record<string, unknown>);
@@ -92,4 +100,4 @@ interface GraphQLErrorEntry {
     extensions?: Record<string, unknown>;
 }
 
-export { DvinaError as D, GRAPHQL_ERROR_CODES as G, DvinaAuthenticationError as a, DvinaGraphQLError as b, DvinaNetworkError as c, DvinaNotFoundError as d, DvinaPlanRestrictionError as e, DvinaTokenLimitError as f, type GraphQLErrorEntry as g, createGraphQLError as h, extractErrorCode as i };
+export { DvinaAuthenticationError as D, GRAPHQL_ERROR_CODES as G, DvinaForbiddenError as a, DvinaError as b, DvinaGraphQLError as c, DvinaNetworkError as d, DvinaNotFoundError as e, DvinaPlanRestrictionError as f, DvinaTokenLimitError as g, type GraphQLErrorEntry as h, createGraphQLError as i, extractErrorCode as j };