@north-light/sdk 0.0.0 → 0.3.414

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/cloud.d.ts

@@ -0,0 +1,209 @@
+import type { ProviderDependency } from '@north-light/api';
+import { Crouter } from '../client.js';
+import { type ConnectionStore } from '../oauth/index.js';
+import { type FakeNotice, type RunNoticeOptions } from './notices.js';
+import { FakeRun } from './run.js';
+import { type FakeRefusalCode, type FakeScope, type FakeUser, type Responder } from './users.js';
+import { type FakeError } from './wire.js';
+/** A runtime operation, named as the daemon's `OPERATIONS` table names it. */
+export type FakeOp = 'grant.get' | 'run.start' | 'run.list' | 'run.get' | 'run.message' | 'run.events' | 'run.interrupt' | 'run.cancel' | 'run.delete' | 'run.rename' | 'question.get' | 'question.answer' | 'trace.get' | 'memory.list' | 'memory.get' | 'provider.tools' | 'provider.call' | 'profile.list';
+/** A directory operation. */
+export type FakeDirectoryOp = 'directory.discovery' | 'directory.token' | 'directory.jwks';
+/** What `intercept` / `failNext` / `gate` match: a runtime operation, `'*'` (every runtime operation), or a directory operation. */
+export type FakeInterceptOp = FakeOp | '*' | FakeDirectoryOp;
+/** One runtime request the fake received. */
+export interface FakeCall {
+    /** The bearer token's `sub` when it names a person this cloud knows (whatever their grant or refresh-token state);
+     *  null when there is no bearer, it does not decode, or its `sub` is a person the cloud has never seen. */
+    userId: string | null;
+    op: FakeOp;
+    /** The run the call addresses: the id in the path of `run.get`/`message`/`events`/`interrupt`/`cancel`/`delete`/
+     *  `rename` and `trace.get` (as sent, whether or not such a run exists); for `question.get`/`answer`, the run that
+     *  holds the question (null when no run of the caller does). Null for every other operation. */
+    runId: string | null;
+    /** The question id in the path of `question.get`/`answer`; null otherwise. */
+    questionId: string | null;
+    method: string;
+    path: string;
+    query: Record<string, string>;
+    /** Parsed JSON body, or null. */
+    body: unknown;
+    idempotencyKey: string | null;
+    /** The status answered; null while held or before an answer. */
+    status: number | null;
+    at: number;
+}
+/** One directory request the fake received. */
+export interface FakeDirectoryCall {
+    op: FakeDirectoryOp;
+    /** The refresh token's owner on `directory.token`; null otherwise. */
+    userId: string | null;
+    /** `ok`, a refusal code, an HTTP status, or `unreachable`. */
+    answer: 'ok' | FakeRefusalCode | number | 'unreachable';
+    at: number;
+}
+/** A scripted failure: `'unreachable'` (fetch rejects), an HTTP status, or a `FakeCloud.error(...)` envelope (runtime only). */
+export type FakeAnswer = 'unreachable' | number | FakeError;
+/** Runs before an operation. It may await (a gate), act, or return a replacement answer. */
+export type Intercept = (call: FakeCall | FakeDirectoryCall) => void | FakeAnswer | Promise<void | FakeAnswer>;
+/** A provider tool's handler; its return value is the call's result. Throw `FakeCloud.error(...)` for an envelope. */
+export type FakeToolHandler = (input: {
+    userId: string;
+    arguments: Record<string, unknown>;
+    signal: AbortSignal | null;
+}) => unknown;
+/** `providers.define` input. */
+export interface FakeProvider {
+    displayName?: string;
+    /** `available` (default), or an install state: listed with `error`, calls answer 503 `provider_unavailable`. */
+    status?: 'available' | 'installing' | 'install_failed';
+    error?: string;
+    tools: Record<string, {
+        group?: string;
+        description?: string;
+        handler: FakeToolHandler;
+    }>;
+}
+export interface FakeCloudOptions {
+    /** The app registration this cloud serves. */
+    clientId: string;
+    /** Default `https://directory.test`. */
+    issuer?: string;
+    /** Default `https://runtime.test`; a function gives each user their own host. */
+    runtimeUrl?: string | ((userId: string) => string);
+    /** The runtime's identity in run-notice tokens (`act.sub`). Default `runtime:test`. */
+    runtimeId?: string;
+    /** The runtime's client id in run-notice tokens (`client_id`). Default `runtime-client`. */
+    runtimeClientId?: string;
+    /** The runtime's release; default `SDK_VERSION`. An older one refuses this SDK with 426. */
+    runtimeVersion?: string;
+    /** Idle close of a run's event stream. Default 60 000 ms. */
+    streamIdleMs?: number;
+    /** Discovery's `account_app_uri_template`; default `<issuer>/account/apps/{client_id}`, null omits it. */
+    accountAppUriTemplate?: string | null;
+    /** Runtime→app run notices; without it nothing is sent. */
+    runNotice?: RunNoticeOptions;
+    /**
+     * Whether the runtime can start an `isolated: true` run. `available` (default) models a crouter cloud guest, where
+     * the Linux root launcher always exists: the run starts, `run.params.isolated` is true, and a `cwd` outside the run's
+     * root folder (`/apps/<clientId>/nodes/<run id>`) is 400 `invalid_request` `param: cwd`. `unavailable` models a
+     * runtime without the launcher (a developer's Mac): every isolated start is 503 `isolated_unavailable`, retryable.
+     */
+    isolatedRuns?: 'available' | 'unavailable';
+}
+/** `cloud.runs` and `user.runs`: the runs in start order, and the responder for them. */
+export interface FakeRuns {
+    /** The runs in start order (deleted ones included, with `deleted` set). */
+    readonly all: FakeRun[];
+    /** Set the responder (null clears it). On a user's `runs` it overrides the cloud's for that user. */
+    respond(fn: Responder | null): void;
+}
+/** A fake crouter cloud: the directory (discovery, refresh, JWKS) and each person's runtime, behind `fetch`. */
+export declare class FakeCloud {
+    /** Pass to `OAuth2Client` (and `verifyRunNotice`) as `fetch`. Unique per cloud. */
+    readonly fetch: typeof fetch;
+    readonly issuer: string;
+    readonly clientId: string;
+    /** Every runtime request, in order. */
+    readonly calls: FakeCall[];
+    /** Every directory request, in order. */
+    readonly directoryCalls: FakeDirectoryCall[];
+    /** Every run-notice attempt, in order. */
+    readonly notices: FakeNotice[];
+    /** What responders threw. */
+    readonly responderErrors: unknown[];
+    readonly runs: FakeRuns;
+    readonly providers: {
+        define(provider: string, definition: FakeProvider): void;
+    };
+    private readonly options;
+    private readonly users;
+    private readonly handles;
+    private readonly allRuns;
+    private readonly providerDefs;
+    private intercepts;
+    private readonly gates;
+    private responder;
+    private readonly key;
+    private readonly runNotices;
+    private readonly host;
+    /** Superseded refresh tokens → owner, for `refresh_token_reused`. */
+    private readonly superseded;
+    private tokenSerial;
+    private refreshSerial;
+    private runSerial;
+    constructor(options: FakeCloudOptions);
+    /** A `FakeError` envelope for intercepts, `failNext` and provider handlers. `retryable` defaults to `status === 503`. */
+    static error(input: {
+        status: number;
+        code: string;
+        message?: string;
+        origin?: string;
+        retryable?: boolean;
+        details?: unknown;
+        param?: string;
+    }): FakeError;
+    /** The `directory.token` subset of `directoryCalls`. */
+    get refreshes(): FakeDirectoryCall[];
+    /** That user's handle, created on first use. */
+    user(userId: string): FakeUser;
+    /**
+     * Make `userId`'s grant active and save a stored connection for them in `store`, with its access token expired so
+     * the first call refreshes through the directory. Default scopes: `crtr:llm`, `crtr:act`.
+     */
+    connect(store: ConnectionStore, userId: string, options?: {
+        scopes?: FakeScope[];
+        dependencies?: Record<string, ProviderDependency>;
+    }): Promise<FakeUser>;
+    /**
+     * A real `Crouter` on `userId`'s runtime with a fresh access token and no refresh: refusals never reach it. For
+     * code whose production signature takes a `Crouter`; an app that goes through `OAuth2Client` tests through it.
+     */
+    crouter(userId: string): Crouter;
+    /** Run `fn` before `op`. `times` defaults to Infinity. `user` filters runtime operations and `directory.token`. */
+    intercept(op: FakeInterceptOp, fn: Intercept, options?: {
+        user?: string;
+        times?: number;
+    }): () => void;
+    /** Answer the next `times` (default 1) matching requests with `answer`. */
+    failNext(op: FakeInterceptOp, answer: FakeAnswer, options?: {
+        user?: string;
+        times?: number;
+    }): void;
+    /** Hold every matching request until `release()`, which frees them all and removes the gate. */
+    gate(op: FakeInterceptOp, options?: {
+        user?: string;
+    }): () => void;
+    /** Clear runs, calls, intercepts (gates are released), responders, memory, idempotency keys and notices. Grants
+     *  and refresh-token chains stay, so stored connections remain valid. */
+    reset(): void;
+    /** The exact error the SDK raises when the directory refuses a refresh with `code` (`refusalOf(e)` is set). */
+    refusalError(code: FakeRefusalCode): Promise<unknown>;
+    private state;
+    private runtimeUrlFor;
+    private isRuntimeOrigin;
+    private headers;
+    private route;
+    private runIntercepts;
+    private directory;
+    private refresh;
+    private newRefreshToken;
+    private accessToken;
+    private runtime;
+    private ownedRun;
+    private respond;
+    private idempotencyKey;
+    private handle;
+    private grantGet;
+    private runStart;
+    /** An isolated run's root folder on a guest (`appSpace(app).nodes/<run id>`, apps root `/apps`). */
+    private isolatedRoot;
+    private runMessage;
+    private question;
+    private memoryStore;
+    private memoryVisible;
+    private memoryList;
+    private providerEntry;
+    private providerTools;
+    private providerCall;
+}