@instantdb/platform 1.0.60 → 1.0.61

package/dist/commonjs/backupDownload.js

@@ -0,0 +1,255 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.downloadBackupArchive = downloadBackupArchive;
+const isAbortError = (e) => e?.name === 'AbortError';
+const errorMessage = (e) => e instanceof Error ? e.message : String(e);
+/**
+ * Downloads a backup into a single archive written to `opts.sink`: entries
+ * in the canonical restore order (`config.json`, then the
+ * `entities/<etype>.jsonl` shards, then `files/<locationId>` storage blobs —
+ * all entity files before any storage file), with the encoder writing
+ * through a counting sink that awaits the caller's sink, so a fast source
+ * can't outrun it and balloon memory.
+ *
+ * The runtime-specific pieces are injected: how to fetch a presigned URL
+ * (`fetchBody`), where the bytes go (`sink`), and the archive encoder
+ * (`createWriter`). Most callers reach this via
+ * {@link BackupsManager.downloadArchive}.
+ */
+async function downloadBackupArchive(opts) {
+    const { manager, backup, fetchBody, createWriter, onProgress } = opts;
+    // Internal controller so a pipeline failure also tears down the
+    // storage-files discovery stream and any in-flight body fetches.
+    const abortController = new AbortController();
+    if (opts.signal?.aborted) {
+        abortController.abort();
+    }
+    else {
+        opts.signal?.addEventListener('abort', () => abortController.abort(), {
+            once: true,
+        });
+    }
+    const signal = abortController.signal;
+    let entitiesCompleted = 0;
+    let entitiesTotal = null;
+    let filesCompleted = 0;
+    let filesTotal = null;
+    let zipBytes = 0;
+    let bytesRead = 0;
+    let currentEntity = '';
+    let currentFile = '';
+    const bytesTotal = backup.uncompressedSize != null
+        ? backup.uncompressedSize + (backup.filesSize ?? 0)
+        : null;
+    const tick = () => onProgress?.({
+        entitiesCompleted,
+        entitiesTotal,
+        filesCompleted,
+        filesTotal,
+        zipBytes,
+        bytesRead,
+        bytesTotal,
+        currentEntity,
+        currentFile,
+    });
+    // Throttle by time: a large backup pushes many small chunks and ticking on
+    // every one is wasted work. Phase changes tick() directly so they're still
+    // immediate.
+    const TICK_INTERVAL_MS = 100;
+    let lastTickAt = 0;
+    const throttledTick = () => {
+        const now = Date.now();
+        if (now - lastTickAt >= TICK_INTERVAL_MS) {
+            lastTickAt = now;
+            tick();
+        }
+    };
+    // Count the uncompressed bytes of a source body for progress as it streams
+    // into the archive.
+    const countBytes = (body) => body.pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+            bytesRead += chunk.byteLength;
+            throttledTick();
+            controller.enqueue(chunk);
+        },
+    }));
+    // Storage-files discovery runs concurrently with the entity phase and is
+    // drained eagerly into a queue. That isn't just overlap: it closes the
+    // NDJSON connection quickly instead of holding it open (and at the mercy of
+    // idle timeouts) while multi-GB blobs download. `queueHead` walks the array
+    // in place, freeing each slot as it's consumed.
+    const queue = [];
+    let queueHead = 0;
+    let storageDone = false;
+    let storageError = null;
+    let waitResolve = null;
+    const notify = () => {
+        const w = waitResolve;
+        waitResolve = null;
+        w?.();
+    };
+    // Never rejects: failures land in storageError for the drain loop to throw.
+    const discovery = (async () => {
+        let discoveryComplete = false;
+        try {
+            for await (const file of manager.streamStorageFiles(backup.id, {
+                signal,
+            })) {
+                queue.push(file);
+                filesTotal = (filesTotal ?? 0) + 1;
+                throttledTick();
+                notify();
+            }
+            discoveryComplete = true;
+        }
+        catch (e) {
+            // The abort path is expected when the pipeline failed and we tore the
+            // discovery down.
+            if (!isAbortError(e)) {
+                storageError = e;
+            }
+        }
+        finally {
+            // A failed listing keeps the total unknown rather than reading as an
+            // empty-but-complete storage phase.
+            if (discoveryComplete && filesTotal == null)
+                filesTotal = 0;
+            storageDone = true;
+            tick();
+            notify();
+        }
+    })();
+    const entries = (async function* () {
+        const files = await manager.listFiles(backup.id, { signal });
+        if (files.length === 0) {
+            throw new Error('No files found for this backup.');
+        }
+        // We write entries in the order the server returns them, and restore
+        // requires config.json to be the first entry. Fail loudly rather than
+        // build a zip that can't be restored.
+        if (files[0].name !== 'config.json') {
+            throw new Error(`Backup files came back in an unexpected order (expected config.json first, got "${files[0].name}").`);
+        }
+        // config.json isn't a namespace — count only the entities/*.jsonl shards.
+        entitiesTotal = files.filter((f) => f.name !== 'config.json').length;
+        tick();
+        for (const f of files) {
+            currentEntity = f.name;
+            tick();
+            const url = await manager.getFileUrl(backup.id, f.name, { signal });
+            let body;
+            try {
+                body = await fetchBody(url, signal);
+            }
+            catch (e) {
+                if (isAbortError(e))
+                    throw e;
+                throw new Error(`Failed to fetch ${f.name}: ${errorMessage(e)}.`);
+            }
+            yield {
+                name: f.name,
+                input: countBytes(body),
+                onAdded: () => {
+                    if (f.name !== 'config.json')
+                        entitiesCompleted++;
+                    tick();
+                },
+            };
+        }
+        currentEntity = '';
+        tick();
+        while (true) {
+            if (storageError)
+                throw storageError;
+            // A caller abort while no fetch is in flight surfaces only in the
+            // discovery stream, which swallows it as expected teardown — check
+            // explicitly so a cancellation can't read as a complete storage phase
+            // with files still undiscovered.
+            signal.throwIfAborted();
+            let file;
+            if (queueHead < queue.length) {
+                file = queue[queueHead];
+                queue[queueHead] = undefined;
+                queueHead++;
+            }
+            if (file) {
+                const label = file.path || file.locationId;
+                currentFile = label;
+                tick();
+                let body;
+                try {
+                    body = await fetchBody(file.url, signal);
+                }
+                catch (e) {
+                    if (isAbortError(e))
+                        throw e;
+                    throw new Error(`Couldn't download storage file "${label}" (${errorMessage(e)}).`);
+                }
+                yield {
+                    name: `files/${file.locationId}`,
+                    input: countBytes(body),
+                    onAdded: () => {
+                        filesCompleted++;
+                        tick();
+                    },
+                };
+            }
+            else if (storageDone) {
+                break;
+            }
+            else {
+                await new Promise((resolve) => {
+                    waitResolve = resolve;
+                });
+            }
+        }
+        currentFile = '';
+        tick();
+        if (storageError)
+            throw storageError;
+    })();
+    const sinkWriter = opts.sink.getWriter();
+    try {
+        // Sink the archive encoder writes into: it tallies the encoded size for
+        // progress, then forwards to the caller's sink. Awaiting the downstream
+        // write propagates backpressure up into the encoder, so a fast source
+        // can't outrun the sink and balloon memory.
+        const countingSink = new WritableStream({
+            async write(chunk) {
+                zipBytes += chunk.byteLength;
+                throttledTick();
+                await sinkWriter.write(chunk);
+            },
+            async close() {
+                await sinkWriter.close();
+                tick();
+            },
+            async abort(reason) {
+                await sinkWriter.abort(reason);
+            },
+        });
+        const writer = await createWriter(countingSink, signal);
+        for await (const entry of entries) {
+            await writer.add(entry.name, entry.input, {
+                lastModDate: backup.backupAt,
+            });
+            entry.onAdded();
+        }
+        // A caller abort that lands after the last entry lets the generator
+        // finish cleanly; don't close and return a complete-looking archive.
+        signal.throwIfAborted();
+        await writer.close();
+        await discovery;
+        tick();
+        return { entities: entitiesCompleted, files: filesCompleted, zipBytes };
+    }
+    catch (e) {
+        // Tear down the discovery stream and any in-flight body fetches so we
+        // don't keep pulling from S3, and abort the caller's sink so it can
+        // discard whatever it wrote.
+        abortController.abort();
+        await sinkWriter.abort(e).catch(() => { });
+        throw e;
+    }
+}
+//# sourceMappingURL=backupDownload.js.map

package/dist/commonjs/backupDownload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backupDownload.js","sourceRoot":"","sources":["../../src/backupDownload.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  AppBackup,\n  AppBackupStorageFile,\n  BackupsManager,\n} from './backups.ts';\n\nexport type BackupDownloadProgress = {\n  entitiesCompleted: number;\n  entitiesTotal: number | null;\n  filesCompleted: number;\n  filesTotal: number | null;\n  // Compressed bytes written to the sink so far (the zip's on-disk size).\n  zipBytes: number;\n  // Uncompressed bytes read from source bodies, and the backup's known\n  // uncompressed total — the numerator/denominator for a progress bar.\n  // bytesTotal is null when the backup row carries no sizes.\n  bytesRead: number;\n  bytesTotal: number | null;\n  // The entry currently being fetched in each phase; empty while that phase\n  // isn't actively fetching, so a finished phase stops claiming a file.\n  currentEntity: string;\n  currentFile: string;\n};\n\nexport type BackupDownloadResult = {\n  entities: number;\n  files: number;\n  zipBytes: number;\n};\n\n/**\n * The archive encoder {@link downloadBackupArchive} writes entries through,\n * supplied by the caller so this package doesn't depend on a zip\n * implementation. zip.js's `ZipWriter` satisfies it structurally, so\n * `new ZipWriter(sink, { zip64: true, signal })` works without an adapter.\n *\n * Implementations must handle archives past 4GB — for zip that means zip64,\n * without which the central-directory offsets wrap and the archive is\n * silently unreadable.\n */\nexport type BackupArchiveWriter = {\n  add(\n    name: string,\n    input: ReadableStream<Uint8Array>,\n    opts: { lastModDate: Date },\n  ): Promise<unknown>;\n  close(): Promise<unknown>;\n};\n\nexport type DownloadBackupArchiveOpts = {\n  backup: AppBackup;\n  /**\n   * Fetches a presigned URL, resolving with the response body and rejecting\n   * on a non-200 status. Put the status in the message (e.g. `HTTP 403`) —\n   * it's surfaced to the user alongside the failing entry's name. The entity\n   * files are served with `Content-Encoding: zstd`; browser fetch decodes\n   * that transparently, other runtimes must decompress explicitly.\n   */\n  fetchBody: (\n    url: string,\n    signal: AbortSignal,\n  ) => Promise<ReadableStream<Uint8Array>>;\n  /**\n   * Where the archive's bytes go. Closed after the last entry is written;\n   * aborted when the download fails or is cancelled, so the caller can\n   * discard partial output.\n   */\n  sink: WritableStream<Uint8Array>;\n  /**\n   * Builds the archive encoder over a sink that already counts progress and\n   * carries the caller's sink's backpressure.\n   */\n  createWriter: (\n    sink: WritableStream<Uint8Array>,\n    signal: AbortSignal,\n  ) => Promise<BackupArchiveWriter>;\n  signal?: AbortSignal;\n  onProgress?: (progress: BackupDownloadProgress) => void;\n};\n\nconst isAbortError = (e: unknown): boolean =>\n  (e as { name?: string })?.name === 'AbortError';\n\nconst errorMessage = (e: unknown): string =>\n  e instanceof Error ? e.message : String(e);\n\n/**\n * Downloads a backup into a single archive written to `opts.sink`: entries\n * in the canonical restore order (`config.json`, then the\n * `entities/<etype>.jsonl` shards, then `files/<locationId>` storage blobs —\n * all entity files before any storage file), with the encoder writing\n * through a counting sink that awaits the caller's sink, so a fast source\n * can't outrun it and balloon memory.\n *\n * The runtime-specific pieces are injected: how to fetch a presigned URL\n * (`fetchBody`), where the bytes go (`sink`), and the archive encoder\n * (`createWriter`). Most callers reach this via\n * {@link BackupsManager.downloadArchive}.\n */\nexport async function downloadBackupArchive(\n  opts: DownloadBackupArchiveOpts & {\n    manager: Pick<\n      BackupsManager,\n      'listFiles' | 'getFileUrl' | 'streamStorageFiles'\n    >;\n  },\n): Promise<BackupDownloadResult> {\n  const { manager, backup, fetchBody, createWriter, onProgress } = opts;\n\n  // Internal controller so a pipeline failure also tears down the\n  // storage-files discovery stream and any in-flight body fetches.\n  const abortController = new AbortController();\n  if (opts.signal?.aborted) {\n    abortController.abort();\n  } else {\n    opts.signal?.addEventListener('abort', () => abortController.abort(), {\n      once: true,\n    });\n  }\n  const signal = abortController.signal;\n\n  let entitiesCompleted = 0;\n  let entitiesTotal: number | null = null;\n  let filesCompleted = 0;\n  let filesTotal: number | null = null;\n  let zipBytes = 0;\n  let bytesRead = 0;\n  let currentEntity = '';\n  let currentFile = '';\n  const bytesTotal =\n    backup.uncompressedSize != null\n      ? backup.uncompressedSize + (backup.filesSize ?? 0)\n      : null;\n\n  const tick = () =>\n    onProgress?.({\n      entitiesCompleted,\n      entitiesTotal,\n      filesCompleted,\n      filesTotal,\n      zipBytes,\n      bytesRead,\n      bytesTotal,\n      currentEntity,\n      currentFile,\n    });\n\n  // Throttle by time: a large backup pushes many small chunks and ticking on\n  // every one is wasted work. Phase changes tick() directly so they're still\n  // immediate.\n  const TICK_INTERVAL_MS = 100;\n  let lastTickAt = 0;\n  const throttledTick = () => {\n    const now = Date.now();\n    if (now - lastTickAt >= TICK_INTERVAL_MS) {\n      lastTickAt = now;\n      tick();\n    }\n  };\n\n  // Count the uncompressed bytes of a source body for progress as it streams\n  // into the archive.\n  const countBytes = (\n    body: ReadableStream<Uint8Array>,\n  ): ReadableStream<Uint8Array> =>\n    body.pipeThrough(\n      new TransformStream<Uint8Array, Uint8Array>({\n        transform(chunk, controller) {\n          bytesRead += chunk.byteLength;\n          throttledTick();\n          controller.enqueue(chunk);\n        },\n      }),\n    );\n\n  // Storage-files discovery runs concurrently with the entity phase and is\n  // drained eagerly into a queue. That isn't just overlap: it closes the\n  // NDJSON connection quickly instead of holding it open (and at the mercy of\n  // idle timeouts) while multi-GB blobs download. `queueHead` walks the array\n  // in place, freeing each slot as it's consumed.\n  const queue: (AppBackupStorageFile | undefined)[] = [];\n  let queueHead = 0;\n  let storageDone = false;\n  let storageError: Error | null = null;\n  let waitResolve: (() => void) | null = null;\n  const notify = () => {\n    const w = waitResolve;\n    waitResolve = null;\n    w?.();\n  };\n\n  // Never rejects: failures land in storageError for the drain loop to throw.\n  const discovery = (async () => {\n    let discoveryComplete = false;\n    try {\n      for await (const file of manager.streamStorageFiles(backup.id, {\n        signal,\n      })) {\n        queue.push(file);\n        filesTotal = (filesTotal ?? 0) + 1;\n        throttledTick();\n        notify();\n      }\n      discoveryComplete = true;\n    } catch (e) {\n      // The abort path is expected when the pipeline failed and we tore the\n      // discovery down.\n      if (!isAbortError(e)) {\n        storageError = e as Error;\n      }\n    } finally {\n      // A failed listing keeps the total unknown rather than reading as an\n      // empty-but-complete storage phase.\n      if (discoveryComplete && filesTotal == null) filesTotal = 0;\n      storageDone = true;\n      tick();\n      notify();\n    }\n  })();\n\n  // Entry write order is significant for restore: config.json first, then the\n  // entities/*.jsonl shards, then files/<locationId>. In particular ALL entity\n  // files must be written before ANY storage file. listFiles returns the\n  // entity files in write order; this generator yields them to completion,\n  // then drains the storage queue.\n  type ArchiveEntry = {\n    name: string;\n    input: ReadableStream<Uint8Array>;\n    // Fired after the writer finishes consuming the entry, so completion\n    // counters reflect fully-written files rather than started fetches.\n    onAdded: () => void;\n  };\n  const entries = (async function* (): AsyncGenerator<ArchiveEntry> {\n    const files = await manager.listFiles(backup.id, { signal });\n    if (files.length === 0) {\n      throw new Error('No files found for this backup.');\n    }\n    // We write entries in the order the server returns them, and restore\n    // requires config.json to be the first entry. Fail loudly rather than\n    // build a zip that can't be restored.\n    if (files[0].name !== 'config.json') {\n      throw new Error(\n        `Backup files came back in an unexpected order (expected config.json first, got \"${files[0].name}\").`,\n      );\n    }\n    // config.json isn't a namespace — count only the entities/*.jsonl shards.\n    entitiesTotal = files.filter((f) => f.name !== 'config.json').length;\n    tick();\n\n    for (const f of files) {\n      currentEntity = f.name;\n      tick();\n      const url = await manager.getFileUrl(backup.id, f.name, { signal });\n      let body: ReadableStream<Uint8Array>;\n      try {\n        body = await fetchBody(url, signal);\n      } catch (e) {\n        if (isAbortError(e)) throw e;\n        throw new Error(`Failed to fetch ${f.name}: ${errorMessage(e)}.`);\n      }\n      yield {\n        name: f.name,\n        input: countBytes(body),\n        onAdded: () => {\n          if (f.name !== 'config.json') entitiesCompleted++;\n          tick();\n        },\n      };\n    }\n    currentEntity = '';\n    tick();\n\n    while (true) {\n      if (storageError) throw storageError;\n      // A caller abort while no fetch is in flight surfaces only in the\n      // discovery stream, which swallows it as expected teardown — check\n      // explicitly so a cancellation can't read as a complete storage phase\n      // with files still undiscovered.\n      signal.throwIfAborted();\n      let file: AppBackupStorageFile | undefined;\n      if (queueHead < queue.length) {\n        file = queue[queueHead];\n        queue[queueHead] = undefined;\n        queueHead++;\n      }\n      if (file) {\n        const label = file.path || file.locationId;\n        currentFile = label;\n        tick();\n        let body: ReadableStream<Uint8Array>;\n        try {\n          body = await fetchBody(file.url, signal);\n        } catch (e) {\n          if (isAbortError(e)) throw e;\n          throw new Error(\n            `Couldn't download storage file \"${label}\" (${errorMessage(e)}).`,\n          );\n        }\n        yield {\n          name: `files/${file.locationId}`,\n          input: countBytes(body),\n          onAdded: () => {\n            filesCompleted++;\n            tick();\n          },\n        };\n      } else if (storageDone) {\n        break;\n      } else {\n        await new Promise<void>((resolve) => {\n          waitResolve = resolve;\n        });\n      }\n    }\n    currentFile = '';\n    tick();\n\n    if (storageError) throw storageError;\n  })();\n\n  const sinkWriter = opts.sink.getWriter();\n  try {\n    // Sink the archive encoder writes into: it tallies the encoded size for\n    // progress, then forwards to the caller's sink. Awaiting the downstream\n    // write propagates backpressure up into the encoder, so a fast source\n    // can't outrun the sink and balloon memory.\n    const countingSink = new WritableStream<Uint8Array>({\n      async write(chunk) {\n        zipBytes += chunk.byteLength;\n        throttledTick();\n        await sinkWriter.write(chunk);\n      },\n      async close() {\n        await sinkWriter.close();\n        tick();\n      },\n      async abort(reason) {\n        await sinkWriter.abort(reason);\n      },\n    });\n\n    const writer = await createWriter(countingSink, signal);\n    for await (const entry of entries) {\n      await writer.add(entry.name, entry.input, {\n        lastModDate: backup.backupAt,\n      });\n      entry.onAdded();\n    }\n    // A caller abort that lands after the last entry lets the generator\n    // finish cleanly; don't close and return a complete-looking archive.\n    signal.throwIfAborted();\n    await writer.close();\n    await discovery;\n    tick();\n    return { entities: entitiesCompleted, files: filesCompleted, zipBytes };\n  } catch (e) {\n    // Tear down the discovery stream and any in-flight body fetches so we\n    // don't keep pulling from S3, and abort the caller's sink so it can\n    // discard whatever it wrote.\n    abortController.abort();\n    await sinkWriter.abort(e).catch(() => {});\n    throw e;\n  }\n}\n"]}

package/dist/commonjs/backups.d.ts

@@ -0,0 +1,146 @@
+import type { WithAuth } from '@instantdb/webhooks';
+import { type BackupDownloadResult, type DownloadBackupArchiveOpts } from './backupDownload.ts';
+/** A point-in-time snapshot of an app. */
+export type AppBackup = {
+    /** Unique identifier for the backup. */
+    id: string;
+    /** Instant sequence number the snapshot was taken at. */
+    isn: string;
+    /** When the snapshot was taken. */
+    backupAt: Date;
+    /** Total size in bytes of the app's storage files at backup time, if known. */
+    filesSize: number | null;
+    /** Size in bytes of the app's database at backup time, if known. */
+    dbSize: number | null;
+    /**
+     * Total uncompressed size in bytes of the backup's entity files (what they
+     * take up unpacked on disk), if known.
+     */
+    uncompressedSize: number | null;
+    /** Human-readable label, e.g. "Automated Daily Snapshot". */
+    description: string | null;
+    /** When the backup stops being available for download. */
+    expiresAt: Date | null;
+};
+/**
+ * A file that makes up the backup payload: `config.json` or an
+ * `entities/<etype>.jsonl` shard.
+ */
+export type AppBackupFile = {
+    name: string;
+    /** Size in bytes as stored (the entity shards are stored compressed). */
+    size: number;
+};
+/** A storage file captured in a backup, with a presigned download URL. */
+export type AppBackupStorageFile = {
+    /**
+     * Stable id of the file's blob. A backup archive stores the blob at
+     * `files/<locationId>`.
+     */
+    locationId: string;
+    /** The path the user uploaded the file to. */
+    path: string | null;
+    /** Presigned URL for the file's contents. Expires after 12 hours. */
+    url: string;
+};
+type AppBackupResponse = {
+    id: string;
+    isn: string;
+    backup_at: string;
+    files_size: number | null;
+    db_size: number | null;
+    uncompressed_size: number | null;
+    description: string | null;
+    expires_at: string | null;
+};
+/** Converts a backup row as the server sends it into an {@link AppBackup}. */
+export declare function toAppBackup(row: AppBackupResponse): AppBackup;
+/** Suggested filename for a backup archive. */
+export declare function backupZipName(backup: AppBackup): string;
+/**
+ * Formats a byte count the way macOS/Finder reports file sizes: decimal
+ * (1000-based) units with SI labels, so the number lines up with what lands
+ * on disk.
+ */
+export declare function formatFileSize(n: number): string;
+/**
+ * Estimated size range for a backup's zip archive, or null when the backup
+ * row carries no sizes. Upper bound: everything stored uncompressed (STORE
+ * mode and/or files that don't compress). Lower bound: everything compressed
+ * at a ~4x DEFLATE ratio, best case for text/JSON, but storage files vary
+ * wildly (raw text compresses well, already-compressed images/videos don't).
+ * The same divisor applies to both since the file types aren't visible from
+ * here; the actual zip lands somewhere inside the range.
+ */
+export declare function estimateZipSize(backup: AppBackup): {
+    min: number;
+    max: number;
+} | null;
+/**
+ * Read-only API for an app's backups.
+ *
+ * A backup archive has a canonical entry order that restore relies on:
+ * `config.json` first, then every `entities/<etype>.jsonl` shard, then the
+ * `files/<locationId>` storage blobs. In particular ALL entity files must
+ * come before ANY storage file, so a restore can process the archive in a
+ * single streaming pass: `config.json` sets up the schema, the `$files`
+ * entities register file metadata, and only then can each blob be matched
+ * to its entity. {@link downloadArchive} implements that order end to end;
+ * {@link listFiles} (which returns the entity files already in write order)
+ * and {@link streamStorageFiles} are the pieces for building a custom
+ * pipeline.
+ */
+export declare class BackupsManager {
+    #private;
+    constructor(opts: {
+        appId: string;
+        apiURI: string;
+        withAuth: WithAuth;
+    });
+    /**
+     * Returns the app's downloadable (non-expired) backups, newest first.
+     */
+    list(opts?: {
+        signal?: AbortSignal;
+    }): Promise<AppBackup[]>;
+    /**
+     * Returns the backup's entity files (`config.json` and the
+     * `entities/<etype>.jsonl` shards) in archive write order. Storage blobs
+     * are not included; discover those with {@link streamStorageFiles}.
+     */
+    listFiles(backupId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<AppBackupFile[]>;
+    /**
+     * Returns a presigned download URL for one of the backup's entity files.
+     * The URL expires after 1 hour, so fetch it right before downloading.
+     *
+     * The entity files are stored zstd-compressed (the response carries
+     * `Content-Encoding: zstd`); decompress to get the raw JSON/JSONL.
+     */
+    getFileUrl(backupId: string, name: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    /**
+     * Streams every storage file captured in the backup, each with a presigned
+     * download URL. Completes without yielding anything when the app has no
+     * storage files.
+     *
+     * The server ends a healthy stream with a terminal sentinel; if the stream
+     * closes without it (a server-side failure truncated the listing), this
+     * throws instead of silently under-reporting files.
+     */
+    streamStorageFiles(backupId: string, opts?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<AppBackupStorageFile, void, void>;
+    /**
+     * Downloads the backup into a single zip archive written to `opts.sink`,
+     * entries in the canonical restore order described above. The caller
+     * supplies the runtime-specific pieces — how to fetch a presigned URL,
+     * where the bytes go, and the archive encoder (e.g. zip.js's `ZipWriter`);
+     * see {@link DownloadBackupArchiveOpts}.
+     */
+    downloadArchive(opts: DownloadBackupArchiveOpts): Promise<BackupDownloadResult>;
+}
+export {};
+//# sourceMappingURL=backups.d.ts.map

package/dist/commonjs/backups.d.ts.map

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