executor-app.d.ts

// Types for the "executor:app" module that Executor's publish pipeline
// provides at bundle time. Mirrors @executor-js/plugin-apps/authoring.
declare module "executor:app" {
  import type { StandardSchemaV1 } from "@standard-schema/spec";

  export type JsonPrimitive = string | number | boolean | null;
  export type JsonValue = JsonPrimitive | JsonObject | readonly JsonValue[];
  export interface JsonObject {
    readonly [key: string]: JsonValue;
  }

  export type ToolSchema<TOutput = unknown> = StandardSchemaV1<unknown, TOutput> | JsonObject;

  export type AppIntegrationClient = {
    readonly [key: string]: AppIntegrationClient;
  } & ((...args: readonly unknown[]) => Promise<unknown>);

  export type IntegrationMode = "one" | "many";

  export interface IntegrationDeclaration<
    Slug extends string = string,
    Mode extends IntegrationMode = IntegrationMode,
  > {
    readonly kind: "integration";
    readonly slug: Slug;
    readonly mode: Mode;
    readonly description?: string;
    readonly array: () => IntegrationDeclaration<Slug, "many">;
    readonly describe: (text: string) => IntegrationDeclaration<Slug, Mode>;
  }

  export type IntegrationDeclarations = Readonly<Record<string, IntegrationDeclaration>>;

  export type IntegrationClients<TIntegrations> =
    TIntegrations extends Readonly<Record<string, IntegrationDeclaration>>
      ? {
          readonly [K in keyof TIntegrations]: TIntegrations[K] extends {
            readonly mode: "many";
          }
            ? readonly AppIntegrationClient[]
            : AppIntegrationClient;
        }
      : Record<string, never>;

  export type InferToolInput<TSchema> = TSchema extends StandardSchemaV1
    ? StandardSchemaV1.InferOutput<TSchema>
    : unknown;

  export type InferToolOutput<TSchema> = TSchema extends StandardSchemaV1
    ? StandardSchemaV1.InferOutput<TSchema>
    : unknown;

  export interface DefineToolOptions<
    TInputSchema extends ToolSchema,
    TOutputSchema extends ToolSchema | undefined = undefined,
    TIntegrations extends IntegrationDeclarations | undefined = undefined,
  > {
    readonly description: string;
    readonly integrations?: TIntegrations;
    readonly input: TInputSchema;
    readonly output?: TOutputSchema;
    readonly annotations?: {
      readonly readOnly?: boolean;
      readonly destructive?: boolean;
      readonly requiresApproval?: boolean;
    };
    readonly handler: (
      input: InferToolInput<TInputSchema>,
      context: IntegrationClients<TIntegrations>,
    ) =>
      | Promise<TOutputSchema extends ToolSchema ? InferToolOutput<TOutputSchema> : unknown>
      | (TOutputSchema extends ToolSchema ? InferToolOutput<TOutputSchema> : unknown);
  }

  export interface DefinedTool<
    TInputSchema extends ToolSchema = ToolSchema,
    TOutputSchema extends ToolSchema | undefined = ToolSchema | undefined,
    TIntegrations extends IntegrationDeclarations | undefined = IntegrationDeclarations | undefined,
  > extends DefineToolOptions<TInputSchema, TOutputSchema, TIntegrations> {
    readonly "~executorAppTool": true;
  }

  export function integration<Slug extends string>(
    slug: Slug,
  ): IntegrationDeclaration<Slug, "one">;

  export function defineTool<
    TInputSchema extends ToolSchema,
    TOutputSchema extends ToolSchema | undefined = undefined,
    TIntegrations extends IntegrationDeclarations | undefined = undefined,
  >(
    options: DefineToolOptions<TInputSchema, TOutputSchema, TIntegrations>,
  ): DefinedTool<TInputSchema, TOutputSchema, TIntegrations>;
}