@flintpay/cli 0.2.0 → 0.3.0

package/README.md

@@ -10,6 +10,8 @@ Every command maps to a documented `/v1` route, so anything you can do over HTTP
 npm install -g @flintpay/cli
 ```
 
+On macOS and Linux, run `flint upgrade` to update the global package and its platform binary to the latest stable release. On Windows, the command prints the exact npm update to run after closing the CLI.
+
 This package resolves a prebuilt binary for your platform. Node `>=18` is required to run the installer. On macOS and Linux you can install with Homebrew instead:
 
 ```bash
@@ -27,12 +29,36 @@ flint doctor
 
 Confirm the code shown in your terminal and approve CLI access on the website. Flint validates the OAuth session and stores its access and refresh tokens in your OS keychain. Use `--no-open` to open the printed link yourself, `--profile NAME` for an existing profile, or `--live` to explicitly request production access.
 
-Browser login has been verified against Flint staging. To use staging, set `FLINT_BASE_URL=https://api.staging.withflintpay.com` for login and subsequent commands. Production rollout is separate; use `flint auth import` on servers without browser login support.
+The existing single-context browser login has been verified against Flint staging. To use staging, set `FLINT_BASE_URL=https://api.staging.withflintpay.com` for login and subsequent commands. Production rollout is separate; use `flint auth import` on servers without browser login support.
 
 Access tokens refresh automatically as needed. `flint auth logout --confirm` revokes the OAuth session before removing its local credentials. If the server does not confirm revocation, logout reports failure and retains the credentials for retry. Imported API-key logout still removes only the local key.
 
 `flint login` is a shortcut for `flint auth login`. Related shortcuts: `flint logout` for `flint auth logout`, and `flint whoami` for `flint auth status`.
 
+### Sessions and contexts
+
+With a server that supports multi-context sessions, approve access to selected merchants, sandboxes, and live contexts once in the browser, then select where commands run:
+
+```sh
+flint login
+flint context list
+flint context switch                        # interactive selector
+flint context switch ctx_development        # select an authorized sandbox
+flint context switch ctx_production --live   # explicitly select a live default
+flint auth status --context ctx_development  # one command, without changing the default
+flint reauth                                # change browser-approved access
+```
+
+`flint login` reuses a valid saved OAuth session and starts browser approval again when the server confirms that the session expired or was revoked. Temporary connection failures or loss of access to one context do not automatically replace the session. Use `flint login --new-session` to replace it after browser approval; the CLI then attempts to revoke the previous session. `flint logout --confirm` revokes the entire session across its contexts.
+
+Manage and revoke sessions on the [CLI sessions page](https://app.withflintpay.com/developers/cli). Browser authorization sends your computer's hostname and operating system to help identify the session.
+
+Context selection uses `--context ID`, then a project's `.flint/config.json` `context` field, then the profile default. For example, `{"context":"ctx_development"}` pins a project. Switching changes the profile default, not a project pin. Each running command retains its starting context. Access tokens remain restricted to one context and refresh automatically. LIVE contexts are labeled in the selector and command diagnostics; selected multi-context sessions do not need `--live` on every command, while sensitive/destructive operations still require confirmation.
+
+Environment credentials (`FLINT_API_KEY`, `FLINT_ACCESS_TOKEN`, or `FLINT_CHECKOUT_SESSION_SECRET`) override configured browser-session contexts. An explicit `--context` cannot be combined with these overrides. Merchant and sandbox guards still apply.
+
+**Backend rollout required:** multi-context listing, switching, and reauthorization require the new session endpoints and token metadata. Existing single-context OAuth sessions remain usable and keep their existing live-mode safeguards. Run `flint reauth` after the server is upgraded to authorize multiple contexts. The new multi-context flow has not yet been verified against a deployed backend.
+
 ### API keys and automation
 
 For manual setup, create a key in the [Flint dashboard](https://app.withflintpay.com/developers/api-keys) and run `flint auth import`. For CI, supply `FLINT_API_KEY` through your secret store and set `FLINT_NO_INPUT=1`. `flint signup` remains available for creating an account from the terminal.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flintpay/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Flint Pay command-line interface",
   "mcpName": "com.withflintpay/cli",
   "license": "Apache-2.0",
@@ -16,11 +16,11 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@flintpay/cli-darwin-arm64": "0.2.0",
-    "@flintpay/cli-darwin-amd64": "0.2.0",
-    "@flintpay/cli-linux-arm64": "0.2.0",
-    "@flintpay/cli-linux-amd64": "0.2.0",
-    "@flintpay/cli-windows-amd64": "0.2.0"
+    "@flintpay/cli-darwin-arm64": "0.3.0",
+    "@flintpay/cli-darwin-amd64": "0.3.0",
+    "@flintpay/cli-linux-arm64": "0.3.0",
+    "@flintpay/cli-linux-amd64": "0.3.0",
+    "@flintpay/cli-windows-amd64": "0.3.0"
   },
   "repository": {
     "type": "git",