Novel Systems API

Liveness and database reachability.

getHealth

Unauthenticated and outside /v1 on purpose: it is infrastructure, not API surface, and the load balancer that calls it has no credentials. Returns 503 rather than 200-with-a-status-field, because a green check on a broken service is worse than no check at all.

The route table of the process answering this request.

getRoutes

Exists so that a contract check can fail. The obvious way to ask a live deployment whether it serves a path is to call it unauthenticated and read the status, and that does not work here: the guards are mounted on the routers rather than on each route, so authentication runs before Express matches a path within the router and a real path and an invented one both answer 401 with the same envelope. Under `/api/v1` that test cannot fail, which is a worse state than having no test.

So the process says what it serves, walked from the router stack it actually dispatches against — not parsed from source, because the deployed artefact is built from a different repository and reading source in CI cannot describe it. `scripts/check-deployed-api.mjs` diffs this against the document you are reading now.

Unauthenticated, and it discloses nothing this document does not already publish: methods and paths, no handlers, no schemas, no configuration. The authorisation on each route is the control, and it is unchanged.

Which of the three integrations this deployment can actually begin.

getConnectors

Unauthenticated, for the audience that cannot authenticate: someone evaluating whether a connector they read about on the marketing site is a switch they can flip. The field mappings, the system-of-record rules and the deployment path are all published as prose. This is the endpoint behind them.

Three states, derived from the adapters rather than typed anywhere:

- `operator_credentials_missing` — this deployment holds no application credentials for the provider. There is no consent screen to send anyone to, and no tenant can begin. The connector is built; it is not connectable here. - `awaiting_tenant_consent` — the platform side is complete. Each organisation authorises its own account and nothing syncs until an administrator does. - `platform_account_live` — configured, and the account is ours rather than the tenant's. Stripe is the only provider shaped this way.

It reports no tenant rows and does not name the environment variables behind a gap. Those stay behind the ADMIN guard on `GET /api/v1/integrations`, which answers the operator's question — *what do I set* — rather than the buyer's. Whether a Connect button would work is a fact anyone can establish by pressing it; the name of the variable holding a client secret is not.

Exchange workspace, email and password for a bearer token.

login

The workspace subdomain is part of the credential, not something discovered from the email: addresses are unique per organization, not globally. Wrong password, unknown email, unknown workspace and disabled account all return the same 401 with the same timing.

The caller's own profile and organization.

getCurrentUser

Exists so a client can recover its identity after a reload without decoding the token itself. The role comes from the database, not from the token, so a role changed after issue takes effect on the next call.

The tenant's quotes, newest first.

listQuotes

Cursor paginated, not offset: this table grows while you read it, and offsets both skip and repeat rows when a colleague saves a quote mid-scroll. Pass the `next_cursor` from the previous page as `cursor`.

Price a configuration server-side.

calculateQuote

The client sends dimensions and SKU codes and nothing else. It does not send costs, and if it did they would be ignored: every figure in the response is resolved from the tenant's own rate card inside the transaction.

`targetMargin` is a fraction — 0.50, never 50. Omitting it prices at the floor. A value above the floor is accepted without ceremony; a value below it requires `marginOverride.reason` and an ADMIN token, and the reason is stored on the quote. See D-001 in DECISIONS.md.

`persist: false` prices and discards. `persist: true` writes the quote and returns its id and per-tenant sequential number.

Approve a quote and fire `quote.approved`.

approveQuote

Its own endpoint rather than a PATCH on status, because approval is the moment a quote stops being a working document and becomes a commitment. It has side effects — webhooks to the tenant's accounting system — that a general-purpose field update should not be able to trigger by accident.

Mint a hosted Stripe payment page for an approved quote.

createQuoteCheckoutSession

The *pay now* path. Approval already fires an invoice with net-14 terms through the integration fan-out, which is what a commercial buyer expects; this endpoint is the other option — a hosted card page, returned as a URL the product can put behind a button. Neither is the default, because which one a job wants is a commercial question.

Amounts are the quote's own per-line integers, sent with `quantity: 1` so Stripe cannot recompute a line and land a cent away from the document that was approved. HST is an explicit thirteen-percent line, not Stripe Tax, which computes zero until a registration is configured and does so silently.

`return_url` is optional and must be an origin already in `CORS_ALLOWED_ORIGINS`. A caller-supplied redirect echoed into a page hosted on `checkout.stripe.com` is an open redirect on an origin both a phishing filter and a human trust, so the allowlist is checked rather than the string merely being parsed. Omitting it returns the payer to the first configured origin.

Calling twice returns the still-open session with `reused: true` rather than minting a second live payment link. Once the quote is paid the endpoint returns 409 — a second payable page for a settled job is how a customer pays twice.

The Stripe invoice written when this quote was approved.

getQuoteInvoice

Approval fans out to the configured connectors, and Stripe's adapter responds by resolving a customer, posting one invoice item per quote line plus an explicit HST line, creating the invoice and finalising it. This endpoint returns that document. It is a read — nothing at Stripe is created or changed by calling it.

It is the companion to `POST /quotes/{id}/checkout-session`, not a duplicate of it. That endpoint mints a hosted card page for paying now; this one returns the net-14 invoice that already exists, with `hosted_invoice_url` and `invoice_pdf_url` pointing at Stripe's own copies.

`mode` is derived from the `livemode` flag Stripe stamps on the object, not from which key the deployment holds — so a caller asking whether it is looking at test data gets an answer that travelled with the artifact.

`tax_cents` is nullable and the nullability is deliberate. This platform does not use Stripe Tax, which computes zero until a registration is configured on the account and does so silently; HST is posted as an ordinary line and identified on the way back by the description we wrote. Null means no line carried that label. Zero would mean the invoice has no tax on it, which on a Canadian total is a different claim.

Make sure an approved quote has an invoice at Stripe.

writeQuoteInvoice

The repair path for the `GET` above, and the only way an already-approved quote can acquire an invoice.

Approval fires the connector fan-out exactly once and `POST /approve` answers 409 on a second attempt — deliberately, because two approvals would mean two invoices for one job. The consequence is that a quote whose Stripe leg failed, or one approved before the connector existed, had no second chance. This is it.

Idempotent, and by three independent mechanisms rather than one. A recorded successful sync short-circuits before any call to Stripe and the existing invoice is returned unchanged. Every mutating call the adapter makes carries an `Idempotency-Key` derived from the quote id, so a retry after a timeout re-reads Stripe's stored response rather than creating a second document. And the sync table's unique key on `(organization, provider, entity type, quote)` makes the record itself single. So the accurate description is not "this creates an invoice" but "this ensures exactly one exists" — `created` tells you which case you were in, and `201` versus `200` says the same thing.

It repairs one connector for one quote. It does not re-fire the tenant's `quote.approved` webhook or the QuickBooks and Salesforce legs: a missing Stripe invoice is not a reason to tell everyone else the quote was approved a second time.

Amounts come from the calculation stored at approval, never from a recalculation. On a path that may run an arbitrary time after the quote was agreed, today's SKU costs would bill a different document from the one the customer accepted.

Scheduled work, soonest first.

listWorkOrders

A TECHNICIAN sees only their own jobs — the mobile app renders this list as the day's route. Note what the response does not carry: no cost, no margin, no quote total.

Dispatch a job. ADMIN only.

createWorkOrder

Creating work is a dispatch decision; quoting it is not. Both references are verified inside the tenant transaction before the insert, so a cross-tenant id returns a 404 naming which reference was wrong rather than an opaque conflict.

Move a work order through the dispatch state machine.

updateWorkOrderStatus

PENDING → DISPATCHED or CANCELLED. DISPATCHED → COMPLETED, PENDING or CANCELLED. COMPLETED and CANCELLED are terminal: reopening a completed job would destroy the timestamp billing runs off, and a cancelled job that comes back is a new work order.

Idempotent. Sending the status a record already has returns 200 with `unchanged: true` rather than a conflict, because a technician on intermittent signal will send the same completion twice.

Every provider this deployment knows about, and the caller's own connection.

listIntegrations

Two different questions, answered separately on purpose. `configured` is about the platform: whether this deployment holds the client credentials the provider needs at all. `connection` is about the tenant: whether this organization has consented. A UI that conflates them tells an administrator to reconnect when the thing that is actually missing is an environment variable only we can set, and `configuration.summary` exists so the wrong instruction is never the one shown.

No token, ciphertext or secret appears in this response. The only thing said about credentials is when they expire.

What each provider did with each approved quote.

listIntegrationSyncs

The answer to "did the invoice go out". A SKIPPED row is a real answer — it means the provider was not connected when the quote was approved, so nothing was attempted — and it is recorded rather than left as silence, because silence is indistinguishable from a bug.

Begin an OAuth consent flow.

connectIntegration

Returns the provider's consent URL rather than redirecting to it. A 302 from an XHR is followed by the browser transparently and lands the provider's HTML consent page inside a fetch the client cannot render, so the client has to move the top-level window itself.

`stripe` is rejected with a 400. Stripe here is the platform's own account, not a per-tenant grant, so there is nothing for a tenant to consent to — and a connect flow that silently succeeds while doing nothing is worse than a refusal that says why.

Forget this organization's credentials for a provider.

disconnectIntegration

Idempotent, and destructive on purpose: the stored ciphertext is cleared rather than superseded. A history of retired refresh tokens is a history of live ones. Sync rows are kept — they are the tenant's audit trail of invoices that already exist in someone else's system, and deleting them would not unsend anything.

The provider's redirect at the end of consent.

oauthCallback

Public by necessity. This is a top-level browser navigation from the provider's own domain: it carries no cookie of ours and no bearer token, and nothing about the request is under our control except the signed `state` we put into the authorize URL ten minutes earlier. That signature is the authentication.

Not for programmatic use, and the only endpoint in this API that answers with HTML — a human is looking at it. Every outcome including a refusal renders a page rather than an error envelope; pressing Deny is a completed flow with a no in it, not a validation failure.

Stripe's event delivery endpoint.

stripeWebhook

Public, and authenticated by an HMAC over the exact bytes Stripe sent — it has no credential of ours to present. The body is read raw for that reason: parsing and re-serialising JSON is not byte-identical to its input, so a handler working from a parsed object cannot verify anything.

Returns 200 for events it acts on and events it does not, distinguished by `handled`. Stripe retries any non-2xx with backoff for three days, so a 500 on an event type we have no handler for buys three days of retrying something that will never succeed. A failed signature is the one case where retrying is right, and the one case that answers 4xx.

`invoice.paid` sets `paid_at` on the originating quote, guarded on that column being null so a replayed delivery cannot rewrite the date a tenant was paid.