@openclaw/gateway-protocol 0.0.0 → 2026.7.2-beta.4

package/dist/gateway-error-details-CsX7mtLy.d.mts

@@ -0,0 +1,52 @@
+//#region src/gateway-error-details.d.ts
+/** Gateway JSON-RPC style error codes shared by clients and server handlers. */
+declare const ErrorCodes: {
+  /** Client has not completed account/device linking for this gateway. */readonly NOT_LINKED: "NOT_LINKED"; /** Device exists but still needs an explicit pairing approval. */
+  readonly NOT_PAIRED: "NOT_PAIRED"; /** Agent turn exceeded the gateway wait window. */
+  readonly AGENT_TIMEOUT: "AGENT_TIMEOUT"; /** Request payload failed protocol validation or method preconditions. */
+  readonly INVALID_REQUEST: "INVALID_REQUEST"; /** Authenticated caller lacks permission for the requested operation. */
+  readonly FORBIDDEN: "FORBIDDEN"; /** Approval resolution referenced a missing or expired approval request. */
+  readonly APPROVAL_NOT_FOUND: "APPROVAL_NOT_FOUND"; /** Gateway service or required backend is temporarily unavailable. */
+  readonly UNAVAILABLE: "UNAVAILABLE";
+};
+/** Closed set of canonical gateway error code strings. */
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+/** Stable discriminants for structured method-level failures. */
+declare const GatewayErrorDetailCodes: {
+  readonly MISSING_SCOPE: "MISSING_SCOPE";
+  readonly MCP_APP_VIEW_EXPIRED: "MCP_APP_VIEW_EXPIRED";
+  readonly SESSION_OBSERVER_BUSY: "SESSION_OBSERVER_BUSY";
+  readonly SESSION_OBSERVER_UNAVAILABLE: "SESSION_OBSERVER_UNAVAILABLE";
+  readonly UNKNOWN_AGENT_ID: "UNKNOWN_AGENT_ID";
+  readonly WIZARD_NOT_FOUND: "WIZARD_NOT_FOUND";
+};
+/** Missing operator-scope details shared by WebSocket and HTTP responses. */
+type MissingScopeErrorDetails = {
+  code: typeof GatewayErrorDetailCodes.MISSING_SCOPE;
+  missingScope: string;
+  requiredScopes: string[];
+};
+type McpAppViewExpiredErrorDetails = {
+  code: typeof GatewayErrorDetailCodes.MCP_APP_VIEW_EXPIRED;
+};
+/** Unknown agent details carried by agent-scoped method validation failures. */
+type UnknownAgentIdErrorDetails = {
+  code: typeof GatewayErrorDetailCodes.UNKNOWN_AGENT_ID;
+  agentId: string;
+};
+/** Missing or expired process-local setup wizard session. */
+type WizardNotFoundErrorDetails = {
+  code: typeof GatewayErrorDetailCodes.WIZARD_NOT_FOUND;
+};
+/** Structured details emitted by method-level failures. */
+type GatewayErrorDetails = MissingScopeErrorDetails | McpAppViewExpiredErrorDetails | UnknownAgentIdErrorDetails | WizardNotFoundErrorDetails;
+/** Reads validated missing-scope details from an untrusted protocol payload. */
+declare function readMissingScopeErrorDetails(details: unknown): MissingScopeErrorDetails | null;
+declare function isMcpAppViewExpiredError(error: unknown): boolean;
+/**
+ * Reads a method-level missing-scope failure, preferring structured details.
+ * The message fallback keeps clients compatible with gateways predating structured details.
+ */
+declare function readMissingScopeError(error: unknown): MissingScopeErrorDetails | null;
+//#endregion
+export { McpAppViewExpiredErrorDetails as a, WizardNotFoundErrorDetails as c, readMissingScopeErrorDetails as d, GatewayErrorDetails as i, isMcpAppViewExpiredError as l, ErrorCodes as n, MissingScopeErrorDetails as o, GatewayErrorDetailCodes as r, UnknownAgentIdErrorDetails as s, ErrorCode as t, readMissingScopeError as u };

package/dist/gateway-error-details.d.mts

@@ -0,0 +1,2 @@
+import { a as McpAppViewExpiredErrorDetails, c as WizardNotFoundErrorDetails, d as readMissingScopeErrorDetails, i as GatewayErrorDetails, l as isMcpAppViewExpiredError, n as ErrorCodes, o as MissingScopeErrorDetails, r as GatewayErrorDetailCodes, s as UnknownAgentIdErrorDetails, t as ErrorCode, u as readMissingScopeError } from "./gateway-error-details-CsX7mtLy.mjs";
+export { ErrorCode, ErrorCodes, GatewayErrorDetailCodes, GatewayErrorDetails, McpAppViewExpiredErrorDetails, MissingScopeErrorDetails, UnknownAgentIdErrorDetails, WizardNotFoundErrorDetails, isMcpAppViewExpiredError, readMissingScopeError, readMissingScopeErrorDetails };

package/dist/gateway-error-details.mjs

@@ -0,0 +1,68 @@
+//#region src/gateway-error-details.ts
+/** Gateway JSON-RPC style error codes shared by clients and server handlers. */
+const ErrorCodes = {
+	/** Client has not completed account/device linking for this gateway. */
+	NOT_LINKED: "NOT_LINKED",
+	/** Device exists but still needs an explicit pairing approval. */
+	NOT_PAIRED: "NOT_PAIRED",
+	/** Agent turn exceeded the gateway wait window. */
+	AGENT_TIMEOUT: "AGENT_TIMEOUT",
+	/** Request payload failed protocol validation or method preconditions. */
+	INVALID_REQUEST: "INVALID_REQUEST",
+	/** Authenticated caller lacks permission for the requested operation. */
+	FORBIDDEN: "FORBIDDEN",
+	/** Approval resolution referenced a missing or expired approval request. */
+	APPROVAL_NOT_FOUND: "APPROVAL_NOT_FOUND",
+	/** Gateway service or required backend is temporarily unavailable. */
+	UNAVAILABLE: "UNAVAILABLE"
+};
+/** Stable discriminants for structured method-level failures. */
+const GatewayErrorDetailCodes = {
+	MISSING_SCOPE: "MISSING_SCOPE",
+	MCP_APP_VIEW_EXPIRED: "MCP_APP_VIEW_EXPIRED",
+	SESSION_OBSERVER_BUSY: "SESSION_OBSERVER_BUSY",
+	SESSION_OBSERVER_UNAVAILABLE: "SESSION_OBSERVER_UNAVAILABLE",
+	UNKNOWN_AGENT_ID: "UNKNOWN_AGENT_ID",
+	WIZARD_NOT_FOUND: "WIZARD_NOT_FOUND"
+};
+const LEGACY_MISSING_SCOPE_PATTERN = /\bmissing scope:\s*([a-z0-9._-]+)/i;
+function asRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+/** Reads validated missing-scope details from an untrusted protocol payload. */
+function readMissingScopeErrorDetails(details) {
+	const record = asRecord(details);
+	if (record?.code !== GatewayErrorDetailCodes.MISSING_SCOPE) return null;
+	const missingScope = typeof record.missingScope === "string" ? record.missingScope.trim() : "";
+	const requiredScopes = Array.isArray(record.requiredScopes) ? record.requiredScopes.map((scope) => typeof scope === "string" ? scope.trim() : "") : [];
+	if (!missingScope || requiredScopes.length === 0 || requiredScopes.some((scope) => !scope)) return null;
+	return {
+		code: GatewayErrorDetailCodes.MISSING_SCOPE,
+		missingScope,
+		requiredScopes
+	};
+}
+function isMcpAppViewExpiredError(error) {
+	return asRecord(asRecord(error)?.details)?.code === GatewayErrorDetailCodes.MCP_APP_VIEW_EXPIRED;
+}
+/**
+* Reads a method-level missing-scope failure, preferring structured details.
+* The message fallback keeps clients compatible with gateways predating structured details.
+*/
+function readMissingScopeError(error) {
+	const record = asRecord(error);
+	if (!record) return null;
+	const structured = readMissingScopeErrorDetails(record.details);
+	if (structured) return structured;
+	const gatewayError = record;
+	const code = typeof gatewayError.gatewayCode === "string" ? gatewayError.gatewayCode : typeof gatewayError.code === "string" ? gatewayError.code : "";
+	if (code !== ErrorCodes.FORBIDDEN && code !== ErrorCodes.INVALID_REQUEST) return null;
+	const missingScope = (typeof gatewayError.message === "string" ? gatewayError.message : "").match(LEGACY_MISSING_SCOPE_PATTERN)?.[1];
+	return missingScope ? {
+		code: GatewayErrorDetailCodes.MISSING_SCOPE,
+		missingScope,
+		requiredScopes: [missingScope]
+	} : null;
+}
+//#endregion
+export { ErrorCodes, GatewayErrorDetailCodes, isMcpAppViewExpiredError, readMissingScopeError, readMissingScopeErrorDetails };