@lantharos/pult 0.8.0 → 0.9.0

package/index.d.mts

@@ -12,11 +12,6 @@ interface SendResult {
   reopened: boolean;
   occurrences: number;
 }
-interface ActionResult {
-  message?: string;
-  blocks?: Block[];
-  running?: boolean;
-}
 interface IncomingMessage {
   thread: string;
   from: string;
@@ -77,7 +72,7 @@ interface FlagState extends FlagValue {
 //#region ../protocol/src/status.d.ts
 type ComponentState = "operational" | "degraded" | "partial" | "down" | "maintenance";
 //#endregion
-//#region ../protocol/src/console.d.ts
+//#region ../protocol/src/console/console.d.ts
 interface ItemSummary {
   id: string;
   inbox: string;
@@ -368,6 +363,17 @@ interface PageDef {
   params: JsonSchema | null;
   blocks: Block[] | null;
 }
+interface SpaceDef {
+  name: string;
+  source: string;
+  label: string;
+  icon: string;
+  home: string | null;
+  inboxes: string[];
+  resources: string[];
+  pages: string[];
+  flags: string[];
+}
 interface FlagDef {
   source: string;
   label: string;
@@ -409,13 +415,13 @@ interface StatusLogo {
   light: string;
   dark: string;
 }
-interface StatusDef {
+interface StatusDef<Component extends string = string> {
   source: string;
   title: string;
   logo: StatusLogo | null;
   website: string | null;
   css: string | null;
-  components: Record<string, StatusComponentDef>;
+  components: Record<Component, StatusComponentDef>;
   alert: Recipient[];
   after: number;
 }
@@ -425,7 +431,7 @@ type Delivery = {
   mode: "webhook";
   path: string;
 };
-interface Manifest {
+interface Manifest<Component extends string = string> {
   project: string;
   version: string;
   environments: string[];
@@ -438,8 +444,9 @@ interface Manifest {
   pages: Record<string, PageDef>;
   flags: Record<string, FlagDef>;
   roles: Record<string, RoleDef>;
+  spaces: SpaceDef[];
   notify: Record<string, NotifyDef>;
-  status: StatusDef | null;
+  status: StatusDef<Component> | null;
 }
 //#endregion
 //#region src/schema.d.ts
@@ -452,9 +459,10 @@ export declare class ValidationError extends Error {
   constructor(issues: readonly StandardSchemaV1.Issue[]);
 }
 //#endregion
-//#region src/define/source.d.ts
+//#region src/define/core.d.ts
 declare const KIND: unique symbol;
-type Kind = "resource" | "action" | "inbox" | "role" | "view" | "page" | "flag" | "notify" | "status" | "config";
+type Awaitable<T> = T | Promise<T>;
+type Kind = "resource" | "action" | "inbox" | "role" | "view" | "page" | "flag" | "notify" | "space" | "status" | "config";
 interface Located {
   readonly [KIND]: Kind;
   readonly origin: Origin;
@@ -465,7 +473,6 @@ interface Origin {
 }
 //#endregion
 //#region src/define/resource.d.ts
-type Awaitable$2<T> = T | Promise<T>;
 interface ActionContext<R, I> {
   record: R;
   input: I;
@@ -473,8 +480,12 @@ interface ActionContext<R, I> {
   item: string | null;
   progress: (fraction: number | null, note?: string) => Promise<void>;
 }
-type ActionReturn = undefined | string | ActionResult;
-type ActionInput$1<S> = S extends AnySchema ? InferOutput<S> : Record<string, never>;
+type ActionReturn = undefined | string | {
+  message?: string;
+  blocks?: BlockInput[];
+};
+type ActionInput<S> = S extends AnySchema ? InferOutput<S> : Record<string, never>;
+type Prefill<S> = S extends AnySchema ? Partial<InferInput<S>> : Record<string, never>;
 type ChoiceInput = string | {
   value: string;
   label: string;
@@ -488,11 +499,11 @@ interface ActionOptions<R, S> {
   approval?: boolean;
   background?: boolean;
   when?: (record: R) => boolean;
-  defaults?: (record: R) => Partial<ActionInput$1<S>>;
-  pick?: { [K in keyof ActionInput$1<S>]?: string; };
-  choices?: { [K in keyof ActionInput$1<S>]?: (record: R) => Awaitable$2<ChoiceInput[]>; };
-  preview?: (context: ActionContext<R, ActionInput$1<S>>) => Awaitable$2<BlockInput[]>;
-  run: (context: ActionContext<R, ActionInput$1<S>>) => Awaitable$2<ActionReturn>;
+  defaults?: (record: R) => Partial<ActionInput<S>>;
+  pick?: { [K in keyof ActionInput<S>]?: string; };
+  choices?: { [K in keyof ActionInput<S>]?: (record: R) => Awaitable<ChoiceInput[]>; };
+  preview?: (context: ActionContext<R, ActionInput<S>>) => Awaitable<BlockInput[]>;
+  run: (context: ActionContext<R, ActionInput<S>>) => Awaitable<ActionReturn>;
 }
 interface ActionRef {
   readonly id: string;
@@ -516,7 +527,7 @@ type ActionFactory<R> = <S extends AnySchema | undefined = undefined>(options: A
 interface Relation<R = any> {
   resource: string;
   label?: string;
-  list: (record: R, limit: number) => Awaitable$2<unknown[]>;
+  list: (record: R, limit: number) => Awaitable<unknown[]>;
 }
 interface ListQuery<F> {
   query: string;
@@ -526,21 +537,21 @@ interface ListQuery<F> {
 }
 interface ListOptions<R, F extends AnySchema | undefined> {
   filters?: F;
-  run: (query: ListQuery<F extends AnySchema ? InferOutput<F> : Record<string, never>>) => Awaitable$2<{
+  run: (query: ListQuery<F extends AnySchema ? InferOutput<F> : Record<string, never>>) => Awaitable<{
     records: R[];
     cursor?: string | null;
   }>;
 }
 interface ResourceOptions<R, A, F extends AnySchema | undefined> {
-  get: (id: string) => Awaitable$2<R | null | undefined>;
-  find?: (query: string, limit: number) => Awaitable$2<R[]>;
+  get: (id: string) => Awaitable<R | null | undefined>;
+  find?: (query: string, limit: number) => Awaitable<R[]>;
   list?: ListOptions<R, F>;
   id?: (record: R) => string;
   title: (record: R) => string;
   subtitle?: (record: R) => string | undefined;
   fields?: (record: R) => Record<string, FieldInput>;
   url?: (record: R) => string | undefined;
-  render?: (record: R) => Awaitable$2<BlockInput[]>;
+  render?: (record: R) => Awaitable<BlockInput[]>;
   label?: string;
   plural?: string;
   icon?: string;
@@ -557,7 +568,7 @@ interface Resource<R = any, A = any> extends Located {
 }
 export declare function resource<R, A extends Record<string, unknown> = Record<never, never>, F extends AnySchema | undefined = undefined>(name: string, options: ResourceOptions<R, A, F>): Resource<R, A>;
 //#endregion
-//#region src/define/triage.d.ts
+//#region src/define/inbox/triage.d.ts
 declare const answer: unique symbol;
 type Question<T> = TriageQuestion & {
   readonly [answer]?: T;
@@ -571,7 +582,7 @@ type Answers<Q extends Record<string, Question<unknown>>> = { [K in keyof Q]: Q[
 interface Rule<A> {
   name?: string;
   live?: boolean;
-  when: (answers: A) => boolean;
+  when(answers: A): boolean;
   then: TriageDecision | TriageDecision[];
 }
 interface Triage<Q extends Record<string, Question<unknown>> = Record<string, Question<unknown>>> {
@@ -586,10 +597,9 @@ export declare function triage<Q extends Record<string, Question<unknown>>>(opti
 }): Triage<Q>;
 export declare const setState: (state: string) => TriageDecision;
 export declare const tag: (name: string) => TriageDecision;
-export declare const run: (action: ActionRef, input?: Record<string, unknown>) => TriageDecision;
+export declare const run: <S>(action: Action<any, S>, input?: Prefill<S>) => TriageDecision;
 //#endregion
-//#region src/define/inbox.d.ts
-type Awaitable$1<T> = T | Promise<T>;
+//#region src/define/inbox/inbox.d.ts
 type Duration = `${number}${"m" | "h" | "d"}`;
 interface ItemView<D> {
   title: string;
@@ -612,18 +622,18 @@ interface InboxOptions<S extends Schema | undefined> {
   reopenFrom?: string[];
   data?: S;
   title?: (data: InboxData<S>) => string;
-  render?: (item: ItemView<InboxData<S>>) => Awaitable$1<BlockInput[]>;
+  render?: (item: ItemView<InboxData<S>>) => Awaitable<BlockInput[]>;
   columns?: string[];
   intake?: boolean | {
     title?: string;
     description?: string;
   };
-  triage?: Triage<any>;
+  triage?: Triage;
   reply?: {
     to: (item: ItemView<InboxData<S>>) => string | undefined;
-    send: (email: OutgoingEmail<InboxData<S>>) => Awaitable$1<void>;
+    send: (email: OutgoingEmail<InboxData<S>>) => Awaitable<void>;
   };
-  onState?: (change: StateChange<InboxData<S>>) => Awaitable$1<void>;
+  onState?: (change: StateChange<InboxData<S>>) => Awaitable<void>;
   sla?: Record<string, Duration>;
 }
 interface OutgoingEmail<D> {
@@ -660,13 +670,13 @@ interface Inbox<S extends Schema | undefined = any> extends Located {
 }
 export declare function inbox<S extends Schema | undefined = undefined>(name: string, options: InboxOptions<S>): Inbox<S>;
 //#endregion
-//#region src/define/flag.d.ts
+//#region src/define/controls/flag.d.ts
 interface Guard {
   inbox: Inbox;
   perHour: number;
   then?: "pause" | "revert";
 }
-interface FlagOptionsBase<A> {
+interface FlagOptions<A = undefined> {
   label?: string;
   description?: string;
   target?: Resource;
@@ -676,27 +686,26 @@ interface FlagOptionsBase<A> {
   approval?: boolean;
 }
 type Attributes<A> = A extends AnySchema ? Partial<InferOutput<A>> : Record<string, Attribute | null | undefined>;
-type FlagContext<A> = {
+type FlagContext<A = undefined> = {
   key?: string;
 } & Attributes<A>;
 interface Flag<T = unknown, A = unknown> extends Located {
   readonly name: string;
-  readonly options: FlagOptionsBase<AnySchema> & {
+  readonly options: FlagOptions<AnySchema> & {
     value?: AnySchema;
     default: T;
   };
   readonly context?: FlagContext<A>;
 }
-export declare function flag<A extends AnySchema | undefined = undefined>(name: string, options?: FlagOptionsBase<A> & {
+export declare function flag<A extends AnySchema | undefined = undefined>(name: string, options?: FlagOptions<A> & {
   default?: boolean;
 }): Flag<boolean, A>;
-export declare function flag<S extends AnySchema, A extends AnySchema | undefined = undefined>(name: string, options: FlagOptionsBase<A> & {
+export declare function flag<S extends AnySchema, A extends AnySchema | undefined = undefined>(name: string, options: FlagOptions<A> & {
   value: S;
   default: InferOutput<S>;
 }): Flag<InferOutput<S>, A>;
 //#endregion
-//#region src/define/page.d.ts
-type Awaitable<T> = T | Promise<T>;
+//#region src/define/inbox/view.d.ts
 type Filter = Omit<ViewFilter, "state"> & {
   state?: string | string[];
 };
@@ -713,24 +722,6 @@ interface View extends Located {
   readonly options: ViewOptions;
 }
 export declare function view(name: string, options: ViewOptions): View;
-type Params<P> = P extends AnySchema ? InferOutput<P> : Record<string, never>;
-interface PageContext<P> {
-  params: P;
-  actor: Actor;
-}
-type PageContent<P> = BlockInput[] | ((context: PageContext<Params<P>>) => Awaitable<BlockInput[]>);
-interface PageOptions<P extends AnySchema | undefined> {
-  label?: string;
-  icon?: string;
-  params?: P;
-  render: PageContent<P>;
-}
-interface Page extends Located {
-  readonly name: string;
-  readonly options: PageOptions<any>;
-}
-export declare function page<P extends AnySchema | undefined = undefined>(name: string, options: PageOptions<P>): Page;
-export declare function home<P extends AnySchema | undefined = undefined>(options: PageContent<P> | PageOptions<P>): Page;
 //#endregion
 //#region src/blocks.d.ts
 type FieldInput = FieldValue | Date | undefined;
@@ -740,7 +731,11 @@ interface PendingAttachment {
   contentType: string;
   data: Blob | ArrayBuffer | Uint8Array;
 }
-type BlockInput = Block | PendingAttachment;
+interface ColumnsInput {
+  type: "columns";
+  columns: BlockInput[][];
+}
+type BlockInput = Block | PendingAttachment | ColumnsInput;
 type ResourceLike = string | {
   readonly name: string;
 };
@@ -760,13 +755,18 @@ declare function chart(inbox: Inbox, options?: {
   title?: string;
 }): Block;
 type Listing = Inbox | View;
-type ActionInput = ActionRef | string;
-type ButtonInput = ActionInput | {
-  action: ActionInput;
+type ActionTarget = Action | string;
+interface ButtonOptions {
   record?: string;
-  input?: Record<string, unknown>;
   label?: string;
-};
+}
+type ButtonInput<S = any> = ActionTarget | (ButtonOptions & {
+  action: string;
+  input?: Record<string, unknown>;
+}) | (ButtonOptions & {
+  action: Action<any, S>;
+  input?: Prefill<S>;
+});
 export declare const b: {
   markdown: (text: string) => Block;
   fields: (fields: Record<string, FieldInput>) => Block;
@@ -795,9 +795,9 @@ export declare const b: {
     value: FieldInput;
     note?: string;
   }>) => Block;
-  actions: (...buttons: ButtonInput[]) => Block;
-  form: (action: ButtonInput) => Block;
-  columns: (...columns: BlockInput[][]) => Block;
+  actions: <S extends unknown[]>(...buttons: { [K in keyof S]: ButtonInput<S[K]>; }) => Block;
+  form: <S>(action: ButtonInput<S>) => Block;
+  columns: (...columns: BlockInput[][]) => BlockInput;
   count: (target: Listing, options?: {
     filter?: Filter;
     label?: string;
@@ -807,8 +807,8 @@ export declare const b: {
     label?: string;
     limit?: number;
   }) => Block;
-  flag: (flag: Flag<any>) => Block;
-  edit: (value: FieldInput, action: ActionInput, options?: {
+  flag: (flag: Flag) => Block;
+  edit: (value: FieldInput, action: ActionTarget, options?: {
     record?: string;
     field?: string;
   }) => FieldValue;
@@ -827,14 +827,34 @@ interface Config extends Located {
 }
 export declare function defineConfig(options: ConfigOptions): Config;
 //#endregion
-//#region src/define/role.d.ts
+//#region src/define/console/page.d.ts
+type Params<P> = P extends AnySchema ? InferOutput<P> : Record<string, never>;
+interface PageContext<P> {
+  params: P;
+  actor: Actor;
+}
+type PageContent<P> = BlockInput[] | ((context: PageContext<Params<P>>) => Awaitable<BlockInput[]>);
+interface PageOptions<P extends AnySchema | undefined> {
+  label?: string;
+  icon?: string;
+  params?: P;
+  render: PageContent<P>;
+}
+interface Page extends Located {
+  readonly name: string;
+  readonly options: PageOptions<any>;
+}
+export declare function page<P extends AnySchema | undefined = undefined>(name: string, options: PageOptions<P>): Page;
+export declare function home<P extends AnySchema | undefined = undefined>(options: PageContent<P> | PageOptions<P>): Page;
+//#endregion
+//#region src/define/console/role.d.ts
 interface RoleOptions {
   label?: string;
   inboxes?: Inbox[];
   resources?: Resource[];
   actions?: ActionRef[];
   pages?: Page[];
-  flags?: Flag<any>[];
+  flags?: Flag[];
   reveal?: boolean;
   status?: boolean;
 }
@@ -844,7 +864,24 @@ interface Role extends Located {
 }
 export declare function role(name: string, options: RoleOptions): Role;
 //#endregion
-//#region src/define/notify.d.ts
+//#region src/define/console/space.d.ts
+interface SpaceOptions {
+  label?: string;
+  icon?: string;
+  home?: Page | PageContent<undefined>;
+  inboxes?: Inbox[];
+  resources?: Resource[];
+  pages?: Page[];
+  flags?: Flag[];
+}
+interface Space extends Located {
+  readonly name: string;
+  readonly options: SpaceOptions;
+  readonly home: Page | null;
+}
+export declare function space(name: string, options: SpaceOptions): Space;
+//#endregion
+//#region src/define/inbox/notify.d.ts
 interface Channel {
   readonly channel: string;
 }
@@ -860,7 +897,7 @@ interface Notify extends Located {
 }
 export declare function notify(name: string, options: NotifyOptions): Notify;
 //#endregion
-//#region src/define/status.d.ts
+//#region src/define/controls/status.d.ts
 interface StatusComponent {
   label: string;
   description?: string;
@@ -884,12 +921,6 @@ interface Status extends Located {
 }
 export declare function status(options: StatusOptions): Status;
 //#endregion
-//#region src/client/dispatch.d.ts
-interface Project {
-  manifest: Manifest;
-  modules: Record<string, () => Promise<Record<string, unknown>>>;
-}
-//#endregion
 //#region src/client/transport.d.ts
 type Fetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 export declare class PultError extends Error {
@@ -898,32 +929,42 @@ export declare class PultError extends Error {
   constructor(message: string, status: number, code?: string | undefined);
 }
 //#endregion
+//#region src/client/dispatch.d.ts
+interface Project<Component extends string = string> {
+  manifest: Manifest<Component>;
+  modules: Record<string, () => Promise<Record<string, unknown>>>;
+}
+//#endregion
 //#region src/client/socket.d.ts
 interface Connection {
   close(): void;
 }
 //#endregion
 //#region src/client/pult.d.ts
-interface PultOptions {
+interface PultOptions<Component extends string = string> {
   key?: string;
-  project: Project;
+  project: Project<Component>;
   url?: string;
   fetch?: Fetch;
 }
-interface SendOptions<S extends Schema | undefined> {
+interface Suggestion<S = any> {
+  action: Action<any, S>;
+  input?: Prefill<S>;
+  reason?: string;
+}
+interface SendOptions<S extends Schema | undefined, Suggested extends unknown[] = unknown[]> {
   title?: string;
   fingerprint?: string;
   record?: string;
   data: InboxInput<S>;
   tags?: string[];
-  suggest?: {
-    action: ActionRef;
-    input?: Record<string, unknown>;
-    reason?: string;
-  }[];
+  suggest?: { [K in keyof Suggested]: Suggestion<Suggested[K]>; };
+}
+interface ListenOptions {
+  onStatus?: (status: "connected" | "disconnected") => void;
 }
-export declare function createPult({ key, project, url, fetch }: PultOptions): {
-  send: <S extends Schema | undefined>(inbox: Inbox<S>, item: SendOptions<S>) => Promise<SendResult>;
+export declare function createPult<Component extends string = string>({ key, project, url, fetch }: PultOptions<Component>): {
+  send: <S extends Schema | undefined, Suggested extends unknown[]>(inbox: Inbox<S>, item: SendOptions<S, Suggested>) => Promise<SendResult>;
   log: (resource: Resource, id: string, text: string, options?: {
     blocks?: BlockInput[];
     by?: string;
@@ -933,11 +974,9 @@ export declare function createPult({ key, project, url, fetch }: PultOptions): {
   } | null>;
   flag: <T, A>(definition: Flag<T, A>, context?: string | FlagContext<A>) => Promise<T>;
   status: {
-    set(component: string, state: ComponentState): Promise<void>;
+    set(component: Component, state: ComponentState): Promise<void>;
   };
-  listen: (options?: {
-    onStatus?: (status: "connected" | "disconnected") => void;
-  }) => Connection;
+  listen: (options?: ListenOptions) => Connection;
   handler: () => (request: Request, context?: {
     waitUntil(work: Promise<unknown>): void;
   }) => Promise<Response>;
@@ -947,4 +986,4 @@ export declare function createPult({ key, project, url, fetch }: PultOptions): {
 };
 type Pult = ReturnType<typeof createPult>;
 //#endregion
-export type { Action, ActionContext, Actor, Block, Channel, ComponentState, Config, Duration, Flag, Inbox, ItemView, ListQuery, Manifest, Notify, OutgoingEmail, Page, PageContext, Project, Pult, Relation, Resource, Role, SendOptions, SendResult, StateChange, Status, View };
+export type { Action, ActionContext, ActionOptions, ActionRef, Actor, Block, BlockInput, ButtonInput, Channel, ComponentState, Config, ConfigOptions, Duration, FieldInput, Flag, FlagContext, FlagOptions, Guard, Inbox, InboxOptions, ItemView, ListOptions, ListQuery, ListenOptions, Manifest, Notify, NotifyOptions, OutgoingEmail, Page, PageContext, PageOptions, Project, Pult, PultOptions, Question, Relation, Resource, ResourceOptions, Role, RoleOptions, Rule, SendOptions, SendResult, Space, SpaceOptions, StandaloneOptions, StateChange, Status, StatusOptions, Suggestion, Triage, View, ViewOptions };