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

package/README.md

@@ -181,9 +181,9 @@ A `Ruling` is `{ allowed, source, reason?, remaining?, limit?, adjudicated_at }`
 | `degraded`       | Offline, ruled from the last snapshot                                                            |
 | `client_default` | No basis for a ruling: invalid request, cold start offline, or online with nothing in the mirror |
 
-Online rulings from the mirror compare `quantity` exactly against the remaining allowance, which the snapshot carries as fixed-point decimal strings. Beyond the remaining allowance nothing is allowed locally, whatever the overage policy: whether credits (and, for `ALLOW_AND_BILL`, the wallet's overdraft limit) cover the write is state of the instance, so the local answer is a refusal with `reason: 'quota_exhausted'`, which `adjudicateAsync()` turns into a question to the instance and returns its ruling. When no ruling can be had the write stays refused. A capability the mirror does not hold is refused with `reason: 'capability_not_granted'` (which `adjudicateAsync()` turns into a question to the instance).
+Online rulings from the mirror compare `quantity` exactly against the remaining allowance, which the snapshot carries as fixed-point decimal strings. Beyond the remaining allowance nothing is allowed locally, whatever the overage policy: whether credits cover the write is state of the instance, so the local answer is a refusal with `reason: 'quota_exhausted'` (`'plan_upgrade_required'` when the capability's overage policy is `PROMPT_UPGRADE`; the instance's ruling uses the same two reasons), which `adjudicateAsync()` turns into a question to the instance and returns its ruling. When no ruling can be had the write stays refused. A capability the mirror does not hold is refused with `reason: 'capability_not_granted'` (which `adjudicateAsync()` turns into a question to the instance).
 
-`guardWrite(options, action)` runs `action` only when a `write` ruling allows it, and otherwise throws `DisconnectedWriteError`.
+`guardWrite(options, action)` runs `action` only when a `write` ruling allows it. A refusal with `reason: 'quota_exhausted'` throws `QuotaExhaustedError`, one with `reason: 'plan_upgrade_required'` throws `PlanUpgradeRequiredError`, and any other refusal (disconnected, a capability the mirror does not hold) throws `DisconnectedWriteError`. Both funds errors carry `code` (`'QUOTA_EXHAUSTED'`, `'PLAN_UPGRADE_REQUIRED'`).
 
 ## Usage reporting
 
@@ -203,7 +203,7 @@ Before sending the buffer, each flush first drains what is waiting in the backlo
 
 `await flush()` (and `await stop()`) resolves only when every event reported before the call has been accepted, refused (`on_rejected`), or moved to the backlog because it could not be delivered (offline, no service token, or a failed request; `on_flush_failure` is called for a failed buffer batch). If another flush is in flight, for example the one that follows a reconnection, the call waits for it and then makes its own pass. A flush started by `flush()` sends the whole backlog, batch by batch, stopping at the first failed batch; a timer tick skips while a flush is in flight and sends at most one backlog batch.
 
-For work whose cost is only known afterwards, reserve first and settle later: `reserve({ organization_id, capability_key, amount, ttl_seconds? })`, then `confirm(reservationId, actualAmount?)` (without an amount, the reserved amount is confirmed) or `release(reservationId)`. Reservations need a service token, which `start()` obtains; without one they throw.
+For work whose cost is only known afterwards, reserve first and settle later: `reserve({ organization_id, capability_key, amount, ttl_seconds? })`, then `confirm(reservationId, actualAmount?)` (without an amount, the reserved amount is confirmed) or `release(reservationId)`. Reservations need a service token, which `start()` obtains; without one they throw. A reservation refused for funds is HTTP `400` with `error.code` `QUOTA_EXHAUSTED` (credits short: offer a top-up) or `PLAN_UPGRADE_REQUIRED` (`PROMPT_UPGRADE` policy: offer a larger plan); `reserve()` throws `QuotaExhaustedError` or `PlanUpgradeRequiredError` accordingly, chosen by the code and never by the message, with `code`, `status` and `request_id`. It is not retried. Any other refusal throws as before.
 
 ## Connection
 

package/dist/client/shiprev-client.d.ts

@@ -83,8 +83,10 @@ export declare class ShipRevClient {
      */
     sendUsage(events: UsageSendEvent[]): Promise<UsageSendResult>;
     /**
-     * Guard for write operations (fail-closed).
-     * Intercepts action if write operation is denied (e.g. disconnected).
+     * Guard for write operations (fail-closed): runs `action` only when the local ruling allows the write.
+     * A refusal for funds throws `QuotaExhaustedError` (`quota_exhausted`) or `PlanUpgradeRequiredError`
+     * (`plan_upgrade_required`, PROMPT_UPGRADE); any other refusal, a disconnected write included, throws
+     * `DisconnectedWriteError` as before.
      */
     guardWrite<T>(options: Omit<AdjudicateOptions, 'operation'>, action: () => Promise<T> | T): Promise<T>;
     /**

package/dist/client/shiprev-client.js

@@ -127,7 +127,8 @@ class ShipRevClient {
         // Two cases are not decided by the mirror, and the service is asked for an authoritative ruling:
         // the mirror misses the organization or capability, or the write goes beyond the allowance the mirror
         // counts (credits and overdraft are the service's state). The mirror's refusal stands when no ruling comes.
-        const beyondAllowance = ruling.reason === 'quota_exhausted' && ruling.source === 'realtime';
+        const beyondAllowance = (ruling.reason === 'quota_exhausted' || ruling.reason === 'plan_upgrade_required') &&
+            ruling.source === 'realtime';
         if (this.supervisor.currentToken() && (ruling.reason === 'capability_not_granted' || beyondAllowance)) {
             try {
                 const remote = await this.supervisor.authorized((token) => this.transport.lookupAdjudication({
@@ -215,12 +216,18 @@ class ShipRevClient {
         }
     }
     /**
-     * Guard for write operations (fail-closed).
-     * Intercepts action if write operation is denied (e.g. disconnected).
+     * Guard for write operations (fail-closed): runs `action` only when the local ruling allows the write.
+     * A refusal for funds throws `QuotaExhaustedError` (`quota_exhausted`) or `PlanUpgradeRequiredError`
+     * (`plan_upgrade_required`, PROMPT_UPGRADE); any other refusal, a disconnected write included, throws
+     * `DisconnectedWriteError` as before.
      */
     async guardWrite(options, action) {
         const ruling = this.adjudicate({ ...options, operation: 'write' });
         if (!ruling.allowed) {
+            if (ruling.reason === 'quota_exhausted')
+                throw new types_1.QuotaExhaustedError();
+            if (ruling.reason === 'plan_upgrade_required')
+                throw new types_1.PlanUpgradeRequiredError();
             throw new types_1.DisconnectedWriteError(ruling.reason === 'disconnected_write'
                 ? 'Write operation denied while client is disconnected'
                 : `Write operation denied: ${ruling.reason ?? 'not allowed'}`);

package/dist/ruling/adjudicator.js

@@ -94,7 +94,8 @@ class Adjudicator {
                 remaining: (0, decimal_1.decimalToNumber)(item.remaining),
                 limit,
                 source: 'realtime',
-                reason: 'quota_exhausted',
+                // Under PROMPT_UPGRADE the way on is a larger plan, not more credits; the service rules the same way.
+                reason: item.overage_policy === 'PROMPT_UPGRADE' ? 'plan_upgrade_required' : 'quota_exhausted',
                 adjudicated_at: now,
             };
         }

package/dist/transport/http.transport.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpTransport = exports.HttpError = void 0;
 exports.isHttpStatus = isHttpStatus;
+const types_1 = require("../types");
 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 {
@@ -17,6 +18,25 @@ exports.HttpError = HttpError;
 function isHttpStatus(error, ...statuses) {
     return error instanceof HttpError && statuses.includes(error.status);
 }
+/**
+ * The typed error of a refusal for funds, read from `error.code` of the instance's error envelope; undefined for any
+ * other answer. Only the code decides: the message text is never parsed for meaning.
+ */
+function fundsRefusal(errorText, status, message) {
+    let error;
+    try {
+        error = JSON.parse(errorText)?.error;
+    }
+    catch {
+        return undefined;
+    }
+    const details = { status, request_id: typeof error?.request_id === 'string' ? error.request_id : undefined };
+    if (error?.code === 'QUOTA_EXHAUSTED')
+        return new types_1.QuotaExhaustedError(message, details);
+    if (error?.code === 'PLAN_UPGRADE_REQUIRED')
+        return new types_1.PlanUpgradeRequiredError(message, details);
+    return undefined;
+}
 class HttpTransport {
     baseUrl;
     timeoutMs;
@@ -205,7 +225,8 @@ class HttpTransport {
         });
         if (!response.ok) {
             const errorText = await response.text();
-            throw new HttpError(`${failure}: HTTP ${response.status} - ${errorText}`, response.status);
+            const message = `${failure}: HTTP ${response.status} - ${errorText}`;
+            throw fundsRefusal(errorText, response.status, message) ?? new HttpError(message, response.status);
         }
         return (await response.json());
     }

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 {
@@ -55,6 +61,11 @@ export interface OrganizationSnapshot {
      * 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
@@ -208,6 +219,38 @@ 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

package/dist/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TokenRejectedError = exports.UsageDeliveryError = 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,41 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shiprev/server-sdk-node",
-  "version": "0.1.0-beta.1",
+  "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",