@coswic/aipay 0.2.0 → 0.4.0

package/dist/project.js

@@ -0,0 +1,126 @@
+/**
+ * Local artifacts (consultant report §6.5):
+ *   .aipay/project.json  — committable: which app this project is linked to (no secrets)
+ *   .env.local           — NOT committed: only public values (client_id, URLs)
+ *   .gitignore           — gets `.env.local` and `.aipay/local/` appended once
+ *
+ * Tokens live only in memory for the duration of `aipay test`. Nothing here writes them.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Accepted by `--framework`; detection picks server frameworks first, then Vite, then plain Node. */
+export const FRAMEWORKS = [
+    'next',
+    'express',
+    'fastify',
+    'hono',
+    'vite',
+    'node',
+];
+export function isFramework(v) {
+    return typeof v === 'string' && FRAMEWORKS.includes(v);
+}
+export const PROJECT_DIR = '.aipay';
+export const PROJECT_FILE = 'project.json';
+export const ENV_FILE = '.env.local';
+export function projectPath(dir) {
+    return join(dir, PROJECT_DIR, PROJECT_FILE);
+}
+export function readProject(dir) {
+    const p = projectPath(dir);
+    if (!existsSync(p))
+        return null;
+    const raw = readFileSync(p, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!isProjectConfig(parsed))
+        throw new Error(`${p} is not a valid AI-Pay project file`);
+    return parsed;
+}
+export function writeProject(dir, cfg) {
+    mkdirSync(join(dir, PROJECT_DIR), { recursive: true });
+    const p = projectPath(dir);
+    writeFileSync(p, `${JSON.stringify(cfg, null, 2)}\n`);
+    return p;
+}
+export function isProjectConfig(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const o = v;
+    const app = o.app;
+    return (o.version === 1 &&
+        !!app &&
+        typeof app.client_id === 'string' &&
+        typeof o.auth_origin === 'string' &&
+        typeof o.api_base === 'string' &&
+        typeof o.callback === 'string');
+}
+/** Env var names the SDK samples and the scaffolded route read. Public values only. */
+export const ENV_KEYS = {
+    clientId: 'AIPAY_CLIENT_ID',
+    authOrigin: 'AIPAY_AUTH_ORIGIN',
+    apiBase: 'AIPAY_API_BASE',
+    callback: 'AIPAY_CALLBACK_URL',
+};
+/** Vite only exposes VITE_-prefixed values to browser code, so a Vite project gets the same four
+ * public values twice: the plain names (for any server-side tooling) and these aliases. */
+export const VITE_ENV_KEYS = {
+    clientId: 'VITE_AIPAY_CLIENT_ID',
+    authOrigin: 'VITE_AIPAY_AUTH_ORIGIN',
+    apiBase: 'VITE_AIPAY_API_BASE',
+    callback: 'VITE_AIPAY_CALLBACK_URL',
+};
+/**
+ * Merge our keys into `.env.local` without touching anything else in it: existing lines
+ * for our keys are replaced in place, missing ones appended under a marker comment.
+ * Returns the keys that actually changed (so `--dry-run` and `status` can report).
+ */
+export function mergeEnvFile(existing, values) {
+    const lines = existing ? existing.split(/\r?\n/) : [];
+    if (lines.length && lines[lines.length - 1] === '')
+        lines.pop();
+    const changed = [];
+    const seen = new Set();
+    const out = lines.map((line) => {
+        const m = /^\s*(?:export\s+)?([A-Z0-9_]+)\s*=(.*)$/.exec(line);
+        if (!m)
+            return line;
+        const key = m[1];
+        if (!(key in values))
+            return line;
+        seen.add(key);
+        const want = values[key];
+        if (unquote(m[2] ?? '') === want)
+            return line;
+        changed.push(key);
+        return `${key}=${want}`;
+    });
+    const missing = Object.keys(values).filter((k) => !seen.has(k));
+    if (missing.length) {
+        if (out.length)
+            out.push('');
+        out.push('# AI-Pay (written by `aipay init`; public values, safe to keep local)');
+        for (const k of missing) {
+            out.push(`${k}=${values[k]}`);
+            changed.push(k);
+        }
+    }
+    return { content: `${out.join('\n')}\n`, changed };
+}
+function unquote(s) {
+    const t = s.trim();
+    if (t.length >= 2 &&
+        ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))))
+        return t.slice(1, -1);
+    return t;
+}
+/** Append missing ignore entries; never reorder or remove anything. */
+export function mergeGitignore(existing, entries) {
+    const lines = existing ? existing.split(/\r?\n/) : [];
+    const have = new Set(lines.map((l) => l.trim()));
+    const added = entries.filter((e) => !have.has(e));
+    if (!added.length)
+        return { content: existing ?? '', added };
+    const base = existing ? (existing.endsWith('\n') ? existing : `${existing}\n`) : '';
+    const block = `${base}${base ? '\n' : ''}# AI-Pay local files (never commit)\n${added.join('\n')}\n`;
+    return { content: block, added };
+}

package/dist/remote.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Everything that talks to AI-Pay over the network, in one place so the commands stay
+ * readable and tests can stub it.
+ */
+import { EMPTY_404_HINT } from './network.js';
+export interface Remote {
+    fetchDocs(apiBase: string, locale?: 'en' | 'zh-Hant'): Promise<{
+        markdown: string | null;
+        empty404: boolean;
+        status: number;
+    }>;
+    probe(url: string): Promise<{
+        ok: boolean;
+        status: number;
+        empty404: boolean;
+        error?: string;
+    }>;
+}
+export declare function createRemote(): Remote;
+export declare function docsUrl(apiBase: string, locale?: 'en' | 'zh-Hant'): string;
+export { EMPTY_404_HINT };

package/dist/remote.js

@@ -0,0 +1,41 @@
+/**
+ * Everything that talks to AI-Pay over the network, in one place so the commands stay
+ * readable and tests can stub it.
+ */
+import { EMPTY_404_HINT, isEmpty404 } from './network.js';
+import { CliError, EXIT } from './output.js';
+export function createRemote() {
+    const f = fetch;
+    return {
+        async fetchDocs(apiBase, locale = 'en') {
+            const url = docsUrl(apiBase, locale);
+            let res;
+            try {
+                res = await f(url, { headers: { accept: 'text/markdown, text/plain' } });
+            }
+            catch (e) {
+                throw new CliError('network', `cannot reach ${url}: ${e.message}. Check the endpoint URL and network connectivity, then retry.`, EXIT.remote);
+            }
+            const text = await res.text();
+            if (res.ok)
+                return { markdown: text, empty404: false, status: res.status };
+            return { markdown: null, empty404: isEmpty404(res.status, text), status: res.status };
+        },
+        async probe(url) {
+            try {
+                const res = await f(url, { method: 'GET', redirect: 'manual' });
+                const text = await res.text();
+                return { ok: res.ok, status: res.status, empty404: isEmpty404(res.status, text) };
+            }
+            catch (e) {
+                return { ok: false, status: 0, empty404: false, error: e.message };
+            }
+        },
+    };
+}
+export function docsUrl(apiBase, locale = 'en') {
+    const u = new URL('/docs.md', apiBase);
+    u.searchParams.set('lang', locale);
+    return u.toString();
+}
+export { EMPTY_404_HINT };

package/dist/setup-events.d.ts

@@ -0,0 +1,3 @@
+import type { Reporter } from './output.js';
+export type SetupEventKind = 'cli.init' | 'cli.test' | 'cli.doctor';
+export declare function reportSetupEvent(appId: string, kind: SetupEventKind, detail: Record<string, string | number | boolean | string[]>, out: Reporter, env?: NodeJS.ProcessEnv): Promise<boolean>;

package/dist/setup-events.js

@@ -0,0 +1,28 @@
+/**
+ * Setup-session events (consultant §6.3): after `init` / `test` the CLI tells the Console
+ * what happened so the "waiting for the tool" line turns into "the CLI finished init".
+ * Best effort and strictly opt-in by state: only when the developer is signed in with the
+ * CLI (`aipay login`); never blocks the command, never sends tokens or file contents.
+ */
+import { createAuthStore } from './auth-store.js';
+import { openDeveloperApi } from './developer-api.js';
+export async function reportSetupEvent(appId, kind, detail, out, env = process.env) {
+    const store = createAuthStore(env);
+    if (!store.load())
+        return false; // not signed in with the CLI → the Console still sees server facts
+    try {
+        const api = await openDeveloperApi(store);
+        const res = await api.request('POST', `/v1/developer/apps/${encodeURIComponent(appId)}/setup-events`, {
+            body: { kind, detail },
+        });
+        if (res.status === 201) {
+            out.line('info', `reported ${kind} to the Console`);
+            return true;
+        }
+        out.debug(`setup event ${kind} not recorded (HTTP ${res.status})`);
+    }
+    catch (e) {
+        out.debug(`setup event ${kind} skipped: ${e.message}`);
+    }
+    return false;
+}

package/dist/templates.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Scaffold templates: one `aipay` helper module (sign-in flow + first completion) and a
+ * thin wiring file per framework. Authored twice (TypeScript / JavaScript) so nothing is
+ * generated by stripping types. The callback path is the one registered in the Console
+ * for the app (default /auth/aipay/callback); the start path sits next to it.
+ *
+ * Sessions are the developer's business — the template keeps pending flows and signed-in
+ * users in memory with a loud comment, which is correct for a dev server and obviously
+ * wrong for production.
+ */
+import type { Framework } from './project.js';
+export interface TemplateFile {
+    /** Path relative to the project root. */
+    path: string;
+    content: string;
+}
+export interface TemplateInput {
+    framework: Framework;
+    typescript: boolean;
+    srcDir: string;
+    callbackPath: string;
+}
+export declare function startPathFor(callbackPath: string): string;
+export declare function scaffoldFiles(input: TemplateInput): TemplateFile[];

package/dist/templates.js

@@ -0,0 +1,333 @@
+export function startPathFor(callbackPath) {
+    return callbackPath.replace(/\/[^/]*$/, '/start');
+}
+export function scaffoldFiles(input) {
+    const ext = input.typescript ? 'ts' : 'js';
+    const startPath = startPathFor(input.callbackPath);
+    const core = {
+        path: `${prefix(input.srcDir)}aipay.${ext}`,
+        content: coreModule(input.typescript),
+    };
+    switch (input.framework) {
+        case 'next':
+            return [
+                core,
+                { path: `app${startPath}/route.${ext}`, content: nextStart(input) },
+                { path: `app${input.callbackPath}/route.${ext}`, content: nextCallback(input) },
+            ];
+        case 'express':
+            return [
+                core,
+                {
+                    path: `${prefix(input.srcDir)}aipay-routes.${ext}`,
+                    content: expressRoutes(input, startPath),
+                },
+            ];
+        case 'fastify':
+            return [
+                core,
+                {
+                    path: `${prefix(input.srcDir)}aipay-routes.${ext}`,
+                    content: fastifyRoutes(input, startPath),
+                },
+            ];
+        case 'hono':
+            return [
+                core,
+                {
+                    path: `${prefix(input.srcDir)}aipay-routes.${ext}`,
+                    content: honoRoutes(input, startPath),
+                },
+            ];
+        case 'vite':
+            // Browser SPA: no server, so the helper module itself runs in the page (PKCE public
+            // client; tokens live in sessionStorage for the tab) and a boot file handles the callback.
+            return [
+                { path: `${prefix(input.srcDir)}aipay.${ext}`, content: browserModule(input) },
+                { path: `${prefix(input.srcDir)}aipay-boot.${ext}`, content: viteBoot(input) },
+            ];
+        default:
+            return [
+                core,
+                {
+                    path: `${prefix(input.srcDir)}aipay-routes.${ext}`,
+                    content: nodeRoutes(input, startPath),
+                },
+            ];
+    }
+}
+function prefix(srcDir) {
+    return srcDir === '.' ? '' : `${srcDir.replace(/\/$/, '')}/`;
+}
+const ENV_HEADER = `// Reads the public values \`aipay init\` wrote to .env.local (load them with your usual
+// dotenv/framework mechanism). No secret exists: the app is a public PKCE client.`;
+function coreModule(ts) {
+    const t = (typed, plain) => (ts ? typed : plain);
+    return `${ENV_HEADER}
+import {
+  AIPayClient,
+  createConnectUrl,
+  getUserInfo,
+  handleCallback,${t('\n  type TokenSet,', '')}
+} from '@coswic/aipay-sdk'
+
+const cfg = {
+  hydraPublicUrl: process.env.AIPAY_AUTH_ORIGIN${t(' as string', '')},
+  clientId: process.env.AIPAY_CLIENT_ID${t(' as string', '')},
+  redirectUri: process.env.AIPAY_CALLBACK_URL${t(' as string', '')},
+}
+const apiBase = process.env.AIPAY_API_BASE${t(' as string', '')}
+
+// DEV ONLY: in-memory stores. Replace both with your session store before shipping.
+const pendingFlows = new Map${t('<string, { codeVerifier: string; expires: number }>', '')}()
+const sessions = new Map${t('<string, TokenSet>', '')}()
+
+/** Step 1 — build the AI-Pay sign-in URL; remember the PKCE verifier under the state. */
+export async function beginSignIn()${t(': Promise<string>', '')} {
+  const { url, state, codeVerifier } = await createConnectUrl(cfg)
+  pendingFlows.set(state, { codeVerifier, expires: Date.now() + 10 * 60_000 })
+  return url
+}
+
+/** Step 2 — on the callback, exchange the code (state + PKCE are verified by the SDK). */
+export async function finishSignIn(callbackUrl${t(': string', '')})${t(': Promise<{ sessionId: string; sub: string; email: string | null }>', '')} {
+  const state = new URL(callbackUrl).searchParams.get('state') ?? ''
+  const pending = pendingFlows.get(state)
+  pendingFlows.delete(state)
+  const saved = pending && pending.expires > Date.now() ? { state, codeVerifier: pending.codeVerifier } : null
+  const tokens = await handleCallback(cfg, callbackUrl, saved)
+  const user = await getUserInfo(cfg, tokens.accessToken)
+  const sessionId = crypto.randomUUID()
+  sessions.set(sessionId, tokens)
+  // user.sub is the stable per-app id of this user — key your accounts on it, not on email.
+  return { sessionId, sub: user.sub, email: user.email ?? null }
+}
+
+/** Step 3 — call a model on the user's behalf; the response carries the billing receipt. */
+export async function firstCompletion(sessionId${t(': string', '')}, model${t(': string', '')}) {
+  const tokens = sessions.get(sessionId)
+  if (!tokens) throw new Error('not signed in')
+  const client = new AIPayClient({ baseUrl: apiBase, accessToken: tokens.accessToken })
+  const res = await client.chat.completions.create({
+    model,
+    messages: [{ role: 'user', content: 'Say hello in five words.' }],
+    max_tokens: 32,
+  })
+  return { text: res.choices[0]?.message.content ?? '', receipt: res.aipay }
+}
+
+export function sessionCookie(sessionId${t(': string', '')})${t(': string', '')} {
+  return \`aipay_session=\${sessionId}; Path=/; HttpOnly; SameSite=Lax\`
+}
+
+export function sessionFromCookie(cookieHeader${t(': string | null | undefined', '')})${t(': string | null', '')} {
+  const m = /(?:^|;\\s*)aipay_session=([^;]+)/.exec(cookieHeader ?? '')
+  return m ? m[1]${t(' ?? null', '')} : null
+}
+`;
+}
+function nextStart(input) {
+    const imp = importPath(input, 'app/x/y/z'); // depth: app/<a>/<b>/<start>/route
+    return `import { beginSignIn } from '${imp}'
+
+export async function GET() {
+  const url = await beginSignIn()
+  return Response.redirect(url, 302)
+}
+`;
+}
+function nextCallback(input) {
+    const imp = importPath(input, 'app/x/y/z');
+    return `import { finishSignIn, sessionCookie } from '${imp}'
+
+export async function GET(request${input.typescript ? ': Request' : ''}) {
+  const { sessionId, email } = await finishSignIn(request.url)
+  return new Response(\`Signed in as \${email ?? 'user'}. You can now call firstCompletion(sessionId, model).\`, {
+    status: 200,
+    headers: { 'set-cookie': sessionCookie(sessionId), 'content-type': 'text/plain; charset=utf-8' },
+  })
+}
+`;
+}
+/** Relative import from a route file to the core module (depth-aware, extension-less). */
+function importPath(input, routeDir) {
+    const depth = routeDir.split('/').length;
+    const up = '../'.repeat(depth);
+    const core = `${prefix(input.srcDir)}aipay`;
+    return `${up}${core}${input.typescript ? '' : '.js'}`;
+}
+function expressRoutes(input, startPath) {
+    const ts = input.typescript;
+    return `import { Router } from 'express'
+import { beginSignIn, finishSignIn, sessionCookie } from './aipay${ts ? '' : '.js'}'
+
+export const aipayRouter = Router()
+
+aipayRouter.get('${startPath}', async (_req, res) => {
+  res.redirect(await beginSignIn())
+})
+
+aipayRouter.get('${input.callbackPath}', async (req, res) => {
+  const full = new URL(req.originalUrl, \`\${req.protocol}://\${req.get('host')}\`).toString()
+  const { sessionId, email } = await finishSignIn(full)
+  res.setHeader('set-cookie', sessionCookie(sessionId))
+  res.type('text/plain').send(\`Signed in as \${email ?? 'user'}.\`)
+})
+// app.use(aipayRouter)
+`;
+}
+function fastifyRoutes(input, startPath) {
+    const ts = input.typescript;
+    return `${ts ? "import type { FastifyInstance } from 'fastify'\n" : ''}import { beginSignIn, finishSignIn, sessionCookie } from './aipay${ts ? '' : '.js'}'
+
+export async function aipayRoutes(app${ts ? ': FastifyInstance' : ''}) {
+  app.get('${startPath}', async (_req, reply) => reply.redirect(await beginSignIn()))
+  app.get('${input.callbackPath}', async (req, reply) => {
+    const full = new URL(req.url, \`\${req.protocol}://\${req.headers.host}\`).toString()
+    const { sessionId, email } = await finishSignIn(full)
+    reply.header('set-cookie', sessionCookie(sessionId))
+    return \`Signed in as \${email ?? 'user'}.\`
+  })
+}
+// await app.register(aipayRoutes)
+`;
+}
+function honoRoutes(input, startPath) {
+    const ts = input.typescript;
+    return `import { Hono } from 'hono'
+import { beginSignIn, finishSignIn, sessionCookie } from './aipay${ts ? '' : '.js'}'
+
+export const aipay = new Hono()
+
+aipay.get('${startPath}', async (c) => c.redirect(await beginSignIn()))
+
+aipay.get('${input.callbackPath}', async (c) => {
+  const { sessionId, email } = await finishSignIn(c.req.url)
+  c.header('set-cookie', sessionCookie(sessionId))
+  return c.text(\`Signed in as \${email ?? 'user'}.\`)
+})
+// app.route('/', aipay)
+`;
+}
+function nodeRoutes(input, startPath) {
+    const ts = input.typescript;
+    return `${ts ? "import type { IncomingMessage, ServerResponse } from 'node:http'\n" : ''}import { beginSignIn, finishSignIn, sessionCookie } from './aipay${ts ? '' : '.js'}'
+
+/** Plug into your http server: \`if (await handleAIPay(req, res)) return\` */
+export async function handleAIPay(req${ts ? ': IncomingMessage' : ''}, res${ts ? ': ServerResponse' : ''})${ts ? ': Promise<boolean>' : ''} {
+  const url = new URL(req.url ?? '/', \`http://\${req.headers.host}\`)
+  if (url.pathname === '${startPath}') {
+    res.writeHead(302, { location: await beginSignIn() })
+    res.end()
+    return true
+  }
+  if (url.pathname === '${input.callbackPath}') {
+    const { sessionId, email } = await finishSignIn(url.toString())
+    res.writeHead(200, { 'set-cookie': sessionCookie(sessionId), 'content-type': 'text/plain; charset=utf-8' })
+    res.end(\`Signed in as \${email ?? 'user'}.\`)
+    return true
+  }
+  return false
+}
+`;
+}
+/**
+ * Vite/browser variant of the helper module. Same three steps as the server module, but the
+ * pending flow and the tokens live in sessionStorage (tab-scoped, gone when the tab closes) and
+ * the config comes from `import.meta.env.VITE_AIPAY_*` — Vite only exposes VITE_-prefixed values.
+ */
+function browserModule(input) {
+    const ts = input.typescript;
+    const t = (typed, plain) => (ts ? typed : plain);
+    return `${ts ? '/// <reference types="vite/client" />\n' : ''}// Browser (Vite) build of the AI-Pay helper. Reads the VITE_AIPAY_* values \`aipay init\`
+// wrote to .env.local (Vite exposes only VITE_-prefixed values to the page). No secret
+// exists: the app is a public PKCE client and the token endpoint accepts browser calls.
+import {
+  AIPayClient,
+  createConnectUrl,
+  getUserInfo,
+  handleCallback,${t('\n  type TokenSet,', '')}
+} from '@coswic/aipay-sdk'
+
+const cfg = {
+  hydraPublicUrl: import.meta.env.VITE_AIPAY_AUTH_ORIGIN${t(' as string', '')},
+  clientId: import.meta.env.VITE_AIPAY_CLIENT_ID${t(' as string', '')},
+  redirectUri: import.meta.env.VITE_AIPAY_CALLBACK_URL${t(' as string', '')},
+}
+const apiBase = import.meta.env.VITE_AIPAY_API_BASE${t(' as string', '')}
+/** Path part of the registered callback — the page that must call completeSignInIfCallback(). */
+export const CALLBACK_PATH = ${JSON.stringify(input.callbackPath)}
+
+const PENDING_KEY = 'aipay:pending' // { state, codeVerifier } while the user is at AI-Pay
+const TOKENS_KEY = 'aipay:tokens' // TokenSet for this tab (sessionStorage: cleared when the tab closes)
+
+/** Step 1 — send the user to AI-Pay. The PKCE verifier is kept under the state for the callback. */
+export async function beginSignIn()${t(': Promise<void>', '')} {
+  const { url, state, codeVerifier } = await createConnectUrl(cfg)
+  sessionStorage.setItem(PENDING_KEY, JSON.stringify({ state, codeVerifier }))
+  location.assign(url)
+}
+
+/**
+ * Step 2 — call once at startup. On the callback page it exchanges the code (state + PKCE are
+ * verified by the SDK), stores the tokens for this tab and cleans the URL; elsewhere it is a no-op.
+ */
+export async function completeSignInIfCallback()${t(': Promise<{ sub: string; email: string | null } | null>', '')} {
+  if (location.pathname !== CALLBACK_PATH) return null
+  const raw = sessionStorage.getItem(PENDING_KEY)
+  sessionStorage.removeItem(PENDING_KEY)
+  const saved = raw ? ${t('(JSON.parse(raw) as { state: string; codeVerifier: string })', 'JSON.parse(raw)')} : null
+  const tokens = await handleCallback(cfg, location.href, saved)
+  sessionStorage.setItem(TOKENS_KEY, JSON.stringify(tokens))
+  history.replaceState(null, '', '/')
+  const user = await getUserInfo(cfg, tokens.accessToken)
+  // user.sub is the stable per-app id of this user — key your accounts on it, not on email.
+  return { sub: user.sub, email: user.email ?? null }
+}
+
+export function currentTokens()${t(': TokenSet | null', '')} {
+  const raw = sessionStorage.getItem(TOKENS_KEY)
+  return raw ? ${t('(JSON.parse(raw) as TokenSet)', 'JSON.parse(raw)')} : null
+}
+
+export function signOut()${t(': void', '')} {
+  sessionStorage.removeItem(TOKENS_KEY)
+}
+
+/** Step 3 — call a model on the user's behalf; the response carries the billing receipt. */
+export async function firstCompletion(model${t(': string', '')}) {
+  const tokens = currentTokens()
+  if (!tokens) throw new Error('not signed in')
+  const client = new AIPayClient({ baseUrl: apiBase, accessToken: tokens.accessToken })
+  const res = await client.chat.completions.create({
+    model,
+    messages: [{ role: 'user', content: 'Say hello in five words.' }],
+    max_tokens: 32,
+  })
+  return { text: res.choices[0]?.message.content ?? '', receipt: res.aipay }
+}
+`;
+}
+/** Startup wiring for a Vite app: handle the callback page, expose the two actions to your UI. */
+function viteBoot(input) {
+    const ts = input.typescript;
+    const from = ts ? './aipay' : './aipay.js';
+    return `// Call bootAIPay() once when your app starts (top of main.${ts ? 'ts' : 'js'} / before rendering).
+// It completes the sign-in when the page is the AI-Pay callback (${input.callbackPath}) and
+// otherwise does nothing. Vite's dev server serves index.html for that path (SPA fallback),
+// so no route configuration is needed; with a client-side router, keep the path unrouted.
+import { beginSignIn, completeSignInIfCallback, currentTokens, firstCompletion } from '${from}'
+
+export async function bootAIPay() {
+  const justSignedIn = await completeSignInIfCallback()
+  const signedIn = justSignedIn !== null || currentTokens() !== null
+  return {
+    signedIn,
+    /** Wire this to your "Sign in with AI-Pay" button. */
+    beginSignIn,
+    /** After sign-in: one model call; the receipt (cost, request id) is on the result. */
+    firstCompletion,
+  }
+}
+`;
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare function cliVersion(): string;

package/dist/version.js

@@ -0,0 +1,10 @@
+import { createRequire } from 'node:module';
+export function cliVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        return require('../package.json').version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coswic/aipay",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "AI-Pay CLI — init (link an app + scaffold the integration), doctor, test (real sign-in + first receipt), status, unlink. For developers and their coding agents.",
   "license": "MIT",
   "type": "module",
@@ -15,7 +15,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -24,7 +25,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@coswic/aipay-sdk": "^0.3.1"
+    "@coswic/aipay-sdk": "^0.3.2"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",