@primitivedotdev/sdk 0.16.0 → 0.18.0

package/dist/api/generated/sdk.gen.js

@@ -31,8 +31,25 @@ export const getStorageStats = (options) => (options?.client ?? client).get({
 /**
  * Get webhook signing secret
  *
- * Returns the webhook signing secret for your account. If no secret
- * exists yet, one is generated automatically on first access.
+ * Returns the webhook signing secret for your account. If no
+ * secret exists yet, one is generated automatically on first
+ * access.
+ *
+ * Signing is account-scoped, not per-endpoint. Every webhook
+ * delivery from any of your registered endpoints is signed
+ * with this single secret. Rotate via
+ * `POST /account/webhook-secret/rotate`.
+ *
+ * **Secret format**: the returned string looks base64-shaped
+ * (e.g. `XNHBBW8VqoBjRfNs1tkZj11jTk...`) but is NOT base64.
+ * Use it AS-IS as a UTF-8 string when computing HMAC over a
+ * delivery body. Base64-decoding before HMAC will silently
+ * produce mismatched signatures.
+ *
+ * See the API-level "Webhook signing" section for the full
+ * wire format (header name, signed string shape, hash algo,
+ * tolerance) including a language-agnostic verification
+ * recipe.
  *
  */
 export const getWebhookSecret = (options) => (options?.client ?? client).get({
@@ -125,12 +142,20 @@ export const verifyDomain = (options) => (options.client ?? client).post({
  * List inbound emails
  *
  * Returns a paginated list of INBOUND emails received at your
- * verified domains. Outbound messages sent via /send-mail are not
- * included; this endpoint is the inbox view, not a unified
- * send/receive history.
+ * verified domains. Outbound messages sent via /send-mail are
+ * not included; this endpoint is the inbox view, not a
+ * unified send/receive history.
+ *
+ * Supports filtering by domain, status, date range, and
+ * free-text search across subject, sender, and recipient
+ * fields.
  *
- * Supports filtering by domain, status, date range, and free-text
- * search across subject, sender, and recipient fields.
+ * For a compact text-table summary of the most recent N
+ * inbounds (no filters, no cursor pagination), the CLI ships
+ * `primitive emails:latest` as a one-line-per-email shortcut.
+ * It's TTY-aware so id columns are full UUIDs when piped, and
+ * a `--json` flag returns the same envelope this endpoint
+ * does. Use whichever fits the call site.
  *
  */
 export const listEmails = (options) => (options?.client ?? client).get({
@@ -288,9 +313,22 @@ export const listEndpoints = (options) => (options?.client ?? client).get({
 /**
  * Create a webhook endpoint
  *
- * Creates a new webhook endpoint. If a deactivated endpoint with the
- * same URL and domain exists, it is reactivated instead.
- * Subject to plan limits on the number of active endpoints.
+ * Creates a new webhook endpoint. If a deactivated endpoint
+ * with the same URL and domain exists, it is reactivated
+ * instead. Subject to plan limits on the number of active
+ * endpoints.
+ *
+ * **Signing is account-scoped, not per-endpoint.** This call
+ * does not return any signing material; every endpoint on the
+ * account uses the same webhook secret, fetched via
+ * `GET /account/webhook-secret`. See the API-level "Webhook
+ * signing" section for the full wire format (header name,
+ * signed string, hash algo, secret format, tolerance) and a
+ * language-agnostic verification recipe.
+ *
+ * After creating the endpoint, fire a test delivery against
+ * it via `POST /endpoints/{id}/test` to confirm your verifier
+ * accepts the signature.
  *
  */
 export const createEndpoint = (options) => (options.client ?? client).post({

package/dist/api/index.d.ts

@@ -1,2 +1,2 @@
-import { $ as AddDomainData, $i as RequestOptions, $n as ListDomainsErrors, $r as SendPermissionAddress, $t as DownloadAttachmentsResponses, A as getSendPermissions, Ai as UpdateEndpointError, An as GetSentEmailData, Ar as ReplayEmailWebhooksError, At as DeleteEndpointError, B as replayDelivery, Bi as UpdateFilterResponses, Bn as GetWebhookSecretData, Br as ResourceId, Bt as DeliverySummary, C as deleteEndpoint, Ci as UpdateDomainData, Cn as GetEmailResponse, Cr as PaginationMeta, Ct as DeleteDomainResponses, D as downloadRawEmail, Di as UpdateDomainResponse, Dn as GetSendPermissionsErrors, Dr as ReplayDeliveryResponse, Dt as DeleteEmailResponse, E as downloadAttachments, Ei as UpdateDomainInput, En as GetSendPermissionsError, Er as ReplayDeliveryErrors, Et as DeleteEmailErrors, F as listDomains, Fi as UpdateFilterData, Fn as GetStorageStatsData, Fr as ReplyToEmailData, Ft as DeleteFilterError, G as testEndpoint, Gi as VerifyDomainResponse, Gn as Limit, Gr as RotateWebhookSecretResponses, Gt as DiscardEmailContentResponse, H as replyToEmail, Hi as VerifyDomainData, Hn as GetWebhookSecretErrors, Hr as RotateWebhookSecretError, Ht as DiscardEmailContentData, I as listEmails, Ii as UpdateFilterError, In as GetStorageStatsError, Ir as ReplyToEmailError, It as DeleteFilterErrors, J as updateEndpoint, Ji as Client, Jn as ListDeliveriesErrors, Jr as SendEmailErrors, Jt as DomainVerifyResult, K as updateAccount, Ki as VerifyDomainResponses, Kn as ListDeliveriesData, Kr as SendEmailData, Kt as DiscardEmailContentResponses, L as listEndpoints, Li as UpdateFilterErrors, Ln as GetStorageStatsErrors, Lr as ReplyToEmailErrors, Lt as DeleteFilterResponse, M as getStorageStats, Mi as UpdateEndpointInput, Mn as GetSentEmailErrors, Mr as ReplayEmailWebhooksResponse, Mt as DeleteEndpointResponse, N as getWebhookSecret, Ni as UpdateEndpointResponse, Nn as GetSentEmailResponse, Nr as ReplayEmailWebhooksResponses, Nt as DeleteEndpointResponses, O as getAccount, Oi as UpdateDomainResponses, On as GetSendPermissionsResponse, Or as ReplayDeliveryResponses, Ot as DeleteEmailResponses, P as listDeliveries, Pi as UpdateEndpointResponses, Pn as GetSentEmailResponses, Pr as ReplayResult, Pt as DeleteFilterData, Q as AccountUpdated, Qi as Options$1, Qn as ListDomainsError, Qr as SendMailResult, Qt as DownloadAttachmentsResponse, R as listFilters, Ri as UpdateFilterInput, Rn as GetStorageStatsResponse, Rr as ReplyToEmailResponse, Rt as DeleteFilterResponses, S as deleteEmail, Si as UpdateAccountResponses, Sn as GetEmailErrors, Sr as ListSentEmailsResponses, St as DeleteDomainResponse, T as discardEmailContent, Ti as UpdateDomainErrors, Tn as GetSendPermissionsData, Tr as ReplayDeliveryError, Tt as DeleteEmailError, U as rotateWebhookSecret, Ui as VerifyDomainError, Un as GetWebhookSecretResponse, Ur as RotateWebhookSecretErrors, Ut as DiscardEmailContentError, V as replayEmailWebhooks, Vi as VerifiedDomain, Vn as GetWebhookSecretError, Vr as RotateWebhookSecretData, Vt as DiscardContentResult, W as sendEmail, Wi as VerifyDomainErrors, Wn as GetWebhookSecretResponses, Wr as RotateWebhookSecretResponse, Wt as DiscardEmailContentErrors, X as verifyDomain, Xi as Config, Xn as ListDeliveriesResponses, Xr as SendEmailResponses, Xt as DownloadAttachmentsError, Y as updateFilter, Yi as ClientOptions$1, Yn as ListDeliveriesResponse, Yr as SendEmailResponse, Yt as DownloadAttachmentsData, Z as Account, Zi as CreateClientConfig, Zn as ListDomainsData, Zr as SendMailInput, Zt as DownloadAttachmentsErrors, _ as Options, _i as UpdateAccountData, _n as GetAccountErrors, _r as ListFiltersResponses, _t as CreateFilterResponses, a as PrimitiveApiError, ai as SentEmailDetail, an as EmailDetail, ar as ListEmailsResponse, at as ClientOptions, b as createFilter, bi as UpdateAccountInput, bn as GetEmailData, br as ListSentEmailsErrors, bt as DeleteDomainError, c as PrimitiveClientOptions, ci as StorageStats, cn as EmailSummary, cr as ListEndpointsError, ct as CreateEndpointErrors, d as SendResult, di as TestEndpointError, dn as ErrorResponse, dr as ListEndpointsResponses, dt as CreateEndpointResponses, ea as RequestResult, ei as SendPermissionAnyRecipient, en as DownloadRawEmailData, er as ListDomainsResponse, et as AddDomainError, f as SendThreadInput, fi as TestEndpointErrors, fn as Filter, fr as ListEnvelope, ft as CreateFilterData, g as operations, gi as UnverifiedDomain, gn as GetAccountError, gr as ListFiltersResponse, gt as CreateFilterResponse, h as createPrimitiveClient, hi as TestResult, hn as GetAccountData, hr as ListFiltersErrors, ht as CreateFilterInput, i as PrimitiveApiClientOptions, ii as SendPermissionsMeta, in as DownloadRawEmailResponses, ir as ListEmailsErrors, it as AddDomainResponses, j as getSentEmail, ji as UpdateEndpointErrors, jn as GetSentEmailError, jr as ReplayEmailWebhooksErrors, jt as DeleteEndpointErrors, k as getEmail, ki as UpdateEndpointData, kn as GetSendPermissionsResponses, kr as ReplayEmailWebhooksData, kt as DeleteEndpointData, l as ReplyInput, li as SuccessEnvelope, ln as EmailWebhookStatus, lr as ListEndpointsErrors, lt as CreateEndpointInput, m as createPrimitiveApiClient, mi as TestEndpointResponses, mn as GateFix, mr as ListFiltersError, mt as CreateFilterErrors, n as ForwardInput, na as Auth, ni as SendPermissionRule, nn as DownloadRawEmailErrors, nr as ListEmailsData, nt as AddDomainInput, o as PrimitiveApiErrorDetails, oi as SentEmailStatus, on as EmailDetailReply, or as ListEmailsResponses, ot as CreateEndpointData, p as client, pi as TestEndpointResponse, pn as GateDenial, pr as ListFiltersData, pt as CreateFilterError, q as updateDomain, qi as WebhookSecret, qn as ListDeliveriesError, qr as SendEmailError, qt as Domain, r as PrimitiveApiClient, ri as SendPermissionYourDomain, rn as DownloadRawEmailResponse, rr as ListEmailsError, rt as AddDomainResponse, s as PrimitiveClient, si as SentEmailSummary, sn as EmailStatus, sr as ListEndpointsData, st as CreateEndpointError, t as DEFAULT_BASE_URL, ta as ResponseStyle, ti as SendPermissionManagedZone, tn as DownloadRawEmailError, tr as ListDomainsResponses, tt as AddDomainErrors, u as SendInput, ui as TestEndpointData, un as Endpoint, ur as ListEndpointsResponse, ut as CreateEndpointResponse, v as addDomain, vi as UpdateAccountError, vn as GetAccountResponse, vr as ListSentEmailsData, vt as Cursor, w as deleteFilter, wi as UpdateDomainError, wn as GetEmailResponses, wr as ReplayDeliveryData, wt as DeleteEmailData, x as deleteDomain, xi as UpdateAccountResponse, xn as GetEmailError, xr as ListSentEmailsResponse, xt as DeleteDomainErrors, y as createEndpoint, yi as UpdateAccountErrors, yn as GetAccountResponses, yr as ListSentEmailsError, yt as DeleteDomainData, z as listSentEmails, zi as UpdateFilterResponse, zn as GetStorageStatsResponses, zr as ReplyToEmailResponses, zt as DeliveryStatus } from "../index-SK_HbwVN.js";
+import { $ as AddDomainData, $i as RequestOptions, $n as ListDomainsErrors, $r as SendPermissionAddress, $t as DownloadAttachmentsResponses, A as getSendPermissions, Ai as UpdateEndpointError, An as GetSentEmailData, Ar as ReplayEmailWebhooksError, At as DeleteEndpointError, B as replayDelivery, Bi as UpdateFilterResponses, Bn as GetWebhookSecretData, Br as ResourceId, Bt as DeliverySummary, C as deleteEndpoint, Ci as UpdateDomainData, Cn as GetEmailResponse, Cr as PaginationMeta, Ct as DeleteDomainResponses, D as downloadRawEmail, Di as UpdateDomainResponse, Dn as GetSendPermissionsErrors, Dr as ReplayDeliveryResponse, Dt as DeleteEmailResponse, E as downloadAttachments, Ei as UpdateDomainInput, En as GetSendPermissionsError, Er as ReplayDeliveryErrors, Et as DeleteEmailErrors, F as listDomains, Fi as UpdateFilterData, Fn as GetStorageStatsData, Fr as ReplyToEmailData, Ft as DeleteFilterError, G as testEndpoint, Gi as VerifyDomainResponse, Gn as Limit, Gr as RotateWebhookSecretResponses, Gt as DiscardEmailContentResponse, H as replyToEmail, Hi as VerifyDomainData, Hn as GetWebhookSecretErrors, Hr as RotateWebhookSecretError, Ht as DiscardEmailContentData, I as listEmails, Ii as UpdateFilterError, In as GetStorageStatsError, Ir as ReplyToEmailError, It as DeleteFilterErrors, J as updateEndpoint, Ji as Client, Jn as ListDeliveriesErrors, Jr as SendEmailErrors, Jt as DomainVerifyResult, K as updateAccount, Ki as VerifyDomainResponses, Kn as ListDeliveriesData, Kr as SendEmailData, Kt as DiscardEmailContentResponses, L as listEndpoints, Li as UpdateFilterErrors, Ln as GetStorageStatsErrors, Lr as ReplyToEmailErrors, Lt as DeleteFilterResponse, M as getStorageStats, Mi as UpdateEndpointInput, Mn as GetSentEmailErrors, Mr as ReplayEmailWebhooksResponse, Mt as DeleteEndpointResponse, N as getWebhookSecret, Ni as UpdateEndpointResponse, Nn as GetSentEmailResponse, Nr as ReplayEmailWebhooksResponses, Nt as DeleteEndpointResponses, O as getAccount, Oi as UpdateDomainResponses, On as GetSendPermissionsResponse, Or as ReplayDeliveryResponses, Ot as DeleteEmailResponses, P as listDeliveries, Pi as UpdateEndpointResponses, Pn as GetSentEmailResponses, Pr as ReplayResult, Pt as DeleteFilterData, Q as AccountUpdated, Qi as Options$1, Qn as ListDomainsError, Qr as SendMailResult, Qt as DownloadAttachmentsResponse, R as listFilters, Ri as UpdateFilterInput, Rn as GetStorageStatsResponse, Rr as ReplyToEmailResponse, Rt as DeleteFilterResponses, S as deleteEmail, Si as UpdateAccountResponses, Sn as GetEmailErrors, Sr as ListSentEmailsResponses, St as DeleteDomainResponse, T as discardEmailContent, Ti as UpdateDomainErrors, Tn as GetSendPermissionsData, Tr as ReplayDeliveryError, Tt as DeleteEmailError, U as rotateWebhookSecret, Ui as VerifyDomainError, Un as GetWebhookSecretResponse, Ur as RotateWebhookSecretErrors, Ut as DiscardEmailContentError, V as replayEmailWebhooks, Vi as VerifiedDomain, Vn as GetWebhookSecretError, Vr as RotateWebhookSecretData, Vt as DiscardContentResult, W as sendEmail, Wi as VerifyDomainErrors, Wn as GetWebhookSecretResponses, Wr as RotateWebhookSecretResponse, Wt as DiscardEmailContentErrors, X as verifyDomain, Xi as Config, Xn as ListDeliveriesResponses, Xr as SendEmailResponses, Xt as DownloadAttachmentsError, Y as updateFilter, Yi as ClientOptions$1, Yn as ListDeliveriesResponse, Yr as SendEmailResponse, Yt as DownloadAttachmentsData, Z as Account, Zi as CreateClientConfig, Zn as ListDomainsData, Zr as SendMailInput, Zt as DownloadAttachmentsErrors, _ as Options, _i as UpdateAccountData, _n as GetAccountErrors, _r as ListFiltersResponses, _t as CreateFilterResponses, a as PrimitiveApiError, ai as SentEmailDetail, an as EmailDetail, ar as ListEmailsResponse, at as ClientOptions, b as createFilter, bi as UpdateAccountInput, bn as GetEmailData, br as ListSentEmailsErrors, bt as DeleteDomainError, c as PrimitiveClientOptions, ci as StorageStats, cn as EmailSummary, cr as ListEndpointsError, ct as CreateEndpointErrors, d as SendResult, di as TestEndpointError, dn as ErrorResponse, dr as ListEndpointsResponses, dt as CreateEndpointResponses, ea as RequestResult, ei as SendPermissionAnyRecipient, en as DownloadRawEmailData, er as ListDomainsResponse, et as AddDomainError, f as SendThreadInput, fi as TestEndpointErrors, fn as Filter, fr as ListEnvelope, ft as CreateFilterData, g as operations, gi as UnverifiedDomain, gn as GetAccountError, gr as ListFiltersResponse, gt as CreateFilterResponse, h as createPrimitiveClient, hi as TestResult, hn as GetAccountData, hr as ListFiltersErrors, ht as CreateFilterInput, i as PrimitiveApiClientOptions, ii as SendPermissionsMeta, in as DownloadRawEmailResponses, ir as ListEmailsErrors, it as AddDomainResponses, j as getSentEmail, ji as UpdateEndpointErrors, jn as GetSentEmailError, jr as ReplayEmailWebhooksErrors, jt as DeleteEndpointErrors, k as getEmail, ki as UpdateEndpointData, kn as GetSendPermissionsResponses, kr as ReplayEmailWebhooksData, kt as DeleteEndpointData, l as ReplyInput, li as SuccessEnvelope, ln as EmailWebhookStatus, lr as ListEndpointsErrors, lt as CreateEndpointInput, m as createPrimitiveApiClient, mi as TestEndpointResponses, mn as GateFix, mr as ListFiltersError, mt as CreateFilterErrors, n as ForwardInput, na as Auth, ni as SendPermissionRule, nn as DownloadRawEmailErrors, nr as ListEmailsData, nt as AddDomainInput, o as PrimitiveApiErrorDetails, oi as SentEmailStatus, on as EmailDetailReply, or as ListEmailsResponses, ot as CreateEndpointData, p as client, pi as TestEndpointResponse, pn as GateDenial, pr as ListFiltersData, pt as CreateFilterError, q as updateDomain, qi as WebhookSecret, qn as ListDeliveriesError, qr as SendEmailError, qt as Domain, r as PrimitiveApiClient, ri as SendPermissionYourDomain, rn as DownloadRawEmailResponse, rr as ListEmailsError, rt as AddDomainResponse, s as PrimitiveClient, si as SentEmailSummary, sn as EmailStatus, sr as ListEndpointsData, st as CreateEndpointError, t as DEFAULT_BASE_URL, ta as ResponseStyle, ti as SendPermissionManagedZone, tn as DownloadRawEmailError, tr as ListDomainsResponses, tt as AddDomainErrors, u as SendInput, ui as TestEndpointData, un as Endpoint, ur as ListEndpointsResponse, ut as CreateEndpointResponse, v as addDomain, vi as UpdateAccountError, vn as GetAccountResponse, vr as ListSentEmailsData, vt as Cursor, w as deleteFilter, wi as UpdateDomainError, wn as GetEmailResponses, wr as ReplayDeliveryData, wt as DeleteEmailData, x as deleteDomain, xi as UpdateAccountResponse, xn as GetEmailError, xr as ListSentEmailsResponse, xt as DeleteDomainErrors, y as createEndpoint, yi as UpdateAccountErrors, yn as GetAccountResponses, yr as ListSentEmailsError, yt as DeleteDomainData, z as listSentEmails, zi as UpdateFilterResponse, zn as GetStorageStatsResponses, zr as ReplyToEmailResponses, zt as DeliveryStatus } from "../index-CHWqMBs6.js";
 export { Account, AccountUpdated, AddDomainData, AddDomainError, AddDomainErrors, AddDomainInput, AddDomainResponse, AddDomainResponses, Auth, ClientOptions, CreateClientConfig, CreateEndpointData, CreateEndpointError, CreateEndpointErrors, CreateEndpointInput, CreateEndpointResponse, CreateEndpointResponses, CreateFilterData, CreateFilterError, CreateFilterErrors, CreateFilterInput, CreateFilterResponse, CreateFilterResponses, Cursor, DEFAULT_BASE_URL, DeleteDomainData, DeleteDomainError, DeleteDomainErrors, DeleteDomainResponse, DeleteDomainResponses, DeleteEmailData, DeleteEmailError, DeleteEmailErrors, DeleteEmailResponse, DeleteEmailResponses, DeleteEndpointData, DeleteEndpointError, DeleteEndpointErrors, DeleteEndpointResponse, DeleteEndpointResponses, DeleteFilterData, DeleteFilterError, DeleteFilterErrors, DeleteFilterResponse, DeleteFilterResponses, DeliveryStatus, DeliverySummary, DiscardContentResult, DiscardEmailContentData, DiscardEmailContentError, DiscardEmailContentErrors, DiscardEmailContentResponse, DiscardEmailContentResponses, Domain, DomainVerifyResult, DownloadAttachmentsData, DownloadAttachmentsError, DownloadAttachmentsErrors, DownloadAttachmentsResponse, DownloadAttachmentsResponses, DownloadRawEmailData, DownloadRawEmailError, DownloadRawEmailErrors, DownloadRawEmailResponse, DownloadRawEmailResponses, EmailDetail, EmailDetailReply, EmailStatus, EmailSummary, EmailWebhookStatus, Endpoint, ErrorResponse, Filter, ForwardInput, GateDenial, GateFix, GetAccountData, GetAccountError, GetAccountErrors, GetAccountResponse, GetAccountResponses, GetEmailData, GetEmailError, GetEmailErrors, GetEmailResponse, GetEmailResponses, GetSendPermissionsData, GetSendPermissionsError, GetSendPermissionsErrors, GetSendPermissionsResponse, GetSendPermissionsResponses, GetSentEmailData, GetSentEmailError, GetSentEmailErrors, GetSentEmailResponse, GetSentEmailResponses, GetStorageStatsData, GetStorageStatsError, GetStorageStatsErrors, GetStorageStatsResponse, GetStorageStatsResponses, GetWebhookSecretData, GetWebhookSecretError, GetWebhookSecretErrors, GetWebhookSecretResponse, GetWebhookSecretResponses, Limit, ListDeliveriesData, ListDeliveriesError, ListDeliveriesErrors, ListDeliveriesResponse, ListDeliveriesResponses, ListDomainsData, ListDomainsError, ListDomainsErrors, ListDomainsResponse, ListDomainsResponses, ListEmailsData, ListEmailsError, ListEmailsErrors, ListEmailsResponse, ListEmailsResponses, ListEndpointsData, ListEndpointsError, ListEndpointsErrors, ListEndpointsResponse, ListEndpointsResponses, ListEnvelope, ListFiltersData, ListFiltersError, ListFiltersErrors, ListFiltersResponse, ListFiltersResponses, ListSentEmailsData, ListSentEmailsError, ListSentEmailsErrors, ListSentEmailsResponse, ListSentEmailsResponses, Options, PaginationMeta, PrimitiveApiClient, PrimitiveApiClientOptions, PrimitiveApiError, PrimitiveApiErrorDetails, PrimitiveClient, PrimitiveClientOptions, Client as PrimitiveGeneratedApiClient, ClientOptions$1 as PrimitiveGeneratedApiClientOptions, Config as PrimitiveGeneratedApiConfig, Options$1 as PrimitiveGeneratedApiOptions, RequestOptions as PrimitiveGeneratedApiRequestOptions, RequestResult as PrimitiveGeneratedApiRequestResult, ReplayDeliveryData, ReplayDeliveryError, ReplayDeliveryErrors, ReplayDeliveryResponse, ReplayDeliveryResponses, ReplayEmailWebhooksData, ReplayEmailWebhooksError, ReplayEmailWebhooksErrors, ReplayEmailWebhooksResponse, ReplayEmailWebhooksResponses, ReplayResult, ReplyInput, ReplyToEmailData, ReplyToEmailError, ReplyToEmailErrors, ReplyToEmailResponse, ReplyToEmailResponses, ResourceId, ResponseStyle, RotateWebhookSecretData, RotateWebhookSecretError, RotateWebhookSecretErrors, RotateWebhookSecretResponse, RotateWebhookSecretResponses, SendEmailData, SendEmailError, SendEmailErrors, SendEmailResponse, SendEmailResponses, SendInput, SendMailInput, SendMailResult, SendPermissionAddress, SendPermissionAnyRecipient, SendPermissionManagedZone, SendPermissionRule, SendPermissionYourDomain, SendPermissionsMeta, SendResult, SendThreadInput, SentEmailDetail, SentEmailStatus, SentEmailSummary, StorageStats, SuccessEnvelope, TestEndpointData, TestEndpointError, TestEndpointErrors, TestEndpointResponse, TestEndpointResponses, TestResult, UnverifiedDomain, UpdateAccountData, UpdateAccountError, UpdateAccountErrors, UpdateAccountInput, UpdateAccountResponse, UpdateAccountResponses, UpdateDomainData, UpdateDomainError, UpdateDomainErrors, UpdateDomainInput, UpdateDomainResponse, UpdateDomainResponses, UpdateEndpointData, UpdateEndpointError, UpdateEndpointErrors, UpdateEndpointInput, UpdateEndpointResponse, UpdateEndpointResponses, UpdateFilterData, UpdateFilterError, UpdateFilterErrors, UpdateFilterInput, UpdateFilterResponse, UpdateFilterResponses, VerifiedDomain, VerifyDomainData, VerifyDomainError, VerifyDomainErrors, VerifyDomainResponse, VerifyDomainResponses, WebhookSecret, addDomain, client, createEndpoint, createFilter, createPrimitiveApiClient, createPrimitiveClient, deleteDomain, deleteEmail, deleteEndpoint, deleteFilter, discardEmailContent, downloadAttachments, downloadRawEmail, getAccount, getEmail, getSendPermissions, getSentEmail, getStorageStats, getWebhookSecret, listDeliveries, listDomains, listEmails, listEndpoints, listFilters, listSentEmails, operations, replayDelivery, replayEmailWebhooks, replyToEmail, rotateWebhookSecret, sendEmail, testEndpoint, updateAccount, updateDomain, updateEndpoint, updateFilter, verifyDomain };

package/dist/{api-CTf0cUsi.js → api-DrAZhxS-.js}

@@ -687,8 +687,25 @@ const getStorageStats = (options) => (options?.client ?? client$1).get({
 /**
 * Get webhook signing secret
 *
-* Returns the webhook signing secret for your account. If no secret
-* exists yet, one is generated automatically on first access.
+* Returns the webhook signing secret for your account. If no
+* secret exists yet, one is generated automatically on first
+* access.
+*
+* Signing is account-scoped, not per-endpoint. Every webhook
+* delivery from any of your registered endpoints is signed
+* with this single secret. Rotate via
+* `POST /account/webhook-secret/rotate`.
+*
+* **Secret format**: the returned string looks base64-shaped
+* (e.g. `XNHBBW8VqoBjRfNs1tkZj11jTk...`) but is NOT base64.
+* Use it AS-IS as a UTF-8 string when computing HMAC over a
+* delivery body. Base64-decoding before HMAC will silently
+* produce mismatched signatures.
+*
+* See the API-level "Webhook signing" section for the full
+* wire format (header name, signed string shape, hash algo,
+* tolerance) including a language-agnostic verification
+* recipe.
 *
 */
 const getWebhookSecret = (options) => (options?.client ?? client$1).get({
@@ -802,12 +819,20 @@ const verifyDomain = (options) => (options.client ?? client$1).post({
 * List inbound emails
 *
 * Returns a paginated list of INBOUND emails received at your
-* verified domains. Outbound messages sent via /send-mail are not
-* included; this endpoint is the inbox view, not a unified
-* send/receive history.
+* verified domains. Outbound messages sent via /send-mail are
+* not included; this endpoint is the inbox view, not a
+* unified send/receive history.
 *
-* Supports filtering by domain, status, date range, and free-text
-* search across subject, sender, and recipient fields.
+* Supports filtering by domain, status, date range, and
+* free-text search across subject, sender, and recipient
+* fields.
+*
+* For a compact text-table summary of the most recent N
+* inbounds (no filters, no cursor pagination), the CLI ships
+* `primitive emails:latest` as a one-line-per-email shortcut.
+* It's TTY-aware so id columns are full UUIDs when piped, and
+* a `--json` flag returns the same envelope this endpoint
+* does. Use whichever fits the call site.
 *
 */
 const listEmails = (options) => (options?.client ?? client$1).get({
@@ -992,9 +1017,22 @@ const listEndpoints = (options) => (options?.client ?? client$1).get({
 /**
 * Create a webhook endpoint
 *
-* Creates a new webhook endpoint. If a deactivated endpoint with the
-* same URL and domain exists, it is reactivated instead.
-* Subject to plan limits on the number of active endpoints.
+* Creates a new webhook endpoint. If a deactivated endpoint
+* with the same URL and domain exists, it is reactivated
+* instead. Subject to plan limits on the number of active
+* endpoints.
+*
+* **Signing is account-scoped, not per-endpoint.** This call
+* does not return any signing material; every endpoint on the
+* account uses the same webhook secret, fetched via
+* `GET /account/webhook-secret`. See the API-level "Webhook
+* signing" section for the full wire format (header name,
+* signed string, hash algo, secret format, tolerance) and a
+* language-agnostic verification recipe.
+*
+* After creating the endpoint, fire a test delivery against
+* it via `POST /endpoints/{id}/test` to confirm your verifier
+* accepts the signature.
 *
 */
 const createEndpoint = (options) => (options.client ?? client$1).post({

package/dist/{index-SK_HbwVN.d.ts → index-CHWqMBs6.d.ts}

@@ -2711,8 +2711,25 @@ declare const getStorageStats: <ThrowOnError extends boolean = false>(options?:
 /**
  * Get webhook signing secret
  *
- * Returns the webhook signing secret for your account. If no secret
- * exists yet, one is generated automatically on first access.
+ * Returns the webhook signing secret for your account. If no
+ * secret exists yet, one is generated automatically on first
+ * access.
+ *
+ * Signing is account-scoped, not per-endpoint. Every webhook
+ * delivery from any of your registered endpoints is signed
+ * with this single secret. Rotate via
+ * `POST /account/webhook-secret/rotate`.
+ *
+ * **Secret format**: the returned string looks base64-shaped
+ * (e.g. `XNHBBW8VqoBjRfNs1tkZj11jTk...`) but is NOT base64.
+ * Use it AS-IS as a UTF-8 string when computing HMAC over a
+ * delivery body. Base64-decoding before HMAC will silently
+ * produce mismatched signatures.
+ *
+ * See the API-level "Webhook signing" section for the full
+ * wire format (header name, signed string shape, hash algo,
+ * tolerance) including a language-agnostic verification
+ * recipe.
  *
  */
 declare const getWebhookSecret: <ThrowOnError extends boolean = false>(options?: Options<GetWebhookSecretData, ThrowOnError>) => RequestResult<GetWebhookSecretResponses, GetWebhookSecretErrors, ThrowOnError, "fields">;
@@ -2769,12 +2786,20 @@ declare const verifyDomain: <ThrowOnError extends boolean = false>(options: Opti
  * List inbound emails
  *
  * Returns a paginated list of INBOUND emails received at your
- * verified domains. Outbound messages sent via /send-mail are not
- * included; this endpoint is the inbox view, not a unified
- * send/receive history.
+ * verified domains. Outbound messages sent via /send-mail are
+ * not included; this endpoint is the inbox view, not a
+ * unified send/receive history.
  *
- * Supports filtering by domain, status, date range, and free-text
- * search across subject, sender, and recipient fields.
+ * Supports filtering by domain, status, date range, and
+ * free-text search across subject, sender, and recipient
+ * fields.
+ *
+ * For a compact text-table summary of the most recent N
+ * inbounds (no filters, no cursor pagination), the CLI ships
+ * `primitive emails:latest` as a one-line-per-email shortcut.
+ * It's TTY-aware so id columns are full UUIDs when piped, and
+ * a `--json` flag returns the same envelope this endpoint
+ * does. Use whichever fits the call site.
  *
  */
 declare const listEmails: <ThrowOnError extends boolean = false>(options?: Options<ListEmailsData, ThrowOnError>) => RequestResult<ListEmailsResponses, ListEmailsErrors, ThrowOnError, "fields">;
@@ -2884,9 +2909,22 @@ declare const listEndpoints: <ThrowOnError extends boolean = false>(options?: Op
 /**
  * Create a webhook endpoint
  *
- * Creates a new webhook endpoint. If a deactivated endpoint with the
- * same URL and domain exists, it is reactivated instead.
- * Subject to plan limits on the number of active endpoints.
+ * Creates a new webhook endpoint. If a deactivated endpoint
+ * with the same URL and domain exists, it is reactivated
+ * instead. Subject to plan limits on the number of active
+ * endpoints.
+ *
+ * **Signing is account-scoped, not per-endpoint.** This call
+ * does not return any signing material; every endpoint on the
+ * account uses the same webhook secret, fetched via
+ * `GET /account/webhook-secret`. See the API-level "Webhook
+ * signing" section for the full wire format (header name,
+ * signed string, hash algo, secret format, tolerance) and a
+ * language-agnostic verification recipe.
+ *
+ * After creating the endpoint, fire a test delivery against
+ * it via `POST /endpoints/{id}/test` to confirm your verifier
+ * accepts the signature.
  *
  */
 declare const createEndpoint: <ThrowOnError extends boolean = false>(options: Options<CreateEndpointData, ThrowOnError>) => RequestResult<CreateEndpointResponses, CreateEndpointErrors, ThrowOnError, "fields">;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { A as UnknownEvent, C as ParsedDataFailed, D as RawContentDownloadOnly, E as RawContent, M as WebhookAttachment, N as WebhookEvent, O as RawContentInline, S as ParsedDataComplete, T as ParsedStatus, _ as ForwardResultInline, a as DmarcPolicy, b as KnownWebhookEvent, c as EmailAnalysis, d as EventType, f as ForwardAnalysis, g as ForwardResultAttachmentSkipped, h as ForwardResultAttachmentAnalyzed, i as DkimSignature, j as ValidateEmailAuthResult, k as SpfResult, l as EmailAuth, m as ForwardResult, n as AuthVerdict, o as DmarcResult, p as ForwardOriginalSender, r as DkimResult, s as EmailAddress, t as AuthConfidence, u as EmailReceivedEvent, v as ForwardVerdict, w as ParsedError, x as ParsedData, y as ForwardVerification } from "./types-9vXGZjPd.js";
 import { a as buildReplySubject, c as parseHeaderAddress, i as buildForwardSubject, n as ReceivedEmailAddress, o as formatAddress, r as ReceivedEmailThread, s as normalizeReceivedEmail, t as ReceivedEmail } from "./received-email-DNjpq_Wt.js";
-import { a as PrimitiveApiError, c as PrimitiveClientOptions, d as SendResult, f as SendThreadInput, h as createPrimitiveClient, l as ReplyInput, n as ForwardInput, p as client, s as PrimitiveClient, u as SendInput } from "./index-SK_HbwVN.js";
+import { a as PrimitiveApiError, c as PrimitiveClientOptions, d as SendResult, f as SendThreadInput, h as createPrimitiveClient, l as ReplyInput, n as ForwardInput, p as client, s as PrimitiveClient, u as SendInput } from "./index-CHWqMBs6.js";
 import { A as VerifyOptions, B as PAYLOAD_ERRORS, C as signStandardWebhooksPayload, D as PRIMITIVE_CONFIRMED_HEADER, E as LEGACY_SIGNATURE_HEADER, F as VerifyDownloadTokenResult, G as VERIFICATION_ERRORS, H as RAW_EMAIL_ERRORS, I as generateDownloadToken, J as WebhookPayloadErrorCode, K as WebhookErrorCode, L as verifyDownloadToken, M as verifyWebhookSignature, N as GenerateDownloadTokenOptions, O as PRIMITIVE_SIGNATURE_HEADER, P as VerifyDownloadTokenOptions, Q as WebhookVerificationErrorCode, R as safeValidateEmailReceivedEvent, S as StandardWebhooksVerifyOptions, T as LEGACY_CONFIRMED_HEADER, U as RawEmailDecodeError, V as PrimitiveWebhookError, W as RawEmailDecodeErrorCode, X as WebhookValidationErrorCode, Y as WebhookValidationError, Z as WebhookVerificationError, _ as emailReceivedEventJsonSchema, a as confirmedHeaders, b as STANDARD_WEBHOOK_TIMESTAMP_HEADER, c as handleWebhook, d as isRawIncluded, f as parseWebhookEvent, g as validateEmailAuth, h as WEBHOOK_VERSION, i as WebhookHeaders, j as signWebhookPayload, k as SignResult, l as isDownloadExpired, m as verifyRawEmailDownload, n as HandleWebhookOptions, o as decodeRawEmail, p as receive, q as WebhookPayloadError, r as ReceiveRequestOptions, s as getDownloadTimeRemaining, t as DecodeRawEmailOptions, u as isEmailReceivedEvent, v as STANDARD_WEBHOOK_ID_HEADER, w as verifyStandardWebhooksSignature, x as StandardWebhooksSignResult, y as STANDARD_WEBHOOK_SIGNATURE_HEADER, z as validateEmailReceivedEvent } from "./index-CbEivn3S.js";
 
 //#region src/index.d.ts

package/dist/index.js

@@ -1,5 +1,5 @@
 import { a as parseHeaderAddress, i as normalizeReceivedEmail, n as buildReplySubject, r as formatAddress, t as buildForwardSubject } from "./received-email-D6tKtWwW.js";
-import { a as client, i as PrimitiveClient, r as PrimitiveApiError, s as createPrimitiveClient } from "./api-CTf0cUsi.js";
+import { a as client, i as PrimitiveClient, r as PrimitiveApiError, s as createPrimitiveClient } from "./api-DrAZhxS-.js";
 import { A as PRIMITIVE_CONFIRMED_HEADER, B as RAW_EMAIL_ERRORS, C as STANDARD_WEBHOOK_ID_HEADER, D as verifyStandardWebhooksSignature, E as signStandardWebhooksPayload, F as verifyDownloadToken, G as WebhookVerificationError, H as VERIFICATION_ERRORS, I as safeValidateEmailReceivedEvent, L as validateEmailReceivedEvent, M as signWebhookPayload, N as verifyWebhookSignature, O as LEGACY_CONFIRMED_HEADER, P as generateDownloadToken, R as PAYLOAD_ERRORS, S as emailReceivedEventJsonSchema, T as STANDARD_WEBHOOK_TIMESTAMP_HEADER, U as WebhookPayloadError, V as RawEmailDecodeError, W as WebhookValidationError, _ as DmarcResult, a as isDownloadExpired, b as ParsedStatus, c as parseWebhookEvent, d as WEBHOOK_VERSION, f as validateEmailAuth, g as DmarcPolicy, h as DkimResult, i as handleWebhook, j as PRIMITIVE_SIGNATURE_HEADER, k as LEGACY_SIGNATURE_HEADER, l as receive, m as AuthVerdict, n as decodeRawEmail, o as isEmailReceivedEvent, p as AuthConfidence, r as getDownloadTimeRemaining, s as isRawIncluded, t as confirmedHeaders, u as verifyRawEmailDownload, v as EventType, w as STANDARD_WEBHOOK_SIGNATURE_HEADER, x as SpfResult, y as ForwardVerdict, z as PrimitiveWebhookError } from "./webhook-zkN4wUTs.js";
 //#region src/index.ts
 const primitive = {

package/dist/oclif/api-command.js

@@ -302,6 +302,45 @@ export function writeErrorWithHints(payload) {
         process.stderr.write(`${ERROR_CODE_HINTS[code]}\n`);
     }
 }
+// Format milliseconds as a short human-readable wall-clock duration.
+// Sub-second uses 2 decimal places (e.g. `0.18s`); seconds use 2
+// decimals up to 60s (`12.34s`); minute-plus uses `Mm SS.SSs`.
+// Display-only; the underlying ms value is what the caller computed.
+export function formatElapsed(ms) {
+    const seconds = ms / 1000;
+    if (seconds < 60)
+        return `${seconds.toFixed(2)}s`;
+    const minutes = Math.floor(seconds / 60);
+    const rem = seconds - minutes * 60;
+    return `${minutes}m ${rem.toFixed(2)}s`;
+}
+// Run `fn` and, when `enabled` is true, write a one-line wall-clock
+// timing report to stderr after it completes. Stderr keeps the row
+// data on stdout grep/jq-friendly. The timer captures the full
+// duration of the function (HTTPS round trip, server-side gate +
+// agent + delivery, polling, etc.), not just the API call's
+// server-side processing.
+//
+// Used by every `--time` callsite across the CLI: generated
+// operation commands and hand-coded shortcuts (send, whoami,
+// emails:latest, describe). Pulled out as a helper so timing is
+// uniform across commands and a single render-format change
+// propagates everywhere.
+export async function runWithTiming(enabled, fn) {
+    if (!enabled)
+        return fn();
+    const start = Date.now();
+    try {
+        return await fn();
+    }
+    finally {
+        process.stderr.write(`[time: ${formatElapsed(Date.now() - start)}]\n`);
+    }
+}
+// Shared `--time` flag definition every CLI command spreads into its
+// own static flags. Lives here so the flag's description and short
+// name stay consistent across the hand-coded and generated commands.
+export const TIME_FLAG_DESCRIPTION = "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.";
 // Reserved flag names the body-field expander must never overwrite.
 // `--raw-body` and `--body-file` are the JSON escape hatches.
 // `--api-key`, `--base-url`, `--output` are infra. Path and query
@@ -363,6 +402,9 @@ function buildFlags(operation) {
             description: "API base URL (defaults to PRIMITIVE_API_URL or production)",
             env: "PRIMITIVE_API_URL",
         }),
+        time: Flags.boolean({
+            description: TIME_FLAG_DESCRIPTION,
+        }),
     };
     for (const parameter of [...operation.pathParams, ...operation.queryParams]) {
         flags[flagName(parameter.name)] = flagForParameter(parameter);
@@ -460,101 +502,103 @@ export function createOperationCommand(operation) {
         async run() {
             const { flags } = await this.parse(OperationCommand);
             const parsedFlags = flags;
-            const apiClient = new PrimitiveApiClient({
-                apiKey: typeof parsedFlags["api-key"] === "string"
-                    ? parsedFlags["api-key"]
-                    : undefined,
-                baseUrl: typeof parsedFlags["base-url"] === "string"
-                    ? parsedFlags["base-url"]
-                    : undefined,
-            });
-            // Two body sources, merged: explicit JSON via --body /
-            // --body-file (the base) plus per-field flags (the
-            // overrides). Per-field flag values take precedence on key
-            // conflicts so a caller can pass a base payload via --body
-            // and override one field on the command line.
-            let body;
-            if (operation.hasJsonBody) {
-                const explicit = readJsonBody(parsedFlags);
-                const overrides = collectBodyFieldFlags(parsedFlags, bodyFieldFlagToProperty);
-                if (Object.keys(overrides).length > 0) {
-                    if (explicit === undefined) {
-                        body = overrides;
-                    }
-                    else if (explicit !== null &&
-                        typeof explicit === "object" &&
-                        !Array.isArray(explicit)) {
-                        body = { ...explicit, ...overrides };
+            await runWithTiming(parsedFlags.time === true, async () => {
+                const apiClient = new PrimitiveApiClient({
+                    apiKey: typeof parsedFlags["api-key"] === "string"
+                        ? parsedFlags["api-key"]
+                        : undefined,
+                    baseUrl: typeof parsedFlags["base-url"] === "string"
+                        ? parsedFlags["base-url"]
+                        : undefined,
+                });
+                // Two body sources, merged: explicit JSON via --body /
+                // --body-file (the base) plus per-field flags (the
+                // overrides). Per-field flag values take precedence on key
+                // conflicts so a caller can pass a base payload via --body
+                // and override one field on the command line.
+                let body;
+                if (operation.hasJsonBody) {
+                    const explicit = readJsonBody(parsedFlags);
+                    const overrides = collectBodyFieldFlags(parsedFlags, bodyFieldFlagToProperty);
+                    if (Object.keys(overrides).length > 0) {
+                        if (explicit === undefined) {
+                            body = overrides;
+                        }
+                        else if (explicit !== null &&
+                            typeof explicit === "object" &&
+                            !Array.isArray(explicit)) {
+                            body = { ...explicit, ...overrides };
+                        }
+                        else {
+                            // Caller passed --raw-body as null, an array, or a
+                            // primitive AND also passed per-field flags. We can't
+                            // merge per-field overrides into a non-object body
+                            // shape, and silently dropping either source would
+                            // leave the caller's actual intent unclear. Refuse
+                            // loudly so the next attempt is unambiguous.
+                            const explicitKind = explicit === null
+                                ? "null"
+                                : Array.isArray(explicit)
+                                    ? "array"
+                                    : typeof explicit;
+                            const overrideFlags = Object.keys(overrides)
+                                .map((p) => `--${flagName(p)}`)
+                                .join(", ");
+                            throw new Errors.CLIError(`--raw-body must be a JSON object when also passing per-field flags (got ${explicitKind}); supplied per-field flags: ${overrideFlags}. Either drop --raw-body and rely on the per-field flags, or move every field into the JSON --raw-body and drop the flags.`);
+                        }
                     }
                     else {
-                        // Caller passed --raw-body as null, an array, or a
-                        // primitive AND also passed per-field flags. We can't
-                        // merge per-field overrides into a non-object body
-                        // shape, and silently dropping either source would
-                        // leave the caller's actual intent unclear. Refuse
-                        // loudly so the next attempt is unambiguous.
-                        const explicitKind = explicit === null
-                            ? "null"
-                            : Array.isArray(explicit)
-                                ? "array"
-                                : typeof explicit;
-                        const overrideFlags = Object.keys(overrides)
-                            .map((p) => `--${flagName(p)}`)
-                            .join(", ");
-                        throw new Errors.CLIError(`--raw-body must be a JSON object when also passing per-field flags (got ${explicitKind}); supplied per-field flags: ${overrideFlags}. Either drop --raw-body and rely on the per-field flags, or move every field into the JSON --raw-body and drop the flags.`);
+                        body = explicit;
                     }
                 }
-                else {
-                    body = explicit;
+                if (operation.bodyRequired && body === undefined) {
+                    throw new Errors.CLIError(`Operation ${operation.operationId} requires a body. Pass each field as a --flag (see --help) or supply JSON via --raw-body / --body-file.`);
                 }
-            }
-            if (operation.bodyRequired && body === undefined) {
-                throw new Errors.CLIError(`Operation ${operation.operationId} requires a body. Pass each field as a --flag (see --help) or supply JSON via --raw-body / --body-file.`);
-            }
-            const operationFn = operations[operation.sdkName];
-            const result = await operationFn({
-                body,
-                client: apiClient.client,
-                parseAs: operation.binaryResponse ? "blob" : "auto",
-                path: collectValues(operation.pathParams, parsedFlags),
-                query: collectValues(operation.queryParams, parsedFlags),
-                responseStyle: "fields",
-            });
-            if (result.error) {
-                writeErrorWithHints(extractErrorPayload(result.error));
-                process.exitCode = 1;
-                return;
-            }
-            if (operation.binaryResponse) {
-                const blob = result.data;
-                const bytes = Buffer.from(await blob.arrayBuffer());
-                const output = parsedFlags.output;
-                if (typeof output === "string") {
-                    writeFileSync(output, bytes);
+                const operationFn = operations[operation.sdkName];
+                const result = await operationFn({
+                    body,
+                    client: apiClient.client,
+                    parseAs: operation.binaryResponse ? "blob" : "auto",
+                    path: collectValues(operation.pathParams, parsedFlags),
+                    query: collectValues(operation.queryParams, parsedFlags),
+                    responseStyle: "fields",
+                });
+                if (result.error) {
+                    writeErrorWithHints(extractErrorPayload(result.error));
+                    process.exitCode = 1;
                     return;
                 }
-                process.stdout.write(bytes);
-                return;
-            }
-            const envelope = result.data;
-            const cursor = envelope?.meta?.cursor;
-            if (cursor) {
-                process.stderr.write(`next cursor: ${cursor}\n`);
-            }
-            // Empty-result hint. When a list-style operation returns
-            // an empty array, emit an operation-specific note to
-            // stderr so a naive caller can distinguish "nothing here"
-            // from "something isn't set up." Stdout still gets the
-            // raw `[]` so machine-readable output is unchanged. The
-            // AGX walkthrough flagged this: `list-deliveries` returning
-            // `[]` left the agent unsure whether they had an empty
-            // delivery log or no endpoints configured at all.
-            if (Array.isArray(envelope?.data) && envelope.data.length === 0) {
-                const hint = EMPTY_RESULT_HINTS[operation.sdkName];
-                if (hint)
-                    process.stderr.write(`${hint}\n`);
-            }
-            this.log(JSON.stringify(envelope?.data ?? null, null, 2));
+                if (operation.binaryResponse) {
+                    const blob = result.data;
+                    const bytes = Buffer.from(await blob.arrayBuffer());
+                    const output = parsedFlags.output;
+                    if (typeof output === "string") {
+                        writeFileSync(output, bytes);
+                        return;
+                    }
+                    process.stdout.write(bytes);
+                    return;
+                }
+                const envelope = result.data;
+                const cursor = envelope?.meta?.cursor;
+                if (cursor) {
+                    process.stderr.write(`next cursor: ${cursor}\n`);
+                }
+                // Empty-result hint. When a list-style operation returns
+                // an empty array, emit an operation-specific note to
+                // stderr so a naive caller can distinguish "nothing here"
+                // from "something isn't set up." Stdout still gets the
+                // raw `[]` so machine-readable output is unchanged. The
+                // AGX walkthrough flagged this: `list-deliveries` returning
+                // `[]` left the agent unsure whether they had an empty
+                // delivery log or no endpoints configured at all.
+                if (Array.isArray(envelope?.data) && envelope.data.length === 0) {
+                    const hint = EMPTY_RESULT_HINTS[operation.sdkName];
+                    if (hint)
+                        process.stderr.write(`${hint}\n`);
+                }
+                this.log(JSON.stringify(envelope?.data ?? null, null, 2));
+            });
         }
     }
     return OperationCommand;
@@ -566,9 +610,9 @@ export function createOperationCommand(operation) {
 // `sdkName` for the operation. Operations without an entry fall
 // back to no hint (silent empty array, same as before).
 const EMPTY_RESULT_HINTS = {
-    listDeliveries: "(no results) Often means no webhook endpoints are configured to receive deliveries. Run `primitive endpoints:list-endpoints` to check.",
+    listDeliveries: "(no results) No webhook deliveries logged yet. If you have an endpoint configured but expected to see test fires here: test deliveries from `primitive endpoints:test-endpoint` are NOT logged in this list, they're synchronous and visible only in the test-endpoint command's response. Real deliveries are logged when an inbound `email.received` event fans out to your endpoints. If you have no endpoints, run `primitive endpoints:list-endpoints` to check.",
     listEndpoints: "(no results) No webhook endpoints configured. Add one with `primitive endpoints:create-endpoint --url <your-url>`.",
-    listEmails: "(no results) No inbound emails received yet on this account.",
+    listEmails: "(no results) No inbound emails received yet on this account. Send one to a verified domain to populate this list. For a compact view, prefer `primitive emails:latest`.",
     listDomains: "(no results) No domains on this account. Add one with `primitive domains:add-domain --domain <yourdomain.example>`.",
     listFilters: "(no results) No filter rules configured.",
 };