@primitivedotdev/sdk 0.27.1 → 0.29.0

package/dist/{operations.generated-T3exFpgJ.js → operations.generated-B3sb0jWW.js}

@@ -10,7 +10,7 @@ const openapiDocument = {
 	"info": {
 		"title": "Primitive API",
 		"version": "1.0.0",
-		"description": "The Primitive API lets you manage domains, emails, webhook endpoints,\nfilters, and account settings programmatically.\n\n## Authentication\n\nAll endpoints require a Bearer token in the `Authorization` header:\n\n```\nAuthorization: Bearer prim_<your_api_key>\n```\n\nAPI keys are org-scoped. Create and manage them in your dashboard\nunder Settings > API Keys.\n\n## Rate Limiting\n\nThe API enforces a sliding window rate limit of **120 requests per\n60 seconds** per organization. When exceeded, the API returns `429`\nwith a `Retry-After` header indicating how many seconds to wait.\n\n## Pagination\n\nList endpoints use cursor-based pagination. Responses include a\n`meta` object with `total`, `limit`, and `cursor` fields. Pass the\n`cursor` value as a query parameter to fetch the next page. When\n`cursor` is `null`, there are no more results.\n\n## Response Format\n\nAll responses use a consistent envelope:\n\n```json\n{\n  \"success\": true,\n  \"data\": { ... },\n  \"meta\": { \"total\": 42, \"limit\": 50, \"cursor\": \"...\" }\n}\n```\n\nErrors follow the same pattern:\n\n```json\n{\n  \"success\": false,\n  \"error\": { \"code\": \"not_found\", \"message\": \"Email not found\" }\n}\n```\n\n## Webhook signing\n\nOutbound webhook deliveries (configured via the `endpoints` API)\nare signed so receivers can verify they came from Primitive and\nhave not been tampered with in transit. The signing scheme is\ndeliberately simple so it can be reimplemented in any language\nin a few lines. The Node SDK's `verifyWebhookSignature` helper\nis the reference implementation; the wire details below let you\nwrite a verifier in Python, Go, Ruby, etc. without reading our\nsource.\n\n**Header**: `Primitive-Signature: t=<unix-seconds>,v1=<hex>`\n\nA legacy `MyMX-Signature` header is also sent on every delivery\nwith the same value, retained for back-compatibility with\nintegrations written before the rename. New code should read\n`Primitive-Signature`.\n\n**Signed string**: `${timestamp}.${rawBody}` where `timestamp`\nis the Unix-seconds integer from the `t=` parameter and\n`rawBody` is the exact bytes of the HTTP request body BEFORE\nany JSON decoding. Verify against the raw body, not a\nre-serialized parse, or you will silently mismatch on\ninsignificant whitespace.\n\n**Signature**: HMAC-SHA256 of the signed string, hex-encoded\n(lowercase). Use the account's webhook secret as the HMAC key,\nas a UTF-8 byte sequence.\n\n**Secret**: returned by `GET /account/webhook-secret`. The\nstring looks base64-shaped (e.g. `XNHBBW8VqoBjRfNs1tkZj11jTk...`)\nbut is NOT base64; use it AS-IS as a UTF-8 string for the HMAC\nkey. Base64-decoding before HMAC will silently produce\nmismatched signatures.\n\n**Tolerance**: by convention, reject deliveries whose `t=`\ntimestamp is more than 5 minutes off your wall-clock to defend\nagainst replay attacks. The Node SDK's helper enforces this by\ndefault.\n\n**Verification recipe** (any language):\n\n```\n1. Read the raw HTTP body (do not parse).\n2. Read `Primitive-Signature: t=<ts>,v1=<sig>`.\n3. Reject if abs(now - ts) > 300 seconds.\n4. expected = HMAC_SHA256_hex(secret_utf8, f\"{ts}.{rawBody}\")\n5. Constant-time compare expected to sig. Reject if not equal.\n```\n\nFor Node, use `verifyWebhookSignature` from\n`@primitivedotdev/sdk/webhook` (or the higher-level\n`handleWebhook` helper if you want a one-liner). For other\nlanguages, the recipe above is everything you need.\n\nTest deliveries: `POST /endpoints/{id}/test` triggers a fake\ndelivery to your endpoint URL, signed with your real account\nsecret, so you can confirm verification end-to-end without\nneeding real inbound mail. The test response carries the exact\n`signature` header value sent on the wire so you can compare\nstrings directly.\n",
+		"description": "The Primitive API lets you manage domains, emails, webhook endpoints,\nfilters, and account settings programmatically.\n\n## Authentication\n\nMost endpoints require a Bearer token in the `Authorization` header:\n\n```\nAuthorization: Bearer prim_<your_api_key>\n```\n\nAPI keys are org-scoped. Create and manage them in your dashboard\nunder Settings > API Keys. CLI login and signup endpoints explicitly\ndeclare `security: []`; they do not require an API key because they\nare used to mint one.\n\n## Rate Limiting\n\nThe API enforces a sliding window rate limit of **120 requests per\n60 seconds** per organization. When exceeded, the API returns `429`\nwith a `Retry-After` header indicating how many seconds to wait.\n\n## Pagination\n\nList endpoints use cursor-based pagination. Responses include a\n`meta` object with `total`, `limit`, and `cursor` fields. Pass the\n`cursor` value as a query parameter to fetch the next page. When\n`cursor` is `null`, there are no more results.\n\n## Response Format\n\nAll responses use a consistent envelope:\n\n```json\n{\n  \"success\": true,\n  \"data\": { ... },\n  \"meta\": { \"total\": 42, \"limit\": 50, \"cursor\": \"...\" }\n}\n```\n\nErrors follow the same pattern:\n\n```json\n{\n  \"success\": false,\n  \"error\": { \"code\": \"not_found\", \"message\": \"Email not found\" }\n}\n```\n\n## Webhook signing\n\nOutbound webhook deliveries (configured via the `endpoints` API)\nare signed so receivers can verify they came from Primitive and\nhave not been tampered with in transit. The signing scheme is\ndeliberately simple so it can be reimplemented in any language\nin a few lines. The Node SDK's `verifyWebhookSignature` helper\nis the reference implementation; the wire details below let you\nwrite a verifier in Python, Go, Ruby, etc. without reading our\nsource.\n\n**Header**: `Primitive-Signature: t=<unix-seconds>,v1=<hex>`\n\nA legacy `MyMX-Signature` header is also sent on every delivery\nwith the same value, retained for back-compatibility with\nintegrations written before the rename. New code should read\n`Primitive-Signature`.\n\n**Signed string**: `${timestamp}.${rawBody}` where `timestamp`\nis the Unix-seconds integer from the `t=` parameter and\n`rawBody` is the exact bytes of the HTTP request body BEFORE\nany JSON decoding. Verify against the raw body, not a\nre-serialized parse, or you will silently mismatch on\ninsignificant whitespace.\n\n**Signature**: HMAC-SHA256 of the signed string, hex-encoded\n(lowercase). Use the account's webhook secret as the HMAC key,\nas a UTF-8 byte sequence.\n\n**Secret**: returned by `GET /account/webhook-secret`. The\nstring looks base64-shaped (e.g. `XNHBBW8VqoBjRfNs1tkZj11jTk...`)\nbut is NOT base64; use it AS-IS as a UTF-8 string for the HMAC\nkey. Base64-decoding before HMAC will silently produce\nmismatched signatures.\n\n**Tolerance**: by convention, reject deliveries whose `t=`\ntimestamp is more than 5 minutes off your wall-clock to defend\nagainst replay attacks. The Node SDK's helper enforces this by\ndefault.\n\n**Verification recipe** (any language):\n\n```\n1. Read the raw HTTP body (do not parse).\n2. Read `Primitive-Signature: t=<ts>,v1=<sig>`.\n3. Reject if abs(now - ts) > 300 seconds.\n4. expected = HMAC_SHA256_hex(secret_utf8, f\"{ts}.{rawBody}\")\n5. Constant-time compare expected to sig. Reject if not equal.\n```\n\nFor Node, use `verifyWebhookSignature` from\n`@primitivedotdev/sdk/webhook` (or the higher-level\n`handleWebhook` helper if you want a one-liner). For other\nlanguages, the recipe above is everything you need.\n\nTest deliveries: `POST /endpoints/{id}/test` triggers a fake\ndelivery to your endpoint URL, signed with your real account\nsecret, so you can confirm verification end-to-end without\nneeding real inbound mail. The test response carries the exact\n`signature` header value sent on the wire so you can compare\nstrings directly.\n",
 		"contact": {
 			"name": "Primitive",
 			"url": "https://primitive.dev"
@@ -182,6 +182,97 @@ const openapiDocument = {
 				}
 			}
 		} },
+		"/cli/signup/start": { "post": {
+			"operationId": "startCliSignup",
+			"summary": "Start CLI account signup",
+			"description": "Starts a terminal-native CLI signup. The API validates the signup code,\ncreates a pending signup session, sends an email verification code, and\nreturns an opaque signup token used by the resend and verify steps. This\nendpoint does not require an API key.\n",
+			"tags": ["CLI"],
+			"security": [],
+			"requestBody": {
+				"required": true,
+				"content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartCliSignupInput" } } }
+			},
+			"responses": {
+				"201": {
+					"description": "CLI signup session created and verification email sent",
+					"headers": { "Cache-Control": {
+						"schema": { "type": "string" },
+						"description": "Always `no-store`"
+					} },
+					"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+						"type": "object",
+						"properties": { "data": { "$ref": "#/components/schemas/CliSignupStartResult" } }
+					}] } } }
+				},
+				"400": { "$ref": "#/components/responses/ValidationError" },
+				"429": { "$ref": "#/components/responses/RateLimited" }
+			}
+		} },
+		"/cli/signup/resend": { "post": {
+			"operationId": "resendCliSignupVerification",
+			"summary": "Resend CLI signup verification code",
+			"description": "Sends a new email verification code for a pending CLI signup session.\nThis endpoint does not require an API key.\n",
+			"tags": ["CLI"],
+			"security": [],
+			"requestBody": {
+				"required": true,
+				"content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendCliSignupVerificationInput" } } }
+			},
+			"responses": {
+				"200": {
+					"description": "Verification email resent",
+					"headers": { "Cache-Control": {
+						"schema": { "type": "string" },
+						"description": "Always `no-store`"
+					} },
+					"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+						"type": "object",
+						"properties": { "data": { "$ref": "#/components/schemas/CliSignupResendResult" } }
+					}] } } }
+				},
+				"400": {
+					"description": "Invalid token or expired token",
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
+				},
+				"429": {
+					"description": "Global rate limit exceeded or resend requested too quickly",
+					"headers": { "Retry-After": {
+						"schema": { "type": "integer" },
+						"description": "Seconds to wait before retrying"
+					} },
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
+				}
+			}
+		} },
+		"/cli/signup/verify": { "post": {
+			"operationId": "verifyCliSignup",
+			"summary": "Verify CLI signup and create API key",
+			"description": "Verifies the email code for a CLI signup session, creates the account,\nredeems the reserved signup code, mints an org-scoped CLI API key, and\nreturns the raw key exactly once. This endpoint does not require an API key.\n",
+			"tags": ["CLI"],
+			"security": [],
+			"requestBody": {
+				"required": true,
+				"content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyCliSignupInput" } } }
+			},
+			"responses": {
+				"200": {
+					"description": "CLI signup verified and API key created",
+					"headers": { "Cache-Control": {
+						"schema": { "type": "string" },
+						"description": "Always `no-store`"
+					} },
+					"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+						"type": "object",
+						"properties": { "data": { "$ref": "#/components/schemas/CliSignupVerifyResult" } }
+					}] } } }
+				},
+				"400": {
+					"description": "Invalid request, invalid verification code, expired token, invalid signup code, rejected password, or account creation failure",
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
+				},
+				"429": { "$ref": "#/components/responses/RateLimited" }
+			}
+		} },
 		"/cli/logout": { "post": {
 			"operationId": "cliLogout",
 			"summary": "Revoke the current CLI API key",
@@ -1322,7 +1413,7 @@ const openapiDocument = {
 			"post": {
 				"operationId": "createFunction",
 				"summary": "Deploy a function",
-				"description": "Creates and deploys a new function. The handler must be a single\nESM module whose default export is an object with an async\n`fetch(request, env)` method (Workers-style). The gateway\nHMAC-verifies the POST against the org's webhook secret before\ninvoking the handler; the request body parses to an\n`email.received` event (see `EmailReceivedEvent` and the\nWebhook payload section for the full schema). Code is bundled\nbefore being uploaded; ship a single self-contained file rather\nthan relying on external imports.\n\n**Code limits.** `code` is capped at 1 MiB UTF-8. `sourceMap`\n(optional) is capped at 5 MiB UTF-8 and is stored only on the\nedge runtime side; it is not persisted in Primitive's database.\n\n**Auto-wiring.** On successful deploy, Primitive automatically\ncreates a webhook endpoint that delivers inbound mail to the\nfunction. There is nothing to configure on the Endpoints API\nfor this to work; the gateway URL returned here is for\nreference only and is not directly callable from outside.\n\n**Secrets.** New functions ship with the managed secrets\n(`PRIMITIVE_WEBHOOK_SECRET`, `PRIMITIVE_API_KEY`) already\nbound. Add user-set secrets via\n`POST /functions/{id}/secrets`; secret writes only land in the\nrunning handler on the next redeploy.\n",
+				"description": "Creates and deploys a new function. The handler must be a single\nESM module whose default export is an object with an async\n`fetch(request, env)` method (Workers-style). The gateway\nHMAC-verifies the POST against the org's webhook secret before\ninvoking the handler; the request body parses to an\n`email.received` event (see `EmailReceivedEvent` and the\nWebhook payload section for the full schema). Code is bundled\nbefore being uploaded; ship a single self-contained file rather\nthan relying on external imports.\n\n**Code limits.** `code` is capped at 1 MiB UTF-8. `sourceMap`\n(optional) is capped at 5 MiB UTF-8, stored with each deployment\nattempt, and sent to the runtime so stack traces can resolve to\noriginal source files.\n\n**Auto-wiring.** On successful deploy, Primitive automatically\ncreates a webhook endpoint that delivers inbound mail to the\nfunction. There is nothing to configure on the Endpoints API\nfor this to work; the gateway URL returned here is for\nreference only and is not directly callable from outside.\n\n**Secrets.** New functions ship with the managed secrets\n(`PRIMITIVE_WEBHOOK_SECRET`, `PRIMITIVE_API_KEY`) already\nbound. Add user-set secrets via\n`POST /functions/{id}/secrets`; secret writes only land in the\nrunning handler on the next redeploy.\n",
 				"tags": ["Functions"],
 				"requestBody": {
 					"required": true,
@@ -1336,13 +1427,18 @@ const openapiDocument = {
 							"properties": { "data": { "$ref": "#/components/schemas/CreateFunctionResult" } }
 						}] } } }
 					},
-					"400": { "$ref": "#/components/responses/ValidationError" },
+					"400": {
+						"description": "Invalid request parameters or customer-correctable deploy rejection",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
+					},
 					"401": { "$ref": "#/components/responses/Unauthorized" },
 					"409": {
 						"description": "A function with this name already exists in the org",
 						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
 					},
-					"502": { "$ref": "#/components/responses/BadGateway" }
+					"424": { "$ref": "#/components/responses/DeployFailed" },
+					"429": { "$ref": "#/components/responses/DeployFailed" },
+					"503": { "$ref": "#/components/responses/DeployFailed" }
 				}
 			}
 		},
@@ -1368,7 +1464,7 @@ const openapiDocument = {
 			"put": {
 				"operationId": "updateFunction",
 				"summary": "Update and redeploy a function",
-				"description": "Replaces the function's source code with the body's `code` and\ntriggers a redeploy. Same size limits as `POST /functions`.\nUse this verb to push secret writes into the running handler:\npassing the same `code` re-runs the deploy and refreshes the\nbinding set with the latest values from the secrets table.\n\nOn a 502 deploy failure, the previously-deployed code stays\nlive; the runtime never serves a half-built bundle. The\n`deploy_error` field on the returned record carries the error\nthat came back from the runtime so you can surface it to users\nwithout polling.\n",
+				"description": "Replaces the function's source code with the body's `code` and\ntriggers a redeploy. Same size limits as `POST /functions`.\nUse this verb to push secret writes into the running handler:\npassing the same `code` re-runs the deploy and refreshes the\nbinding set with the latest values from the secrets table.\n\nOn deploy failure, the previously-deployed code stays live; the\nruntime never serves a half-built bundle. The response uses\n`error.code` `deploy_failed`, and the function's `deploy_error`\nfield carries the latest deploy error for dashboard/API reads.\n",
 				"tags": ["Functions"],
 				"requestBody": {
 					"required": true,
@@ -1382,10 +1478,15 @@ const openapiDocument = {
 							"properties": { "data": { "$ref": "#/components/schemas/FunctionDetail" } }
 						}] } } }
 					},
-					"400": { "$ref": "#/components/responses/ValidationError" },
+					"400": {
+						"description": "Invalid request parameters or customer-correctable deploy rejection",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
+					},
 					"401": { "$ref": "#/components/responses/Unauthorized" },
 					"404": { "$ref": "#/components/responses/NotFound" },
-					"502": { "$ref": "#/components/responses/BadGateway" }
+					"424": { "$ref": "#/components/responses/DeployFailed" },
+					"429": { "$ref": "#/components/responses/DeployFailed" },
+					"503": { "$ref": "#/components/responses/DeployFailed" }
 				}
 			},
 			"delete": {
@@ -1445,6 +1546,37 @@ const openapiDocument = {
 				}
 			}
 		},
+		"/functions/{id}/test-runs/{run_id}/trace": {
+			"parameters": [{ "$ref": "#/components/parameters/ResourceId" }, {
+				"name": "run_id",
+				"in": "path",
+				"required": true,
+				"description": "Function test run id returned by POST /functions/{id}/test.",
+				"schema": {
+					"type": "string",
+					"format": "uuid"
+				}
+			}],
+			"get": {
+				"operationId": "getFunctionTestRunTrace",
+				"summary": "Get a function test run trace",
+				"description": "Returns the current end-to-end trace for a function test run.\nThe trace is intentionally partial while the test is still in\nflight: callers can poll this endpoint and watch it fill in\nfrom send -> inbound -> webhook deliveries -> outbound\nrequests, logs, and replies.\n",
+				"tags": ["Functions"],
+				"responses": {
+					"200": {
+						"description": "Function test run trace",
+						"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+							"type": "object",
+							"properties": { "data": { "$ref": "#/components/schemas/FunctionTestRunTrace" } }
+						}] } } }
+					},
+					"400": { "$ref": "#/components/responses/ValidationError" },
+					"401": { "$ref": "#/components/responses/Unauthorized" },
+					"403": { "$ref": "#/components/responses/Forbidden" },
+					"404": { "$ref": "#/components/responses/NotFound" }
+				}
+			}
+		},
 		"/functions/{id}/secrets": {
 			"parameters": [{ "$ref": "#/components/parameters/ResourceId" }],
 			"get": {
@@ -1704,6 +1836,19 @@ const openapiDocument = {
 					}
 				} }
 			},
+			"DeployFailed": {
+				"description": "Function deploy could not be completed; previously deployed code remains live",
+				"content": { "application/json": {
+					"schema": { "$ref": "#/components/schemas/ErrorResponse" },
+					"example": {
+						"success": false,
+						"error": {
+							"code": "deploy_failed",
+							"message": "Function deploy failed"
+						}
+					}
+				} }
+			},
 			"RateLimited": {
 				"description": "Rate limit exceeded",
 				"headers": { "Retry-After": {
@@ -2063,6 +2208,162 @@ const openapiDocument = {
 					"org_name"
 				]
 			},
+			"StartCliSignupInput": {
+				"type": "object",
+				"additionalProperties": false,
+				"properties": {
+					"email": {
+						"type": "string",
+						"format": "email",
+						"maxLength": 254
+					},
+					"signup_code": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 128
+					},
+					"terms_accepted": {
+						"type": "boolean",
+						"const": true,
+						"description": "Must be true to confirm acceptance of Primitive's Terms of Service and Privacy Policy"
+					},
+					"device_name": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 80,
+						"description": "Human-readable device name used for the created CLI API key"
+					},
+					"metadata": {
+						"type": "object",
+						"additionalProperties": true,
+						"description": "Optional client metadata stored with the signup session; serialized JSON must be 2048 bytes or fewer"
+					}
+				},
+				"required": [
+					"email",
+					"signup_code",
+					"terms_accepted"
+				]
+			},
+			"CliSignupStartResult": {
+				"type": "object",
+				"properties": {
+					"signup_token": {
+						"type": "string",
+						"description": "Opaque token used to verify or resend the pending CLI signup"
+					},
+					"email": {
+						"type": "string",
+						"format": "email"
+					},
+					"expires_in": {
+						"type": "integer",
+						"description": "Seconds until the pending signup expires"
+					},
+					"resend_after": {
+						"type": "integer",
+						"description": "Minimum seconds before requesting another verification email"
+					},
+					"verification_code_length": {
+						"type": "integer",
+						"description": "Number of digits in the emailed verification code"
+					}
+				},
+				"required": [
+					"signup_token",
+					"email",
+					"expires_in",
+					"resend_after",
+					"verification_code_length"
+				]
+			},
+			"ResendCliSignupVerificationInput": {
+				"type": "object",
+				"additionalProperties": false,
+				"properties": { "signup_token": {
+					"type": "string",
+					"minLength": 1
+				} },
+				"required": ["signup_token"]
+			},
+			"CliSignupResendResult": {
+				"type": "object",
+				"properties": {
+					"email": {
+						"type": "string",
+						"format": "email"
+					},
+					"expires_in": {
+						"type": "integer",
+						"description": "Seconds until the pending signup expires"
+					},
+					"resend_after": {
+						"type": "integer",
+						"description": "Minimum seconds before requesting another verification email"
+					},
+					"verification_code_length": {
+						"type": "integer",
+						"description": "Number of digits in the emailed verification code"
+					}
+				},
+				"required": [
+					"email",
+					"expires_in",
+					"resend_after",
+					"verification_code_length"
+				]
+			},
+			"VerifyCliSignupInput": {
+				"type": "object",
+				"additionalProperties": false,
+				"properties": {
+					"signup_token": {
+						"type": "string",
+						"minLength": 1
+					},
+					"verification_code": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 32
+					},
+					"password": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 1024
+					}
+				},
+				"required": [
+					"signup_token",
+					"verification_code",
+					"password"
+				]
+			},
+			"CliSignupVerifyResult": {
+				"type": "object",
+				"properties": {
+					"api_key": {
+						"type": "string",
+						"description": "Newly-created API key for CLI authentication"
+					},
+					"key_id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"key_prefix": { "type": "string" },
+					"org_id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"org_name": { "type": ["string", "null"] }
+				},
+				"required": [
+					"api_key",
+					"key_id",
+					"key_prefix",
+					"org_id",
+					"org_name"
+				]
+			},
 			"CliLogoutInput": {
 				"type": "object",
 				"additionalProperties": false,
@@ -3529,7 +3830,7 @@ const openapiDocument = {
 						"type": "string",
 						"minLength": 1,
 						"maxLength": 5242880,
-						"description": "Optional source map for the bundle. Up to 5 MiB UTF-8.\nStored only on the runtime side (not in Primitive's\ndatabase) and used to symbolicate stack traces in the\nfunction's logs.\n"
+						"description": "Optional source map for the bundle. Up to 5 MiB UTF-8.\nStored with the deployment attempt and sent to the runtime\nto symbolicate stack traces in the function's logs.\n"
 					}
 				},
 				"required": ["name", "code"]
@@ -3576,8 +3877,13 @@ const openapiDocument = {
 			},
 			"TestInvocationResult": {
 				"type": "object",
-				"description": "Metadata returned by POST /functions/{id}/test. The send is\nqueued; the actual invocation lands on the function's\ninvocations list a few seconds later as the inbound mail\ntraverses the MX path.\n",
+				"description": "Metadata returned by POST /functions/{id}/test. The send is\nqueued; poll `trace_url` to watch the run progress through\nsend -> inbound -> webhook deliveries -> outbound requests,\nlogs, and replies.\n",
 				"properties": {
+					"test_run_id": {
+						"type": "string",
+						"format": "uuid",
+						"description": "Durable test run id used to fetch the run trace."
+					},
 					"inbound_domain": {
 						"type": "string",
 						"description": "Verified inbound domain the test email was sent to."
@@ -3607,53 +3913,376 @@ const openapiDocument = {
 						"type": "string",
 						"format": "uri",
 						"description": "Function detail page where invocations show up live."
+					},
+					"trace_url": {
+						"type": "string",
+						"description": "Relative API URL for GET /functions/{id}/test-runs/{test_run_id}/trace."
 					}
 				},
 				"required": [
+					"test_run_id",
 					"inbound_domain",
 					"to",
 					"from",
 					"send_id",
 					"subject",
 					"poll_since",
-					"watch_url"
+					"watch_url",
+					"trace_url"
 				]
 			},
-			"FunctionLogRow": {
+			"FunctionTestRunState": {
+				"type": "string",
+				"description": "High-level state for a function test run trace:\n  - `send_failed`: the initial test email send failed.\n  - `waiting_for_send`: the test run was created but no send result has been recorded yet.\n  - `waiting_for_inbound`: the test send was queued and the matching inbound email has not arrived yet.\n  - `waiting_for_function`: the inbound email arrived and webhook/function processing is still in flight.\n  - `completed`: the function webhook completed successfully.\n  - `failed`: webhook delivery exhausted retries.\n",
+				"enum": [
+					"send_failed",
+					"waiting_for_send",
+					"waiting_for_inbound",
+					"waiting_for_function",
+					"completed",
+					"failed"
+				]
+			},
+			"FunctionTestRun": {
 				"type": "object",
-				"description": "One row from GET /functions/{id}/logs. Represents a single\ncaptured log line emitted by the running handler (e.g. via\n`console.log` / `console.error`).\n",
 				"properties": {
 					"id": {
 						"type": "string",
-						"format": "uuid",
-						"description": "Unique log row id (stable across pages)."
+						"format": "uuid"
 					},
 					"function_id": {
 						"type": "string",
-						"format": "uuid",
-						"description": "The function this log row belongs to."
+						"format": "uuid"
 					},
-					"level": {
+					"inbound_domain": { "type": "string" },
+					"to": { "type": "string" },
+					"from": { "type": "string" },
+					"subject": { "type": "string" },
+					"poll_since": {
 						"type": "string",
-						"enum": [
-							"debug",
-							"log",
-							"info",
-							"warn",
-							"error"
-						],
-						"description": "Severity. `log` is the runtime's default for unannotated\n`console.log` calls; the other levels match standard\n`console.*` methods.\n"
+						"format": "date-time"
 					},
-					"message": {
+					"created_at": {
 						"type": "string",
-						"description": "The textual message body. The runtime stringifies non-string\narguments before persisting, so this is always a plain\nstring.\n"
+						"format": "date-time"
 					},
-					"ts": {
-						"type": "string",
-						"format": "date-time",
-						"description": "When the handler emitted this line. Newest-first ordering\non this column drives pagination; clock is the runtime's,\nnot the gateway's.\n"
+					"sent_at": {
+						"type": ["string", "null"],
+						"format": "date-time"
 					},
-					"metadata": {
+					"send_error": { "type": ["string", "null"] }
+				},
+				"required": [
+					"id",
+					"function_id",
+					"inbound_domain",
+					"to",
+					"from",
+					"subject",
+					"poll_since",
+					"created_at",
+					"sent_at",
+					"send_error"
+				]
+			},
+			"FunctionTestRunSend": {
+				"type": ["object", "null"],
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"status": { "$ref": "#/components/schemas/SentEmailStatus" },
+					"queue_id": { "type": ["string", "null"] },
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"updated_at": {
+						"type": "string",
+						"format": "date-time"
+					}
+				},
+				"required": [
+					"id",
+					"status",
+					"queue_id",
+					"created_at",
+					"updated_at"
+				]
+			},
+			"FunctionTestRunInboundEmail": {
+				"type": ["object", "null"],
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"status": { "$ref": "#/components/schemas/EmailStatus" },
+					"received_at": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"from": { "type": "string" },
+					"to": { "type": "string" },
+					"subject": { "type": ["string", "null"] },
+					"webhook_status": { "$ref": "#/components/schemas/EmailWebhookStatus" },
+					"webhook_attempt_count": { "type": "integer" },
+					"webhook_last_status_code": { "type": ["integer", "null"] },
+					"webhook_last_error": { "type": ["string", "null"] }
+				},
+				"required": [
+					"id",
+					"status",
+					"received_at",
+					"from",
+					"to",
+					"subject",
+					"webhook_status",
+					"webhook_attempt_count",
+					"webhook_last_status_code",
+					"webhook_last_error"
+				]
+			},
+			"FunctionTestRunDeliveryEndpoint": {
+				"type": ["object", "null"],
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"kind": {
+						"type": "string",
+						"description": "Endpoint kind. Current traces may include `http` or `function`; future endpoint kinds may appear."
+					},
+					"function_id": {
+						"type": ["string", "null"],
+						"format": "uuid"
+					},
+					"function_name": { "type": ["string", "null"] },
+					"domain_id": {
+						"type": ["string", "null"],
+						"format": "uuid"
+					},
+					"enabled": { "type": "boolean" },
+					"deactivated_at": {
+						"type": ["string", "null"],
+						"format": "date-time"
+					},
+					"is_current_function": { "type": "boolean" }
+				},
+				"required": [
+					"id",
+					"kind",
+					"function_id",
+					"function_name",
+					"domain_id",
+					"enabled",
+					"deactivated_at",
+					"is_current_function"
+				]
+			},
+			"FunctionTestRunDelivery": {
+				"type": "object",
+				"properties": {
+					"id": {
+						"type": "string",
+						"description": "Webhook delivery id."
+					},
+					"endpoint_id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"endpoint_url": {
+						"type": "string",
+						"format": "uri"
+					},
+					"status": {
+						"type": "string",
+						"enum": [
+							"pending",
+							"delivered",
+							"header_confirmed",
+							"failed"
+						]
+					},
+					"attempt_count": { "type": "integer" },
+					"duration_ms": { "type": ["integer", "null"] },
+					"last_error": { "type": ["string", "null"] },
+					"last_error_code": { "type": ["string", "null"] },
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"updated_at": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"endpoint": { "$ref": "#/components/schemas/FunctionTestRunDeliveryEndpoint" }
+				},
+				"required": [
+					"id",
+					"endpoint_id",
+					"endpoint_url",
+					"status",
+					"attempt_count",
+					"duration_ms",
+					"last_error",
+					"last_error_code",
+					"created_at",
+					"updated_at",
+					"endpoint"
+				]
+			},
+			"FunctionTestRunOutboundRequest": {
+				"type": "object",
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"function_id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"webhook_delivery_id": { "type": ["string", "null"] },
+					"email_id": {
+						"type": ["string", "null"],
+						"format": "uuid"
+					},
+					"endpoint_id": {
+						"type": ["string", "null"],
+						"format": "uuid"
+					},
+					"method": { "type": "string" },
+					"url": {
+						"type": "string",
+						"format": "uri"
+					},
+					"host": { "type": "string" },
+					"path": { "type": "string" },
+					"status_code": { "type": ["integer", "null"] },
+					"ok": { "type": ["boolean", "null"] },
+					"duration_ms": { "type": "integer" },
+					"error": { "type": ["string", "null"] },
+					"ts": {
+						"type": "string",
+						"format": "date-time"
+					}
+				},
+				"required": [
+					"id",
+					"function_id",
+					"webhook_delivery_id",
+					"email_id",
+					"endpoint_id",
+					"method",
+					"url",
+					"host",
+					"path",
+					"status_code",
+					"ok",
+					"duration_ms",
+					"error",
+					"ts"
+				]
+			},
+			"FunctionTestRunReply": {
+				"type": "object",
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"status": { "$ref": "#/components/schemas/SentEmailStatus" },
+					"to": { "type": "string" },
+					"subject": { "type": "string" },
+					"queue_id": { "type": ["string", "null"] },
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					}
+				},
+				"required": [
+					"id",
+					"status",
+					"to",
+					"subject",
+					"queue_id",
+					"created_at"
+				]
+			},
+			"FunctionTestRunTrace": {
+				"type": "object",
+				"description": "End-to-end trace for a `POST /functions/{id}/test` run. The\nshape is stable, but many nested sections are null or empty\nuntil the corresponding phase has happened.\n",
+				"properties": {
+					"state": { "$ref": "#/components/schemas/FunctionTestRunState" },
+					"test_run": { "$ref": "#/components/schemas/FunctionTestRun" },
+					"test_send": { "$ref": "#/components/schemas/FunctionTestRunSend" },
+					"inbound_email": { "$ref": "#/components/schemas/FunctionTestRunInboundEmail" },
+					"deliveries": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/FunctionTestRunDelivery" }
+					},
+					"outbound_requests": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/FunctionTestRunOutboundRequest" }
+					},
+					"logs": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/FunctionLogRow" }
+					},
+					"replies": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/FunctionTestRunReply" }
+					}
+				},
+				"required": [
+					"state",
+					"test_run",
+					"test_send",
+					"inbound_email",
+					"deliveries",
+					"outbound_requests",
+					"logs",
+					"replies"
+				]
+			},
+			"FunctionLogRow": {
+				"type": "object",
+				"description": "One row from GET /functions/{id}/logs. Represents a single\ncaptured log line emitted by the running handler (e.g. via\n`console.log` / `console.error`).\n",
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid",
+						"description": "Unique log row id (stable across pages)."
+					},
+					"function_id": {
+						"type": "string",
+						"format": "uuid",
+						"description": "The function this log row belongs to."
+					},
+					"level": {
+						"type": "string",
+						"enum": [
+							"debug",
+							"log",
+							"info",
+							"warn",
+							"error"
+						],
+						"description": "Severity. `log` is the runtime's default for unannotated\n`console.log` calls; the other levels match standard\n`console.*` methods.\n"
+					},
+					"message": {
+						"type": "string",
+						"description": "The textual message body. The runtime stringifies non-string\narguments before persisting, so this is always a plain\nstring.\n"
+					},
+					"ts": {
+						"type": "string",
+						"format": "date-time",
+						"description": "When the handler emitted this line. Newest-first ordering\non this column drives pagination; clock is the runtime's,\nnot the gateway's.\n"
+					},
+					"metadata": {
 						"type": ["object", "null"],
 						"additionalProperties": true,
 						"description": "Optional structured payload the runtime attaches alongside\nthe message (e.g. extra args passed to `console.log`).\nShape is opaque; treat keys as untyped.\n"
@@ -4063,27 +4692,79 @@ const operationManifest = [
 	},
 	{
 		"binaryResponse": false,
-		"bodyRequired": false,
-		"command": "start-cli-login",
-		"description": "Starts a browser-assisted CLI login session. The response includes a\ndevice code for polling and a user code that the user approves in the\nbrowser. This endpoint does not require an API key.\n",
+		"bodyRequired": true,
+		"command": "resend-cli-signup-verification",
+		"description": "Sends a new email verification code for a pending CLI signup session.\nThis endpoint does not require an API key.\n",
 		"hasJsonBody": true,
 		"method": "POST",
-		"operationId": "startCliLogin",
-		"path": "/cli/login/start",
+		"operationId": "resendCliSignupVerification",
+		"path": "/cli/signup/resend",
 		"pathParams": [],
 		"queryParams": [],
 		"requestSchema": {
 			"type": "object",
 			"additionalProperties": false,
+			"properties": { "signup_token": {
+				"type": "string",
+				"minLength": 1
+			} },
+			"required": ["signup_token"]
+		},
+		"responseSchema": {
+			"type": "object",
 			"properties": {
-				"device_name": {
+				"email": {
 					"type": "string",
-					"minLength": 1,
-					"maxLength": 80,
-					"description": "Human-readable device name shown during browser approval"
+					"format": "email"
 				},
-				"metadata": {
-					"type": "object",
+				"expires_in": {
+					"type": "integer",
+					"description": "Seconds until the pending signup expires"
+				},
+				"resend_after": {
+					"type": "integer",
+					"description": "Minimum seconds before requesting another verification email"
+				},
+				"verification_code_length": {
+					"type": "integer",
+					"description": "Number of digits in the emailed verification code"
+				}
+			},
+			"required": [
+				"email",
+				"expires_in",
+				"resend_after",
+				"verification_code_length"
+			]
+		},
+		"sdkName": "resendCliSignupVerification",
+		"summary": "Resend CLI signup verification code",
+		"tag": "CLI",
+		"tagCommand": "cli"
+	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": false,
+		"command": "start-cli-login",
+		"description": "Starts a browser-assisted CLI login session. The response includes a\ndevice code for polling and a user code that the user approves in the\nbrowser. This endpoint does not require an API key.\n",
+		"hasJsonBody": true,
+		"method": "POST",
+		"operationId": "startCliLogin",
+		"path": "/cli/login/start",
+		"pathParams": [],
+		"queryParams": [],
+		"requestSchema": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"device_name": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 80,
+					"description": "Human-readable device name shown during browser approval"
+				},
+				"metadata": {
+					"type": "object",
 					"additionalProperties": true,
 					"description": "Optional client metadata stored with the login session; serialized JSON must be 2048 bytes or fewer"
 				}
@@ -4132,6 +4813,158 @@ const operationManifest = [
 		"tag": "CLI",
 		"tagCommand": "cli"
 	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": true,
+		"command": "start-cli-signup",
+		"description": "Starts a terminal-native CLI signup. The API validates the signup code,\ncreates a pending signup session, sends an email verification code, and\nreturns an opaque signup token used by the resend and verify steps. This\nendpoint does not require an API key.\n",
+		"hasJsonBody": true,
+		"method": "POST",
+		"operationId": "startCliSignup",
+		"path": "/cli/signup/start",
+		"pathParams": [],
+		"queryParams": [],
+		"requestSchema": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"email": {
+					"type": "string",
+					"format": "email",
+					"maxLength": 254
+				},
+				"signup_code": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 128
+				},
+				"terms_accepted": {
+					"type": "boolean",
+					"const": true,
+					"description": "Must be true to confirm acceptance of Primitive's Terms of Service and Privacy Policy"
+				},
+				"device_name": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 80,
+					"description": "Human-readable device name used for the created CLI API key"
+				},
+				"metadata": {
+					"type": "object",
+					"additionalProperties": true,
+					"description": "Optional client metadata stored with the signup session; serialized JSON must be 2048 bytes or fewer"
+				}
+			},
+			"required": [
+				"email",
+				"signup_code",
+				"terms_accepted"
+			]
+		},
+		"responseSchema": {
+			"type": "object",
+			"properties": {
+				"signup_token": {
+					"type": "string",
+					"description": "Opaque token used to verify or resend the pending CLI signup"
+				},
+				"email": {
+					"type": "string",
+					"format": "email"
+				},
+				"expires_in": {
+					"type": "integer",
+					"description": "Seconds until the pending signup expires"
+				},
+				"resend_after": {
+					"type": "integer",
+					"description": "Minimum seconds before requesting another verification email"
+				},
+				"verification_code_length": {
+					"type": "integer",
+					"description": "Number of digits in the emailed verification code"
+				}
+			},
+			"required": [
+				"signup_token",
+				"email",
+				"expires_in",
+				"resend_after",
+				"verification_code_length"
+			]
+		},
+		"sdkName": "startCliSignup",
+		"summary": "Start CLI account signup",
+		"tag": "CLI",
+		"tagCommand": "cli"
+	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": true,
+		"command": "verify-cli-signup",
+		"description": "Verifies the email code for a CLI signup session, creates the account,\nredeems the reserved signup code, mints an org-scoped CLI API key, and\nreturns the raw key exactly once. This endpoint does not require an API key.\n",
+		"hasJsonBody": true,
+		"method": "POST",
+		"operationId": "verifyCliSignup",
+		"path": "/cli/signup/verify",
+		"pathParams": [],
+		"queryParams": [],
+		"requestSchema": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"signup_token": {
+					"type": "string",
+					"minLength": 1
+				},
+				"verification_code": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 32
+				},
+				"password": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 1024
+				}
+			},
+			"required": [
+				"signup_token",
+				"verification_code",
+				"password"
+			]
+		},
+		"responseSchema": {
+			"type": "object",
+			"properties": {
+				"api_key": {
+					"type": "string",
+					"description": "Newly-created API key for CLI authentication"
+				},
+				"key_id": {
+					"type": "string",
+					"format": "uuid"
+				},
+				"key_prefix": { "type": "string" },
+				"org_id": {
+					"type": "string",
+					"format": "uuid"
+				},
+				"org_name": { "type": ["string", "null"] }
+			},
+			"required": [
+				"api_key",
+				"key_id",
+				"key_prefix",
+				"org_id",
+				"org_name"
+			]
+		},
+		"sdkName": "verifyCliSignup",
+		"summary": "Verify CLI signup and create API key",
+		"tag": "CLI",
+		"tagCommand": "cli"
+	},
 	{
 		"binaryResponse": false,
 		"bodyRequired": true,
@@ -5802,7 +6635,7 @@ const operationManifest = [
 		"binaryResponse": false,
 		"bodyRequired": true,
 		"command": "create-function",
-		"description": "Creates and deploys a new function. The handler must be a single\nESM module whose default export is an object with an async\n`fetch(request, env)` method (Workers-style). The gateway\nHMAC-verifies the POST against the org's webhook secret before\ninvoking the handler; the request body parses to an\n`email.received` event (see `EmailReceivedEvent` and the\nWebhook payload section for the full schema). Code is bundled\nbefore being uploaded; ship a single self-contained file rather\nthan relying on external imports.\n\n**Code limits.** `code` is capped at 1 MiB UTF-8. `sourceMap`\n(optional) is capped at 5 MiB UTF-8 and is stored only on the\nedge runtime side; it is not persisted in Primitive's database.\n\n**Auto-wiring.** On successful deploy, Primitive automatically\ncreates a webhook endpoint that delivers inbound mail to the\nfunction. There is nothing to configure on the Endpoints API\nfor this to work; the gateway URL returned here is for\nreference only and is not directly callable from outside.\n\n**Secrets.** New functions ship with the managed secrets\n(`PRIMITIVE_WEBHOOK_SECRET`, `PRIMITIVE_API_KEY`) already\nbound. Add user-set secrets via\n`POST /functions/{id}/secrets`; secret writes only land in the\nrunning handler on the next redeploy.\n",
+		"description": "Creates and deploys a new function. The handler must be a single\nESM module whose default export is an object with an async\n`fetch(request, env)` method (Workers-style). The gateway\nHMAC-verifies the POST against the org's webhook secret before\ninvoking the handler; the request body parses to an\n`email.received` event (see `EmailReceivedEvent` and the\nWebhook payload section for the full schema). Code is bundled\nbefore being uploaded; ship a single self-contained file rather\nthan relying on external imports.\n\n**Code limits.** `code` is capped at 1 MiB UTF-8. `sourceMap`\n(optional) is capped at 5 MiB UTF-8, stored with each deployment\nattempt, and sent to the runtime so stack traces can resolve to\noriginal source files.\n\n**Auto-wiring.** On successful deploy, Primitive automatically\ncreates a webhook endpoint that delivers inbound mail to the\nfunction. There is nothing to configure on the Endpoints API\nfor this to work; the gateway URL returned here is for\nreference only and is not directly callable from outside.\n\n**Secrets.** New functions ship with the managed secrets\n(`PRIMITIVE_WEBHOOK_SECRET`, `PRIMITIVE_API_KEY`) already\nbound. Add user-set secrets via\n`POST /functions/{id}/secrets`; secret writes only land in the\nrunning handler on the next redeploy.\n",
 		"hasJsonBody": true,
 		"method": "POST",
 		"operationId": "createFunction",
@@ -5828,7 +6661,7 @@ const operationManifest = [
 					"type": "string",
 					"minLength": 1,
 					"maxLength": 5242880,
-					"description": "Optional source map for the bundle. Up to 5 MiB UTF-8.\nStored only on the runtime side (not in Primitive's\ndatabase) and used to symbolicate stack traces in the\nfunction's logs.\n"
+					"description": "Optional source map for the bundle. Up to 5 MiB UTF-8.\nStored with the deployment attempt and sent to the runtime\nto symbolicate stack traces in the function's logs.\n"
 				}
 			},
 			"required": ["name", "code"]
@@ -6064,6 +6897,439 @@ const operationManifest = [
 		"tag": "Functions",
 		"tagCommand": "functions"
 	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": false,
+		"command": "get-function-test-run-trace",
+		"description": "Returns the current end-to-end trace for a function test run.\nThe trace is intentionally partial while the test is still in\nflight: callers can poll this endpoint and watch it fill in\nfrom send -> inbound -> webhook deliveries -> outbound\nrequests, logs, and replies.\n",
+		"hasJsonBody": false,
+		"method": "GET",
+		"operationId": "getFunctionTestRunTrace",
+		"path": "/functions/{id}/test-runs/{run_id}/trace",
+		"pathParams": [{
+			"description": "Resource UUID",
+			"enum": null,
+			"name": "id",
+			"required": true,
+			"type": "string"
+		}, {
+			"description": "Function test run id returned by POST /functions/{id}/test.",
+			"enum": null,
+			"name": "run_id",
+			"required": true,
+			"type": "string"
+		}],
+		"queryParams": [],
+		"requestSchema": null,
+		"responseSchema": {
+			"type": "object",
+			"description": "End-to-end trace for a `POST /functions/{id}/test` run. The\nshape is stable, but many nested sections are null or empty\nuntil the corresponding phase has happened.\n",
+			"properties": {
+				"state": {
+					"type": "string",
+					"description": "High-level state for a function test run trace:\n  - `send_failed`: the initial test email send failed.\n  - `waiting_for_send`: the test run was created but no send result has been recorded yet.\n  - `waiting_for_inbound`: the test send was queued and the matching inbound email has not arrived yet.\n  - `waiting_for_function`: the inbound email arrived and webhook/function processing is still in flight.\n  - `completed`: the function webhook completed successfully.\n  - `failed`: webhook delivery exhausted retries.\n",
+					"enum": [
+						"send_failed",
+						"waiting_for_send",
+						"waiting_for_inbound",
+						"waiting_for_function",
+						"completed",
+						"failed"
+					]
+				},
+				"test_run": {
+					"type": "object",
+					"properties": {
+						"id": {
+							"type": "string",
+							"format": "uuid"
+						},
+						"function_id": {
+							"type": "string",
+							"format": "uuid"
+						},
+						"inbound_domain": { "type": "string" },
+						"to": { "type": "string" },
+						"from": { "type": "string" },
+						"subject": { "type": "string" },
+						"poll_since": {
+							"type": "string",
+							"format": "date-time"
+						},
+						"created_at": {
+							"type": "string",
+							"format": "date-time"
+						},
+						"sent_at": {
+							"type": ["string", "null"],
+							"format": "date-time"
+						},
+						"send_error": { "type": ["string", "null"] }
+					},
+					"required": [
+						"id",
+						"function_id",
+						"inbound_domain",
+						"to",
+						"from",
+						"subject",
+						"poll_since",
+						"created_at",
+						"sent_at",
+						"send_error"
+					]
+				},
+				"test_send": {
+					"type": ["object", "null"],
+					"properties": {
+						"id": {
+							"type": "string",
+							"format": "uuid"
+						},
+						"status": {
+							"type": "string",
+							"description": "Lifecycle status of a sent_emails row. Possible values:\n\n  - `queued`: pre-call INSERT; the outbound agent has not\n    yet replied.\n  - `submitted_to_agent`: agent accepted; `queue_id` is set.\n  - `agent_failed`: agent rejected; `error_code` and\n    `error_message` carry the reason.\n  - `gate_denied`: a recipient-scope gate denied the send;\n    the agent was never called. The `gates` array carries\n    the denial detail. /send-mail returns 403 in this case\n    so callers see the denial synchronously; /sent-emails\n    additionally records the row for historical lookup,\n    which is when this status appears in a listing.\n  - `unknown`: terminal indeterminate; the on-box log\n    poller couldn't classify the receiver's response.\n  - `delivered` / `bounced` / `deferred` / `wait_timeout`:\n    terminal delivery outcomes (see DeliveryStatus).\n",
+							"enum": [
+								"queued",
+								"submitted_to_agent",
+								"agent_failed",
+								"gate_denied",
+								"unknown",
+								"delivered",
+								"bounced",
+								"deferred",
+								"wait_timeout"
+							]
+						},
+						"queue_id": { "type": ["string", "null"] },
+						"created_at": {
+							"type": "string",
+							"format": "date-time"
+						},
+						"updated_at": {
+							"type": "string",
+							"format": "date-time"
+						}
+					},
+					"required": [
+						"id",
+						"status",
+						"queue_id",
+						"created_at",
+						"updated_at"
+					]
+				},
+				"inbound_email": {
+					"type": ["object", "null"],
+					"properties": {
+						"id": {
+							"type": "string",
+							"format": "uuid"
+						},
+						"status": {
+							"type": "string",
+							"description": "Lifecycle status of an INBOUND email (a row in the `emails`\ntable). Distinct from `SentEmailStatus`, which describes\nthe OUTBOUND lifecycle (the `sent_emails` table) and uses\na different vocabulary because the lifecycles differ.\nPossible values:\n\n  - `pending`: the row was inserted at ingestion (mx_main)\n    and has not yet completed the spam / filter / auth\n    pipeline. Body and parsed fields are present; webhook\n    delivery is not yet scheduled. Most rows transition out\n    of `pending` within seconds.\n  - `accepted`: the inbound passed the policy gates and is\n    queued for webhook delivery. The `webhook_status` field\n    tracks the separate webhook-delivery lifecycle from\n    this point.\n  - `completed`: terminal success. Webhook delivery\n    attempted and acknowledged by every active endpoint, OR\n    no endpoints are configured, so the row is durably\n    archived.\n  - `rejected`: terminal failure at ingestion (spam, blocked\n    sender, filter rule, malformed). The body and metadata\n    are stored for auditing but no webhook fires and the\n    row is not repliable.\n\nSee also `webhook_status` (separate enum tracking the\nwebhook-delivery state machine) and `SentEmailStatus` (the\noutbound vocabulary).\n",
+							"enum": [
+								"pending",
+								"accepted",
+								"completed",
+								"rejected"
+							]
+						},
+						"received_at": {
+							"type": "string",
+							"format": "date-time"
+						},
+						"from": { "type": "string" },
+						"to": { "type": "string" },
+						"subject": { "type": ["string", "null"] },
+						"webhook_status": {
+							"type": ["string", "null"],
+							"description": "Webhook-delivery state for an inbound email. Tracks a\nSEPARATE lifecycle from the email's `status` field; the\nsame row carries both. Possible values:\n\n  - `pending`: ingestion is past `pending` (the email itself\n    is `accepted`) but the webhook fan-out has not yet\n    started for this row.\n  - `in_flight`: at least one delivery attempt is in flight.\n  - `fired`: terminal success. Every active endpoint\n    acknowledged the delivery (or accepted it after retries).\n  - `failed`: terminal partial-failure. At least one endpoint\n    exhausted its retry budget; some endpoints may still\n    have succeeded.\n  - `exhausted`: terminal failure. Every endpoint exhausted\n    its retry budget without success.\n  - `null`: no endpoints configured, so no webhook lifecycle\n    applies.\n\nNote that the value `pending` here does NOT mean the email\nis `pending`; it means the email is past ingestion but\nwebhook delivery has not yet begun. Two overlapping uses\nof the word `pending` for distinct lifecycle phases.\n",
+							"enum": [
+								"pending",
+								"in_flight",
+								"fired",
+								"failed",
+								"exhausted",
+								null
+							]
+						},
+						"webhook_attempt_count": { "type": "integer" },
+						"webhook_last_status_code": { "type": ["integer", "null"] },
+						"webhook_last_error": { "type": ["string", "null"] }
+					},
+					"required": [
+						"id",
+						"status",
+						"received_at",
+						"from",
+						"to",
+						"subject",
+						"webhook_status",
+						"webhook_attempt_count",
+						"webhook_last_status_code",
+						"webhook_last_error"
+					]
+				},
+				"deliveries": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"properties": {
+							"id": {
+								"type": "string",
+								"description": "Webhook delivery id."
+							},
+							"endpoint_id": {
+								"type": "string",
+								"format": "uuid"
+							},
+							"endpoint_url": {
+								"type": "string",
+								"format": "uri"
+							},
+							"status": {
+								"type": "string",
+								"enum": [
+									"pending",
+									"delivered",
+									"header_confirmed",
+									"failed"
+								]
+							},
+							"attempt_count": { "type": "integer" },
+							"duration_ms": { "type": ["integer", "null"] },
+							"last_error": { "type": ["string", "null"] },
+							"last_error_code": { "type": ["string", "null"] },
+							"created_at": {
+								"type": "string",
+								"format": "date-time"
+							},
+							"updated_at": {
+								"type": "string",
+								"format": "date-time"
+							},
+							"endpoint": {
+								"type": ["object", "null"],
+								"properties": {
+									"id": {
+										"type": "string",
+										"format": "uuid"
+									},
+									"kind": {
+										"type": "string",
+										"description": "Endpoint kind. Current traces may include `http` or `function`; future endpoint kinds may appear."
+									},
+									"function_id": {
+										"type": ["string", "null"],
+										"format": "uuid"
+									},
+									"function_name": { "type": ["string", "null"] },
+									"domain_id": {
+										"type": ["string", "null"],
+										"format": "uuid"
+									},
+									"enabled": { "type": "boolean" },
+									"deactivated_at": {
+										"type": ["string", "null"],
+										"format": "date-time"
+									},
+									"is_current_function": { "type": "boolean" }
+								},
+								"required": [
+									"id",
+									"kind",
+									"function_id",
+									"function_name",
+									"domain_id",
+									"enabled",
+									"deactivated_at",
+									"is_current_function"
+								]
+							}
+						},
+						"required": [
+							"id",
+							"endpoint_id",
+							"endpoint_url",
+							"status",
+							"attempt_count",
+							"duration_ms",
+							"last_error",
+							"last_error_code",
+							"created_at",
+							"updated_at",
+							"endpoint"
+						]
+					}
+				},
+				"outbound_requests": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"properties": {
+							"id": {
+								"type": "string",
+								"format": "uuid"
+							},
+							"function_id": {
+								"type": "string",
+								"format": "uuid"
+							},
+							"webhook_delivery_id": { "type": ["string", "null"] },
+							"email_id": {
+								"type": ["string", "null"],
+								"format": "uuid"
+							},
+							"endpoint_id": {
+								"type": ["string", "null"],
+								"format": "uuid"
+							},
+							"method": { "type": "string" },
+							"url": {
+								"type": "string",
+								"format": "uri"
+							},
+							"host": { "type": "string" },
+							"path": { "type": "string" },
+							"status_code": { "type": ["integer", "null"] },
+							"ok": { "type": ["boolean", "null"] },
+							"duration_ms": { "type": "integer" },
+							"error": { "type": ["string", "null"] },
+							"ts": {
+								"type": "string",
+								"format": "date-time"
+							}
+						},
+						"required": [
+							"id",
+							"function_id",
+							"webhook_delivery_id",
+							"email_id",
+							"endpoint_id",
+							"method",
+							"url",
+							"host",
+							"path",
+							"status_code",
+							"ok",
+							"duration_ms",
+							"error",
+							"ts"
+						]
+					}
+				},
+				"logs": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"description": "One row from GET /functions/{id}/logs. Represents a single\ncaptured log line emitted by the running handler (e.g. via\n`console.log` / `console.error`).\n",
+						"properties": {
+							"id": {
+								"type": "string",
+								"format": "uuid",
+								"description": "Unique log row id (stable across pages)."
+							},
+							"function_id": {
+								"type": "string",
+								"format": "uuid",
+								"description": "The function this log row belongs to."
+							},
+							"level": {
+								"type": "string",
+								"enum": [
+									"debug",
+									"log",
+									"info",
+									"warn",
+									"error"
+								],
+								"description": "Severity. `log` is the runtime's default for unannotated\n`console.log` calls; the other levels match standard\n`console.*` methods.\n"
+							},
+							"message": {
+								"type": "string",
+								"description": "The textual message body. The runtime stringifies non-string\narguments before persisting, so this is always a plain\nstring.\n"
+							},
+							"ts": {
+								"type": "string",
+								"format": "date-time",
+								"description": "When the handler emitted this line. Newest-first ordering\non this column drives pagination; clock is the runtime's,\nnot the gateway's.\n"
+							},
+							"metadata": {
+								"type": ["object", "null"],
+								"additionalProperties": true,
+								"description": "Optional structured payload the runtime attaches alongside\nthe message (e.g. extra args passed to `console.log`).\nShape is opaque; treat keys as untyped.\n"
+							}
+						},
+						"required": [
+							"id",
+							"function_id",
+							"level",
+							"message",
+							"ts"
+						]
+					}
+				},
+				"replies": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"properties": {
+							"id": {
+								"type": "string",
+								"format": "uuid"
+							},
+							"status": {
+								"type": "string",
+								"description": "Lifecycle status of a sent_emails row. Possible values:\n\n  - `queued`: pre-call INSERT; the outbound agent has not\n    yet replied.\n  - `submitted_to_agent`: agent accepted; `queue_id` is set.\n  - `agent_failed`: agent rejected; `error_code` and\n    `error_message` carry the reason.\n  - `gate_denied`: a recipient-scope gate denied the send;\n    the agent was never called. The `gates` array carries\n    the denial detail. /send-mail returns 403 in this case\n    so callers see the denial synchronously; /sent-emails\n    additionally records the row for historical lookup,\n    which is when this status appears in a listing.\n  - `unknown`: terminal indeterminate; the on-box log\n    poller couldn't classify the receiver's response.\n  - `delivered` / `bounced` / `deferred` / `wait_timeout`:\n    terminal delivery outcomes (see DeliveryStatus).\n",
+								"enum": [
+									"queued",
+									"submitted_to_agent",
+									"agent_failed",
+									"gate_denied",
+									"unknown",
+									"delivered",
+									"bounced",
+									"deferred",
+									"wait_timeout"
+								]
+							},
+							"to": { "type": "string" },
+							"subject": { "type": "string" },
+							"queue_id": { "type": ["string", "null"] },
+							"created_at": {
+								"type": "string",
+								"format": "date-time"
+							}
+						},
+						"required": [
+							"id",
+							"status",
+							"to",
+							"subject",
+							"queue_id",
+							"created_at"
+						]
+					}
+				}
+			},
+			"required": [
+				"state",
+				"test_run",
+				"test_send",
+				"inbound_email",
+				"deliveries",
+				"outbound_requests",
+				"logs",
+				"replies"
+			]
+		},
+		"sdkName": "getFunctionTestRunTrace",
+		"summary": "Get a function test run trace",
+		"tag": "Functions",
+		"tagCommand": "functions"
+	},
 	{
 		"binaryResponse": false,
 		"bodyRequired": false,
@@ -6380,8 +7646,13 @@ const operationManifest = [
 		},
 		"responseSchema": {
 			"type": "object",
-			"description": "Metadata returned by POST /functions/{id}/test. The send is\nqueued; the actual invocation lands on the function's\ninvocations list a few seconds later as the inbound mail\ntraverses the MX path.\n",
+			"description": "Metadata returned by POST /functions/{id}/test. The send is\nqueued; poll `trace_url` to watch the run progress through\nsend -> inbound -> webhook deliveries -> outbound requests,\nlogs, and replies.\n",
 			"properties": {
+				"test_run_id": {
+					"type": "string",
+					"format": "uuid",
+					"description": "Durable test run id used to fetch the run trace."
+				},
 				"inbound_domain": {
 					"type": "string",
 					"description": "Verified inbound domain the test email was sent to."
@@ -6411,16 +7682,22 @@ const operationManifest = [
 					"type": "string",
 					"format": "uri",
 					"description": "Function detail page where invocations show up live."
+				},
+				"trace_url": {
+					"type": "string",
+					"description": "Relative API URL for GET /functions/{id}/test-runs/{test_run_id}/trace."
 				}
 			},
 			"required": [
+				"test_run_id",
 				"inbound_domain",
 				"to",
 				"from",
 				"send_id",
 				"subject",
 				"poll_since",
-				"watch_url"
+				"watch_url",
+				"trace_url"
 			]
 		},
 		"sdkName": "testFunction",
@@ -6432,7 +7709,7 @@ const operationManifest = [
 		"binaryResponse": false,
 		"bodyRequired": true,
 		"command": "update-function",
-		"description": "Replaces the function's source code with the body's `code` and\ntriggers a redeploy. Same size limits as `POST /functions`.\nUse this verb to push secret writes into the running handler:\npassing the same `code` re-runs the deploy and refreshes the\nbinding set with the latest values from the secrets table.\n\nOn a 502 deploy failure, the previously-deployed code stays\nlive; the runtime never serves a half-built bundle. The\n`deploy_error` field on the returned record carries the error\nthat came back from the runtime so you can surface it to users\nwithout polling.\n",
+		"description": "Replaces the function's source code with the body's `code` and\ntriggers a redeploy. Same size limits as `POST /functions`.\nUse this verb to push secret writes into the running handler:\npassing the same `code` re-runs the deploy and refreshes the\nbinding set with the latest values from the secrets table.\n\nOn deploy failure, the previously-deployed code stays live; the\nruntime never serves a half-built bundle. The response uses\n`error.code` `deploy_failed`, and the function's `deploy_error`\nfield carries the latest deploy error for dashboard/API reads.\n",
 		"hasJsonBody": true,
 		"method": "PUT",
 		"operationId": "updateFunction",