@crouter/sdk 0.3.377

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+export { Crouter as default, Crouter } from './client.js';
+export type { CrouterOptions } from './client.js';
+export { NodeStream } from './resources/node-stream.js';
+export { RunStream } from './resources/run-stream.js';
+export { CustomObjects } from './resources/custom-objects.js';
+export type { CustomDeliveryStream, ReceiveOptions } from './resources/custom-objects.js';
+export type { RunEvent, RunEventListener, RunEventOf, RunEventType, UnknownRunEvent } from './resources/run-stream.js';
+export { RunReply } from './resources/run-reply.js';
+export type { RunReplyCollectOptions, RunReplyEnding, RunReplyEvent, RunReplyResult, SentRunMessage } from './resources/run-reply.js';
+export type { AppProfile, RunActivity, RunDeleteResult, RunObject, RunParsedOutcome, RunParseOptions, RunParseParams, RunStartParams, RunStartResult, RunStatus, RunTrace } from './resources/runs.js';
+export type { FileDownloadOptions } from './resources/files.js';
+export type { Upload, UploadCreateParams } from './resources/uploads.js';
+export type { AttachmentLink } from './resources/attachments.js';
+export type { Share, ShareCreated, ShareCreateParams } from './resources/shares.js';
+export type { MemoryDocument, MemoryGetParams, MemoryListItem, MemoryListPage, MemoryListParams } from './resources/memory.js';
+export type { Question, QuestionAnswered, QuestionFields, QuestionResponses, QuestionSlot, QuestionStatus } from './resources/questions.js';
+export type { ProviderToolEntry } from './resources/providers.js';
+export { OAuth2Client, MemoryConnectionStore, profileFromClaims } from './oauth/index.js';
+export { refreshRefusal } from './oauth/index.js';
+export type { RefreshFailure, RefreshRefusal } from './oauth/index.js';
+export { generateKeyPair } from './oauth/keygen.js';
+export { parsePrivateJwk, privateKeyFromFile } from './oauth/keygen.js';
+export type { AuthorizeNonce, Connection, ConnectionStore, Identity, OAuth2Options } from './oauth/index.js';
+export type { IdTokenClaims } from '@crouter/identity';
+export { cursorFromRequest, forwardRunEvents } from './resources/forward.js';
+export type { NodeStreamEvent, NodeStreamEventListener, NodeStreamEventType } from './resources/node-stream.js';
+export { describeToolDefault, followActivity } from './resources/activity.js';
+export type { ActivityStep, DescribeTool } from './resources/activity.js';
+export { APIError, APIConnectionError, APIConnectionTimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, ConflictError, CrouterError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, UnprocessableEntityError, mapError, } from './errors.js';
+export { sdkErrorCodes } from './error-codes.js';
+export type { SdkErrorCode } from './error-codes.js';
+export type { AuthStatus, AuthStatusParams, CancelParams, EnsureProfileParams, JsonSchema, MessageParams, NodeCreateParams, NodeEventsOptions, NodeOutcomeOptions, OutputSchema, ParsedOutcome, RequestOptions, SchemaOutput, } from './types.js';
+export type * from '@crouter/api';

package/dist/index.js

@@ -0,0 +1,13 @@
+export { Crouter as default, Crouter } from './client.js';
+export { NodeStream } from './resources/node-stream.js';
+export { RunStream } from './resources/run-stream.js';
+export { CustomObjects } from './resources/custom-objects.js';
+export { RunReply } from './resources/run-reply.js';
+export { OAuth2Client, MemoryConnectionStore, profileFromClaims } from './oauth/index.js';
+export { refreshRefusal } from './oauth/index.js';
+export { generateKeyPair } from './oauth/keygen.js';
+export { parsePrivateJwk, privateKeyFromFile } from './oauth/keygen.js';
+export { cursorFromRequest, forwardRunEvents } from './resources/forward.js';
+export { describeToolDefault, followActivity } from './resources/activity.js';
+export { APIError, APIConnectionError, APIConnectionTimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, ConflictError, CrouterError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, UnprocessableEntityError, mapError, } from './errors.js';
+export { sdkErrorCodes } from './error-codes.js';

package/dist/keygen-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/keygen-cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runKeygen } from './keygen-command.js';
+runKeygen(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});

package/dist/keygen-command.d.ts

@@ -0,0 +1,6 @@
+export interface KeygenOptions {
+    /** How long `crtr cloud apps keys add` may run before keygen gives up. */
+    crtrTimeoutMs?: number;
+}
+/** The `crouter-sdk keygen` command. Returns the process exit code. */
+export declare function runKeygen(argv: string[], options?: KeygenOptions): Promise<number>;

package/dist/keygen-command.js

@@ -0,0 +1,157 @@
+import { execFile } from 'node:child_process';
+import { mkdir, open, unlink } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { createInterface } from 'node:readline';
+import { generateKeyPair } from './oauth/keygen.js';
+const USAGE = 'Usage: crouter-sdk keygen [--out <path>] [--app <client id>] [--yes]';
+const CRTR_TIMEOUT_MS = 60_000;
+function parseArgs(args) {
+    if (args[0] !== 'keygen')
+        throw new Error(USAGE);
+    const parsed = { path: 'local/app-key.json', yes: false };
+    const seen = new Set();
+    for (let i = 1; i < args.length; i++) {
+        const flag = args[i];
+        if (seen.has(flag))
+            throw new Error(USAGE);
+        seen.add(flag);
+        if (flag === '--yes') {
+            parsed.yes = true;
+            continue;
+        }
+        const value = args[++i];
+        if ((flag !== '--out' && flag !== '--app') || !value || value.startsWith('--'))
+            throw new Error(USAGE);
+        if (flag === '--out')
+            parsed.path = value;
+        else
+            parsed.app = value;
+    }
+    return parsed;
+}
+const manualSteps = (path) => [
+    'Next, in this order:',
+    "  1. Add the public JWK printed on stdout as a key: click Add key on your app's Sign-in tab in the console, or paste it under Register an app for a new app. Adding a key never replaces your current one.",
+    `  2. Then point your app's privateKey at ${path} and deploy.`,
+    '  3. Once a real sign-in works, retire the old key on the Sign-in tab.',
+];
+const addedSteps = (path, app) => [
+    'Next, in this order:',
+    `  1. Point your app's privateKey at ${path} and deploy.`,
+    '  2. Check that a real sign-in works.',
+    `  3. Retire the old key: on the app's Sign-in tab, or \`crtr cloud apps keys retire --app-id ${app} --kid <old kid>\` (\`crtr cloud apps keys list --app-id ${app}\` shows the kids).`,
+];
+const seconds = (ms) => {
+    const n = Math.max(1, Math.round(ms / 1000));
+    return `${n} second${n === 1 ? '' : 's'}`;
+};
+const say = (lines) => console.error(lines.join('\n'));
+/** Asks on stderr; resolves true only for Enter or y/yes. End of input declines. */
+function confirm(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        let answered = false;
+        rl.on('close', () => { if (!answered) {
+            process.stderr.write('\n');
+            resolve(false);
+        } });
+        rl.question(`${question} `, (answer) => {
+            answered = true;
+            rl.close();
+            resolve(/^(y|yes)?$/i.test(answer.trim()));
+        });
+    });
+}
+const parseJson = (text) => {
+    try {
+        return JSON.parse(text.trim());
+    }
+    catch {
+        return undefined;
+    }
+};
+const lastLine = (text) => text.split('\n').map((line) => line.trim()).filter(Boolean).at(-1);
+/** The `message` of a JSON error that ends `text`, even when other lines (a warning, a notice) precede it. */
+const errorMessage = (text) => {
+    const body = parseJson(text.slice(text.lastIndexOf('\n{') + 1));
+    return typeof body?.message === 'string' && body.message ? body.message : undefined;
+};
+/** Runs `crtr cloud apps keys add` once: execFile, no shell, the caller's environment. */
+function addKey(app, publicJwk, timeoutMs) {
+    const argv = ['cloud', 'apps', 'keys', 'add', '--app-id', app, '--jwk', publicJwk, '--json'];
+    return new Promise((resolve) => {
+        execFile('crtr', argv, { timeout: timeoutMs, env: process.env, maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => {
+            const err = error;
+            if (err?.code === 'ENOENT')
+                return resolve({ kind: 'missing' });
+            if (err) {
+                const message = err.killed
+                    ? `crtr did not answer within ${seconds(timeoutMs)}.`
+                    : errorMessage(stdout) ?? errorMessage(stderr) ?? lastLine(stderr) ?? lastLine(stdout) ?? err.message;
+                return resolve({ kind: 'failed', message });
+            }
+            const answer = parseJson(stdout);
+            if (typeof answer?.kid !== 'string') {
+                return resolve({ kind: 'failed', message: `crtr answered without the added key: ${lastLine(stdout) ?? '(no output)'}` });
+            }
+            resolve({ kind: 'added', kid: answer.kid, created: answer.created !== false });
+        });
+    });
+}
+/** The `crouter-sdk keygen` command. Returns the process exit code. */
+export async function runKeygen(argv, options = {}) {
+    const { path, app, yes } = parseArgs(argv);
+    await mkdir(dirname(path), { recursive: true });
+    // Reserve the destination before generating or printing the public key; never truncate an existing key.
+    const file = await open(path, 'wx', 0o600).catch((error) => {
+        if (error.code === 'EEXIST')
+            throw new Error(`${path} already exists. Delete it or pass --out to write somewhere else.`);
+        throw error;
+    });
+    let publicJwk;
+    let kid;
+    try {
+        const pair = await generateKeyPair();
+        await file.writeFile(`${JSON.stringify(pair.privateJwk)}\n`);
+        ({ publicJwk, kid } = pair);
+    }
+    catch (error) {
+        await file.close();
+        await unlink(path);
+        throw error;
+    }
+    await file.close();
+    const publicLine = JSON.stringify(publicJwk);
+    console.error(`Saved the private key to ${path} (key id ${kid}). Keep it out of git.`);
+    console.log(publicLine);
+    if (!app) {
+        say([...manualSteps(path), 'Tip: pass --app <client id> to add the key with crtr.']);
+        return 0;
+    }
+    if (!yes) {
+        if (!process.stdin.isTTY || !process.stderr.isTTY) {
+            say(['Not adding the key: no terminal to confirm. Pass --yes to add it with crtr.', ...manualSteps(path)]);
+            return 0;
+        }
+        if (!(await confirm(`Add this key to ${app} as an additional key? Your current key keeps working. [Y/n]`))) {
+            say(manualSteps(path));
+            return 0;
+        }
+    }
+    const outcome = await addKey(app, publicLine, options.crtrTimeoutMs ?? CRTR_TIMEOUT_MS);
+    if (outcome.kind === 'missing') {
+        say(["Couldn't find crtr, so the key was not added.", ...manualSteps(path)]);
+        return 0;
+    }
+    if (outcome.kind === 'failed') {
+        say([`Couldn't add the key: ${outcome.message}`, ...manualSteps(path)]);
+        return 2;
+    }
+    say([
+        outcome.created
+            ? `Added key ${outcome.kid} to ${app} as an additional key. Your current key still works.`
+            : `Key ${outcome.kid} is already on ${app}.`,
+        ...addedSteps(path, app),
+    ]);
+    return 0;
+}

package/dist/oauth/index.d.ts

@@ -0,0 +1,147 @@
+import { type JWK } from 'jose';
+import { type IdTokenClaims } from '@crouter/identity';
+import { Crouter } from '../client.js';
+/**
+ * Why the directory refused a connection's refresh token, and what it 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; drop the dead connection and ask them to sign in again.
+ */
+export type RefreshRefusal = 'removed' | 'paused' | 'reconnect';
+/** What a refused refresh means (`RefreshRefusal`), or `null` when `error` is not the directory refusing one.
+ *  Takes any error a connected client or `refresh` threw; only `APIError` with `origin: 'directory'` counts. */
+export declare function refreshRefusal(error: unknown): RefreshRefusal | null;
+/** One connection `refreshIdleConnections` could not refresh. `reason` is `refreshRefusal(error)`. */
+export interface RefreshFailure {
+    userId: string;
+    error: unknown;
+    reason: RefreshRefusal | null;
+}
+export interface Connection {
+    userId: string;
+    runtimeUrl: string;
+    refreshToken: string;
+    grantId: string;
+    accessToken: string;
+    accessTokenExpiresAt: number;
+    idToken?: string;
+}
+export interface ConnectionStore {
+    load(userId: string): Promise<Connection | null>;
+    save(connection: Connection): Promise<void>;
+    lock?<T>(userId: string, fn: () => Promise<T>): Promise<T>;
+    /** Connections last saved before this instant. A save must update the store's activity timestamp. */
+    listStale?(before: Date): Promise<Connection[]>;
+}
+export declare class MemoryConnectionStore implements ConnectionStore {
+    private readonly connections;
+    private readonly locks;
+    private readonly savedAt;
+    load(userId: string): Promise<Connection | null>;
+    save(connection: Connection): Promise<void>;
+    listStale(before: Date): Promise<Connection[]>;
+    lock<T>(userId: string, fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * A person's crouter cloud identity from a sign-in-only (`openid`, `openid email`, `openid profile`, or `openid email profile`) request, read from an
+ * ID token the SDK verified: ES256 signature against the directory's JWKS, `iss`, `aud` = the client id,
+ * `exp`, and the `nonce` from `authorizeUrl`. It is not a connection: it holds no runtime URL, refresh
+ * token, or grant, and nothing can be called on the person's runtime with it.
+ */
+export interface Identity {
+    /** The person's crouter cloud user id (`user:<id>`), the same `sub` a `Connection.userId` carries. */
+    sub: string;
+    /** Present only when `email` was requested and approved. */
+    email?: string;
+    emailVerified?: boolean;
+    /** Present only when `profile` was requested and approved and the person has a name (a phone-only account has none). The full name, e.g. `Sam Rivera`. */
+    name?: string;
+    givenName?: string;
+    familyName?: string;
+    /** Present only when `profile` was requested and approved and the ID token carries an https `picture` (the person's Google photo URL). An account with no photo has none; show initials then. */
+    picture?: string;
+    /** Every verified ID token claim. */
+    claims: IdTokenClaims;
+}
+/** `authorizeUrl`'s nonce: `string` when the scopes are known to include `openid`, `undefined` when known not to, else either. */
+export type AuthorizeNonce<S extends readonly string[]> = string extends S[number] ? string | undefined : 'openid' extends S[number] ? string : undefined;
+/** The `profile` claims a verified ID token carries, each only when present: use it on `Connection.idToken` after `verifyIdToken` for a sign-in that requested runtime scopes (`exchangeCode`), as `exchangeIdentity` does for a sign-in-only one. */
+export declare function profileFromClaims(claims: IdTokenClaims): Pick<Identity, 'name' | 'givenName' | 'familyName' | 'picture'>;
+export interface OAuth2Options {
+    clientId: string;
+    privateKey: string | JWK;
+    keyId?: string;
+    redirectUri: string;
+    issuer: string;
+    fetch?: typeof fetch;
+}
+export declare class OAuth2Client {
+    private readonly options;
+    private readonly issuer;
+    private readonly fetcher;
+    private jwks?;
+    private discoveryPromise?;
+    private readonly inFlight;
+    constructor(options: OAuth2Options);
+    private discovery;
+    /** Start a sign-in. When `scopes` includes `openid` the result carries the `nonce` to pass to the exchange; with literal scopes its type is `string`.
+     * `prompt: 'consent'` makes the directory show its consent screen even when the person already approved these scopes. */
+    authorizeUrl<const S extends readonly string[]>({ scopes, state, codeVerifier, prompt }: {
+        scopes: S;
+        state: string;
+        codeVerifier?: string;
+        prompt?: 'consent';
+    }): Promise<{
+        url: string;
+        codeVerifier: string;
+        state: string;
+        nonce: AuthorizeNonce<S>;
+    }>;
+    /**
+     * Finish a sign-in that asked for runtime scopes and return the person's `Connection`. A sign-in-only
+     * request (`openid`, `openid email`, `openid profile`, or `openid email profile`) gets no connection from the directory; finish it with
+     * `exchangeIdentity`, which this method names when it receives such a response.
+     */
+    exchangeCode({ code, codeVerifier, state, expectedState, nonce }: {
+        code: string;
+        codeVerifier: string;
+        state: string;
+        expectedState: string;
+        nonce?: string;
+    }): Promise<Connection>;
+    /**
+     * Finish a sign-in-only request (`authorizeUrl` with scopes `openid` or `openid email`) and return the
+     * person's verified identity. There is no connection, refresh token, or runtime access on this path.
+     * `nonce` is the value `authorizeUrl` returned and is required. A response without an ID token, or with
+     * one that fails verification, throws `id_token_invalid`; a response carrying a runtime connection (the
+     * request asked for runtime scopes) throws `oauth_exchange_mismatch` and must be finished with `exchangeCode`.
+     */
+    exchangeIdentity({ code, codeVerifier, state, expectedState, nonce }: {
+        code: string;
+        codeVerifier: string;
+        state: string;
+        expectedState: string;
+        nonce: string;
+    }): Promise<Identity>;
+    /** Refresh a store's idle connections once. The app owns scheduling; failures remain visible to its worker,
+     *  each with `reason` set when the directory refused that connection's refresh (see `RefreshRefusal`). */
+    refreshIdleConnections(store: ConnectionStore, { olderThanMs }: {
+        olderThanMs: number;
+    }): Promise<{
+        refreshed: number;
+        failures: RefreshFailure[];
+    }>;
+    refresh(connection: Connection, store?: ConnectionStore): Promise<Connection>;
+    client(connection: Connection, store: ConnectionStore): Crouter;
+    /** Verify an ID token: ES256 signature against the discovered JWKS, `iss`, `aud` = client id, `exp`, and `nonce` when given. A token that fails any check throws `id_token_invalid`; a JWKS that can't be fetched or is malformed rethrows that error. */
+    verifyIdToken(idToken: string, { nonce }?: {
+        nonce?: string;
+    }): Promise<IdTokenClaims>;
+    revoke(connection: Connection): Promise<boolean>;
+    private tokenResponse;
+    private connectionFrom;
+    private post;
+}