@memberjunction/work-queue-core 0.0.1-seed.1 → 6.2.0-edge.4

package/LICENSE

@@ -0,0 +1,183 @@
+Business Source License 1.1
+
+License text copyright (c) 2024 MariaDB plc, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB plc.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Blue Cypress, Inc.
+
+Licensed Work:        MemberJunction.
+                      The Licensed Work is (c) 2023-2026 Blue Cypress, Inc.
+
+Additional Use Grant: Subject to the terms of this License, Licensor grants
+                      you the following additional rights to make Production
+                      Use of the Licensed Work.
+
+                      1. Internal Use
+
+                      You may make production use of the Licensed Work for
+                      your own internal business or organizational operations.
+
+                      2. Nonprofit Use
+
+                      If you are a Nonprofit, you may make production use of
+                      the Licensed Work for the operations and activities of
+                      your Organizational Family.
+
+                      3. MemberJunction Certified Program Use
+
+                      If you are authorized by Licensor under the
+                      MemberJunction Certified Program to provide professional
+                      services using the Licensed Work, you may make
+                      production use of the Licensed Work in providing such
+                      professional services to a client, provided that:
+
+                      (a) the Licensed Work is deployed in, and the applicable
+                      production use occurs within, an environment owned,
+                      leased, licensed, subscribed to, or otherwise controlled
+                      by that client; and
+
+                      (b) the production use is for that client's own internal
+                      business or organizational operations or is otherwise
+                      independently permitted to that client under this
+                      Additional Use Grant.
+
+                      4. Definitions Applicable to the Additional Use Grant
+
+                      "Affiliate" means, with respect to a specified Person,
+                      any other Person that directly or indirectly Controls,
+                      is Controlled by, or is under common Control with such
+                      specified Person.
+
+                      "Control" (including the terms "Controls," "Controlled
+                      by," and "under common Control with") means the direct
+                      or indirect possession of the power to direct or cause
+                      the direction of the management and policies of a
+                      Person, whether through ownership of voting interests,
+                      by contract, or otherwise.
+
+                      "Organizational Family" means, with respect to a Person,
+                      (a) such Person and its Affiliates, and (b) any
+                      nonprofit organization, governmental entity, chapter,
+                      division, local affiliate, regional affiliate, state
+                      affiliate, national affiliate, or other entity that is
+                      formally affiliated with such Person through governing
+                      documents, a charter, bylaws, a membership agreement, or
+                      another written organizational instrument, and is
+                      recognized under such documents as part of the same
+                      organizational structure.
+
+                      "Nonprofit" means a Person recognized by the Internal
+                      Revenue Service as exempt from federal income taxation
+                      under Section 501(c)(3), 501(c)(4), 501(c)(5), or
+                      501(c)(6) of the Internal Revenue Code, or a foreign
+                      organization recognized under substantially equivalent
+                      laws.
+
+                      A Person claiming eligibility as a Nonprofit shall, upon
+                      Licensor's reasonable request, provide documentation
+                      reasonably sufficient to demonstrate that it qualifies
+                      as a Nonprofit. If such Person materially misrepresents,
+                      or is unable to demonstrate, its qualification as a
+                      Nonprofit, the rights granted to such Person under
+                      Section 2 of this Additional Use Grant shall terminate.
+
+                      "MemberJunction Certified Program" means Licensor's
+                      then-current program for certifying and authorizing a
+                      Person to provide professional services using the
+                      Licensed Work.
+
+                      "Person" means any individual, corporation, limited
+                      liability company, partnership, association, nonprofit
+                      organization, governmental entity, or other legal or
+                      organizational entity.
+
+Change Date:          Four (4) years from the date the Licensed Work is first
+                      made available.
+
+Change License:       MIT License.
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact Blue Cypress, Inc.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+-----------------------------------------------------------------------------
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License
+   can be included in a program with software provided under GPL Version 2.0
+   or a later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.

package/README.md

@@ -1,4 +1,130 @@
 # @memberjunction/work-queue-core
-Seed release published over OIDC to prove trusted publishing is configured for
-this package. It contains no code and is tagged `seed`, never `latest`.
-Real releases are published by .github/workflows/publish.yml.
+
+Transport-neutral contracts and runtime for the MemberJunction durable work queue. **No MemberJunction
+runtime dependencies** — Lambda and other external consumers import only this package (plus a transport
+package such as `@memberjunction/work-queue-aws`).
+
+Design and contract: `02-implementation-overview.md` and `03-interfaces-and-tables.md` under `plans/work-queue-1/` on the `spec/work-queue` branch; the handler author's rules are in `guides/WORK_QUEUE_CONSUMER_GUIDE.md`.
+
+## What is in the box
+
+| Area | Exports |
+| --- | --- |
+| Envelope & publishing | `WorkMessage`, `PublishRequest`, `PublishResult`, `IWorkPublisher`, `ValidatePublishRequest`, `BuildWorkMessage`, `CanonicalEnvelope`, `PublishErrorCodes` |
+| Handlers | `WorkHandler`, `WorkContext`, `Outcome`, `FatalWorkError`, `TransientWorkError` |
+| Policy & rules | `SubscriptionPolicy`, `ParseSubscriptionFilter`, `ValidateSubscriptionFilter`, `MatchesFilter`, `FilterFields`, `WORK_QUEUE_FILTER_SUPPORT`, `ComputeBackoffSeconds`, `HeartbeatIntervalSeconds`, `SubscriptionUnsupportedReason`, `FilterUnsupportedReason` |
+| Transports | `ITransportDriver`, `ITransportConsumer`, `ITransportOperator`, `TransportCapabilities` |
+| Runtime | `ConsumerRuntime` (loop or `ProcessBatch`), `DeliveryExecution` |
+| Reference transport | `InMemoryTransport` (Database-transport semantics, in memory) |
+| REST client | `WorkQueueApiPublisher`, REST mapping helpers |
+| Testing (`/testing`) | `RunConformanceChecks`, `CONFORMANCE_CASES`, `ConformanceAssertionError`, `BuildTopicBinding`, `BuildSubscriptionBinding`, `ManualClock` |
+| Testing with vitest (`/testing/vitest`) | `RunTransportConformanceSuite` |
+
+## Writing a handler
+
+```typescript
+import { FatalWorkError, Outcome, type WorkContext, type WorkHandler, type WorkMessage } from '@memberjunction/work-queue-core';
+
+interface UnsubscribePayload { email: string; occurredAt: string }
+
+export class UnsubscribeHandler implements WorkHandler<UnsubscribePayload> {
+    public async Handle(message: WorkMessage<UnsubscribePayload>, context: WorkContext) {
+        if (!message.Payload?.email) {
+            throw new FatalWorkError('email missing');           // dead-letter immediately
+        }
+        await suppress(message.Payload.email, message.MessageID); // idempotent by MessageID
+        return Outcome.Complete();                                 // throw anything else → retry with backoff
+    }
+}
+```
+
+### Handler rules
+
+The queue guarantees durable delivery, one valid lease holder while your handler runs, and fencing. Everything
+else is yours — see `guides/WORK_QUEUE_CONSUMER_GUIDE.md`. Four rules cover most handlers:
+
+1. **Long awaits need no heartbeat code.** Keep `HeartbeatMode: 'Auto'` (the default) and set
+   `MaxProcessingSeconds` to the longest a healthy run should take: the runtime renews the lease while your
+   handler awaits, and aborts once the cap passes. Use `'Manual'` only when you want a *stuck* handler detected,
+   then call `await context.Heartbeat({ Percent })` at real progress boundaries.
+2. **Honor `context.Signal`.** It aborts when an operator cancels the item, the lease is lost, the processing cap
+   is hit, or the host shuts down; `context.Signal.reason` says which (`'Cancelled'`, `'LeaseLost'`,
+   `'MaxProcessingSeconds'`, `'Shutdown'`). Stop whatever external work you started — a child process, a remote
+   job, a long query. Stopping promptly matters: after a cancel, the runtime acknowledges it as soon as your
+   handler returns, which frees an `Exclusive`/`Ordered` key immediately instead of at lease expiry.
+3. **Never block the event loop.** A long synchronous CPU-bound loop stops the heartbeat timer with it and the
+   lease expires under you; move that work to a worker thread or child process.
+4. **Non-restartable side effects need your own guard.** At-least-once delivery means a handler can run twice.
+   Make handlers idempotent (`message.MessageID` is stable across redeliveries and replays), and for work that
+   must not overlap — an infrastructure apply, a financial posting — set a `LeaseSeconds` larger than your worst
+   heartbeat outage *and* hold a domain lock of your own.
+
+`context.Heartbeat` resolves `false` once the lease is gone or the delivery is cancelled; a transient transport
+error does not — it is retried on the next tick. The runtime heartbeats every `min(LeaseSeconds / 3, 30 s)`, so a
+cancel or a lost lease is noticed within 30 seconds however long the lease, and it enforces the lease's expiry on
+its own timer in both heartbeat modes — a `Manual` handler that stops heartbeating is aborted when its lease runs
+out.
+
+**Ordering is publish order.** There is no producer-supplied ordering number. If one producer owns a key's order,
+it publishes in order: do not publish N+1 until N is accepted, or publish both in one call. `Ordered`
+subscriptions need a topic on the Database transport.
+
+## Subscription filters
+
+A filter is MJ's standard `CompositeFilterDescriptor` JSON over **envelope attributes** — the shape
+`mj-filter-builder` edits and user views persist — restricted to what every transport can express:
+
+```jsonc
+{ "logic": "and", "filters": [
+  { "field": "eventType", "operator": "eq", "value": "click" },
+  { "logic": "or", "filters": [
+      { "field": "tenant", "operator": "eq", "value": "acme" },
+      { "field": "tenant", "operator": "eq", "value": "globex" } ] }
+] }
+```
+
+Operators: `eq`, `neq`, `startswith`, `isnull`, `isnotnull`. The root is `and`; a nested group may only be a
+single-field OR of `eq`; and each field may be constrained only once (brokers read a field's values as OR, so two
+AND-ed rules on one field would widen the filter rather than narrow it). Matching is **case-sensitive** (brokers match exactly, so MJ and the broker agree),
+which is the one deliberate divergence from `CompositeFilter`'s case-insensitive comparison. Richer filters are
+rejected by `ValidateSubscriptionFilter` / `SubscriptionUnsupportedReason` when a subscription is saved, rather
+than silently delivering everything.
+
+## Publishing from outside MJ
+
+```typescript
+import { WorkQueueApiPublisher } from '@memberjunction/work-queue-core';
+
+const publisher = new WorkQueueApiPublisher({ BaseUrl: 'https://api.example.com/work-queue', ApiKey: process.env.MJ_API_KEY ?? '' });
+const results = await publisher.Publish('email.events', [
+    { PartitionKey: 'alice@example.com', Attributes: { eventType: 'unsubscribe' }, Payload: { email: 'alice@example.com', occurredAt: '2026-09-16T12:00:00Z' }, DeduplicationKey: 'sg:evt-123' },
+]);
+// Every result is Accepted, Duplicate or Rejected; retry Rejected items whose Error.Retryable is true.
+```
+
+## Testing a transport driver
+
+```typescript
+import { BuildTopicBinding, BuildSubscriptionBinding } from '@memberjunction/work-queue-core/testing';
+import { RunTransportConformanceSuite } from '@memberjunction/work-queue-core/testing/vitest';
+
+RunTransportConformanceSuite('MyTransport', {
+    Capabilities: MY_CAPABILITIES,
+    Traits: { ReleaseConsumesAttempt: false, ExpiredLeaseDeadLetters: true, ReceiveWaitSeconds: 0 },
+    CreateDriver: async () => new MyTransport(),
+    CreateTopic: async (_driver, name, overrides) => BuildTopicBinding(name, overrides),
+    CreateSubscription: async (_driver, topic, name, overrides) => BuildSubscriptionBinding(topic, name, overrides),
+    AdvanceTime: async (ms) => clock.Advance(ms),
+});
+```
+
+Outside vitest (for example an integration runner against a live database), call
+`await RunConformanceChecks(harness)` from `/testing`: it runs the same 26 cases sequentially, never throws, and
+returns `{ Id, Title, Status: 'Passed' | 'Failed' | 'Skipped', Detail, DurationMs }` per case.
+
+`vitest` is an optional peer dependency used only by `/testing/vitest`.
+
+## Rules for contributors
+
+- No `@memberjunction/*` dependency or import, and no runtime `dependencies` — enforced by `src/__tests__/dependencyGuard.test.ts`.
+- `cd packages/WorkQueue/core && pnpm test` and `pnpm run build`.

package/dist/api/WorkQueueApiPublisher.d.ts

@@ -0,0 +1,35 @@
+import type { WorkJson } from '../envelope.js';
+import type { IWorkPublisher, PublishRequest, PublishResult } from '../publishing.js';
+export interface WorkQueueApiPublisherOptions {
+    /** Root of the work-queue REST extension, e.g. https://api.example.com/work-queue */
+    BaseUrl: string;
+    /** MJ API key with workqueue:publish for the target topics. */
+    ApiKey: string;
+    Fetch?: typeof fetch;
+    /** Retries after the first attempt. Default 3. */
+    MaxRetries?: number;
+    /** Per-request timeout. Default 10000. */
+    TimeoutMs?: number;
+    /** Base for exponential retry delay. Default 200. */
+    RetryBaseDelayMs?: number;
+    NewId?: () => string;
+    Sleep?: (ms: number) => Promise<void>;
+}
+export declare class WorkQueueApiPublisher implements IWorkPublisher {
+    private readonly options;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly maxRetries;
+    private readonly timeoutMs;
+    private readonly retryBaseDelayMs;
+    private readonly newId;
+    private readonly sleep;
+    constructor(options: WorkQueueApiPublisherOptions);
+    Publish<TPayload extends WorkJson>(topic: string, requests: PublishRequest<TPayload>[]): Promise<PublishResult[]>;
+    private publishChunk;
+    private send;
+    private retryDelayMs;
+}
+/** Upper bound on a server-requested wait: a hostile or mistaken header must not park a producer. */
+export declare const MAX_RETRY_AFTER_SECONDS = 60;
+//# sourceMappingURL=WorkQueueApiPublisher.d.ts.map

package/dist/api/WorkQueueApiPublisher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkQueueApiPublisher.d.ts","sourceRoot":"","sources":["../../src/api/WorkQueueApiPublisher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAInF,MAAM,WAAW,4BAA4B;IACzC,qFAAqF;IACrF,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AA2BD,qBAAa,qBAAsB,YAAW,cAAc;IAS5C,OAAO,CAAC,QAAQ,CAAC,OAAO;IARpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;gBAEzB,OAAO,EAAE,4BAA4B;IAUrD,OAAO,CAAC,QAAQ,SAAS,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;YAShH,YAAY;YAgBZ,IAAI;IAoBlB,OAAO,CAAC,YAAY;CAMvB;AA2CD,qGAAqG;AACrG,eAAO,MAAM,uBAAuB,KAAK,CAAC"}

package/dist/api/WorkQueueApiPublisher.js

@@ -0,0 +1,136 @@
+import { PublishErrorCodes, RejectedPublishResult } from '../publishing.js';
+import { MAX_REST_PUBLISH_BATCH, ParseRestPublishResponse, ToRestPublishRequest } from './restContract.js';
+const FALLBACK_CODES = new Map([
+    [400, PublishErrorCodes.BadRequest],
+    [401, PublishErrorCodes.Unauthorized],
+    [403, PublishErrorCodes.Forbidden],
+    [404, PublishErrorCodes.TopicNotFound],
+    [413, PublishErrorCodes.PayloadTooLarge],
+]);
+/** IWorkPublisher for producers outside MJ: calls the MJ work-queue REST publish endpoint (spec 03 §9). */
+/** Drops every trailing '/' without a regex (a `/\/+$/` pattern on caller input is polynomial-time). */
+function TrimTrailingSlashes(url) {
+    let end = url.length;
+    while (end > 0 && url[end - 1] === '/') {
+        end -= 1;
+    }
+    return url.slice(0, end);
+}
+export class WorkQueueApiPublisher {
+    constructor(options) {
+        this.options = options;
+        this.baseUrl = TrimTrailingSlashes(options.BaseUrl);
+        this.fetchImpl = options.Fetch ?? ((input, init) => fetch(input, init));
+        this.maxRetries = options.MaxRetries ?? 3;
+        this.timeoutMs = options.TimeoutMs ?? 10_000;
+        this.retryBaseDelayMs = options.RetryBaseDelayMs ?? 200;
+        this.newId = options.NewId ?? (() => crypto.randomUUID());
+        this.sleep = options.Sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    }
+    async Publish(topic, requests) {
+        const identified = requests.map((request) => ({ ...request, MessageID: request.MessageID ?? this.newId() }));
+        const results = [];
+        for (let start = 0; start < identified.length; start += MAX_REST_PUBLISH_BATCH) {
+            results.push(...(await this.publishChunk(topic, identified.slice(start, start + MAX_REST_PUBLISH_BATCH))));
+        }
+        return results;
+    }
+    async publishChunk(topic, chunk) {
+        const url = `${this.baseUrl}/topics/${encodeURIComponent(topic)}/messages`;
+        const body = JSON.stringify({ messages: chunk.map((request) => ToRestPublishRequest(request)) });
+        for (let attempt = 0;; attempt += 1) {
+            const outcome = await this.send(url, body);
+            if (outcome.Kind === 'Response' && !isRetryableStatus(outcome.Status)) {
+                return mapResponse(outcome.Status, outcome.Body, chunk);
+            }
+            if (attempt >= this.maxRetries) {
+                const reason = outcome.Kind === 'Response' ? `HTTP ${outcome.Status}` : outcome.Error;
+                return chunk.map((request) => RejectedPublishResult(request.MessageID, PublishErrorCodes.TransportUnavailable, reason));
+            }
+            await this.sleep(this.retryDelayMs(attempt, outcome));
+        }
+    }
+    async send(url, body) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await this.fetchImpl(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', 'X-API-Key': this.options.ApiKey },
+                body,
+                signal: controller.signal,
+            });
+            const text = await response.text();
+            return { Kind: 'Response', Status: response.status, Body: parseJson(text), RetryAfterSeconds: parseRetryAfter(response.headers.get('Retry-After')) };
+        }
+        catch (error) {
+            const message = controller.signal.aborted ? `Timed out after ${this.timeoutMs} ms` : error instanceof Error ? error.message : String(error);
+            return { Kind: 'NetworkError', Error: message };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    retryDelayMs(attempt, outcome) {
+        if (outcome.Kind === 'Response' && outcome.RetryAfterSeconds !== null) {
+            return outcome.RetryAfterSeconds * 1000;
+        }
+        return this.retryBaseDelayMs * Math.pow(2, attempt);
+    }
+}
+function isRetryableStatus(status) {
+    return status === 429 || status >= 500;
+}
+function mapResponse(status, body, chunk) {
+    if (status === 200 || status === 202) {
+        const parsed = ParseRestPublishResponse(body, chunk.length);
+        if (parsed !== null) {
+            return parsed;
+        }
+        return chunk.map((request) => RejectedPublishResult(request.MessageID, PublishErrorCodes.InvalidResponse, `Unexpected response body for HTTP ${status}`));
+    }
+    const { Code, Message } = readErrorBody(status, body);
+    return chunk.map((request) => RejectedPublishResult(request.MessageID, Code, Message));
+}
+function readErrorBody(status, body) {
+    const fallback = FALLBACK_CODES.get(status) ?? `Http${status}`;
+    if (typeof body !== 'object' || body === null) {
+        return { Code: fallback, Message: `HTTP ${status}` };
+    }
+    const code = Reflect.get(body, 'code');
+    const message = Reflect.get(body, 'message');
+    return {
+        Code: typeof code === 'string' ? code : fallback,
+        Message: typeof message === 'string' ? message : `HTTP ${status}`,
+    };
+}
+function parseJson(text) {
+    if (text.trim() === '') {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Upper bound on a server-requested wait: a hostile or mistaken header must not park a producer. */
+export const MAX_RETRY_AFTER_SECONDS = 60;
+/** RFC 9110 Retry-After: delta-seconds or an HTTP date. Capped at MAX_RETRY_AFTER_SECONDS. */
+function parseRetryAfter(header) {
+    if (header === null || header.trim() === '') {
+        return null;
+    }
+    const seconds = Number(header);
+    if (Number.isFinite(seconds)) {
+        return seconds >= 0 ? Math.min(seconds, MAX_RETRY_AFTER_SECONDS) : null;
+    }
+    const at = Date.parse(header);
+    if (Number.isNaN(at)) {
+        return null;
+    }
+    return Math.min(Math.max(0, (at - Date.now()) / 1000), MAX_RETRY_AFTER_SECONDS);
+}
+//# sourceMappingURL=WorkQueueApiPublisher.js.map

package/dist/api/WorkQueueApiPublisher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkQueueApiPublisher.js","sourceRoot":"","sources":["../../src/api/WorkQueueApiPublisher.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAwBxG,MAAM,cAAc,GAAgC,IAAI,GAAG,CAAiB;IACxE,CAAC,GAAG,EAAE,iBAAiB,CAAC,UAAU,CAAC;IACnC,CAAC,GAAG,EAAE,iBAAiB,CAAC,YAAY,CAAC;IACrC,CAAC,GAAG,EAAE,iBAAiB,CAAC,SAAS,CAAC;IAClC,CAAC,GAAG,EAAE,iBAAiB,CAAC,aAAa,CAAC;IACtC,CAAC,GAAG,EAAE,iBAAiB,CAAC,eAAe,CAAC;CAC3C,CAAC,CAAC;AAEH,2GAA2G;AAE3G,wGAAwG;AACxG,SAAS,mBAAmB,CAAC,GAAW;IACpC,IAAI,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC;IACrB,OAAO,GAAG,GAAG,CAAC,IAAI,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;QACrC,GAAG,IAAI,CAAC,CAAC;IACb,CAAC;IACD,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,OAAO,qBAAqB;IAS9B,YAA6B,OAAqC;QAArC,YAAO,GAAP,OAAO,CAA8B;QAC9D,IAAI,CAAC,OAAO,GAAG,mBAAmB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACpD,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;QACxE,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC;QAC7C,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,GAAG,CAAC;QACxD,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;QAC1D,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IACpG,CAAC;IAEM,KAAK,CAAC,OAAO,CAA4B,KAAa,EAAE,QAAoC;QAC/F,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAA+B,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;QAC1I,MAAM,OAAO,GAAoB,EAAE,CAAC;QACpC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,KAAK,IAAI,sBAAsB,EAAE,CAAC;YAC7E,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/G,CAAC;QACD,OAAO,OAAO,CAAC;IACnB,CAAC;IAEO,KAAK,CAAC,YAAY,CAA4B,KAAa,EAAE,KAAoC;QACrG,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,WAAW,kBAAkB,CAAC,KAAK,CAAC,WAAW,CAAC;QAC3E,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;QACjG,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,IAAI,CAAC,EAAE,CAAC;YACnC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAC3C,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBACpE,OAAO,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAC5D,CAAC;YACD,IAAI,OAAO,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;gBAC7B,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,QAAQ,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;gBACtF,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,qBAAqB,CAAC,OAAO,CAAC,SAAS,EAAE,iBAAiB,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC,CAAC;YAC5H,CAAC;YACD,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QAC1D,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,IAAI,CAAC,GAAW,EAAE,IAAY;QACxC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACnE,IAAI,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE;gBACvC,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE;gBACjF,IAAI;gBACJ,MAAM,EAAE,UAAU,CAAC,MAAM;aAC5B,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,iBAAiB,EAAE,eAAe,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC;QACzJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,mBAAmB,IAAI,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC5I,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QACpD,CAAC;gBAAS,CAAC;YACP,YAAY,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;IACL,CAAC;IAEO,YAAY,CAAC,OAAe,EAAE,OAAoB;QACtD,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU,IAAI,OAAO,CAAC,iBAAiB,KAAK,IAAI,EAAE,CAAC;YACpE,OAAO,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;QAC5C,CAAC;QACD,OAAO,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACxD,CAAC;CACJ;AAED,SAAS,iBAAiB,CAAC,MAAc;IACrC,OAAO,MAAM,KAAK,GAAG,IAAI,MAAM,IAAI,GAAG,CAAC;AAC3C,CAAC;AAED,SAAS,WAAW,CAAC,MAAc,EAAE,IAAa,EAAE,KAA8B;IAC9E,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,wBAAwB,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAC5D,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YAClB,OAAO,MAAM,CAAC;QAClB,CAAC;QACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,qBAAqB,CAAC,OAAO,CAAC,SAAS,EAAE,iBAAiB,CAAC,eAAe,EAAE,qCAAqC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC9J,CAAC;IACD,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACtD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,qBAAqB,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;AAC3F,CAAC;AAED,SAAS,aAAa,CAAC,MAAc,EAAE,IAAa;IAChD,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,OAAO,MAAM,EAAE,CAAC;IAC/D,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC5C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,MAAM,EAAE,EAAE,CAAC;IACzD,CAAC;IACD,MAAM,IAAI,GAAY,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAChD,MAAM,OAAO,GAAY,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACtD,OAAO;QACH,IAAI,EAAE,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ;QAChD,OAAO,EAAE,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,MAAM,EAAE;KACpE,CAAC;AACN,CAAC;AAED,SAAS,SAAS,CAAC,IAAY;IAC3B,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,IAAI,CAAC;QACD,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzC,OAAO,MAAM,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,IAAI,CAAC;IAChB,CAAC;AACL,CAAC;AAED,qGAAqG;AACrG,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAE1C,8FAA8F;AAC9F,SAAS,eAAe,CAAC,MAAqB;IAC1C,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC1C,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAC/B,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,OAAO,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5E,CAAC;IACD,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;QACnB,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,uBAAuB,CAAC,CAAC;AACpF,CAAC"}

package/dist/api/restContract.d.ts

@@ -0,0 +1,50 @@
+import type { WorkJson } from '../envelope.js';
+import type { PublishRequest, PublishResult, PublishStatus } from '../publishing.js';
+export declare const MAX_REST_PUBLISH_BATCH = 100;
+export interface RestPayloadRefJson {
+    uri: string;
+    contentType?: string;
+    sizeBytes?: number;
+    checksum?: string;
+}
+export interface RestPublishRequestJson {
+    messageId?: string;
+    partitionKey?: string;
+    attributes?: Record<string, string>;
+    payload?: WorkJson;
+    payloadRef?: RestPayloadRefJson;
+    correlationId?: string;
+    deduplicationKey?: string;
+    deduplicationTtlSeconds?: number;
+}
+export interface RestPublishBodyJson {
+    messages: RestPublishRequestJson[];
+}
+export interface RestPublishErrorJson {
+    code: string;
+    message: string;
+    retryable: boolean;
+}
+export interface RestPublishResultJson {
+    messageId: string;
+    status: PublishStatus;
+    error?: RestPublishErrorJson;
+}
+export interface RestPublishResponseJson {
+    results: RestPublishResultJson[];
+}
+export type RestPublishBodyParseResult = {
+    Kind: 'Parsed';
+    Requests: PublishRequest[];
+} | {
+    Kind: 'Invalid';
+    Error: string;
+};
+export declare function ToRestPublishRequest(request: PublishRequest): RestPublishRequestJson;
+export declare function FromRestPublishRequest(json: RestPublishRequestJson): PublishRequest;
+export declare function ToRestPublishResult(result: PublishResult): RestPublishResultJson;
+/** Checks the body's shape and maps it to PublishRequests. Envelope rules are ValidatePublishRequest's job. */
+export declare function ParseRestPublishBody(value: unknown): RestPublishBodyParseResult;
+export declare function ParseRestPublishResponse(value: unknown, expectedCount: number): PublishResult[] | null;
+export declare function IsWorkJson(value: unknown): value is WorkJson;
+//# sourceMappingURL=restContract.d.ts.map

package/dist/api/restContract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restContract.d.ts","sourceRoot":"","sources":["../../src/api/restContract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAkB,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EAAgB,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGhG,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,MAAM,WAAW,kBAAkB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uBAAuB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAChC,QAAQ,EAAE,sBAAsB,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,oBAAoB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,CAAC,EAAE,oBAAoB,CAAC;CAChC;AAED,MAAM,WAAW,uBAAuB;IACpC,OAAO,EAAE,qBAAqB,EAAE,CAAC;CACpC;AAED,MAAM,MAAM,0BAA0B,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,cAAc,EAAE,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAU7H,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,sBAAsB,CAWpF;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,sBAAsB,GAAG,cAAc,CAWnF;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,qBAAqB,CAQhF;AAED,+GAA+G;AAC/G,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,0BAA0B,CAiB/E;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,GAAG,aAAa,EAAE,GAAG,IAAI,CAiBtG;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAW5D"}