apps 0.0.1-beta.15 → 0.0.1-beta.17

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

@@ -1,6 +1,12 @@
 /** Provider declarations use native Effect schemas. The trusted host interprets them. */
 import { Data, type Effect, Schema } from "effect";
 import { type AccountId } from "./schema.js";
+/**
+ * How app code sees a field of a provider that declares hosts. Unmarked string fields are secret:
+ * app code receives sealed handles that only the host's outbound network turns into values.
+ * `plain` fields are not secret. `raw` fields are secret, but app code reads the real value.
+ */
+export type FieldExposure = "plain" | "raw";
 declare const SecretsMethod_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Readonly<A> & {
     readonly _tag: "secrets";
 } & import("effect/Pipeable").Pipeable;
@@ -8,6 +14,8 @@ declare const SecretsMethod_base: new <A extends Record<string, any> = {}>(args:
 export declare class SecretsMethod<Fields extends Schema.Decoder<unknown>> extends SecretsMethod_base<{
     readonly label: string;
     readonly fields: Fields;
+    /** Fields marked with `plain()` or `raw()`. */
+    readonly exposure?: Readonly<Record<string, FieldExposure>>;
 }> {
 }
 /** How an OAuth client authenticates at the token endpoint; raw Basic is an explicit provider compatibility option. */
@@ -114,6 +122,8 @@ declare const OAuth2Method_base: new <A extends Record<string, any> = {}>(args:
 export declare class OAuth2Method<Response extends Schema.Decoder<unknown>> extends OAuth2Method_base<{
     readonly config: OAuth2Config;
     readonly response: Response;
+    /** Response fields marked with `plain()` or `raw()`. */
+    readonly exposure?: Readonly<Record<string, FieldExposure>>;
 }> {
 }
 /** Supported declarations; these acquire credentials rather than normalize them. */
@@ -165,6 +175,11 @@ export interface AccountCheck<Auth extends AuthMethods> {
 export declare class Provider<Auth extends AuthMethods> extends Data.Class<{
     readonly name: string;
     readonly auth: Auth;
+    /**
+     * The hosts this provider's credentials may be sent to. When present, secret fields reach app
+     * code as handles that the outbound network replaces only on requests to these hosts.
+     */
+    readonly hosts?: readonly string[];
     /**
      * Stored without its method types so a specific provider still fills a general slot. The host
      * binds the account against this provider's methods before running it.

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

@@ -58,8 +58,8 @@ export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
                 } | {
                     readonly type: "string";
                     readonly default?: string;
-                    readonly format?: "email" | "uri" | "date" | "date-time";
                     readonly description?: string;
+                    readonly format?: "email" | "uri" | "date" | "date-time";
                     readonly title?: string;
                     readonly minLength?: number;
                     readonly maxLength?: number;

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

@@ -16,8 +16,6 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
 }) => Effect.Effect<{
     operations: {
         readonly name: string;
-        readonly path: string;
-        readonly description: string;
         readonly request: {
             readonly parameters: readonly {
                 readonly name: string;
@@ -56,6 +54,8 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
                 readonly required?: boolean;
             };
         };
+        readonly path: string;
+        readonly description: string;
         readonly input: {
             readonly [x: string]: Schema.Json;
         };

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

@@ -79,8 +79,18 @@ export declare const operationOptions: <Input, Output>(options: OperationOptions
     title?: string;
     description?: string;
 };
+/**
+ * Replace a native operation's approval. Property descriptors are copied so an output schema that
+ * a protocol adapter builds only when read stays lazy.
+ */
+export declare const approvedOperation: <Input, Native extends AppOperation<Input, unknown>>(operation: Native, approval: Approval<Input>) => Native;
 /** Attach the same approval function to a generated or shared operation. */
 export declare const withApproval: <Input, Output, Kind extends "query" | "mutation", Context>(operation: Operation<Input, Output, Kind, Context>, approval: Approval<Input>) => Operation<Input, Output, Kind, Context>;
+/**
+ * The advisory hints an operation carries, such as an MCP server's `destructiveHint`. App code
+ * reads them to choose an approval; the framework never infers one from them.
+ */
+export declare const toolAnnotations: (operation: OperationDeclaration<"query" | "mutation", never>) => ToolAnnotations | undefined;
 /** Read operation. External reads are allowed; only database writes are mechanically prohibited. */
 export declare const query: <Input, Output, Context extends AppContext = QueryContext>(options: OperationOptions<Input, Output>, run: (context: Context, input: Input) => Promise<Output>) => Operation<Input, Output, "query", Context>;
 /** Explicit write operation. Database writes roll back on failure; external effects cannot be undone. */

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

@@ -1,19 +1,28 @@
 /** Pure constructors over the native provider contracts. */
 import { Effect, Schema } from "effect";
 import { type PromiseMethod } from "./authoring.js";
-import { type AccountCheck, type AuthMethods, OAuth2Config, OAuth2Method, Provider, SecretsMethod } from "../contracts/provider.js";
+import { type AccountCheck, type AuthMethods, type FieldExposure, OAuth2Config, OAuth2Method, Provider, SecretsMethod } from "../contracts/provider.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>>;
 }) => 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) => Effect.Effect<OAuth2Method<Response>, ValidationError>;
+export declare const oauth2: <Response extends Schema.Decoder<unknown>>(config: OAuth2Config, response: Response, exposure?: Readonly<Record<string, FieldExposure>>) => Effect.Effect<OAuth2Method<Response>, ValidationError>;
 /** Author options: the account check is an ordinary async function. */
 export interface ProviderOptions<Auth extends AuthMethods> {
     readonly name: string;
     readonly auth: Auth;
+    /**
+     * Hosts the credentials may be sent to: `api.example.com`, `api.example.com:8443`, or
+     * `*.example.com` for one level of subdomain. Secret fields then reach app code as handles
+     * that the outbound network replaces only on requests to these hosts. An account records the
+     * hosts it was connected for; changing them does not change the provider, but an existing
+     * account sends only to hosts it was connected for until it is connected again.
+     */
+    readonly hosts?: readonly string[];
     /** Verify a connected account with a safe read, optionally reporting its upstream identity. */
     readonly health?: PromiseMethod<AccountCheck<Auth>["run"]>;
 }

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

@@ -1,6 +1,7 @@
 import { HostedTool } from "../contracts/host.js";
 import type { AppOperation } from "../contracts/operations.js";
 import { RouterMeta, type AppRouter, type DynamicRouter, type RouterIcon } from "../contracts/router.js";
+import type { Approval } from "../approval.js";
 import { type OperationDeclaration, type RouterChild, type RouterDeclaration } from "./operations.js";
 export type { RouterChild, RouterDeclaration } from "./operations.js";
 /** Author metadata for a router. Instructions become a skill named after the router's path. */
@@ -57,3 +58,11 @@ export declare const declaredOperations: (root: AppRouter | undefined, path?: st
     readonly router: string;
     readonly operation: AppOperation;
 }>;
+/**
+ * Choose an approval for each operation a router contains, including tools a dynamic router
+ * resolves later. `policy` receives the operation and its name relative to this router; returning
+ * undefined keeps the operation's own approval. Read hints with `toolAnnotations(operation)`.
+ * Apply it to each account's router before `accountRouter` combines them, so every account keeps
+ * its own tools' hints.
+ */
+export declare const withApprovals: <Query, Mutation>(source: RouterDeclaration<Query, Mutation>, policy: (operation: OperationDeclaration<"query" | "mutation", never>, name: string) => Approval | undefined) => RouterDeclaration<Query, Mutation>;

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

@@ -2,6 +2,7 @@
 import { Effect, Schema as EffectSchema } from "effect";
 import { JsonObject, ValidationError } from "../contracts/schema.js";
 import type { Field } from "../../../app-data/src/contracts/database.js";
+import type { FieldExposure } from "../contracts/provider.js";
 declare const StorageField: unique symbol;
 declare const Decoder: unique symbol;
 /** An author-facing value schema. Effect is never required in author code. */
@@ -59,6 +60,44 @@ export declare function literal<const T extends string | number | boolean | null
 export declare const array: <T>(item: Schema<T, boolean>) => Schema<readonly T[]>;
 /** Parse declared fields and omit undeclared fields. */
 export declare function object<const F extends Fields>(fields: F): ObjectSchema<F>;
+declare const Exposure: unique symbol;
+/** A schema marked with how app code sees the field in a provider that declares hosts. */
+export type Exposed<S, E extends FieldExposure = FieldExposure> = S & {
+    readonly [Exposure]: E;
+};
+/** The marking of one account field, if any. */
+export declare const exposureOf: (schema: Schema<unknown, boolean>) => FieldExposure | undefined;
+/**
+ * A field that is not secret, such as a subdomain or region. App code reads its real value and
+ * the connect form shows it.
+ */
+export declare const plain: <S extends Schema<unknown, boolean>>(schema: S) => Exposed<S, "plain">;
+/**
+ * A secret field that app code reads as its real value, for request signing and similar uses.
+ * The connect form warns that the app can read it. Prefer an unmarked field, which app code
+ * receives as a handle that only reaches the provider's declared hosts.
+ */
+export declare const raw: <S extends Schema<unknown, boolean>>(schema: S) => Exposed<S, "raw">;
+/** Marked fields of an account object, by name. */
+export declare const fieldExposure: (fields: Fields) => Readonly<Record<string, FieldExposure>>;
+declare const Secret: unique symbol;
+/**
+ * A secret account value. In a provider that declares hosts it is a handle, which the host's
+ * outbound network replaces with the real value only on requests to those hosts. Pass it to
+ * clients and headers as an ordinary string; do not decode or transform it.
+ */
+export type SecretString = string & {
+    readonly [Secret]: true;
+};
+type Sealed<T> = T extends string ? SecretString : T;
+/** Account fields as app code receives them: unmarked string fields are secret. */
+export type SecretFields<F extends Fields> = {
+    readonly [Key in keyof ObjectValue<F>]: Key extends keyof F ? F[Key] extends Exposed<unknown> ? ObjectValue<F>[Key] : Sealed<ObjectValue<F>[Key]> : ObjectValue<F>[Key];
+};
+/** An account object without declared fields, such as a default OAuth projection. */
+export type SecretObject<T> = {
+    readonly [Key in keyof T]: Sealed<T[Key]>;
+};
 declare const ImportedJsonSchema: unique symbol;
 /** Read the original document for an imported decoder without a lossy schema round trip. */
 export declare const importedJsonSchema: (decoder: EffectSchema.Decoder<unknown>) => unknown | undefined;

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

@@ -11,20 +11,22 @@ 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 Fields, type Infer, type ObjectSchema, type Schema } from "./implementation/schema.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, } from "./implementation/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 { accountRouter } from "./implementation/account-router.js";
-export { router, dynamicRouter, type RouterDeclaration, type RouterChild, type RouterOptions, } from "./implementation/router.js";
+export { router, dynamicRouter, withApprovals, type RouterDeclaration, type RouterChild, type RouterOptions, } from "./implementation/router.js";
 export type { RouterIcon } from "./contracts/router.js";
 export { dynamicSkills } from "./implementation/dynamic-skills.js";
 export type { HostedTool as OperationDescription } from "./contracts/host.js";
+/** Account fields as app code receives them from a method declared with this schema. */
+type AccountFields<S> = S extends ObjectSchema<infer F> ? SecretFields<F> : SecretObject<Infer<S>>;
 /** A secrets declaration inferred from an author schema. */
-export type SecretsMethod<Shape extends ObjectSchema<Fields>> = NativeSecretsMethod<EffectSchema.Decoder<Infer<Shape>>>;
+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<Infer<Response>>>;
+export type OAuth2Method<Response extends Schema<unknown, boolean>> = NativeOAuth2Method<EffectSchema.Decoder<AccountFields<Response>>>;
 /** Default OAuth fields visible to app code. Host-only grants and clients stay private. */
 export declare const OAuth2AccessToken: Schema<{
     readonly access_token: string;
@@ -72,7 +74,7 @@ export { NotImplemented } from "./contracts/app.js";
 export { ElicitationFailed, type FormElicitation, type ElicitationResponse, type Elicit, } from "./contracts/elicitation.js";
 export { table, defineDatabase, type Table, type DatabaseReader, type Database, type DatabaseDefinition, } from "./implementation/storage.js";
 export { id, userId } from "./implementation/schema.js";
-export { query, mutation, withApproval, type Operation, type OperationOptions, } from "./implementation/operations.js";
+export { query, 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";