@coswic/aipay 0.2.0 → 0.3.0

package/dist/commands/test.js

@@ -0,0 +1,162 @@
+/**
+ * `aipay test [--model <id>] [--no-open] [--timeout <s>] [--json]`
+ *
+ * The one check only a CLI can do end to end: a real sign-in through the AI-Pay
+ * authorization server on the registered loopback callback, then one chat completion
+ * on the user's behalf. The receipt in the response is the proof (and the Console's
+ * verify step turns green from the server-side facts). Tokens live in memory only.
+ */
+import { AIPayClient, AuthorizationError, ConnectError, createConnectUrl, getUserInfo, handleCallback, InsufficientBalanceError, } from '@coswic/aipay-sdk';
+import { flagBool, flagString } from '../args.js';
+import { openBrowser } from '../browser.js';
+import { GATE_ENV, gatedFetch, looksGated } from '../gate.js';
+import { parseCallback, portIsVariable, redirectUriFor, startLoopback } from '../loopback.js';
+import { CliError, EXIT } from '../output.js';
+import { readProject } from '../project.js';
+import { GATE_HINT } from '../remote.js';
+import { reportSetupEvent } from '../setup-events.js';
+export async function runTest(args, out, deps = {}) {
+    const env = deps.env ?? process.env;
+    const dir = flagString(args.flags, 'dir') ?? '.';
+    const project = readProject(dir);
+    if (!project)
+        throw new CliError('not_linked', 'this directory is not linked to an app — run `aipay init --app <client_id> ...` first', EXIT.problem);
+    const timeoutS = Number(flagString(args.flags, 'timeout') ?? '300');
+    const fetchImpl = gatedFetch(env);
+    const target = parseCallback(project.callback);
+    // 127.0.0.1: the authorization server ignores the port for loopback redirect URIs
+    // (RFC 8252 §7.3), so the CLI takes any free port and your dev server can keep running.
+    // localhost / explicit --port: bind exactly that port.
+    const portFlag = flagString(args.flags, 'port');
+    const bindPort = portFlag ? Number(portFlag) : portIsVariable(target) ? 0 : target.port;
+    const loop = await startLoopback({ ...target, port: bindPort }, { timeoutMs: timeoutS * 1000 }).catch((e) => {
+        if (e.code === 'EADDRINUSE')
+            throw new CliError('port_busy', `port ${bindPort} is in use — stop what is listening there, or pass --port <free port>`, EXIT.problem);
+        throw e;
+    });
+    const redirectUri = redirectUriFor(target, loop.port);
+    const cfg = { hydraPublicUrl: project.auth_origin, clientId: project.app.client_id, redirectUri };
+    const { url, state, codeVerifier } = await createConnectUrl(cfg);
+    const note = redirectUri === project.callback
+        ? ''
+        : ` (registered: ${project.callback}; the port is not compared for 127.0.0.1)`;
+    out.line('info', `listening on ${redirectUri}${note}`);
+    out.line('info', `sign in here (opens in your browser):\n\n  ${url}\n`);
+    deps.onAuthorizeUrl?.(url);
+    if (out.json)
+        out.debug(`authorize_url ${url}`); // --json keeps stdout for the result; drivers read this
+    if (flagBool(args.flags, 'open', true))
+        (deps.open ?? openBrowser)(url);
+    const result = {
+        ok: false,
+        app: project.app,
+        signin: null,
+        completion: null,
+    };
+    try {
+        const cb = await loop.waitForCallback;
+        let tokens;
+        try {
+            tokens = await handleCallback(cfg, cb.url, { state, codeVerifier }, { fetchImpl });
+        }
+        catch (e) {
+            if (e instanceof ConnectError)
+                throw new CliError('signin_failed', `sign-in failed: ${e.message}${e.body ? ` — ${e.body}` : ''}`, EXIT.remote);
+            throw e;
+        }
+        const user = await getUserInfo(cfg, tokens.accessToken, { fetchImpl });
+        result.signin = {
+            sub: user.sub,
+            email: user.email ?? null,
+            scope: tokens.scope,
+            expires_in: tokens.expiresInSeconds,
+        };
+        out.line('ok', `signed in: ${user.email ?? user.sub} (scope: ${tokens.scope || '—'})`);
+        const client = new AIPayClient({
+            baseUrl: project.api_base,
+            accessToken: tokens.accessToken,
+            fetchImpl,
+        });
+        let model = flagString(args.flags, 'model');
+        if (!model) {
+            const models = await client.models.list().catch((e) => {
+                throw new CliError('models', `cannot list models: ${e.message}`, EXIT.remote);
+            });
+            model = pickModel(models.map((m) => m.id));
+            if (!model)
+                throw new CliError('models', 'no sellable model right now — pass --model <id>', EXIT.remote);
+        }
+        out.line('info', `calling ${model} …`);
+        try {
+            const res = await client.chat.completions.create({
+                model,
+                messages: [{ role: 'user', content: 'Reply with exactly one word: pong' }],
+                max_tokens: 8,
+            });
+            const r = res.aipay;
+            const charged = r.total_charged_uusd ?? r.cost_uusd;
+            result.completion = {
+                model: res.model,
+                text: res.choices[0]?.message.content ?? '',
+                request_id: r.request_id,
+                usage_event_id: r.usage_event_id,
+                charged_uusd: charged,
+                currency: r.currency,
+                usage: res.usage,
+            };
+            result.ok = true;
+            out.line('ok', `receipt: request_id ${r.request_id}, charged ${formatUusd(charged)} ${r.currency}`);
+            // C2 setup session：登入狀態下回報 test 通過（伺服器本來就看得到回執；這條是給 Console 的時間戳）
+            await reportSetupEvent(project.app.client_id, 'cli.test', { request_id: r.request_id, model: res.model, ok: true }, out, env);
+            out.line('ok', "done — the Console's verify step reads this from the server side");
+        }
+        catch (e) {
+            if (e instanceof InsufficientBalanceError) {
+                result.completion = { error: 'insufficient_balance' };
+                out.line('warn', 'signed in fine, but this account has no balance for a completion — top up in the Console and rerun');
+                await reportSetupEvent(project.app.client_id, 'cli.test', { ok: false, error_code: 'insufficient_balance' }, out, env);
+                out.result(result);
+                return EXIT.problem;
+            }
+            if (e instanceof AuthorizationError)
+                throw new CliError('unauthorized', `the API rejected the token: ${e.message}`, EXIT.remote);
+            throw e;
+        }
+        out.result(result);
+        return EXIT.ok;
+    }
+    catch (e) {
+        if (e instanceof CliError) {
+            result.error = { code: e.code, message: e.message };
+            out.line('bad', e.message);
+            // 顧問 §13.2：失敗也回報（error_code 進 Console 的驗證步與 setup 事件；best effort、無 token）
+            await reportSetupEvent(project.app.client_id, 'cli.test', { ok: false, error_code: e.code }, out, env);
+            out.result(result);
+            return e.exitCode;
+        }
+        const msg = e.message ?? String(e);
+        const gated = /404/.test(msg) && looksGated(404, '');
+        result.error = { code: 'failed', message: msg };
+        out.line('bad', gated ? `${msg}\n${GATE_HINT}` : msg);
+        if (!env[GATE_ENV])
+            out.line('info', `pilot: if this was a 404 with an empty body, export ${GATE_ENV} and retry`);
+        out.result(result);
+        return EXIT.remote;
+    }
+    finally {
+        await loop.close();
+    }
+}
+/** Cheapest sensible default: prefer a small/cheap model id if present, else the first. */
+export function pickModel(ids) {
+    if (!ids.length)
+        return null;
+    const cheap = ids.find((id) => /mini|flash|haiku|nano|small|8b|7b/i.test(id));
+    return cheap ?? ids[0];
+}
+export function formatUusd(uusd) {
+    const n = Number(uusd);
+    if (!Number.isFinite(n))
+        return `${uusd} µUSD`;
+    return `$${(n / 1_000_000).toFixed(6)}`;
+}

package/dist/commands/unlink.d.ts

@@ -0,0 +1,5 @@
+import { type ParsedArgs } from '../args.js';
+import { type Reporter } from '../output.js';
+export declare function runUnlink(args: ParsedArgs, out: Reporter): number;
+/** Drop our keys and the marker comment; keep everything else byte-for-byte. */
+export declare function stripEnvKeys(content: string, keys: string[]): string;

package/dist/commands/unlink.js

@@ -0,0 +1,73 @@
+/**
+ * `aipay unlink [--dir] [--dry-run] [--json]` — forgets the link: removes
+ * .aipay/project.json and our four keys from .env.local. Scaffolded code and the agent
+ * guide are the developer's files now; they are listed, not deleted.
+ */
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { flagBool, flagString } from '../args.js';
+import { EXIT } from '../output.js';
+import { ENV_FILE, ENV_KEYS, PROJECT_DIR, projectPath, readProject, VITE_ENV_KEYS, } from '../project.js';
+export function runUnlink(args, out) {
+    const dir = resolve(flagString(args.flags, 'dir') ?? '.');
+    const dryRun = flagBool(args.flags, 'dry-run');
+    const project = readProject(dir);
+    if (!project) {
+        out.line('info', 'nothing to unlink here');
+        out.result({ ok: true, unlinked: false, dir });
+        return EXIT.ok;
+    }
+    const removed = [];
+    const envPath = join(dir, ENV_FILE);
+    let envChanged = false;
+    if (existsSync(envPath)) {
+        const before = readFileSync(envPath, 'utf8');
+        const after = stripEnvKeys(before, [
+            ...Object.values(ENV_KEYS),
+            ...Object.values(VITE_ENV_KEYS),
+        ]);
+        envChanged = after !== before;
+        if (envChanged && !dryRun)
+            writeFileSync(envPath, after);
+    }
+    if (!dryRun) {
+        rmSync(projectPath(dir));
+        try {
+            rmSync(join(dir, PROJECT_DIR), { recursive: false });
+        }
+        catch {
+            /* not empty (e.g. .aipay/local/) — leave it */
+        }
+    }
+    removed.push('.aipay/project.json');
+    out.line('ok', `${dryRun ? 'would remove' : 'removed'} .aipay/project.json`);
+    if (envChanged)
+        out.line('ok', `${dryRun ? 'would strip' : 'stripped'} AIPAY_* from ${ENV_FILE}`);
+    if (project.scaffold.files.length)
+        out.line('info', `kept your files: ${project.scaffold.files.join(', ')}, aipay-agent.md`);
+    out.result({
+        ok: true,
+        unlinked: !dryRun,
+        dry_run: dryRun,
+        dir,
+        removed,
+        env_stripped: envChanged,
+        kept: project.scaffold.files,
+    });
+    return EXIT.ok;
+}
+/** Drop our keys and the marker comment; keep everything else byte-for-byte. */
+export function stripEnvKeys(content, keys) {
+    const set = new Set(keys);
+    const lines = content.split(/\r?\n/);
+    const kept = lines.filter((line) => {
+        if (line.startsWith('# AI-Pay (written by `aipay init`'))
+            return false;
+        const m = /^\s*(?:export\s+)?([A-Z0-9_]+)\s*=/.exec(line);
+        return !(m && set.has(m[1]));
+    });
+    // collapse a trailing blank run left behind by the removed block
+    while (kept.length > 1 && kept[kept.length - 1] === '' && kept[kept.length - 2] === '')
+        kept.pop();
+    return kept.join('\n');
+}

package/dist/detect.d.ts

@@ -0,0 +1,27 @@
+import type { Framework } from './project.js';
+export type PackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun';
+export interface Detection {
+    packageManager: PackageManager | null;
+    framework: Framework | null;
+    hasPackageJson: boolean;
+    typescript: boolean;
+    /** Whether @coswic/aipay-sdk is already a dependency. */
+    sdkInstalled: boolean;
+    /** `src/` exists → scaffold under it, else project root. */
+    srcDir: string;
+}
+export interface PackageJsonLike {
+    packageManager?: string;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+}
+export declare function detectPackageManager(pkg: PackageJsonLike | null, lockfiles: {
+    pnpm: boolean;
+    yarn: boolean;
+    bun: boolean;
+    npm: boolean;
+}): PackageManager | null;
+export declare function detectFramework(pkg: PackageJsonLike | null): Framework | null;
+export declare function detectProject(dir: string): Detection;
+/** The install command for the detected manager (printed in --dry-run, run otherwise). */
+export declare function installCommand(pm: PackageManager, pkgName: string): string[];

package/dist/detect.js

@@ -0,0 +1,83 @@
+/**
+ * Project detection: package manager (from lockfile / packageManager field) and web
+ * framework (from dependencies). Pure functions over the file contents so they are
+ * unit-testable without a filesystem.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export function detectPackageManager(pkg, lockfiles) {
+    const pm = pkg?.packageManager;
+    if (typeof pm === 'string') {
+        const name = pm.split('@')[0];
+        if (name === 'pnpm' || name === 'npm' || name === 'yarn' || name === 'bun')
+            return name;
+    }
+    if (lockfiles.pnpm)
+        return 'pnpm';
+    if (lockfiles.bun)
+        return 'bun';
+    if (lockfiles.yarn)
+        return 'yarn';
+    if (lockfiles.npm)
+        return 'npm';
+    return pkg ? 'npm' : null;
+}
+export function detectFramework(pkg) {
+    if (!pkg)
+        return null;
+    const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    if ('next' in deps)
+        return 'next';
+    if ('hono' in deps)
+        return 'hono';
+    if ('fastify' in deps)
+        return 'fastify';
+    if ('express' in deps)
+        return 'express';
+    // Browser SPA (React/Vue/Svelte on Vite): PKCE runs in the browser; no server route to write.
+    // A project with both a server framework and Vite is treated as the server (routes win above).
+    if ('vite' in deps)
+        return 'vite';
+    return 'node';
+}
+export function detectProject(dir) {
+    const pkgPath = join(dir, 'package.json');
+    const hasPackageJson = existsSync(pkgPath);
+    let pkg = null;
+    if (hasPackageJson) {
+        try {
+            pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        }
+        catch {
+            pkg = null;
+        }
+    }
+    const lockfiles = {
+        pnpm: existsSync(join(dir, 'pnpm-lock.yaml')),
+        yarn: existsSync(join(dir, 'yarn.lock')),
+        bun: existsSync(join(dir, 'bun.lockb')) || existsSync(join(dir, 'bun.lock')),
+        npm: existsSync(join(dir, 'package-lock.json')),
+    };
+    const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+    return {
+        packageManager: detectPackageManager(pkg, lockfiles),
+        framework: detectFramework(pkg),
+        hasPackageJson,
+        typescript: 'typescript' in deps || existsSync(join(dir, 'tsconfig.json')),
+        sdkInstalled: '@coswic/aipay-sdk' in deps,
+        srcDir: existsSync(join(dir, 'src')) ? 'src' : '.',
+    };
+}
+/** The install command for the detected manager (printed in --dry-run, run otherwise). */
+export function installCommand(pm, pkgName) {
+    switch (pm) {
+        case 'pnpm':
+            return ['pnpm', 'add', pkgName];
+        case 'yarn':
+            return ['yarn', 'add', pkgName];
+        case 'bun':
+            return ['bun', 'add', pkgName];
+        default:
+            return ['npm', 'install', pkgName];
+    }
+}

package/dist/developer-api.d.ts

@@ -0,0 +1,14 @@
+import type { AuthStore, StoredAuth } from './auth-store.js';
+export interface ApiResult<T> {
+    status: number;
+    body: T;
+}
+export interface DeveloperApi {
+    auth: StoredAuth;
+    request<T = Record<string, unknown>>(method: string, path: string, opts?: {
+        body?: unknown;
+        headers?: Record<string, string>;
+    }): Promise<ApiResult<T>>;
+}
+export declare function openDeveloperApi(store: AuthStore, env?: NodeJS.ProcessEnv): Promise<DeveloperApi>;
+export declare function errorMessage(body: unknown, status: number): string;

package/dist/developer-api.js

@@ -0,0 +1,74 @@
+/**
+ * Calls to the developer management API with the developer's own token (audience
+ * aipay-developer-api). Refreshes once on 401 when a refresh token exists; the gate header
+ * comes from the environment like everywhere else.
+ */
+import { refreshAccessToken } from '@coswic/aipay-sdk';
+import { gatedFetch, looksGated } from './gate.js';
+import { CliError, EXIT } from './output.js';
+import { GATE_HINT } from './remote.js';
+export async function openDeveloperApi(store, env = process.env) {
+    let auth = store.load();
+    if (!auth)
+        throw new CliError('not_logged_in', 'not signed in — run `aipay login` first', EXIT.problem);
+    const f = gatedFetch(env);
+    if (auth.expires_at - 30_000 < Date.now())
+        auth = await refresh(store, auth, f);
+    const api = {
+        auth,
+        async request(method, path, opts = {}) {
+            const call = async (a) => f(new URL(path, a.api_base), {
+                method,
+                headers: {
+                    authorization: `Bearer ${a.access_token}`,
+                    ...(opts.body !== undefined ? { 'content-type': 'application/json' } : {}),
+                    ...(opts.headers ?? {}),
+                },
+                ...(opts.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
+            });
+            let res = await call(api.auth);
+            if (res.status === 401 && api.auth.refresh_token) {
+                api.auth = await refresh(store, api.auth, f);
+                res = await call(api.auth);
+            }
+            const text = await res.text();
+            if (looksGated(res.status, text))
+                throw new CliError('gated', GATE_HINT, EXIT.remote);
+            if (res.status === 401)
+                throw new CliError('unauthorized', 'the API rejected the developer token — run `aipay login` again', EXIT.remote);
+            let body = null;
+            try {
+                body = text ? JSON.parse(text) : null;
+            }
+            catch {
+                body = { raw: text.slice(0, 500) };
+            }
+            return { status: res.status, body: body };
+        },
+    };
+    return api;
+}
+async function refresh(store, auth, fetchImpl) {
+    if (!auth.refresh_token)
+        throw new CliError('expired', 'the developer token expired — run `aipay login` again', EXIT.problem);
+    const t = await refreshAccessToken({
+        hydraPublicUrl: auth.auth_origin,
+        clientId: auth.client_id,
+    }, auth.refresh_token, { fetchImpl }).catch(() => {
+        throw new CliError('expired', 'could not renew the developer token — run `aipay login` again', EXIT.problem);
+    });
+    const next = {
+        ...auth,
+        access_token: t.accessToken,
+        refresh_token: t.refreshToken ?? auth.refresh_token,
+        expires_at: Date.now() + t.expiresInSeconds * 1000,
+        scope: t.scope || auth.scope,
+    };
+    store.save(next);
+    return next;
+}
+export function errorMessage(body, status) {
+    const b = (body ?? {});
+    const msg = typeof b.message === 'string' ? b.message : typeof b.error === 'string' ? b.error : '';
+    return msg ? `${msg} (HTTP ${status})` : `HTTP ${status}`;
+}

package/dist/device.d.ts

@@ -0,0 +1,38 @@
+export declare const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+export interface DeviceAuthorization {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    /** Same URL with the user code embedded (RFC 8628 §3.3.1) when the server offers one. */
+    verificationUriComplete: string | null;
+    expiresInSeconds: number;
+    /** Minimum seconds between polls (server-suggested; slow_down adds 5s). */
+    intervalSeconds: number;
+}
+export interface DeviceTokens {
+    accessToken: string;
+    refreshToken: string | null;
+    expiresInSeconds: number;
+    scope: string;
+}
+export interface DeviceClientConfig {
+    authOrigin: string;
+    clientId: string;
+    scopes: string[];
+    audience: string;
+}
+/** POST /oauth2/device/auth — public client, so only client_id/scope/audience are sent. */
+export declare function requestDeviceCode(cfg: DeviceClientConfig, fetchImpl?: typeof fetch): Promise<DeviceAuthorization>;
+export interface PollOptions {
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** Called before each wait (progress dots for humans). */
+    onWait?: (secondsLeft: number) => void;
+}
+/**
+ * Poll POST /oauth2/token with the device grant until the developer approves, denies, or the
+ * code expires. `authorization_pending` → wait `interval`; `slow_down` → interval += 5s
+ * (RFC 8628 §3.5); anything else is final.
+ */
+export declare function pollDeviceToken(cfg: DeviceClientConfig, auth: DeviceAuthorization, opts?: PollOptions): Promise<DeviceTokens>;

package/dist/device.js

@@ -0,0 +1,122 @@
+/**
+ * RFC 8628 device authorization for `aipay login --device` (consultant §10.2, auth model A2):
+ * for machines without a browser (SSH boxes, containers, CI). The CLI asks the
+ * authorization server for a device code + a short user code, prints the verification
+ * URL and the code, then polls the token endpoint until the developer approves it in
+ * a browser on any device. No loopback listener, no ports.
+ */
+import { CliError, EXIT } from './output.js';
+export const DEVICE_CODE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+/** POST /oauth2/device/auth — public client, so only client_id/scope/audience are sent. */
+export async function requestDeviceCode(cfg, fetchImpl = fetch) {
+    const form = new URLSearchParams({
+        client_id: cfg.clientId,
+        scope: cfg.scopes.join(' '),
+        audience: cfg.audience,
+    });
+    let res;
+    try {
+        res = await fetchImpl(new URL('/oauth2/device/auth', cfg.authOrigin), {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: form.toString(),
+        });
+    }
+    catch (e) {
+        throw new CliError('network', `cannot reach ${cfg.authOrigin}: ${e.message}`, EXIT.remote);
+    }
+    const text = await res.text();
+    if (!res.ok) {
+        const err = parseOAuthError(text);
+        if (err?.error === 'invalid_grant' || err?.error === 'unauthorized_client')
+            throw new CliError('device_unsupported', 'this AI-Pay does not allow device sign-in for the CLI yet — use `aipay login` on a machine with a browser', EXIT.remote);
+        throw new CliError('remote', `device authorization failed: HTTP ${res.status} ${err?.error ?? ''} ${err?.error_description ?? ''}`.trim(), EXIT.remote);
+    }
+    const j = JSON.parse(text);
+    if (typeof j.device_code !== 'string' ||
+        typeof j.user_code !== 'string' ||
+        typeof j.verification_uri !== 'string')
+        throw new CliError('remote', 'unexpected device authorization response', EXIT.remote);
+    return {
+        deviceCode: j.device_code,
+        userCode: j.user_code,
+        verificationUri: j.verification_uri,
+        verificationUriComplete: typeof j.verification_uri_complete === 'string' ? j.verification_uri_complete : null,
+        expiresInSeconds: typeof j.expires_in === 'number' ? j.expires_in : 600,
+        intervalSeconds: typeof j.interval === 'number' && j.interval > 0 ? j.interval : 5,
+    };
+}
+/**
+ * Poll POST /oauth2/token with the device grant until the developer approves, denies, or the
+ * code expires. `authorization_pending` → wait `interval`; `slow_down` → interval += 5s
+ * (RFC 8628 §3.5); anything else is final.
+ */
+export async function pollDeviceToken(cfg, auth, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = opts.now ?? Date.now;
+    const deadline = now() + auth.expiresInSeconds * 1000;
+    let interval = auth.intervalSeconds;
+    for (;;) {
+        if (now() >= deadline)
+            throw new CliError('expired', 'the sign-in code expired — run `aipay login --device` again', EXIT.remote);
+        opts.onWait?.(Math.max(0, Math.round((deadline - now()) / 1000)));
+        await sleep(interval * 1000);
+        const form = new URLSearchParams({
+            grant_type: DEVICE_CODE_GRANT,
+            device_code: auth.deviceCode,
+            client_id: cfg.clientId,
+        });
+        let res;
+        try {
+            res = await fetchImpl(new URL('/oauth2/token', cfg.authOrigin), {
+                method: 'POST',
+                headers: { 'content-type': 'application/x-www-form-urlencoded' },
+                body: form.toString(),
+            });
+        }
+        catch {
+            continue; // transient network blip: keep polling until the deadline
+        }
+        const text = await res.text();
+        if (res.ok) {
+            const j = JSON.parse(text);
+            if (typeof j.access_token !== 'string')
+                throw new CliError('remote', 'token response missing access_token', EXIT.remote);
+            return {
+                accessToken: j.access_token,
+                refreshToken: typeof j.refresh_token === 'string' ? j.refresh_token : null,
+                expiresInSeconds: typeof j.expires_in === 'number' ? j.expires_in : 0,
+                scope: typeof j.scope === 'string' ? j.scope : cfg.scopes.join(' '),
+            };
+        }
+        const err = parseOAuthError(text);
+        switch (err?.error) {
+            case 'authorization_pending':
+                continue;
+            case 'slow_down':
+                interval += 5;
+                continue;
+            case 'expired_token':
+                throw new CliError('expired', 'the sign-in code expired — run `aipay login --device` again', EXIT.remote);
+            case 'access_denied':
+                throw new CliError('denied', 'sign-in was denied in the browser', EXIT.remote);
+            default:
+                throw new CliError('remote', `token endpoint returned ${res.status} ${err?.error ?? ''} ${err?.error_description ?? ''}`.trim(), EXIT.remote);
+        }
+    }
+}
+function parseOAuthError(text) {
+    try {
+        const j = JSON.parse(text);
+        return {
+            ...(typeof j.error === 'string' ? { error: j.error } : {}),
+            ...(typeof j.error_description === 'string'
+                ? { error_description: j.error_description }
+                : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/gate.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Pilot gate: during the closed pilot, non-public paths answer 404 with an empty body
+ * unless the request carries `X-AIPay-Gate: <token>` (or the browser cookie set by
+ * `/__gate/<token>`). The CLI only ever reads the token from the environment — it is
+ * never written to any file and never printed.
+ */
+export declare const GATE_ENV = "AIPAY_GATE_TOKEN";
+export declare function gateHeaders(env?: NodeJS.ProcessEnv): Record<string, string>;
+/** fetch wrapper that adds the gate header; passed to the SDK as `fetchImpl`. */
+export declare function gatedFetch(env?: NodeJS.ProcessEnv): typeof fetch;
+/** Explain a 404-with-empty-body in gate terms (the SDK/API otherwise say "not found"). */
+export declare function looksGated(status: number, bodyText: string): boolean;
+export declare const GATE_HINT = "AI-Pay answered 404 with an empty body \u2014 that is the pilot gate, not a missing route. Set AIPAY_GATE_TOKEN in your environment (the value is in the Console next to the app) and retry. Do not put it in code or version control.";

package/dist/gate.js

@@ -0,0 +1,29 @@
+/**
+ * Pilot gate: during the closed pilot, non-public paths answer 404 with an empty body
+ * unless the request carries `X-AIPay-Gate: <token>` (or the browser cookie set by
+ * `/__gate/<token>`). The CLI only ever reads the token from the environment — it is
+ * never written to any file and never printed.
+ */
+export const GATE_ENV = 'AIPAY_GATE_TOKEN';
+export function gateHeaders(env = process.env) {
+    const token = env[GATE_ENV];
+    return token ? { 'X-AIPay-Gate': token } : {};
+}
+/** fetch wrapper that adds the gate header; passed to the SDK as `fetchImpl`. */
+export function gatedFetch(env = process.env) {
+    const extra = gateHeaders(env);
+    if (!Object.keys(extra).length)
+        return fetch;
+    return (input, init) => {
+        const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+        for (const [k, v] of Object.entries(extra))
+            if (!headers.has(k))
+                headers.set(k, v);
+        return fetch(input, { ...init, headers });
+    };
+}
+/** Explain a 404-with-empty-body in gate terms (the SDK/API otherwise say "not found"). */
+export function looksGated(status, bodyText) {
+    return status === 404 && bodyText.trim() === '';
+}
+export const GATE_HINT = `AI-Pay answered 404 with an empty body — that is the pilot gate, not a missing route. Set ${GATE_ENV} in your environment (the value is in the Console next to the app) and retry. Do not put it in code or version control.`;