@fleetless/contracts 6.2.0 → 6.3.0-next.1

package/artifacts/routes.json

@@ -16,6 +16,10 @@
       "id": "org",
       "title": "Org"
     },
+    {
+      "id": "billing",
+      "title": "Billing"
+    },
     {
       "id": "users",
       "title": "Team"
@@ -6414,7 +6418,7 @@
         "target_state_conflict"
       ],
       "transport": "http",
-      "notes": "Owner tier, and **downward only**: this route moves the org to a lower plan or cancels it outright to Basic. It never moves the org up — until payment exists, an upgrade or an add-on is not this route's job at all, and is handled today as a Feedback request that Fleetless then applies through the admin route. `409 target_state_conflict` names `target_plan` with rule `not_lower` when the chosen plan is not below the org's current one; with rule `locked_basic_only` when the org is locked (`orgLock`) and the chosen plan is anything but Basic; and with rule `migration_basic_only` when the org is still on the beta, awaiting the switch to priced plans, and the chosen plan is anything but Basic — that choice is exactly what the org lands on at the switch. An owner is never named in `keep` and always stays, but still counts against the target plan's `seats`; `409 plan_limit` names `seats` when the owners alone already exceed it, and names whichever other limit `keep` still exceeds otherwise. `keep` is `null` when the org's current usage already fits the target plan outright and nothing is deleted; named, it lists exactly the robots, apps, app users and developers that stay. The choice is stored as `pending_change` and takes effect at `period_ends_at` — **everything of the chosen kind not named in `keep` is deleted at that instant, never before** — except a choice made while the org is locked, which takes effect at once, and a beta org's choice, which takes effect at the switch date instead. Anything created while the choice is pending is checked against the target plan too and, when it passes, is folded into `keep`, so exactly what the confirmation counted is what is actually deleted. A later `PUT` replaces a still-pending choice outright."
+      "notes": "Owner tier, and **downward only**: this route moves the org to a lower plan or cancels it outright to Basic. It never moves the org up — an upgrade or an add-on goes through the billing routes instead (`POST /api/billing/checkout`, `POST /api/billing/change`). `409 target_state_conflict` names `target_plan` with rule `not_lower` when the chosen plan is not below the org's current one; with rule `locked_basic_only` when the org is locked (`orgLock`) and the chosen plan is anything but Basic; and with rule `migration_basic_only` when the org is still on the beta, awaiting the switch to priced plans, and the chosen plan is anything but Basic — that choice is exactly what the org lands on at the switch. An owner is never named in `keep` and always stays, but still counts against the target plan's `seats`; `409 plan_limit` names `seats` when the owners alone already exceed it, and names whichever other limit `keep` still exceeds otherwise. `keep` is `null` when the org's current usage already fits the target plan outright and nothing is deleted; named, it lists exactly the robots, apps, app users and developers that stay. The choice is stored as `pending_change` and takes effect at `period_ends_at` — **everything of the chosen kind not named in `keep` is deleted at that instant, never before** — except a choice made while the org is locked, which takes effect at once, and a beta org's choice, which takes effect at the switch date instead. Anything created while the choice is pending is checked against the target plan too and, when it passes, is folded into `keep`, so exactly what the confirmation counted is what is actually deleted. A later `PUT` replaces a still-pending choice outright."
     },
     {
       "method": "DELETE",
@@ -6464,10 +6468,330 @@
         "not_found",
         "validation_error",
         "plan_limit",
+        "rate_limited",
+        "target_state_conflict"
+      ],
+      "transport": "http",
+      "notes": "Every public host answers `404 not_found` for every `/api/admin/*` path — this route is reachable only on the cloud's private address — and that same address answers `404` here too while `OPS_API_TOKEN` is not configured, so a door with no key behind it reads exactly like one nobody opened. An unknown `:id` is the same `404`. Applies at once, never queued as a `pending_change`, and only when the org's current usage fits the result: `409 plan_limit` when a lower plan, a lowered override or a removed add-on would leave the org over a limit — the operator never deletes an org's things, only the owner's own choice does. On success it also withdraws any `pending_change`, ends a beta org's wait for the switch and lifts a lock. Audited as `org.plan_changed` with the `fleetless` actor, never a developer's — the row names what an operator did, not who in the org asked for it. `409 target_state_conflict` names `currency` or `period_ends_at` with rule `billed` when the org has a billing account in `active` or `past_due` and the request names either field: both are fixed at the first payment and billing, not the operator, owns them from then on. The plan itself keeps working on a billed org — a plan, an add-on or an override the operator sets here is charged from the next renewal, except `enterprise` and `basic`, which the sweep cancels the billing account for instead."
+    },
+    {
+      "method": "GET",
+      "path": "/api/billing",
+      "section": "billing",
+      "summary": "Reads the org's billing account, payment method and invoices.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": true,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "billing-view",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "tier_required"
+      ],
+      "transport": "http",
+      "notes": "`available: false` when `MOLLIE_API_KEY` is not configured — this cloud takes no payments, and every mutating route on this page answers `503 billing_unavailable` instead of acting. `account` is `null` before the org has ever checked out; the plan and its limits still come from `GET /api/org/plan` (#103) and are not repeated here."
+    },
+    {
+      "method": "POST",
+      "path": "/api/billing/checkout",
+      "section": "billing",
+      "summary": "Starts a Mollie checkout for a plan, or an upgrade paid at once.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": true,
+      "ownerTier": true,
+      "status": 201,
+      "params": [],
+      "query": null,
+      "request": "checkout-request",
+      "response": "checkout-response",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "tier_required",
+        "validation_error",
+        "plan_limit",
+        "target_state_conflict",
+        "rate_limited",
+        "billing_unavailable",
+        "payment_provider_unavailable"
+      ],
+      "transport": "http",
+      "notes": "Rate limited on the `billing.checkout` bucket, same as `POST /api/billing/payment-method` and `POST /api/billing/invoices/:id/pay` — the three routes that mint a Mollie checkout. `400 validation_error` names who may not pay with these rules: `{ field: 'billing.address.country', rule: 'eu_person' }` for a person in another EU country, `{ field: 'billing.vat_id', rule: 'vat_id_required' }` for a company there with no VAT ID, `{ field: 'billing.vat_id', rule: 'vat_id_invalid' }` once VIES has said so, and `{ field: 'accept_withdrawal', rule: 'required' }` for a person who did not confirm it. `409 target_state_conflict` names `plan` with rule `already_billed` when the org already has an `active` or `past_due` billing account — checkout is for the first payment only, every later change is `POST /api/billing/change`. `checkout_url` is Mollie's hosted page; the return lands on `<console>/settings/billing?checkout=<checkout_id>`, which polls `GET /api/billing/checkout/:id` until the webhook — or the poll itself — has reconciled the payment. `409 plan_limit` is the org's own usage against the plan being bought."
+    },
+    {
+      "method": "GET",
+      "path": "/api/billing/checkout/:id",
+      "section": "billing",
+      "summary": "Reads a checkout's status, for the return page's poll.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": true,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The checkout id from `checkoutResponse.checkout_id`, carried on the return URL."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": "checkout-status",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "tier_required",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "Calls the same `reconcilePayment(deps, molliePaymentId)` the webhook calls, so a return page that lands before the webhook does still sees the payment applied — this route, not the webhook, is what the dev stack and the test-mode suite rely on, since Mollie refuses an unreachable webhook URL. `plan` is the org's plan after applying, unchanged unless `purpose` is `upgrade` and `status` is `paid`."
+    },
+    {
+      "method": "POST",
+      "path": "/api/billing/vat-id/check",
+      "section": "billing",
+      "summary": "Checks a VAT ID against VIES, for the checkout form and the details page.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": true,
+      "ownerTier": true,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": "vat-id-check-request",
+      "response": "vat-id-check-response",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "tier_required",
+        "validation_error",
         "rate_limited"
       ],
       "transport": "http",
-      "notes": "Every public host answers `404 not_found` for every `/api/admin/*` path — this route is reachable only on the cloud's private address — and that same address answers `404` here too while `OPS_API_TOKEN` is not configured, so a door with no key behind it reads exactly like one nobody opened. An unknown `:id` is the same `404`. Applies at once, never queued as a `pending_change`, and only when the org's current usage fits the result: `409 plan_limit` when a lower plan, a lowered override or a removed add-on would leave the org over a limit — the operator never deletes an org's things, only the owner's own choice does. On success it also withdraws any `pending_change`, ends a beta org's wait for the switch and lifts a lock. Audited as `org.plan_changed` with the `fleetless` actor, never a developer's — the row names what an operator did, not who in the org asked for it."
+      "notes": "Rate limited on its own `billing.vat_check` bucket, sized for a form checked on blur rather than for a checkout. Never refuses for an `unverified` VIES answer — the checkout itself accepts `unverified` and the hourly sweep re-checks it — this route only reports what VIES currently says, in a different place for the same ID, entered either at checkout or on `PATCH /api/billing/details`."
+    },
+    {
+      "method": "PATCH",
+      "path": "/api/billing/details",
+      "section": "billing",
+      "summary": "Edits the billing account's invoice email or VAT ID.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": true,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": "billing-details-update",
+      "response": "billing-view",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "tier_required",
+        "validation_error",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "`404 not_found` when the org has no billing account yet — there is nothing here to edit before the first checkout. A new `vat_id` is re-checked through VIES the same way `POST /api/billing/vat-id/check` does; a valid ID entered here lifts the block a definitive `invalid` answer placed on the next renewal."
+    },
+    {
+      "method": "POST",
+      "path": "/api/billing/change",
+      "section": "billing",
+      "summary": "Moves the org's plan, cycle or add-ons, charging increases at once.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": true,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": "billing-change-request",
+      "response": "billing-change-response",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "tier_required",
+        "validation_error",
+        "plan_limit",
+        "target_state_conflict",
+        "billing_unavailable",
+        "payment_provider_unavailable"
+      ],
+      "transport": "http",
+      "notes": "The body names the **absolute** target — plan, cycle and add-ons — never a delta: the route compares it with the org's current state and splits the difference. The increasing part is charged now, through the same proration `changeNetCents` computes, and takes effect the moment Mollie accepts the `recurring` payment with anything but `failed`, `canceled` or `expired` — cards answer within seconds, SEPA stays `pending` for days; if Mollie refuses or does not answer, nothing is applied and this answers `502 payment_provider_unavailable` instead. The decreasing part — a lower plan, yearly → monthly, fewer add-ons — is stored as a pending change and applied at the period's end, same as `PUT /api/org/plan/change`; a lower plan over the target's limits answers `409 plan_limit` and the console opens #103's choose-what-stays page. Any increase first withdraws a pending downgrade or cancel, exactly as the admin route does. `409 target_state_conflict` names `billing` with rule `no_account` (no checkout yet — use `POST /api/billing/checkout`), `past_due` (an open invoice has to be paid first) or `no_valid_mandate` (the payment method needs renewing first, `POST /api/billing/payment-method`). `charged` in the response is the invoice from the part charged now, or `null` when the whole request was a decrease."
+    },
+    {
+      "method": "POST",
+      "path": "/api/billing/payment-method",
+      "section": "billing",
+      "summary": "Starts a Mollie checkout for a new payment method.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": true,
+      "ownerTier": true,
+      "status": 201,
+      "params": [],
+      "query": null,
+      "request": "payment-method-change-request",
+      "response": "checkout-response",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "tier_required",
+        "validation_error",
+        "not_found",
+        "rate_limited",
+        "billing_unavailable",
+        "payment_provider_unavailable"
+      ],
+      "transport": "http",
+      "notes": "Rate limited on the `billing.checkout` bucket, same as `POST /api/billing/checkout`. Creates a `first` payment on the existing Mollie customer: with an open invoice, the new payment **is** that invoice's amount, for any method the currency allows, and pays it; without one, `card` and `paypal` use a zero amount and `sepa` is refused — Mollie allows a zero-amount first payment for card and PayPal only — `400 validation_error` with `{ field: 'method', rule: 'sepa_needs_open_invoice' }`. SEPA is also refused outside the org's EUR currency, `{ field: 'method', rule: 'sepa_eur_only' }`. `404 not_found` when the org has no billing account yet. When the new mandate turns `valid`, every other mandate of the customer is revoked."
+    },
+    {
+      "method": "POST",
+      "path": "/api/billing/cancel",
+      "section": "billing",
+      "summary": "Schedules the org's plan to cancel to Basic at the period's end.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": true,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": "billing-cancel-request",
+      "requestOptional": true,
+      "response": "billing-view",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "tier_required",
+        "validation_error",
+        "not_found",
+        "plan_limit"
+      ],
+      "transport": "http",
+      "notes": "A body is optional — `reason` alone, and nobody but Fleetless reads it. `404 not_found` when the org has no billing account to cancel. Takes effect at the period's end, nothing credited or refunded; over Basic's limits this is refused `409 plan_limit` and the console sends the owner to #103's choose-what-stays page instead, the same as a plan downgrade. \"Cancel at period end\" is not a flag here — it reads as `pending_change.target_plan === 'basic'` on `GET /api/org/plan`."
+    },
+    {
+      "method": "POST",
+      "path": "/api/billing/resume",
+      "section": "billing",
+      "summary": "Withdraws a scheduled cancel, keeping the current plan.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": true,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "billing-view",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "tier_required",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "`404 not_found` when nothing is pending — there is no scheduled cancel to withdraw. The org stays on its current plan, unchanged."
+    },
+    {
+      "method": "GET",
+      "path": "/api/billing/invoices/:id/pdf",
+      "section": "billing",
+      "summary": "Downloads one invoice's rendered PDF.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": true,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The invoice id, from `billingInvoice.id` in `GET /api/billing`'s `invoices`."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": null,
+      "contentType": "application/pdf",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "tier_required",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "Rendered once, with `pdfkit`, when the invoice is issued, and stored as bytes — an issued invoice never changes, so this always answers the same PDF for the same id. `404 not_found` for an unknown id or one from another org."
+    },
+    {
+      "method": "POST",
+      "path": "/api/billing/invoices/:id/pay",
+      "section": "billing",
+      "summary": "Pays one open invoice, through a new Mollie payment.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": true,
+      "ownerTier": true,
+      "status": 201,
+      "params": [
+        {
+          "name": "id",
+          "description": "The invoice id, from `billingInvoice.id`, of the open invoice to pay."
+        }
+      ],
+      "query": null,
+      "request": null,
+      "response": "checkout-response",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "tier_required",
+        "not_found",
+        "target_state_conflict",
+        "rate_limited",
+        "billing_unavailable",
+        "payment_provider_unavailable"
+      ],
+      "transport": "http",
+      "notes": "Rate limited on the `billing.checkout` bucket, same as `POST /api/billing/checkout`. `409 target_state_conflict` names `invoice` with rule `not_open` when the invoice is already `paid` or `uncollectible` — there is nothing left to pay. Paying the open invoice of a locked org unlocks it and keeps the plan running to the period's end, the same as a renewal that succeeds on a retry. `404 not_found` for an unknown id or one from another org."
+    },
+    {
+      "method": "POST",
+      "path": "/api/billing/mollie/webhook",
+      "section": "billing",
+      "summary": "Takes Mollie's payment-changed notification and reconciles the payment.",
+      "audience": "internal",
+      "auth": "none",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [],
+      "transport": "http",
+      "notes": "**The body is never trusted**: it names only a payment id (`id=tr_…`, form-encoded, Mollie's own shape), and this route does nothing with it but call `reconcilePayment(deps, molliePaymentId)` — the same function `GET /api/billing/checkout/:id` and the hourly sweep call — which fetches the payment from Mollie itself and applies what Mollie says, idempotently. Rate limited on the `billing.webhook` bucket, per ip, 600/min — generous, because this is Mollie's own infrastructure calling, not a browser. **Every answer is `200`**, including an id this cloud does not recognise, which is logged and otherwise ignored, **except a processing fault, which is `500`** so Mollie retries the notification rather than this cloud losing it. `auth: 'none'` because Mollie signs nothing Fleetless checks here — the payment is only ever trusted once fetched back from Mollie's own API with the configured key."
     },
     {
       "method": "POST",

package/artifacts/schema/billing-address.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "line1": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200,
+      "description": "Street and number, or the first address line."
+    },
+    "line2": {
+      "anyOf": [
+        {
+          "type": "string",
+          "maxLength": 200
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "A second address line, or `null` when there is none."
+    },
+    "postal_code": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 20,
+      "description": "Postal or ZIP code."
+    },
+    "city": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 100,
+      "description": "City or town."
+    },
+    "country": {
+      "type": "string",
+      "pattern": "^[A-Z]{2}$",
+      "description": "The billing country. Decides VAT (`vatFor`) and currency (`currencyForCountry`)."
+    }
+  },
+  "required": [
+    "line1",
+    "line2",
+    "postal_code",
+    "city",
+    "country"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/billing-cancel-request.schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "reason": {
+      "description": "An optional free-text reason. Shown to nobody but Fleetless.",
+      "type": "string",
+      "maxLength": 500
+    }
+  },
+  "additionalProperties": false
+}

package/artifacts/schema/billing-change-request.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "plan": {
+      "description": "The target plan. Omitted leaves the plan as it is.",
+      "type": "string",
+      "enum": [
+        "plus",
+        "pro"
+      ]
+    },
+    "cycle": {
+      "description": "The target cycle. Omitted leaves the cycle as it is.",
+      "type": "string",
+      "enum": [
+        "monthly",
+        "yearly"
+      ]
+    },
+    "addons": {
+      "description": "Absolute add-on counts to end up with, not a delta. Omitted leaves add-ons as they are.",
+      "type": "object",
+      "properties": {
+        "seats": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "description": "Extra developer seats, one each."
+        },
+        "robots": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "description": "Extra robots, one each."
+        },
+        "apps": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "description": "Extra apps, one each."
+        },
+        "app_user_packs": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "description": "Packs of five extra app users."
+        },
+        "live_video_packs": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "description": "Packs of 250 extra hours of app-user live video per month."
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}