@userreason/cli 0.1.0 → 0.2.0

package/dist/client.js

@@ -1,7 +1,10 @@
 import { randomUUID } from "node:crypto";
 import { object, string, uuid, workspace, site, grantRequest } from "./contracts.js";
-import { refresh } from "./workos.js";
+import { refresh, AuthenticationError } from "./workos.js";
 import { withSessionLock } from "./lock.js";
+import { fetchWithErrors } from './errors.js';
+/** What the dashboard reads beside records: results, the response feed, users, events and members. */
+export const READ_OPERATIONS = ['workspace.ai', 'conversation.transcript', 'insights.conversations', 'insights.overview', 'insights.prompt', 'insights.experiments', 'insights.breakdown', 'responses.list', 'users.list', 'users.get', 'users.eligibility', 'prompts.validate', 'prompts.history', 'events.overview', 'site.activity', 'members.list'];
 export class ApiError extends Error {
     status;
     code;
@@ -24,27 +27,48 @@ export class UserReasonClient {
         this.options = options;
         this.fetcher = options.fetcher ?? fetch;
     }
-    async token(forceRefresh = false, previous) {
-        const lock = this.options.lock ?? ((operation) => withSessionLock(this.config, operation));
-        return lock(async () => {
+    async token(forceRefresh = false, previous, signal) {
+        const read = async () => {
+            signal?.throwIfAborted();
             const current = await this.credentials.load();
             if (!current)
-                throw new Error("Run userreason login first");
+                throw new AuthenticationError('login_required', 'Run userreason login --open first. Existing Keychain logins can be used with --credential-store keychain.');
             if (current.apiUrl !== this.config.apiUrl || current.clientId !== this.config.clientId)
                 throw new Error("Stored login belongs to a different environment or WorkOS client");
-            if (current.expiresAt > Date.now() + 60_000 && (!forceRefresh || current.accessToken !== previous))
+            return current;
+        };
+        const usable = (session) => session.expiresAt > Date.now() + 60_000 && (!forceRefresh || session.accessToken !== previous);
+        const initial = await read();
+        if (usable(initial))
+            return initial;
+        if (initial.accessToken.startsWith('ur-install.'))
+            throw new AuthenticationError('installation_expired', 'Installation access expired or was revoked; rerun the wizard to reconnect');
+        const lock = this.options.lock ?? ((operation) => withSessionLock(this.config, operation));
+        return lock(async () => {
+            const current = await read();
+            if (usable(current))
                 return current;
-            return refresh(this.config, this.credentials, current, this.fetcher);
+            if (current.accessToken.startsWith('ur-install.'))
+                throw new AuthenticationError('installation_expired', 'Installation access expired or was revoked; rerun the wizard to reconnect');
+            return refresh(this.config, this.credentials, current, this.fetcher, signal);
         });
     }
-    async request(path, body) {
+    async request(path, body, signal) {
+        return this.authenticatedRequest(path, body === undefined ? undefined : JSON.stringify(body), 'application/json', signal);
+    }
+    async authenticatedRequest(path, body, contentType, signal) {
         if (!path.startsWith("/onboarding/v1/") || path.includes("//") || path.includes("\\"))
             throw new Error("Invalid UserReason API path");
-        let session = await this.token();
+        // Planning may use the API's full 40-second deadline. One transport budget
+        // also bounds authentication refresh; cancellation must survive a retry.
+        const requestSignal = AbortSignal.any([AbortSignal.timeout(path === '/onboarding/v1/planning/analyze' ? 45_000 : 20_000), ...(signal ? [signal] : [])]);
+        requestSignal.throwIfAborted();
+        let session = await this.token(false, undefined, requestSignal);
         for (let attempt = 0; attempt < 2; attempt++) {
-            const response = await this.fetcher(this.config.apiUrl + path, { method: body === undefined ? "GET" : "POST", redirect: "error", headers: { Authorization: `Bearer ${session.accessToken}`, "x-ur-client": "cli", "Content-Type": "application/json" }, ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: AbortSignal.timeout(20_000) });
+            requestSignal.throwIfAborted();
+            const response = await fetchWithErrors(this.fetcher, this.config.apiUrl + path, { method: body === undefined ? "GET" : "POST", redirect: "error", headers: { Authorization: `Bearer ${session.accessToken}`, "x-ur-client": "cli", "Content-Type": contentType }, ...(body === undefined ? {} : { body: body }), signal: requestSignal }, 'UserReason API request');
             if (response.status === 401 && attempt === 0) {
-                session = await this.token(true, session.accessToken);
+                session = await this.token(true, session.accessToken, requestSignal);
                 continue;
             }
             let result;
@@ -73,6 +97,23 @@ export class UserReasonClient {
         }
         throw new ApiError(401, "authentication_required");
     }
+    async previewCaptures(workspaceId, siteId, forUpload = false) {
+        const query = new URLSearchParams({ workspace_id: uuid(workspaceId), site_id: uuid(siteId) });
+        if (forUpload)
+            query.set('intent', 'upload');
+        return this.request(`/onboarding/v1/dev/preview/captures?${query}`);
+    }
+    async uploadPreview(workspaceId, siteId, name, html) {
+        if (!name.trim() || name.length > 100)
+            throw new Error('Capture name must contain 1–100 characters');
+        if (!html.byteLength || html.byteLength > 4 * 1024 * 1024)
+            throw new Error('Capture must be between 1 byte and 4 MiB');
+        const query = new URLSearchParams({ workspace_id: uuid(workspaceId), site_id: uuid(siteId), name: name.trim() });
+        return this.authenticatedRequest(`/onboarding/v1/dev/preview/captures?${query}`, html, 'text/html; charset=utf-8');
+    }
+    async deletion(operation, input) {
+        return this.request(`/onboarding/v1/deletions/${operation}`, input);
+    }
     async account() {
         const data = object(await this.request("/onboarding/v1/account"), "account"), user = object(data.user, "user");
         uuid(string(user.id, "user ID"));
@@ -92,35 +133,117 @@ export class UserReasonClient {
             throw new Error("Invalid site list");
         return items.map(site);
     }
+    async siteById(siteId) {
+        return site(await this.request(`/onboarding/v1/sites/${uuid(siteId)}`));
+    }
     async createSite(input) {
         if (!input.name.trim() || input.name.length > 240)
             throw new Error("Site name must contain 1–240 characters");
-        const value = object(await this.request("/onboarding/v1/sites", { request_id: uuid(input.requestId ?? randomUUID()), workspace_id: uuid(input.workspaceId), site_id: uuid(input.siteId ?? randomUUID()), name: input.name.trim(), environment: input.environment, allowed_origins: input.origins }), "site creation");
+        const value = object(await this.request("/onboarding/v1/sites", { request_id: uuid(input.requestId ?? randomUUID()), workspace_id: uuid(input.workspaceId), site_id: uuid(input.siteId ?? randomUUID()), name: input.name.trim(), environment: input.environment, allowed_origins: input.origins ?? [] }), "site creation");
         return site(value.site ?? value);
     }
     async requestGrant(input) {
-        if (!input.scopes.length || input.scopes.length > 7)
+        if (!input.scopes.length || input.scopes.length > 8)
             throw new Error("Request at least one supported permission");
-        return grantRequest(await this.request("/onboarding/v1/grants/request", { request_id: uuid(input.requestId ?? randomUUID()), workspace_id: input.workspaceId ? uuid(input.workspaceId) : null, site_ids: input.siteIds?.map(id => uuid(id)) ?? null, scopes: [...new Set(input.scopes)] }));
+        return grantRequest(await this.request("/onboarding/v1/grants/request", { request_id: uuid(input.requestId ?? randomUUID()), workspace_id: input.workspaceId ? uuid(input.workspaceId) : null, site_ids: input.siteIds?.map(id => uuid(id)) ?? null, ...(input.allWorkspaces ? { all_workspaces: true } : {}), ...(input.workspaceIds ? { workspace_ids: input.workspaceIds.map(id => uuid(id)) } : {}), scopes: [...new Set(input.scopes)] }));
     }
     async grantStatus(id) { return grantRequest(await this.request(`/onboarding/v1/grants/requests/${uuid(id)}`)); }
     /** The server parses the complete versioned command and derives authorization from the verified caller. */
     async command(input) {
         uuid(string(input.workspace_id, "workspace ID"));
         uuid(string(input.request_id, "request ID"));
-        if (typeof input.action !== "string" || !/^[a-z]+\.[a-z]+$/.test(input.action))
+        if (typeof input.action !== "string" || !/^[a-z]+(\.[a-z]+){1,2}$/.test(input.action))
             throw new Error("Command requires a supported resource.action");
         if (input.action === "workspace.create" || input.action === "site.create")
             throw new Error("Use workspace create or site create for authenticated onboarding");
         return this.request("/onboarding/v1/command", input);
     }
     async query(input) {
-        if (!["sites", "surveys", "campaigns", "events", "responses", "audits"].includes(input.resource))
+        if (!["sites", "surveys", "campaigns", "prompts", "audiences", "events", "event_capture", "responses", "audits"].includes(input.resource))
             throw new Error("Unsupported query resource");
+        if (input.promptId && input.resource !== 'responses')
+            throw new Error('A survey filter applies only to responses');
         const limit = input.limit ?? 50;
         if (!Number.isInteger(limit) || limit < 1 || limit > 100)
             throw new Error("Query limit must be an integer from 1 to 100");
-        return this.request("/onboarding/v1/query", { workspace_id: uuid(input.workspaceId), ...(input.siteId ? { site_id: uuid(input.siteId) } : {}), resource: input.resource, limit, ...(input.after ? { after: uuid(input.after) } : {}) });
+        return this.request("/onboarding/v1/query", { workspace_id: uuid(input.workspaceId), ...(input.siteId ? { site_id: uuid(input.siteId) } : {}), resource: input.resource, event_capture_mode: input.eventCaptureMode, event_collection_limits: input.eventCollectionLimits, limit, ...(input.after ? { after: uuid(input.after) } : {}), ...(input.id ? { id: uuid(input.id) } : {}), ...(input.promptId ? { prompt_id: uuid(input.promptId) } : {}) });
+    }
+    /** A read-only view of one workspace (members) or one of its sites (everything else). Empty values are left out. */
+    async read(operation, input) {
+        if (!READ_OPERATIONS.includes(operation))
+            throw new Error("Unsupported read operation");
+        const { workspaceId, siteId, ...rest } = input;
+        if (!['members.list', 'workspace.ai'].includes(operation) && !siteId)
+            throw new Error("This read requires a site");
+        if (rest.run_id !== undefined)
+            uuid(string(rest.run_id, 'Experiment run ID'));
+        if (rest.variant_id && !rest.run_id)
+            throw new Error('A variant filter requires an experiment run');
+        const body = { workspace_id: uuid(workspaceId), ...(operation === 'members.list' || !siteId ? {} : { site_id: uuid(siteId) }) };
+        for (const [key, value] of Object.entries(rest))
+            if (value !== undefined && value !== null && value !== '')
+                body[key] = value;
+        return this.request(`/onboarding/v1/read/${operation}`, body);
+    }
+    /** Workspace allowance settings and optional site product context; server enforces the caller's role. */
+    async updateWorkspaceAi(input) {
+        const allowed = new Set(['enabled', 'voice_enabled', 'monthly_limit_microusd', 'concurrent_limit', 'preview_daily_limit', 'product_context']);
+        if (!Object.keys(input.settings).length || Object.keys(input.settings).some(key => !allowed.has(key)))
+            throw new Error('AI settings require supported setting fields only');
+        if ('product_context' in input.settings && !input.siteId)
+            throw new Error('Product context requires a site');
+        return this.request('/onboarding/v1/workspace/ai/update', { ...input.settings, workspace_id: uuid(input.workspaceId), ...(input.siteId ? { site_id: uuid(input.siteId) } : {}) });
+    }
+    /** One site as stored, with its revision and frequency policy (null while it follows the starting values). */
+    async siteRecord(input) {
+        const page = object(await this.query({ ...input, resource: 'sites', id: input.siteId, limit: 1 }), 'sites');
+        const items = Array.isArray(page.items) ? page.items : [];
+        if (!items.length)
+            throw new ApiError(404, 'not_found');
+        return object(items[0], 'site');
+    }
+    async prompts(input) {
+        return this.query({ ...input, resource: 'prompts' });
+    }
+    async prompt(input) {
+        const page = object(await this.query({ ...input, resource: 'prompts', id: input.promptId, promptId: undefined, limit: 1 }), 'prompts');
+        if (!Array.isArray(page.items) || !page.items.length)
+            throw new Error('Survey unavailable in this workspace/site');
+        return object(page.items[0], 'prompt');
+    }
+    async promptCommand(input) {
+        if (!['create', 'update', 'publish', 'pause', 'resume', 'archive'].includes(input.action))
+            throw new Error('Unsupported survey action');
+        if (input.action !== 'create' && (!input.revision || !/^[1-9][0-9]{0,18}$/.test(input.revision) || BigInt(input.revision) > 9223372036854775807n))
+            throw new Error('Supply the current positive --revision from prompt get');
+        if ((input.action === 'create' || input.action === 'update') && !input.definition)
+            throw new Error('A complete survey definition JSON file is required');
+        return this.command({ action: `prompt.${input.action}`, workspace_id: uuid(input.workspaceId), site_id: uuid(input.siteId), prompt_id: uuid(input.promptId), request_id: uuid(input.requestId), ...(input.action !== 'create' ? { expected_revision: input.revision } : {}), ...(input.definition ? { definition: input.definition } : {}) });
+    }
+    /** Saved audiences: named conditions that several prompts of a site share. */
+    async audiences(input) {
+        return this.query({ ...input, resource: 'audiences' });
+    }
+    async audience(input) {
+        const page = object(await this.query({ ...input, resource: 'audiences', id: input.audienceId, limit: 1 }), 'audiences');
+        if (!Array.isArray(page.items) || !page.items.length)
+            throw new Error('Audience unavailable in this workspace/site');
+        return object(page.items[0], 'audience');
+    }
+    /**
+     * Create and update save a draft from `{ name, description, rule }`. Publish makes every prompt
+     * that names the audience follow the new version at once; read `used_by` first.
+     */
+    async audienceCommand(input) {
+        if (!['create', 'update', 'publish', 'discard', 'archive'].includes(input.action))
+            throw new Error('Unsupported audience action');
+        if (input.action !== 'create' && (!input.revision || !/^[1-9][0-9]{0,18}$/.test(input.revision) || BigInt(input.revision) > 9223372036854775807n))
+            throw new Error('Supply the current positive --revision from audience get');
+        const saves = input.action === 'create' || input.action === 'update';
+        if (saves && (!input.audience || typeof input.audience.name !== 'string' || !input.audience.rule || typeof input.audience.rule !== 'object'))
+            throw new Error('An audience JSON file with name, description and rule is required');
+        return this.command({ action: `audience.${input.action}`, workspace_id: uuid(input.workspaceId), site_id: uuid(input.siteId), audience_id: uuid(input.audienceId), request_id: uuid(input.requestId), ...(input.action !== 'create' ? { expected_revision: input.revision } : {}),
+            ...(saves ? { name: input.audience.name, description: input.audience.description ?? null, rule: input.audience.rule } : {}) });
     }
     async waitForGrant(id, options = {}) {
         const deadline = Date.now() + (options.timeoutMs ?? 300_000);

package/dist/config.d.ts

@@ -1,12 +1,16 @@
+export type CredentialStoreKind = 'file' | 'keychain';
 export interface ClientConfig {
     apiUrl: string;
     clientId: string;
+    credentialStore?: CredentialStoreKind;
 }
+export declare function credentialStoreKind(value: unknown): CredentialStoreKind;
 export declare const configDirectory: () => string;
 export declare function discoverAuthConfig(url: string, development?: boolean, fetcher?: typeof fetch): Promise<string>;
 export declare function resolveConfig(options?: {
     development?: boolean;
     apiUrl?: string;
     clientId?: string;
+    credentialStore?: string;
 }): Promise<ClientConfig>;
 export declare function saveConfig(config: ClientConfig, development?: boolean): Promise<void>;

package/dist/config.js

@@ -2,15 +2,25 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { apiUrl, object } from "./contracts.js";
+import { packageProfile } from "./profile.js";
+import { ConfigurationError, fetchWithErrors } from "./errors.js";
+export function credentialStoreKind(value) {
+    if (value === undefined)
+        return 'file';
+    if (value !== 'file' && value !== 'keychain')
+        throw new Error('Credential storage must be file or keychain (--credential-store or UR_CREDENTIAL_STORE)');
+    return value;
+}
 export const configDirectory = () => join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "userreason");
+function readConfigurationError(error) {
+    const invalid = error instanceof SyntaxError || (error instanceof Error && error.message.startsWith('Invalid '));
+    return new ConfigurationError(invalid ? 'invalid_config' : 'config_read_failed', invalid
+        ? 'Invalid UserReason user configuration; repair config.json in the user configuration directory.'
+        : `Unable to read UserReason configuration in ${configDirectory()}. Allow local read access; workspace grants are unrelated.`);
+}
 export async function discoverAuthConfig(url, development = false, fetcher = fetch) {
     let response;
-    try {
-        response = await fetcher(`${apiUrl(url)}/onboarding/v1/auth-config`, { headers: { Accept: "application/json" }, redirect: "error", signal: AbortSignal.timeout(10_000) });
-    }
-    catch {
-        throw new Error("Unable to discover UserReason authentication configuration. Check the API deployment or supply its public --client-id.");
-    }
+    response = await fetchWithErrors(fetcher, `${apiUrl(url)}/onboarding/v1/auth-config`, { headers: { Accept: "application/json" }, redirect: "error", signal: AbortSignal.timeout(10_000) }, 'Unable to discover UserReason authentication configuration');
     if (!response.ok)
         throw new Error(`UserReason authentication configuration is unavailable (${response.status}). Configure WorkOS in the Worker before running the wizard.`);
     if (!response.headers.get("content-type")?.toLowerCase().startsWith("application/json") || !response.body)
@@ -56,6 +66,7 @@ export async function discoverAuthConfig(url, development = false, fetcher = fet
     return config.client_id;
 }
 export async function resolveConfig(options = {}) {
+    options = { ...options, development: options.development ?? packageProfile().apiEnvironment === "development" };
     const environment = options.development ? "development" : "production";
     let saved = {};
     try {
@@ -64,25 +75,37 @@ export async function resolveConfig(options = {}) {
     }
     catch (error) {
         if (error.code !== "ENOENT")
-            throw new Error("Unable to read UserReason configuration");
+            throw readConfigurationError(error);
     }
     const url = apiUrl(options.apiUrl ?? process.env.UR_API_URL ?? (typeof saved.apiUrl === "string" ? saved.apiUrl : options.development ? "https://api-dev.userreason.com" : "https://api.userreason.com"));
-    const configured = options.clientId ?? (options.development ? process.env.UR_WORKOS_DEV_CLIENT_ID : undefined) ?? process.env.UR_WORKOS_CLIENT_ID ?? (typeof saved.clientId === "string" ? saved.clientId : undefined);
+    const configured = options.clientId ?? (options.development ? process.env.UR_WORKOS_DEV_CLIENT_ID : undefined) ?? process.env.UR_WORKOS_CLIENT_ID ?? (saved.apiUrl === url && typeof saved.clientId === "string" ? saved.clientId : undefined);
+    const storage = options.credentialStore ?? process.env.UR_CREDENTIAL_STORE ?? (saved.apiUrl === url ? saved.credentialStore : undefined);
+    const kind = credentialStoreKind(storage);
     const clientId = configured ?? await discoverAuthConfig(url, options.development);
     if (!/^client_[A-Za-z0-9]+$/.test(clientId))
         throw new Error("Set UR_WORKOS_CLIENT_ID or pass --client-id with the public WorkOS client ID. Never supply a WorkOS API key.");
-    return { apiUrl: url, clientId };
+    return { apiUrl: url, clientId, ...(storage === undefined ? {} : { credentialStore: kind }) };
 }
 export async function saveConfig(config, development = false) {
-    await mkdir(configDirectory(), { recursive: true, mode: 0o700 });
+    try {
+        await mkdir(configDirectory(), { recursive: true, mode: 0o700 });
+    }
+    catch {
+        throw new ConfigurationError('config_write_failed', `Unable to save UserReason configuration in ${configDirectory()}. Allow local write access to remember this login's API and credential store.`);
+    }
     let existing = {};
     try {
         existing = object(JSON.parse(await readFile(join(configDirectory(), "config.json"), "utf8")), "configuration");
     }
     catch (error) {
         if (error.code !== "ENOENT")
-            throw new Error("Unable to read UserReason configuration");
+            throw readConfigurationError(error);
     }
     existing[development ? "development" : "production"] = config;
-    await writeFile(join(configDirectory(), "config.json"), JSON.stringify(existing, null, 2) + "\n", { mode: 0o600 });
+    try {
+        await writeFile(join(configDirectory(), "config.json"), JSON.stringify(existing, null, 2) + "\n", { mode: 0o600 });
+    }
+    catch {
+        throw new ConfigurationError('config_write_failed', `Unable to save UserReason configuration in ${configDirectory()}. Allow local write access to remember this login's API and credential store.`);
+    }
 }

package/dist/contracts.d.ts

@@ -1,4 +1,4 @@
-export declare const SCOPES: readonly ["workspace:create", "workspace:read", "site:create", "site:read", "site:update", "survey:write", "campaign:publish"];
+export declare const SCOPES: readonly ["workspace:create", "workspace:read", "site:create", "site:read", "site:update", "survey:write", "campaign:publish", "resource:delete"];
 export type Scope = typeof SCOPES[number];
 export interface Workspace {
     id: string;
@@ -14,6 +14,16 @@ export interface Site {
     allowed_origins: string[];
     revision?: string;
 }
+export interface Grant {
+    id: string;
+    workspace_id: string | null;
+    all_workspaces?: boolean;
+    workspace_ids?: string[] | null;
+    site_ids: string[] | null;
+    scopes: Scope[];
+    expires_at: string;
+    revoked_at: string | null;
+}
 export interface Account {
     user: {
         id: string;
@@ -21,7 +31,7 @@ export interface Account {
         name?: string | null;
     };
     workspaces: Workspace[];
-    grants: unknown[];
+    grants: Grant[];
 }
 export interface GrantRequest {
     id: string;
@@ -48,7 +58,7 @@ export declare function object(value: unknown, label: string): Record<string, un
 export declare function string(value: unknown, label: string): string;
 export declare function uuid(value: string, label?: string): string;
 export declare function scope(value: string): Scope;
-export declare function apiUrl(value: string): string;
+export declare function apiUrl(value: string, label?: string): string;
 export declare function origin(value: string, environment: Site["environment"]): string;
 export declare function workspace(value: unknown): Workspace;
 export declare function site(value: unknown): Site;

package/dist/contracts.js

@@ -1,4 +1,4 @@
-export const SCOPES = ["workspace:create", "workspace:read", "site:create", "site:read", "site:update", "survey:write", "campaign:publish"];
+export const SCOPES = ["workspace:create", "workspace:read", "site:create", "site:read", "site:update", "survey:write", "campaign:publish", "resource:delete"];
 export function object(value, label) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         throw new Error(`Invalid ${label} response`);
@@ -19,12 +19,12 @@ export function scope(value) {
         throw new Error(`Unknown scope: ${value}`);
     return value;
 }
-export function apiUrl(value) {
+export function apiUrl(value, label = "API URL") {
     const url = new URL(value);
     if (url.username || url.password || url.search || url.hash || url.pathname !== "/")
-        throw new Error("API URL must be an origin without credentials, query or path");
+        throw new Error(`${label} must be an origin without credentials, query or path`);
     if (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))
-        throw new Error("API URL must use HTTPS; loopback HTTP is allowed for local development");
+        throw new Error(`${label} must use HTTPS; loopback HTTP is allowed for local development`);
     return url.origin;
 }
 export function origin(value, environment) {

package/dist/credentials.d.ts

@@ -1,3 +1,13 @@
-import type { Credentials } from "./contracts.js";
-import type { ClientConfig } from "./config.js";
+import type { Credentials } from './contracts.js';
+import { type ClientConfig } from './config.js';
+export declare class CredentialStoreError extends Error {
+    readonly code: 'native_addons_blocked' | 'unavailable' | 'read_failed' | 'write_failed' | 'delete_failed' | 'invalid_session' | 'lock_failed' | 'lock_timeout';
+    constructor(code: 'native_addons_blocked' | 'unavailable' | 'read_failed' | 'write_failed' | 'delete_failed' | 'invalid_session' | 'lock_failed' | 'lock_timeout', message: string);
+}
+export declare const credentialAccount: (config: ClientConfig) => string;
+export declare const credentialFile: (config: ClientConfig) => string;
+/** Reads never create a directory or lock. Atomic replacement prevents partial session reads. */
+export declare function fileCredentials(config: ClientConfig): Credentials;
+/** An explicit Keychain choice never silently falls back to plaintext. */
+export declare function resolveCredentials(config: ClientConfig): Credentials;
 export declare function keychainCredentials(config: ClientConfig): Credentials;

package/dist/credentials.js

@@ -1,13 +1,95 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { configDirectory, credentialStoreKind } from './config.js';
+export class CredentialStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export const credentialAccount = (config) => createHash('sha256').update(`${config.apiUrl}\n${config.clientId}`).digest('hex');
+export const credentialFile = (config) => join(configDirectory(), 'credentials', `${credentialAccount(config)}.json`);
+function parseSession(serialized, config) {
+    try {
+        const value = JSON.parse(serialized);
+        if (!value || value.apiUrl !== config.apiUrl || value.clientId !== config.clientId ||
+            !['accessToken', 'refreshToken', 'userId', 'email'].every(key => typeof value[key] === 'string') ||
+            !value.accessToken || !value.refreshToken || !Number.isFinite(value.expiresAt))
+            throw new Error();
+        // Only persist known credential fields, never arbitrary configuration or properties.
+        const { accessToken, refreshToken, expiresAt, userId, email, apiUrl, clientId } = value;
+        return { accessToken, refreshToken, expiresAt, userId, email, apiUrl, clientId };
+    }
+    catch {
+        throw new CredentialStoreError('invalid_session', 'Invalid stored UserReason session for this API/client; run userreason logout, then login again using the same credential store.');
+    }
+}
+/** Reads never create a directory or lock. Atomic replacement prevents partial session reads. */
+export function fileCredentials(config) {
+    const path = credentialFile(config);
+    return {
+        async load() {
+            let serialized;
+            try {
+                serialized = await readFile(path, 'utf8');
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    return null;
+                throw new CredentialStoreError('read_failed', `Unable to read UserReason credentials at ${path}. Allow local read access; workspace grants are unrelated.`);
+            }
+            return parseSession(serialized, config);
+        },
+        async save(session) {
+            const serialized = JSON.stringify(parseSession(JSON.stringify(session), config)) + '\n';
+            const temporary = `${path}.${randomUUID()}.tmp`;
+            try {
+                await mkdir(join(configDirectory(), 'credentials'), { recursive: true, mode: 0o700 });
+                const handle = await open(temporary, 'wx', 0o600);
+                try {
+                    await handle.writeFile(serialized, 'utf8');
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+                await rename(temporary, path);
+            }
+            catch {
+                throw new CredentialStoreError('write_failed', `Unable to save UserReason credentials at ${path}. Login and token refresh require local write access; the previous file is retained if replacement fails.`);
+            }
+            finally {
+                await rm(temporary, { force: true }).catch(() => { });
+            }
+        },
+        async clear() {
+            try {
+                await rm(path, { force: true });
+            }
+            catch {
+                throw new CredentialStoreError('delete_failed', `Unable to remove UserReason credentials at ${path}. Allow local write access and retry logout.`);
+            }
+        },
+    };
+}
+/** An explicit Keychain choice never silently falls back to plaintext. */
+export function resolveCredentials(config) {
+    return credentialStoreKind(config.credentialStore ?? process.env.UR_CREDENTIAL_STORE) === 'keychain' ? keychainCredentials(config) : fileCredentials(config);
+}
+const absent = (error) => /No entry|NoEntry|No matching entry found in secure storage|not found|not exist/i.test(String(error.message));
 export function keychainCredentials(config) {
-    const account = createHash("sha256").update(`${config.apiUrl}\n${config.clientId}`).digest("hex");
+    const account = credentialAccount(config);
     async function entry() {
+        if (process.permission && !process.permission.has('addons'))
+            throw new CredentialStoreError('native_addons_blocked', 'The Node permission policy blocks the native module required for OS credential storage.');
         try {
-            const { Entry } = await import("@napi-rs/keyring");
-            return new Entry("com.userreason.cli", account, { linux: { store: "secret-service" } });
+            const { Entry } = await import('@napi-rs/keyring');
+            return new Entry('com.userreason.cli', account, { linux: { store: 'secret-service' } });
         }
         catch {
-            throw new Error("UserReason cannot access the OS credential store. Enable macOS Keychain, Windows Credential Manager or Linux Secret Service; credentials will not be written to a plaintext file.");
+            throw new CredentialStoreError('unavailable', 'UserReason cannot access the selected OS credential store. Enable macOS Keychain, Windows Credential Manager or Linux Secret Service and install the optional @napi-rs/keyring dependency. To choose file storage explicitly, run login --credential-store file; no plaintext fallback was used.');
         }
     }
     return {
@@ -17,34 +99,36 @@ export function keychainCredentials(config) {
                 serialized = (await entry()).getPassword();
             }
             catch (error) {
-                if (/No entry|NoEntry|not found|not exist/i.test(String(error.message)))
+                if (error instanceof CredentialStoreError)
+                    throw error;
+                if (absent(error))
                     return null;
-                throw new Error("Unable to read the UserReason OS credential-store entry");
+                throw new CredentialStoreError('read_failed', 'Unable to read the UserReason OS credential-store entry');
             }
             if (!serialized)
                 return null;
+            return parseSession(serialized, config);
+        },
+        async save(session) {
             try {
-                const session = JSON.parse(serialized);
-                if (session.apiUrl !== config.apiUrl || session.clientId !== config.clientId || typeof session.accessToken !== "string" || typeof session.refreshToken !== "string" || typeof session.expiresAt !== "number")
-                    throw new Error();
-                return session;
+                (await entry()).setPassword(JSON.stringify(session));
             }
-            catch {
-                throw new Error("Invalid stored UserReason session; run userreason logout, then login again");
+            catch (error) {
+                if (error instanceof CredentialStoreError)
+                    throw error;
+                throw new CredentialStoreError('write_failed', 'Unable to save the UserReason session in the OS credential store');
+            }
+        },
+        async clear() {
+            try {
+                (await entry()).deletePassword();
+            }
+            catch (error) {
+                if (error instanceof CredentialStoreError)
+                    throw error;
+                if (!absent(error))
+                    throw new CredentialStoreError('delete_failed', 'Unable to remove the UserReason OS credential-store entry');
             }
         },
-        async save(session) { try {
-            (await entry()).setPassword(JSON.stringify(session));
-        }
-        catch {
-            throw new Error("Unable to save the UserReason session in the OS credential store");
-        } },
-        async clear() { try {
-            (await entry()).deletePassword();
-        }
-        catch (error) {
-            if (!/No entry|NoEntry|not found|not exist/i.test(String(error.message)))
-                throw new Error("Unable to remove the UserReason OS credential-store entry");
-        } },
     };
 }

package/dist/docs.d.ts

@@ -0,0 +1,51 @@
+import type { Fetch } from "./workos.js";
+export declare const DOCS_URL = "https://docs.userreason.com";
+export interface DocsSearchResult {
+    title: string;
+    heading: string | null;
+    url: string;
+    markdown_url: string;
+    package?: string;
+    version?: string;
+    since?: string;
+    passage: string;
+}
+export interface DocsSearch {
+    query: string;
+    results: DocsSearchResult[];
+    source?: 'bundled';
+    warning?: {
+        code: string;
+        message: string;
+    };
+}
+export interface DocsPage {
+    url: string;
+    markdown: string;
+    tokens?: number;
+    source?: 'bundled';
+}
+export interface DocsOptions {
+    origin?: string;
+    fetcher?: Fetch;
+    offline?: boolean;
+    live?: boolean;
+}
+export declare class DocsError extends Error {
+    code: string;
+    status?: number | undefined;
+    constructor(code: string, message: string, status?: number | undefined);
+}
+export declare const docsUrl: (value: string) => string;
+export declare function searchDocs(input: DocsOptions & {
+    query: string;
+    limit?: number;
+}): Promise<DocsSearch>;
+/** Accepts a page address or path. Search results name the public site, so its addresses are read from the selected origin. */
+export declare function docsPageUrl(target: string, origin?: string): string;
+export declare function getDocsPage(input: DocsOptions & {
+    target: string;
+}): Promise<DocsPage>;
+/** Terminal output keeps line breaks and tabs and drops other control characters. */
+export declare const printable: (text: string) => string;
+export declare function formatDocsSearch(found: DocsSearch): string;