@samva/cli 0.17.0 → 0.18.0

package/AGENTS.md

@@ -37,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.

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.17.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.17.0",
-    "@samva/cli-darwin-x64": "workspace:0.17.0",
-    "@samva/cli-linux-arm64": "workspace:0.17.0",
-    "@samva/cli-linux-x64": "workspace:0.17.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"
@@ -19596,6 +19596,9 @@ var ENTITY_PREFIXES = {
   waflow: "WhatsAppFlowId",
   wafver: "WhatsAppFlowVersionId",
   wafreg: "WhatsAppFlowRegistrationId",
+  wafkey: "WhatsAppFlowEncryptionKeyId",
+  wafx: "WhatsAppFlowExchangeId",
+  wasl: "WhatsAppSetupLinkId",
   mbx: "MailboxId",
   mbxep: "MailboxEndpointId",
   thread: "MailboxThreadId",
@@ -19691,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));
@@ -20398,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",
@@ -20422,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
 ];
@@ -24149,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({
@@ -24462,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"),
@@ -24799,6 +24809,7 @@ var apiStatuses = {
   MailboxSendConflictError: 409,
   MailboxSendRefusedError: 403,
   CursorExpiredError: 410,
+  WhatsAppSetupLinkUnavailableError: 410,
   MethodNotAllowedError: 405,
   UpgradeRequiredError: 426,
   RateLimitedError: 429,
@@ -25082,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;
@@ -25473,6 +25484,7 @@ var commandTree = {
   webhooks: {
     list: {},
     get: {},
+    secret: {},
     create: {},
     update: {},
     test: {},
@@ -25903,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({
@@ -27166,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"]
@@ -28558,6 +28579,7 @@ var SamvaOperations = {
   webhooksRetryDelivery: operationMetadata96,
   webhooksGetLogs: operationMetadata95,
   webhooksRegenerateSecret: operationMetadata96,
+  webhooksGetSecret: operationMetadata97,
   webhooksGetStats: operationMetadata97,
   webhooksTest: operationMetadata96,
   whoamiGet: {
@@ -28804,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]),
@@ -28817,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]),
@@ -54206,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({
@@ -54304,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,
@@ -54659,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);
@@ -55131,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],
@@ -55146,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,
@@ -55186,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"),
@@ -67136,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",
@@ -67678,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])
@@ -67701,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]),
@@ -68329,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]
 ]);
@@ -73851,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,
@@ -73894,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"),
@@ -73919,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"),
@@ -74004,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;
@@ -74030,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;
@@ -74073,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;
@@ -79060,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,
@@ -79388,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])),
@@ -79437,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: [
@@ -79508,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,
@@ -79539,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");
@@ -79628,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),
@@ -79785,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)));
@@ -79814,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],
@@ -79873,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.17.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.17.0",
-    "@samva/cli-darwin-x64": "0.17.0",
-    "@samva/cli-linux-arm64": "0.17.0",
-    "@samva/cli-linux-x64": "0.17.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"