apps 0.0.1-beta.13 → 0.0.1-beta.15

package/types/apps/src/contracts/protocols/oauth.d.ts

@@ -0,0 +1,89 @@
+/** OAuth declarations frozen for host protocols 1 through 5. */
+import { Schema } from "effect";
+/** How an OAuth client authenticates at the token endpoint; raw Basic is an explicit provider compatibility option. */
+export declare const OAuthClientAuth: Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+export type OAuthClientAuth = typeof OAuthClientAuth.Type;
+/** Machine clients always authenticate; public clients cannot use the client-credentials grant. */
+export declare const OAuthSecretClientAuth: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+/** Parameters the host sets on every authorization request; a declaration cannot replace them. */
+export declare const reservedAuthorizationParams: readonly ["response_type", "client_id", "redirect_uri", "state", "scope", "code_challenge", "code_challenge_method", "nonce", "resource", "request", "request_uri"];
+/** A protocol parameter only the host sets on the authorization request. */
+export type ReservedAuthorizationParam = (typeof reservedAuthorizationParams)[number];
+/**
+ * Extra authorization request parameters, such as `access_type: "offline"`. RFC 6749 §3.1
+ * lets services define their own; the protocol and security parameters stay host-owned.
+ */
+export declare const OAuthAuthorizationParams: Schema.$Record<Schema.String, Schema.String>;
+/** How the token endpoint reads requests. RFC 6749 uses a form; some services want JSON. */
+export declare const OAuthTokenRequestFormat: Schema.Literals<readonly ["form", "json"]>;
+export type OAuthTokenRequestFormat = typeof OAuthTokenRequestFormat.Type;
+/**
+ * Where a service nests the grant in its token response, as a dot-separated member path. Slack
+ * returns a user token under `authed_user`.
+ */
+export declare const OAuthTokenResponse: Schema.Struct<{
+    readonly path: Schema.String;
+}>;
+export type OAuthTokenResponse = typeof OAuthTokenResponse.Type;
+/**
+ * OAuth endpoints and protocol choices. Omitted grant means authorization code; clients remain
+ * host-owned. Declared endpoints may name an RFC 7009 `revocationUrl`; discovery reads the
+ * server's `revocation_endpoint` metadata instead.
+ */
+export declare const OAuth2Config: Schema.Union<readonly [Schema.Struct<{
+    readonly discover: Schema.String;
+    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+    readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+    readonly revocationUrl: Schema.optionalKey<Schema.Never>;
+    readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly tokenResponse: Schema.optionalKey<Schema.Struct<{
+        readonly path: Schema.String;
+    }>>;
+    readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+    readonly authorizationParams: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
+}>, Schema.Struct<{
+    /** Its query is kept; it cannot set protocol parameters or repeat `authorizationParams`. */
+    readonly authorizationUrl: Schema.String;
+    readonly tokenUrl: Schema.String;
+    readonly revocationUrl: Schema.optionalKey<Schema.String>;
+    readonly scopes: Schema.$Array<Schema.String>;
+    /** RFC 8414 issuer identifier. Declared issuers are checked against the callback's `iss`. */
+    readonly issuer: Schema.optionalKey<Schema.String>;
+    readonly discover: Schema.optionalKey<Schema.Never>;
+    readonly tokenResponse: Schema.optionalKey<Schema.Struct<{
+        readonly path: Schema.String;
+    }>>;
+    readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+    readonly authorizationParams: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
+}>, Schema.Struct<{
+    readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
+    readonly grant: Schema.Literal<"client_credentials">;
+    readonly discover: Schema.String;
+    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+    readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+    readonly revocationUrl: Schema.optionalKey<Schema.Never>;
+    readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+}>, Schema.Struct<{
+    readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+    readonly discover: Schema.optionalKey<Schema.Never>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
+    readonly grant: Schema.Literal<"client_credentials">;
+    readonly tokenUrl: Schema.String;
+    readonly revocationUrl: Schema.optionalKey<Schema.String>;
+    readonly scopes: Schema.$Array<Schema.String>;
+}>]>;
+export type OAuth2Config = typeof OAuth2Config.Type;

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

@@ -42,6 +42,8 @@ export type OAuthTokenResponse = typeof OAuthTokenResponse.Type;
  */
 export declare const OAuth2Config: Schema.Union<readonly [Schema.Struct<{
     readonly discover: Schema.String;
+    /** Fetch this exact metadata document and verify its issuer against discovery. */
+    readonly authorizationServerMetadataUrl: Schema.optionalKey<Schema.String>;
     readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
     readonly tokenUrl: Schema.optionalKey<Schema.Never>;
     readonly revocationUrl: Schema.optionalKey<Schema.Never>;
@@ -64,6 +66,7 @@ export declare const OAuth2Config: Schema.Union<readonly [Schema.Struct<{
     /** RFC 8414 issuer identifier. Declared issuers are checked against the callback's `iss`. */
     readonly issuer: Schema.optionalKey<Schema.String>;
     readonly discover: Schema.optionalKey<Schema.Never>;
+    readonly authorizationServerMetadataUrl: Schema.optionalKey<Schema.Never>;
     readonly tokenResponse: Schema.optionalKey<Schema.Struct<{
         readonly path: Schema.String;
     }>>;
@@ -80,6 +83,8 @@ export declare const OAuth2Config: Schema.Union<readonly [Schema.Struct<{
     readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
     readonly grant: Schema.Literal<"client_credentials">;
     readonly discover: Schema.String;
+    /** Fetch this exact metadata document and verify its issuer against discovery. */
+    readonly authorizationServerMetadataUrl: Schema.optionalKey<Schema.String>;
     readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
     readonly tokenUrl: Schema.optionalKey<Schema.Never>;
     readonly revocationUrl: Schema.optionalKey<Schema.Never>;
@@ -89,6 +94,7 @@ export declare const OAuth2Config: Schema.Union<readonly [Schema.Struct<{
     readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
     readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
     readonly discover: Schema.optionalKey<Schema.Never>;
+    readonly authorizationServerMetadataUrl: Schema.optionalKey<Schema.Never>;
     readonly scopeSeparator: Schema.optionalKey<Schema.String>;
     readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
     readonly grant: Schema.Literal<"client_credentials">;

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

@@ -4,8 +4,11 @@ import { JsonObject } from "../contracts/schema.js";
 import { OpenapiCompileError as TemplateError } from "../contracts/openapi-compile.js";
 import type { OpenApiImport } from "../contracts/openapi-document.js";
 import { type GeneratedOperation, type GeneratedSecrets } from "../contracts/openapi-document.js";
-/** Compile a revision of a live OpenAPI source into tool declarations for the app runtime. */
-export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocument: unknown, options?: {
+/** Compile a revision of a live OpenAPI source into tool declarations for the app runtime.
+ * The document is consumed: compilation upgrades it in place instead of copying it. It must be a
+ * tree, with no object reached twice, as parsed JSON is.
+ */
+export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocument: JsonObject, options?: {
     readonly baseUrl?: string;
     readonly allowedOrigin?: string;
     readonly securitySchemes?: Readonly<Record<string, JsonObject>>;

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

@@ -1,11 +1,24 @@
 import { Schema } from "effect";
 import { JsonObject } from "../contracts/schema.js";
-/** Resolve OpenAPI objects once with Swagger; schemas retain their original recursive references.
+/**
+ * An object in a document that was validated as JSON when it was read. Compilation only turns JSON
+ * into JSON, so inside it an object's shape is checked, not its every leaf again: re-validating
+ * whole documents was most of a large API's compile time.
+ */
+export declare const DocumentObject: Schema.declare<{
+    readonly [x: string]: Schema.Json;
+}, {
+    readonly [x: string]: Schema.Json;
+}>;
+export declare const documentObject: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
+    readonly [x: string]: Schema.Json;
+};
+/** 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.
  */
-export declare function openApiDocument(input: unknown): Promise<{
+export declare function openApiDocument(input: JsonObject): Promise<{
     spec: {
         readonly openapi: string;
         readonly paths: {

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

@@ -6,12 +6,19 @@ import { OpenapiError, type CredentialBinding, type OpenapiOperation, type Opena
 type DeclaredError = OpenapiErrorResponse & {
     readonly decoder: Schema.Decoder<Schema.Json>;
 };
+/** What decides whether an account can call an operation: its transport and security. */
+export interface OpenapiOperationAccess {
+    readonly streaming?: true;
+    readonly request: {
+        readonly security: OpenapiOperation["request"]["security"];
+    };
+}
 /** Create request helpers from credential-free generated authentication metadata. */
 export declare function createRequest(config: {
     readonly methods: Readonly<Record<string, readonly CredentialBinding[]>>;
     readonly oauth: readonly string[];
 }): {
-    available: (op: OpenapiOperation, account: OpenapiAccount | undefined) => boolean;
+    available: (op: OpenapiOperationAccess, account: OpenapiAccount | undefined) => boolean;
     call: (op: OpenapiOperation, input: unknown, account: OpenapiAccount | undefined, errors: readonly DeclaredError[]) => Effect.Effect<Schema.Json, ProviderError | OpenapiResponseError | OpenapiError, never>;
 };
 export {};

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

@@ -0,0 +1,4 @@
+type Node = Record<string, unknown>;
+/** Upgrade a 3.0 document the caller owns. Any other version is returned unchanged. */
+export declare const upgradeOpenApi30InPlace: (document: Node) => Node;
+export {};

package/types/apps/src/implementation/runtime-yield.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Let the runtime run its own tasks between long synchronous steps. In a Worker, a large OpenAPI
+ * compilation that never yields leaves the garbage collector only long, full pauses; yielding
+ * between steps measurably shortens it. A timer is used because a resolved promise would continue
+ * without leaving the current task.
+ */
+export declare const yieldToRuntime: () => Promise<void>;