apps 0.0.1-beta.89 → 0.0.1-beta.90

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

@@ -20,7 +20,7 @@ export interface AppDefinition<Context> {
         readonly tool: string;
     }>>;
     readonly webhooks?: Readonly<Record<string, {
-        readonly account: string;
+        readonly account: WebhookAccount;
         readonly config: Schema.Decoder<unknown>;
         readonly state: Schema.Decoder<unknown>;
         readonly setup?: import("./webhook-protocol.js").ManualWebhookSetup;
@@ -29,11 +29,35 @@ export interface AppDefinition<Context> {
         readonly unregister?: Handler<Context>;
     }>>;
 }
+/**
+ * Whose accounts a requirement or context names. App accounts are linked for everyone by the app's
+ * managers and fill the requirement for every caller and for the app's background work; user
+ * accounts are the caller's own links. App-scope work, such as an app schedule, has no caller.
+ */
+export type AccountScope = "app" | "user";
+/** The requirement a webhook's source account fills, in its scope. */
+export type WebhookAccount = {
+    readonly app: string;
+} | {
+    readonly user: string;
+};
 /** Named requirements for one account or a collection from a provider. */
 export type AccountSlots = Readonly<Record<string, Provider<AuthMethods> | ManyAccounts<AuthMethods>>>;
+/**
+ * An app's requirements by scope. A requirement name is unique across both scopes, so a host can
+ * name one requirement without its scope.
+ */
+export interface ScopedSlots {
+    readonly app: AccountSlots;
+    readonly user: AccountSlots;
+}
 type AccountsFor<Slot> = Slot extends ManyAccounts<infer Auth> ? readonly AccountOf<Provider<Auth>>[] : AccountOf<Slot>;
-/** Current credentials for one invocation. Never retained in source or build output. */
-export interface BoundContext<Slots extends AccountSlots> {
+/** One scope's current accounts, by requirement. */
+export type BoundAccounts<Slots extends AccountSlots> = {
+    readonly [Slot in keyof Slots]: AccountsFor<Slots[Slot]>;
+};
+/** Invocation capabilities every context has, whatever its accounts. */
+export interface InvocationServices {
     /** Explicit app/build-scoped caching. Account-specific loaders opt into forAccount. */
     readonly cache: import("./cache.js").AppCache;
     /** Text files retained in this deployment. Paths are package-relative, never host filesystem paths. */
@@ -50,18 +74,37 @@ export interface BoundContext<Slots extends AccountSlots> {
     readonly fetch: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
     /** Host cancellation for this invocation. Pass it to fetch and other interruptible APIs. */
     readonly signal: AbortSignal;
-    readonly accounts: {
-        readonly [Slot in keyof Slots]: AccountsFor<Slots[Slot]>;
+}
+/** The app's own accounts, linked for everyone by its managers. Every invocation has them. */
+export interface AppAccountsContext<Slots extends AccountSlots> {
+    readonly app: {
+        readonly accounts: BoundAccounts<Slots>;
+    };
+}
+/** The caller's own linked accounts. App-scope work has no caller, so it has none. */
+export interface UserAccountsContext<Slots extends AccountSlots> {
+    readonly user: {
+        readonly accounts: BoundAccounts<Slots>;
     };
 }
-/** The host evaluates this factory fresh with the configured app's selected accounts. */
-export interface App<Slots extends AccountSlots, Def extends AppDefinition<never>> {
+/**
+ * Current credentials for one invocation. Never retained in source or build output. A context of
+ * the `"app"` scope has no `user`: it serves work without a caller, such as an app schedule.
+ */
+export type BoundContext<Slots extends ScopedSlots, Scope extends AccountScope = "user"> = InvocationServices & AppAccountsContext<Slots["app"]> & ([Scope] extends ["user"] ? UserAccountsContext<Slots["user"]> : unknown);
+/**
+ * What the app factory receives: the app's accounts, and the caller's when the invocation has a
+ * caller. App-scope work evaluates the factory without `user`.
+ */
+export type EvaluationContext<Slots extends ScopedSlots> = BoundContext<Slots, "app"> & Partial<UserAccountsContext<Slots["user"]>>;
+/** The host evaluates this factory fresh with the invocation's accounts. */
+export interface App<Slots extends ScopedSlots, 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>;
+    readonly evaluate: (context: EvaluationContext<Slots>) => Effect.Effect<Def, unknown>;
 }
 declare const NotImplemented_base: Schema.Class<NotImplemented, Schema.TaggedStruct<"NotImplemented", {
     readonly operation: Schema.String;

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

@@ -52,7 +52,7 @@ export type AccountCredential<Credential extends object> = ({
 } & {
     readonly [Field in keyof Credential]?: undefined;
 }) | ({
-    /** The selected account, as `accounts.<slot>` provides it. */
+    /** The selected account, as `ctx.app.accounts.<slot>` or `ctx.user.accounts.<slot>` provides it. */
     readonly account: {
         readonly id: string;
     };

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

@@ -1,12 +1,23 @@
 /** Public handler contexts derive capabilities from one shared requirements declaration. */
 import type { WorkflowControls } from "./workflows.js";
-import type { AccountSlots, BoundContext } from "./app.js";
+import type { AccountScope, 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. */
+/**
+ * Requirements are pure values; bound accounts and SQL access belong to invocations. `app` names the
+ * accounts the app's managers link for every caller and for background work, `user` the accounts
+ * each caller links. A requirement name is used once across both.
+ */
 export interface AppRequirements {
-    readonly accounts: AccountSlots;
+    readonly app?: {
+        readonly accounts: AccountSlots;
+    };
+    readonly user?: {
+        readonly accounts: AccountSlots;
+    };
+    /** Removed: declare `user: { accounts }` for the caller's accounts or `app: { accounts }`. */
+    readonly accounts?: never;
     /** Events this app emits, by name, such as `issue.opened`. */
     readonly events?: Readonly<Record<string, AnyEventDeclaration>>;
     /**
@@ -15,6 +26,15 @@ export interface AppRequirements {
      */
     readonly icons?: ReadonlyArray<AppIcon>;
 }
+/** One scope's requirements; none when the app declares none in it. */
+type ScopeSlots<Requirements, Scope extends AccountScope> = Scope extends keyof Requirements ? NonNullable<Requirements[Scope]> extends {
+    readonly accounts: infer Slots extends AccountSlots;
+} ? Slots : Record<never, never> : Record<never, never>;
+/** An app's requirements by scope, as contexts bind them. */
+export type RequirementSlots<Requirements extends AppRequirements> = {
+    readonly app: ScopeSlots<Requirements, "app">;
+    readonly user: ScopeSlots<Requirements, "user">;
+};
 /** The emitter for an app's declared events. */
 type EventsContext<Requirements extends AppRequirements> = {
     readonly events: EventEmitter<NonNullable<Requirements["events"]>>;
@@ -26,14 +46,23 @@ type EventsContext<Requirements extends AppRequirements> = {
 type StorageContext<Writable extends boolean> = {
     readonly sql: Writable extends true ? Sql : SqlReader;
 };
-/** Context available during dynamic app evaluation; storage opens only for handlers. */
-export type AppContext<Requirements extends AppRequirements = AppRequirements> = BoundContext<Requirements["accounts"]>;
+/**
+ * Context available during dynamic app evaluation; storage opens only for handlers. `ctx.app.accounts`
+ * holds the app's accounts and `ctx.user.accounts` the caller's. With the `"app"` scope there is no
+ * `user`: app schedules and app-account webhooks run without a caller.
+ */
+export type AppContext<Requirements extends AppRequirements = AppRequirements, Scope extends AccountScope = "user"> = BoundContext<RequirementSlots<Requirements>, Scope>;
 /** Interactive query context; declared storage exposes only read methods. */
-export type QueryContext<Requirements extends AppRequirements = AppRequirements> = AppContext<Requirements> & StorageContext<false>;
+export type QueryContext<Requirements extends AppRequirements = AppRequirements, Scope extends AccountScope = "user"> = AppContext<Requirements, Scope> & StorageContext<false>;
 /** Interactive mutation context; outside calls happen between SQL transactions, never inside one. */
-export type MutationContext<Requirements extends AppRequirements = AppRequirements> = Omit<AppContext<Requirements>, "workflows"> & {
+export type MutationContext<Requirements extends AppRequirements = AppRequirements, Scope extends AccountScope = "user"> = Omit<AppContext<Requirements, Scope>, "workflows"> & {
     readonly workflows: WorkflowControls;
 } & StorageContext<true> & EventsContext<Requirements>;
+/**
+ * The context of a mutation whose handler declares no parameters. It uses no context, so it may run
+ * as the app, such as from an app schedule, where `user` is absent.
+ */
+export type AnyScopeMutationContext<Requirements extends AppRequirements = AppRequirements> = MutationContext<Requirements, "app"> & Partial<Pick<MutationContext<Requirements>, "user">>;
 /** Background webhook context has account and storage access without interactive input. */
-export type WebhookContext<Requirements extends AppRequirements = AppRequirements> = Omit<MutationContext<Requirements>, "elicit">;
+export type WebhookContext<Requirements extends AppRequirements = AppRequirements, Scope extends AccountScope = "user"> = Omit<MutationContext<Requirements, Scope>, "elicit">;
 export {};

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

@@ -87,7 +87,8 @@ export interface EmitOptions<Filters> {
     readonly occurredAt?: Date | number | undefined;
     /**
      * The ID of the account the event came from. A webhook handler defaults to its source account,
-     * and an invocation with exactly one account to that account. Name it when there are several.
+     * and an invocation with exactly one of the caller's accounts to that account; the app's own
+     * accounts never count. Name it when there are several.
      */
     readonly account?: string | undefined;
 }