@primitivedotdev/cli 0.31.7 → 0.31.8

package/bin/run.js

@@ -7,5 +7,10 @@ import { restartWithProxyEnvIfNeeded } from "../dist/oclif/proxy-auto-detect.js"
 // process.env inside this process is too late for built-in fetch.
 restartWithProxyEnvIfNeeded();
 
+const { writeLoggedOutSignupHintIfNeeded } = await import(
+  "../dist/oclif/root-signup-hint.js"
+);
+writeLoggedOutSignupHintIfNeeded();
+
 const { execute } = await import("@oclif/core");
 await execute({ dir: import.meta.url });

package/dist/oclif/index.js

@@ -655,6 +655,7 @@ var sdk_gen_exports = /* @__PURE__ */ __exportAll({
 	getSendPermissions: () => getSendPermissions,
 	getSentEmail: () => getSentEmail,
 	getStorageStats: () => getStorageStats,
+	getThread: () => getThread,
 	getWebhookSecret: () => getWebhookSecret,
 	listDeliveries: () => listDeliveries,
 	listDomains: () => listDomains,
@@ -1579,6 +1580,33 @@ const getSentEmail = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* Get a conversation thread by id
+*
+* Returns a conversation thread: its metadata plus the inbound
+* and outbound messages that belong to it, interleaved in time
+* order (oldest first). A thread spans both received emails and
+* your sends, so an agent can reconstruct an entire back-and-forth
+* from one call instead of walking reply headers.
+*
+* Each message carries a `direction` (`inbound` | `outbound`) and
+* an `id`; fetch the full message via `/emails/{id}` or
+* `/sent-emails/{id}` accordingly. Bodies are omitted here to keep
+* the thread view lightweight.
+*
+* Discover a thread id from the `thread_id` field on any email or
+* sent-email (list or detail). The message list is capped; compare
+* `message_count` against `messages.length` to detect truncation.
+*
+*/
+const getThread = (options) => (options.client ?? client).get({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/threads/{id}",
+	...options
+});
+/**
 * List functions
 *
 * Returns every active (non-deleted) function in the org, newest
@@ -1929,6 +1957,10 @@ const openapiDocument = {
 			"name": "Sending",
 			"description": "Send outbound emails through the Primitive API"
 		},
+		{
+			"name": "Threads",
+			"description": "Conversation threads spanning received and sent emails"
+		},
 		{
 			"name": "Endpoints",
 			"description": "Manage webhook endpoints that receive email events"
@@ -3424,6 +3456,27 @@ const openapiDocument = {
 				"404": { "$ref": "#/components/responses/NotFound" }
 			}
 		} },
+		"/threads/{id}": {
+			"parameters": [{ "$ref": "#/components/parameters/ResourceId" }],
+			"get": {
+				"operationId": "getThread",
+				"summary": "Get a conversation thread by id",
+				"description": "Returns a conversation thread: its metadata plus the inbound\nand outbound messages that belong to it, interleaved in time\norder (oldest first). A thread spans both received emails and\nyour sends, so an agent can reconstruct an entire back-and-forth\nfrom one call instead of walking reply headers.\n\nEach message carries a `direction` (`inbound` | `outbound`) and\nan `id`; fetch the full message via `/emails/{id}` or\n`/sent-emails/{id}` accordingly. Bodies are omitted here to keep\nthe thread view lightweight.\n\nDiscover a thread id from the `thread_id` field on any email or\nsent-email (list or detail). The message list is capped; compare\n`message_count` against `messages.length` to detect truncation.\n",
+				"tags": ["Threads"],
+				"responses": {
+					"200": {
+						"description": "Thread detail",
+						"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+							"type": "object",
+							"properties": { "data": { "$ref": "#/components/schemas/Thread" } }
+						}] } } }
+					},
+					"400": { "$ref": "#/components/responses/ValidationError" },
+					"401": { "$ref": "#/components/responses/Unauthorized" },
+					"404": { "$ref": "#/components/responses/NotFound" }
+				}
+			}
+		},
 		"/functions": {
 			"get": {
 				"operationId": "listFunctions",
@@ -5291,7 +5344,12 @@ const openapiDocument = {
 					},
 					"raw_size_bytes": { "type": ["integer", "null"] },
 					"webhook_status": { "$ref": "#/components/schemas/EmailWebhookStatus" },
-					"webhook_attempt_count": { "type": "integer" }
+					"webhook_attempt_count": { "type": "integer" },
+					"thread_id": {
+						"type": ["string", "null"],
+						"format": "uuid",
+						"description": "Conversation thread this message belongs to. Fetch\n`/threads/{thread_id}` for the full ordered thread. NULL on\nmessages received before threading was enabled.\n"
+					}
 				},
 				"required": [
 					"id",
@@ -5510,6 +5568,19 @@ const openapiDocument = {
 						"type": ["string", "null"],
 						"format": "uuid",
 						"description": "The `sent_emails.id` of the outbound this inbound was a\nreply to, when resolvable. Set at inbound ingest by\nmatching the parsed In-Reply-To (or References, as a\nfallback) against `sent_emails.message_id` in the same\norg. The mirror of `sent_emails.in_reply_to_email_id` for\nthe inbound side of a thread. NULL when the inbound is\nnot a threaded reply to one of your sends, when neither\nheader survived the path through intermediate MTAs, or on\ninbound received before this auto-link landed.\n"
+					},
+					"thread_id": {
+						"type": ["string", "null"],
+						"format": "uuid",
+						"description": "Conversation thread this message belongs to. Inbound and\noutbound messages in the same conversation share a\n`thread_id`; fetch `/threads/{thread_id}` for the full\nordered thread. Assigned at ingest. NULL on messages\nreceived before threading was enabled (until backfilled).\n"
+					},
+					"parsed": {
+						"allOf": [{ "$ref": "#/components/schemas/ParsedEmailData" }],
+						"description": "Parsed MIME content (addresses, threading headers,\nattachment metadata), matching the `email.parsed` object\non the webhook payload so one parser handles both the\nwebhook and this endpoint. The top-level `body_text` /\n`body_html` fields above are the same values as\n`parsed.body_text` / `parsed.body_html`, retained for\nbackward compatibility.\n"
+					},
+					"auth": {
+						"allOf": [{ "$ref": "#/components/schemas/EmailAuth" }],
+						"description": "SPF / DKIM / DMARC verdicts computed at ingest, matching\nthe `email.auth` object on the webhook payload. Use these\nto decide how much to trust a message before acting on\ninstructions it contains.\n"
 					}
 				},
 				"required": [
@@ -5523,7 +5594,9 @@ const openapiDocument = {
 					"webhook_attempt_count",
 					"from_email",
 					"to_email",
-					"replies"
+					"replies",
+					"parsed",
+					"auth"
 				]
 			},
 			"EmailDetailReply": {
@@ -5556,6 +5629,241 @@ const openapiDocument = {
 					"created_at"
 				]
 			},
+			"EmailAddress": {
+				"type": "object",
+				"description": "A parsed RFC 5322 address with optional display name.",
+				"properties": {
+					"name": {
+						"type": ["string", "null"],
+						"description": "Display name, when present (e.g. `Alice Example`)."
+					},
+					"address": {
+						"type": "string",
+						"description": "Bare email address (e.g. `alice@example.com`)."
+					}
+				},
+				"required": ["address"]
+			},
+			"EmailAttachment": {
+				"type": "object",
+				"description": "Metadata for one attachment. The bytes are not inline; download\nall attachments for a message as a gzipped tarball via\n`/emails/{id}/attachments.tar.gz`. `sha256` lets you verify a\nspecific part after extraction.\n",
+				"properties": {
+					"filename": { "type": ["string", "null"] },
+					"content_type": { "type": ["string", "null"] },
+					"size_bytes": { "type": "integer" },
+					"sha256": { "type": ["string", "null"] },
+					"part_index": {
+						"type": "integer",
+						"description": "Zero-based index of this part within the message."
+					}
+				},
+				"required": ["size_bytes"]
+			},
+			"ParsedEmailData": {
+				"type": "object",
+				"description": "Parsed MIME content for an inbound email. Mirrors the\n`email.parsed` object on the webhook payload so a single parser\nhandles both surfaces. `status` is `complete` when parsing\nsucceeded; on `failed` the body/address/attachment fields are\nabsent and `error` describes why.\n",
+				"properties": {
+					"status": {
+						"type": "string",
+						"enum": ["complete", "failed"]
+					},
+					"body_text": {
+						"type": ["string", "null"],
+						"description": "Plain-text body. Present when `status` is `complete`."
+					},
+					"body_html": {
+						"type": ["string", "null"],
+						"description": "HTML body. Present when `status` is `complete`."
+					},
+					"reply_to": {
+						"type": ["array", "null"],
+						"items": { "$ref": "#/components/schemas/EmailAddress" },
+						"description": "Parsed `Reply-To` header addresses."
+					},
+					"cc": {
+						"type": ["array", "null"],
+						"items": { "$ref": "#/components/schemas/EmailAddress" },
+						"description": "Parsed `Cc` header addresses."
+					},
+					"bcc": {
+						"type": ["array", "null"],
+						"items": { "$ref": "#/components/schemas/EmailAddress" },
+						"description": "Parsed `Bcc` header addresses (rarely present on inbound)."
+					},
+					"to_addresses": {
+						"type": ["array", "null"],
+						"items": { "$ref": "#/components/schemas/EmailAddress" },
+						"description": "Parsed `To` header addresses."
+					},
+					"in_reply_to": {
+						"type": ["array", "null"],
+						"items": { "type": "string" },
+						"description": "Message-IDs from the `In-Reply-To` header."
+					},
+					"references": {
+						"type": ["array", "null"],
+						"items": { "type": "string" },
+						"description": "Message-IDs from the `References` header."
+					},
+					"attachments": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/EmailAttachment" },
+						"description": "Attachment metadata. Empty array when none."
+					},
+					"error": {
+						"type": ["object", "null"],
+						"description": "Present (non-null) only when `status` is `failed`. When\npresent, all three fields are populated, so a consumer can\nbranch on `code` without defensive null checks.\n",
+						"properties": {
+							"code": {
+								"type": "string",
+								"description": "Stable failure code (e.g. `PARSE_FAILED`)."
+							},
+							"message": { "type": "string" },
+							"retryable": { "type": "boolean" }
+						},
+						"required": [
+							"code",
+							"message",
+							"retryable"
+						]
+					}
+				},
+				"required": ["status"]
+			},
+			"DkimSignature": {
+				"type": "object",
+				"description": "One DKIM signature found on the message, with its verdict.",
+				"properties": {
+					"domain": { "type": "string" },
+					"selector": { "type": "string" },
+					"result": {
+						"type": "string",
+						"description": "Verification result (e.g. `pass`, `fail`, `none`)."
+					},
+					"aligned": {
+						"type": "boolean",
+						"description": "Whether the signing domain aligns with the From domain (for DMARC)."
+					},
+					"keyBits": { "type": ["integer", "null"] },
+					"algo": { "type": ["string", "null"] }
+				},
+				"required": [
+					"domain",
+					"selector",
+					"result",
+					"aligned"
+				]
+			},
+			"EmailAuth": {
+				"type": "object",
+				"description": "SPF / DKIM / DMARC verdicts computed at ingest. Mirrors the\n`email.auth` object on the webhook payload. Field names are\ncamelCase to match that payload exactly. For messages received\nbefore auth was recorded, the verdicts default to `none`.\n",
+				"properties": {
+					"spf": {
+						"type": "string",
+						"description": "SPF result (e.g. `pass`, `fail`, `softfail`, `none`)."
+					},
+					"dmarc": {
+						"type": "string",
+						"description": "DMARC result (e.g. `pass`, `fail`, `none`)."
+					},
+					"dmarcPolicy": {
+						"type": ["string", "null"],
+						"description": "Published DMARC policy (`none`, `quarantine`, `reject`)."
+					},
+					"dmarcFromDomain": {
+						"type": ["string", "null"],
+						"description": "The From-header domain DMARC was evaluated against."
+					},
+					"dmarcSpfAligned": { "type": "boolean" },
+					"dmarcDkimAligned": { "type": "boolean" },
+					"dmarcSpfStrict": { "type": ["boolean", "null"] },
+					"dmarcDkimStrict": { "type": ["boolean", "null"] },
+					"dkimSignatures": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/DkimSignature" }
+					}
+				},
+				"required": [
+					"spf",
+					"dmarc",
+					"dmarcSpfAligned",
+					"dmarcDkimAligned",
+					"dkimSignatures"
+				]
+			},
+			"Thread": {
+				"type": "object",
+				"description": "A conversation thread: its metadata plus the inbound and\noutbound messages that belong to it, interleaved oldest-first.\nMembership is the stored `thread_id` on each message. Bodies are\nomitted here to keep the thread view lightweight; fetch\n`/emails/{id}` or `/sent-emails/{id}` for a single message's\nfull content.\n",
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"subject": {
+						"type": ["string", "null"],
+						"description": "Normalized subject of the thread (Re/Fwd prefixes stripped)."
+					},
+					"root_message_id": {
+						"type": ["string", "null"],
+						"description": "Message-ID of the conversation root, when known."
+					},
+					"message_count": {
+						"type": "integer",
+						"description": "Total messages in the thread. `messages` is capped (most\nrecent first, then re-sorted oldest-first), so\n`message_count > messages.length` signals truncation.\n"
+					},
+					"first_message_at": {
+						"type": ["string", "null"],
+						"format": "date-time"
+					},
+					"last_message_at": {
+						"type": ["string", "null"],
+						"format": "date-time"
+					},
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"messages": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/ThreadMessage" }
+					}
+				},
+				"required": [
+					"id",
+					"message_count",
+					"created_at",
+					"messages"
+				]
+			},
+			"ThreadMessage": {
+				"type": "object",
+				"description": "One message in a thread (inbound or outbound).",
+				"properties": {
+					"direction": {
+						"type": "string",
+						"enum": ["inbound", "outbound"],
+						"description": "`inbound` for a received email (`/emails/{id}`), `outbound`\nfor a send (`/sent-emails/{id}`). Use it with `id` to fetch\nfull content from the right endpoint.\n"
+					},
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"message_id": { "type": ["string", "null"] },
+					"from": { "type": ["string", "null"] },
+					"to": { "type": ["string", "null"] },
+					"subject": { "type": ["string", "null"] },
+					"status": {
+						"type": ["string", "null"],
+						"description": "Lifecycle status (an EmailStatus or SentEmailStatus value, per `direction`)."
+					},
+					"timestamp": {
+						"type": ["string", "null"],
+						"format": "date-time",
+						"description": "received_at for inbound, created_at for outbound."
+					}
+				},
+				"required": ["direction", "id"]
+			},
 			"SendMailAttachment": {
 				"type": "object",
 				"additionalProperties": false,
@@ -5772,6 +6080,11 @@ const openapiDocument = {
 						"format": "uuid",
 						"description": "Reference to the inbound `emails.id` that this send\nreplied to, when known. Populated when the caller used\n/emails/{id}/reply or when /send-mail's `in_reply_to`\nmatched a stored inbound message_id in the same org.\n"
 					},
+					"thread_id": {
+						"type": ["string", "null"],
+						"format": "uuid",
+						"description": "Conversation thread this send belongs to. A reply inherits\nthe thread of the inbound it answers; a fresh send starts a\nnew thread. Fetch `/threads/{thread_id}` for the full\nordered thread (inbound + outbound interleaved). NULL on\ngate-denied sends and on sends created before threading was\nenabled.\n"
+					},
 					"queue_id": {
 						"type": ["string", "null"],
 						"description": "Message identifier assigned by Primitive's outbound\nrelay once the agent accepts the message. Null on\nqueued, gate_denied, and agent_failed rows.\n"
@@ -8873,6 +9186,218 @@ const operationManifest = [
 					"type": ["string", "null"],
 					"format": "uuid",
 					"description": "The `sent_emails.id` of the outbound this inbound was a\nreply to, when resolvable. Set at inbound ingest by\nmatching the parsed In-Reply-To (or References, as a\nfallback) against `sent_emails.message_id` in the same\norg. The mirror of `sent_emails.in_reply_to_email_id` for\nthe inbound side of a thread. NULL when the inbound is\nnot a threaded reply to one of your sends, when neither\nheader survived the path through intermediate MTAs, or on\ninbound received before this auto-link landed.\n"
+				},
+				"thread_id": {
+					"type": ["string", "null"],
+					"format": "uuid",
+					"description": "Conversation thread this message belongs to. Inbound and\noutbound messages in the same conversation share a\n`thread_id`; fetch `/threads/{thread_id}` for the full\nordered thread. Assigned at ingest. NULL on messages\nreceived before threading was enabled (until backfilled).\n"
+				},
+				"parsed": {
+					"allOf": [{
+						"type": "object",
+						"description": "Parsed MIME content for an inbound email. Mirrors the\n`email.parsed` object on the webhook payload so a single parser\nhandles both surfaces. `status` is `complete` when parsing\nsucceeded; on `failed` the body/address/attachment fields are\nabsent and `error` describes why.\n",
+						"properties": {
+							"status": {
+								"type": "string",
+								"enum": ["complete", "failed"]
+							},
+							"body_text": {
+								"type": ["string", "null"],
+								"description": "Plain-text body. Present when `status` is `complete`."
+							},
+							"body_html": {
+								"type": ["string", "null"],
+								"description": "HTML body. Present when `status` is `complete`."
+							},
+							"reply_to": {
+								"type": ["array", "null"],
+								"items": {
+									"type": "object",
+									"description": "A parsed RFC 5322 address with optional display name.",
+									"properties": {
+										"name": {
+											"type": ["string", "null"],
+											"description": "Display name, when present (e.g. `Alice Example`)."
+										},
+										"address": {
+											"type": "string",
+											"description": "Bare email address (e.g. `alice@example.com`)."
+										}
+									},
+									"required": ["address"]
+								},
+								"description": "Parsed `Reply-To` header addresses."
+							},
+							"cc": {
+								"type": ["array", "null"],
+								"items": {
+									"type": "object",
+									"description": "A parsed RFC 5322 address with optional display name.",
+									"properties": {
+										"name": {
+											"type": ["string", "null"],
+											"description": "Display name, when present (e.g. `Alice Example`)."
+										},
+										"address": {
+											"type": "string",
+											"description": "Bare email address (e.g. `alice@example.com`)."
+										}
+									},
+									"required": ["address"]
+								},
+								"description": "Parsed `Cc` header addresses."
+							},
+							"bcc": {
+								"type": ["array", "null"],
+								"items": {
+									"type": "object",
+									"description": "A parsed RFC 5322 address with optional display name.",
+									"properties": {
+										"name": {
+											"type": ["string", "null"],
+											"description": "Display name, when present (e.g. `Alice Example`)."
+										},
+										"address": {
+											"type": "string",
+											"description": "Bare email address (e.g. `alice@example.com`)."
+										}
+									},
+									"required": ["address"]
+								},
+								"description": "Parsed `Bcc` header addresses (rarely present on inbound)."
+							},
+							"to_addresses": {
+								"type": ["array", "null"],
+								"items": {
+									"type": "object",
+									"description": "A parsed RFC 5322 address with optional display name.",
+									"properties": {
+										"name": {
+											"type": ["string", "null"],
+											"description": "Display name, when present (e.g. `Alice Example`)."
+										},
+										"address": {
+											"type": "string",
+											"description": "Bare email address (e.g. `alice@example.com`)."
+										}
+									},
+									"required": ["address"]
+								},
+								"description": "Parsed `To` header addresses."
+							},
+							"in_reply_to": {
+								"type": ["array", "null"],
+								"items": { "type": "string" },
+								"description": "Message-IDs from the `In-Reply-To` header."
+							},
+							"references": {
+								"type": ["array", "null"],
+								"items": { "type": "string" },
+								"description": "Message-IDs from the `References` header."
+							},
+							"attachments": {
+								"type": "array",
+								"items": {
+									"type": "object",
+									"description": "Metadata for one attachment. The bytes are not inline; download\nall attachments for a message as a gzipped tarball via\n`/emails/{id}/attachments.tar.gz`. `sha256` lets you verify a\nspecific part after extraction.\n",
+									"properties": {
+										"filename": { "type": ["string", "null"] },
+										"content_type": { "type": ["string", "null"] },
+										"size_bytes": { "type": "integer" },
+										"sha256": { "type": ["string", "null"] },
+										"part_index": {
+											"type": "integer",
+											"description": "Zero-based index of this part within the message."
+										}
+									},
+									"required": ["size_bytes"]
+								},
+								"description": "Attachment metadata. Empty array when none."
+							},
+							"error": {
+								"type": ["object", "null"],
+								"description": "Present (non-null) only when `status` is `failed`. When\npresent, all three fields are populated, so a consumer can\nbranch on `code` without defensive null checks.\n",
+								"properties": {
+									"code": {
+										"type": "string",
+										"description": "Stable failure code (e.g. `PARSE_FAILED`)."
+									},
+									"message": { "type": "string" },
+									"retryable": { "type": "boolean" }
+								},
+								"required": [
+									"code",
+									"message",
+									"retryable"
+								]
+							}
+						},
+						"required": ["status"]
+					}],
+					"description": "Parsed MIME content (addresses, threading headers,\nattachment metadata), matching the `email.parsed` object\non the webhook payload so one parser handles both the\nwebhook and this endpoint. The top-level `body_text` /\n`body_html` fields above are the same values as\n`parsed.body_text` / `parsed.body_html`, retained for\nbackward compatibility.\n"
+				},
+				"auth": {
+					"allOf": [{
+						"type": "object",
+						"description": "SPF / DKIM / DMARC verdicts computed at ingest. Mirrors the\n`email.auth` object on the webhook payload. Field names are\ncamelCase to match that payload exactly. For messages received\nbefore auth was recorded, the verdicts default to `none`.\n",
+						"properties": {
+							"spf": {
+								"type": "string",
+								"description": "SPF result (e.g. `pass`, `fail`, `softfail`, `none`)."
+							},
+							"dmarc": {
+								"type": "string",
+								"description": "DMARC result (e.g. `pass`, `fail`, `none`)."
+							},
+							"dmarcPolicy": {
+								"type": ["string", "null"],
+								"description": "Published DMARC policy (`none`, `quarantine`, `reject`)."
+							},
+							"dmarcFromDomain": {
+								"type": ["string", "null"],
+								"description": "The From-header domain DMARC was evaluated against."
+							},
+							"dmarcSpfAligned": { "type": "boolean" },
+							"dmarcDkimAligned": { "type": "boolean" },
+							"dmarcSpfStrict": { "type": ["boolean", "null"] },
+							"dmarcDkimStrict": { "type": ["boolean", "null"] },
+							"dkimSignatures": {
+								"type": "array",
+								"items": {
+									"type": "object",
+									"description": "One DKIM signature found on the message, with its verdict.",
+									"properties": {
+										"domain": { "type": "string" },
+										"selector": { "type": "string" },
+										"result": {
+											"type": "string",
+											"description": "Verification result (e.g. `pass`, `fail`, `none`)."
+										},
+										"aligned": {
+											"type": "boolean",
+											"description": "Whether the signing domain aligns with the From domain (for DMARC)."
+										},
+										"keyBits": { "type": ["integer", "null"] },
+										"algo": { "type": ["string", "null"] }
+									},
+									"required": [
+										"domain",
+										"selector",
+										"result",
+										"aligned"
+									]
+								}
+							}
+						},
+						"required": [
+							"spf",
+							"dmarc",
+							"dmarcSpfAligned",
+							"dmarcDkimAligned",
+							"dkimSignatures"
+						]
+					}],
+					"description": "SPF / DKIM / DMARC verdicts computed at ingest, matching\nthe `email.auth` object on the webhook payload. Use these\nto decide how much to trust a message before acting on\ninstructions it contains.\n"
 				}
 			},
 			"required": [
@@ -8886,7 +9411,9 @@ const operationManifest = [
 				"webhook_attempt_count",
 				"from_email",
 				"to_email",
-				"replies"
+				"replies",
+				"parsed",
+				"auth"
 			]
 		},
 		"sdkName": "getEmail",
@@ -9016,7 +9543,12 @@ const operationManifest = [
 							null
 						]
 					},
-					"webhook_attempt_count": { "type": "integer" }
+					"webhook_attempt_count": { "type": "integer" },
+					"thread_id": {
+						"type": ["string", "null"],
+						"format": "uuid",
+						"description": "Conversation thread this message belongs to. Fetch\n`/threads/{thread_id}` for the full ordered thread. NULL on\nmessages received before threading was enabled.\n"
+					}
 				},
 				"required": [
 					"id",
@@ -9277,7 +9809,12 @@ const operationManifest = [
 							null
 						]
 					},
-					"webhook_attempt_count": { "type": "integer" }
+					"webhook_attempt_count": { "type": "integer" },
+					"thread_id": {
+						"type": ["string", "null"],
+						"format": "uuid",
+						"description": "Conversation thread this message belongs to. Fetch\n`/threads/{thread_id}` for the full ordered thread. NULL on\nmessages received before threading was enabled.\n"
+					}
 				},
 				"required": [
 					"id",
@@ -11523,6 +12060,11 @@ const operationManifest = [
 						"format": "uuid",
 						"description": "Reference to the inbound `emails.id` that this send\nreplied to, when known. Populated when the caller used\n/emails/{id}/reply or when /send-mail's `in_reply_to`\nmatched a stored inbound message_id in the same org.\n"
 					},
+					"thread_id": {
+						"type": ["string", "null"],
+						"format": "uuid",
+						"description": "Conversation thread this send belongs to. A reply inherits\nthe thread of the inbound it answers; a fresh send starts a\nnew thread. Fetch `/threads/{thread_id}` for the full\nordered thread (inbound + outbound interleaved). NULL on\ngate-denied sends and on sends created before threading was\nenabled.\n"
+					},
 					"queue_id": {
 						"type": ["string", "null"],
 						"description": "Message identifier assigned by Primitive's outbound\nrelay once the agent accepts the message. Null on\nqueued, gate_denied, and agent_failed rows.\n"
@@ -11807,6 +12349,11 @@ const operationManifest = [
 						"format": "uuid",
 						"description": "Reference to the inbound `emails.id` that this send\nreplied to, when known. Populated when the caller used\n/emails/{id}/reply or when /send-mail's `in_reply_to`\nmatched a stored inbound message_id in the same org.\n"
 					},
+					"thread_id": {
+						"type": ["string", "null"],
+						"format": "uuid",
+						"description": "Conversation thread this send belongs to. A reply inherits\nthe thread of the inbound it answers; a fresh send starts a\nnew thread. Fetch `/threads/{thread_id}` for the full\nordered thread (inbound + outbound interleaved). NULL on\ngate-denied sends and on sends created before threading was\nenabled.\n"
+					},
 					"queue_id": {
 						"type": ["string", "null"],
 						"description": "Message identifier assigned by Primitive's outbound\nrelay once the agent accepts the message. Null on\nqueued, gate_denied, and agent_failed rows.\n"
@@ -12259,6 +12806,101 @@ const operationManifest = [
 		"tag": "Sending",
 		"tagCommand": "sending"
 	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": false,
+		"command": "get-thread",
+		"description": "Returns a conversation thread: its metadata plus the inbound\nand outbound messages that belong to it, interleaved in time\norder (oldest first). A thread spans both received emails and\nyour sends, so an agent can reconstruct an entire back-and-forth\nfrom one call instead of walking reply headers.\n\nEach message carries a `direction` (`inbound` | `outbound`) and\nan `id`; fetch the full message via `/emails/{id}` or\n`/sent-emails/{id}` accordingly. Bodies are omitted here to keep\nthe thread view lightweight.\n\nDiscover a thread id from the `thread_id` field on any email or\nsent-email (list or detail). The message list is capped; compare\n`message_count` against `messages.length` to detect truncation.\n",
+		"hasJsonBody": false,
+		"method": "GET",
+		"operationId": "getThread",
+		"path": "/threads/{id}",
+		"pathParams": [{
+			"description": "Resource UUID",
+			"enum": null,
+			"name": "id",
+			"required": true,
+			"type": "string"
+		}],
+		"queryParams": [],
+		"requestSchema": null,
+		"responseSchema": {
+			"type": "object",
+			"description": "A conversation thread: its metadata plus the inbound and\noutbound messages that belong to it, interleaved oldest-first.\nMembership is the stored `thread_id` on each message. Bodies are\nomitted here to keep the thread view lightweight; fetch\n`/emails/{id}` or `/sent-emails/{id}` for a single message's\nfull content.\n",
+			"properties": {
+				"id": {
+					"type": "string",
+					"format": "uuid"
+				},
+				"subject": {
+					"type": ["string", "null"],
+					"description": "Normalized subject of the thread (Re/Fwd prefixes stripped)."
+				},
+				"root_message_id": {
+					"type": ["string", "null"],
+					"description": "Message-ID of the conversation root, when known."
+				},
+				"message_count": {
+					"type": "integer",
+					"description": "Total messages in the thread. `messages` is capped (most\nrecent first, then re-sorted oldest-first), so\n`message_count > messages.length` signals truncation.\n"
+				},
+				"first_message_at": {
+					"type": ["string", "null"],
+					"format": "date-time"
+				},
+				"last_message_at": {
+					"type": ["string", "null"],
+					"format": "date-time"
+				},
+				"created_at": {
+					"type": "string",
+					"format": "date-time"
+				},
+				"messages": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"description": "One message in a thread (inbound or outbound).",
+						"properties": {
+							"direction": {
+								"type": "string",
+								"enum": ["inbound", "outbound"],
+								"description": "`inbound` for a received email (`/emails/{id}`), `outbound`\nfor a send (`/sent-emails/{id}`). Use it with `id` to fetch\nfull content from the right endpoint.\n"
+							},
+							"id": {
+								"type": "string",
+								"format": "uuid"
+							},
+							"message_id": { "type": ["string", "null"] },
+							"from": { "type": ["string", "null"] },
+							"to": { "type": ["string", "null"] },
+							"subject": { "type": ["string", "null"] },
+							"status": {
+								"type": ["string", "null"],
+								"description": "Lifecycle status (an EmailStatus or SentEmailStatus value, per `direction`)."
+							},
+							"timestamp": {
+								"type": ["string", "null"],
+								"format": "date-time",
+								"description": "received_at for inbound, created_at for outbound."
+							}
+						},
+						"required": ["direction", "id"]
+					}
+				}
+			},
+			"required": [
+				"id",
+				"message_count",
+				"created_at",
+				"messages"
+			]
+		},
+		"sdkName": "getThread",
+		"summary": "Get a conversation thread by id",
+		"tag": "Threads",
+		"tagCommand": "threads"
+	},
 	{
 		"binaryResponse": false,
 		"bodyRequired": false,

package/dist/oclif/root-signup-hint.js

@@ -0,0 +1,31 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+//#region src/oclif/root-signup-hint.ts
+const CREDENTIALS_FILE = "credentials.json";
+function activeConfigDir(env, home) {
+	if (env.PRIMITIVE_CONFIG_DIR) return env.PRIMITIVE_CONFIG_DIR;
+	return join(env.XDG_CONFIG_HOME || join(home, ".config"), "primitive");
+}
+function shouldShowLoggedOutSignupHint(options = {}) {
+	if ((options.argv ?? process.argv.slice(2)).length > 0) return false;
+	const env = options.env ?? process.env;
+	if (env.PRIMITIVE_HIDE_SIGNUP_HINT === "1") return false;
+	if (env.PRIMITIVE_API_KEY?.trim()) return false;
+	return !existsSync(join(activeConfigDir(env, options.home ?? homedir()), CREDENTIALS_FILE));
+}
+function loggedOutSignupHint() {
+	return [
+		"New to Primitive?",
+		"  You or your user don't have an account yet?",
+		"  Run `primitive signup <email> --signup-code <invite-code> --accept-terms`",
+		"  to create an account, get your own domain, and get started now.",
+		""
+	].join("\n");
+}
+function writeLoggedOutSignupHintIfNeeded(options = {}) {
+	if (!shouldShowLoggedOutSignupHint(options)) return;
+	(options.write ?? ((message) => process.stdout.write(message)))(loggedOutSignupHint());
+}
+//#endregion
+export { loggedOutSignupHint, shouldShowLoggedOutSignupHint, writeLoggedOutSignupHintIfNeeded };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/cli",
-  "version": "0.31.7",
+  "version": "0.31.8",
   "description": "Official Primitive CLI: deploy Primitive Functions, send and inspect mail, manage endpoints, all from the terminal. Wraps the @primitivedotdev/sdk runtime client with one-shot commands.",
   "type": "module",
   "sideEffects": false,
@@ -25,8 +25,15 @@
     "dirname": "primitive",
     "plugins": [
       "@oclif/plugin-help",
-      "@oclif/plugin-autocomplete"
+      "@oclif/plugin-autocomplete",
+      "@oclif/plugin-warn-if-update-available"
     ],
+    "warn-if-update-available": {
+      "timeoutInDays": 1,
+      "frequency": 1,
+      "frequencyUnit": "days",
+      "message": "Primitive CLI update available from <%= chalk.greenBright(config.version) %> to <%= chalk.greenBright(latest) %>. Run `npm install -g @primitivedotdev/cli@latest` to update."
+    },
     "topics": {
       "cli": {
         "description": "CLI authentication"
@@ -59,6 +66,9 @@
       "sent": {
         "description": "Short aliases for outbound sent-email history: `primitive sent list` and `primitive sent get`."
       },
+      "threads": {
+        "description": "Inspect conversation threads spanning received and sent emails: `primitive threads get --id <thread-id>`."
+      },
       "endpoints": {
         "description": "Manage webhook endpoints that receive email events"
       },
@@ -112,7 +122,8 @@
   "dependencies": {
     "@oclif/core": "^4.10.5",
     "@oclif/plugin-autocomplete": "^3.2.45",
-    "@oclif/plugin-help": "^6.2.44"
+    "@oclif/plugin-help": "^6.2.44",
+    "@oclif/plugin-warn-if-update-available": "^3.1.65"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",