@north-light/sdk 0.0.0-stage → 0.3.414

package/dist/resources/follower.js

@@ -0,0 +1,202 @@
+import { CrouterError } from '../errors.js';
+import { refusalOf } from '../oauth/refusal.js';
+const firstBackoffMs = 5_000;
+const maxBackoffMs = 300_000;
+/**
+ * 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 class Follower {
+    hooks;
+    following = new Map();
+    /** Keys queued at least once and not forgotten since. */
+    known = new Set();
+    /** Keys the last sweep read from `items()`. */
+    wanted = new Set();
+    /** Keys backing off after a failure, until this instant. */
+    retryAt = new Map();
+    backoff = new Map();
+    queue = [];
+    active = 0;
+    running = false;
+    timer;
+    sweeping;
+    sweepAgain = false;
+    lifetime = new AbortController();
+    constructor(hooks) {
+        this.hooks = hooks;
+        if (!Number.isFinite(hooks.sweepMs) || hooks.sweepMs <= 0)
+            throw new CrouterError('sweepMs must be a positive number');
+        if (!Number.isInteger(hooks.concurrency) || hooks.concurrency < 1)
+            throw new CrouterError('concurrency must be a positive integer');
+    }
+    get isRunning() { return this.running; }
+    /** Whether the last sweep still returned this key. */
+    wants(key) { return this.wanted.has(key); }
+    async start() {
+        if (this.running)
+            return;
+        if (this.lifetime.signal.aborted)
+            throw new CrouterError(`A stopped ${this.hooks.name} cannot be started again; build a new one`);
+        this.running = true;
+        await this.sweep();
+    }
+    nudge() { if (this.running)
+        void this.sweep(); }
+    async stop() {
+        this.running = false;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.lifetime.abort();
+        this.queue.length = 0;
+        await Promise.allSettled([...this.following.values()].map((follow) => follow.done));
+    }
+    /** A delivery landed for this key: clear its backoff. */
+    succeeded(key) {
+        this.retryAt.delete(key);
+        this.backoff.delete(key);
+    }
+    sweep() {
+        if (this.sweeping) {
+            this.sweepAgain = true;
+            return this.sweeping;
+        }
+        this.sweeping = (async () => {
+            do {
+                this.sweepAgain = false;
+                await this.sweepOnce();
+            } while (this.sweepAgain && this.running);
+        })().finally(() => {
+            this.sweeping = undefined;
+            if (this.running) {
+                if (this.timer)
+                    clearTimeout(this.timer);
+                this.timer = setTimeout(() => void this.sweep(), this.hooks.sweepMs);
+                unref(this.timer);
+            }
+        });
+        return this.sweeping;
+    }
+    async sweepOnce() {
+        if (!this.running)
+            return;
+        let items;
+        try {
+            items = await this.hooks.items();
+        }
+        catch (error) {
+            this.report(error, null);
+            return;
+        }
+        if (!this.running)
+            return;
+        const wanted = new Map(items.map((item) => [this.hooks.key(item), item]));
+        this.wanted = new Set(wanted.keys());
+        // Forget keys the app no longer returns, so a later reuse of the key starts clean.
+        for (const key of new Set([...this.known, ...this.retryAt.keys()]))
+            if (!wanted.has(key))
+                this.forget(key);
+        for (let i = this.queue.length - 1; i >= 0; i--)
+            if (!wanted.has(this.hooks.key(this.queue[i])))
+                this.queue.splice(i, 1);
+        const now = Date.now();
+        for (const [key, item] of wanted) {
+            if (this.following.has(key) || this.queue.some((queued) => this.hooks.key(queued) === key))
+                continue;
+            if ((this.retryAt.get(key) ?? 0) > now)
+                continue;
+            if (this.hooks.admit && !this.hooks.admit(key))
+                continue;
+            this.known.add(key);
+            this.queue.push(item);
+        }
+        this.drain();
+    }
+    forget(key) {
+        this.known.delete(key);
+        this.retryAt.delete(key);
+        this.backoff.delete(key);
+        this.hooks.onForget?.(key);
+    }
+    drain() {
+        while (this.running && this.active < this.hooks.concurrency && this.queue.length > 0) {
+            const item = this.queue.shift();
+            const key = this.hooks.key(item);
+            const controller = new AbortController();
+            const abort = () => controller.abort(this.lifetime.signal.reason);
+            this.lifetime.signal.addEventListener('abort', abort, { once: true });
+            this.active++;
+            const follow = { item, done: Promise.resolve() };
+            this.following.set(key, follow);
+            follow.done = this.run(item, controller.signal).then((result) => {
+                this.lifetime.signal.removeEventListener('abort', abort);
+                this.active--;
+                if (this.following.get(key) === follow)
+                    this.following.delete(key);
+                // The app stopped returning it during the turn: clear what the turn may have recorded.
+                if (!this.wanted.has(key))
+                    this.forget(key);
+                // Back of the queue, so with more items than slots every item still gets a turn in order.
+                if (result === 'requeue' && this.running && this.wanted.has(key) && !this.queue.some((queued) => this.hooks.key(queued) === key))
+                    this.queue.push(item);
+                this.drain();
+            });
+        }
+    }
+    async run(item, signal) {
+        let result;
+        try {
+            result = await this.hooks.turn(item, signal);
+        }
+        catch (error) {
+            this.report(error, item);
+            result = 'fail';
+        }
+        if (result === 'fail')
+            this.fail(this.hooks.key(item));
+        return result;
+    }
+    /** Back off this key: 5 s doubling to 5 min, then a sweep picks it up again. */
+    fail(key) {
+        const delay = Math.min(maxBackoffMs, this.backoff.get(key) ?? firstBackoffMs);
+        this.backoff.set(key, Math.min(maxBackoffMs, delay * 2));
+        this.retryAt.set(key, Date.now() + delay);
+        if (!this.running)
+            return;
+        const timer = setTimeout(() => { if (this.running)
+            void this.sweep(); }, delay);
+        unref(timer);
+        this.lifetime.signal.addEventListener('abort', () => clearTimeout(timer), { once: true });
+    }
+    report(error, item) {
+        try {
+            this.hooks.onError?.(error, item);
+        }
+        catch { /* A throwing onError must not stop the watcher. */ }
+    }
+}
+/** No stored connection, or a refusal `OAuth2Client` already handled: the item is dropped until the next sweep. */
+export function isConnectionTrouble(error) {
+    return refusalOf(error) !== null || (error instanceof CrouterError && (error.code === 'not_connected' || error.code === 'refusal_handler_reentry'));
+}
+/** 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 function troubleResult(follower, error, item) {
+    follower.report(error, item);
+    return isConnectionTrouble(error) ? 'drop' : 'fail';
+}
+/** Abortable pause; resolves early (without throwing) when `signal` aborts. */
+export function pause(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const done = () => { clearTimeout(timer); signal.removeEventListener('abort', done); resolve(); };
+        const timer = setTimeout(done, ms);
+        unref(timer);
+        signal.addEventListener('abort', done, { once: true });
+    });
+}
+function unref(timer) { timer.unref?.(); }

package/dist/resources/forward.d.ts

@@ -0,0 +1,7 @@
+import type { Crouter } from '../client.js';
+/** Native EventSource sends Last-Event-ID on reconnect; it takes precedence over the URL cursor. */
+export declare function cursorFromRequest(request: Request): number;
+export declare function forwardRunEvents(crouter: Crouter, runId: string, options: {
+    after: number;
+    signal?: AbortSignal;
+}): Response;

package/dist/resources/forward.js

@@ -0,0 +1,67 @@
+import { APIError } from '../errors.js';
+/** Native EventSource sends Last-Event-ID on reconnect; it takes precedence over the URL cursor. */
+export function cursorFromRequest(request) {
+    const header = request.headers.get('Last-Event-ID');
+    const value = header !== null ? header : new URL(request.url).searchParams.get('after') ?? '0';
+    const cursor = Number(value);
+    if (!/^(0|[1-9]\d*)$/.test(value) || !Number.isSafeInteger(cursor))
+        throw new RangeError('Invalid event cursor');
+    return cursor;
+}
+export function forwardRunEvents(crouter, runId, options) {
+    const encoder = new TextEncoder();
+    const envelope = (failure) => ({
+        code: failure.code, message: failure.message,
+        ...(failure.type !== undefined ? { type: failure.type } : {}),
+        ...(failure.param !== undefined ? { param: failure.param } : {}),
+        ...(failure.details !== undefined ? { details: failure.details } : {}),
+        ...(failure.retryable !== undefined ? { retryable: failure.retryable } : {}),
+        ...(failure.retryAfterS !== undefined ? { retry_after_s: failure.retryAfterS } : {}),
+        ...(failure.resetAt !== undefined ? { reset_at: failure.resetAt } : {}),
+        ...(failure.userAction !== undefined ? { user_action: failure.userAction } : {}),
+        ...(failure.requestId !== undefined ? { request_id: failure.requestId } : {}),
+        ...(failure.runId !== undefined ? { run_id: failure.runId } : {}),
+        ...(failure.questionId !== undefined ? { question_id: failure.questionId } : {}),
+        ...(failure.scope !== undefined ? { scope: failure.scope } : {}),
+        ...(failure.origin !== undefined ? { origin: failure.origin } : {}),
+    });
+    const failureEnvelope = (error) => envelope(error instanceof APIError ? error : new APIError(0, 'transport_error', String(error), undefined, undefined, { retryable: true }));
+    let notify = () => undefined;
+    const source = crouter.runs.events(runId, { ...options, onReconnect: (state, error) => notify(state, error) });
+    let closed = false;
+    const stream = new ReadableStream({
+        start(controller) {
+            const write = (text) => { if (!closed)
+                controller.enqueue(encoder.encode(text)); };
+            notify = (state, error) => write(`data: ${JSON.stringify(state === 'reconnected' ? { type: 'stream.reconnected' } : { type: 'stream.reconnecting', error: failureEnvelope(error) })}\n\n`);
+            const keepalive = setInterval(() => write(': keepalive\n\n'), 15_000);
+            void (async () => {
+                try {
+                    for await (const event of source) {
+                        write(`id: ${event.sequence_number}\ndata: ${JSON.stringify(event)}\n\n`);
+                        if (event.type === 'node.settled')
+                            break;
+                    }
+                    // The runtime closed an idle stream: tell the browser, then close, so an auto-reconnecting EventSource does not reopen at once.
+                    if (source.idle)
+                        write(`data: ${JSON.stringify({ type: 'stream.idle', cursor: source.position })}\n\n`);
+                }
+                catch (error) {
+                    if (options.signal?.aborted)
+                        return;
+                    write(`data: ${JSON.stringify({ type: 'stream.refused', error: failureEnvelope(error) })}\n\n`);
+                }
+                finally {
+                    source.abort();
+                    clearInterval(keepalive);
+                    if (!closed) {
+                        closed = true;
+                        controller.close();
+                    }
+                }
+            })();
+        },
+        cancel() { closed = true; source.abort(); },
+    });
+    return new Response(stream, { headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'X-Accel-Buffering': 'no' } });
+}

package/dist/resources/grant-watcher.d.ts

@@ -0,0 +1,57 @@
+import type { GrantGetDTO } from '@north-light/api';
+import type { Crouter } from '../client.js';
+/** One grant reading `GrantWatcher` hands to `onChanged`. `previous` is the grant last delivered for this user in this
+ *  process, or `null` on the first delivery (also after a restart, or after the user left and re-entered `users()`). */
+export interface GrantChanged {
+    userId: string;
+    grant: GrantGetDTO;
+    previous: GrantGetDTO | null;
+}
+export interface GrantWatchOptions {
+    /** The people whose grant the app follows (crouter cloud user ids), read from its own rows. Called at `start()`,
+     *  every `sweepMs`, after each delivery, and on `nudge()`. Return only people whose change the app will act on:
+     *  each followed person holds one request on their runtime per turn. A user no longer returned is forgotten. */
+    users: () => Promise<string[]> | string[];
+    /** Level-triggered: decide from `event.grant` (and the app's rows), never from "did it just change". The first event
+     *  per user in a process carries the current grant with `previous: null`. At least once per `(userId, version)`:
+     *  make it idempotent. If it throws, the same version is delivered again after 5 s, doubling to 5 min. */
+    onChanged: (event: GrantChanged) => Promise<void> | void;
+    /** Told about every failure the watcher recovers from itself: a throwing `users()` or `onChanged`, a transient
+     *  runtime error, a missing (`not_connected`) or refused connection. Defaults to ignoring them. */
+    onError?: (error: unknown, userId: string | null) => void;
+    /** Milliseconds between sweeps of `users()`. Default 30 000. */
+    sweepMs?: number;
+    /** Most users read at once. Default 50; the rest wait their turn, round-robin. */
+    concurrency?: number;
+    /** Seconds each held read waits for a change: an integer 1–25, default 25. */
+    wait?: number;
+}
+/**
+ * Follows the grants of the people an app names and hands each change to `onChanged` at least once. Build it with
+ * `oauth.watchGrants(...)`, then `start()`.
+ *
+ * One turn per user is one `grant.get`; then the user goes to the back of the queue. A user whose last answer was
+ * delivered reads `{wait, since: version}`, so the runtime holds the read until the grant changes; a user with nothing
+ * delivered yet (first turn, a throwing `onChanged`) reads at once. Delivered versions are kept in memory: the app's
+ * rows are the durable record, and a restarted watcher delivers each user's current grant again.
+ */
+export declare class GrantWatcher {
+    private readonly open;
+    private readonly options;
+    private readonly wait;
+    /** The grant last delivered per user. */
+    private readonly delivered;
+    /** The version last read per user: a user whose last reading was not delivered reads again without `wait`. */
+    private readonly seen;
+    /** Users whose last held read answered at once with the same version: their next turn pauses first. */
+    private readonly unheld;
+    private readonly follower;
+    constructor(open: (userId: string) => Promise<Crouter>, options: GrantWatchOptions);
+    /** Read `users()` and begin following; sweeps repeat every `sweepMs` until `stop()`. Resolves after the first sweep. */
+    start(): Promise<void>;
+    /** Sweep now instead of waiting for `sweepMs`, for example right after the app starts waiting on someone. */
+    nudge(): void;
+    /** Stop sweeping, abort every open read, and resolve once every turn has ended. No handler starts afterwards. */
+    stop(): Promise<void>;
+    private turn;
+}

package/dist/resources/grant-watcher.js

@@ -0,0 +1,100 @@
+import { CrouterError } from '../errors.js';
+import { Follower, pause, troubleResult } from './follower.js';
+/** A held read that answers its unchanged `since` sooner than this is treated as not holding: the next turn waits. */
+const minHoldMs = 1_000;
+const unheldRetryMs = 1_000;
+/**
+ * Follows the grants of the people an app names and hands each change to `onChanged` at least once. Build it with
+ * `oauth.watchGrants(...)`, then `start()`.
+ *
+ * One turn per user is one `grant.get`; then the user goes to the back of the queue. A user whose last answer was
+ * delivered reads `{wait, since: version}`, so the runtime holds the read until the grant changes; a user with nothing
+ * delivered yet (first turn, a throwing `onChanged`) reads at once. Delivered versions are kept in memory: the app's
+ * rows are the durable record, and a restarted watcher delivers each user's current grant again.
+ */
+export class GrantWatcher {
+    open;
+    options;
+    wait;
+    /** The grant last delivered per user. */
+    delivered = new Map();
+    /** The version last read per user: a user whose last reading was not delivered reads again without `wait`. */
+    seen = new Map();
+    /** Users whose last held read answered at once with the same version: their next turn pauses first. */
+    unheld = new Set();
+    follower;
+    constructor(open, options) {
+        this.open = open;
+        this.options = options;
+        this.wait = options.wait ?? 25;
+        if (!Number.isInteger(this.wait) || this.wait < 1 || this.wait > 25)
+            throw new CrouterError('wait must be an integer from 1 to 25');
+        this.follower = new Follower({
+            name: 'GrantWatcher',
+            items: () => options.users(),
+            key: (userId) => userId,
+            turn: (userId, signal) => this.turn(userId, signal),
+            onForget: (userId) => { this.delivered.delete(userId); this.seen.delete(userId); this.unheld.delete(userId); },
+            onError: options.onError,
+            sweepMs: options.sweepMs ?? 30_000,
+            concurrency: options.concurrency ?? 50,
+        });
+    }
+    /** Read `users()` and begin following; sweeps repeat every `sweepMs` until `stop()`. Resolves after the first sweep. */
+    start() { return this.follower.start(); }
+    /** Sweep now instead of waiting for `sweepMs`, for example right after the app starts waiting on someone. */
+    nudge() { this.follower.nudge(); }
+    /** Stop sweeping, abort every open read, and resolve once every turn has ended. No handler starts afterwards. */
+    stop() { return this.follower.stop(); }
+    async turn(userId, signal) {
+        if (this.unheld.delete(userId))
+            await pause(unheldRetryMs, signal);
+        if (signal.aborted || !this.follower.isRunning)
+            return 'park';
+        let client;
+        try {
+            client = await this.open(userId);
+        }
+        catch (error) {
+            return troubleResult(this.follower, error, userId);
+        }
+        const last = this.delivered.get(userId);
+        const started = Date.now();
+        let grant;
+        // Hold only when the last reading was delivered; otherwise (first turn, a throwing onChanged) read at once.
+        const hold = last !== undefined && this.seen.get(userId) === last.version;
+        try {
+            grant = await client.grant.get(hold ? { signal, wait: this.wait, since: last.version } : { signal });
+        }
+        catch (error) {
+            if (signal.aborted || !this.follower.isRunning)
+                return 'park';
+            return troubleResult(this.follower, error, userId);
+        }
+        if (typeof grant?.version !== 'string' || grant.version === '') {
+            this.follower.report(new CrouterError('grant.get answered without a version; the runtime predates the grant watch'), userId);
+            return 'fail';
+        }
+        this.seen.set(userId, grant.version);
+        if (last && grant.version === last.version) {
+            if (hold && Date.now() - started < minHoldMs)
+                this.unheld.add(userId);
+            return 'requeue';
+        }
+        if (!this.follower.isRunning || !this.follower.wants(userId))
+            return 'park';
+        try {
+            await this.options.onChanged({ userId, grant, previous: last ?? null });
+        }
+        catch (error) {
+            this.follower.report(error, userId);
+            return 'fail';
+        }
+        this.delivered.set(userId, grant);
+        this.follower.succeeded(userId);
+        // The app has likely acted on it; re-read users() so the set shrinks promptly.
+        if (this.follower.isRunning)
+            void this.follower.sweep();
+        return 'requeue';
+    }
+}

package/dist/resources/human/inbox.d.ts

@@ -0,0 +1,14 @@
+import { type CancelInboxTicketRequest, type CanceledTicketResultDTO, type InboxListDTO, type InboxPageDTO, type InboxPageHistoryDTO, type InboxPageProgressDTO, type InboxPageResponseDTO, type PageTicketResultDTO, type RespondInboxPageRequest } from '@north-light/api';
+import type { RequestOptions } from '../../types.js';
+import type { Request } from '../request.js';
+export declare class HumanInbox {
+    private readonly request;
+    constructor(request: Request);
+    list(options?: RequestOptions): Promise<InboxListDTO>;
+    retrieve(ticketId: string, options?: RequestOptions): Promise<InboxPageDTO>;
+    respond(ticketId: string, body: RespondInboxPageRequest, options?: RequestOptions): Promise<PageTicketResultDTO>;
+    progress(ticketId: string, body: InboxPageProgressDTO, options?: RequestOptions): Promise<Record<string, unknown>>;
+    cancel(ticketId: string, body?: CancelInboxTicketRequest, options?: RequestOptions): Promise<CanceledTicketResultDTO>;
+    history(nodeId?: string, options?: RequestOptions): Promise<InboxPageHistoryDTO>;
+    response(ticketId: string, options?: RequestOptions): Promise<InboxPageResponseDTO>;
+}

package/dist/resources/human/inbox.js

@@ -0,0 +1,30 @@
+import { routes, } from '@north-light/api';
+import { inboxTicketId } from '../identifiers.js';
+import { withQuery } from '../request.js';
+export class HumanInbox {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    list(options) {
+        return this.request('GET', routes.humanInbox(), undefined, options);
+    }
+    async retrieve(ticketId, options) {
+        return this.request('GET', routes.humanInboxTicket(inboxTicketId(ticketId)), undefined, options);
+    }
+    async respond(ticketId, body, options) {
+        return this.request('POST', routes.humanInboxRespond(inboxTicketId(ticketId)), body, options);
+    }
+    async progress(ticketId, body, options) {
+        return this.request('POST', routes.humanInboxProgress(inboxTicketId(ticketId)), body, options);
+    }
+    async cancel(ticketId, body, options) {
+        return this.request('POST', routes.humanInboxCancel(inboxTicketId(ticketId)), body ?? {}, options);
+    }
+    history(nodeId, options) {
+        return this.request('GET', withQuery('/v1/human/inbox/history', nodeId === undefined ? undefined : { node_id: nodeId }), undefined, options);
+    }
+    async response(ticketId, options) {
+        return this.request('GET', routes.humanInboxResponse(inboxTicketId(ticketId)), undefined, options);
+    }
+}

package/dist/resources/human/requests.d.ts

@@ -0,0 +1,13 @@
+import { type CreateHumanRequestDTO, type CreateHumanRequestRequest, type HumanRequestDTO, type ReplaceHumanRequestRequest, type RespondHumanRequestRequest, type SettleHumanRequestRequest } from '@north-light/api';
+import type { RequestOptions } from '../../types.js';
+import type { Request } from '../request.js';
+export declare class HumanRequests {
+    private readonly request;
+    constructor(request: Request);
+    create(body: CreateHumanRequestRequest, options?: RequestOptions): Promise<CreateHumanRequestDTO>;
+    retrieve(id: string, options?: RequestOptions): Promise<HumanRequestDTO>;
+    replace(id: string, body: ReplaceHumanRequestRequest, options?: RequestOptions): Promise<HumanRequestDTO>;
+    respond(id: string, body: RespondHumanRequestRequest, options?: RequestOptions): Promise<HumanRequestDTO>;
+    dismiss(id: string, body?: SettleHumanRequestRequest, options?: RequestOptions): Promise<HumanRequestDTO>;
+    cancel(id: string, body?: SettleHumanRequestRequest, options?: RequestOptions): Promise<HumanRequestDTO>;
+}

package/dist/resources/human/requests.js

@@ -0,0 +1,26 @@
+import { routes, } from '@north-light/api';
+import { requestId } from '../identifiers.js';
+export class HumanRequests {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    create(body, options) {
+        return this.request('POST', routes.humanRequests(), body, options);
+    }
+    async retrieve(id, options) {
+        return this.request('GET', routes.humanRequest(requestId(id)), undefined, options);
+    }
+    async replace(id, body, options) {
+        return this.request('POST', routes.humanRequestReplace(requestId(id)), body, options);
+    }
+    async respond(id, body, options) {
+        return this.request('POST', routes.humanRequestRespond(requestId(id)), body, options);
+    }
+    async dismiss(id, body, options) {
+        return this.request('POST', routes.humanRequestDismiss(requestId(id)), body ?? {}, options);
+    }
+    async cancel(id, body, options) {
+        return this.request('POST', routes.humanRequestCancel(requestId(id)), body ?? {}, options);
+    }
+}

package/dist/resources/human.d.ts

@@ -0,0 +1,8 @@
+import { HumanInbox } from './human/inbox.js';
+import { HumanRequests } from './human/requests.js';
+import type { Request } from './request.js';
+export declare class Human {
+    readonly requests: HumanRequests;
+    readonly inbox: HumanInbox;
+    constructor(request: Request);
+}

package/dist/resources/human.js

@@ -0,0 +1,10 @@
+import { HumanInbox } from './human/inbox.js';
+import { HumanRequests } from './human/requests.js';
+export class Human {
+    requests;
+    inbox;
+    constructor(request) {
+        this.requests = new HumanRequests(request);
+        this.inbox = new HumanInbox(request);
+    }
+}

package/dist/resources/identifiers.d.ts

@@ -0,0 +1,8 @@
+export declare class ResourceIdentifierError extends TypeError {
+}
+export declare function nodeId(value: string): string;
+export declare function requestId(value: string): string;
+export declare function cronId(value: string): string;
+export declare function jobId(value: string): string;
+export declare function inboxTicketId(value: string): string;
+export declare function pathSegment(value: string, label: string): string;

package/dist/resources/identifiers.js

@@ -0,0 +1,33 @@
+import { isSafeBashJobId, isSafeCronId, isSafeNodeId } from '@north-light/api';
+export class ResourceIdentifierError extends TypeError {
+}
+function validated(value, label, validator) {
+    if (!validator(value) || !isSafePathSegment(value)) {
+        throw new ResourceIdentifierError(`invalid ${label}: ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+function isSafePathSegment(value) {
+    return typeof value === 'string'
+        && value !== '' && value !== '.' && value !== '..'
+        && !/[\\/\0\s?#%]/u.test(value)
+        && new TextEncoder().encode(value).byteLength <= 128;
+}
+export function nodeId(value) {
+    return validated(value, 'node id', isSafeNodeId);
+}
+export function requestId(value) {
+    return validated(value, 'request id', isSafeNodeId);
+}
+export function cronId(value) {
+    return validated(value, 'cron id', isSafeCronId);
+}
+export function jobId(value) {
+    return validated(value, 'job id', isSafeBashJobId);
+}
+export function inboxTicketId(value) {
+    return validated(value, 'inbox ticket id', (ticketId) => /^[a-f0-9]{64}$/u.test(ticketId));
+}
+export function pathSegment(value, label) {
+    return validated(value, label, isSafePathSegment);
+}

package/dist/resources/memory.d.ts

@@ -0,0 +1,69 @@
+import type { RequestOptions } from '../types.js';
+import { type Request } from './request.js';
+/** `memory.list` input. Only the documents the person owns (`store: 'user'`) are served in this release. */
+export interface MemoryListParams {
+    store: 'user';
+    /** A folder: documents whose name starts with `<path>/`, at any depth. */
+    path?: string;
+    kind?: 'knowledge' | 'preference';
+    /** 1 to 100; default 50. */
+    limit?: number;
+    /** The previous page's `next_cursor`, unchanged, with the same `store`, `path` and `kind`. */
+    cursor?: string;
+}
+/** `memory.get` input. */
+export interface MemoryGetParams {
+    store: 'user';
+    /** The document's full name, as `memory.list` returns it. */
+    name: string;
+}
+/** One document the person owns, as listed. */
+export interface MemoryListItem {
+    /** The full name without the `user/` owner prefix. */
+    name: string;
+    /** The name up to its last `/`; `""` for a top-level document. */
+    folder: string;
+    kind: 'knowledge' | 'preference';
+    preview: string;
+    summary: string | null;
+    /** Without a `crtr:memory:manage:user` grant an app only ever sees `public`. */
+    privacy: 'public' | 'friends' | 'private';
+    /** The current revision number. */
+    revision: number;
+    /** The time of revision 1. */
+    created_at: string;
+    /** The time of the current revision. */
+    updated_at: string;
+}
+/** A page of `memory.list`, ordered by name. */
+export interface MemoryListPage {
+    items: MemoryListItem[];
+    /** `null` on the last page. */
+    next_cursor: string | null;
+}
+/** A document with its body, from `memory.get`. */
+export interface MemoryDocument extends MemoryListItem {
+    /** The current markdown body as stored; links are not resolved. At most 1 MiB. */
+    body: string;
+    /** The full body's length in UTF-8 bytes. */
+    size: number;
+    /** `true` when `size` is over 1 MiB and `body` is its prefix. */
+    truncated: boolean;
+    /** `app:<id>` of the app whose node wrote revision 1; `null` when the person wrote it. */
+    grantee: string | null;
+}
+/**
+ * Reads the documents the person owns. The daemon filters each one by the caller's
+ * grant: an app reads `public` documents with no scope, and every privacy level with
+ * `crtr:memory:manage:user`; without it a `friends` or `private` document reads
+ * exactly as an absent one (`NotFoundError`). Reading records nothing.
+ */
+export declare class Memory {
+    private readonly request;
+    constructor(request: Request);
+    list(params: MemoryListParams, options?: RequestOptions): Promise<MemoryListPage>;
+    /** Every document across pages, ordered by name: `for await (const item of memory.listAll({store: 'user'}))`.
+     *  Fetches the next page (`limit` per page) only as you iterate; `break` stops fetching. */
+    listAll(params: Omit<MemoryListParams, 'cursor'>, options?: RequestOptions): AsyncGenerator<MemoryListItem, void, undefined>;
+    get(params: MemoryGetParams, options?: RequestOptions): Promise<MemoryDocument>;
+}