effect-inngest 0.1.3 → 0.2.0-beta.0

package/dist/internal/step.js

@@ -1,21 +1,20 @@
 import { formatTimestamp, timeStr } from "./helpers.js";
+import { stepRun } from "./protocol.js";
 import { InngestClient } from "../Client.js";
 import { SendEventError, StepError, isNonRetriableError, isRetryAfterError } from "./errors.js";
-import { StepInterrupt, errorInterrupt, invokeInterrupt, plannedInterrupt, runInterrupt, sleepInterrupt, waitForEventInterrupt } from "./interrupts.js";
+import { errorInterrupt, invokeInterrupt, plannedInterrupt, runInterrupt, sleepInterrupt, waitForEventInterrupt } from "./interrupts.js";
 import { OtelAttributes } from "./constants.js";
 import { decodeMemo } from "./memo.js";
 import * as Duration from "effect/Duration";
-import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
 import * as Schema from "effect/Schema";
 import * as Predicate from "effect/Predicate";
-import * as Arr from "effect/Array";
 import * as HashMap from "effect/HashMap";
-import * as Match from "effect/Match";
-import * as Ref from "effect/Ref";
 import { pipe } from "effect/Function";
-
+import * as Arr from "effect/Array";
+import * as Match from "effect/Match";
 //#region src/internal/step.ts
 /**
 * Internal step tools implementation.
@@ -40,10 +39,9 @@ const errorOtelAttributes = (err) => {
 };
 const encodeTaggedEvent = (event) => {
 	const ctor = event.constructor;
-	if (Schema.isSchema(ctor)) return Schema.encode(ctor)(event).pipe(Effect.orElseSucceed(() => event));
+	if (Schema.isSchema(ctor)) return Schema.encodeEffect(ctor)(event).pipe(Effect.orElseSucceed(() => event));
 	return Effect.succeed(event);
 };
-var Step = class extends Context.Tag("effect-inngest/Step")() {};
 const normalizeOpts = (opts) => typeof opts === "string" ? {
 	id: opts,
 	name: opts
@@ -57,7 +55,7 @@ const stepError = (stepId, message, opts) => Effect.fail(StepError.make({
 	noRetry: opts?.noRetry,
 	cause: opts?.cause
 }));
-const createStepTools = (request, appName, stepIdCounts) => {
+const createStepTools = (request, appName, stepIdCounts, checkpoint = Option.none()) => {
 	const ctx = request.ctx;
 	const steps = request.steps;
 	const getInfo = (opts) => {
@@ -74,30 +72,40 @@ const createStepTools = (request, appName, stepIdCounts) => {
 	const getMemo = (hash) => decodeMemo(steps[hash]);
 	const canExecute = (hash) => ctx.step_id === hash || ctx.step_id === "step";
 	const isBlocked = (hash) => ctx.disable_immediate_execution && ctx.step_id !== hash;
-	const sleep = (opts, duration) => Effect.flatMap(getInfo(opts), (info) => pipe(getMemo(info.hash), Match.value, Match.tag("MemoData", () => Effect.void), Match.tag("MemoTimeout", () => Effect.void), Match.tag("MemoError", () => Effect.void), Match.tag("MemoInput", () => Effect.void), Match.tag("MemoNone", () => Effect.fail(sleepInterrupt({
+	const flushIfCheckpoint = Option.match(checkpoint, {
+		onNone: () => Effect.void,
+		onSome: (state) => state.flush
+	});
+	const sleep = (opts, duration) => Effect.flatMap(getInfo(opts), (info) => pipe(getMemo(info.hash), Match.value, Match.tag("MemoData", () => Effect.void), Match.tag("MemoTimeout", () => Effect.void), Match.tag("MemoError", () => Effect.void), Match.tag("MemoInput", () => Effect.void), Match.tag("MemoNone", () => Effect.andThen(flushIfCheckpoint, Effect.fail(sleepInterrupt({
 		info,
 		duration: timeStr(duration)
-	}))), Match.exhaustive));
-	const sleepUntil = (opts, timestamp) => Effect.flatMap(getInfo(opts), (info) => pipe(getMemo(info.hash), Match.value, Match.tag("MemoData", () => Effect.void), Match.tag("MemoTimeout", () => Effect.void), Match.tag("MemoError", () => Effect.void), Match.tag("MemoInput", () => Effect.void), Match.tag("MemoNone", () => Effect.fail(sleepInterrupt({
+	}))).pipe(Effect.withSpan(`inngest.step/sleep/${info.id}`, { attributes: {
+		[OtelAttributes.StepId]: info.id,
+		[OtelAttributes.StepType]: "sleep"
+	} }))), Match.exhaustive));
+	const sleepUntil = (opts, timestamp) => Effect.flatMap(getInfo(opts), (info) => pipe(getMemo(info.hash), Match.value, Match.tag("MemoData", () => Effect.void), Match.tag("MemoTimeout", () => Effect.void), Match.tag("MemoError", () => Effect.void), Match.tag("MemoInput", () => Effect.void), Match.tag("MemoNone", () => Effect.andThen(flushIfCheckpoint, Effect.fail(sleepInterrupt({
 		info,
 		duration: formatTimestamp(timestamp)
-	}))), Match.exhaustive));
+	}))).pipe(Effect.withSpan(`inngest.step/sleepUntil/${info.id}`, { attributes: {
+		[OtelAttributes.StepId]: info.id,
+		[OtelAttributes.StepType]: "sleepUntil"
+	} }))), Match.exhaustive));
 	const waitForEvent = (opts, event, options) => Effect.flatMap(getInfo(opts), (info) => pipe(getMemo(info.hash), Match.value, Match.tag("MemoData", ({ data }) => {
 		if (data == null) return Effect.succeed(Option.none());
 		const event = data;
 		const payload = event.data !== void 0 ? event.data : data;
 		if (payload == null) return Effect.succeed(Option.none());
 		return Effect.succeed(Option.some(payload));
-	}), Match.tag("MemoTimeout", () => Effect.succeed(Option.none())), Match.tag("MemoError", () => Effect.succeed(Option.none())), Match.tag("MemoInput", () => Effect.succeed(Option.none())), Match.tag("MemoNone", () => Effect.fail(waitForEventInterrupt({
+	}), Match.tag("MemoTimeout", () => Effect.succeed(Option.none())), Match.tag("MemoError", () => Effect.succeed(Option.none())), Match.tag("MemoInput", () => Effect.succeed(Option.none())), Match.tag("MemoNone", () => Effect.andThen(flushIfCheckpoint, Effect.fail(waitForEventInterrupt({
 		info,
-		event: event._tag,
+		event: event.identifier,
 		timeout: timeStr(options.timeout),
 		if: options.if
-	}))), Match.exhaustive));
+	})))), Match.exhaustive));
 	const invoke = (opts, options) => Effect.flatMap(getInfo(opts), (info) => pipe(getMemo(info.hash), Match.value, Match.tag("MemoData", ({ data }) => Effect.succeed(data)), Match.tag("MemoError", ({ error }) => stepError(info.id, Predicate.hasProperty(error, "message") ? String(error.message) : "Invoke failed", { cause: error })), Match.tag("MemoTimeout", () => stepError(info.id, "Invoke timed out", { noRetry: true })), Match.tag("MemoInput", () => Effect.succeed(void 0)), Match.tag("MemoNone", () => {
 		const rawData = Predicate.hasProperty(options, "data") ? options.data : void 0;
 		const encodeData = rawData ? encodeTaggedEvent(rawData) : Effect.succeed(void 0);
-		return Effect.flatMap(encodeData, (encodedData) => Effect.fail(invokeInterrupt({
+		return Effect.flatMap(encodeData, (encodedData) => Effect.andThen(flushIfCheckpoint, Effect.fail(invokeInterrupt({
 			info,
 			functionId: `${appName}-${options.function._tag}`,
 			payload: {
@@ -106,9 +114,12 @@ const createStepTools = (request, appName, stepIdCounts) => {
 				v: options.v ?? "1"
 			},
 			timeout: options.timeout ? timeStr(options.timeout) : "365d"
-		})));
+		}))));
 	}), Match.exhaustive));
-	const run = (opts, effect) => Effect.flatMap(getInfo(opts), (info) => pipe(getMemo(info.hash), Match.value, Match.tag("MemoData", ({ data }) => Effect.succeed(data)), Match.tag("MemoError", ({ error }) => stepError(info.id, Predicate.hasProperty(error, "message") ? String(error.message) : "Step failed", { noRetry: true })), Match.tag("MemoTimeout", () => stepError(info.id, "Step timed out", { noRetry: true })), Match.tag("MemoInput", () => stepError(info.id, "Unexpected step result type: input")), Match.tag("MemoNone", () => {
+	const run = (opts, effect) => Effect.flatMap(getInfo(opts), (info) => pipe(getMemo(info.hash), Match.value, Match.tag("MemoData", ({ data }) => Effect.succeed(data)), Match.tag("MemoError", ({ error }) => stepError(info.id, Predicate.hasProperty(error, "message") ? String(error.message) : "Step failed", {
+		noRetry: true,
+		cause: error
+	})), Match.tag("MemoTimeout", () => stepError(info.id, "Step timed out", { noRetry: true })), Match.tag("MemoInput", () => stepError(info.id, "Unexpected step result type: input")), Match.tag("MemoNone", () => {
 		if (isBlocked(info.hash) || !canExecute(info.hash)) return Effect.fail(plannedInterrupt({ info }));
 		return effect.pipe(Effect.withSpan(`inngest.step/run/${info.id}`, { attributes: {
 			[OtelAttributes.StepId]: info.id,
@@ -117,18 +128,21 @@ const createStepTools = (request, appName, stepIdCounts) => {
 			onFailure: (err) => {
 				const noRetry = isNonRetriableError(err) ? true : void 0;
 				const retryAfterMs = isRetryAfterError(err) ? Duration.toMillis(err.retryAfter) : void 0;
-				return Effect.zipRight(Effect.annotateCurrentSpan(errorOtelAttributes(err)), Effect.fail(errorInterrupt({
+				return Effect.andThen(Effect.annotateCurrentSpan(errorOtelAttributes(err)), Effect.fail(errorInterrupt({
 					info,
 					error: err,
 					noRetry,
 					retryAfterMs
 				})));
 			},
-			onSuccess: (data) => Effect.fail(runInterrupt({
-				info,
-				data
-			}))
-		}), Effect.catchAllDefect((defect) => Effect.zipRight(Effect.annotateCurrentSpan(errorOtelAttributes(defect)), Effect.fail(errorInterrupt({
+			onSuccess: (data) => Option.match(checkpoint, {
+				onNone: () => Effect.fail(runInterrupt({
+					info,
+					data
+				})),
+				onSome: (state) => Effect.as(state.bufferStep(stepRun(info, data)), data)
+			})
+		}), Effect.catchDefect((defect) => Effect.andThen(Effect.annotateCurrentSpan(errorOtelAttributes(defect)), Effect.fail(errorInterrupt({
 			info,
 			error: defect
 		})))));
@@ -145,13 +159,16 @@ const createStepTools = (request, appName, stepIdCounts) => {
 		return Effect.flatMap(Effect.forEach(events, (e) => Effect.map(encodeTaggedEvent(e), (encoded) => ({
 			name: e._tag,
 			data: encoded
-		}))), (eventPayloads) => Effect.flatMap(InngestClient, (client) => client.sendEvent(eventPayloads).pipe(Effect.withSpan(`inngest.step/sendEvent/${info.id}`, { attributes: {
+		}))), (eventPayloads) => InngestClient.use((client) => client.sendEvent(eventPayloads).pipe(Effect.withSpan(`inngest.step/sendEvent/${info.id}`, { attributes: {
 			[OtelAttributes.StepId]: info.id,
 			[OtelAttributes.StepType]: "sendEvent"
-		} }), Effect.flatMap((result) => Effect.fail(runInterrupt({
-			info,
-			data: result
-		}))))));
+		} }), Effect.flatMap((result) => Option.match(checkpoint, {
+			onNone: () => Effect.fail(runInterrupt({
+				info,
+				data: result
+			})),
+			onSome: (state) => Effect.as(state.bufferStep(stepRun(info, result)), result)
+		})))));
 	}), Match.exhaustive));
 	return {
 		run,
@@ -187,6 +204,5 @@ const buildHandlerContext = (fn, step, request) => {
 		}
 	};
 };
-
 //#endregion
-export { Step, buildHandlerContext, createStepTools };
+export { buildHandlerContext, createStepTools };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-inngest",
-  "version": "0.1.3",
+  "version": "0.2.0-beta.0",
   "description": "Native Effect client library for Inngest - build durable, type-safe workflows",
   "keywords": [
     "background-jobs",
@@ -91,33 +91,38 @@
     }
   },
   "scripts": {
-    "build": "tsdown",
-    "format": "oxfmt",
-    "lint": "oxlint --fix --type-aware --type-check --promise-plugin",
+    "build": "vp pack",
+    "test": "vp test run",
+    "test:watch": "vp test",
+    "format": "vp fmt",
+    "lint": "vp lint --fix --type-aware --type-check --promise-plugin",
     "typecheck": "tsgo --noEmit",
-    "prepare": "effect-language-service patch",
+    "prepare": "vp config && effect-language-service patch && effect-tsgo patch",
     "changeset": "changeset",
     "changeset:version": "changeset version",
     "changeset:publish": "bun run build && changeset publish"
   },
   "devDependencies": {
-    "@changesets/changelog-github": "^0.5.2",
-    "@changesets/cli": "^2.29.8",
-    "@effect/cluster": "^0.56.1",
-    "@effect/language-service": "0.72.0",
-    "@effect/platform": "^0.94.2",
-    "@effect/platform-bun": "^0.87.0",
-    "@types/bun": "1.3.6",
-    "@typescript/native-preview": "^7.0.0-dev.20260124.1",
-    "effect": "^3.15.0",
-    "oxfmt": "0.26.0",
-    "oxlint": "1.41.0",
-    "oxlint-tsgolint": "0.11.1",
-    "tsdown": "0.20.1",
-    "typescript": "^5.9.3"
+    "@changesets/changelog-github": "^0.6.0",
+    "@changesets/cli": "^2.31.0",
+    "@effect/platform-bun": "4.0.0-beta.59",
+    "@effect/tsgo": "0.5.2",
+    "@effect/vitest": "4.0.0-beta.59",
+    "@types/bun": "1.3.12",
+    "@typescript/native-preview": "^7.0.0-dev.20260420.1",
+    "typescript": "^5.9.3",
+    "vite-plus": "latest"
   },
   "peerDependencies": {
-    "@effect/platform": ">=0.87.0",
-    "effect": ">=3.15.0"
+    "effect": ">=4.0.0-beta.44",
+    "typescript": ">=5.9"
+  },
+  "overrides": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@latest",
+    "vitest": "npm:@voidzero-dev/vite-plus-test@latest"
+  },
+  "packageManager": "bun@1.3.13",
+  "patchedDependencies": {
+    "@effect/vitest@4.0.0-beta.59": "patches/@effect%2Fvitest@4.0.0-beta.59.patch"
   }
 }

package/src/Client.ts

@@ -1,18 +1,25 @@
 /**
  * @since 0.1.0
  */
-import * as HttpClient from "@effect/platform/HttpClient";
-import * as HttpClientRequest from "@effect/platform/HttpClientRequest";
-import * as HttpClientResponse from "@effect/platform/HttpClientResponse";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+import * as Clock from "effect/Clock";
 import * as Config from "effect/Config";
-import type * as ConfigError from "effect/ConfigError";
 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 Predicate from "effect/Predicate";
+import * as Ref from "effect/Ref";
+import * as Schedule from "effect/Schedule";
 import * as Schema from "effect/Schema";
+import { CheckpointApiError, type CheckpointingOption } from "./internal/checkpoint.js";
 import * as Protocol from "./internal/protocol.js";
+import { hashSigningKey } from "./internal/signature.js";
+
+export type { CheckpointingOption } from "./internal/checkpoint.js";
+export { CheckpointApiError } from "./internal/checkpoint.js";
 
 /**
  * @since 0.1.0
@@ -111,6 +118,23 @@ interface ClientConfig {
    * The path where the Inngest serve handler is mounted. Used for registration.
    */
   readonly servePath?: string | undefined;
+
+  /**
+   * Whether to use checkpointing by default for executions of functions
+   * created using this client.
+   *
+   * - `false` disables checkpointing for all functions on this client.
+   * - `true` enables checkpointing with safe defaults (`bufferedSteps: 1`,
+   *   `maxInterval: 0`, `maxRuntime: 10s`). Steps are checkpointed to the
+   *   Inngest API as they complete instead of yielding a 206 per step.
+   * - An object lets you tune `bufferedSteps`, `maxInterval`, `maxRuntime`.
+   *
+   * Per-function `checkpointing` overrides this setting. Defaults to `true`
+   * (checkpointing enabled).
+   *
+   * @default true
+   */
+  readonly checkpointing?: CheckpointingOption | undefined;
 }
 
 export const EventPayload = Schema.Struct({
@@ -122,14 +146,14 @@ export const EventPayload = Schema.Struct({
 });
 
 const SendEventResponse = Schema.Struct({
-  ids: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] }),
+  ids: Schema.Array(Schema.String).pipe(Schema.withDecodingDefault(Effect.succeed([]))),
   status: Schema.optional(Schema.Number),
 });
 
 type EventPayload = typeof EventPayload.Type;
 type SendEventResponse = typeof SendEventResponse.Type;
 
-class SendEventError extends Schema.TaggedError<SendEventError>()("SendEventError", {
+class SendEventError extends Schema.TaggedErrorClass<SendEventError>()("SendEventError", {
   message: Schema.String,
   events: Schema.Array(Schema.String),
 }) {}
@@ -141,6 +165,23 @@ interface InngestClientService {
   readonly eventBaseUrl: string;
   readonly apiBaseUrl: string;
   readonly sendEvent: (events: ReadonlyArray<EventPayload>) => Effect.Effect<SendEventResponse, SendEventError>;
+  /**
+   * Async checkpoint API call per spec §10.3.1.
+   *
+   * POSTs `{run_id, fn_id, qi_id, steps, ts}` to
+   * `{apiBaseUrl}/v1/checkpoint/{runId}/async` with a hashed-signing-key
+   * Bearer token. Retries 5xx responses with exponential backoff + jitter
+   * (5 attempts). On 401, falls back to the configured fallback signing key
+   * for the remainder of the client's lifetime (one-way switch).
+   *
+   * @internal
+   */
+  readonly checkpointAsync: (args: {
+    readonly runId: string;
+    readonly fnId: string;
+    readonly qiId: string;
+    readonly steps: ReadonlyArray<typeof Protocol.GeneratorOpcode.Type>;
+  }) => Effect.Effect<void, CheckpointApiError>;
 }
 
 /**
@@ -149,7 +190,9 @@ interface InngestClientService {
  * @since 0.1.0
  * @category context
  */
-export class InngestClient extends Context.Tag("effect-inngest/InngestClient")<InngestClient, InngestClientService>() {}
+export class InngestClient extends Context.Service<InngestClient, InngestClientService>()(
+  "effect-inngest/InngestClient",
+) {}
 
 const resolveMode = (config: ClientConfig): ClientMode => config.mode ?? "dev";
 
@@ -159,64 +202,175 @@ const resolveEventBaseUrl = (config: ClientConfig, mode: ClientMode): string =>
 const resolveApiBaseUrl = (config: ClientConfig, mode: ClientMode): string =>
   config.apiBaseUrl ?? (mode === "dev" ? DEFAULT_DEV_SERVER_URL : DEFAULT_API_BASE_URL);
 
-const makeClient = (config: ClientConfig, httpClient: HttpClient.HttpClient): InngestClientService => {
-  const mode = resolveMode(config);
-  const eventBaseUrl = resolveEventBaseUrl(config, mode);
-  const apiBaseUrl = resolveApiBaseUrl(config, mode);
-
-  const sendEvent = (events: ReadonlyArray<EventPayload>): Effect.Effect<SendEventResponse, SendEventError> => {
-    if (!config.eventKey && mode === "cloud") {
-      return new SendEventError({
-        message: "Event key is required to send events in cloud mode",
-        events: events.map((e) => e.name),
-      });
-    }
-
-    const key = config.eventKey ?? "local";
-    const url = new URL(`e/${key}`, eventBaseUrl).toString();
-    const eventNames = events.map((e) => e.name);
-    const now = Date.now();
-
-    const payloads = events.map((e) => ({
-      name: e.name,
-      data: e.data ?? {},
-      ts: e.ts ?? now,
-      id: e.id,
-      v: e.v,
-    }));
-
-    const request = HttpClientRequest.post(url).pipe(
-      HttpClientRequest.setHeaders({
-        "Content-Type": "application/json",
-        [Protocol.Headers.SDK]: `effect-ts:v${SDK_VERSION}`,
-        ...(config.env ? { [Protocol.Headers.Env]: config.env } : {}),
-      }),
-    );
+const isRetriable = (error: CheckpointApiError): boolean => error.status === undefined || error.status >= 500;
+
+const defaultCheckpointRetrySchedule: Schedule.Schedule<unknown, CheckpointApiError> = Schedule.exponential(
+  "100 millis",
+  2.0,
+).pipe(
+  Schedule.jittered,
+  Schedule.both(Schedule.recurs(5)),
+  Schedule.while((m: Schedule.Metadata<unknown, CheckpointApiError>) => isRetriable(m.input)),
+);
 
-    return HttpClientRequest.schemaBodyJson(Schema.Array(EventPayload))(request, payloads).pipe(
-      Effect.flatMap(httpClient.execute),
-      Effect.flatMap(HttpClientResponse.schemaBodyJson(SendEventResponse)),
-      Effect.map((response) => ({ ids: response.ids, status: response.status })),
-      Effect.scoped,
-      Effect.catchAll(
-        (error) =>
+const makeClient = (
+  config: ClientConfig,
+  httpClient: HttpClient.HttpClient,
+  retrySchedule: Schedule.Schedule<unknown, CheckpointApiError> = defaultCheckpointRetrySchedule,
+): Effect.Effect<InngestClientService> =>
+  Effect.gen(function* () {
+    const mode = resolveMode(config);
+    const eventBaseUrl = resolveEventBaseUrl(config, mode);
+    const apiBaseUrl = resolveApiBaseUrl(config, mode);
+
+    /**
+     * One-way switch: once the fallback signing key succeeds for any
+     * checkpoint API call, all subsequent calls use it first. Per spec
+     * §10.3.4.
+     */
+    const useFallbackKey = yield* Ref.make(false);
+
+    const sendEvent = Effect.fn("InngestClient.sendEvent")(function* (events: ReadonlyArray<EventPayload>) {
+      if (!config.eventKey && mode === "cloud") {
+        return yield* Effect.fail(
           new SendEventError({
-            message: `Failed to send events: ${Predicate.hasProperty(error, "message") ? (error.message as string) : "Unknown error"}`,
-            events: eventNames,
+            message: "Event key is required to send events in cloud mode",
+            events: events.map((e) => e.name),
           }),
-      ),
+        );
+      }
+
+      const key = config.eventKey ?? "local";
+      const url = new URL(`e/${key}`, eventBaseUrl).toString();
+      const eventNames = events.map((e) => e.name);
+      const now = yield* Clock.currentTimeMillis;
+
+      const payloads = events.map((e) => ({
+        name: e.name,
+        data: e.data ?? {},
+        ts: e.ts ?? now,
+        id: e.id,
+        v: e.v,
+      }));
+
+      const request = HttpClientRequest.post(url).pipe(
+        HttpClientRequest.setHeaders({
+          "Content-Type": "application/json",
+          [Protocol.Headers.SDK]: `effect-ts:v${SDK_VERSION}`,
+          ...(config.env ? { [Protocol.Headers.Env]: config.env } : {}),
+        }),
+      );
+
+      return yield* HttpClientRequest.schemaBodyJson(Schema.Array(EventPayload))(request, payloads).pipe(
+        Effect.flatMap(httpClient.execute),
+        Effect.flatMap(HttpClientResponse.schemaBodyJson(SendEventResponse)),
+        Effect.map((response) => ({ ids: response.ids, status: response.status })),
+        Effect.scoped,
+        Effect.catch((error) =>
+          Effect.fail(
+            new SendEventError({
+              message: `Failed to send events: ${Predicate.hasProperty(error, "message") ? (error.message as string) : "Unknown error"}`,
+              events: eventNames,
+            }),
+          ),
+        ),
+      );
+    });
+
+    /**
+     * Issue a checkpoint POST with the given signing key. Returns a tagged
+     * error on non-2xx so the caller can decide whether to retry, swap keys,
+     * or fall back.
+     */
+    const checkpointRequest = (
+      runId: string,
+      body: string,
+      signingKey: string,
+    ): Effect.Effect<void, CheckpointApiError> => {
+      const url = new URL(`v1/checkpoint/${runId}/async`, apiBaseUrl).toString();
+      const request = HttpClientRequest.post(url).pipe(
+        HttpClientRequest.setHeaders({
+          "Content-Type": "application/json",
+          [Protocol.Headers.SDK]: `effect-inngest:v${SDK_VERSION}`,
+          [Protocol.Headers.RequestVersion]: "2",
+          ...(config.env ? { [Protocol.Headers.Env]: config.env } : {}),
+        }),
+        HttpClientRequest.bearerToken(hashSigningKey(signingKey)),
+        HttpClientRequest.bodyText(body, "application/json"),
+      );
+
+      return httpClient.execute(request).pipe(
+        Effect.scoped,
+        Effect.catch((error) =>
+          Effect.fail(
+            new CheckpointApiError({
+              message: `Network error issuing checkpoint: ${Predicate.hasProperty(error, "message") ? (error.message as string) : String(error)}`,
+            }),
+          ),
+        ),
+        Effect.flatMap((response) => {
+          if (response.status >= 200 && response.status < 300) {
+            return Effect.void;
+          }
+          return Effect.fail(
+            new CheckpointApiError({
+              message: `Checkpoint API returned ${response.status}`,
+              status: response.status,
+            }),
+          );
+        }),
+      );
+    };
+
+    const checkpointAsync: InngestClientService["checkpointAsync"] = Effect.fn("InngestClient.checkpointAsync")(
+      function* (args) {
+        const signingKey = config.signingKey;
+        if (!signingKey) {
+          return yield* Effect.fail(
+            new CheckpointApiError({ message: "No signing key configured for checkpoint API" }),
+          );
+        }
+
+        const now = yield* Clock.currentTimeMillis;
+        const body = JSON.stringify({
+          run_id: args.runId,
+          fn_id: args.fnId,
+          qi_id: args.qiId,
+          steps: Schema.encodeSync(Schema.Array(Protocol.GeneratorOpcode))(args.steps),
+          ts: now,
+        });
+
+        const fallbackKey = config.signingKeyFallback;
+
+        // Single attempt: tries the chosen key first; on 401 with primary,
+        // tries the fallback once and flips the Ref.
+        const attempt: Effect.Effect<void, CheckpointApiError> = Ref.get(useFallbackKey).pipe(
+          Effect.flatMap((usingFallback) => {
+            const primaryKey = usingFallback && fallbackKey ? fallbackKey : signingKey;
+            return checkpointRequest(args.runId, body, primaryKey).pipe(
+              Effect.catch((error) =>
+                error.status === 401 && !usingFallback && fallbackKey
+                  ? checkpointRequest(args.runId, body, fallbackKey).pipe(Effect.andThen(Ref.set(useFallbackKey, true)))
+                  : Effect.fail(error),
+              ),
+            );
+          }),
+        );
+
+        return yield* attempt.pipe(Effect.retry(retrySchedule));
+      },
     );
-  };
-
-  return {
-    [TypeId]: TypeId,
-    config,
-    mode,
-    eventBaseUrl,
-    apiBaseUrl,
-    sendEvent,
-  };
-};
+
+    return {
+      [TypeId]: TypeId,
+      config,
+      mode,
+      eventBaseUrl,
+      apiBaseUrl,
+      sendEvent,
+      checkpointAsync,
+    };
+  });
 
 /**
  * Create an InngestClient layer from a config.
@@ -234,7 +388,27 @@ const makeClient = (config: ClientConfig, httpClient: HttpClient.HttpClient): In
 export const layer = (config: ClientConfig): Layer.Layer<InngestClient, never, HttpClient.HttpClient> =>
   Layer.effect(
     InngestClient,
-    Effect.map(HttpClient.HttpClient, (httpClient) => makeClient(config, httpClient)),
+    Effect.gen(function* () {
+      const httpClient = yield* HttpClient.HttpClient;
+      return yield* makeClient(config, httpClient);
+    }),
+  );
+
+// Test-only factory attached via Symbol.for; not a named export, not in
+// TypeScript autocomplete, not in the public `InngestClient.*` namespace.
+// Tests retrieve it by re-deriving the same global symbol. Do not use from
+// application code.
+const TEST_FACTORY_KEY = Symbol.for("effect-inngest/internal/test-retry-schedule-factory");
+(InngestClient as unknown as Record<symbol, unknown>)[TEST_FACTORY_KEY] = (
+  config: ClientConfig,
+  retrySchedule: Schedule.Schedule<unknown, CheckpointApiError>,
+): Layer.Layer<InngestClient, never, HttpClient.HttpClient> =>
+  Layer.effect(
+    InngestClient,
+    Effect.gen(function* () {
+      const httpClient = yield* HttpClient.HttpClient;
+      return yield* makeClient(config, httpClient, retrySchedule);
+    }),
   );
 
 /**
@@ -244,13 +418,15 @@ export const layer = (config: ClientConfig): Layer.Layer<InngestClient, never, H
  * @category layers
  */
 export const layerConfig = (
-  config: Config.Config.Wrap<ClientConfig>,
-): Layer.Layer<InngestClient, ConfigError.ConfigError, HttpClient.HttpClient> =>
+  config: Config.Wrap<ClientConfig>,
+): Layer.Layer<InngestClient, Config.ConfigError, HttpClient.HttpClient> =>
   Layer.effect(
     InngestClient,
-    Effect.flatMap(Config.unwrap(config), (resolvedConfig) =>
-      Effect.map(HttpClient.HttpClient, (httpClient) => makeClient(resolvedConfig, httpClient)),
-    ),
+    Effect.gen(function* () {
+      const resolvedConfig = yield* Config.unwrap(config);
+      const httpClient = yield* HttpClient.HttpClient;
+      return yield* makeClient(resolvedConfig, httpClient);
+    }),
   );
 
 /**
@@ -266,7 +442,7 @@ export const layerConfig = (
  * @since 0.1.0
  * @category layers
  */
-export const layerFromEnv: Layer.Layer<InngestClient, ConfigError.ConfigError, HttpClient.HttpClient> = layerConfig(
+export const layerFromEnv: Layer.Layer<InngestClient, Config.ConfigError, HttpClient.HttpClient> = layerConfig(
   Config.all({
     id: Config.string("INNGEST_APP_ID").pipe(Config.withDefault("app")),
     eventKey: Config.string("INNGEST_EVENT_KEY").pipe(Config.option, Config.map(Option.getOrUndefined)),

package/src/Events.ts

@@ -25,7 +25,7 @@ export class FunctionFailed extends Schema.TaggedClass<FunctionFailed>()("innges
   function_id: Schema.String,
   run_id: Schema.String,
   error: JsonError,
-  event: Schema.Record({ key: Schema.String, value: Schema.Unknown }),
+  event: Schema.Record(Schema.String, Schema.Unknown),
 }) {}
 
 /**
@@ -57,7 +57,7 @@ export class FunctionFinishedSuccess extends Schema.TaggedClass<FunctionFinished
  * Union of both FunctionFinished variants.
  * @since 0.1.0
  */
-export const FunctionFinished = Schema.Union(FunctionFinishedError, FunctionFinishedSuccess);
+export const FunctionFinished = Schema.Union([FunctionFinishedError, FunctionFinishedSuccess]);
 export type FunctionFinished = typeof FunctionFinished.Type;
 
 /**
@@ -75,7 +75,7 @@ export class FunctionCancelled extends Schema.TaggedClass<FunctionCancelled>()("
  * @since 0.1.0
  */
 export class FunctionInvoked extends Schema.TaggedClass<FunctionInvoked>()("inngest/function.invoked", {
-  data: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+  data: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
 }) {}
 
 /**