@nebutra/queue 0.1.0 → 0.1.1

package/dist/queuebase.js

@@ -0,0 +1,48 @@
+import { queuebaseJobs } from "./queuebase-webhook";
+export { createJobRouter, createQueuebaseWebhookHandler, defineQueueJob, listQueuebaseSchedules, queuebaseJobs, queuebaseWebhookHandler, verifyQueuebaseSignature, } from "./queuebase-webhook";
+export function createJobClient(router, options) {
+    return Object.fromEntries(Object.entries(router).map(([jobName, definition]) => [
+        jobName,
+        {
+            enqueue: async (input, enqueueOptions) => {
+                const parsed = definition.input.safeParse(input);
+                if (!parsed.success) {
+                    throw new Error(`Invalid input for job ${jobName}: ${parsed.error.message}`);
+                }
+                const { createJob, getQueue } = await import("./factory");
+                const queue = options.queue ?? (await getQueue());
+                const result = await queue.enqueue(createJob("queuebase", jobName, parsed.data, {
+                    ...enqueueOptions,
+                    maxRetries: enqueueOptions?.maxRetries ?? definition.defaults?.retries,
+                    metadata: {
+                        ...enqueueOptions?.metadata,
+                        queuebaseJobName: jobName,
+                        callbackUrl: options.callbackUrl,
+                        ...(options.apiUrl ? { apiUrl: options.apiUrl } : {}),
+                        ...(definition.defaults?.backoff ? { backoff: definition.defaults.backoff } : {}),
+                    },
+                }));
+                return {
+                    ...result,
+                    jobName,
+                    callbackUrl: options.callbackUrl,
+                };
+            },
+        },
+    ]));
+}
+export function getQueuebaseCallbackUrl(baseUrl = getBaseUrlFromEnv()) {
+    return `${baseUrl.replace(/\/$/, "")}/api/webhooks/queuebase`;
+}
+export const queuebaseJobClient = createJobClient(queuebaseJobs, {
+    apiUrl: process.env.QUEUEBASE_API_URL ?? "http://localhost:3847",
+    ...(process.env.QUEUEBASE_API_KEY ? { apiKey: process.env.QUEUEBASE_API_KEY } : {}),
+    callbackUrl: getQueuebaseCallbackUrl(),
+});
+function getBaseUrlFromEnv() {
+    if (process.env.NEXT_PUBLIC_SITE_URL)
+        return process.env.NEXT_PUBLIC_SITE_URL;
+    if (process.env.VERCEL_URL)
+        return `https://${process.env.VERCEL_URL}`;
+    return `http://localhost:${process.env.PORT ?? "3001"}`;
+}

package/dist/scheduled/index.d.ts

@@ -0,0 +1,15 @@
+export type { RunInvitationCleanupOptions } from "./jobs/invitation-cleanup";
+export { invitationCleanup, runInvitationCleanup } from "./jobs/invitation-cleanup";
+export type { RunSessionCleanupOptions } from "./jobs/session-cleanup";
+export { runSessionCleanup, sessionCleanup } from "./jobs/session-cleanup";
+export type { ScheduledJob, ScheduledJobResult } from "./scheduler";
+export { clearScheduledJobs, getScheduledJob, listScheduledJobs, registerScheduledJob, } from "./scheduler";
+/**
+ * Register the two built-in production scheduled jobs:
+ *   - `invitation-cleanup` (every 6h)
+ *   - `session-cleanup`    (daily 00:00 UTC)
+ *
+ * Idempotent — re-registering overwrites the previous entry.
+ */
+export declare function registerDefaultScheduledJobs(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/scheduled/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scheduled/index.ts"],"names":[],"mappings":"AASA,YAAY,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAC7E,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACpF,YAAY,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC3E,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAMrB;;;;;;GAMG;AACH,wBAAgB,4BAA4B,IAAI,IAAI,CAGnD"}

package/dist/scheduled/index.js

@@ -0,0 +1,25 @@
+// =============================================================================
+// @nebutra/queue/scheduled — scheduled (cron) job registry & built-in jobs
+// =============================================================================
+// Public re-exports:
+//   - The scheduler abstraction: register / get / list / clear scheduled jobs
+//   - Built-in production jobs: invitation-cleanup, session-cleanup
+//   - `registerDefaultScheduledJobs()` — convenience to register the built-ins
+// =============================================================================
+export { invitationCleanup, runInvitationCleanup } from "./jobs/invitation-cleanup";
+export { runSessionCleanup, sessionCleanup } from "./jobs/session-cleanup";
+export { clearScheduledJobs, getScheduledJob, listScheduledJobs, registerScheduledJob, } from "./scheduler";
+import { invitationCleanup } from "./jobs/invitation-cleanup";
+import { sessionCleanup } from "./jobs/session-cleanup";
+import { registerScheduledJob } from "./scheduler";
+/**
+ * Register the two built-in production scheduled jobs:
+ *   - `invitation-cleanup` (every 6h)
+ *   - `session-cleanup`    (daily 00:00 UTC)
+ *
+ * Idempotent — re-registering overwrites the previous entry.
+ */
+export function registerDefaultScheduledJobs() {
+    registerScheduledJob(invitationCleanup);
+    registerScheduledJob(sessionCleanup);
+}

package/dist/scheduled/jobs/invitation-cleanup.d.ts

@@ -0,0 +1,40 @@
+import type { ScheduledJob, ScheduledJobResult } from "../scheduler";
+/**
+ * Minimal subset of the Prisma client surface this job needs.
+ * Keeps the test fakes tiny and avoids pulling Prisma's full type into hot paths.
+ */
+interface InvitationCleanupClient {
+    organizationInvitation: {
+        updateMany(args: {
+            where: {
+                status: string;
+                expiresAt: {
+                    lt: Date;
+                };
+            };
+            data: {
+                status: string;
+            };
+        }): Promise<{
+            count: number;
+        }>;
+    };
+}
+export interface RunInvitationCleanupOptions {
+    /** Prisma client (or a structural fake in tests). */
+    client: InvitationCleanupClient;
+    /** Override "now" for deterministic testing. */
+    now?: () => Date;
+}
+/**
+ * Pure handler — flips rows whose `expiresAt < now()` and `status = 'pending'`
+ * to `status = 'expired'`. Returns the count of affected rows.
+ */
+export declare function runInvitationCleanup(options: RunInvitationCleanupOptions): Promise<ScheduledJobResult>;
+/**
+ * Registry-shaped definition. The handler resolves the real Prisma client
+ * lazily via dynamic import so tests don't need a live database.
+ */
+export declare const invitationCleanup: ScheduledJob;
+export {};
+//# sourceMappingURL=invitation-cleanup.d.ts.map

package/dist/scheduled/jobs/invitation-cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invitation-cleanup.d.ts","sourceRoot":"","sources":["../../../src/scheduled/jobs/invitation-cleanup.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAErE;;;GAGG;AACH,UAAU,uBAAuB;IAC/B,sBAAsB,EAAE;QACtB,UAAU,CAAC,IAAI,EAAE;YACf,KAAK,EAAE;gBAAE,MAAM,EAAE,MAAM,CAAC;gBAAC,SAAS,EAAE;oBAAE,EAAE,EAAE,IAAI,CAAA;iBAAE,CAAA;aAAE,CAAC;YACnD,IAAI,EAAE;gBAAE,MAAM,EAAE,MAAM,CAAA;aAAE,CAAC;SAC1B,GAAG,OAAO,CAAC;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAChC,CAAC;CACH;AAED,MAAM,WAAW,2BAA2B;IAC1C,qDAAqD;IACrD,MAAM,EAAE,uBAAuB,CAAC;IAChC,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,kBAAkB,CAAC,CAiB7B;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,YAO/B,CAAC"}

package/dist/scheduled/jobs/invitation-cleanup.js

@@ -0,0 +1,44 @@
+// =============================================================================
+// invitation-cleanup — marks expired pending OrganizationInvitation rows
+// =============================================================================
+// Scheduled every 6 hours. Idempotent — re-running the same hour is a no-op
+// because rows already flipped to `expired` no longer match the WHERE clause.
+//
+// The job is implemented as two layers:
+//   - `runInvitationCleanup({ client })` is the pure async unit, easily
+//      testable with an injected fake Prisma client.
+//   - `invitationCleanup` is the registry-shaped `ScheduledJob` whose
+//      handler resolves the real Prisma client from `@nebutra/db` lazily.
+// =============================================================================
+import { logger } from "@nebutra/logger";
+/**
+ * Pure handler — flips rows whose `expiresAt < now()` and `status = 'pending'`
+ * to `status = 'expired'`. Returns the count of affected rows.
+ */
+export async function runInvitationCleanup(options) {
+    const now = (options.now ?? (() => new Date()))();
+    const { count } = await options.client.organizationInvitation.updateMany({
+        where: {
+            status: "pending",
+            expiresAt: { lt: now },
+        },
+        data: { status: "expired" },
+    });
+    logger.info("[scheduled:invitation-cleanup] expired pending invitations", {
+        expired: count,
+        cutoff: now.toISOString(),
+    });
+    return { ok: true, details: { expired: count } };
+}
+/**
+ * Registry-shaped definition. The handler resolves the real Prisma client
+ * lazily via dynamic import so tests don't need a live database.
+ */
+export const invitationCleanup = {
+    name: "invitation-cleanup",
+    cron: "0 */6 * * *",
+    handler: async () => {
+        const { getSystemDb } = await import("@nebutra/db");
+        return runInvitationCleanup({ client: getSystemDb() });
+    },
+};

package/dist/scheduled/jobs/session-cleanup.d.ts

@@ -0,0 +1,24 @@
+import type { ScheduledJob, ScheduledJobResult } from "../scheduler";
+interface SessionCleanupClient {
+    authSession: {
+        deleteMany(args: {
+            where: {
+                expiresAt: {
+                    lt: Date;
+                };
+            };
+        }): Promise<{
+            count: number;
+        }>;
+    };
+}
+export interface RunSessionCleanupOptions {
+    /** Prisma client (or a structural fake in tests). */
+    client: SessionCleanupClient;
+    /** Override "now" for deterministic testing. */
+    now?: () => Date;
+}
+export declare function runSessionCleanup(options: RunSessionCleanupOptions): Promise<ScheduledJobResult>;
+export declare const sessionCleanup: ScheduledJob;
+export {};
+//# sourceMappingURL=session-cleanup.d.ts.map

package/dist/scheduled/jobs/session-cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-cleanup.d.ts","sourceRoot":"","sources":["../../../src/scheduled/jobs/session-cleanup.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAErE,UAAU,oBAAoB;IAC5B,WAAW,EAAE;QACX,UAAU,CAAC,IAAI,EAAE;YAAE,KAAK,EAAE;gBAAE,SAAS,EAAE;oBAAE,EAAE,EAAE,IAAI,CAAA;iBAAE,CAAA;aAAE,CAAA;SAAE,GAAG,OAAO,CAAC;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACtF,CAAC;CACH;AAED,MAAM,WAAW,wBAAwB;IACvC,qDAAqD;IACrD,MAAM,EAAE,oBAAoB,CAAC;IAC7B,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAe7B;AAED,eAAO,MAAM,cAAc,EAAE,YAO5B,CAAC"}

package/dist/scheduled/jobs/session-cleanup.js

@@ -0,0 +1,32 @@
+// =============================================================================
+// session-cleanup — deletes expired auth_sessions rows
+// =============================================================================
+// Scheduled daily at midnight UTC. Idempotent — already-deleted rows simply
+// don't match the next run's WHERE clause.
+//
+// Two layers (mirrors invitation-cleanup):
+//   - `runSessionCleanup({ client })` — pure async unit, DI-friendly.
+//   - `sessionCleanup` — registry-shaped `ScheduledJob`.
+// =============================================================================
+import { logger } from "@nebutra/logger";
+export async function runSessionCleanup(options) {
+    const now = (options.now ?? (() => new Date()))();
+    const { count } = await options.client.authSession.deleteMany({
+        where: {
+            expiresAt: { lt: now },
+        },
+    });
+    logger.info("[scheduled:session-cleanup] deleted expired auth sessions", {
+        deleted: count,
+        cutoff: now.toISOString(),
+    });
+    return { ok: true, details: { deleted: count } };
+}
+export const sessionCleanup = {
+    name: "session-cleanup",
+    cron: "0 0 * * *",
+    handler: async () => {
+        const { getSystemDb } = await import("@nebutra/db");
+        return runSessionCleanup({ client: getSystemDb() });
+    },
+};

package/dist/scheduled/scheduler.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Result returned by a scheduled job handler.
+ *
+ * - `ok`      — true on success, false on partial / soft failure
+ * - `details` — arbitrary structured payload (counts, IDs) for observability
+ */
+export interface ScheduledJobResult {
+    ok: boolean;
+    details?: Record<string, unknown>;
+}
+/**
+ * A scheduled job is a cron-triggered idempotent unit of work.
+ */
+export interface ScheduledJob {
+    /** Unique registry key — used by HTTP entry points to look up the handler. */
+    name: string;
+    /**
+     * Cron expression in standard 5-field syntax (minute hour dom month dow).
+     * This is metadata only — the registry never schedules anything itself.
+     */
+    cron: string;
+    /** The async unit of work. Must be idempotent. */
+    handler: () => Promise<ScheduledJobResult>;
+}
+/**
+ * Register a scheduled job. Re-registering the same name overwrites the
+ * previous entry (useful for tests; production code registers once at boot).
+ */
+export declare function registerScheduledJob(job: ScheduledJob): void;
+/**
+ * Look up a registered job by name. Returns `undefined` if not registered.
+ */
+export declare function getScheduledJob(name: string): ScheduledJob | undefined;
+/**
+ * List all registered jobs. Returns a snapshot array — mutating it does NOT
+ * affect the registry.
+ */
+export declare function listScheduledJobs(): ScheduledJob[];
+/**
+ * Remove all registered jobs. Intended for tests; production code should not
+ * call this.
+ */
+export declare function clearScheduledJobs(): void;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduled/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/scheduled/scheduler.ts"],"names":[],"mappings":"AAeA;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,OAAO,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC5C;AAMD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAW5D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEtE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,YAAY,EAAE,CAElD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/scheduled/scheduler.js

@@ -0,0 +1,52 @@
+// =============================================================================
+// Scheduled Job Registry — Provider-agnostic cron abstraction
+// =============================================================================
+// This module defines a pure runtime registry for scheduled (cron) jobs.
+//
+// Schedule activation is decoupled from job definition: jobs are registered
+// here with their cron expression, and an external scheduler (Vercel Cron,
+// QStash schedules, BullMQ repeatable jobs) triggers them via HTTP route or
+// worker.
+//
+// Default activation in this codebase is Vercel Cron — see
+// `apps/web/src/app/api/cron/<name>/route.ts` for the HTTP entry points and
+// the root `vercel.json` `crons` block for schedule activation.
+// =============================================================================
+// ── Registry (module-scoped Map) ────────────────────────────────────────────
+const registry = new Map();
+/**
+ * Register a scheduled job. Re-registering the same name overwrites the
+ * previous entry (useful for tests; production code registers once at boot).
+ */
+export function registerScheduledJob(job) {
+    if (!job.name || typeof job.name !== "string") {
+        throw new Error("[scheduler] job.name must be a non-empty string");
+    }
+    if (!job.cron || typeof job.cron !== "string") {
+        throw new Error("[scheduler] job.cron must be a non-empty string");
+    }
+    if (typeof job.handler !== "function") {
+        throw new Error("[scheduler] job.handler must be a function");
+    }
+    registry.set(job.name, job);
+}
+/**
+ * Look up a registered job by name. Returns `undefined` if not registered.
+ */
+export function getScheduledJob(name) {
+    return registry.get(name);
+}
+/**
+ * List all registered jobs. Returns a snapshot array — mutating it does NOT
+ * affect the registry.
+ */
+export function listScheduledJobs() {
+    return Array.from(registry.values());
+}
+/**
+ * Remove all registered jobs. Intended for tests; production code should not
+ * call this.
+ */
+export function clearScheduledJobs() {
+    registry.clear();
+}

package/dist/types.d.ts

@@ -0,0 +1,202 @@
+import { z } from "zod";
+/**
+ * Supported queue backend providers.
+ *
+ * - `qstash`  — Upstash QStash (serverless, HTTP-based, zero infra)
+ * - `bullmq`  — BullMQ over self-hosted Redis (full-featured, self-managed)
+ * - `sqs`     — AWS SQS (managed, pull-based, ideal for AWS-native deployments)
+ * - `memory`  — In-memory queue for local dev & testing (NOT for production)
+ */
+export type QueueProviderType = "qstash" | "bullmq" | "sqs" | "memory";
+export declare const JobOptionsSchema: z.ZodObject<{
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    delaySec: z.ZodOptional<z.ZodNumber>;
+    maxRetries: z.ZodOptional<z.ZodNumber>;
+    priority: z.ZodOptional<z.ZodNumber>;
+    cron: z.ZodOptional<z.ZodString>;
+    tenantId: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type JobOptions = z.infer<typeof JobOptionsSchema>;
+export declare const JobPayloadSchema: z.ZodObject<{
+    id: z.ZodString;
+    queue: z.ZodString;
+    type: z.ZodString;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    options: z.ZodOptional<z.ZodObject<{
+        idempotencyKey: z.ZodOptional<z.ZodString>;
+        delaySec: z.ZodOptional<z.ZodNumber>;
+        maxRetries: z.ZodOptional<z.ZodNumber>;
+        priority: z.ZodOptional<z.ZodNumber>;
+        cron: z.ZodOptional<z.ZodString>;
+        tenantId: z.ZodOptional<z.ZodString>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export type JobPayload = z.infer<typeof JobPayloadSchema>;
+export interface JobResult {
+    /** Provider-specific job/message ID */
+    jobId: string;
+    /** Acknowledged by the provider? */
+    accepted: boolean;
+    /** Provider name that handled the enqueue */
+    provider: QueueProviderType;
+}
+export type JobStatus = "pending" | "active" | "completed" | "failed" | "dead-lettered" | "delayed" | "waiting" | "canceled";
+export type JobLifecycleAction = "enqueued" | "started" | "attempt-failed" | "completed" | "failed" | "dead-lettered" | "canceled" | "retried";
+export interface JobLifecycleEvent {
+    id: string;
+    jobId: string;
+    queue: string;
+    action: JobLifecycleAction;
+    at: string;
+    attempt?: number;
+    reason?: string;
+    actor?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface JobLifecycleActionResult {
+    jobId: string;
+    queue: string;
+    accepted: boolean;
+    action: "cancel" | "retry";
+    reason?: string;
+}
+export interface JobStatusInfo {
+    id: string;
+    queue: string;
+    status: JobStatus;
+    attempts: number;
+    maxRetries: number;
+    failedReason?: string;
+    canceledReason?: string;
+    createdAt: string;
+    processedAt?: string;
+    completedAt?: string;
+    deadLetteredAt?: string;
+    canceledAt?: string;
+}
+export interface DeadLetterJob {
+    id: string;
+    queue: string;
+    type: string;
+    originalJob: JobPayload;
+    attempts: number;
+    maxRetries: number;
+    failedReason: string;
+    provider: QueueProviderType;
+    failedAt: string;
+}
+export type QueueDeadLetterRecord = Record<string, unknown>;
+export interface QueueDeadLetterFetchContext {
+    token: string;
+    endpoint?: string;
+    queue?: string;
+}
+export type QueueDeadLetterFetcher = (context: QueueDeadLetterFetchContext) => Promise<QueueDeadLetterRecord[]>;
+/**
+ * A job handler receives the payload and returns void on success
+ * or throws to trigger a retry.
+ */
+export type JobHandler<T extends Record<string, unknown> = Record<string, unknown>> = (job: JobPayload & {
+    data: T;
+}) => Promise<void>;
+/**
+ * Every queue backend must implement this interface.
+ * The factory function (`createQueue`) returns a `QueueProvider`.
+ */
+export interface QueueProvider {
+    readonly name: QueueProviderType;
+    /**
+     * Enqueue a job for async processing.
+     */
+    enqueue(job: JobPayload): Promise<JobResult>;
+    /**
+     * Enqueue multiple jobs in a single round-trip (where supported).
+     * Falls back to sequential enqueue if the provider has no native batch API.
+     */
+    enqueueBatch(jobs: JobPayload[]): Promise<JobResult[]>;
+    /**
+     * Register a handler for a given job type.
+     * - BullMQ: starts a Worker that polls Redis.
+     * - QStash: returns an HTTP handler to mount in your API route.
+     * - Memory: processes inline.
+     */
+    registerHandler<T extends Record<string, unknown>>(queue: string, type: string, handler: JobHandler<T>): void;
+    /**
+     * Query the status of a previously enqueued job (best-effort).
+     * Not all providers support this; returns `undefined` if unsupported.
+     */
+    getJobStatus?(jobId: string, queue: string): Promise<JobStatusInfo | undefined>;
+    /**
+     * Inspect jobs that exhausted retries and require operator attention.
+     * Providers without a durable DLQ may omit this method.
+     */
+    getDeadLetteredJobs?(queue?: string): Promise<DeadLetterJob[]>;
+    /**
+     * Return provider-neutral lifecycle logs for operator tooling.
+     * Providers without durable inspection may omit this method.
+     */
+    getJobLogs?(jobId: string, queue: string): Promise<JobLifecycleEvent[]>;
+    /**
+     * Cancel a pending/delayed job when supported.
+     */
+    cancelJob?(jobId: string, queue: string, reason?: string): Promise<JobLifecycleActionResult>;
+    /**
+     * Replay a failed or dead-lettered job when supported.
+     */
+    retryJob?(jobId: string, queue: string, reason?: string): Promise<JobLifecycleActionResult>;
+    /**
+     * Graceful shutdown — drain in-flight jobs, close connections.
+     */
+    close(): Promise<void>;
+}
+export interface QStashProviderConfig {
+    provider: "qstash";
+    /** QStash REST token (defaults to `process.env.QSTASH_TOKEN`) */
+    token?: string;
+    /**
+     * Base URL of your API that QStash will POST callbacks to.
+     * e.g. "https://api.nebutra.com" or "https://my-tunnel.ngrok.io"
+     */
+    callbackBaseUrl: string;
+    /** Optional signing keys for webhook verification */
+    currentSigningKey?: string;
+    nextSigningKey?: string;
+    /** Optional provider-side DLQ endpoint for injected fetchers. */
+    dlqEndpoint?: string;
+    /** Injectable provider-side DLQ fetcher. No Upstash SDK DLQ APIs are assumed. */
+    dlqFetcher?: QueueDeadLetterFetcher;
+}
+export interface BullMQProviderConfig {
+    provider: "bullmq";
+    /** Redis connection URL (defaults to `process.env.REDIS_URL`) */
+    redisUrl?: string;
+    /** Default concurrency per worker (default: 5) */
+    concurrency?: number;
+    /** Key prefix for Redis keys (default: "nebutra:queue") */
+    prefix?: string;
+}
+export interface MemoryProviderConfig {
+    provider: "memory";
+}
+export interface SQSProviderConfig {
+    provider: "sqs";
+    /** AWS region (defaults to `process.env.AWS_REGION`) */
+    region?: string;
+    /** SQS queue URL (defaults to `process.env.AWS_SQS_QUEUE_URL`) */
+    queueUrl?: string;
+    /** AWS access key (defaults to `process.env.AWS_ACCESS_KEY_ID`) */
+    accessKeyId?: string;
+    /** AWS secret key (defaults to `process.env.AWS_SECRET_ACCESS_KEY`) */
+    secretAccessKey?: string;
+    /** Long-poll wait time in seconds when receiving (1-20, default 20) */
+    waitTimeSeconds?: number;
+    /** Max messages per receive call (1-10, default 10) */
+    maxMessages?: number;
+    /** Visibility timeout in seconds — how long a received message is hidden (default 30) */
+    visibilityTimeoutSeconds?: number;
+}
+export type QueueConfig = QStashProviderConfig | BullMQProviderConfig | SQSProviderConfig | MemoryProviderConfig;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,32 @@
+import { z } from "zod";
+// ── Job Schema ──────────────────────────────────────────────────────────────
+export const JobOptionsSchema = z.object({
+    /** Unique idempotency key — prevents duplicate processing */
+    idempotencyKey: z.string().optional(),
+    /** Delay before the job becomes visible (in seconds) */
+    delaySec: z.number().int().min(0).optional(),
+    /** Maximum retry attempts on failure (default: 3) */
+    maxRetries: z.number().int().min(0).optional(),
+    /** Priority: lower number = higher priority (BullMQ only, ignored by QStash) */
+    priority: z.number().int().min(0).optional(),
+    /** Cron expression for recurring jobs (e.g. "0 3 * * *") */
+    cron: z.string().optional(),
+    /** Tenant isolation — jobs can be scoped to a tenant */
+    tenantId: z.string().optional(),
+    /** Arbitrary metadata passed through to the handler */
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export const JobPayloadSchema = z.object({
+    /** Globally unique job ID (auto-generated if omitted) */
+    id: z.string(),
+    /** Queue / topic name this job belongs to */
+    queue: z.string(),
+    /** Fully-qualified handler name (e.g. "email.send", "report.generate") */
+    type: z.string(),
+    /** Serialisable job data */
+    data: z.record(z.string(), z.unknown()),
+    /** Job scheduling & retry options */
+    options: JobOptionsSchema.optional(),
+    /** ISO-8601 creation timestamp */
+    createdAt: z.string().datetime(),
+});

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@nebutra/queue",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
-  "license": "AGPL-3.0",
+  "license": "MIT",
   "type": "module",
   "nebutra": {
     "status": "foundation",
     "productionReady": false,
     "requires": [
       "QSTASH_TOKEN (+ signing keys) for serverless",
+      "Configured QStash dlqFetcher/dlqEndpoint for provider-side DLQ observability",
       "REDIS_URL for BullMQ self-hosted",
       "AWS_SQS_QUEUE_URL (+ AWS credentials) for SQS"
     ],
     "gaps": [
-      "QStash provider dead letter retrieval not implemented",
       "Worker auto-scaling TODO"
     ]
   },
@@ -35,6 +35,18 @@
     "./sqs": {
       "types": "./dist/providers/sqs.d.ts",
       "import": "./dist/providers/sqs.js"
+    },
+    "./queuebase": {
+      "types": "./dist/queuebase.d.ts",
+      "import": "./dist/queuebase.js"
+    },
+    "./queuebase-webhook": {
+      "types": "./dist/queuebase-webhook.d.ts",
+      "import": "./dist/queuebase-webhook.js"
+    },
+    "./scheduled": {
+      "types": "./dist/scheduled/index.d.ts",
+      "import": "./dist/scheduled/index.js"
     }
   },
   "files": [
@@ -47,7 +59,8 @@
     "bullmq": "^5.34.8",
     "ioredis": "^5.4.2",
     "zod": "^4.3.6",
-    "@nebutra/logger": "0.1.0"
+    "@nebutra/logger": "0.1.0",
+    "@nebutra/provider-factory": "0.2.0"
   },
   "peerDependencies": {
     "@nebutra/db": "0.1.0"