openclaw-brokerkit 0.3.3 → 0.3.4

package/README.md

@@ -24,6 +24,24 @@ pnpm --filter openclaw-brokerkit build
 openclaw plugins install --link ./plugins/openclaw
 ```
 
+## Operator V1 consumers
+
+Trusted hosts can consume the same generated Operator V1 types and runtime
+validators as the plugin without installing OpenClaw:
+
+```ts
+import {
+  parseRequestPage,
+  type RequestPage,
+} from "openclaw-brokerkit/operator-v1";
+
+const page: RequestPage = parseRequestPage(await response.json());
+```
+
+The subpath is generated from BrokerKit's canonical OpenAPI document. Its
+standalone validators use no runtime code generation and reject unknown fields,
+invalid bounds, unsafe integers, and protocol drift.
+
 ## Choose a trust mode
 
 - `direct` trusts the OpenClaw process with operator SecretRefs and enables

package/dist/src/generated/openapi-operator-v1.d.ts

@@ -0,0 +1,458 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export interface paths {
+    "/.well-known/brokerkit-operator": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["discoverOperator"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/healthz": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["operatorHealth"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/readyz": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["operatorReady"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/operator/v1/requests": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** @description Target fields use additional bounded query names with the target. prefix. */
+        get: operations["listOperatorRequests"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/operator/v1/requests/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["getOperatorRequest"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/operator/v1/requests/{id}/{action}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["decideOperatorRequest"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/operator/v1/events": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["streamOperatorEvents"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        Descriptor: {
+            /** @constant */
+            api_version: "brokerkit.io/operator/v1";
+        };
+        Health: {
+            status: string;
+        };
+        /** @enum {string} */
+        Action: "approve" | "deny" | "revoke";
+        /** @enum {string} */
+        Status: "pending" | "active" | "denied" | "canceled" | "expired" | "consumed" | "revoked";
+        /** @enum {string} */
+        StatusGroup: "pending" | "active" | "history" | "all";
+        Fact: {
+            label: string;
+            value: string;
+        };
+        Warning: {
+            severity: components["schemas"]["PresentationRisk"];
+            text: string;
+        };
+        /** @enum {string} */
+        PresentationRisk: "unknown" | "low" | "medium" | "high" | "critical";
+        Presentation: {
+            risk: components["schemas"]["PresentationRisk"];
+            title: string;
+            summary?: string;
+            target: string;
+            facts?: components["schemas"]["Fact"][];
+            warnings?: components["schemas"]["Warning"][];
+            plan_hash?: string;
+        };
+        ApprovalBounds: {
+            max_duration_seconds: number;
+            max_uses: number | null;
+        };
+        Constraints: {
+            duration_seconds?: number;
+            max_uses?: number | null;
+        };
+        NotificationDecision: {
+            /** @constant */
+            kind: "telegram";
+            renderer: string;
+            decision_token: string;
+            chat_id: number;
+            message_id: number;
+            text: string;
+            presentation_json: string;
+            presentation_digest: string;
+            rendered_digest: string;
+        };
+        Decision: {
+            expected_revision: number;
+            idempotency_key: string;
+            on_behalf_of?: string;
+            constraints?: components["schemas"]["Constraints"];
+            notification?: components["schemas"]["NotificationDecision"];
+        };
+        BrokerRequest: {
+            id: string;
+            revision: number;
+            requester: string;
+            operation: string;
+            status: components["schemas"]["Status"];
+            /** Format: date-time */
+            requested_at: string;
+            /** Format: date-time */
+            pending_expires_at?: string;
+            /** Format: date-time */
+            active_expires_at?: string;
+            requested_duration_seconds: number;
+            requested_max_uses: number | null;
+            granted_max_uses: number | null;
+            used_count: number;
+            request_reason?: string;
+            /** Format: date-time */
+            decided_at?: string;
+            decided_by?: string;
+            decided_on_behalf_of?: string;
+            presentation: components["schemas"]["Presentation"];
+            presentation_unavailable?: boolean;
+            allowed_actions: components["schemas"]["Action"][];
+            approval_bounds?: components["schemas"]["ApprovalBounds"];
+        };
+        RequestPage: {
+            requests: components["schemas"]["BrokerRequest"][];
+            next_cursor?: string;
+            event_cursor?: string;
+        };
+        UISourceHealth: {
+            id: string;
+            label: string;
+            healthy: boolean;
+            /** Format: date-time */
+            last_sync_at?: string;
+            error?: string;
+        };
+        UIRequest: {
+            source_id: string;
+            source_label: string;
+            handle: string;
+            request: components["schemas"]["BrokerRequest"];
+        };
+        UISnapshot: {
+            /** @constant */
+            api_version: "brokerkit.io/operator-ui/v1";
+            cursor: string;
+            /** Format: date-time */
+            synchronized_at: string;
+            sources: components["schemas"]["UISourceHealth"][];
+            requests: components["schemas"]["UIRequest"][];
+            delivery_failures?: number;
+        };
+        UISnapshotEvent: {
+            /** @constant */
+            api_version: "brokerkit.io/operator-ui/v1";
+            cursor: string;
+            changed: boolean;
+        };
+        UISummary: {
+            /** @constant */
+            api_version: "brokerkit.io/operator-ui/v1";
+            cursor: string;
+            pending: number;
+            healthy: boolean;
+        };
+        BrokerEvent: {
+            cursor: string;
+            /** @enum {string} */
+            kind: "request.created" | "request.approved" | "request.denied" | "request.canceled" | "request.expired" | "grant.revoked" | "grant.reserved" | "grant.consumed" | "grant.released" | "execution.succeeded" | "execution.failed" | "execution.ambiguous";
+            request_id: string;
+            revision: number;
+            status: components["schemas"]["Status"];
+            /** Format: date-time */
+            occurred_at: string;
+            used_count: number;
+        };
+        Error: {
+            /** @enum {string} */
+            code: "invalid_request" | "unauthorized" | "forbidden" | "not_found" | "method_not_allowed" | "revision_conflict" | "idempotency_conflict" | "constraint_exceeded" | "invalid_transition" | "invalid_decision_token" | "cursor_expired" | "temporarily_unavailable" | "internal_error";
+            message: string;
+            correlation_id: string;
+            current?: components["schemas"]["BrokerRequest"];
+        };
+        ErrorEnvelope: {
+            error: components["schemas"]["Error"];
+        };
+    };
+    responses: {
+        /** @description Stable error envelope */
+        ErrorResponse: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorEnvelope"];
+            };
+        };
+    };
+    parameters: {
+        RequestID: string;
+    };
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    discoverOperator: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Operator V1 discovery */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Descriptor"];
+                };
+            };
+            default: components["responses"]["ErrorResponse"];
+        };
+    };
+    operatorHealth: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Liveness status */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Health"];
+                };
+            };
+        };
+    };
+    operatorReady: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Readiness status */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Health"];
+                };
+            };
+            503: components["responses"]["ErrorResponse"];
+        };
+    };
+    listOperatorRequests: {
+        parameters: {
+            query?: {
+                status?: components["schemas"]["StatusGroup"];
+                requester?: string;
+                operation?: string;
+                target_kind?: string;
+                cursor?: string;
+                limit?: number;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Bounded request page */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RequestPage"];
+                };
+            };
+            default: components["responses"]["ErrorResponse"];
+        };
+    };
+    getOperatorRequest: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: components["parameters"]["RequestID"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Safe operator request */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BrokerRequest"];
+                };
+            };
+            default: components["responses"]["ErrorResponse"];
+        };
+    };
+    decideOperatorRequest: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: components["parameters"]["RequestID"];
+                action: components["schemas"]["Action"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["Decision"];
+            };
+        };
+        responses: {
+            /** @description Committed decision */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BrokerRequest"];
+                };
+            };
+            default: components["responses"]["ErrorResponse"];
+        };
+    };
+    streamOperatorEvents: {
+        parameters: {
+            query?: {
+                cursor?: string;
+            };
+            header?: {
+                "Last-Event-ID"?: string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description SSE stream of BrokerEvent values */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/event-stream": string;
+                };
+            };
+            default: components["responses"]["ErrorResponse"];
+        };
+    };
+}

package/dist/src/generated/operator-v1.d.ts

@@ -0,0 +1,36 @@
+import type { components } from "./openapi-operator-v1.js";
+export declare const OPERATOR_V1_SCHEMA_SHA256 = "fb446551ce8f2e00cfb6555daf93ed5b8e2ce8c45d8029b4a49e6a5fb8fef98d";
+export declare const operatorV1: {
+    readonly apiVersion: "brokerkit.io/operator/v1";
+    readonly statuses: readonly ["pending", "active", "denied", "canceled", "expired", "consumed", "revoked"];
+    readonly actions: readonly ["approve", "deny", "revoke"];
+    readonly eventKinds: readonly ["request.created", "request.approved", "request.denied", "request.canceled", "request.expired", "grant.revoked", "grant.reserved", "grant.consumed", "grant.released", "execution.succeeded", "execution.failed", "execution.ambiguous"];
+    readonly errorCodes: readonly ["invalid_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "revision_conflict", "idempotency_conflict", "constraint_exceeded", "invalid_transition", "invalid_decision_token", "cursor_expired", "temporarily_unavailable", "internal_error"];
+    readonly limits: {
+        readonly id: 128;
+        readonly requester: 80;
+        readonly operation: 500;
+        readonly reason: 2000;
+        readonly actor: 200;
+        readonly title: 200;
+        readonly summary: 2000;
+        readonly facts: 20;
+        readonly factLabel: 80;
+        readonly factValue: 500;
+        readonly cursor: 1024;
+        readonly page: 100;
+        readonly idempotencyKey: 200;
+        readonly errorMessage: 500;
+        readonly correlationId: 128;
+    };
+};
+export type Decision = components["schemas"]["Decision"];
+export type Discovery = components["schemas"]["Descriptor"];
+export type ErrorEnvelope = components["schemas"]["ErrorEnvelope"];
+export type BrokerEvent = components["schemas"]["BrokerEvent"];
+export type RequestPage = components["schemas"]["RequestPage"];
+export type Presentation = components["schemas"]["Presentation"];
+export type BrokerRequest = components["schemas"]["BrokerRequest"];
+export type UISnapshot = components["schemas"]["UISnapshot"];
+export type UISnapshotEvent = components["schemas"]["UISnapshotEvent"];
+export type UISummary = components["schemas"]["UISummary"];

package/dist/src/generated/operator-v1.js

@@ -1,4 +1,4 @@
-export const OPERATOR_V1_SCHEMA_SHA256 = "306810514cd7e378b194f9d539aae99de07396994ec7de273a18dc5a4aa47118";
+export const OPERATOR_V1_SCHEMA_SHA256 = "fb446551ce8f2e00cfb6555daf93ed5b8e2ce8c45d8029b4a49e6a5fb8fef98d";
 export const operatorV1 = {
     apiVersion: "brokerkit.io/operator/v1",
     statuses: [

package/dist/src/generated/operator-validators.d.ts

@@ -0,0 +1,131 @@
+export declare const validateDescriptor: typeof validate20;
+declare function validate20(data: any, { instancePath, parentData, parentDataProperty, rootData, dynamicAnchors }?: {
+    instancePath?: string | undefined;
+    rootData?: any;
+    dynamicAnchors?: {} | undefined;
+}): boolean;
+declare namespace validate20 {
+    var evaluated: {
+        props: boolean;
+        dynamicProps: boolean;
+        dynamicItems: boolean;
+    };
+}
+export declare const validateHealth: typeof validate22;
+declare function validate22(data: any, { instancePath, parentData, parentDataProperty, rootData, dynamicAnchors }?: {
+    instancePath?: string | undefined;
+    rootData?: any;
+    dynamicAnchors?: {} | undefined;
+}): boolean;
+declare namespace validate22 {
+    var evaluated: {
+        props: boolean;
+        dynamicProps: boolean;
+        dynamicItems: boolean;
+    };
+}
+export declare const validateBrokerRequest: typeof validate23;
+declare function validate23(data: any, { instancePath, parentData, parentDataProperty, rootData, dynamicAnchors }?: {
+    instancePath?: string | undefined;
+    rootData?: any;
+    dynamicAnchors?: {} | undefined;
+}): boolean;
+declare namespace validate23 {
+    var evaluated: {
+        props: boolean;
+        dynamicProps: boolean;
+        dynamicItems: boolean;
+    };
+}
+export declare const validateRequestPage: typeof validate30;
+declare function validate30(data: any, { instancePath, parentData, parentDataProperty, rootData, dynamicAnchors }?: {
+    instancePath?: string | undefined;
+    rootData?: any;
+    dynamicAnchors?: {} | undefined;
+}): boolean;
+declare namespace validate30 {
+    var evaluated: {
+        props: boolean;
+        dynamicProps: boolean;
+        dynamicItems: boolean;
+    };
+}
+export declare const validateBrokerEvent: typeof validate36;
+declare function validate36(data: any, { instancePath, parentData, parentDataProperty, rootData, dynamicAnchors }?: {
+    instancePath?: string | undefined;
+    rootData?: any;
+    dynamicAnchors?: {} | undefined;
+}): boolean;
+declare namespace validate36 {
+    var evaluated: {
+        props: boolean;
+        dynamicProps: boolean;
+        dynamicItems: boolean;
+    };
+}
+export declare const validateErrorEnvelope: typeof validate39;
+declare function validate39(data: any, { instancePath, parentData, parentDataProperty, rootData, dynamicAnchors }?: {
+    instancePath?: string | undefined;
+    rootData?: any;
+    dynamicAnchors?: {} | undefined;
+}): boolean;
+declare namespace validate39 {
+    var evaluated: {
+        props: boolean;
+        dynamicProps: boolean;
+        dynamicItems: boolean;
+    };
+}
+export declare const validateUISnapshot: typeof validate45;
+declare function validate45(data: any, { instancePath, parentData, parentDataProperty, rootData, dynamicAnchors }?: {
+    instancePath?: string | undefined;
+    rootData?: any;
+    dynamicAnchors?: {} | undefined;
+}): boolean;
+declare namespace validate45 {
+    var evaluated: {
+        props: boolean;
+        dynamicProps: boolean;
+        dynamicItems: boolean;
+    };
+}
+export declare const validateUISnapshotEvent: typeof validate51;
+declare function validate51(data: any, { instancePath, parentData, parentDataProperty, rootData, dynamicAnchors }?: {
+    instancePath?: string | undefined;
+    rootData?: any;
+    dynamicAnchors?: {} | undefined;
+}): boolean;
+declare namespace validate51 {
+    var evaluated: {
+        props: boolean;
+        dynamicProps: boolean;
+        dynamicItems: boolean;
+    };
+}
+export declare const validateUISummary: typeof validate52;
+declare function validate52(data: any, { instancePath, parentData, parentDataProperty, rootData, dynamicAnchors }?: {
+    instancePath?: string | undefined;
+    rootData?: any;
+    dynamicAnchors?: {} | undefined;
+}): boolean;
+declare namespace validate52 {
+    var evaluated: {
+        props: boolean;
+        dynamicProps: boolean;
+        dynamicItems: boolean;
+    };
+}
+export declare const validateUIRequest: typeof validate53;
+declare function validate53(data: any, { instancePath, parentData, parentDataProperty, rootData, dynamicAnchors }?: {
+    instancePath?: string | undefined;
+    rootData?: any;
+    dynamicAnchors?: {} | undefined;
+}): boolean;
+declare namespace validate53 {
+    var evaluated: {
+        props: boolean;
+        dynamicProps: boolean;
+        dynamicItems: boolean;
+    };
+}
+export {};