@north-light/sdk 0.0.0 → 0.3.415

package/dist/testing/cloud.d.ts

@@ -0,0 +1,228 @@
+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';
+    /**
+     * The clock every timestamp the fake writes reads, and the idempotency window runs on (default `Date.now`). Use
+     * `manualClock()` to step time. Stream idle, long-poll waits and run-notice retries stay on real timers.
+     */
+    clock?: {
+        now(): number;
+    };
+}
+/** `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 clock;
+    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>;
+    private activateState;
+    /**
+     * Make `userId`'s grant active with no stored connection, for an app that mints a per-user runtime token through
+     * the directory's `client_credentials` grant. Default scopes: `crtr:llm`, `crtr:act`.
+     */
+    activate(userId: string, options?: {
+        scopes?: FakeScope[];
+        dependencies?: Record<string, ProviderDependency>;
+    }): 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;
+    /** `grant_type=client_credentials` + `sub`: the directory's per-user runtime-token mint. The client assertion is not verified. */
+    private mint;
+    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;
+}