@shiprev/server-sdk-node 0.0.0-stage → 0.1.0-beta.0

package/dist/metering/usage-buffer.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsageBuffer = void 0;
+const host_adapter_backlog_1 = require("./backlog/host-adapter-backlog");
+const journal_backlog_1 = require("./backlog/journal-backlog");
+const memory_backlog_1 = require("./backlog/memory-backlog");
+class UsageBuffer {
+    transport;
+    getToken;
+    isOnline;
+    send;
+    batchSize;
+    flushIntervalMs;
+    backlog;
+    onFlushFailure;
+    onRejected;
+    buffer = [];
+    timer = null;
+    /** The pass in flight, if any; at most one runs at a time. */
+    inFlight = null;
+    isStopped = false;
+    constructor(options) {
+        this.transport = options.transport;
+        this.getToken = options.getToken;
+        this.isOnline = options.isOnline;
+        this.send = options.send;
+        this.batchSize = options.bufferConfig?.batch_size ?? 100;
+        this.flushIntervalMs = options.bufferConfig?.flush_interval_ms ?? 5000;
+        this.onFlushFailure = options.onFlushFailure;
+        this.onRejected = options.onRejected;
+        // Initialize backlog adapter based on mode
+        const mode = options.backlogConfig?.mode ?? 'memory';
+        if (mode === 'journal') {
+            this.backlog = new journal_backlog_1.JournalBacklog(options.backlogConfig?.journal_path);
+        }
+        else if (mode === 'host_adapter') {
+            this.backlog = new host_adapter_backlog_1.HostAdapterBacklog(options.backlogConfig?.adapter);
+        }
+        else {
+            this.backlog = new memory_backlog_1.MemoryBacklog();
+        }
+        this.startTimer();
+    }
+    /**
+     * Appends an event to the buffer. If buffer reaches batchSize, triggers flush.
+     */
+    async reportUsage(event) {
+        if (this.isStopped) {
+            throw new Error('UsageBuffer is stopped, cannot report new events');
+        }
+        this.buffer.push(event);
+        if (this.buffer.length >= this.batchSize) {
+            await this.flush();
+        }
+    }
+    /**
+     * Delivers every usage event reported before this call: the backlog first, in batches, then the
+     * in-memory buffer. A flush already in flight is awaited first, then this call runs its own pass.
+     * Resolves once each of those events was accepted, refused (`onRejected`), or moved to the
+     * backlog because it could not be delivered (offline, no token, or a failed request).
+     */
+    async flush() {
+        while (this.inFlight) {
+            await this.inFlight.catch(() => undefined);
+        }
+        await this.runPass(true);
+    }
+    runPass(drainBacklog) {
+        const pass = this.pass(drainBacklog).finally(() => {
+            if (this.inFlight === pass)
+                this.inFlight = null;
+        });
+        this.inFlight = pass;
+        return pass;
+    }
+    /**
+     * One pass. With `drainBacklog` the backlog is sent in batches until it is empty or a batch
+     * fails; without it (timer ticks) at most one backlog batch is sent.
+     */
+    async pass(drainBacklog) {
+        const token = this.getToken();
+        const online = this.isOnline();
+        // If offline or no token available, route memory events to backlog directly
+        if (!online || !token) {
+            if (this.buffer.length > 0) {
+                const eventsToBacklog = [...this.buffer];
+                this.buffer = [];
+                for (const ev of eventsToBacklog) {
+                    await this.backlog.enqueue(ev);
+                }
+            }
+            return;
+        }
+        // 1. Drain pending backlog first; bounded by its size now, so later arrivals cannot extend it
+        const batches = drainBacklog ? Math.ceil((await this.backlog.size()) / this.batchSize) : 1;
+        for (let i = 0; i < batches; i++) {
+            if ((await this.flushBacklog(token)) !== 'delivered')
+                break;
+        }
+        // 2. Drain current memory buffer
+        if (this.buffer.length > 0) {
+            const eventsToSend = [...this.buffer];
+            this.buffer = [];
+            try {
+                const res = await this.deliver(eventsToSend, token);
+                if (res.rejected && res.rejected.length > 0) {
+                    this.onRejected?.(res.rejected);
+                }
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                this.onFlushFailure?.(eventsToSend, error);
+                // Persist to backlog on failure
+                for (const ev of eventsToSend) {
+                    await this.backlog.enqueue(ev);
+                }
+            }
+        }
+    }
+    async flushBacklog(token) {
+        const backlogItems = await this.backlog.peek(this.batchSize);
+        if (backlogItems.length === 0)
+            return 'empty';
+        const events = backlogItems.map((item) => item.event);
+        const ids = backlogItems.map((item) => item.id);
+        try {
+            const res = await this.deliver(events, token);
+            await this.backlog.ack(ids);
+            if (res.rejected && res.rejected.length > 0) {
+                this.onRejected?.(res.rejected);
+            }
+            return 'delivered';
+        }
+        catch {
+            await this.backlog.nack(ids);
+            return 'failed';
+        }
+    }
+    deliver(events, token) {
+        return this.send ? this.send(events) : this.transport.reportUsageEvents(events, token);
+    }
+    startTimer() {
+        if (this.flushIntervalMs <= 0)
+            return;
+        this.timer = setInterval(() => {
+            // A tick skips while a pass is in flight, and sends at most one backlog batch.
+            if (this.inFlight)
+                return;
+            void this.runPass(false);
+        }, this.flushIntervalMs);
+        // Don't keep Node process alive solely for background flush interval
+        if (this.timer.unref) {
+            this.timer.unref();
+        }
+    }
+    /**
+     * Gracefully stops the buffer flusher and performs final drain.
+     */
+    async stop() {
+        this.isStopped = true;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await this.flush();
+    }
+    getBufferSize() {
+        return this.buffer.length;
+    }
+    async getBacklogSize() {
+        return this.backlog.size();
+    }
+}
+exports.UsageBuffer = UsageBuffer;
+//# sourceMappingURL=usage-buffer.js.map

package/dist/mirror/entitlement-mirror.d.ts

@@ -0,0 +1,47 @@
+import { Snapshot, SnapshotItem } from '../types';
+export declare const MAX_SUPPORTED_SCHEMA_VERSION = 1;
+/**
+ * In-memory replica of the application-level entitlement snapshot served by
+ * `GET /sdk/v1/entitlements/snapshot`, indexed by organization and capability.
+ */
+export declare class EntitlementMirror {
+    private readonly organizations;
+    private currentSchemaVersion;
+    private projectId;
+    private lastUpdatedAt;
+    /**
+     * Replaces the mirror with an application-level snapshot envelope.
+     * If schema_version is higher than supported, the update is rejected and the existing mirror is retained.
+     */
+    loadSnapshot(snapshot: Snapshot): boolean;
+    /**
+     * Merges the organizations of a (typically single-organization) snapshot envelope into the mirror,
+     * leaving every other organization untouched. Used to refill a mirror miss.
+     */
+    mergeSnapshot(snapshot: Snapshot): boolean;
+    /**
+     * Removes an organization, for a refill whose envelope no longer holds it (unsubscribed or deleted).
+     */
+    removeOrganization(organizationId: string): void;
+    /**
+     * Revision of one organization, or `undefined` when the mirror does not hold it.
+     */
+    getOrganizationRevision(organizationId: string): number | undefined;
+    /**
+     * Looks up the snapshot item of a capability for an organization.
+     */
+    getItem(organizationId: string, capabilityKey: string): SnapshotItem | undefined;
+    /**
+     * Checks whether the organization exists in the mirror.
+     */
+    hasOrganization(organizationId: string): boolean;
+    /**
+     * Highest organization revision in the mirror (0 when empty).
+     */
+    getRevision(): number;
+    getSchemaVersion(): number;
+    getProjectId(): string;
+    getLastUpdatedAt(): number;
+    isEmpty(): boolean;
+    private acceptsEnvelope;
+}

package/dist/mirror/entitlement-mirror.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntitlementMirror = exports.MAX_SUPPORTED_SCHEMA_VERSION = void 0;
+exports.MAX_SUPPORTED_SCHEMA_VERSION = 1;
+/**
+ * In-memory replica of the application-level entitlement snapshot served by
+ * `GET /sdk/v1/entitlements/snapshot`, indexed by organization and capability.
+ */
+class EntitlementMirror {
+    organizations = new Map();
+    currentSchemaVersion = exports.MAX_SUPPORTED_SCHEMA_VERSION;
+    projectId = '';
+    lastUpdatedAt = 0;
+    /**
+     * Replaces the mirror with an application-level snapshot envelope.
+     * If schema_version is higher than supported, the update is rejected and the existing mirror is retained.
+     */
+    loadSnapshot(snapshot) {
+        if (!this.acceptsEnvelope(snapshot)) {
+            return false;
+        }
+        this.organizations.clear();
+        this.projectId = snapshot.project_id;
+        this.currentSchemaVersion = snapshot.schema_version;
+        for (const [organizationId, organization] of Object.entries(snapshot.organizations ?? {})) {
+            this.organizations.set(organizationId, organization);
+        }
+        this.lastUpdatedAt = Date.now();
+        return true;
+    }
+    /**
+     * Merges the organizations of a (typically single-organization) snapshot envelope into the mirror,
+     * leaving every other organization untouched. Used to refill a mirror miss.
+     */
+    mergeSnapshot(snapshot) {
+        if (!this.acceptsEnvelope(snapshot)) {
+            return false;
+        }
+        if (this.projectId && snapshot.project_id !== this.projectId) {
+            return false;
+        }
+        this.projectId = snapshot.project_id;
+        for (const [organizationId, organization] of Object.entries(snapshot.organizations ?? {})) {
+            const known = this.organizations.get(organizationId);
+            if (!known || organization.revision >= known.revision) {
+                this.organizations.set(organizationId, organization);
+            }
+        }
+        this.lastUpdatedAt = Date.now();
+        return true;
+    }
+    /**
+     * Removes an organization, for a refill whose envelope no longer holds it (unsubscribed or deleted).
+     */
+    removeOrganization(organizationId) {
+        if (this.organizations.delete(organizationId)) {
+            this.lastUpdatedAt = Date.now();
+        }
+    }
+    /**
+     * Revision of one organization, or `undefined` when the mirror does not hold it.
+     */
+    getOrganizationRevision(organizationId) {
+        return this.organizations.get(organizationId)?.revision;
+    }
+    /**
+     * Looks up the snapshot item of a capability for an organization.
+     */
+    getItem(organizationId, capabilityKey) {
+        return this.organizations.get(organizationId)?.items?.[capabilityKey];
+    }
+    /**
+     * Checks whether the organization exists in the mirror.
+     */
+    hasOrganization(organizationId) {
+        return this.organizations.has(organizationId);
+    }
+    /**
+     * Highest organization revision in the mirror (0 when empty).
+     */
+    getRevision() {
+        let highest = 0;
+        for (const organization of this.organizations.values()) {
+            highest = Math.max(highest, organization.revision);
+        }
+        return highest;
+    }
+    getSchemaVersion() {
+        return this.currentSchemaVersion;
+    }
+    getProjectId() {
+        return this.projectId;
+    }
+    getLastUpdatedAt() {
+        return this.lastUpdatedAt;
+    }
+    isEmpty() {
+        return this.organizations.size === 0;
+    }
+    acceptsEnvelope(snapshot) {
+        if (!snapshot || typeof snapshot.schema_version !== 'number') {
+            throw new Error('Invalid snapshot structure: missing schema_version');
+        }
+        // A newer schema is refused to protect the host process; the existing mirror is kept.
+        return snapshot.schema_version <= exports.MAX_SUPPORTED_SCHEMA_VERSION;
+    }
+}
+exports.EntitlementMirror = EntitlementMirror;
+//# sourceMappingURL=entitlement-mirror.js.map

package/dist/nest/decorators.d.ts

@@ -0,0 +1,15 @@
+export declare const SHIPREV_CLIENT = "SHIPREV_CLIENT";
+export declare const SHIPREV_CAPABILITY_METADATA = "SHIPREV_CAPABILITY_METADATA";
+export interface CapabilityRequirement {
+    capabilityKey: string;
+    operation: 'read' | 'write';
+    quantity?: number;
+}
+/**
+ * Injects the ShipRevClient instance in NestJS services / controllers
+ */
+export declare const InjectShipRevClient: () => PropertyDecorator & ParameterDecorator;
+/**
+ * Declares capability requirement for a controller route handler.
+ */
+export declare const RequireCapability: (capabilityKey: string, operation?: "read" | "write", quantity?: number) => import("@nestjs/common").CustomDecorator<string>;

package/dist/nest/decorators.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequireCapability = exports.InjectShipRevClient = exports.SHIPREV_CAPABILITY_METADATA = exports.SHIPREV_CLIENT = void 0;
+const common_1 = require("@nestjs/common");
+exports.SHIPREV_CLIENT = 'SHIPREV_CLIENT';
+exports.SHIPREV_CAPABILITY_METADATA = 'SHIPREV_CAPABILITY_METADATA';
+/**
+ * Injects the ShipRevClient instance in NestJS services / controllers
+ */
+const InjectShipRevClient = () => (0, common_1.Inject)(exports.SHIPREV_CLIENT);
+exports.InjectShipRevClient = InjectShipRevClient;
+/**
+ * Declares capability requirement for a controller route handler.
+ */
+const RequireCapability = (capabilityKey, operation = 'read', quantity = 1) => (0, common_1.SetMetadata)(exports.SHIPREV_CAPABILITY_METADATA, {
+    capabilityKey,
+    operation,
+    quantity,
+});
+exports.RequireCapability = RequireCapability;
+//# sourceMappingURL=decorators.js.map

package/dist/nest/index.d.ts

@@ -0,0 +1,4 @@
+export * from './decorators';
+export * from './shiprev.module';
+export * from './shiprev-auth.guard';
+export * from './shiprev-capability.guard';

package/dist/nest/index.js

@@ -0,0 +1,21 @@
+"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 });
+__exportStar(require("./decorators"), exports);
+__exportStar(require("./shiprev.module"), exports);
+__exportStar(require("./shiprev-auth.guard"), exports);
+__exportStar(require("./shiprev-capability.guard"), exports);
+//# sourceMappingURL=index.js.map

package/dist/nest/shiprev-auth.guard.d.ts

@@ -0,0 +1,7 @@
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+import { ShipRevClient } from '../client/shiprev-client';
+export declare class ShipRevAuthGuard implements CanActivate {
+    private readonly client;
+    constructor(client: ShipRevClient);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}

package/dist/nest/shiprev-auth.guard.js

@@ -0,0 +1,52 @@
+"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 __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShipRevAuthGuard = void 0;
+const common_1 = require("@nestjs/common");
+const shiprev_client_1 = require("../client/shiprev-client");
+const decorators_1 = require("./decorators");
+let ShipRevAuthGuard = class ShipRevAuthGuard {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async canActivate(context) {
+        const request = context.switchToHttp().getRequest();
+        const authHeader = request.headers?.authorization;
+        if (!authHeader || typeof authHeader !== 'string') {
+            throw new common_1.UnauthorizedException('Missing Authorization header');
+        }
+        const [scheme, token] = authHeader.split(' ');
+        if (scheme?.toLowerCase() !== 'bearer' || !token) {
+            throw new common_1.UnauthorizedException('Invalid Bearer token format');
+        }
+        try {
+            const claims = await this.client.verifyToken(token);
+            request.authClaims = claims;
+            request.user = claims;
+            return true;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Invalid or expired token';
+            throw new common_1.UnauthorizedException(`Token verification failed: ${message}`);
+        }
+    }
+};
+exports.ShipRevAuthGuard = ShipRevAuthGuard;
+exports.ShipRevAuthGuard = ShipRevAuthGuard = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(decorators_1.SHIPREV_CLIENT)),
+    __metadata("design:paramtypes", [shiprev_client_1.ShipRevClient])
+], ShipRevAuthGuard);
+//# sourceMappingURL=shiprev-auth.guard.js.map

package/dist/nest/shiprev-capability.guard.d.ts

@@ -0,0 +1,9 @@
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { ShipRevClient } from '../client/shiprev-client';
+export declare class ShipRevCapabilityGuard implements CanActivate {
+    private readonly reflector;
+    private readonly client;
+    constructor(reflector: Reflector, client: ShipRevClient);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}

package/dist/nest/shiprev-capability.guard.js

@@ -0,0 +1,65 @@
+"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 __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShipRevCapabilityGuard = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const shiprev_client_1 = require("../client/shiprev-client");
+const decorators_1 = require("./decorators");
+let ShipRevCapabilityGuard = class ShipRevCapabilityGuard {
+    reflector;
+    client;
+    constructor(reflector, client) {
+        this.reflector = reflector;
+        this.client = client;
+    }
+    async canActivate(context) {
+        const requirement = this.reflector.getAllAndOverride(decorators_1.SHIPREV_CAPABILITY_METADATA, [context.getHandler(), context.getClass()]);
+        // If route doesn't require capability check, allow
+        if (!requirement) {
+            return true;
+        }
+        const request = context.switchToHttp().getRequest();
+        // The organization comes only from the verified token. Headers, route parameters and the body
+        // are under the caller's control, so falling back to them would let a signed-in user rule and
+        // meter against another organization. No organization in the token is a refusal.
+        const claims = request.authClaims || request.user;
+        const organizationId = claims?.organization_id;
+        if (typeof organizationId !== 'string' || organizationId === '') {
+            throw new common_1.ForbiddenException(`Capability ${requirement.capabilityKey} not allowed: missing_organization`);
+        }
+        const ruling = await this.client.adjudicateAsync({
+            organization_id: organizationId,
+            capability_key: requirement.capabilityKey,
+            operation: requirement.operation,
+            quantity: requirement.quantity ?? 1,
+        });
+        if (!ruling.allowed) {
+            if (ruling.reason === 'disconnected_write') {
+                throw new common_1.ForbiddenException('Write operation denied while client is disconnected');
+            }
+            throw new common_1.ForbiddenException(`Capability ${requirement.capabilityKey} not allowed: ${ruling.reason ?? 'denied'}`);
+        }
+        request.ruling = ruling;
+        return true;
+    }
+};
+exports.ShipRevCapabilityGuard = ShipRevCapabilityGuard;
+exports.ShipRevCapabilityGuard = ShipRevCapabilityGuard = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)(decorators_1.SHIPREV_CLIENT)),
+    __metadata("design:paramtypes", [core_1.Reflector,
+        shiprev_client_1.ShipRevClient])
+], ShipRevCapabilityGuard);
+//# sourceMappingURL=shiprev-capability.guard.js.map

package/dist/nest/shiprev.module.d.ts

@@ -0,0 +1,17 @@
+import { DynamicModule, FactoryProvider, ModuleMetadata } from '@nestjs/common';
+import { ShipRevClientOptions } from '../types';
+export interface ShipRevModuleAsyncOptions {
+    /** Modules that export what `useFactory` injects, for example the host's `ConfigModule`. */
+    imports?: ModuleMetadata['imports'];
+    /** Providers passed to `useFactory`, in order. */
+    inject?: FactoryProvider['inject'];
+    /**
+     * Builds the client options from the injected providers. Declared as a method so that a factory
+     * typed with the injected classes, `(config: ConfigService) => …`, is assignable as written.
+     */
+    useFactory(...args: unknown[]): Promise<ShipRevClientOptions> | ShipRevClientOptions;
+}
+export declare class ShipRevModule {
+    static forRoot(options: ShipRevClientOptions): DynamicModule;
+    static forRootAsync(asyncOptions: ShipRevModuleAsyncOptions): DynamicModule;
+}

package/dist/nest/shiprev.module.js

@@ -0,0 +1,57 @@
+"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 ShipRevModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShipRevModule = void 0;
+const common_1 = require("@nestjs/common");
+const shiprev_client_1 = require("../client/shiprev-client");
+const decorators_1 = require("./decorators");
+const shiprev_auth_guard_1 = require("./shiprev-auth.guard");
+const shiprev_capability_guard_1 = require("./shiprev-capability.guard");
+let ShipRevModule = ShipRevModule_1 = class ShipRevModule {
+    static forRoot(options) {
+        const clientProvider = {
+            provide: decorators_1.SHIPREV_CLIENT,
+            useFactory: () => {
+                const client = new shiprev_client_1.ShipRevClient(options);
+                // Start client in background (non-blocking for host boot)
+                void client.start();
+                return client;
+            },
+        };
+        return {
+            module: ShipRevModule_1,
+            providers: [clientProvider, shiprev_auth_guard_1.ShipRevAuthGuard, shiprev_capability_guard_1.ShipRevCapabilityGuard],
+            exports: [clientProvider, shiprev_auth_guard_1.ShipRevAuthGuard, shiprev_capability_guard_1.ShipRevCapabilityGuard],
+        };
+    }
+    static forRootAsync(asyncOptions) {
+        const clientProvider = {
+            provide: decorators_1.SHIPREV_CLIENT,
+            useFactory: async (...args) => {
+                const options = await asyncOptions.useFactory(...args);
+                const client = new shiprev_client_1.ShipRevClient(options);
+                void client.start();
+                return client;
+            },
+            inject: asyncOptions.inject ?? [],
+        };
+        return {
+            module: ShipRevModule_1,
+            imports: asyncOptions.imports ?? [],
+            providers: [clientProvider, shiprev_auth_guard_1.ShipRevAuthGuard, shiprev_capability_guard_1.ShipRevCapabilityGuard],
+            exports: [clientProvider, shiprev_auth_guard_1.ShipRevAuthGuard, shiprev_capability_guard_1.ShipRevCapabilityGuard],
+        };
+    }
+};
+exports.ShipRevModule = ShipRevModule;
+exports.ShipRevModule = ShipRevModule = ShipRevModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], ShipRevModule);
+//# sourceMappingURL=shiprev.module.js.map

package/dist/ruling/adjudicator.d.ts

@@ -0,0 +1,15 @@
+import { EntitlementMirror } from '../mirror/entitlement-mirror';
+import { AdjudicateOptions, ClientPresets, Ruling } from '../types';
+export declare class Adjudicator {
+    private readonly mirror;
+    private readonly presets?;
+    constructor(mirror: EntitlementMirror, presets?: ClientPresets | undefined);
+    /**
+     * Synthesizes a four-tier ruling based on local mirror and connection state.
+     *
+     * @param options Adjudication parameters including explicit operation ('read' | 'write')
+     * @param isOnline Whether the connection to the control plane is currently healthy
+     * @param authoritativeLookup Optional callback to synchronously fetch from remote if missing in mirror
+     */
+    adjudicate(options: AdjudicateOptions, isOnline: boolean, authoritativeLookup?: () => Ruling | undefined): Ruling;
+}