@credda/cli 0.1.1 → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Credda, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,85 +1,290 @@
-# @credda/cli
-
-The official Credda CLI — portable trust from the terminal. A thin client
-over [`@credda/js`](../sdk)'s headless export; **no scoring logic lives
-here** (the deterministic score is computed only by the API's
-`score.service`).
-
-## Install / run
-
-Not yet published to npm (same status as `@credda/mcp-server`). Run from a
-checkout:
-
-```sh
-pnpm --filter @credda/js run build   # build the SDK first (dist/ is gitignored)
-pnpm --filter @credda/cli run build
-node packages/cli/dist/index.js help
-```
-
-## Commands
-
-Public — no API key:
-
-```sh
-credda lookup <token>       # trust check for a share token (GET /verify/:token)
-credda export <token>       # full self-verifying trust export bundle
-credda verify <file|->      # OFFLINE-verify a credential someone handed you:
-                            #   a W3C VC-JWT, a compact Trust Credential, or a
-                            #   saved trust-export bundle — auto-detected.
-                            #   '-' reads stdin. Exit 0 valid / 2 invalid.
-credda registry             # federated trust registry (/.well-known)
-credda did                  # issuer DID document
-```
-
-Platform — set `CREDDA_API_KEY` (a `crd_live_…` platform key):
-
-```sh
-credda score <userId>       # current score
-credda explain <userId>     # factor-level explanation
-credda components <userId>  # six named 0-100 components
-credda risk <userId>        # advisory risk signals
-credda usage [days]         # your platform's metered usage
-credda mint <userId>        # mint a share token
-credda revoke <userId>      # revoke a share token
-```
-
-Webhooks — set `CREDDA_API_KEY`:
-
-```sh
-credda webhooks list
-credda webhooks create https://hooks.you/credda score.updated score.band_changed
-                            # signing secret shown ONCE
-credda webhooks delete <id>
-credda webhooks test <id>   # synthetic signed delivery
-credda webhooks deliveries <id>   # recent attempts, incl. retries
-```
-
-Local development:
-
-```sh
-CREDDA_WEBHOOK_SECRET=whsec_... credda listen 4141
-```
-
-`credda listen` runs a local receiver that HMAC-verifies each delivery (the
-same check your production handler must do) and pretty-prints the payload.
-Credda delivers to public HTTPS only, so expose the port with your own tunnel
-(e.g. `cloudflared tunnel --url http://localhost:4141`) and register the
-tunnel URL as the webhook — the Stripe-CLI-style local loop without Credda
-running a tunneling service.
-
-Environment: `CREDDA_API_URL` overrides the API base (default
-`https://api.credda.io`); `CREDDA_WEBHOOK_SECRET` enables signature
-verification in `credda listen`.
-
-## Design
-
-- `src/cli.ts` is the pure command router — no `process`, `fs`, or env access,
-  so the whole surface is unit-tested with a mocked `CreddaClient` (same
-  pattern as `packages/mcp`'s `tools.ts`).
-- `src/index.ts` only wires the real environment (env vars, stdin/file
-  reading, exit codes).
-- `verify` uses the SDK's offline verifiers (WebCrypto Ed25519 + StatusList
-  revocation) — the point is that a received credential can be checked
-  without trusting the wire it arrived on.
-- Every command is read-only against the score. `mint`/`revoke` manage a
-  share token — a capability, not a score write.
+# @credda/cli
+
+The official Credda CLI: portable trust from the terminal. A thin client over
+[`@credda/js`](https://www.npmjs.com/package/@credda/js)'s headless export;
+**no scoring logic lives here** (the deterministic score is computed only by
+the API's `score.service`).
+
+## Install
+
+```sh
+npm install -g @credda/cli   # or: pnpm add -g @credda/cli
+credda help
+```
+
+Node 20 or newer. Nothing else to configure for the public commands below.
+
+Prefer not to install globally? `npx @credda/cli help` works the same way.
+
+`credda help` always lists exactly what the version you installed can do, so
+treat it, not this file, as the authority on your copy. `credda --version`
+prints that version.
+
+## Commands
+
+Start here, if you hold a sandbox key (`CREDDA_API_KEY` of the `crd_test_`
+kind; a live key is refused before anything happens):
+
+```sh
+credda quickstart           # seed the sandbox with synthetic subjects, print
+                            #   their real scores, then close the counterparty-
+                            #   confirmation loop so you finish holding a real
+                            #   VERIFIED event rather than a number you read
+             --no-confirm   # stop after the seed; skip the confirmation loop
+```
+
+Public — no API key:
+
+```sh
+credda lookup <token>       # trust check for a share token (GET /verify/:token)
+credda export <token>       # full self-verifying trust export bundle
+credda verify <file|->      # OFFLINE-verify a credential someone handed you:
+                            #   a W3C VC-JWT, a compact Trust Credential, or a
+                            #   saved trust-export bundle — auto-detected.
+                            #   '-' reads stdin. Exit 0 valid / 2 invalid.
+credda registry             # federated trust registry (/.well-known)
+credda did                  # issuer DID document
+credda benchmarks           # cohort-benchmark catalog: the dimensions you can
+                            #   benchmark on and the k-anonymity floor below
+                            #   which no cohort is disclosed
+credda reason-codes         # adverse-action reason-code catalog (ECOA / Reg B).
+                            #   Credda supplies the attribution only — it is not
+                            #   a creditor and issues no notice.
+credda badges list          # the closed set of Open Badges 3.0 achievements
+credda badges get <badgeId> #   this issuer will sign, and one definition
+credda outcome-templates [industry]
+                            # how a business maps its work to Credda events, and
+                            #   WHO confirms each outcome. Guidance only.
+credda professional-record public <token>
+                            # the professional record behind a share token —
+                            #   the token IS the subject's consent to present it
+credda career-export --token <token>
+                            # the whole verified record as a JSON Resume document,
+                            #   behind a share token (no API key sent)
+```
+
+Platform — set `CREDDA_API_KEY` (a `crd_live_…` platform key):
+
+```sh
+credda score <userId>       # current score
+credda explain <userId>     # factor-level explanation
+credda components <userId>  # six named 0-100 components
+credda risk <userId>        # advisory risk signals
+credda trust-summary <userId> [--narrative]
+                            # deterministic, evidence-based summary + strengths
+                            #   + risks. It explains; it is never a verdict.
+                            #   --narrative adds an advisory AI retelling.
+credda benchmark <userId> [--dimension <d>]
+                            # where the subject sits in its cohort: percentile
+                            #   + the cohort distribution. `available:false`
+                            #   when the cohort is below the k-anonymity floor
+                            #   (insufficient_data) or the subject has no score
+                            #   yet (no_score).
+credda distribution [--dimension <d>] [--cohort <c>]
+                            # aggregate, k-anonymised cohort distribution.
+                            #   Omit --cohort for every cohort on the dimension.
+credda users [--score-min <n>] [--score-max <n>] [--band <b>]
+             [--subject-type <PERSON|AGENT|ORGANIZATION>]
+             [--scored|--unscored] [--frozen]
+             [--active-since <iso>] [--registered-since <iso>]
+             [--registered-before <iso>] [--verified] [--min-verified <n>]
+             [--sort <score|lastActivity|registered|externalId>]
+             [--order <asc|desc>] [--cursor <c>] [--limit <n>]
+                            # query + export your book of subjects. The filter
+                            #   set is closed and validated — no query DSL.
+                            #   A subject with no score yet reports null, never
+                            #   a placeholder; list those with --unscored.
+credda book-summary [same filters as "users"]
+                            # size a segment WITHOUT paging it: how many match,
+                            #   how many are scored, band mix, median/mean.
+                            #   Null (not 0) when nothing in it is scored.
+credda usage [days]         # your platform's metered usage (trailing window)
+credda usage --from 2026-06-01 --to 2026-06-30
+                            # explicit statement range (mutually exclusive
+                            # with [days])
+credda usage --csv usage.csv
+                            # write the flat CSV statement to a file
+                            # (raw ?format=csv fetch; combines with either window)
+credda activity [--action <A>] [--from <t>] [--to <t>] [--cursor <c>] [--limit <n>]
+                            # your platform's own activity/audit log,
+                            # newest-first, cursor-paginated
+credda verified-profile <userId>
+                            # how much of a subject's CLAIMED record
+                            #   (education/skills/certifications/employment) is
+                            #   third-party verified. Counts WHETHER a claim is
+                            #   verified, never how prestigious it is — and can
+                            #   never move the Reliability Score.
+credda qualify <userId> --category <education|skill|certification|employment>
+        [--label <l>] [--issuer <i>] [--verified-by <witness>]
+                            # record a qualification claim. Always recorded;
+                            #   counts as VERIFIED only with a genuine
+                            #   third-party --verified-by witness.
+credda professional-record get <userId>
+                            # résumé-shaped summary of a VERIFIED work record.
+                            #   Describes a record — not a hiring verdict, a
+                            #   background check, or a consumer report.
+credda professional-record credential <userId> [--ttl <seconds>]
+                            # mint the signed, offline-verifiable credential
+                            #   (+ an "Add to LinkedIn" certification link)
+credda reliability-report <userId> [--recent <n>] [--benchmark]
+                            # the consolidated worker reliability report a
+                            #   staffing agency or employer weighs. EVIDENCE, not
+                            #   a hire / place / rank verdict or a consumer report.
+                            #   Use --token <token> for the public worker-consent
+                            #   route (NO API key).
+credda career-export <userId>
+                            # the whole verified record as an open JSON Resume
+                            #   document. Use --token <token> for the public route.
+credda mint <userId>        # mint a share token
+credda revoke <userId>      # revoke a share token
+```
+
+Confirmation requests — the counterparty-confirmation primitive. You propose an
+outcome and deliver the one-time token yourself; the event is written, verified,
+only when that distinct party confirms:
+
+```sh
+credda confirmations create --user worker_7 --type CONTRACT_FULFILLED \
+        --counterparty client_42 --counterparty-name "Acme Ltd" \
+        --description "Kitchen refit" [--stake HIGH] [--value 1200] \
+        [--due <iso>] [--completed <iso>] [--return-url <url>] \
+        [--expires-in 14] [--idempotency-key <k>]
+                            # needs CREDDA_API_KEY. The token is shown ONCE;
+                            #   creating a request writes no event.
+credda confirmations batch <file.json> [--idempotency-key <k>]
+                            # the ACTIVATION ENGINE — bulk-create up to 100
+                            #   requests from a JSON file (an array of request
+                            #   bodies, or { "requests": [...] }), warming a cold
+                            #   ledger from your book. Needs CREDDA_API_KEY; each
+                            #   ok item's token is shown ONCE.
+credda confirmations list [--status PENDING] [--cursor <c>] [--limit <n>]
+credda confirmations get <id>
+credda confirmations cancel <id>          # only while PENDING
+
+# ⚠️ These two are the COUNTERPARTY's calls and take NO API key — they hold a
+# token, not a Credda account:
+credda confirmations preview <id> --token <t>
+credda confirmations respond <id> --token <t> --confirm
+credda confirmations respond <id> --token <t> --decline
+                            # --confirm writes the verified event; --decline
+                            #   writes nothing. Single-use either way, and
+                            #   there is no default: you must say which.
+```
+
+Reference requests — the qualifications-half sibling of confirmations. A résumé
+claim (employment / education / certification / skill) becomes verified when the
+named third party who was there confirms it; a reference never moves the score:
+
+```sh
+credda references create --user worker_7 --category employment \
+        --counterparty manager_42 --label "Senior Engineer" \
+        --issuer "Acme Ltd" [--jurisdiction US-CA] [--reference EMP-9910] \
+        [--counterparty-name "Dana Lee"] [--description <d>] \
+        [--return-url <url>] [--expires-in 14] [--idempotency-key <k>]
+                            # needs CREDDA_API_KEY. The token is shown ONCE;
+                            #   creating a request records no qualification.
+credda references list [--status PENDING] [--cursor <c>] [--limit <n>]
+credda references get <id>
+credda references cancel <id>             # only while PENDING
+
+# ⚠️ These two are the REFERENCE's calls and take NO API key — they hold a
+# token, not a Credda account:
+credda references preview <id> --token <t>
+credda references respond <id> --token <t> --confirm
+credda references respond <id> --token <t> --decline
+                            # --confirm records the verified qualification;
+                            #   --decline writes nothing. Single-use either way,
+                            #   and there is no default: you must say which.
+```
+
+Threshold policies — declarative "tell me when this line is crossed", delivered
+as `policy.threshold_crossed` through your webhooks. Config only: a policy never
+reads into, blocks, or changes a score:
+
+```sh
+credda policies create --name "Watch 60" --user worker_7 \
+        --metric score --direction down --threshold 60
+credda policies create --name "Anyone entering High Risk" --all \
+        --metric band --direction enter --band "High Risk"
+credda policies list [--cursor <c>] [--limit <n>]
+credda policies get <id>
+credda policies update <id> [--threshold <n>] [--direction <d>] [--band <b>]
+        [--component <c>] [--name <n>] [--activate | --deactivate]
+                            # the metric is immutable — delete and recreate
+credda policies delete <id>
+```
+
+Score monitors — set `CREDDA_API_KEY`. Edge-triggered threshold/band watches
+that deliver `monitor.triggered` through your subscribed webhooks;
+notification config only — a monitor never affects a score:
+
+```sh
+credda monitors list [--cursor <c>] [--limit <n>]
+credda monitors get <id>
+credda monitors create --user <externalId> --below 40
+                            # at least one condition required:
+                            #   --below <score>   downward crossing (also fires
+                            #                     on a FIRST score already below)
+                            #   --above <score>   upward crossing
+                            #   --band-change     any band change
+credda monitors delete <id>
+```
+
+Bulk screenings — set `CREDDA_API_KEY`. Async batch score reads (up to
+10,000 ids per job), strictly read-only:
+
+```sh
+credda screen u1,u2 u3      # ids inline, comma/space separated
+credda screen --file roster.csv
+                            # one id per line, or a CSV whose FIRST column is
+                            # the id (a leading id/userId/externalId header
+                            # row is skipped; no quoted-CSV handling)
+credda screen u1,u2 --wait  # poll until the job finishes, print the summary
+                            # (exit 1 if the job FAILED)
+credda screenings list [--cursor <c>] [--limit <n>]
+credda screenings get <id>  # job status + summary
+credda screenings results <id>            # per-user results as JSON
+credda screenings results <id> --csv out.csv
+                            # write the CSV attachment instead (raw fetch)
+```
+
+Webhooks — set `CREDDA_API_KEY`:
+
+```sh
+credda webhooks list
+credda webhooks create https://hooks.you/credda score.updated score.band_changed
+                            # signing secret shown ONCE
+credda webhooks delete <id>
+credda webhooks test <id>   # synthetic signed delivery
+credda webhooks deliveries <id>   # recent attempts, incl. retries
+```
+
+Local development:
+
+```sh
+CREDDA_WEBHOOK_SECRET=whsec_... credda listen 4141
+```
+
+`credda listen` runs a local receiver that HMAC-verifies each delivery (the
+same check your production handler must do) and pretty-prints the payload.
+Credda delivers to public HTTPS only, so expose the port with your own tunnel
+(e.g. `cloudflared tunnel --url http://localhost:4141`) and register the
+tunnel URL as the webhook — the Stripe-CLI-style local loop without Credda
+running a tunneling service.
+
+Environment: `CREDDA_API_URL` overrides the API base (default
+`https://api.credda.io`); `CREDDA_WEBHOOK_SECRET` enables signature
+verification in `credda listen`.
+
+## Design
+
+- `src/cli.ts` is the pure command router — no `process`, `fs`, or env access,
+  so the whole surface is unit-tested with a mocked `CreddaClient` (same
+  pattern as `packages/mcp`'s `tools.ts`).
+- `src/index.ts` only wires the real environment (env vars, stdin/file
+  reading, exit codes).
+- `verify` uses the SDK's offline verifiers (WebCrypto Ed25519 + StatusList
+  revocation) — the point is that a received credential can be checked
+  without trusting the wire it arrived on.
+- Every command is read-only against the score. `mint`/`revoke` manage a
+  share token — a capability, not a score write.

package/dist/cli.d.ts

@@ -31,9 +31,68 @@ export interface CliContext {
         port: number;
         secret?: string;
     }) => Promise<void>;
+    /**
+     * Raw authenticated GET returning the response body as text — for the CSV
+     * endpoints (`?format=csv`), which the typed SDK deliberately leaves to raw
+     * fetch. `path` is relative to the `/api/v1` prefix.
+     */
+    fetchCsv?: (path: string, apiKey: string) => Promise<string>;
+    /** Write a file to disk (CSV outputs). Injected so the router stays fs-free. */
+    writeFile?: (path: string, content: string) => Promise<void>;
+    /** Sleep between `screen --wait` polls. Injected so tests don't wait. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Poll interval for `screen --wait` (default 2000ms). */
+    pollIntervalMs?: number;
 }
-export declare const VERSION = "0.0.1";
-export declare const HELP = "credda \u2014 portable trust from the terminal\n\nPublic (no API key):\n  credda lookup <token>          Trust check for a share token\n  credda export <token>          Full self-verifying trust export bundle\n  credda verify <file|->         Offline-verify a credential: a W3C VC-JWT,\n                                 a compact Trust Credential, or a saved trust\n                                 export bundle (auto-detected). '-' = stdin.\n  credda registry                Federated trust registry\n  credda did                     Issuer DID document\n\nPlatform (needs CREDDA_API_KEY):\n  credda score <userId>          Current score\n  credda explain <userId>        Factor-level score explanation\n  credda components <userId>     Six named 0-100 score components\n  credda risk <userId>           Advisory risk signals\n  credda usage [days]            Your platform's metered API usage\n  credda mint <userId>           Mint a share token for a user\n  credda revoke <userId>         Revoke a user's share token\n\nWebhooks (needs CREDDA_API_KEY):\n  credda webhooks list                     Your webhook subscriptions\n  credda webhooks create <url> <event..>   Subscribe (secret shown ONCE)\n  credda webhooks delete <id>              Remove a webhook\n  credda webhooks test <id>                Send a synthetic signed delivery\n  credda webhooks deliveries <id>          Recent delivery attempts (incl. retries)\n\nLocal development:\n  credda listen [port]           Local webhook receiver: verifies each delivery's\n                                 HMAC signature (CREDDA_WEBHOOK_SECRET) and\n                                 pretty-prints the payload. Default port 4141.\n                                 Credda delivers to public HTTPS only \u2014 expose\n                                 this port with your own tunnel (e.g. cloudflared).\n\nEnvironment:\n  CREDDA_API_URL                 API base (default https://api.credda.io)\n  CREDDA_API_KEY                 Platform API key for keyed commands\n  CREDDA_WEBHOOK_SECRET          whsec_\u2026 signing secret for \"credda listen\"\n\nExit codes: 0 ok/valid \u00B7 1 error \u00B7 2 credential failed verification";
+export declare const VERSION = "0.1.3";
+export declare const HELP = "credda: portable trust from the terminal\n\nStart here (needs a sandbox CREDDA_API_KEY, the crd_test_ kind):\n  credda quickstart              Seed your sandbox with synthetic subjects, print\n                                 their real scores, read one back, and then close\n                                 the counterparty-confirmation loop end to end so\n                                 you finish holding a real VERIFIED event, not\n                                 just a number you read. One command, nothing\n                                 written outside the sandbox.\n       --no-confirm              Stop after the seed; skip the confirmation loop.\n\nSandbox (crd_test_ keys only; a live key is refused before anything happens):\n  credda sandbox seed            Populate the sandbox with synthetic subjects.\n                                 Idempotent: an already-seeded subject is left\n                                 alone, never doubled.\n  credda sandbox reset           Wipe the sandbox and start over.\n\nPublic (no API key):\n  credda lookup <token>          Trust check for a share token\n  credda export <token>          Full self-verifying trust export bundle\n  credda verify <file|->         Offline-verify a credential: a W3C VC-JWT,\n                                 a compact Trust Credential, or a saved trust\n                                 export bundle (auto-detected). '-' = stdin.\n  credda registry                Federated trust registry\n  credda did                     Issuer DID document\n  credda benchmarks              Cohort-benchmark catalog (dimensions + k-anonymity)\n  credda reason-codes            Adverse-action reason-code catalog (ECOA / Reg B)\n  credda outcome-templates [industry]\n                                 How a real-world business maps its work to\n                                 Credda events, and WHO confirms each outcome.\n                                 Guidance only. Optional industry slug filters.\n  credda badges list             Open Badges 3.0 achievements this issuer signs\n  credda badges get <badgeId>    One achievement definition\n  credda professional-record public <token>\n                                 The professional record behind a share token\n                                 (the subject's own consent to present it)\n  credda career-export --token <token>\n                                 The subject's whole verified record as a JSON\n                                 Resume document, behind a share token (the\n                                 subject's own consent, no API key sent)\n\nPlatform (needs CREDDA_API_KEY):\n  credda score <userId>          Current score\n  credda explain <userId>        Factor-level score explanation\n  credda components <userId>     Six named 0-100 score components\n  credda risk <userId>           Advisory risk signals\n  credda trust-summary <userId> [--narrative]\n                                 Deterministic, evidence-based trust summary\n                                 (explains; never a verdict). --narrative adds an\n                                 advisory AI retelling when the server has AI on.\n  credda benchmark <userId> [--dimension <d>]\n                                 Where a subject sits within its cohort:\n                                 percentile + the cohort distribution\n  credda distribution [--dimension <d>] [--cohort <c>]\n                                 Aggregate, k-anonymised cohort distribution.\n                                 Omit --cohort for every cohort on the dimension.\n  credda users [--score-min <n>] [--score-max <n>] [--band <b>]\n        [--subject-type <PERSON|AGENT|ORGANIZATION>] [--scored|--unscored] [--frozen]\n        [--active-since <iso>] [--registered-since <iso>] [--registered-before <iso>]\n        [--verified] [--min-verified <n>]\n        [--sort <score|lastActivity|registered|externalId>] [--order <asc|desc>]\n        [--cursor <c>] [--limit <n>]\n                                 Query + export your book of subjects.\n                                 A subject with no score yet reports null,\n                                 never a placeholder; list those with\n                                 --unscored.\n  credda book-summary [same filters as \"users\"]\n                                 Size a segment WITHOUT paging it: how many\n                                 match, how many are scored, band mix and\n                                 median/mean. Null (not 0) when nothing in the\n                                 segment is scored.\n  credda usage [days] [--from <date> --to <date>] [--csv <outfile>]\n                                 Your platform's metered API usage. Either a\n                                 trailing [days] window OR an inclusive\n                                 --from/--to date range (YYYY-MM-DD), not both.\n                                 --csv writes the flat CSV statement to a file.\n  credda activity [--action <A>] [--from <t> --to <t>] [--cursor <c>] [--limit <n>]\n                                 Your platform's own activity/audit log,\n                                 newest-first, cursor-paginated\n  credda verified-profile <userId>\n                                 How much of a subject's CLAIMED record\n                                 (education/skills/certifications/employment) is\n                                 third-party verified. Counts whether a claim is\n                                 verified, never how prestigious it is, and it\n                                 can never move the Reliability Score.\n  credda qualify <userId> --category <education|skill|certification|employment>\n        [--label <l>] [--issuer <i>] [--verified-by <witness>]\n                                 Record a qualification claim. Always recorded;\n                                 counts as VERIFIED only with a genuine\n                                 third-party --verified-by witness.\n  credda professional-record get <userId>\n                                 R\u00E9sum\u00E9-shaped summary of a VERIFIED work record.\n                                 Describes a record, not a hiring verdict, a\n                                 background check, or a consumer report.\n  credda professional-record credential <userId> [--ttl <seconds>]\n                                 Mint the signed, offline-verifiable Professional\n                                 Record Credential (+ an \"Add to LinkedIn\" link)\n  credda reliability-report <userId> [--recent <n>] [--benchmark]\n                                 The consolidated worker reliability report a\n                                 staffing agency or employer weighs: reliability,\n                                 metrics, verified experience, tenure, ranked\n                                 drivers, recent outcomes. EVIDENCE, not a hire /\n                                 place / rank verdict, a background check, or a\n                                 consumer report. Use --token <token> for the\n                                 public worker-consent route (NO API key).\n  credda career-export <userId>  The subject's whole verified record as an open\n                                 JSON Resume document (jsonresume.org). Describes\n                                 a record, not a hiring verdict or a consumer\n                                 report. Use --token <token> for the public route.\n  credda mint <userId>           Mint a share token for a user\n  credda revoke <userId>         Revoke a user's share token\n\nConfirmation requests: the counterparty-confirmation primitive. You PROPOSE an\noutcome and deliver the one-time token to the counterparty over YOUR OWN channel;\nthe event is written, verified, only when that distinct party confirms:\n  credda confirmations create --user <externalId> --type <eventType>\n        --counterparty <ref> [--counterparty-name <n>] [--description <d>]\n        [--stake <HIGH|MEDIUM|LOW>] [--value <n>] [--due <iso>] [--completed <iso>]\n        [--return-url <url>] [--expires-in <days>] [--idempotency-key <k>]\n                                 Needs CREDDA_API_KEY. Token shown ONCE.\n  credda confirmations batch <file.json> [--idempotency-key <k>]\n                                 The ACTIVATION ENGINE: bulk-create up to 100\n                                 requests from a JSON file (an array of request\n                                 bodies, or { \"requests\": [...] }). Warms a cold\n                                 ledger from your book. Needs CREDDA_API_KEY;\n                                 each ok item's token is shown ONCE.\n  credda confirmations list [--status <s>] [--cursor <c>] [--limit <n>]\n  credda confirmations get <id>\n  credda confirmations cancel <id>\n  credda confirmations preview <id> --token <t>\n                                 What the counterparty is asked to confirm.\n                                 NO API key; the token is the capability.\n  credda confirmations respond <id> --token <t> (--confirm | --decline)\n                                 The counterparty's decision. NO API key.\n                                 --confirm writes the event; --decline writes\n                                 nothing. Single-use either way.\n\nReference requests: the qualifications-half sibling of confirmations. A r\u00E9sum\u00E9\nclaim (employment / education / certification / skill) becomes VERIFIED when the\nnamed third party who was there confirms it. Records no qualification and never\nmoves the reliability score:\n  credda references create --user <externalId>\n        --category <employment|education|certification|skill>\n        --counterparty <ref> [--label <l>] [--issuer <i>] [--jurisdiction <j>]\n        [--reference <r>] [--counterparty-name <n>] [--description <d>]\n        [--return-url <url>] [--expires-in <days>] [--idempotency-key <k>]\n                                 Needs CREDDA_API_KEY. Token shown ONCE.\n  credda references list [--status <s>] [--cursor <c>] [--limit <n>]\n  credda references get <id>\n  credda references cancel <id>\n  credda references preview <id> --token <t>\n                                 What the reference is asked to confirm.\n                                 NO API key; the token is the capability.\n  credda references respond <id> --token <t> (--confirm | --decline)\n                                 The reference's decision. NO API key.\n                                 --confirm records the qualification; --decline\n                                 writes nothing. Single-use either way.\n\nThreshold policies (needs CREDDA_API_KEY): declarative \"tell me when this line\nis crossed\"; delivers policy.threshold_crossed through your webhooks. Config\nonly: a policy never reads into, blocks, or changes a score:\n  credda policies list [--cursor <c>] [--limit <n>]\n  credda policies get <id>\n  credda policies create --name <n> (--user <externalId> | --all)\n        --metric <score|component|band|verified_events>\n        [--direction <up|down|enter|leave>] [--threshold <n>]\n        [--component <reliability|timeliness|trustworthiness|verification|consistency|momentum>]\n        [--band <b>]\n  credda policies update <id> [--name <n>] [--direction <d>] [--threshold <n>]\n        [--component <c>] [--band <b>] [--activate | --deactivate]\n                                 The metric is immutable; delete + recreate.\n  credda policies delete <id>\n\nScore monitors (needs CREDDA_API_KEY): edge-triggered watches that deliver\n\"monitor.triggered\" through your webhooks; notification config only, a\nmonitor never affects a score:\n  credda monitors list [--cursor <c>] [--limit <n>]\n  credda monitors get <id>\n  credda monitors create --user <externalId> [--below <score>] [--above <score>] [--band-change]\n                                 At least one condition required. --below fires\n                                 on a downward crossing (and on a first score\n                                 already below it), --above on an upward\n                                 crossing, --band-change on any band change.\n  credda monitors delete <id>\n\nBulk screenings (needs CREDDA_API_KEY): async batch score reads, up to\n10,000 ids per job, strictly read-only:\n  credda screen <ids...>         Submit ids (comma/space separated), or:\n  credda screen --file <path>    One id per line, or a CSV whose FIRST column\n                                 is the id (a leading \"id\"/\"userId\"/\n                                 \"externalId\" header row is skipped).\n         [--wait]                Poll until the job finishes, then print the\n                                 summary (exit 1 if the job FAILED).\n  credda screenings list [--cursor <c>] [--limit <n>]\n  credda screenings get <id>     Job status + summary\n  credda screenings results <id> [--csv <outfile>]\n                                 Per-user results (JSON; --csv writes the CSV\n                                 attachment to a file instead)\n\nWebhooks (needs CREDDA_API_KEY):\n  credda webhooks list                     Your webhook subscriptions\n  credda webhooks create <url> <event..>   Subscribe (secret shown ONCE)\n  credda webhooks delete <id>              Remove a webhook\n  credda webhooks test <id>                Send a synthetic signed delivery\n  credda webhooks deliveries <id>          Recent delivery attempts (incl. retries)\n  credda webhooks recent [event..]         Recent events across ALL your endpoints\n                                           (sample data for automation platforms;\n                                           falls back to catalog examples, flagged\n                                           isExample, when nothing has fired yet)\n\nLocal development:\n  credda listen [port]           Local webhook receiver: verifies each delivery's\n                                 HMAC signature (CREDDA_WEBHOOK_SECRET) and\n                                 pretty-prints the payload. Default port 4141.\n                                 Credda delivers to public HTTPS only; expose\n                                 this port with your own tunnel (e.g. cloudflared).\n\nEnvironment:\n  CREDDA_API_URL                 API base (default https://api.credda.io)\n  CREDDA_API_KEY                 Platform API key for keyed commands\n  CREDDA_WEBHOOK_SECRET          whsec_\u2026 signing secret for \"credda listen\"\n\nExit codes: 0 ok/valid \u00B7 1 error \u00B7 2 credential failed verification";
+/** Raw-key prefix the API stamps on a sandbox key (lib/testMode.ts). */
+export declare const TEST_KEY_PREFIX = "crd_test_";
+/**
+ * A sandbox key, or an error that says exactly what to do next.
+ *
+ * The server refuses a live key anyway (`403 TEST_MODE_ONLY`), but a first-run
+ * user does not deserve a 403 to interpret — the prefix is visible locally, so
+ * the actionable message costs one string comparison. This is the "better
+ * first-run errors" rule applied to the single most likely first mistake.
+ */
+export declare function requireSandboxKey(ctx: CliContext): string;
+/**
+ * Extra stderr lines for a failed command.
+ *
+ * The important one is the **request id**: it is the single fastest way for
+ * Credda to diagnose a failure, and a CLI user has nowhere else to find it.
+ * Also surfaces the machine code (so it can be looked up in
+ * `GET /api/v1/errors`) and any `Retry-After` the server asked for.
+ *
+ * Duck-typed rather than `instanceof CreddaError` on purpose — the router
+ * imports only TYPES from the SDK, so it stays pure and trivially mockable.
+ * Pure and exported for testing.
+ */
+export declare function errorHints(e: unknown): string[];
+/**
+ * Tiny flag parser: `--name value` for valued flags, bare `--name` for
+ * booleans, everything else positional. Unknown `--flags` are an error rather
+ * than silently becoming positionals.
+ */
+export declare function parseFlags(args: string[], spec?: {
+    valued?: string[];
+    boolean?: string[];
+}): {
+    positional: string[];
+    flags: Record<string, string | true>;
+};
+/**
+ * Parse the ids for `credda screen`. Inline args may be comma- and/or
+ * space-separated. A file is one id per line — or a CSV, in which case only
+ * the FIRST column is read (a leading header row named id/userId/externalId
+ * is skipped). Deduped, order-preserving. Deliberately simple: no quoted-CSV
+ * handling — an id containing a comma isn't a valid external id anyway.
+ */
+export declare function parseIdList(input: {
+    inline?: string[];
+    fileText?: string;
+}): string[];
 /** Classify verify input: trust-export bundle JSON, VC-JWT, or compact credential. */
 export declare function classifyCredentialInput(raw: string): {
     kind: 'export';

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAClB,UAAU,EACV,mBAAmB,EACnB,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,SAAS,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACnD,uDAAuD;IACvD,SAAS,EAAE;QACT,eAAe,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;QACrE,oBAAoB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;QAC7D,WAAW,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;KACpE,CAAC;IACF,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5E;AAED,eAAO,MAAM,OAAO,UAAU,CAAC;AAE/B,eAAO,MAAM,IAAI,4oEAuCmD,CAAC;AAmBrE,sFAAsF;AACtF,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,GACV;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAcrH;AAED,6DAA6D;AAC7D,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA6I7E"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}