@rafads/plugin-openapi 1.5.38

package/dist/sdk/plugin.d.ts

@@ -0,0 +1,109 @@
+import { Effect, Schema } from "effect";
+import type { Layer } from "effect";
+import { HttpClient } from "effect/unstable/http";
+import { IntegrationAlreadyExistsError, IntegrationNotFoundError, IntegrationSlug, HealthCheckSpec, type AuthMethodDescriptor, type Integration, type IntegrationRecord, type StorageFailure } from "@rafads/sdk/core";
+import { type OpenApiIntegrationConfig } from "./config";
+import { OpenApiExtractionError, OpenApiOAuthError, OpenApiParseError } from "./errors";
+import { type SpecPreview } from "./preview";
+import { type OpenApiPreset } from "./presets";
+import { type OpenapiStore } from "./store";
+import { type SpecFormatAdapter } from "./spec-format";
+import type { Authentication } from "./types";
+import { type AuthenticationInput } from "./types";
+import type { InvokeOptions } from "./invoke";
+export type OpenApiSpecInput = typeof OpenApiSpecInputSchema.Type;
+export interface OpenApiPreviewInput {
+    readonly spec: string;
+    readonly specFormat?: string;
+}
+/** Add an OpenAPI integration to the catalog. The integration is the API
+ *  surface; connections (the credentials) are attached separately and resolve
+ *  their value through the declared `authenticationTemplate`. */
+export interface OpenApiSpecConfig {
+    readonly spec: OpenApiSpecInput;
+    /** The catalog slug for the new integration (the `<integration>` segment). */
+    readonly slug?: string;
+    /** Display name (defaults to the spec title). */
+    readonly name?: string;
+    /** Agent-visible description (defaults to the spec's `info.description`,
+     *  then the title). */
+    readonly description?: string;
+    readonly baseUrl?: string;
+    /** Static headers applied to every request (no secret material). */
+    readonly headers?: Record<string, string>;
+    /** Static query params applied to every request. */
+    readonly queryParams?: Record<string, string>;
+    readonly specFormat?: string;
+    readonly family?: string;
+    readonly healthCheck?: HealthCheckSpec;
+    /** Auth methods a connection's value renders through - canonical
+     *  placements or the request-shaped authoring dialect. */
+    readonly authenticationTemplate?: readonly AuthenticationInput[];
+}
+export interface OpenApiExtensionFailure {
+    readonly _tag: string;
+}
+/** Add / merge custom auth methods onto an existing OpenAPI integration's
+ *  `authenticationTemplate`, and update request routing metadata. Mirrors the
+ *  GraphQL plugin's `configure`. */
+export interface OpenApiConfigureInput {
+    /** The auth methods to add. Each entry is appended to (or, when its `slug`
+     *  already exists, replaces) the integration's existing template array. A
+     *  custom apiKey method with no `slug` is assigned a generated `custom_<id>`
+     *  slug that is collision-checked against the existing template. */
+    readonly authenticationTemplate?: readonly AuthenticationInput[];
+    readonly mode?: "merge" | "replace";
+    readonly baseUrl?: string;
+}
+/** What changed in the tool catalog when a spec was updated in place. Tool
+ *  names, not addresses - the same diff applies to every connection. */
+export interface UpdateSpecResult {
+    readonly slug: IntegrationSlug;
+    readonly toolCount: number;
+    readonly addedTools: readonly string[];
+    readonly removedTools: readonly string[];
+}
+export interface OpenApiUpdateSpecInput {
+    /** New spec source. Omit to re-fetch from the integration's stored
+     *  `specUrl`. */
+    readonly spec?: OpenApiSpecInput;
+}
+export interface OpenApiPluginExtension {
+    readonly previewSpec: (input: string | OpenApiPreviewInput) => Effect.Effect<SpecPreview, OpenApiParseError | OpenApiExtractionError | OpenApiOAuthError | StorageFailure>;
+    readonly addSpec: (config: OpenApiSpecConfig) => Effect.Effect<{
+        readonly slug: IntegrationSlug;
+        readonly toolCount: number;
+    }, OpenApiParseError | OpenApiExtractionError | OpenApiOAuthError | IntegrationAlreadyExistsError | StorageFailure>;
+    /** Re-resolve the integration's spec (from its stored source URL, or the
+     *  provided input) and rebuild its tools IN PLACE - connections,
+     *  credentials, policies, and the curated description are untouched. */
+    readonly updateSpec: (slug: string, input?: OpenApiUpdateSpecInput) => Effect.Effect<UpdateSpecResult, OpenApiParseError | OpenApiExtractionError | OpenApiOAuthError | IntegrationNotFoundError | StorageFailure>;
+    readonly removeSpec: (slug: string) => Effect.Effect<void, StorageFailure>;
+    readonly getIntegration: (slug: string) => Effect.Effect<Integration | null, StorageFailure>;
+    /** Read the integration's full opaque config, including its
+     *  `authenticationTemplate`. Returns null when the integration is absent. */
+    readonly getConfig: (slug: string) => Effect.Effect<OpenApiIntegrationConfig | null, StorageFailure>;
+    /** Add / merge custom auth methods onto the integration's
+     *  `authenticationTemplate`. Returns the resulting template array. */
+    readonly configure: (slug: string, input: OpenApiConfigureInput) => Effect.Effect<readonly Authentication[], StorageFailure>;
+}
+declare const OpenApiSpecInputSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"url">;
+    readonly url: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"blob">;
+    readonly value: Schema.String;
+}>]>;
+export declare const describeOpenApiAuthMethods: (record: IntegrationRecord) => readonly AuthMethodDescriptor[];
+export declare const describeOpenApiIntegrationDisplay: (record: IntegrationRecord) => {
+    readonly url?: string;
+    readonly family?: string;
+};
+export interface OpenApiPluginOptions {
+    readonly httpClientLayer?: Layer.Layer<HttpClient.HttpClient, never, never>;
+    readonly invokeOptions?: InvokeOptions;
+    readonly specFormats?: readonly SpecFormatAdapter[];
+    readonly presets?: readonly OpenApiPreset[];
+}
+export declare const openApiPlugin: import("@rafads/sdk/core").ConfiguredPlugin<"openapi", OpenApiPluginExtension, OpenapiStore, OpenApiPluginOptions, undefined, Layer.Layer<unknown, never, never>, import("effect/unstable/httpapi/HttpApiGroup").Any>;
+export {};

package/dist/sdk/plugin.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/presets.d.ts

@@ -0,0 +1,15 @@
+import type { HealthCheckSpec, IntegrationPresetAuthentication } from "@rafads/sdk/core";
+export interface OpenApiPreset {
+    readonly id: string;
+    readonly name: string;
+    readonly summary: string;
+    readonly url?: string;
+    readonly icon?: string;
+    readonly featured?: boolean;
+    readonly family?: string;
+    readonly specFormat?: string;
+    readonly defaultSlug?: string;
+    readonly authTemplate?: readonly IntegrationPresetAuthentication[];
+    readonly healthCheck?: HealthCheckSpec;
+}
+export declare const openApiPresets: readonly OpenApiPreset[];

package/dist/sdk/preview-oauth2.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/preview.d.ts

@@ -0,0 +1,514 @@
+import { Effect, Option } from "effect";
+import { Schema } from "effect";
+export declare const OAuth2AuthorizationCodeFlow: Schema.Struct<{
+    readonly authorizationUrl: Schema.String;
+    readonly tokenUrl: Schema.String;
+    readonly refreshUrl: Schema.OptionFromOptional<Schema.String>;
+    readonly scopes: Schema.$Record<Schema.String, Schema.String>;
+}>;
+export type OAuth2AuthorizationCodeFlow = typeof OAuth2AuthorizationCodeFlow.Type;
+export declare const OAuth2ClientCredentialsFlow: Schema.Struct<{
+    readonly tokenUrl: Schema.String;
+    readonly refreshUrl: Schema.OptionFromOptional<Schema.String>;
+    readonly scopes: Schema.$Record<Schema.String, Schema.String>;
+}>;
+export type OAuth2ClientCredentialsFlow = typeof OAuth2ClientCredentialsFlow.Type;
+export declare const OAuth2Flows: Schema.Struct<{
+    readonly authorizationCode: Schema.OptionFromOptional<Schema.Struct<{
+        readonly authorizationUrl: Schema.String;
+        readonly tokenUrl: Schema.String;
+        readonly refreshUrl: Schema.OptionFromOptional<Schema.String>;
+        readonly scopes: Schema.$Record<Schema.String, Schema.String>;
+    }>>;
+    readonly clientCredentials: Schema.OptionFromOptional<Schema.Struct<{
+        readonly tokenUrl: Schema.String;
+        readonly refreshUrl: Schema.OptionFromOptional<Schema.String>;
+        readonly scopes: Schema.$Record<Schema.String, Schema.String>;
+    }>>;
+}>;
+export type OAuth2Flows = typeof OAuth2Flows.Type;
+export declare const SecurityScheme: Schema.Struct<{
+    /** Key name in components.securitySchemes (e.g. "api_token") */
+    readonly name: Schema.String;
+    /** OpenAPI security scheme type */
+    readonly type: Schema.Literals<readonly ["http", "apiKey", "oauth2", "openIdConnect"]>;
+    /** For type: "http" — e.g. "bearer", "basic" */
+    readonly scheme: Schema.OptionFromOptional<Schema.String>;
+    /** For type: "http" with scheme "bearer" — e.g. "JWT" */
+    readonly bearerFormat: Schema.OptionFromOptional<Schema.String>;
+    /** For type: "apiKey" — where the key goes */
+    readonly in: Schema.OptionFromOptional<Schema.Literals<readonly ["header", "query", "cookie"]>>;
+    /** For type: "apiKey" — the header/query/cookie name */
+    readonly headerName: Schema.OptionFromOptional<Schema.String>;
+    readonly description: Schema.OptionFromOptional<Schema.String>;
+    /** For type: "oauth2" — declared flows (authorizationCode / clientCredentials only; implicit and password are deprecated). */
+    readonly flows: Schema.OptionFromOptional<Schema.Struct<{
+        readonly authorizationCode: Schema.OptionFromOptional<Schema.Struct<{
+            readonly authorizationUrl: Schema.String;
+            readonly tokenUrl: Schema.String;
+            readonly refreshUrl: Schema.OptionFromOptional<Schema.String>;
+            readonly scopes: Schema.$Record<Schema.String, Schema.String>;
+        }>>;
+        readonly clientCredentials: Schema.OptionFromOptional<Schema.Struct<{
+            readonly tokenUrl: Schema.String;
+            readonly refreshUrl: Schema.OptionFromOptional<Schema.String>;
+            readonly scopes: Schema.$Record<Schema.String, Schema.String>;
+        }>>;
+    }>>;
+    /** For type: "openIdConnect" — the discovery URL. */
+    readonly openIdConnectUrl: Schema.OptionFromOptional<Schema.String>;
+}>;
+export type SecurityScheme = typeof SecurityScheme.Type;
+export declare const AuthStrategy: Schema.Struct<{
+    /** The security schemes required together for this strategy */
+    readonly schemes: Schema.$Array<Schema.String>;
+}>;
+export type AuthStrategy = typeof AuthStrategy.Type;
+export declare const HeaderPreset: Schema.Struct<{
+    /** Human-readable label for the UI (e.g. "Bearer Token", "API Key + Email") */
+    readonly label: Schema.String;
+    /** Headers this strategy needs. Value is null when the user must provide it. */
+    readonly headers: Schema.$Record<Schema.String, Schema.NullOr<Schema.String>>;
+    /** Which headers should be stored as secrets */
+    readonly secretHeaders: Schema.$Array<Schema.String>;
+}>;
+export type HeaderPreset = typeof HeaderPreset.Type;
+export declare const OAuth2Preset: Schema.Struct<{
+    /** Human-readable label for the UI (e.g. "OAuth2 (Authorization Code) — oauth_app") */
+    readonly label: Schema.String;
+    /** The source security scheme this preset came from (components.securitySchemes key). */
+    readonly securitySchemeName: Schema.String;
+    /** Which OAuth2 flow this preset uses. */
+    readonly flow: Schema.Literals<readonly ["authorizationCode", "clientCredentials"]>;
+    /** For authorizationCode: user-agent redirect URL (from the spec). */
+    readonly authorizationUrl: Schema.OptionFromOptional<Schema.String>;
+    /** Token endpoint to exchange the code / refresh. */
+    readonly tokenUrl: Schema.String;
+    /** RFC 8707 resource indicator discovered from protected-resource metadata. */
+    readonly resource: Schema.OptionFromOptional<Schema.String>;
+    /** Optional refresh endpoint if the spec declares one separately. */
+    readonly refreshUrl: Schema.OptionFromOptional<Schema.String>;
+    /** Declared scopes for this flow: `{ scope: description }`. */
+    readonly scopes: Schema.$Record<Schema.String, Schema.String>;
+    /** Identity scopes to request alongside API scopes. `"auto"` discovers standard OIDC scopes. */
+    readonly identityScopes: Schema.Union<readonly [Schema.Literal<"auto">, Schema.Literal<false>, Schema.$Array<Schema.String>]>;
+    /** Provider metadata advertised Client ID Metadata Document support. */
+    readonly supportsClientIdMetadataDocument: Schema.optional<Schema.Boolean>;
+}>;
+export type OAuth2Preset = typeof OAuth2Preset.Type;
+export declare const PreviewOperation: Schema.Struct<{
+    readonly operationId: Schema.String;
+    readonly method: Schema.Literals<readonly ["get", "put", "post", "delete", "patch", "head", "options", "trace"]>;
+    readonly path: Schema.String;
+    readonly summary: Schema.OptionFromOptional<Schema.String>;
+    readonly tags: Schema.$Array<Schema.String>;
+    readonly deprecated: Schema.Boolean;
+}>;
+export type PreviewOperation = typeof PreviewOperation.Type;
+export declare const SpecPreview: Schema.Struct<{
+    readonly title: Schema.OptionFromOptional<Schema.String>;
+    /** The spec's `info.description` — prefills the add form's description field. */
+    readonly description: Schema.OptionFromOptional<Schema.String>;
+    readonly version: Schema.OptionFromOptional<Schema.String>;
+    /** Reuses ServerInfo from extraction */
+    readonly servers: Schema.$Array<Schema.Struct<{
+        readonly url: Schema.String;
+        readonly description: Schema.OptionFromOptional<Schema.String>;
+        readonly variables: Schema.OptionFromOptional<Schema.$Record<Schema.String, Schema.Struct<{
+            readonly default: Schema.String;
+            readonly enum: Schema.OptionFromOptional<Schema.$Array<Schema.String>>;
+            readonly description: Schema.OptionFromOptional<Schema.String>;
+        }>>>;
+    }>>;
+    readonly operationCount: Schema.Number;
+    /** Lightweight operation list for the add-integration UI */
+    readonly operations: Schema.$Array<Schema.Struct<{
+        readonly operationId: Schema.String;
+        readonly method: Schema.Literals<readonly ["get", "put", "post", "delete", "patch", "head", "options", "trace"]>;
+        readonly path: Schema.String;
+        readonly summary: Schema.OptionFromOptional<Schema.String>;
+        readonly tags: Schema.$Array<Schema.String>;
+        readonly deprecated: Schema.Boolean;
+    }>>;
+    readonly tags: Schema.$Array<Schema.String>;
+    readonly securitySchemes: Schema.$Array<Schema.Struct<{
+        /** Key name in components.securitySchemes (e.g. "api_token") */
+        readonly name: Schema.String;
+        /** OpenAPI security scheme type */
+        readonly type: Schema.Literals<readonly ["http", "apiKey", "oauth2", "openIdConnect"]>;
+        /** For type: "http" — e.g. "bearer", "basic" */
+        readonly scheme: Schema.OptionFromOptional<Schema.String>;
+        /** For type: "http" with scheme "bearer" — e.g. "JWT" */
+        readonly bearerFormat: Schema.OptionFromOptional<Schema.String>;
+        /** For type: "apiKey" — where the key goes */
+        readonly in: Schema.OptionFromOptional<Schema.Literals<readonly ["header", "query", "cookie"]>>;
+        /** For type: "apiKey" — the header/query/cookie name */
+        readonly headerName: Schema.OptionFromOptional<Schema.String>;
+        readonly description: Schema.OptionFromOptional<Schema.String>;
+        /** For type: "oauth2" — declared flows (authorizationCode / clientCredentials only; implicit and password are deprecated). */
+        readonly flows: Schema.OptionFromOptional<Schema.Struct<{
+            readonly authorizationCode: Schema.OptionFromOptional<Schema.Struct<{
+                readonly authorizationUrl: Schema.String;
+                readonly tokenUrl: Schema.String;
+                readonly refreshUrl: Schema.OptionFromOptional<Schema.String>;
+                readonly scopes: Schema.$Record<Schema.String, Schema.String>;
+            }>>;
+            readonly clientCredentials: Schema.OptionFromOptional<Schema.Struct<{
+                readonly tokenUrl: Schema.String;
+                readonly refreshUrl: Schema.OptionFromOptional<Schema.String>;
+                readonly scopes: Schema.$Record<Schema.String, Schema.String>;
+            }>>;
+        }>>;
+        /** For type: "openIdConnect" — the discovery URL. */
+        readonly openIdConnectUrl: Schema.OptionFromOptional<Schema.String>;
+    }>>;
+    /** Valid auth strategies (each is a set of schemes used together) */
+    readonly authStrategies: Schema.$Array<Schema.Struct<{
+        /** The security schemes required together for this strategy */
+        readonly schemes: Schema.$Array<Schema.String>;
+    }>>;
+    /** Pre-built header presets derived from auth strategies */
+    readonly headerPresets: Schema.$Array<Schema.Struct<{
+        /** Human-readable label for the UI (e.g. "Bearer Token", "API Key + Email") */
+        readonly label: Schema.String;
+        /** Headers this strategy needs. Value is null when the user must provide it. */
+        readonly headers: Schema.$Record<Schema.String, Schema.NullOr<Schema.String>>;
+        /** Which headers should be stored as secrets */
+        readonly secretHeaders: Schema.$Array<Schema.String>;
+    }>>;
+    /** OAuth2 presets — one per (oauth2 scheme × supported flow) combination */
+    readonly oauth2Presets: Schema.$Array<Schema.Struct<{
+        /** Human-readable label for the UI (e.g. "OAuth2 (Authorization Code) — oauth_app") */
+        readonly label: Schema.String;
+        /** The source security scheme this preset came from (components.securitySchemes key). */
+        readonly securitySchemeName: Schema.String;
+        /** Which OAuth2 flow this preset uses. */
+        readonly flow: Schema.Literals<readonly ["authorizationCode", "clientCredentials"]>;
+        /** For authorizationCode: user-agent redirect URL (from the spec). */
+        readonly authorizationUrl: Schema.OptionFromOptional<Schema.String>;
+        /** Token endpoint to exchange the code / refresh. */
+        readonly tokenUrl: Schema.String;
+        /** RFC 8707 resource indicator discovered from protected-resource metadata. */
+        readonly resource: Schema.OptionFromOptional<Schema.String>;
+        /** Optional refresh endpoint if the spec declares one separately. */
+        readonly refreshUrl: Schema.OptionFromOptional<Schema.String>;
+        /** Declared scopes for this flow: `{ scope: description }`. */
+        readonly scopes: Schema.$Record<Schema.String, Schema.String>;
+        /** Identity scopes to request alongside API scopes. `"auto"` discovers standard OIDC scopes. */
+        readonly identityScopes: Schema.Union<readonly [Schema.Literal<"auto">, Schema.Literal<false>, Schema.$Array<Schema.String>]>;
+        /** Provider metadata advertised Client ID Metadata Document support. */
+        readonly supportsClientIdMetadataDocument: Schema.optional<Schema.Boolean>;
+    }>>;
+    /** Top-ranked health-check candidates (bounded), so the add screen can offer a
+     *  typed operation + identity picker before the integration is registered. */
+    readonly healthCheckCandidates: Schema.$Array<Schema.Struct<{
+        readonly operation: Schema.String;
+        readonly method: Schema.String;
+        readonly requiredArgCount: Schema.Number;
+        readonly destructive: Schema.Boolean;
+        readonly summary: Schema.optional<Schema.String>;
+        readonly parameters: Schema.optional<Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly location: Schema.String;
+            readonly required: Schema.Boolean;
+            readonly description: Schema.optional<Schema.String>;
+        }>>>;
+        readonly responseFields: Schema.optional<Schema.$Array<Schema.Struct<{
+            readonly path: Schema.String;
+            readonly type: Schema.String;
+        }>>>;
+    }>>;
+}>;
+export type SpecPreview = typeof SpecPreview.Type;
+export declare const SpecPreviewSummary: Schema.Struct<{
+    readonly title: Schema.OptionFromOptional<Schema.String>;
+    readonly description: Schema.OptionFromOptional<Schema.String>;
+    readonly version: Schema.OptionFromOptional<Schema.String>;
+    readonly servers: Schema.$Array<Schema.Struct<{
+        readonly url: Schema.String;
+        readonly description: Schema.OptionFromOptional<Schema.String>;
+        readonly variables: Schema.OptionFromOptional<Schema.$Record<Schema.String, Schema.Struct<{
+            readonly default: Schema.String;
+            readonly enum: Schema.OptionFromOptional<Schema.$Array<Schema.String>>;
+            readonly description: Schema.OptionFromOptional<Schema.String>;
+        }>>>;
+    }>>;
+    readonly operationCount: Schema.Number;
+    readonly tags: Schema.$Array<Schema.String>;
+    readonly securitySchemes: Schema.$Array<Schema.Struct<{
+        /** Key name in components.securitySchemes (e.g. "api_token") */
+        readonly name: Schema.String;
+        /** OpenAPI security scheme type */
+        readonly type: Schema.Literals<readonly ["http", "apiKey", "oauth2", "openIdConnect"]>;
+        /** For type: "http" — e.g. "bearer", "basic" */
+        readonly scheme: Schema.OptionFromOptional<Schema.String>;
+        /** For type: "http" with scheme "bearer" — e.g. "JWT" */
+        readonly bearerFormat: Schema.OptionFromOptional<Schema.String>;
+        /** For type: "apiKey" — where the key goes */
+        readonly in: Schema.OptionFromOptional<Schema.Literals<readonly ["header", "query", "cookie"]>>;
+        /** For type: "apiKey" — the header/query/cookie name */
+        readonly headerName: Schema.OptionFromOptional<Schema.String>;
+        readonly description: Schema.OptionFromOptional<Schema.String>;
+        /** For type: "oauth2" — declared flows (authorizationCode / clientCredentials only; implicit and password are deprecated). */
+        readonly flows: Schema.OptionFromOptional<Schema.Struct<{
+            readonly authorizationCode: Schema.OptionFromOptional<Schema.Struct<{
+                readonly authorizationUrl: Schema.String;
+                readonly tokenUrl: Schema.String;
+                readonly refreshUrl: Schema.OptionFromOptional<Schema.String>;
+                readonly scopes: Schema.$Record<Schema.String, Schema.String>;
+            }>>;
+            readonly clientCredentials: Schema.OptionFromOptional<Schema.Struct<{
+                readonly tokenUrl: Schema.String;
+                readonly refreshUrl: Schema.OptionFromOptional<Schema.String>;
+                readonly scopes: Schema.$Record<Schema.String, Schema.String>;
+            }>>;
+        }>>;
+        /** For type: "openIdConnect" — the discovery URL. */
+        readonly openIdConnectUrl: Schema.OptionFromOptional<Schema.String>;
+    }>>;
+    readonly authStrategies: Schema.$Array<Schema.Struct<{
+        /** The security schemes required together for this strategy */
+        readonly schemes: Schema.$Array<Schema.String>;
+    }>>;
+    readonly headerPresets: Schema.$Array<Schema.Struct<{
+        /** Human-readable label for the UI (e.g. "Bearer Token", "API Key + Email") */
+        readonly label: Schema.String;
+        /** Headers this strategy needs. Value is null when the user must provide it. */
+        readonly headers: Schema.$Record<Schema.String, Schema.NullOr<Schema.String>>;
+        /** Which headers should be stored as secrets */
+        readonly secretHeaders: Schema.$Array<Schema.String>;
+    }>>;
+    readonly oauth2Presets: Schema.$Array<Schema.Struct<{
+        /** Human-readable label for the UI (e.g. "OAuth2 (Authorization Code) — oauth_app") */
+        readonly label: Schema.String;
+        /** The source security scheme this preset came from (components.securitySchemes key). */
+        readonly securitySchemeName: Schema.String;
+        /** Which OAuth2 flow this preset uses. */
+        readonly flow: Schema.Literals<readonly ["authorizationCode", "clientCredentials"]>;
+        /** For authorizationCode: user-agent redirect URL (from the spec). */
+        readonly authorizationUrl: Schema.OptionFromOptional<Schema.String>;
+        /** Token endpoint to exchange the code / refresh. */
+        readonly tokenUrl: Schema.String;
+        /** RFC 8707 resource indicator discovered from protected-resource metadata. */
+        readonly resource: Schema.OptionFromOptional<Schema.String>;
+        /** Optional refresh endpoint if the spec declares one separately. */
+        readonly refreshUrl: Schema.OptionFromOptional<Schema.String>;
+        /** Declared scopes for this flow: `{ scope: description }`. */
+        readonly scopes: Schema.$Record<Schema.String, Schema.String>;
+        /** Identity scopes to request alongside API scopes. `"auto"` discovers standard OIDC scopes. */
+        readonly identityScopes: Schema.Union<readonly [Schema.Literal<"auto">, Schema.Literal<false>, Schema.$Array<Schema.String>]>;
+        /** Provider metadata advertised Client ID Metadata Document support. */
+        readonly supportsClientIdMetadataDocument: Schema.optional<Schema.Boolean>;
+    }>>;
+    readonly healthCheckCandidates: Schema.$Array<Schema.Struct<{
+        readonly operation: Schema.String;
+        readonly method: Schema.String;
+        readonly requiredArgCount: Schema.Number;
+        readonly destructive: Schema.Boolean;
+        readonly summary: Schema.optional<Schema.String>;
+        readonly parameters: Schema.optional<Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly location: Schema.String;
+            readonly required: Schema.Boolean;
+            readonly description: Schema.optional<Schema.String>;
+        }>>>;
+        readonly responseFields: Schema.optional<Schema.$Array<Schema.Struct<{
+            readonly path: Schema.String;
+            readonly type: Schema.String;
+        }>>>;
+    }>>;
+}>;
+export type SpecPreviewSummary = typeof SpecPreviewSummary.Type;
+export declare const specPreviewSummary: (preview: SpecPreview) => SpecPreviewSummary;
+/** Preview already-resolved spec text — extract metadata without registering
+ *  anything and without any HTTP dependency. */
+export declare const previewSpecText: (specText: string) => Effect.Effect<{
+    readonly version: Option.Option<string>;
+    readonly operations: readonly {
+        readonly path: string;
+        readonly summary: Option.Option<string>;
+        readonly method: "post" | "options" | "get" | "delete" | "put" | "patch" | "head" | "trace";
+        readonly deprecated: boolean;
+        readonly tags: readonly string[];
+        readonly operationId: string;
+    }[];
+    readonly description: Option.Option<string>;
+    readonly title: Option.Option<string>;
+    readonly servers: readonly {
+        readonly description: Option.Option<string>;
+        readonly url: string;
+        readonly variables: Option.Option<{
+            readonly [x: string]: {
+                readonly default: string;
+                readonly description: Option.Option<string>;
+                readonly enum: Option.Option<readonly string[]>;
+            };
+        }>;
+    }[];
+    readonly tags: readonly string[];
+    readonly securitySchemes: readonly {
+        readonly name: string;
+        readonly type: "oauth2" | "apiKey" | "http" | "openIdConnect";
+        readonly in: Option.Option<"header" | "query" | "cookie">;
+        readonly description: Option.Option<string>;
+        readonly scheme: Option.Option<string>;
+        readonly bearerFormat: Option.Option<string>;
+        readonly headerName: Option.Option<string>;
+        readonly flows: Option.Option<{
+            readonly authorizationCode: Option.Option<{
+                readonly authorizationUrl: string;
+                readonly tokenUrl: string;
+                readonly scopes: {
+                    readonly [x: string]: string;
+                };
+                readonly refreshUrl: Option.Option<string>;
+            }>;
+            readonly clientCredentials: Option.Option<{
+                readonly tokenUrl: string;
+                readonly scopes: {
+                    readonly [x: string]: string;
+                };
+                readonly refreshUrl: Option.Option<string>;
+            }>;
+        }>;
+        readonly openIdConnectUrl: Option.Option<string>;
+    }[];
+    readonly authStrategies: readonly {
+        readonly schemes: readonly string[];
+    }[];
+    readonly headerPresets: readonly {
+        readonly label: string;
+        readonly headers: {
+            readonly [x: string]: string | null;
+        };
+        readonly secretHeaders: readonly string[];
+    }[];
+    readonly oauth2Presets: readonly {
+        readonly resource: Option.Option<string>;
+        readonly label: string;
+        readonly authorizationUrl: Option.Option<string>;
+        readonly tokenUrl: string;
+        readonly scopes: {
+            readonly [x: string]: string;
+        };
+        readonly refreshUrl: Option.Option<string>;
+        readonly flow: "authorizationCode" | "clientCredentials";
+        readonly identityScopes: false | "auto" | readonly string[];
+        readonly securitySchemeName: string;
+        readonly supportsClientIdMetadataDocument?: boolean | undefined;
+    }[];
+    readonly healthCheckCandidates: readonly {
+        readonly operation: string;
+        readonly method: string;
+        readonly requiredArgCount: number;
+        readonly destructive: boolean;
+        readonly summary?: string | undefined;
+        readonly parameters?: readonly {
+            readonly name: string;
+            readonly required: boolean;
+            readonly location: string;
+            readonly description?: string | undefined;
+        }[] | undefined;
+        readonly responseFields?: readonly {
+            readonly type: string;
+            readonly path: string;
+        }[] | undefined;
+    }[];
+    readonly operationCount: number;
+}, import("./errors").OpenApiParseError | import("./errors").OpenApiExtractionError, never>;
+/** Preview an OpenAPI spec — extract metadata without registering anything.
+ *  Accepts either a URL or raw JSON/YAML text. */
+export declare const previewSpec: (input: string) => Effect.Effect<{
+    readonly version: Option.Option<string>;
+    readonly operations: readonly {
+        readonly path: string;
+        readonly summary: Option.Option<string>;
+        readonly method: "post" | "options" | "get" | "delete" | "put" | "patch" | "head" | "trace";
+        readonly deprecated: boolean;
+        readonly tags: readonly string[];
+        readonly operationId: string;
+    }[];
+    readonly description: Option.Option<string>;
+    readonly title: Option.Option<string>;
+    readonly servers: readonly {
+        readonly description: Option.Option<string>;
+        readonly url: string;
+        readonly variables: Option.Option<{
+            readonly [x: string]: {
+                readonly default: string;
+                readonly description: Option.Option<string>;
+                readonly enum: Option.Option<readonly string[]>;
+            };
+        }>;
+    }[];
+    readonly tags: readonly string[];
+    readonly securitySchemes: readonly {
+        readonly name: string;
+        readonly type: "oauth2" | "apiKey" | "http" | "openIdConnect";
+        readonly in: Option.Option<"header" | "query" | "cookie">;
+        readonly description: Option.Option<string>;
+        readonly scheme: Option.Option<string>;
+        readonly bearerFormat: Option.Option<string>;
+        readonly headerName: Option.Option<string>;
+        readonly flows: Option.Option<{
+            readonly authorizationCode: Option.Option<{
+                readonly authorizationUrl: string;
+                readonly tokenUrl: string;
+                readonly scopes: {
+                    readonly [x: string]: string;
+                };
+                readonly refreshUrl: Option.Option<string>;
+            }>;
+            readonly clientCredentials: Option.Option<{
+                readonly tokenUrl: string;
+                readonly scopes: {
+                    readonly [x: string]: string;
+                };
+                readonly refreshUrl: Option.Option<string>;
+            }>;
+        }>;
+        readonly openIdConnectUrl: Option.Option<string>;
+    }[];
+    readonly authStrategies: readonly {
+        readonly schemes: readonly string[];
+    }[];
+    readonly headerPresets: readonly {
+        readonly label: string;
+        readonly headers: {
+            readonly [x: string]: string | null;
+        };
+        readonly secretHeaders: readonly string[];
+    }[];
+    readonly oauth2Presets: readonly {
+        readonly resource: Option.Option<string>;
+        readonly label: string;
+        readonly authorizationUrl: Option.Option<string>;
+        readonly tokenUrl: string;
+        readonly scopes: {
+            readonly [x: string]: string;
+        };
+        readonly refreshUrl: Option.Option<string>;
+        readonly flow: "authorizationCode" | "clientCredentials";
+        readonly identityScopes: false | "auto" | readonly string[];
+        readonly securitySchemeName: string;
+        readonly supportsClientIdMetadataDocument?: boolean | undefined;
+    }[];
+    readonly healthCheckCandidates: readonly {
+        readonly operation: string;
+        readonly method: string;
+        readonly requiredArgCount: number;
+        readonly destructive: boolean;
+        readonly summary?: string | undefined;
+        readonly parameters?: readonly {
+            readonly name: string;
+            readonly required: boolean;
+            readonly location: string;
+            readonly description?: string | undefined;
+        }[] | undefined;
+        readonly responseFields?: readonly {
+            readonly type: string;
+            readonly path: string;
+        }[] | undefined;
+    }[];
+    readonly operationCount: number;
+}, import("./errors").OpenApiParseError | import("./errors").OpenApiExtractionError, import("effect/unstable/http/HttpClient").HttpClient>;

package/dist/sdk/query-serialization.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/real-specs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/request-user-agent.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/response-headers-timeout.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/server-url-resolution.test.d.ts

@@ -0,0 +1 @@
+export {};