@samva/cli 0.16.0 → 0.18.0

package/AGENTS.md

@@ -21,9 +21,15 @@ response writes its body to stderr and exits `4` for 401 and 403, otherwise `1`.
 is no built-in filter.
 
 `samva api-keys` manages the organization's keys: `list`, `get`, `create`, `update`, `rotate`, and
-`revoke`. `create` takes `--name` and exactly one of `--full-access` or repeatable `--grant
-<resource>=read|write` (neither or both exits `2`), plus optional `--description` and `--expires-at`;
-mailbox and namespace scope go through `samva api`. The API refuses a key with more access than the
+`revoke`. `create` takes `--name` and either `--full-access` or restricted access built from repeatable
+`--grant <resource>=read|write` and mailbox access: repeatable `--mailbox-permission
+read|update|send|quarantine.read`, optionally narrowed to repeatable `--mailbox <id>` (default:
+every mailbox the owner reaches) with `--send-mode approval` (each send waits for a person other
+than the key). `--namespace <id>` confines a restricted key to one namespace. Passing no access, or both
+`--full-access` and restricted access, exits `2`, as does `--mailbox` or `--send-mode` without a
+`--mailbox-permission`. `--description` and `--expires-at` are optional. `update` renames a key,
+sets its description, or changes a mailbox key's `--send-mode` (a person signed in with `samva
+login`); every other part of a key's access is fixed at creation. The API refuses a key with more access than the
 caller holds. `create` and `rotate` return the secret once: `--json` carries `{apiKey, key,
 displayOnce, warning}`, so `samva api-keys create ... --json | jq -r .data.key` yields the key, and
 human mode prints it to stdout with the warning on stderr. `rotate` and `revoke` require
@@ -31,6 +37,12 @@ confirmation (`--yes` outside a terminal), and every mutation supports `--dry-ru
 `SAMVA_API_KEY`, `samva org current` asks the API who the key is (`GET /v1/whoami`) and reports its
 organization and key; with OAuth it reports the profile's selected organization.
 
+`samva webhooks secret <id>` reads the current signing secret with `webhooks:update` permission.
+Human output includes the secret, its creation time, and when the previous secret stops verifying
+if one exists. `--json` returns `{secret, createdAt, previousExpiresAt}` inside the result envelope.
+`create` and `rotate-secret` return readable secrets too; retrieve them again with `secret <id>`.
+Their JSON results contain `secret` and `warning` (`create` also includes `endpoint`).
+
 `samva templates export --out <dir>` renders every local template's fixtures to HTML
 and text with the asset manifest, needing a Samva credential only to resolve a live `samva:brand`; `--asset-base <origin>` is for an
 export that will be delivered, which cannot carry a relative reference.
@@ -136,7 +148,10 @@ calls to you, rather than to an installation. Read what exists with `list`, `ver
 `run <id> <run-id>` (adds the handler's log lines); the list commands page with `--limit`,
 `--cursor`, and `--all --jsonl`.
 
-`samva mailboxes` reads and sends as a mailbox: `list` pages with `--limit`, `--cursor`, `--after`,
+`samva mailboxes` reads and sends as a mailbox. Every command except `list` and `create`
+takes the mailbox ID as its first argument and the message, action, or endpoint ID second,
+as in `read <mailbox-id> <message-id>` and `endpoints update <mailbox-id> <endpoint-id>`; `events`
+takes any number of mailbox IDs, or none for every mailbox the credential reads. `list` pages with `--limit`, `--cursor`, `--after`,
 and `--before`. `create --address <address> --name <name>` makes a mailbox with one email endpoint; the
 slug defaults to the address's local part, and a collision asks for `--slug` rather than suffixing.
 `get <id>` inspects a mailbox; `update <id> --data <JSON-or-@file>` changes
@@ -156,9 +171,9 @@ public SDK describes email only.
 Quarantine `list` pages the same way, bounded by `--after` and `--before` on when a message was
 held; `release` and `discard` take the held message's `id` and require a person signed in with
 `samva login`. Discard requires confirmation (`--yes` outside a terminal) and supports `--dry-run`.
-`actions list --mailbox <id>` filters by `--state` and pages with `--limit`, `--cursor`, and
-`--all --jsonl`. `actions approve <action-id> --mailbox <id>` and `actions deny <action-id>
---mailbox <id> [--reason <text>]` require a person different from the proposer, confirmation
+`actions list <mailbox-id>` filters by `--state` and pages with `--limit`, `--cursor`, and
+`--all --jsonl`. `actions approve <mailbox-id> <action-id>` and `actions deny <mailbox-id>
+<action-id> [--reason <text>]` require a person different from the proposer, confirmation
 (`--yes` outside a terminal), and offer `--dry-run`.
 Human mailbox and extension results retain the same facts as JSON: mailbox endpoints (channel, address,
 sender name, default), thread state and activity, message bodies, attachments, authentication and actor,

package/dist/bin.mjs

@@ -14106,7 +14106,7 @@ var layer12 = /* @__PURE__ */ layer.pipe(/* @__PURE__ */ provideMerge(/* @__PURE
 // package.json
 var package_default = {
   name: "@samva/cli",
-  version: "0.16.0",
+  version: "0.18.0",
   description: "Samva CLI \u2014 email and platform operations from your terminal",
   keywords: [
     "cli",
@@ -14162,16 +14162,16 @@ var package_default = {
     "@types/node": "catalog:",
     "better-auth": "catalog:",
     effect: "catalog:effect",
-    samva: "workspace:0.20.0",
+    samva: "workspace:0.21.0",
     typescript: "catalog:",
     vite: "~8.3.0",
     vitest: "catalog:"
   },
   optionalDependencies: {
-    "@samva/cli-darwin-arm64": "workspace:0.16.0",
-    "@samva/cli-darwin-x64": "workspace:0.16.0",
-    "@samva/cli-linux-arm64": "workspace:0.16.0",
-    "@samva/cli-linux-x64": "workspace:0.16.0"
+    "@samva/cli-darwin-arm64": "workspace:0.18.0",
+    "@samva/cli-darwin-x64": "workspace:0.18.0",
+    "@samva/cli-linux-arm64": "workspace:0.18.0",
+    "@samva/cli-linux-x64": "workspace:0.18.0"
   },
   engines: {
     node: ">=18"
@@ -19353,6 +19353,7 @@ var Literals4 = (name, choices) => Literals2(argumentKind, name, choices);
 var optional5 = (arg) => optional3(arg);
 var withDescription4 = /* @__PURE__ */ dual(2, (self, description) => withDescription(self, description));
 var withDefault6 = withDefault4;
+var atLeast3 = /* @__PURE__ */ dual(2, (self, min) => atLeast(self, min));
 var withSchema3 = /* @__PURE__ */ dual(2, (self, schema) => withSchema(self, schema));
 var filterMap3 = /* @__PURE__ */ dual(3, (self, f, onNone) => filterMap2(self, f, onNone));
 
@@ -19595,6 +19596,9 @@ var ENTITY_PREFIXES = {
   waflow: "WhatsAppFlowId",
   wafver: "WhatsAppFlowVersionId",
   wafreg: "WhatsAppFlowRegistrationId",
+  wafkey: "WhatsAppFlowEncryptionKeyId",
+  wafx: "WhatsAppFlowExchangeId",
+  wasl: "WhatsAppSetupLinkId",
   mbx: "MailboxId",
   mbxep: "MailboxEndpointId",
   thread: "MailboxThreadId",
@@ -19690,6 +19694,9 @@ var WhatsAppBusinessAccountId = entityId("waba").pipe(brand(ENTITY_PREFIXES.waba
 var WhatsAppFlowId = entityId("waflow").pipe(brand(ENTITY_PREFIXES.waflow));
 var WhatsAppFlowVersionId = entityId("wafver").pipe(brand(ENTITY_PREFIXES.wafver));
 var WhatsAppFlowRegistrationId = entityId("wafreg").pipe(brand(ENTITY_PREFIXES.wafreg));
+var WhatsAppFlowEncryptionKeyId = entityId("wafkey").pipe(brand(ENTITY_PREFIXES.wafkey));
+var WhatsAppFlowExchangeId = entityId("wafx").pipe(brand(ENTITY_PREFIXES.wafx));
+var WhatsAppSetupLinkId = entityId("wasl").pipe(brand(ENTITY_PREFIXES.wasl));
 var WhatsAppServiceWindowId = entityId("wasw").pipe(brand(ENTITY_PREFIXES.wasw));
 var WebhookEndpointId = entityId("wep").pipe(brand(ENTITY_PREFIXES.wep));
 var WebhookCredentialId = entityId("whcred").pipe(brand(ENTITY_PREFIXES.whcred));
@@ -20397,6 +20404,7 @@ var DOMAIN_WEBHOOK_EVENT_TYPE_VALUES = [
 var domainWebhookEventTypeSchema = Literals(DOMAIN_WEBHOOK_EVENT_TYPE_VALUES);
 var TEMPLATE_WEBHOOK_EVENT_TYPE_VALUES = ["template.registration.updated"];
 var FLOW_WEBHOOK_EVENT_TYPE_VALUES = ["flow.registration.updated"];
+var WHATSAPP_NUMBER_WEBHOOK_EVENT_TYPE_VALUES = ["whatsapp.number.connected"];
 var MAILBOX_WEBHOOK_EVENT_TYPE_VALUES = [
   "mailbox.message.received",
   "mailbox.message.sent",
@@ -20421,6 +20429,7 @@ var WEBHOOK_EVENT_TYPE_VALUES = [
   ...DOMAIN_WEBHOOK_EVENT_TYPE_VALUES,
   ...TEMPLATE_WEBHOOK_EVENT_TYPE_VALUES,
   ...FLOW_WEBHOOK_EVENT_TYPE_VALUES,
+  ...WHATSAPP_NUMBER_WEBHOOK_EVENT_TYPE_VALUES,
   ...MAILBOX_WEBHOOK_EVENT_TYPE_VALUES,
   ...JOURNEY_WEBHOOK_EVENT_TYPE_VALUES
 ];
@@ -24148,6 +24157,7 @@ var CreateTemplatePayload = /* @__PURE__ */ Struct({
   ]), Null2]), Null2])),
   isActive: optionalKey2(Union2([Boolean3, Null2])),
   namespaceId: optionalKey2(Union2([NamespaceId2, Null2]).annotate({ description: "The namespace the new template project belongs to; the project and every entry added to it share it. Omit for organization level. A namespace-scoped key always creates in its own namespace." })),
+  shared: optionalKey2(Union2([Boolean3, Null2]).annotate({ description: "Share the new organization-level project with every namespace: namespace-scoped keys read and send its entries but cannot change them. Defaults to false. Not with `namespaceId`, and not from a namespace-scoped key." })),
   idempotencyKey: String4.check(isMinLength(1).annotate({ expected: "a value with a length of at least 1" })).check(isMaxCodePoints(255).annotate({ expected: "a string with at most 255 code points" })).check(isMaxLength(255).annotate({ expected: "a value with a length of at most 255" }))
 }).annotate({ identifier: "CreateTemplatePayload" });
 var CreateWebhookPayload = /* @__PURE__ */ Struct({
@@ -24461,7 +24471,8 @@ var UpdateTemplatePayload = /* @__PURE__ */ Struct({ data: Struct({
   ]), Null2]), Null2])),
   fromDefault: optionalKey2(Union2([Union2([TemplateFromDefault, Null2]), Null2])),
   replyToDefault: optionalKey2(Union2([Union2([ArraySchema(String4), Null2]), Null2])),
-  isActive: optionalKey2(Union2([Boolean3, Null2]))
+  isActive: optionalKey2(Union2([Boolean3, Null2])),
+  shared: optionalKey2(Union2([Boolean3, Null2]).annotate({ description: "Share the template's project with every namespace, or stop sharing it. Applies to every entry in the project. Only an organization-level project is shared." }))
 }) }).annotate({ identifier: "UpdateTemplatePayload" });
 var ApiKeyAccess = /* @__PURE__ */ Union2([Struct({ mode: Literal2("full") }), Struct({
   mode: Literal2("restricted"),
@@ -24798,6 +24809,7 @@ var apiStatuses = {
   MailboxSendConflictError: 409,
   MailboxSendRefusedError: 403,
   CursorExpiredError: 410,
+  WhatsAppSetupLinkUnavailableError: 410,
   MethodNotAllowedError: 405,
   UpgradeRequiredError: 426,
   RateLimitedError: 429,
@@ -25081,7 +25093,7 @@ var __exportAll = (all, no_symbols) => {
 };
 
 // ../sdk/dist/package.js
-var version = "0.20.0";
+var version = "0.21.0";
 
 // ../sdk/dist/client-attribution.js
 var SDK_VERSION = version;
@@ -25472,6 +25484,7 @@ var commandTree = {
   webhooks: {
     list: {},
     get: {},
+    secret: {},
     create: {},
     update: {},
     test: {},
@@ -25902,7 +25915,12 @@ var getAuthenticatedJsonForContext = fn2("CliClient.getAuthenticatedJson")(funct
   };
   const url = `${config.baseUrl.replace(/\/$/, "")}${path}`;
   const response = yield* tryPromise2({
-    try: (signal) => fetch(url, request === undefined ? { headers, signal } : { method: "POST", headers, body: JSON.stringify(request.body), signal }),
+    try: (signal) => fetch(url, request === undefined ? { headers, signal } : {
+      method: request.method ?? "POST",
+      headers,
+      body: JSON.stringify(request.body),
+      signal
+    }),
     catch: (cause) => new SamvaCliError({ message: `Request to ${url} failed: ${String(cause)}` })
   });
   const body = yield* tryPromise2({
@@ -26569,6 +26587,7 @@ var API_KEY_STATEMENT = {
 };
 var API_KEY_RESOURCES = Object.keys(API_KEY_STATEMENT);
 var API_KEY_LEVEL_RESOURCES = API_KEY_RESOURCES.filter((resource) => resource !== "mailboxes");
+var API_KEY_MAILBOX_ACTIONS = mailboxKeyActions;
 function apiKeyAccessLevels(resource) {
   return API_KEY_STATEMENT[resource].some((action) => action !== "read") ? ["read", "write"] : ["read"];
 }
@@ -27164,6 +27183,10 @@ var SDK_OPERATION_CALLS = {
   whoamiGet: { kind: "none" },
   webhooksList: { kind: "params" },
   webhooksCreate: { kind: "payload" },
+  webhooksGetSecret: {
+    kind: "path",
+    paths: ["id"]
+  },
   webhooksGet: {
     kind: "path",
     paths: ["id"]
@@ -28556,6 +28579,7 @@ var SamvaOperations = {
   webhooksRetryDelivery: operationMetadata96,
   webhooksGetLogs: operationMetadata95,
   webhooksRegenerateSecret: operationMetadata96,
+  webhooksGetSecret: operationMetadata97,
   webhooksGetStats: operationMetadata97,
   webhooksTest: operationMetadata96,
   whoamiGet: {
@@ -28802,6 +28826,7 @@ var ApiKey = /* @__PURE__ */ Struct({
   name: String4,
   key: optionalKey2(Union2([String4, Null2])),
   start: Union2([String4, Null2]),
+  end: Union2([String4, Null2]),
   description: optionalKey2(Union2([String4, Null2])),
   createdAt: String4,
   expiresAt: Union2([String4, Null2]),
@@ -28815,6 +28840,7 @@ var ApiKeyWithSecret = /* @__PURE__ */ Struct({
   name: String4,
   key: SensitiveString,
   start: Union2([String4, Null2]),
+  end: Union2([String4, Null2]),
   description: optionalKey2(Union2([String4, Null2])),
   createdAt: String4,
   expiresAt: Union2([String4, Null2]),
@@ -29066,7 +29092,7 @@ var parseGrant = (raw) => {
   if (resource === "mailboxes") {
     return new CliUsageError({
       code: "invalid_grant",
-      message: "--grant does not cover mailboxes; mailbox and namespace access are set with `samva api`."
+      message: "--grant does not cover mailboxes; use --mailbox-permission <action> (with optional --mailbox and --send-mode) instead."
     });
   }
   if (!isLevelResource(resource) || !isGrantLevel(level)) {
@@ -29083,19 +29109,52 @@ var parseGrant = (raw) => {
   }
   return { resource, level };
 };
-var accessFromFlags = (grants, fullAccess) => gen2(function* () {
-  if (fullAccess && grants.length > 0) {
+var repeated = (values) => values.find((value, index) => values.indexOf(value) !== index);
+var mailboxAccessFromFlags = (flags) => gen2(function* () {
+  if (flags.permissions.length === 0) {
+    if (flags.mailboxIds.length > 0 || isSome2(flags.sendMode)) {
+      return yield* new CliUsageError({
+        code: "mailbox_permission_required",
+        message: `--mailbox and --send-mode narrow mailbox access; also pass --mailbox-permission ${API_KEY_MAILBOX_ACTIONS.join("|")}.`
+      });
+    }
+    return;
+  }
+  const duplicatePermission = repeated(flags.permissions);
+  if (duplicatePermission !== undefined) {
+    return yield* new CliUsageError({
+      code: "invalid_mailbox_access",
+      message: `--mailbox-permission names ${duplicatePermission} more than once.`
+    });
+  }
+  const duplicateMailbox = repeated(flags.mailboxIds);
+  if (duplicateMailbox !== undefined) {
+    return yield* new CliUsageError({
+      code: "invalid_mailbox_access",
+      message: `--mailbox names ${duplicateMailbox} more than once.`
+    });
+  }
+  return {
+    permissions: flags.permissions,
+    ...flags.mailboxIds.length > 0 ? { mailboxIds: flags.mailboxIds } : {},
+    ...isSome2(flags.sendMode) ? { sendMode: flags.sendMode.value } : {}
+  };
+});
+var accessFromFlags = (grants, fullAccess, mailbox, namespace) => gen2(function* () {
+  const restrictedFlags = grants.length > 0 || mailbox.permissions.length > 0 || mailbox.mailboxIds.length > 0 || isSome2(mailbox.sendMode) || isSome2(namespace);
+  if (fullAccess && restrictedFlags) {
     return yield* new CliUsageError({
       code: "access_conflict",
-      message: "Pass either --full-access or --grant <resource>=read|write, not both."
+      message: "Pass either --full-access or restricted access (--grant, --mailbox-permission, --namespace), not both."
     });
   }
   if (fullAccess)
     return { mode: "full" };
-  if (grants.length === 0) {
+  const mailboxes = yield* mailboxAccessFromFlags(mailbox);
+  if (grants.length === 0 && mailboxes === undefined) {
     return yield* new CliUsageError({
       code: "access_required",
-      message: "Choose the key's access: --full-access, or one or more --grant <resource>=read|write."
+      message: "Choose the key's access: --full-access, or one or more --grant <resource>=read|write and/or --mailbox-permission <action>."
     });
   }
   const resources = {};
@@ -29111,7 +29170,12 @@ var accessFromFlags = (grants, fullAccess) => gen2(function* () {
     }
     resources[grant.resource] = grant.level;
   }
-  return { mode: "restricted", resources };
+  return {
+    mode: "restricted",
+    resources,
+    ...mailboxes === undefined ? {} : { mailboxes },
+    ...isSome2(namespace) ? { namespaceId: namespace.value } : {}
+  };
 });
 var parseExpiresAt = (raw) => Number.isNaN(Date.parse(raw)) ? fail6(new CliUsageError({
   code: "invalid_expires_at",
@@ -29125,7 +29189,12 @@ var describeAccess = (access) => {
     return "full";
   const grants = Object.entries(access.resources).filter(([, level]) => level !== undefined).map(([resource, level]) => `${resource}:${level}`);
   if (access.mailboxes !== undefined && access.mailboxes !== null) {
-    grants.push(`mailboxes:${access.mailboxes.permissions.join("+")}`);
+    const { permissions, mailboxIds, sendMode } = access.mailboxes;
+    const scope = [
+      ...mailboxIds === undefined || mailboxIds === null ? [] : [mailboxIds.join("+")],
+      ...sendMode === undefined || sendMode === "send" ? [] : [`${sendMode} sends`]
+    ];
+    grants.push(`mailboxes:${permissions.join("+")}${scope.length === 0 ? "" : ` [${scope.join("; ")}]`}`);
   }
   if (access.namespaceId !== undefined && access.namespaceId !== null)
     grants.push(`namespace:${access.namespaceId}`);
@@ -29204,11 +29273,19 @@ var create2 = make29("create", {
   description: String9("description").pipe(withDescription2("What the key is for"), optional4),
   expiresAt: String9("expires-at").pipe(withDescription2("When the key stops working, an ISO 8601 instant"), optional4),
   grant: String9("grant").pipe(withDescription2(`Give a restricted key a resource at a level, <resource>=read|write (repeatable). Resources: ${GRANTABLE_RESOURCES.join(", ")}`), atLeast2(0)),
-  fullAccess: Boolean6("full-access").pipe(withDescription2("Give the key its owner's full access instead of --grant"), withDefault5(false)),
+  mailboxPermission: Literals3("mailbox-permission", API_KEY_MAILBOX_ACTIONS).pipe(withDescription2(`Let a restricted key work in mailboxes with this action (repeatable): ${API_KEY_MAILBOX_ACTIONS.join(", ")}`), atLeast2(0)),
+  mailbox: String9("mailbox").pipe(withSchema2(MailboxId), withDescription2("Confine the mailbox access to this mailbox (repeatable); omit for every mailbox the owner reaches"), atLeast2(0)),
+  sendMode: Literals3("send-mode", mailboxSendModes).pipe(withDescription2("With approval, each send waits until a person other than the key approves it (default send)"), optional4),
+  namespace: String9("namespace").pipe(withSchema2(NamespaceId), withDescription2("Confine a restricted key to one namespace (ns_...)"), optional4),
+  fullAccess: Boolean6("full-access").pipe(withDescription2("Give the key its owner's full access instead of restricted access"), withDefault5(false)),
   dryRun: dryRunFlag,
   json: jsonFlag
 }).pipe(withDescription3("Create an API key. The secret is shown once; the API refuses access you do not hold."), withExamples([
   { command: "samva api-keys create --name ci --grant email=write --dry-run" },
+  {
+    command: "samva api-keys create --name agent --mailbox-permission read --mailbox-permission send --mailbox mbx_1234567890123456 --send-mode approval",
+    description: "A key that works in one mailbox and needs a person to approve each send"
+  },
   {
     command: "samva api-keys create --name ci --grant email=write --json | jq -r .data.key",
     description: "Pipe the secret into another tool"
@@ -29216,8 +29293,20 @@ var create2 = make29("create", {
   {
     command: "samva api-keys create --name deploy --full-access --expires-at 2027-01-01T00:00:00Z"
   }
-]), withHandler(({ name, description, expiresAt, grant, fullAccess, dryRun, json }) => withJsonQuiet(json, gen2(function* () {
-  const access = yield* accessFromFlags(grant, fullAccess);
+]), withHandler(({
+  name,
+  description,
+  expiresAt,
+  grant,
+  mailboxPermission,
+  mailbox,
+  sendMode,
+  namespace,
+  fullAccess,
+  dryRun,
+  json
+}) => withJsonQuiet(json, gen2(function* () {
+  const access = yield* accessFromFlags(grant, fullAccess, { permissions: mailboxPermission, mailboxIds: mailbox, sendMode }, namespace);
   const expires = yield* match(expiresAt, {
     onNone: () => void_3,
     onSome: parseExpiresAt
@@ -29233,7 +29322,11 @@ var create2 = make29("create", {
   });
   if (dryRun) {
     if (json) {
-      return yield* printJson({ dryRun: true, action: "api-keys.create", request: payload });
+      return yield* printJson({
+        dryRun: true,
+        action: "api-keys.create",
+        request: payload
+      });
     }
     return yield* printFields([
       ["Action", "api-keys.create"],
@@ -29256,13 +29349,17 @@ var update3 = make29("update", {
   id: idArgument,
   name: String9("name").pipe(withDescription2("New key name"), optional4),
   description: String9("description").pipe(withDescription2("New description"), optional4),
+  sendMode: Literals3("send-mode", mailboxSendModes).pipe(withDescription2("Change a mailbox key's send mode: approval holds each send for a person other than the key, send releases them. Takes a person signed in with samva login"), optional4),
   dryRun: dryRunFlag,
   json: jsonFlag
-}).pipe(withDescription3("Rename an API key or change its description. Access is fixed at creation; create a new key to change it."), withExamples([{ command: "samva api-keys update key_abc123 --name ci-prod --dry-run" }]), withHandler(({ id, name, description, dryRun, json }) => withJsonQuiet(json, gen2(function* () {
-  if (isNone2(name) && isNone2(description)) {
+}).pipe(withDescription3("Rename an API key, change its description, or change a mailbox key's send mode. Its other access is fixed at creation; create a new key to change it."), withExamples([
+  { command: "samva api-keys update key_abc123 --name ci-prod --dry-run" },
+  { command: "samva api-keys update key_abc123 --send-mode approval" }
+]), withHandler(({ id, name, description, sendMode, dryRun, json }) => withJsonQuiet(json, gen2(function* () {
+  if (isNone2(name) && isNone2(description) && isNone2(sendMode)) {
     return yield* new CliUsageError({
       code: "update_required",
-      message: "Pass --name, --description, or both."
+      message: "Pass --name, --description, --send-mode, or a combination."
     });
   }
   const payload = yield* decodeRequest(ApiKeysUpdateRequestJson, {
@@ -29270,6 +29367,10 @@ var update3 = make29("update", {
     ...match(description, {
       onNone: () => ({}),
       onSome: (value) => ({ description: value })
+    }),
+    ...match(sendMode, {
+      onNone: () => ({}),
+      onSome: (value) => ({ mailboxes: { sendMode: value } })
     })
   });
   if (dryRun) {
@@ -29285,7 +29386,8 @@ var update3 = make29("update", {
       ["Action", "api-keys.update"],
       ["API key", id],
       ["Name", payload.name],
-      ["Description", payload.description]
+      ["Description", payload.description],
+      ["Send mode", payload.mailboxes?.sendMode]
     ]);
   }
   const client = yield* getClientProvider;
@@ -54128,6 +54230,7 @@ var CampaignLatestRun = /* @__PURE__ */ Struct({
   dispatchedCount: Finite.check(isFinite4().annotate({ expected: "a finite number" })),
   failedCount: Finite.check(isFinite4().annotate({ expected: "a finite number" })),
   skippedCount: Finite.check(isFinite4().annotate({ expected: "a finite number" })),
+  pendingCount: Finite.check(isFinite4().annotate({ expected: "a finite number" })),
   estimatedCompletionAt: Union2([String4, Null2])
 }).annotate({ identifier: "CampaignLatestRun" });
 var CampaignRecipientPage = /* @__PURE__ */ Struct({
@@ -54226,11 +54329,14 @@ var CampaignRun = /* @__PURE__ */ Struct({
   dispatchedCount: Finite.check(isFinite4().annotate({ expected: "a finite number" })),
   failedCount: Finite.check(isFinite4().annotate({ expected: "a finite number" })),
   skippedCount: Finite.check(isFinite4().annotate({ expected: "a finite number" })),
+  pendingCount: Finite.check(isFinite4().annotate({ expected: "a finite number" })),
   skippedReasons: ArraySchema(CampaignRunSkippedReason),
   estimatedCompletionAt: Union2([String4, Null2]),
   failureReason: Union2([String4, Null2]),
   holdReason: Union2([String4, Null2]),
   holdDomainId: Union2([EmailDomainId2, Null2]),
+  holdUntil: Union2([String4, Null2]),
+  capacityWarning: Union2([String4, Null2]),
   lastContactId: Union2([String4, Null2]),
   createdBy: Union2([String4, Null2]),
   actorEmail: String4,
@@ -54581,6 +54687,23 @@ var resumeRun = /* @__PURE__ */ make42("campaignsResumeRun");
 var cancelRun = /* @__PURE__ */ make42("campaignsCancelRun");
 var listRecipients = /* @__PURE__ */ make42("campaignsListRecipients");
 
+// src/lib/run-hold.ts
+var WHATSAPP_MESSAGING_LIMIT_HOLD = "whatsapp_messaging_limit";
+var holdLabel = (reason) => reason === null || reason === undefined ? null : reason === WHATSAPP_MESSAGING_LIMIT_HOLD ? `${reason} (the number's messaging limit; the run resumes on its own)` : reason;
+var holdFields = (run) => [
+  ["Held", holdLabel(run.holdReason)],
+  ["Resumes at", run.holdUntil]
+];
+var campaignPacingFields = (run, options) => [
+  ...holdFields(run),
+  [
+    "Pending",
+    run.pendingCount !== undefined && (run.pendingCount > 0 || run.holdReason != null) ? String(run.pendingCount) : null
+  ],
+  ["Est. completion", run.estimatedCompletionAt],
+  ...options.warning ? [["Capacity warning", run.capacityWarning]] : []
+];
+
 // src/lib/template-reference.ts
 var publicationIdFlag = String9("publication-id").pipe(withDescription2("Pin one exact publication, so nothing published later changes what this renders"), optional4);
 var inputContractIdFlag = String9("input-contract-id").pipe(withDescription2("Follow the newest publication that still validates input identically to this contract"), optional4);
@@ -55053,7 +55176,7 @@ var archive2 = make29("archive", {
     ["Definition", data.definition.state]
   ]);
 }).pipe(json ? provideService2(MinimumLogLevel2, "None") : identity)));
-var printRun = (run) => printFields([
+var printRun = (run, options = { warning: true }) => printFields([
   ["Run ID", run.id],
   ["Campaign", run.campaignId],
   ["Status", run.status],
@@ -55068,8 +55191,10 @@ var printRun = (run) => printFields([
     "Skipped by reason",
     (run.skippedReasons ?? []).map(({ reason, count }) => `${reason} ${count}`).join(", ")
   ],
-  ["Failure", run.failureReason]
+  ["Failure", run.failureReason],
+  ...campaignPacingFields(run, options)
 ]);
+var warnCapacity = (run) => run.capacityWarning ? error(`Warning: ${run.capacityWarning}`) : void_3;
 var runCreate = make29("create", {
   campaignId: String10("campaignId"),
   at: atFlag,
@@ -55108,7 +55233,8 @@ var runCreate = make29("create", {
     return yield* printJson(data);
   yield* logInfo(`Run scheduled.
 `);
-  yield* printRun(data);
+  yield* printRun(data, { warning: false });
+  yield* warnCapacity(data);
 }).pipe(json ? provideService2(MinimumLogLevel2, "None") : identity)));
 var runList = make29("list", {
   campaignId: String10("campaignId"),
@@ -66402,7 +66528,7 @@ var refusalNext = (failure) => {
     case "ForbiddenError":
       return "Use a credential that may read mailboxes and follow the API message.";
     case "ResourceNotFoundError":
-      return "Run samva mailboxes list to find the mailboxes this credential can read, then retry with those --mailbox ids.";
+      return "Run samva mailboxes list to find the mailboxes this credential can read, then retry with those mailbox ids.";
     case "CursorExpiredError":
       return "Events after your cursor expired. Read current state from the API and reconnect without --cursor.";
     case "ValidationError":
@@ -66529,12 +66655,16 @@ var tailEvents = (options) => gen2(function* () {
   })), mapError4(streamError), options.limit === undefined ? (stream) => stream : take3(options.limit), interruptWhen2(interrupted), runForEach2(options.onEvent), raceFirst2(interrupted.pipe(andThen2(sleep2(HANDLER_DRAIN)))))));
 });
 var mailboxesEventsCommand = make29("events", {
+  mailbox: String10("mailbox-id").pipe(withDescription4("Mailboxes to follow; omit to follow every mailbox the credential reads"), withSchema3(MailboxId), atLeast3(0)),
   cursor: String9("cursor").pipe(withDescription2("Replay events after a cursor from an earlier event frame, then go live"), optional4),
-  mailbox: String9("mailbox").pipe(withSchema2(MailboxId), atLeast2(0)),
   limit: Int5("limit").pipe(optional4),
   noReconnect: Boolean6("no-reconnect").pipe(withDefault5(false), withDescription2("Exit non-zero with the last cursor when the connection drops, instead of reconnecting from it"))
 }).pipe(withDescription3("Tail mailbox events, one record per line; --jsonl wraps each in a result envelope; a dropped connection reconnects from the last cursor; Ctrl+C exits cleanly"), withExamples([
-  { command: "samva mailboxes events --mailbox mbx_1234567890123456 --limit 10" },
+  { command: "samva mailboxes events mbx_1234567890123456 --limit 10" },
+  {
+    command: "samva mailboxes events mbx_1234567890123456 mbx_6543210987654321 --jsonl",
+    description: "Follow several mailboxes"
+  },
   { command: "samva mailboxes events --jsonl", description: "Stream envelopes for automation" },
   { command: "samva mailboxes events --cursor <cursor-from-an-event-frame>" },
   {
@@ -67054,6 +67184,18 @@ class WhatsAppTemplateIneligibleError extends TaggedError3()("WhatsAppTemplateIn
   message: String4
 }, { httpApiStatus: 422 }) {
 }
+
+class WhatsAppSetupLinkUnavailableError extends TaggedError3()("WhatsAppSetupLinkUnavailableError", {
+  reason: Literals(["completed", "revoked", "expired"]),
+  message: String4
+}, { httpApiStatus: 410 }) {
+  static new(reason) {
+    return new WhatsAppSetupLinkUnavailableError({
+      reason,
+      message: reason === "completed" ? "This setup link already connected a WhatsApp number. Ask for a new link to connect another." : reason === "revoked" ? "This setup link was revoked. Ask for a new link." : "This setup link expired. Ask for a new link."
+    });
+  }
+}
 var EmailChannelErrorReason = Literals([
   "transport",
   "rejected",
@@ -67596,6 +67738,8 @@ var JourneyRun = /* @__PURE__ */ Struct({
   exitReason: Union2([JourneyRunExitReason, Null2]),
   failureReason: Union2([String4, Null2]),
   currentNodeId: Union2([JourneyNodeId, Null2]),
+  holdReason: Union2([String4, Null2]),
+  holdUntil: Union2([String4, Null2]),
   trigger: JourneyRunTrigger,
   enteredAt: String4,
   endedAt: Union2([String4, Null2])
@@ -67619,6 +67763,8 @@ var JourneyRunDetail = /* @__PURE__ */ Struct({
   exitReason: Union2([JourneyRunExitReason, Null2]),
   failureReason: Union2([String4, Null2]),
   currentNodeId: Union2([JourneyNodeId, Null2]),
+  holdReason: Union2([String4, Null2]),
+  holdUntil: Union2([String4, Null2]),
   trigger: JourneyRunTrigger,
   enteredAt: String4,
   endedAt: Union2([String4, Null2]),
@@ -68247,6 +68393,7 @@ var printRun2 = (run) => printFields([
   ["Exit reason", run.exitReason],
   ["Failure", run.failureReason],
   ["Current node", run.currentNodeId],
+  ...holdFields(run),
   ["Entered", run.enteredAt],
   ["Ended", run.endedAt]
 ]);
@@ -71573,7 +71720,7 @@ var decodeThreadPage = decoder3(WireThreadPage, "thread page");
 var decodeMessage = decoder3(WireMessage, "message");
 
 // src/commands/mailboxes.ts
-var mailboxFlag = String9("mailbox").pipe(withDescription2("Mailbox ID"), withSchema2(MailboxId));
+var mailboxIdArgument = String10("mailbox-id").pipe(withSchema3(MailboxId));
 var messageIdArgument = String10("message-id").pipe(withSchema3(MessageId));
 var optional6 = (name) => String9(name).pipe(optional4);
 var pageFlags2 = {
@@ -71616,7 +71763,7 @@ var chatContent = (channel, flags) => gen2(function* () {
   }
   if (channel !== "whatsapp")
     return yield* usage2("mailbox_chat_template", "A template sends on WhatsApp only.");
-  const templateId = yield* decodeUnknownEffect2(TemplateId)(flags.template.value).pipe(mapError2(() => usage2("mailbox_chat_template", "--template must be an approved template id (tmpl_\u2026).")));
+  const templateId = yield* decodeEffect2(TemplateId)(flags.template.value).pipe(mapError2(() => usage2("mailbox_chat_template", "--template must be an approved template id (tmpl_\u2026).")));
   const dataText = getOrUndefined(flags.data);
   if (dataText === undefined)
     return { templateId };
@@ -71734,7 +71881,6 @@ var create9 = make29("create", {
     return yield* printJson(data);
   yield* printMailbox(data);
 })));
-var mailboxIdArgument = String10("mailbox-id").pipe(withSchema3(MailboxId));
 var get22 = make29("get", { id: mailboxIdArgument, json: jsonFlag }).pipe(withDescription3("Inspect a mailbox's endpoints and settings"), withHandler(({ id, json }) => gen2(function* () {
   const raw = yield* getMailboxJson("Could not read mailbox", `/v1/mailboxes/${id}`);
   const result = yield* decodeMailbox(raw);
@@ -71793,7 +71939,7 @@ var update9 = make29("update", {
   yield* json ? printJson(result) : printMailbox(result);
 })));
 var endpointAdd = make29("add", {
-  mailbox: mailboxFlag,
+  mailbox: mailboxIdArgument,
   channel: channelFlag2,
   address: String9("address").pipe(withDescription2("The address to add: an email address such as billing@acme.samva.email, or on whatsapp and sms a number you connected, in E.164 form such as +14155550123")),
   displayName: String9("display-name").pipe(withDescription2("The sender name messages from this endpoint carry"), optional4),
@@ -71801,10 +71947,10 @@ var endpointAdd = make29("add", {
   json: jsonFlag
 }).pipe(withDescription3("Add an endpoint on a channel (email by default) to a mailbox"), withExamples([
   {
-    command: "samva mailboxes endpoints add --mailbox mbx_1234567890123456 --address billing@acme.samva.email"
+    command: "samva mailboxes endpoints add mbx_1234567890123456 --address billing@acme.samva.email"
   },
   {
-    command: "samva mailboxes endpoints add --mailbox mbx_1234567890123456 --channel whatsapp --address +14155550123",
+    command: "samva mailboxes endpoints add mbx_1234567890123456 --channel whatsapp --address +14155550123",
     description: "Add a connected WhatsApp number"
   }
 ]), withHandler(({ mailbox, channel, address, displayName, dryRun, json }) => gen2(function* () {
@@ -71836,8 +71982,8 @@ var endpointAdd = make29("add", {
 })));
 var endpointIdArgument = String10("endpoint-id").pipe(withSchema3(MailboxEndpointId));
 var endpointUpdate = make29("update", {
+  mailbox: mailboxIdArgument,
   endpointId: endpointIdArgument,
-  mailbox: mailboxFlag,
   displayName: String9("display-name").pipe(withDescription2("The sender name messages from this endpoint carry"), optional4),
   clearDisplayName: Boolean6("clear-display-name").pipe(withDescription2("Send under the mailbox's name again"), withDefault5(false)),
   makeDefault: Boolean6("default").pipe(withDescription2("Start new conversations from this endpoint on its channel"), withDefault5(false)),
@@ -71845,7 +71991,7 @@ var endpointUpdate = make29("update", {
   json: jsonFlag
 }).pipe(withDescription3("Rename an endpoint's sender or make it the mailbox's default"), withExamples([
   {
-    command: 'samva mailboxes endpoints update mbxep_1234567890123456 --mailbox mbx_1234567890123456 --display-name "Acme Billing" --default'
+    command: 'samva mailboxes endpoints update mbx_1234567890123456 mbxep_1234567890123456 --display-name "Acme Billing" --default'
   }
 ]), withHandler(({ endpointId, mailbox, displayName, clearDisplayName, makeDefault, dryRun, json }) => gen2(function* () {
   if (isSome2(displayName) && clearDisplayName)
@@ -71879,14 +72025,14 @@ var endpointUpdate = make29("update", {
   yield* json ? printJson(result) : printMailbox(result);
 })));
 var endpointRemove = make29("remove", {
+  mailbox: mailboxIdArgument,
   endpointId: endpointIdArgument,
-  mailbox: mailboxFlag,
   dryRun: Boolean6("dry-run").pipe(withDefault5(false)),
   yes: Boolean6("yes").pipe(withDefault5(false)),
   json: jsonFlag
 }).pipe(withDescription3("Remove an endpoint from a mailbox; mail sent to it stops reaching the mailbox"), withExamples([
   {
-    command: "samva mailboxes endpoints remove mbxep_1234567890123456 --mailbox mbx_1234567890123456 --yes"
+    command: "samva mailboxes endpoints remove mbx_1234567890123456 mbxep_1234567890123456 --yes"
   }
 ]), withHandler(({ endpointId, mailbox, dryRun, yes, json }) => gen2(function* () {
   if (dryRun)
@@ -71918,7 +72064,7 @@ var lifecycle = (verb) => make29(verb, {
   yield* json ? printJson(result) : printMailbox(result);
 })));
 var actionsList = make29("list", {
-  mailbox: mailboxFlag,
+  mailbox: mailboxIdArgument,
   ...pageFlags2,
   state: Literals3("state", MailboxActionState.literals).pipe(optional4),
   after: instantFlag("after", "Only actions created after this ISO 8601 instant"),
@@ -71943,8 +72089,8 @@ var actionsList = make29("list", {
   });
 })));
 var actionDecision = (verb) => make29(verb, {
+  mailbox: mailboxIdArgument,
   actionId: String10("action-id").pipe(withSchema3(MailboxActionId)),
-  mailbox: mailboxFlag,
   ...verb === "deny" ? {
     reason: optional6("reason").pipe(withDescription2("Denial reason; defaults to Denied by reviewer."))
   } : {},
@@ -71999,7 +72145,7 @@ var remove9 = make29("remove", {
   yield* log(`Removed mailbox ${id}. The messages it received stay with the organization.`);
 }).pipe(json ? provideService2(MinimumLogLevel2, "None") : identity)));
 var threads = make29("threads", {
-  mailbox: mailboxFlag,
+  mailbox: mailboxIdArgument,
   ...pageFlags2,
   query: optional6("query"),
   folder: Literals3("folder", MailboxThreadFolder2.literals).pipe(optional4),
@@ -72010,37 +72156,35 @@ var threads = make29("threads", {
   before: instantFlag("before", "Only threads whose last activity is before this ISO 8601 instant"),
   json: jsonFlag
 }).pipe(withDescription3("Search and list mailbox threads"), withExamples([
-  { command: "samva mailboxes threads --mailbox mbx_1234567890123456 --query invoice --json" },
+  { command: "samva mailboxes threads mbx_1234567890123456 --query invoice --json" },
   {
-    command: "samva mailboxes threads --mailbox mbx_1234567890123456 --starred --after 2026-10-01T00:00:00Z"
+    command: "samva mailboxes threads mbx_1234567890123456 --starred --after 2026-10-01T00:00:00Z"
   },
-  { command: "samva mailboxes threads --mailbox mbx_1234567890123456 --all --jsonl" }
-]), withHandler(({ mailbox, limit, cursor, all, query, folder, label, unread, starred, after, before, json }) => gen2(function* () {
-  yield* followPages({
-    all,
-    json,
-    cursor,
-    page: (pageCursor) => getMailboxJson("Could not list threads", `/v1/mailboxes/${mailbox}/threads${searchParams({
-      cursor: pageCursor,
-      limit: pageLimit(limit),
-      q: getOrUndefined(query),
-      folder: getOrUndefined(folder),
-      label: getOrUndefined(label),
-      unread: unread ? "true" : undefined,
-      starred: starred ? "true" : undefined,
-      after: getOrUndefined(after),
-      before: getOrUndefined(before)
-    })}`).pipe(flatMap3(decodeThreadPage)),
-    empty: "No threads found.",
-    human: printThread
-  });
+  { command: "samva mailboxes threads mbx_1234567890123456 --all --jsonl" }
+]), withHandler(({ mailbox, limit, cursor, all, query, folder, label, unread, starred, after, before, json }) => followPages({
+  all,
+  json,
+  cursor,
+  page: (pageCursor) => getMailboxJson("Could not list threads", `/v1/mailboxes/${mailbox}/threads${searchParams({
+    cursor: pageCursor,
+    limit: pageLimit(limit),
+    q: getOrUndefined(query),
+    folder: getOrUndefined(folder),
+    label: getOrUndefined(label),
+    unread: unread ? "true" : undefined,
+    starred: starred ? "true" : undefined,
+    after: getOrUndefined(after),
+    before: getOrUndefined(before)
+  })}`).pipe(flatMap3(decodeThreadPage)),
+  empty: "No threads found.",
+  human: printThread
 })));
 var read2 = make29("read", {
+  mailbox: mailboxIdArgument,
   messageId: messageIdArgument,
-  mailbox: mailboxFlag,
   json: jsonFlag
 }).pipe(withDescription3("Read a mailbox message"), withExamples([
-  { command: "samva mailboxes read msg_1234567890123456 --mailbox mbx_1234567890123456 --json" }
+  { command: "samva mailboxes read mbx_1234567890123456 msg_1234567890123456 --json" }
 ]), withHandler(({ messageId, mailbox, json }) => gen2(function* () {
   const raw = yield* getMailboxJson("Could not read message", `/v1/mailboxes/${mailbox}/messages/${messageId}`);
   const data = yield* decodeMessage(raw);
@@ -72049,7 +72193,7 @@ var read2 = make29("read", {
   yield* printMessage2(data);
 })));
 var send7 = make29("send", {
-  mailbox: mailboxFlag,
+  mailbox: mailboxIdArgument,
   channel: channelFlag2,
   to: String9("to").pipe(withDescription2("Recipient email address (repeatable), or one phone number in E.164 form"), atLeast2(1)),
   subject: String9("subject").pipe(withDescription2("Email only"), optional4),
@@ -72060,14 +72204,14 @@ var send7 = make29("send", {
   json: jsonFlag
 }).pipe(withDescription3("Send a message from a mailbox: email by default, or to one phone number with --channel whatsapp or sms"), withExamples([
   {
-    command: 'samva mailboxes send --mailbox mbx_1234567890123456 --to recipient@example.com --subject Hello --text "Hello"'
+    command: 'samva mailboxes send mbx_1234567890123456 --to recipient@example.com --subject Hello --text "Hello"'
   },
   {
-    command: `samva mailboxes send --mailbox mbx_1234567890123456 --channel whatsapp --to +14155550123 --template tmpl_1234567890123456 --data '{"name":"Ada"}'`,
+    command: `samva mailboxes send mbx_1234567890123456 --channel whatsapp --to +14155550123 --template tmpl_1234567890123456 --data '{"name":"Ada"}'`,
     description: "Open a WhatsApp conversation with an approved template"
   },
   {
-    command: 'samva mailboxes send --mailbox mbx_1234567890123456 --channel sms --to +14155550123 --text "Your order shipped."'
+    command: 'samva mailboxes send mbx_1234567890123456 --channel sms --to +14155550123 --text "Your order shipped."'
   }
 ]), withHandler(({
   mailbox,
@@ -72119,18 +72263,18 @@ var send7 = make29("send", {
 })));
 var messageChannel = (mailbox, messageId) => getMailboxJson("Could not read message", `/v1/mailboxes/${mailbox}/messages/${messageId}`).pipe(flatMap3((raw) => decodeUnknownEffect2(Struct({ channel: Literals(["email", "whatsapp", "sms"]) }))(raw).pipe(map7(({ channel }) => channel), mapError2(() => new SamvaCliError({ message: "The API answered with an unreadable message." })))));
 var reply2 = make29("reply", {
+  mailbox: mailboxIdArgument,
   messageId: messageIdArgument,
-  mailbox: mailboxFlag,
   ...bodyFlags,
   ...chatOnlyFlags,
   all: Boolean6("all").pipe(withDefault5(false)),
   json: jsonFlag
 }).pipe(withDescription3("Reply to a message; --all includes the other recipients. A WhatsApp or SMS message is answered on its thread, with --text or a WhatsApp --template"), withExamples([
   {
-    command: 'samva mailboxes reply msg_1234567890123456 --mailbox mbx_1234567890123456 --text "Thanks" --all'
+    command: 'samva mailboxes reply mbx_1234567890123456 msg_1234567890123456 --text "Thanks" --all'
   },
   {
-    command: "samva mailboxes reply msg_1234567890123456 --mailbox mbx_1234567890123456 --template tmpl_1234567890123456",
+    command: "samva mailboxes reply mbx_1234567890123456 msg_1234567890123456 --template tmpl_1234567890123456",
     description: "Answer a WhatsApp thread whose 24-hour service window has closed"
   }
 ]), withHandler(({ messageId, mailbox, text, html, template, data, idempotencyKey, all, json }) => gen2(function* () {
@@ -72158,8 +72302,8 @@ var reply2 = make29("reply", {
 })));
 var actionIdArgument = String10("action-id").pipe(withSchema3(MailboxActionId));
 var actionGet = make29("get", {
+  mailbox: mailboxIdArgument,
   actionId: actionIdArgument,
-  mailbox: mailboxFlag,
   json: jsonFlag
 }).pipe(withDescription3("Read a mailbox action and its current send progress"), withHandler(({ actionId, mailbox, json }) => gen2(function* () {
   const client = yield* getClientProvider;
@@ -72169,8 +72313,8 @@ var actionGet = make29("get", {
   yield* printAction(data);
 })));
 var actionCancel = make29("cancel", {
+  mailbox: mailboxIdArgument,
   actionId: actionIdArgument,
-  mailbox: mailboxFlag,
   json: jsonFlag
 }).pipe(withDescription3("Cancel an unaccepted send as a permitted person signed in with samva login"), withHandler(({ actionId, mailbox, json }) => gen2(function* () {
   const client = yield* getClientProvider;
@@ -72184,8 +72328,8 @@ var actionCancel = make29("cancel", {
   ]);
 })));
 var actionRetry = make29("retry", {
+  mailbox: mailboxIdArgument,
   actionId: actionIdArgument,
-  mailbox: mailboxFlag,
   json: jsonFlag
 }).pipe(withDescription3("Resume an eligible ended execution as a permitted person; preserves content and deadline"), withHandler(({ actionId, mailbox, json }) => gen2(function* () {
   const client = yield* getClientProvider;
@@ -72199,14 +72343,14 @@ var actionRetry = make29("retry", {
   ]);
 })));
 var quarantineList = make29("list", {
-  mailbox: mailboxFlag,
+  mailbox: mailboxIdArgument,
   ...pageFlags2,
   after: instantFlag("after", "Only messages held after this ISO 8601 instant"),
   before: instantFlag("before", "Only messages held before this ISO 8601 instant"),
   json: jsonFlag
 }).pipe(withDescription3("List held messages without their bodies"), withExamples([
-  { command: "samva mailboxes quarantine list --mailbox mbx_1234567890123456 --json" },
-  { command: "samva mailboxes quarantine list --mailbox mbx_1234567890123456 --all --jsonl" }
+  { command: "samva mailboxes quarantine list mbx_1234567890123456 --json" },
+  { command: "samva mailboxes quarantine list mbx_1234567890123456 --all --jsonl" }
 ]), withHandler(({ mailbox, limit, cursor, all, after, before, json }) => gen2(function* () {
   const client = yield* getClientProvider;
   yield* followPages({
@@ -72225,12 +72369,12 @@ var quarantineList = make29("list", {
   });
 })));
 var release2 = make29("release", {
+  mailbox: mailboxIdArgument,
   messageId: messageIdArgument,
-  mailbox: mailboxFlag,
   json: jsonFlag
 }).pipe(withDescription3("Release a held message as a person signed in with samva login"), withExamples([
   {
-    command: "samva mailboxes quarantine release msg_1234567890123456 --mailbox mbx_1234567890123456"
+    command: "samva mailboxes quarantine release mbx_1234567890123456 msg_1234567890123456"
   }
 ]), withHandler(({ messageId, mailbox, json }) => gen2(function* () {
   const client = yield* getClientProvider;
@@ -72242,12 +72386,12 @@ var release2 = make29("release", {
 var discard = make29("discard", {
   dryRun: Boolean6("dry-run").pipe(withDefault5(false)),
   yes: Boolean6("yes").pipe(withDefault5(false)),
+  mailbox: mailboxIdArgument,
   messageId: messageIdArgument,
-  mailbox: mailboxFlag,
   json: jsonFlag
 }).pipe(withDescription3("Discard a held message for good as a person signed in with samva login"), withExamples([
   {
-    command: "samva mailboxes quarantine discard msg_1234567890123456 --mailbox mbx_1234567890123456"
+    command: "samva mailboxes quarantine discard mbx_1234567890123456 msg_1234567890123456"
   }
 ]), withHandler(({ messageId, mailbox, dryRun, yes, json }) => gen2(function* () {
   if (dryRun)
@@ -73772,7 +73916,8 @@ var TemplateFamilyId2 = /* @__PURE__ */ String4.check(isPattern2(/* @__PURE__ */
 var VersionCursor2 = /* @__PURE__ */ String4.annotate({ identifier: "VersionCursor" });
 var BrandFooterBlock = /* @__PURE__ */ Struct({
   html: String4,
-  text: String4
+  text: String4,
+  headCss: optionalKey2(Union2([String4, Null2]))
 }).annotate({ identifier: "BrandFooterBlock" });
 var TemplatePublicationRender = /* @__PURE__ */ Struct({
   subject: String4,
@@ -73815,7 +73960,8 @@ var TemplateSummary = /* @__PURE__ */ Struct({
   name: String4,
   channel: Literal2("email"),
   projectId: TemplateProjectId2,
-  namespaceId: Union2([NamespaceId2, Null2]).annotate({ description: "The namespace the template's project belongs to; every entry in a project shares it. Null at organization level. A namespace-scoped key reaches only its own namespace's templates." }),
+  namespaceId: Union2([NamespaceId2, Null2]).annotate({ description: "The namespace the template's project belongs to; every entry in a project shares it. Null at organization level. A namespace-scoped key reaches only its own namespace's templates and shared ones." }),
+  shared: Boolean3.annotate({ description: "Whether the template's project is shared with every namespace. Every entry in a project shares it. A namespace-scoped key reads and sends a shared template in its own namespace but cannot change it. Only an organization-level project is shared." }),
   entryPath: String4.check(isMaxCodePoints(1024).annotate({ expected: "a string with at most 1024 code points" })).check(isPattern2(/* @__PURE__ */ new RegExp("^(?!\\/)(?!.*\\\\)(?!.*(?:^|\\/)\\.{1,2}(?:\\/|$))(?!.*(?:^|\\/)\\.git(?:\\/|$))(?:templates|emails)\\/.+\\.tsx$", "u")).annotate({ expected: "a string matching the RegExp ^(?!\\/)(?!.*\\\\)(?!.*(?:^|\\/)\\.{1,2}(?:\\/|$))(?!.*(?:^|\\/)\\.git(?:\\/|$))(?:templates|emails)\\/.+\\.tsx$" })).check(isMaxLength(1024).annotate({ expected: "a value with a length of at most 1024" })),
   status: Union2([
     Literal2("draft"),
@@ -73840,7 +73986,8 @@ var Template = /* @__PURE__ */ Struct({
   name: String4,
   channel: Literal2("email"),
   projectId: TemplateProjectId2,
-  namespaceId: Union2([NamespaceId2, Null2]).annotate({ description: "The namespace the template's project belongs to; every entry in a project shares it. Null at organization level. A namespace-scoped key reaches only its own namespace's templates." }),
+  namespaceId: Union2([NamespaceId2, Null2]).annotate({ description: "The namespace the template's project belongs to; every entry in a project shares it. Null at organization level. A namespace-scoped key reaches only its own namespace's templates and shared ones." }),
+  shared: Boolean3.annotate({ description: "Whether the template's project is shared with every namespace. Every entry in a project shares it. A namespace-scoped key reads and sends a shared template in its own namespace but cannot change it. Only an organization-level project is shared." }),
   entryPath: String4.check(isMaxCodePoints(1024).annotate({ expected: "a string with at most 1024 code points" })).check(isPattern2(/* @__PURE__ */ new RegExp("^(?!\\/)(?!.*\\\\)(?!.*(?:^|\\/)\\.{1,2}(?:\\/|$))(?!.*(?:^|\\/)\\.git(?:\\/|$))(?:templates|emails)\\/.+\\.tsx$", "u")).annotate({ expected: "a string matching the RegExp ^(?!\\/)(?!.*\\\\)(?!.*(?:^|\\/)\\.{1,2}(?:\\/|$))(?!.*(?:^|\\/)\\.git(?:\\/|$))(?:templates|emails)\\/.+\\.tsx$" })).check(isMaxLength(1024).annotate({ expected: "a value with a length of at most 1024" })),
   status: Union2([
     Literal2("draft"),
@@ -73925,7 +74072,8 @@ var TemplatesListQuery = /* @__PURE__ */ Struct({
   ]), Null2])),
   search: optionalKey2(Union2([String4, Null2])),
   projectId: optionalKey2(Union2([TemplateProjectId2, Null2])),
-  namespaceId: optionalKey2(Union2([NamespaceId2, Null2]).annotate({ description: "Only templates in this namespace. A namespace-scoped key lists its own namespace's templates only." }))
+  namespaceId: optionalKey2(Union2([NamespaceId2, Null2]).annotate({ description: "Only the templates this namespace uses: its own and those shared with every namespace (add `shared=false` for its own only). A namespace-scoped key lists its own namespace's and shared templates." })),
+  shared: optionalKey2(Union2([Union2([Literal2("true"), Literal2("false")]), Null2]).annotate({ description: "Only templates whose project is shared with every namespace (true), or only unshared ones (false)." }))
 });
 var TemplatesList200 = TemplatePage;
 var TemplatesList401 = UnauthorizedError2;
@@ -73951,6 +74099,7 @@ var TemplatesCreateRequestJson = /* @__PURE__ */ Struct({
   ]), Null2]), Null2])),
   isActive: optionalKey2(Union2([Boolean3, Null2])),
   namespaceId: optionalKey2(Union2([NamespaceId2, Null2]).annotate({ description: "The namespace the new template project belongs to; the project and every entry added to it share it. Omit for organization level. A namespace-scoped key always creates in its own namespace." })),
+  shared: optionalKey2(Union2([Boolean3, Null2]).annotate({ description: "Share the new organization-level project with every namespace: namespace-scoped keys read and send its entries but cannot change them. Defaults to false. Not with `namespaceId`, and not from a namespace-scoped key." })),
   idempotencyKey: String4.check(isMinLength(1).annotate({ expected: "a value with a length of at least 1" })).check(isMaxCodePoints(255).annotate({ expected: "a string with at most 255 code points" })).check(isMaxLength(255).annotate({ expected: "a value with a length of at most 255" }))
 });
 var TemplatesCreate201 = Template;
@@ -73994,7 +74143,8 @@ var TemplatesUpdateRequestJson = /* @__PURE__ */ Struct({ data: Struct({
   ]), Null2]), Null2])),
   fromDefault: optionalKey2(Union2([Union2([TemplateFromDefault, Null2]), Null2])),
   replyToDefault: optionalKey2(Union2([Union2([ArraySchema(String4), Null2]), Null2])),
-  isActive: optionalKey2(Union2([Boolean3, Null2]))
+  isActive: optionalKey2(Union2([Boolean3, Null2])),
+  shared: optionalKey2(Union2([Boolean3, Null2]).annotate({ description: "Share the template's project with every namespace, or stop sharing it. Applies to every entry in the project. Only an organization-level project is shared." }))
 }) });
 var TemplatesUpdate200 = Template;
 var TemplatesUpdate401 = UnauthorizedError2;
@@ -75659,7 +75809,7 @@ var TemplatesGroup = class extends make37("Templates").add(get5("templatesList",
     TemplatesPublish500,
     TemplatesPublish504.pipe(status(504))
   ]
-}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "templates.publish").annotate(Summary, "Publish an exact template commit").annotate(Description, "Builds an exact Git commit and entry path, stores the immutable compiled IR and its assets, records the input contract it validates against, and makes that publication current."), get5("templatesGetPublication", "/v1/templates/:id/publications/:publicationId", {
+}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "templates.publish").annotate(Summary, "Publish an exact template commit").annotate(Description, "Builds an exact Git commit and entry path, stores the immutable compiled IR and its assets, records the input contract it validates against, and makes that publication current. A commit that compiles to the same build as an existing publication makes that publication current again instead of recording another."), get5("templatesGetPublication", "/v1/templates/:id/publications/:publicationId", {
   params: TemplatesGetPublicationPathParams,
   success: TemplatesGetPublication200,
   error: [
@@ -78981,6 +79131,11 @@ var WebhookDailyDeliveries = /* @__PURE__ */ Struct({
   exhausted: Finite.check(isInt().annotate({ expected: "an integer" })).check(isGreaterThanOrEqualTo2(0).annotate({ expected: "a value greater than or equal to 0" })),
   cancelled: Finite.check(isInt().annotate({ expected: "an integer" })).check(isGreaterThanOrEqualTo2(0).annotate({ expected: "a value greater than or equal to 0" }))
 }).annotate({ identifier: "WebhookDailyDeliveries" });
+var WebhookSigningSecret = /* @__PURE__ */ Struct({
+  secret: SensitiveString,
+  createdAt: String4,
+  previousExpiresAt: Union2([String4, Null2])
+}).annotate({ identifier: "WebhookSigningSecret" });
 var WebhookEndpoint = /* @__PURE__ */ Struct({
   id: WebhookEndpointId2,
   name: String4,
@@ -79309,6 +79464,14 @@ var WebhooksRegenerateSecret404 = ResourceNotFoundError2;
 var WebhooksRegenerateSecret422 = ValidationError2;
 var WebhooksRegenerateSecret500 = InternalError2;
 var WebhooksRegenerateSecret504 = GatewayTimeoutError2;
+var WebhooksGetSecretPathParams = /* @__PURE__ */ Struct({ id: WebhookEndpointId2 });
+var WebhooksGetSecret200 = WebhookSigningSecret;
+var WebhooksGetSecret401 = UnauthorizedError2;
+var WebhooksGetSecret403 = ForbiddenError2;
+var WebhooksGetSecret404 = ResourceNotFoundError2;
+var WebhooksGetSecret422 = ValidationError2;
+var WebhooksGetSecret500 = InternalError2;
+var WebhooksGetSecret504 = GatewayTimeoutError2;
 var WebhooksGetStatsPathParams = /* @__PURE__ */ Struct({ id: WebhookEndpointId2 });
 var WebhooksGetStatsQuery = /* @__PURE__ */ Struct({
   after: optionalKey2(Union2([String4, Null2])),
@@ -79358,7 +79521,7 @@ var WebhooksGroup = class extends make37("Webhooks").add(get5("webhooksList", "/
     WebhooksCreate502.pipe(status(502)),
     WebhooksCreate504.pipe(status(504))
   ]
-}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "webhooks.create").annotate(Summary, "Create a webhook").annotate(Description, "Creates a signed webhook endpoint for Samva delivery and inbound events, stores subscriptions, and returns the endpoint and signing secret with a 201 response. `mailboxIds` and `namespaceId` confine mailbox events; when both are set, every mailbox must belong to the namespace."), get5("webhooksGet", "/v1/webhooks/:id", {
+}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "webhooks.create").annotate(Summary, "Create a webhook").annotate(Description, "Creates a signed webhook endpoint for Samva delivery and inbound events, stores subscriptions, and returns the endpoint and signing secret with a 201 response. `namespaceId` confines the endpoint to one namespace's events and `mailboxIds` to those mailboxes' events; when both are set, every mailbox must belong to the namespace."), get5("webhooksGet", "/v1/webhooks/:id", {
   params: WebhooksGetPathParams,
   success: WebhooksGet200,
   error: [
@@ -79429,7 +79592,18 @@ var WebhooksGroup = class extends make37("Webhooks").add(get5("webhooksList", "/
     WebhooksRegenerateSecret500,
     WebhooksRegenerateSecret504.pipe(status(504))
   ]
-}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "webhooks.regenerateSecret").annotate(Summary, "Rotate a webhook signing secret").annotate(Description, "Generates and returns a new signing secret. The previous secret remains valid for a 24-hour rotation overlap."), get5("webhooksGetStats", "/v1/webhooks/:id/stats", {
+}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "webhooks.regenerateSecret").annotate(Summary, "Rotate a webhook signing secret").annotate(Description, "Generates and returns a new signing secret. The previous secret remains valid for a 24-hour rotation overlap."), get5("webhooksGetSecret", "/v1/webhooks/:id/secret", {
+  params: WebhooksGetSecretPathParams,
+  success: WebhooksGetSecret200,
+  error: [
+    WebhooksGetSecret401.pipe(status(401)),
+    WebhooksGetSecret403.pipe(status(403)),
+    WebhooksGetSecret404.pipe(status(404)),
+    WebhooksGetSecret422.pipe(status(422)),
+    WebhooksGetSecret500,
+    WebhooksGetSecret504.pipe(status(504))
+  ]
+}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "webhooks.getSecret").annotate(Summary, "Get a webhook signing secret").annotate(Description, "Returns the endpoint's current signing secret and when a rotated-out secret stops verifying. It needs the same permission as rotating the secret."), get5("webhooksGetStats", "/v1/webhooks/:id/stats", {
   params: WebhooksGetStatsPathParams,
   query: WebhooksGetStatsQuery,
   success: WebhooksGetStats200,
@@ -79460,6 +79634,7 @@ var WebhooksGroup = class extends make37("Webhooks").add(get5("webhooksList", "/
 var make55 = /* @__PURE__ */ forGroup(WebhooksGroup);
 var list27 = /* @__PURE__ */ make55("webhooksList");
 var create16 = /* @__PURE__ */ make55("webhooksCreate");
+var getSecret = /* @__PURE__ */ make55("webhooksGetSecret");
 var get28 = /* @__PURE__ */ make55("webhooksGet");
 var remove14 = /* @__PURE__ */ make55("webhooksRemove");
 var update13 = /* @__PURE__ */ make55("webhooksUpdate");
@@ -79549,6 +79724,18 @@ var get29 = make29("get", { id: idArgument4, json: jsonFlag }).pipe(withDescript
     ["URL", data.url]
   ]);
 }).pipe(json ? provideService2(MinimumLogLevel2, "None") : identity)));
+var secret = make29("secret", { id: idArgument4, json: jsonFlag }).pipe(withDescription3("Read the current webhook signing secret (requires webhooks:update)"), withExamples([{ command: "samva webhooks secret wep_abc123 --json" }]), withHandler(({ id, json }) => gen2(function* () {
+  const client = yield* getClientProvider;
+  const data = yield* getSecret({ id }).pipe(client.provide, mapError2((error) => toCliApiError("Could not read webhook signing secret", error)));
+  if (json)
+    return yield* printJson({ ...data, secret: value2(data.secret) });
+  yield* printFields([
+    ["Signing secret", value2(data.secret)],
+    ["Created at", data.createdAt]
+  ]);
+  if (data.previousExpiresAt !== null)
+    yield* log(`The previous secret keeps verifying until ${data.previousExpiresAt}.`);
+}).pipe(json ? provideService2(MinimumLogLevel2, "None") : identity)));
 var logs = make29("logs", {
   id: idArgument4,
   limit: Int5("limit").pipe(optional4),
@@ -79706,15 +79893,15 @@ var rotate3 = make29("rotate-secret", {
   yield* confirmDestructive({
     yes,
     json,
-    message: `Rotate the signing secret for webhook ${id}? The current secret will stop working.`,
+    message: `Rotate the signing secret for webhook ${id}? The previous secret keeps verifying for 24 hours.`,
     nonInteractiveMessage: "Secret rotation requires --yes in non-interactive mode. Preview with --dry-run."
   });
   const client = yield* getClientProvider;
   const data = yield* regenerateSecret({ id }).pipe(client.provide, mapError2((error) => toCliApiError("Could not rotate webhook secret", error)));
-  const warning = "This signing secret is shown once. Store it now; the previous secret remains valid for 24 hours.";
+  const warning = `Read this signing secret again with samva webhooks secret ${id}. The previous secret remains valid for 24 hours.`;
   const secret = value2(data.secret);
   if (json)
-    return yield* printJson({ secret, displayOnce: true, warning });
+    return yield* printJson({ secret, warning });
   yield* error(`WARNING: ${warning}`);
   yield* log(secret);
 }).pipe(json ? provideService2(MinimumLogLevel2, "None") : identity)));
@@ -79735,10 +79922,10 @@ var create17 = make29("create", {
     ]);
   const client = yield* getClientProvider;
   const result = yield* create16(payload).pipe(client.provide, mapError2((error) => toCliApiError("Could not create webhook", error)));
-  const warning = "This signing secret is shown once. Store it now; `samva webhooks rotate-secret` issues a new one.";
+  const warning = `Read this signing secret again with samva webhooks secret ${result.endpoint.id}.`;
   const secret = value2(result.secret);
   if (json)
-    return yield* printJson({ endpoint: result.endpoint, secret, displayOnce: true, warning });
+    return yield* printJson({ endpoint: result.endpoint, secret, warning });
   yield* error(`WARNING: ${warning}`);
   yield* printFields([
     ["ID", result.endpoint.id],
@@ -79794,7 +79981,19 @@ var remove15 = make29("remove", {
     return yield* printJson(result);
   yield* log(`Removed webhook ${id}.`);
 }).pipe(json ? provideService2(MinimumLogLevel2, "None") : identity)));
-var webhooksCommand = make29("webhooks").pipe(withDescription3("Inspect, test, and recover customer webhooks"), withExamples([{ command: "samva webhooks list --json" }]), withSubcommands([list28, get29, create17, update14, test2, logs, stats3, retry4, rotate3, remove15]));
+var webhooksCommand = make29("webhooks").pipe(withDescription3("Inspect, test, and recover customer webhooks"), withExamples([{ command: "samva webhooks list --json" }]), withSubcommands([
+  list28,
+  get29,
+  secret,
+  create17,
+  update14,
+  test2,
+  logs,
+  stats3,
+  retry4,
+  rotate3,
+  remove15
+]));
 
 // src/lib/root-commands.ts
 var rootCommands = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samva/cli",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Samva CLI — email and platform operations from your terminal",
   "keywords": [
     "cli",
@@ -50,22 +50,22 @@
     "@effect/vitest": "4.0.0",
     "@samva/contracts": "0.0.0",
     "@samva/core": "0.0.0",
-    "@samva/mailbox": "0.5.0",
+    "@samva/mailbox": "0.5.1",
     "@samva/markup": "^0.13.1",
     "@samva/vite": "^0.13.1",
     "@types/node": "^26.6.2",
     "better-auth": "1.7.5",
     "effect": "4.0.0",
-    "samva": "0.20.0",
+    "samva": "0.21.0",
     "typescript": "^7.0.2",
     "vite": "~8.3.0",
     "vitest": "^5.0.3"
   },
   "optionalDependencies": {
-    "@samva/cli-darwin-arm64": "0.16.0",
-    "@samva/cli-darwin-x64": "0.16.0",
-    "@samva/cli-linux-arm64": "0.16.0",
-    "@samva/cli-linux-x64": "0.16.0"
+    "@samva/cli-darwin-arm64": "0.18.0",
+    "@samva/cli-darwin-x64": "0.18.0",
+    "@samva/cli-linux-arm64": "0.18.0",
+    "@samva/cli-linux-x64": "0.18.0"
   },
   "engines": {
     "node": ">=18"