@primitivedotdev/sdk 0.19.0 → 0.20.0

package/dist/openapi/openapi.generated.js

@@ -62,6 +62,10 @@ export const openapiDocument = {
         {
             "name": "Webhook Deliveries",
             "description": "View and replay webhook delivery attempts"
+        },
+        {
+            "name": "Functions",
+            "description": "Deploy JavaScript handlers that run on inbound mail. Each function\nexports a default async handler receiving the `email.received`\nevent. Code runs on Primitive's edge runtime; there is no\ninfrastructure to manage. Secrets land in `env` as encrypted\nbindings and are refreshed on every redeploy.\n"
         }
     ],
     "paths": {
@@ -2075,7 +2079,519 @@ export const openapiDocument = {
                                             "type": "object",
                                             "properties": {
                                                 "data": {
-                                                    "$ref": "#/components/schemas/SentEmailDetail"
+                                                    "$ref": "#/components/schemas/SentEmailDetail"
+                                                }
+                                            }
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "$ref": "#/components/responses/ValidationError"
+                    },
+                    "401": {
+                        "$ref": "#/components/responses/Unauthorized"
+                    },
+                    "404": {
+                        "$ref": "#/components/responses/NotFound"
+                    }
+                }
+            }
+        },
+        "/functions": {
+            "get": {
+                "operationId": "listFunctions",
+                "summary": "List functions",
+                "description": "Returns every active (non-deleted) function in the org, newest\nfirst. Each entry carries the deploy status and the gateway URL\nthat the platform's webhook delivery loop posts to. To inspect\nthe source code or deploy errors, use `GET /functions/{id}`.\n",
+                "tags": [
+                    "Functions"
+                ],
+                "responses": {
+                    "200": {
+                        "description": "List of functions",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "allOf": [
+                                        {
+                                            "$ref": "#/components/schemas/SuccessEnvelope"
+                                        },
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "data": {
+                                                    "type": "array",
+                                                    "items": {
+                                                        "$ref": "#/components/schemas/FunctionListItem"
+                                                    }
+                                                }
+                                            }
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "401": {
+                        "$ref": "#/components/responses/Unauthorized"
+                    }
+                }
+            },
+            "post": {
+                "operationId": "createFunction",
+                "summary": "Deploy a function",
+                "description": "Creates and deploys a new function. The handler must be a single\nESM module that exports a default async function receiving the\n`email.received` event (see the Webhook payload section for the\nfull schema). Code is bundled before being uploaded; ship a\nsingle self-contained file rather than relying on external\nimports.\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",
+                "tags": [
+                    "Functions"
+                ],
+                "requestBody": {
+                    "required": true,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/CreateFunctionInput"
+                            }
+                        }
+                    }
+                },
+                "responses": {
+                    "201": {
+                        "description": "Function created and deployed",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "allOf": [
+                                        {
+                                            "$ref": "#/components/schemas/SuccessEnvelope"
+                                        },
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "data": {
+                                                    "$ref": "#/components/schemas/CreateFunctionResult"
+                                                }
+                                            }
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "$ref": "#/components/responses/ValidationError"
+                    },
+                    "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"
+                    }
+                }
+            }
+        },
+        "/functions/{id}": {
+            "parameters": [
+                {
+                    "$ref": "#/components/parameters/ResourceId"
+                }
+            ],
+            "get": {
+                "operationId": "getFunction",
+                "summary": "Get a function",
+                "description": "Returns the full record for a function, including its current\nsource code and the deploy status / error from the most recent\ndeploy attempt.\n",
+                "tags": [
+                    "Functions"
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Function record",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "allOf": [
+                                        {
+                                            "$ref": "#/components/schemas/SuccessEnvelope"
+                                        },
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "data": {
+                                                    "$ref": "#/components/schemas/FunctionDetail"
+                                                }
+                                            }
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "401": {
+                        "$ref": "#/components/responses/Unauthorized"
+                    },
+                    "404": {
+                        "$ref": "#/components/responses/NotFound"
+                    }
+                }
+            },
+            "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",
+                "tags": [
+                    "Functions"
+                ],
+                "requestBody": {
+                    "required": true,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/UpdateFunctionInput"
+                            }
+                        }
+                    }
+                },
+                "responses": {
+                    "200": {
+                        "description": "Updated function",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "allOf": [
+                                        {
+                                            "$ref": "#/components/schemas/SuccessEnvelope"
+                                        },
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "data": {
+                                                    "$ref": "#/components/schemas/FunctionDetail"
+                                                }
+                                            }
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "$ref": "#/components/responses/ValidationError"
+                    },
+                    "401": {
+                        "$ref": "#/components/responses/Unauthorized"
+                    },
+                    "404": {
+                        "$ref": "#/components/responses/NotFound"
+                    },
+                    "502": {
+                        "$ref": "#/components/responses/BadGateway"
+                    }
+                }
+            },
+            "delete": {
+                "operationId": "deleteFunction",
+                "summary": "Delete a function",
+                "description": "Soft-deletes the function row, removes the script from the edge\nruntime, and deactivates the auto-wired webhook endpoint so no\nfurther inbound mail is delivered. Past deploy history,\ninvocations, and logs are retained.\n\nReturns 502 if the runtime delete fails partway; the function\nrow stays in place and the call is safe to retry until it\nsucceeds.\n",
+                "tags": [
+                    "Functions"
+                ],
+                "responses": {
+                    "200": {
+                        "$ref": "#/components/responses/Deleted"
+                    },
+                    "401": {
+                        "$ref": "#/components/responses/Unauthorized"
+                    },
+                    "404": {
+                        "$ref": "#/components/responses/NotFound"
+                    },
+                    "502": {
+                        "$ref": "#/components/responses/BadGateway"
+                    }
+                }
+            }
+        },
+        "/functions/{id}/test": {
+            "parameters": [
+                {
+                    "$ref": "#/components/parameters/ResourceId"
+                }
+            ],
+            "post": {
+                "operationId": "testFunction",
+                "summary": "Send a test invocation",
+                "description": "Sends a real test email from a Primitive-controlled sender to a\nsynthetic local-part on one of the org's verified inbound\ndomains. The function fires through the normal MX delivery\npath, so reply / send-mail calls from inside the handler\nagainst the inbound's `email.id` work the same as in\nproduction. Returns immediately after the send is queued; the\ninvocation appears on the function's invocations list within a\nfew seconds.\n\nRequires that the function is currently `deployed`. Returns 422\nif the function is in `pending` or `failed` state, or if the\norg has no verified inbound domain to receive the test mail.\n",
+                "tags": [
+                    "Functions"
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Test send queued",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "allOf": [
+                                        {
+                                            "$ref": "#/components/schemas/SuccessEnvelope"
+                                        },
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "data": {
+                                                    "$ref": "#/components/schemas/TestInvocationResult"
+                                                }
+                                            }
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "$ref": "#/components/responses/ValidationError"
+                    },
+                    "401": {
+                        "$ref": "#/components/responses/Unauthorized"
+                    },
+                    "404": {
+                        "$ref": "#/components/responses/NotFound"
+                    },
+                    "422": {
+                        "description": "Function not in a state that can be invoked, or no inbound domain configured",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/ErrorResponse"
+                                }
+                            }
+                        }
+                    },
+                    "502": {
+                        "$ref": "#/components/responses/BadGateway"
+                    },
+                    "503": {
+                        "description": "Sending agent misconfigured",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/ErrorResponse"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/functions/{id}/secrets": {
+            "parameters": [
+                {
+                    "$ref": "#/components/parameters/ResourceId"
+                }
+            ],
+            "get": {
+                "operationId": "listFunctionSecrets",
+                "summary": "List a function's secrets",
+                "description": "Returns metadata for every secret bound to the function, with\nmanaged entries (provisioned by Primitive) listed first and\nuser-set entries listed alphabetically after. **Values are\nnever returned.** Secret writes are write-only.\n\nManaged entries (e.g. `PRIMITIVE_WEBHOOK_SECRET`,\n`PRIMITIVE_API_KEY`) carry a `description` instead of\n`created_at` / `updated_at`. They cannot be created, updated,\nor deleted via this API.\n",
+                "tags": [
+                    "Functions"
+                ],
+                "responses": {
+                    "200": {
+                        "description": "List of secrets (metadata only, no values)",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "allOf": [
+                                        {
+                                            "$ref": "#/components/schemas/SuccessEnvelope"
+                                        },
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "data": {
+                                                    "type": "object",
+                                                    "properties": {
+                                                        "items": {
+                                                            "type": "array",
+                                                            "items": {
+                                                                "$ref": "#/components/schemas/FunctionSecretListItem"
+                                                            }
+                                                        }
+                                                    },
+                                                    "required": [
+                                                        "items"
+                                                    ]
+                                                }
+                                            }
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "401": {
+                        "$ref": "#/components/responses/Unauthorized"
+                    },
+                    "404": {
+                        "$ref": "#/components/responses/NotFound"
+                    }
+                }
+            },
+            "post": {
+                "operationId": "createFunctionSecret",
+                "summary": "Create or update a secret",
+                "description": "Idempotent insert-or-update keyed on `(function_id, key)`.\nReturns 201 the first time the key is set, 200 on subsequent\nupdates. Values are encrypted at rest and only become visible\nto the running handler on the next deploy (`PUT /functions/{id}`\nwith the existing code is sufficient to refresh bindings).\n\nKeys must match `^[A-Z_][A-Z0-9_]*$` (uppercase letters,\ndigits, underscores; first character is a letter or\nunderscore). Values are at most 4096 UTF-8 bytes. System-\nmanaged keys are reserved and rejected.\n",
+                "tags": [
+                    "Functions"
+                ],
+                "requestBody": {
+                    "required": true,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/CreateFunctionSecretInput"
+                            }
+                        }
+                    }
+                },
+                "responses": {
+                    "200": {
+                        "description": "Secret updated",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "allOf": [
+                                        {
+                                            "$ref": "#/components/schemas/SuccessEnvelope"
+                                        },
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "data": {
+                                                    "$ref": "#/components/schemas/FunctionSecretWriteResult"
+                                                }
+                                            }
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "201": {
+                        "description": "Secret created",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "allOf": [
+                                        {
+                                            "$ref": "#/components/schemas/SuccessEnvelope"
+                                        },
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "data": {
+                                                    "$ref": "#/components/schemas/FunctionSecretWriteResult"
+                                                }
+                                            }
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "$ref": "#/components/responses/ValidationError"
+                    },
+                    "401": {
+                        "$ref": "#/components/responses/Unauthorized"
+                    },
+                    "404": {
+                        "$ref": "#/components/responses/NotFound"
+                    }
+                }
+            }
+        },
+        "/functions/{id}/secrets/{key}": {
+            "parameters": [
+                {
+                    "$ref": "#/components/parameters/ResourceId"
+                },
+                {
+                    "name": "key",
+                    "in": "path",
+                    "required": true,
+                    "description": "Secret key. Must match `^[A-Z_][A-Z0-9_]*$`.",
+                    "schema": {
+                        "type": "string",
+                        "pattern": "^[A-Z_][A-Z0-9_]*$"
+                    }
+                }
+            ],
+            "put": {
+                "operationId": "setFunctionSecret",
+                "summary": "Set a secret by key",
+                "description": "Path-keyed companion to `POST /functions/{id}/secrets`.\nIdempotent: returns 201 the first time the key is set, 200 on\nsubsequent updates. Same validation rules and same write-only\nguarantees as the POST verb; the new value lands in the running\nhandler on the next deploy.\n",
+                "tags": [
+                    "Functions"
+                ],
+                "requestBody": {
+                    "required": true,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/SetFunctionSecretInput"
+                            }
+                        }
+                    }
+                },
+                "responses": {
+                    "200": {
+                        "description": "Secret updated",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "allOf": [
+                                        {
+                                            "$ref": "#/components/schemas/SuccessEnvelope"
+                                        },
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "data": {
+                                                    "$ref": "#/components/schemas/FunctionSecretWriteResult"
+                                                }
+                                            }
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "201": {
+                        "description": "Secret created",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "allOf": [
+                                        {
+                                            "$ref": "#/components/schemas/SuccessEnvelope"
+                                        },
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "data": {
+                                                    "$ref": "#/components/schemas/FunctionSecretWriteResult"
                                                 }
                                             }
                                         }
@@ -2094,6 +2610,28 @@ export const openapiDocument = {
                         "$ref": "#/components/responses/NotFound"
                     }
                 }
+            },
+            "delete": {
+                "operationId": "deleteFunctionSecret",
+                "summary": "Delete a secret",
+                "description": "Removes the secret. The binding stays live in the running\nhandler until the next deploy refreshes the binding set\n(`PUT /functions/{id}` with the existing code is sufficient).\nReturns 404 if the key did not exist. Managed system keys\ncannot be deleted.\n",
+                "tags": [
+                    "Functions"
+                ],
+                "responses": {
+                    "204": {
+                        "description": "Secret deleted"
+                    },
+                    "400": {
+                        "$ref": "#/components/responses/ValidationError"
+                    },
+                    "401": {
+                        "$ref": "#/components/responses/Unauthorized"
+                    },
+                    "404": {
+                        "$ref": "#/components/responses/NotFound"
+                    }
+                }
             }
         }
     },
@@ -4318,6 +4856,339 @@ export const openapiDocument = {
                     "discarded",
                     "already_discarded"
                 ]
+            },
+            "FunctionDeployStatus": {
+                "type": "string",
+                "enum": [
+                    "pending",
+                    "deployed",
+                    "failed"
+                ],
+                "description": "Lifecycle state of the latest deploy attempt:\n  * `pending` — deploy in flight; the runtime has not yet\n    confirmed the new bundle is live.\n  * `deployed` — the running edge handler is the latest code.\n  * `failed` — the most recent deploy attempt failed; the\n    previously-live code (if any) is still running. The\n    `deploy_error` field carries the error message.\n"
+            },
+            "FunctionListItem": {
+                "type": "object",
+                "description": "One row from the function listing.",
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "format": "uuid",
+                        "description": "Function id, also the script name in the edge runtime."
+                    },
+                    "name": {
+                        "type": "string",
+                        "description": "Slug-style name set on creation. Stable; cannot be changed."
+                    },
+                    "deploy_status": {
+                        "$ref": "#/components/schemas/FunctionDeployStatus"
+                    },
+                    "deployed_at": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "format": "date-time",
+                        "description": "Timestamp of the most recent successful deploy. Null until the first deploy succeeds."
+                    },
+                    "gateway_url": {
+                        "type": "string",
+                        "format": "uri",
+                        "description": "URL the platform's webhook delivery loop posts to in order\nto invoke the function. Reference only; not directly\ncallable from outside.\n"
+                    },
+                    "created_at": {
+                        "type": "string",
+                        "format": "date-time"
+                    },
+                    "updated_at": {
+                        "type": "string",
+                        "format": "date-time"
+                    }
+                },
+                "required": [
+                    "id",
+                    "name",
+                    "deploy_status",
+                    "gateway_url",
+                    "created_at",
+                    "updated_at"
+                ]
+            },
+            "FunctionDetail": {
+                "type": "object",
+                "description": "Full function record returned by GET / PUT.",
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "format": "uuid"
+                    },
+                    "name": {
+                        "type": "string"
+                    },
+                    "code": {
+                        "type": "string",
+                        "description": "The bundled handler source. UTF-8 string up to 1 MiB. The\nsame value most recently passed as `code` to POST or PUT.\n"
+                    },
+                    "deploy_status": {
+                        "$ref": "#/components/schemas/FunctionDeployStatus"
+                    },
+                    "deploy_error": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "description": "Error message from the most recent failed deploy, or null\nafter a successful deploy. Surface this to users to explain\na `failed` status without polling.\n"
+                    },
+                    "deployed_at": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "format": "date-time"
+                    },
+                    "gateway_url": {
+                        "type": "string",
+                        "format": "uri"
+                    },
+                    "created_at": {
+                        "type": "string",
+                        "format": "date-time"
+                    },
+                    "updated_at": {
+                        "type": "string",
+                        "format": "date-time"
+                    }
+                },
+                "required": [
+                    "id",
+                    "name",
+                    "code",
+                    "deploy_status",
+                    "gateway_url",
+                    "created_at",
+                    "updated_at"
+                ]
+            },
+            "CreateFunctionInput": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "pattern": "^[a-z0-9_-]{1,64}$",
+                        "description": "Slug-style name. Lowercase letters, digits, hyphens, and\nunderscores. 1 to 64 characters. Must be unique within the\norg; a 409 is returned on collision.\n"
+                    },
+                    "code": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 1048576,
+                        "description": "Bundled handler as a single ESM module. Up to 1 MiB UTF-8.\nMust export a default `{ async fetch(req, env, ctx) { ... } }`\nobject.\n"
+                    },
+                    "sourceMap": {
+                        "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"
+                    }
+                },
+                "required": [
+                    "name",
+                    "code"
+                ]
+            },
+            "CreateFunctionResult": {
+                "type": "object",
+                "description": "Returned by POST /functions on a successful deploy.",
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "format": "uuid"
+                    },
+                    "name": {
+                        "type": "string"
+                    },
+                    "deploy_status": {
+                        "$ref": "#/components/schemas/FunctionDeployStatus"
+                    },
+                    "gateway_url": {
+                        "type": "string",
+                        "format": "uri"
+                    }
+                },
+                "required": [
+                    "id",
+                    "name",
+                    "deploy_status",
+                    "gateway_url"
+                ]
+            },
+            "UpdateFunctionInput": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                    "code": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 1048576,
+                        "description": "New bundled handler. Same rules as CreateFunctionInput.code."
+                    },
+                    "sourceMap": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 5242880
+                    }
+                },
+                "required": [
+                    "code"
+                ]
+            },
+            "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",
+                "properties": {
+                    "inbound_domain": {
+                        "type": "string",
+                        "description": "Verified inbound domain the test email was sent to."
+                    },
+                    "to": {
+                        "type": "string",
+                        "description": "Synthetic local-part plus inbound_domain. Visible in the org's inbox."
+                    },
+                    "from": {
+                        "type": "string",
+                        "description": "Primitive-controlled outbound sender used for the test."
+                    },
+                    "send_id": {
+                        "type": "string",
+                        "description": "Outbound message id from the underlying send. NOT the\ninbound email's id; the inbound id is created when the\nemail arrives via MX and lands on the function's\ninvocations list.\n"
+                    },
+                    "subject": {
+                        "type": "string",
+                        "description": "Subject placed on the test email so it can be located in the inbox."
+                    },
+                    "poll_since": {
+                        "type": "string",
+                        "format": "date-time",
+                        "description": "ISO timestamp suitable as a `since` lower bound when\npolling /emails for the inbound's arrival. Captured\nslightly before the send to absorb light clock skew.\n"
+                    },
+                    "watch_url": {
+                        "type": "string",
+                        "format": "uri",
+                        "description": "Function detail page where invocations show up live."
+                    }
+                },
+                "required": [
+                    "inbound_domain",
+                    "to",
+                    "from",
+                    "send_id",
+                    "subject",
+                    "poll_since",
+                    "watch_url"
+                ]
+            },
+            "FunctionSecretListItem": {
+                "type": "object",
+                "description": "One row from GET /functions/{id}/secrets. Discriminate on the\n`managed` field:\n  * `managed = true`  — system secret provisioned by Primitive.\n    `description` is set; `created_at` / `updated_at` are\n    null because the row is virtual (resolved at deploy time\n    from the managed registry, not stored in the secrets\n    table).\n  * `managed = false` — secret the user set via the API.\n    `created_at` / `updated_at` are set; `description` is\n    null.\n",
+                "properties": {
+                    "key": {
+                        "type": "string"
+                    },
+                    "managed": {
+                        "type": "boolean",
+                        "description": "True for managed system secrets, false for user-set entries."
+                    },
+                    "description": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "description": "Set on managed entries only; null on user-set entries."
+                    },
+                    "created_at": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "format": "date-time",
+                        "description": "Set on user-set entries only; null on managed entries."
+                    },
+                    "updated_at": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "format": "date-time",
+                        "description": "Set on user-set entries only; null on managed entries."
+                    }
+                },
+                "required": [
+                    "key",
+                    "managed"
+                ]
+            },
+            "CreateFunctionSecretInput": {
+                "type": "object",
+                "additionalProperties": false,
+                "description": "Body for POST /functions/{id}/secrets.",
+                "properties": {
+                    "key": {
+                        "type": "string",
+                        "pattern": "^[A-Z_][A-Z0-9_]*$",
+                        "description": "Uppercase letters, digits, and underscores. Must start with\na letter or underscore. System-managed keys (e.g.\nPRIMITIVE_WEBHOOK_SECRET) are reserved.\n"
+                    },
+                    "value": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 4096,
+                        "description": "Secret value, up to 4096 UTF-8 bytes. Encrypted at rest.\nNever returned by any read endpoint.\n"
+                    }
+                },
+                "required": [
+                    "key",
+                    "value"
+                ]
+            },
+            "SetFunctionSecretInput": {
+                "type": "object",
+                "additionalProperties": false,
+                "description": "Body for PUT /functions/{id}/secrets/{key}. Key comes from the path.",
+                "properties": {
+                    "value": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 4096
+                    }
+                },
+                "required": [
+                    "value"
+                ]
+            },
+            "FunctionSecretWriteResult": {
+                "type": "object",
+                "description": "Returned by POST and PUT secret routes.",
+                "properties": {
+                    "key": {
+                        "type": "string"
+                    },
+                    "created_at": {
+                        "type": "string",
+                        "format": "date-time"
+                    },
+                    "updated_at": {
+                        "type": "string",
+                        "format": "date-time"
+                    },
+                    "created": {
+                        "type": "boolean",
+                        "description": "True if this call inserted a new row, false if it updated an existing one."
+                    }
+                },
+                "required": [
+                    "key",
+                    "created_at",
+                    "updated_at",
+                    "created"
+                ]
             }
         }
     }