apps 0.0.1-beta.6 → 0.0.1-beta.7

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

@@ -1,5 +1,5 @@
 /** Provider declarations use native Effect schemas. The trusted host interprets them. */
-import { Data, Schema } from "effect";
+import { Data, type Effect, Schema } from "effect";
 import { type AccountId } from "./schema.js";
 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";
@@ -84,10 +84,54 @@ export declare class OAuth2Method<Response extends Schema.Decoder<unknown>> exte
 export type AuthMethod = SecretsMethod<Schema.Decoder<unknown>> | OAuth2Method<Schema.Decoder<unknown>>;
 /** Auth method names are chosen by the provider author. */
 export type AuthMethods = Readonly<Record<string, AuthMethod>>;
-/** A provider declaration. The future host derives its identity from normalized content. */
+/**
+ * Upstream identity that a passing account check may report for display. Only these fields are
+ * retained; the host never stores raw provider responses.
+ */
+export declare const AccountInfo: Schema.Struct<{
+    readonly externalId: Schema.optionalKey<Schema.String>;
+    readonly displayName: Schema.optionalKey<Schema.String>;
+    readonly username: Schema.optionalKey<Schema.String>;
+    readonly email: Schema.optionalKey<Schema.String>;
+    readonly avatarUrl: Schema.optionalKey<Schema.String>;
+    readonly profileUrl: Schema.optionalKey<Schema.String>;
+}>;
+export type AccountInfo = typeof AccountInfo.Type;
+/** A passing account check. Failures are thrown, so there is no failing variant. */
+export declare const AccountCheckResult: Schema.Struct<{
+    readonly accountInfo: Schema.optionalKey<Schema.Struct<{
+        readonly externalId: Schema.optionalKey<Schema.String>;
+        readonly displayName: Schema.optionalKey<Schema.String>;
+        readonly username: Schema.optionalKey<Schema.String>;
+        readonly email: Schema.optionalKey<Schema.String>;
+        readonly avatarUrl: Schema.optionalKey<Schema.String>;
+        readonly profileUrl: Schema.optionalKey<Schema.String>;
+    }>>;
+}>;
+export type AccountCheckResult = typeof AccountCheckResult.Type;
+/** The account a provider's check verifies, with invocation-owned HTTP and cancellation. */
+export interface AccountCheckContext<Auth extends AuthMethods> {
+    readonly account: AccountOfMethods<Auth>;
+    readonly fetch: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+    readonly signal: AbortSignal;
+}
+/**
+ * A safe authenticated read proving the account works for this app. Returning passes; a thrown
+ * `ProviderError` or HTTP status failure classifies the problem. Any other failure, including a
+ * timeout, means the check could not verify the account, not that its credentials are bad.
+ */
+export interface AccountCheck<Auth extends AuthMethods> {
+    run(context: AccountCheckContext<Auth>): Effect.Effect<AccountCheckResult | void, unknown>;
+}
+/** A provider declaration. The host derives its identity from the declaration, never its check. */
 export declare class Provider<Auth extends AuthMethods> extends Data.Class<{
     readonly name: string;
     readonly auth: Auth;
+    /**
+     * 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.
+     */
+    readonly health?: AccountCheck<AuthMethods>;
 }> {
     /** Declare zero or more accounts from this provider without performing I/O. */
     many(): ManyAccounts<Auth>;
@@ -102,12 +146,14 @@ 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;
-/** One selected account, discriminated by its author-chosen method name. */
-export type AccountOf<P> = P extends Provider<infer Auth> ? {
+/** 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]>;
     };
-}[keyof Auth & string] : never;
+}[keyof Auth & string];
+/** One selected account, discriminated by its author-chosen method name. */
+export type AccountOf<P> = P extends Provider<infer Auth> ? AccountOfMethods<Auth> : never;
 export {};

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

@@ -1,6 +1,7 @@
 /** Pure constructors over the native provider contracts. */
 import { Effect, Schema } from "effect";
-import { type AuthMethods, OAuth2Config, OAuth2Method, Provider, SecretsMethod } from "../contracts/provider.js";
+import { type PromiseMethod } from "./authoring.js";
+import { type AccountCheck, type AuthMethods, 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: {
@@ -9,8 +10,12 @@ export declare const secrets: <Fields extends Schema.Decoder<unknown>>(options:
 }) => 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>;
-/** Retain the provider and literal method names without registering or authenticating it. */
-export declare const defineProvider: <const Auth extends AuthMethods>(options: {
+/** Author options: the account check is an ordinary async function. */
+export interface ProviderOptions<Auth extends AuthMethods> {
     readonly name: string;
     readonly auth: Auth;
-}) => Provider<Auth>;
+    /** 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. */
+export declare const defineProvider: <const Auth extends AuthMethods>({ health, ...options }: ProviderOptions<Auth>) => Provider<Auth>;

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

@@ -14,8 +14,8 @@ import { type PromiseMethods } from "./implementation/authoring.js";
 import { type Fields, type Infer, type ObjectSchema, type Schema } 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 AccountOf, type AuthMethod, type AuthMethodData, type AuthMethods, type ManyAccounts, type OAuth2Config, type Provider, } from "./contracts/provider.js";
-export { defineProvider } from "./implementation/provider.js";
+export { type AccountCheckContext, type AccountCheckResult, type AccountInfo, type AccountOf, type AuthMethod, type AuthMethodData, type AuthMethods, type ManyAccounts, type OAuth2Config, type Provider, } 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 type { RouterIcon } from "./contracts/router.js";