@airwallex/airi-cli 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -1,11 +1,12 @@
 # airi-cli
 
-![Version](https://img.shields.io/badge/version-0.1.0--beta.1-orange)
+![Version](https://img.shields.io/badge/version-0.1.0--beta.3-orange)
 
 Command-line tool for the Airi wallet. Authenticate with OAuth, inspect your
 session, and drive an **agentic checkout** — list payment methods, create a
-payment mandate, fetch the single-use checkout credential, and report the
-result — from your terminal or an AI agent.
+payment mandate, fetch the single-use checkout credential, report the result,
+and cancel a mandate — or browse mandates already in the wallet, from your
+terminal or an AI agent.
 
 Results are printed to stdout as JSON, so they are easy to consume from scripts
 and agents.
@@ -13,7 +14,8 @@ and agents.
 ## Installation
 
 airi-cli is available for macOS and Linux as a single self-contained binary.
-Install it with npm:
+
+### npm
 
 ```bash
 npm install -g @airwallex/airi-cli@beta
@@ -23,17 +25,68 @@ This installs the `@airwallex/airi-cli` package, which downloads the prebuilt
 binary for your platform, verifies its SHA256 checksum, and puts `airi-cli` on
 your `PATH`.
 
-> **Agent skills:** deploy the bundled agent skills with `airi-cli skills install`
-> after installing (see [Skills](#skills)).
+To run it once without installing globally, use npx:
+
+```bash
+npx @airwallex/airi-cli@beta
+```
+
+#### Switching from a `curl | sh` install
+
+If you previously installed with the `install.sh` script (via `curl`), remove
+that copy first — otherwise it may stay ahead of the npm one on your `PATH` and
+keep shadowing it, so `airi-cli` keeps running the old binary.
+
+Check for more than one `airi-cli` on your `PATH`:
+
+```bash
+which -a airi-cli
+```
+
+If an entry under `~/.local/bin` (the `install.sh` default) shows up alongside
+the npm one, remove the old install:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/airwallex/airi-cli/master/install.sh | sh -s -- uninstall
+```
+
+Then reopen your shell and re-check with `which -a airi-cli`.
+
+### install.sh (fallback)
+
+If npm is not available, install the binary directly with the install script:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/airwallex/airi-cli/master/install.sh | sh
+```
+
+To uninstall (removes the binary):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/airwallex/airi-cli/master/install.sh | sh -s -- uninstall
+```
+
+### Install-time environment variables
 
-Environment variables (install time):
+Both install methods honour the same variables and behave identically, except
+where noted:
 
 | Variable | Description |
 |----------|-------------|
-| `AIRI_CLI_VERSION` | Download a specific release tag (e.g. `v0.1.0`) instead of the version bundled with the package. |
-| `AIRI_CLI_SKIP_DOWNLOAD` | Set to `1` to skip the binary download during install. |
+| `AIRI_CLI_VERSION` | Install a specific release tag (e.g. `v0.1.0`) instead of the default. With npm the pinned checksum only matches the package's own version, so overriding it there also requires `AIRI_CLI_SKIP_CHECKSUM=1`. |
+| `AIRI_CLI_INSTALL_DIR` | install.sh only: where to install (default: `$HOME/.local/bin`). npm always installs inside the package and ignores this. |
 | `AIRI_CLI_SKIP_CHECKSUM` | **Local development only.** Set to `1` to bypass SHA256 verification. Never use this in production or CI. |
-| `AIRI_CLI_BASE_URL` | Override the release host the binary is downloaded from (for internal mirrors). |
+| `AIRI_CLI_SKIP_SKILLS` | Set to `1` to skip deploying the bundled agent skills. |
+
+Both methods deploy the bundled agent skills at install time. You can also
+deploy them to a specific project with:
+
+```bash
+npx skills add airwallex/airi-cli
+```
+
+or re-run deployment any time with `airi-cli skills install` (see
+[Skills](#skills)).
 
 ### Checking for updates
 
@@ -151,6 +204,22 @@ after `auth login`, is:
 
 4. **Report the result** — after submitting the checkout, always report the
    outcome with `airi-cli mandate result --mandate-id <id> --result <SUCCEEDED|CANCELLED|DECLINED>`.
+5. **Cancel a mandate** — when the user asks to cancel, run
+   `airi-cli mandate cancel --mandate-id <id>`. The id is a flag, not a
+   positional argument. A cancelled mandate's status becomes `DENIED`. An
+   agent should cancel only when the user requests it.
+
+## Browsing mandates
+
+`airi-cli mandate list` returns the user's mandates, most recent first. Page
+with `--page` (0-based) and `--size` when `hasMore` is true. Filter with
+repeatable `--status` (`CREATED`, `AUTHENTICATED`, `READY`, `COMPLETED`,
+`FAILED`, `DENIED`) and `--created-from` / `--created-to` (full ISO-8601
+timestamps, for example `2026-10-01T00:00:00Z`).
+
+```bash
+airi-cli mandate list --status READY --size 10 --pretty
+```
 
 ## Commands
 
@@ -161,7 +230,9 @@ after `auth login`, is:
 | `airi-cli auth whoami` | Print the current sign-in status. |
 | `airi-cli auth logout` | Sign out by removing the stored session (local only). |
 | `airi-cli payment-methods list` | List payment methods available for agentic checkout. |
+| `airi-cli mandate list` | List payment mandates, most recent first. |
 | `airi-cli mandate create` | Create a payment mandate for a checkout. |
+| `airi-cli mandate cancel` | Cancel a payment mandate (`status` becomes `DENIED`). |
 | `airi-cli mandate get-credential` | Poll for and fetch the single-use checkout credential. |
 | `airi-cli mandate result` | Report the transaction outcome for a mandate. |
 | `airi-cli skills install` | Deploy the bundled agent skills into local AI-agent skill directories. |
@@ -186,6 +257,22 @@ Flags for `airi-cli auth whoami`:
 | --- | --- | --- |
 | `--verbose` | `false` | Include device details (name, platform, device id). |
 
+Flags for `airi-cli mandate list`:
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--status` | — | Filter by mandate status (repeatable): `CREATED`, `AUTHENTICATED`, `READY`, `COMPLETED`, `FAILED`, `DENIED`. |
+| `--created-from` | — | Include mandates created at or after this ISO-8601 time. |
+| `--created-to` | — | Include mandates created at or before this ISO-8601 time. |
+| `--page` | `0` | Zero-based page number. |
+| `--size` | `10` | Mandates per page (1–100). |
+
+Flags for `airi-cli mandate cancel`:
+
+| Flag | Description |
+| --- | --- |
+| `--mandate-id` | Mandate ID (required). |
+
 Flags for `airi-cli mandate create` (all required):
 
 | Flag | Description |

package/checksums.json

@@ -1,8 +1,8 @@
 {
   "checksums": {
-    "linux_amd64": "b6f0ea7935b018ef1752ddbde54eee6033b754709972ddffd1be4182b527934f",
-    "linux_arm64": "595b6f2ee28b8a254ad38d0e3db20947d06c4d0be77afa123348b2ba4bd6b8d4",
-    "macos_x86_64": "de210b14b727cecaf8f9d2feeb228d8374b3881e4dc52f7572466c13750cc2d5",
-    "macos_arm64": "11cfeaf377cae47048891735f616b40740b11c92f882d47739bcc035332fe4f0"
+    "linux_amd64": "c928039f16658358e493b27ab09710ef8d768552d4b55ffdc2a32375d7b8ce2d",
+    "linux_arm64": "267acceccdbecf8de21aabbdc654dc2552aa7f22da8d060a09cd33143bd5096a",
+    "macos_x86_64": "2fb413d8c48b0639f548e5a250bce69b95bcc0cd1267ba1758a16472e3bfda91",
+    "macos_arm64": "6e617b33e087a12e57e0c601d223aa55e809acbc211abbfa2f9c2ecd4510f25d"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@airwallex/airi-cli",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.3",
   "description": "Command-line tool for the Airi wallet — OAuth sign-in and agentic checkout from your terminal or an AI agent.",
   "bin": {
     "airi-cli": "bin/airi-cli.js"

package/scripts/postinstall.mjs

@@ -17,23 +17,22 @@
 //
 // Environment variables:
 //   AIRI_CLI_VERSION        download this release tag instead of the package's
-//                           own version (e.g. "v0.2.0" or "0.2.0"). The pinned
-//                           digest only matches the package's own version, so
-//                           an override requires AIRI_CLI_SKIP_CHECKSUM.
-//   AIRI_CLI_SKIP_DOWNLOAD  set to "1" to skip the download entirely. Useful
-//                           for offline CI that provides the binary another
-//                           way; the CLI won't run until it is present.
+//                           own version. The pinned digest only matches the
+//                           package's own version, so an override also requires
+//                           AIRI_CLI_SKIP_CHECKSUM.
 //   AIRI_CLI_SKIP_CHECKSUM  set to "1" to skip SHA256 verification (local-dev
 //                           only — never in production or CI).
-//   AIRI_CLI_BASE_URL       override the release host (internal mirror/testing).
+//   AIRI_CLI_SKIP_SKILLS    set to "1" to skip deploying the bundled agent skills.
+//   AIRI_CLI_BASE_URL       (internal, undocumented) override the release host.
+//                           The e2e tests point it at a local server; kept out
+//                           of the README so it isn't a supported user knob.
 //
-// The script is resilient by design: a download or verification failure prints
-// clear guidance but does NOT hard-fail the install, so installing a larger
-// dependency tree is not aborted by a transient network issue. The launcher
-// re-reports a missing binary with the same remediation if the CLI is run.
+// A download or verification failure warns but does NOT hard-fail: a transient
+// network issue must not abort a larger `npm install`. The launcher re-reports
+// a missing binary with the same remediation if the CLI is run.
 
 import { createWriteStream, existsSync } from 'node:fs'
-import { mkdir, mkdtemp, readFile, rm, chmod, rename } from 'node:fs/promises'
+import { mkdir, mkdtemp, readFile, rm, chmod, rename, copyFile } from 'node:fs/promises'
 import { createHash } from 'node:crypto'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
@@ -157,12 +156,29 @@ function extract(tarball, destDir) {
   if (res.status !== 0) throw new Error(`tar exited ${res.status}`)
 }
 
-async function main() {
-  if (process.env.AIRI_CLI_SKIP_DOWNLOAD === '1') {
-    warn('AIRI_CLI_SKIP_DOWNLOAD=1 — skipping binary download.')
+// Deploy the agent skills bundled in the binary, mirroring install.sh: invoke
+// the freshly installed binary's `skills install`, honouring AIRI_CLI_SKIP_SKILLS.
+// Best-effort — a failure warns but never fails the install (the user can
+// re-run `airi-cli skills install`).
+function deploySkills(bin) {
+  if (process.env.AIRI_CLI_SKIP_SKILLS === '1') {
+    warn('AIRI_CLI_SKIP_SKILLS=1 — skipping skill deployment.')
     return
   }
+  log('deploying agent skills')
+  // stdio inherited so the CLI's own output — including the target directories
+  // it installed into — flows through to the npm install log.
+  const res = spawnSync(
+    bin,
+    ['--no-telemetry', '-o', 'text', 'skills', 'install'],
+    { stdio: 'inherit' }
+  )
+  if (res.error || res.status !== 0) {
+    warn(`skill deployment failed; retry later with: ${BIN_NAME} skills install`)
+  }
+}
 
+async function main() {
   let platform
   try {
     platform = detectPlatform()
@@ -230,18 +246,19 @@ async function main() {
       throw new Error(`archive did not contain expected '${BIN_NAME}' binary`)
     }
     const finalPath = binPath()
-    // Stage the new binary INSIDE the vendor dir (same filesystem as finalPath)
-    // and rename it into place. Renaming within one filesystem is atomic and
-    // avoids EXDEV (which a rename from os.tmpdir() across filesystems would
-    // hit) — and because the staged copy is fully in place and executable
-    // before the swap, a failure never leaves the old working binary deleted
-    // with no replacement.
+    // copyFile (not rename) crosses devices without EXDEV; staging inside the
+    // vendor dir keeps the final swap a same-device atomic rename, so a failure
+    // never leaves the old working binary deleted with no replacement.
     const staged = path.join(dir, `.${BIN_NAME}.new`)
     await rm(staged, { force: true })
-    await rename(extracted, staged)
+    await copyFile(extracted, staged)
     await chmod(staged, 0o755)
     await rename(staged, finalPath)
-    log(`installed binary to ${finalPath}`)
+    log(`installed ${BIN_NAME} ${tag}`)
+
+    // Only after the binary is verified and in place, so skills are never
+    // deployed from a half-installed or unverified CLI.
+    deploySkills(finalPath)
   } catch (err) {
     warn(`failed to download the airi-cli binary: ${err.message}`)
     warn(