@staqon/cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2026 VistarKriya Marketings Private Limited. All rights reserved.
+
+This software is proprietary. No licence is granted to copy, modify, merge,
+publish, distribute, sublicense or sell it, except as expressly agreed in
+writing with the copyright holder. It is provided "as is", without warranty of
+any kind.

package/README.md

@@ -1,3 +1,279 @@
-# Temporary Holding Version
+# @staqon/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command-line client for the StaqOn partner API. Send messages, post comments, run push-approval
+verifications and broadcast ads as your workspace, from a terminal or a script.
+
+- Requires **Node.js 20 or newer**.
+- Talks to `https://staqon.one` by default (override with `--base-url` or `STAQON_BASE_URL`).
+
+## Install
+
+```sh
+npm install -g @staqon/cli
+staqon --version
+```
+
+## Getting started
+
+1. **The workspace owner creates an API key first.** Open your workspace at
+   `<your-workspace-url>/workspace/settings.php?w=<your-workspace-slug>&tab=api` and, under the
+   relevant card (Messaging API, Ad API, etc.), generate a key for the team you want the CLI to
+   act as. Messaging and Ad keys both require a **Link** key to already exist on that same tab �
+   set that up first if you see a "set up Link API first" notice.
+2. On that same `api` tab, turn on **"Allow CLI access"** for the workspace. This is a separate
+   switch from the API key above � it must be ON before `staqon login` can be approved. Turning it
+   OFF immediately signs out every CLI session for that workspace.
+3. Run `staqon login` from the machine or server you want to use. It prints a URL and a short code.
+4. The **workspace owner** opens that URL (it's also reachable directly at `/cli`) and approves the
+   code � they may be asked for their MPIN if their web session is old.
+5. Run `staqon whoami`. It lists every key the CLI can use and which teams hold it. If a command you
+   need isn't listed, go back to step 1 for that key type � the CLI itself can never create or see
+   API keys, only the owner can.
+6. Send your first message:
+   ```sh
+   staqon message send --email member@example.com -m "Hello from the CLI"
+   ```
+7. **Member approval (exit code 6).** Most calls that reach a specific member � direct messages,
+   comments, internal messages, verification requests � require that member to have approved
+   linking with your workspace in their own StaqOn app first. If they haven't, the CLI exits with
+   code 6 and a message like "This member hasn't approved linking with this workspace." This isn't
+   something the CLI or the owner can bypass � the member has to approve it on their end.
+
+## Sign in
+
+There is no separate `init` step: `staqon login` is the whole setup.
+
+```sh
+staqon login            # prints a URL and a one-time code
+staqon login --open     # also opens the URL in your browser
+```
+
+1. The CLI shows a verification URL and a code.
+2. **The workspace owner** opens the URL and approves the code (they may be asked for their MPIN).
+3. The CLI polls, receives a session token, and stores it.
+
+Where the token lives: the OS keychain when available, otherwise a user-only file
+(`credentials.json` in the `staqon` config directory: `%APPDATA%\staqon` on Windows,
+`$XDG_CONFIG_HOME/staqon` or `~/.config/staqon` elsewhere). The CLI says so when it has to use the file.
+
+| Command | What it does |
+|---|---|
+| `staqon whoami` | Workspace, session expiry, rate limits, and which teams can do what |
+| `staqon refresh` | Rotate the session token (the old one works for 5 more minutes) |
+| `staqon logout` | Forget the local token. Revoking it is done by the owner in the web UI |
+
+### Running unattended (a server sending automatic alerts)
+
+Session tokens are sliding-expiry: **90 days of inactivity invalidates them, and every call extends
+that window**, up to a hard cap of **1 year from the original login**. For a server that calls the
+CLI regularly (e.g. daily alerts), the token effectively never goes stale on its own � but you should
+still rotate it well before the 90-day mark, in case the server is ever idle for a stretch:
+
+- Run `staqon refresh` on a schedule (cron / Task Scheduler) every 30-60 days. It rotates the token;
+  the old one keeps working for 5 more minutes, so overlap is safe. Save the new token exactly as
+  `staqon` does (OS keychain, or the user-only `credentials.json` file) � don't hardcode it elsewhere.
+- Once a year, at the hard cap, `refresh` will stop working and the command exits with an auth error.
+  At that point a human (the workspace owner, or whoever can reach the approval URL) has to run
+  `staqon login` again � there is no way around this step by design, since it's what lets the owner
+  revoke access.
+- Do **not** try to use the partner's raw API key directly as a substitute for a long-lived token:
+  the CLI protocol deliberately never hands the API key to the CLI session at all (see the server
+  contract) � the CLI only ever gets a revocable, rate-limited session token, scoped to the CLI's own
+  separate limits, so the partner's production API key headroom is never affected by CLI traffic.
+  `STAQON_TOKEN` (below) is the only supported "skip login" path, and it still expires the same way.
+
+For CI, set `STAQON_TOKEN` instead of logging in (and `STAQON_BASE_URL` if not production). Tokens are
+only ever sent to the host that issued them, and the CLI refuses to send one to a different `--base-url`.
+`refresh` is not available for `STAQON_TOKEN` sessions -- if you use this path, you are responsible for
+replacing the value yourself before it expires (same 90-day sliding / 1-year hard cap rules apply).
+
+## Teams
+
+Most calls are made on behalf of a **team** that holds the right API key. Selection order:
+
+1. `--team <id|slug>` on the command line
+2. the saved default (`staqon use <team>`; `staqon use` shows it; `staqon use --clear` removes it)
+3. if the server answers `team_required`:
+   - in a terminal, you are asked to pick one (and can save it as the default);
+   - otherwise the CLI exits with code 5 and lists the eligible teams. It never picks one for you.
+
+`team_not_eligible` (exit 5) means the chosen team has no key for that call; the error lists the teams that do.
+`staqon whoami` shows which teams can send messages and ads.
+
+## Commands
+
+Every command accepts the global options below. `--to` takes an email **or** a username and converts it if the
+endpoint wants the other kind (see [Identity](#identity-email-vs-username)).
+
+| Global option | |
+|---|---|
+| `--json` | Machine-readable: raw response body on stdout, errors as JSON on stderr |
+| `--team <team>` | Team to act as |
+| `--base-url <url>` | API host |
+| `--verbose` | Print request lines and trace ids to stderr |
+| `--no-color` | Disable colors |
+
+### Messaging
+
+```sh
+staqon message send --email ada@example.com -m "Hello"
+staqon message send --to ada_username -m "Hello"          # username resolved to an email
+staqon message send --email ada@example.com --message-file note.txt   # or -m - to read stdin
+
+staqon messages --username ada_username --limit 20        # read a thread (needs the member's approved link)
+staqon messages --username ada_username --before 152698   # page backwards (--after pages forwards)
+
+staqon comment --username ada_username -c "Looks good" --external-ref order-1042
+staqon comment --username ada_username -c "Status" --card @card.json
+
+staqon internal message --email ada@example.com -m "FYI" --title "Heads up" --link-url https://example.com
+```
+
+- Message and comment text: up to 60,000 characters. `--external-ref` (max 190) is an idempotency key: a repeat is
+  rejected and nothing is posted.
+- `messages --limit` is 1-200 (default 50). Attachment URLs in results are signed and **expire after 1 day**;
+  re-fetch the thread for fresh ones.
+- `internal message` sends to a member's one-way API Messages feed and needs their approval.
+
+### Members
+
+```sh
+staqon members list --search "Ada" --limit 50 --page 2
+staqon member ada@example.com            # or: staqon member --member-id 311
+staqon internal members --search ada     # internal directory (search also matches username)
+```
+
+`members list` shows email and username side by side. `--limit` is **1-100**: the directory is slow server-side
+(about 0.35 s per row) and larger pages hit the gateway timeout. Member searches match **name or email**, not username.
+
+### Verification (push approval)
+
+```sh
+staqon verify start --username ada_username --action "Approve payout #1042" \
+  --context "Payout of 5,000 to account ending 1234" --ttl 60
+staqon verify check <verification_id>             # prints Verified. / Not verified: <reason>
+staqon verify check <verification_id> --strict    # exit 1 unless verified
+staqon verify cancel <verification_id>
+```
+
+- `--ttl` is clamped to 30-180 seconds (default 30). `--action` max 100 chars, `--context` max 500.
+- `check` reasons include `pending`, `declined`, `timeout` and `cancelled`. Without `--strict`, `check` exits 0 for any
+  answer; with it, only a verified result exits 0.
+- `cancel` after the member answered returns exit 1 with "Too late to cancel"; after expiry, "already expired".
+- Needs the member's approved link.
+
+### Ads
+
+Ads are delivered asynchronously by a background worker.
+
+```sh
+staqon ad image banner.png                          # upload only; nothing is delivered
+staqon ad create --body-file ad.txt --button-label "Open" --button-url https://example.com --image banner.png --wait
+staqon ad status <ad_request_id>                    # or --external-ref <ref>
+```
+
+- Images: JPEG, PNG or WebP (checked on file contents), **max 300 KB**; the server crops to 16:9 and downsizes to
+  at most 1280x720, so the stored size differs from your file.
+- `ad create`: body 50-900 characters; success is HTTP 202 plus an `ad_request_id`. `--wait` polls every 5 s for up
+  to 10 minutes. `--external-ref` (max 150) is an idempotency key.
+
+### Raw access
+
+```sh
+staqon api external/members -q search=ada -q limit=10
+staqon api external/message -d '{"email":"ada@example.com","message":"Hi"}'
+```
+
+Calls any CLI-proxy endpoint directly: `external/{message,messages,comment,members,member,ad,ad-image,ad-status,
+staqon-verify-start,staqon-verify-check,staqon-verify-cancel}` and `internal/{message,members}`.
+`-d` takes inline JSON, `@file.json` or `-` for stdin; `-F k=v` / `-F k=@path` sends multipart.
+
+### Cards
+
+`--card` (comment, internal message, verify start) takes a JSON object, inline, `@file.json` or `-`. The CLI
+validates it before sending: required `header_color` (one of the palette colors), `title` (200) and `body` (2000);
+optional `meta_title`, `sub_body`, `icon`, `button` (`label`, `url`; not allowed on verification cards) and `table`
+(2-6 columns, 1-500 rows). Unknown keys are rejected.
+
+## Identity: email vs. username
+
+The endpoints disagree: `message send` wants an email, while `messages`, `comment`, `verify` want a username. Give
+`--email`, `--username` or `--to <either>`; the CLI converts when needed.
+
+- email -> username is one fast lookup.
+- username -> email tries the directory search, then looks up the member's name via their thread and searches by
+  name (fast, but only for members linked to your workspace), then **pages through the whole directory**. That last
+  step can take minutes on a large workspace. **If you know the email, pass `--email`.**
+
+## The consent model (why some calls return 403)
+
+Members control what a workspace may do. For `messages`, `comment`, `verify *` and `internal message`, the member must
+have approved the link with your workspace in their app. If they have not, the server answers 403 and the CLI prints
+a friendly message and exits with **code 6**:
+
+```
+Error: This member hasn't approved linking with this workspace.
+trace id: ...
+Server said: No approved link for this member
+The member has to approve the link in their app; the CLI can't do it for them.
+```
+
+The CLI can't work around it. Ask the member to approve, then retry. A 403 that is *not* about consent (CLI access
+switched off, workspace inactive) exits with code 3 instead.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | General failure: server rejected the request (4xx/5xx), network error or timeout, `verify check --strict` not verified, cancel too late or expired |
+| 2 | Usage error: bad flags or input, caught before anything is sent; also a token used against a different host |
+| 3 | Authentication: not logged in, session expired/revoked (401), or access denied (non-consent 403) |
+| 4 | Rate limited (429): session 30/min, 3,000/day, or the API key's own ceiling. `Retry after` is shown when sent |
+| 5 | Team or key problem: `team_required` (non-interactive), `team_not_eligible`, `no_key` |
+| 6 | Member has not approved the link (consent 403) |
+| 130 | Interrupted (Ctrl-C) |
+
+The CLI never retries on its own, except re-asking once after you pick a team interactively.
+Requests time out after 30 s (120 s for member directory listings); override with `STAQON_TIMEOUT_MS`.
+
+## `--json`
+
+With `--json`, success prints the server's response body, unchanged, on stdout. Errors print **one JSON object on
+stderr** and nothing on stdout:
+
+```json
+{
+  "error": "This member hasn't approved linking with this workspace.",
+  "exit_code": 6,
+  "status": 403,
+  "trace_id": "30becdb4-daac-46b0-9fb6-395249329632",
+  "body": { "ok": false, "error": "No approved link for this member" },
+  "hint": "Server said: No approved link for this member\n..."
+}
+```
+
+`status`, `trace_id` and `body` appear for errors that came from the server; client-side errors have only
+`error`, `exit_code` and optionally `hint`. In `--json` mode the CLI never prompts, so team selection must be
+explicit (`--team` or a saved default). Tokens are redacted (`stq_cli_***`) from all output. Quote the `trace_id`
+when contacting support.
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `STAQON_TOKEN` | Use this session token instead of the stored login |
+| `STAQON_BASE_URL` | API host (default `https://staqon.one`) |
+| `STAQON_TIMEOUT_MS` | Request timeout in milliseconds |
+
+## Development
+
+```sh
+npm install
+npm run build      # bundle to dist/
+npm test           # 52 mocked tests; no network, no login needed
+npm run test:live  # optional; needs a login: STAQON_LIVE_USERNAME=... STAQON_LIVE_EMAIL=... (slow case: SLOW=1)
+```
+
+The mocked tests run the real CLI against a local fake server with an isolated config directory, so they never touch
+your real login or keychain.

package/bin/staqon.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';