@fleetless/contracts 1.0.0

package/dist/routes.d.ts

@@ -0,0 +1,94 @@
+/**
+ * **The route manifest: every HTTP route the cloud registers, declared once.**
+ *
+ * The cloud's `test/route-manifest.test.ts` boots the server and asserts set
+ * equality with this list in both directions, so a route cannot be added,
+ * renamed or removed without this file moving with it. `scripts/export-schemas.ts`
+ * writes it to `artifacts/routes.json` (schemas resolved to artifact names)
+ * and derives `artifacts/openapi.json` from it; the docs site renders its
+ * route and field tables from those two files.
+ *
+ * `OAUTH_PATHS` (`oauth.ts`) was the precedent: nine paths declared once so
+ * two repositories could not spell them differently. Its `idpStart` entry
+ * named a route the cloud had deleted, and nothing noticed for months. This
+ * list exists so that cannot happen again — and the cloud test is the half
+ * that makes it true.
+ *
+ * **What an entry does not prove.** `errors` is hand-written: the codes a
+ * route is known to answer, read from its handler, the service it calls and
+ * the helpers they share. Nothing checks that each code is still reachable,
+ * and a code the route stopped emitting stays listed until a reader
+ * notices. A runtime tally across the suite was considered and rejected: a
+ * code no test provokes would look identical to one the route cannot emit.
+ *
+ * `audience` is who the documentation addresses; `auth` is the mechanism,
+ * and the cloud test checks it against the registered guards exactly
+ * (`preHandler` names, `preParsing` names, an anonymous rate limiter).
+ */
+import type { ZodType } from 'zod';
+import type { ErrorCode } from './errors.js';
+export type RouteMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type RouteAudience = 'developer' | 'client' | 'internal';
+export type RouteAuth = 'developer' | 'developer_or_client' | 'none' | 'robot_upload' | 'in_handler';
+export type RouteTransport = 'http' | 'websocket';
+export type RouteSection = 'health' | 'developer-auth' | 'client-auth' | 'org' | 'users' | 'apps' | 'robots' | 'config' | 'alerts' | 'commands' | 'cameras' | 'assets' | 'mcp' | 'transports';
+export interface RouteParam {
+    readonly name: string;
+    /** One sentence: what the segment identifies and where a caller gets it. */
+    readonly description: string;
+}
+export interface RouteEntry {
+    readonly method: RouteMethod;
+    /** The display path with `:name` params and no inline regex. */
+    readonly path: string;
+    readonly section: RouteSection;
+    /** One sentence ending in a full stop. */
+    readonly summary: string;
+    readonly audience: RouteAudience;
+    readonly auth: RouteAuth;
+    /** A rate limiter is registered as an anonymous preHandler. */
+    readonly rateLimited: boolean;
+    /** The handler additionally requires the Owner tier of a developer. */
+    readonly ownerTier: boolean;
+    /** The success status the handler answers with. */
+    readonly status: number;
+    readonly params: readonly RouteParam[];
+    readonly query: ZodType | null;
+    readonly request: ZodType | null;
+    /**
+     * The handler accepts a **missing** body; the schema still describes it when
+     * one is present. Absent means a body is required.
+     *
+     * It exists because the OpenAPI render marked every request body `required`,
+     * which documented a refusal `POST /api/robots/:id/jobs/:slug/cancel` does not
+     * make: it parses `request.body ?? {}`, and a bodyless `POST` was every
+     * caller's shape before `job_id` existed. Getting that wrong in the other
+     * direction is what W5's worst bug was — a bodyless `POST` with a JSON
+     * content type rejected outright — so this is a fact worth carrying rather
+     * than a default worth assuming.
+     */
+    readonly requestOptional?: true;
+    readonly response: ZodType | null;
+    /**
+     * For routes that answer bytes rather than JSON: the media type, or a family
+     * such as `image/*` where the producer decides it. Implies `response: null`.
+     *
+     * It exists because `response: null` alone says two different things — *this
+     * route sends no body* and *this route sends a body contracts cannot
+     * describe* — and the generated reference rendered both as **returns
+     * nothing**. Five routes that hand back a CSV, an XML document, a camera
+     * frame or an asset were documented as answering nothing at all.
+     */
+    readonly contentType?: string;
+    readonly errors: readonly ErrorCode[];
+    readonly transport: RouteTransport;
+    /** Markdown rendered under the route; the place for what the schema cannot say. */
+    readonly notes?: string;
+}
+export declare const ROUTE_SECTIONS: readonly {
+    readonly id: RouteSection;
+    readonly title: string;
+}[];
+/** The routes that verify a credential inside the handler; `auth: 'in_handler'` is refused elsewhere. */
+export declare const IN_HANDLER_ROUTES: readonly string[];
+export declare const ROUTES: readonly RouteEntry[];