@worker-protocol/hono 0.1.0

package/dist/surfaces.d.ts

@@ -0,0 +1,483 @@
+import { type RouteConfig, z } from "@hono/zod-openapi";
+/** ENDP-5 — on every protocol response, whatever it says. */
+export declare const RESPONSE_HEADERS: {
+    readonly "Worker-Protocol-Edition": {
+        readonly description: string;
+        readonly required: true;
+        readonly schema: {
+            readonly type: "string";
+            readonly pattern: "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$";
+        };
+    };
+    readonly "Worker-Protocol-Capability-Version": {
+        readonly description: string;
+        readonly required: true;
+        readonly schema: {
+            readonly type: "integer";
+            readonly minimum: 1;
+        };
+    };
+};
+export declare const readDescriptor: {
+    method: "get";
+    path: "/.well-known/worker-protocol";
+    summary: string;
+    description: string;
+    request: {
+        headers: z.ZodObject<{
+            "Worker-Protocol-Capability-Version": z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        }, z.core.$strip>;
+    };
+    responses: {
+        200: {
+            description: string;
+            headers: {
+                readonly "Worker-Protocol-Edition": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "string";
+                        readonly pattern: "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$";
+                    };
+                };
+                readonly "Worker-Protocol-Capability-Version": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                    };
+                };
+            };
+            content?: {
+                "application/json": {
+                    schema: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+                };
+            } | undefined;
+        };
+    };
+} & {
+    getRoutingPath(): "/.well-known/worker-protocol";
+};
+export declare const pollHealth: {
+    method: "get";
+    path: "/";
+    summary: string;
+    description: string;
+    request: {
+        headers: z.ZodObject<{
+            "Worker-Protocol-Capability-Version": z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        }, z.core.$strip>;
+    };
+    responses: {
+        200: {
+            description: string;
+            headers: {
+                readonly "Worker-Protocol-Edition": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "string";
+                        readonly pattern: "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$";
+                    };
+                };
+                readonly "Worker-Protocol-Capability-Version": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                    };
+                };
+            };
+            content?: {
+                "application/json": {
+                    schema: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+                };
+            } | undefined;
+        };
+    };
+} & {
+    getRoutingPath(): "/";
+};
+export declare const readMetric: {
+    method: "get";
+    path: "/";
+    summary: string;
+    description: string;
+    request: {
+        query: z.ZodObject<{
+            metric: z.ZodString;
+            granularity: z.ZodOptional<z.ZodEnum<{
+                day: "day";
+                hour: "hour";
+                month: "month";
+                week: "week";
+                year: "year";
+            }>>;
+            from: z.ZodOptional<z.ZodString>;
+            to: z.ZodOptional<z.ZodString>;
+            by: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodString>>, unknown>;
+            dimensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            cursor: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        headers: z.ZodObject<{
+            "Worker-Protocol-Capability-Version": z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        }, z.core.$strip>;
+    };
+    responses: {
+        200: {
+            description: string;
+            headers: {
+                readonly "Worker-Protocol-Edition": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "string";
+                        readonly pattern: "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$";
+                    };
+                };
+                readonly "Worker-Protocol-Capability-Version": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                    };
+                };
+            };
+            content?: {
+                "application/json": {
+                    schema: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+                };
+            } | undefined;
+        };
+    };
+} & {
+    getRoutingPath(): "/";
+};
+export declare const performAction: {
+    method: "post";
+    path: "/";
+    summary: string;
+    description: string;
+    request: {
+        query: z.ZodObject<{
+            action: z.ZodString;
+        }, z.core.$strip>;
+        headers: z.ZodObject<{
+            "Idempotency-Key": z.ZodOptional<z.ZodString>;
+            "Worker-Protocol-Capability-Version": z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        }, z.core.$strip>;
+        body: {
+            required: true;
+            description: string;
+            content: {
+                "application/json": {
+                    schema: never;
+                };
+            };
+        };
+    };
+    responses: {
+        200: {
+            description: string;
+            headers: {
+                readonly "Worker-Protocol-Edition": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "string";
+                        readonly pattern: "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$";
+                    };
+                };
+                readonly "Worker-Protocol-Capability-Version": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                    };
+                };
+            };
+            content?: {
+                "application/json": {
+                    schema: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+                };
+            } | undefined;
+        };
+        204: {
+            description: string;
+            headers: {
+                readonly "Worker-Protocol-Edition": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "string";
+                        readonly pattern: "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$";
+                    };
+                };
+                readonly "Worker-Protocol-Capability-Version": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                    };
+                };
+            };
+            content?: {
+                "application/json": {
+                    schema: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+                };
+            } | undefined;
+        };
+        202: {
+            description: string;
+            headers: {
+                readonly "Worker-Protocol-Edition": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "string";
+                        readonly pattern: "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$";
+                    };
+                };
+                readonly "Worker-Protocol-Capability-Version": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                    };
+                };
+            };
+            content?: {
+                "application/json": {
+                    schema: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+                };
+            } | undefined;
+        };
+    };
+} & {
+    getRoutingPath(): "/";
+};
+export declare const readTasks: {
+    method: "get";
+    path: "/";
+    summary: string;
+    description: string;
+    request: {
+        query: z.ZodObject<{
+            type: z.ZodOptional<z.ZodString>;
+            cursor: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        headers: z.ZodObject<{
+            "Worker-Protocol-Capability-Version": z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        }, z.core.$strip>;
+    };
+    responses: {
+        200: {
+            description: string;
+            headers: {
+                readonly "Worker-Protocol-Edition": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "string";
+                        readonly pattern: "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$";
+                    };
+                };
+                readonly "Worker-Protocol-Capability-Version": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                    };
+                };
+            };
+            content?: {
+                "application/json": {
+                    schema: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+                };
+            } | undefined;
+        };
+    };
+} & {
+    getRoutingPath(): "/";
+};
+export declare const takeNudge: {
+    method: "post";
+    path: "/";
+    summary: string;
+    description: string;
+    request: {
+        headers: z.ZodObject<{
+            "Worker-Protocol-Capability-Version": z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        }, z.core.$strip>;
+        body: {
+            required: true;
+            description: string;
+            content: {
+                "application/json": {
+                    schema: never;
+                };
+            };
+        };
+    };
+    responses: {
+        204: {
+            description: string;
+            headers: {
+                readonly "Worker-Protocol-Edition": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "string";
+                        readonly pattern: "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$";
+                    };
+                };
+                readonly "Worker-Protocol-Capability-Version": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                    };
+                };
+            };
+            content?: {
+                "application/json": {
+                    schema: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+                };
+            } | undefined;
+        };
+    };
+} & {
+    getRoutingPath(): "/";
+};
+export declare const readAlerts: {
+    method: "get";
+    path: "/";
+    summary: string;
+    description: string;
+    request: {
+        query: z.ZodObject<{
+            cursor: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        headers: z.ZodObject<{
+            "Worker-Protocol-Capability-Version": z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        }, z.core.$strip>;
+    };
+    responses: {
+        200: {
+            description: string;
+            headers: {
+                readonly "Worker-Protocol-Edition": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "string";
+                        readonly pattern: "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$";
+                    };
+                };
+                readonly "Worker-Protocol-Capability-Version": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                    };
+                };
+            };
+            content?: {
+                "application/json": {
+                    schema: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+                };
+            } | undefined;
+        };
+    };
+} & {
+    getRoutingPath(): "/";
+};
+export declare const readActivity: {
+    method: "get";
+    path: "/";
+    summary: string;
+    description: string;
+    request: {
+        query: z.ZodObject<{
+            cursor: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        headers: z.ZodObject<{
+            "Worker-Protocol-Capability-Version": z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        }, z.core.$strip>;
+    };
+    responses: {
+        200: {
+            description: string;
+            headers: {
+                readonly "Worker-Protocol-Edition": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "string";
+                        readonly pattern: "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$";
+                    };
+                };
+                readonly "Worker-Protocol-Capability-Version": {
+                    readonly description: string;
+                    readonly required: true;
+                    readonly schema: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                    };
+                };
+            };
+            content?: {
+                "application/json": {
+                    schema: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+                };
+            } | undefined;
+        };
+    };
+} & {
+    getRoutingPath(): "/";
+};
+export type Surface = {
+    /** The generated file, without `.json`. */
+    document: string;
+    /** The Capability, or `descriptor` for the one route this protocol fixes. */
+    capability: string;
+    /**
+     * The server variable this document is served under — which is a *declared address* and never a
+     * path. ENDP-1 says no reader assembles an address, so a generated client is constructed with
+     * one read from the Descriptor and resolved per DESC-12, and concatenates nothing.
+     */
+    server: {
+        variable: string;
+        rule: string;
+        description: string;
+    };
+    title: string;
+    description: string;
+    /** The route this document describes: one declared address, one operation. */
+    route: RouteConfig;
+};
+export declare const SURFACES: Surface[];
+/**
+ * What this file deliberately does not describe.
+ *
+ * - **`events`.** It has no address: it travels over a broker this protocol declines to name, which
+ *   is the one case DESC-22 leaves the shared entry's address optional for. There is no call to
+ *   describe, and inventing a document for it would be the artifact claiming a surface the
+ *   specification refuses to fix.
+ * - **Anything whose shape is the Worker's own.** An Action's input and result, a Task's payload, an
+ *   event's data. Each is a JSON Schema a Worker declares in its Descriptor. A Worker that mounts
+ *   these routes and asks its own app for a document gets them in it, because that document is
+ *   generated from that Worker's routes and not from this file.
+ * - **A dimension named as a query parameter.** MET-16 spells a dimension into a parameter of its
+ *   own name, and those names are the Worker's. `dimensions` above is the OpenAPI shape for that
+ *   and never travels under its own name.
+ */