apps 0.0.1-beta.25 → 0.0.1-beta.26

package/types/apps/src/contracts/openapi-compile.d.ts

@@ -1,11 +1,39 @@
 /** Shared OpenAPI compilation diagnostics. */
 import { Schema } from "effect";
-export declare const OpenapiCompileErrorCode: Schema.Literals<readonly ["server_protocol", "server_url", "external_reference", "circular_reference", "schema_keyword", "schema_reference", "missing_component", "openapi_version", "auth_helper", "auth_missing", "operation_path", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
+export declare const OpenapiCompileErrorCode: Schema.Literals<readonly ["server_protocol", "server_url", "external_reference", "circular_reference", "schema_keyword", "schema_reference", "missing_component", "openapi_version", "auth_helper", "auth_missing", "operation_path", "operation_method", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "event_stream", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
+/** A declared operation the importer left out, and why. */
+export declare const OpenapiSkippedOperation: Schema.Struct<{
+    /** The tool name the operation would have; reading that tool reports why it is missing. */
+    readonly name: Schema.String;
+    /** The HTTP method, such as `GET`. */
+    readonly method: Schema.String;
+    /** The path as the definition declares it. */
+    readonly path: Schema.String;
+    readonly code: Schema.Literals<readonly ["server_protocol", "server_url", "external_reference", "circular_reference", "schema_keyword", "schema_reference", "missing_component", "openapi_version", "auth_helper", "auth_missing", "operation_path", "operation_method", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "event_stream", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
+    readonly reason: Schema.String;
+}>;
+export type OpenapiSkippedOperation = typeof OpenapiSkippedOperation.Type;
 declare const OpenapiCompileError_base: Schema.Class<OpenapiCompileError, Schema.TaggedStruct<"OpenapiCompileError", {
-    readonly code: Schema.Literals<readonly ["server_protocol", "server_url", "external_reference", "circular_reference", "schema_keyword", "schema_reference", "missing_component", "openapi_version", "auth_helper", "auth_missing", "operation_path", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
+    readonly code: Schema.Literals<readonly ["server_protocol", "server_url", "external_reference", "circular_reference", "schema_keyword", "schema_reference", "missing_component", "openapi_version", "auth_helper", "auth_missing", "operation_path", "operation_method", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "event_stream", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
     readonly reason: Schema.String;
+    readonly skipped: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        /** The tool name the operation would have; reading that tool reports why it is missing. */
+        readonly name: Schema.String;
+        /** The HTTP method, such as `GET`. */
+        readonly method: Schema.String;
+        /** The path as the definition declares it. */
+        readonly path: Schema.String;
+        readonly code: Schema.Literals<readonly ["server_protocol", "server_url", "external_reference", "circular_reference", "schema_keyword", "schema_reference", "missing_component", "openapi_version", "auth_helper", "auth_missing", "operation_path", "operation_method", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "event_stream", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
+        readonly reason: Schema.String;
+    }>>>;
+    readonly origins: Schema.optionalKey<Schema.$Array<Schema.String>>;
 }>, import("effect/Cause").YieldableError>;
-/** A safe generation failure, translated into product HTTP errors at the boundary. */
+/**
+ * A safe generation failure. `reason` explains the cause; `skipped` lists the declared operations
+ * it left out and why, and `origins` the origins operations resolve to when none of them matches
+ * the allowed origin. Reading one left-out tool fails with this error for that operation alone.
+ */
 export declare class OpenapiCompileError extends OpenapiCompileError_base {
+    get message(): string;
 }
 export {};

package/types/apps/src/contracts/openapi.d.ts

@@ -20,7 +20,8 @@ export type OpenapiErrorResponse = typeof OpenapiErrorResponse.Type;
 /** Resolved OpenAPI parameter shared by import validation and request construction. */
 export declare const OpenapiParameter: Schema.Struct<{
     readonly name: Schema.String;
-    readonly in: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+    /** OpenAPI 3.2's `querystring` is the whole query string, serialized from one `content` value. */
+    readonly in: Schema.Literals<readonly ["path", "query", "querystring", "header", "cookie"]>;
     readonly required: Schema.optionalKey<Schema.Boolean>;
     readonly schema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
     readonly style: Schema.optionalKey<Schema.String>;
@@ -45,7 +46,7 @@ export declare const OpenapiOperation: Schema.Struct<{
     /** The document's operationId, when it declares one. `kinds` overrides are keyed by it. */
     readonly operationId: Schema.optionalKey<Schema.String>;
     readonly description: Schema.String;
-    readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]>;
+    readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "QUERY"]>;
     readonly path: Schema.String;
     readonly baseUrl: Schema.String;
     readonly openapi: Schema.String;
@@ -54,7 +55,8 @@ export declare const OpenapiOperation: Schema.Struct<{
     readonly request: Schema.Struct<{
         readonly parameters: Schema.$Array<Schema.Struct<{
             readonly name: Schema.String;
-            readonly in: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+            /** OpenAPI 3.2's `querystring` is the whole query string, serialized from one `content` value. */
+            readonly in: Schema.Literals<readonly ["path", "query", "querystring", "header", "cookie"]>;
             readonly required: Schema.optionalKey<Schema.Boolean>;
             readonly schema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
             readonly style: Schema.optionalKey<Schema.String>;
@@ -92,6 +94,8 @@ export declare const OpenapiOperation: Schema.Struct<{
     }>>>;
 }>;
 export type OpenapiOperation = typeof OpenapiOperation.Type;
+/** Safe methods, whose operations are queries unless `kinds` says otherwise. QUERY is OpenAPI 3.2's. */
+export declare const isOpenapiReadMethod: (method: OpenapiOperation["method"]) => method is "GET" | "HEAD" | "OPTIONS" | "QUERY";
 /** Map a selected account field to one Swagger credential value. */
 export declare const CredentialBinding: Schema.Struct<{
     readonly scheme: Schema.String;
@@ -125,7 +129,7 @@ export declare const OpenapiToolsOptions: Schema.Struct<{
         /** The document's operationId, when it declares one. `kinds` overrides are keyed by it. */
         readonly operationId: Schema.optionalKey<Schema.String>;
         readonly description: Schema.String;
-        readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]>;
+        readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "QUERY"]>;
         readonly path: Schema.String;
         readonly baseUrl: Schema.String;
         readonly openapi: Schema.String;
@@ -134,7 +138,8 @@ export declare const OpenapiToolsOptions: Schema.Struct<{
         readonly request: Schema.Struct<{
             readonly parameters: Schema.$Array<Schema.Struct<{
                 readonly name: Schema.String;
-                readonly in: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+                /** OpenAPI 3.2's `querystring` is the whole query string, serialized from one `content` value. */
+                readonly in: Schema.Literals<readonly ["path", "query", "querystring", "header", "cookie"]>;
                 readonly required: Schema.optionalKey<Schema.Boolean>;
                 readonly schema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
                 readonly style: Schema.optionalKey<Schema.String>;
@@ -223,7 +228,12 @@ export declare const defaultOpenapiResponseLimits: {
     readonly maxBodyBytes: 16777216;
     readonly readTimeoutMs: 30000;
 };
-/** Media returned as text rather than a base64 file. NDJSON remains an unparsed text result. */
+/**
+ * A sequence of JSON values, one per line or record: NDJSON, JSON Lines and `json-seq`, whose
+ * items OpenAPI 3.2 describes with `itemSchema`. The body is not one JSON value.
+ */
+export declare const isOpenapiJsonSequence: (type: string) => boolean;
+/** Media returned as text rather than a base64 file. JSON sequences remain unparsed text. */
 export declare const isOpenapiTextMedia: (type: string) => boolean;
 /** A form field that carries raw file bytes: OpenAPI 3.1 `contentMediaType` without an
  * encoding, or the `format: binary` string that 3.1 documents still commonly use. */

package/types/apps/src/implementation/openapi-compile.d.ts

@@ -11,6 +11,8 @@ import { type GeneratedOperation, type GeneratedSecrets } from "../contracts/ope
 export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocument: JsonObject, options?: {
     readonly baseUrl?: string;
     readonly allowedOrigin?: string;
+    /** Inserted between every operation's server and path; see `prefixParameters`. */
+    readonly pathPrefix?: string;
     readonly securitySchemes?: Readonly<Record<string, JsonObject>>;
     readonly fallbackSecurity?: GeneratedOperation["request"]["security"];
 }) => Effect.Effect<{
@@ -19,7 +21,7 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
         readonly request: {
             readonly parameters: readonly {
                 readonly name: string;
-                readonly in: "query" | "path" | "header" | "cookie";
+                readonly in: "query" | "path" | "querystring" | "header" | "cookie";
                 readonly required?: boolean;
                 readonly schema?: {
                     readonly [x: string]: Schema.Json;
@@ -59,7 +61,7 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
         readonly input: {
             readonly [x: string]: Schema.Json;
         };
-        readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+        readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "QUERY";
         readonly securitySchemes: {
             readonly [x: string]: {
                 readonly [x: string]: Schema.Json;
@@ -87,6 +89,14 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
             };
         }[];
     }[];
+    /** Declared operations left out of `operations`, in definition order. */
+    skipped: {
+        readonly name: string;
+        readonly method: string;
+        readonly path: string;
+        readonly code: "server_protocol" | "server_url" | "external_reference" | "circular_reference" | "schema_keyword" | "schema_reference" | "missing_component" | "openapi_version" | "auth_helper" | "auth_missing" | "operation_path" | "operation_method" | "duplicate_operation" | "server_missing" | "multiple_hosts" | "parameter_encoding" | "parameter_style" | "request_body" | "combined_oauth" | "auth_method" | "event_stream" | "input_schema" | "no_operations" | "no_supported_operations" | "invalid_document" | "source_generation" | "authoring_reference";
+        readonly reason: string;
+    }[];
     definitions: {
         [k: string]: {
             readonly [x: string]: Schema.Json;

package/types/apps/src/implementation/openapi-document.d.ts

@@ -13,10 +13,18 @@ export declare const DocumentObject: Schema.declare<{
 export declare const documentObject: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
     readonly [x: string]: Schema.Json;
 };
+/** One JSON Pointer reference token. */
+export declare const pointerToken: (key: string) => string;
+/**
+ * Decode one part of the definition, located by the JSON Pointer `at`. A mismatch names the
+ * pointer of the first failing value and what was expected there.
+ */
+export declare const decodeDefinition: <S extends Schema.Decoder<unknown>>(schema: S, value: unknown, at: string, what: string) => S["Type"];
 /** Resolve OpenAPI objects once; schemas retain their original recursive references.
- * Scalar first upgrades Swagger 2.0 and OpenAPI 3.0 to 3.1, so the importer has one dialect and
- * 3.1 keywords that appear in 3.0 documents keep their meaning.
- * Unsupported versions, references and conversions throw TemplateError at the import boundary.
+ * Scalar first upgrades Swagger 2.0 and OpenAPI 3.0 to 3.1, so the importer reads 3.1 and 3.2,
+ * whose Schema Objects share one dialect, and 3.1 keywords that appear in 3.0 documents keep
+ * their meaning. Unsupported versions, references and conversions throw TemplateError at the
+ * import boundary.
  */
 export declare function openApiDocument(input: JsonObject): Promise<{
     spec: {
@@ -51,14 +59,20 @@ export declare function openApiDocument(input: JsonObject): Promise<{
     definitions: Map<string, {
         readonly [x: string]: Schema.Json;
     }>;
+    /**
+     * The JSON Pointer of the object a local reference resolved to, so a diagnostic can locate
+     * a resolved Response, Parameter, Request Body or Path Item where the definition declares it.
+     */
+    origin(value: unknown): string | undefined;
     /** Inspect a component schema without expanding its children. OpenAPI object refs must already be resolved by Swagger. */
     resolve(value: JsonObject): JsonObject;
     /** Compose a Draft 2020-12 schema around API Schema Objects. Only values passed to
      * `api` use the document's OpenAPI dialect; Executor-authored wrappers are already
-     * Draft 2020-12 and must not be reinterpreted. Reached components are converted once into
-     * the shared `definitions` and stay references here; nothing is inlined or copied per operation.
+     * Draft 2020-12 and must not be reinterpreted. `api` takes the schema's JSON Pointer in the
+     * definition, which failures name. Reached components are converted once into the shared
+     * `definitions` and stay references here; nothing is inlined or copied per operation.
      */
-    schema(build: (api: (input: Schema.Json) => JsonObject) => JsonObject): JsonObject;
+    schema(build: (api: (input: Schema.Json, at: string) => JsonObject) => JsonObject): JsonObject;
 }>;
 /** A parsed document with one reference scope and one schema dialect. */
 export type OpenApiDocument = Awaited<ReturnType<typeof openApiDocument>>;

package/types/apps/src/implementation/openapi-names.d.ts

@@ -11,8 +11,13 @@ export interface OperationNameInput {
     readonly path: string;
 }
 /**
- * Plan one name per input, in input order. Names that collide are refined together: first by
- * the path's version segment, then by the HTTP method, then by a stable hash. Refinement only
- * touches the colliding names, so adding an operation never renames an unrelated one.
+ * Name every input, in input order. Names that collide, whether or not they come from an
+ * operationId, are refined together: first by the path's version segment, then by the path
+ * segments that tell them apart (`GET /items` and `GET /items/{id}` are `items.getItems` and
+ * `items.getItemsById`), then by the whole path, then by the HTTP method, then by a stable hash.
+ * Refinement only touches the colliding names, so adding an operation never renames an unrelated
+ * one.
  */
-export declare const planOperationNames: (inputs: readonly OperationNameInput[]) => string[];
+export declare const planOperationNames: <I extends OperationNameInput>(inputs: readonly I[]) => (I & {
+    readonly name: string;
+})[];

package/types/apps/src/implementation/openapi-source.d.ts

@@ -16,6 +16,12 @@ export interface OpenapiSourceOptions extends Omit<OpenapiToolsOptions, "operati
     readonly allowedOrigin: string;
     readonly securitySchemes: Readonly<Record<string, JsonObject>>;
     readonly baseUrl?: string;
+    /**
+     * A path inserted between the server and every operation's path, for a definition that omits a
+     * leading segment, such as `/projects/{project}`. Each `{name}` becomes a required string path
+     * parameter of every tool, unless the operation already declares it without placing it.
+     */
+    readonly pathPrefix?: string;
     readonly freshFor?: Duration.Input;
     readonly staleFor?: Duration.Input;
     /**