@coswic/aipay 0.6.0 → 0.7.0

package/README.md

@@ -14,7 +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 region` / `region set --country <CC> [--state US-XX --line1 <street> --city <city> --zip <ZIP>] --accept-terms` | Show or set your country/region and accept the current Terms of Service; US accounts also need the full postal address (the backend locates the sales-tax jurisdiction: state / county / city / special district — `aipay region` shows it). The developer API answers 403 `region_required` until everything is 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

@@ -1,5 +1,8 @@
 /**
- * `aipay region` (show) and `aipay region set --country <CC> [--state US-XX] [--accept-terms]`.
+ * `aipay region` (show) and
+ * `aipay region set --country <CC> [--state US-XX --line1 <street> [--line2 <apt>] --city <city> --zip <ZIP>] [--accept-terms]`.
+ * US accounts (0121) must carry a full postal address: the backend locates the sales-tax jurisdiction
+ * (state / county / city / special district) from it; `aipay region` shows the lookup result.
  *
  * 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:
@@ -9,6 +12,25 @@
  */
 import { type ParsedArgs } from '../args.js';
 import { type Reporter } from '../output.js';
+export interface RegionAddress {
+    line1: string;
+    line2: string | null;
+    city: string;
+    postal_code: string;
+}
+export interface TaxLocationState {
+    status: 'pending' | 'resolved' | 'failed';
+    provider: string | null;
+    jurisdictions: Array<{
+        level: string;
+        name: string;
+        rate_bps: number;
+    }> | null;
+    combined_rate_bps: number | null;
+    standardized_postal_code: string | null;
+    county: string | null;
+    resolved_at: string | null;
+}
 export interface RegionState {
     country: string | null;
     subdivision: string | null;
@@ -16,5 +38,9 @@ export interface RegionState {
     declared: boolean;
     terms_current: boolean;
     complete: boolean;
+    /** US only (0121): the full postal address on file */
+    address?: RegionAddress | null;
+    /** US only: background jurisdiction lookup (state / county / city / special district) */
+    tax_location?: TaxLocationState | null;
 }
 export declare function runRegion(args: ParsedArgs, out: Reporter, env?: NodeJS.ProcessEnv): Promise<number>;

package/dist/commands/region.js

@@ -1,5 +1,8 @@
 /**
- * `aipay region` (show) and `aipay region set --country <CC> [--state US-XX] [--accept-terms]`.
+ * `aipay region` (show) and
+ * `aipay region set --country <CC> [--state US-XX --line1 <street> [--line2 <apt>] --city <city> --zip <ZIP>] [--accept-terms]`.
+ * US accounts (0121) must carry a full postal address: the backend locates the sales-tax jurisdiction
+ * (state / county / city / special district) from it; `aipay region` shows the lookup result.
  *
  * 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:
@@ -11,7 +14,7 @@ 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';
+const FIX_HINT = 'aipay region set --country <ISO 3166-1> [--state US-XX --line1 <street> --city <city> --zip <ZIP>] --accept-terms';
 async function currentRegion(api) {
     const res = await api.request('GET', '/v1/developer/me/region');
     if (res.status !== 200 || !res.body?.region)
@@ -29,6 +32,15 @@ function report(out, apiBase, doc, saved = false) {
     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 ?? '—');
+    if (r.country === 'US') {
+        const a = r.address;
+        out.kv('address', a
+            ? [a.line1, a.line2, a.city, `${r.subdivision?.slice(3) ?? ''} ${a.postal_code}`.trim()]
+                .filter(Boolean)
+                .join(', ')
+            : 'missing (required for the US)');
+        out.kv('tax', taxLocationText(r.tax_location ?? null));
+    }
     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)})`);
@@ -41,6 +53,40 @@ function report(out, apiBase, doc, saved = false) {
         ...(saved ? { saved: true } : {}),
     });
 }
+/** Background jurisdiction lookup, one line: pending / failed / combined rate with the per-level breakdown. */
+function taxLocationText(tl) {
+    if (!tl || tl.status === 'pending')
+        return 'jurisdiction lookup pending (background)';
+    if (tl.status === 'failed')
+        return 'address could not be located — check it and set it again';
+    const pct = (bps) => `${(bps / 100).toFixed(2).replace(/\.?0+$/, '')}%`;
+    const parts = (tl.jurisdictions ?? [])
+        .filter((j) => j.rate_bps > 0)
+        .map((j) => `${j.level} ${j.name} ${pct(j.rate_bps)}`);
+    return `combined ${pct(tl.combined_rate_bps ?? 0)} (${parts.join('; ') || '—'})${tl.standardized_postal_code ? ` · ZIP+4 ${tl.standardized_postal_code}` : ''}`;
+}
+/** US address flags → body.address; usage errors before any network call. */
+function parseAddressFlags(flags) {
+    const squash = (v) => (v ?? '').trim().replace(/\s+/g, ' ');
+    const line1 = squash(flagString(flags, 'line1'));
+    const line2 = squash(flagString(flags, 'line2'));
+    const city = squash(flagString(flags, 'city'));
+    const zipRaw = squash(flagString(flags, 'zip') ?? flagString(flags, 'postal-code')).replace(/[\s-]/g, '');
+    if (!line1 || line1.length > 120)
+        throw new CliError('usage', 'the United States needs --line1 <street address> (1–120 characters)', EXIT.usage);
+    if (line2.length > 120)
+        throw new CliError('usage', '--line2 is limited to 120 characters', EXIT.usage);
+    if (!city || city.length > 80)
+        throw new CliError('usage', 'the United States needs --city <city> (1–80 characters)', EXIT.usage);
+    if (!/^\d{5}(\d{4})?$/.test(zipRaw))
+        throw new CliError('usage', 'the United States needs --zip <5 digits or ZIP+4> (e.g. 94105 or 94105-1234)', EXIT.usage);
+    return {
+        line1,
+        line2: line2 || null,
+        city,
+        postal_code: zipRaw.length === 9 ? `${zipRaw.slice(0, 5)}-${zipRaw.slice(5)}` : zipRaw,
+    };
+}
 export async function runRegion(args, out, env = process.env) {
     const sub = args.positionals[0] ?? 'show';
     if (sub !== 'show' && sub !== 'set')
@@ -52,6 +98,7 @@ export async function runRegion(args, out, env = process.env) {
     const acceptTerms = flagBool(args.flags, 'accept-terms');
     let country = null;
     let state = null;
+    let address = 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);
@@ -69,6 +116,13 @@ export async function runRegion(args, out, env = process.env) {
         }
         if (country === 'US' && !state)
             throw new CliError('usage', 'the United States needs --state (e.g. --state US-CA)', EXIT.usage);
+        // 0121: the US needs a full address (street, city, ZIP) — the backend locates the sales-tax jurisdiction from it
+        if (country === 'US')
+            address = parseAddressFlags(args.flags);
+        else if (flagString(args.flags, 'line1') ||
+            flagString(args.flags, 'city') ||
+            flagString(args.flags, 'zip'))
+            throw new CliError('usage', '--line1/--line2/--city/--zip are only accepted for --country US', 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);
@@ -84,6 +138,7 @@ export async function runRegion(args, out, env = process.env) {
     const body = {
         country,
         ...(state ? { subdivision: state } : {}),
+        ...(address ? { address: { ...address, line2: address.line2 ?? undefined } } : {}),
         ...(acceptTerms ? { accept_terms: true, terms_version: current.terms_version_required } : {}),
     };
     const res = await api.request('POST', '/v1/developer/me/region', { body });

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 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 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 --line1 <street> [--line2 <apt>] --city <city> --zip <ZIP>]\n             [--accept-terms] [--json]                      US accounts need the full address (sales-tax jurisdiction)\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

@@ -16,7 +16,8 @@ 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 region set --country <CC> [--state US-XX --line1 <street> [--line2 <apt>] --city <city> --zip <ZIP>]
+             [--accept-terms] [--json]                      US accounts need the full address (sales-tax jurisdiction)
   aipay apps list [--json]
   aipay apps create --name <name> [--callback <url>] [--json]
   aipay apps callbacks list [--app <client_id>] [--dir <path>] [--json]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coswic/aipay",
-  "version": "0.6.0",
+  "version": "0.7.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",