@credda/cli 0.1.2 → 0.1.4

package/dist/cli.d.ts

@@ -44,8 +44,19 @@ export interface CliContext {
     /** Poll interval for `screen --wait` (default 2000ms). */
     pollIntervalMs?: number;
 }
-export declare const VERSION = "0.1.2";
-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  credda benchmarks              Cohort-benchmark catalog (dimensions + k-anonymity)\n  credda reason-codes            Adverse-action reason-code catalog (ECOA / Reg B)\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\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>] [--subject-type <PERSON|AGENT>]\n        [--active-since <iso>] [--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  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 \u2014 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 \u2014 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 mint <userId>           Mint a share token for a user\n  credda revoke <userId>         Revoke a user's share token\n\nConfirmation requests \u2014 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 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 \u2014 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\nThreshold policies (needs CREDDA_API_KEY) \u2014 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 \u2014 delete + recreate.\n  credda policies delete <id>\n\nScore monitors (needs CREDDA_API_KEY) \u2014 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) \u2014 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 \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.
  *
@@ -95,4 +106,3 @@ export declare function classifyCredentialInput(raw: string): {
 };
 /** Run one CLI invocation. Returns the process exit code. */
 export declare function runCli(argv: string[], ctx: CliContext): Promise<number>;
-//# sourceMappingURL=cli.d.ts.map