@boostkit/queue-inngest 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 BoostKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# @boostkit/queue-inngest
+
+Inngest serverless queue adapter for `@boostkit/queue`.
+
+## Installation
+
+```bash
+pnpm add @boostkit/queue-inngest inngest
+```
+
+## Usage
+
+### 1. Configure the queue
+
+```ts
+// config/queue.ts
+import { Env } from '@boostkit/core/support'
+import { SendWelcomeEmailJob } from '../app/Jobs/SendWelcomeEmailJob.js'
+
+export default {
+  default: 'inngest',
+  connections: {
+    inngest: {
+      driver:     'inngest',
+      appId:      Env.get('INNGEST_APP_ID', 'my-forge-app'),
+      signingKey: Env.get('INNGEST_SIGNING_KEY'),
+      eventKey:   Env.get('INNGEST_EVENT_KEY'),
+      baseUrl:    Env.get('APP_URL', 'http://localhost:3000'),
+      jobs: [
+        SendWelcomeEmailJob,
+      ],
+    },
+  },
+}
+```
+
+### 2. Register the provider
+
+```ts
+// bootstrap/providers.ts
+import { queue } from '@boostkit/queue'
+import configs from '../config/index.js'
+
+export default [
+  queue(configs.queue),
+]
+```
+
+### 3. Mount the Inngest endpoint
+
+Inngest requires an HTTP endpoint to receive function registration and event delivery. Mount it in your routes:
+
+```ts
+// routes/api.ts
+import { router } from '@boostkit/router'
+import { inngest } from '@boostkit/queue-inngest'
+import configs from '../config/index.js'
+
+// Mount the Inngest serve handler at /api/inngest
+router.all('/api/inngest', inngest(configs.queue.connections.inngest).serveHandler())
+```
+
+### 4. Define jobs
+
+```ts
+// app/Jobs/SendWelcomeEmailJob.ts
+import { Job } from '@boostkit/queue'
+
+export class SendWelcomeEmailJob extends Job {
+  static retries = 3   // Optional: override default retry count
+
+  constructor(private readonly data: { email: string; name: string }) {
+    super()
+  }
+
+  async handle(): Promise<void> {
+    await sendEmail({
+      to:      this.data.email,
+      subject: 'Welcome!',
+      body:    `Hello, ${this.data.name}!`,
+    })
+  }
+}
+```
+
+### 5. Dispatch jobs
+
+```ts
+import { SendWelcomeEmailJob } from '../app/Jobs/SendWelcomeEmailJob.js'
+
+await SendWelcomeEmailJob.dispatch({
+  data: { email: 'alice@example.com', name: 'Alice' }
+}).send()
+```
+
+## API Reference
+
+- `InngestConfig`
+- `inngest(config)` → `QueueAdapterProvider`
+- `inngest(config).serveHandler()` → route handler for `router.all('/api/inngest', ...)`
+
+## Configuration
+
+- `InngestConfig`
+  - `driver` — `'inngest'`
+  - `appId` — unique app identifier shown in the Inngest dashboard
+  - `signingKey?` — Inngest signing key (required in production)
+  - `eventKey?` — Inngest event key (required in production)
+  - `baseUrl?` — app's public URL (Inngest uses this to call your serve endpoint)
+  - `jobs` — array of job classes to register with Inngest
+
+## Event Naming
+
+Forge maps job class names to Inngest event names using the pattern:
+
+```
+forge/job.<ClassName>
+```
+
+For example, `SendWelcomeEmailJob` is dispatched as the `forge/job.SendWelcomeEmailJob` event.
+
+## Retries
+
+Override the default retry count on a job class:
+
+```ts
+export class SendWelcomeEmailJob extends Job {
+  static retries = 5   // retry up to 5 times on failure
+  // ...
+}
+```
+
+## Development Setup
+
+In development, run the [Inngest Dev Server](https://www.inngest.com/docs/dev-server) locally:
+
+```bash
+npx inngest-cli@latest dev
+```
+
+The dev server runs at `http://localhost:8288` and automatically discovers your functions by calling the `/api/inngest` endpoint. No signing key is needed in development.
+
+Set `APP_URL` so Inngest can reach your endpoint:
+
+```dotenv
+APP_URL=http://localhost:3000
+INNGEST_APP_ID=my-forge-app
+```
+
+## Production Setup
+
+In production (Inngest Cloud):
+
+```dotenv
+INNGEST_APP_ID=my-forge-app
+INNGEST_SIGNING_KEY=signkey-prod-...
+INNGEST_EVENT_KEY=eventkey-...
+APP_URL=https://my-app.example.com
+```
+
+Inngest will call your `/api/inngest` endpoint to register functions and deliver events.
+
+## Notes
+
+- All job classes must be listed in the `jobs` array for Inngest to register them
+- The `/api/inngest` route must be publicly reachable for Inngest to deliver events
+- Inngest handles retries, concurrency, and observability automatically via the dashboard
+- `serveHandler()` returns a `MiddlewareHandler` compatible with `router.all()`

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import type { Job, QueueAdapterProvider } from '@boostkit/queue';
+export interface InngestConfig {
+    appId?: string;
+    eventKey?: string;
+    signingKey?: string;
+    /**
+     * Job classes to register as Inngest functions.
+     * Each class is mapped to a "forge/job.<ClassName>" event.
+     *
+     * @example
+     *   jobs: [WelcomeUserJob, ProcessOrderJob]
+     */
+    jobs?: (new (...args: never[]) => Job)[];
+    [key: string]: unknown;
+}
+export declare function inngest(config?: InngestConfig): QueueAdapterProvider;
+//# 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":"AAEA,OAAO,KAAK,EACV,GAAG,EAEH,oBAAoB,EAErB,MAAM,iBAAiB,CAAA;AAIxB,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAO,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAI,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,CAAC,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,GAAG,CAAC,EAAE,CAAA;IACxC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AA4ED,wBAAgB,OAAO,CAAC,MAAM,GAAE,aAAkB,GAAG,oBAAoB,CAMxE"}

package/dist/index.js

@@ -0,0 +1,64 @@
+import { Inngest } from 'inngest';
+import { serve } from 'inngest/hono';
+// ─── Helpers ───────────────────────────────────────────────
+/** Derives the Inngest event name from a Job class */
+function eventName(JobClass) {
+    return `forge/job.${JobClass.name}`;
+}
+// ─── Inngest Adapter ───────────────────────────────────────
+class InngestAdapter {
+    client;
+    handler;
+    constructor(config) {
+        this.client = new Inngest({
+            id: config.appId ?? 'forge-app',
+            ...(config.eventKey ? { eventKey: config.eventKey } : {}),
+        });
+        // Register each job class as an Inngest function.
+        // When Inngest calls the serve endpoint for an event, it reconstructs
+        // the job from the serialized payload and calls handle().
+        const functions = (config.jobs ?? []).map((JobClass) => this.client.createFunction({
+            id: JobClass.name,
+            name: JobClass.name,
+            retries: (JobClass.retries ?? 3),
+        }, { event: eventName(JobClass) }, async ({ event }) => {
+            const payload = event.data['payload'] ?? {};
+            // Reconstruct the job instance from the serialized payload.
+            // TypeScript `private` fields are plain JS properties at runtime,
+            // so Object.assign correctly restores them.
+            const job = Object.assign(new JobClass(), payload);
+            await job.handle();
+        }));
+        // Build the Hono-compatible serve handler for GET + POST /api/inngest.
+        // The Hono Context (c) is passed directly — it IS req.raw in the Forge adapter.
+        this.handler = serve({
+            client: this.client,
+            functions,
+            ...(config.signingKey ? { signingKey: config.signingKey } : {}),
+        });
+    }
+    async dispatch(job, options = {}) {
+        const name = job.constructor.name;
+        await this.client.send({
+            name: eventName({ name }),
+            data: {
+                job: name,
+                payload: JSON.parse(JSON.stringify(job)),
+                queue: options.queue ?? 'default',
+            },
+            ...(options.delay ? { ts: Date.now() + options.delay } : {}),
+        });
+    }
+    serveHandler() {
+        return this.handler;
+    }
+}
+// ─── Factory ───────────────────────────────────────────────
+export function inngest(config = {}) {
+    return {
+        create() {
+            return new InngestAdapter(config);
+        },
+    };
+}
+//# 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,37 @@
+{
+  "name": "@boostkit/queue-inngest",
+  "version": "0.0.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/boostkitjs/boostkit",
+    "directory": "packages/queue-inngest"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "inngest": "^3.0.0",
+    "@boostkit/queue": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}