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

package/src/Action.ts

@@ -0,0 +1,370 @@
+/**
+ * Canonical action definition builders and types for the Dual SDK.
+ *
+ * @since 0.0.0
+ */
+import type { Context, Pipeable, SchemaIssue } from "effect";
+import {
+  Array,
+  DateTime,
+  Duration,
+  Effect,
+  Match,
+  Number,
+  Option,
+  pipe,
+  Predicate,
+  Schema,
+} from "effect";
+
+import { Headers, HttpClientError } from "effect/http";
+
+import type * as AuthMethod from "./AuthMethod.ts";
+import type { ContextForMethods } from "./internal/auth-context.ts";
+import { validateIdentifier } from "./internal/identifier.ts";
+import { PipeableProto } from "./internal/proto.ts";
+
+/**
+ * @since 0.0.0
+ * @category type ids
+ */
+export const TypeId = "@dual-os/sdk/Action" as const;
+
+/**
+ * @since 0.0.0
+ * @category type ids
+ */
+export type TypeId = typeof TypeId;
+
+/**
+ * Constraint type for working with any {@link Action}.
+ *
+ * @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 input: Schema.Top;
+  readonly output: Schema.Top;
+  readonly examples: readonly ActionExample<unknown>[];
+  readonly requireAuth: boolean;
+}
+
+/**
+ * Stable action metadata.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export interface ActionOptions {
+  readonly name?: string | undefined;
+  readonly description?: string | undefined;
+}
+
+/**
+ * Example input shown alongside an action definition.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export interface ActionExample<Input> {
+  readonly title?: string;
+  readonly input: Input;
+}
+
+/**
+ * Handler context exposed to an action implementation.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export type HandlerContext<EffectiveAuthMethods extends readonly AuthMethod.Any[]> =
+  ContextForMethods<EffectiveAuthMethods>;
+
+/**
+ * Non-retryable failure reported by a trusted action handler.
+ *
+ * The invoke boundary owns action/provider/version metadata, so handler errors
+ * intentionally describe only the failed operation itself.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export class ActionHandlerError extends Schema.TaggedError<ActionHandlerError>()(
+  "ActionHandlerError",
+  {
+    cause: Schema.optional(Schema.Defect()),
+    details: Schema.optional(Schema.Unknown),
+    message: Schema.String,
+    status: Schema.optional(Schema.Number),
+  },
+) {}
+
+/**
+ * Retryable failure reported by a trusted action handler.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export class RetryableActionHandlerError extends Schema.TaggedError<RetryableActionHandlerError>()(
+  "RetryableActionHandlerError",
+  {
+    cause: Schema.optional(Schema.Defect()),
+    details: Schema.optional(Schema.Unknown),
+    message: Schema.String,
+    retryAfterSeconds: Schema.optional(Schema.Number),
+    status: Schema.optional(Schema.Number),
+  },
+) {}
+
+/** @since 0.0.0 @category errors */
+export type ActionHandlerFailure = ActionHandlerError | RetryableActionHandlerError;
+
+/**
+ * Failures produced while an Effect HTTP client executes or decodes a request.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export type HttpClientFailure = HttpClientError.HttpClientError | Schema.SchemaError;
+
+/**
+ * A response the provider declared as an error, as a generated client raises it:
+ * the received response plus its decoded body.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export interface DeclaredResponseFailure {
+  readonly response: { readonly status: number; readonly headers: Headers.Headers };
+  readonly cause: unknown;
+}
+
+function retryAfterSeconds(headers?: Headers.Headers) {
+  return pipe(
+    Option.fromNullishOr(headers),
+    Option.flatMap(Headers.get("retry-after")),
+    Option.flatMap(value =>
+      Option.orElse(Number.parse(value), () =>
+        Option.map(DateTime.make(value), date =>
+          Duration.toSeconds(DateTime.distance(DateTime.nowUnsafe(), date)),
+        ),
+      ),
+    ),
+    Option.map(Number.clamp({ maximum: 3600, minimum: 0 })),
+    Option.getOrUndefined,
+  );
+}
+
+interface SchemaIssueAt {
+  readonly kind: string;
+  readonly path: ReadonlyArray<PropertyKey>;
+}
+
+// Where a response broke its schema and how, as issue tags only. Effect's formatters can quote
+// the received value, such as an unmatched union member, and failure details are stored with
+// the run, so the provider's data stays out of them.
+function schemaIssuesAt(
+  issue: SchemaIssue.Issue,
+  path: ReadonlyArray<PropertyKey>,
+): Array<SchemaIssueAt> {
+  return pipe(
+    Match.value(issue),
+    Match.tags({
+      AnyOf: anyOf =>
+        Array.match(anyOf.issues, {
+          onEmpty: () => [{ kind: anyOf._tag, path }],
+          onNonEmpty: issues => Array.flatMap(issues, inner => schemaIssuesAt(inner, path)),
+        }),
+      Composite: composite => Array.flatMap(composite.issues, inner => schemaIssuesAt(inner, path)),
+      Encoding: encoding => schemaIssuesAt(encoding.issue, path),
+      Pointer: pointer => schemaIssuesAt(pointer.issue, [...path, ...pointer.path]),
+    }),
+    Match.orElse(leaf => [{ kind: leaf._tag, path }]),
+  );
+}
+
+function schemaIssues(issue: SchemaIssue.Issue) {
+  return Array.map(schemaIssuesAt(issue, []), located => ({
+    kind: located.kind,
+    path: Array.filter(located.path, Predicate.or(Predicate.isString, Predicate.isNumber)),
+  }));
+}
+
+/**
+ * Map an Effect HTTP client failure to the action failure contract.
+ *
+ * Transport failures, rate limits, and server errors can be retried, carrying
+ * the provider's Retry-After delay (at most an hour) when the response sent
+ * one. Request construction, response decoding, declared client errors, and
+ * other client errors are terminal.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export const fromHttpClientFailure = (
+  error: HttpClientFailure | DeclaredResponseFailure,
+): ActionHandlerFailure => {
+  if (Schema.isSchemaError(error)) {
+    return new ActionHandlerError({
+      cause: error,
+      details: { issues: schemaIssues(error.issue), reason: "SchemaError" },
+      message: "HTTP response did not match the expected schema",
+    });
+  }
+  if (!HttpClientError.isHttpClientError(error)) {
+    const status = error.response.status;
+    const fields = {
+      details: error.cause,
+      message: `HTTP request failed with status ${status}`,
+      status,
+    };
+    return status === 429 || status >= 500
+      ? RetryableActionHandlerError.make({
+          ...fields,
+          retryAfterSeconds: retryAfterSeconds(error.response.headers),
+        })
+      : new ActionHandlerError(fields);
+  }
+
+  const status = error.response?.status;
+  const fields = {
+    message:
+      status === undefined ? "HTTP request failed" : `HTTP request failed with status ${status}`,
+    ...(status === undefined ? {} : { status }),
+    details: { method: error.request.method, reason: error.reason._tag },
+    cause: error,
+  };
+
+  return error.reason._tag === "TransportError" ||
+    status === 429 ||
+    (status !== undefined && status >= 500)
+    ? RetryableActionHandlerError.make({
+        ...fields,
+        retryAfterSeconds: retryAfterSeconds(error.response?.headers),
+      })
+    : new ActionHandlerError(fields);
+};
+
+/**
+ * Map an Effect HTTP client effect onto the action failure contract.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export const orHttpClientFailure = <A, R>(
+  effect: Effect.Effect<A, HttpClientFailure | DeclaredResponseFailure, R>,
+): Effect.Effect<A, ActionHandlerFailure, R> => Effect.mapError(effect, fromHttpClientFailure);
+
+/**
+ * A runtime handler service for one canonical action id.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export interface Handler<ActionId extends string = string> {
+  readonly _: unique symbol;
+  readonly actionId: ActionId;
+  readonly context: Context.Context<never>;
+  readonly handler: (
+    input: unknown,
+    context: unknown,
+  ) => Effect.Effect<unknown, ActionHandlerFailure, unknown>;
+}
+
+/**
+ * Context key used for the action handler with the supplied canonical id.
+ *
+ * @since 0.0.0
+ * @category handlers
+ */
+export const handlerKey = (actionId: string): string => `@dual-os/sdk/Action/Handler/${actionId}`;
+
+/**
+ * Options used to declare an action contract.
+ *
+ * @since 0.6.0
+ * @category models
+ */
+export interface ContractOptions<
+  Input extends Schema.Top,
+  Output extends Schema.Top,
+  RequireAuth extends boolean,
+> extends ActionOptions {
+  readonly input: Input;
+  readonly output: Output;
+  readonly examples?: readonly ActionExample<Schema.Schema.Type<Input>>[];
+  /** Set to `false` to make a connection optional for this action. */
+  readonly requireAuth?: RequireAuth;
+}
+
+/**
+ * A typed action declaration.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export interface Action<
+  out Identifier extends string = string,
+  out Input extends Schema.Top = Schema.Top,
+  out Output extends Schema.Top = Schema.Top,
+  out RequireAuth extends boolean = boolean,
+>
+  extends Pipeable.Pipeable {
+  readonly [TypeId]: TypeId;
+  readonly identifier: Identifier;
+  readonly name: string | undefined;
+  readonly description: string | undefined;
+  readonly input: Input;
+  readonly output: Output;
+  readonly examples: readonly ActionExample<Schema.Schema.Type<Input>>[];
+  readonly requireAuth: RequireAuth;
+}
+
+export type InputSchema<ActionDef extends Any> = ActionDef["input"];
+
+export type OutputSchema<ActionDef extends Any> = ActionDef["output"];
+
+export type Input<ActionDef extends Any> = Schema.Schema.Type<InputSchema<ActionDef>>;
+
+export type Output<ActionDef extends Any> = Schema.Schema.Type<OutputSchema<ActionDef>>;
+
+const Proto = { ...PipeableProto, [TypeId]: TypeId };
+
+/**
+ * Create an {@link Action} from its contract.
+ *
+ * @since 0.0.0
+ * @category constructors
+ */
+export const make = <
+  const Identifier extends string,
+  Input extends Schema.Top,
+  Output extends Schema.Top,
+  const RequireAuth extends boolean = true,
+>(
+  identifier: Identifier,
+  options: ContractOptions<Input, Output, RequireAuth>,
+): Action<Identifier, Input, Output, RequireAuth> => {
+  validateIdentifier("action", identifier);
+  return Object.assign(Object.create(Proto), {
+    description: options.description,
+    examples: options.examples ?? [],
+    identifier,
+    input: options.input,
+    name: options.name,
+    output: options.output,
+    requireAuth: options.requireAuth ?? true,
+  });
+};
+
+/**
+ * Check if a value is an {@link Action}.
+ *
+ * @since 0.0.0
+ * @category guards
+ */
+export const isAction = (u: unknown): u is Any => Predicate.hasProperty(u, TypeId);