@abloatai/ablo 0.35.0 → 0.37.0

package/dist/sync/BootstrapFetcher.d.ts

@@ -1,280 +0,0 @@
-/**
- * Fetches the initial snapshot the sync engine needs before it can go live: the
- * current rows for the requested models plus the sync position from which to
- * resume live updates. It calls the sync server's `/sync/bootstrap` HTTP
- * endpoint, retries transient failures with backoff, and can fall back to a
- * cached snapshot when the device is offline. {@link BootstrapData} is the
- * shape it returns; {@link BootstrapOptions} configures it.
- */
-export interface BootstrapData {
-    type: 'full' | 'partial';
-    lastSyncId: number;
-    /**
-     * Model rows keyed by type name. Each row is opaque at this boundary; the
-     * engine asserts the per-model shape against the registered schema when it
-     * reduces the rows and writes them to local storage.
-     */
-    models?: Record<string, unknown[]>;
-    deltas?: ValidatedServerDelta[];
-    deltaCount?: number;
-    /** Model types whose server-side query failed (timeout, RLS error, and the like). */
-    failedModels?: string[];
-    timestamp: number;
-    /**
-     * The content hash of the schema the server currently has active for this
-     * tenant — the same hash `ablo push` computes. Present once a schema has been
-     * pushed. The client compares it against its own `expectedSchemaHash` to warn
-     * when the app's schema and the deployed schema have drifted apart.
-     */
-    schemaHash?: string;
-    /**
-     * Present when a paged single-model request stopped at its row limit with
-     * rows remaining: pass it back as the next page's `cursor`. Absent on the
-     * final page, on unpaged responses, and from servers that predate paging.
-     */
-    nextCursor?: string;
-}
-export interface BootstrapFetchResult {
-    notModified: boolean;
-    data?: BootstrapData;
-    etag?: string | null;
-}
-export interface BootstrapOptions {
-    /**
-     * Full base URL of the sync server's HTTP API, **including the `/api`
-     * prefix**. The bootstrap endpoint is appended as `/sync/bootstrap`, so
-     * the final request hits `${baseUrl}/sync/bootstrap`.
-     *
-     * Example: `'http://localhost:8080/api'` → `http://localhost:8080/api/sync/bootstrap`
-     *
-     * Default: `'http://localhost:8080/api'`.
-     */
-    baseUrl?: string;
-    /**
-     * Namespace for the offline bootstrap cache. Most callers leave this unset;
-     * the SDK fills it in once authentication has resolved the account scope, so
-     * the fallback cache is partitioned per account.
-     */
-    cacheScope?: string | null;
-    /**
-     * @deprecated Use `cacheScope`. Retained so code that constructs
-     * {@link BootstrapFetcher} directly keeps its cache namespace.
-     */
-    organizationId?: string;
-    syncGroups?: string[];
-    maxRetries?: number;
-    retryDelay?: number;
-    /**
-     * How long to wait for the server to START responding (response headers), in
-     * milliseconds. Default 20000 (20 seconds).
-     *
-     * Deliberately NOT a bound on the whole download: a cold-start snapshot can
-     * be tens of megabytes, and its transfer time depends on the connection. A
-     * healthy download that is actively delivering bytes is never aborted, no
-     * matter how long it takes — {@link stallTimeout} guards the body instead.
-     */
-    fetchTimeout?: number;
-    /**
-     * The longest quiet gap allowed between body chunks while downloading, in
-     * milliseconds. Default 15000 (15 seconds). This is the progress watchdog:
-     * it aborts a download whose stream has gone silent (dead connection,
-     * hung proxy) without ever penalizing a slow-but-moving transfer.
-     */
-    stallTimeout?: number;
-    /**
-     * The model names to request. When set, the server returns only these models
-     * and skips the rest. This is derived from each model's `load` strategy: only
-     * models loaded instantly (the default) are included. When unset, the server
-     * returns every model.
-     */
-    instantModels?: string[];
-    /**
-     * Getter for the current credential, read at request time so a refreshed
-     * token takes effect without recreating the helper. Preferred over
-     * {@link BootstrapFetcher.setAuthToken}.
-     */
-    getAuthToken?: AuthTokenGetter;
-}
-import { type AuthTokenGetter } from '../transaction/auth/credentialSource.js';
-import { type ValidatedServerDelta } from './schemas.js';
-export declare class BootstrapFetcher {
-    private options;
-    /**
-     * Every in-flight request's controller, tagged with the lane it belongs to. A
-     * registry rather than a single field because a chunked cold start runs
-     * several model fetches concurrently — aborting one request (its own
-     * TTFB/stall watchdog) must never take its siblings down, while
-     * {@link abort} takes down all of them.
-     */
-    private readonly activeControllers;
-    /**
-     * Non-scoped bootstraps currently running, keyed by request identity. A
-     * second call for the same snapshot joins the one already in flight rather
-     * than cancelling and restarting it — see {@link fetchBootstrap}.
-     */
-    private readonly flights;
-    /** Warn about schema drift at most once per helper. */
-    private schemaDriftWarned;
-    /**
-     * Abort every in-flight request in `lane` — or in every lane when none is
-     * given — with an explicit reason.
-     *
-     * The reason is load-bearing, not decoration. `fetch` rejects with the exact
-     * value handed to `abort()`, so passing a typed error is what lets the retry
-     * loop below tell a deliberate cancellation apart from a dead connection. A
-     * bare `abort()` produces an `AbortError` indistinguishable from the one the
-     * browser's stop button produces, and a retry loop that cannot tell them
-     * apart re-issues the requests it just killed.
-     */
-    private cancelActive;
-    /**
-     * The longest a single bootstrap can run before every watchdog below has
-     * necessarily fired, derived from those watchdogs rather than guessed. A
-     * caller wanting an outer deadline reads this instead of picking a number,
-     * so it cannot set one shorter than the work it wraps. A cold start pages
-     * through its models {@link CHUNK_CONCURRENCY} at a time; each request may
-     * spend `fetchTimeout` waiting for response headers and `stallTimeout`
-     * waiting for the next body chunk, and may be retried `maxRetries` times.
-     */
-    get budgetMs(): number;
-    get baseUrl(): string;
-    /**
-     * Advisory schema-drift check: compare the server's active schema hash (on the
-     * bootstrap response) against the hash this client was built with. A mismatch
-     * means the app's schema and the deployed schema have diverged — reads/writes
-     * relying on undeployed changes will later fail with an opaque DB constraint
-     * error. Warn once, actionably; never throws or blocks the bootstrap.
-     *
-     * The message names the SERVER it connected to, and spans all three real
-     * causes rather than assuming "you forgot to push". Drift most often means the
-     * schema was pushed to a different server, project, or environment than this
-     * client points at (a bare `ablo push` targets the hosted default; a local app
-     * usually reads a local server) — so the first, load-bearing pointer is `ablo
-     * status`, which names the exact org/project/environment the key resolves to
-     * and the deployed hash, turning "which of these is it?" into one glance. The
-     * older "Run `ablo push`" copy sent everyone down one path and confused the
-     * common wrong-target and version-skew cases.
-     */
-    private warnOnSchemaDrift;
-    /** Fetch the server's per-model schema surface and warn precisely — or stay
-     *  silent when every model this client declares matches (additive lead). */
-    private resolveSemanticDrift;
-    private warnWholeHashDrift;
-    constructor(options: BootstrapOptions);
-    /**
-     * Update the offline-cache namespace once auth has resolved the server-side
-     * account scope. This is intentionally not a public organizationId input.
-     */
-    setCacheScope(cacheScope: string): void;
-    setSyncGroups(syncGroups: readonly string[] | undefined): void;
-    /**
-     * Sets a fixed credential for callers that construct the helper directly.
-     * The SDK instead supplies `getAuthToken` and never calls this.
-     */
-    setAuthToken(authToken: string | undefined): void;
-    /**
-     * Fetch bootstrap data from sync engine with partial bootstrap support
-     * @param lastSyncId - Optional: client's current lastSyncId for partial bootstrap
-     * @returns Bootstrap data (either full snapshot or delta batch)
-     */
-    fetchBootstrap(lastSyncId?: number, 
-    /**
-     * A per-call set of sync groups for a scoped hydrate-on-enter. When given,
-     * the request uses these groups instead of the configured `syncGroups`, and
-     * does so without mutating the shared options, so a concurrent full
-     * bootstrap is unaffected. It also bypasses the offline snapshot cache,
-     * which holds the full bootstrap and would be a wrong answer to a subset
-     * request.
-     */
-    syncGroupsOverride?: readonly string[]): Promise<BootstrapData>;
-    /**
-     * The identity of a bootstrap request: everything that determines its answer.
-     * Two calls with the same key are asking the same question, so the second can
-     * take the first's result.
-     */
-    private flightKey;
-    /** One bootstrap, start to finish. {@link fetchBootstrap} owns whether it runs. */
-    private runBootstrap;
-    /**
-     * One bootstrap URL, fetched with backoff. Session errors and other
-     * non-retryable failures throw immediately; only transient failures
-     * (5xx, 429, timeouts, network blips) consume attempts. A cancellation is
-     * deliberate and therefore non-retryable — it leaves through the same gate.
-     */
-    private fetchWithRetries;
-    /**
-     * Cold-start bootstrap, one request per instant model with a small
-     * concurrency cap. Any chunk's terminal failure fails the whole
-     * bootstrap (a partial snapshot must never masquerade as a full one)
-     * and cancels its siblings.
-     */
-    private fetchChunkedBootstrap;
-    /**
-     * Fetch bootstrap with ETag, returning 304 hints
-     */
-    fetchBootstrapWithETag(): Promise<BootstrapFetchResult>;
-    private fetchWithETagUsing;
-    /**
-     * Read a response body as a stream under a progress watchdog: the stall
-     * timer re-arms on every chunk, so only a silent stream is aborted — a
-     * slow-but-moving download is never killed for total duration. A cold-start
-     * snapshot can be tens of megabytes; bounding its total transfer time was
-     * what trapped large orgs in an endless full-bootstrap retry loop.
-     *
-     * Falls back to `response.json()` when the response exposes no readable
-     * stream (empty bodies, some test doubles).
-     */
-    private readJsonWithStallGuard;
-    /**
-     * Perform one fetch. The timeout here bounds time to response headers
-     * only; the body download is guarded by the stall watchdog in
-     * {@link readJsonWithStallGuard}. Superseding an older in-flight
-     * bootstrap is the caller's job ({@link fetchBootstrap} cancels the
-     * registry) — chunk requests run through here concurrently and must
-     * not cancel each other.
-     */
-    private fetchOnce;
-    private fetchOnceWith;
-    /**
-     * Fetch a single entity by ID (on-demand self-healing).
-     * Returns `null` for 404 (entity deleted) — this is an expected state, not an error.
-     * Throws for unexpected HTTP errors (5xx, network failures).
-     */
-    fetchEntity(modelName: string, id: string): Promise<Record<string, unknown> | null>;
-    /**
-     * Clear all cached bootstrap data
-     */
-    clearCache(): void;
-    private getBootstrapCacheKey;
-    private saveCachedBootstrap;
-    private loadCachedBootstrap;
-    /**
-     * Abort every ongoing bootstrap request (including all chunks of a
-     * chunked cold start). Entity self-heal fetches are unaffected.
-     *
-     * The flight registry is cleared first and synchronously, so a caller that
-     * bootstraps again in the same tick starts a fresh request rather than
-     * joining the one being torn down.
-     */
-    abort(): void;
-    /**
-     * Helper to delay execution
-     */
-    private delay;
-    /**
-     * Get health status of sync engine
-     */
-    checkHealth(): Promise<boolean>;
-}
-/**
- * Assemble per-model chunk responses into one full snapshot.
- *
- * Each chunk is internally consistent at its own sync position, and the
- * positions differ (the chunks were served seconds apart). Anchoring the
- * merged snapshot at the MINIMUM position turns that skew into an ordinary
- * "briefly offline client": the WS catch-up replays every delta from the
- * anchor, and since deltas carry full rows, re-applying one a later chunk
- * already reflects converges to the same state. Anchoring at anything later
- * would silently skip deltas for the earliest-fetched models.
- */
-export declare function mergeBootstrapChunks(chunks: readonly BootstrapData[]): BootstrapData;