@loams/client 0.1.0 → 0.1.2

package/dist/runtime/consistency.js

@@ -1,68 +1,234 @@
-// Consistency tokens (design §44 §7.4, D609; runtime contract R4).
+// Consistency tokens (design §44 §7.4, D609; runtime contract R4 as amended
+// by SDKP §2.1).
 //
-// A write answers with a `consistency_token`; a read accepts one, so a caller
-// that just wrote can read its own write. Threading those by hand is the
-// caller's job today. The session store is the alternative §44 §7.4 asks for:
-// off by default, and when a call opts in, every response's token is merged
-// into the session and attached to later reads.
+// A write answers with a token; a read accepts one, so a caller that just
+// wrote can read its own write. The encoding is the server's
+// (`crates/loams-collection/src/token.rs`):
 //
-// **The token's encoding is not in the protos yet.** §05 §5 defines the
-// semantics (offsets per stream and partition, `STRONG` as the default,
-// `EVENTUAL`, `AT_LEAST{token}`) and API1's write paths carry it as an opaque
-// `v1:` string; §44 §7.4 says it merges by "max offset per stream and
-// partition", which needs the encoding to be parsed. Until that lands this
-// store keeps the token it was given, refuses to merge two different tokens
-// into a wrong one, and says so — a silently-wrong consistency token reads
-// stale data, which is worse than an error.
-import { LoamsError } from './errors.js';
+//   v1:s<stream>/p<partition>@<offset>,s<stream>/p<partition>@<offset>,…
+//
+// Each item is "the next offset after the write" for one `(stream, partition)`.
+// Merging two tokens keeps, per pair, the larger offset: a read held to the
+// merge waits for both writes. Every number is canonical decimal (no sign, no
+// leading zeros), so a token has exactly one spelling, and a malformed token is
+// `invalid_argument` here, before any network call.
+//
+// The session store is off by default. With `sessionConsistency: true` every
+// token a response carries is merged into it, and every read whose request has
+// a `consistency` field is sent `at_least = session` when the caller left the
+// field unset.
+//
+// Offsets are `bigint`: an offset is a `u64` on the server, and a `number`
+// silently rounds above 2^53, which would make a read wait for the wrong
+// position.
 import { Code } from '@connectrpc/connect';
+import { InvalidArgumentError } from './errors.js';
 /** The prefix every token carries (§44 §7.4). */
 export const TOKEN_PREFIX = 'v1:';
-/** Whether a string looks like a consistency token. */
+/** Whether a string looks like a consistency token (the prefix only). */
 export function isConsistencyToken(value) {
-    return value.startsWith(TOKEN_PREFIX) && value.length > TOKEN_PREFIX.length;
+    return value.startsWith(TOKEN_PREFIX);
+}
+const U32_MAX = 0xffffffffn;
+const U64_MAX = 0xffffffffffffffffn;
+/** A decimal `u64` with no sign and no leading zeros (except `"0"`). */
+function canonical(text, max) {
+    if (text === '' || !/^[0-9]+$/.test(text) || (text.length > 1 && text.startsWith('0'))) {
+        return undefined;
+    }
+    const value = BigInt(text);
+    return value <= max ? value : undefined;
+}
+/** `s<stream>/p<partition>@<offset>`. */
+function parseItem(item) {
+    const match = /^s([^/]*)\/p([^@]*)@(.*)$/.exec(item);
+    if (match === null) {
+        return undefined;
+    }
+    const stream = canonical(match[1], U64_MAX);
+    const partition = canonical(match[2], U32_MAX);
+    const offset = canonical(match[3], U64_MAX);
+    if (stream === undefined || partition === undefined || offset === undefined) {
+        return undefined;
+    }
+    return { stream, partition: Number(partition), offset };
+}
+function compare(a, b) {
+    if (a.stream !== b.stream) {
+        return a.stream < b.stream ? -1 : 1;
+    }
+    if (a.partition !== b.partition) {
+        return a.partition - b.partition;
+    }
+    if (a.offset !== b.offset) {
+        return a.offset < b.offset ? -1 : 1;
+    }
+    return 0;
 }
 /**
- * A session's consistency token.
+ * A parsed consistency token: `parse`, `toString`, `merge`, `equals`.
  *
- * Merging is deliberately conservative while the encoding is opaque: the store
- * keeps what it has, and a second, different token is a conflict the caller has
- * to resolve, not something to merge blindly.
+ * Immutable. `merge` returns a new token, normalised (sorted by stream and
+ * partition, one item per pair, the max offset kept), which is exactly what
+ * `ConsistencyToken::merge` on the server produces, so the two print the same.
+ */
+export class ConsistencyToken {
+    positions;
+    constructor(positions) {
+        this.positions = positions;
+    }
+    /** The token that names nothing: `v1:`. */
+    static empty() {
+        return new ConsistencyToken([]);
+    }
+    /** A token from its items, in the order given. */
+    static of(positions) {
+        return new ConsistencyToken([...positions]);
+    }
+    /** Parses the text form, or throws `InvalidArgumentError`. The items are
+     * kept in the order given, as the server's parser keeps them. */
+    static parse(text) {
+        const invalid = () => new InvalidArgumentError(`invalid consistency token ${JSON.stringify(text)}`, {
+            code: Code.InvalidArgument,
+            reason: 'invalid_consistency_token',
+            metadata: { field: 'consistency_token' },
+        });
+        if (!text.startsWith(TOKEN_PREFIX)) {
+            throw invalid();
+        }
+        const body = text.slice(TOKEN_PREFIX.length);
+        if (body === '') {
+            return ConsistencyToken.empty();
+        }
+        const positions = [];
+        for (const item of body.split(',')) {
+            const position = parseItem(item);
+            if (position === undefined) {
+                throw invalid();
+            }
+            positions.push(position);
+        }
+        return new ConsistencyToken(positions);
+    }
+    /** Whether `text` parses. */
+    static isValid(text) {
+        try {
+            ConsistencyToken.parse(text);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Sorted by `(stream, partition)`, one item per pair, the max offset kept. */
+    normalized() {
+        const sorted = [...this.positions].sort(compare);
+        const items = [];
+        for (const item of sorted) {
+            const last = items[items.length - 1];
+            if (last !== undefined && last.stream === item.stream && last.partition === item.partition) {
+                items[items.length - 1] = item;
+            }
+            else {
+                items.push(item);
+            }
+        }
+        return new ConsistencyToken(items);
+    }
+    /** Both tokens' offsets; a pair both name keeps the larger. Normalised. */
+    merge(other) {
+        const right = typeof other === 'string' ? ConsistencyToken.parse(other) : other;
+        return new ConsistencyToken([...this.positions, ...right.positions]).normalized();
+    }
+    /** The offset for `(stream, partition)`, the max if listed twice. */
+    offset(stream, partition) {
+        const s = BigInt(stream);
+        let found;
+        for (const item of this.positions) {
+            if (item.stream === s && item.partition === partition) {
+                found = found === undefined || item.offset > found ? item.offset : found;
+            }
+        }
+        return found;
+    }
+    /** Whether the two tokens name the same positions (after normalising). */
+    equals(other) {
+        const right = typeof other === 'string' ? ConsistencyToken.parse(other) : other;
+        return this.normalized().toString() === right.normalized().toString();
+    }
+    /** Whether the token names nothing. */
+    get isEmpty() {
+        return this.positions.length === 0;
+    }
+    /** The text form, `v1:` plus the items joined by `,`, in this token's order. */
+    toString() {
+        return (TOKEN_PREFIX +
+            this.positions
+                .map((item) => `s${item.stream}/p${item.partition}@${item.offset}`)
+                .join(','));
+    }
+    toJSON() {
+        return this.toString();
+    }
+}
+/**
+ * A session's consistency tokens: every token a response carried, merged, kept
+ * **per proto package** (R4, SDKP-17).
+ *
+ * A Graph read refuses a token naming another package's stream, so a
+ * collection write's token must never become a graph read's `at_least`: the
+ * session holds one merged token per scope, and the call path passes the
+ * call's package as the scope. A caller using the store directly may leave the
+ * scope out, which is one shared scope.
+ *
+ * `record` folds a token in; `current` is the scope's merge, as text. A token
+ * that does not parse is counted in `rejected` and otherwise ignored: the write
+ * that answered with it has already happened, and turning a committed write
+ * into a thrown error invites a caller to retry it.
  */
 export class ConsistencySession {
-    #token;
-    /** How many times two different tokens met. Surfaced so the limitation is
-     * visible rather than silent. */
-    #conflicts = 0;
-    /** The token to attach to the next read. */
-    current() {
-        return this.#token;
-    }
-    /** Folds a token the server returned in. */
-    record(token) {
+    #tokens = new Map();
+    #rejected = 0;
+    /** The token to attach to the next read in `scope`, or undefined. */
+    current(scope = '') {
+        return this.#tokens.get(scope)?.toString();
+    }
+    /** The merged token of `scope`, parsed. */
+    token(scope = '') {
+        return this.#tokens.get(scope);
+    }
+    /** The scopes the session holds a token for. */
+    scopes() {
+        return [...this.#tokens.keys()];
+    }
+    /** Folds a token the server returned, in `scope`, in. Throws
+     * `InvalidArgumentError` on a malformed token, after counting it. */
+    record(token, scope = '') {
         if (token === undefined || token === '') {
             return;
         }
-        if (!isConsistencyToken(token)) {
-            this.#conflicts += 1;
-            throw new LoamsError(`not a consistency token: ${token}`, { code: Code.Internal });
+        let parsed;
+        try {
+            parsed = typeof token === 'string' ? ConsistencyToken.parse(token) : token;
         }
-        if (this.#token === undefined || this.#token === token) {
-            this.#token = token;
-            return;
+        catch (error) {
+            this.#rejected += 1;
+            throw error;
         }
-        this.#conflicts += 1;
-        throw new LoamsError('two different consistency tokens met and the encoding cannot merge them yet; ' +
-            'the session keeps the first. Merging by stream and partition offset arrives with ' +
-            'the write paths that carry offsets (§44 §7.4, D609).', { code: Code.FailedPrecondition });
+        const held = this.#tokens.get(scope);
+        this.#tokens.set(scope, held === undefined ? parsed.normalized() : held.merge(parsed));
+    }
+    /** How many tokens the session could not parse. */
+    get rejected() {
+        return this.#rejected;
     }
-    /** How many unmergeable pairs the session has seen. */
+    /** @deprecated The old name of `rejected`, from before tokens merged. */
     get conflicts() {
-        return this.#conflicts;
+        return this.#rejected;
     }
-    /** Forgets the token, so the next read is not held to it. */
+    /** Forgets every token, so the next read is not held to one. */
     clear() {
-        this.#token = undefined;
-        this.#conflicts = 0;
+        this.#tokens.clear();
+        this.#rejected = 0;
     }
 }

package/dist/runtime/errors.d.ts

@@ -1,5 +1,13 @@
 import { Code, ConnectError } from '@connectrpc/connect';
 import { type Reason } from '../gen/facade.js';
+/**
+ * Reasons the SDK raises itself, without a server answer (SDKP §2.1, R12 and
+ * R13). They are registered in `docs/api/reasons.md` as client-side, and are
+ * kept here as well so the SDK does not depend on when that registry lands.
+ */
+export declare const CLIENT_REASONS: readonly ["client_deadline_exceeded", "batch_partially_applied"];
+/** A reason the SDK raises itself. */
+export type ClientReason = (typeof CLIENT_REASONS)[number];
 /** What every Loams failure carries. */
 export declare class LoamsError extends Error {
     /** The Connect code, the canonical classification. */
@@ -7,7 +15,7 @@ export declare class LoamsError extends Error {
     /** The stable cause, when the server sent an `ErrorInfo`. Undefined means
      * the failure came from below the API (a socket, a timeout, a CORS
      * rejection), not from a Loams service. */
-    readonly reason: Reason | undefined;
+    readonly reason: Reason | ClientReason | undefined;
     /** Structured context the server sent. Never secrets. */
     readonly metadata: Readonly<Record<string, string>>;
     /** A short next step in the caller's locale, when the server sent one. */
@@ -19,7 +27,7 @@ export declare class LoamsError extends Error {
     readonly unknownReason: string | undefined;
     constructor(message: string, init: {
         code: Code;
-        reason?: Reason;
+        reason?: Reason | ClientReason;
         unknownReason?: string;
         metadata?: Record<string, string>;
         hint?: string;
@@ -69,6 +77,25 @@ export declare class FeatureNotInVariantError extends UnimplementedError {
         variant?: string;
     });
 }
+/**
+ * A `documents.writeBatch` that stopped at a failed chunk (runtime contract
+ * R13). The chunks before it are applied and stay applied; `token` is their
+ * merged consistency token, so a caller can read what did land, and `cause` is
+ * the failed chunk's own error.
+ */
+export declare class BatchError extends LoamsError {
+    /** How many chunks were applied before the failure. */
+    readonly chunksApplied: number;
+    /** How many documents those chunks carried. */
+    readonly rowsApplied: number;
+    /** The merged token of the applied chunks, if any carried one. */
+    readonly token: string | undefined;
+    constructor(message: string, init: ConstructorParameters<typeof LoamsError>[1] & {
+        chunksApplied: number;
+        rowsApplied: number;
+        token?: string;
+    });
+}
 /** A token the server rejected as expired: `unauthenticated` with reason
  * `token_expired`. The runtime refreshes once and retries once (D608, R1). */
 export declare class TokenExpiredError extends UnauthenticatedError {

package/dist/runtime/errors.js

@@ -13,6 +13,12 @@ import { REASONS } from '../gen/facade.js';
  * union does not have is a server newer than this SDK, and is surfaced rather
  * than dropped. */
 const KNOWN_REASONS = new Set(REASONS);
+/**
+ * Reasons the SDK raises itself, without a server answer (SDKP §2.1, R12 and
+ * R13). They are registered in `docs/api/reasons.md` as client-side, and are
+ * kept here as well so the SDK does not depend on when that registry lands.
+ */
+export const CLIENT_REASONS = ['client_deadline_exceeded', 'batch_partially_applied'];
 /** What every Loams failure carries. */
 export class LoamsError extends Error {
     /** The Connect code, the canonical classification. */
@@ -84,6 +90,26 @@ export class FeatureNotInVariantError extends UnimplementedError {
         this.variant = init.variant;
     }
 }
+/**
+ * A `documents.writeBatch` that stopped at a failed chunk (runtime contract
+ * R13). The chunks before it are applied and stay applied; `token` is their
+ * merged consistency token, so a caller can read what did land, and `cause` is
+ * the failed chunk's own error.
+ */
+export class BatchError extends LoamsError {
+    /** How many chunks were applied before the failure. */
+    chunksApplied;
+    /** How many documents those chunks carried. */
+    rowsApplied;
+    /** The merged token of the applied chunks, if any carried one. */
+    token;
+    constructor(message, init) {
+        super(message, init);
+        this.chunksApplied = init.chunksApplied;
+        this.rowsApplied = init.rowsApplied;
+        this.token = init.token;
+    }
+}
 /** A token the server rejected as expired: `unauthenticated` with reason
  * `token_expired`. The runtime refreshes once and retries once (D608, R1). */
 export class TokenExpiredError extends UnauthenticatedError {

package/dist/runtime/machine-key.d.ts

@@ -0,0 +1,33 @@
+import type { TokenSource } from './token-source.js';
+/** How long an assertion is valid, in seconds. */
+export declare const MACHINE_KEY_ASSERTION_TTL_S = 300;
+/** How long before expiry a token is traded again, in seconds. */
+export declare const MACHINE_KEY_REFRESH_EARLY_S = 60;
+/** The RFC 7523 grant type. */
+export declare const JWT_BEARER_GRANT = "urn:ietf:params:oauth:grant-type:jwt-bearer";
+/** A machine user's key file, as the identity provider hands it out. */
+export interface MachineKeyFile {
+    type?: string;
+    keyId: string;
+    key: string;
+    userId: string;
+}
+export interface MachineKeyOptions {
+    /** The key file's JSON text, or the parsed file. */
+    keyFile: string | MachineKeyFile;
+    /** The identity provider's issuer URL (`https://auth.loams.dev`). */
+    issuer: string;
+    /** The Loams project's id at the identity provider: the audience Loams checks. */
+    project: string;
+    /** Injected for tests and for hosts with their own `fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** The clock, in milliseconds (tests). */
+    now?: () => number;
+}
+/**
+ * An agent's token source from its machine key (module header). The key is checked when the
+ * source is built; it is imported into WebCrypto on first use.
+ */
+export declare function machineKey(options: MachineKeyOptions): TokenSource & {
+    readonly userId: string;
+};

package/dist/runtime/machine-key.js

@@ -0,0 +1,174 @@
+// An agent's token from its identity provider's private-key JWT key (design 76 §10, D1607;
+// plan IA1, IA4 Task 2).
+//
+// An agent is a machine user at the identity provider (Zitadel). Its key file is the JSON the
+// provider hands out once (`{"type": "serviceaccount", "keyId", "key", "userId"}`). The source
+// signs an RFC 7523 assertion (RS256, `kid` = `keyId`, `iss` = `sub` = `userId`, `aud` = the
+// issuer, valid for 5 minutes) with WebCrypto, trades it at `<issuer>/oauth/v2/token` for an
+// access token whose audience is the Loams project
+// (`urn:zitadel:iam:org:project:id:<project>:aud`), caches it, and trades again a minute
+// before it expires or when the server answers `token_expired`. Concurrent callers share one
+// trade. The private key never leaves the process. A sandboxed agent holds no key: agentd
+// vends it a 15-minute token file instead (D1618).
+/** How long an assertion is valid, in seconds. */
+export const MACHINE_KEY_ASSERTION_TTL_S = 300;
+/** How long before expiry a token is traded again, in seconds. */
+export const MACHINE_KEY_REFRESH_EARLY_S = 60;
+/** The RFC 7523 grant type. */
+export const JWT_BEARER_GRANT = 'urn:ietf:params:oauth:grant-type:jwt-bearer';
+const b64url = (bytes) => {
+    let text = '';
+    for (const b of bytes) {
+        text += String.fromCharCode(b);
+    }
+    return btoa(text).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/u, '');
+};
+const utf8 = (text) => Uint8Array.from(new TextEncoder().encode(text));
+function derLength(n) {
+    if (n < 0x80) {
+        return Uint8Array.of(n);
+    }
+    const out = [];
+    for (let v = n; v > 0; v >>= 8) {
+        out.unshift(v & 0xff);
+    }
+    return Uint8Array.of(0x80 | out.length, ...out);
+}
+function der(tag, ...parts) {
+    const body = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const p of parts) {
+        body.set(p, at);
+        at += p.length;
+    }
+    const length = derLength(body.length);
+    const out = new Uint8Array(1 + length.length + body.length);
+    out[0] = tag;
+    out.set(length, 1);
+    out.set(body, 1 + length.length);
+    return out;
+}
+/** PKCS #1 `RSAPrivateKey` wrapped as PKCS #8, which is what WebCrypto imports. */
+function pkcs1ToPkcs8(pkcs1) {
+    const version = Uint8Array.of(0x02, 0x01, 0x00);
+    // rsaEncryption (1.2.840.113549.1.1.1) with NULL parameters.
+    const algorithm = Uint8Array.of(0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x01, 0x05, 0x00);
+    return der(0x30, version, algorithm, der(0x04, pkcs1));
+}
+function pemToPkcs8(pem) {
+    const match = /-----BEGIN (RSA )?PRIVATE KEY-----([\s\S]+?)-----END (RSA )?PRIVATE KEY-----/u.exec(pem);
+    if (match === null) {
+        throw new Error('machineKey: the key is not a PEM private key');
+    }
+    const bytes = Uint8Array.from(atob((match[2] ?? '').replace(/\s+/gu, '')), (c) => c.charCodeAt(0));
+    return match[1] === undefined ? bytes : pkcs1ToPkcs8(bytes);
+}
+function parseKeyFile(keyFile) {
+    let file;
+    if (typeof keyFile === 'string') {
+        try {
+            file = JSON.parse(keyFile);
+        }
+        catch {
+            throw new Error('machineKey: not a machine key file');
+        }
+    }
+    else {
+        file = keyFile;
+    }
+    if (file.type !== undefined && file.type !== '' && file.type !== 'serviceaccount') {
+        throw new Error(`machineKey: a ${JSON.stringify(file.type)} key is not a machine user's key`);
+    }
+    if (!file.keyId || !file.userId || !file.key) {
+        throw new Error('machineKey: the key file has no keyId, key or userId');
+    }
+    return file;
+}
+/**
+ * An agent's token source from its machine key (module header). The key is checked when the
+ * source is built; it is imported into WebCrypto on first use.
+ */
+export function machineKey(options) {
+    const file = parseKeyFile(options.keyFile);
+    const issuer = options.issuer.replace(/\/+$/u, '');
+    if (!/^https?:\/\/[^/]+/u.test(issuer)) {
+        throw new Error(`machineKey: the issuer ${JSON.stringify(issuer)} is not a URL`);
+    }
+    if (options.project === '') {
+        throw new Error('machineKey: the Loams project id (the audience) is empty');
+    }
+    const pkcs8 = pemToPkcs8(file.key);
+    const scope = `openid urn:zitadel:iam:org:project:id:${options.project}:aud`;
+    const doFetch = options.fetch ?? globalThis.fetch;
+    const now = options.now ?? Date.now;
+    let signingKey;
+    let cached;
+    let inFlight;
+    const assertion = async (issuedAtMs) => {
+        signingKey ??= globalThis.crypto.subtle.importKey('pkcs8', pkcs8, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['sign']);
+        const iat = Math.floor(issuedAtMs / 1000);
+        const header = b64url(utf8(JSON.stringify({ alg: 'RS256', typ: 'JWT', kid: file.keyId })));
+        const claims = b64url(utf8(JSON.stringify({
+            iss: file.userId,
+            sub: file.userId,
+            aud: issuer,
+            iat,
+            exp: iat + MACHINE_KEY_ASSERTION_TTL_S,
+        })));
+        const signing = `${header}.${claims}`;
+        const signature = await globalThis.crypto.subtle.sign('RSASSA-PKCS1-v1_5', await signingKey, utf8(signing));
+        return `${signing}.${b64url(new Uint8Array(signature))}`;
+    };
+    const trade = () => {
+        inFlight ??= (async () => {
+            const started = now();
+            const response = await doFetch(`${issuer}/oauth/v2/token`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/x-www-form-urlencoded' },
+                body: new URLSearchParams({
+                    grant_type: JWT_BEARER_GRANT,
+                    scope,
+                    assertion: await assertion(started),
+                }).toString(),
+            });
+            if (!response.ok) {
+                const text = (await response.text()).slice(0, 512);
+                throw new Error(`the token endpoint refused the machine key (${response.status}): ${text}`);
+            }
+            const body = (await response.json());
+            if (!body.access_token) {
+                throw new Error('the token endpoint answered no access_token');
+            }
+            const life = body.expires_in ?? 900;
+            const early = Math.min(MACHINE_KEY_REFRESH_EARLY_S, life / 2);
+            cached = { token: body.access_token, refreshAt: started + (life - early) * 1000 };
+            return body.access_token;
+        })()
+            .catch((error) => {
+            cached = undefined;
+            throw error;
+        })
+            .finally(() => {
+            inFlight = undefined;
+        });
+        return inFlight;
+    };
+    return {
+        userId: file.userId,
+        token: async () => {
+            if (cached !== undefined && now() < cached.refreshAt) {
+                return cached.token;
+            }
+            try {
+                return await trade();
+            }
+            catch {
+                // A failed trade sends no credential; `refresh()` reports the reason.
+                return undefined;
+            }
+        },
+        refresh: async () => {
+            await trade();
+        },
+    };
+}

package/dist/runtime/pagination.js

@@ -25,13 +25,15 @@ export async function* paginate(binding, fetch, request, options = {}) {
             ...request,
             ...(pageToken === undefined ? {} : { [pageTokenField]: pageToken }),
         }, options));
-        const items = page[pagination.items];
+        // The binding spells the field as the proto does (`service_accounts`);
+        // a decoded message has it in TypeScript case (`serviceAccounts`).
+        const items = page[pagination.items] ?? page[camelCase(pagination.items)];
         if (Array.isArray(items)) {
             for (const item of items) {
                 yield item;
             }
         }
-        const next = page[pagination.nextPageToken];
+        const next = page[pagination.nextPageToken] ?? page[camelCase(pagination.nextPageToken)];
         if (typeof next !== 'string' || next === '') {
             return;
         }
@@ -45,3 +47,7 @@ export function pageFields(binding) {
     }
     return { pageSizeField: 'pageSize', pageTokenField: 'pageToken' };
 }
+/** `snake_case` to `lowerCamelCase`, as protobuf-es names a field. */
+function camelCase(name) {
+    return name.replace(/_([a-z0-9])/g, (_match, letter) => letter.toUpperCase());
+}

package/dist/runtime/subscribe.d.ts

@@ -0,0 +1,37 @@
+/** The first and the largest pause after an empty fetch. */
+export declare const SUBSCRIBE_MIN_BACKOFF_MS = 100;
+export declare const SUBSCRIBE_MAX_BACKOFF_MS = 1000;
+/** Where a subscription starts and how much each fetch asks for. */
+export interface SubscribeRequest {
+    namespace?: string;
+    stream: string;
+    partition?: number;
+    /** The first offset to read; default 0. */
+    fromOffset?: bigint | number;
+    maxRecords?: number;
+    maxBytes?: number;
+    /** A server long poll per fetch, when the server offers it (P0c). */
+    maxWaitMs?: number;
+}
+/** One record, as far as the loop needs to know it. */
+export interface OffsetRecord {
+    readonly offset: bigint | number | string;
+}
+/** One `Fetch`. */
+export type RecordFetcher<R extends OffsetRecord> = (request: Record<string, unknown>, options?: {
+    signal?: AbortSignal;
+}) => Promise<{
+    records?: readonly R[];
+} | undefined>;
+/** A running subscription: an async iterable that knows where it is. */
+export interface Subscription<R> extends AsyncIterableIterator<R> {
+    /** The next offset to read. */
+    readonly offset: bigint;
+    /** Stops the loop; the same as `return()`. */
+    cancel(): void;
+}
+/** Starts a subscription over `fetch`. Nothing is sent until the first
+ * `next()`. */
+export declare function subscribe<R extends OffsetRecord>(fetch: RecordFetcher<R>, request: SubscribeRequest, options?: {
+    signal?: AbortSignal;
+}): Subscription<R>;