@north-light/sdk 0.0.0 → 0.3.415

package/dist/oauth/keygen.js

@@ -0,0 +1,46 @@
+import { calculateJwkThumbprint, exportJWK, generateKeyPair as generateSigningKeyPair } from 'jose';
+import { CrouterError } from '../errors.js';
+/** Make an app signing key and the public JWK to register in the directory. */
+export async function generateKeyPair() {
+    const keys = await generateSigningKeyPair('ES256', { extractable: true });
+    const publicKey = await exportJWK(keys.publicKey);
+    const kid = await calculateJwkThumbprint(publicKey, 'sha256');
+    const properties = { kid, alg: 'ES256', use: 'sig' };
+    return {
+        privateJwk: { ...await exportJWK(keys.privateKey), ...properties },
+        publicJwk: { ...publicKey, ...properties },
+        kid,
+    };
+}
+const keygenHint = 'make one with: pnpm exec crouter-sdk keygen';
+/** Check that `value` (a JWK object or its JSON text) is a private signing key with a `kid`, and return it as
+ *  `OAuth2Options.privateKey` takes it. `source` names where it came from in the error, e.g. a file path. */
+export function parsePrivateJwk(value, source = 'The key') {
+    let key = value;
+    if (typeof value === 'string') {
+        try {
+            key = JSON.parse(value);
+        }
+        catch {
+            throw new CrouterError(`${source} is not JSON; it must hold a private JWK with a kid (${keygenHint}).`);
+        }
+    }
+    if (!key || typeof key !== 'object' || Array.isArray(key) || typeof key.d !== 'string' || !key.d
+        || typeof key.kid !== 'string' || !key.kid) {
+        throw new CrouterError(`${source} must hold a private JWK with a kid (${keygenHint}).`);
+    }
+    return key;
+}
+/** Read a private JWK file, such as the one `crouter-sdk keygen` writes, and check it as `parsePrivateJwk` does. Node only. */
+export async function privateKeyFromFile(path) {
+    const load = new Function('specifier', 'return import(specifier)');
+    const { readFile } = await load('node:fs/promises');
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        throw new CrouterError(`${path} could not be read (${error instanceof Error ? error.message : String(error)}); it must hold a private JWK with a kid (${keygenHint}).`);
+    }
+    return parsePrivateJwk(text, path);
+}

package/dist/oauth/refusal.d.ts

@@ -0,0 +1,32 @@
+import { APIError } from '../errors.js';
+/**
+ * What a refused refresh means for the app's data:
+ * - `removed` (`grant_removed`): the person removed the app or deleted their account. The runtime has
+ *   deleted the app's runs; delete what the app stores for them.
+ * - `paused` (`grant_suspended`): the grant is suspended or expired. Nothing was deleted; keep the
+ *   person's data and show the app paused until they sign in again.
+ * - `reconnect` (`refresh_token_expired`, `refresh_token_reused`, or `grant_revoked` with no reason given):
+ *   the grant still exists. Nothing was deleted; ask them to sign in again.
+ */
+export type RefusalKind = 'removed' | 'paused' | 'reconnect';
+export declare const isRefusalCode: (code: string) => boolean;
+/** A connection the directory refused to refresh: passed to `OAuth2Options.onRefusal`, and read from the
+ *  refused call's error with `refusalOf(error)`. The SDK removes the stored connection once the handler resolves. */
+export interface Refusal {
+    kind: RefusalKind;
+    /** The directory's code: `grant_removed`, `grant_suspended`, `refresh_token_expired`, `refresh_token_reused`, or `grant_revoked`. */
+    code: string;
+    /** The connection's crouter cloud user id (`user:<id>`). */
+    userId: string;
+    /** The grant the refused connection held. */
+    grantId: string;
+    /** The `AuthenticationError` (401, `origin: 'directory'`, `userAction: 'reconnect'`) the refusal raised. */
+    error: APIError;
+}
+export declare function refusalKindOf(code: string): RefusalKind | null;
+export declare function attachRefusal(error: APIError, refusal: Refusal): void;
+/** The `Refusal` a call failed with when the directory refused its connection's refresh, else `null`. Read it to
+ *  answer one request (show "sign in again"); act on the connection itself in `OAuth2Options.onRefusal`, which the
+ *  SDK has already run. Only an error raised by `OAuth2Client` refreshing a stored connection carries one; a 429,
+ *  `cap_exhausted`, `scope_missing`, or a runtime-origin `grant_revoked` does not. */
+export declare function refusalOf(error: unknown): Refusal | null;

package/dist/oauth/refusal.js

@@ -0,0 +1,17 @@
+import { APIError } from '../errors.js';
+/** The one map from a directory refresh refusal code to what it means. Every other use of these codes reads its keys. */
+const refusalKinds = {
+    grant_removed: 'removed', grant_suspended: 'paused',
+    refresh_token_expired: 'reconnect', refresh_token_reused: 'reconnect', grant_revoked: 'reconnect',
+};
+export const isRefusalCode = (code) => Object.hasOwn(refusalKinds, code);
+const refusalKey = Symbol('crouter.refusal');
+export function refusalKindOf(code) { return isRefusalCode(code) ? refusalKinds[code] : null; }
+export function attachRefusal(error, refusal) { Object.defineProperty(error, refusalKey, { value: refusal }); }
+/** The `Refusal` a call failed with when the directory refused its connection's refresh, else `null`. Read it to
+ *  answer one request (show "sign in again"); act on the connection itself in `OAuth2Options.onRefusal`, which the
+ *  SDK has already run. Only an error raised by `OAuth2Client` refreshing a stored connection carries one; a 429,
+ *  `cap_exhausted`, `scope_missing`, or a runtime-origin `grant_revoked` does not. */
+export function refusalOf(error) {
+    return error instanceof APIError ? error[refusalKey] ?? null : null;
+}

package/dist/resources/activity.d.ts

@@ -0,0 +1,22 @@
+import type { NodeStreamEvent } from './node-stream.js';
+/** One tool call rendered as an activity step. */
+export interface ActivityStep {
+    /** The tool call's id, stable across its status changes. */
+    id: string;
+    /** Tool name, e.g. `bash` or `read`. */
+    tool: string;
+    /** The daemon's one-line summary of the call. */
+    summary: string;
+    /** What `describe` returned for this call, for display. */
+    label: string;
+    /** Where the call stands. */
+    status: 'running' | 'done' | 'failed';
+}
+/** Turn a streamed tool call into a label, or return null to omit it. */
+export type DescribeTool = (tool: string, summary: string) => string | null;
+/** Plain labels for the tools every node can use. */
+export declare const describeToolDefault: DescribeTool;
+/** Yield an immutable activity snapshot after every streamed tool-call change. */
+export declare function followActivity(stream: AsyncIterable<NodeStreamEvent>, options?: {
+    describe?: DescribeTool;
+}): AsyncGenerator<ActivityStep[]>;

package/dist/resources/activity.js

@@ -0,0 +1,43 @@
+/** Plain labels for the tools every node can use. */
+export const describeToolDefault = (tool) => {
+    switch (tool) {
+        case 'bash': return 'running bash';
+        case 'read': return 'reading';
+        case 'write': return 'writing';
+        case 'edit': return 'editing';
+        default: return tool;
+    }
+};
+/** Yield an immutable activity snapshot after every streamed tool-call change. */
+export async function* followActivity(stream, options = {}) {
+    const describe = options.describe ?? describeToolDefault;
+    const steps = [];
+    const byId = new Map();
+    for await (const event of stream) {
+        if (event.type === 'node.tool_call.started') {
+            const label = describe(event.tool, event.summary);
+            if (label === null || byId.has(event.tool_call_id))
+                continue;
+            const step = {
+                id: event.tool_call_id,
+                tool: event.tool,
+                summary: event.summary,
+                label,
+                status: 'running',
+            };
+            byId.set(step.id, step);
+            steps.push(step);
+            yield snapshot(steps);
+        }
+        else if (event.type === 'node.tool_call.completed') {
+            const step = byId.get(event.tool_call_id);
+            if (step === undefined || step.status !== 'running')
+                continue;
+            step.status = event.status === 'ok' ? 'done' : 'failed';
+            yield snapshot(steps);
+        }
+    }
+}
+function snapshot(steps) {
+    return steps.map((step) => ({ ...step }));
+}

package/dist/resources/attachments.d.ts

@@ -0,0 +1,15 @@
+import type { RequestOptions } from '../types.js';
+import type { Request } from './request.js';
+/** A short-lived signed link to an uploaded file's stored bytes. */
+export interface AttachmentLink {
+    url: string;
+    expires_at: string;
+}
+/** Links to files a run received as attachments (app listener only). */
+export declare class Attachments {
+    private readonly request;
+    constructor(request: Request);
+    /** A signed download link for the upload fetched to `path`, an absolute path under a run's
+     *  `attachments/` folder. A path with no recorded upload, or in a run the caller cannot read, is `not_found`. */
+    link(path: string, options?: RequestOptions): Promise<AttachmentLink>;
+}

package/dist/resources/attachments.js

@@ -0,0 +1,13 @@
+import { withQuery } from './request.js';
+/** Links to files a run received as attachments (app listener only). */
+export class Attachments {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    /** A signed download link for the upload fetched to `path`, an absolute path under a run's
+     *  `attachments/` folder. A path with no recorded upload, or in a run the caller cannot read, is `not_found`. */
+    link(path, options) {
+        return this.request('GET', withQuery('/v1/attachments/link', { path }), undefined, options);
+    }
+}

package/dist/resources/bash.d.ts

@@ -0,0 +1,9 @@
+import { type BashRunDTO, type BashRunParams } from '@north-light/api';
+import type { RequestOptions } from '../types.js';
+import type { Request } from './request.js';
+export declare class Bash {
+    private readonly request;
+    private readonly defaultTimeout;
+    constructor(request: Request, defaultTimeout: number);
+    run(params: BashRunParams, options?: RequestOptions): Promise<BashRunDTO>;
+}

package/dist/resources/bash.js

@@ -0,0 +1,15 @@
+import { routes } from '@north-light/api';
+const DEFAULT_TIMEOUT_SECONDS = 60;
+const TIMEOUT_ALLOWANCE_MS = 15_000;
+export class Bash {
+    request;
+    defaultTimeout;
+    constructor(request, defaultTimeout) {
+        this.request = request;
+        this.defaultTimeout = defaultTimeout;
+    }
+    run(params, options) {
+        const requiredTimeout = (params.timeout_s ?? DEFAULT_TIMEOUT_SECONDS) * 1000 + TIMEOUT_ALLOWANCE_MS;
+        return this.request('POST', routes.bash(), params, { ...options, timeout: Math.max(options?.timeout ?? this.defaultTimeout, requiredTimeout) });
+    }
+}

package/dist/resources/canvas/history.d.ts

@@ -0,0 +1,11 @@
+import { type HistoryGrepQuery, type HistoryGrepResultDTO, type HistoryReadQuery, type HistoryReadResultDTO, type HistorySearchQuery, type HistorySearchResultDTO, type HistoryStatsQuery, type HistoryStatsResultDTO } from '@north-light/api';
+import type { RequestOptions } from '../../types.js';
+import type { Request } from '../request.js';
+export declare class CanvasHistory {
+    private readonly request;
+    constructor(request: Request);
+    search(body: HistorySearchQuery, options?: RequestOptions): Promise<HistorySearchResultDTO>;
+    grep(body: HistoryGrepQuery, options?: RequestOptions): Promise<HistoryGrepResultDTO>;
+    read(query: HistoryReadQuery, options?: RequestOptions): Promise<HistoryReadResultDTO>;
+    stats(body: HistoryStatsQuery, options?: RequestOptions): Promise<HistoryStatsResultDTO>;
+}

package/dist/resources/canvas/history.js

@@ -0,0 +1,20 @@
+import { routes, } from '@north-light/api';
+import { withQuery } from '../request.js';
+export class CanvasHistory {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    search(body, options) {
+        return this.request('POST', routes.canvasHistorySearch(), body, options);
+    }
+    grep(body, options) {
+        return this.request('POST', routes.canvasHistoryGrep(), body, options);
+    }
+    read(query, options) {
+        return this.request('GET', withQuery(routes.canvasHistoryRead(), query), undefined, options);
+    }
+    stats(body, options) {
+        return this.request('POST', routes.canvasHistoryStats(), body, options);
+    }
+}

package/dist/resources/canvas.d.ts

@@ -0,0 +1,19 @@
+import { type AttentionCountsDTO, type AttentionCountsRequest, type AttentionDTO, type DashboardDTO, type DashboardQuery, type PruneRequest, type PruneResultDTO, type RosterDTO, type SnapshotDTO, type WatchRequest, type WatchResultDTO, type UnwatchQuery, type UnwatchResultDTO } from '@north-light/api';
+import type { RequestOptions } from '../types.js';
+import { CanvasHistory } from './canvas/history.js';
+import type { Request } from './request.js';
+export declare class Canvas {
+    private readonly request;
+    readonly history: CanvasHistory;
+    constructor(request: Request);
+    attention(options?: RequestOptions): Promise<AttentionDTO>;
+    attentionCounts(body: AttentionCountsRequest, options?: RequestOptions): Promise<AttentionCountsDTO>;
+    snapshot(options?: RequestOptions): Promise<SnapshotDTO>;
+    roster(options?: RequestOptions): Promise<RosterDTO>;
+    dashboard(query?: DashboardQuery, options?: RequestOptions): Promise<DashboardDTO>;
+    /** Watch an object; `watcher` makes a custom object the receiver instead of the caller's node. */
+    watch(ref: string, body?: WatchRequest, options?: RequestOptions): Promise<WatchResultDTO>;
+    /** Remove a watch. `watcher` identifies the custom object whose watch is removed. */
+    unwatch(ref: string, query?: UnwatchQuery, options?: RequestOptions): Promise<UnwatchResultDTO>;
+    prune(body: PruneRequest, options?: RequestOptions): Promise<PruneResultDTO>;
+}

package/dist/resources/canvas.js

@@ -0,0 +1,42 @@
+import { routes, } from '@north-light/api';
+import { CanvasHistory } from './canvas/history.js';
+import { withQuery } from './request.js';
+export class Canvas {
+    request;
+    history;
+    constructor(request) {
+        this.request = request;
+        this.history = new CanvasHistory(request);
+    }
+    attention(options) {
+        return this.request('GET', routes.canvasAttention(), undefined, options);
+    }
+    attentionCounts(body, options) {
+        return this.request('POST', routes.canvasAttentionCounts(), body, options);
+    }
+    snapshot(options) {
+        return this.request('GET', routes.canvasSnapshot(), undefined, options);
+    }
+    roster(options) {
+        return this.request('GET', routes.canvasRoster(), undefined, options);
+    }
+    async dashboard(query, options) {
+        const nodeQuery = query?.under === undefined ? undefined : { under: query.under };
+        const [nodes, status] = await Promise.all([
+            this.request('GET', withQuery(routes.nodes(), nodeQuery), undefined, options),
+            this.request('GET', routes.status(), undefined, options),
+        ]);
+        return { nodes, counts: status.node_counts, generated_at: new Date().toISOString() };
+    }
+    /** Watch an object; `watcher` makes a custom object the receiver instead of the caller's node. */
+    watch(ref, body = {}, options) {
+        return this.request('POST', routes.objectWatch(ref), body, options);
+    }
+    /** Remove a watch. `watcher` identifies the custom object whose watch is removed. */
+    unwatch(ref, query, options) {
+        return this.request('DELETE', withQuery(routes.objectWatch(ref), query), undefined, options);
+    }
+    prune(body, options) {
+        return this.request('POST', routes.canvasPrune(), body, options);
+    }
+}

package/dist/resources/crons.d.ts

@@ -0,0 +1,15 @@
+import { type ArmCronRequest, type CancelCronQuery, type CronDTO, type CronRunDTO, type CronScopeQuery, type CronShowDTO, type ListCronsQuery, type PokeCronsResult } from '@north-light/api';
+import type { RequestOptions } from '../types.js';
+import type { Request } from './request.js';
+export declare class Crons {
+    private readonly request;
+    constructor(request: Request);
+    create(body: ArmCronRequest, options?: RequestOptions): Promise<CronDTO>;
+    retrieve(id: string, query?: CronScopeQuery, options?: RequestOptions): Promise<CronShowDTO>;
+    list(query?: ListCronsQuery, options?: RequestOptions): Promise<CronDTO[]>;
+    pause(id: string, query?: CronScopeQuery, options?: RequestOptions): Promise<CronDTO>;
+    resume(id: string, query?: CronScopeQuery, options?: RequestOptions): Promise<CronDTO>;
+    run(id: string, query?: CronScopeQuery, options?: RequestOptions): Promise<CronRunDTO>;
+    delete(id: string, query?: CancelCronQuery, options?: RequestOptions): Promise<void>;
+    poke(options?: RequestOptions): Promise<PokeCronsResult>;
+}

package/dist/resources/crons.js

@@ -0,0 +1,33 @@
+import { routes, } from '@north-light/api';
+import { cronId } from './identifiers.js';
+import { withQuery } from './request.js';
+export class Crons {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    create(body, options) {
+        return this.request('POST', routes.crons(), body, options);
+    }
+    async retrieve(id, query, options) {
+        return this.request('GET', withQuery(routes.cron(cronId(id)), query), undefined, options);
+    }
+    list(query, options) {
+        return this.request('GET', withQuery(routes.crons(), query), undefined, options);
+    }
+    async pause(id, query, options) {
+        return this.request('POST', withQuery(routes.cronPause(cronId(id)), query), {}, options);
+    }
+    async resume(id, query, options) {
+        return this.request('POST', withQuery(routes.cronResume(cronId(id)), query), {}, options);
+    }
+    async run(id, query, options) {
+        return this.request('POST', withQuery(routes.cronRun(cronId(id)), query), {}, options);
+    }
+    async delete(id, query, options) {
+        return this.request('DELETE', withQuery(routes.cron(cronId(id)), query), undefined, options);
+    }
+    poke(options) {
+        return this.request('POST', routes.cronsPoke(), {}, options);
+    }
+}

package/dist/resources/custom-objects.d.ts

@@ -0,0 +1,20 @@
+import { type AckCustomDeliveriesResponseDTO, type PublishCustomObjectRequestDTO, type PublishCustomObjectResponseDTO, type QueueLineDTO, type RegisterCustomObjectRequestDTO, type RegisterCustomObjectResponseDTO } from '@north-light/api';
+import type { RequestOptions } from '../types.js';
+import type { Request } from './request.js';
+/** Queue streams replay every pending delivery on connect. `after` is accepted for compatibility but ignored for pending work. */
+export type ReceiveOptions = Pick<RequestOptions, 'signal' | 'headers' | 'maxRetries'> & {
+    after?: number;
+};
+/** A single queue connection. EOF (including rotate/unregister/receiver change) ends iteration; reconnect to replay unacknowledged work. */
+export interface CustomDeliveryStream extends AsyncIterableIterator<QueueLineDTO> {
+}
+export declare class CustomObjects {
+    private readonly request;
+    private readonly open;
+    constructor(request: Request, open: (path: string, options: ReceiveOptions) => Promise<Response>);
+    register(body: RegisterCustomObjectRequestDTO, options?: RequestOptions): Promise<RegisterCustomObjectResponseDTO>;
+    publish(ref: string, body: PublishCustomObjectRequestDTO, options?: RequestOptions): Promise<PublishCustomObjectResponseDTO>;
+    unregister(ref: string, options?: RequestOptions): Promise<void>;
+    ack(ref: string, deliveryIds: string[], options?: RequestOptions): Promise<AckCustomDeliveriesResponseDTO>;
+    receive(ref: string, options?: ReceiveOptions): CustomDeliveryStream;
+}

package/dist/resources/custom-objects.js

@@ -0,0 +1,84 @@
+import { routes, } from '@north-light/api';
+import { APIConnectionError, APIError, APIUserAbortError } from '../errors.js';
+import { withQuery } from './request.js';
+export class CustomObjects {
+    request;
+    open;
+    constructor(request, open) {
+        this.request = request;
+        this.open = open;
+    }
+    register(body, options) {
+        return this.request('POST', routes.customObjects(), body, options);
+    }
+    publish(ref, body, options) {
+        return this.request('POST', routes.customObjectEvents(ref), body, options);
+    }
+    unregister(ref, options) {
+        return this.request('DELETE', routes.customObject(ref), undefined, options);
+    }
+    ack(ref, deliveryIds, options) {
+        return this.request('POST', routes.customObjectAck(ref), { delivery_ids: deliveryIds }, options);
+    }
+    receive(ref, options = {}) {
+        const { after, ...requestOptions } = options;
+        if (after !== undefined && (!Number.isSafeInteger(after) || after < 0)) {
+            throw new RangeError('after must be a non-negative safe integer');
+        }
+        const path = withQuery(routes.customObjectDeliveries(ref), { after });
+        const iterate = async function* (open) {
+            const controller = new AbortController();
+            const abort = () => controller.abort(options.signal?.reason);
+            if (options.signal?.aborted)
+                abort();
+            else
+                options.signal?.addEventListener('abort', abort, { once: true });
+            let reader;
+            try {
+                const response = await open(path, { ...requestOptions, signal: controller.signal });
+                if (response.body === null)
+                    return;
+                reader = response.body.getReader();
+                const decoder = new TextDecoder();
+                let buffer = '';
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    buffer += decoder.decode(value, { stream: !done });
+                    const lines = buffer.split(/\r?\n/);
+                    buffer = lines.pop() ?? '';
+                    if (done && buffer !== '')
+                        lines.push(buffer);
+                    for (const line of lines) {
+                        if (line.trim() === '')
+                            continue; // heartbeat
+                        const delivery = JSON.parse(line);
+                        yield delivery;
+                    }
+                    if (done)
+                        return; // server deliberately closes on rotate/unregister/receiver change
+                }
+            }
+            catch (error) {
+                if (controller.signal.aborted && options.signal?.aborted) {
+                    throw new APIUserAbortError(0, 'request_aborted', 'request aborted by caller signal');
+                }
+                if (error instanceof Error && !(error instanceof SyntaxError) && !(error instanceof APIError)) {
+                    throw new APIConnectionError(0, 'connection_error', error.message);
+                }
+                throw error;
+            }
+            finally {
+                options.signal?.removeEventListener('abort', abort);
+                controller.abort();
+                if (reader !== undefined) {
+                    try {
+                        await reader.cancel();
+                    }
+                    catch { /* the server may have already closed */ }
+                    reader.releaseLock();
+                }
+            }
+        };
+        return iterate(this.open);
+    }
+}

package/dist/resources/files.d.ts

@@ -0,0 +1,34 @@
+import { type FileEncoding, type FileListDTO, type FilePeekDTO, type FileWriteDTO } from '@north-light/api';
+import type { RequestOptions } from '../types.js';
+import type { Request } from './request.js';
+/** Options for `files.download`. */
+export interface FileDownloadOptions {
+    /** A single `Range` header value, e.g. `bytes=0-0` or `bytes=-500`; the answer is then 206 with `Content-Range`. */
+    range?: string;
+    /** Aborts the request and the body stream. */
+    signal?: AbortSignal;
+}
+/** Opens a raw download; the client supplies the bearer token and refresh. */
+export type FileDownloadOpener = (path: string, options: FileDownloadOptions) => Promise<Response>;
+export declare class Files {
+    private readonly request;
+    private readonly openDownload?;
+    constructor(request: Request, openDownload?: FileDownloadOpener | undefined);
+    read(path: string, options?: {
+        encoding?: FileEncoding;
+    } & RequestOptions): Promise<FilePeekDTO>;
+    write(path: string, content: string, options?: {
+        encoding?: FileEncoding;
+    } & RequestOptions): Promise<FileWriteDTO>;
+    list(path: string, options?: {
+        limit?: number;
+    } & RequestOptions): Promise<FileListDTO>;
+    /**
+     * The raw bytes of a file the caller may read (app listener only). Answers the `Response`
+     * itself (200, or 206 for `range`) with `Content-Type`, `Content-Length`, and `Content-Range`,
+     * so its body can be piped on. A non-2xx answer is thrown as `APIError` — a bad range is
+     * 416 `invalid_request` with `param: 'range'` — and never returned as bytes. A body cut
+     * short mid-stream means the file could not be read to the end.
+     */
+    download(path: string, options?: FileDownloadOptions): Promise<Response>;
+}

package/dist/resources/files.js

@@ -0,0 +1,34 @@
+import { routes, } from '@north-light/api';
+import { withQuery } from './request.js';
+export class Files {
+    request;
+    openDownload;
+    constructor(request, openDownload) {
+        this.request = request;
+        this.openDownload = openDownload;
+    }
+    read(path, options) {
+        const { encoding, ...requestOptions } = options ?? {};
+        return this.request('GET', withQuery(routes.filePeek(), { path, encoding }), undefined, requestOptions);
+    }
+    write(path, content, options) {
+        const { encoding, ...requestOptions } = options ?? {};
+        return this.request('POST', routes.fileWrite(), { path, content, encoding }, requestOptions);
+    }
+    list(path, options) {
+        const { limit, ...requestOptions } = options ?? {};
+        return this.request('GET', withQuery(routes.fileList(), { path, limit }), undefined, requestOptions);
+    }
+    /**
+     * The raw bytes of a file the caller may read (app listener only). Answers the `Response`
+     * itself (200, or 206 for `range`) with `Content-Type`, `Content-Length`, and `Content-Range`,
+     * so its body can be piped on. A non-2xx answer is thrown as `APIError` — a bad range is
+     * 416 `invalid_request` with `param: 'range'` — and never returned as bytes. A body cut
+     * short mid-stream means the file could not be read to the end.
+     */
+    async download(path, options = {}) {
+        if (!this.openDownload)
+            throw new TypeError('files.download requires a Crouter client');
+        return this.openDownload(path, options);
+    }
+}

package/dist/resources/follower.d.ts

@@ -0,0 +1,71 @@
+/**
+ * What one turn asks of the follower when it ends:
+ * - `requeue`: the item goes to the back of the queue at once (while the app still returns it).
+ * - `park`: the item rests until a sweep queues it again.
+ * - `drop`: the item is left alone until the next sweep (connection trouble; the turn already reported it).
+ * - `fail`: the item backs off (5 s doubling to 5 min; the turn already reported the error), then a sweep queues it.
+ */
+export type TurnResult = 'requeue' | 'park' | 'drop' | 'fail';
+export interface FollowerHooks<T> {
+    /** The followed set, read from the app's rows at `start()`, every `sweepMs`, on `nudge()` and on `sweep()`. */
+    items: () => Promise<T[]> | T[];
+    key: (item: T) => string;
+    /** One turn for one item. `signal` aborts on `stop()`. A throw is treated as `fail` with that error. */
+    turn: (item: T, signal: AbortSignal) => Promise<TurnResult>;
+    /** Whether a sweep may queue this item (default: always). */
+    admit?: (key: string) => boolean;
+    /** The app stopped returning this key: clear what the watcher keeps for it. */
+    onForget?: (key: string) => void;
+    onError?: (error: unknown, item: T | null) => void;
+    sweepMs: number;
+    concurrency: number;
+    /** For the "cannot be started again" message. */
+    name: string;
+}
+/**
+ * The machinery `RunWatcher` and `GrantWatcher` share: the sweep loop (`sweepMs`, `nudge`, sweep-again coalescing),
+ * the queue and `concurrency` slots, per-key backoff, the lifetime `AbortController` and `stop()`, and `onError`.
+ * What a turn does, and whether it re-queues, is the watcher's.
+ */
+export declare class Follower<T> {
+    private readonly hooks;
+    private readonly following;
+    /** Keys queued at least once and not forgotten since. */
+    private readonly known;
+    /** Keys the last sweep read from `items()`. */
+    private wanted;
+    /** Keys backing off after a failure, until this instant. */
+    private readonly retryAt;
+    private readonly backoff;
+    private readonly queue;
+    private active;
+    private running;
+    private timer;
+    private sweeping;
+    private sweepAgain;
+    private readonly lifetime;
+    constructor(hooks: FollowerHooks<T>);
+    get isRunning(): boolean;
+    /** Whether the last sweep still returned this key. */
+    wants(key: string): boolean;
+    start(): Promise<void>;
+    nudge(): void;
+    stop(): Promise<void>;
+    /** A delivery landed for this key: clear its backoff. */
+    succeeded(key: string): void;
+    sweep(): Promise<void>;
+    private sweepOnce;
+    private forget;
+    private drain;
+    private run;
+    /** Back off this key: 5 s doubling to 5 min, then a sweep picks it up again. */
+    private fail;
+    report(error: unknown, item: T | null): void;
+}
+/** No stored connection, or a refusal `OAuth2Client` already handled: the item is dropped until the next sweep. */
+export declare function isConnectionTrouble(error: unknown): boolean;
+/** A turn's failure to open the person's client or read for them: reported to `onError`, then `drop` for connection
+ *  trouble (the next sweep decides) or `fail` (back off) for anything else. */
+export declare function troubleResult<T>(follower: Follower<T>, error: unknown, item: T): TurnResult;
+/** Abortable pause; resolves early (without throwing) when `signal` aborts. */
+export declare function pause(ms: number, signal: AbortSignal): Promise<void>;