@samva/cli 0.8.0 → 0.9.0

package/README.md

@@ -420,13 +420,20 @@ review decision, sendable domain and verified sender counts, and domain-verifica
 `readyToSend` is true when a production send would be admitted and at least one domain or sender can
 carry it. It is read-only and does not inspect receiving configuration, check DNS itself, send an
 email, or replay fixtures.
-Use `samva email receiving status <domain-id>` to read a domain's receiving prerequisite status.
-`samva email receiving enable <domain-id> ...` acts by default; its `--dry-run` is offline and does
-not require credentials or call the API. Each check is `passed`, `failed`, or
+Each check is `passed`, `failed`, or
 `unavailable`. A `failed` check carries the underlying error detail; `unavailable`, such as no
 sending domain yet or a review in progress, is informational; a rejected review fails. The command always prints the full report, then
 exits `1` if any check failed and `0` otherwise. The `--json` result's `data` adds an aggregate
 `ok` boolean, and human output marks checks with `✓`, `!`, and `✗` respectively.
 
+Use `samva email receiving status <domain-id>` to read a domain's receiving prerequisites in
+order: sending verified, a destination, receiving enabled, and the inbound MX, which it looks up
+live and names when mail is routed elsewhere.
+`samva email receiving enable <domain-id> --domain <name> --catch-all [--endpoint <webhook-id>]`
+routes every address on a verified domain. A catch-all needs a destination, either `--endpoint` or
+an active forwarding rule that covers the domain; mail that matches neither is rejected. Pass
+`--address` for exact recipients instead. The command acts by default; its `--dry-run` is offline
+and does not require credentials or call the API.
+
 A command that needs a subcommand, such as a bare `samva` or a group like `samva email`, prints its
 help to stdout and exits `2`, so a script never mistakes a missing subcommand for success.

package/dist/bin.mjs

@@ -13982,7 +13982,7 @@ var layer12 = /* @__PURE__ */ layer.pipe(/* @__PURE__ */ provideMerge(/* @__PURE
 // package.json
 var package_default = {
   name: "@samva/cli",
-  version: "0.8.0",
+  version: "0.9.0",
   description: "Samva CLI \u2014 email and platform operations from your terminal",
   keywords: [
     "cli",
@@ -14037,16 +14037,16 @@ var package_default = {
     "@types/node": "catalog:",
     "better-auth": "catalog:",
     effect: "catalog:effect",
-    samva: "workspace:0.11.0",
+    samva: "workspace:0.12.0",
     typescript: "catalog:",
     vite: "~8.3.0",
     vitest: "catalog:"
   },
   optionalDependencies: {
-    "@samva/cli-darwin-arm64": "workspace:0.8.0",
-    "@samva/cli-darwin-x64": "workspace:0.8.0",
-    "@samva/cli-linux-arm64": "workspace:0.8.0",
-    "@samva/cli-linux-x64": "workspace:0.8.0"
+    "@samva/cli-darwin-arm64": "workspace:0.9.0",
+    "@samva/cli-darwin-x64": "workspace:0.9.0",
+    "@samva/cli-linux-arm64": "workspace:0.9.0",
+    "@samva/cli-linux-x64": "workspace:0.9.0"
   },
   engines: {
     node: ">=18"
@@ -43690,8 +43690,8 @@ function buildMessagesSendPayload(input) {
   };
 }
 
-// ../sdk/dist/client-attribution-Ct2FKITg.js
-var SDK_VERSION = "0.11.0";
+// ../sdk/dist/client-attribution-BTWYSXxo.js
+var SDK_VERSION = "0.12.0";
 var CLIENT_ATTRIBUTION_HEADER = "x-samva-client";
 var clientAttribution = (surface) => `${surface}/${SDK_VERSION}`;
 
@@ -46053,7 +46053,7 @@ var fetch2 = /* @__PURE__ */ make34((request, url, signal, fiber) => {
 });
 var layer15 = /* @__PURE__ */ layerMergedContext(/* @__PURE__ */ succeed6(fetch2));
 
-// ../sdk/dist/client-8YXjfsVc.js
+// ../sdk/dist/client-Cj1bqIEe.js
 var Sensitive = (schema) => RedactedFromValue(schema);
 var SensitiveString = Sensitive(String4);
 var ABSOLUTE_ISO_INSTANT_PATTERN = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?(Z|([+-])(\d{2}):(\d{2}))$/;
@@ -46381,6 +46381,25 @@ var EmailChannelError = class extends TaggedError3()("EmailChannelError", Struct
   statusCode: optionalKey2(Union2([Finite.check(isFinite4().annotate({ expected: "a finite number" })), Null2]))
 })) {
 };
+var CustomTrackingCertificate = Struct({
+  reason: Struct({
+    code: Union2([
+      Literal2("initializing"),
+      Literal2("awaiting-hostname"),
+      Literal2("awaiting-dcv"),
+      Literal2("issuing"),
+      Literal2("caa-blocked"),
+      Literal2("validation-error"),
+      Literal2("timed-out"),
+      Literal2("verifying-route"),
+      Literal2("ready"),
+      Literal2("provider-unreachable")
+    ]),
+    message: String4
+  }),
+  lastCheckedAt: Union2([String4, Null2]),
+  nextCheckAt: Union2([String4, Null2])
+}).annotate({ identifier: "CustomTrackingCertificate" });
 var CustomTrackingDnsRecord = Struct({
   name: String4,
   type: String4,
@@ -47727,6 +47746,49 @@ var BlockLogPage = Struct({
   })),
   nextCursor: Union2([String4, Null2])
 }).annotate({ identifier: "BlockLogPage" });
+var ReceivingStatus = Struct({
+  domain: String4,
+  receivingHost: String4,
+  sending: Struct({
+    satisfied: Boolean3,
+    phase: Union2([
+      Literal2("dns-setup"),
+      Literal2("provisioning"),
+      Literal2("verifying"),
+      Literal2("ready"),
+      Literal2("degraded"),
+      Literal2("failed")
+    ])
+  }),
+  destination: Struct({
+    satisfied: Boolean3,
+    endpointId: Union2([WebhookEndpointId, Null2]),
+    forwardingRules: Finite.check(isInt().annotate({ expected: "an integer" })).check(isGreaterThanOrEqualTo2(0).annotate({ expected: "a value greater than or equal to 0" })),
+    mailboxes: Finite.check(isInt().annotate({ expected: "an integer" })).check(isGreaterThanOrEqualTo2(0).annotate({ expected: "a value greater than or equal to 0" }))
+  }),
+  receiving: Struct({
+    satisfied: Boolean3,
+    catchAll: Boolean3
+  }),
+  mx: Struct({
+    satisfied: Boolean3,
+    state: Union2([
+      Literal2("pointing-here"),
+      Literal2("elsewhere"),
+      Literal2("missing"),
+      Literal2("unknown")
+    ]),
+    expected: Struct({
+      exchange: String4,
+      priority: Finite.check(isInt().annotate({ expected: "an integer" })).check(isGreaterThanOrEqualTo2(0).annotate({ expected: "a value greater than or equal to 0" }))
+    }),
+    current: ArraySchema(Struct({
+      exchange: String4,
+      priority: Finite.check(isInt().annotate({ expected: "an integer" })).check(isGreaterThanOrEqualTo2(0).annotate({ expected: "a value greater than or equal to 0" }))
+    }))
+  }),
+  ready: Boolean3
+}).annotate({ identifier: "ReceivingStatus" });
 var WebhookEndpoint = Struct({
   id: WebhookEndpointId,
   name: String4,
@@ -47879,6 +47941,7 @@ var CustomTrackingStatus = Struct({
     hostname: String4,
     region: String4,
     sslStatus: Union2([String4, Null2]),
+    certificate: Union2([CustomTrackingCertificate, Null2]),
     dnsRecords: Struct({
       tracking: Union2([CustomTrackingDnsRecord, Null2]),
       dcvDelegation: Union2([CustomTrackingDnsRecord, Null2])
@@ -47967,10 +48030,11 @@ var ForwardingRuleList = Struct({ items: ArraySchema(Struct({
   id: EmailForwardingRuleId,
   name: String4,
   description: Union2([String4, Null2]),
+  domainId: Union2([EmailDomainId, Null2]),
   sourcePattern: Union2([String4, Null2]),
   forwardTo: ArraySchema(String4),
   preserveHeaders: Boolean3,
-  priority: Finite.check(isInt().annotate({ expected: "an integer" })).check(isGreaterThanOrEqualTo2(0).annotate({ expected: "a value greater than or equal to 0" })),
+  priority: Finite.check(isInt().annotate({ expected: "an integer" })).check(isGreaterThanOrEqualTo2(0).annotate({ expected: "a value greater than or equal to 0" })).check(isLessThanOrEqualTo3(2147483647).annotate({ expected: "a value less than or equal to 2147483647" })),
   isActive: Boolean3,
   forwardCount: Finite.check(isInt().annotate({ expected: "an integer" })).check(isGreaterThanOrEqualTo2(0).annotate({ expected: "a value greater than or equal to 0" })),
   failureCount: Finite.check(isInt().annotate({ expected: "an integer" })).check(isGreaterThanOrEqualTo2(0).annotate({ expected: "a value greater than or equal to 0" })),
@@ -51367,6 +51431,16 @@ var EmailCompleteCustomTrackingDomainConnect403 = ForbiddenError;
 var EmailCompleteCustomTrackingDomainConnect422 = ValidationError;
 var EmailCompleteCustomTrackingDomainConnect500 = InternalError;
 var EmailCompleteCustomTrackingDomainConnect504 = GatewayTimeoutError;
+var EmailRecheckCustomTrackingPathParams = Struct({ id: EmailDomainId });
+var EmailRecheckCustomTracking200 = CustomTrackingStatus;
+var EmailRecheckCustomTracking401 = UnauthorizedError;
+var EmailRecheckCustomTracking403 = ForbiddenError;
+var EmailRecheckCustomTracking404 = ResourceNotFoundError;
+var EmailRecheckCustomTracking409 = ConflictError;
+var EmailRecheckCustomTracking422 = ValidationError;
+var EmailRecheckCustomTracking500 = InternalError;
+var EmailRecheckCustomTracking502 = EmailChannelError;
+var EmailRecheckCustomTracking504 = GatewayTimeoutError;
 var EmailSetDefaultDomainPathParams = Struct({ id: EmailDomainId });
 var EmailSetDefaultDomain200 = SuccessResult;
 var EmailSetDefaultDomain401 = UnauthorizedError;
@@ -51436,7 +51510,7 @@ var EmailCompleteDomainConnect500 = InternalError;
 var EmailCompleteDomainConnect502 = EmailChannelError;
 var EmailCompleteDomainConnect504 = GatewayTimeoutError;
 var EmailEnableCatchAllPathParams = Struct({ id: EmailDomainId });
-var EmailEnableCatchAllRequestJson = Struct({ endpointId: WebhookEndpointId });
+var EmailEnableCatchAllRequestJson = Struct({ endpointId: optionalKey2(Union2([WebhookEndpointId, Null2])) });
 var EmailEnableCatchAll201 = Struct({ success: Literal2(true) });
 var EmailEnableCatchAll401 = UnauthorizedError;
 var EmailEnableCatchAll403 = ForbiddenError;
@@ -51462,6 +51536,14 @@ var EmailEnableReceiving404 = ResourceNotFoundError;
 var EmailEnableReceiving422 = ValidationError;
 var EmailEnableReceiving500 = InternalError;
 var EmailEnableReceiving504 = GatewayTimeoutError;
+var EmailGetReceivingStatusPathParams = Struct({ id: EmailDomainId });
+var EmailGetReceivingStatus200 = ReceivingStatus;
+var EmailGetReceivingStatus401 = UnauthorizedError;
+var EmailGetReceivingStatus403 = ForbiddenError;
+var EmailGetReceivingStatus404 = ResourceNotFoundError;
+var EmailGetReceivingStatus422 = ValidationError;
+var EmailGetReceivingStatus500 = InternalError;
+var EmailGetReceivingStatus504 = GatewayTimeoutError;
 var EmailDetectRegistrarPathParams = Struct({ id: EmailDomainId });
 var EmailDetectRegistrarRequestJson = Struct({ domain: String4 });
 var EmailDetectRegistrar200 = Struct({
@@ -51607,7 +51689,7 @@ var EmailCreateForwardingRuleRequestJson = Struct({
   preserveHeaders: optionalKey2(Union2([Boolean3, Null2])),
   appendNote: optionalKey2(Union2([String4, Null2])),
   conditions: optionalKey2(Union2([ForwardingConditions, Null2])),
-  priority: optionalKey2(Union2([Finite.check(isFinite4().annotate({ expected: "a finite number" })), Null2])),
+  priority: optionalKey2(Union2([Finite.check(isInt().annotate({ expected: "an integer" })).check(isGreaterThanOrEqualTo2(0).annotate({ expected: "a value greater than or equal to 0" })).check(isLessThanOrEqualTo3(2147483647).annotate({ expected: "a value less than or equal to 2147483647" })), Null2])),
   isActive: optionalKey2(Union2([Boolean3, Null2])),
   metadata: optionalKey2(Union2([Union2([Record(String4, JsonValue), Null2]), Null2]))
 });
@@ -51615,7 +51697,7 @@ var EmailCreateForwardingRule201 = Struct({
   id: EmailForwardingRuleId,
   name: String4,
   forwardTo: ArraySchema(String4),
-  priority: Finite.check(isInt().annotate({ expected: "an integer" })).check(isGreaterThanOrEqualTo2(0).annotate({ expected: "a value greater than or equal to 0" })),
+  priority: Finite.check(isInt().annotate({ expected: "an integer" })).check(isGreaterThanOrEqualTo2(0).annotate({ expected: "a value greater than or equal to 0" })).check(isLessThanOrEqualTo3(2147483647).annotate({ expected: "a value less than or equal to 2147483647" })),
   isActive: Boolean3,
   createdAt: String4
 });
@@ -51644,7 +51726,7 @@ var EmailUpdateForwardingRuleRequestJson = Struct({
   preserveHeaders: optionalKey2(Union2([Boolean3, Null2])),
   appendNote: optionalKey2(Union2([String4, Null2])),
   conditions: optionalKey2(Union2([Union2([ForwardingConditions, Null2]), Null2])),
-  priority: optionalKey2(Union2([Finite.check(isFinite4().annotate({ expected: "a finite number" })), Null2])),
+  priority: optionalKey2(Union2([Finite.check(isInt().annotate({ expected: "an integer" })).check(isGreaterThanOrEqualTo2(0).annotate({ expected: "a value greater than or equal to 0" })).check(isLessThanOrEqualTo3(2147483647).annotate({ expected: "a value less than or equal to 2147483647" })), Null2])),
   isActive: optionalKey2(Union2([Boolean3, Null2])),
   metadata: optionalKey2(Union2([Union2([Record(String4, JsonValue), Null2]), Null2]))
 });
@@ -51652,7 +51734,7 @@ var EmailUpdateForwardingRule200 = Struct({
   id: EmailForwardingRuleId,
   name: String4,
   forwardTo: ArraySchema(String4),
-  priority: Finite.check(isInt().annotate({ expected: "an integer" })).check(isGreaterThanOrEqualTo2(0).annotate({ expected: "a value greater than or equal to 0" })),
+  priority: Finite.check(isInt().annotate({ expected: "an integer" })).check(isGreaterThanOrEqualTo2(0).annotate({ expected: "a value greater than or equal to 0" })).check(isLessThanOrEqualTo3(2147483647).annotate({ expected: "a value less than or equal to 2147483647" })),
   isActive: Boolean3,
   updatedAt: String4
 });
@@ -56589,7 +56671,20 @@ var EmailGroup = class extends make38("Email").add(get5("emailListBlocks", "/v1/
     EmailCompleteCustomTrackingDomainConnect500,
     EmailCompleteCustomTrackingDomainConnect504.pipe(status(504))
   ]
-}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "email.completeCustomTrackingDomainConnect").annotate(Summary, "Complete an automatic Custom Tracking Domain return").annotate(Description, "Validates the signed state returned by the DNS provider, then checks the tracking host again. Returning here never marks the host ready or changes which tracking host email uses."), post("emailSetDefaultDomain", "/v1/email/domains/:id/default", {
+}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "email.completeCustomTrackingDomainConnect").annotate(Summary, "Complete an automatic Custom Tracking Domain return").annotate(Description, "Validates the signed state returned by the DNS provider, then checks the tracking host again. Returning here never marks the host ready or changes which tracking host email uses."), post("emailRecheckCustomTracking", "/v1/email/domains/:id/custom-tracking/recheck", {
+  params: EmailRecheckCustomTrackingPathParams,
+  success: EmailRecheckCustomTracking200,
+  error: [
+    EmailRecheckCustomTracking401.pipe(status(401)),
+    EmailRecheckCustomTracking403.pipe(status(403)),
+    EmailRecheckCustomTracking404.pipe(status(404)),
+    EmailRecheckCustomTracking409.pipe(status(409)),
+    EmailRecheckCustomTracking422.pipe(status(422)),
+    EmailRecheckCustomTracking500,
+    EmailRecheckCustomTracking502.pipe(status(502)),
+    EmailRecheckCustomTracking504.pipe(status(504))
+  ]
+}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "email.recheckCustomTracking").annotate(Summary, "Recheck a custom tracking domain's certificate").annotate(Description, "Checks the hostname's certificate now instead of waiting for the next scheduled check, and returns the refreshed state. Samva checks a hostname at most once every 30 seconds; a recheck inside that window returns the state from the last check. Returns a conflict when custom tracking is disabled or being torn down."), post("emailSetDefaultDomain", "/v1/email/domains/:id/default", {
   params: EmailSetDefaultDomainPathParams,
   success: EmailSetDefaultDomain200,
   error: [
@@ -56661,7 +56756,7 @@ var EmailGroup = class extends make38("Email").add(get5("emailListBlocks", "/v1/
     EmailBuildDomainConnectApplyUrl502.pipe(status(502)),
     EmailBuildDomainConnectApplyUrl504.pipe(status(504))
   ]
-}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "email.buildDomainConnectApplyUrl").annotate(Summary, "Build a one-click DNS apply URL").annotate(Description, "Builds the signed Domain Connect apply URL for the selected sending-only or sending-and-receiving service. Manual DNS remains available for either mode."), post("emailCompleteDomainConnect", "/v1/email/domains/:id/domain-connect/complete", {
+}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "email.buildDomainConnectApplyUrl").annotate(Summary, "Build a one-click DNS apply URL").annotate(Description, "Builds the signed Domain Connect apply URL for the selected sending-only or sending-and-receiving service. The sending-and-receiving service writes the apex inbound MX, so it is refused until the domain's receiving is enabled. Manual DNS remains available for either mode."), post("emailCompleteDomainConnect", "/v1/email/domains/:id/domain-connect/complete", {
   params: EmailCompleteDomainConnectPathParams,
   payload: EmailCompleteDomainConnectRequestJson,
   success: EmailCompleteDomainConnect200,
@@ -56687,7 +56782,7 @@ var EmailGroup = class extends make38("Email").add(get5("emailListBlocks", "/v1/
     EmailEnableCatchAll502.pipe(status(502)),
     EmailEnableCatchAll504.pipe(status(504))
   ]
-}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "email.enableCatchAll").annotate(Summary, "Enable catch-all receiving").annotate(Description, "Enables catch-all inbound receiving for a domain. `endpointId` is one of the organization's webhook endpoints; every address on the domain delivers `message.received` to it. Responds with 201."), post("emailEnableReceiving", "/v1/email/domains/:id/enable-receiving", {
+}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "email.enableCatchAll").annotate(Summary, "Enable catch-all receiving").annotate(Description, "Enables catch-all inbound receiving for a verified domain. `endpointId` is one of the organization's webhook endpoints; every address on the domain delivers `message.received` to it. Omit it to deliver through forwarding rules alone, which needs at least one active forwarding rule covering the domain. Mail that matches neither a rule nor an endpoint is rejected as an unknown recipient. Responds with 201."), post("emailEnableReceiving", "/v1/email/domains/:id/enable-receiving", {
   params: EmailEnableReceivingPathParams,
   payload: EmailEnableReceivingRequestJson,
   success: EmailEnableReceiving200,
@@ -56699,7 +56794,18 @@ var EmailGroup = class extends make38("Email").add(get5("emailListBlocks", "/v1/
     EmailEnableReceiving500,
     EmailEnableReceiving504.pipe(status(504))
   ]
-}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "email.enableReceiving").annotate(Summary, "Enable inbound email for a domain").annotate(Description, "Enables inbound receiving for a verified domain and returns the recipient addresses it accepts. Set `catchAll` to route every address on the domain; that requires a webhook endpoint, supplied as `endpointId` or already configured on the domain."), post("emailDetectRegistrar", "/v1/email/domains/:id/registrar", {
+}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "email.enableReceiving").annotate(Summary, "Enable inbound email for a domain").annotate(Description, "Enables inbound receiving for a verified domain and returns the recipient addresses it accepts. Set `catchAll` to route every address on the domain; that needs a destination: a webhook endpoint, supplied as `endpointId` or already configured on the domain, or at least one active forwarding rule that covers the domain. Mail that matches neither is rejected, never accepted and dropped."), get5("emailGetReceivingStatus", "/v1/email/domains/:id/receiving-status", {
+  params: EmailGetReceivingStatusPathParams,
+  success: EmailGetReceivingStatus200,
+  error: [
+    EmailGetReceivingStatus401.pipe(status(401)),
+    EmailGetReceivingStatus403.pipe(status(403)),
+    EmailGetReceivingStatus404.pipe(status(404)),
+    EmailGetReceivingStatus422.pipe(status(422)),
+    EmailGetReceivingStatus500,
+    EmailGetReceivingStatus504.pipe(status(504))
+  ]
+}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "email.getReceivingStatus").annotate(Summary, "Get receiving setup status").annotate(Description, "Reports each prerequisite for receiving a domain's mail at Samva, in order: sending verified, a destination (a webhook endpoint or an active forwarding rule), receiving enabled, and the inbound MX record. The MX answer is a live DNS lookup that names the current target when mail is routed elsewhere."), post("emailDetectRegistrar", "/v1/email/domains/:id/registrar", {
   params: EmailDetectRegistrarPathParams,
   payload: EmailDetectRegistrarRequestJson,
   success: EmailDetectRegistrar200,
@@ -56847,7 +56953,7 @@ var EmailGroup = class extends make38("Email").add(get5("emailListBlocks", "/v1/
     EmailListForwardingRules500,
     EmailListForwardingRules504.pipe(status(504))
   ]
-}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "email.listForwardingRules").annotate(Summary, "List forwarding rules").annotate(Description, "Returns every inbound email forwarding rule, highest priority first, optionally filtered by domain and active state. An organization holds at most 100, so the list is never paged."), post("emailCreateForwardingRule", "/v1/email/forwarding", {
+}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "email.listForwardingRules").annotate(Summary, "List forwarding rules").annotate(Description, "Returns every inbound email forwarding rule in the order inbound mail is matched against them: highest priority first, then an exact address before a wildcard pattern at equal priority, then oldest first. The first rule that matches is the one that forwards. Filtering by domain returns that domain's rules and the rules that apply to every domain (domainId null). An organization holds at most 100, so the list is never paged."), post("emailCreateForwardingRule", "/v1/email/forwarding", {
   payload: EmailCreateForwardingRuleRequestJson,
   success: EmailCreateForwardingRule201.pipe(status(201)),
   error: [
@@ -56859,7 +56965,7 @@ var EmailGroup = class extends make38("Email").add(get5("emailListBlocks", "/v1/
     EmailCreateForwardingRule500,
     EmailCreateForwardingRule504.pipe(status(504))
   ]
-}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "email.createForwardingRule").annotate(Summary, "Create a forwarding rule").annotate(Description, "Creates an inbound email forwarding rule and returns it. Responds with 201. An organization holds at most 100 forwarding rules."), del("emailDeleteForwardingRule", "/v1/email/forwarding/:id", {
+}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "email.createForwardingRule").annotate(Summary, "Create a forwarding rule").annotate(Description, "Creates an inbound email forwarding rule and returns it. Responds with 201. Priority is a non-negative integer, default 0; higher priority rules are tried first, and at equal priority an exact address outranks a wildcard pattern. An organization holds at most 100 forwarding rules."), del("emailDeleteForwardingRule", "/v1/email/forwarding/:id", {
   params: EmailDeleteForwardingRulePathParams,
   success: EmailDeleteForwardingRule200,
   error: [
@@ -59110,7 +59216,7 @@ var generateIdempotencyKey = gen2(function* () {
   return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 });
 
-// ../sdk/dist/operation-BuyvAsZ1.js
+// ../sdk/dist/operation-BEghYyLu.js
 var SDK_OPERATION_CALLS = {
   brandsList: { kind: "none" },
   brandsCreate: { kind: "payload" },
@@ -59308,6 +59414,10 @@ var SDK_OPERATION_CALLS = {
     kind: "pathPayload",
     paths: ["id"]
   },
+  emailGetReceivingStatus: {
+    kind: "path",
+    paths: ["id"]
+  },
   emailEnableCustomTracking: {
     kind: "pathPayload",
     paths: ["id"]
@@ -59316,6 +59426,10 @@ var SDK_OPERATION_CALLS = {
     kind: "path",
     paths: ["id"]
   },
+  emailRecheckCustomTracking: {
+    kind: "path",
+    paths: ["id"]
+  },
   emailGetCustomTrackingDomainConnect: {
     kind: "path",
     paths: ["id"]
@@ -60357,8 +60471,10 @@ var getDomainConnect = make40("emailGetDomainConnect");
 var buildDomainConnectApplyUrl = make40("emailBuildDomainConnectApplyUrl");
 var completeDomainConnect = make40("emailCompleteDomainConnect");
 var enableReceiving = make40("emailEnableReceiving");
+var getReceivingStatus = make40("emailGetReceivingStatus");
 var enableCustomTracking = make40("emailEnableCustomTracking");
 var getCustomTracking = make40("emailGetCustomTracking");
+var recheckCustomTracking = make40("emailRecheckCustomTracking");
 var getCustomTrackingDomainConnect = make40("emailGetCustomTrackingDomainConnect");
 var buildCustomTrackingDomainConnectApplyUrl = make40("emailBuildCustomTrackingDomainConnectApplyUrl");
 var completeCustomTrackingDomainConnect = make40("emailCompleteCustomTrackingDomainConnect");
@@ -60420,7 +60536,7 @@ var getVersion = make40("extensionsGetVersion");
 // ../sdk/dist/effect/feedback.js
 var send2 = make40("feedbackSend");
 
-// ../sdk/dist/mailbox-events-CcWm8lO4.js
+// ../sdk/dist/mailbox-events-CsbF35vH.js
 var MAILBOX_EVENT_STREAM_PATH = "/v1/mailboxes/events";
 var MailboxEventStreamCloseCode = {
   invalidFrame: 4400,
@@ -60470,7 +60586,9 @@ var RETRY_MAX_MILLIS = 30000;
 var RETRY_AFTER_MAX_MILLIS = 300000;
 var REFUSAL_BODY_LIMIT = 65536;
 var DIAGNOSE_TIMEOUT_MILLIS = 1e4;
-var MAILBOX_EVENT_STREAM_IDLE_MILLIS = 90000;
+var MAILBOX_EVENT_STREAM_PING_FRAME = '{"kind":"ping"}';
+var MAILBOX_EVENT_STREAM_PING_MILLIS = 30000;
+var MAILBOX_EVENT_STREAM_IDLE_MILLIS = 3 * MAILBOX_EVENT_STREAM_PING_MILLIS;
 var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var frameText = (raw) => {
   if (typeof raw === "string")
@@ -60488,9 +60606,11 @@ var decodeFrame = (raw) => {
   } catch {
     return;
   }
+  if (isRecord(parsed) && parsed.kind === "pong")
+    return { kind: "pong" };
   if (!isRecord(parsed) || typeof parsed.cursor !== "string")
     return;
-  if (parsed.kind === "live" || parsed.kind === "heartbeat")
+  if (parsed.kind === "live" || parsed.kind === "progress")
     return {
       kind: parsed.kind,
       cursor: parsed.cursor
@@ -60831,6 +60951,7 @@ var MailboxEventStream = class {
       let opened = false;
       let settled = false;
       let idleTimer;
+      let pingTimer;
       const armIdle = () => {
         clearTimeout(idleTimer);
         idleTimer = setTimeout(() => {
@@ -60846,6 +60967,7 @@ var MailboxEventStream = class {
           return;
         settled = true;
         clearTimeout(idleTimer);
+        clearInterval(pingTimer);
         this.#stop.signal.removeEventListener("abort", onStop);
         if (this.#socket === socket)
           this.#socket = undefined;
@@ -60868,6 +60990,10 @@ var MailboxEventStream = class {
       armIdle();
       socket.addEventListener("open", () => {
         opened = true;
+        pingTimer = setInterval(() => {
+          if (socket.readyState === OPEN)
+            socket.send(MAILBOX_EVENT_STREAM_PING_FRAME);
+        }, MAILBOX_EVENT_STREAM_PING_MILLIS);
       });
       socket.addEventListener("message", (message) => {
         if (this.#ended)
@@ -60884,6 +61010,8 @@ var MailboxEventStream = class {
           socket.close(1000);
           return;
         }
+        if (frame.kind === "pong")
+          return;
         if (frame.kind === "event") {
           this.#queue.push({
             cursor: frame.cursor,
@@ -60994,7 +61122,7 @@ var readRefusalBody = async (response) => {
   }
 };
 
-// ../sdk/dist/mailboxes-4gJMAJh4.js
+// ../sdk/dist/mailboxes-BtcktcNB.js
 var toStreamError = (cause) => cause instanceof MailboxEventStreamError ? cause : new MailboxEventStreamError({
   _tag: "StreamDisconnectedError",
   message: String(cause)
@@ -61412,7 +61540,7 @@ var commandTree = {
       check: {},
       remove: {},
       "rotate-dkim": {},
-      "custom-tracking": { enable: {}, status: {}, disable: {} }
+      "custom-tracking": { enable: {}, status: {}, recheck: {}, disable: {} }
     },
     senders: { list: {}, add: {}, check: {}, remove: {} }
   },
@@ -63282,7 +63410,10 @@ var printCustomTracking = (data) => gen2(function* () {
     ["Host", custom.hostname],
     ["Region", custom.region],
     ["Certificate", custom.sslStatus ?? "pending"],
-    ["CAA blocked", custom.caaBlocked ? "yes" : "no"]
+    ["CAA blocked", custom.caaBlocked ? "yes" : "no"],
+    ["Reason", custom.certificate?.reason.message],
+    ["Last checked", custom.certificate?.lastCheckedAt],
+    ["Next check", custom.certificate?.nextCheckAt]
   ]);
   yield* log(`
 Create these DNS records:`);
@@ -63334,6 +63465,16 @@ var customStatus = make29("status", {
     return yield* printJson(data);
   yield* printCustomTracking(data);
 }).pipe(json ? provideService2(MinimumLogLevel2, "None") : identity)));
+var customRecheck = make29("recheck", {
+  id: String10("id").pipe(withDescription4("Domain id to recheck")),
+  json: jsonFlag
+}).pipe(withDescription3("Check a domain's custom tracking certificate now instead of waiting for the next scheduled check"), withExamples([{ command: "samva email domains custom-tracking recheck dom_abc123" }]), withHandler(({ id, json }) => gen2(function* () {
+  const client = yield* getClientProvider;
+  const data = yield* recheckCustomTracking({ id }).pipe(client.provide, mapError2((error) => toCliApiError("Could not recheck custom tracking", error)));
+  if (json)
+    return yield* printJson(data);
+  yield* printCustomTracking(data);
+}).pipe(json ? provideService2(MinimumLogLevel2, "None") : identity)));
 var customDisable = make29("disable", {
   id: String10("id").pipe(withDescription4("Domain id to disable custom tracking for")),
   dryRun: Boolean6("dry-run").pipe(withDescription2("Print the teardown plan without calling the API"), withDefault5(false)),
@@ -63358,50 +63499,106 @@ var customDisable = make29("disable", {
     return yield* printJson(data);
   yield* log(`Disabled custom tracking for ${id}.`);
 }).pipe(json ? provideService2(MinimumLogLevel2, "None") : identity)));
-var customTracking = make29("custom-tracking").pipe(withDescription3("Manage a domain's custom tracking (custom open/click subdomain)"), withExamples([{ command: "samva email domains custom-tracking enable dom_abc123" }]), withSubcommands([customEnable, customStatus, customDisable]));
+var customTracking = make29("custom-tracking").pipe(withDescription3("Manage a domain's custom tracking (custom open/click subdomain)"), withExamples([{ command: "samva email domains custom-tracking enable dom_abc123" }]), withSubcommands([customEnable, customStatus, customRecheck, customDisable]));
 var domainsCommand = make29("domains").pipe(withDescription3("Manage email sending domains"), withExamples([
   { command: "samva email domains list", description: "List configured domains" }
 ]), withSubcommands([list21, add2, check2, rotateDkim, remove16, customTracking]));
 
 // src/commands/email/receiving.ts
+var destinationLabel = (destination) => {
+  const parts = [
+    destination.endpointId === null ? [] : [`webhook ${destination.endpointId}`],
+    destination.forwardingRules === 0 ? [] : [
+      `${destination.forwardingRules} forwarding rule${destination.forwardingRules === 1 ? "" : "s"}`
+    ],
+    destination.mailboxes === 0 ? [] : [`${destination.mailboxes} mailbox${destination.mailboxes === 1 ? "" : "es"}`]
+  ].flat();
+  return parts.length === 0 ? "none (add a webhook endpoint or a forwarding rule)" : parts.join(", ");
+};
+var mxLabel = (mx) => {
+  switch (mx.state) {
+    case "pointing-here":
+      return `points at ${mx.expected.exchange}`;
+    case "elsewhere":
+      return `routes mail to ${mx.current[0]?.exchange ?? "another provider"}; set it to ${mx.expected.exchange}`;
+    case "missing":
+      return `no MX record; add ${mx.expected.exchange}`;
+    default:
+      return "could not be looked up; try again";
+  }
+};
 var status2 = make29("status", {
   domainId: String10("domain-id").pipe(withDescription4("Sending domain id")),
   json: jsonFlag
-}).pipe(withDescription3("Get a domain's receiving prerequisite status"), withExamples([{ command: "samva email receiving status dom_abc123 --json" }]), withHandler(({ domainId, json }) => gen2(function* () {
+}).pipe(withDescription3("Report each prerequisite for receiving a domain's mail at Samva, in order, with a live MX lookup"), withExamples([{ command: "samva email receiving status dom_abc123 --json" }]), withHandler(({ domainId, json }) => gen2(function* () {
   const client = yield* getClientProvider;
-  const data = yield* getDomainVerification({ id: domainId }).pipe(client.provide, mapError2((error) => toCliApiError("Could not get receiving status", error)));
+  const data = yield* getReceivingStatus({ id: domainId }).pipe(client.provide, mapError2((error) => toCliApiError("Could not get receiving status", error)));
   if (json)
     return yield* printJson(data);
+  const mark = (satisfied) => satisfied ? "done" : "todo";
   yield* printFields([
     ["Domain", data.domain],
-    ["Phase", data.phase]
+    ["1. Sending", `${mark(data.sending.satisfied)} (${data.sending.phase})`],
+    [
+      "2. Destination",
+      `${mark(data.destination.satisfied)} ${destinationLabel(data.destination)}`
+    ],
+    [
+      "3. Receiving",
+      `${mark(data.receiving.satisfied)}${data.receiving.catchAll ? " (catch-all)" : ""}`
+    ],
+    [`4. Inbound MX`, `${mark(data.mx.satisfied)} ${data.receivingHost} ${mxLabel(data.mx)}`],
+    ["Ready", data.ready ? "yes" : "no"]
   ]);
 }).pipe(json ? provideService2(MinimumLogLevel2, "None") : identity)));
 var enable2 = make29("enable", {
   domainId: String10("domain-id").pipe(withDescription4("Sending domain id")),
   domain: String9("domain").pipe(withDescription2("Verified domain name")),
-  address: String9("address").pipe(withDescription2("Recipient address to receive (repeatable)"), atLeast2(1)),
-  catchAll: Boolean6("catch-all").pipe(withDescription2("Also receive unmatched addresses"), withDefault5(false)),
+  address: String9("address").pipe(withDescription2("Exact recipient address to receive (repeatable)"), atLeast2(0)),
+  catchAll: Boolean6("catch-all").pipe(withDescription2("Receive every address on the domain. Needs --endpoint or an active forwarding rule that covers the domain"), withDefault5(false)),
+  endpoint: String9("endpoint").pipe(withDescription2("Webhook endpoint id that receives message.received for a catch-all domain"), optional4),
   dryRun: Boolean6("dry-run").pipe(withDescription2("Print the provider setup request without calling the API"), withDefault5(false)),
   json: jsonFlag
-}).pipe(withDescription3("Enable inbound receiving for a verified domain"), withExamples([
+}).pipe(withDescription3("Enable inbound receiving for a verified domain. Receiving needs somewhere to deliver: exact addresses are accepted, and a catch-all needs a webhook endpoint or a forwarding rule"), withExamples([
+  {
+    command: "samva email receiving enable dom_abc123 --domain example.com --catch-all --endpoint wep_abc123"
+  },
+  {
+    command: "samva email receiving enable dom_abc123 --domain example.com --catch-all"
+  },
   {
     command: "samva email receiving enable dom_abc123 --domain example.com --address replies@example.com --dry-run"
   },
   {
     command: "samva email receiving enable dom_abc123 --domain example.com --address replies@example.com"
   }
-]), withHandler(({ domainId, domain, address, catchAll, dryRun, json }) => gen2(function* () {
-  const request = { domain, catchAll, addresses: [...address] };
+]), withHandler(({ domainId, domain, address, catchAll, endpoint, dryRun, json }) => gen2(function* () {
+  if (address.length === 0 && !catchAll) {
+    return yield* new SamvaCliError({
+      message: "Pass --address for each exact recipient, or --catch-all for the whole domain."
+    });
+  }
+  const endpointId = getOrUndefined(endpoint);
+  if (endpointId !== undefined && !catchAll) {
+    return yield* new SamvaCliError({
+      message: "--endpoint names the catch-all webhook, so it needs --catch-all."
+    });
+  }
+  const request = {
+    domain,
+    catchAll,
+    addresses: [...address],
+    ...endpointId === undefined ? {} : { endpointId }
+  };
   if (dryRun)
-    return yield* json ? printJson({ dryRun: true, action: "email.receiving.enable", domainId, request }) : log(`[dry-run] Would enable receiving for ${domain} (${address.join(", ")}).`);
+    return yield* json ? printJson({ dryRun: true, action: "email.receiving.enable", domainId, request }) : log(`[dry-run] Would enable receiving for ${domain} (${catchAll ? "catch-all" : address.join(", ")}).`);
   const client = yield* getClientProvider;
   const data = yield* enableReceiving({ id: domainId, ...request }).pipe(client.provide, mapError2((error) => toCliApiError("Could not enable receiving", error)));
   if (json)
     return yield* printJson(data);
   yield* printFields([["Recipients", data.recipients.join(", ")]]);
 }).pipe(json ? provideService2(MinimumLogLevel2, "None") : identity)));
-var receivingCommand = make29("receiving").pipe(withDescription3("Configure inbound email receiving"), withExamples([{ command: "samva email receiving status dom_abc123" }]), withSubcommands([status2, enable2]));
+var receivingCommand = make29("receiving").pipe(withDescription3("Move a domain's inbound email to Samva and check what is left to do"), withExamples([{ command: "samva email receiving status dom_abc123" }]), withSubcommands([status2, enable2]));
 
 // src/commands/email/review.ts
 var readStatus = gen2(function* () {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samva/cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Samva CLI — email and platform operations from your terminal",
   "keywords": [
     "cli",
@@ -49,22 +49,22 @@
     "@effect/platform-bun": "4.0.0",
     "@effect/vitest": "4.0.0",
     "@samva/core": "0.0.0",
-    "@samva/mailbox": "0.1.1",
+    "@samva/mailbox": "0.1.2",
     "@samva/markup": "^0.12.0",
     "@samva/vite": "^0.12.0",
     "@types/node": "^26.6.2",
     "better-auth": "1.7.5",
     "effect": "4.0.0",
-    "samva": "0.11.0",
+    "samva": "0.12.0",
     "typescript": "^7.0.2",
     "vite": "~8.3.0",
     "vitest": "^5.0.3"
   },
   "optionalDependencies": {
-    "@samva/cli-darwin-arm64": "0.8.0",
-    "@samva/cli-darwin-x64": "0.8.0",
-    "@samva/cli-linux-arm64": "0.8.0",
-    "@samva/cli-linux-x64": "0.8.0"
+    "@samva/cli-darwin-arm64": "0.9.0",
+    "@samva/cli-darwin-x64": "0.9.0",
+    "@samva/cli-linux-arm64": "0.9.0",
+    "@samva/cli-linux-x64": "0.9.0"
   },
   "engines": {
     "node": ">=18"