@mantajs/adapter-queue-qstash 0.2.0-beta.0

package/dist/adapter.d.ts

@@ -0,0 +1,26 @@
+import type { IQueuePort, QueueMessage } from '@mantajs/core';
+export interface QStashQueueAdapterOptions {
+    /** Upstash QStash REST endpoint, e.g. `https://qstash-eu-central-1.upstash.io`. */
+    url: string;
+    /** Upstash QStash publish token (`QSTASH_TOKEN`). */
+    token: string;
+    /** Request timeout in ms (default 5s). */
+    timeoutMs?: number;
+    /** fetch override, for tests. */
+    fetch?: typeof globalThis.fetch;
+    /** Optional logger for delivery errors. */
+    logger?: {
+        warn: (msg: string) => void;
+        error?: (msg: string, err?: unknown) => void;
+    };
+}
+export declare class QStashQueueAdapter implements IQueuePort {
+    private _url;
+    private _token;
+    private _timeoutMs;
+    private _fetch;
+    private _logger;
+    constructor(opts: QStashQueueAdapterOptions);
+    enqueue(message: QueueMessage): Promise<void>;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAE7D,MAAM,WAAW,yBAAyB;IACxC,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAA;IACX,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAA;IACb,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iCAAiC;IACjC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IAC/B,2CAA2C;IAC3C,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAA;CACvF;AAED,qBAAa,kBAAmB,YAAW,UAAU;IACnD,OAAO,CAAC,IAAI,CAAQ;IACpB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,OAAO,CAAqC;gBAExC,IAAI,EAAE,yBAAyB;IAQrC,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAmCpD"}

package/dist/adapter.js

@@ -0,0 +1,63 @@
+// QStashQueueAdapter — IQueuePort backed by Upstash QStash (HTTP scheduler).
+//
+// QStash accepts a publish request (`POST {QSTASH_URL}/v2/publish/{dest}`)
+// and calls `dest` later with our payload as the POST body. It handles
+// retries (up to 3 by default), signed headers (HMAC-SHA256 over the body),
+// and delivery to internet-reachable URLs.
+//
+// Auth: `Authorization: Bearer $QSTASH_TOKEN` on the publish request.
+// Delivery headers on the receiving endpoint include
+// `Upstash-Signature` — verify with `@upstash/qstash` SDK or the
+// receiver-side `verifyQStashSignature` helper in this package.
+//
+// Free tier: 500 msg/day, enough for a rebuild button.
+export class QStashQueueAdapter {
+    _url;
+    _token;
+    _timeoutMs;
+    _fetch;
+    _logger;
+    constructor(opts) {
+        this._url = opts.url.replace(/\/+$/, '');
+        this._token = opts.token;
+        this._timeoutMs = opts.timeoutMs ?? 5_000;
+        this._fetch = opts.fetch ?? globalThis.fetch;
+        this._logger = opts.logger;
+    }
+    async enqueue(message) {
+        const target = `${this._url}/v2/publish/${encodeURIComponent(message.url)}`;
+        const headers = {
+            Authorization: `Bearer ${this._token}`,
+            'Content-Type': 'application/json',
+        };
+        if (message.delayMs && message.delayMs > 0) {
+            headers['Upstash-Delay'] = `${Math.ceil(message.delayMs / 1000)}s`;
+        }
+        if (message.idempotencyKey) {
+            // QStash doesn't have native idempotency on publish but accepts a
+            // custom `Upstash-Deduplication-Id` header on some plans; always include
+            // it — backend ignores it if unsupported.
+            headers['Upstash-Deduplication-Id'] = message.idempotencyKey;
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this._timeoutMs);
+        try {
+            const res = await this._fetch(target, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(message.payload ?? {}),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => '');
+                const msg = `[QStashQueueAdapter] publish ${res.status} for ${message.url}: ${body.slice(0, 200)}`;
+                this._logger?.warn?.(msg);
+                throw new Error(msg);
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,EAAE;AACF,2EAA2E;AAC3E,uEAAuE;AACvE,4EAA4E;AAC5E,2CAA2C;AAC3C,EAAE;AACF,sEAAsE;AACtE,qDAAqD;AACrD,iEAAiE;AACjE,gEAAgE;AAChE,EAAE;AACF,uDAAuD;AAiBvD,MAAM,OAAO,kBAAkB;IACrB,IAAI,CAAQ;IACZ,MAAM,CAAQ;IACd,UAAU,CAAQ;IAClB,MAAM,CAAyB;IAC/B,OAAO,CAAqC;IAEpD,YAAY,IAA+B;QACzC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;QACxC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAA;QACxB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,SAAS,IAAI,KAAK,CAAA;QACzC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAA;QAC5C,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAA;IAC5B,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,OAAqB;QACjC,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,eAAe,kBAAkB,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAA;QAC3E,MAAM,OAAO,GAA2B;YACtC,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;YACtC,cAAc,EAAE,kBAAkB;SACnC,CAAA;QACD,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;YAC3C,OAAO,CAAC,eAAe,CAAC,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAA;QACpE,CAAC;QACD,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;YAC3B,kEAAkE;YAClE,yEAAyE;YACzE,0CAA0C;YAC1C,OAAO,CAAC,0BAA0B,CAAC,GAAG,OAAO,CAAC,cAAc,CAAA;QAC9D,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;QACxC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,UAAU,CAAC,CAAA;QACnE,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE;gBACpC,MAAM,EAAE,MAAM;gBACd,OAAO;gBACP,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;gBAC3C,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAA;YACF,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;gBAC7C,MAAM,GAAG,GAAG,gCAAgC,GAAG,CAAC,MAAM,QAAQ,OAAO,CAAC,GAAG,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAA;gBAClG,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAAA;gBACzB,MAAM,IAAI,KAAK,CAAC,GAAG,CAAC,CAAA;YACtB,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAA;QACrB,CAAC;IACH,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { QStashQueueAdapter, type QStashQueueAdapterOptions } from './adapter';
+export { type VerifyQStashSignatureOptions, verifyQStashSignature } from './verify';
+//# 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,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,WAAW,CAAA;AAC9E,OAAO,EAAE,KAAK,4BAA4B,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAA"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { QStashQueueAdapter } from './adapter';
+export { verifyQStashSignature } from './verify';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAkC,MAAM,WAAW,CAAA;AAC9E,OAAO,EAAqC,qBAAqB,EAAE,MAAM,UAAU,CAAA"}

package/dist/verify.d.ts

@@ -0,0 +1,6 @@
+export interface VerifyQStashSignatureOptions {
+    currentSigningKey: string;
+    nextSigningKey?: string;
+}
+export declare function verifyQStashSignature(body: string, signatureHeader: string | null | undefined, opts: VerifyQStashSignatureOptions): boolean;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,4BAA4B;IAC3C,iBAAiB,EAAE,MAAM,CAAA;IACzB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC1C,IAAI,EAAE,4BAA4B,GACjC,OAAO,CAeT"}

package/dist/verify.js

@@ -0,0 +1,43 @@
+// verifyQStashSignature — HMAC-SHA256 verification for incoming QStash
+// deliveries. QStash signs the body with `QSTASH_CURRENT_SIGNING_KEY` (and
+// rotates to `QSTASH_NEXT_SIGNING_KEY` periodically — we accept both).
+//
+// Protocol (Upstash docs):
+//   - Request header `Upstash-Signature`: "v1,<base64url(HMAC-SHA256(body, key))>"
+//   - We recompute both signatures (current + next), accept the message if
+//     EITHER matches. This covers the ~5-minute key rotation window.
+//
+// Use in your resume endpoint before calling `manager.resume(runId)` so end
+// users can't directly POST /_workflow/:id/resume and replay old messages.
+import { createHmac, timingSafeEqual } from 'node:crypto';
+export function verifyQStashSignature(body, signatureHeader, opts) {
+    if (!signatureHeader)
+        return false;
+    const match = /^v1,(.+)$/.exec(signatureHeader.trim());
+    if (!match)
+        return false;
+    const signature = match[1];
+    const expectedCurrent = sign(body, opts.currentSigningKey);
+    if (safeEqual(signature, expectedCurrent))
+        return true;
+    if (opts.nextSigningKey) {
+        const expectedNext = sign(body, opts.nextSigningKey);
+        if (safeEqual(signature, expectedNext))
+            return true;
+    }
+    return false;
+}
+function sign(body, key) {
+    return createHmac('sha256', key).update(body).digest('base64url');
+}
+function safeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    try {
+        return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,2EAA2E;AAC3E,uEAAuE;AACvE,EAAE;AACF,2BAA2B;AAC3B,mFAAmF;AACnF,2EAA2E;AAC3E,qEAAqE;AACrE,EAAE;AACF,4EAA4E;AAC5E,2EAA2E;AAE3E,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAOzD,MAAM,UAAU,qBAAqB,CACnC,IAAY,EACZ,eAA0C,EAC1C,IAAkC;IAElC,IAAI,CAAC,eAAe;QAAE,OAAO,KAAK,CAAA;IAClC,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC,CAAA;IACtD,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAA;IACxB,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;IAE1B,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,iBAAiB,CAAC,CAAA;IAC1D,IAAI,SAAS,CAAC,SAAS,EAAE,eAAe,CAAC;QAAE,OAAO,IAAI,CAAA;IAEtD,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;QACxB,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,cAAc,CAAC,CAAA;QACpD,IAAI,SAAS,CAAC,SAAS,EAAE,YAAY,CAAC;YAAE,OAAO,IAAI,CAAA;IACrD,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC;AAED,SAAS,IAAI,CAAC,IAAY,EAAE,GAAW;IACrC,OAAO,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAA;AACnE,CAAC;AAED,SAAS,SAAS,CAAC,CAAS,EAAE,CAAS;IACrC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IACvC,IAAI,CAAC;QACH,OAAO,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@mantajs/adapter-queue-qstash",
+  "version": "0.2.0-beta.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@mantajs/core": "0.2.0-beta.0"
+  },
+  "files": [
+    "dist"
+  ]
+}