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

package/dist/types.d.ts

@@ -0,0 +1,252 @@
+export type RulingSource = 'realtime' | 'authoritative' | 'degraded' | 'client_default';
+export interface Ruling {
+    allowed: boolean;
+    remaining?: number;
+    limit?: number;
+    source: RulingSource;
+    reason?: 'disconnected_write' | 'invalid_request' | string;
+    adjudicated_at: number;
+}
+export interface AdjudicateOptions {
+    organization_id: string;
+    capability_key: string;
+    quantity?: number;
+    operation: 'read' | 'write';
+}
+export interface TokenClaims {
+    account_id: string;
+    organization_id: string;
+    project_id: string;
+    tenant_id: string;
+    key_version: number;
+    scope: string;
+    exp: number;
+    iat?: number;
+    iss?: string;
+    sub?: string;
+    aud?: string;
+}
+/**
+ * Overage policy of a capability, as the service reports it. Unknown future values are kept as
+ * strings and treated like BLOCK by local rulings.
+ */
+export type OveragePolicy = 'BLOCK' | 'ALLOW_AND_BILL' | 'PROMPT_UPGRADE' | (string & {});
+/**
+ * One capability of an organization's snapshot, as served by `GET /sdk/v1/entitlements/snapshot`.
+ * Quantities are fixed-point decimal strings (e.g. "10.000000"), never floating point.
+ */
+export interface SnapshotItem {
+    capability_key: string;
+    allowance: string;
+    used: string;
+    remaining: string;
+    overage_policy: OveragePolicy;
+    starts_at?: string;
+    ends_at?: string;
+    reset_interval?: string;
+    billing_interval?: string;
+}
+/** One buyer organization inside the application snapshot. */
+export interface OrganizationSnapshot {
+    revision: number;
+    wallet_balance: string;
+    /**
+     * Credits the wallet may go below zero by for ALLOW_AND_BILL capabilities. Informational: the mirror never widens
+     * a local ruling with it; beyond the allowance the service decides. Absent on instances that predate it.
+     */
+    overdraft_limit?: string;
+    items: Record<string, SnapshotItem>;
+    /**
+     * Degradation level the instance computed for the organization. Instances that predate it leave it out; a
+     * value outside `DegradationLevel` is read as `RESTRICT_USAGE`.
+     */
+    degradation_level?: string;
+    /** ISO 8601 time until which this entry may be used without a newer answer. */
+    valid_until?: string;
+}
+/**
+ * Degradation level of a buyer organization, strictly increasing: `RESTRICT_NEW` blocks new commercial objects,
+ * `RESTRICT_USAGE` every write, `RESTRICT_READ` end-user reads too, and `SUSPENDED` is an explicit "no
+ * entitlement". Computed by the instance; a client only enforces it.
+ */
+export type DegradationLevel = 'NONE' | 'RESTRICT_NEW' | 'RESTRICT_USAGE' | 'RESTRICT_READ' | 'SUSPENDED';
+/**
+ * The level to act on for one organization, combined from the mirror entry and what the client observes:
+ * `source: 'answer'` while the instance answers (online, or a pull of the organization just succeeded);
+ * `'degraded'` when acting on the mirror without an answer, with `expired` once the entry's `valid_until` has
+ * passed (the level is then at least `RESTRICT_USAGE`).
+ */
+export interface EffectiveLevel {
+    level: DegradationLevel;
+    source: 'answer' | 'degraded';
+    expired: boolean;
+}
+/** One usage event for `sendUsage()`. The quantity may be a decimal string, sent as it is. */
+export interface UsageSendEvent {
+    usage_event_id: string;
+    organization_id: string;
+    capability_key: string;
+    quantity: number | string;
+    occurred_at: string;
+    properties?: Record<string, unknown>;
+}
+/** What the instance did with a batch sent by `sendUsage()`. */
+export interface UsageSendResult {
+    accepted_count: number;
+    duplicates_dropped: number;
+    rejected: Array<{
+        usage_event_id: string;
+        reason: string;
+    }>;
+}
+/**
+ * Application-level entitlement snapshot envelope served by `GET /sdk/v1/entitlements/snapshot`:
+ * every buyer organization of the application, keyed by organization ID.
+ */
+export interface Snapshot {
+    project_id: string;
+    schema_version: number;
+    generated_at: string;
+    organizations: Record<string, OrganizationSnapshot>;
+}
+export interface ClientPresets {
+    cold_start?: 'allow' | 'deny';
+    connect_timeout_ms?: number;
+    reservation_ttl_s?: number;
+}
+export interface BacklogItem {
+    id: string;
+    event: UsageEventItem;
+    enqueued_at: number;
+    attempts: number;
+}
+export interface BacklogAdapter {
+    enqueue(event: UsageEventItem): Promise<void>;
+    peek(limit: number): Promise<BacklogItem[]>;
+    ack(ids: string[]): Promise<void>;
+    nack(ids: string[]): Promise<void>;
+    size(): Promise<number>;
+}
+export interface BacklogConfig {
+    mode?: 'memory' | 'host_adapter' | 'journal';
+    journal_path?: string;
+    adapter?: BacklogAdapter;
+    max_attempts?: number;
+}
+export interface UsageBufferConfig {
+    batch_size?: number;
+    flush_interval_ms?: number;
+}
+export interface UsageEventItem {
+    usage_event_id: string;
+    organization_id: string;
+    capability_key: string;
+    quantity: number;
+    occurred_at: string;
+    idempotency_key?: string;
+    properties?: Record<string, unknown>;
+}
+export interface RejectedEvent {
+    usage_event_id: string;
+    reason: string;
+}
+export interface UsageEventsResponse {
+    accepted: number;
+    duplicates_dropped: number;
+    rejected: RejectedEvent[];
+}
+export interface ReserveOptions {
+    organization_id: string;
+    capability_key: string;
+    amount: number;
+    idempotency_key?: string;
+    ttl_seconds?: number;
+}
+export interface ReservationResult {
+    reservation_id: string;
+    status: 'RESERVED' | 'CONFIRMED' | 'RELEASED';
+    expires_at: string;
+}
+export interface ConfirmReservationResult {
+    reservation_id: string;
+    status: 'CONFIRMED';
+    confirmed_amount: number;
+}
+export interface ReleaseReservationResult {
+    reservation_id: string;
+    status: 'RELEASED';
+}
+export interface AdjudicationLookupRequest {
+    organization_id: string;
+    capability_key: string;
+    quantity?: number;
+    operation: 'read' | 'write';
+}
+export interface AdjudicationLookupResponse {
+    allowed: boolean;
+    remaining?: number;
+    limit?: number;
+    source: 'authoritative';
+    reason?: string;
+}
+export interface ShipRevClientOptions {
+    api_key: string;
+    base_url: string;
+    presets?: ClientPresets;
+    buffer?: UsageBufferConfig;
+    backlog?: BacklogConfig;
+    on_flush_failure?: (events: UsageEventItem[], error: Error) => void;
+    on_rejected?: (rejected: RejectedEvent[]) => void;
+    /**
+     * Called when the effective level of an organization changes: a new entry, the connection going up or down,
+     * or an entry's `valid_until` passing while disconnected. Never called for an organization the mirror does
+     * not hold.
+     */
+    on_level_change?: (organization_id: string, level: EffectiveLevel) => void;
+}
+export declare class DisconnectedWriteError extends Error {
+    readonly reason = "disconnected_write";
+    constructor(message?: string);
+}
+/**
+ * Thrown by `sendUsage()` when the batch did not reach the instance or the instance failed to process it (a
+ * network error, a timeout or a 5xx answer). Nothing in the batch can be assumed delivered; sending it again is
+ * safe, as every event carries its idempotency key.
+ */
+export declare class UsageDeliveryError extends Error {
+    constructor(message?: string);
+}
+/** Why `verifyToken()` refused a correctly signed, unexpired token. */
+export type TokenRejectionReason = 
+/** The client has not obtained a machine token yet, so the expected issuer and application are unknown. */
+'not_ready'
+/** `aud` or `scope` is not `'public'`: not a buyer session token. */
+ | 'audience_mismatch'
+/** `iss` differs from the issuer of this client's machine token. */
+ | 'issuer_mismatch'
+/** `pid` differs from the application of this client's machine token. */
+ | 'project_mismatch'
+/** The token carries a `purpose` claim: a one-time token such as an email verification link. */
+ | 'not_a_session_token'
+/** The token has no numeric `exp`. */
+ | 'missing_expiry';
+/**
+ * Thrown by `verifyToken()` when a token is correctly signed but is not a session token this client
+ * accepts. The message names the reason and never contains the token.
+ */
+export declare class TokenRejectedError extends Error {
+    readonly reason: TokenRejectionReason;
+    constructor(reason: TokenRejectionReason, message?: string);
+}
+export type ClientState = 'COLD' | 'CLAIMED' | 'LIVE' | 'COLD_OFFLINE' | 'DISCONNECTED';
+export interface JwksKey {
+    kid: string;
+    kty: string;
+    alg?: string;
+    use?: string;
+    n: string;
+    e: string;
+}
+export interface JwksResponse {
+    keys: JwksKey[];
+}

package/dist/types.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenRejectedError = exports.UsageDeliveryError = exports.DisconnectedWriteError = void 0;
+class DisconnectedWriteError extends Error {
+    reason = 'disconnected_write';
+    constructor(message = 'Write operation denied while client is disconnected') {
+        super(message);
+        this.name = 'DisconnectedWriteError';
+    }
+}
+exports.DisconnectedWriteError = DisconnectedWriteError;
+/**
+ * Thrown by `sendUsage()` when the batch did not reach the instance or the instance failed to process it (a
+ * network error, a timeout or a 5xx answer). Nothing in the batch can be assumed delivered; sending it again is
+ * safe, as every event carries its idempotency key.
+ */
+class UsageDeliveryError extends Error {
+    constructor(message = 'Usage events could not be delivered') {
+        super(message);
+        this.name = 'UsageDeliveryError';
+    }
+}
+exports.UsageDeliveryError = UsageDeliveryError;
+/**
+ * Thrown by `verifyToken()` when a token is correctly signed but is not a session token this client
+ * accepts. The message names the reason and never contains the token.
+ */
+class TokenRejectedError extends Error {
+    reason;
+    constructor(reason, message = `Token rejected: ${reason}`) {
+        super(message);
+        this.name = 'TokenRejectedError';
+        this.reason = reason;
+    }
+}
+exports.TokenRejectedError = TokenRejectedError;
+//# sourceMappingURL=types.js.map

package/dist/util/decimal.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Exact helpers for the fixed-point decimal strings the service uses for quantities and amounts.
+ * Public SDK types carry numbers; these helpers convert at the wire boundary and compare
+ * decimal strings without going through floating point.
+ */
+/**
+ * Converts a finite number to a plain decimal string (no exponent), e.g. 3 -> "3", 1e-7 -> "0.0000001".
+ * Throws RangeError for NaN or infinite values.
+ */
+export declare function toDecimalString(value: number): string;
+/** Compares two decimal strings exactly: negative when a < b, zero when equal, positive when a > b. */
+export declare function compareDecimal(a: string, b: string): number;
+/** Reads a decimal string from the wire into the number used by public SDK types. */
+export declare function decimalToNumber(value: string | null | undefined): number | undefined;

package/dist/util/decimal.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Exact helpers for the fixed-point decimal strings the service uses for quantities and amounts.
+ * Public SDK types carry numbers; these helpers convert at the wire boundary and compare
+ * decimal strings without going through floating point.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toDecimalString = toDecimalString;
+exports.compareDecimal = compareDecimal;
+exports.decimalToNumber = decimalToNumber;
+const DECIMAL_PATTERN = /^(-)?(\d+)(?:\.(\d+))?$/;
+/**
+ * Converts a finite number to a plain decimal string (no exponent), e.g. 3 -> "3", 1e-7 -> "0.0000001".
+ * Throws RangeError for NaN or infinite values.
+ */
+function toDecimalString(value) {
+    if (!Number.isFinite(value)) {
+        throw new RangeError(`Quantity must be a finite number, got ${value}`);
+    }
+    const text = String(value);
+    if (!/e/i.test(text)) {
+        return text;
+    }
+    // Exponent notation: expand through toFixed and drop trailing zeros.
+    const fixed = Math.abs(value) >= 1 ? BigInt(Math.trunc(value)).toString() : value.toFixed(20);
+    return fixed.includes('.') ? fixed.replace(/0+$/, '').replace(/\.$/, '') : fixed;
+}
+function parse(value) {
+    const match = DECIMAL_PATTERN.exec(value.trim());
+    if (!match) {
+        throw new RangeError(`Not a decimal string: ${value}`);
+    }
+    const fraction = match[3] ?? '';
+    return {
+        negative: match[1] === '-',
+        digits: BigInt(`${match[2]}${fraction}`),
+        scale: fraction.length,
+    };
+}
+/** Compares two decimal strings exactly: negative when a < b, zero when equal, positive when a > b. */
+function compareDecimal(a, b) {
+    const pa = parse(a);
+    const pb = parse(b);
+    const scale = Math.max(pa.scale, pb.scale);
+    const va = (pa.negative ? -1n : 1n) * pa.digits * 10n ** BigInt(scale - pa.scale);
+    const vb = (pb.negative ? -1n : 1n) * pb.digits * 10n ** BigInt(scale - pb.scale);
+    return va < vb ? -1 : va > vb ? 1 : 0;
+}
+/** Reads a decimal string from the wire into the number used by public SDK types. */
+function decimalToNumber(value) {
+    if (value === null || value === undefined) {
+        return undefined;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+//# sourceMappingURL=decimal.js.map

package/package.json

@@ -1,6 +1,99 @@
 {
   "name": "@shiprev/server-sdk-node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-beta.1",
+  "description": "Server SDK for Node.js and NestJS services: token verification, local entitlement rulings, usage reporting, and two-phase reservations against a ShipRev instance.",
+  "keywords": [
+    "shiprev",
+    "entitlements",
+    "metering",
+    "usage-based-billing",
+    "nestjs",
+    "sdk"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./nest": {
+      "types": "./dist/nest/index.d.ts",
+      "default": "./dist/nest/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "nest": [
+        "./dist/nest/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^9.0.0 || ^10.0.0 || ^11.0.0",
+    "@nestjs/core": "^9.0.0 || ^10.0.0 || ^11.0.0",
+    "reflect-metadata": "^0.1.13 || ^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    },
+    "@nestjs/core": {
+      "optional": true
+    },
+    "reflect-metadata": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/core": "^11.1.12",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.10.7",
+    "eslint": "^9.18.0",
+    "eslint-plugin-prettier": "^5.2.2",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "globals": "^16.0.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.0.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.20.0"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.ts$": "ts-jest"
+    },
+    "testEnvironment": "node"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "jest",
+    "test:nest9": "node scripts/test-nest9.mjs",
+    "lint": "eslint \"src/**/*.ts\"",
+    "format": "prettier --write \"src/**/*.ts\""
+  }
 }