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

package/dist/ruling/adjudicator.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Adjudicator = void 0;
+const decimal_1 = require("../util/decimal");
+class Adjudicator {
+    mirror;
+    presets;
+    constructor(mirror, presets) {
+        this.mirror = mirror;
+        this.presets = presets;
+    }
+    /**
+     * 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, isOnline, authoritativeLookup) {
+        const now = Date.now();
+        // 1. Mandatory operation guard
+        if (options.operation !== 'read' && options.operation !== 'write') {
+            return {
+                allowed: false,
+                source: 'client_default',
+                reason: 'invalid_request',
+                adjudicated_at: now,
+            };
+        }
+        const { organization_id, capability_key, quantity = 1, operation } = options;
+        if (typeof quantity !== 'number' || !Number.isFinite(quantity) || quantity < 0) {
+            return {
+                allowed: false,
+                source: 'client_default',
+                reason: 'invalid_request',
+                adjudicated_at: now,
+            };
+        }
+        // 2. Cold start offline (mirror is empty and control plane is offline)
+        if (this.mirror.isEmpty() && !isOnline) {
+            if (operation === 'write') {
+                return {
+                    allowed: false,
+                    source: 'client_default',
+                    reason: 'disconnected_write',
+                    adjudicated_at: now,
+                };
+            }
+            // Read operation: check customer preset
+            const allowColdRead = this.presets?.cold_start === 'allow';
+            return {
+                allowed: allowColdRead,
+                source: 'client_default',
+                reason: allowColdRead ? undefined : 'cold_start_denied',
+                adjudicated_at: now,
+            };
+        }
+        // 3. Disconnected mode with existing mirror
+        if (!isOnline) {
+            if (operation === 'write') {
+                return {
+                    allowed: false,
+                    source: 'degraded',
+                    reason: 'disconnected_write',
+                    adjudicated_at: now,
+                };
+            }
+            // Read fail-open under disconnected state
+            return {
+                allowed: true,
+                source: 'degraded',
+                adjudicated_at: now,
+            };
+        }
+        // 4. Online evaluation: check mirror first
+        const item = this.mirror.getItem(organization_id, capability_key);
+        if (item) {
+            // Tier 1: realtime, compared exactly on the snapshot's decimal strings
+            const limit = (0, decimal_1.decimalToNumber)(item.allowance);
+            if ((0, decimal_1.compareDecimal)((0, decimal_1.toDecimalString)(quantity), item.remaining) <= 0) {
+                return {
+                    allowed: true,
+                    remaining: (0, decimal_1.decimalToNumber)(item.remaining),
+                    limit,
+                    source: 'realtime',
+                    adjudicated_at: now,
+                };
+            }
+            // Beyond the remaining allowance only ALLOW_AND_BILL lets the call through locally; any other
+            // policy depends on prices and wallet state the mirror does not hold, so it is refused.
+            if (item.overage_policy === 'ALLOW_AND_BILL') {
+                return {
+                    allowed: true,
+                    remaining: 0,
+                    limit,
+                    source: 'realtime',
+                    adjudicated_at: now,
+                };
+            }
+            return {
+                allowed: false,
+                remaining: (0, decimal_1.decimalToNumber)(item.remaining),
+                limit,
+                source: 'realtime',
+                reason: 'quota_exhausted',
+                adjudicated_at: now,
+            };
+        }
+        // 5. Tier 2: authoritative fallback if missing in mirror but online
+        if (authoritativeLookup) {
+            const authoritativeResult = authoritativeLookup();
+            if (authoritativeResult) {
+                return {
+                    ...authoritativeResult,
+                    source: 'authoritative',
+                    adjudicated_at: now,
+                };
+            }
+        }
+        // Online but the mirror does not know the organization or capability: a client-side refusal,
+        // not a service ruling. adjudicateAsync() asks the service on this reason.
+        return {
+            allowed: false,
+            source: 'client_default',
+            reason: 'capability_not_granted',
+            adjudicated_at: now,
+        };
+    }
+}
+exports.Adjudicator = Adjudicator;
+//# sourceMappingURL=adjudicator.js.map

package/dist/transport/event-stream.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Server-Sent Events reader for `GET /sdk/v1/events`, on top of a `fetch` response body. No
+ * dependency: the frames are parsed here.
+ *
+ * Accepts what the format allows: frames split across reads or several per read, LF, CRLF or CR
+ * line endings, comment lines (starting with `:`), and `data` spread over several lines (joined
+ * with a newline). Fields other than `event` and `data` are ignored.
+ */
+export interface EventStreamFrame {
+    /** Event type; `message` when the frame names none. */
+    event: string;
+    /** The `data` lines joined with `\n`. */
+    data: string;
+}
+/** Incremental parser: feed it text, it returns the frames completed so far. */
+export declare class EventStreamParser {
+    private pending;
+    private eventType;
+    private dataLines;
+    push(chunk: string): EventStreamFrame[];
+    private line;
+}
+/**
+ * Reads the body of an event stream response and hands every frame to `onFrame`. Resolves when the
+ * body ends, rejects on a read error (a reset connection, an abort).
+ */
+export declare function readEventStream(body: ReadableStream<Uint8Array>, onFrame: (frame: EventStreamFrame) => void): Promise<void>;

package/dist/transport/event-stream.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * Server-Sent Events reader for `GET /sdk/v1/events`, on top of a `fetch` response body. No
+ * dependency: the frames are parsed here.
+ *
+ * Accepts what the format allows: frames split across reads or several per read, LF, CRLF or CR
+ * line endings, comment lines (starting with `:`), and `data` spread over several lines (joined
+ * with a newline). Fields other than `event` and `data` are ignored.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventStreamParser = void 0;
+exports.readEventStream = readEventStream;
+/** Incremental parser: feed it text, it returns the frames completed so far. */
+class EventStreamParser {
+    pending = '';
+    eventType = '';
+    dataLines = [];
+    push(chunk) {
+        this.pending += chunk;
+        const frames = [];
+        let start = 0;
+        for (let i = 0; i < this.pending.length; i++) {
+            const ch = this.pending[i];
+            if (ch !== '\n' && ch !== '\r')
+                continue;
+            // A CR at the very end may be the first half of a CRLF split across reads: wait for more.
+            if (ch === '\r' && i === this.pending.length - 1)
+                break;
+            const line = this.pending.slice(start, i);
+            if (ch === '\r' && this.pending[i + 1] === '\n')
+                i++;
+            start = i + 1;
+            const frame = this.line(line);
+            if (frame)
+                frames.push(frame);
+        }
+        this.pending = this.pending.slice(start);
+        return frames;
+    }
+    line(line) {
+        if (line === '') {
+            if (this.dataLines.length === 0) {
+                this.eventType = '';
+                return undefined;
+            }
+            const frame = { event: this.eventType || 'message', data: this.dataLines.join('\n') };
+            this.eventType = '';
+            this.dataLines = [];
+            return frame;
+        }
+        if (line.startsWith(':'))
+            return undefined;
+        const colon = line.indexOf(':');
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? '' : line.slice(colon + 1);
+        if (value.startsWith(' '))
+            value = value.slice(1);
+        if (field === 'event') {
+            this.eventType = value;
+        }
+        else if (field === 'data') {
+            this.dataLines.push(value);
+        }
+        return undefined;
+    }
+}
+exports.EventStreamParser = EventStreamParser;
+/**
+ * Reads the body of an event stream response and hands every frame to `onFrame`. Resolves when the
+ * body ends, rejects on a read error (a reset connection, an abort).
+ */
+async function readEventStream(body, onFrame) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder('utf-8');
+    const parser = new EventStreamParser();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                for (const frame of parser.push(decoder.decode() + '\n'))
+                    onFrame(frame);
+                return;
+            }
+            for (const frame of parser.push(decoder.decode(value, { stream: true })))
+                onFrame(frame);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+//# sourceMappingURL=event-stream.js.map

package/dist/transport/http.transport.d.ts

@@ -0,0 +1,64 @@
+import { AdjudicationLookupRequest, AdjudicationLookupResponse, ConfirmReservationResult, JwksResponse, ReleaseReservationResult, ReservationResult, ReserveOptions, Snapshot, UsageEventItem, UsageEventsResponse } from '../types';
+/** A non-success HTTP answer from the instance; `status` lets callers tell a refused token from an outage. */
+export declare class HttpError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/** True when `error` is an HTTP answer with one of the given statuses. */
+export declare function isHttpStatus(error: unknown, ...statuses: number[]): boolean;
+export interface TransportOptions {
+    baseUrl: string;
+    connectTimeoutMs?: number;
+    clientVersion?: string;
+}
+export declare class HttpTransport {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly userAgent;
+    constructor(options: TransportOptions);
+    /**
+     * Fetches public JWKS keys from the unauthenticated runtime endpoint GET /sdk/v1/jwks
+     */
+    fetchJwks(): Promise<JwksResponse>;
+    /**
+     * Exchanges an SDK-scoped API key for an RS256 short-lived M2M JWT token
+     */
+    exchangeM2MToken(apiKey: string): Promise<{
+        access_token: string;
+        expires_in: number;
+    }>;
+    /**
+     * Fetches the application-level entitlement snapshot: GET /sdk/v1/entitlements/snapshot.
+     * With `organizationId` the envelope carries that organization only (used to refill a mirror miss).
+     */
+    fetchSnapshot(token: string, organizationId?: string): Promise<Snapshot>;
+    /**
+     * Submits a batch of usage events: POST /sdk/v1/usage-events.
+     * Quantities are sent as decimal strings; `properties` travel as the event's `dimensions`.
+     */
+    reportUsageEvents(events: UsageEventItem[], token: string): Promise<UsageEventsResponse>;
+    /**
+     * Authoritative ruling when the mirror misses an organization or capability: POST /sdk/v1/adjudicate.
+     */
+    lookupAdjudication(request: AdjudicationLookupRequest, token: string): Promise<AdjudicationLookupResponse>;
+    /**
+     * Requests a two-phase reservation: POST /sdk/v1/reservations/reserve.
+     */
+    reserve(options: ReserveOptions, token: string): Promise<ReservationResult>;
+    /**
+     * Confirms a pending reservation with the quantity actually used: POST /sdk/v1/reservations/:id/confirm.
+     */
+    confirmReservation(reservationId: string, actualAmount: number, token: string): Promise<ConfirmReservationResult>;
+    /**
+     * Releases a pending reservation: POST /sdk/v1/reservations/:id/release.
+     */
+    releaseReservation(reservationId: string, token: string): Promise<ReleaseReservationResult>;
+    /**
+     * Opens the push stream `GET /sdk/v1/events`. Resolves with the response once the headers arrive;
+     * the body stays open until the instance ends it or `signal` aborts it, so no request timeout
+     * applies here (the caller bounds the wait for `ready`).
+     */
+    openEventStream(token: string, signal: AbortSignal): Promise<Response>;
+    private postJson;
+    private request;
+}

package/dist/transport/http.transport.js

@@ -0,0 +1,218 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpTransport = exports.HttpError = void 0;
+exports.isHttpStatus = isHttpStatus;
+const decimal_1 = require("../util/decimal");
+/** A non-success HTTP answer from the instance; `status` lets callers tell a refused token from an outage. */
+class HttpError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'HttpError';
+    }
+}
+exports.HttpError = HttpError;
+/** True when `error` is an HTTP answer with one of the given statuses. */
+function isHttpStatus(error, ...statuses) {
+    return error instanceof HttpError && statuses.includes(error.status);
+}
+class HttpTransport {
+    baseUrl;
+    timeoutMs;
+    userAgent;
+    constructor(options) {
+        // Strip trailing slashes
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.timeoutMs = options.connectTimeoutMs ?? 5000;
+        this.userAgent = `@shiprev/server-sdk-node/${options.clientVersion ?? '0.0.0'}`;
+    }
+    /**
+     * Fetches public JWKS keys from the unauthenticated runtime endpoint GET /sdk/v1/jwks
+     */
+    async fetchJwks() {
+        const url = `${this.baseUrl}/sdk/v1/jwks`;
+        const response = await this.request(url, {
+            method: 'GET',
+        });
+        if (!response.ok) {
+            throw new HttpError(`Failed to fetch JWKS from ${url}: HTTP ${response.status}`, response.status);
+        }
+        return (await response.json());
+    }
+    /**
+     * Exchanges an SDK-scoped API key for an RS256 short-lived M2M JWT token
+     */
+    async exchangeM2MToken(apiKey) {
+        const url = `${this.baseUrl}/sdk/v1/m2m/token`;
+        const response = await this.request(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ api_key: apiKey }),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new HttpError(`Failed to exchange M2M token: HTTP ${response.status} - ${errorText}`, response.status);
+        }
+        return (await response.json());
+    }
+    /**
+     * Fetches the application-level entitlement snapshot: GET /sdk/v1/entitlements/snapshot.
+     * With `organizationId` the envelope carries that organization only (used to refill a mirror miss).
+     */
+    async fetchSnapshot(token, organizationId) {
+        const url = organizationId
+            ? `${this.baseUrl}/sdk/v1/entitlements/snapshot?organization_id=${encodeURIComponent(organizationId)}`
+            : `${this.baseUrl}/sdk/v1/entitlements/snapshot`;
+        const response = await this.request(url, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${token}`,
+            },
+        });
+        if (!response.ok) {
+            throw new HttpError(`Failed to fetch snapshot: HTTP ${response.status}`, response.status);
+        }
+        return (await response.json());
+    }
+    /**
+     * Submits a batch of usage events: POST /sdk/v1/usage-events.
+     * Quantities are sent as decimal strings; `properties` travel as the event's `dimensions`.
+     */
+    async reportUsageEvents(events, token) {
+        const wireEvents = events.map((event) => ({
+            usage_event_id: event.usage_event_id,
+            organization_id: event.organization_id,
+            capability_key: event.capability_key,
+            quantity: (0, decimal_1.toDecimalString)(event.quantity),
+            occurred_at: event.occurred_at,
+            ...(event.properties !== undefined ? { dimensions: event.properties } : {}),
+        }));
+        const body = await this.postJson('/sdk/v1/usage-events', { events: wireEvents }, token, 'Failed to report usage events');
+        return {
+            accepted: body.accepted_count,
+            duplicates_dropped: body.duplicates_dropped,
+            rejected: body.rejected ?? [],
+        };
+    }
+    /**
+     * Authoritative ruling when the mirror misses an organization or capability: POST /sdk/v1/adjudicate.
+     */
+    async lookupAdjudication(request, token) {
+        const wireRequest = {
+            organization_id: request.organization_id,
+            capability_key: request.capability_key,
+            operation: request.operation,
+            ...(request.quantity !== undefined ? { quantity: (0, decimal_1.toDecimalString)(request.quantity) } : {}),
+        };
+        const body = await this.postJson('/sdk/v1/adjudicate', wireRequest, token, 'Authoritative lookup failed');
+        return {
+            allowed: body.allowed,
+            remaining: (0, decimal_1.decimalToNumber)(body.remaining),
+            limit: (0, decimal_1.decimalToNumber)(body.limit),
+            source: 'authoritative',
+            reason: body.reason ?? undefined,
+        };
+    }
+    /**
+     * Requests a two-phase reservation: POST /sdk/v1/reservations/reserve.
+     */
+    async reserve(options, token) {
+        const wireRequest = {
+            organization_id: options.organization_id,
+            capability_key: options.capability_key,
+            quantity: (0, decimal_1.toDecimalString)(options.amount),
+            ...(options.ttl_seconds !== undefined ? { ttl_seconds: options.ttl_seconds } : {}),
+        };
+        const body = await this.postJson('/sdk/v1/reservations/reserve', wireRequest, token, 'Reservation failed');
+        return {
+            reservation_id: body.reservation_id,
+            status: body.status === 'RESERVED' ? 'PENDING' : body.status,
+            expires_at: body.expires_at,
+        };
+    }
+    /**
+     * Confirms a pending reservation with the quantity actually used: POST /sdk/v1/reservations/:id/confirm.
+     */
+    async confirmReservation(reservationId, actualAmount, token) {
+        const wireRequest = { actual_quantity: (0, decimal_1.toDecimalString)(actualAmount) };
+        const body = await this.postJson(`/sdk/v1/reservations/${encodeURIComponent(reservationId)}/confirm`, wireRequest, token, 'Reservation confirm failed');
+        return {
+            reservation_id: body.reservation_id,
+            status: 'CONFIRMED',
+            confirmed_amount: (0, decimal_1.decimalToNumber)(body.actual_quantity) ?? actualAmount,
+        };
+    }
+    /**
+     * Releases a pending reservation: POST /sdk/v1/reservations/:id/release.
+     */
+    async releaseReservation(reservationId, token) {
+        const body = await this.postJson(`/sdk/v1/reservations/${encodeURIComponent(reservationId)}/release`, {}, token, 'Reservation release failed');
+        return { reservation_id: body.reservation_id, status: 'RELEASED' };
+    }
+    /**
+     * Opens the push stream `GET /sdk/v1/events`. Resolves with the response once the headers arrive;
+     * the body stays open until the instance ends it or `signal` aborts it, so no request timeout
+     * applies here (the caller bounds the wait for `ready`).
+     */
+    async openEventStream(token, signal) {
+        const url = `${this.baseUrl}/sdk/v1/events`;
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: 'text/event-stream',
+                'User-Agent': this.userAgent,
+            },
+            signal,
+        });
+        if (!response.ok || !response.body) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new HttpError(`Failed to open the event stream: HTTP ${response.status}`, response.status);
+        }
+        return response;
+    }
+    async postJson(path, payload, token, failure) {
+        const response = await this.request(`${this.baseUrl}${path}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify(payload),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new HttpError(`${failure}: HTTP ${response.status} - ${errorText}`, response.status);
+        }
+        return (await response.json());
+    }
+    async request(url, init) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const headers = new Headers(init.headers);
+            headers.set('User-Agent', this.userAgent);
+            headers.set('Accept', 'application/json');
+            const response = await fetch(url, {
+                ...init,
+                headers,
+                signal: controller.signal,
+            });
+            return response;
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new Error(`Request to ${url} timed out after ${this.timeoutMs}ms`);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+exports.HttpTransport = HttpTransport;
+//# sourceMappingURL=http.transport.js.map

package/dist/transport/wire.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Request and response bodies of the service's `sdk` partition, exactly as they travel on the wire.
+ * The service owns these shapes; the transport maps them to and from the public SDK types, so
+ * nothing outside `transport/` depends on them. Quantities are fixed-point decimal strings.
+ */
+/** `POST /sdk/v1/adjudicate` request. */
+export interface WireAdjudicateRequest {
+    organization_id: string;
+    capability_key: string;
+    quantity?: string;
+    operation: 'read' | 'write';
+}
+/** `POST /sdk/v1/adjudicate` response. */
+export interface WireAdjudicateResponse {
+    allowed: boolean;
+    remaining: string;
+    limit?: string;
+    source: 'AUTHORITATIVE';
+    reason?: string | null;
+    adjudicated_at: number;
+}
+/** One event of `POST /sdk/v1/usage-events`. */
+export interface WireUsageEvent {
+    usage_event_id: string;
+    organization_id: string;
+    capability_key: string;
+    quantity: string;
+    occurred_at: string;
+    dimensions?: Record<string, unknown>;
+}
+/** `POST /sdk/v1/usage-events` response. */
+export interface WireUsageEventsResponse {
+    accepted_count: number;
+    duplicates_dropped: number;
+    rejected_count: number;
+    rejected: Array<{
+        usage_event_id: string;
+        reason: string;
+    }>;
+}
+/** `POST /sdk/v1/reservations/reserve` request. */
+export interface WireReserveRequest {
+    organization_id: string;
+    capability_key: string;
+    quantity: string;
+    ttl_seconds?: number;
+}
+/** `POST /sdk/v1/reservations/reserve` response. */
+export interface WireReservationResponse {
+    reservation_id: string;
+    project_id: string;
+    organization_id: string;
+    capability_key: string;
+    quantity: string;
+    status: 'RESERVED' | 'CONFIRMED' | 'RELEASED';
+    expires_at: string;
+    created_at: string;
+}
+/** `POST /sdk/v1/reservations/:id/confirm` request. */
+export interface WireConfirmReservationRequest {
+    actual_quantity: string;
+}
+/** `POST /sdk/v1/reservations/:id/confirm` response. */
+export interface WireConfirmReservationResponse {
+    reservation_id: string;
+    status: 'CONFIRMED';
+    reserved_quantity: string;
+    actual_quantity: string;
+    difference_refunded?: string;
+    difference_debited?: string;
+    settled_at: string;
+}
+/** `POST /sdk/v1/reservations/:id/release` response. */
+export interface WireReleaseReservationResponse {
+    reservation_id: string;
+    status: 'RELEASED';
+    released_quantity: string;
+    released_at: string;
+}

package/dist/transport/wire.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Request and response bodies of the service's `sdk` partition, exactly as they travel on the wire.
+ * The service owns these shapes; the transport maps them to and from the public SDK types, so
+ * nothing outside `transport/` depends on them. Quantities are fixed-point decimal strings.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=wire.js.map