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

package/dist/types.d.ts

@@ -4,7 +4,13 @@ export interface Ruling {
     remaining?: number;
     limit?: number;
     source: RulingSource;
-    reason?: 'disconnected_write' | 'invalid_request' | string;
+    /**
+     * Why the call was refused. `quota_exhausted`: the allowance is used up and the credits do not cover the overage
+     * (BLOCK, ALLOW_AND_BILL). `plan_upgrade_required`: the same under the PROMPT_UPGRADE policy, where the way on
+     * is a larger plan. Other values: `capability_not_found`, `capability_not_granted`, `disconnected_write`,
+     * `invalid_request`.
+     */
+    reason?: 'quota_exhausted' | 'plan_upgrade_required' | 'disconnected_write' | 'invalid_request' | string;
     adjudicated_at: number;
 }
 export interface AdjudicateOptions {
@@ -50,7 +56,59 @@ export interface SnapshotItem {
 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;
+    /**
+     * Credits that could still be spent when the entry was read: `wallet_balance` plus the overdraft limit, minus
+     * the credits held by open reservations. Informational, like `overdraft_limit`. Absent on instances that predate it.
+     */
+    available_credits?: 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`:
@@ -117,7 +175,7 @@ export interface ReserveOptions {
 }
 export interface ReservationResult {
     reservation_id: string;
-    status: 'PENDING' | 'CONFIRMED' | 'RELEASED' | 'RECLAIMED';
+    status: 'RESERVED' | 'CONFIRMED' | 'RELEASED';
     expires_at: string;
 }
 export interface ConfirmReservationResult {
@@ -150,11 +208,57 @@ export interface ShipRevClientOptions {
     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);
 }
+/** The `error.code` values of a refusal for funds, as the instance sends them and the two error types carry them. */
+export type FundsRefusalCode = 'QUOTA_EXHAUSTED' | 'PLAN_UPGRADE_REQUIRED';
+/** Where a funds refusal came from: the instance's HTTP answer (`status`, `request_id`) or a local ruling. */
+export interface FundsRefusalDetails {
+    /** HTTP status of the instance's answer (400); absent when the refusal is a local ruling. */
+    status?: number;
+    /** The instance's request id, for support; absent when the refusal is a local ruling. */
+    request_id?: string;
+}
+/**
+ * The allowance is used up and the credits do not cover the overage: the buyer can top up (BLOCK, ALLOW_AND_BILL
+ * past the overdraft limit, credits held by other reservations, or an overage that is not for sale). Thrown by
+ * `reserve()` when the instance answers `code: 'QUOTA_EXHAUSTED'`, and by `guardWrite()` when the local ruling is
+ * `quota_exhausted`. The type follows the code, never the message.
+ */
+export declare class QuotaExhaustedError extends Error {
+    readonly code: "QUOTA_EXHAUSTED";
+    readonly status?: number;
+    readonly request_id?: string;
+    constructor(message?: string, details?: FundsRefusalDetails);
+}
+/**
+ * The capability's policy is PROMPT_UPGRADE and the allowance is used up: the buyer has to move to a larger plan.
+ * Thrown by `reserve()` when the instance answers `code: 'PLAN_UPGRADE_REQUIRED'`, and by `guardWrite()` when the
+ * local ruling is `plan_upgrade_required`. The type follows the code, never the message.
+ */
+export declare class PlanUpgradeRequiredError extends Error {
+    readonly code: "PLAN_UPGRADE_REQUIRED";
+    readonly status?: number;
+    readonly request_id?: string;
+    constructor(message?: string, details?: FundsRefusalDetails);
+}
+/**
+ * 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. */

package/dist/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TokenRejectedError = exports.DisconnectedWriteError = void 0;
+exports.TokenRejectedError = exports.UsageDeliveryError = exports.PlanUpgradeRequiredError = exports.QuotaExhaustedError = exports.DisconnectedWriteError = void 0;
 class DisconnectedWriteError extends Error {
     reason = 'disconnected_write';
     constructor(message = 'Write operation denied while client is disconnected') {
@@ -9,6 +9,53 @@ class DisconnectedWriteError extends Error {
     }
 }
 exports.DisconnectedWriteError = DisconnectedWriteError;
+/**
+ * The allowance is used up and the credits do not cover the overage: the buyer can top up (BLOCK, ALLOW_AND_BILL
+ * past the overdraft limit, credits held by other reservations, or an overage that is not for sale). Thrown by
+ * `reserve()` when the instance answers `code: 'QUOTA_EXHAUSTED'`, and by `guardWrite()` when the local ruling is
+ * `quota_exhausted`. The type follows the code, never the message.
+ */
+class QuotaExhaustedError extends Error {
+    code = 'QUOTA_EXHAUSTED';
+    status;
+    request_id;
+    constructor(message = 'The allowance is used up and the credits do not cover the overage', details = {}) {
+        super(message);
+        this.name = 'QuotaExhaustedError';
+        this.status = details.status;
+        this.request_id = details.request_id;
+    }
+}
+exports.QuotaExhaustedError = QuotaExhaustedError;
+/**
+ * The capability's policy is PROMPT_UPGRADE and the allowance is used up: the buyer has to move to a larger plan.
+ * Thrown by `reserve()` when the instance answers `code: 'PLAN_UPGRADE_REQUIRED'`, and by `guardWrite()` when the
+ * local ruling is `plan_upgrade_required`. The type follows the code, never the message.
+ */
+class PlanUpgradeRequiredError extends Error {
+    code = 'PLAN_UPGRADE_REQUIRED';
+    status;
+    request_id;
+    constructor(message = 'The allowance is used up; the plan has to be upgraded', details = {}) {
+        super(message);
+        this.name = 'PlanUpgradeRequiredError';
+        this.status = details.status;
+        this.request_id = details.request_id;
+    }
+}
+exports.PlanUpgradeRequiredError = PlanUpgradeRequiredError;
+/**
+ * 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shiprev/server-sdk-node",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-beta.2",
   "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",
@@ -42,15 +42,6 @@
     "access": "public",
     "tag": "beta"
   },
-  "scripts": {
-    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "build": "tsc -p tsconfig.build.json",
-    "prepack": "pnpm run clean && pnpm run build",
-    "test": "jest",
-    "test:nest9": "node scripts/test-nest9.mjs",
-    "lint": "eslint \"src/**/*.ts\"",
-    "format": "prettier --write \"src/**/*.ts\""
-  },
   "peerDependencies": {
     "@nestjs/common": "^9.0.0 || ^10.0.0 || ^11.0.0",
     "@nestjs/core": "^9.0.0 || ^10.0.0 || ^11.0.0",
@@ -96,5 +87,13 @@
       "^.+\\.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\""
   }
-}
+}