apps 0.0.1-beta.87 → 0.0.1-beta.89

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

@@ -59,6 +59,8 @@ export interface App<Slots extends AccountSlots, Def extends AppDefinition<never
     readonly accounts: Slots;
     /** Declared beside the accounts, so a host lists them without evaluating the app. */
     readonly events?: Readonly<Record<string, import("./events.js").AppEvent>>;
+    /** Declared beside the accounts and checked when the module loads. */
+    readonly icons?: import("./icons.js").AppIcons;
     readonly evaluate: (context: BoundContext<Slots>) => Effect.Effect<Def, unknown>;
 }
 declare const NotImplemented_base: Schema.Class<NotImplemented, Schema.TaggedStruct<"NotImplemented", {

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

@@ -3,11 +3,17 @@ import type { WorkflowControls } from "./workflows.js";
 import type { AccountSlots, BoundContext } from "./app.js";
 import type { Sql, SqlReader } from "./sql.js";
 import type { AnyEventDeclaration, EventEmitter } from "../implementation/events.js";
+import type { AppIcon } from "./icons.js";
 /** Requirements are pure values; selected accounts and SQL access belong to invocations. */
 export interface AppRequirements {
     readonly accounts: AccountSlots;
     /** Events this app emits, by name, such as `issue.opened`. */
     readonly events?: Readonly<Record<string, AnyEventDeclaration>>;
+    /**
+     * Images a dashboard shows for the app, such as its logo in light and dark variants. Each `src`
+     * is base64 `data:image/...` or an `https:` URL; at most 8 icons and 32 KiB in total.
+     */
+    readonly icons?: ReadonlyArray<AppIcon>;
 }
 /** The emitter for an app's declared events. */
 type EventsContext<Requirements extends AppRequirements> = {

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

@@ -20,9 +20,10 @@ export { ElicitationLimits, defaultElicitationLimits, FormElicitation, Elicitati
 export { McpClientLimits, defaultMcpClientLimits } from "./mcp.js";
 export * from "./webhook-protocol.js";
 export * from "./events.js";
+export { AppIcon, AppIcons, appIconLimits } from "./icons.js";
 export * from "./placement.js";
 export { AccountId, HttpUrl } from "./schema.js";
-export { OAuthAuthorizationParams, OAuthClientAuth, OAuthSecretClientAuth, OAuthTokenRequestFormat, OAuthTokenResponse, } from "./provider.js";
+export { OAuthAuthorizationParams, OAuthClientAuth, OAuthSecretClientAuth, OAuthTokenRequestFormat, OAuthTokenResponse, reservedAuthorizationParams, type ReservedAuthorizationParam, } from "./provider.js";
 /**
  * The host protocol this framework speaks and its wire schemas, from `protocols/current.ts`. The
  * released protocol modules are frozen records that host adapters read.

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

@@ -0,0 +1,28 @@
+/** The icons an app declares beside its accounts, so a host shows them without evaluating it. */
+import { Schema } from "effect";
+/** At most this many icons, together at most this many characters of JSON (32 KiB). */
+export declare const appIconLimits: {
+    readonly icons: 8;
+    readonly characters: number;
+};
+/**
+ * One image an app shows for itself, the same shape as a router's icon. `theme` names the color
+ * scheme it is drawn for; an icon without one suits both.
+ */
+export declare const AppIcon: Schema.Struct<{
+    readonly src: Schema.String;
+    readonly mimeType: Schema.optionalKey<Schema.String>;
+    readonly sizes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly theme: Schema.optionalKey<Schema.Literals<readonly ["light", "dark"]>>;
+}>;
+export type AppIcon = typeof AppIcon.Type;
+/** An app's icons, bounded in number and total size. */
+export declare const AppIcons: Schema.$Array<Schema.Struct<{
+    readonly src: Schema.String;
+    readonly mimeType: Schema.optionalKey<Schema.String>;
+    readonly sizes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly theme: Schema.optionalKey<Schema.Literals<readonly ["light", "dark"]>>;
+}>>;
+export type AppIcons = typeof AppIcons.Type;
+/** Why declared icons are refused, in the author's terms, or undefined when they are valid. */
+export declare const appIconsProblem: (icons: unknown) => string | undefined;

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

@@ -663,6 +663,13 @@ export declare const DeclaredRequirements: Schema.Struct<{
         readonly filters: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
         readonly payload: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
     }>>>;
+    /** The icons the app declares, so a host shows them without evaluating the app. */
+    readonly icons: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly src: Schema.String;
+        readonly mimeType: Schema.optionalKey<Schema.String>;
+        readonly sizes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly theme: Schema.optionalKey<Schema.Literals<readonly ["light", "dark"]>>;
+    }>>>;
 }>;
 /** Parsed declared account requirements. */
 export type DeclaredRequirements = typeof DeclaredRequirements.Type;
@@ -3175,6 +3182,13 @@ export declare const current: {
                 readonly filters: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
                 readonly payload: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
             }>>>;
+            /** The icons the app declares, so a host shows them without evaluating the app. */
+            readonly icons: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+                readonly src: Schema.String;
+                readonly mimeType: Schema.optionalKey<Schema.String>;
+                readonly sizes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+                readonly theme: Schema.optionalKey<Schema.Literals<readonly ["light", "dark"]>>;
+            }>>>;
         }>;
         readonly catalog: Schema.Struct<{
             readonly tools: Schema.$Array<Schema.Struct<{

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

@@ -12,6 +12,27 @@ export declare const AccountId: Schema.brand<Schema.String, "acc">;
 export type AccountId = typeof AccountId.Type;
 /** Absolute HTTP(S) URL; local HTTP hosts are supported. */
 export declare const HttpUrl: Schema.String;
+/** One problem with a declaration: where in it, and what is wrong there. */
+export declare const DeclarationIssue: Schema.Struct<{
+    readonly path: Schema.$Array<Schema.String>;
+    readonly message: Schema.String;
+}>;
+export type DeclarationIssue = typeof DeclarationIssue.Type;
+declare const DeclarationInvalid_base: Schema.Class<DeclarationInvalid, Schema.TaggedStruct<"DeclarationInvalid", {
+    readonly declaration: Schema.String;
+    readonly issues: Schema.$Array<Schema.Struct<{
+        readonly path: Schema.$Array<Schema.String>;
+        readonly message: Schema.String;
+    }>>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * An author's declaration, such as the options of `oauth2()`, did not match its schema. Unlike
+ * {@link ValidationError} it names each failing path and problem, because the value is the
+ * author's own source. Messages never include supplied values.
+ */
+export declare class DeclarationInvalid extends DeclarationInvalid_base {
+    get message(): string;
+}
 declare const ValidationError_base: Schema.Class<ValidationError, Schema.TaggedStruct<"ValidationError", {}>, import("effect/Cause").YieldableError>;
 /** Invalid input. Never includes supplied values, credentials or response bodies. */
 export declare class ValidationError extends ValidationError_base {

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

@@ -25,12 +25,13 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
     readonly fallbackSecurity?: GeneratedOperation["request"]["security"];
 }) => Effect.Effect<{
     operations: {
+        readonly path: string;
         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 in: "path" | "header" | "query" | "querystring" | "cookie";
                 readonly name: string;
                 readonly required?: boolean;
                 readonly schema?: {
@@ -66,7 +67,6 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
                 readonly required?: boolean;
             };
         };
-        readonly path: string;
         readonly input: {
             readonly [x: string]: Schema.Json;
         };

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

@@ -3,7 +3,7 @@ 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";
+import type { DeclarationInvalid } 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;
@@ -12,7 +12,7 @@ export declare const secrets: <Fields extends Schema.Decoder<unknown>>(options:
     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>>, request?: readonly Placement[]) => 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>, DeclarationInvalid>;
 /** Author options: the account check is an ordinary async function. */
 export interface ProviderOptions<Auth extends AuthMethods> {
     readonly name: string;

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

@@ -190,15 +190,15 @@ export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined,
         readonly description?: string;
         readonly error?: import("../index.js").ProviderError | import("../contracts/host.js").McpError | import("../contracts/host.js").SkillLoadFailed | HostDeclarationInvalid | HostEvaluationFailed;
         readonly title?: string;
-        readonly tags?: {
-            readonly [x: string]: string;
-        };
         readonly icons?: readonly {
             readonly src: string;
             readonly mimeType?: string;
             readonly sizes?: readonly string[];
             readonly theme?: "light" | "dark";
         }[];
+        readonly tags?: {
+            readonly [x: string]: string;
+        };
         readonly skill?: string;
     }[];
 }, import("../index.js").ProviderError | import("../contracts/host.js").McpError | import("../contracts/host.js").SkillLoadFailed | HostDeclarationInvalid | HostEvaluationFailed, never>;

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

@@ -1,6 +1,6 @@
 /** Author schema facade. Internals use the native decoder retained by each value. */
 import { Effect, Schema as EffectSchema } from "effect";
-import { JsonObject, ValidationError } from "../contracts/schema.js";
+import { DeclarationInvalid, JsonObject, ValidationError } from "../contracts/schema.js";
 import type { FieldExposure } from "../contracts/provider.js";
 declare const Decoder: unique symbol;
 /** An author-facing value schema. Effect is never required in author code. */
@@ -42,6 +42,13 @@ export declare const isSchema: (value: unknown) => value is Schema<unknown, bool
 export declare const schemaArgument: <S extends Schema<unknown, boolean>>(value: S, role: string) => S;
 /** Decode within an Effect program. Invalid input is omitted from the failure. */
 export declare const parse: <T>(decoder: EffectSchema.Decoder<T>, input: unknown) => Effect.Effect<T, ValidationError>;
+/**
+ * Decode an author's declaration, naming every failing path. A declaration with several forms,
+ * such as `oauth2()`'s discovered, declared and client credentials endpoints, is explained by the
+ * form its author chose (`intended`), so the problems are that form's, including the options it
+ * lacks, rather than every other form's objections. Messages never include the supplied values.
+ */
+export declare const parseDeclaration: <T>(decoder: EffectSchema.Decoder<T>, input: unknown, declaration: string, intended?: (input: unknown) => EffectSchema.Decoder<unknown>) => Effect.Effect<T, DeclarationInvalid>;
 /** Present a native decoder through the synchronous author API. */
 export declare function wrap<T, Optional extends boolean>(decoder: EffectSchema.Decoder<T>, optionalValue: Optional): Schema<T, Optional>;
 /** A string, optionally with a minimum length. No coercion. */

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

@@ -17,7 +17,7 @@ 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 { DeclarationInvalid, type DeclarationIssue, 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";
@@ -27,6 +27,7 @@ export type { AccountRequest } from "./contracts/provider.js";
 export { accountRouter } from "./implementation/account-router.js";
 export { router, dynamicRouter, withApprovals, renameTools, type OperationChild, type OperationDeclaration, type RouterDeclaration, type RouterChild, type RouterOptions, } from "./implementation/router.js";
 export type { RouterIcon } from "./contracts/router.js";
+export type { AppIcon } from "./contracts/icons.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. */