@drakkar.software/starfish-client 3.0.0-alpha.1 → 3.0.0-alpha.11

package/dist/client.d.ts

@@ -1,5 +1,10 @@
 import type { PullResult, PushSuccess } from "@drakkar.software/starfish-protocol";
+import { type AppendAuthor } from "@drakkar.software/starfish-protocol";
 import type { StarfishClientOptions } from "./types.js";
+/** 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;
@@ -36,12 +41,39 @@ 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;
     /**
@@ -63,6 +95,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 +118,88 @@ 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[]>;
+    /**
+     * 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.
+     *
+     * Unlike {@link push}, appendOnly writes carry no hash/conflict check — an
+     * authorized append is always accepted. Each element is stored server-side as
+     * `{ts, data}` and pulls can filter by `ts` via `since`/`checkpoint`.
+     *
+     * @param path - the push endpoint (e.g. "/push/events")
+     * @param data - the element payload. For a `delegated` collection, encrypt it
+     *   first (e.g. `createKeyringEncryptor(keyring, kem).encrypt(data)`); the
+     *   server stores it opaquely and never reads it.
+     * @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
+     *   `{ 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>;
     /**
      * Pull binary data from a blob collection.
      * Returns raw bytes with the content hash from the ETag header.

package/dist/config.d.ts

@@ -2,12 +2,12 @@
 export type EncryptionMode = "none" | "delegated";
 /** Append-only configuration exposed via GET /config. */
 export interface AppendOnlyClientInfo {
+    /** Append-only strategy. Only `"by_timestamp"` is currently supported. */
+    type: "by_timestamp";
     /** 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 {

package/dist/index.d.ts

@@ -5,9 +5,11 @@ export { buildRevocationList, revocationListCanonicalSigningInput } from "@drakk
 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 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";
@@ -40,8 +42,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";