apps 0.0.1-beta.46 → 0.0.1-beta.48

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

@@ -3,10 +3,11 @@ import { type RouterDeclaration } from "./router.js";
  * Discover each selected account's router and combine matching names.
  * Calls take { accountId, input }; each branch retains its account's input schema,
  * credentials, approval and output validation. Empty selections expose no operations.
- * Discovery is sequential and cancellation follows the caller's signal.
+ * Discovery is sequential and cancellation follows the caller's signal. `discover` may return the
+ * router or a Promise of it, and the combined router keeps its operations' handler contexts.
  */
 export declare const accountRouter: <Account extends {
     readonly id: string;
-}>(accounts: readonly Account[], discover: (account: Account) => Promise<RouterDeclaration>, options: {
+}, Query = unknown, Mutation = unknown>(accounts: readonly Account[], discover: (account: Account) => RouterDeclaration<Query, Mutation> | Promise<RouterDeclaration<Query, Mutation>>, options: {
     readonly signal: AbortSignal;
-}) => Promise<RouterDeclaration>;
+}) => Promise<RouterDeclaration<Query, Mutation>>;

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

@@ -0,0 +1,59 @@
+/** Event declarations and the per-invocation emitter. Emitted events leave in the reply. */
+import { Effect, Schema as EffectSchema } from "effect";
+import { EmittedEvent, type AppEvent, type EmitOptions } from "../contracts/events.js";
+import { type Fields, type Infer, type ObjectValue, type Schema } from "./schema.js";
+declare const Native: unique symbol;
+/** An event an app emits. Declare it in `defineApp`'s requirements under `events`. */
+export interface EventDeclaration<F extends Fields, P extends Schema<unknown, boolean>> {
+    readonly [Native]: AppEvent;
+    readonly description: string;
+    readonly filters: F;
+    readonly payload: P;
+}
+/** Any declared event, for requirement constraints. */
+export type AnyEventDeclaration = EventDeclaration<Fields, Schema<unknown, boolean>>;
+/**
+ * Declare an event. `filters` are scalar fields subscribers can narrow on, such as a repository;
+ * every emitted occurrence supplies their values. `payload` describes each occurrence's data.
+ */
+export declare const event: <const F extends Fields = {}, P extends Schema<unknown, boolean> = Schema<unknown>>(options: {
+    readonly description: string;
+    readonly filters?: F;
+    readonly payload: P;
+}) => EventDeclaration<F, P>;
+/** The native declaration retained by an author event. */
+export declare const nativeEvent: (declaration: unknown) => AppEvent | undefined;
+/** JSON Schema for each declared event, as the host reads it from requirements. */
+export declare const declaredEvents: (events: Readonly<Record<string, AppEvent>>) => Effect.Effect<{
+    readonly [x: string]: {
+        readonly description: string;
+        readonly filters: {
+            readonly [x: string]: EffectSchema.Json;
+        };
+        readonly payload: {
+            readonly [x: string]: EffectSchema.Json;
+        };
+    };
+}, EffectSchema.SchemaError, never>;
+/** Emit options typed by the event's filters: required exactly when it declares some. */
+type OptionsFor<F extends Fields> = keyof F extends never ? [options?: Omit<EmitOptions<never>, "filters">] : [options: EmitOptions<ObjectValue<F>> & {
+    readonly filters: ObjectValue<F>;
+}];
+/** `ctx.events` in mutations and webhook handlers. */
+export interface EventEmitter<Events extends Readonly<Record<string, AnyEventDeclaration>>> {
+    /**
+     * Record an occurrence. It is delivered only if this invocation succeeds. Invalid data, filters
+     * or options throw here, before anything is recorded.
+     */
+    readonly emit: <Name extends keyof Events & string>(name: Name, data: Infer<Events[Name]["payload"]>, ...options: OptionsFor<Events[Name]["filters"]>) => void;
+}
+/** One invocation's buffer. The handler reads `emitted` only after the invocation succeeds. */
+export declare const makeEmitter: (input: {
+    readonly events: Readonly<Record<string, AppEvent>>;
+    /** Every account ID bound to this invocation. */
+    readonly accounts: readonly string[];
+    /** The webhook's source account, which an emit names by default. */
+    readonly sourceAccount?: string;
+    readonly emitted: EmittedEvent[];
+}) => EventEmitter<Readonly<Record<string, AnyEventDeclaration>>>;
+export {};

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

@@ -38,6 +38,11 @@ export interface RouterChild<Query, Mutation> {
     readonly [QueryHandlerContext]?: (context: Query) => void;
     readonly [MutationHandlerContext]?: (context: Mutation) => void;
 }
+/**
+ * A query or mutation whose handler context is checked by its kind, as a dynamic router resolves
+ * one. `query()` and `mutation()` results fit with their inferred contexts.
+ */
+export type OperationChild<Query, Mutation> = RouterChild<Query, Mutation> & Pick<OperationDeclaration<"query" | "mutation">, "kind" | typeof NativeOperation>;
 /** Private key for a router's native definition. */
 export declare const NativeRouterKey: unique symbol;
 /** Typed operation handles drive browser reference inference without bundling handlers. */

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

@@ -2,8 +2,8 @@ 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";
+import { type OperationChild, type OperationDeclaration, type RouterChild, type RouterDeclaration } from "./operations.js";
+export type { OperationChild, OperationDeclaration, RouterChild, RouterDeclaration, } from "./operations.js";
 /** Author metadata for a router. Instructions become a skill named after the router's path. */
 export interface RouterOptions {
     readonly title?: string;
@@ -28,12 +28,14 @@ export declare function router<Query, Mutation>(source: RouterDeclaration<Query,
 /**
  * Declare a router whose tools are discovered when read. `list` returns tools with names relative
  * to this router; mark queries with `readOnly: true`. `resolve` receives one of those names.
+ * The router carries the handler contexts of the operations `resolve` returns, so `defineApp`
+ * checks them like a static router's.
  */
-export declare const dynamicRouter: (source: {
+export declare const dynamicRouter: <Query = unknown, Mutation = unknown>(source: {
     readonly meta?: () => RouterOptions | Promise<RouterOptions>;
     readonly list: () => readonly HostedTool[] | Promise<readonly HostedTool[]>;
-    readonly resolve: (name: string) => OperationDeclaration<"query" | "mutation", unknown> | undefined | Promise<OperationDeclaration<"query" | "mutation", unknown> | undefined>;
-}) => RouterDeclaration;
+    readonly resolve: (name: string) => OperationChild<Query, Mutation> | undefined | Promise<OperationChild<Query, Mutation> | undefined>;
+}) => RouterDeclaration<Query, Mutation>;
 /** Join a router path and a relative name. The root router's path is "". */
 export declare const joinPath: (path: string, name: string) => string;
 /** Where a full tool name points: a declared operation, or a name inside a dynamic router. */

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

@@ -22,6 +22,11 @@ export interface StepReplay {
 export declare const authorSql: (storage: AppSqlStorage, options: {
     readonly signal: AbortSignal;
     readonly step?: StepReplay;
+    /**
+     * The invocation's emitted events. A transaction that rolls back also discards the events its
+     * callback emitted, so subscribers never hear of writes that did not commit.
+     */
+    readonly emitted?: unknown[];
 }) => {
     reader: SqlReader;
     writer: Sql;

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

@@ -18,7 +18,7 @@ export { type Fields, type Infer, type ObjectSchema, type ObjectValue, type Sche
 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, withApprovals, type RouterDeclaration, type RouterChild, type RouterOptions, } from "./implementation/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";
 export { dynamicSkills } from "./implementation/dynamic-skills.js";
 export type { HostedTool as OperationDescription } from "./contracts/host.js";
@@ -59,6 +59,8 @@ export declare function oauth2<Response extends Schema<unknown, boolean>>(option
 export type { AccountSlots } from "./contracts/app.js";
 export type { AppRequirements, AppContext, QueryContext, MutationContext, WebhookContext, } from "./contracts/context.js";
 export { type App, type AppDefinition, defineApp } from "./implementation/app.js";
+export { event, type EventDeclaration, type EventEmitter } from "./implementation/events.js";
+export type { EmitOptions } from "./contracts/events.js";
 export type { Approval, ApprovalContext, ApprovalDecision } from "./approval.js";
 type AuthorWebhook<Member, Config, State> = Member extends object ? Omit<PromiseMethods<Member>, "config" | "state"> & {
     readonly config: Config;