apps 0.0.1-beta.16 → 0.0.1-beta.18

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/contracts/ui.d.ts

@@ -7,6 +7,24 @@ export declare const UiContext: Schema.Struct<{
     readonly profile: Schema.optional<Schema.NonEmptyString>;
     readonly expectedProfileRevision: Schema.optional<Schema.Int>;
 }>;
+/** A problem with one of the page profile's accounts, from stored state. Labels are the owner's own names. */
+export type UiAccountProblem = {
+    readonly provider: string;
+    readonly reason: "missing" | "removed" | "incompatible";
+} | {
+    readonly provider: string;
+    readonly account: string;
+    readonly reason: "credentials_rejected" | "forbidden" | "upstream_unavailable" | "check_failed";
+};
+/** Account problems found when the page opened, with dashboard links that resolve them. */
+export interface UiAccountNotice {
+    readonly app: string;
+    readonly problems: readonly UiAccountProblem[];
+    /** The profile's accounts in the dashboard. */
+    readonly fix: string;
+    /** The dashboard chooser, returning to this page. */
+    readonly choose: string;
+}
 /** Retained browser bytes. Hosts authorize access before reading or rendering them. */
 export interface AppUiAsset {
     readonly body: Uint8Array;

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/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/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/implementation/ui-account-notice.d.ts

@@ -0,0 +1,9 @@
+/** Host-rendered account notices; no authored app code or provider responses enter them. */
+import type { UiAccountNotice, UiAccountProblem } from "../contracts/ui.js";
+/** Missing, removed, incompatible, or rejected accounts stop the app; other failed checks are advisory. */
+export declare const accountProblemBlocks: (problem: UiAccountProblem) => boolean;
+export declare const accountProblemText: (problem: UiAccountProblem) => string;
+/** Full page shown instead of the app while an account problem stops it from working. */
+export declare const accountBlockedPage: (notice: UiAccountNotice) => string;
+/** Inline card for advisory problems; the app still loads underneath. */
+export declare const accountNoticeBootstrap: (notice: UiAccountNotice) => string;

package/types/apps/src/implementation/ui-serving.d.ts

@@ -1,12 +1,16 @@
 import { Effect } from "effect";
 import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
-import { UiForbidden, type AppUiAsset } from "../contracts/ui.js";
-/** Render an authorized deployment with a host-owned deployment watcher. */
+import { UiForbidden, type AppUiAsset, type UiAccountNotice } from "../contracts/ui.js";
+/**
+ * Render an authorized deployment with a host-owned deployment watcher. Account problems that stop
+ * the app replace its document with a page that links to their fix; others add a dismissible card.
+ */
 export declare const appDocument: <E, R>(options: {
     readonly deployment: string;
     readonly profile?: string | undefined;
     readonly expectedProfileRevision?: number | undefined;
     readonly origin: string;
+    readonly accounts?: UiAccountNotice | undefined;
     readonly asset: (path: string) => Effect.Effect<AppUiAsset | undefined, E, R>;
 }) => Effect.Effect<HttpServerResponse.HttpServerResponse, UiForbidden | E, HttpServerRequest.HttpServerRequest | R>;
 /** Serve an asset only after the host has checked current access and file existence.

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

@@ -11,9 +11,9 @@ 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";
@@ -21,10 +21,12 @@ export { router, dynamicRouter, withApprovals, type RouterDeclaration, type Rout
 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;