@fleetless/contracts 6.0.0-next.1 → 6.0.0-next.3

package/dist/routes.js

@@ -1,8 +1,9 @@
 // SPDX-License-Identifier: Apache-2.0
-import { appListResponse, appDeletionSummary, createAppRequest, createServerKeyResponse, app as appSchema, role, roleListResponse, rolePermissions, serverKeyListResponse, updateAppRequest, } from './apps.js';
+import { appListResponse, appDeletionSummary, createAppRequest, createServerKeyResponse, app as appSchema, role, roleListResponse, roleDeleteQuery, rolePermissions, roleRenameRequest, serverKeyListResponse, updateAppRequest, } from './apps.js';
 import { alertListResponse, orgAlertsQuery, orgFiringAlertsResponse } from './alerts.js';
 import { asset, assetListResponse, assetsClearResponse, assetSyncRequest, assetSyncResponse, assetSyncStatus, missingAssetQuery } from './assets.js';
 import { auditListResponse, auditQuery } from './audit.js';
+import { feedbackRequest, feedbackResponse } from './feedback.js';
 import { CLIENT_OIDC_CALLBACK_PATH, clientAcceptInvitationRequest, clientIdentity, clientLoginCodeRequest, clientLoginCodeVerifyRequest, clientLoginRequest, clientLogoutRequest, clientMcpInteraction, clientMcpInteractionDecisionResponse, clientOidcCallbackQuery, clientOidcExchangeRequest, clientOidcStartQuery, clientPasswordResetConfirmRequest, clientPasswordResetRequest, clientProviderListQuery, clientProviderListResponse, clientRefreshRequest, clientRegisterRequest, clientResendVerificationRequest, clientSignInResult, clientTwoFactorDisableRequest, clientTwoFactorSetupConfirmRequest, clientTwoFactorSetupConfirmResponse, clientTwoFactorSetupRequest, clientTwoFactorVerifyRequest, clientVerifyEmailRequest, mcpConsentGrantListResponse, } from './client-auth.js';
 import { clientRobotListResponse } from './client-robots.js';
 import { appAuthConfig, appInvitation, appInvitationListResponse, appMailTemplate, appMailTemplateListResponse, appOidcProvider, appOidcProviderListResponse, appUser, appUserListResponse, createAppInvitationRequest, createAppOidcProviderRequest, createAppUserRequest, mailOutcome, mailTemplatePreviewRequest, mailTemplatePreviewResponse, patchAppOidcProviderRequest, patchAppUserRequest, putAppAuthLookRequest, putAppAuthMcpRequest, putAppAuthRegistrationRequest, putAppAuthSignInRequest, putAppAuthUrlsRequest, putAppMailTemplateRequest, } from './app-users.js';
@@ -126,9 +127,16 @@ const CLIENT_GUARD = ['unauthorized', 'token_expired', 'token_revoked', 'forbidd
  *
  * Every step is a page the auth portal serves to itself: `audience:
  * 'internal'`, no request schema — the handlers read form fields by hand — and
- * HTML for a browser form post, JSON for a JSON caller. Every step after
- * `identify` needs the browser-proof cookie set there, so a step posted from
- * another browser renders the `wrong_browser` page. The interaction's ten
+ * HTML for a browser form post, JSON for a JSON caller.
+ *
+ * **The browser-proof cookie binds the interaction to one browser**, and it
+ * is set by whichever of these comes first for the interaction: the email
+ * card (`GET <prefix>/interaction/:id`), `POST <prefix>/identify`, or `POST
+ * <prefix>/passkey/options`. The email card is what a browser normally opens
+ * first; the two steps set it for a caller that never loaded the page, so
+ * `Sign in with a passkey` works without an email step. Once the interaction
+ * is bound, every step — those three included — without the matching cookie
+ * renders the `wrong_browser` page. The interaction's ten
  * minutes cover every step; only when the last one is done is anything
  * minted. **For `/mcp/oauth`, "done" means the consent step**, as the
  * password did before.
@@ -150,11 +158,11 @@ export function developerSignInRoutes(prefix) {
         params: [], query: null, request: null, response, errors: ['rate_limited', ...errors], transport: 'http', notes,
     });
     return [
-        step('/identify', 'Takes the email address, mails a sign-in code and hands back the code step.', null, ['validation_error', 'token_spent'], 'The page answers `Check your email` **for every address**: a known one gets `Your Fleetless sign-in code`, six digits valid ten ' +
+        step('/identify', 'Takes the email address, mails a sign-in code and hands back the code step.', null, ['validation_error', 'token_spent', 'wrong_browser'], 'The page answers `Check your email` **for every address**: a known one gets `Your Fleetless sign-in code`, six digits valid ten ' +
             'minutes; an unknown one gets a mail saying no Fleetless account uses it, with a link to sign up (or the waiting list while sign-up ' +
             'is closed). So the page never reveals who has an account, and the address is trimmed and compared case-insensitively. A request ' +
             'within sixty seconds of the last one for the same address renders the same page without a second mail. The browser-proof cookie is ' +
-            `set here. A browser form post gets the code card; a JSON caller gets \`{ "next": "${prefix}/code" }\`, which has no schema. A dead ` +
+            `set here when the interaction has none yet, and checked when it has. A browser form post gets the code card; a JSON caller gets \`{ "next": "${prefix}/code" }\`, which has no schema. A dead ` +
             'interaction is `410 token_spent`.'),
         step('/code', 'Checks the emailed code and finishes the sign-in, or hands back the second step.', oauthRedirectResponse, ['validation_error', 'token_spent', 'wrong_browser', 'invalid_code'], 'A wrong code renders the code card again with the attempts left (`400 invalid_code`, `details.attempts_left`); a code spent, past ' +
             'its ten minutes or out of its five attempts is `410 token_spent` and a new one has to be asked for. Spaces inside a typed code are ' +
@@ -171,7 +179,9 @@ export function developerSignInRoutes(prefix) {
             `a \`303\` to ${done}; a JSON caller that URL as \`redirect_to\`.`),
         step('/passkey/options', 'Answers the WebAuthn request options for a passkey sign-in or second step.', webauthnOptionsResponse, ['token_spent', 'wrong_browser'], 'Before an address is known the options name no credential, so the browser offers every discoverable passkey for `fleetless.dev` ' +
             '(`Sign in with a passkey`); after the code step they name the account\'s own passkeys. User verification is required. The challenge ' +
-            'is bound to the interaction and single-use.'),
+            'is bound to the interaction and single-use. **This is the first step of a passkey sign-in**, which has no email step: the ' +
+            'browser-proof cookie is set here when the interaction has none yet, and checked when it has — so `POST ' + prefix + '/passkey` ' +
+            'can require it.'),
         step('/passkey', 'Checks a passkey assertion; a passkey completes the sign-in on its own.', oauthRedirectResponse, ['validation_error', 'token_spent', 'wrong_browser', 'invalid_credentials'], '**A passkey is a full sign-in**: it proves possession and user verification, two factors, so it skips the emailed code and the ' +
             'second step — used as the second step, it finishes it. An assertion that does not verify, or names no passkey of an account, is ' +
             '`401 invalid_credentials`, the same answer for both. When the organisation requires two-factor, a passkey satisfies it. A browser ' +
@@ -516,7 +526,7 @@ export const ROUTES = [
         params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }],
         query: null, request: null, response: role,
         errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found', 'validation_error'], transport: 'http',
-        notes: 'The body is `{ "name": string }` — non-empty, trimmed, at most 120 characters — and is deliberately not a contract shape: contracts ' +
+        notes: 'The body is `{ "name": string }` — non-empty, trimmed, at most 60 characters as on `role.name` — and is deliberately not a contract shape: contracts ' +
             'define the `role` this answers with, not this one trivial request. **The answer is a bare `role`, not an envelope**, unlike the ' +
             'listing beside it.',
     },
@@ -569,6 +579,33 @@ export const ROUTES = [
             'offered and consults nothing about any user\'s actual MCP entitlement. A robot the role grants nothing on still appears, with an empty ' +
             '`exposures` — dropping it would read as "not attached", which is a different fact.',
     },
+    {
+        method: 'PATCH', path: '/api/apps/:id/roles/:roleId', section: 'apps',
+        summary: 'Renames a role; its users keep it.',
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
+        params: [
+            { name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' },
+            { name: 'roleId', description: 'The role\'s uuid, from `GET /api/apps/:id/roles`; a role of another app answers `404`.' },
+        ],
+        query: null, request: roleRenameRequest, response: role,
+        errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found', 'validation_error', 'role_name_taken'], transport: 'http',
+        notes: 'Names are unique per app, compared exactly as stored after trimming. Built-in roles can be renamed.',
+    },
+    {
+        method: 'DELETE', path: '/api/apps/:id/roles/:roleId', section: 'apps',
+        summary: 'Deletes a role, moving its users, pending invitations and default-role status to another role.',
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 204,
+        params: [
+            { name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' },
+            { name: 'roleId', description: 'The role\'s uuid, from `GET /api/apps/:id/roles`; a role of another app answers `404`.' },
+        ],
+        query: roleDeleteQuery, request: null, response: null,
+        errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found', 'validation_error', 'role_in_use', 'last_role'], transport: 'http',
+        notes: 'Without `move_to`, a role that app users or pending invitations hold, or that is the app\'s default, answers ' +
+            '`409 role_in_use` with `{ users, invitations, is_default }`. With `move_to` — another role of the same app, else ' +
+            '`400 validation_error` — one transaction moves `app_users.role_id`, pending invitations and `default_role_id`, then deletes ' +
+            'the role and its permissions. The app\'s only role answers `409 last_role`. Built-in roles can be deleted like any other.',
+    },
     {
         method: 'POST', path: '/api/apps/:id/server-keys', section: 'apps',
         summary: 'Mints a server key for the app and returns the raw secret once.',
@@ -696,8 +733,9 @@ export const ROUTES = [
         audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 202,
         params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'userId', description: 'The app user\'s uuid, from `GET /api/apps/:id/users`; a user of another app answers `404`.' }],
         query: null, request: null, response: mailOutcome,
-        errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found', 'target_state_conflict'], transport: 'http',
-        notes: 'The support door beside `POST /api/client/password/reset`: the same one-hour token and the same link, triggered by a developer for a ' +
+        errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found', 'target_state_conflict', 'method_not_allowed'], transport: 'http',
+        notes: 'The support door beside `POST /api/client/password/reset`, refused like it with `403 method_not_allowed` while the app has the ' +
+            'password method off: the same one-hour token and the same link, triggered by a developer for a ' +
             'user who asked them rather than the form. **No enumeration discipline applies** — the caller is authenticated into the app and can read ' +
             'the user list — so this one answers what actually happened: `{ "mail": mailStatus }`, where `not_configured` is a deployment without a ' +
             'mailer and `failed` is the state worth somebody\'s attention. The link points at the app\'s `reset_url`, or at the hosted reset page ' +
@@ -1018,7 +1056,7 @@ export const ROUTES = [
         method: 'GET', path: '/api/apps/:id/mail-templates/:kind', section: 'apps',
         summary: 'Reads one custom mail template of the app.',
         audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
-        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.' }],
+        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.' }],
         query: null, request: null, response: appMailTemplate,
         errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'validation_error', 'not_found'], transport: 'http',
         notes: 'The `kind` segment is a `mailTemplateKind`, so a fourth word is `400 validation_error` — the path names a set that is closed, and ' +
@@ -1030,7 +1068,7 @@ export const ROUTES = [
         method: 'PUT', path: '/api/apps/:id/mail-templates/:kind', section: 'apps',
         summary: 'Stores or replaces the app\'s template for one kind of mail, refusing one that does not render.',
         audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
-        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.' }],
+        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.' }],
         query: null, request: putAppMailTemplateRequest, response: appMailTemplate,
         errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'validation_error', 'not_found', 'template_invalid', 'rate_limited'], transport: 'http',
         notes: 'The body carries `subject`, `text` and an optional `html`, each a Liquid template; `kind` is in the path and `updated_at` is the ' +
@@ -1048,7 +1086,7 @@ export const ROUTES = [
         method: 'DELETE', path: '/api/apps/:id/mail-templates/:kind', section: 'apps',
         summary: 'Drops the app\'s custom template for one kind, returning that mail to the Fleetless default.',
         audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 204,
-        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.' }],
+        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.' }],
         query: null, request: null, response: null,
         errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'validation_error', 'not_found'], transport: 'http',
         notes: 'The mail keeps being sent — this removes the developer\'s wording, not the message. A kind that already has no custom template answers ' +
@@ -1059,7 +1097,7 @@ export const ROUTES = [
         method: 'POST', path: '/api/apps/:id/mail-templates/:kind/preview', section: 'apps',
         summary: 'Renders a template with sample data and answers the three parts, storing nothing.',
         audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
-        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.' }],
+        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.' }],
         query: null, request: mailTemplatePreviewRequest, response: mailTemplatePreviewResponse,
         errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'validation_error', 'not_found', 'template_invalid', 'rate_limited'], transport: 'http',
         notes: 'Takes the same document the PUT does and writes nothing, so a developer can see the rendered subject, text and HTML before anybody ' +
@@ -1076,7 +1114,7 @@ export const ROUTES = [
         method: 'POST', path: '/api/apps/:id/mail-templates/:kind/test', section: 'apps',
         summary: 'Sends the rendered template as a real mail to the calling developer.',
         audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 202,
-        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the three mails this template replaces — a `mailTemplateKind`: `invite`, `verify` or `reset`.' }],
+        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'kind', description: 'Which of the four mails this template replaces — a `mailTemplateKind`: `invite`, `verify`, `reset` or `login_code`.' }],
         query: null, request: mailTemplatePreviewRequest, response: mailOutcome,
         errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'validation_error', 'not_found', 'template_invalid', 'rate_limited', 'target_state_conflict'],
         transport: 'http',
@@ -1296,7 +1334,8 @@ export const ROUTES = [
         query: null, request: null, response: null, errors: [], transport: 'http',
         notes: 'HTML, and a GET rather than the body of the authorize response — so it is reloadable, bookmarkable and survives a back button, which ' +
             'the inline page it replaced was not. An expired, consumed, unknown or hand-edited interaction renders one page at `410`, and so does a ' +
-            'client whose dynamic registration lapsed in between.',
+            'client whose dynamic registration lapsed in between. It offers the email field and `Sign in with a passkey`, and opening it binds ' +
+            'the interaction to this browser with the browser-proof cookie, which every sign-in step after it checks.',
     },
     ...developerSignInRoutes('/mcp/oauth'),
     {
@@ -1347,7 +1386,8 @@ export const ROUTES = [
         audience: 'internal', auth: 'none', rateLimited: false, ownerTier: false, status: 200,
         params: [{ name: 'id', description: 'The interaction id minted by `GET /console/oauth/authorize`, which redirects the browser here.' }],
         query: null, request: null, response: null, errors: [], transport: 'http',
-        notes: 'HTML: the email field, `Email me a code`, and `Sign in with a passkey`. An expired, consumed, unknown or hand-edited interaction ' +
+        notes: 'HTML: the email field, `Email me a code`, and `Sign in with a passkey`. Opening it binds the interaction to this browser with the ' +
+            'browser-proof cookie, which every sign-in step after it checks. An expired, consumed, unknown or hand-edited interaction ' +
             'renders one page at `410`: which of the four it was is not a fact a stranger may learn, and to the person it is one fact anyway. The ' +
             'page resolves nothing about the address typed into it, so there is no enumeration oracle here at all.',
     },
@@ -1613,7 +1653,8 @@ export const ROUTES = [
         errors: ['rate_limited', 'validation_error', 'not_found', 'method_not_allowed'], transport: 'http',
         notes: '**`202` and an empty body for every request the policy allows**, in status, body and timing, whether or not the address names an ' +
             'active account of this app — a decoy like `POST /api/client/resend-verification`, so this is no enumeration oracle. A mail goes out ' +
-            'only for an account that may sign in. The code is six digits, valid ten minutes, takes five wrong attempts, and a new request expires ' +
+            'for an `active` account and for one still `pending_verification` — spending the code proves the address, as the verification link ' +
+            'would — and never for a `blocked` one or an unknown address. The code is six digits, valid ten minutes, takes five wrong attempts, and a new request expires ' +
             'the previous one for the same address; a request within sixty seconds of the last sends no second mail. The address is trimmed and ' +
             'compared case-insensitively. `404 not_found` is the **app identifier**, never the address; `403 method_not_allowed` when the app has ' +
             'the email-code method off. Limited per app, address and IP, so it cannot be used to mail somebody repeatedly.',
@@ -1697,8 +1738,10 @@ export const ROUTES = [
         summary: 'Mails an app user a reset link, and answers the same either way.',
         audience: 'client', auth: 'none', rateLimited: true, ownerTier: false, status: 202,
         params: [], query: null, request: clientPasswordResetRequest, response: null,
-        errors: ['rate_limited', 'validation_error', 'not_found'], transport: 'http',
+        errors: ['rate_limited', 'validation_error', 'not_found', 'method_not_allowed'], transport: 'http',
         notes: 'The pair of app identifier and address is the identifier: an app user\'s address is unique only within their app. ' +
+            '`403 method_not_allowed` when the app has the password method off — a reset link whose confirmation would be refused is not mailed; ' +
+            'the code names the app\'s policy, not a person. ' +
             'Status, body and timing are identical for a known and an unknown address. An account with no password — one created through an ' +
             'identity provider — is mailed nothing and still answers `202`. `404 not_found` is the **app identifier**, never the address. The link ' +
             'points at the app\'s `reset_url`, or at the hosted reset page when the app has configured none.',
@@ -1773,8 +1816,10 @@ export const ROUTES = [
         summary: "Changes an app user's own password and answers a fresh session.",
         audience: 'client', auth: 'developer_or_client', rateLimited: false, ownerTier: false, status: 200,
         params: [], query: null, request: passwordChangeRequest, response: sessionTokens,
-        errors: [...CLIENT_GUARD, 'validation_error', 'invalid_credentials', 'target_state_conflict'], transport: 'http',
-        notes: 'The guard admits all three caller kinds, but a password belongs to an app user specifically — a developer bearer or a server key ' +
+        errors: [...CLIENT_GUARD, 'validation_error', 'invalid_credentials', 'target_state_conflict', 'method_not_allowed'], transport: 'http',
+        notes: '`403 method_not_allowed` when the app has the password method off: a stored password stays stored but is not in use, so it is not ' +
+            'changed either. ' +
+            'The guard admits all three caller kinds, but a password belongs to an app user specifically — a developer bearer or a server key ' +
             'reaching this is `401 unauthorized`. Every other session of the account ends; the answer is the replacement pair, so the tab that made ' +
             'the change stays signed in. An app user belongs to one app, so "every session" is this app\'s. An account that has **no password** — ' +
             'an OIDC-only app user, which the schema admits — answers `409 target_state_conflict` naming the `password` field with rule `not_set`, ' +
@@ -1806,10 +1851,11 @@ export const ROUTES = [
         method: 'POST', path: '/api/client/two-factor/setup', section: 'client-auth',
         summary: 'Starts an authenticator setup and answers its secret and otpauth URL.',
         audience: 'client', auth: 'in_handler', rateLimited: true, ownerTier: false, status: 200,
-        params: [], query: null, request: clientTwoFactorSetupRequest, response: twoFactorSetupResponse,
+        params: [], query: null, request: clientTwoFactorSetupRequest, requestOptional: true, response: twoFactorSetupResponse,
         errors: ['rate_limited', 'validation_error', 'token_spent', 'unauthorized', 'target_state_conflict'], transport: 'http',
         notes: '**Two ways in, decided in the handler.** During sign-in the body carries the `two_factor_setup_required` challenge, and that is the ' +
-            'credential; from the app\'s own account settings the app user\'s bearer is, with no challenge. Neither is `401 unauthorized`, and a ' +
+            'credential; from the app\'s own account settings the app user\'s bearer is, with no challenge and an empty or missing body. Neither ' +
+            'is `401 unauthorized`, and a ' +
             'dead challenge is `410 token_spent`. `409 target_state_conflict` names `two_factor` with rule `off` when the app\'s policy is `off`. ' +
             'The secret is not in use until `POST /api/client/two-factor/setup/confirm` accepts a code from it; a second call replaces a pending ' +
             'secret, and an account that already has an authenticator keeps it until the new one is confirmed.',
@@ -2731,6 +2777,16 @@ export const ROUTES = [
             'platform will answer is owed a refusal, not a shorter answer they will mistake for the whole picture. `from_day <= to_day` is a ' +
             'cross-field rule no JSON Schema can express and is enforced here. The window is echoed back.',
     },
+    {
+        method: 'POST', path: '/api/feedback', section: 'org',
+        summary: 'Sends a message from a developer to the people who build Fleetless.',
+        audience: 'developer', auth: 'developer', rateLimited: true, ownerTier: false, status: 202,
+        params: [], query: null, request: feedbackRequest, response: feedbackResponse,
+        errors: [...DEVELOPER_GUARD, 'validation_error', 'rate_limited'], transport: 'http',
+        notes: 'The message is stored before any mail is tried, so `202` means it is kept whatever `mail` says: `sent`, `failed`, or ' +
+            '`not_configured` when this cloud has no feedback address. At most 10 messages per developer per hour; the 11th answers ' +
+            '`429 rate_limited` with `retry_after_ms`. Replies come by mail, to the sender\'s address.',
+    },
     /* ------------------------------------------------- assets (robot upload) */
     {
         method: 'POST', path: '/api/bridge/assets', section: 'assets',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fleetless/contracts",
-  "version": "6.0.0-next.1",
+  "version": "6.0.0-next.3",
   "description": "Fleetless wire contracts: the bridge-cloud protocol, the REST API schemas and the error codes, as zod schemas with generated JSON Schema and OpenAPI artifacts.",
   "license": "Apache-2.0",
   "author": "Dehne Robotik GmbH",