@drakkar.software/starfish-client 3.0.0-alpha.4 → 3.0.0-alpha.40

package/dist/client.d.ts

@@ -1,5 +1,17 @@
 import type { PullResult, PushSuccess } from "@drakkar.software/starfish-protocol";
+import { type AppendAuthor } from "@drakkar.software/starfish-protocol";
 import type { StarfishClientOptions } from "./types.js";
+/**
+ * Whether a {@link PullResult} was served from the offline read-through cache
+ * (the transport was unreachable) rather than a live server response. Used by
+ * {@link SyncManager} to surface a `stale` flag to the UI without treating a
+ * cache hit as proof the server is reachable.
+ */
+export declare function pullWasFromCache(result: PullResult): boolean;
+/** The storage `documentKey` for a push `path`: the path with the `/push/`
+ *  action prefix stripped (the namespace lives only in the URL). The author
+ *  signature binds to this key. */
+export declare function stripPushPrefix(path: string): string;
 /** Result of pulling a binary blob from the server. */
 export interface BlobPullResult {
     data: ArrayBuffer;
@@ -19,6 +31,13 @@ export interface AppendPullOptions {
     since?: number;
     /** Return only the last K items (applied after `since` filter). Sent as `?last=`. */
     last?: number;
+    /** Return only the last K items. Alias of `last`; sent as `?limit=`. When both
+     *  are given, `limit` wins. */
+    limit?: number;
+    /** Explicitly fetch the whole collection (sent as `?full=true`). Mutually
+     *  exclusive with `since`/`limit`/`last` — the server requires a pull to declare
+     *  exactly one of {checkpoint, limit/last, full}. */
+    full?: boolean;
 }
 /**
  * Options for a structured (non-append) pull.
@@ -35,6 +54,66 @@ export interface PullOptions {
     checkpoint?: number;
     /** Include the sibling `_keyring` document in the response. Defaults to false. */
     withKeyring?: boolean;
+    /**
+     * Serve the last-synced cached snapshot immediately (tagged via
+     * {@link pullWasFromCache}) and revalidate in the background. Requires a
+     * {@link StarfishClientOptions.cache} to be configured; without one the option
+     * is a no-op and the pull goes to the network as usual.
+     *
+     * On a cache hit: returns the stale snapshot at once, kicks a background fetch,
+     * and on success writes the fresh snapshot to cache and fires
+     * {@link StarfishClientOptions.onRevalidated}. Uses the same dedup set as the
+     * {@link StarfishClientOptions.cacheFallbackStatuses} revalidation path — a
+     * concurrent error-triggered loop for the same document is not duplicated.
+     *
+     * On a cache miss: falls through to the normal network-first pull unchanged.
+     */
+    staleWhileRevalidate?: boolean;
+}
+/** Per-collection result in a {@link BatchPullResult}: either the pulled
+ *  document (`data`/`hash`/`timestamp`) or a per-collection `error` string. */
+export interface BatchPullEntry {
+    data?: unknown;
+    hash?: string;
+    timestamp?: number;
+    error?: string;
+}
+/** Response of {@link StarfishClient.batchPull}: a map of requested collection
+ *  name → an ARRAY of {@link BatchPullEntry}, one per requested param-set, in
+ *  request order. A collection read with no params yields a one-element array. */
+export interface BatchPullResult {
+    collections: Record<string, BatchPullEntry[]>;
+}
+/** Options for {@link StarfishClient.batchPull}. */
+export interface BatchPullOptions {
+    /** Per-collection path params: collection name → an ARRAY of param-sets, one
+     *  per document to read from that collection, e.g.
+     *  `{ profile: [{ identity: "a" }, { identity: "b" }] }` reads two profiles in
+     *  one round-trip. Serialized to a URL-encoded JSON `params` query. The
+     *  `{identity}` param is auto-filled by the server from the authenticated
+     *  caller when a set omits it, so a single self-doc read can pass `[{}]` — or
+     *  omit the collection from `params` entirely (an unlisted collection reads one
+     *  auto-filled doc). Results come back under the same name in request order. */
+    params?: Record<string, Record<string, string>[]>;
+    /**
+     * Per-collection append options, index-aligned to `params`. Makes the batch
+     * request **append/checkpoint-aware**: each entry returns the bounded tail of
+     * that collection's append-only log rather than the full document.
+     *
+     * Serialized as URL-encoded JSON alongside `params`. Server ignores it for
+     * collections that are not append-only (returns `{ error: "append_params_not_supported" }`
+     * for those entries). `full` is disallowed in batch (`full_not_allowed` per entry).
+     *
+     * Example — read the last 5 events for two rooms and the newest item for a third:
+     * ```ts
+     * await client.batchPull(["events"], {
+     *   params: { events: [{ room: "a" }, { room: "b" }, { room: "c" }] },
+     *   appendParams: { events: [{ last: 5 }, { last: 5 }, { last: 1 }] },
+     * })
+     * ```
+     * Each `data[appendField]` in the result is the filtered array for that entry.
+     */
+    appendParams?: Record<string, AppendPullOptions[]>;
 }
 /**
  * Low-level HTTP client for the Starfish sync protocol.
@@ -42,14 +121,32 @@ export interface PullOptions {
  */
 export declare class StarfishClient {
     private readonly baseUrl;
+    private readonly namespace?;
     private readonly capProvider?;
     private readonly fetch;
+    private readonly cache?;
+    private readonly cacheMaxAgeMs?;
+    private readonly cacheFallbackStatuses?;
+    private readonly onRevalidated?;
+    private readonly revalidating;
+    /**
+     * In-memory mirror of the latest document timestamp written to each cache
+     * key via {@link writeCache}. Updated synchronously so {@link revalidateLoop}
+     * can guard against stale overwrites without an extra async cache read.
+     */
+    private readonly latestCacheTimestamp;
     /**
      * Installed client-side plugins. Currently stored as inert data; no
      * hooks fire yet. Extensions can inspect this list if needed.
      */
     readonly plugins: ReadonlyArray<import("./types.js").ClientPlugin>;
     constructor(options: StarfishClientOptions);
+    /**
+     * Mark a `PullResult` as having been served from the offline read-through
+     * cache (transport was unreachable). Non-enumerable so it doesn't leak into
+     * JSON / equality / re-caching; read via {@link pullWasFromCache}.
+     */
+    private tagFromCache;
     /**
      * Resolve the host portion of the URL the client will send to. The host
      * is folded into the signed canonical input as the `h` field so the
@@ -63,6 +160,18 @@ export declare class StarfishClient {
      * empty-host case still verifies symmetrically when both sides agree.
      */
     private signingHost;
+    /**
+     * Rewrite a request path for the configured namespace. A no-op when no
+     * namespace is set; otherwise `/{action}/…` becomes `/v1/{namespace}/{action}/…`
+     * (the `/v1` protocol-version segment is part of the namespaced route, matching
+     * the Python client and the server's namespace mount).
+     *
+     * Applied to the path used for BOTH the signature and the URL so the canonical
+     * path the client signs equals the path the server reconstructs from the URL.
+     * Covers SDK-helper-built paths too — that's the point: a namespace-unaware
+     * helper passing `/push/spaces/x/_keyring` reaches `/v1/{ns}/push/spaces/x/_keyring`.
+     */
+    private applyNamespace;
     /**
      * Build auth headers for a request. When a `capProvider` is set, signs the
      * request with the device's Ed25519 private key and returns the v3 header
@@ -74,23 +183,131 @@ export declare class StarfishClient {
      * The host bound into the signature is derived from `baseUrl` once per call.
      */
     private buildAuthHeaders;
+    /**
+     * Build the request-signing headers from an ALREADY-fetched cap context. Split
+     * out of {@link buildAuthHeaders} so {@link append} can fetch the cap once and
+     * reuse it for BOTH the author signature (over the element data) and the
+     * request signature (over the body), without redeeming the cap twice — a
+     * second `getCap()` could rotate keys and break the `authorPubkey ===
+     * presenter` bind the server checks.
+     */
+    private capRequestHeaders;
+    /**
+     * Resolve the author public key to attach to a signed append: the redeemer's
+     * `pubHex` for an audience cap, else the cert subject `cap.sub` for a
+     * device/member cap. This is the SAME key that signs the request, so a server
+     * enforcing author proof can bind the stored element to its writer. Returns
+     * undefined only for a (malformed) cap with neither — the append then goes
+     * unsigned and a server requiring signatures rejects it.
+     */
+    private appendAuthorKey;
     /** Pull synced data from the server. Returns the raw `PullResult`. */
     pull(path: string, checkpoint?: number): Promise<PullResult>;
     /** Pull synced data with structured options (e.g. `{withKeyring: true}`). */
     pull(path: string, options: PullOptions): Promise<PullResult>;
     /** Pull an append-only collection. Extracts and returns `data[appendField]` as `T[]`. */
     pull<T = unknown>(path: string, options: AppendPullOptions): Promise<T[]>;
+    /**
+     * Write a pull snapshot to the cache. Fire-and-forget; errors are swallowed
+     * so a failing cache never blocks the caller. No-op when no cache is configured.
+     */
+    private writeCache;
+    /** Build the URL + auth headers for one revalidation GET. Shared between
+     *  {@link pull} and {@link revalidateLoop} to avoid duplicated fetch setup. */
+    private revalidateFetch;
+    /**
+     * Deduplicated fire-and-forget: starts one revalidation loop per cacheKey.
+     * Used by both the {@link cacheFallbackStatuses} error path (delayed first
+     * attempt, honoring `Retry-After`) and the {@link PullOptions.staleWhileRevalidate}
+     * read path (`immediate: true` — no initial delay on the first attempt). The
+     * `revalidating` set deduplicates across both triggers so a concurrent
+     * error-triggered loop and an SWR-on-read loop for the same key collapse to one.
+     */
+    private scheduleRevalidate;
+    /**
+     * Background revalidation loop shared by both {@link cacheFallbackStatuses}
+     * hits and {@link PullOptions.staleWhileRevalidate} reads.
+     *
+     * Retries (honoring `Retry-After`) up to {@link MAX_REVALIDATE_ATTEMPTS} times.
+     * When `immediate` is true the first attempt fires without any initial delay
+     * (SWR-on-read path). On a live 2xx the fresh snapshot is written to cache and
+     * {@link onRevalidated} fires. Stops early on a non-fallback status (403/404).
+     */
+    private revalidateLoop;
+    /**
+     * Read the cached snapshot for a document `path` WITHOUT hitting the network —
+     * the basis for cache-first paint (seed the UI from the last-synced snapshot,
+     * then revalidate with a live {@link pull}). Returns the tagged `PullResult`,
+     * or null when no cache is configured / there's no entry. Namespacing matches
+     * {@link pull}, so the key lines up with whatever `pull` wrote.
+     */
+    peekCache(path: string): Promise<PullResult | null>;
+    /** Read + parse a cached pull snapshot, tagged {@link tagFromCache}. Returns
+     *  null on a miss or an unparseable blob (never throws — a corrupt cache entry
+     *  must not break a pull, just miss). */
+    private readCache;
+    /**
+     * Pull several documents in one round-trip via `/batch/pull`. `collections` is
+     * the list of distinct collection names; `opts.params` supplies, per collection,
+     * an ARRAY of path-param sets — one per document to read — so the SAME collection
+     * can fan in many documents (e.g. many users' `profile`) in a single request.
+     * The server auto-fills the `{identity}` param from the authenticated caller for
+     * any set that omits it, so a self-doc collection needs no params. Returns a map
+     * of collection name → an ARRAY of pulled documents (or per-document `{ error }`),
+     * in request order. Honors the configured namespace.
+     *
+     * For the common "many docs of one collection" case prefer {@link batchPullMany}.
+     *
+     * Pass `appendParams` per entry for append-only bounded-tail reads (see {@link batchPullManyAppend}).
+     */
+    batchPull(collections: string[], opts?: BatchPullOptions): Promise<BatchPullResult>;
+    /**
+     * Convenience over {@link batchPull} for reading MANY documents of ONE
+     * collection in a single round-trip: pass the per-document param-sets and get
+     * back the {@link BatchPullEntry} array aligned to `paramsList` by index (each
+     * entry is `{ data, hash, timestamp }` or `{ error }`). An empty `paramsList`
+     * issues no request and returns `[]`.
+     */
+    batchPullMany(collection: string, paramsList: Record<string, string>[]): Promise<BatchPullEntry[]>;
+    /**
+     * Convenience over {@link batchPull} for reading append-only bounded tails from
+     * MANY entries of ONE collection in a single round-trip.
+     *
+     * Each request in `requests` carries optional `params` (path params) and
+     * `options` (append bounds: `since`/`last`/`limit`/`appendField`). An empty
+     * `requests` issues no request and returns `[]`.
+     *
+     * Returns an array aligned to `requests` by index. Each element is either:
+     * - the filtered array `T[]` extracted from `entry.data[appendField]`, or
+     * - `{ error: string }` if the server returned a per-entry error.
+     *
+     * The `appendField` used for extraction defaults to `"items"` and can be
+     * overridden per request via `options.appendField`.
+     *
+     * The `appendField` option is client-side only (used for result extraction, not sent to the server).
+     * It must match the collection's server-configured append field and defaults to `"items"`.
+     *
+     * Note: `full: true` is not supported in batch and is rejected client-side
+     * before the request is sent.
+     */
+    batchPullManyAppend<T = unknown>(collection: string, requests: {
+        params?: Record<string, string>;
+        options: AppendPullOptions;
+    }[]): Promise<(T[] | {
+        error: string;
+    })[]>;
     /**
      * Push synced data to the server.
      * @param path - The push endpoint path (e.g. "/push/users/abc/settings")
      * @param data - The full document data to push
      * @param baseHash - Hash of the document this push is based on (null for first push)
      *
-     * v3 author fields (`authorPubkey` + `authorSignature`) live inside `data`
-     * and are produced by `SyncManager` when a `signer` is configured.
+     * v3 author proof (`authorPubkey` + `authorSignature`) is passed via `author`
+     * (produced by `SyncManager` when a `signer` is configured) and sent as
+     * top-level body siblings of `data`, where the server verifies it.
      * @throws {ConflictError} if the server detects a hash mismatch (409)
      */
-    push(path: string, data: Record<string, unknown>, baseHash: string | null): Promise<PushSuccess>;
+    push(path: string, data: Record<string, unknown>, baseHash: string | null, author?: AppendAuthor): Promise<PushSuccess>;
     /**
      * Append an element to an appendOnly (`by_timestamp`) collection.
      *
@@ -105,12 +322,44 @@ export declare class StarfishClient {
      * @param opts.ts - optional client-supplied element timestamp (ms). Must be a
      *   non-negative integer strictly greater than the latest stored element's ts
      *   (else the server responds 409). Omit to let the server assign one.
-     * @throws {StarfishHttpError} on a non-2xx response (e.g. 409 for a
-     *   non-monotonic timestamp).
+     * @throws {StarfishHttpError} on a non-2xx response — e.g. 409
+     *   `{ error: "non_monotonic_timestamp" }` for a non-monotonic timestamp, or
+     *   `{ error: "append_limit_exceeded", limit }` if the collection's `maxItems`
+     *   cap is reached (partition by a path parameter for higher volume).
      */
     append(path: string, data: Record<string, unknown>, opts?: {
         ts?: number;
     }): Promise<PushSuccess>;
+    /**
+     * Append one element to a **public-write** append-only collection with an
+     * Ed25519 author proof but **no cap `Authorization` header**.
+     *
+     * Unlike {@link append}, which always attaches a cap-signed `Authorization`
+     * header from the configured `capProvider`, this method signs only the
+     * append-author proof (binding the element to the writer's Ed25519 key) and
+     * sends the request without authentication headers. This is required for
+     * collections with `writeRoles: ["public"]` — the server's cap-scope check
+     * would reject a request carrying a cap whose scope does not cover the path.
+     *
+     * Typical use-case: writing a sealed invitation to another user's
+     * public-write inbox collection without needing a cap scoped to the
+     * recipient's namespace. The author proof is optional on the server side
+     * (`requireAuthorSignature: false` for a public inbox), but signing anyway
+     * binds the stored element to the sender's Ed25519 key for verification in
+     * the receive path.
+     *
+     * The element is sent as `{ data, authorPubkey, authorSignature }`.
+     *
+     * @param path    The push path, e.g. `/push/inbox/{userId}/{shard}`.
+     * @param element The JSON element to append.
+     * @param signer  The sender's Ed25519 keypair (signs the author proof).
+     *
+     * @throws {AppendHttpError} on a non-2xx response.
+     */
+    appendAnonymous(path: string, element: Record<string, unknown>, signer: {
+        edPubHex: string;
+        edPrivHex: string;
+    }): Promise<void>;
     /**
      * Pull binary data from a blob collection.
      * Returns raw bytes with the content hash from the ETag header.
@@ -121,4 +370,33 @@ export declare class StarfishClient {
      * Binary collections use last-write-wins (no conflict detection).
      */
     pushBlob(path: string, data: ArrayBuffer | Uint8Array | Blob, contentType: string): Promise<BlobPushResult>;
+    /**
+     * Push an Apache Parquet file to a Parquet collection.
+     *
+     * Thin wrapper over {@link pushBlob} that fixes `Content-Type` to
+     * `application/vnd.apache.parquet` so the S3 object is tagged correctly
+     * for DuckDB and CDN consumption.
+     *
+     * @example
+     * ```ts
+     * const parquetBytes = await generateParquet(rows)
+     * const result = await client.pushParquet("/push/analytics/alice/q1.parquet", parquetBytes)
+     * console.log("stored hash:", result.hash)
+     * ```
+     */
+    pushParquet(path: string, data: ArrayBuffer | Uint8Array | Blob): Promise<BlobPushResult>;
+    /**
+     * Pull an Apache Parquet file from a Parquet collection.
+     *
+     * Thin wrapper over {@link pullBlob} for API symmetry with
+     * {@link pushParquet}.
+     *
+     * @example
+     * ```ts
+     * const result = await client.pullParquet("/pull/analytics/alice/q1.parquet")
+     * // result.data        → ArrayBuffer
+     * // result.contentType → "application/vnd.apache.parquet"
+     * ```
+     */
+    pullParquet(path: string): Promise<BlobPullResult>;
 }