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

package/dist/metering/backlog/journal-backlog.js

@@ -0,0 +1,135 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JournalBacklog = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+class JournalBacklog {
+    filePath;
+    queue = [];
+    isCompacting = false;
+    constructor(filePath) {
+        this.filePath = filePath || path.resolve(process.cwd(), '.shiprev-usage-journal.log');
+        this.recoverSync();
+    }
+    recoverSync() {
+        try {
+            if (!fs.existsSync(this.filePath)) {
+                return;
+            }
+            const content = fs.readFileSync(this.filePath, 'utf-8');
+            const lines = content.split('\n').filter((l) => l.trim().length > 0);
+            for (const line of lines) {
+                try {
+                    const parsed = JSON.parse(line);
+                    if (parsed.event && parsed.id) {
+                        this.queue.push({
+                            id: parsed.id,
+                            event: parsed.event,
+                            enqueued_at: parsed.enqueued_at ?? Date.now(),
+                            attempts: parsed.attempts ?? 0,
+                        });
+                    }
+                }
+                catch {
+                    // Ignore corrupt line to protect rest of journal
+                }
+            }
+        }
+        catch {
+            // Ignore recovery read error
+        }
+    }
+    async enqueue(event) {
+        const item = {
+            id: event.usage_event_id,
+            event,
+            enqueued_at: Date.now(),
+            attempts: 0,
+        };
+        this.queue.push(item);
+        // Atomically append line to journal file
+        try {
+            const line = JSON.stringify(item) + '\n';
+            await fs.promises.appendFile(this.filePath, line, 'utf-8');
+        }
+        catch {
+            // In-memory queue remains even if disk append encounters temporary issue
+        }
+    }
+    async peek(limit) {
+        return this.queue.slice(0, limit);
+    }
+    async ack(ids) {
+        const idSet = new Set(ids);
+        this.queue = this.queue.filter((item) => !idSet.has(item.id));
+        await this.compact();
+    }
+    async nack(ids) {
+        const idSet = new Set(ids);
+        for (const item of this.queue) {
+            if (idSet.has(item.id)) {
+                item.attempts += 1;
+            }
+        }
+    }
+    async size() {
+        return this.queue.length;
+    }
+    async compact() {
+        if (this.isCompacting)
+            return;
+        this.isCompacting = true;
+        try {
+            if (this.queue.length === 0) {
+                if (fs.existsSync(this.filePath)) {
+                    await fs.promises.writeFile(this.filePath, '', 'utf-8');
+                }
+            }
+            else {
+                const lines = this.queue.map((item) => JSON.stringify(item)).join('\n') + '\n';
+                await fs.promises.writeFile(this.filePath, lines, 'utf-8');
+            }
+        }
+        catch {
+            // Best-effort compaction
+        }
+        finally {
+            this.isCompacting = false;
+        }
+    }
+}
+exports.JournalBacklog = JournalBacklog;
+//# sourceMappingURL=journal-backlog.js.map

package/dist/metering/backlog/memory-backlog.d.ts

@@ -0,0 +1,9 @@
+import { BacklogAdapter, BacklogItem, UsageEventItem } from '../../types';
+export declare class MemoryBacklog implements BacklogAdapter {
+    private queue;
+    enqueue(event: UsageEventItem): Promise<void>;
+    peek(limit: number): Promise<BacklogItem[]>;
+    ack(ids: string[]): Promise<void>;
+    nack(ids: string[]): Promise<void>;
+    size(): Promise<number>;
+}

package/dist/metering/backlog/memory-backlog.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryBacklog = void 0;
+class MemoryBacklog {
+    queue = [];
+    async enqueue(event) {
+        this.queue.push({
+            id: event.usage_event_id,
+            event,
+            enqueued_at: Date.now(),
+            attempts: 0,
+        });
+    }
+    async peek(limit) {
+        return this.queue.slice(0, limit);
+    }
+    async ack(ids) {
+        const idSet = new Set(ids);
+        this.queue = this.queue.filter((item) => !idSet.has(item.id));
+    }
+    async nack(ids) {
+        const idSet = new Set(ids);
+        for (const item of this.queue) {
+            if (idSet.has(item.id)) {
+                item.attempts += 1;
+            }
+        }
+    }
+    async size() {
+        return this.queue.length;
+    }
+}
+exports.MemoryBacklog = MemoryBacklog;
+//# sourceMappingURL=memory-backlog.js.map

package/dist/metering/usage-buffer.d.ts

@@ -0,0 +1,59 @@
+import { HttpTransport } from '../transport/http.transport';
+import { BacklogConfig, RejectedEvent, UsageBufferConfig, UsageEventItem, UsageEventsResponse } from '../types';
+export interface UsageBufferOptions {
+    transport: HttpTransport;
+    getToken: () => string | null;
+    isOnline: () => boolean;
+    /**
+     * Delivers a batch; defaults to `transport.reportUsageEvents(events, getToken())`. The client
+     * passes a sender that renews the token once on a 401.
+     */
+    send?: (events: UsageEventItem[]) => Promise<UsageEventsResponse>;
+    bufferConfig?: UsageBufferConfig;
+    backlogConfig?: BacklogConfig;
+    onFlushFailure?: (events: UsageEventItem[], error: Error) => void;
+    onRejected?: (rejected: RejectedEvent[]) => void;
+}
+export declare class UsageBuffer {
+    private readonly transport;
+    private readonly getToken;
+    private readonly isOnline;
+    private readonly send?;
+    private readonly batchSize;
+    private readonly flushIntervalMs;
+    private readonly backlog;
+    private readonly onFlushFailure?;
+    private readonly onRejected?;
+    private buffer;
+    private timer;
+    /** The pass in flight, if any; at most one runs at a time. */
+    private inFlight;
+    private isStopped;
+    constructor(options: UsageBufferOptions);
+    /**
+     * Appends an event to the buffer. If buffer reaches batchSize, triggers flush.
+     */
+    reportUsage(event: UsageEventItem): Promise<void>;
+    /**
+     * 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).
+     */
+    flush(): Promise<void>;
+    private runPass;
+    /**
+     * 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.
+     */
+    private pass;
+    private flushBacklog;
+    private deliver;
+    private startTimer;
+    /**
+     * Gracefully stops the buffer flusher and performs final drain.
+     */
+    stop(): Promise<void>;
+    getBufferSize(): number;
+    getBacklogSize(): Promise<number>;
+}

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/degradation.d.ts

@@ -0,0 +1,22 @@
+import { DegradationLevel, EffectiveLevel, OrganizationSnapshot } from '../types';
+/** The five levels in their strict order; each blocks what the one before it blocks, and more. */
+export declare const DEGRADATION_LEVELS: readonly DegradationLevel[];
+/** What a replica past its `valid_until` is tightened to, at least. */
+export declare const EXPIRED_FLOOR: DegradationLevel;
+/**
+ * The level an organization entry carries. Anything that is not one of the five values (missing, another
+ * string, not a string) is read as RESTRICT_USAGE: a level this client does not know is never read as looser.
+ */
+export declare function levelOf(entry: OrganizationSnapshot): DegradationLevel;
+/** `valid_until` in epoch milliseconds, or undefined when missing or unparsable (read as already expired). */
+export declare function validUntilOf(entry: OrganizationSnapshot): number | undefined;
+/**
+ * Combines an entry with what the client observes:
+ *
+ * - answered (online, or a pull of this organization just succeeded): the entry's level;
+ * - not answered and `now < valid_until`: the entry's level, marked degraded;
+ * - not answered and `now >= valid_until` (or no usable `valid_until`): at least RESTRICT_USAGE, marked expired.
+ */
+export declare function combineLevel(entry: OrganizationSnapshot, answered: boolean, now: number): EffectiveLevel;
+/** True when two effective levels are the same triple. */
+export declare function sameLevel(a: EffectiveLevel | undefined, b: EffectiveLevel | undefined): boolean;

package/dist/mirror/degradation.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXPIRED_FLOOR = exports.DEGRADATION_LEVELS = void 0;
+exports.levelOf = levelOf;
+exports.validUntilOf = validUntilOf;
+exports.combineLevel = combineLevel;
+exports.sameLevel = sameLevel;
+/** The five levels in their strict order; each blocks what the one before it blocks, and more. */
+exports.DEGRADATION_LEVELS = [
+    'NONE',
+    'RESTRICT_NEW',
+    'RESTRICT_USAGE',
+    'RESTRICT_READ',
+    'SUSPENDED',
+];
+/** What a replica past its `valid_until` is tightened to, at least. */
+exports.EXPIRED_FLOOR = 'RESTRICT_USAGE';
+function rank(level) {
+    return exports.DEGRADATION_LEVELS.indexOf(level);
+}
+/**
+ * The level an organization entry carries. Anything that is not one of the five values (missing, another
+ * string, not a string) is read as RESTRICT_USAGE: a level this client does not know is never read as looser.
+ */
+function levelOf(entry) {
+    const raw = entry.degradation_level;
+    return typeof raw === 'string' && exports.DEGRADATION_LEVELS.includes(raw)
+        ? raw
+        : exports.EXPIRED_FLOOR;
+}
+/** `valid_until` in epoch milliseconds, or undefined when missing or unparsable (read as already expired). */
+function validUntilOf(entry) {
+    const raw = entry.valid_until;
+    if (typeof raw !== 'string')
+        return undefined;
+    const at = Date.parse(raw);
+    return Number.isFinite(at) ? at : undefined;
+}
+/**
+ * Combines an entry with what the client observes:
+ *
+ * - answered (online, or a pull of this organization just succeeded): the entry's level;
+ * - not answered and `now < valid_until`: the entry's level, marked degraded;
+ * - not answered and `now >= valid_until` (or no usable `valid_until`): at least RESTRICT_USAGE, marked expired.
+ */
+function combineLevel(entry, answered, now) {
+    const level = levelOf(entry);
+    if (answered) {
+        return { level, source: 'answer', expired: false };
+    }
+    const validUntil = validUntilOf(entry);
+    if (validUntil !== undefined && now < validUntil) {
+        return { level, source: 'degraded', expired: false };
+    }
+    return {
+        level: rank(level) >= rank(exports.EXPIRED_FLOOR) ? level : exports.EXPIRED_FLOOR,
+        source: 'degraded',
+        expired: true,
+    };
+}
+/** True when two effective levels are the same triple. */
+function sameLevel(a, b) {
+    if (!a || !b)
+        return a === b;
+    return a.level === b.level && a.source === b.source && a.expired === b.expired;
+}
+//# sourceMappingURL=degradation.js.map

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

@@ -0,0 +1,61 @@
+import { OrganizationSnapshot, 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 onChange?;
+    private readonly organizations;
+    /** When each organization's entry was received (local clock). */
+    private readonly receivedAt;
+    private currentSchemaVersion;
+    private projectId;
+    private lastUpdatedAt;
+    /**
+     * @param onChange called after the mirror changed: with the organizations whose entry was replaced or
+     *   removed, or with `null` when the whole mirror was replaced.
+     */
+    constructor(onChange?: ((organizationIds: string[] | null) => void) | undefined);
+    /**
+     * 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;
+    /** The entry of one organization, or `undefined` when the mirror does not hold it. */
+    getOrganization(organizationId: string): OrganizationSnapshot | undefined;
+    /** When the entry of one organization was received (local clock), or `undefined`. */
+    getReceivedAt(organizationId: string): number | undefined;
+    /** The organizations the mirror holds. */
+    organizationIds(): string[];
+    /**
+     * 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;
+}