@drakkar.software/starfish-client 3.0.0-alpha.2 → 3.0.0-alpha.21

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.
@@ -36,20 +55,55 @@ export interface PullOptions {
     /** Include the sibling `_keyring` document in the response. Defaults to false. */
     withKeyring?: 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>[]>;
+}
 /**
  * Low-level HTTP client for the Starfish sync protocol.
  * Handles auth headers and response parsing.
  */
 export declare class StarfishClient {
     private readonly baseUrl;
+    private readonly namespace?;
     private readonly capProvider?;
     private readonly fetch;
+    private readonly cache?;
+    private readonly cacheMaxAgeMs?;
     /**
      * 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 +117,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 +140,78 @@ 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[]>;
+    /**
+     * 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}.
+     *
+     * Note: not append/checkpoint-aware — for incremental append-only reads use
+     * `pull(path, { since })` (or `AppendLogCursor`) per collection.
+     */
+    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[]>;
     /**
      * 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,8 +226,10 @@ 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;

package/dist/config.d.ts

@@ -9,6 +9,15 @@ export interface AppendOnlyClientInfo {
     /** false = no storage write (replaces queueOnly). true/absent = append to array. */
     persist?: boolean;
 }
+/** Append-only configuration exposed via GET /config. */
+export interface AppendOnlyClientInfo {
+    /** Array field name in the stored document. Defaults to "items". */
+    field?: string;
+    /** false = no storage write (replaces queueOnly). true/absent = append to array. */
+    persist?: boolean;
+    /** When true, server validates client's baseHash against hash(lastItem). */
+    checkLastItem?: boolean;
+}
 /** Per-collection metadata returned by GET /config. */
 export interface CollectionClientInfo {
     name: string;

package/dist/index.d.ts

@@ -4,14 +4,16 @@ export { stableStringify, computeHash } from "@drakkar.software/starfish-protoco
 export { buildRevocationList, revocationListCanonicalSigningInput } from "@drakkar.software/starfish-protocol";
 export type { RevocationList, RevocationEntry, RevokedSubject, BuildRevocationListOpts, } from "@drakkar.software/starfish-protocol";
 export type { PullResult, PushSuccess, PullKeyringProjection } from "@drakkar.software/starfish-protocol";
-export { StarfishClient } from "./client.js";
-export type { BlobPullResult, BlobPushResult, AppendPullOptions, PullOptions } from "./client.js";
+export { StarfishClient, pullWasFromCache } from "./client.js";
+export type { BlobPullResult, BlobPushResult, AppendPullOptions, PullOptions, BatchPullOptions, BatchPullResult, BatchPullEntry, } from "./client.js";
 export { SyncManager, AbortError } from "./sync.js";
 export type { SyncManagerOptions, SyncSigner } from "./sync.js";
+export { AppendLogCursor, AppendAuthorError, checkpointOf } from "./append-log.js";
+export type { AppendLogCursorOptions, AppendElement, AuthorVerifier, ElementErrorPolicy } from "./append-log.js";
 export { ENCRYPTED_KEY } from "@drakkar.software/starfish-protocol";
 export type { Encryptor } from "@drakkar.software/starfish-protocol";
 export { ConflictError, StarfishHttpError, } from "./types.js";
-export type { StarfishClientOptions, StarfishCapProvider, ConflictResolver, ClientPlugin, } from "./types.js";
+export type { StarfishClientOptions, StarfishCapProvider, PullCache, ConflictResolver, ClientPlugin, } from "./types.js";
 export { consoleSyncLogger, noopSyncLogger, createMetricsCollector } from "./logger.js";
 export type { SyncLogger, SyncMetrics, MetricsCollector } from "./logger.js";
 export { createMigrator } from "./migrate.js";
@@ -27,6 +29,8 @@ export type { Snapshot, SnapshotHistoryOptions } from "./history.js";
 export { startPolling, startAdaptivePolling } from "./polling.js";
 export type { PollableState, AdaptivePollingOptions, AdaptivePollingControls } from "./polling.js";
 export { createDedupFetch } from "./dedup.js";
+export { mutateDoc } from "./mutate.js";
+export type { DocState, DocMutator, MutateDocOptions } from "./mutate.js";
 export { fetchServerConfig } from "./config.js";
 export type { EncryptionMode, CollectionClientInfo, ConfigResponse } from "./config.js";
 export { createIndexedDBStorage } from "./storage/indexeddb.js";
@@ -40,8 +44,8 @@ export type { ServiceWorkerOptions } from "./service-worker.js";
 export { createSuspenseResource } from "./bindings/suspense.js";
 export { createDebouncedSync, createDebouncedPush } from "./debounced-sync.js";
 export type { DebouncedSyncOptions, DebouncedSync, DebouncedPushOptions, DebouncedPush } from "./debounced-sync.js";
-export { createMobileLifecycle } from "./mobile-lifecycle.js";
-export type { AppStateModule, NetInfoModule, MobileLifecycleDeps, MobileLifecycleOptions } from "./mobile-lifecycle.js";
+export { createMobileLifecycle, createAppendLogMobileLifecycle } from "./mobile-lifecycle.js";
+export type { AppStateModule, NetInfoModule, MobileLifecycleDeps, MobileLifecycleOptions, AppendLogLifecycleOptions } from "./mobile-lifecycle.js";
 export { createMultiStoreSync } from "./multi-store.js";
 export type { StoreSlice, BackupDocument, MultiStoreMigrationFn, MultiStoreSyncOptions, MultiStoreSync, } from "./multi-store.js";
 export type { AppendOnlyClientInfo } from "./config.js";