apps 0.0.1-beta.67 → 0.0.1-beta.69

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

@@ -1,5 +1,6 @@
 /** Provider declarations use native Effect schemas. The trusted host interprets them. */
 import { Data, type Effect, Schema } from "effect";
+import type { Placement } from "./placement.js";
 import { type AccountId } from "./schema.js";
 /**
  * How app code sees a field of a provider that declares hosts. Unmarked string fields are secret:
@@ -16,6 +17,8 @@ export declare class SecretsMethod<Fields extends Schema.Decoder<unknown>> exten
     readonly fields: Fields;
     /** Fields marked with `plain()` or `raw()`. */
     readonly exposure?: Readonly<Record<string, FieldExposure>>;
+    /** The only places the outbound network sends this method's secret fields; see `Placement`. */
+    readonly request?: readonly Placement[];
 }> {
 }
 /** How an OAuth client authenticates at the token endpoint; raw Basic is an explicit provider compatibility option. */
@@ -124,6 +127,8 @@ export declare class OAuth2Method<Response extends Schema.Decoder<unknown>> exte
     readonly response: Response;
     /** Response fields marked with `plain()` or `raw()`. */
     readonly exposure?: Readonly<Record<string, FieldExposure>>;
+    /** The only places the outbound network sends this method's secret fields; see `Placement`. */
+    readonly request?: readonly Placement[];
 }> {
 }
 /** Supported declarations; these acquire credentials rather than normalize them. */
@@ -205,12 +210,32 @@ export declare class ManyAccounts<Auth extends AuthMethods> extends ManyAccounts
 }
 /** Infer the data for one method from its native Effect decoder. */
 export type AuthMethodData<Method> = Method extends SecretsMethod<infer Fields> ? Fields["Type"] : Method extends OAuth2Method<infer Response> ? Response["Type"] : never;
+/**
+ * Render an account's credential placements. Each renders the method's `request` with the fields
+ * app code holds, so a request built with them is one the outbound network accepts.
+ */
+export interface AccountRequest {
+    /**
+     * The headers the method's `request` places credentials in, by lowercase name. Spread them into
+     * a request's headers. Throws when the method declares no `request`.
+     */
+    headers(): Record<string, string>;
+    /**
+     * `input` with the query parameters the method's `request` places credentials in, replacing any
+     * of the same name. Throws when the method declares no `request`.
+     */
+    url(input: string | URL): string;
+}
 /** One account for these methods, discriminated by its author-chosen method name. */
 export type AccountOfMethods<Auth extends AuthMethods> = {
     readonly [Method in keyof Auth & string]: {
         readonly id: AccountId;
         readonly method: Method;
         readonly fields: AuthMethodData<Auth[Method]>;
+        /** See `AccountRequest`. */
+        readonly headers: AccountRequest["headers"];
+        /** See `AccountRequest`. */
+        readonly url: AccountRequest["url"];
     };
 }[keyof Auth & string];
 /** One selected account, discriminated by its author-chosen method name. */

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

@@ -56,3 +56,8 @@ export interface AppSqlStorage {
 export declare const reservedTablePrefix = "_executor_";
 /** Where an app keeps its migrations: `0001_create_notes.sql`, applied in number order. */
 export declare const migrationsDirectory = "migrations";
+/**
+ * The most values one statement may bind. Durable Object SQLite sets `SQLITE_LIMIT_VARIABLE_NUMBER`
+ * to 100 on every host; `ctx.sql` checks it first so the error names the limit.
+ */
+export declare const sqlBindingsLimit = 100;

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

@@ -24,11 +24,13 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
     readonly fallbackSecurity?: GeneratedOperation["request"]["security"];
 }) => Effect.Effect<{
     operations: {
+        readonly method: "HEAD" | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "QUERY";
         readonly description: string;
+        readonly name: string;
         readonly request: {
             readonly parameters: readonly {
+                readonly in: "header" | "query" | "path" | "querystring" | "cookie";
                 readonly name: string;
-                readonly in: "path" | "query" | "querystring" | "header" | "cookie";
                 readonly required?: boolean;
                 readonly schema?: {
                     readonly [x: string]: Schema.Json;
@@ -64,11 +66,9 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
             };
         };
         readonly path: string;
-        readonly name: string;
         readonly input: {
             readonly [x: string]: Schema.Json;
         };
-        readonly method: "HEAD" | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "QUERY";
         readonly securitySchemes: {
             readonly [x: string]: {
                 readonly [x: string]: Schema.Json;

package/types/apps/src/implementation/placement.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Authoring credential placements. A method's `request` callback runs once, when the provider is
+ * declared, with an opaque reference for each of the method's fields. It returns placements built
+ * from `header` or `query` and a value from `t`, `base64` and references; the result is stored
+ * as data. A reference is not a string: an untagged template literal fails when it is evaluated.
+ */
+import { Placement, type PlacementPart } from "../contracts/placement.js";
+import type { AccountRequest, FieldExposure } from "../contracts/provider.js";
+/** Throw when JavaScript turns a placement into a string, so untagged templates fail. */
+declare class NotAString {
+    #private;
+    constructor(described: string);
+    [Symbol.toPrimitive](): never;
+    toString(): never;
+    toJSON(): never;
+}
+/** A reference to one of the method's account fields, given to its `request` callback. */
+export declare class FieldRef<Name extends string = string> extends NotAString {
+    readonly field: Name;
+    constructor(field: Name);
+}
+/** A value template built with `t` or `base64`. */
+export declare class PlacementValue extends NotAString {
+    readonly parts: readonly PlacementPart[];
+    constructor(parts: readonly PlacementPart[]);
+}
+/** What a template may interpolate: literal text, a field reference or another value. */
+export type PlacementInput = string | FieldRef | PlacementValue;
+/** A value template: literal text with interpolated field references and values. */
+export declare const t: (strings: TemplateStringsArray, ...values: readonly PlacementInput[]) => PlacementValue;
+/** Base64 of a value's UTF-8 bytes, such as the `user:password` of Basic credentials. */
+export declare const base64: (value: PlacementInput) => PlacementValue;
+/** Send a value as the whole value of this header. The name is case-insensitive. */
+export declare const header: (name: string, input: PlacementInput) => Placement;
+/** Send a value as the whole value of this query parameter. */
+export declare const query: (name: string, input: unknown) => Placement;
+/** `Authorization: Bearer <token>`. */
+export declare const bearer: (token: FieldRef) => Placement;
+/** `Authorization: Basic base64(<user>:<password>)`. */
+export declare const basic: (user: PlacementInput, password: PlacementInput) => Placement;
+/** The field references a `request` callback receives, by field name. */
+export type FieldRefs<Name extends string> = {
+    readonly [Key in Name]: FieldRef<Key>;
+};
+/** How a method declares its placements: called once with its field references. */
+export type RequestPlacements<Name extends string> = (fields: FieldRefs<Name>) => Placement | readonly Placement[];
+/**
+ * Run a method's `request` callback once and check its placements. Every reference names one of
+ * the method's fields, no `raw()` field appears, and each placement references a secret field.
+ */
+export declare const declarePlacements: (method: string, names: readonly string[], exposure: Readonly<Record<string, FieldExposure>> | undefined, request: RequestPlacements<string>) => readonly Placement[];
+/**
+ * Give a bound account `headers()` and `url()`, rendering the placements the host granted with the
+ * fields app code holds. They are not enumerable, so the account's JSON is unchanged.
+ */
+export declare const withPlacements: <Account extends {
+    readonly method: string;
+    readonly fields: unknown;
+}>(account: Account, placements: readonly Placement[] | undefined) => Account & AccountRequest;
+export {};

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

@@ -2,15 +2,17 @@
 import { Effect, Schema } from "effect";
 import { type PromiseMethod } from "./authoring.js";
 import { type AccountCheck, type AuthMethods, type FieldExposure, OAuth2Config, OAuth2Method, Provider, SecretsMethod } from "../contracts/provider.js";
+import type { Placement } from "../contracts/placement.js";
 import type { ValidationError } from "../contracts/schema.js";
 /** Declare a secrets method with an Effect decoder. */
 export declare const secrets: <Fields extends Schema.Decoder<unknown>>(options: {
     readonly label: string;
     readonly fields: Fields;
     readonly exposure?: Readonly<Record<string, FieldExposure>>;
+    readonly request?: readonly Placement[];
 }) => SecretsMethod<Fields>;
 /** Validate OAuth endpoints while declaring their app-visible response projection. */
-export declare const oauth2: <Response extends Schema.Decoder<unknown>>(config: OAuth2Config, response: Response, exposure?: Readonly<Record<string, FieldExposure>>) => Effect.Effect<OAuth2Method<Response>, ValidationError>;
+export declare const oauth2: <Response extends Schema.Decoder<unknown>>(config: OAuth2Config, response: Response, exposure?: Readonly<Record<string, FieldExposure>>, request?: readonly Placement[]) => Effect.Effect<OAuth2Method<Response>, ValidationError>;
 /** Author options: the account check is an ordinary async function. */
 export interface ProviderOptions<Auth extends AuthMethods> {
     readonly name: string;
@@ -26,5 +28,9 @@ export interface ProviderOptions<Auth extends AuthMethods> {
     /** Verify a connected account with a safe read, optionally reporting its upstream identity. */
     readonly health?: PromiseMethod<AccountCheck<Auth>["run"]>;
 }
-/** Retain the provider and literal method names without registering or authenticating it. */
+/**
+ * Retain the provider and literal method names without registering or authenticating it. A
+ * method's `request` restricts where its credentials go only among the provider's `hosts`, so a
+ * provider that declares a `request` declares `hosts` too.
+ */
 export declare const defineProvider: <const Auth extends AuthMethods>({ health, ...options }: ProviderOptions<Auth>) => Provider<Auth>;

package/types/apps/src/index.d.ts

@@ -12,11 +12,18 @@ import { type JsonResponse as NativeResponse } from "./contracts/http.js";
 import { type OAuth2Config as NativeOAuth2Config, type OAuth2Method as NativeOAuth2Method, type ReservedAuthorizationParam, type SecretsMethod as NativeSecretsMethod } from "./contracts/provider.js";
 import type { Webhook as NativeWebhook } from "./contracts/webhooks.js";
 import { type PromiseMethods } from "./implementation/authoring.js";
+import { type PlacementInput, type RequestPlacements } from "./implementation/placement.js";
+import type { Placement } from "./contracts/placement.js";
+import type { AppContext as NativeAppContext, QueryContext as NativeQueryContext } from "./contracts/context.js";
+import { query as operationQuery, type OperationOptions } from "./implementation/operations.js";
 import { type Fields, type Infer, type ObjectSchema, type Schema, type SecretFields, type SecretObject } from "./implementation/schema.js";
 export { type JsonObject, type JsonValue, ValidationError } from "./contracts/schema.js";
 export { type Fields, type Infer, type ObjectSchema, type ObjectValue, type Schema, array, boolean, json, jsonSchema, literal, number, object, record, string, plain, raw, type SecretString, } from "./implementation/schema.js";
 export { type AccountCheckContext, type AccountCheckResult, type AccountInfo, type AccountOf, type AuthMethod, type AuthMethodData, type AuthMethods, type ManyAccounts, type Provider, type ReservedAuthorizationParam, } from "./contracts/provider.js";
 export { defineProvider, type ProviderOptions } from "./implementation/provider.js";
+export { base64, basic, bearer, header, t, type FieldRef, type FieldRefs, type PlacementInput, type PlacementValue, type RequestPlacements, } from "./implementation/placement.js";
+export type { Placement };
+export type { AccountRequest } from "./contracts/provider.js";
 export { accountRouter } from "./implementation/account-router.js";
 export { router, dynamicRouter, withApprovals, type OperationChild, type OperationDeclaration, type RouterDeclaration, type RouterChild, type RouterOptions, } from "./implementation/router.js";
 export type { RouterIcon } from "./contracts/router.js";
@@ -28,6 +35,8 @@ type AccountFields<S> = S extends ObjectSchema<infer F> ? SecretFields<F> : Secr
 export type SecretsMethod<Shape extends ObjectSchema<Fields>> = NativeSecretsMethod<EffectSchema.Decoder<AccountFields<Shape>>>;
 /** An OAuth declaration inferred from its author-facing response schema. */
 export type OAuth2Method<Response extends Schema<unknown, boolean>> = NativeOAuth2Method<EffectSchema.Decoder<AccountFields<Response>>>;
+/** The names of an object schema's fields, which a method's `request` can reference. */
+type FieldNameOf<S> = S extends ObjectSchema<infer F> ? keyof F & string : never;
 /** Default OAuth fields visible to app code. Host-only grants and clients stay private. */
 export declare const OAuth2AccessToken: Schema<{
     readonly access_token: string;
@@ -42,19 +51,28 @@ type WithoutReservedParams<Config> = Config extends unknown ? "authorizationPara
         readonly [Key in ReservedAuthorizationParam]?: never;
     };
 } : Config : never;
-/** Declare a secrets method without requiring an Effect schema from the author. */
+/**
+ * Declare a secrets method without requiring an Effect schema from the author. `request` says
+ * where its secret fields may be sent, such as `({ token }) => bearer(token)`; it runs once, here.
+ */
 export declare const secrets: <const F extends Fields>(options: {
     readonly label: string;
     readonly fields: ObjectSchema<F>;
+    readonly request?: RequestPlacements<keyof F & string>;
 }) => SecretsMethod<ObjectSchema<F>>;
 /**
  * Declare OAuth discovery/endpoints and an optional app-visible response projection.
  * `authorizationParams` adds service-defined sign-in parameters; a declared `authorizationUrl`
  * keeps its own query. Neither can set host-owned parameters, and each parameter appears once.
+ * `request` says where the projected secret fields may be sent, such as
+ * `({ access_token }) => bearer(access_token)`; it runs once, here.
  */
-export declare function oauth2(options: OAuth2Config): OAuth2Method<typeof OAuth2AccessToken>;
+export declare function oauth2(options: OAuth2Config & {
+    readonly request?: RequestPlacements<"access_token">;
+}): OAuth2Method<typeof OAuth2AccessToken>;
 export declare function oauth2<Response extends Schema<unknown, boolean>>(options: OAuth2Config & {
     readonly response: Response;
+    readonly request?: RequestPlacements<FieldNameOf<Response>>;
 }): OAuth2Method<Response>;
 export type { AccountSlots } from "./contracts/app.js";
 export type { AppRequirements, AppContext, QueryContext, MutationContext, WebhookContext, } from "./contracts/context.js";
@@ -76,7 +94,13 @@ export declare const decodeJson: <T>(response: JsonResponse, schema: Schema<T, b
 export { NotImplemented } from "./contracts/app.js";
 export { ElicitationFailed, type FormElicitation, type ElicitationResponse, type Elicit, } from "./contracts/elicitation.js";
 export type { Sql, SqlCursor, SqlReader, SqlRow, SqlTransaction, SqlValue, } from "./contracts/sql.js";
-export { query, mutation, withApproval, toolAnnotations, type Operation, type OperationOptions, } from "./implementation/operations.js";
+/**
+ * `query(options, run)` declares a read operation. `query(name, value)` inside a method's
+ * `request` places a credential in a query parameter, such as `query("key", key)`.
+ */
+export declare function query(name: string, value: PlacementInput): Placement;
+export declare function query<Input, Output, Context extends NativeAppContext = NativeQueryContext>(options: OperationOptions<Input, Output>, run: (context: Context, input: Input) => Promise<Output>): ReturnType<typeof operationQuery<Input, Output, Context>>;
+export { mutation, withApproval, toolAnnotations, type Operation, type OperationOptions, } from "./implementation/operations.js";
 export type { OperationContext } from "./contracts/operations.js";
 export { workflow, type Workflow, type WorkflowDeclaration } from "./implementation/workflows.js";
 export { NonRetryableError, WorkflowFailure, type WorkflowContext, type WorkflowStepContext, type WorkflowStep, type WorkflowStepOptions, type WorkflowDuration, type WorkflowReads, type WorkflowControls, } from "./contracts/workflows.js";