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

package/src/Files.ts

@@ -0,0 +1,89 @@
+/**
+ * Files that actions take and return: a small reference in action data, with the bytes kept by the
+ * host and read or written through the host's file service.
+ *
+ * @since 0.1.0
+ */
+import { Context, Effect, Schema, pipe } from "effect";
+
+/**
+ * A file stored by the host. Action inputs and outputs carry this reference, never the bytes.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export type File = typeof File.Type;
+export const File = Schema.TaggedStruct("File", {
+  contentType: Schema.String,
+  id: Schema.NonEmptyString,
+  name: Schema.String,
+  sizeBytes: Schema.Natural,
+}).annotate({
+  description: "A file: pass the reference a file input or an earlier step returned.",
+});
+
+/**
+ * A file the host could not read or keep. The message is safe for callers; an optional cause
+ * retains the host failure in memory for trusted diagnostics. Wrap causes with Redacted.make
+ * without a provider-derived label. JSON schema encoding of a cause is intentionally refused.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export class FileError extends Schema.TaggedError<FileError>()("FileError", {
+  cause: Schema.optionalKey(Schema.Redacted(Schema.Unknown, { disallowJsonEncode: true })),
+  message: Schema.String,
+}) {}
+
+/**
+ * Reads and stores files for the caller of an action: a workflow run, or the person in a chat.
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export class Service extends Context.Service<
+  Service,
+  {
+    readonly read: (file: File) => Effect.Effect<Uint8Array, FileError>;
+    readonly write: (file: {
+      bytes: Uint8Array;
+      name: string;
+      // oxlint-disable-next-line typescript/no-restricted-types -- Hosts and existing callers may explicitly supply an absent content type.
+      contentType?: string | null | undefined;
+    }) => Effect.Effect<File, FileError>;
+  }
+>()("@dual-os/sdk/Files/Service") {}
+
+// Dual provides the service to each action call, so an action declares no requirement for it.
+const service = pipe(
+  Effect.serviceOption(Service),
+  Effect.flatMap(
+    Effect.fromOption(() =>
+      FileError.make({ message: "Files are only available when Dual calls the action" }),
+    ),
+  ),
+);
+
+/**
+ * Reads a file's bytes through the caller's file service.
+ *
+ * @since 0.1.0
+ * @category files
+ */
+export const read = Effect.fnUntraced(function* (file: File) {
+  return yield* (yield* service).read(file);
+});
+
+/**
+ * Stores bytes as a new file of the caller and returns its reference.
+ *
+ * @since 0.1.0
+ * @category files
+ */
+export const write = Effect.fnUntraced(function* (
+  file: Parameters<Service["Service"]["write"]>[0],
+) {
+  return yield* (yield* service).write(file);
+});
+
+export * as Files from "./Files.ts";

package/src/Group.ts

@@ -0,0 +1,292 @@
+/**
+ * Canonical group definition builders and types for the Dual SDK.
+ *
+ * Groups are structural namespaces nested beneath providers or other groups.
+ *
+ * @since 0.0.0
+ */
+import type { Pipeable } from "effect";
+import { Function as Func, Predicate } from "effect";
+
+import type * as Action from "./Action.ts";
+import {
+  assertUniqueMixedChildIdentifiers,
+  assertUniqueStructuralChildIdentifiers,
+  type FilterChildren,
+  partitionChildren,
+  type StructuralChildKind,
+} from "./internal/children.ts";
+import { appendElements } from "./internal/collection-utils.ts";
+import { validateIdentifier } from "./internal/identifier.ts";
+import { PipeableProto } from "./internal/proto.ts";
+import type * as Trigger from "./Trigger.ts";
+
+/** @since 0.0.0 @category type ids */
+export const TypeId = "@dual-os/sdk/Group" as const;
+/** @since 0.0.0 @category type ids */
+export type TypeId = typeof TypeId;
+
+/** @since 0.0.0 @category type-level */
+export interface Any extends Pipeable.Pipeable {
+  readonly [TypeId]: TypeId;
+  readonly identifier: string;
+  readonly name: string | undefined;
+  readonly description: string | undefined;
+  readonly groups: readonly Any[];
+  readonly actions: readonly Action.Any[];
+  readonly triggers: readonly Trigger.Any[];
+}
+
+/** @since 0.0.0 @category models */
+export interface GroupOptions<Identifier extends string = string> {
+  readonly identifier: Identifier;
+  readonly name?: string;
+  readonly description?: string;
+}
+
+/** @since 0.0.0 @category models */
+export interface Group<
+  out Identifier extends string = string,
+  out Groups extends readonly Any[] = readonly [],
+  out Actions extends readonly Action.Any[] = readonly [],
+  out Triggers extends readonly Trigger.Any[] = readonly [],
+>
+  extends Pipeable.Pipeable {
+  readonly [TypeId]: TypeId;
+  readonly identifier: Identifier;
+  readonly name: string | undefined;
+  readonly description: string | undefined;
+  readonly groups: Groups;
+  readonly actions: Actions;
+  readonly triggers: Triggers;
+}
+
+export type StructuralChild = Any | Action.Any | Trigger.Any;
+
+export type GroupsFromChildren<Children extends readonly StructuralChild[]> = FilterChildren<
+  Children,
+  Any
+>;
+
+export type ActionsFromChildren<Children extends readonly StructuralChild[]> = FilterChildren<
+  Children,
+  Action.Any
+>;
+
+export type TriggersFromChildren<Children extends readonly StructuralChild[]> = FilterChildren<
+  Children,
+  Trigger.Any
+>;
+
+/**
+ * Result of appending children to a group; shared by every child combinator so
+ * their overloads stay declarative.
+ *
+ * @since 0.0.0
+ * @category type-level
+ */
+export type AddChildren<
+  Self extends Any,
+  AddedGroups extends readonly Any[] = readonly [],
+  AddedActions extends readonly Action.Any[] = readonly [],
+  AddedTriggers extends readonly Trigger.Any[] = readonly [],
+> =
+  Self extends Group<infer Identifier, infer Groups, infer Actions, infer Triggers>
+    ? Group<
+        Identifier,
+        readonly [...Groups, ...AddedGroups],
+        readonly [...Actions, ...AddedActions],
+        readonly [...Triggers, ...AddedTriggers]
+      >
+    : never;
+
+const optionsFromGroup = (group: Any): GroupOptions => ({
+  identifier: group.identifier,
+  ...(group.name === undefined ? {} : { name: group.name }),
+  ...(group.description === undefined ? {} : { description: group.description }),
+});
+
+const Proto = { ...PipeableProto, [TypeId]: TypeId };
+
+const makeGroup = <
+  Identifier extends string,
+  Groups extends readonly Any[],
+  Actions extends readonly Action.Any[],
+  Triggers extends readonly Trigger.Any[],
+>(
+  options: GroupOptions<Identifier>,
+  groups: Groups,
+  actions: Actions,
+  triggers: Triggers,
+): Group<Identifier, Groups, Actions, Triggers> => {
+  validateIdentifier("group", options.identifier);
+
+  return Object.assign(Object.create(Proto), {
+    actions,
+    description: options.description,
+    groups,
+    identifier: options.identifier,
+    name: options.name,
+    triggers,
+  }) as Group<Identifier, Groups, Actions, Triggers>;
+};
+
+const appendChildren = (
+  group: Any,
+  children: readonly StructuralChild[],
+  childKind?: StructuralChildKind,
+): Any => {
+  if (childKind === undefined) {
+    assertUniqueMixedChildIdentifiers("group", group.identifier, group, children);
+  } else {
+    assertUniqueStructuralChildIdentifiers("group", group.identifier, group, children, childKind);
+  }
+
+  const partitioned = partitionChildren(children);
+  return makeGroup(
+    optionsFromGroup(group),
+    appendElements(group.groups, partitioned.groups),
+    appendElements(group.actions, partitioned.actions),
+    appendElements(group.triggers, partitioned.triggers),
+  );
+};
+
+/** @since 0.0.0 @category constructors */
+export const make = <const Identifier extends string>(identifier: Identifier): Group<Identifier> =>
+  makeGroup({ identifier }, [] as const, [] as const, [] as const);
+
+/** @since 0.0.0 @category guards */
+export const isGroup = (u: unknown): u is Any => Predicate.hasProperty(u, TypeId);
+
+/** @since 0.0.0 @category combinators */
+export const withName: {
+  (name: string): <G extends Group<any, any, any, any>>(group: G) => G;
+  <G extends Group<any, any, any, any>>(group: G, name: string): G;
+} = Func.dual(
+  2,
+  <G extends Group<any, any, any, any>>(group: G, name: string): G =>
+    makeGroup(
+      { ...optionsFromGroup(group), name },
+      group.groups,
+      group.actions,
+      group.triggers,
+    ) as G,
+);
+
+/** @since 0.0.0 @category combinators */
+export const withDescription: {
+  (description: string): <G extends Group<any, any, any, any>>(group: G) => G;
+  <G extends Group<any, any, any, any>>(group: G, description: string): G;
+} = Func.dual(
+  2,
+  <G extends Group<any, any, any, any>>(group: G, description: string): G =>
+    makeGroup(
+      { ...optionsFromGroup(group), description },
+      group.groups,
+      group.actions,
+      group.triggers,
+    ) as G,
+);
+
+/** @since 0.0.0 @category combinators */
+export const withGroups: {
+  <const AddedGroups extends readonly Any[]>(
+    groups: AddedGroups,
+  ): <Self extends Any>(group: Self) => AddChildren<Self, AddedGroups>;
+  <Self extends Any, const AddedGroups extends readonly Any[]>(
+    group: Self,
+    groups: AddedGroups,
+  ): AddChildren<Self, AddedGroups>;
+} = Func.dual(2, (group: Any, groups: readonly Any[]) => appendChildren(group, groups, "group"));
+
+/** @since 0.0.0 @category combinators */
+export const withActions: {
+  <const AddedActions extends readonly Action.Any[]>(
+    actions: AddedActions,
+  ): <Self extends Any>(group: Self) => AddChildren<Self, readonly [], AddedActions>;
+  <Self extends Any, const AddedActions extends readonly Action.Any[]>(
+    group: Self,
+    actions: AddedActions,
+  ): AddChildren<Self, readonly [], AddedActions>;
+} = Func.dual(2, (group: Any, actions: readonly Action.Any[]) =>
+  appendChildren(group, actions, "action"),
+);
+
+/** @since 0.0.0 @category combinators */
+export const withTriggers: {
+  <const AddedTriggers extends readonly Trigger.Any[]>(
+    triggers: AddedTriggers,
+  ): <Self extends Any>(group: Self) => AddChildren<Self, readonly [], readonly [], AddedTriggers>;
+  <Self extends Any, const AddedTriggers extends readonly Trigger.Any[]>(
+    group: Self,
+    triggers: AddedTriggers,
+  ): AddChildren<Self, readonly [], readonly [], AddedTriggers>;
+} = Func.dual(2, (group: Any, triggers: readonly Trigger.Any[]) =>
+  appendChildren(group, triggers, "trigger"),
+);
+
+/** @since 0.0.0 @category combinators */
+export const withGroup: {
+  <const AddedGroup extends Any>(
+    group: AddedGroup,
+  ): <Self extends Any>(value: Self) => AddChildren<Self, readonly [AddedGroup]>;
+  <Self extends Any, const AddedGroup extends Any>(
+    value: Self,
+    group: AddedGroup,
+  ): AddChildren<Self, readonly [AddedGroup]>;
+} = Func.dual(2, (value: Any, group: Any) => appendChildren(value, [group], "group"));
+
+/** @since 0.0.0 @category combinators */
+export const withAction: {
+  <const AddedAction extends Action.Any>(
+    action: AddedAction,
+  ): <Self extends Any>(value: Self) => AddChildren<Self, readonly [], readonly [AddedAction]>;
+  <Self extends Any, const AddedAction extends Action.Any>(
+    value: Self,
+    action: AddedAction,
+  ): AddChildren<Self, readonly [], readonly [AddedAction]>;
+} = Func.dual(2, (value: Any, action: Action.Any) => appendChildren(value, [action], "action"));
+
+/** @since 0.0.0 @category combinators */
+export const withTrigger: {
+  <const AddedTrigger extends Trigger.Any>(
+    trigger: AddedTrigger,
+  ): <Self extends Any>(
+    value: Self,
+  ) => AddChildren<Self, readonly [], readonly [], readonly [AddedTrigger]>;
+  <Self extends Any, const AddedTrigger extends Trigger.Any>(
+    value: Self,
+    trigger: AddedTrigger,
+  ): AddChildren<Self, readonly [], readonly [], readonly [AddedTrigger]>;
+} = Func.dual(2, (value: Any, trigger: Trigger.Any) => appendChildren(value, [trigger], "trigger"));
+
+/**
+ * Add mixed structural children to a group.
+ *
+ * @since 0.0.0
+ * @category combinators
+ */
+export const add: {
+  <const Children extends readonly StructuralChild[]>(
+    ...children: Children
+  ): <Self extends Any>(
+    group: Self,
+  ) => AddChildren<
+    Self,
+    GroupsFromChildren<Children>,
+    ActionsFromChildren<Children>,
+    TriggersFromChildren<Children>
+  >;
+  <Self extends Any, const Children extends readonly StructuralChild[]>(
+    group: Self,
+    ...children: Children
+  ): AddChildren<
+    Self,
+    GroupsFromChildren<Children>,
+    ActionsFromChildren<Children>,
+    TriggersFromChildren<Children>
+  >;
+} = Func.dual(
+  args => isGroup(args[0]),
+  (group: Any, ...children: readonly StructuralChild[]) => appendChildren(group, children),
+);