effect-inngest 0.1.0

package/src/Group.ts

@@ -0,0 +1,314 @@
+/**
+ * @since 0.1.0
+ */
+import * as HttpApp from "@effect/platform/HttpApp";
+import * as HttpClient from "@effect/platform/HttpClient";
+import * as HttpServerRequest from "@effect/platform/HttpServerRequest";
+import * as HttpServerResponse from "@effect/platform/HttpServerResponse";
+import * as UrlParams from "@effect/platform/UrlParams";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import type { InngestFunction } from "./Function.js";
+import { InngestClient } from "./Client.js";
+import * as InternalHandler from "./internal/handler.js";
+import * as Protocol from "./internal/protocol.js";
+import { SignatureLive } from "./internal/signature.js";
+
+import { type HandlerContext } from "./internal/step.js";
+
+/**
+ * Re-export HandlerContext from internal step module.
+ * @since 0.1.0
+ * @category models
+ */
+export { type HandlerContext };
+
+/**
+ * @since 0.1.0
+ * @category type ids
+ */
+export const TypeId: unique symbol = Symbol.for("effect-inngest/Group");
+
+/**
+ * @since 0.1.0
+ * @category type ids
+ */
+export type TypeId = typeof TypeId;
+
+/**
+ * @since 0.1.0
+ * @category models
+ */
+export type HandlerFn<F extends InngestFunction.Any> = (
+  context: HandlerContext<F>,
+) => Effect.Effect<InngestFunction.Success<F>, unknown, unknown>;
+
+/**
+ * @since 0.1.0
+ * @category models
+ */
+export type HandlersFrom<Fns extends InngestFunction.Any> = {
+  readonly [F in Fns as InngestFunction.Tag<F>]: HandlerFn<F>;
+};
+
+/**
+ * @since 0.1.0
+ * @category models
+ */
+export type HandlerFrom<Fns extends InngestFunction.Any, Tag extends InngestFunction.Tag<Fns>> =
+  Extract<Fns, { readonly _tag: Tag }> extends infer Current
+    ? Current extends InngestFunction.Any
+      ? HandlerFn<Current>
+      : never
+    : never;
+
+/**
+ * @since 0.1.0
+ * @category models
+ */
+export type HandlersRequirements<H> =
+  H extends Record<string, (...args: ReadonlyArray<unknown>) => Effect.Effect<unknown, unknown, infer R>> ? R : never;
+
+/**
+ * @since 0.1.0
+ * @category models
+ */
+export type HandlerRequirements<Handler> = Handler extends (
+  ...args: ReadonlyArray<unknown>
+) => Effect.Effect<unknown, unknown, infer R>
+  ? R
+  : never;
+
+/**
+ * A nominal type representing a registered handler for a specific function tag.
+ * @since 0.1.0
+ * @category models
+ */
+export interface Handler<Tag extends string> {
+  readonly _: unique symbol;
+  readonly tag: Tag;
+  readonly handler: (context: unknown) => Effect.Effect<unknown, unknown, unknown>;
+  readonly context: Context.Context<never>;
+}
+
+/**
+ * Maps a function to its Handler type.
+ * @since 0.1.0
+ * @category models
+ */
+export type ToHandler<F extends InngestFunction.Any> =
+  F extends InngestFunction<infer _Tag, infer _Triggers, infer _Success> ? Handler<_Tag> : never;
+
+/**
+ * @since 0.1.0
+ * @category models
+ */
+export interface InngestGroup<Fns extends InngestFunction.Any> {
+  readonly [TypeId]: TypeId;
+  readonly functions: ReadonlyMap<string, Fns>;
+
+  /**
+   * Implement all handlers for the functions in this group.
+   */
+  readonly toLayer: <H extends HandlersFrom<Fns>>(
+    handlers: H,
+  ) => Layer.Layer<ToHandler<Fns>, never, HandlersRequirements<H>>;
+
+  /**
+   * Implement a single handler from the group.
+   */
+  readonly toLayerHandler: <Tag extends InngestFunction.Tag<Fns>, H extends HandlerFrom<Fns, Tag>>(
+    tag: Tag,
+    handler: H,
+  ) => Layer.Layer<Handler<Tag>, never, HandlerRequirements<H>>;
+}
+
+/**
+ * @since 0.1.0
+ * @category models
+ */
+export declare namespace InngestGroup {
+  export type Any = InngestGroup<InngestFunction.Any>;
+  export type Functions<G> = G extends InngestGroup<infer Fns> ? Fns : never;
+  export type FunctionTags<G> = G extends InngestGroup<infer Fns> ? InngestFunction.Tag<Fns> : never;
+  export type Handlers<G> = G extends InngestGroup<infer Fns> ? HandlersFrom<Fns> : never;
+}
+
+const Proto = {
+  [TypeId]: TypeId,
+
+  toLayer(this: InngestGroup<InngestFunction.Any>, handlers: Record<string, unknown>) {
+    const functions = this.functions;
+    return Layer.effectContext(
+      Effect.gen(function* () {
+        const context = yield* Effect.context<never>();
+        const contextMap = new Map<string, unknown>();
+        for (const [tag, handler] of Object.entries(handlers)) {
+          const fn = functions.get(tag)!;
+          contextMap.set(fn.key, { handler, context });
+        }
+        return Context.unsafeMake(contextMap);
+      }),
+    );
+  },
+
+  toLayerHandler(this: InngestGroup<InngestFunction.Any>, tag: string, handler: unknown) {
+    const fn = this.functions.get(tag)!;
+    return Layer.effectContext(
+      Effect.gen(function* () {
+        const context = yield* Effect.context<never>();
+        const contextMap = new Map<string, unknown>();
+        contextMap.set(fn.key, { handler, context });
+        return Context.unsafeMake(contextMap);
+      }),
+    );
+  },
+};
+
+/**
+ * @since 0.1.0
+ * @category constructors
+ */
+export const make = <Fns extends ReadonlyArray<InngestFunction.Any>>(...fns: Fns): InngestGroup<Fns[number]> => {
+  const functions = new Map(fns.map((fn) => [fn._tag, fn]));
+  const group = Object.create(Proto);
+  group.functions = functions;
+  return group;
+};
+
+/**
+ * Build an HttpApp from an InngestGroup.
+ *
+ * @since 0.1.0
+ * @category http
+ * @example
+ * ```ts
+ * import { Effect, Layer } from "effect"
+ * import { HttpServer } from "@effect/platform"
+ * import { NodeHttpServer, NodeRuntime } from "@effect/platform-node"
+ * import { InngestGroup, InngestClient } from "effect-inngest"
+ *
+ * InngestGroup.toHttpApp(MyGroup).pipe(
+ *   Effect.flatMap((app) => HttpServer.serve(app)),
+ *   Effect.provide(InngestClient.layer({ id: "my-app" })),
+ *   Effect.provide(NodeHttpServer.layer({ port: 3000 })),
+ *   NodeRuntime.runMain,
+ * )
+ * ```
+ */
+export const toHttpApp = (group: InngestGroup.Any): HttpApp.Default<never, InngestClient | HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const request = yield* HttpServerRequest.HttpServerRequest;
+    const method = request.method;
+    const requestUrl = Option.match(HttpServerRequest.toURL(request), {
+      onNone: () => request.url,
+      onSome: (url) => url.toString(),
+    });
+
+    if (method === "GET") {
+      const result = yield* InternalHandler.handleIntrospection(group, requestUrl);
+      return yield* HttpServerResponse.json(result.body, {
+        status: result.status,
+        headers: result.headers,
+      });
+    }
+
+    if (method === "PUT") {
+      const result = yield* InternalHandler.handleRegistration(group, requestUrl);
+      return yield* HttpServerResponse.json(result.body, {
+        status: result.status,
+        headers: result.headers,
+      });
+    }
+
+    if (method === "POST") {
+      const url = Option.getOrThrow(HttpServerRequest.toURL(request));
+
+      const ExecuteParams = Schema.Struct({
+        fnId: Schema.String,
+        stepId: Schema.optional(Schema.String),
+      });
+
+      const params = yield* UrlParams.schemaStruct(ExecuteParams)(UrlParams.fromInput(url.searchParams)).pipe(
+        Effect.catchAll(() =>
+          Effect.fail(
+            HttpServerResponse.unsafeJson(
+              { error: "Missing or invalid fnId query parameter" },
+              { status: 400, headers: { [Protocol.Headers.NoRetry]: "true" } },
+            ),
+          ),
+        ),
+      );
+
+      const body = yield* InternalHandler.verifyAndParseRequestBody(request).pipe(
+        Effect.provide(SignatureLive),
+        Effect.catchAll((error) =>
+          Effect.fail(
+            HttpServerResponse.unsafeJson(
+              { error: error.message },
+              {
+                status: error._tag === "SignatureError" ? 401 : 400,
+                headers: { [Protocol.Headers.NoRetry]: "true" },
+              },
+            ),
+          ),
+        ),
+      );
+
+      const result = yield* InternalHandler.handleExecution(group, params.fnId, params.stepId, body);
+
+      return yield* HttpServerResponse.json(result.body, {
+        status: result.status,
+        headers: result.headers,
+      });
+    }
+
+    return yield* HttpServerResponse.json({ error: `Method ${method} not allowed` }, { status: 405 });
+  }).pipe(
+    Effect.catchAllCause((cause) =>
+      HttpServerResponse.json({ error: "Internal server error", cause: String(cause) }, { status: 500 }).pipe(
+        Effect.orDie,
+      ),
+    ),
+  );
+
+/**
+ * Create a standalone web handler from an InngestGroup.
+ *
+ * @since 0.1.0
+ * @category http
+ * @example
+ * ```ts
+ * import { InngestGroup, InngestClient } from "effect-inngest"
+ * import { HttpClient } from "@effect/platform"
+ * import { FetchHttpClient } from "@effect/platform"
+ *
+ * const { handler, dispose } = InngestGroup.toWebHandler(MyGroup, {
+ *   layer: InngestClient.layer({ id: "my-app" }).pipe(
+ *     Layer.provide(FetchHttpClient.layer),
+ *   ),
+ * })
+ *
+ * // Use with any web framework
+ * Bun.serve({ fetch: handler, port: 3000 })
+ *
+ * // Call dispose() on shutdown
+ * process.on("SIGTERM", dispose)
+ * ```
+ */
+export const toWebHandler = <R, E>(
+  group: InngestGroup.Any,
+  options: {
+    readonly layer: Layer.Layer<InngestClient | HttpClient.HttpClient | R, E, never>;
+    readonly memoMap?: Layer.MemoMap;
+  },
+): {
+  readonly handler: (request: Request) => Promise<Response>;
+  readonly dispose: () => Promise<void>;
+} =>
+  HttpApp.toWebHandlerLayer(toHttpApp(group), Layer.mergeAll(options.layer, Layer.scope), {
+    memoMap: options.memoMap,
+  });

package/src/HttpApi.ts

@@ -0,0 +1,82 @@
+/**
+ * @since 0.1.0
+ */
+import * as HttpApi from "@effect/platform/HttpApi";
+import * as HttpApiBuilder from "@effect/platform/HttpApiBuilder";
+import * as HttpApiEndpoint from "@effect/platform/HttpApiEndpoint";
+import * as HttpApiGroup from "@effect/platform/HttpApiGroup";
+import * as HttpClient from "@effect/platform/HttpClient";
+import * as HttpServerRequest from "@effect/platform/HttpServerRequest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { InngestClient } from "./Client.js";
+import type { InngestGroup } from "./Group.js";
+import * as InternalHandler from "./internal/handler.js";
+import * as Protocol from "./internal/protocol.js";
+import { SignatureLive } from "./internal/signature.js";
+
+const ExecuteParams = Schema.Struct({
+  fnId: Schema.String,
+  stepId: Schema.optional(Schema.String),
+});
+
+class FunctionNotFoundError extends Schema.TaggedError<FunctionNotFoundError>()("FunctionNotFoundError", {
+  message: Schema.String,
+}) {}
+
+const IntrospectEndpoint = HttpApiEndpoint.get("introspect", "/").addSuccess(Protocol.IntrospectionResponse);
+const RegisterEndpoint = HttpApiEndpoint.put("register", "/").addSuccess(Protocol.RegisterResponse);
+const ExecuteEndpoint = HttpApiEndpoint.post("execute", "/").setUrlParams(ExecuteParams).addSuccess(Schema.Unknown);
+
+/**
+ * @since 0.1.0
+ * @category api
+ */
+export const InngestApiGroup = HttpApiGroup.make("inngest")
+  .add(IntrospectEndpoint)
+  .add(RegisterEndpoint)
+  .add(ExecuteEndpoint)
+  .addError(FunctionNotFoundError, { status: 404 })
+  .addError(InternalHandler.InvalidRequestError, { status: 400 })
+  .addError(InternalHandler.SignatureError, { status: 401 });
+
+type InngestApiGroupType = typeof InngestApiGroup;
+
+/**
+ * @since 0.1.0
+ * @category layers
+ */
+export const layerGroup = <ApiId extends string, Groups extends HttpApiGroup.HttpApiGroup.Any, ApiError, ApiR>(
+  api: HttpApi.HttpApi<ApiId, Groups, ApiError, ApiR>,
+  group: InngestGroup.Any,
+): Layer.Layer<HttpApiGroup.ApiGroup<ApiId, "inngest">, never, InngestClient | HttpClient.HttpClient> => {
+  const toUrl = (req: HttpServerRequest.HttpServerRequest) =>
+    Option.match(HttpServerRequest.toURL(req), {
+      onNone: () => req.url,
+      onSome: (url) => url.toString(),
+    });
+
+  return HttpApiBuilder.group(
+    api as unknown as HttpApi.HttpApi<ApiId, InngestApiGroupType, ApiError, ApiR>,
+    "inngest",
+    (handlers) =>
+      handlers
+        .handle("introspect", ({ request }) =>
+          InternalHandler.handleIntrospection(group, toUrl(request)).pipe(Effect.map((r) => r.body)),
+        )
+        .handle("register", ({ request }) =>
+          InternalHandler.handleRegistration(group, toUrl(request)).pipe(Effect.map((r) => r.body)),
+        )
+        .handleRaw("execute", ({ urlParams, request }) =>
+          InternalHandler.verifyAndParseRequestBody(request).pipe(
+            Effect.provide(SignatureLive),
+            Effect.flatMap((payload) =>
+              InternalHandler.handleExecution(group, urlParams.fnId, urlParams.stepId, payload),
+            ),
+            Effect.map((r) => r.body),
+          ),
+        ),
+  ) as Layer.Layer<HttpApiGroup.ApiGroup<ApiId, "inngest">, never, InngestClient | HttpClient.HttpClient>;
+};

package/src/index.ts

@@ -0,0 +1,171 @@
+/**
+ * This module provides types and functions for defining Inngest functions.
+ *
+ * Functions are the core building blocks of Inngest applications. Each function
+ * defines what events trigger it, what it returns on success, and optional
+ * configuration like retries, concurrency limits, rate limiting, and more.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { InngestFunction, InngestGroup } from "effect-inngest"
+ *
+ * // Define events as TaggedClass
+ * class UserCreated extends Schema.TaggedClass<UserCreated>()("user/created", {
+ *   userId: Schema.String,
+ *   email: Schema.String,
+ * }) {}
+ *
+ * // Define functions
+ * const SendWelcomeEmail = InngestFunction.make("send-welcome-email", {
+ *   event: UserCreated,
+ *   success: Schema.Void,
+ *   retries: 3,
+ * })
+ *
+ * // Create a group
+ * const MyGroup = InngestGroup.make(SendWelcomeEmail)
+ *
+ * // Implement handlers
+ * const HandlersLive = MyGroup.toLayer({
+ *   "send-welcome-email": (event) =>
+ *     Effect.gen(function* () {
+ *       yield* sendEmail(event.email)
+ *     }),
+ * })
+ * ```
+ *
+ * @module InngestFunction
+ * @since 0.1.0
+ */
+export * as InngestFunction from "./Function.js";
+
+/**
+ * This module provides types and functions for grouping Inngest functions
+ * and creating handler layers.
+ *
+ * Groups aggregate functions and provide a way to define handlers as a single
+ * layer that can be composed with the rest of your Effect application.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { InngestGroup } from "effect-inngest"
+ *
+ * const MyGroup = InngestGroup.make(ProcessOrder, SendNotification)
+ *
+ * const HandlersLive = MyGroup.toLayer({
+ *   "process-order": (event) => Effect.succeed({ processed: true }),
+ *   "send-notification": (event) => Effect.void,
+ * })
+ * ```
+ *
+ * @module InngestGroup
+ * @since 0.1.0
+ */
+export * as InngestGroup from "./Group.js";
+
+/**
+ * This module provides the InngestClient service for communicating with Inngest.
+ *
+ * The client handles event sending, function registration, and API communication.
+ * It supports both development (local dev server) and cloud modes, with automatic
+ * mode detection from environment variables.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { HttpClient } from "@effect/platform"
+ * import { InngestClient } from "effect-inngest"
+ *
+ * // Create a layer with explicit config
+ * const ClientLive = InngestClient.layer({
+ *   id: "my-app",
+ *   eventKey: "my-event-key",
+ * })
+ *
+ * // Or use environment variables
+ * const ClientFromEnv = InngestClient.layerFromEnv
+ *
+ * // Use in your program
+ * const program = Effect.gen(function* () {
+ *   const client = yield* InngestClient.InngestClientTag
+ *   yield* client.sendEvent([{ name: "user/created", data: { userId: "123" } }])
+ * })
+ * ```
+ *
+ * @module InngestClient
+ * @since 0.1.0
+ */
+export * as InngestClient from "./Client.js";
+
+/**
+ * This module provides integration with `@effect/platform` HttpApi.
+ *
+ * Use `InngestHttpApi.InngestApiGroup` to add Inngest endpoints to your HttpApi,
+ * then use `InngestHttpApi.layerGroup` to implement the handlers.
+ *
+ * @example
+ * ```ts
+ * import { HttpApi, HttpApiBuilder } from "@effect/platform"
+ * import { InngestHttpApi, InngestGroup, InngestClient } from "effect-inngest"
+ * import { Layer } from "effect"
+ *
+ * // Add InngestApiGroup to your HttpApi
+ * class MyApi extends HttpApi.make("my-api")
+ *   .add(InngestHttpApi.InngestApiGroup.prefix("/api/inngest")) {}
+ *
+ * // Create the implementation layer
+ * const InngestLayer = InngestHttpApi.layerGroup(MyApi, MyFunctions)
+ *
+ * // Wire it up with HttpApiBuilder
+ * const ApiLive = HttpApiBuilder.api(MyApi).pipe(
+ *   Layer.provide(InngestLayer),
+ *   Layer.provide(FunctionsLayer),
+ *   Layer.provide(InngestClient.layer({ id: "my-app" })),
+ * )
+ * ```
+ *
+ * @module InngestHttpApi
+ * @since 0.1.0
+ */
+export * as InngestHttpApi from "./HttpApi.js";
+
+/**
+ * Internal Inngest events that the platform sends automatically.
+ * Use these as triggers to react to function lifecycle events.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { InngestFunction, InngestEvents } from "effect-inngest"
+ *
+ * // React to function failures
+ * const HandleFailure = InngestFunction.make("handle-failure", {
+ *   trigger: { event: InngestEvents.FunctionFailed },
+ *   success: Schema.Void,
+ * })
+ * ```
+ *
+ * @module InngestEvents
+ * @since 0.1.0
+ */
+export * as InngestEvents from "./Events.js";
+
+/**
+ * Error thrown to indicate that an operation should not be retried.
+ * Use this when you know retrying won't help (e.g., validation errors, auth failures).
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export { NonRetriableError } from "./internal/errors.js";
+
+/**
+ * Error thrown to indicate that an operation should be retried after a specific delay.
+ * Use this for rate limiting or when you know when a resource will become available.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export { RetryAfterError } from "./internal/errors.js";

package/src/internal/constants.ts

@@ -0,0 +1,11 @@
+export const OtelAttributes = {
+  RunId: "inngest.run_id",
+  FunctionId: "inngest.function_id",
+  AppId: "inngest.app_id",
+  Attempt: "inngest.attempt",
+  StepId: "inngest.step.id",
+  StepType: "inngest.step.type",
+  ExceptionType: "exception.type",
+  ExceptionMessage: "exception.message",
+  ExceptionStacktrace: "exception.stacktrace",
+} as const;