@nestarc/inbox 0.0.0-stage → 0.2.0

package/dist/contracts/types.d.ts

@@ -0,0 +1,174 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type InboxScope = {
+    kind: "tenant";
+    id: string;
+} | {
+    kind: "global";
+};
+export type InboxStatus = "PENDING" | "PROCESSING" | "RETRYABLE" | "COMPLETED" | "DEAD";
+/** The subset of a Prisma interactive transaction used by the inbox. */
+export interface InboxTransaction {
+    $queryRawUnsafe<T = unknown>(query: string, ...values: any[]): Promise<T>;
+    $executeRawUnsafe(query: string, ...values: any[]): Promise<number>;
+}
+export interface InboxPrismaClient extends InboxTransaction {
+    $transaction<T>(fn: (tx: InboxTransaction) => Promise<T>, options?: {
+        maxWait?: number;
+        timeout?: number;
+        isolationLevel?: "ReadCommitted";
+    }): Promise<T>;
+}
+export interface InboxEnvelope<T extends JsonValue = JsonValue> {
+    scope: InboxScope;
+    source: string;
+    consumer: string;
+    messageId: string;
+    eventType: string;
+    schemaVersion: number;
+    payload: T;
+    correlationId?: string;
+    causationId?: string;
+    headers?: {
+        traceparent?: string;
+        tracestate?: string;
+    };
+}
+export interface InboxRecord {
+    id: string;
+    scope: InboxScope;
+    source: string;
+    consumer: string;
+    messageId: string;
+    eventType: string;
+    schemaVersion: number;
+    payload: JsonValue;
+    payloadPurged: boolean;
+    fingerprint: string;
+    fingerprintVersion: number;
+    status: InboxStatus;
+    claimToken: string;
+    rowVersion: string;
+    attemptCount: number;
+    cycleAttemptCount: number;
+    requeueCount: number;
+    receivedAt: Date;
+    completedAt: Date | null;
+    nextAttemptAt: Date;
+    leaseExpiresAt: Date | null;
+    workerId: string | null;
+    lastErrorCode: string | null;
+    lastErrorMessage: string | null;
+    lastRequeueReason: string | null;
+    lastRequeueActor: string | null;
+    lastRequeueAt: Date | null;
+    correlationId?: string;
+    causationId?: string;
+    headers?: InboxEnvelope["headers"];
+    /** Present only for an explicitly requested replay; the original receipt is retained. */
+    replay?: {
+        originalInboxId: string;
+        requestId: string;
+        sourceVersion: string;
+        actor: string;
+        reason: string;
+        requestedAt: Date;
+    };
+}
+export interface InboxReceipt {
+    kind: "accepted" | "duplicate";
+    id: string;
+    status: InboxStatus;
+}
+export interface InboxContext<TTx extends InboxTransaction = InboxTransaction> {
+    tx: TTx;
+    scope: InboxScope;
+    messageId: string;
+    source: string;
+    consumer: string;
+    inboxId: string;
+    attempt: number;
+    signal: AbortSignal;
+    replay?: InboxRecord["replay"];
+    correlationId?: string;
+    causationId?: string;
+}
+export interface InboxHandler<TPayload = JsonValue, TTx extends InboxTransaction = InboxTransaction> {
+    consumer: string;
+    eventType: string;
+    schemaVersion: number;
+    /** Return false or throw to quarantine invalid payloads. Must be synchronous and side-effect free. */
+    validate?: (payload: JsonValue) => boolean | void;
+    handle(payload: TPayload, context: InboxContext<TTx>): Promise<void>;
+}
+/** Wrap handler execution inside its existing transaction, e.g. with tenant context. */
+export type InboxHandlerContextRunner = (context: InboxContext, next: () => Promise<void>) => Promise<void>;
+export interface InboxListOptions {
+    status?: InboxStatus;
+    consumer?: string;
+    cursor?: string;
+    limit?: number;
+}
+export interface InboxPage {
+    records: InboxRecord[];
+    nextCursor: string | null;
+}
+export interface InboxStats {
+    counts: Record<InboxStatus, number>;
+    oldestPendingAt: Date | null;
+}
+/** No payloads, tenant IDs, or raw exceptions are passed to observation hooks. */
+export interface InboxObservation {
+    type: "accepted" | "duplicate" | "completed" | "retry" | "dead" | "lease_lost" | "error";
+    consumer?: string;
+    code?: string;
+}
+export interface InboxWorkerOptions {
+    enabled?: boolean;
+    consumers?: string[];
+    concurrency?: number;
+    pollIntervalMs?: number;
+    leaseMs?: number;
+    heartbeatIntervalMs?: number;
+    transactionTimeoutMs?: number;
+    transactionMaxWaitMs?: number;
+    lockTimeoutMs?: number;
+    shutdownTimeoutMs?: number;
+    maxAttempts?: number;
+    retryBaseMs?: number;
+    retryMaxMs?: number;
+}
+export interface InboxOptions {
+    prisma: InboxPrismaClient;
+    handlers?: InboxHandler<any, any>[];
+    /** Accepted consumer names; defaults to registered handler names. Required for ingress-only apps. */
+    consumers?: string[];
+    worker?: InboxWorkerOptions;
+    maxPayloadBytes?: number;
+    /** Optional approximate admission limit; concurrently accepted messages may exceed it. */
+    maxPendingMessages?: number;
+    observer?: (event: InboxObservation) => void | Promise<void>;
+    handlerContext?: InboxHandlerContextRunner;
+    privilegedAdmin?: boolean;
+}
+export interface NormalizedEnvelope extends InboxEnvelope {
+    payloadJson: string;
+    fingerprint: string;
+    fingerprintVersion: 1;
+}
+export interface ResolvedWorkerOptions {
+    enabled: boolean;
+    consumers: string[];
+    concurrency: number;
+    pollIntervalMs: number;
+    leaseMs: number;
+    heartbeatIntervalMs: number;
+    transactionTimeoutMs: number;
+    transactionMaxWaitMs: number;
+    lockTimeoutMs: number;
+    shutdownTimeoutMs: number;
+    maxAttempts: number;
+    retryBaseMs: number;
+    retryMaxMs: number;
+}

package/dist/contracts/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/contracts/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/contracts/types.ts"],"names":[],"mappings":""}

package/dist/inbox-admin.service.d.ts

@@ -0,0 +1,44 @@
+import type { InboxListOptions, InboxRecord, InboxScope } from "./contracts/types";
+import { PrismaInboxStorage } from "./storage/prisma/prisma-inbox.storage";
+export interface InboxRequeueOptions {
+    id: string;
+    expectedVersion: string;
+    reason: string;
+    actor: string;
+}
+export interface InboxReplayOptions extends InboxRequeueOptions {
+    /** Stable UUID identifying one operator request within the original record's scope. */
+    requestId: string;
+    /** May name the original consumer or a separately registered projection consumer. */
+    targetConsumer: string;
+}
+export interface InboxReplayResult {
+    kind: "accepted" | "duplicate";
+    record: InboxRecord;
+}
+/** A fixed scope is captured when this view is constructed. It is never read from request payloads. */
+export declare class InboxAdminView {
+    private readonly storage;
+    private readonly scope;
+    constructor(storage: PrismaInboxStorage, scope: InboxScope | undefined);
+    get(recordId: string): Promise<InboxRecord | null>;
+    list(options?: InboxListOptions): Promise<import("./contracts/types").InboxPage>;
+    stats(): Promise<import("./contracts/types").InboxStats>;
+    requeue(options: InboxRequeueOptions): Promise<InboxRecord>;
+    /** An intentional new delivery; the original COMPLETED receipt stays immutable. */
+    replay(options: InboxReplayOptions): Promise<InboxReplayResult>;
+    purgeCompletedPayload(options: {
+        before: Date;
+        limit?: number;
+    }): Promise<number>;
+}
+export declare class InboxAdminService {
+    private readonly storage;
+    constructor(storage: PrismaInboxStorage);
+    forTenant(tenantId: string): InboxAdminView;
+    forGlobal(): InboxAdminView;
+}
+/** Injected only when the module explicitly enables privilegedAdmin. Protect access in your app. */
+export declare class InboxPrivilegedAdminService extends InboxAdminView {
+    constructor(storage: PrismaInboxStorage);
+}

package/dist/inbox-admin.service.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InboxPrivilegedAdminService = exports.InboxAdminService = exports.InboxAdminView = void 0;
+const errors_1 = require("./contracts/errors");
+const validation_1 = require("./internal/validation");
+function id(value) {
+    if (typeof value !== "string" ||
+        !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value))
+        throw new errors_1.InboxValidationError("Invalid inbox ID.");
+    return value;
+}
+function version(value) {
+    if (typeof value !== "string" ||
+        !/^[1-9][0-9]{0,18}$/.test(value) ||
+        BigInt(value) > 9223372036854775807n) {
+        throw new errors_1.InboxValidationError("expectedVersion must be a positive bigint string.");
+    }
+    return value;
+}
+/** A fixed scope is captured when this view is constructed. It is never read from request payloads. */
+class InboxAdminView {
+    storage;
+    scope;
+    constructor(storage, scope) {
+        this.storage = storage;
+        this.scope = scope;
+    }
+    get(recordId) {
+        return this.storage.get(id(recordId), this.scope);
+    }
+    list(options = {}) {
+        if (options.consumer !== undefined)
+            (0, validation_1.boundedString)(options.consumer, "consumer", 128);
+        return this.storage.list(options, this.scope);
+    }
+    stats() {
+        return this.storage.stats(this.scope);
+    }
+    requeue(options) {
+        id(options.id);
+        return this.storage.requeue(options.id, this.scope, version(options.expectedVersion), (0, validation_1.boundedString)(options.reason, "reason", 1024), (0, validation_1.boundedString)(options.actor, "actor", 256));
+    }
+    /** An intentional new delivery; the original COMPLETED receipt stays immutable. */
+    replay(options) {
+        if (!options ||
+            typeof options !== "object" ||
+            Array.isArray(options) ||
+            ![Object.prototype, null].includes(Object.getPrototypeOf(options)))
+            throw new errors_1.InboxValidationError("Replay options must be a plain object.");
+        const fields = [
+            "id",
+            "expectedVersion",
+            "requestId",
+            "targetConsumer",
+            "reason",
+            "actor",
+        ];
+        for (const key of Reflect.ownKeys(options)) {
+            const descriptor = Object.getOwnPropertyDescriptor(options, key);
+            if (typeof key !== "string" ||
+                !fields.includes(key) ||
+                !descriptor.enumerable ||
+                !("value" in descriptor))
+                throw new errors_1.InboxValidationError("Replay options contain an unsupported field.");
+        }
+        return this.storage.replay({
+            id: id(options.id).toLowerCase(),
+            expectedVersion: version(options.expectedVersion),
+            requestId: id(options.requestId).toLowerCase(),
+            targetConsumer: (0, validation_1.boundedString)(options.targetConsumer, "targetConsumer", 128),
+            reason: (0, validation_1.boundedString)(options.reason, "reason", 1024),
+            actor: (0, validation_1.boundedString)(options.actor, "actor", 256),
+        }, this.scope);
+    }
+    purgeCompletedPayload(options) {
+        if (!(options.before instanceof Date))
+            throw new errors_1.InboxValidationError("before must be a Date.");
+        return this.storage.purgeCompletedPayload(options.before, options.limit ?? 100, this.scope);
+    }
+}
+exports.InboxAdminView = InboxAdminView;
+class InboxAdminService {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    forTenant(tenantId) {
+        return new InboxAdminView(this.storage, (0, validation_1.validateScope)({ kind: "tenant", id: tenantId }));
+    }
+    forGlobal() {
+        return new InboxAdminView(this.storage, { kind: "global" });
+    }
+}
+exports.InboxAdminService = InboxAdminService;
+/** Injected only when the module explicitly enables privilegedAdmin. Protect access in your app. */
+class InboxPrivilegedAdminService extends InboxAdminView {
+    constructor(storage) {
+        super(storage, undefined);
+    }
+}
+exports.InboxPrivilegedAdminService = InboxPrivilegedAdminService;
+//# sourceMappingURL=inbox-admin.service.js.map

package/dist/inbox-admin.service.js.map

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

package/dist/inbox.module.d.ts

@@ -0,0 +1,13 @@
+import type { DynamicModule, FactoryProvider, ModuleMetadata } from "@nestjs/common";
+import type { InboxOptions } from "./contracts/types";
+export interface InboxModuleAsyncOptions extends Pick<ModuleMetadata, "imports"> {
+    inject?: FactoryProvider["inject"];
+    useFactory: (...dependencies: any[]) => InboxOptions | Promise<InboxOptions>;
+    /** Explicit module-level opt-in is required to register the cross-tenant admin provider. */
+    privilegedAdmin?: boolean;
+}
+export declare class InboxModule {
+    static forRoot(options: InboxOptions): DynamicModule;
+    static forRootAsync(options: InboxModuleAsyncOptions): DynamicModule;
+    private static configure;
+}

package/dist/inbox.module.js

@@ -0,0 +1,59 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var InboxModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InboxModule = void 0;
+const common_1 = require("@nestjs/common");
+const inbox_admin_service_1 = require("./inbox-admin.service");
+const inbox_service_1 = require("./inbox.service");
+const INBOX_OPTIONS = Symbol("NESTARC_INBOX_OPTIONS");
+let InboxModule = InboxModule_1 = class InboxModule {
+    static forRoot(options) {
+        return this.configure({ provide: INBOX_OPTIONS, useValue: options }, [], options.privilegedAdmin === true);
+    }
+    static forRootAsync(options) {
+        return this.configure({
+            provide: INBOX_OPTIONS,
+            inject: options.inject ?? [],
+            useFactory: async (...dependencies) => ({
+                ...(await options.useFactory(...dependencies)),
+                privilegedAdmin: options.privilegedAdmin === true,
+            }),
+        }, options.imports ?? [], options.privilegedAdmin === true);
+    }
+    static configure(options, imports, privileged) {
+        const providers = [
+            options,
+            {
+                provide: inbox_service_1.InboxService,
+                inject: [INBOX_OPTIONS],
+                useFactory: (value) => new inbox_service_1.InboxService(value),
+            },
+            {
+                provide: inbox_admin_service_1.InboxAdminService,
+                inject: [inbox_service_1.InboxService],
+                useFactory: (inbox) => inbox.admin,
+            },
+        ];
+        const exports = [inbox_service_1.InboxService, inbox_admin_service_1.InboxAdminService];
+        if (privileged) {
+            providers.push({
+                provide: inbox_admin_service_1.InboxPrivilegedAdminService,
+                inject: [inbox_service_1.InboxService],
+                useFactory: (inbox) => inbox.privilegedAdmin,
+            });
+            exports.push(inbox_admin_service_1.InboxPrivilegedAdminService);
+        }
+        return { module: InboxModule_1, imports, providers, exports };
+    }
+};
+exports.InboxModule = InboxModule;
+exports.InboxModule = InboxModule = InboxModule_1 = __decorate([
+    (0, common_1.Module)({})
+], InboxModule);
+//# sourceMappingURL=inbox.module.js.map

package/dist/inbox.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox.module.js","sourceRoot":"","sources":["../src/inbox.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAwC;AAQxC,+DAG+B;AAC/B,mDAA+C;AAE/C,MAAM,aAAa,GAAG,MAAM,CAAC,uBAAuB,CAAC,CAAC;AAW/C,IAAM,WAAW,mBAAjB,MAAM,WAAW;IACtB,MAAM,CAAC,OAAO,CAAC,OAAqB;QAClC,OAAO,IAAI,CAAC,SAAS,CACnB,EAAE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,OAAO,EAAE,EAC7C,EAAE,EACF,OAAO,CAAC,eAAe,KAAK,IAAI,CACjC,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,YAAY,CAAC,OAAgC;QAClD,OAAO,IAAI,CAAC,SAAS,CACnB;YACE,OAAO,EAAE,aAAa;YACtB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE;YAC5B,UAAU,EAAE,KAAK,EAAE,GAAG,YAAmB,EAAE,EAAE,CAAC,CAAC;gBAC7C,GAAG,CAAC,MAAM,OAAO,CAAC,UAAU,CAAC,GAAG,YAAY,CAAC,CAAC;gBAC9C,eAAe,EAAE,OAAO,CAAC,eAAe,KAAK,IAAI;aAClD,CAAC;SACH,EACD,OAAO,CAAC,OAAO,IAAI,EAAE,EACrB,OAAO,CAAC,eAAe,KAAK,IAAI,CACjC,CAAC;IACJ,CAAC;IACO,MAAM,CAAC,SAAS,CACtB,OAAiB,EACjB,OAA+C,EAC/C,UAAmB;QAEnB,MAAM,SAAS,GAAe;YAC5B,OAAO;YACP;gBACE,OAAO,EAAE,4BAAY;gBACrB,MAAM,EAAE,CAAC,aAAa,CAAC;gBACvB,UAAU,EAAE,CAAC,KAAmB,EAAE,EAAE,CAAC,IAAI,4BAAY,CAAC,KAAK,CAAC;aAC7D;YACD;gBACE,OAAO,EAAE,uCAAiB;gBAC1B,MAAM,EAAE,CAAC,4BAAY,CAAC;gBACtB,UAAU,EAAE,CAAC,KAAmB,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK;aACjD;SACF,CAAC;QACF,MAAM,OAAO,GAIT,CAAC,4BAAY,EAAE,uCAAiB,CAAC,CAAC;QACtC,IAAI,UAAU,EAAE,CAAC;YACf,SAAS,CAAC,IAAI,CAAC;gBACb,OAAO,EAAE,iDAA2B;gBACpC,MAAM,EAAE,CAAC,4BAAY,CAAC;gBACtB,UAAU,EAAE,CAAC,KAAmB,EAAE,EAAE,CAAC,KAAK,CAAC,eAAgB;aAC5D,CAAC,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,iDAA2B,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,aAAW,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IAC9D,CAAC;CACF,CAAA;AAvDY,kCAAW;sBAAX,WAAW;IADvB,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,WAAW,CAuDvB"}

package/dist/inbox.service.d.ts

@@ -0,0 +1,22 @@
+import type { OnModuleInit, OnModuleDestroy } from "@nestjs/common";
+import type { InboxEnvelope, InboxOptions } from "./contracts/types";
+import { InboxAdminService, InboxPrivilegedAdminService } from "./inbox-admin.service";
+export declare class InboxService implements OnModuleInit, OnModuleDestroy {
+    private readonly options;
+    private readonly storage;
+    private readonly worker;
+    private readonly consumers;
+    private initialization?;
+    private closed;
+    readonly admin: InboxAdminService;
+    readonly privilegedAdmin?: InboxPrivilegedAdminService;
+    constructor(options: InboxOptions);
+    onModuleInit(): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+    initialize(): Promise<void>;
+    accept(envelope: InboxEnvelope): Promise<import("./contracts/types").InboxReceipt>;
+    /** Explicit bounded processing for managed workers and tests; automatic polling is optional. */
+    runOnce(): Promise<number>;
+    close(): Promise<void>;
+    private observe;
+}

package/dist/inbox.service.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InboxService = void 0;
+const errors_1 = require("./contracts/errors");
+const inbox_admin_service_1 = require("./inbox-admin.service");
+const options_1 = require("./internal/options");
+const validation_1 = require("./internal/validation");
+const prisma_inbox_storage_1 = require("./storage/prisma/prisma-inbox.storage");
+const inbox_worker_1 = require("./worker/inbox-worker");
+class InboxService {
+    options;
+    storage;
+    worker;
+    consumers;
+    initialization;
+    closed = false;
+    admin;
+    privilegedAdmin;
+    constructor(options) {
+        this.options = options;
+        const resolved = (0, options_1.resolveOptions)(options);
+        this.consumers = resolved.consumers;
+        this.storage = new prisma_inbox_storage_1.PrismaInboxStorage(options.prisma, {
+            maxPendingMessages: options.maxPendingMessages,
+        });
+        this.worker = new inbox_worker_1.InboxWorker(this.storage, options.handlers ?? [], resolved.worker, options.observer, options.handlerContext);
+        this.admin = new inbox_admin_service_1.InboxAdminService(this.storage);
+        if (options.privilegedAdmin)
+            this.privilegedAdmin = new inbox_admin_service_1.InboxPrivilegedAdminService(this.storage);
+    }
+    async onModuleInit() {
+        await this.initialize();
+    }
+    async onModuleDestroy() {
+        await this.close();
+    }
+    initialize() {
+        if (this.closed)
+            return Promise.reject(new errors_1.InboxError("CLOSED", "The inbox service is closed."));
+        this.initialization ??= this.storage.assertSchema().then(() => {
+            if (!this.closed)
+                this.worker.start();
+        });
+        return this.initialization;
+    }
+    async accept(envelope) {
+        const normalized = (0, validation_1.normalizeEnvelope)(envelope, this.consumers, this.options.maxPayloadBytes);
+        await this.initialize();
+        if (this.closed)
+            throw new errors_1.InboxError("CLOSED", "The inbox service is closed.");
+        const receipt = await this.storage.accept(normalized);
+        this.observe({ type: receipt.kind, consumer: normalized.consumer });
+        return receipt;
+    }
+    /** Explicit bounded processing for managed workers and tests; automatic polling is optional. */
+    async runOnce() {
+        await this.initialize();
+        return this.worker.tick();
+    }
+    async close() {
+        this.closed = true;
+        await this.worker.stop();
+    }
+    observe(event) {
+        try {
+            void Promise.resolve(this.options.observer?.(event)).catch(() => undefined);
+        }
+        catch {
+            /* Observation cannot change committed data. */
+        }
+    }
+}
+exports.InboxService = InboxService;
+//# sourceMappingURL=inbox.service.js.map

package/dist/inbox.service.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { InboxModule } from "./inbox.module";
+export type { InboxModuleAsyncOptions } from "./inbox.module";
+export { InboxService } from "./inbox.service";
+export { createInboxTenancyContext } from "./integrations/tenancy";
+export type { InboxTenancyOptions } from "./integrations/tenancy";
+export { InboxAdminService, InboxPrivilegedAdminService, } from "./inbox-admin.service";
+export type { InboxAdminView, InboxRequeueOptions, InboxReplayOptions, InboxReplayResult, } from "./inbox-admin.service";
+export * from "./contracts/errors";
+export type { JsonValue, InboxScope, InboxStatus, InboxTransaction, InboxPrismaClient, InboxEnvelope, InboxRecord, InboxReceipt, InboxContext, InboxHandler, InboxListOptions, InboxPage, InboxStats, InboxObservation, InboxWorkerOptions, InboxOptions, InboxHandlerContextRunner, } from "./contracts/types";

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InboxPrivilegedAdminService = exports.InboxAdminService = exports.createInboxTenancyContext = exports.InboxService = exports.InboxModule = void 0;
+var inbox_module_1 = require("./inbox.module");
+Object.defineProperty(exports, "InboxModule", { enumerable: true, get: function () { return inbox_module_1.InboxModule; } });
+var inbox_service_1 = require("./inbox.service");
+Object.defineProperty(exports, "InboxService", { enumerable: true, get: function () { return inbox_service_1.InboxService; } });
+var tenancy_1 = require("./integrations/tenancy");
+Object.defineProperty(exports, "createInboxTenancyContext", { enumerable: true, get: function () { return tenancy_1.createInboxTenancyContext; } });
+var inbox_admin_service_1 = require("./inbox-admin.service");
+Object.defineProperty(exports, "InboxAdminService", { enumerable: true, get: function () { return inbox_admin_service_1.InboxAdminService; } });
+Object.defineProperty(exports, "InboxPrivilegedAdminService", { enumerable: true, get: function () { return inbox_admin_service_1.InboxPrivilegedAdminService; } });
+__exportStar(require("./contracts/errors"), exports);
+//# 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,+CAA6C;AAApC,2GAAA,WAAW,OAAA;AAEpB,iDAA+C;AAAtC,6GAAA,YAAY,OAAA;AACrB,kDAAmE;AAA1D,oHAAA,yBAAyB,OAAA;AAElC,6DAG+B;AAF7B,wHAAA,iBAAiB,OAAA;AACjB,kIAAA,2BAA2B,OAAA;AAQ7B,qDAAmC"}

package/dist/integrations/tenancy.d.ts

@@ -0,0 +1,25 @@
+import type { InboxContext } from "../contracts/types";
+export interface InboxTenancyOptions {
+    /** Public TenancyContext methods; structural so the integration stays optional. */
+    context: {
+        run<T>(tenantId: string, callback: () => Promise<T>): Promise<T>;
+    };
+    /** Public TenancyService methods, supplied by the application's TenancyModule. */
+    tenancy: {
+        getDbSettingKey(): string;
+        getCurrentTenantOrThrow(): string;
+        withoutTenant<T>(callback: () => Promise<T>): Promise<T>;
+    };
+    /** Reject global messages by default. Shared work still obeys database RLS. */
+    global?: "reject" | "shared";
+}
+/**
+ * Bind @nestarc/tenancy context to the durable message scope and set the canonical
+ * PostgreSQL setting on Inbox's existing transaction before running the handler.
+ * Use the application's raw Prisma client for Inbox, not a tenancy extension.
+ *
+ * The application authenticates the scope before accept(), provisions RLS policies
+ * using the same setting key, and runs handlers with a non-owner, non-BYPASSRLS
+ * database role. This adapter neither installs policies nor grants authorization.
+ */
+export declare function createInboxTenancyContext(options: InboxTenancyOptions): (context: InboxContext, next: () => Promise<void>) => Promise<void>;

package/dist/integrations/tenancy.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createInboxTenancyContext = createInboxTenancyContext;
+const errors_1 = require("../contracts/errors");
+const validation_1 = require("../internal/validation");
+/**
+ * Bind @nestarc/tenancy context to the durable message scope and set the canonical
+ * PostgreSQL setting on Inbox's existing transaction before running the handler.
+ * Use the application's raw Prisma client for Inbox, not a tenancy extension.
+ *
+ * The application authenticates the scope before accept(), provisions RLS policies
+ * using the same setting key, and runs handlers with a non-owner, non-BYPASSRLS
+ * database role. This adapter neither installs policies nor grants authorization.
+ */
+function createInboxTenancyContext(options) {
+    if (!options ||
+        typeof options.context?.run !== "function" ||
+        typeof options.tenancy?.getDbSettingKey !== "function" ||
+        typeof options.tenancy?.getCurrentTenantOrThrow !== "function" ||
+        typeof options.tenancy?.withoutTenant !== "function" ||
+        (options.global !== undefined &&
+            options.global !== "reject" &&
+            options.global !== "shared")) {
+        throw new errors_1.InboxConfigurationError("Provide valid tenancy context and service options.");
+    }
+    const settingKey = options.tenancy.getDbSettingKey();
+    // A canonical custom GUC is required; do not accept built-in session settings.
+    if (!/^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)+$/.test(settingKey)) {
+        throw new errors_1.InboxConfigurationError("Tenancy requires a valid PostgreSQL custom setting key.");
+    }
+    const global = options.global ?? "reject";
+    return async (context, next) => {
+        const scope = (0, validation_1.validateScope)(context.scope);
+        if (scope.kind === "global") {
+            if (global !== "shared") {
+                throw new errors_1.InboxPermanentError("This handler context requires a tenant-scoped message.", "TENANT_SCOPE_REQUIRED");
+            }
+            await options.tenancy.withoutTenant(async () => {
+                // An explicit shared path clears any inherited database tenant setting.
+                // Empty context cannot satisfy the tenant RLS policy; this is no bypass.
+                await context.tx.$queryRawUnsafe("SELECT set_config($1, $2, true)", settingKey, "");
+                await next();
+            });
+            return;
+        }
+        await options.context.run(scope.id, async () => {
+            const tenantId = options.tenancy.getCurrentTenantOrThrow();
+            if (tenantId !== scope.id) {
+                throw new errors_1.InboxPermanentError("The active tenant context does not match the durable message scope.", "TENANT_CONTEXT_MISMATCH");
+            }
+            await context.tx.$queryRawUnsafe("SELECT set_config($1, $2, true)", settingKey, tenantId);
+            await next();
+        });
+    };
+}
+//# sourceMappingURL=tenancy.js.map

package/dist/integrations/tenancy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenancy.js","sourceRoot":"","sources":["../../src/integrations/tenancy.ts"],"names":[],"mappings":";;AA+BA,8DAkEC;AAjGD,gDAG6B;AAE7B,uDAAuD;AAiBvD;;;;;;;;GAQG;AACH,SAAgB,yBAAyB,CACvC,OAA4B;IAE5B,IACE,CAAC,OAAO;QACR,OAAO,OAAO,CAAC,OAAO,EAAE,GAAG,KAAK,UAAU;QAC1C,OAAO,OAAO,CAAC,OAAO,EAAE,eAAe,KAAK,UAAU;QACtD,OAAO,OAAO,CAAC,OAAO,EAAE,uBAAuB,KAAK,UAAU;QAC9D,OAAO,OAAO,CAAC,OAAO,EAAE,aAAa,KAAK,UAAU;QACpD,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS;YAC3B,OAAO,CAAC,MAAM,KAAK,QAAQ;YAC3B,OAAO,CAAC,MAAM,KAAK,QAAQ,CAAC,EAC9B,CAAC;QACD,MAAM,IAAI,gCAAuB,CAC/B,oDAAoD,CACrD,CAAC;IACJ,CAAC;IACD,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;IACrD,+EAA+E;IAC/E,IACE,CAAC,uDAAuD,CAAC,IAAI,CAAC,UAAU,CAAC,EACzE,CAAC;QACD,MAAM,IAAI,gCAAuB,CAC/B,yDAAyD,CAC1D,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,QAAQ,CAAC;IAE1C,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;QAC7B,MAAM,KAAK,GAAG,IAAA,0BAAa,EAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC3C,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC5B,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;gBACxB,MAAM,IAAI,4BAAmB,CAC3B,wDAAwD,EACxD,uBAAuB,CACxB,CAAC;YACJ,CAAC;YACD,MAAM,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,KAAK,IAAI,EAAE;gBAC7C,wEAAwE;gBACxE,yEAAyE;gBACzE,MAAM,OAAO,CAAC,EAAE,CAAC,eAAe,CAC9B,iCAAiC,EACjC,UAAU,EACV,EAAE,CACH,CAAC;gBACF,MAAM,IAAI,EAAE,CAAC;YACf,CAAC,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,IAAI,EAAE;YAC7C,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,uBAAuB,EAAE,CAAC;YAC3D,IAAI,QAAQ,KAAK,KAAK,CAAC,EAAE,EAAE,CAAC;gBAC1B,MAAM,IAAI,4BAAmB,CAC3B,qEAAqE,EACrE,yBAAyB,CAC1B,CAAC;YACJ,CAAC;YACD,MAAM,OAAO,CAAC,EAAE,CAAC,eAAe,CAC9B,iCAAiC,EACjC,UAAU,EACV,QAAQ,CACT,CAAC;YACF,MAAM,IAAI,EAAE,CAAC;QACf,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}