@beignet/provider-inngest 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @beignet/provider-inngest
+
+## 0.0.1
+
+- Initial Beignet release under the `@beignet` npm scope.

package/README.md

@@ -0,0 +1,290 @@
+# @beignet/provider-inngest
+
+Inngest-backed `JobDispatcherPort` provider for Beignet applications.
+
+The provider installs the app-facing `ctx.ports.jobs` dispatcher for durable
+background jobs using [Inngest](https://www.inngest.com/) and exposes
+`ctx.ports.inngest` only as an escape hatch for raw Inngest access.
+
+## Install
+
+```bash
+bun add @beignet/provider-inngest @beignet/core inngest
+```
+
+## Setup
+
+```typescript
+import { createNextServer } from "@beignet/next";
+import { definePorts } from "@beignet/core/ports";
+import { inngestProvider } from "@beignet/provider-inngest";
+import { routes } from "@/server/routes";
+
+// Set environment variables:
+// INNGEST_APP_NAME=my-app (optional, defaults to "beignet-app")
+// INNGEST_EVENT_KEY=your-event-key (optional, required for Inngest Cloud)
+
+const appPorts = definePorts({});
+
+export const server = await createNextServer({
+  ports: appPorts,
+  providers: [inngestProvider],
+  createContext: ({ ports }) => ({
+    ports,
+  }),
+  routes,
+});
+```
+
+## Usage
+
+Once the provider is registered, your ports include:
+
+- `jobs`: the canonical `JobDispatcherPort` for app code.
+- `inngest`: the raw Inngest escape hatch for advanced usage.
+
+Define jobs with `@beignet/core/jobs`, then dispatch them through
+`ctx.ports.jobs`:
+
+```typescript
+import { createJobHandlers } from "@beignet/core/jobs";
+import { z } from "zod";
+
+const jobs = createJobHandlers<AppCtx>();
+
+export const SendInviteEmailJob = jobs.defineJob("mail.invite.send", {
+  payload: z.object({
+    inviteId: z.string(),
+    inviteeEmail: z.string().email(),
+  }),
+  retry: {
+    attempts: 3,
+  },
+  async handle({ payload, ctx }) {
+    await ctx.ports.mailer.send({
+      to: payload.inviteeEmail,
+      subject: "You were invited",
+      text: `Invite id: ${payload.inviteId}`,
+    });
+  },
+});
+
+async function inviteUser(ctx: AppCtx, input: InviteUserInput) {
+  const invite = await ctx.ports.db.invites.create({
+    inviterId: ctx.actor.id,
+    inviteeEmail: input.email,
+  });
+
+  await ctx.ports.jobs.dispatch(SendInviteEmailJob, {
+    inviteId: invite.id,
+    inviteeEmail: input.email,
+  });
+
+  return invite;
+}
+```
+
+## Configuration
+
+The Inngest provider reads configuration from environment variables with the `INNGEST_` prefix:
+
+| Variable | Required | Description | Default |
+|----------|----------|-------------|---------|
+| `INNGEST_APP_NAME` | No | Friendly application name shown in Inngest | `"beignet-app"` |
+| `INNGEST_EVENT_KEY` | No | Event key / signing key for Inngest Cloud | - |
+
+**Note:** `INNGEST_EVENT_KEY` is required when using Inngest Cloud for production deployments.
+
+## Ports
+
+### `jobs: JobDispatcherPort`
+
+The `jobs` port is the recommended application API. It validates and parses the
+job payload with the job definition before sending an Inngest event using the
+job name.
+
+```typescript
+await ctx.ports.jobs.dispatch(SendInviteEmailJob, {
+  inviteId: invite.id,
+  inviteeEmail: input.email,
+});
+```
+
+### `inngest: InngestPort`
+
+The `inngest` port is an escape hatch for direct Inngest usage.
+
+#### `send<TData>(args: { name: string; data: TData }): Promise<void>`
+
+Send a raw event to Inngest. Prefer `ctx.ports.jobs.dispatch(...)` for
+first-class Beignet jobs.
+
+```typescript
+await ctx.ports.inngest.send({
+  name: "user.invited",
+  data: {
+    inviterId: ctx.actor.id,
+    inviteeEmail: input.email,
+    inviteId: createdInvite.id,
+  },
+});
+```
+
+#### `client: Inngest`
+
+Access the underlying Inngest client for advanced operations.
+
+```typescript
+// Define Inngest functions using the client directly
+const myFunction = ctx.ports.inngest.client.createFunction(
+  { id: "my-function" },
+  { event: "user.invited" },
+  async ({ event, step }) => {
+    // Your function logic
+  }
+);
+```
+
+## Devtools
+
+When `@beignet/devtools` is registered before this provider, calls to
+`ctx.ports.jobs.dispatch(...)` and `ctx.ports.inngest.send(...)` are recorded
+automatically under the `jobs` watcher. Successful enqueues are recorded as
+`scheduled`; failed enqueues are recorded as `failed` with schedule-phase error
+details.
+
+Pass an instrumentation target to `createInngestJobFunction(...)` to record
+worker execution as `started`, `completed`, and `failed` events:
+
+```typescript
+const sendInviteEmail = createInngestJobFunction({
+  client: inngest,
+  job: SendInviteEmailJob,
+  ctx: () => createBackgroundContext(),
+  instrumentation: appPorts.devtools,
+});
+```
+
+## TypeScript support
+
+To get proper type inference, include both provider-contributed ports in your
+app ports type:
+
+```typescript
+import { definePorts } from "@beignet/core/ports";
+import type { JobDispatcherPort } from "@beignet/core/ports";
+import type { InngestPort } from "@beignet/provider-inngest";
+
+// Your base ports, if any
+const basePorts = definePorts({});
+
+type AppPorts = typeof basePorts & {
+  jobs: JobDispatcherPort;
+  inngest: InngestPort;
+};
+```
+
+## Wiring domain events → Inngest jobs
+
+This provider does NOT automatically subscribe to domain events. That is
+intentional: events are facts that happened, while jobs are explicit work to do.
+
+To wire a domain event to a durable job, register a listener in your application
+and dispatch the job from the listener:
+
+```typescript
+// features/users/listeners.ts
+import { createEventHandlers } from "@beignet/core/events";
+import { UserInvited } from "@/features/users/domain/events";
+import { SendInviteEmailJob } from "@/features/users/jobs";
+import type { AppCtx } from "@/app-context";
+
+const events = createEventHandlers<AppCtx>();
+
+export const sendInviteEmail = events.defineListener(UserInvited, {
+  name: "mail.send-invite-email",
+  async handle({ payload, ctx }) {
+    await ctx.ports.jobs.dispatch(SendInviteEmailJob, {
+      inviteId: payload.inviteId,
+      inviteeEmail: payload.inviteeEmail,
+    });
+  },
+});
+```
+
+Register that listener against your event bus during infrastructure startup.
+In tests, use `createInlineJobDispatcher(...)` from `@beignet/core/jobs`; in
+production, install `inngestProvider`.
+
+## Inngest functions
+
+Use `createInngestJobFunction(...)` to turn a first-class Beignet job into
+an Inngest function. The helper subscribes to `job.name`, validates incoming
+event data with `parseJobPayload`, and then calls `job.handle(...)`.
+
+If the job defines `retry.attempts`, the helper maps it to Inngest's
+function-level `retries` option. Inngest supports integer values from `0` to
+`20`; values outside that range throw during function creation.
+
+Define functions separately from your Beignet server, usually in a
+serverless function or route handler:
+
+```typescript
+// app/api/inngest/route.ts (Next.js App Router example)
+import { createInngestJobFunction } from "@beignet/provider-inngest";
+import { serve } from "inngest/next";
+import { inngest } from "@/infra/inngest";
+import { SendInviteEmailJob } from "@/features/users/jobs";
+import { createBackgroundContext } from "@/infra/background-context";
+
+const sendInviteEmail = createInngestJobFunction({
+  client: inngest,
+  job: SendInviteEmailJob,
+  ctx: () => createBackgroundContext(),
+});
+
+export const { GET, POST, PUT } = serve({
+  client: inngest,
+  functions: [sendInviteEmail],
+});
+```
+
+`createBackgroundContext()` is application-owned. Put it near your
+infrastructure wiring and return the ports, logger, auth assumptions, and
+devtools context your background workers need.
+
+## Lifecycle
+
+The Inngest provider:
+
+1. **During `setup`**:
+   - Creates Inngest client
+   - Returns the `jobs` port
+   - Returns the `inngest` escape hatch port
+2. **No cleanup needed**: Inngest client doesn't require explicit shutdown
+
+## Error handling
+
+The provider will throw errors in these cases:
+
+- Missing required configuration (though all fields have defaults or are optional)
+- Invalid configuration values
+
+Make sure to handle these during application startup.
+
+## Local development
+
+For local development, you can run the Inngest Dev Server:
+
+```bash
+npx inngest-cli@latest dev
+```
+
+This provides a local UI at `http://localhost:8288` where you can:
+- View events
+- Trigger functions
+- Debug execution
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @beignet/provider-inngest
+ *
+ * Inngest provider that extends ports with background job and event capabilities using Inngest.
+ *
+ * Configuration:
+ * - INNGEST_APP_NAME: Friendly application name shown in Inngest (optional, default: "beignet-app")
+ * - INNGEST_EVENT_KEY: Optional event key / signing key for Inngest cloud
+ *
+ * @example
+ * ```ts
+ * import { createNextServer } from "@beignet/next";
+ * import { inngestProvider } from "@beignet/provider-inngest";
+ *
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [inngestProvider],
+ *   // ...
+ * });
+ *
+ * // In your use cases:
+ * await ctx.ports.jobs.dispatch(SendInviteEmailJob, {
+ *   inviteId: createdInvite.id,
+ *   inviteeEmail: input.email,
+ * });
+ * ```
+ */
+import type { JobDef, MaybePromise, StandardSchema } from "@beignet/core/jobs";
+import type { JobDispatcherPort } from "@beignet/core/ports";
+import { type ProviderInstrumentationTarget } from "@beignet/core/providers";
+import { Inngest, type InngestFunction } from "inngest";
+import { z } from "zod";
+/**
+ * Configuration schema for the Inngest provider.
+ * Validates environment variables with INNGEST_ prefix.
+ */
+declare const InngestConfigSchema: z.ZodObject<{
+    APP_NAME: z.ZodDefault<z.ZodString>;
+    EVENT_KEY: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Inferred configuration type for Inngest provider.
+ */
+export type InngestConfig = z.infer<typeof InngestConfigSchema>;
+/**
+ * Port interface for Inngest integration.
+ * Provides a stable abstraction over Inngest's client API.
+ */
+export interface InngestPort {
+    /**
+     * The raw Inngest client instance.
+     * Useful for advanced operations like defining functions.
+     */
+    client: Inngest;
+    /**
+     * Send an Inngest event.
+     * Equivalent to inngest.send({ name, data }).
+     *
+     * @example
+     * ```ts
+     * await ctx.ports.inngest.send({
+     *   name: "user.invited",
+     *   data: { inviteId, email }
+     * });
+     * ```
+     */
+    send<TData>(args: {
+        name: string;
+        data: TData;
+    }): Promise<void>;
+}
+export interface InngestJobDispatcherOptions {
+    instrumentation?: ProviderInstrumentationTarget;
+}
+export type InngestFunctionRetryAttempts = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20;
+export type InngestJobFunctionContext<Ctx> = Ctx | ((args: InngestJobFunctionContextArgs) => MaybePromise<Ctx>);
+export interface InngestJobFunctionContextArgs {
+    event: {
+        name: string;
+        data: unknown;
+    };
+    step: unknown;
+}
+export type InngestJobFunctionInstrumentation = ProviderInstrumentationTarget;
+export interface CreateInngestJobFunctionOptions<J extends JobDef<string, StandardSchema, Ctx>, Ctx> {
+    client: Inngest;
+    job: J;
+    id?: string;
+    name?: string;
+    description?: string;
+    ctx?: InngestJobFunctionContext<Ctx>;
+    instrumentation?: InngestJobFunctionInstrumentation;
+}
+export declare function createInngestJobDispatcher(client: Inngest, options?: InngestJobDispatcherOptions): JobDispatcherPort;
+export declare function createInngestJobFunction<Ctx, J extends JobDef<string, StandardSchema, Ctx>>(options: CreateInngestJobFunctionOptions<J, Ctx>): InngestFunction.Any;
+/**
+ * Inngest provider that extends ports with background job and event capabilities.
+ *
+ * This provider creates an Inngest client and exposes it through the ports system.
+ * It contributes a canonical `jobs` port for app code and keeps the raw
+ * Inngest client available as an escape hatch through `ports.inngest.client`.
+ *
+ * Configuration via environment variables:
+ * - INNGEST_APP_NAME: Application name (optional, default: "beignet-app")
+ * - INNGEST_EVENT_KEY: Event key for Inngest cloud (optional)
+ *
+ * @example
+ * ```ts
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [inngestProvider],
+ *   // ...
+ * });
+ * ```
+ */
+export declare const inngestProvider: import("@beignet/core/providers").ServiceProvider<unknown, z.ZodObject<{
+    APP_NAME: z.ZodDefault<z.ZodString>;
+    EVENT_KEY: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, {
+    inngest: InngestPort;
+    jobs: JobDispatcherPort;
+}>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAEV,MAAM,EACN,YAAY,EACZ,cAAc,EACf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAGL,KAAK,6BAA6B,EACnC,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,QAAA,MAAM,mBAAmB;;;iBAYvB,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAED,MAAM,WAAW,2BAA2B;IAC1C,eAAe,CAAC,EAAE,6BAA6B,CAAC;CACjD;AAED,MAAM,MAAM,4BAA4B,GACpC,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,EAAE,GACF,EAAE,GACF,EAAE,GACF,EAAE,GACF,EAAE,GACF,EAAE,GACF,EAAE,GACF,EAAE,GACF,EAAE,GACF,EAAE,GACF,EAAE,CAAC;AAEP,MAAM,MAAM,yBAAyB,CAAC,GAAG,IACrC,GAAG,GACH,CAAC,CAAC,IAAI,EAAE,6BAA6B,KAAK,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;AAEjE,MAAM,WAAW,6BAA6B;IAC5C,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,OAAO,CAAC;KACf,CAAC;IACF,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,iCAAiC,GAAG,6BAA6B,CAAC;AAE9E,MAAM,WAAW,+BAA+B,CAC9C,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,CAAC,EAC7C,GAAG;IAEH,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,CAAC,CAAC;IACP,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,yBAAyB,CAAC,GAAG,CAAC,CAAC;IACrC,eAAe,CAAC,EAAE,iCAAiC,CAAC;CACrD;AAgDD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,OAAO,EACf,OAAO,GAAE,2BAAgC,GACxC,iBAAiB,CAoCnB;AAED,wBAAgB,wBAAwB,CACtC,GAAG,EACH,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,CAAC,EAC7C,OAAO,EAAE,+BAA+B,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,eAAe,CAAC,GAAG,CAyDvE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe;;;;;;EA4D1B,CAAC"}

package/dist/index.js

@@ -0,0 +1,225 @@
+/**
+ * @beignet/provider-inngest
+ *
+ * Inngest provider that extends ports with background job and event capabilities using Inngest.
+ *
+ * Configuration:
+ * - INNGEST_APP_NAME: Friendly application name shown in Inngest (optional, default: "beignet-app")
+ * - INNGEST_EVENT_KEY: Optional event key / signing key for Inngest cloud
+ *
+ * @example
+ * ```ts
+ * import { createNextServer } from "@beignet/next";
+ * import { inngestProvider } from "@beignet/provider-inngest";
+ *
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [inngestProvider],
+ *   // ...
+ * });
+ *
+ * // In your use cases:
+ * await ctx.ports.jobs.dispatch(SendInviteEmailJob, {
+ *   inviteId: createdInvite.id,
+ *   inviteeEmail: input.email,
+ * });
+ * ```
+ */
+import { parseJobPayload } from "@beignet/core/jobs";
+import { createProvider, createProviderInstrumentation, } from "@beignet/core/providers";
+import { Inngest } from "inngest";
+import { z } from "zod";
+/**
+ * Configuration schema for the Inngest provider.
+ * Validates environment variables with INNGEST_ prefix.
+ */
+const InngestConfigSchema = z.object({
+    /**
+     * Application ID used as the client's `id` property in Inngest v3.
+     * This value uniquely identifies your application in Inngest and may be shown in the dashboard.
+     */
+    APP_NAME: z.string().default("beignet-app"),
+    /**
+     * Optional event key / signing key for Inngest cloud.
+     * Required when using Inngest Cloud for production deployments.
+     */
+    EVENT_KEY: z.string().optional(),
+});
+async function resolveJobContext(ctx, args) {
+    if (typeof ctx === "function") {
+        return ctx(args);
+    }
+    return ctx;
+}
+function errorDetails(phase, error) {
+    if (error instanceof Error) {
+        return {
+            phase,
+            error: {
+                name: error.name,
+                message: error.message,
+                stack: error.stack,
+            },
+        };
+    }
+    return {
+        phase,
+        error: String(error),
+    };
+}
+function resolveRetryAttempts(job) {
+    const attempts = job.retry?.attempts;
+    if (attempts === undefined)
+        return undefined;
+    if (!Number.isInteger(attempts) || attempts < 0 || attempts > 20) {
+        throw new Error(`[provider-inngest] Job "${job.name}" retry.attempts must be an integer between 0 and 20.`);
+    }
+    return attempts;
+}
+export function createInngestJobDispatcher(client, options = {}) {
+    const instrumentation = createProviderInstrumentation(options.instrumentation, {
+        providerName: "inngest",
+        watcher: "jobs",
+    });
+    return {
+        async dispatch(job, payload) {
+            const parsed = await parseJobPayload(job, payload);
+            try {
+                await client.send({ name: job.name, data: parsed });
+                instrumentation.record({
+                    type: "job",
+                    jobName: job.name,
+                    status: "scheduled",
+                });
+            }
+            catch (error) {
+                instrumentation.record({
+                    type: "job",
+                    jobName: job.name,
+                    status: "failed",
+                    details: errorDetails("schedule", error),
+                });
+                throw error;
+            }
+        },
+    };
+}
+export function createInngestJobFunction(options) {
+    const { client, job } = options;
+    const retries = resolveRetryAttempts(job);
+    const instrumentation = createProviderInstrumentation(options.instrumentation, {
+        providerName: "inngest",
+        watcher: "jobs",
+    });
+    return client.createFunction({
+        id: options.id ?? job.name,
+        name: options.name ?? job.name,
+        description: options.description ?? job.description,
+        ...(retries === undefined ? {} : { retries }),
+    }, { event: job.name }, async ({ event, step }) => {
+        instrumentation.record({
+            type: "job",
+            jobName: job.name,
+            status: "started",
+        });
+        try {
+            const payload = await parseJobPayload(job, event.data);
+            await job.handle({
+                job,
+                payload,
+                ctx: await resolveJobContext(options.ctx, {
+                    event: {
+                        name: event.name,
+                        data: event.data,
+                    },
+                    step,
+                }),
+            });
+            instrumentation.record({
+                type: "job",
+                jobName: job.name,
+                status: "completed",
+            });
+        }
+        catch (error) {
+            instrumentation.record({
+                type: "job",
+                jobName: job.name,
+                status: "failed",
+                details: errorDetails("execute", error),
+            });
+            throw error;
+        }
+    });
+}
+/**
+ * Inngest provider that extends ports with background job and event capabilities.
+ *
+ * This provider creates an Inngest client and exposes it through the ports system.
+ * It contributes a canonical `jobs` port for app code and keeps the raw
+ * Inngest client available as an escape hatch through `ports.inngest.client`.
+ *
+ * Configuration via environment variables:
+ * - INNGEST_APP_NAME: Application name (optional, default: "beignet-app")
+ * - INNGEST_EVENT_KEY: Event key for Inngest cloud (optional)
+ *
+ * @example
+ * ```ts
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [inngestProvider],
+ *   // ...
+ * });
+ * ```
+ */
+export const inngestProvider = createProvider({
+    name: "inngest",
+    config: {
+        schema: InngestConfigSchema,
+        envPrefix: "INNGEST_",
+    },
+    async setup({ ports, config }) {
+        if (!config) {
+            throw new Error("[inngestProvider] Missing config. Please set INNGEST_APP_NAME and optional INNGEST_EVENT_KEY.");
+        }
+        // Create Inngest client
+        const clientOptions = {
+            id: config.APP_NAME,
+        };
+        // Add event key if provided (required for Inngest Cloud)
+        if (config.EVENT_KEY) {
+            clientOptions.eventKey = config.EVENT_KEY;
+        }
+        const client = new Inngest(clientOptions);
+        const instrumentation = createProviderInstrumentation(ports, {
+            providerName: "inngest",
+            watcher: "jobs",
+        });
+        // Build port
+        const inngestPort = {
+            client,
+            async send({ name, data }) {
+                try {
+                    await client.send({ name, data });
+                    instrumentation.record({
+                        type: "job",
+                        jobName: name,
+                        status: "scheduled",
+                    });
+                }
+                catch (error) {
+                    instrumentation.record({
+                        type: "job",
+                        jobName: name,
+                        status: "failed",
+                        details: errorDetails("schedule", error),
+                    });
+                    throw error;
+                }
+            },
+        };
+        const jobs = createInngestJobDispatcher(client, { instrumentation });
+        return { ports: { inngest: inngestPort, jobs } };
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@beignet/provider-inngest",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Inngest provider for Beignet - adds inngest port for background jobs and events",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist coverage .turbo",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "biome check ."
+  },
+  "keywords": [
+    "beignet",
+    "inngest",
+    "provider",
+    "jobs",
+    "events",
+    "background-jobs",
+    "ports"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taylorbryant/beignet.git",
+    "directory": "packages/provider-inngest"
+  },
+  "author": "Taylor Bryant",
+  "homepage": "https://github.com/taylorbryant/beignet#readme",
+  "bugs": "https://github.com/taylorbryant/beignet/issues",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "inngest": "^3.0.0"
+  },
+  "dependencies": {
+    "zod": "^4.0.0",
+    "@beignet/core": "*"
+  },
+  "devDependencies": {
+    "@beignet/devtools": "*",
+    "@types/bun": "^1.3.13",
+    "@types/node": "^20.10.0",
+    "inngest": "^3.0.0",
+    "typescript": "^5.3.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,377 @@
+/**
+ * @beignet/provider-inngest
+ *
+ * Inngest provider that extends ports with background job and event capabilities using Inngest.
+ *
+ * Configuration:
+ * - INNGEST_APP_NAME: Friendly application name shown in Inngest (optional, default: "beignet-app")
+ * - INNGEST_EVENT_KEY: Optional event key / signing key for Inngest cloud
+ *
+ * @example
+ * ```ts
+ * import { createNextServer } from "@beignet/next";
+ * import { inngestProvider } from "@beignet/provider-inngest";
+ *
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [inngestProvider],
+ *   // ...
+ * });
+ *
+ * // In your use cases:
+ * await ctx.ports.jobs.dispatch(SendInviteEmailJob, {
+ *   inviteId: createdInvite.id,
+ *   inviteeEmail: input.email,
+ * });
+ * ```
+ */
+
+import type {
+  InferJobPayload,
+  JobDef,
+  MaybePromise,
+  StandardSchema,
+} from "@beignet/core/jobs";
+import { parseJobPayload } from "@beignet/core/jobs";
+import type { JobDispatcherPort } from "@beignet/core/ports";
+import {
+  createProvider,
+  createProviderInstrumentation,
+  type ProviderInstrumentationTarget,
+} from "@beignet/core/providers";
+import { Inngest, type InngestFunction } from "inngest";
+import { z } from "zod";
+
+/**
+ * Configuration schema for the Inngest provider.
+ * Validates environment variables with INNGEST_ prefix.
+ */
+const InngestConfigSchema = z.object({
+  /**
+   * Application ID used as the client's `id` property in Inngest v3.
+   * This value uniquely identifies your application in Inngest and may be shown in the dashboard.
+   */
+  APP_NAME: z.string().default("beignet-app"),
+
+  /**
+   * Optional event key / signing key for Inngest cloud.
+   * Required when using Inngest Cloud for production deployments.
+   */
+  EVENT_KEY: z.string().optional(),
+});
+
+/**
+ * Inferred configuration type for Inngest provider.
+ */
+export type InngestConfig = z.infer<typeof InngestConfigSchema>;
+
+/**
+ * Port interface for Inngest integration.
+ * Provides a stable abstraction over Inngest's client API.
+ */
+export interface InngestPort {
+  /**
+   * The raw Inngest client instance.
+   * Useful for advanced operations like defining functions.
+   */
+  client: Inngest;
+
+  /**
+   * Send an Inngest event.
+   * Equivalent to inngest.send({ name, data }).
+   *
+   * @example
+   * ```ts
+   * await ctx.ports.inngest.send({
+   *   name: "user.invited",
+   *   data: { inviteId, email }
+   * });
+   * ```
+   */
+  send<TData>(args: { name: string; data: TData }): Promise<void>;
+}
+
+export interface InngestJobDispatcherOptions {
+  instrumentation?: ProviderInstrumentationTarget;
+}
+
+export type InngestFunctionRetryAttempts =
+  | 0
+  | 1
+  | 2
+  | 3
+  | 4
+  | 5
+  | 6
+  | 7
+  | 8
+  | 9
+  | 10
+  | 11
+  | 12
+  | 13
+  | 14
+  | 15
+  | 16
+  | 17
+  | 18
+  | 19
+  | 20;
+
+export type InngestJobFunctionContext<Ctx> =
+  | Ctx
+  | ((args: InngestJobFunctionContextArgs) => MaybePromise<Ctx>);
+
+export interface InngestJobFunctionContextArgs {
+  event: {
+    name: string;
+    data: unknown;
+  };
+  step: unknown;
+}
+
+export type InngestJobFunctionInstrumentation = ProviderInstrumentationTarget;
+
+export interface CreateInngestJobFunctionOptions<
+  J extends JobDef<string, StandardSchema, Ctx>,
+  Ctx,
+> {
+  client: Inngest;
+  job: J;
+  id?: string;
+  name?: string;
+  description?: string;
+  ctx?: InngestJobFunctionContext<Ctx>;
+  instrumentation?: InngestJobFunctionInstrumentation;
+}
+
+async function resolveJobContext<Ctx>(
+  ctx: InngestJobFunctionContext<Ctx> | undefined,
+  args: InngestJobFunctionContextArgs,
+): Promise<Ctx> {
+  if (typeof ctx === "function") {
+    return (ctx as (args: InngestJobFunctionContextArgs) => MaybePromise<Ctx>)(
+      args,
+    );
+  }
+
+  return ctx as Ctx;
+}
+
+function errorDetails(phase: "schedule" | "execute", error: unknown) {
+  if (error instanceof Error) {
+    return {
+      phase,
+      error: {
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      },
+    };
+  }
+
+  return {
+    phase,
+    error: String(error),
+  };
+}
+
+function resolveRetryAttempts(
+  job: JobDef,
+): InngestFunctionRetryAttempts | undefined {
+  const attempts = job.retry?.attempts;
+  if (attempts === undefined) return undefined;
+
+  if (!Number.isInteger(attempts) || attempts < 0 || attempts > 20) {
+    throw new Error(
+      `[provider-inngest] Job "${job.name}" retry.attempts must be an integer between 0 and 20.`,
+    );
+  }
+
+  return attempts as InngestFunctionRetryAttempts;
+}
+
+export function createInngestJobDispatcher(
+  client: Inngest,
+  options: InngestJobDispatcherOptions = {},
+): JobDispatcherPort {
+  const instrumentation = createProviderInstrumentation(
+    options.instrumentation,
+    {
+      providerName: "inngest",
+      watcher: "jobs",
+    },
+  );
+
+  return {
+    async dispatch<J extends JobDef>(
+      job: J,
+      payload: InferJobPayload<J>,
+    ): Promise<void> {
+      const parsed = await parseJobPayload(job, payload);
+
+      try {
+        await client.send({ name: job.name, data: parsed });
+
+        instrumentation.record({
+          type: "job",
+          jobName: job.name,
+          status: "scheduled",
+        });
+      } catch (error) {
+        instrumentation.record({
+          type: "job",
+          jobName: job.name,
+          status: "failed",
+          details: errorDetails("schedule", error),
+        });
+
+        throw error;
+      }
+    },
+  };
+}
+
+export function createInngestJobFunction<
+  Ctx,
+  J extends JobDef<string, StandardSchema, Ctx>,
+>(options: CreateInngestJobFunctionOptions<J, Ctx>): InngestFunction.Any {
+  const { client, job } = options;
+  const retries = resolveRetryAttempts(job);
+  const instrumentation = createProviderInstrumentation(
+    options.instrumentation,
+    {
+      providerName: "inngest",
+      watcher: "jobs",
+    },
+  );
+
+  return client.createFunction(
+    {
+      id: options.id ?? job.name,
+      name: options.name ?? job.name,
+      description: options.description ?? job.description,
+      ...(retries === undefined ? {} : { retries }),
+    },
+    { event: job.name },
+    async ({ event, step }) => {
+      instrumentation.record({
+        type: "job",
+        jobName: job.name,
+        status: "started",
+      });
+
+      try {
+        const payload = await parseJobPayload(job, event.data);
+        await job.handle({
+          job,
+          payload,
+          ctx: await resolveJobContext(options.ctx, {
+            event: {
+              name: event.name,
+              data: event.data,
+            },
+            step,
+          }),
+        });
+
+        instrumentation.record({
+          type: "job",
+          jobName: job.name,
+          status: "completed",
+        });
+      } catch (error) {
+        instrumentation.record({
+          type: "job",
+          jobName: job.name,
+          status: "failed",
+          details: errorDetails("execute", error),
+        });
+
+        throw error;
+      }
+    },
+  ) as InngestFunction.Any;
+}
+
+/**
+ * Inngest provider that extends ports with background job and event capabilities.
+ *
+ * This provider creates an Inngest client and exposes it through the ports system.
+ * It contributes a canonical `jobs` port for app code and keeps the raw
+ * Inngest client available as an escape hatch through `ports.inngest.client`.
+ *
+ * Configuration via environment variables:
+ * - INNGEST_APP_NAME: Application name (optional, default: "beignet-app")
+ * - INNGEST_EVENT_KEY: Event key for Inngest cloud (optional)
+ *
+ * @example
+ * ```ts
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [inngestProvider],
+ *   // ...
+ * });
+ * ```
+ */
+export const inngestProvider = createProvider({
+  name: "inngest",
+
+  config: {
+    schema: InngestConfigSchema,
+    envPrefix: "INNGEST_",
+  },
+
+  async setup({ ports, config }) {
+    if (!config) {
+      throw new Error(
+        "[inngestProvider] Missing config. Please set INNGEST_APP_NAME and optional INNGEST_EVENT_KEY.",
+      );
+    }
+
+    // Create Inngest client
+    const clientOptions: { id: string; eventKey?: string } = {
+      id: config.APP_NAME,
+    };
+
+    // Add event key if provided (required for Inngest Cloud)
+    if (config.EVENT_KEY) {
+      clientOptions.eventKey = config.EVENT_KEY;
+    }
+
+    const client = new Inngest(clientOptions);
+    const instrumentation = createProviderInstrumentation(ports, {
+      providerName: "inngest",
+      watcher: "jobs",
+    });
+
+    // Build port
+    const inngestPort: InngestPort = {
+      client,
+      async send({ name, data }) {
+        try {
+          await client.send({ name, data });
+
+          instrumentation.record({
+            type: "job",
+            jobName: name,
+            status: "scheduled",
+          });
+        } catch (error) {
+          instrumentation.record({
+            type: "job",
+            jobName: name,
+            status: "failed",
+            details: errorDetails("schedule", error),
+          });
+
+          throw error;
+        }
+      },
+    };
+
+    const jobs = createInngestJobDispatcher(client, { instrumentation });
+
+    return { ports: { inngest: inngestPort, jobs } };
+  },
+});