@coswic/aipay 0.5.0 → 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Coswic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -14,6 +14,7 @@ npx @coswic/aipay test
 | Command | What it does |
 |---|---|
 | `aipay login` / `whoami` / `logout` | Sign in as the developer to manage your Apps; on a remote machine use `login --device`. This is separate from an end user authorizing AI spending in your App. |
+| `aipay region` / `region set --country <CC> [--state US-XX] --accept-terms` | Show or set your country/region (US: state) and accept the current Terms of Service. The developer API answers 403 `region_required` until both are on file. |
 | `aipay apps list` / `apps create --name <name>` | List or create Apps using your developer authorization. |
 | `aipay apps callbacks list --app <client_id>` | Read the registered callback URLs. In a linked project, `--app` can be omitted; `--dir` selects the project. |
 | `aipay apps callbacks add --app <client_id> --callback <url>` | Add a registered callback while preserving the others. Adding an existing URL makes no write. |

package/dist/commands/region.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `aipay region` (show) and `aipay region set --country <CC> [--state US-XX] [--accept-terms]`.
+ *
+ * The developer API is closed (403 region_required) until the account has a declared region and an
+ * accepted current Terms of Service version. Both endpoints used here are exempt from that gate:
+ *   GET  /v1/developer/me/region  → current state + the version to accept
+ *   POST /v1/developer/me/region  → declare (same body as the dashboard)
+ * Non-interactive on purpose (agents drive this): everything is a flag; missing input is a usage error.
+ */
+import { type ParsedArgs } from '../args.js';
+import { type Reporter } from '../output.js';
+export interface RegionState {
+    country: string | null;
+    subdivision: string | null;
+    terms_version: string | null;
+    declared: boolean;
+    terms_current: boolean;
+    complete: boolean;
+}
+export declare function runRegion(args: ParsedArgs, out: Reporter, env?: NodeJS.ProcessEnv): Promise<number>;

package/dist/commands/region.js

@@ -0,0 +1,100 @@
+/**
+ * `aipay region` (show) and `aipay region set --country <CC> [--state US-XX] [--accept-terms]`.
+ *
+ * The developer API is closed (403 region_required) until the account has a declared region and an
+ * accepted current Terms of Service version. Both endpoints used here are exempt from that gate:
+ *   GET  /v1/developer/me/region  → current state + the version to accept
+ *   POST /v1/developer/me/region  → declare (same body as the dashboard)
+ * Non-interactive on purpose (agents drive this): everything is a flag; missing input is a usage error.
+ */
+import { flagBool, flagString } from '../args.js';
+import { createAuthStore } from '../auth-store.js';
+import { errorMessage, openDeveloperApi } from '../developer-api.js';
+import { CliError, EXIT } from '../output.js';
+const FIX_HINT = 'aipay region set --country <ISO 3166-1> [--state US-XX] --accept-terms';
+async function currentRegion(api) {
+    const res = await api.request('GET', '/v1/developer/me/region');
+    if (res.status !== 200 || !res.body?.region)
+        throw new CliError('remote', `GET /v1/developer/me/region → ${errorMessage(res.body?.error ?? res.body, res.status)}`, EXIT.remote);
+    return res.body;
+}
+function termsUrl(apiBase, doc) {
+    return new URL(doc.terms_path ?? '/terms', apiBase).toString();
+}
+function report(out, apiBase, doc, saved = false) {
+    const r = doc.region;
+    const place = r.country
+        ? `${r.country}${r.subdivision ? ` ${r.subdivision}` : ''}`
+        : 'not declared';
+    out.line(r.complete ? 'ok' : 'warn', saved ? `region saved: ${place}` : r.complete ? `region ${place}` : 'region incomplete');
+    out.kv('country', r.country ?? '—');
+    out.kv('state', r.subdivision ?? '—');
+    out.kv('terms', r.terms_current
+        ? `accepted version ${r.terms_version}`
+        : `${r.terms_version ? `accepted ${r.terms_version}, ` : ''}version ${doc.terms_version_required} needs acceptance (${termsUrl(apiBase, doc)})`);
+    if (!r.complete)
+        out.line('info', `run \`${FIX_HINT}\``);
+    out.result({
+        ...r,
+        terms_version_required: doc.terms_version_required,
+        terms_url: termsUrl(apiBase, doc),
+        ...(saved ? { saved: true } : {}),
+    });
+}
+export async function runRegion(args, out, env = process.env) {
+    const sub = args.positionals[0] ?? 'show';
+    if (sub !== 'show' && sub !== 'set')
+        throw new CliError('usage', `unknown region subcommand "${sub}" (show | set)`, EXIT.usage);
+    if (args.positionals.length > 1)
+        throw new CliError('usage', 'unexpected region positional argument', EXIT.usage);
+    const countryRaw = flagString(args.flags, 'country');
+    const stateRaw = flagString(args.flags, 'state');
+    const acceptTerms = flagBool(args.flags, 'accept-terms');
+    let country = null;
+    let state = null;
+    if (sub === 'set') {
+        if (!countryRaw)
+            throw new CliError('usage', 'missing --country <ISO 3166-1 alpha-2 code, e.g. TW or US>', EXIT.usage);
+        country = countryRaw.trim().toUpperCase();
+        if (!/^[A-Z]{2}$/.test(country))
+            throw new CliError('usage', `--country must be a two-letter ISO 3166-1 code (got "${countryRaw}")`, EXIT.usage);
+        if (stateRaw) {
+            state = stateRaw.trim().toUpperCase();
+            if (!/^[A-Z]{2}-[A-Z0-9]{1,3}$/.test(state))
+                throw new CliError('usage', `--state must look like US-CA (got "${stateRaw}")`, EXIT.usage);
+            if (!state.startsWith(`${country}-`))
+                throw new CliError('usage', `--state ${state} does not belong to --country ${country}`, EXIT.usage);
+            if (country !== 'US')
+                throw new CliError('usage', '--state is only accepted for --country US', EXIT.usage);
+        }
+        if (country === 'US' && !state)
+            throw new CliError('usage', 'the United States needs --state (e.g. --state US-CA)', EXIT.usage);
+    }
+    else if (countryRaw || stateRaw || acceptTerms) {
+        throw new CliError('usage', '`aipay region` shows the current state; use `aipay region set …` to change it', EXIT.usage);
+    }
+    const api = await openDeveloperApi(createAuthStore(env));
+    const current = await currentRegion(api);
+    if (sub === 'show') {
+        report(out, api.auth.api_base, current);
+        return EXIT.ok;
+    }
+    if (!current.region.terms_current && !acceptTerms)
+        throw new CliError('terms_required', `the AI-Pay Terms of Service (version ${current.terms_version_required}, ${termsUrl(api.auth.api_base, current)}) need your explicit acceptance — read them, then rerun with --accept-terms`, EXIT.problem);
+    const body = {
+        country,
+        ...(state ? { subdivision: state } : {}),
+        ...(acceptTerms ? { accept_terms: true, terms_version: current.terms_version_required } : {}),
+    };
+    const res = await api.request('POST', '/v1/developer/me/region', { body });
+    if (res.status === 409)
+        throw new CliError('terms_version_changed', 'the Terms of Service changed while you were reading — run `aipay region` to see the new version, then accept again', EXIT.problem);
+    if (res.status !== 200 || !res.body?.region)
+        throw new CliError('region_rejected', `could not save the region: ${errorMessage(res.body?.error ?? res.body, res.status)}`, res.status === 400 ? EXIT.usage : EXIT.problem);
+    report(out, api.auth.api_base, {
+        region: res.body.region,
+        terms_version_required: current.terms_version_required,
+        ...(current.terms_path ? { terms_path: current.terms_path } : {}),
+    }, true);
+    return EXIT.ok;
+}

package/dist/developer-api.js

@@ -43,6 +43,10 @@ export async function openDeveloperApi(store) {
             catch {
                 body = { raw: text.slice(0, 500) };
             }
+            // 0074 hard gate: the developer API is closed until region + current Terms are on file.
+            // `aipay region …` talks to the exempt endpoints, so this never traps the fix itself.
+            if (res.status === 403 && errorCodeOf(body) === 'region_required')
+                throw new CliError('region_required', 'AI-Pay needs your country/region and your acceptance of the current Terms of Service before the developer API can be used — run `aipay region set --country <ISO 3166-1> [--state US-XX] --accept-terms` (`aipay region` shows the version and terms URL)', EXIT.problem);
             return { status: res.status, body: body };
         },
     };
@@ -72,3 +76,9 @@ export function errorMessage(body, status) {
     const msg = typeof b.message === 'string' ? b.message : typeof b.error === 'string' ? b.error : '';
     return msg ? `${msg} (HTTP ${status})` : `HTTP ${status}`;
 }
+function errorCodeOf(body) {
+    const err = body?.error;
+    if (err && typeof err === 'object' && typeof err.code === 'string')
+        return err.code;
+    return null;
+}

package/dist/main.d.ts

@@ -1,4 +1,4 @@
-export declare const HELP = "aipay \u2014 AI-Pay CLI\n\nUsage\n  aipay login [--api <base>] [--device] [--json]      developer sign-in for the CLI itself\n  aipay whoami [--json] \u00B7 aipay logout [--json]\n  aipay apps list [--json]\n  aipay apps create --name <name> [--callback <url>] [--json]\n  aipay apps callbacks list [--app <client_id>] [--dir <path>] [--json]\n  aipay apps callbacks add|remove --callback <url> [--app <client_id>] [--dir <path>] [--json]\n  aipay init --app <client_id> [--auth <origin>] [--api <base>] [--callback <url>] [--name <app name>]\n             [--framework next|express|fastify|hono|vite|node]  override detection\n             [--dir <path>] [--dry-run] [--no-install] [--json]\n  aipay init --create <app name> [--api <base>] ...     create the app (needs login) and link it\n  aipay test [--model <id>] [--callback <registered-loopback-url>] [--port <n>] [--no-open] [--timeout <seconds>] [--dir <path>] [--json]\n  aipay doctor [--offline] [--dir <path>] [--json]\n  aipay status [--dir <path>] [--json]\n  aipay unlink [--dry-run] [--dir <path>] [--json]\n\nlogin   sign in as a developer (loopback PKCE, audience aipay-developer-api); tokens go to the\n        OS keychain or a 0600 file \u2014 never into the project\napps    list/create your apps; callbacks list/add/remove manages registered redirects\n        callback changes preserve other URLs and reject concurrent edits\ninit    link this project to an app: .aipay/project.json, .env.local, .gitignore,\n        a callback route for your framework, aipay-agent.md, and the SDK install\n        (--auth/--api are optional once you are signed in; --create makes the app first)\ntest    real sign-in via a loopback callback (any free port on 127.0.0.1) + one chat completion \u2192 receipt\ndoctor  check the link, files, SDK, and that AI-Pay is reachable\nstatus  what this directory is linked to\nunlink  forget the link (keeps your code)\n\nExit codes: 0 ok \u00B7 1 problem you can fix \u00B7 2 usage \u00B7 3 network/auth\n";
+export declare const HELP = "aipay \u2014 AI-Pay CLI\n\nUsage\n  aipay login [--api <base>] [--device] [--json]      developer sign-in for the CLI itself\n  aipay whoami [--json] \u00B7 aipay logout [--json]\n  aipay region [--json]                                your country/region + Terms of Service status\n  aipay region set --country <CC> [--state US-XX] [--accept-terms] [--json]\n  aipay apps list [--json]\n  aipay apps create --name <name> [--callback <url>] [--json]\n  aipay apps callbacks list [--app <client_id>] [--dir <path>] [--json]\n  aipay apps callbacks add|remove --callback <url> [--app <client_id>] [--dir <path>] [--json]\n  aipay init --app <client_id> [--auth <origin>] [--api <base>] [--callback <url>] [--name <app name>]\n             [--framework next|express|fastify|hono|vite|node]  override detection\n             [--dir <path>] [--dry-run] [--no-install] [--json]\n  aipay init --create <app name> [--api <base>] ...     create the app (needs login) and link it\n  aipay test [--model <id>] [--callback <registered-loopback-url>] [--port <n>] [--no-open] [--timeout <seconds>] [--dir <path>] [--json]\n  aipay doctor [--offline] [--dir <path>] [--json]\n  aipay status [--dir <path>] [--json]\n  aipay unlink [--dry-run] [--dir <path>] [--json]\n\nlogin   sign in as a developer (loopback PKCE, audience aipay-developer-api); tokens go to the\n        OS keychain or a 0600 file \u2014 never into the project\nregion  the developer API stays closed (403 region_required) until your account has a country/region\n        (US: a state) and has accepted the current Terms of Service \u2014 \"region set\" does both; the\n        version to accept and the terms URL are printed by \"aipay region\"\napps    list/create your apps; callbacks list/add/remove manages registered redirects\n        callback changes preserve other URLs and reject concurrent edits\ninit    link this project to an app: .aipay/project.json, .env.local, .gitignore,\n        a callback route for your framework, aipay-agent.md, and the SDK install\n        (--auth/--api are optional once you are signed in; --create makes the app first)\ntest    real sign-in via a loopback callback (any free port on 127.0.0.1) + one chat completion \u2192 receipt\ndoctor  check the link, files, SDK, and that AI-Pay is reachable\nstatus  what this directory is linked to\nunlink  forget the link (keeps your code)\n\nExit codes: 0 ok \u00B7 1 problem you can fix \u00B7 2 usage \u00B7 3 network/auth\n";
 export declare function main(argv: string[], io?: {
     stdout?: (s: string) => void;
     stderr?: (s: string) => void;

package/dist/main.js

@@ -3,6 +3,7 @@ import { runApps } from './commands/apps.js';
 import { runDoctor } from './commands/doctor.js';
 import { runInit } from './commands/init.js';
 import { runLogin } from './commands/login.js';
+import { runRegion } from './commands/region.js';
 import { runLogout, runWhoami } from './commands/session.js';
 import { runStatus } from './commands/status.js';
 import { runTest } from './commands/test.js';
@@ -14,6 +15,8 @@ export const HELP = `aipay — AI-Pay CLI
 Usage
   aipay login [--api <base>] [--device] [--json]      developer sign-in for the CLI itself
   aipay whoami [--json] · aipay logout [--json]
+  aipay region [--json]                                your country/region + Terms of Service status
+  aipay region set --country <CC> [--state US-XX] [--accept-terms] [--json]
   aipay apps list [--json]
   aipay apps create --name <name> [--callback <url>] [--json]
   aipay apps callbacks list [--app <client_id>] [--dir <path>] [--json]
@@ -29,6 +32,9 @@ Usage
 
 login   sign in as a developer (loopback PKCE, audience aipay-developer-api); tokens go to the
         OS keychain or a 0600 file — never into the project
+region  the developer API stays closed (403 region_required) until your account has a country/region
+        (US: a state) and has accepted the current Terms of Service — "region set" does both; the
+        version to accept and the terms URL are printed by "aipay region"
 apps    list/create your apps; callbacks list/add/remove manages registered redirects
         callback changes preserve other URLs and reject concurrent edits
 init    link this project to an app: .aipay/project.json, .env.local, .gitignore,
@@ -63,6 +69,8 @@ export async function main(argv, io) {
                 return await runLogout(args, out);
             case 'whoami':
                 return await runWhoami(args, out);
+            case 'region':
+                return await runRegion(args, out);
             case 'apps':
                 return await runApps(args, out);
             case 'init':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coswic/aipay",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "AI-Pay CLI — developer sign-in, App and callback management, project integration, diagnostics, and real sign-in + AI receipt verification.",
   "license": "MIT",
   "type": "module",