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

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,69 @@
+import { AdjudicationLookupRequest, AdjudicationLookupResponse, ConfirmReservationResult, JwksResponse, ReleaseReservationResult, ReservationResult, ReserveOptions, Snapshot, UsageEventItem, UsageEventsResponse, UsageSendEvent, UsageSendResult } 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>;
+    /**
+     * Sends a batch of usage events as they are: POST /sdk/v1/usage-events. A string quantity travels unchanged,
+     * so decimals keep every digit.
+     */
+    sendUsageEvents(events: UsageSendEvent[], token: string): Promise<UsageSendResult>;
+    /**
+     * 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,238 @@
+"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 ?? [],
+        };
+    }
+    /**
+     * Sends a batch of usage events as they are: POST /sdk/v1/usage-events. A string quantity travels unchanged,
+     * so decimals keep every digit.
+     */
+    async sendUsageEvents(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: typeof event.quantity === 'string' ? event.quantity.trim() : (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 send usage events');
+        return {
+            accepted_count: 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,
+            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