apps 0.0.1-beta.46 → 0.0.1-beta.47

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/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

@@ -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;