@coswic/aipay 0.2.0 → 0.4.0

package/dist/commands/session.js

@@ -0,0 +1,62 @@
+import { createAuthStore } from '../auth-store.js';
+import { openDeveloperApi } from '../developer-api.js';
+import { CliError, EXIT } from '../output.js';
+export async function runWhoami(_args, out, env = process.env) {
+    const store = createAuthStore(env);
+    const auth = store.load();
+    if (!auth) {
+        out.line('info', 'not signed in (run `aipay login --api <api base>`)');
+        out.result({ signed_in: false });
+        return EXIT.ok;
+    }
+    const api = await openDeveloperApi(store); // refreshes if needed
+    out.line('ok', `${api.auth.email ?? api.auth.sub} @ ${api.auth.api_base}`);
+    out.kv('scope', api.auth.scope || '—');
+    out.kv('expires', new Date(api.auth.expires_at).toISOString());
+    out.kv('store', store.where);
+    out.result({
+        signed_in: true,
+        api_base: api.auth.api_base,
+        email: api.auth.email,
+        sub: api.auth.sub,
+        scope: api.auth.scope,
+        expires_at: api.auth.expires_at,
+        store: store.kind,
+    });
+    return EXIT.ok;
+}
+export async function runLogout(_args, out, env = process.env) {
+    const store = createAuthStore(env);
+    const auth = store.load();
+    if (!auth) {
+        out.line('info', 'already signed out');
+        out.result({ ok: true, revoked: false });
+        return EXIT.ok;
+    }
+    // Best effort: revoke the refresh token (and with it the access token) at the authorization server.
+    let revoked = false;
+    const f = fetch;
+    for (const token of [auth.refresh_token, auth.access_token]) {
+        if (!token)
+            continue;
+        try {
+            const res = await f(new URL('/oauth2/revoke', auth.auth_origin), {
+                method: 'POST',
+                headers: { 'content-type': 'application/x-www-form-urlencoded' },
+                body: new URLSearchParams({ token, client_id: auth.client_id }).toString(),
+            });
+            revoked = revoked || res.ok;
+        }
+        catch {
+            /* offline: local forget still happens */
+        }
+    }
+    store.clear();
+    out.line('ok', `signed out${revoked ? ' (token revoked)' : ' (could not reach the authorization server; token forgotten locally)'}`);
+    out.result({ ok: true, revoked });
+    return EXIT.ok;
+}
+export function requireLogin(env) {
+    if (!createAuthStore(env).load())
+        throw new CliError('not_logged_in', 'not signed in — run `aipay login` first', EXIT.problem);
+}

package/dist/commands/status.d.ts

@@ -0,0 +1,3 @@
+import { type ParsedArgs } from '../args.js';
+import { type Reporter } from '../output.js';
+export declare function runStatus(args: ParsedArgs, out: Reporter): number;

package/dist/commands/status.js

@@ -0,0 +1,24 @@
+/** `aipay status [--dir] [--json]` — what this directory is linked to. No network. */
+import { resolve } from 'node:path';
+import { flagString } from '../args.js';
+import { EXIT } from '../output.js';
+import { readProject } from '../project.js';
+export function runStatus(args, out) {
+    const dir = resolve(flagString(args.flags, 'dir') ?? '.');
+    const project = readProject(dir);
+    if (!project) {
+        out.line('info', 'not linked (no .aipay/project.json here)');
+        out.result({ linked: false, dir });
+        return EXIT.ok;
+    }
+    out.line('ok', `linked: ${project.app.name ?? '(unnamed app)'}`);
+    out.kv('client_id', project.app.client_id);
+    out.kv('auth', project.auth_origin);
+    out.kv('api', project.api_base);
+    out.kv('callback', project.callback);
+    out.kv('framework', `${project.scaffold.framework ?? '—'} / ${project.scaffold.package_manager ?? '—'}`);
+    out.kv('scaffolded', project.scaffold.files.length ? project.scaffold.files.join(', ') : '—');
+    out.kv('linked at', project.linked_at);
+    out.result({ linked: true, dir, project });
+    return EXIT.ok;
+}

package/dist/commands/test.d.ts

@@ -0,0 +1,12 @@
+import { type ParsedArgs } from '../args.js';
+import { type Reporter } from '../output.js';
+export interface TestDeps {
+    env?: NodeJS.ProcessEnv;
+    open?: (url: string) => boolean;
+    /** For e2e drivers: receives the authorize URL (in addition to the printed line). */
+    onAuthorizeUrl?: (url: string) => void;
+}
+export declare function runTest(args: ParsedArgs, out: Reporter, deps?: TestDeps): Promise<number>;
+/** Cheapest sensible default: prefer a small/cheap model id if present, else the first. */
+export declare function pickModel(ids: string[]): string | null;
+export declare function formatUusd(uusd: string): string;

package/dist/commands/test.js

@@ -0,0 +1,159 @@
+/**
+ * `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 { parseCallback, portIsVariable, redirectUriFor, startLoopback } from '../loopback.js';
+import { CliError, EXIT } from '../output.js';
+import { readProject } from '../project.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 = fetch;
+    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);
+        result.error = { code: 'failed', message: msg };
+        out.line('bad', msg);
+        if (/\b404\b/.test(msg))
+            out.line('info', 'Check the endpoint URL and network connectivity before retrying.');
+        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): Promise<DeveloperApi>;
+export declare function errorMessage(body: unknown, status: number): string;

package/dist/developer-api.js

@@ -0,0 +1,73 @@
+/**
+ * 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.
+ */
+import { refreshAccessToken } from '@coswic/aipay-sdk';
+import { isEmpty404 } from './network.js';
+import { CliError, EXIT } from './output.js';
+import { EMPTY_404_HINT } from './remote.js';
+export async function openDeveloperApi(store) {
+    let auth = store.load();
+    if (!auth)
+        throw new CliError('not_logged_in', 'not signed in — run `aipay login` first', EXIT.problem);
+    const f = fetch;
+    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 (isEmpty404(res.status, text))
+                throw new CliError('empty_404', EMPTY_404_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>;