@openemail/cli 0.0.1 → 0.0.3

package/README.md

@@ -126,7 +126,7 @@ openemail temp read
 openemail temp delete --yes
 ```
 
-A disposable inbox needs no account and no key. `temp new` prints the address, and the CLI keeps the inbox's token so the other `temp` commands find it by its id or address. `temp watch --first` waits for the first message, which suits a script waiting for a sign-up code.
+A disposable inbox needs no account and no key. `temp new` prints the address, and the CLI keeps the inbox's token so the other `temp` commands find it by its id or address. `temp watch --first` waits for the first message, which suits a script waiting for a sign-up code. `temp-mail extend` adds up to an hour, within 24 hours of the inbox being created, and the CLI keeps the new token it returns. `temp delete` moves the mail to the bin and forgets the token here, while the lease runs on until it expires.
 
 ### Every resource
 ```bash

package/openemail.js

@@ -344,7 +344,8 @@ const CLI_CALLBACK = {
     APP_PATH: '/cli/callback',
     LOOPBACK_PATH: '/callback',
     LOOPBACK_HOST: '127.0.0.1',
-    PASTE_SEPARATOR: '.'};
+    PASTE_SEPARATOR: '.'
+};
 const OAUTH_PARAMS = {
     RESPONSE_TYPE: 'response_type',
     CLIENT_ID: 'client_id',
@@ -672,7 +673,7 @@ const AUTH_MESSAGES = {
         : `OpenEmail could not refresh your sign-in (status ${status}). Try again shortly.`,
     SESSION_EXPIRED_PROFILE_NEXT: (name) => `Run \`openemail login --profile ${name}\` again.`,
     SERVER_SAID: (reason) => `The server said: ${reason}`,
-    CLIENT_NAME: (host) => `OpenEmail CLI on ${host}`,
+    CLIENT_NAME: (host) => `${OAUTH_CLIENT.NAME_PREFIX}${host}`,
     WHO_WORKSPACE: (workspace) => `workspace ${workspace}`,
     WHO_KEY: (keyId) => `key ${keyId}`,
     KEY_STAYS_VALID: (keyId) => `The key itself still works. Revoke it with \`openemail keys revoke ${keyId}\` if you no longer need it.`,
@@ -818,7 +819,6 @@ const DOCS_CHAT = {
 };
 const DOCS_PATHS = {
     DOCS: '/docs',
-    DOCS_PREFIX: 'docs/',
     MARKDOWN_EXTENSION: '.md',
     INDEX: '/llms.txt',
     ANCHOR: '#',
@@ -829,7 +829,8 @@ const DOCS_PATTERNS = {
     LEADING_SLASHES: /^\/+/,
     TRAILING_SLASHES: /\/+$/,
     LINE_BREAK: /\r?\n/,
-    DOT_SEGMENT: /^\.{1,2}$/
+    DOT_SEGMENT: /^\.{1,2}$/,
+    DOCS_PREFIX: /^(?:[a-z]{2}\/)?docs(?:\/|$)/i
 };
 const DOCS_FETCH = {
     ACCEPT: 'text/markdown, text/plain;q=0.9',
@@ -1111,7 +1112,7 @@ const BOOLEAN_TRUE_WORDS = new Set(['true', '1', 'yes', 'on']);
 const BOOLEAN_FALSE_WORDS = new Set(['false', '0', 'no', 'off']);
 const NEGATIVE_NUMBER_PATTERN = /^-\d+(\.\d+)?$/;
 
-var version$1 = "0.0.1";
+var version$1 = "0.0.3";
 
 const VERSION$1 = version$1;
 const CLI_NAME = 'openemail';
@@ -1244,7 +1245,7 @@ const SCRIPTING_ROWS = [
 const HELP_JSON_SCHEMA_VERSION = 1;
 const CLI_NAME_WORD_PATTERN = new RegExp(`(^|[^\\w-])${CLI_NAME}($|[^\\w-])`);
 
-var version = "0.0.5";
+var version = "0.0.7";
 
 const BUILD_BASE_URL = 'https://api.openemail.uk';
 
@@ -3495,7 +3496,7 @@ const DomainsCreateAddressMethod = {
     scopes: ['domains:write'],
     parameters: [
         { name: 'id', type: 'string', required: true, description: 'Domain id from `list` or `create`, a UUID.' },
-        { name: 'body.localPart', type: 'string', required: true, description: 'The part in front of the @, 1 to 64 characters once trimmed, lower cased. Letters, digits and ! # $ % & \' * + / = ? ^ _ ` { | } ~ - are allowed, and so are dots between them. `*` on its own is how the catch-all is written and is refused.' },
+        { name: 'body.localPart', type: 'string', required: true, description: 'The part in front of the @, 1 to 64 characters once trimmed, lower cased. Letters, digits, the backtick and ! # $ % & \' * + / = ? ^ _ { | } ~ - are allowed, and so are dots between them. `*` on its own is how the catch-all is written and is refused.' },
         { name: 'body.label', type: 'string | null', required: false, description: 'A name for the address shown in the app, trimmed, up to 120 characters. Leave it out, or send null or an empty string, for none.' },
         { name: 'options.signal', type: 'AbortSignal', required: false, description: 'Cancels the request.' },
         { name: 'options.apiKey', type: 'string', required: false, description: 'Overrides the client\'s API key for this call only.' }
@@ -7500,14 +7501,14 @@ const TempMailCreateMethod = {
     slug: 'temp-mail/create',
     signature: 'create(body?: TempInboxCreate, options?: InboxScope): Promise<CreatedTempInboxResource>',
     summary: 'Create a disposable inbox and its access token',
-    description: 'Mints a disposable address and resolves with the inbox plus its `token`. It needs no credential, and this is the only response that ever carries the token. The server keeps only an HMAC of it, so a lost token cannot be recovered, and every other method except `listDomains` needs it. Store it before you show the address to anyone.\n\nThe body is optional and so is every field in it. With nothing, you get a 12 character generated local part on a domain picked at random from the pool, leased for 60 minutes. A chosen `localPart` is lowercased and must be 3 to 32 letters, digits, dots, dashes or underscores, starting and ending with a letter or digit, or it is 422 `invalid_address`. Names such as `postmaster`, `abuse` and `support` are 422 `reserved_address`, and an address the domain owner created as a real mailbox is 409 `address_taken`.\n\nMinting is capped per client IP at 6 inboxes an hour and 30 a day, so a shared network shares the ceiling, and going past it is 429 `too_many_inboxes`. Extending an inbox you already hold costs nothing against that cap, which makes `extend` the intended answer to a 429.',
+    description: 'Mints a disposable address and resolves with the inbox plus its `token`. It needs no credential, and only this call and `extend` return a token. The token is the lease itself, signed, and nothing about it is stored on the server, so a lost token cannot be recovered, and every other method except `listDomains` needs it. Store it before you show the address to anyone.\n\nThe body is optional and so is every field in it. With nothing, you get a 12 character generated local part on the first domain in the pool, leased for 60 minutes. A chosen `localPart` is lowercased and must be up to 64 letters, digits, dots, dashes or underscores, starting and ending with a letter or digit, or it is 422 `invalid_address`, and one longer than 64 characters is 422 `invalid_parameter`. Names such as `postmaster`, `abuse` and `support` are 422 `reserved_address`, and an install with no pooled domain answers 503 `not_configured`.\n\nNothing is rate limited and nothing reserves an address, so this never answers 429 or 409. A name you choose is issued to anyone who asks for it, and each of you reads the mail that reaches it from the start of your own lease. Leave `localPart` out when the mail should reach you alone.',
     method: 'POST',
     path: '/temp-mail/inboxes',
     scopes: [],
     auth: 'none',
     parameters: [
-        { name: 'body.domain', type: 'string', required: false, description: 'A domain from `listDomains`. Omit it for a random pick. Any other name is 422 `unknown_domain` rather than a silent substitute.' },
-        { name: 'body.localPart', type: 'string', required: false, description: 'The part before the @. Omit it for a generated one, which cannot collide.' },
+        { name: 'body.domain', type: 'string', required: false, description: 'A domain from `listDomains`. Omit it for the first one in the pool. Any other name is 422 `unknown_domain` rather than a silent substitute.' },
+        { name: 'body.localPart', type: 'string', required: false, description: 'The part before the @. Omit it for a generated one, which nobody else is likely to be issued.' },
         { name: 'body.ttlMinutes', type: 'number', required: false, description: 'Lease length from now, a whole number from 1 to 1440. Defaults to 60. Out of range is 422 `invalid_parameter`, not clamped.' },
         { name: 'options.signal', type: 'AbortSignal', required: false, description: 'Cancels the request.' },
         { name: 'options.inboxToken', type: 'string', required: false, description: 'Ignored and never sent. Creating an inbox is anonymous and hands you the token instead.' }
@@ -7516,8 +7517,8 @@ const TempMailCreateMethod = {
     example: 'const temp = createTempMail()\n\nconst inbox = await temp.create({ ttlMinutes: 120 })\n\nconsole.log(inbox.address, inbox.expiresAt)\nconsole.log(inbox.token)',
     notes: [
         'Not retried automatically. A retry would mint a second inbox, and the first would be unreachable because its only token was in the lost response.',
-        'A destroyed or expired address stays reserved until 7 days after its lease end, so asking for it again in that window is 409 `address_taken`.',
-        'A lease of 1440 minutes reaches the 24 hour ceiling at once, so the inbox comes back with `extensionsLeft: 0`.',
+        'Nothing holds an address back after its lease ends or its inbox is deleted, so it can be issued again at once, to anybody.',
+        'A lease of 1440 minutes reaches the 24 hour ceiling at once, yet the inbox still comes back with `extensionsLeft: 23`, because that counts calls rather than time. None of them can add a minute.',
         'Unknown body keys are 422 `invalid_parameter`, while a body that is not valid JSON is treated as an empty one.'
     ]
 };
@@ -7529,21 +7530,21 @@ const TempMailDeleteMessageMethod = {
     slug: 'temp-mail/deleteMessage',
     signature: 'deleteMessage(inboxId: string, messageId: string, options?: InboxScope): Promise<DeletedTempMessageResource>',
     summary: 'Delete one message from a disposable inbox',
-    description: 'Removes the message row, its stored body and its attachments immediately. There is no undo and no bin, since a disposable inbox has no folders.\n\n`messageCount` goes down by one. There is never a slot to free: an inbox keeps every message that reaches it, and `listMessages` pages through all of them.',
+    description: 'Moves the message, attachments and all, to the bin of the mailbox that runs the pool, and no lease lists or opens it again. Nothing in this SDK restores it.\n\n`messageCount` goes down by one. There is never a slot to free: an inbox keeps every message that reaches it, and `listMessages` pages through all of them.',
     method: 'DELETE',
     path: '/temp-mail/inboxes/{id}/messages/{messageId}',
     scopes: [],
     auth: 'inboxToken',
     parameters: [
-        { name: 'inboxId', type: 'string', required: true, description: 'The `tinb_` id `create` returned. It must name the same inbox as the token, or the answer is a 404.' },
-        { name: 'messageId', type: 'string', required: true, description: 'A `tmail_` id from `listMessages`.' },
+        { name: 'inboxId', type: 'string', required: true, description: 'The `tinb_` id `create` returned. It is not checked against the token, which alone decides the inbox.' },
+        { name: 'messageId', type: 'string', required: true, description: 'An `id` from `listMessages`, such as `thr_` and 24 hex.' },
         { name: 'options.signal', type: 'AbortSignal', required: false, description: 'Cancels the request.' },
         { name: 'options.inboxToken', type: 'string', required: false, description: 'The `oe_inbox_` token `create` returned. Overrides the token given to `createTempMail` for this call, and is required on the `OpenEmail` client, which would otherwise send its API key.' }
     ],
     returns: '`DeletedTempMessageResource` with `object` set to `temp_message`, the message `id` and `deleted: true`.',
     example: 'const temp = createTempMail()\n\nconst inbox = await temp.create()\n\nconst { items } = await temp.listMessages(inbox.id, { inboxToken: inbox.token })\n\nfor (const message of items.filter((row) => row.spam)) {\n    await temp.deleteMessage(inbox.id, message.id, { inboxToken: inbox.token })\n}',
     notes: [
-        'An unknown or already deleted message id is 404 `resource_not_found`.',
+        'An unknown or already deleted message id is 404 `resource_not_found`, and an install with no key to read the pool answers 503 `not_configured`.',
         'Not retried automatically. If you repeat it yourself after a lost response, that 404 means the first attempt already worked.'
     ]
 };
@@ -7554,14 +7555,14 @@ const TempMailDeleteMethod = {
     accessor: 'openemail.tempMail.delete',
     slug: 'temp-mail/delete',
     signature: 'delete(inboxId: string, options?: InboxScope): Promise<DeletedTempInboxResource>',
-    summary: 'Destroy a disposable inbox and its mail now',
-    description: 'Deletes every message, stored body and attachment in the inbox immediately rather than at the next sweep, and the token stops authenticating on the very next request. There is no undo and nothing is archived.\n\nThe address is not released. The inbox is kept as a tombstone until 7 days after its lease would have ended, so the local part cannot be issued to someone else while a slow sender may still be delivering to it. Creating the same address in that window is 409 `address_taken`, and mail that arrives for it is dropped.\n\nThe response is a tombstone rather than an empty body, so a log line can name what went.',
+    summary: 'Move the mail in a disposable inbox to the bin now',
+    description: 'Moves every message the inbox shows to the bin of the mailbox that runs the pool, at once. It does not end the lease: nothing about a lease is stored, so there is nothing to revoke, and the token keeps opening the address until its expiry. Mail that arrives afterwards is listed as usual.\n\nNothing holds the address back either, so it can be issued again at once, to anybody. An install with no key to read the pool answers 503 `not_configured`.\n\nThe response is a tombstone rather than an empty body, so a log line can name what went.',
     method: 'DELETE',
     path: '/temp-mail/inboxes/{id}',
     scopes: [],
     auth: 'inboxToken',
     parameters: [
-        { name: 'inboxId', type: 'string', required: true, description: 'The `tinb_` id `create` returned. It must name the same inbox as the token, or the answer is a 404.' },
+        { name: 'inboxId', type: 'string', required: true, description: 'The `tinb_` id `create` returned. It is not checked against the token, which alone decides the inbox.' },
         { name: 'options.signal', type: 'AbortSignal', required: false, description: 'Cancels the request.' },
         { name: 'options.inboxToken', type: 'string', required: false, description: 'The `oe_inbox_` token `create` returned. Overrides the token given to `createTempMail` for this call, and is required on the `OpenEmail` client, which would otherwise send its API key.' }
     ],
@@ -7569,7 +7570,7 @@ const TempMailDeleteMethod = {
     example: 'const temp = createTempMail()\n\nconst inbox = await temp.create()\n\nconst result = await temp.delete(inbox.id, { inboxToken: inbox.token })\n\nconsole.log(result.destroyed)',
     notes: [
         'The flag is `destroyed`, not `deleted` as on other tombstones.',
-        'Not retried automatically. If you repeat it yourself after a lost response, a 404 `resource_not_found` means the first attempt already destroyed the inbox.'
+        'Not retried automatically. Repeating it is harmless: the lease still stands, so a second call answers 200 and moves whatever has arrived since.'
     ]
 };
 
@@ -7578,23 +7579,23 @@ const TempMailExtendMethod = {
     name: 'extend',
     accessor: 'openemail.tempMail.extend',
     slug: 'temp-mail/extend',
-    signature: 'extend(inboxId: string, options?: InboxScope): Promise<TempInboxResource>',
+    signature: 'extend(inboxId: string, options?: InboxScope): Promise<ExtendedTempInboxResource>',
     summary: 'Push the expiry of an inbox an hour further out',
-    description: 'Adds up to 60 minutes to `expiresAt` and resolves with the updated inbox. There is no body.\n\nThe cap is on the whole lease, not on the number of calls. The new expiry is the earlier of one hour past the current expiry and 24 hours after `createdAt`, and a lease allows at most 23 extensions. The last extension therefore often buys less than an hour, and an inbox created with a long `ttlMinutes` has fewer to spend. `extensionsLeft` accounts for both limits, so read it from the response rather than counting calls.\n\nWhen `extensionsLeft` is 0 this answers 409 `extension_limit` for good, and the only way on is a new inbox. Extending does not reset the 50 message ceiling and does not count against the minting limit on `create`.',
+    description: 'Adds up to 60 minutes to `expiresAt` and resolves with the updated inbox and a new `token` that carries the later expiry. There is no body. The old token keeps its old expiry, so use the new one from here on, including in a client built with `createTempMail({ inboxToken })`.\n\nThe new expiry is the earlier of one hour past the current expiry and 24 hours after `createdAt`, and a lease allows at most 23 extensions. The last extension can buy less than an hour, and on a lease that already reaches the 24 hours a call still succeeds, spends an extension and buys nothing. `extensionsLeft` counts only the 23 calls, so compare `expiresAt` with `createdAt` before offering more time.\n\nWhen `extensionsLeft` is 0 this answers 422 `extension_limit` for good, and the only way on is a new inbox. The response reads no mail, so its `messageCount` is 0 and its `lastMessageAt` is null.',
     method: 'POST',
     path: '/temp-mail/inboxes/{id}/extend',
     scopes: [],
     auth: 'inboxToken',
     parameters: [
-        { name: 'inboxId', type: 'string', required: true, description: 'The `tinb_` id `create` returned. It must name the same inbox as the token, or the answer is a 404.' },
+        { name: 'inboxId', type: 'string', required: true, description: 'The `tinb_` id `create` returned. It is not checked against the token, which alone decides the inbox.' },
         { name: 'options.signal', type: 'AbortSignal', required: false, description: 'Cancels the request.' },
         { name: 'options.inboxToken', type: 'string', required: false, description: 'The `oe_inbox_` token `create` returned. Overrides the token given to `createTempMail` for this call, and is required on the `OpenEmail` client, which would otherwise send its API key.' }
     ],
-    returns: '`TempInboxResource` with the new `expiresAt` and the updated `extensionsLeft`.',
-    example: 'const temp = createTempMail({ inboxToken: \'oe_inbox_Vb3kT9qLm2Xw7RzN4pYc6HfJ1sGa5Ed8KuQo0iWnS2e\' })\n\nconst inbox = await temp.extend(\'tinb_5d2a8f1c7e4b9a30d6c1f8e2\')\n\nconsole.log(inbox.expiresAt, inbox.extensionsLeft)',
+    returns: '`ExtendedTempInboxResource`: the `TempInboxResource` fields with the new `expiresAt` and the updated `extensionsLeft`, plus the new `token` beginning `oe_inbox_`.',
+    example: 'const temp = createTempMail({ inboxToken: \'oe_inbox_Vb3kT9qLm2Xw7RzN4pYc6HfJ1sGa5Ed8KuQo0iWnS2e\' })\n\nconst inbox = await temp.extend(\'tinb_k7m2q9xw4bdp\')\n\nconsole.log(inbox.expiresAt, inbox.extensionsLeft)\n\nconst renewed = createTempMail({ inboxToken: inbox.token })',
     notes: [
         'Not retried automatically, because a replay would spend a second extension.',
-        'An inbox created with `ttlMinutes: 1440` has `extensionsLeft: 0` from the start.'
+        'An inbox created with `ttlMinutes: 1440` still reports `extensionsLeft: 23`, and none of them can add a minute.'
     ]
 };
 
@@ -7605,21 +7606,21 @@ const TempMailGetMessageMethod = {
     slug: 'temp-mail/getMessage',
     signature: 'getMessage(inboxId: string, messageId: string, options?: InboxScope): Promise<TempMessageDetailResource>',
     summary: 'Read one message with its stored body',
-    description: 'Resolves the list row for one message plus the parsed message as stored. Reading marks the message seen, so `seen` on this response is always true and the next `listMessages` agrees. There is no way to read without marking, and nothing on the server depends on the flag.\n\nRender `message.decodedBody`. `body` and `processedHtml` are empty strings for every message that can reach a disposable inbox, so a client reading either shows a blank page. Bodies over 2 MB are cut at that size, so check `truncated` before treating the content as the whole message.\n\nThe HTML came from a stranger to an address anyone could name. Render it outside your own origin, for example in a sandboxed iframe.',
+    description: 'Resolves the list row for one message plus the parsed message as stored. Reading it does not mark it seen: `seen` mirrors the unread state of the message in the mailbox that runs the pool, and nothing on these routes changes it.\n\nRender `message.decodedBody`. `body` and `processedHtml` are empty strings for every message that can reach a disposable inbox, so a client reading either shows a blank page. The body is never cut, so `truncated` is always false.\n\nThe HTML came from a stranger to an address anyone could name. Render it outside your own origin, for example in a sandboxed iframe.',
     method: 'GET',
     path: '/temp-mail/inboxes/{id}/messages/{messageId}',
     scopes: [],
     auth: 'inboxToken',
     parameters: [
-        { name: 'inboxId', type: 'string', required: true, description: 'The `tinb_` id `create` returned. It must name the same inbox as the token, or the answer is a 404.' },
-        { name: 'messageId', type: 'string', required: true, description: 'A `tmail_` id from `listMessages`.' },
+        { name: 'inboxId', type: 'string', required: true, description: 'The `tinb_` id `create` returned. It is not checked against the token, which alone decides the inbox.' },
+        { name: 'messageId', type: 'string', required: true, description: 'An `id` from `listMessages`, such as `thr_` and 24 hex.' },
         { name: 'options.signal', type: 'AbortSignal', required: false, description: 'Cancels the request.' },
         { name: 'options.inboxToken', type: 'string', required: false, description: 'The `oe_inbox_` token `create` returned. Overrides the token given to `createTempMail` for this call, and is required on the `OpenEmail` client, which would otherwise send its API key.' }
     ],
     returns: '`TempMessageDetailResource`: every `TempMessageResource` field plus `message`, the stored parsed message, and `truncated`.',
-    example: 'const temp = createTempMail({ inboxToken: \'oe_inbox_Vb3kT9qLm2Xw7RzN4pYc6HfJ1sGa5Ed8KuQo0iWnS2e\' })\n\nconst detail = await temp.getMessage(\'tinb_5d2a8f1c7e4b9a30d6c1f8e2\', \'tmail_9e3b7c1a5f2d8e40b6a9c3f1\')\n\nconsole.log(detail.subject, detail.truncated)\nconsole.log(detail.message.decodedBody)',
+    example: 'const temp = createTempMail({ inboxToken: \'oe_inbox_Vb3kT9qLm2Xw7RzN4pYc6HfJ1sGa5Ed8KuQo0iWnS2e\' })\n\nconst detail = await temp.getMessage(\'tinb_k7m2q9xw4bdp\', \'thr_9e3b7c1a5f2d8e40b6a9c3f1\')\n\nconsole.log(detail.subject, detail.truncated)\nconsole.log(detail.message.decodedBody)',
     notes: [
-        'An unknown or deleted message id is 404 `resource_not_found`, the same answer as an expired inbox.',
+        'A message this lease cannot see, deleted ones included, is 404 `resource_not_found`. An expired lease is 401 `inbox_expired`, and an install with no key to read the pool answers 503 `not_configured`.',
         '`message` is typed as a loose record, so narrow `decodedBody` to a string before rendering it.'
     ]
 };
@@ -7631,20 +7632,20 @@ const TempMailGetMethod = {
     slug: 'temp-mail/get',
     signature: 'get(inboxId: string, options?: InboxScope): Promise<TempInboxResource>',
     summary: 'Read the lease and counters of a disposable inbox',
-    description: 'Resolves the inbox with its expiry, remaining extensions and message counters, without any messages. To watch an inbox, poll `listMessages` instead: it returns `expiresAt` alongside the mail, so one request covers both.\n\nThis call is authorised by the inbox token, never by an API key. A workspace key sent in its place is refused with 401 `invalid_credential_type`, and no scope on any key reaches this resource. The id in the path must be the inbox the token belongs to.\n\nOnce the lease is over the inbox is gone rather than read only. An expired, destroyed, foreign or unknown inbox all answer the same 404 `resource_not_found`.',
+    description: 'Resolves the inbox with its expiry, remaining extensions and message counters, without any messages. To watch an inbox, poll `listMessages` instead: it returns `expiresAt` alongside the mail, so one request covers both.\n\nThis call is authorised by the inbox token, never by an API key. A workspace key sent in its place is refused with 401 `missing_inbox_token`, and no scope on any key reaches this resource. The token alone decides which inbox is read, and the id in the path is not checked against it.\n\nOnce the lease is over the token answers 401 `inbox_expired`, and a token this server did not sign answers 404 `resource_not_found`. Deleting an inbox does not end its lease, so its token still reads it. `messageCount` is counted by reading every page, and is 0 when the install cannot read the mailbox that runs the pool.',
     method: 'GET',
     path: '/temp-mail/inboxes/{id}',
     scopes: [],
     auth: 'inboxToken',
     parameters: [
-        { name: 'inboxId', type: 'string', required: true, description: 'The `tinb_` id `create` returned. It must name the same inbox as the token, or the answer is a 404.' },
+        { name: 'inboxId', type: 'string', required: true, description: 'The `tinb_` id `create` returned. It is not checked against the token, which alone decides the inbox.' },
         { name: 'options.signal', type: 'AbortSignal', required: false, description: 'Cancels the request.' },
         { name: 'options.inboxToken', type: 'string', required: false, description: 'The `oe_inbox_` token `create` returned. Overrides the token given to `createTempMail` for this call, and is required on the `OpenEmail` client, which would otherwise send its API key.' }
     ],
     returns: '`TempInboxResource` with `id`, `address`, `domain`, `createdAt`, `expiresAt`, `extensionsLeft`, `messageCount`, `messageLimit` and `lastMessageAt`.',
     example: 'const temp = createTempMail()\n\nconst created = await temp.create()\n\nconst inbox = await temp.get(created.id, { inboxToken: created.token })\n\nconsole.log(inbox.expiresAt, inbox.messageCount, inbox.messageLimit)',
     notes: [
-        'A token that is mistyped or not an inbox token at all is a 404, not a 401. Only a missing token and a workspace API key get 401.',
+        'A token that does not start with `oe_inbox_` is 401 `missing_inbox_token`, the same as no token at all. One that starts with it but was not signed by this server is 404 `resource_not_found`.',
         '`messageCount` counts every message the inbox is showing, across every page, and goes down when one is deleted. `messageLimit`, which is 50, is the page size of `listMessages`, not a ceiling: nothing past it is dropped.'
     ]
 };
@@ -7708,23 +7709,23 @@ const TempMailListAttachmentsMethod = {
     name: 'listAttachments',
     accessor: 'openemail.tempMail.listAttachments',
     slug: 'temp-mail/listAttachments',
-    signature: 'listAttachments(inboxId: string, messageId: string, options?: InboxScope): Promise<Array<AttachmentResource>>',
-    summary: 'Read the attachments of a message with their bytes',
-    description: 'Resolves every attachment on a message as a plain array, metadata and content together, with the bytes base64 encoded in `content`. There is no per attachment fetch.\n\n`content` is null when a part was over the 8 MB storage ceiling and its bytes were never kept. That is not an empty file, and the metadata is still returned so a client can say the attachment was too large to keep. `filename` and `contentType` are whatever the sender declared.\n\nNothing here is scanned. The bytes came from a stranger to an address anyone could name, so open or render them outside your own origin.',
+    signature: 'listAttachments(inboxId: string, messageId: string, options?: InboxScope): Promise<Array<TempAttachmentResource>>',
+    summary: 'List the attachments of a message, metadata only',
+    description: 'Resolves every attachment on a message as a plain array of metadata: `attachmentId`, `filename`, `mimeType` and `size` in decoded bytes, with `body` an empty string and `headers` empty. No route on a disposable inbox serves the bytes, and there is no per attachment fetch.\n\n`filename` and `mimeType` are whatever the sender declared, and nothing here is scanned. A message this lease cannot see is 404 `resource_not_found`, and an install with no key to read the pool answers 503 `not_configured`.',
     method: 'GET',
     path: '/temp-mail/inboxes/{id}/messages/{messageId}/attachments',
     scopes: [],
     auth: 'inboxToken',
     parameters: [
-        { name: 'inboxId', type: 'string', required: true, description: 'The `tinb_` id `create` returned. It must name the same inbox as the token, or the answer is a 404.' },
-        { name: 'messageId', type: 'string', required: true, description: 'A `tmail_` id from `listMessages`.' },
+        { name: 'inboxId', type: 'string', required: true, description: 'The `tinb_` id `create` returned. It is not checked against the token, which alone decides the inbox.' },
+        { name: 'messageId', type: 'string', required: true, description: 'An `id` from `listMessages`, such as `thr_` and 24 hex.' },
         { name: 'options.signal', type: 'AbortSignal', required: false, description: 'Cancels the request.' },
         { name: 'options.inboxToken', type: 'string', required: false, description: 'The `oe_inbox_` token `create` returned. Overrides the token given to `createTempMail` for this call, and is required on the `OpenEmail` client, which would otherwise send its API key.' }
     ],
-    returns: '`Array<AttachmentResource>`, each with `attachmentId`, `filename`, `contentType`, `size` in decoded bytes and `content` as base64 or null.',
-    example: 'const temp = createTempMail({ inboxToken: \'oe_inbox_Vb3kT9qLm2Xw7RzN4pYc6HfJ1sGa5Ed8KuQo0iWnS2e\' })\n\nconst attachments = await temp.listAttachments(\'tinb_5d2a8f1c7e4b9a30d6c1f8e2\', \'tmail_9e3b7c1a5f2d8e40b6a9c3f1\')\n\nconst pdf = attachments.find((file) => file.contentType === \'application/pdf\' && file.content !== null)\n\nconsole.log(pdf?.filename, pdf?.size)',
+    returns: '`Array<TempAttachmentResource>`, each with `attachmentId`, `filename`, `mimeType`, `size` in decoded bytes, `body` as an empty string and `headers` as an empty array.',
+    example: 'const temp = createTempMail({ inboxToken: \'oe_inbox_Vb3kT9qLm2Xw7RzN4pYc6HfJ1sGa5Ed8KuQo0iWnS2e\' })\n\nconst attachments = await temp.listAttachments(\'tinb_k7m2q9xw4bdp\', \'thr_9e3b7c1a5f2d8e40b6a9c3f1\')\n\nfor (const file of attachments) console.log(file.filename, file.size)',
     notes: [
-        'Reading attachments marks the message seen, the same as `getMessage`.',
+        'Listing attachments does not mark the message seen.',
         'Check `attachmentCount` from `listMessages` first to skip this call for messages with none.'
     ]
 };
@@ -7736,7 +7737,7 @@ const TempMailListDomainsMethod = {
     slug: 'temp-mail/listDomains',
     signature: 'listDomains(options?: InboxScope): Promise<Array<TempDomainResource>>',
     summary: 'List the domains a disposable inbox can be created on',
-    description: 'Resolves the pool of domains `create` accepts, as a plain array in the order an operator set for the picker. It takes no credential at all: no API key and no inbox token are sent, even when the client holding this namespace has one.\n\nOnly domains that are enrolled, enabled and verified are listed, because an unverified domain receives nothing and an address on it would never work. An empty array is a normal answer meaning this install offers no disposable domains, and it is exactly the condition under which `create` fails with 503 `temp_mail_unavailable`.',
+    description: 'Resolves the pool of domains `create` accepts, as a plain array in the order the operator wrote them in `TEMP_MAIL_DOMAINS`. It takes no credential at all: no API key and no inbox token are sent, even when the client holding this namespace has one.\n\nNothing checks that a listed domain is verified, so the list is only as good as the operator made it. An empty array is a normal answer meaning this install offers no disposable domains, and it is exactly the condition under which `create` fails with 503 `not_configured`.',
     method: 'GET',
     path: '/temp-mail/domains',
     scopes: [],
@@ -7748,7 +7749,7 @@ const TempMailListDomainsMethod = {
     returns: '`Array<TempDomainResource>`, each with `object` set to `temp_domain` and a lowercased `domain` to pass back to `create`.',
     example: 'const temp = createTempMail()\n\nconst domains = await temp.listDomains()\n\nconsole.log(domains.map((entry) => entry.domain))',
     notes: [
-        'The server caches the pool for up to 60 seconds, so a domain an operator just enrolled can take a minute to appear.',
+        'The pool is server configuration, so a domain appears when the operator adds it to `TEMP_MAIL_DOMAINS`, not when it is added to a workspace.',
         'Retried automatically on network failure and retryable statuses, like every GET.'
     ]
 };
@@ -7760,13 +7761,13 @@ const TempMailListMessagesMethod = {
     slug: 'temp-mail/listMessages',
     signature: 'listMessages(inboxId: string, options?: TempMessageListOptions): Promise<TempMessagesResource>',
     summary: 'List one page of the messages in a disposable inbox',
-    description: 'Resolves one page of the messages in the inbox newest first, by the time the server received them, together with the inbox `expiresAt`. Rows carry metadata only, and the call reads no object storage, so polling it every few seconds is the cheap way to wait for a confirmation email.\n\nA page holds up to 50 messages. When more have arrived, `hasMore` is true and `nextCursor` goes back as `options.cursor` for the next page, so nothing that reached the inbox is hidden; `listAllMessages` and `iterateMessages` do that walk for you. `snippet` is plain text capped at 400 characters, which is often enough to read a one time code without opening the message.\n\n`spam` is a flag, never a filing decision. A machine sent confirmation from a sender with no reputation is exactly what a disposable inbox exists to receive, so flagged messages are still listed. `from` is whatever the message claimed and has not been authenticated.',
+    description: 'Resolves one page of the messages in the inbox newest first, by the time the server received them, together with the inbox `expiresAt`. Rows carry metadata only, and polling this is the way to wait for a confirmation email. Only mail delivered to this address since the lease began is listed.\n\nA page holds up to 50 messages. When more have arrived, `hasMore` is true and `nextCursor` goes back as `options.cursor` for the next page, so nothing that reached the inbox is hidden; `listAllMessages` and `iterateMessages` do that walk for you. A page can hold fewer than `limit` rows, even none, while `hasMore` is true, because mail to other addresses on the pool is read and dropped. `snippet` is plain text capped at 400 characters, which is often enough to read a one time code without opening the message.\n\n`spam` is a flag, never a filing decision. A machine sent confirmation from a sender with no reputation is exactly what a disposable inbox exists to receive, so flagged messages are still listed. `from` is whatever the message claimed and has not been authenticated.',
     method: 'GET',
     path: '/temp-mail/inboxes/{id}/messages',
     scopes: [],
     auth: 'inboxToken',
     parameters: [
-        { name: 'inboxId', type: 'string', required: true, description: 'The `tinb_` id `create` returned. It must name the same inbox as the token, or the answer is a 404.' },
+        { name: 'inboxId', type: 'string', required: true, description: 'The `tinb_` id `create` returned. It is not checked against the token, which alone decides the inbox.' },
         { name: 'options.limit', type: 'number', required: false, description: 'Messages per page, a whole number from 1 to 50, defaulting to 50. Out of range is 422 `invalid_parameter`.' },
         { name: 'options.cursor', type: 'string', required: false, description: 'The `nextCursor` from the previous page. Never build one yourself.' },
         { name: 'options.signal', type: 'AbortSignal', required: false, description: 'Cancels the request.' },
@@ -7778,7 +7779,8 @@ const TempMailListMessagesMethod = {
     notes: [
         'A message whose `Message-ID` header matches one already in the inbox is not stored twice.',
         '`to` is the inbox address. A `+tag` the sender added is folded back into the base address.',
-        'Every message the inbox has received is listed, a page at a time. `messageLimit` on the inbox is the size the tool is built for, not a point past which mail is hidden.'
+        'Every message the inbox has received is listed, a page at a time. `messageLimit` on the inbox is the size the tool is built for, not a point past which mail is hidden.',
+        'An install with no key to read the pool answers 503 `not_configured`.'
     ]
 };
 
@@ -13661,6 +13663,7 @@ const RESOURCE_ONE_TIME_SECRETS = {
 const RESOURCE_TEMP_INBOX = {
     NAMESPACE: 'tempMail',
     CREATE: 'create',
+    EXTEND: 'extend',
     DELETE: 'delete',
     TOKEN_FIELD: 'token'
 };
@@ -13818,6 +13821,12 @@ const RESOURCE_TYPE_COLUMNS = {
     TempMessagesResource: TEMP_MESSAGE_COLUMNS,
     TempMessageResource: TEMP_MESSAGE_COLUMNS,
     TempDomainResource: [Column('domain', 'domain')],
+    TempAttachmentResource: [
+        Column('id', 'attachmentId', RENDER_CELL_FORMATS.ID),
+        Column('filename', 'filename'),
+        Column('type', 'mimeType'),
+        Column('size', 'size', RENDER_CELL_FORMATS.BYTES)
+    ],
     ApiKeyRequestResource: [
         Column('id', 'id', RENDER_CELL_FORMATS.ID),
         Column('method', 'method'),
@@ -13921,6 +13930,7 @@ const RESOURCE_ID_LIST_KEY = 'ids';
 const RESOURCE_ID_LIST_SUFFIX = 'Ids';
 const RESOURCE_MAX_SAMPLE = '100';
 const RESOURCE_READ_METHOD = 'GET';
+const RESOURCE_PATCH_METHOD = 'PATCH';
 const RESOURCE_EXAMPLE_LIMIT = 5;
 const RESOURCE_EXAMPLE_OPTIONAL_FLAGS = 3;
 const RESOURCE_CONFIRM_TARGET_LIMIT = 5;
@@ -13941,6 +13951,7 @@ const RESOURCE_UNSUPPORTED_ESCAPE = /\\[^'\\]/;
 const RESOURCE_SECRET_FLAG = /(key|token|secret|password)$/;
 const RESOURCE_SENTENCE_BREAK = /(?<=[.!?])\s+(?=[A-Z`])/;
 const RESOURCE_CAMEL_PATH = /^[a-z]+[A-Z][A-Za-z]*$/;
+const RESOURCE_EMPTY_STRING_CLEAR = /(\b[Nn]ull\b|`null`) or an empty string/g;
 const RESOURCE_EXAMPLE_PATTERNS = {
     STRING: /(\w+):\s*'((?:[^'\\\n]|\\.)*)'/g,
     NUMBER: /(\w+):\s*(-?\d+(?:\.\d+)?)(?=\s*[,}\n])/g,
@@ -13975,10 +13986,11 @@ const RESOURCE_HELP = {
     NOTES: 'NOTES',
     NO_SCOPES: 'Any key or sign-in for the workspace.',
     SIGNED_OUT: 'None. It works signed out, with no key.',
-    INBOX_TOKEN: 'None. The inbox token authorises it: `--inbox-token`, or the token the CLI saved when it created the inbox.',
+    INBOX_TOKEN: 'None. The inbox token authorises it: `--inbox-token`, or the token the CLI saved when it created or last extended the inbox.',
     REQUIRED: 'Required.',
     REQUIRED_WITH_DATA: 'Required, here or in `--data`.',
     PAGING: 'Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max <n>` stops after that many items.',
+    PAGING_OWN_SHAPE: 'Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one JSON document with `--json`, shaped as Returns describes. `--max <n>` stops after that many items.',
     DATA_USAGE: '--data <json|@file|->',
     JSON_TYPE: (type) => `JSON shaped as \`${type}\`, inline or from a file with @path.`
 };
@@ -14004,6 +14016,7 @@ const RESOURCE_MESSAGES = {
     INBOX_TOKEN_REJECTED: 'The inbox token was refused.',
     INBOX_TOKEN_REJECTED_NEXT: 'Check `--inbox-token`, or create a new inbox with `openemail temp new`.',
     INBOX_SAVED: (address) => `Saved the inbox token for ${address}, so later temp-mail commands find it.`,
+    INBOX_RENEWED: (address) => `Saved the new inbox token for ${address}, which carries the later expiry, so later temp-mail commands use it.`,
     SECRET_IN_ARGV: (label) => `${label} was passed on the command line, where your shell history and the process list can show it. Next time pass \`-\` to read it from standard input, or \`@path\` to read it from a file.`,
     NO_KEYLESS_RESOURCE: (namespace) => `The ${namespace} commands need a credential.`,
     NO_METHOD: (accessor) => `${accessor} is not in the SDK this CLI was built with.`,
@@ -14104,13 +14117,13 @@ const TEMP_FLAGS = {
         name: TEMP_FLAG_NAMES.DOMAIN,
         kind: FLAG_KINDS.STRING,
         placeholder: 'domain',
-        description: 'Domain from `openemail temp-mail list-domains`. Left out, one is picked at random'
+        description: 'Domain from `openemail temp-mail list-domains`. Left out, the first one in that list is used'
     },
     NAME: {
         name: TEMP_FLAG_NAMES.NAME,
         kind: FLAG_KINDS.STRING,
         placeholder: 'local-part',
-        description: 'The part before the @, 3 to 32 letters, digits, dots, dashes or underscores. Left out, one is generated'
+        description: 'The part before the @, up to 64 letters, digits, dots, dashes or underscores, starting and ending with a letter or digit. Left out, one is generated. Anyone who asks for the same name reads its mail too'
     },
     TTL: {
         name: TEMP_FLAG_NAMES.TTL,
@@ -14142,7 +14155,10 @@ const TEMP_LIMITS = {
     SNIPPET_WIDTH: 60
 };
 const TEMP_TOKEN_PREFIX = 'oe_inbox_';
-const TEMP_MESSAGE_PREFIX = 'tmail_';
+const TEMP_MESSAGE_PREFIX = 'thr_';
+const TEMP_API_ERROR_CODES = {
+    INBOX_EXPIRED: 'inbox_expired'
+};
 const TEMP_COLUMNS = {
     ID: 'Inbox',
     ADDRESS: 'Address',
@@ -14157,7 +14173,7 @@ const TEMP_MESSAGES = {
     CREATING: 'Creating a temporary inbox',
     LOADING: 'Loading messages',
     LOADING_MESSAGE: 'Loading the message',
-    DELETING: 'Deleting the inbox',
+    DELETING: 'Moving the mail to the bin',
     NO_INBOXES: 'You have no temporary inboxes.',
     NO_INBOXES_NEXT: 'Run `openemail temp new` to create one.',
     PICK_INBOX: 'Which inbox?',
@@ -14166,12 +14182,9 @@ const TEMP_MESSAGES = {
     TTL_RANGE: '--ttl takes a whole number of minutes from 1 to 1440.',
     INVALID_TOKEN: '--inbox-token must be an inbox token beginning oe_inbox_.',
     NO_MESSAGES: 'No mail yet.',
-    WATCH_STOPPED: 'Stopped watching.',
     EXPIRED: 'The inbox has expired, so there is nothing more to watch.',
-    GONE_LOCALLY: 'The inbox was already gone on the server, so it was only forgotten here.',
-    TRUNCATED: 'The body is longer than 2 MB, so only the first 2 MB is shown.',
-    EMPTY_BODY: '(This message has no body.)',
-    UNVERIFIED_SENDER: 'The sender of mail in a temporary inbox is not verified.',
+    GONE_LOCALLY: 'The server no longer accepts this inbox token, so nothing was moved and the inbox was only forgotten here.',
+    LEASE_RUNS_ON: 'The lease runs on until it expires, so mail can still arrive, and nothing holds the address back from anybody else.',
     MORE: (id) => `Older messages are not shown here. Run \`openemail temp-mail list-messages ${id} --all\` to see every one.`,
     ALREADY_HERE: 'Already in the inbox:',
     CREATED: (address) => `Created ${address}.`,
@@ -14181,8 +14194,8 @@ const TEMP_MESSAGES = {
     PRUNED: (count) => `Forgot ${count} expired ${count === 1 ? 'inbox' : 'inboxes'}.`,
     WATCHING: (address) => `Watching ${address}`,
     WAITING: (left) => `Waiting for mail, ${left} left. Press Ctrl+C to stop`,
-    CONFIRM_DELETE: (address) => `Delete ${address} and every message in it? This cannot be undone.`,
-    DELETED: (address) => `Deleted ${address}.`,
+    CONFIRM_DELETE: (address) => `Move every message in ${address} to the bin and forget the inbox here?`,
+    DELETED: (address) => `Moved the mail in ${address} to the bin and forgot the inbox here.`,
     SENDER_HINT: (id) => `Run \`openemail temp read ${id} <message-id>\` to read one.`
 };
 
@@ -14268,6 +14281,7 @@ const TERMINAL = {
     MIN_WRAP_WIDTH: 16
 };
 const CODE_SPAN_DELIMITER = '`';
+const CODE_SPAN_PATTERN = /`([^`\s](?:[^`]*[^`\s])?)`/g;
 const BANNER_LINES = [
     '                                           _  _',
     ' ___   _ __  ___  _ _   ___  _ __   __ _ (_)| |',
@@ -15535,13 +15549,7 @@ const Config$1 = {
     Update: Update$1
 };
 
-const FormatCode = (text, paint) => {
-    const parts = text.split(CODE_SPAN_DELIMITER);
-    if (parts.length < 3)
-        return text;
-    const balanced = parts.length % 2 === 1 ? parts : [...parts.slice(0, -2), `${parts[parts.length - 2]}${CODE_SPAN_DELIMITER}${parts[parts.length - 1]}`];
-    return balanced.map((part, index) => index % 2 === 1 ? paint(part) : part).join('');
-};
+const FormatCode = (text, paint) => text.replace(CODE_SPAN_PATTERN, (_span, code) => paint(code));
 
 const KNOWN_KINDS = new Set(Object.values(PROFILE_KINDS));
 const IsUsable = (value) => IsRecord$2(value) && KNOWN_KINDS.has(value.kind) && typeof value.baseUrl === 'string';
@@ -17622,6 +17630,17 @@ const NonEmptyEnv = (name) => {
     return value === undefined || value.length === 0 ? null : value;
 };
 
+const LOCAL_NETWORK = /^(localhost|127\.\d+\.\d+\.\d+|0\.0\.0\.0|\[::1\]|10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+|[^/:]+\.local)(:|\/|$)/i;
+
+const withScheme = (value) => {
+    const trimmed = value.trim();
+    if (trimmed === '' || /^https?:\/\//i.test(trimmed))
+        return trimmed;
+    const bare = trimmed.replace(/^\/+/, '');
+    return `${LOCAL_NETWORK.test(bare) ? 'http' : 'https'}://${bare}`;
+};
+const publicUrl = (value) => withScheme(value).replace(/\/+$/, '');
+
 const Invalid = (value) => new UsageError(MESSAGES.INVALID_BASE_URL(Color.Sanitize(value)), { code: CLI_ERROR_CODES.INVALID_VALUE });
 const Parse$3 = (url) => {
     try {
@@ -17641,8 +17660,8 @@ const Unspecified = (normalised, url) => new UsageError(MESSAGES.UNSPECIFIED_HOS
     next: MESSAGES.UNSPECIFIED_HOST_NEXT(Color.Sanitize(LoopbackInstead(url)))
 });
 const NormaliseUrl = (value) => {
-    const normalised = NormaliseEndpoint(value);
-    if (normalised === undefined)
+    const normalised = publicUrl(value);
+    if (normalised.length === 0)
         throw Invalid(value);
     const url = Parse$3(normalised);
     if (url === null || (url.protocol !== URL_PROTOCOLS.HTTP && url.protocol !== URL_PROTOCOLS.HTTPS))
@@ -18410,6 +18429,17 @@ const Find$1 = (idOrAddress) => {
     return List$2().find(inbox => inbox.id === idOrAddress || inbox.address.toLowerCase() === needle) ?? null;
 };
 const Add = (inbox) => Change(inboxes => [...inboxes.filter(existing => existing.id !== inbox.id), inbox]);
+const Renew$1 = (id, inboxToken, expiresAt) => {
+    const outcome = { renewed: false };
+    Change(inboxes => {
+        const stored = inboxes.find(inbox => inbox.id === id);
+        if (stored === undefined || Date.parse(expiresAt) < Date.parse(stored.expiresAt))
+            return null;
+        outcome.renewed = true;
+        return inboxes.map(inbox => inbox === stored ? { ...inbox, inboxToken, expiresAt } : inbox);
+    });
+    return outcome.renewed;
+};
 const Remove$1 = (id) => {
     const outcome = { removed: false };
     Change(inboxes => {
@@ -18433,6 +18463,7 @@ const TempMailStore = {
     List: List$2,
     Find: Find$1,
     Add,
+    Renew: Renew$1,
     Remove: Remove$1,
     PruneExpired
 };
@@ -19257,11 +19288,7 @@ const PathOf = (raw) => {
         return raw;
     }
 };
-const WithoutDocsPrefix = (path) => {
-    if (path === DOCS_PATHS.DOCS_PREFIX.slice(0, -1))
-        return '';
-    return path.startsWith(DOCS_PATHS.DOCS_PREFIX) ? path.slice(DOCS_PATHS.DOCS_PREFIX.length) : path;
-};
+const WithoutDocsPrefix = (path) => path.replace(DOCS_PATTERNS.DOCS_PREFIX, '');
 const Decoded = (segment) => {
     try {
         return decodeURIComponent(segment);
@@ -25631,6 +25658,8 @@ const Send = {
     }
 };
 
+const InboxGone = (error) => error instanceof OpenEmailApiError && (error.isNotFound || error.code === TEMP_API_ERROR_CODES.INBOX_EXPIRED);
+
 const FromStored = (inbox) => ({
     id: inbox.id,
     address: inbox.address,
@@ -25697,15 +25726,15 @@ const TempClient = (baseUrl, signal) => createTempMail(SdkBaseOptions(baseUrl, s
 const TempDelete = {
     name: TEMP_COMMAND_NAMES.DELETE,
     aliases: ['rm'],
-    summary: 'Delete a disposable inbox and forget it',
+    summary: 'Move the mail in a disposable inbox to the bin and forget its token',
     usage: ['temp delete [inbox] [--yes]'],
-    description: 'Deletes every message in the inbox straight away and stops its token working, then removes it from `~/.openemail/temp-mail.json`. The address stays reserved for 7 days after its lease would have ended, so nobody else can take it while late mail may still arrive. You are asked to confirm unless you pass `--yes`.',
+    description: 'Moves every message the inbox shows to the bin at once, then removes the inbox and its token from `~/.openemail/temp-mail.json`. Nothing about the lease is stored on the server, so there is nothing to revoke: it runs on until its expiry, and mail that arrives in the meantime still reaches whoever holds the token. Nothing holds the address back either, so it can be issued again at once, to anybody. You are asked to confirm unless you pass `--yes`.',
     arguments: [{ name: 'inbox', description: 'Inbox id or address from `openemail temp list`, optional when you have only one' }],
     flags: [TEMP_FLAGS.INBOX_TOKEN],
     examples: [
         { command: 'openemail temp delete' },
         { command: 'openemail temp rm quiet-otter-12@example-temp.com --yes' },
-        { command: 'openemail temp delete tinb_4f2a --yes --json' }
+        { command: 'openemail temp delete tinb_k7m2q9xw4bdp --yes --json' }
     ],
     auth: COMMAND_AUTHS.NONE,
     destructive: true,
@@ -25716,7 +25745,7 @@ const TempDelete = {
         if (!await ConfirmDestructive(TEMP_MESSAGES.CONFIRM_DELETE(address)))
             return EXIT_CODES.CANCELLED;
         const gone = await CallAnonymous(context, TEMP_MESSAGES.DELETING, signal => TempClient(baseUrl, signal).delete(target.id, { inboxToken: target.token, signal })).then(() => false, (error) => {
-            if (error instanceof OpenEmailApiError && error.isNotFound)
+            if (InboxGone(error))
                 return true;
             throw error;
         });
@@ -25725,10 +25754,12 @@ const TempDelete = {
             context.io.Json({ object: 'temp_inbox', id: target.id, address: target.address, destroyed: !gone, forgotten });
             return EXIT_CODES.OK;
         }
-        if (gone)
+        if (gone) {
             context.io.Warn(TEMP_MESSAGES.GONE_LOCALLY);
-        else
-            context.io.Success(TEMP_MESSAGES.DELETED(address));
+            return EXIT_CODES.OK;
+        }
+        context.io.Success(TEMP_MESSAGES.DELETED(address));
+        context.io.Hint(TEMP_MESSAGES.LEASE_RUNS_ON);
         return EXIT_CODES.OK;
     }
 };
@@ -25737,7 +25768,7 @@ const TempList = {
     name: TEMP_COMMAND_NAMES.LIST,
     summary: 'List the disposable inboxes this CLI created',
     usage: ['temp list'],
-    description: 'Lists the inboxes kept in `~/.openemail/temp-mail.json`, soonest to expire last. Expired inboxes are forgotten as they are found, because the server has already deleted them. Nothing is read from the network.',
+    description: 'Lists the inboxes kept in `~/.openemail/temp-mail.json`, soonest to expire last. Expired inboxes are forgotten as they are found, because their tokens no longer open anything. An inbox extended with `openemail temp-mail extend` shows its later expiry. Nothing is read from the network.',
     examples: [
         { command: 'openemail temp list' },
         { command: 'openemail temp ls --json', note: 'Ids, addresses and expiry times, never the tokens' }
@@ -25784,7 +25815,7 @@ const TempNew = {
     aliases: ['create'],
     summary: 'Create a disposable inbox',
     usage: ['temp new [--name <local-part>] [--domain <domain>] [--ttl <minutes>]'],
-    description: 'Creates a disposable address that needs no account and no API key, and keeps its token in `~/.openemail/temp-mail.json` so the other `temp` commands can reach it. The address is printed on stdout on its own, so `ADDRESS=$(openemail temp new)` works in a script. It lives for 60 minutes unless you pass `--ttl`, up to 24 hours.',
+    description: 'Creates a disposable address that needs no account and no API key, and keeps its token in `~/.openemail/temp-mail.json` so the other `temp` commands can reach it. The address is printed on stdout on its own, so `ADDRESS=$(openemail temp new)` works in a script. It lives for 60 minutes unless you pass `--ttl`, up to 24 hours, and `openemail temp-mail extend` adds up to an hour at a time within 24 hours of its creation, saving the new token it returns. A name you choose with `--name` is issued to anyone who asks for it too, so leave it out when the mail should reach you alone.',
     flags: [TEMP_FLAGS.NAME, TEMP_FLAGS.DOMAIN, TEMP_FLAGS.TTL],
     examples: [
         { command: 'openemail temp new' },
@@ -25821,7 +25852,7 @@ const TempNew = {
     }
 };
 
-const PrintDetail = (context, detail, raw) => {
+const PrintDetail = (detail, raw) => {
     const view = MessageView(detail.message);
     PrintMailMessage({
         ...view,
@@ -25831,8 +25862,6 @@ const PrintDetail = (context, detail, raw) => {
         subject: view.subject || detail.subject,
         date: view.date ?? detail.receivedAt
     }, raw);
-    if (detail.truncated)
-        context.io.Warn(TEMP_MESSAGES.TRUNCATED);
 };
 const ListMessages = async (context, target) => {
     const baseUrl = TempBaseUrl(context, target);
@@ -25871,22 +25900,23 @@ const TempRead = {
     aliases: ['show', 'open'],
     summary: 'List the mail in a disposable inbox, or read one message',
     usage: ['temp read [inbox] [message-id] [flags]'],
-    description: 'Without a message id it lists what has arrived, newest first, with a short preview that is often enough to read a one time code. With one it prints the whole message, turning HTML into readable text. The inbox is its id or address, and can be left out when you have only one. Reading a message marks it seen. The sender of mail in a temporary inbox is never verified.',
+    description: 'Without a message id it lists what has arrived, newest first, with a short preview that is often enough to read a one time code. With one it prints the whole message, turning HTML into readable text, and lists its attachments by name and size, without their bytes. The inbox is its id or address, and can be left out when you have only one, so a lone `thr_` id reads that message. Reading a message does not mark it seen, and its body is never cut. The sender of mail in a temporary inbox is never verified.',
     arguments: [
         { name: 'inbox', description: 'Inbox id or address from `openemail temp list`' },
-        { name: 'message-id', description: 'A `tmail_` id from the list' }
+        { name: 'message-id', description: 'A `thr_` id from the list' }
     ],
     flags: [TEMP_FLAGS.HTML, TEMP_FLAGS.INBOX_TOKEN],
     examples: [
         { command: 'openemail temp read' },
         { command: 'openemail temp read quiet-otter-12@example-temp.com' },
-        { command: 'openemail temp read tinb_4f2a tmail_91c3' },
-        { command: 'openemail temp read tinb_4f2a tmail_91c3 --html > message.html' }
+        { command: 'openemail temp read thr_9e3b7c1a5f2d8e40b6a9c3f1', note: 'Reads one message from your only inbox' },
+        { command: 'openemail temp read tinb_k7m2q9xw4bdp thr_9e3b7c1a5f2d8e40b6a9c3f1' },
+        { command: 'openemail temp read tinb_k7m2q9xw4bdp thr_9e3b7c1a5f2d8e40b6a9c3f1 --html > message.html' }
     ],
     auth: COMMAND_AUTHS.NONE,
     run: async (context) => {
         const [first, second] = context.args.positional;
-        const firstIsMessage = first !== undefined && second === undefined && first.startsWith(TEMP_MESSAGE_PREFIX);
+        const firstIsMessage = first !== undefined && second === undefined && first.startsWith(TEMP_MESSAGE_PREFIX) && !first.includes('@');
         const target = await ResolveTempInbox(context, firstIsMessage ? null : first ?? null);
         const messageId = firstIsMessage ? first : second;
         if (messageId === undefined)
@@ -25896,7 +25926,7 @@ const TempRead = {
         if (context.io.json)
             context.io.Json(detail);
         else
-            PrintDetail(context, detail, Flags$2.Bool(context.args.flags, TEMP_FLAG_NAMES.HTML));
+            PrintDetail(detail, Flags$2.Bool(context.args.flags, TEMP_FLAG_NAMES.HTML));
         return EXIT_CODES.OK;
     }
 };
@@ -25925,11 +25955,18 @@ const Print = (context, messages) => {
 };
 const Left = (expiresAt) => RelativeTime(expiresAt).replace(/^in /, '');
 const Waiting = (context, expiresAt) => context.io.Spinner(TEMP_MESSAGES.WAITING(Left(expiresAt)));
+const Extended = (target, expiresAt) => {
+    if (!target.fromStore)
+        return null;
+    const stored = TempMailStore.Find(target.id);
+    const later = Date.parse(stored?.expiresAt ?? '');
+    return stored !== null && !Number.isNaN(later) && (Number.isNaN(expiresAt) || later > expiresAt) ? stored : null;
+};
 const TempWatch = {
     name: TEMP_COMMAND_NAMES.WATCH,
     summary: 'Wait for mail to arrive in a disposable inbox',
     usage: ['temp watch [inbox] [--first]'],
-    description: 'Prints what is already in the inbox, then checks every 3 seconds and prints each new message as it lands, until you press Ctrl+C or the inbox expires. With `--first` it stops as soon as there is a message, which suits a script waiting for a sign-up code. With `--json` each message is one JSON line on stdout.',
+    description: 'Prints what is already in the inbox, then checks every 3 seconds and prints each new message as it lands, until you press Ctrl+C or the inbox expires. When `openemail temp-mail extend` saves a new token for the inbox meanwhile, the watch carries on with it until the later expiry. With `--first` it stops as soon as there is a message, which suits a script waiting for a sign-up code. With `--json` each message is one JSON line on stdout.',
     arguments: [{ name: 'inbox', description: 'Inbox id or address from `openemail temp list`, optional when you have only one' }],
     flags: [TEMP_FLAGS.FIRST, TEMP_FLAGS.INBOX_TOKEN],
     examples: [
@@ -25942,7 +25979,8 @@ const TempWatch = {
         const target = await ResolveTempInbox(context, context.args.positional[0] ?? null);
         const first = Flags$2.Bool(context.args.flags, TEMP_FLAG_NAMES.FIRST);
         const baseUrl = TempBaseUrl(context, target);
-        const List = () => CallAnonymous(context, TEMP_MESSAGES.LOADING, signal => TempClient(baseUrl, signal).listMessages(target.id, { inboxToken: target.token, signal }), { spinner: false });
+        const lease = { token: target.token };
+        const List = () => CallAnonymous(context, TEMP_MESSAGES.LOADING, signal => TempClient(baseUrl, signal).listMessages(target.id, { inboxToken: lease.token, signal }), { spinner: false });
         const opening = await List();
         const seen = new Set(opening.items.map(message => message.id));
         let expiresAt = Date.parse(opening.expiresAt ?? target.expiresAt ?? '');
@@ -25959,6 +25997,12 @@ const TempWatch = {
         const spinner = Waiting(context, expiresAt);
         try {
             for (;;) {
+                const extended = Extended(target, expiresAt);
+                if (extended !== null) {
+                    lease.token = extended.inboxToken;
+                    expiresAt = Date.parse(extended.expiresAt);
+                    spinner.Update(TEMP_MESSAGES.WAITING(Left(expiresAt)));
+                }
                 if (!Number.isNaN(expiresAt) && Date.now() >= expiresAt) {
                     spinner.Stop();
                     context.io.Info(TEMP_MESSAGES.EXPIRED);
@@ -25966,10 +26010,12 @@ const TempWatch = {
                 }
                 await Sleep$2(TEMP_LIMITS.WATCH_INTERVAL_MS, context.signal);
                 const page = await List().catch((error) => {
-                    if (error instanceof OpenEmailApiError && error.isNotFound)
+                    if (InboxGone(error))
                         return null;
                     throw error;
                 });
+                if (page === null && Extended(target, expiresAt) !== null)
+                    continue;
                 if (page === null) {
                     spinner.Stop();
                     context.io.Info(TEMP_MESSAGES.EXPIRED);
@@ -25997,12 +26043,12 @@ const Temp = {
     name: TEMP_COMMAND_NAMES.TEMP,
     summary: 'Disposable inboxes for sign-ups and tests',
     usage: ['temp <new|list|read|watch|delete> [arguments] [flags]'],
-    description: 'Creates short-lived addresses that anyone can use without signing in, and reads the mail they receive. Each inbox token is kept in `~/.openemail/temp-mail.json` (mode 0600), so later commands find the inbox by its id or address. Mail that lands in a disposable inbox comes from strangers and its sender is never verified.',
+    description: 'Creates short-lived addresses that anyone can use without signing in, and reads the mail they receive. The inbox token is the lease itself and nothing about it is stored on the server, so it is kept in `~/.openemail/temp-mail.json` (mode 0600) and later commands find the inbox by its id or address. A lost token cannot be recovered. Mail that lands in a disposable inbox comes from strangers and its sender is never verified.',
     subcommands: [TempNew, TempList, TempRead, TempWatch, TempDelete],
     examples: [
         { command: 'openemail temp new', note: 'Prints a fresh address' },
         { command: 'openemail temp watch', note: 'Waits for mail and prints each message as it lands' },
-        { command: 'openemail temp read tmail_91c3' },
+        { command: 'openemail temp read thr_9e3b7c1a5f2d8e40b6a9c3f1', note: 'Reads one message by its thread id' },
         { command: 'openemail temp delete --yes' }
     ],
     section: HELP_SECTIONS.MAIL,
@@ -26329,6 +26375,13 @@ const RememberRotatedKey = (context, verb, call, value) => {
 };
 
 const Text = (value) => typeof value === 'string' && value.length > 0 ? value : null;
+const Renew = (id, address, token, expiresAt, baseUrl) => {
+    const stored = TempMailStore.Find(id);
+    if (stored === null || OriginOf(stored.baseUrl ?? DEFAULT_API_URL) !== OriginOf(baseUrl))
+        return;
+    if (TempMailStore.Renew(id, token, expiresAt))
+        Console.Info(RESOURCE_MESSAGES.INBOX_RENEWED(Color.Sanitize(address)));
+};
 const RememberTempInbox = (verb, call, value, baseUrl) => {
     if (verb.namespace !== RESOURCE_TEMP_INBOX.NAMESPACE)
         return;
@@ -26338,7 +26391,9 @@ const RememberTempInbox = (verb, call, value, baseUrl) => {
             TempMailStore.Remove(inbox);
         return;
     }
-    if (call.method !== RESOURCE_TEMP_INBOX.CREATE || !IsPlainObject(value))
+    if (call.method !== RESOURCE_TEMP_INBOX.CREATE && call.method !== RESOURCE_TEMP_INBOX.EXTEND)
+        return;
+    if (!IsPlainObject(value))
         return;
     const id = Text(value.id);
     const address = Text(value.address);
@@ -26346,6 +26401,10 @@ const RememberTempInbox = (verb, call, value, baseUrl) => {
     const expiresAt = Text(value.expiresAt);
     if (id === null || address === null || token === null || expiresAt === null)
         return;
+    if (call.method === RESOURCE_TEMP_INBOX.EXTEND) {
+        Renew(id, address, token, expiresAt, baseUrl);
+        return;
+    }
     TempMailStore.Add({ id, address, inboxToken: token, expiresAt, baseUrl });
     Console.Info(RESOURCE_MESSAGES.INBOX_SAVED(Color.Sanitize(address)));
 };
@@ -26578,7 +26637,7 @@ const RunVerb = (namespace, verb) => async (context) => {
 
 const Code = (text) => `${CODE_SPAN_DELIMITER}${text}${CODE_SPAN_DELIMITER}`;
 const VerbProse = (verb, text) => {
-    let prose = text;
+    let prose = text.replace(RESOURCE_EMPTY_STRING_CLEAR, '$1');
     for (const flag of verb.flags) {
         if (flag.parameter === null)
             continue;
@@ -26609,7 +26668,10 @@ const VerbArguments = (verb) => verb.positionals.map(positional => ({
 
 const VerbDescription = (verb) => {
     const prose = VerbProse(verb, verb.entry.description).trim();
-    return verb.paginates ? `${prose}\n\n${RESOURCE_HELP.PAGING}` : prose;
+    if (!verb.paginates)
+        return prose;
+    const paging = verb.returns.layout === MANIFEST_DEFAULT_PAGE_LAYOUT ? RESOURCE_HELP.PAGING : RESOURCE_HELP.PAGING_OWN_SHAPE;
+    return `${prose}\n\n${paging}`;
 };
 
 const Collect = (fields, example, pattern, value) => {
@@ -26706,9 +26768,10 @@ const VerbExamples = (namespace, verb, known) => {
     })
         .slice(0, RESOURCE_EXAMPLE_OPTIONAL_FLAGS)
         .flat();
-    const examples = [{ command: Join(essential) }];
+    const emptyPatch = verb.entry.method.toUpperCase() === RESOURCE_PATCH_METHOD && required.length === 0 && optional.length > 0;
+    const examples = emptyPatch ? [] : [{ command: Join(essential) }];
     if (optional.length > 0) {
-        if (required.length > 0 || verb.positionals.some(positional => positional.required))
+        if (!emptyPatch && (required.length > 0 || verb.positionals.some(positional => positional.required)))
             examples[0].note = RESOURCE_EXAMPLE_NOTES.REQUIRED;
         examples.push({ command: Join([...essential, ...optional]), note: RESOURCE_EXAMPLE_NOTES.FULL });
     }
@@ -26729,7 +26792,7 @@ const VerbExamples = (namespace, verb, known) => {
     }
     const reads = verb.entry.method.toUpperCase() === RESOURCE_READ_METHOD && verb.returns.shape === MANIFEST_RETURN_SHAPES.OBJECT;
     if (examples.length < 2 || reads) {
-        examples.push({ command: Join([...essential, `--${GLOBAL_FLAG_NAMES.JSON}`]), note: RESOURCE_EXAMPLE_NOTES.JSON });
+        examples.push({ command: Join([...essential, ...(emptyPatch ? optional : []), `--${GLOBAL_FLAG_NAMES.JSON}`]), note: RESOURCE_EXAMPLE_NOTES.JSON });
     }
     return examples.slice(0, RESOURCE_EXAMPLE_LIMIT);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@openemail/cli",
-    "version": "0.0.1",
+    "version": "0.0.3",
     "author": "OpenEmail",
     "license": "UNLICENSED",
     "description": "The official OpenEmail command line. Sign in once, then send and read mail, manage domains, addresses, keys, webhooks, templates, contacts, audiences and every other OpenEmail resource, use the AI tools and connect MCP clients from your terminal.",