@dual-os/sdk 0.0.0-stage → 0.8.0-next.0

package/src/internal/plugin-handlers.ts

@@ -0,0 +1,146 @@
+/** Plugin handler services and their registration. */
+import { Context, Effect, Predicate } from "effect";
+
+import * as Action from "../Action.ts";
+import * as AgentChannel from "../AgentChannel.ts";
+import type * as AuthMethod from "../AuthMethod.ts";
+import type * as Group from "../Group.ts";
+import type { Any } from "../Plugin.ts";
+import * as Trigger from "../Trigger.ts";
+
+import { walkCapabilities } from "./capabilities.ts";
+import { handlerGroupKey, withoutGroups } from "./handler-context.ts";
+import { MachineIdSeparator } from "./identifier.ts";
+import type { IsGenericArray, JoinPrefix } from "./types.ts";
+
+type LocalTriggerEntriesFromTriggers<
+  Triggers extends readonly Trigger.Any[],
+  Prefix extends string,
+  AllowedMethods extends readonly AuthMethod.Any[],
+> = Triggers[number] extends infer TriggerDef
+  ? TriggerDef extends Trigger.Any
+    ? {
+        readonly localId: JoinPrefix<Prefix, TriggerDef["identifier"]>;
+        readonly trigger: TriggerDef;
+        readonly authMethods: AllowedMethods;
+      }
+    : never
+  : never;
+
+type LocalTriggerEntriesFromGroups<
+  GroupDef extends Group.Any,
+  Prefix extends string,
+  AllowedMethods extends readonly AuthMethod.Any[],
+> = GroupDef extends unknown
+  ?
+      | LocalTriggerEntriesFromTriggers<
+          GroupDef["triggers"],
+          JoinPrefix<Prefix, GroupDef["identifier"]>,
+          AllowedMethods
+        >
+      | (IsGenericArray<GroupDef["groups"]> extends true
+          ? LocalTriggerEntriesFromTriggers<readonly Trigger.Any[], string, AllowedMethods>
+          : LocalTriggerEntriesFromGroups<
+              GroupDef["groups"][number],
+              JoinPrefix<Prefix, GroupDef["identifier"]>,
+              AllowedMethods
+            >)
+  : never;
+
+export type LocalTriggerEntries<P extends Any> =
+  | LocalTriggerEntriesFromTriggers<P["triggers"], "", P["authMethods"]>
+  | LocalTriggerEntriesFromGroups<P["groups"][number], "", P["authMethods"]>;
+
+export type CanonicalTriggerId<
+  P extends Any,
+  LocalId extends string,
+> = `${P["identifier"]}${typeof MachineIdSeparator}${LocalId}`;
+
+/** Keyed by the plugin's capabilities, which `Plugin.provide` keeps, so a Layer serves only them. */
+export interface ActionHandlerService<
+  in out PluginId extends string,
+  in out Actions extends readonly unknown[],
+  in out Groups extends readonly unknown[],
+> {
+  readonly _: unique symbol;
+  readonly pluginId: PluginId;
+  readonly actions: Actions;
+  readonly groups: Groups;
+}
+
+export type ActionHandlerServiceOf<P extends Any> = ActionHandlerService<
+  P["identifier"],
+  P["actions"],
+  P["groups"]
+>;
+
+export type HandlerServices<P extends Any> =
+  | ActionHandlerServiceOf<P>
+  | ([P["agentChannels"][number]] extends [never]
+      ? never
+      : AgentChannel.Handler<`${P["identifier"]}/${P["agentChannels"][number]["identifier"]}`>)
+  | (LocalTriggerEntries<P> extends infer Entry
+      ? Entry extends { readonly localId: infer LocalId extends string }
+        ? Trigger.Handler<CanonicalTriggerId<P, LocalId>>
+        : never
+      : never);
+
+interface Declarations {
+  readonly actions: unknown;
+  readonly triggers: unknown;
+  readonly agentChannels: unknown;
+}
+
+/* Missing handler declarations are builder defects, not expected failures, so
+   they intentionally throw instead of entering the Effect failure channel. */
+const missingDeclaration = (kind: string, localId: string, pluginId: string): never => {
+  throw new Error(`missing ${kind} handler for "${localId}" in plugin "${pluginId}"`);
+};
+
+const getNestedHandler = (handlers: unknown, localId: string): unknown => {
+  let current = handlers;
+  for (const segment of localId.split(MachineIdSeparator)) {
+    if (!Predicate.hasProperty(current, segment)) return undefined;
+    current = current[segment];
+  }
+  return current;
+};
+
+/** Register a plugin's handlers as one Context group keyed by the plugin. */
+export const toHandlers = (
+  plugin: Any,
+  handlers: Declarations,
+): Effect.Effect<Context.Context<never>> =>
+  Effect.gen(function* () {
+    const services = withoutGroups(yield* Effect.context());
+    const map = new Map<string, unknown>();
+    // A declared but invalid handler, such as `null` from JavaScript, fails when it is used.
+    const find = (kind: string, declarations: unknown, localId: string) => {
+      const handler = getNestedHandler(declarations, localId);
+      return handler === undefined ? missingDeclaration(kind, localId, plugin.identifier) : handler;
+    };
+
+    for (const entry of walkCapabilities(plugin, owner => owner.actions)) {
+      map.set(Action.handlerKey(entry.canonicalId), {
+        actionId: entry.canonicalId,
+        context: services,
+        handler: find("action", handlers.actions, entry.localId),
+      });
+    }
+    for (const entry of walkCapabilities(plugin, owner => owner.triggers)) {
+      map.set(Trigger.handlerKey(entry.canonicalId), {
+        context: services,
+        runtime: find("trigger", handlers.triggers, entry.localId),
+        triggerId: entry.canonicalId,
+      });
+    }
+    for (const channel of plugin.agentChannels) {
+      const channelId = `${plugin.identifier}/${channel.identifier}`;
+      map.set(AgentChannel.handlerKey(channelId), {
+        channelId,
+        context: services,
+        runtime: find("agent channel", handlers.agentChannels, channel.identifier),
+      });
+    }
+    return Context.makeUnsafe(new Map([[handlerGroupKey(plugin.identifier), map]]));
+  });

package/src/internal/proto.ts

@@ -0,0 +1,8 @@
+import { Pipeable } from "effect";
+
+/** Shared prototype mixin for all SDK definition objects. */
+export const PipeableProto = {
+  pipe() {
+    return Pipeable.pipeArguments(this, arguments);
+  },
+};

package/src/internal/schema-runtime.ts

@@ -0,0 +1,15 @@
+import { Effect, Schema } from "effect";
+
+export function decodeJson<SchemaDef extends Schema.Top>(
+  schema: SchemaDef,
+  value: unknown,
+): Effect.Effect<SchemaDef["Type"], Schema.SchemaError, SchemaDef["DecodingServices"]> {
+  return Schema.decodeUnknownEffect(Schema.toCodecJson(schema))(value);
+}
+
+export const decodeJsonMapError = <SchemaDef extends Schema.Top, Error>(
+  schema: SchemaDef,
+  value: unknown,
+  mapError: (error: Schema.SchemaError) => Error,
+): Effect.Effect<SchemaDef["Type"], Error, SchemaDef["DecodingServices"]> =>
+  decodeJson(schema, value).pipe(Effect.mapError(mapError));

package/src/internal/trigger-runtime-shared.ts

@@ -0,0 +1,449 @@
+import type { Context } from "effect";
+import { Effect, Schema } from "effect";
+
+import type { ConnectionResolutionContext, Service } from "../ConnectionResolver.ts";
+import * as Trigger from "../Trigger.ts";
+
+import {
+  authRuntimeContext,
+  noAuthRuntimeContext,
+  failConnectionIdNotAllowed,
+  resolveRuntimeConnection,
+  type AuthResolutionRequirements,
+  type AuthSchemaRequirements,
+  type RuntimeConnectionErrorsFor,
+  toNonEmptyArray,
+} from "./auth-execution.ts";
+import { findHandler } from "./handler-context.ts";
+import { decodeJson, decodeJsonMapError } from "./schema-runtime.ts";
+
+type ConfigRequirements<TriggerDef extends Trigger.Any> =
+  Trigger.ConfigSchema<TriggerDef>["DecodingServices"];
+
+type StateDecodingRequirements<TriggerDef extends Trigger.Any> =
+  Trigger.StateSchema<TriggerDef> extends Schema.Top
+    ? Exclude<Trigger.StateSchema<TriggerDef>, undefined>["DecodingServices"]
+    : never;
+
+type StateEncodingRequirements<TriggerDef extends Trigger.Any> =
+  Trigger.StateSchema<TriggerDef> extends Schema.Top
+    ? Exclude<Trigger.StateSchema<TriggerDef>, undefined>["EncodingServices"]
+    : never;
+
+type OutputEncodingRequirements<TriggerDef extends Trigger.Any> =
+  Trigger.OutputSchema<TriggerDef>["EncodingServices"];
+
+/**
+ * Trigger hooks may fail with arbitrary app-defined errors, so phase failures
+ * deliberately widen to `unknown`. The alias keeps that decision visible in
+ * the phase signatures.
+ */
+export type TriggerAppError<_TriggerDef extends Trigger.Any> = unknown;
+
+export type TriggerEncodedState<TriggerDef extends Trigger.Any> =
+  Trigger.StateSchema<TriggerDef> extends Schema.Top
+    ? Exclude<Trigger.StateSchema<TriggerDef>, undefined>["Encoded"] | undefined
+    : undefined;
+
+export type TriggerEncodedOutput<TriggerDef extends Trigger.Any> =
+  Trigger.OutputSchema<TriggerDef>["Encoded"];
+
+export type TriggerIdOf<Entry extends Trigger.RuntimeTriggerEntry<any, any, any, any>> =
+  Entry["triggerId"];
+export type EntryTrigger<Entry extends Trigger.RuntimeTriggerEntry<any, any, any, any>> =
+  Entry["trigger"];
+export type EntryAuthMethods<Entry extends Trigger.RuntimeTriggerEntry<any, any, any, any>> =
+  Entry["authMethods"];
+type EntryHandler<Entry extends Trigger.RuntimeTriggerEntry<any, any, any, any>> = Trigger.Handler<
+  TriggerIdOf<Entry>
+>;
+
+export type TriggerRuntimeRequirements<
+  Entry extends Trigger.RuntimeTriggerEntry<any, any, any, any>,
+  Phase extends Trigger.RuntimePhase,
+> =
+  | EntryHandler<Entry>
+  | ConfigRequirements<EntryTrigger<Entry>>
+  | StateDecodingRequirements<EntryTrigger<Entry>>
+  | (Phase extends "activate" | "verify" | "parse" | "poll"
+      ? StateEncodingRequirements<EntryTrigger<Entry>>
+      : never)
+  | (Phase extends "parse" | "poll" ? OutputEncodingRequirements<EntryTrigger<Entry>> : never)
+  | ([EntryAuthMethods<Entry>[number]] extends [never]
+      ? never
+      :
+          | Service
+          | AuthSchemaRequirements<EntryAuthMethods<Entry>>
+          | AuthResolutionRequirements<EntryAuthMethods<Entry>>);
+
+export const decodeConfig = <Config extends Schema.Top>(
+  triggerId: string,
+  schema: Config,
+  value: unknown,
+): Effect.Effect<Config["Type"], Trigger.InvalidTriggerConfigError, Config["DecodingServices"]> =>
+  decodeJsonMapError(
+    schema,
+    value,
+    error => new Trigger.InvalidTriggerConfigError({ description: error.message, triggerId }),
+  );
+
+const decodeStateValue = (): Effect.Effect<undefined> => Effect.as(Effect.void, undefined);
+
+function decodeStateSchema<State extends Schema.Top>(
+  schema: State,
+  value: undefined,
+): Effect.Effect<State["Type"] | undefined>;
+function decodeStateSchema<State extends Schema.Top>(
+  schema: State,
+  value: unknown,
+): Effect.Effect<State["Type"] | undefined, Schema.SchemaError, State["DecodingServices"]>;
+function decodeStateSchema<State extends Schema.Top>(
+  schema: State,
+  value: unknown,
+): Effect.Effect<State["Type"] | undefined, Schema.SchemaError, State["DecodingServices"]> {
+  if (value === undefined) {
+    return decodeStateValue();
+  }
+
+  return decodeJson(schema, value);
+}
+
+export function decodeState(
+  triggerId: string,
+  phase: Trigger.RuntimePhase,
+  schema: undefined,
+  value: unknown,
+): Effect.Effect<undefined, Trigger.InvalidTriggerStateError>;
+export function decodeState<State extends Schema.Top>(
+  triggerId: string,
+  phase: Trigger.RuntimePhase,
+  schema: State,
+  value: unknown,
+): Effect.Effect<
+  State["Type"] | undefined,
+  Trigger.InvalidTriggerStateError,
+  State["DecodingServices"]
+>;
+export function decodeState<State extends Schema.Top | undefined>(
+  triggerId: string,
+  phase: Trigger.RuntimePhase,
+  schema: State,
+  value: unknown,
+): Effect.Effect<unknown, Trigger.InvalidTriggerStateError, unknown> {
+  if (schema === undefined) {
+    return value === undefined
+      ? decodeStateValue()
+      : Effect.fail(
+          new Trigger.InvalidTriggerStateError({
+            description: "state is not supported for this trigger",
+            location: "input",
+            phase,
+            triggerId,
+          }),
+        );
+  }
+
+  return decodeStateSchema(schema, value).pipe(
+    Effect.mapError(
+      error =>
+        new Trigger.InvalidTriggerStateError({
+          description: error.message,
+          location: "input",
+          phase,
+          triggerId,
+        }),
+    ),
+  );
+}
+
+const encodeStateSchema = <State extends Schema.Top>(
+  triggerId: string,
+  phase: Trigger.RuntimePhase,
+  schema: State,
+  value: State["Type"] | undefined,
+): Effect.Effect<
+  State["Encoded"] | undefined,
+  Trigger.InvalidTriggerStateError,
+  State["EncodingServices"]
+> => {
+  if (value === undefined) {
+    return Effect.void;
+  }
+
+  return Schema.encodeEffect(schema)(value).pipe(
+    Effect.mapError(
+      error =>
+        new Trigger.InvalidTriggerStateError({
+          description: error.message,
+          location: "result",
+          phase,
+          triggerId,
+        }),
+    ),
+  );
+};
+
+export function validateStateResult(
+  triggerId: string,
+  phase: Trigger.RuntimePhase,
+  schema: undefined,
+  value: undefined,
+): Effect.Effect<undefined, Trigger.InvalidTriggerStateError>;
+export function validateStateResult<State extends Schema.Top>(
+  triggerId: string,
+  phase: Trigger.RuntimePhase,
+  schema: State,
+  value: State["Type"] | undefined,
+): Effect.Effect<
+  State["Encoded"] | undefined,
+  Trigger.InvalidTriggerStateError,
+  State["EncodingServices"]
+>;
+export function validateStateResult<State extends Schema.Top | undefined>(
+  triggerId: string,
+  phase: Trigger.RuntimePhase,
+  schema: State,
+  value: Trigger.StateValue<State>,
+): Effect.Effect<unknown, Trigger.InvalidTriggerStateError, unknown> {
+  if (schema === undefined) {
+    return value === undefined
+      ? decodeStateValue()
+      : Effect.fail(
+          new Trigger.InvalidTriggerStateError({
+            description: "state is not supported for this trigger",
+            location: "result",
+            phase,
+            triggerId,
+          }),
+        );
+  }
+
+  return encodeStateSchema(triggerId, phase, schema, value);
+}
+
+const KeyedEventEnvelope = Schema.Struct({ key: Schema.NonEmptyString, payload: Schema.Unknown });
+
+type KeyedEventEnvelope = typeof KeyedEventEnvelope.Type;
+
+const eventKeysAreUnique = (events: readonly KeyedEventEnvelope[]) => {
+  const seen = new Set<string>();
+  for (const event of events) {
+    if (seen.has(event.key)) {
+      return `duplicate event key "${event.key}"`;
+    }
+    seen.add(event.key);
+  }
+
+  return true;
+};
+
+const KeyedEventEnvelopes = Schema.Array(KeyedEventEnvelope).check(
+  Schema.makeFilter(eventKeysAreUnique),
+);
+
+const mapOutputError =
+  (triggerId: string, phase: "parse" | "poll") => (error: Schema.SchemaError) =>
+    new Trigger.InvalidTriggerOutputError({ description: error.message, phase, triggerId });
+
+export const validateOutputs = <Output extends Schema.Top>(
+  triggerId: string,
+  phase: "parse" | "poll",
+  schema: Output,
+  events: unknown,
+): Effect.Effect<
+  readonly Trigger.KeyedEvent<Output["Encoded"]>[],
+  Trigger.InvalidTriggerOutputError,
+  Output["EncodingServices"]
+> =>
+  Schema.decodeUnknownEffect(KeyedEventEnvelopes)(events).pipe(
+    Effect.flatMap(decodedEvents =>
+      Effect.forEach(decodedEvents, event =>
+        Schema.encodeEffect(schema)(event.payload).pipe(
+          Effect.flatMap(encoded => Schema.decodeUnknownEffect(Schema.Json)(encoded)),
+          Effect.map(payload => ({ key: event.key, payload: payload as Output["Encoded"] })),
+        ),
+      ),
+    ),
+    Effect.mapError(mapOutputError(triggerId, phase)),
+  );
+
+interface RuntimeHook<Hook> {
+  readonly hook: Hook;
+  readonly context: Context.Context<never>;
+}
+
+type WebhookPhase = "activate" | "deactivate" | "verify" | "parse";
+
+type WebhookHook<Phase extends WebhookPhase> = NonNullable<
+  Trigger.WebhookRuntime<Schema.Top, Schema.Top, Schema.Top | undefined, any, any, any>[Phase]
+>;
+
+type PollHook = NonNullable<
+  Trigger.PollingRuntime<Schema.Top, Schema.Top, Schema.Top | undefined, any, any, any>["poll"]
+>;
+
+const getTriggerHandler = <Entry extends Trigger.RuntimeTriggerEntry<any, any, any, any>>(
+  entry: Entry,
+): Effect.Effect<
+  EntryHandler<Entry>,
+  Trigger.UnsupportedTriggerRuntimeError,
+  EntryHandler<Entry>
+> =>
+  Effect.context<EntryHandler<Entry>>().pipe(
+    Effect.flatMap(context => {
+      const handler = findHandler(
+        context,
+        entry.providerId,
+        Trigger.handlerKey(entry.triggerId),
+      ) as EntryHandler<Entry> | undefined;
+
+      return handler === undefined
+        ? Effect.fail(
+            new Trigger.UnsupportedTriggerRuntimeError({
+              kind: entry.trigger.kind,
+              phase: entry.trigger.kind === "polling" ? "poll" : "parse",
+              triggerId: entry.triggerId,
+            }),
+          )
+        : Effect.succeed(handler);
+    }),
+  );
+
+export const requireWebhookHook = <
+  Entry extends Trigger.RuntimeTriggerEntry<any, any, any, any>,
+  Phase extends WebhookPhase,
+>(
+  entry: Entry,
+  phase: Phase,
+): Effect.Effect<
+  RuntimeHook<WebhookHook<Phase>>,
+  Trigger.UnsupportedTriggerRuntimeError,
+  EntryHandler<Entry>
+> => {
+  if (entry.trigger.kind !== "webhook") {
+    return Effect.fail(
+      new Trigger.UnsupportedTriggerRuntimeError({
+        kind: entry.trigger.kind,
+        phase,
+        triggerId: entry.triggerId,
+      }),
+    );
+  }
+
+  return getTriggerHandler(entry).pipe(
+    Effect.flatMap(handler => {
+      const hook = (handler.runtime as Trigger.WebhookRuntime<any, any, any, any, any, any>)[phase];
+
+      if (hook === undefined) {
+        return Effect.fail(
+          new Trigger.UnsupportedTriggerRuntimeError({
+            kind: entry.trigger.kind,
+            phase,
+            triggerId: entry.triggerId,
+          }),
+        );
+      }
+
+      return Effect.succeed({ context: handler.context, hook } as RuntimeHook<WebhookHook<Phase>>);
+    }),
+  );
+};
+
+export const requirePollingHook = <Entry extends Trigger.RuntimeTriggerEntry<any, any, any, any>>(
+  entry: Entry,
+): Effect.Effect<
+  RuntimeHook<PollHook>,
+  Trigger.UnsupportedTriggerRuntimeError,
+  EntryHandler<Entry>
+> => {
+  if (entry.trigger.kind !== "polling") {
+    return Effect.fail(
+      new Trigger.UnsupportedTriggerRuntimeError({
+        kind: entry.trigger.kind,
+        phase: "poll",
+        triggerId: entry.triggerId,
+      }),
+    );
+  }
+
+  return getTriggerHandler(entry).pipe(
+    Effect.flatMap(handler => {
+      const hook = (handler.runtime as Trigger.PollingRuntime<any, any, any, any, any, any>).poll;
+
+      if (hook === undefined) {
+        return Effect.fail(
+          new Trigger.UnsupportedTriggerRuntimeError({
+            kind: entry.trigger.kind,
+            phase: "poll",
+            triggerId: entry.triggerId,
+          }),
+        );
+      }
+
+      return Effect.succeed({ context: handler.context, hook } as RuntimeHook<PollHook>);
+    }),
+  );
+};
+
+export const withRuntimeContext: <
+  Entry extends Trigger.RuntimeTriggerEntry<any, any, any, any>,
+  Phase extends Trigger.RuntimePhase,
+  Result,
+>(
+  entry: Entry,
+  phase: Phase,
+  connectionId: string | undefined,
+  context: ConnectionResolutionContext | undefined,
+  run: (
+    context: Trigger.RuntimeContext<EntryAuthMethods<Entry>>,
+  ) => Effect.Effect<
+    Result,
+    TriggerAppError<EntryTrigger<Entry>> | RuntimeConnectionErrorsFor<EntryAuthMethods<Entry>>,
+    TriggerRuntimeRequirements<Entry, Phase>
+  >,
+) => Effect.Effect<
+  Result,
+  TriggerAppError<EntryTrigger<Entry>> | RuntimeConnectionErrorsFor<EntryAuthMethods<Entry>>,
+  TriggerRuntimeRequirements<Entry, Phase>
+> = (
+  entry: Trigger.RuntimeTriggerEntry,
+  phase: Trigger.RuntimePhase,
+  connectionId: string | undefined,
+  context: ConnectionResolutionContext | undefined,
+  run: (context: never) => Effect.Effect<unknown, unknown, unknown>,
+) => {
+  const requiredAuthMethods = toNonEmptyArray(entry.authMethods);
+  const runtimeContext = <AuthContext extends object>(authContext: AuthContext) =>
+    context === undefined ? authContext : ({ ...context, ...authContext } as const);
+
+  if (requiredAuthMethods === undefined) {
+    if (connectionId !== undefined) {
+      return failConnectionIdNotAllowed(
+        "trigger",
+        entry.triggerId,
+        phase,
+        entry.providerId,
+        connectionId,
+      );
+    }
+
+    return run(runtimeContext(noAuthRuntimeContext()) as never) as never;
+  }
+
+  // Only an explicit false skips auth for definitions built outside the SDK.
+  if (entry.trigger.requireAuth === false && connectionId === undefined) {
+    return run(runtimeContext(noAuthRuntimeContext()) as never) as never;
+  }
+
+  return resolveRuntimeConnection(
+    "trigger",
+    entry.triggerId,
+    phase,
+    entry.providerId,
+    requiredAuthMethods,
+    connectionId,
+    context,
+  ).pipe(
+    Effect.flatMap(binding => run(runtimeContext(authRuntimeContext(binding)) as never)),
+  ) as never;
+};