@staqon/cli 0.1.0 → 0.1.1

package/README.md

@@ -13,6 +13,32 @@ 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.
@@ -36,9 +62,30 @@ Where the token lives: the OS keychain when available, otherwise a user-only fil
 | `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.
+`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
 

package/dist/cli.js

@@ -330,15 +330,25 @@ The member has to approve the link in their app; the CLI can't do it for them.`
           teams,
           hint: "Eligible teams: " + (teams.map((t) => t.team_slug ?? t.team_id).join(", ") || "(none listed)") + "\nUse --team <team>, or staqon use <team> (staqon use --clear drops a stale default)."
         });
-      if (code === "no_key")
+      if (code === "no_key") {
+        const o = asObj(r.body);
+        const surface = typeof o["surface"] === "string" ? o["surface"] : void 0;
+        const purpose = typeof o["purpose"] === "string" ? o["purpose"] : void 0;
+        const kind = purpose ? `${purpose.charAt(0).toUpperCase()}${purpose.slice(1)}${surface === "internal" ? " (internal)" : ""} key` : "key of that kind";
         throw new ApiError(
-          msgOf(r.body, "The workspace has no active key of that kind."),
+          `This workspace has no active ${kind}.`,
           Exit.TEAM_OR_KEY,
           409,
           r.body,
           r.traceId,
-          { hint: "The workspace owner must create one in settings \u2192 API. The CLI cannot." }
+          {
+            hint: `The workspace owner creates it at:
+  <your-workspace-url>/workspace/settings.php?w=<workspace-slug>&tab=api
+Messaging and Ad keys both require a "Link" key to be set up first on that same tab.
+The CLI itself can never create or see this key.`
+          }
         );
+      }
     }
     if (r.status === 429) {
       const limit = asObj(r.body)["limit"];
@@ -579,9 +589,20 @@ function registerAuth(program2) {
     const l = b["limits"] ?? {};
     out(`${pc3.bold("Limits")}     ${l.used_last_minute ?? "?"}/${l.per_minute ?? "?"} per min, ${l.used_today ?? "?"}/${l.per_day ?? "?"} today`);
     out(pc3.bold("Access"));
-    for (const a of b["access"] ?? []) {
-      const teams = (a.teams ?? []).map((t) => t.team_slug ?? t.team_id).join(", ") || "-";
-      out(`  ${a.surface ?? ""}${a.purpose ? ` / ${a.purpose}` : ""}  teams: ${teams}${a.automatic ? " (automatic)" : ""}`);
+    const access = b["access"] ?? [];
+    if (!access.length) {
+      out(pc3.yellow("  No API keys on this workspace yet."));
+      out(pc3.dim("  The workspace owner creates one at Settings -> API (tab=api), e.g.:"));
+      out(pc3.dim(`    ${baseUrlFor()}/workspace/settings.php?w=${ws?.slug ?? "<slug>"}&tab=api`));
+    }
+    for (const a of access) {
+      const teams = (a.teams ?? []).map((t) => t.team_slug ?? t.team_id).join(", ");
+      const label = `${a.surface ?? ""}${a.purpose ? ` ${a.purpose}` : ""}`.trim() || "key";
+      if (!teams) {
+        out(pc3.yellow(`  No ${label} key on any team. Create one at Settings -> API.`));
+      } else {
+        out(`  ${label}  teams: ${teams}${a.automatic ? " (automatic)" : ""}`);
+      }
       if (ctx.verbose) out(pc3.dim(`    endpoints: ${(a.endpoints ?? []).join(", ")}`));
     }
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staqon/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "StaqOn command-line client for partner developers",
   "keywords": [
     "staqon",
@@ -31,7 +31,8 @@
     "test": "node --test test/cli.mock.test.mjs test/validate.test.mjs",
     "pretest:live": "tsup --config tsup.test.config.ts",
     "test:live": "node --test test/identity.live.test.mjs",
-    "prepublishOnly": "npm run typecheck && npm run build && npm test"
+    "prepublishOnly": "npm run typecheck && npm run build && npm test",
+    "prepare": "npm run build"
   },
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {