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

package/dist/client/shiprev-client.js

@@ -0,0 +1,267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShipRevClient = void 0;
+const token_verifier_1 = require("../auth/token-verifier");
+const usage_buffer_1 = require("../metering/usage-buffer");
+const entitlement_mirror_1 = require("../mirror/entitlement-mirror");
+const adjudicator_1 = require("../ruling/adjudicator");
+const http_transport_1 = require("../transport/http.transport");
+const types_1 = require("../types");
+const connection_supervisor_1 = require("./connection-supervisor");
+class ShipRevClient {
+    options;
+    transport;
+    tokenVerifier;
+    mirror;
+    adjudicator;
+    usageBuffer;
+    supervisor;
+    /** COLD until start() or setOnline(); otherwise the state follows the online signal and the mirror. */
+    active = false;
+    isOnline = false;
+    /** Issuer and application expected of session tokens, learned from the machine token. */
+    expectations = null;
+    /** Amounts reserved by this client, so `confirm()` without an amount confirms what was reserved. */
+    reservedAmounts = new Map();
+    constructor(options) {
+        this.options = options;
+        this.transport = new http_transport_1.HttpTransport({
+            baseUrl: options.base_url,
+            connectTimeoutMs: options.presets?.connect_timeout_ms,
+        });
+        this.tokenVerifier = new token_verifier_1.TokenVerifier(this.transport);
+        this.mirror = new entitlement_mirror_1.EntitlementMirror();
+        this.adjudicator = new adjudicator_1.Adjudicator(this.mirror, options.presets);
+        this.supervisor = new connection_supervisor_1.ConnectionSupervisor({
+            transport: this.transport,
+            mirror: this.mirror,
+            apiKey: options.api_key,
+            connectTimeoutMs: options.presets?.connect_timeout_ms ?? 5000,
+            loadKeys: () => this.tokenVerifier.refreshKeys(),
+            onToken: (token) => this.learnExpectations(token),
+            setOnline: (online) => this.applyOnline(online),
+            flush: () => this.usageBuffer.flush(),
+        });
+        this.usageBuffer = new usage_buffer_1.UsageBuffer({
+            transport: this.transport,
+            getToken: () => this.supervisor.currentToken(),
+            isOnline: () => this.isOnline,
+            send: (events) => this.supervisor.authorized((token) => this.transport.reportUsageEvents(events, token)),
+            bufferConfig: options.buffer,
+            backlogConfig: options.backlog,
+            onFlushFailure: options.on_flush_failure,
+            onRejected: options.on_rejected,
+        });
+    }
+    /**
+     * Connects the client: fetches the signing keys, exchanges the API key for a service token, opens
+     * the push stream and waits for its `ready` frame, then loads the full entitlement snapshot. Never
+     * throws: LIVE when all four succeed, DISCONNECTED when only the stream failed, COLD_OFFLINE when
+     * nothing could be loaded. From here until `stop()` the client renews its token, follows the push
+     * stream and reconnects by itself.
+     */
+    async start() {
+        this.active = true;
+        await this.supervisor.start();
+        return {
+            project_id: this.mirror.getProjectId(),
+            snapshot_revision: this.mirror.getRevision(),
+            state: this.state().state,
+        };
+    }
+    /**
+     * Closes the push stream, stops every timer and flushes buffered usage events.
+     */
+    async stop() {
+        this.supervisor.stop();
+        await this.usageBuffer.stop();
+        this.active = false;
+        this.isOnline = false;
+    }
+    /**
+     * Enqueues a metered usage event into the memory buffer for batched delivery.
+     */
+    async reportUsage(event) {
+        if (!Number.isFinite(event.quantity)) {
+            throw new RangeError(`Usage quantity must be a finite number, got ${event.quantity}`);
+        }
+        await this.usageBuffer.reportUsage(event);
+    }
+    /**
+     * Manually flushes currently buffered usage events to the core service.
+     */
+    async flush() {
+        await this.usageBuffer.flush();
+    }
+    /**
+     * Verifies an RS256 JWT token locally and extracts subject and isolation keys.
+     */
+    async verifyToken(jwt) {
+        return this.tokenVerifier.verifyToken(jwt, this.expectations);
+    }
+    /**
+     * Executes a four-tier local adjudication (synchronous, zero-IO, P95 <= 5ms).
+     */
+    adjudicate(options) {
+        return this.adjudicator.adjudicate(options, this.isOnline);
+    }
+    /**
+     * Asynchronous adjudication with authoritative fallback.
+     * If local mirror misses the organization or rule and client is online, queries core service and backfills mirror.
+     */
+    async adjudicateAsync(options) {
+        const ruling = this.adjudicate(options);
+        // If local ruling is already allowed (realtime or degraded read) or degraded write rejection, return directly
+        if (ruling.allowed || ruling.source === 'degraded' || !this.isOnline) {
+            return ruling;
+        }
+        // When the mirror misses the organization or capability and the client is online, ask the
+        // service for an authoritative ruling, then refill that organization from the snapshot endpoint.
+        if (this.supervisor.currentToken() && ruling.reason === 'capability_not_granted') {
+            try {
+                const remote = await this.supervisor.authorized((token) => this.transport.lookupAdjudication({
+                    organization_id: options.organization_id,
+                    capability_key: options.capability_key,
+                    quantity: options.quantity,
+                    operation: options.operation,
+                }, token));
+                if (remote.allowed) {
+                    await this.refillOrganization(options.organization_id);
+                }
+                return {
+                    allowed: remote.allowed,
+                    remaining: remote.remaining,
+                    limit: remote.limit,
+                    source: 'authoritative',
+                    reason: remote.reason,
+                    adjudicated_at: Date.now(),
+                };
+            }
+            catch {
+                // Fall back to original ruling if remote call fails
+                return ruling;
+            }
+        }
+        return ruling;
+    }
+    /**
+     * Guard for write operations (fail-closed).
+     * Intercepts action if write operation is denied (e.g. disconnected).
+     */
+    async guardWrite(options, action) {
+        const ruling = this.adjudicate({ ...options, operation: 'write' });
+        if (!ruling.allowed) {
+            throw new types_1.DisconnectedWriteError(ruling.reason === 'disconnected_write'
+                ? 'Write operation denied while client is disconnected'
+                : `Write operation denied: ${ruling.reason ?? 'not allowed'}`);
+        }
+        return action();
+    }
+    /**
+     * Two-phase entitlement reservation: reserve
+     */
+    async reserve(options) {
+        const ttlSeconds = options.ttl_seconds ?? this.options.presets?.reservation_ttl_s;
+        const result = await this.supervisor.authorized((token) => this.transport.reserve(ttlSeconds !== undefined ? { ...options, ttl_seconds: ttlSeconds } : options, token));
+        this.reservedAmounts.set(result.reservation_id, options.amount);
+        return result;
+    }
+    /**
+     * Two-phase entitlement reservation: confirm. Without `actualAmount` the reserved amount is confirmed.
+     */
+    async confirm(reservationId, actualAmount) {
+        const amount = actualAmount ?? this.reservedAmounts.get(reservationId);
+        if (amount === undefined) {
+            throw new Error(`Reservation '${reservationId}' was not made by this client: pass the actual amount to confirm it`);
+        }
+        const result = await this.supervisor.authorized((token) => this.transport.confirmReservation(reservationId, amount, token));
+        this.reservedAmounts.delete(reservationId);
+        return result;
+    }
+    /**
+     * Two-phase entitlement reservation: release
+     */
+    async release(reservationId) {
+        const result = await this.supervisor.authorized((token) => this.transport.releaseReservation(reservationId, token));
+        this.reservedAmounts.delete(reservationId);
+        return result;
+    }
+    /**
+     * Directly loads a snapshot into the local mirror (e.g. for offline seed testing).
+     */
+    loadSnapshot(snapshot) {
+        return this.mirror.loadSnapshot(snapshot);
+    }
+    /**
+     * Returns current internal state and mirror revision.
+     */
+    state() {
+        const state = !this.active
+            ? 'COLD'
+            : this.isOnline
+                ? 'LIVE'
+                : this.mirror.isEmpty()
+                    ? 'COLD_OFFLINE'
+                    : 'DISCONNECTED';
+        return {
+            state,
+            snapshot_revision: this.mirror.getRevision(),
+            last_sync_at: this.mirror.getLastUpdatedAt() || undefined,
+        };
+    }
+    /**
+     * Switches the connection state by hand, for fault injection and tests. `false` closes the push
+     * stream and suspends reconnection until `setOnline(true)`, which sets LIVE at once and resumes
+     * supervision; on a started client the supervisor then corrects the state.
+     */
+    setOnline(online) {
+        this.active = true;
+        this.applyOnline(online);
+        if (online) {
+            this.supervisor.resume();
+        }
+        else {
+            this.supervisor.pause();
+        }
+    }
+    /**
+     * Sets the machine token by hand (for tests without `start()`); a decodable JWT also sets the
+     * issuer and application `verifyToken()` expects.
+     */
+    setM2MToken(token) {
+        this.supervisor.injectToken(token);
+        this.learnExpectations(token);
+    }
+    /**
+     * Directly preloads a public key into the token verifier cache (for testing without network).
+     */
+    setPublicKey(kid, pem) {
+        this.tokenVerifier.setPublicKey(kid, pem);
+    }
+    getUsageBuffer() {
+        return this.usageBuffer;
+    }
+    getTransport() {
+        return this.transport;
+    }
+    applyOnline(online) {
+        this.isOnline = online;
+    }
+    learnExpectations(token) {
+        const expectations = (0, token_verifier_1.expectationsFromMachineToken)(token);
+        if (expectations) {
+            this.expectations = expectations;
+        }
+    }
+    async refillOrganization(organizationId) {
+        try {
+            const snapshot = await this.supervisor.authorized((token) => this.transport.fetchSnapshot(token, organizationId));
+            this.mirror.mergeSnapshot(snapshot);
+        }
+        catch {
+            // The authoritative ruling stands; the next full sync fills the mirror.
+        }
+    }
+}
+exports.ShipRevClient = ShipRevClient;
+//# sourceMappingURL=shiprev-client.js.map

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { ShipRevClient } from './client/shiprev-client';
+import { ShipRevClientOptions } from './types';
+export { jwkToPem, TokenVerifier } from './auth/token-verifier';
+export { ShipRevClient } from './client/shiprev-client';
+export { HostAdapterBacklog } from './metering/backlog/host-adapter-backlog';
+export { JournalBacklog } from './metering/backlog/journal-backlog';
+export { MemoryBacklog } from './metering/backlog/memory-backlog';
+export { UsageBuffer } from './metering/usage-buffer';
+export { EntitlementMirror, MAX_SUPPORTED_SCHEMA_VERSION } from './mirror/entitlement-mirror';
+export { Adjudicator } from './ruling/adjudicator';
+export { HttpTransport } from './transport/http.transport';
+export * from './types';
+/**
+ * Creates and initializes a ShipRev Server SDK client instance for Node.js services.
+ */
+export declare function createClient(options: ShipRevClientOptions): ShipRevClient;

package/dist/index.js

@@ -0,0 +1,47 @@
+"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.HttpTransport = exports.Adjudicator = exports.MAX_SUPPORTED_SCHEMA_VERSION = exports.EntitlementMirror = exports.UsageBuffer = exports.MemoryBacklog = exports.JournalBacklog = exports.HostAdapterBacklog = exports.ShipRevClient = exports.TokenVerifier = exports.jwkToPem = void 0;
+exports.createClient = createClient;
+const shiprev_client_1 = require("./client/shiprev-client");
+var token_verifier_1 = require("./auth/token-verifier");
+Object.defineProperty(exports, "jwkToPem", { enumerable: true, get: function () { return token_verifier_1.jwkToPem; } });
+Object.defineProperty(exports, "TokenVerifier", { enumerable: true, get: function () { return token_verifier_1.TokenVerifier; } });
+var shiprev_client_2 = require("./client/shiprev-client");
+Object.defineProperty(exports, "ShipRevClient", { enumerable: true, get: function () { return shiprev_client_2.ShipRevClient; } });
+var host_adapter_backlog_1 = require("./metering/backlog/host-adapter-backlog");
+Object.defineProperty(exports, "HostAdapterBacklog", { enumerable: true, get: function () { return host_adapter_backlog_1.HostAdapterBacklog; } });
+var journal_backlog_1 = require("./metering/backlog/journal-backlog");
+Object.defineProperty(exports, "JournalBacklog", { enumerable: true, get: function () { return journal_backlog_1.JournalBacklog; } });
+var memory_backlog_1 = require("./metering/backlog/memory-backlog");
+Object.defineProperty(exports, "MemoryBacklog", { enumerable: true, get: function () { return memory_backlog_1.MemoryBacklog; } });
+var usage_buffer_1 = require("./metering/usage-buffer");
+Object.defineProperty(exports, "UsageBuffer", { enumerable: true, get: function () { return usage_buffer_1.UsageBuffer; } });
+var entitlement_mirror_1 = require("./mirror/entitlement-mirror");
+Object.defineProperty(exports, "EntitlementMirror", { enumerable: true, get: function () { return entitlement_mirror_1.EntitlementMirror; } });
+Object.defineProperty(exports, "MAX_SUPPORTED_SCHEMA_VERSION", { enumerable: true, get: function () { return entitlement_mirror_1.MAX_SUPPORTED_SCHEMA_VERSION; } });
+var adjudicator_1 = require("./ruling/adjudicator");
+Object.defineProperty(exports, "Adjudicator", { enumerable: true, get: function () { return adjudicator_1.Adjudicator; } });
+var http_transport_1 = require("./transport/http.transport");
+Object.defineProperty(exports, "HttpTransport", { enumerable: true, get: function () { return http_transport_1.HttpTransport; } });
+__exportStar(require("./types"), exports);
+/**
+ * Creates and initializes a ShipRev Server SDK client instance for Node.js services.
+ */
+function createClient(options) {
+    return new shiprev_client_1.ShipRevClient(options);
+}
+//# sourceMappingURL=index.js.map

package/dist/metering/backlog/host-adapter-backlog.d.ts

@@ -0,0 +1,10 @@
+import { BacklogAdapter, BacklogItem, UsageEventItem } from '../../types';
+export declare class HostAdapterBacklog implements BacklogAdapter {
+    private readonly adapter;
+    constructor(customAdapter?: BacklogAdapter);
+    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/host-adapter-backlog.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HostAdapterBacklog = void 0;
+const memory_backlog_1 = require("./memory-backlog");
+class HostAdapterBacklog {
+    adapter;
+    constructor(customAdapter) {
+        this.adapter = customAdapter ?? new memory_backlog_1.MemoryBacklog();
+    }
+    async enqueue(event) {
+        return this.adapter.enqueue(event);
+    }
+    async peek(limit) {
+        return this.adapter.peek(limit);
+    }
+    async ack(ids) {
+        return this.adapter.ack(ids);
+    }
+    async nack(ids) {
+        return this.adapter.nack(ids);
+    }
+    async size() {
+        return this.adapter.size();
+    }
+}
+exports.HostAdapterBacklog = HostAdapterBacklog;
+//# sourceMappingURL=host-adapter-backlog.js.map

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

@@ -0,0 +1,14 @@
+import { BacklogAdapter, BacklogItem, UsageEventItem } from '../../types';
+export declare class JournalBacklog implements BacklogAdapter {
+    private readonly filePath;
+    private queue;
+    private isCompacting;
+    constructor(filePath?: string);
+    private recoverSync;
+    enqueue(event: UsageEventItem): Promise<void>;
+    peek(limit: number): Promise<BacklogItem[]>;
+    ack(ids: string[]): Promise<void>;
+    nack(ids: string[]): Promise<void>;
+    size(): Promise<number>;
+    private compact;
+}

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>;
+}