@executor-js/plugin-openapi 0.0.1-beta.6 → 0.0.2

package/dist/sdk/invoke.d.ts

@@ -1,23 +1,14 @@
 import { Effect, Layer } from "effect";
-import { HttpClient } from "@effect/platform";
-import { type ToolInvoker, type ScopeId, type SecretId } from "@executor-js/sdk";
+import { HttpClient } from "effect/unstable/http";
+import type { SecretOwnedByConnectionError, StorageFailure } from "@executor-js/sdk/core";
 import { OpenApiInvocationError } from "./errors";
-import type { OpenApiOperationStore } from "./operation-store";
-import { type OperationBinding, InvocationConfig, InvocationResult } from "./types";
-/** Invoke an OpenAPI operation binding. Requires HttpClient in the context. */
-export declare const invoke: (operation: OperationBinding, args: Record<string, unknown>, config: InvocationConfig, resolvedHeaders?: Record<string, string> | undefined) => Effect.Effect<InvocationResult, OpenApiInvocationError | import("@effect/platform/HttpClientError").ResponseError, HttpClient.HttpClient>;
-/**
- * Derive tool annotations from the HTTP method and path.
- */
+import { type HeaderValue, type OperationBinding, InvocationResult } from "./types";
+export declare const resolveHeaders: (headers: Record<string, HeaderValue>, secrets: {
+    readonly get: (id: string) => Effect.Effect<string | null, SecretOwnedByConnectionError | StorageFailure>;
+}) => Effect.Effect<Record<string, string>, OpenApiInvocationError | StorageFailure>;
+export declare const invoke: (operation: OperationBinding, args: Record<string, unknown>, resolvedHeaders: Record<string, string>, sourceQueryParams?: Record<string, string> | undefined) => Effect.Effect<InvocationResult, OpenApiInvocationError, HttpClient.HttpClient>;
+export declare const invokeWithLayer: (operation: OperationBinding, args: Record<string, unknown>, baseUrl: string, resolvedHeaders: Record<string, string>, sourceQueryParams: Record<string, string>, httpClientLayer: Layer.Layer<HttpClient.HttpClient, never, never>) => Effect.Effect<InvocationResult, OpenApiInvocationError, never>;
 export declare const annotationsForOperation: (method: string, pathTemplate: string) => {
     requiresApproval?: boolean;
     approvalDescription?: string;
 };
-export declare const makeOpenApiInvoker: (opts: {
-    readonly operationStore: OpenApiOperationStore;
-    readonly httpClientLayer: Layer.Layer<HttpClient.HttpClient>;
-    readonly secrets: {
-        readonly resolve: (secretId: SecretId, scopeId: ScopeId) => Effect.Effect<string, unknown>;
-    };
-    readonly scopeId: ScopeId;
-}) => ToolInvoker;

package/dist/sdk/multi-scope-bearer.test.d.ts

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

package/dist/sdk/multi-scope-oauth.test.d.ts

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

package/dist/sdk/non-json-body.test.d.ts

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

package/dist/sdk/oauth-refresh.test.d.ts

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

package/dist/sdk/openapi-utils.d.ts

@@ -13,12 +13,43 @@ export declare class DocResolver {
     resolve<T>(value: T | OpenAPIV3.ReferenceObject | OpenAPIV3_1.ReferenceObject): T | null;
     private resolvePointer;
 }
-export declare const resolveBaseUrl: (servers: readonly {
+/** Substitute `{var}` placeholders in a templated URL using a plain map. */
+export declare const substituteUrlVariables: (url: string, values: Record<string, string>) => string;
+type ServerLike = {
     url: string;
-    variables: import("effect/Option").Option<Record<string, string>>;
-}[]) => string;
-/** Pick the preferred media type entry (prefer application/json) */
+    variables: import("effect/Option").Option<Record<string, {
+        default: string;
+    } | string>>;
+};
+export declare const resolveBaseUrl: (servers: readonly ServerLike[]) => string;
+/**
+ * Return all declared media entries in spec order. `Object.entries` on a
+ * plain object preserves insertion order in modern engines, which matches
+ * spec declaration order as the parser produced it.
+ */
+export declare const declaredContents: (content: Record<string, MediaTypeObject> | undefined) => ReadonlyArray<{
+    mediaType: string;
+    media: MediaTypeObject;
+}>;
+/**
+ * Pick the default media type for a requestBody or response. Matches
+ * swagger-client behaviour: **first declared wins** (not JSON-first). Spec
+ * authors order content entries to signal intent (upload-heavy endpoints
+ * declare multipart first, JSON second); respecting that order avoids
+ * silently downgrading a multipart endpoint to JSON.
+ *
+ * For response bodies we still want a JSON preference because the server
+ * picks the response content type, not the client — the old `application/
+ * json` preference is preserved via `preferredResponseContent` below.
+ */
 export declare const preferredContent: (content: Record<string, MediaTypeObject> | undefined) => {
     mediaType: string;
     media: MediaTypeObject;
 } | undefined;
+/** Response-side content picker — still JSON-first because the server
+ *  picks the response media type, so we want to advertise a preference. */
+export declare const preferredResponseContent: (content: Record<string, MediaTypeObject> | undefined) => {
+    mediaType: string;
+    media: MediaTypeObject;
+} | undefined;
+export {};

package/dist/sdk/parse.d.ts

@@ -1,10 +1,34 @@
 import type { OpenAPIV3, OpenAPIV3_1 } from "openapi-types";
 import { Effect } from "effect";
-import { OpenApiParseError } from "./errors";
+import { HttpClient } from "effect/unstable/http";
+import { OpenApiExtractionError, OpenApiParseError } from "./errors";
 export type ParsedDocument = OpenAPIV3.Document | OpenAPIV3_1.Document;
-/** Parse, validate, and bundle an OpenAPI document from text or URL */
-export declare const parse: (input: string) => Effect.Effect<ParsedDocument, OpenApiParseError | OpenApiExtractionErrorFromParse, never>;
-import { OpenApiExtractionError } from "./errors";
+export interface SpecFetchCredentials {
+    readonly headers?: Record<string, string>;
+    readonly queryParams?: Record<string, string>;
+}
 declare class OpenApiExtractionErrorFromParse extends OpenApiExtractionError {
 }
+/**
+ * Fetch an OpenAPI spec URL and return its body text. Uses the Effect
+ * HttpClient so the caller chooses the transport via layer — in Cloudflare
+ * Workers, `FetchHttpClient.layer` binds to the Workers-native `fetch` and
+ * avoids json-schema-ref-parser's Node-polyfill http resolver, which hangs
+ * in production. Bounded by a 20s timeout.
+ */
+export declare const fetchSpecText: (url: string, credentials?: SpecFetchCredentials | undefined) => Effect.Effect<string, OpenApiParseError, HttpClient.HttpClient>;
+/**
+ * Resolve an input string to spec text — if it's a URL, fetch it via
+ * HttpClient; otherwise return it as-is.
+ */
+export declare const resolveSpecText: (input: string, credentials?: SpecFetchCredentials) => Effect.Effect<string, OpenApiParseError, HttpClient.HttpClient>;
+/**
+ * Parse an OpenAPI document from spec text and validate it's OpenAPI 3.x.
+ *
+ * NOTE: does NOT resolve `$ref`s. `DocResolver` + `normalizeOpenApiRefs`
+ * downstream work on refs lazily, so inlining them here would just waste
+ * memory — and for big specs (e.g. Cloudflare's API) that blows through
+ * the 128MB Cloudflare Workers memory cap.
+ */
+export declare const parse: (text: string) => Effect.Effect<ParsedDocument, OpenApiParseError | OpenApiExtractionErrorFromParse, never>;
 export {};

package/dist/sdk/plugin.d.ts

@@ -1,39 +1,186 @@
 import { Effect } from "effect";
-import { HttpClient } from "@effect/platform";
+import { HttpClient } from "effect/unstable/http";
 import type { Layer } from "effect";
-import { type ExecutorPlugin } from "@executor-js/sdk";
-import type { OpenApiOperationStore, StoredSource } from "./operation-store";
+import { type StorageFailure } from "@executor-js/sdk/core";
+import { type ConfigFileSink } from "@executor-js/config";
+import { OpenApiExtractionError, OpenApiOAuthError, OpenApiParseError } from "./errors";
 import { SpecPreview } from "./preview";
-import { type HeaderValue as HeaderValueValue } from "./types";
-/** A header value — either a static string or a reference to a secret */
+import { type OpenapiStore, type StoredSource } from "./store";
+import { OAuth2Auth, OAuth2SourceConfig, OpenApiSourceBindingInput, type OpenApiSourceBindingRef, type ConfiguredHeaderValue as ConfiguredHeaderValueValue, type HeaderValue as HeaderValueValue } from "./types";
 export type HeaderValue = HeaderValueValue;
+export type ConfiguredHeaderValue = ConfiguredHeaderValueValue;
+export type OpenApiHeaderInput = HeaderValue | ConfiguredHeaderValue;
+export type OpenApiOAuthInput = OAuth2Auth | OAuth2SourceConfig;
+export interface OpenApiSpecFetchCredentials {
+    readonly headers?: Record<string, HeaderValue>;
+    readonly queryParams?: Record<string, HeaderValue>;
+}
+export interface OpenApiPreviewInput {
+    readonly spec: string;
+    readonly specFetchCredentials?: OpenApiSpecFetchCredentials;
+}
 export interface OpenApiSpecConfig {
     readonly spec: string;
+    readonly specFetchCredentials?: OpenApiSpecFetchCredentials;
+    /**
+     * Executor scope id that owns this source row. Must be one of the
+     * executor's configured scopes. Typical shape: an admin adds the
+     * source at the outermost (organization) scope so it's visible to
+     * every inner (per-user) scope via fall-through reads.
+     */
+    readonly scope: string;
     readonly name?: string;
     readonly baseUrl?: string;
     readonly namespace?: string;
-    /** Headers applied to every request. Values can reference secrets. */
-    readonly headers?: Record<string, HeaderValue>;
+    readonly headers?: Record<string, OpenApiHeaderInput>;
+    readonly queryParams?: Record<string, HeaderValue>;
+    readonly oauth2?: OpenApiOAuthInput;
 }
 export interface OpenApiUpdateSourceInput {
+    readonly name?: string;
     readonly baseUrl?: string;
-    readonly headers?: Record<string, HeaderValue>;
+    readonly headers?: Record<string, OpenApiHeaderInput>;
+    readonly queryParams?: Record<string, HeaderValue>;
+    /** Refresh the source's stored OAuth2 metadata after a successful
+     *  re-authenticate. */
+    readonly oauth2?: OpenApiOAuthInput;
 }
+/**
+ * Errors any OpenAPI extension method may surface. The first three are
+ * plugin-domain tagged errors that flow directly to clients (4xx, each
+ * carrying its own `HttpApiSchema` status). `StorageFailure` covers
+ * raw backend failures (`StorageError`) plus `UniqueViolationError`;
+ * the HTTP edge (`@executor-js/api`'s `withCapture`) translates
+ * `StorageError` to the opaque `InternalError({ traceId })` at Layer
+ * composition. `UniqueViolationError` passes through — plugins can
+ * `Effect.catchTag` it if they want a friendlier user-facing error.
+ */
+export type OpenApiExtensionFailure = OpenApiParseError | OpenApiExtractionError | OpenApiOAuthError | StorageFailure;
 export interface OpenApiPluginExtension {
-    /** Preview a spec without registering — returns metadata, auth strategies, header presets */
-    readonly previewSpec: (specText: string) => Effect.Effect<SpecPreview, Error>;
-    /** Add an OpenAPI spec and register its operations as tools */
+    readonly previewSpec: (input: string | OpenApiPreviewInput) => Effect.Effect<SpecPreview, OpenApiParseError | OpenApiExtractionError | OpenApiOAuthError | StorageFailure>;
     readonly addSpec: (config: OpenApiSpecConfig) => Effect.Effect<{
+        readonly sourceId: string;
         readonly toolCount: number;
-    }, Error>;
-    /** Remove all tools from a previously added spec by namespace */
-    readonly removeSpec: (namespace: string) => Effect.Effect<void>;
-    /** Fetch the full stored source by namespace (or null if missing) */
-    readonly getSource: (namespace: string) => Effect.Effect<StoredSource | null>;
-    /** Update config (baseUrl, headers) for an existing OpenAPI source */
-    readonly updateSource: (namespace: string, input: OpenApiUpdateSourceInput) => Effect.Effect<void>;
+    }, OpenApiParseError | OpenApiExtractionError | OpenApiOAuthError | StorageFailure>;
+    readonly removeSpec: (namespace: string, scope: string) => Effect.Effect<void, StorageFailure>;
+    readonly getSource: (namespace: string, scope: string) => Effect.Effect<StoredSource | null, StorageFailure>;
+    readonly updateSource: (namespace: string, scope: string, input: OpenApiUpdateSourceInput) => Effect.Effect<void, StorageFailure>;
+    readonly listSourceBindings: (sourceId: string, sourceScope: string) => Effect.Effect<readonly OpenApiSourceBindingRef[], StorageFailure>;
+    readonly setSourceBinding: (input: OpenApiSourceBindingInput) => Effect.Effect<OpenApiSourceBindingRef, StorageFailure>;
+    readonly removeSourceBinding: (sourceId: string, sourceScope: string, slot: string, scope: string) => Effect.Effect<void, StorageFailure>;
+}
+export interface OpenApiPluginOptions {
+    readonly httpClientLayer?: Layer.Layer<HttpClient.HttpClient, never, never>;
+    /** If provided, source add/remove is mirrored to executor.jsonc
+     *  (best-effort — file errors are logged, not raised). */
+    readonly configFile?: ConfigFileSink;
 }
-export declare const openApiPlugin: (options?: {
-    readonly httpClientLayer?: Layer.Layer<HttpClient.HttpClient>;
-    readonly operationStore?: OpenApiOperationStore;
-}) => ExecutorPlugin<"openapi", OpenApiPluginExtension>;
+export declare const openApiPlugin: import("@executor-js/sdk/core").ConfiguredPlugin<"openapi", OpenApiPluginExtension, OpenapiStore, OpenApiPluginOptions, {
+    readonly openapi_source: {
+        readonly fields: {
+            readonly id: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly scope_id: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly name: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly spec: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly source_url: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly base_url: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly headers: {
+                readonly type: "json";
+                readonly required: false;
+            };
+            readonly query_params: {
+                readonly type: "json";
+                readonly required: false;
+            };
+            readonly oauth2: {
+                readonly type: "json";
+                readonly required: false;
+            };
+            readonly invocation_config: {
+                readonly type: "json";
+                readonly required: true;
+            };
+        };
+    };
+    readonly openapi_operation: {
+        readonly fields: {
+            readonly id: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly scope_id: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly source_id: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly binding: {
+                readonly type: "json";
+                readonly required: true;
+            };
+        };
+    };
+    readonly openapi_source_binding: {
+        readonly fields: {
+            readonly id: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly source_id: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly source_scope_id: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly target_scope_id: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly slot: {
+                readonly type: "string";
+                readonly required: true;
+                readonly index: true;
+            };
+            readonly value: {
+                readonly type: "json";
+                readonly required: true;
+            };
+            readonly created_at: {
+                readonly type: "date";
+                readonly required: true;
+            };
+            readonly updated_at: {
+                readonly type: "date";
+                readonly required: true;
+            };
+        };
+    };
+}>;

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

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

package/dist/sdk/preview.d.ts

@@ -1,148 +1,112 @@
-import { Effect, Option } from "effect";
+import { Effect } from "effect";
 import { Schema } from "effect";
-declare const SecurityScheme_base: Schema.Class<SecurityScheme, {
-    /** Key name in components.securitySchemes (e.g. "api_token") */
-    name: typeof Schema.String;
-    /** OpenAPI security scheme type */
-    type: Schema.Literal<["http", "apiKey", "oauth2", "openIdConnect"]>;
-    /** For type: "http" — e.g. "bearer", "basic" */
-    scheme: Schema.optionalWith<typeof Schema.String, {
-        as: "Option";
-    }>;
-    /** For type: "apiKey" — where the key goes */
-    in: Schema.optionalWith<Schema.Literal<["header", "query", "cookie"]>, {
-        as: "Option";
-    }>;
-    /** For type: "apiKey" — the header/query/cookie name */
-    headerName: Schema.optionalWith<typeof Schema.String, {
-        as: "Option";
-    }>;
-    description: Schema.optionalWith<typeof Schema.String, {
-        as: "Option";
-    }>;
-}, Schema.Struct.Encoded<{
+import { ServerInfo } from "./types";
+declare const OAuth2AuthorizationCodeFlow_base: Schema.Class<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 declare class OAuth2AuthorizationCodeFlow extends OAuth2AuthorizationCodeFlow_base {
+}
+declare const OAuth2ClientCredentialsFlow_base: Schema.Class<OAuth2ClientCredentialsFlow, Schema.Struct<{
+    readonly tokenUrl: Schema.String;
+    readonly refreshUrl: Schema.OptionFromOptional<Schema.String>;
+    readonly scopes: Schema.$Record<Schema.String, Schema.String>;
+}>, {}>;
+export declare class OAuth2ClientCredentialsFlow extends OAuth2ClientCredentialsFlow_base {
+}
+declare const OAuth2Flows_base: Schema.Class<OAuth2Flows, Schema.Struct<{
+    readonly authorizationCode: Schema.OptionFromOptional<typeof OAuth2AuthorizationCodeFlow>;
+    readonly clientCredentials: Schema.OptionFromOptional<typeof OAuth2ClientCredentialsFlow>;
+}>, {}>;
+export declare class OAuth2Flows extends OAuth2Flows_base {
+}
+declare const SecurityScheme_base: Schema.Class<SecurityScheme, Schema.Struct<{
     /** Key name in components.securitySchemes (e.g. "api_token") */
-    name: typeof Schema.String;
+    readonly name: Schema.String;
     /** OpenAPI security scheme type */
-    type: Schema.Literal<["http", "apiKey", "oauth2", "openIdConnect"]>;
+    readonly type: Schema.Literals<readonly ["http", "apiKey", "oauth2", "openIdConnect"]>;
     /** For type: "http" — e.g. "bearer", "basic" */
-    scheme: Schema.optionalWith<typeof Schema.String, {
-        as: "Option";
-    }>;
+    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 */
-    in: Schema.optionalWith<Schema.Literal<["header", "query", "cookie"]>, {
-        as: "Option";
-    }>;
+    readonly in: Schema.OptionFromOptional<Schema.Literals<readonly ["header", "query", "cookie"]>>;
     /** For type: "apiKey" — the header/query/cookie name */
-    headerName: Schema.optionalWith<typeof Schema.String, {
-        as: "Option";
-    }>;
-    description: Schema.optionalWith<typeof Schema.String, {
-        as: "Option";
-    }>;
-}>, never, {
-    readonly name: string;
-} & {
-    readonly description: Option.Option<string>;
-} & {
-    readonly type: "http" | "apiKey" | "oauth2" | "openIdConnect";
-} & {
-    readonly scheme: Option.Option<string>;
-} & {
-    readonly in: Option.Option<"query" | "header" | "cookie">;
-} & {
-    readonly headerName: Option.Option<string>;
-}, {}, {}>;
+    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<typeof OAuth2Flows>;
+    /** For type: "openIdConnect" — the discovery URL. */
+    readonly openIdConnectUrl: Schema.OptionFromOptional<Schema.String>;
+}>, {}>;
 export declare class SecurityScheme extends SecurityScheme_base {
 }
-declare const AuthStrategy_base: Schema.Class<AuthStrategy, {
-    /** The security schemes required together for this strategy */
-    schemes: Schema.Array$<typeof Schema.String>;
-}, Schema.Struct.Encoded<{
+declare const AuthStrategy_base: Schema.Class<AuthStrategy, Schema.Struct<{
     /** The security schemes required together for this strategy */
-    schemes: Schema.Array$<typeof Schema.String>;
-}>, never, {
-    readonly schemes: readonly string[];
-}, {}, {}>;
+    readonly schemes: Schema.$Array<Schema.String>;
+}>, {}>;
 export declare class AuthStrategy extends AuthStrategy_base {
 }
-declare const HeaderPreset_base: Schema.Class<HeaderPreset, {
+declare const HeaderPreset_base: Schema.Class<HeaderPreset, Schema.Struct<{
     /** Human-readable label for the UI (e.g. "Bearer Token", "API Key + Email") */
-    label: typeof Schema.String;
+    readonly label: Schema.String;
     /** Headers this strategy needs. Value is null when the user must provide it. */
-    headers: Schema.Record$<typeof Schema.String, Schema.NullOr<typeof Schema.String>>;
+    readonly headers: Schema.$Record<Schema.String, Schema.NullOr<Schema.String>>;
     /** Which headers should be stored as secrets */
-    secretHeaders: Schema.Array$<typeof Schema.String>;
-}, Schema.Struct.Encoded<{
-    /** Human-readable label for the UI (e.g. "Bearer Token", "API Key + Email") */
-    label: typeof Schema.String;
-    /** Headers this strategy needs. Value is null when the user must provide it. */
-    headers: Schema.Record$<typeof Schema.String, Schema.NullOr<typeof Schema.String>>;
-    /** Which headers should be stored as secrets */
-    secretHeaders: Schema.Array$<typeof Schema.String>;
-}>, never, {
-    readonly headers: {
-        readonly [x: string]: string | null;
-    };
-} & {
-    readonly label: string;
-} & {
-    readonly secretHeaders: readonly string[];
-}, {}, {}>;
+    readonly secretHeaders: Schema.$Array<Schema.String>;
+}>, {}>;
 export declare class HeaderPreset extends HeaderPreset_base {
 }
-declare const SpecPreview_base: Schema.Class<SpecPreview, {
-    title: Schema.optionalWith<typeof Schema.String, {
-        as: "Option";
-    }>;
-    version: Schema.optionalWith<typeof Schema.String, {
-        as: "Option";
-    }>;
-    /** Reuses ServerInfo from extraction */
-    servers: Schema.Array$<typeof Schema.Unknown>;
-    operationCount: typeof Schema.Number;
-    tags: Schema.Array$<typeof Schema.String>;
-    securitySchemes: Schema.Array$<typeof SecurityScheme>;
-    /** Valid auth strategies (each is a set of schemes used together) */
-    authStrategies: Schema.Array$<typeof AuthStrategy>;
-    /** Pre-built header presets derived from auth strategies */
-    headerPresets: Schema.Array$<typeof HeaderPreset>;
-}, Schema.Struct.Encoded<{
-    title: Schema.optionalWith<typeof Schema.String, {
-        as: "Option";
-    }>;
-    version: Schema.optionalWith<typeof Schema.String, {
-        as: "Option";
-    }>;
+declare const OAuth2Preset_base: Schema.Class<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;
+    /** 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>;
+}>, {}>;
+export declare class OAuth2Preset extends OAuth2Preset_base {
+}
+declare const PreviewOperation_base: Schema.Class<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 declare class PreviewOperation extends PreviewOperation_base {
+}
+declare const SpecPreview_base: Schema.Class<SpecPreview, Schema.Struct<{
+    readonly title: Schema.OptionFromOptional<Schema.String>;
+    readonly version: Schema.OptionFromOptional<Schema.String>;
     /** Reuses ServerInfo from extraction */
-    servers: Schema.Array$<typeof Schema.Unknown>;
-    operationCount: typeof Schema.Number;
-    tags: Schema.Array$<typeof Schema.String>;
-    securitySchemes: Schema.Array$<typeof SecurityScheme>;
+    readonly servers: Schema.$Array<typeof ServerInfo>;
+    readonly operationCount: Schema.Number;
+    /** Lightweight operation list for the add-source UI */
+    readonly operations: Schema.$Array<typeof PreviewOperation>;
+    readonly tags: Schema.$Array<Schema.String>;
+    readonly securitySchemes: Schema.$Array<typeof SecurityScheme>;
     /** Valid auth strategies (each is a set of schemes used together) */
-    authStrategies: Schema.Array$<typeof AuthStrategy>;
+    readonly authStrategies: Schema.$Array<typeof AuthStrategy>;
     /** Pre-built header presets derived from auth strategies */
-    headerPresets: Schema.Array$<typeof HeaderPreset>;
-}>, never, {
-    readonly title: Option.Option<string>;
-} & {
-    readonly servers: readonly unknown[];
-} & {
-    readonly tags: readonly string[];
-} & {
-    readonly version: Option.Option<string>;
-} & {
-    readonly securitySchemes: readonly SecurityScheme[];
-} & {
-    readonly operationCount: number;
-} & {
-    readonly authStrategies: readonly AuthStrategy[];
-} & {
-    readonly headerPresets: readonly HeaderPreset[];
-}, {}, {}>;
+    readonly headerPresets: Schema.$Array<typeof HeaderPreset>;
+    /** OAuth2 presets — one per (oauth2 scheme × supported flow) combination */
+    readonly oauth2Presets: Schema.$Array<typeof OAuth2Preset>;
+}>, {}>;
 export declare class SpecPreview extends SpecPreview_base {
 }
 /** Preview an OpenAPI spec — extract metadata without registering anything.
- *  Reuses parse() + extract() for the heavy lifting. */
-export declare const previewSpec: (specText: string) => Effect.Effect<SpecPreview, import("./errors").OpenApiParseError | import("./errors").OpenApiExtractionError, never>;
+ *  Accepts either a URL or raw JSON/YAML text. */
+export declare const previewSpec: (input: string) => Effect.Effect<SpecPreview, import("./errors").OpenApiParseError | import("./errors").OpenApiExtractionError, import("effect/unstable/http/HttpClient").HttpClient>;
 export {};