@apifuse/provider-sdk 2.1.0-beta.9 → 2.2.0-beta.2

package/dist/auth-turn/auth-turn.v1.schema.json

@@ -0,0 +1,89 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://apifuse.com/contracts/auth-turn/v1",
+	"title": "APIFuse AuthTurn envelope v1",
+	"description": "Protocol message exchanged during auth.flow ceremonies. kind is an open string; known kinds are tooling metadata, not a wire constraint.",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["kind", "turnId"],
+	"properties": {
+		"kind": {
+			"type": "string",
+			"minLength": 1,
+			"description": "Open turn kind. Known kinds are listed in the TURN_KINDS registry; unknown kinds remain valid on the wire."
+		},
+		"turnId": {
+			"type": "string",
+			"minLength": 1,
+			"description": "Provider-scoped identifier of this turn."
+		},
+		"expiresAt": {
+			"type": "string",
+			"minLength": 1,
+			"description": "Turn expiry timestamp as an ISO 8601 / RFC 3339 string."
+		},
+		"data": {
+			"type": "object",
+			"additionalProperties": true,
+			"description": "Kind-specific payload. Terminal kinds carry the payloads described in $defs."
+		},
+		"expectedInput": {
+			"type": "object",
+			"additionalProperties": true,
+			"description": "JSON Schema describing the input expected next."
+		},
+		"hint": {
+			"type": "string",
+			"description": "Deprecated but load-bearing human-readable hint materialized from provider locale catalogs."
+		},
+		"hintKey": {
+			"type": "string",
+			"description": "Provider locale catalog key for the turn hint."
+		},
+		"timing": {
+			"type": "object",
+			"additionalProperties": false,
+			"description": "Client pacing guidance for poll-style turns.",
+			"properties": {
+				"suggestedPollIntervalMs": {
+					"type": "number",
+					"minimum": 1
+				},
+				"maxWaitMs": {
+					"type": "number",
+					"minimum": 1
+				}
+			}
+		}
+	},
+	"$defs": {
+		"completeTurnData": {
+			"title": "Terminal payload for kind \"complete\"",
+			"description": "data payload of a complete turn. The gateway extracts data.credential for persistence; complete turns are never echoed to browsers.",
+			"type": "object",
+			"additionalProperties": true,
+			"required": ["credential"],
+			"properties": {
+				"credential": {
+					"type": "object",
+					"additionalProperties": true
+				},
+				"metadata": {
+					"type": "object",
+					"additionalProperties": true
+				}
+			}
+		},
+		"abortTurnData": {
+			"title": "Terminal payload for kind \"abort\"",
+			"description": "data payload of an abort turn. code, when present, is the machine-readable abort reason.",
+			"type": "object",
+			"additionalProperties": true,
+			"properties": {
+				"code": {
+					"type": "string"
+				}
+			}
+		}
+	}
+}

package/dist/auth-turn/fixtures/invalid/empty-kind.json

@@ -0,0 +1,4 @@
+{
+	"kind": "",
+	"turnId": "fixture.invalid.empty-kind"
+}

package/dist/auth-turn/fixtures/invalid/expires-at-not-string.json

@@ -0,0 +1,5 @@
+{
+	"kind": "challenge",
+	"turnId": "fixture.invalid.expires-at-not-string",
+	"expiresAt": 1767225600000
+}

package/dist/auth-turn/fixtures/invalid/missing-kind.json

@@ -0,0 +1,3 @@
+{
+	"turnId": "fixture.invalid.missing-kind"
+}

package/dist/auth-turn/fixtures/invalid/missing-turn-id.json

@@ -0,0 +1,3 @@
+{
+	"kind": "form"
+}

package/dist/auth-turn/fixtures/invalid/timing-unknown-field.json

@@ -0,0 +1,7 @@
+{
+	"kind": "poll",
+	"turnId": "fixture.invalid.timing-unknown-field",
+	"timing": {
+		"recommendedIntervalMs": 5000
+	}
+}

package/dist/auth-turn/fixtures/invalid/turn-id-snake-case.json

@@ -0,0 +1,4 @@
+{
+	"kind": "form",
+	"turn_id": "fixture.invalid.turn-id-snake-case"
+}

package/dist/auth-turn/fixtures/invalid/unknown-top-level-field.json

@@ -0,0 +1,5 @@
+{
+	"kind": "form",
+	"turnId": "fixture.invalid.unknown-top-level-field",
+	"setCookie": "session=leaked-value"
+}

package/dist/auth-turn/fixtures/valid/abort.json

@@ -0,0 +1,8 @@
+{
+	"kind": "abort",
+	"turnId": "fixture.abort",
+	"hint": "OAuth flow aborted.",
+	"data": {
+		"code": "flow_expired"
+	}
+}

package/dist/auth-turn/fixtures/valid/challenge.json

@@ -0,0 +1,17 @@
+{
+	"kind": "challenge",
+	"turnId": "fixture.challenge",
+	"hint": "Complete the WebAuthn prompt in your browser.",
+	"expiresAt": "2026-01-01T00:00:00.000Z",
+	"data": {
+		"challenge": "fixture-challenge-not-real",
+		"rpId": "example.com"
+	},
+	"expectedInput": {
+		"type": "object",
+		"required": ["attestation"],
+		"properties": {
+			"attestation": { "type": "object" }
+		}
+	}
+}

package/dist/auth-turn/fixtures/valid/complete.json

@@ -0,0 +1,13 @@
+{
+	"kind": "complete",
+	"turnId": "fixture.complete",
+	"hint": "OAuth flow completed.",
+	"data": {
+		"credential": {
+			"accessToken": "fixture-fake-access-token-not-a-secret"
+		},
+		"metadata": {
+			"scope": "read"
+		}
+	}
+}

package/dist/auth-turn/fixtures/valid/form.json

@@ -0,0 +1,14 @@
+{
+	"kind": "form",
+	"turnId": "fixture.form",
+	"hint": "Provide the required input to continue.",
+	"data": {},
+	"expectedInput": {
+		"type": "object",
+		"required": ["apiKey"],
+		"properties": {
+			"apiKey": { "type": "string" }
+		},
+		"x-apifuse-field-order": ["apiKey"]
+	}
+}

package/dist/auth-turn/fixtures/valid/message.json

@@ -0,0 +1,13 @@
+{
+	"kind": "message",
+	"turnId": "fixture.message",
+	"hint": "Enter the code on the verification page, then poll for completion.",
+	"data": {
+		"user_code": "FIXT-CODE",
+		"verification_uri": "https://example.com/device"
+	},
+	"timing": {
+		"suggestedPollIntervalMs": 5000,
+		"maxWaitMs": 120000
+	}
+}

package/dist/auth-turn/fixtures/valid/multi_choice.json

@@ -0,0 +1,15 @@
+{
+	"kind": "multi_choice",
+	"turnId": "fixture.multi_choice",
+	"hint": "Choose an authentication method.",
+	"data": {
+		"choices": ["oauth", "form"]
+	},
+	"expectedInput": {
+		"type": "object",
+		"required": ["choice"],
+		"properties": {
+			"choice": { "type": "string", "enum": ["oauth", "form"] }
+		}
+	}
+}

package/dist/auth-turn/fixtures/valid/pending.json

@@ -0,0 +1,5 @@
+{
+	"kind": "pending",
+	"turnId": "credentials.noPendingChallenge",
+	"hintKey": "auth.challenge.pending"
+}

package/dist/auth-turn/fixtures/valid/poll.json

@@ -0,0 +1,9 @@
+{
+	"kind": "poll",
+	"turnId": "fixture.poll",
+	"hint": "Continue polling until the device flow completes.",
+	"timing": {
+		"suggestedPollIntervalMs": 5000,
+		"maxWaitMs": 120000
+	}
+}

package/dist/auth-turn/fixtures/valid/redirect.json

@@ -0,0 +1,16 @@
+{
+	"kind": "redirect",
+	"turnId": "fixture.redirect",
+	"hint": "Open the provider authorization page to continue.",
+	"data": {
+		"url": "https://auth.example.com/authorize?state=fixture-state"
+	},
+	"expectedInput": {
+		"type": "object",
+		"required": ["code", "state"],
+		"properties": {
+			"code": { "type": "string" },
+			"state": { "type": "string" }
+		}
+	}
+}

package/dist/auth-turn/fixtures/valid/retry.json

@@ -0,0 +1,8 @@
+{
+	"kind": "retry",
+	"turnId": "fixture.retry",
+	"hint": "OAuth token exchange failed: OAuth callback payload is invalid.",
+	"data": {
+		"error": "OAuth callback payload is invalid."
+	}
+}

package/dist/auth-turn/fixtures/valid/unknown-kind.json

@@ -0,0 +1,7 @@
+{
+	"kind": "totally_custom",
+	"turnId": "fixture.unknown-kind",
+	"data": {
+		"anything": true
+	}
+}

package/dist/auth-turn/index.d.ts

@@ -0,0 +1,195 @@
+import type { AuthTurn } from "../types";
+export type { AuthTurn };
+/**
+ * Major version of the AuthTurn envelope contract.
+ *
+ * The envelope is additive-only within a major. Adding a turn kind is never an
+ * envelope version event (the wire keeps `kind` open); a major bump happens
+ * only on an envelope-shape break, which is expected to be a ~never,
+ * gateway-first coordinated event.
+ */
+export declare const AUTH_TURN_ENVELOPE_MAJOR = 1;
+/**
+ * Package-root-relative path of the static schema artifact shipped in the npm
+ * tarball. Tooling that needs the raw JSON document (for example codegen)
+ * should read this file off the resolved on-disk package directory.
+ */
+export declare const AUTH_TURN_SCHEMA_ARTIFACT_PATH = "dist/auth-turn/auth-turn.v1.schema.json";
+/**
+ * JSON Schema (draft 2020-12) for the AuthTurn envelope, version 1.
+ *
+ * This is the exact codification of the runtime validation the SDK applies to
+ * ceremony outputs (see `validateCeremonyOutput` in `src/ceremonies`), which
+ * compiles this same document. `kind` is an OPEN string on the wire: the known
+ * kinds in {@link TURN_KINDS} are tooling metadata, never a wire constraint.
+ *
+ * The committed artifact at `src/auth-turn/auth-turn.v1.schema.json` (shipped
+ * to `dist/auth-turn/auth-turn.v1.schema.json`) must stay byte-equivalent to
+ * this constant; a contract test enforces the equality.
+ */
+export declare const AUTH_TURN_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://apifuse.com/contracts/auth-turn/v1";
+    readonly title: "APIFuse AuthTurn envelope v1";
+    readonly description: "Protocol message exchanged during auth.flow ceremonies. kind is an open string; known kinds are tooling metadata, not a wire constraint.";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["kind", "turnId"];
+    readonly properties: {
+        readonly kind: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "Open turn kind. Known kinds are listed in the TURN_KINDS registry; unknown kinds remain valid on the wire.";
+        };
+        readonly turnId: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "Provider-scoped identifier of this turn.";
+        };
+        readonly expiresAt: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "Turn expiry timestamp as an ISO 8601 / RFC 3339 string.";
+        };
+        readonly data: {
+            readonly type: "object";
+            readonly additionalProperties: true;
+            readonly description: "Kind-specific payload. Terminal kinds carry the payloads described in $defs.";
+        };
+        readonly expectedInput: {
+            readonly type: "object";
+            readonly additionalProperties: true;
+            readonly description: "JSON Schema describing the input expected next.";
+        };
+        readonly hint: {
+            readonly type: "string";
+            readonly description: "Deprecated but load-bearing human-readable hint materialized from provider locale catalogs.";
+        };
+        readonly hintKey: {
+            readonly type: "string";
+            readonly description: "Provider locale catalog key for the turn hint.";
+        };
+        readonly timing: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly description: "Client pacing guidance for poll-style turns.";
+            readonly properties: {
+                readonly suggestedPollIntervalMs: {
+                    readonly type: "number";
+                    readonly minimum: 1;
+                };
+                readonly maxWaitMs: {
+                    readonly type: "number";
+                    readonly minimum: 1;
+                };
+            };
+        };
+    };
+    readonly $defs: {
+        readonly completeTurnData: {
+            readonly title: 'Terminal payload for kind "complete"';
+            readonly description: "data payload of a complete turn. The gateway extracts data.credential for persistence; complete turns are never echoed to browsers.";
+            readonly type: "object";
+            readonly additionalProperties: true;
+            readonly required: readonly ["credential"];
+            readonly properties: {
+                readonly credential: {
+                    readonly type: "object";
+                    readonly additionalProperties: true;
+                };
+                readonly metadata: {
+                    readonly type: "object";
+                    readonly additionalProperties: true;
+                };
+            };
+        };
+        readonly abortTurnData: {
+            readonly title: 'Terminal payload for kind "abort"';
+            readonly description: "data payload of an abort turn. code, when present, is the machine-readable abort reason.";
+            readonly type: "object";
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly code: {
+                    readonly type: "string";
+                };
+            };
+        };
+    };
+};
+export type TurnKindRendering = "custom" | "schema" | "terminal";
+export interface AuthTurnKindDescriptor {
+    /** Turn kind string as emitted on the wire. */
+    readonly kind: string;
+    /**
+     * How clients present the turn: "custom" (dedicated renderer), "schema"
+     * (generic expectedInput-driven rendering), or "terminal" (never rendered;
+     * consumed by the gateway).
+     */
+    readonly rendering: TurnKindRendering;
+    /** JSON pointer into AUTH_TURN_SCHEMA for the kind's data payload contract. */
+    readonly payloadSchema?: string;
+    /** Envelope major in which the kind was first registered. */
+    readonly since: number;
+}
+/**
+ * Registry of the turn kinds the SDK is known to emit today.
+ *
+ * This is tooling metadata (renderer routing, fixtures, codegen) — it is NOT a
+ * wire constraint. Providers may emit kinds outside this list and they remain
+ * valid against {@link AUTH_TURN_SCHEMA}. Every kind registered here must ship
+ * a golden fixture at `src/auth-turn/fixtures/valid/<kind>.json`; a contract
+ * test enforces the coverage.
+ */
+export declare const TURN_KINDS: readonly [{
+    readonly kind: "abort";
+    readonly rendering: "terminal";
+    readonly payloadSchema: "#/$defs/abortTurnData";
+    readonly since: 1;
+}, {
+    readonly kind: "challenge";
+    readonly rendering: "custom";
+    readonly since: 1;
+}, {
+    readonly kind: "complete";
+    readonly rendering: "terminal";
+    readonly payloadSchema: "#/$defs/completeTurnData";
+    readonly since: 1;
+}, {
+    readonly kind: "form";
+    readonly rendering: "custom";
+    readonly since: 1;
+}, {
+    readonly kind: "message";
+    readonly rendering: "custom";
+    readonly since: 1;
+}, {
+    readonly kind: "multi_choice";
+    readonly rendering: "custom";
+    readonly since: 1;
+}, {
+    readonly kind: "pending";
+    readonly rendering: "schema";
+    readonly since: 1;
+}, {
+    readonly kind: "poll";
+    readonly rendering: "custom";
+    readonly since: 1;
+}, {
+    readonly kind: "redirect";
+    readonly rendering: "custom";
+    readonly since: 1;
+}, {
+    readonly kind: "retry";
+    readonly rendering: "custom";
+    readonly since: 1;
+}];
+/** Turn kinds the SDK is known to emit. Tooling metadata, not a wire constraint. */
+export type KnownAuthTurnKind = (typeof TURN_KINDS)[number]["kind"];
+/** Known kinds presented through a dedicated client renderer. */
+export type CustomRenderedTurnKind = Extract<(typeof TURN_KINDS)[number], {
+    rendering: "custom";
+}>["kind"];
+/** Known kinds consumed by the gateway instead of being rendered. */
+export type TerminalTurnKind = Extract<(typeof TURN_KINDS)[number], {
+    rendering: "terminal";
+}>["kind"];

package/dist/auth-turn/index.js

@@ -0,0 +1,133 @@
+/**
+ * Major version of the AuthTurn envelope contract.
+ *
+ * The envelope is additive-only within a major. Adding a turn kind is never an
+ * envelope version event (the wire keeps `kind` open); a major bump happens
+ * only on an envelope-shape break, which is expected to be a ~never,
+ * gateway-first coordinated event.
+ */
+export const AUTH_TURN_ENVELOPE_MAJOR = 1;
+/**
+ * Package-root-relative path of the static schema artifact shipped in the npm
+ * tarball. Tooling that needs the raw JSON document (for example codegen)
+ * should read this file off the resolved on-disk package directory.
+ */
+export const AUTH_TURN_SCHEMA_ARTIFACT_PATH = "dist/auth-turn/auth-turn.v1.schema.json";
+/**
+ * JSON Schema (draft 2020-12) for the AuthTurn envelope, version 1.
+ *
+ * This is the exact codification of the runtime validation the SDK applies to
+ * ceremony outputs (see `validateCeremonyOutput` in `src/ceremonies`), which
+ * compiles this same document. `kind` is an OPEN string on the wire: the known
+ * kinds in {@link TURN_KINDS} are tooling metadata, never a wire constraint.
+ *
+ * The committed artifact at `src/auth-turn/auth-turn.v1.schema.json` (shipped
+ * to `dist/auth-turn/auth-turn.v1.schema.json`) must stay byte-equivalent to
+ * this constant; a contract test enforces the equality.
+ */
+export const AUTH_TURN_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://apifuse.com/contracts/auth-turn/v1",
+    title: "APIFuse AuthTurn envelope v1",
+    description: "Protocol message exchanged during auth.flow ceremonies. kind is an open string; known kinds are tooling metadata, not a wire constraint.",
+    type: "object",
+    additionalProperties: false,
+    required: ["kind", "turnId"],
+    properties: {
+        kind: {
+            type: "string",
+            minLength: 1,
+            description: "Open turn kind. Known kinds are listed in the TURN_KINDS registry; unknown kinds remain valid on the wire.",
+        },
+        turnId: {
+            type: "string",
+            minLength: 1,
+            description: "Provider-scoped identifier of this turn.",
+        },
+        expiresAt: {
+            type: "string",
+            minLength: 1,
+            description: "Turn expiry timestamp as an ISO 8601 / RFC 3339 string.",
+        },
+        data: {
+            type: "object",
+            additionalProperties: true,
+            description: "Kind-specific payload. Terminal kinds carry the payloads described in $defs.",
+        },
+        expectedInput: {
+            type: "object",
+            additionalProperties: true,
+            description: "JSON Schema describing the input expected next.",
+        },
+        hint: {
+            type: "string",
+            description: "Deprecated but load-bearing human-readable hint materialized from provider locale catalogs.",
+        },
+        hintKey: {
+            type: "string",
+            description: "Provider locale catalog key for the turn hint.",
+        },
+        timing: {
+            type: "object",
+            additionalProperties: false,
+            description: "Client pacing guidance for poll-style turns.",
+            properties: {
+                suggestedPollIntervalMs: { type: "number", minimum: 1 },
+                maxWaitMs: { type: "number", minimum: 1 },
+            },
+        },
+    },
+    $defs: {
+        completeTurnData: {
+            title: 'Terminal payload for kind "complete"',
+            description: "data payload of a complete turn. The gateway extracts data.credential for persistence; complete turns are never echoed to browsers.",
+            type: "object",
+            additionalProperties: true,
+            required: ["credential"],
+            properties: {
+                credential: { type: "object", additionalProperties: true },
+                metadata: { type: "object", additionalProperties: true },
+            },
+        },
+        abortTurnData: {
+            title: 'Terminal payload for kind "abort"',
+            description: "data payload of an abort turn. code, when present, is the machine-readable abort reason.",
+            type: "object",
+            additionalProperties: true,
+            properties: {
+                code: { type: "string" },
+            },
+        },
+    },
+};
+/**
+ * Registry of the turn kinds the SDK is known to emit today.
+ *
+ * This is tooling metadata (renderer routing, fixtures, codegen) — it is NOT a
+ * wire constraint. Providers may emit kinds outside this list and they remain
+ * valid against {@link AUTH_TURN_SCHEMA}. Every kind registered here must ship
+ * a golden fixture at `src/auth-turn/fixtures/valid/<kind>.json`; a contract
+ * test enforces the coverage.
+ */
+export const TURN_KINDS = [
+    {
+        kind: "abort",
+        rendering: "terminal",
+        payloadSchema: "#/$defs/abortTurnData",
+        since: 1,
+    },
+    { kind: "challenge", rendering: "custom", since: 1 },
+    {
+        kind: "complete",
+        rendering: "terminal",
+        payloadSchema: "#/$defs/completeTurnData",
+        since: 1,
+    },
+    { kind: "form", rendering: "custom", since: 1 },
+    { kind: "message", rendering: "custom", since: 1 },
+    { kind: "multi_choice", rendering: "custom", since: 1 },
+    { kind: "pending", rendering: "schema", since: 1 },
+    { kind: "poll", rendering: "custom", since: 1 },
+    { kind: "redirect", rendering: "custom", since: 1 },
+    { kind: "retry", rendering: "custom", since: 1 },
+];