@north-light/sdk 0.0.0 → 0.3.415

package/dist/resources/runs.js

@@ -0,0 +1,228 @@
+import { sleepWithin } from '@north-light/api';
+import { APIError, mapError } from '../errors.js';
+import { RunStream } from './run-stream.js';
+import { RunReply } from './run-reply.js';
+import { resolveJsonSchema } from '../schema.js';
+import { deadline, heldReadOptions } from './request.js';
+export class Runs {
+    request;
+    openEvents;
+    questions;
+    constructor(request, openEvents, questions) {
+        this.request = request;
+        this.openEvents = openEvents;
+        this.questions = questions;
+    }
+    async start(params, options = {}) {
+        const { idempotencyKey = crypto.randomUUID(), maxRetries = 2, ...rest } = options;
+        const body = params.output_schema === undefined ? params : { ...params, output_schema: resolveJsonSchema(params.output_schema) };
+        return this.keyedSend('/v1/runs', body, idempotencyKey, maxRetries, rest);
+    }
+    get(runId, options = {}) {
+        const { wait, ...rest } = options;
+        return this.request('GET', `${runPath(runId)}${query({ wait })}`, undefined, heldReadOptions(wait, rest));
+    }
+    list(filters = {}, options) {
+        return this.request('GET', `/v1/runs${query(filters)}`, undefined, options);
+    }
+    /** Every run across pages, most recently active first: `for await (const run of runs.listAll())`. Fetches
+     *  the next page (`limit` per page) only as you iterate; `break` stops fetching. */
+    async *listAll(filters = {}, options) {
+        for (let after;;) {
+            const page = await this.list({ ...filters, ...(after === undefined ? {} : { after }) }, options);
+            yield* page.runs;
+            if (!page.next)
+                return;
+            after = page.next;
+        }
+    }
+    /** Send a message to a run. `start_turn: true` (the default) answers it in its
+     *  own turn: a running run receives it when its current turn ends, and a
+     *  message sent before the first turn has started queues behind that turn,
+     *  because a run's `runs.start` prompt is always its first turn's input.
+     *  `start_turn: false` stores it without starting a turn; it is delivered as
+     *  context at the start of the next turn, ahead of that turn's input. For a
+     *  new run that is the first turn only if it is stored before the run claims
+     *  its first turn's messages; to guarantee it, pass `message` to `runs.start`.
+     *
+     *  The send carries an `Idempotency-Key`: `idempotencyKey` when given, otherwise a UUID generated for this
+     *  call and reused on every retry of it. The daemon keeps the key for 24 hours; a repeat with the same key
+     *  and the same message returns the first send's result without delivering again, and the same key with a
+     *  different message or `start_turn` throws `ConflictError` `idempotency_conflict`. To make a send safe
+     *  across your own restarts, derive the key from your own record of the send (a batch or row id). */
+    async message(runId, message, options = {}) {
+        const { idempotencyKey = crypto.randomUUID(), maxRetries = 2, start_turn, ...rest } = options;
+        const body = { message, ...(start_turn === undefined ? {} : { start_turn }) };
+        // One key per logical send, reused on every retry: the daemon answers a repeat with the first send's
+        // result, so a retry after a lost response cannot deliver the message twice.
+        return this.keyedSend(`${runPath(runId)}/messages`, body, idempotencyKey, maxRetries, rest);
+    }
+    /** A keyed POST under one overall deadline. `budgetMs` / `deadlineAt` (fixed here, once) bound every attempt, every
+     *  backoff and every `retry_after_s` wait together, so the call never outlasts its deadline: an application lease
+     *  taken for the call needs only to exceed that deadline. A server `retry_after_s` is honored only when it fits the
+     *  time left; otherwise the call rejects at once with `DeadlineExceededError` (`reason: 'retry_after'`), carrying
+     *  the refusal as `cause`, rather than sleeping past the deadline. A send without a deadline keeps the capped
+     *  backoff and honors any `retry_after_s`. */
+    async keyedSend(path, body, idempotencyKey, maxRetries, rest) {
+        const options = deadline(rest) ?? rest;
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await this.request('POST', path, body, { ...options, maxRetries: 0, headers: { ...options.headers, 'Idempotency-Key': idempotencyKey } });
+            }
+            catch (error) {
+                if (attempt >= maxRetries || !(error instanceof APIError) || !retryableSend(error))
+                    throw error;
+                // The server's wait is honored only against a deadline (sleepWithin refuses a wait longer than the time
+                // left); with none, the plain backoff applies and a Retry-After is waited as before.
+                const waitS = error.retryAfterS;
+                try {
+                    if (options.deadlineAt === undefined)
+                        await pause(waitS ? waitS * 1_000 : 500 * 2 ** attempt, options.signal);
+                    else
+                        await sleepWithin(500 * 2 ** attempt, { deadlineAt: options.deadlineAt, signal: options.signal }, waitS, error);
+                }
+                catch (stop) {
+                    // An abort during the wait rejects with the signal's own reason, as `pause` does.
+                    if (options.signal?.aborted)
+                        throw options.signal.reason;
+                    throw stop instanceof APIError ? mapError(stop) : stop;
+                }
+            }
+        }
+    }
+    interrupt(runId, options = {}) {
+        const { children, ...rest } = options;
+        return this.request('POST', `${runPath(runId)}/interrupt`, children === undefined ? {} : { children }, rest);
+    }
+    cancel(runId, options = {}) {
+        const { keepSchedules, ...rest } = options;
+        return this.request('POST', `${runPath(runId)}/cancel`, keepSchedules === undefined ? {} : { keep_schedules: keepSchedules }, rest);
+    }
+    /** Delete the run, running or not: the runtime stops its turns and sandboxes itself, so there is no need to
+     *  `cancel` first. Deleting a run that is already gone throws `NotFoundError` (404).
+     *  `uploads_pending` counts the run's released uploads storage has not yet confirmed deleted; the runtime retries those. */
+    delete(runId, options) {
+        return this.request('DELETE', runPath(runId), undefined, options);
+    }
+    /** Rename the caller's own run. The name is trimmed, must not be empty, and is at most 200 characters. */
+    rename(runId, name, options) {
+        return this.request('POST', `${runPath(runId)}/rename`, { name }, options);
+    }
+    trace(runId, options = {}) {
+        const { format, ...rest } = options;
+        return this.request('GET', `${runPath(runId)}/trace${query({ format })}`, undefined, rest);
+    }
+    events(runId, options = {}) {
+        return new RunStream((after, signal) => this.openEvents(runId, after, signal), options.after, options.signal, options.onReconnect);
+    }
+    /** Follow the reply to one message: `sent` is what `runs.message` returned, or `runs.start`'s `message`. Reads the run's events after
+     *  `sent.sequence_number`, keeps the root's, starts at the turn that delivers the message and ends after that
+     *  turn's `turn.completed` (or the run's settlement). Several messages delivered in one turn share that turn's reply.
+     *  An expired cursor throws `stream_gap`. */
+    reply(runId, sent, options = {}) {
+        if (sent.run_id !== runId)
+            throw new TypeError('sent belongs to a different run');
+        return new RunReply((after) => this.events(runId, { after, signal: options.signal }), sent);
+    }
+    stream(params, options = {}) {
+        const controller = new AbortController();
+        options.signal?.addEventListener('abort', () => controller.abort(), { once: true });
+        const started = this.start(params, options);
+        return new RunStream(async (after, signal) => {
+            const run = await started;
+            return this.openEvents(run.run_id, after, signal);
+        }, 0, controller.signal);
+    }
+    /** Long-polls `runs.get` until the run is `settled`, `waiting_on_user`, or `idle`, and returns that response
+     *  unchanged (`result` is not parsed). Aborting `signal` rejects with its reason and leaves the run as it is. */
+    async wait(runId, options = {}) {
+        // One deadline for the whole wait: every poll shares it instead of restarting `budgetMs`.
+        const bounded = deadline(options) ?? options;
+        return abortable(bounded.signal, async () => {
+            for (;;) {
+                const result = await this.get(runId, { ...bounded, wait: 25 });
+                if (result.status === 'settled' || result.status === 'waiting_on_user' || result.status === 'idle')
+                    return result;
+            }
+        });
+    }
+    /** Start a run with `output_schema` and wait for it to settle; resolves with the outcome and `output_parsed`
+     *  typed to the schema. `onQuestion` answers each open question once; without it, a question rejects with
+     *  `APIError` code `waiting_on_user`. A run that stops without settling rejects `run_idle` (untouched:
+     *  send `runs.message` or `runs.cancel`). Aborting `signal` rejects with its reason; the run is never canceled. */
+    async parse(params, options = {}) {
+        const { onQuestion, idempotencyKey, ...unbounded } = options;
+        // One deadline for the start, every poll and every answer.
+        const rest = deadline(unbounded) ?? unbounded;
+        return abortable(rest.signal, () => this.parseRun(params, onQuestion, idempotencyKey, rest));
+    }
+    async parseRun(params, onQuestion, idempotencyKey, rest) {
+        const run = await this.start(params, { ...rest, ...(idempotencyKey === undefined ? {} : { idempotencyKey }) });
+        const answered = new Set();
+        for (;;) {
+            const current = await this.wait(run.run_id, rest);
+            if (current.status === 'settled' && current.outcome) {
+                const outcome = current.outcome;
+                if (outcome.kind === 'result')
+                    return { ...outcome, output_parsed: current.result };
+                return { ...outcome, output_parsed: null };
+            }
+            if (current.status === 'idle') {
+                throw new APIError(0, 'run_idle', 'the run stopped without settling; send runs.message or runs.cancel', undefined, undefined, { retryable: false, run_id: run.run_id });
+            }
+            const open = current.pending_question_ids.filter((id) => !answered.has(id));
+            if (!onQuestion) {
+                const questionId = open[0] ?? current.pending_question_ids[0];
+                throw new APIError(0, 'waiting_on_user', 'the run is waiting on a question and no onQuestion was given', undefined, undefined, { retryable: false, run_id: run.run_id, ...(questionId === undefined ? {} : { question_id: questionId }) });
+            }
+            if (!this.questions)
+                throw new TypeError('runs.parse needs the client questions resource to answer a question');
+            for (const id of open) {
+                const question = await this.questions.get(id, rest);
+                const responses = await onQuestion(question);
+                answered.add(id);
+                await this.questions.answer(id, responses, rest);
+            }
+            // Every listed question already answered: the run has not moved on yet, so poll again after a pause.
+            if (open.length === 0)
+                await pause(500, rest.signal);
+        }
+    }
+}
+/** A keyed send is safe to repeat after a refusal the daemon marked retryable or a transport failure. */
+function retryableSend(error) {
+    return error.retryable === true || error.code === 'transport_error' || error.code === 'daemon_request_interrupted' || error.code === 'connection_error' || error.code === 'request_timeout';
+}
+function runPath(id) {
+    if (!/^[A-Za-z0-9_-]+$/.test(id))
+        throw new TypeError('Invalid run id');
+    return `/v1/runs/${encodeURIComponent(id)}`;
+}
+function query(fields) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(fields))
+        if (value !== undefined)
+            params.set(key, String(value));
+    return params.size ? `?${params}` : '';
+}
+/** SDK-RUN-27: an aborted helper rejects with the signal's own reason, whatever the in-flight request raised. */
+async function abortable(signal, run) {
+    if (signal?.aborted)
+        throw signal.reason;
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw signal.reason;
+        throw error;
+    }
+}
+async function pause(ms, signal) {
+    if (signal?.aborted)
+        throw signal.reason;
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => { clearTimeout(timer); reject(signal.reason); }, { once: true });
+    });
+}

package/dist/resources/shares.d.ts

@@ -0,0 +1,40 @@
+import type { RequestOptions } from '../types.js';
+import type { Request } from './request.js';
+/** `shares.create` input. */
+export interface ShareCreateParams {
+    /** Absolute path of a file the caller may read. Without `crtr:files:share`, only files in the caller's own app space. */
+    path: string;
+    /** ISO 8601 time in the future; absent or null keeps the share until it is deleted. */
+    expires_at?: string | null;
+}
+/** A newly created share: a frozen copy of the file at a public URL. */
+export interface ShareCreated {
+    share_id: string;
+    url: string;
+    expires_at: string | null;
+}
+/** A share the caller created. */
+export interface Share {
+    share_id: string;
+    url: string;
+    source_path: string;
+    created_by: string;
+    created_at: string;
+    expires_at: string | null;
+    status: 'on' | 'off';
+}
+/** Public share links (app listener only). List and delete act on the caller's own shares. */
+export declare class Shares {
+    private readonly request;
+    constructor(request: Request);
+    /** Never retried: a retry could create a second share. */
+    create(params: ShareCreateParams, options?: RequestOptions): Promise<ShareCreated>;
+    list(options?: RequestOptions): Promise<{
+        shares: Share[];
+    }>;
+    /** Turn a share off and delete its stored copy. */
+    delete(shareId: string, options?: RequestOptions): Promise<{
+        share_id: string;
+        status: 'off';
+    }>;
+}

package/dist/resources/shares.js

@@ -0,0 +1,19 @@
+import { pathSegment } from './identifiers.js';
+/** Public share links (app listener only). List and delete act on the caller's own shares. */
+export class Shares {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    /** Never retried: a retry could create a second share. */
+    create(params, options = {}) {
+        return this.request('POST', '/v1/shares', params, { ...options, maxRetries: 0 });
+    }
+    list(options) {
+        return this.request('GET', '/v1/shares', undefined, options);
+    }
+    /** Turn a share off and delete its stored copy. */
+    delete(shareId, options) {
+        return this.request('DELETE', `/v1/shares/${encodeURIComponent(pathSegment(shareId, 'share id'))}`, undefined, options);
+    }
+}

package/dist/resources/structured-requests.d.ts

@@ -0,0 +1,14 @@
+import type { CreateStructuredRequest, CreateStructuredRequestResponse, StructuredRequestDTO } from '@north-light/api';
+import type { RequestOptions } from '../types.js';
+import type { Request } from './request.js';
+/** Durable structured requests: a schema-bound question to a new or existing node, settled once. */
+export declare class StructuredRequests {
+    private readonly request;
+    constructor(request: Request);
+    create(body: CreateStructuredRequest, options?: RequestOptions): Promise<CreateStructuredRequestResponse>;
+    /** `wait` (0–25 seconds) long-polls until the request settles. */
+    retrieve(requestId: string, query?: {
+        wait?: number;
+    }, options?: RequestOptions): Promise<StructuredRequestDTO>;
+    cancel(requestId: string, options?: RequestOptions): Promise<StructuredRequestDTO>;
+}

package/dist/resources/structured-requests.js

@@ -0,0 +1,19 @@
+import { pathSegment } from './identifiers.js';
+import { withQuery } from './request.js';
+/** Durable structured requests: a schema-bound question to a new or existing node, settled once. */
+export class StructuredRequests {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    create(body, options) {
+        return this.request('POST', '/v1/structured-requests', body, options);
+    }
+    /** `wait` (0–25 seconds) long-polls until the request settles. */
+    retrieve(requestId, query, options) {
+        return this.request('GET', withQuery(`/v1/structured-requests/${pathSegment(requestId, 'request id')}`, query), undefined, options);
+    }
+    cancel(requestId, options) {
+        return this.request('POST', `/v1/structured-requests/${pathSegment(requestId, 'request id')}/cancel`, {}, options);
+    }
+}

package/dist/resources/uploads.d.ts

@@ -0,0 +1,27 @@
+import type { RequestOptions } from '../types.js';
+import type { Request } from './request.js';
+/** `uploads.create` input: the file the caller will PUT to `upload_link`. At most 100 MiB. */
+export interface UploadCreateParams {
+    /** File name, stored as the last segment of `url`. */
+    name: string;
+    /** The media type the bytes are PUT with. */
+    media_type: string;
+    /** Exact byte length, a non-negative integer. */
+    size: number;
+}
+/** A reserved upload. PUT the bytes to `upload_link` before `expires_at`, then put `url` in a run prompt or message. */
+export interface Upload {
+    upload_id: string;
+    /** The storage URL a run's prompt or message names; the runtime fetches it into the run's `attachments/`. */
+    url: string;
+    /** Signed PUT link for the bytes. */
+    upload_link: string;
+    expires_at: string;
+}
+/** Uploads to the runtime's storage (app listener only). */
+export declare class Uploads {
+    private readonly request;
+    constructor(request: Request);
+    /** Reserve an upload. Never retried: a retry would reserve a second upload. */
+    create(params: UploadCreateParams, options?: RequestOptions): Promise<Upload>;
+}

package/dist/resources/uploads.js

@@ -0,0 +1,11 @@
+/** Uploads to the runtime's storage (app listener only). */
+export class Uploads {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    /** Reserve an upload. Never retried: a retry would reserve a second upload. */
+    create(params, options = {}) {
+        return this.request('POST', '/v1/uploads', params, { ...options, maxRetries: 0 });
+    }
+}

package/dist/schema.d.ts

@@ -0,0 +1,7 @@
+import type { JsonSchema } from './types.js';
+/** Accept a plain JSON Schema object or anything with `toJSONSchema()` (a zod
+ *  v4 object satisfies this directly) and resolve it to the plain object the
+ *  wire format (`output_schema`, a JSON string) needs. */
+export declare function resolveJsonSchema(schema: JsonSchema | {
+    toJSONSchema(): JsonSchema;
+}): JsonSchema;

package/dist/schema.js

@@ -0,0 +1,10 @@
+/** Accept a plain JSON Schema object or anything with `toJSONSchema()` (a zod
+ *  v4 object satisfies this directly) and resolve it to the plain object the
+ *  wire format (`output_schema`, a JSON string) needs. */
+export function resolveJsonSchema(schema) {
+    const withMethod = schema;
+    if (typeof withMethod.toJSONSchema === 'function') {
+        return schema.toJSONSchema();
+    }
+    return schema;
+}

package/dist/stores/postgres.d.ts

@@ -0,0 +1,32 @@
+import type { Connection, ConnectionStore } from '../oauth/index.js';
+interface QueryResult {
+    rows: Record<string, unknown>[];
+}
+interface QueryClient {
+    query(sql: string, values?: unknown[]): Promise<QueryResult>;
+    release(): void;
+}
+export interface PostgresPool {
+    query(sql: string, values?: unknown[]): Promise<QueryResult>;
+    connect(): Promise<QueryClient>;
+}
+export interface PostgresConnectionStoreOptions {
+    /** Unquoted PostgreSQL identifier, optionally schema-qualified. Default: connection. */
+    table?: string;
+}
+/** A shared PostgreSQL connection store with a transaction-scoped, per-user advisory lock. */
+export declare class PostgresConnectionStore implements ConnectionStore {
+    private readonly pool;
+    private readonly transaction;
+    private readonly table;
+    constructor(pool: PostgresPool, options?: PostgresConnectionStoreOptions);
+    lock<T>(userId: string, fn: () => Promise<T>): Promise<T>;
+    load(userId: string): Promise<Connection | null>;
+    save(connection: Connection): Promise<void>;
+    /** Delete `userId`'s row only while it still holds `refreshToken`; answers whether one was deleted. Inside
+     *  `lock` it runs in that transaction, so it commits when the locked callback resolves. */
+    remove(userId: string, refreshToken: string): Promise<boolean>;
+    /** Connections not saved since `before`, oldest first. Save activity is not necessarily refresh activity. */
+    listStale(before: Date): Promise<Connection[]>;
+}
+export {};

package/dist/stores/postgres.js

@@ -0,0 +1,92 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+function tableName(name) {
+    const parts = name.split('.');
+    if (parts.length < 1 || parts.length > 2 || parts.some((part) => !/^[a-z_][a-z_0-9]*$/.test(part))) {
+        throw new TypeError('table must be a lowercase PostgreSQL identifier, optionally schema-qualified');
+    }
+    return parts.map((part) => `"${part}"`).join('.');
+}
+function toConnection(row) {
+    const expiry = row.access_token_expires_at;
+    if (!(expiry instanceof Date) || !Number.isFinite(expiry.getTime())) {
+        throw new TypeError('access_token_expires_at must be a PostgreSQL timestamptz (pg Date)');
+    }
+    return {
+        userId: row.user_id,
+        runtimeUrl: row.runtime_url,
+        refreshToken: row.refresh_token,
+        grantId: row.grant_id,
+        accessToken: row.access_token,
+        accessTokenExpiresAt: expiry.getTime(),
+        ...(row.id_token == null ? {} : { idToken: row.id_token }),
+    };
+}
+/** A shared PostgreSQL connection store with a transaction-scoped, per-user advisory lock. */
+export class PostgresConnectionStore {
+    pool;
+    transaction = new AsyncLocalStorage();
+    table;
+    constructor(pool, options = {}) {
+        this.pool = pool;
+        this.table = tableName(options.table ?? 'connection');
+    }
+    async lock(userId, fn) {
+        const current = this.transaction.getStore();
+        if (current) {
+            await current.query('SELECT pg_advisory_xact_lock(hashtextextended($1, 0))', [userId]);
+            return fn();
+        }
+        const db = await this.pool.connect();
+        let begun = false;
+        try {
+            await db.query('BEGIN');
+            begun = true;
+            await db.query('SELECT pg_advisory_xact_lock(hashtextextended($1, 0))', [userId]);
+            const result = await this.transaction.run(db, fn);
+            await db.query('COMMIT');
+            begun = false;
+            return result;
+        }
+        catch (error) {
+            if (begun) {
+                try {
+                    await db.query('ROLLBACK');
+                }
+                catch { /* Preserve the original failure. */ }
+            }
+            throw error;
+        }
+        finally {
+            db.release();
+        }
+    }
+    async load(userId) {
+        const result = await (this.transaction.getStore() ?? this.pool).query(`SELECT user_id, runtime_url, refresh_token, grant_id, access_token, access_token_expires_at, id_token FROM ${this.table} WHERE user_id = $1`, [userId]);
+        return result.rows[0] ? toConnection(result.rows[0]) : null;
+    }
+    async save(connection) {
+        const expiry = new Date(connection.accessTokenExpiresAt);
+        if (!Number.isFinite(expiry.getTime()))
+            throw new TypeError('accessTokenExpiresAt must be a valid timestamp');
+        await (this.transaction.getStore() ?? this.pool).query(`INSERT INTO ${this.table} (user_id, runtime_url, refresh_token, grant_id, access_token, access_token_expires_at, id_token, updated_at)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, clock_timestamp())
+       ON CONFLICT (user_id) DO UPDATE SET runtime_url = EXCLUDED.runtime_url, refresh_token = EXCLUDED.refresh_token,
+         grant_id = EXCLUDED.grant_id, access_token = EXCLUDED.access_token,
+         access_token_expires_at = EXCLUDED.access_token_expires_at, id_token = EXCLUDED.id_token, updated_at = clock_timestamp()`, [connection.userId, connection.runtimeUrl, connection.refreshToken, connection.grantId,
+            connection.accessToken, expiry, connection.idToken ?? null]);
+    }
+    /** Delete `userId`'s row only while it still holds `refreshToken`; answers whether one was deleted. Inside
+     *  `lock` it runs in that transaction, so it commits when the locked callback resolves. */
+    async remove(userId, refreshToken) {
+        const result = await (this.transaction.getStore() ?? this.pool).query(`DELETE FROM ${this.table} WHERE user_id = $1 AND refresh_token = $2 RETURNING user_id`, [userId, refreshToken]);
+        return result.rows.length > 0;
+    }
+    /** Connections not saved since `before`, oldest first. Save activity is not necessarily refresh activity. */
+    async listStale(before) {
+        if (!Number.isFinite(before.getTime()))
+            throw new TypeError('before must be a valid Date');
+        const result = await (this.transaction.getStore() ?? this.pool).query(`SELECT user_id, runtime_url, refresh_token, grant_id, access_token, access_token_expires_at, id_token
+       FROM ${this.table} WHERE updated_at < $1 ORDER BY updated_at ASC, user_id ASC`, [before]);
+        return result.rows.map(toConnection);
+    }
+}

package/dist/testing/clock.d.ts

@@ -0,0 +1,7 @@
+/** A clock a test steps by hand: `now()` returns the same instant until `advance(ms)` moves it. */
+export interface ManualClock {
+    now(): number;
+    advance(ms: number): void;
+}
+/** A `ManualClock` starting at `startMs` (default 2026-01-01T00:00:00Z). Pass it to `FakeCloud` as `clock`. */
+export declare function manualClock(startMs?: number): ManualClock;

package/dist/testing/clock.js

@@ -0,0 +1,12 @@
+/** A `ManualClock` starting at `startMs` (default 2026-01-01T00:00:00Z). Pass it to `FakeCloud` as `clock`. */
+export function manualClock(startMs = Date.UTC(2026, 0, 1)) {
+    let current = startMs;
+    return {
+        now: () => current,
+        advance(ms) {
+            if (!Number.isFinite(ms) || ms < 0)
+                throw new RangeError(`advance needs a non-negative number of ms, got ${ms}`);
+            current += ms;
+        },
+    };
+}