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

package/README.md

@@ -69,18 +69,19 @@ A runnable version of this flow is the `examples/server-sdk-quickstart` example
 
 `createClient(options)` and `new ShipRevClient(options)` take the same `ShipRevClientOptions`:
 
-| Option                       | Default    | Meaning                                                                                              |
-| :--------------------------- | :--------- | :--------------------------------------------------------------------------------------------------- |
-| `base_url`                   | (required) | Base URL of the instance's core service; may include a path prefix. Trailing slashes are ignored     |
-| `api_key`                    | (required) | SDK-scoped API key of the application                                                                |
-| `presets.cold_start`         | `'deny'`   | Ruling for **reads** when the mirror is empty and the instance is unreachable: `'allow'` or `'deny'` |
-| `presets.connect_timeout_ms` | `5000`     | Timeout of every request to the instance                                                             |
-| `presets.reservation_ttl_s`  | (service)  | Default time-to-live of a reservation when `reserve()` does not pass one                             |
-| `buffer.batch_size`          | `100`      | Usage events sent per request; reaching it triggers a flush                                          |
-| `buffer.flush_interval_ms`   | `5000`     | Background flush interval. `0` disables the timer; the timer never keeps the process alive           |
-| `backlog`                    | memory     | Where usage waits while it cannot be delivered; see [Persistence modes](#persistence-modes)          |
-| `on_flush_failure`           |            | `(events, error) => void`, called when a batch could not be delivered (the events go to the backlog) |
-| `on_rejected`                |            | `(rejected) => void`, called with the events the service refused, each with a `reason`               |
+| Option                       | Default    | Meaning                                                                                                                                  |
+| :--------------------------- | :--------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
+| `base_url`                   | (required) | Base URL of the instance's core service; may include a path prefix. Trailing slashes are ignored                                         |
+| `api_key`                    | (required) | SDK-scoped API key of the application                                                                                                    |
+| `presets.cold_start`         | `'deny'`   | Ruling for **reads** when the mirror is empty and the instance is unreachable: `'allow'` or `'deny'`                                     |
+| `presets.connect_timeout_ms` | `5000`     | Timeout of every request to the instance                                                                                                 |
+| `presets.reservation_ttl_s`  | (service)  | Default time-to-live of a reservation when `reserve()` does not pass one                                                                 |
+| `buffer.batch_size`          | `100`      | Usage events sent per request; reaching it triggers a flush                                                                              |
+| `buffer.flush_interval_ms`   | `5000`     | Background flush interval. `0` disables the timer; the timer never keeps the process alive                                               |
+| `backlog`                    | memory     | Where usage waits while it cannot be delivered; see [Persistence modes](#persistence-modes)                                              |
+| `on_flush_failure`           |            | `(events, error) => void`, called when a batch could not be delivered (the events go to the backlog)                                     |
+| `on_rejected`                |            | `(rejected) => void`, called with the events the service refused, each with a `reason`                                                   |
+| `on_level_change`            |            | `(organization_id, level) => void`, called when an organization's effective level changes; see [Degradation levels](#degradation-levels) |
 
 ## NestJS
 
@@ -163,6 +164,8 @@ export class ReportsController {
 
 The expected issuer and application come from the service token the client obtains in `start()`; there is nothing to configure. Until the client has obtained one (never reached the instance), every token is refused with `not_ready`. Once known, the expectations are kept while the client is disconnected, and verification keeps working offline for every signing key already fetched. `TokenRejectedError` is exported from the main entry; its message never contains the token.
 
+A token whose `kid` is not among the cached signing keys triggers one refetch of the instance's keys, but not within 30 seconds of the last successful fetch: inside that window it is refused (`Unknown key ID`) without any request, so forged tokens with random key IDs cannot multiply your traffic into requests to the instance. A failed fetch does not start the window. After the instance rotates its signing key, tokens signed with the new key may therefore be refused for up to 30 seconds after the previous fetch.
+
 ## Rulings and `operation`
 
 Every ruling names its `operation`: `'read'` or `'write'`. It is required, because the two fail in opposite directions when the instance is unreachable: reads keep working from the last known entitlements, writes stop. Anything that consumes quota, changes state or costs money is a `write`. A missing or unknown `operation`, or a negative or non-finite `quantity`, is refused with `reason: 'invalid_request'`.
@@ -178,7 +181,7 @@ 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 only the `ALLOW_AND_BILL` overage policy allows locally; any other policy is refused with `reason: 'quota_exhausted'`. 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 (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).
 
 `guardWrite(options, action)` runs `action` only when a `write` ruling allows it, and otherwise throws `DisconnectedWriteError`.
 
@@ -228,6 +231,26 @@ Writes are refused whenever the push stream is down, even if other requests to t
 
 `setOnline(false)` closes the push stream and suspends reconnection until `setOnline(true)`, which sets `LIVE` at once and resumes; on a started client the next connection attempt then corrects the state. Both are for fault injection and tests. `loadSnapshot(snapshot)` seeds the mirror without the network (a `COLD_OFFLINE` client becomes `DISCONNECTED`).
 
+## Degradation levels
+
+Every organization entry of the snapshot carries two fields the instance computes: `degradation_level`, one of `NONE`, `RESTRICT_NEW`, `RESTRICT_USAGE`, `RESTRICT_READ` and `SUSPENDED` (strictly increasing), and `valid_until`, the time until which the entry may be used without a newer answer. An instance sets the level from its own rules (for example a buyer's unpaid invoices); at `SUSPENDED` the entry's `items` is empty, so nothing is granted. Instances that predate the fields leave them out.
+
+`effectiveLevel(organizationId)` combines them with the connection, synchronously and without I/O, into `{ level, source, expired }` (`undefined` when the mirror does not hold the organization):
+
+| The client observes                                    | `level`                                                | `source`     | `expired` |
+| :----------------------------------------------------- | :----------------------------------------------------- | :----------- | :-------- |
+| `LIVE` (the instance answers)                          | The entry's level                                      | `'answer'`   | `false`   |
+| Not `LIVE`, before the entry's `valid_until`           | The entry's level                                      | `'degraded'` | `false`   |
+| Not `LIVE`, at or after `valid_until` (or none usable) | The entry's level, raised to `RESTRICT_USAGE` at least | `'degraded'` | `true`    |
+
+A level the client does not know (another string, or not a string) reads as `RESTRICT_USAGE`, never looser. The level does not change `adjudicate()`, `adjudicateAsync()` or `guardWrite()`: a disconnected write is refused whatever the level; what a level blocks in your service is your decision.
+
+While `LIVE`, once half of an entry's validity has passed without a newer entry, the client pulls that organization once to renew it (never more than once per entry, never on a fixed period).
+
+`refresh(organizationId, { timeout_ms? })` pulls one organization now, sharing a pull already in flight for it, and resolves with the answer's level (`source: 'answer'`); when the pull fails or does not finish within `timeout_ms` (default `presets.connect_timeout_ms`) it resolves with `effectiveLevel()` as it stands. Use it before refusing an action on a level, so that a change at the instance applies within the action.
+
+`sendUsage(events)` sends one batch at once, outside the buffer and the backlog, and resolves with `{ accepted_count, duplicates_dropped, rejected }`. Quantities may be decimal strings, sent unchanged. It throws `UsageDeliveryError` when the batch did not get through (network error, timeout, `5xx`); any other refusal throws as it came. Sending the same batch again is safe, as events are deduplicated by `usage_event_id`. It is for callers that keep their own durable queue; everyone else uses `reportUsage()`.
+
 ## Persistence modes
 
 `backlog.mode` chooses where undeliverable usage waits:

package/dist/auth/token-verifier.d.ts

@@ -9,21 +9,35 @@ export interface TokenExpectations {
     projectId: string;
 }
 export declare function jwkToPem(jwk: JwksKey): string;
+/**
+ * After a successful JWKS fetch, a token with an unknown `kid` does not trigger another fetch for
+ * this long; it is refused instead. Without it, an anonymous caller could turn every forged token
+ * carrying a random `kid` into one request to the instance. A key rotated in during this window is
+ * accepted at most this long after the previous fetch.
+ */
+export declare const JWKS_REFRESH_COOLDOWN_MS = 30000;
 export declare class TokenVerifier {
     private readonly transport;
     private readonly publicKeyCache;
+    /** `Date.now()` of the last successful JWKS fetch; failed fetches do not set it. */
+    private lastRefreshAt;
+    private inFlightRefresh;
     constructor(transport: HttpTransport);
     /**
-     * Refreshes the local in-memory public key cache from the JWKS endpoint
+     * Refreshes the local in-memory public key cache from the JWKS endpoint. Always fetches (no
+     * cooldown); concurrent calls share one request. A success starts the unknown-`kid` cooldown.
      */
     refreshKeys(): Promise<void>;
+    private fetchKeys;
+    private inRefreshCooldown;
     /**
      * Directly caches a key in memory (e.g. for testing or preloading)
      */
     setPublicKey(kid: string, pem: string): void;
     /**
      * Verifies an RS256 JWT token locally, extracting the subject and isolation keys.
-     * If the kid is unknown in cache, it triggers a single JWKS refresh.
+     * If the kid is unknown in cache, it triggers a single JWKS refresh, unless the last successful
+     * refresh is less than `JWKS_REFRESH_COOLDOWN_MS` old, in which case the token is refused at once.
      *
      * With `expectations` (or `null`, meaning they are not known yet), the token must also be a buyer
      * session token of that issuer and application; the checks run after the signature, in the order

package/dist/auth/token-verifier.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TokenVerifier = void 0;
+exports.TokenVerifier = exports.JWKS_REFRESH_COOLDOWN_MS = void 0;
 exports.jwkToPem = jwkToPem;
 exports.expectationsFromMachineToken = expectationsFromMachineToken;
 exports.expiryOfToken = expiryOfToken;
@@ -59,21 +59,44 @@ function jwkToPem(jwk) {
     });
     return keyObj.export({ type: 'spki', format: 'pem' });
 }
+/**
+ * After a successful JWKS fetch, a token with an unknown `kid` does not trigger another fetch for
+ * this long; it is refused instead. Without it, an anonymous caller could turn every forged token
+ * carrying a random `kid` into one request to the instance. A key rotated in during this window is
+ * accepted at most this long after the previous fetch.
+ */
+exports.JWKS_REFRESH_COOLDOWN_MS = 30_000;
 class TokenVerifier {
     transport;
     publicKeyCache = new Map();
+    /** `Date.now()` of the last successful JWKS fetch; failed fetches do not set it. */
+    lastRefreshAt = null;
+    inFlightRefresh = null;
     constructor(transport) {
         this.transport = transport;
     }
     /**
-     * Refreshes the local in-memory public key cache from the JWKS endpoint
+     * Refreshes the local in-memory public key cache from the JWKS endpoint. Always fetches (no
+     * cooldown); concurrent calls share one request. A success starts the unknown-`kid` cooldown.
      */
     async refreshKeys() {
+        if (!this.inFlightRefresh) {
+            this.inFlightRefresh = this.fetchKeys().finally(() => {
+                this.inFlightRefresh = null;
+            });
+        }
+        return this.inFlightRefresh;
+    }
+    async fetchKeys() {
         const jwks = await this.transport.fetchJwks();
-        for (const key of jwks.keys) {
-            const pem = jwkToPem(key);
-            this.publicKeyCache.set(key.kid, pem);
+        const pems = jwks.keys.map((key) => [key.kid, jwkToPem(key)]);
+        for (const [kid, pem] of pems) {
+            this.publicKeyCache.set(kid, pem);
         }
+        this.lastRefreshAt = Date.now();
+    }
+    inRefreshCooldown() {
+        return this.lastRefreshAt !== null && Date.now() - this.lastRefreshAt < exports.JWKS_REFRESH_COOLDOWN_MS;
     }
     /**
      * Directly caches a key in memory (e.g. for testing or preloading)
@@ -83,7 +106,8 @@ class TokenVerifier {
     }
     /**
      * Verifies an RS256 JWT token locally, extracting the subject and isolation keys.
-     * If the kid is unknown in cache, it triggers a single JWKS refresh.
+     * If the kid is unknown in cache, it triggers a single JWKS refresh, unless the last successful
+     * refresh is less than `JWKS_REFRESH_COOLDOWN_MS` old, in which case the token is refused at once.
      *
      * With `expectations` (or `null`, meaning they are not known yet), the token must also be a buyer
      * session token of that issuer and application; the checks run after the signature, in the order
@@ -116,8 +140,11 @@ class TokenVerifier {
         }
         // Lookup public key from local cache
         let publicKeyPem = this.publicKeyCache.get(kid);
-        // Cache miss / key rotation: refresh keys once
+        // Cache miss / key rotation: refresh keys once, outside the cooldown only
         if (!publicKeyPem) {
+            if (this.inRefreshCooldown()) {
+                throw new Error(`Unknown key ID: kid=${kid}`);
+            }
             await this.refreshKeys();
             publicKeyPem = this.publicKeyCache.get(kid);
             if (!publicKeyPem) {

package/dist/client/connection-supervisor.d.ts

@@ -1,5 +1,6 @@
 import { EntitlementMirror } from '../mirror/entitlement-mirror';
 import { HttpTransport } from '../transport/http.transport';
+import { OrganizationSnapshot, Snapshot } from '../types';
 /**
  * Keeps a started client connected to its instance, from `start()` to `stop()`:
  *
@@ -12,7 +13,9 @@ import { HttpTransport } from '../transport/http.transport';
  *   new one is ready, without pulling; on an unplanned break reconnects once at once, then backs
  *   off (1, 2, 4, 8, 16, 30 s, ±20 %);
  * - turns `snapshot.changed` into per-organization refills (at most one in flight per organization)
- *   and `snapshot.resync` into a full pull. It never pulls on a timer.
+ *   and `snapshot.resync` into a full pull;
+ * - while online, renews an organization entry that carries `valid_until` once half of its validity has passed
+ *   without a newer entry, with one pull of that organization. It never pulls on a fixed period.
  *
  * Every timer is unref'd, so the supervisor never keeps the host process alive.
  */
@@ -31,6 +34,18 @@ export interface SupervisorHost {
     /** Delivers buffered and backlogged usage. */
     flush(): Promise<void>;
 }
+/**
+ * What one per-organization pull did to the mirror: `applied` (the answer's entry is now the mirror's entry),
+ * `removed` (the answer no longer holds the organization and the mirror dropped it), or `ignored` (the answer
+ * was not used: a newer entry was already held or arrived meanwhile, an unsupported schema, or the client was
+ * stopped or paused meanwhile). Only an applied or removed pull is an answer about the organization.
+ */
+export interface OrganizationPull {
+    envelope: Snapshot;
+    outcome: 'applied' | 'removed' | 'ignored';
+    /** The mirror's entry after an applied pull. */
+    entry?: OrganizationSnapshot;
+}
 export declare class ConnectionSupervisor {
     private readonly host;
     private token;
@@ -55,8 +70,13 @@ export declare class ConnectionSupervisor {
     private renewTimer;
     private reconnectTimer;
     private watchdogTimer;
+    private renewalTimer;
     private readonly refillTargets;
     private readonly refillsInFlight;
+    /** Per-organization pulls in flight, shared by refills, renewals and `refresh()`. */
+    private readonly organizationPulls;
+    /** Organizations whose last renewal pull failed, with the time a renewal may be tried again. */
+    private readonly renewalRetryAt;
     constructor(host: SupervisorHost);
     /** The machine token in use, or `null`. */
     currentToken(): string | null;
@@ -109,6 +129,17 @@ export declare class ConnectionSupervisor {
     private onChanged;
     /** Refills one organization until the mirror reaches the highest announced revision. */
     private refill;
+    /**
+     * One pull of one organization, shared by every concurrent caller, merged into the mirror (or removing the
+     * organization when the answer no longer holds it). A pull that finishes after `stop()` or `pause()` leaves
+     * the mirror as it is.
+     */
+    pullOrganization(organizationId: string): Promise<OrganizationPull>;
+    /** Re-arms the renewal timer for the earliest entry due; nothing while offline. Called on every mirror change. */
+    scheduleRenewals(): void;
+    /** Halfway between receiving an entry and its `valid_until`; undefined for an entry without a usable one. */
+    private renewalDue;
+    private renewDueEntries;
     /** Full pull: replaces the whole mirror. */
     private pull;
     /** Drops the stream, every timer and any attempt in flight. */

package/dist/client/connection-supervisor.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConnectionSupervisor = void 0;
 const token_verifier_1 = require("../auth/token-verifier");
+const degradation_1 = require("../mirror/degradation");
+const entitlement_mirror_1 = require("../mirror/entitlement-mirror");
 const event_stream_1 = require("../transport/event-stream");
 const http_transport_1 = require("../transport/http.transport");
 /** Retry interval while the instance refuses the API key (401 or 403 on the token exchange). */
@@ -9,6 +11,10 @@ const REFUSED_RETRY_MS = 30_000;
 const BACKOFF_STEPS_MS = [1_000, 2_000, 4_000, 8_000, 16_000, 30_000];
 const RENEW_AT = 0.8;
 const HEARTBEAT_TIMEOUT_FACTOR = 3;
+/** Shortest time between two renewals of the same entry. */
+const MIN_RENEWAL_SPACING_MS = 10_000;
+/** Wait before renewing an entry again after a renewal pull failed. */
+const RENEWAL_RETRY_MS = 30_000;
 function backoffDelay(step) {
     const base = BACKOFF_STEPS_MS[Math.min(step, BACKOFF_STEPS_MS.length - 1)];
     return Math.round(base * (0.8 + Math.random() * 0.4));
@@ -42,8 +48,13 @@ class ConnectionSupervisor {
     renewTimer = null;
     reconnectTimer = null;
     watchdogTimer = null;
+    renewalTimer = null;
     refillTargets = new Map();
     refillsInFlight = new Set();
+    /** Per-organization pulls in flight, shared by refills, renewals and `refresh()`. */
+    organizationPulls = new Map();
+    /** Organizations whose last renewal pull failed, with the time a renewal may be tried again. */
+    renewalRetryAt = new Map();
     constructor(host) {
         this.host = host;
     }
@@ -218,6 +229,7 @@ class ConnectionSupervisor {
         this.backoffStep = 0;
         this.host.setOnline(true);
         this.armWatchdog();
+        this.scheduleRenewals();
         if (flush) {
             void this.host.flush().catch(() => undefined);
         }
@@ -229,6 +241,7 @@ class ConnectionSupervisor {
             this.stream = null;
         }
         this.clearTimer('watchdogTimer');
+        this.clearTimer('renewalTimer');
         this.host.setOnline(false);
     }
     /** An unplanned break of the active stream: one immediate reconnect, still LIVE meanwhile. */
@@ -487,17 +500,17 @@ class ConnectionSupervisor {
         this.refillsInFlight.add(organizationId);
         try {
             for (;;) {
-                const envelope = await this.authorized((token) => this.host.transport.fetchSnapshot(token, organizationId));
+                const { envelope, outcome } = await this.pullOrganization(organizationId);
                 if (!this.running)
                     return;
-                if (envelope.organizations && organizationId in envelope.organizations) {
-                    this.host.mirror.mergeSnapshot(envelope);
-                }
-                else {
-                    this.host.mirror.removeOrganization(organizationId);
+                if (!envelope.organizations || !(organizationId in envelope.organizations)) {
                     this.refillTargets.delete(organizationId);
                     return;
                 }
+                // An answer the mirror did not take (stale or unsupported) is not asked again at once; the target
+                // stays for the next notification or full pull.
+                if (outcome === 'ignored')
+                    return;
                 const target = this.refillTargets.get(organizationId) ?? 0;
                 if ((this.host.mirror.getOrganizationRevision(organizationId) ?? 0) >= target) {
                     this.refillTargets.delete(organizationId);
@@ -512,6 +525,95 @@ class ConnectionSupervisor {
             this.refillsInFlight.delete(organizationId);
         }
     }
+    /**
+     * One pull of one organization, shared by every concurrent caller, merged into the mirror (or removing the
+     * organization when the answer no longer holds it). A pull that finishes after `stop()` or `pause()` leaves
+     * the mirror as it is.
+     */
+    pullOrganization(organizationId) {
+        const inFlight = this.organizationPulls.get(organizationId);
+        if (inFlight)
+            return inFlight;
+        const generation = this.generation;
+        const pull = (async () => {
+            const heldBefore = this.host.mirror.getOrganization(organizationId);
+            const envelope = await this.authorized((token) => this.host.transport.fetchSnapshot(token, organizationId));
+            const usable = generation === this.generation &&
+                typeof envelope?.schema_version === 'number' &&
+                envelope.schema_version <= entitlement_mirror_1.MAX_SUPPORTED_SCHEMA_VERSION;
+            if (!usable)
+                return { envelope, outcome: 'ignored' };
+            const answered = envelope.organizations?.[organizationId];
+            if (answered) {
+                this.host.mirror.mergeSnapshot(envelope);
+                const held = this.host.mirror.getOrganization(organizationId);
+                return held === answered ? { envelope, outcome: 'applied', entry: held } : { envelope, outcome: 'ignored' };
+            }
+            // Drop the organization only if the mirror still holds what it held when the pull started: a newer entry
+            // that arrived meanwhile is not removed by an older answer.
+            if (this.host.mirror.getOrganization(organizationId) !== heldBefore)
+                return { envelope, outcome: 'ignored' };
+            this.host.mirror.removeOrganization(organizationId);
+            return { envelope, outcome: 'removed' };
+        })();
+        this.organizationPulls.set(organizationId, pull);
+        const clear = () => {
+            if (this.organizationPulls.get(organizationId) === pull)
+                this.organizationPulls.delete(organizationId);
+        };
+        void pull.then(clear, clear);
+        return pull;
+    }
+    // ─── Renewal of entries with a validity ───────────────────────────────────
+    /** Re-arms the renewal timer for the earliest entry due; nothing while offline. Called on every mirror change. */
+    scheduleRenewals() {
+        this.clearTimer('renewalTimer');
+        if (!this.running || this.paused || !this.live)
+            return;
+        let next = Number.POSITIVE_INFINITY;
+        for (const organizationId of this.host.mirror.organizationIds()) {
+            const due = this.renewalDue(organizationId);
+            if (due !== undefined)
+                next = Math.min(next, due);
+        }
+        if (next === Number.POSITIVE_INFINITY)
+            return;
+        this.renewalTimer = unrefTimer(() => {
+            this.renewalTimer = null;
+            this.renewDueEntries();
+        }, next - Date.now());
+    }
+    /** Halfway between receiving an entry and its `valid_until`; undefined for an entry without a usable one. */
+    renewalDue(organizationId) {
+        const entry = this.host.mirror.getOrganization(organizationId);
+        const receivedAt = this.host.mirror.getReceivedAt(organizationId);
+        if (!entry || receivedAt === undefined)
+            return undefined;
+        const validUntil = (0, degradation_1.validUntilOf)(entry);
+        if (validUntil === undefined || validUntil <= receivedAt)
+            return undefined;
+        const due = Math.max(receivedAt + (validUntil - receivedAt) / 2, receivedAt + MIN_RENEWAL_SPACING_MS);
+        return Math.max(due, this.renewalRetryAt.get(organizationId) ?? 0);
+    }
+    renewDueEntries() {
+        if (!this.running || this.paused || !this.live)
+            return;
+        const now = Date.now();
+        for (const organizationId of this.host.mirror.organizationIds()) {
+            const due = this.renewalDue(organizationId);
+            if (due === undefined || due > now)
+                continue;
+            this.renewalRetryAt.set(organizationId, now + RENEWAL_RETRY_MS);
+            // The retry time set above stays unless the renewal was taken: a stale or unsupported answer does not
+            // move the entry's receipt time, and renewing it again at once would pull without end.
+            void this.pullOrganization(organizationId).then(({ outcome }) => {
+                if (outcome !== 'ignored')
+                    this.renewalRetryAt.delete(organizationId);
+                this.scheduleRenewals();
+            }, () => this.scheduleRenewals());
+        }
+        this.scheduleRenewals();
+    }
     /** Full pull: replaces the whole mirror. */
     async pull() {
         const snapshot = await this.authorized((token) => this.host.transport.fetchSnapshot(token));
@@ -535,6 +637,7 @@ class ConnectionSupervisor {
         this.clearTimer('renewTimer');
         this.clearTimer('reconnectTimer');
         this.clearTimer('watchdogTimer');
+        this.clearTimer('renewalTimer');
     }
     clearTimer(name) {
         const timer = this[name];

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

@@ -1,6 +1,6 @@
 import { UsageBuffer } from '../metering/usage-buffer';
 import { HttpTransport } from '../transport/http.transport';
-import { AdjudicateOptions, ClientState, ConfirmReservationResult, ReleaseReservationResult, ReservationResult, ReserveOptions, Ruling, ShipRevClientOptions, Snapshot, TokenClaims, UsageEventItem } from '../types';
+import { AdjudicateOptions, ClientState, ConfirmReservationResult, EffectiveLevel, ReleaseReservationResult, ReservationResult, ReserveOptions, Ruling, ShipRevClientOptions, Snapshot, TokenClaims, UsageEventItem, UsageSendEvent, UsageSendResult } from '../types';
 export declare class ShipRevClient {
     private readonly options;
     private readonly transport;
@@ -16,6 +16,10 @@ export declare class ShipRevClient {
     private expectations;
     /** Amounts reserved by this client, so `confirm()` without an amount confirms what was reserved. */
     private readonly reservedAmounts;
+    /** Effective levels last reported through `on_level_change`. */
+    private readonly reportedLevels;
+    /** Fires when the earliest `valid_until` passes while disconnected, to report the expiry. */
+    private expiryTimer;
     constructor(options: ShipRevClientOptions);
     /**
      * Connects the client: fetches the signing keys, exchanges the API key for a service token, opens
@@ -54,6 +58,30 @@ export declare class ShipRevClient {
      * If local mirror misses the organization or rule and client is online, queries core service and backfills mirror.
      */
     adjudicateAsync(options: AdjudicateOptions): Promise<Ruling>;
+    /**
+     * The effective degradation level of an organization: the level of the mirror entry while the instance
+     * answers; without an answer, the entry's level until its `valid_until`, then at least `RESTRICT_USAGE`
+     * (marked `expired`). `undefined` when the mirror does not hold the organization. Synchronous, no I/O.
+     *
+     * It does not change `adjudicate()` or `guardWrite()`: a disconnected write is refused whatever the level.
+     */
+    effectiveLevel(organizationId: string): EffectiveLevel | undefined;
+    /**
+     * Pulls one organization now (sharing a pull already in flight for it) and resolves with the level of the
+     * answer, `source: 'answer'`. When the pull fails or does not finish within `timeout_ms` (default: the
+     * connect timeout), resolves with `effectiveLevel()` as it stands. `undefined` when the instance no longer
+     * holds the organization, or the mirror never did.
+     */
+    refresh(organizationId: string, options?: {
+        timeout_ms?: number;
+    }): Promise<EffectiveLevel | undefined>;
+    /**
+     * Sends a batch of usage events at once, outside the buffer and the backlog, and resolves with what the
+     * instance did with each. A 401 renews the token once, as every request does. Throws `UsageDeliveryError`
+     * when the batch did not reach the instance or it failed to process it (network error, timeout, 5xx); any
+     * other refusal throws as it came. Sending the same batch again is safe: events are deduplicated by key.
+     */
+    sendUsage(events: UsageSendEvent[]): Promise<UsageSendResult>;
     /**
      * Guard for write operations (fail-closed).
      * Intercepts action if write operation is denied (e.g. disconnected).
@@ -101,6 +129,11 @@ export declare class ShipRevClient {
     getUsageBuffer(): UsageBuffer;
     getTransport(): HttpTransport;
     private applyOnline;
+    private onMirrorChange;
+    /** Reports every organization whose effective level differs from what was last reported. */
+    private notifyLevels;
+    /** While disconnected, wakes up when the earliest entry still valid expires, to report it. */
+    private armExpiryTimer;
     private learnExpectations;
     private refillOrganization;
 }

package/dist/client/shiprev-client.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ShipRevClient = void 0;
 const token_verifier_1 = require("../auth/token-verifier");
 const usage_buffer_1 = require("../metering/usage-buffer");
+const degradation_1 = require("../mirror/degradation");
 const entitlement_mirror_1 = require("../mirror/entitlement-mirror");
 const adjudicator_1 = require("../ruling/adjudicator");
 const http_transport_1 = require("../transport/http.transport");
@@ -23,6 +24,10 @@ class ShipRevClient {
     expectations = null;
     /** Amounts reserved by this client, so `confirm()` without an amount confirms what was reserved. */
     reservedAmounts = new Map();
+    /** Effective levels last reported through `on_level_change`. */
+    reportedLevels = new Map();
+    /** Fires when the earliest `valid_until` passes while disconnected, to report the expiry. */
+    expiryTimer = null;
     constructor(options) {
         this.options = options;
         this.transport = new http_transport_1.HttpTransport({
@@ -30,7 +35,7 @@ class ShipRevClient {
             connectTimeoutMs: options.presets?.connect_timeout_ms,
         });
         this.tokenVerifier = new token_verifier_1.TokenVerifier(this.transport);
-        this.mirror = new entitlement_mirror_1.EntitlementMirror();
+        this.mirror = new entitlement_mirror_1.EntitlementMirror((organizationIds) => this.onMirrorChange(organizationIds));
         this.adjudicator = new adjudicator_1.Adjudicator(this.mirror, options.presets);
         this.supervisor = new connection_supervisor_1.ConnectionSupervisor({
             transport: this.transport,
@@ -74,6 +79,10 @@ class ShipRevClient {
      */
     async stop() {
         this.supervisor.stop();
+        if (this.expiryTimer) {
+            clearTimeout(this.expiryTimer);
+            this.expiryTimer = null;
+        }
         await this.usageBuffer.stop();
         this.active = false;
         this.isOnline = false;
@@ -115,9 +124,11 @@ class ShipRevClient {
         if (ruling.allowed || ruling.source === 'degraded' || !this.isOnline) {
             return ruling;
         }
-        // When the mirror misses the organization or capability and the client is online, ask the
-        // service for an authoritative ruling, then refill that organization from the snapshot endpoint.
-        if (this.supervisor.currentToken() && ruling.reason === 'capability_not_granted') {
+        // 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';
+        if (this.supervisor.currentToken() && (ruling.reason === 'capability_not_granted' || beyondAllowance)) {
             try {
                 const remote = await this.supervisor.authorized((token) => this.transport.lookupAdjudication({
                     organization_id: options.organization_id,
@@ -144,6 +155,65 @@ class ShipRevClient {
         }
         return ruling;
     }
+    /**
+     * The effective degradation level of an organization: the level of the mirror entry while the instance
+     * answers; without an answer, the entry's level until its `valid_until`, then at least `RESTRICT_USAGE`
+     * (marked `expired`). `undefined` when the mirror does not hold the organization. Synchronous, no I/O.
+     *
+     * It does not change `adjudicate()` or `guardWrite()`: a disconnected write is refused whatever the level.
+     */
+    effectiveLevel(organizationId) {
+        const entry = this.mirror.getOrganization(organizationId);
+        return entry ? (0, degradation_1.combineLevel)(entry, this.isOnline, Date.now()) : undefined;
+    }
+    /**
+     * Pulls one organization now (sharing a pull already in flight for it) and resolves with the level of the
+     * answer, `source: 'answer'`. When the pull fails or does not finish within `timeout_ms` (default: the
+     * connect timeout), resolves with `effectiveLevel()` as it stands. `undefined` when the instance no longer
+     * holds the organization, or the mirror never did.
+     */
+    async refresh(organizationId, options) {
+        const timeoutMs = options?.timeout_ms ?? this.options.presets?.connect_timeout_ms ?? 5000;
+        let timer;
+        try {
+            const pulled = await Promise.race([
+                this.supervisor.pullOrganization(organizationId),
+                new Promise((_resolve, reject) => {
+                    timer = setTimeout(() => reject(new Error('refresh timed out')), timeoutMs);
+                    timer.unref();
+                }),
+            ]);
+            // Only an answer the mirror took is an answer; a stale or unsupported one leaves the level as it stands.
+            if (pulled.outcome === 'applied' && pulled.entry)
+                return (0, degradation_1.combineLevel)(pulled.entry, true, Date.now());
+            if (pulled.outcome === 'removed')
+                return undefined;
+            return this.effectiveLevel(organizationId);
+        }
+        catch {
+            return this.effectiveLevel(organizationId);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    /**
+     * Sends a batch of usage events at once, outside the buffer and the backlog, and resolves with what the
+     * instance did with each. A 401 renews the token once, as every request does. Throws `UsageDeliveryError`
+     * when the batch did not reach the instance or it failed to process it (network error, timeout, 5xx); any
+     * other refusal throws as it came. Sending the same batch again is safe: events are deduplicated by key.
+     */
+    async sendUsage(events) {
+        try {
+            return await this.supervisor.authorized((token) => this.transport.sendUsageEvents(events, token));
+        }
+        catch (error) {
+            if (error instanceof http_transport_1.HttpError && error.status < 500)
+                throw error;
+            throw new types_1.UsageDeliveryError(error instanceof Error ? error.message : 'Usage events could not be delivered');
+        }
+    }
     /**
      * Guard for write operations (fail-closed).
      * Intercepts action if write operation is denied (e.g. disconnected).
@@ -245,7 +315,70 @@ class ShipRevClient {
         return this.transport;
     }
     applyOnline(online) {
+        const changed = this.isOnline !== online;
         this.isOnline = online;
+        if (changed) {
+            this.notifyLevels(this.mirror.organizationIds());
+            this.armExpiryTimer();
+        }
+    }
+    onMirrorChange(organizationIds) {
+        if (organizationIds === null) {
+            // The whole mirror was replaced: organizations that left it are forgotten.
+            for (const organizationId of [...this.reportedLevels.keys()]) {
+                if (!this.mirror.hasOrganization(organizationId))
+                    this.reportedLevels.delete(organizationId);
+            }
+        }
+        this.notifyLevels(organizationIds ?? this.mirror.organizationIds());
+        this.armExpiryTimer();
+        this.supervisor?.scheduleRenewals();
+    }
+    /** Reports every organization whose effective level differs from what was last reported. */
+    notifyLevels(organizationIds) {
+        const listener = this.options.on_level_change;
+        if (!listener)
+            return;
+        for (const organizationId of organizationIds) {
+            const level = this.effectiveLevel(organizationId);
+            if (!level) {
+                this.reportedLevels.delete(organizationId);
+                continue;
+            }
+            if ((0, degradation_1.sameLevel)(level, this.reportedLevels.get(organizationId)))
+                continue;
+            this.reportedLevels.set(organizationId, level);
+            try {
+                listener(organizationId, level);
+            }
+            catch {
+                // A listener failure never reaches the connection.
+            }
+        }
+    }
+    /** While disconnected, wakes up when the earliest entry still valid expires, to report it. */
+    armExpiryTimer() {
+        if (this.expiryTimer) {
+            clearTimeout(this.expiryTimer);
+            this.expiryTimer = null;
+        }
+        if (!this.options.on_level_change || this.isOnline || !this.active)
+            return;
+        const now = Date.now();
+        let next = Number.POSITIVE_INFINITY;
+        for (const organizationId of this.mirror.organizationIds()) {
+            const validUntil = (0, degradation_1.validUntilOf)(this.mirror.getOrganization(organizationId));
+            if (validUntil !== undefined && validUntil > now)
+                next = Math.min(next, validUntil);
+        }
+        if (next === Number.POSITIVE_INFINITY)
+            return;
+        this.expiryTimer = setTimeout(() => {
+            this.expiryTimer = null;
+            this.notifyLevels(this.mirror.organizationIds());
+            this.armExpiryTimer();
+        }, next - now);
+        this.expiryTimer.unref();
     }
     learnExpectations(token) {
         const expectations = (0, token_verifier_1.expectationsFromMachineToken)(token);

package/dist/mirror/degradation.d.ts

@@ -0,0 +1,22 @@
+import { DegradationLevel, EffectiveLevel, OrganizationSnapshot } from '../types';
+/** The five levels in their strict order; each blocks what the one before it blocks, and more. */
+export declare const DEGRADATION_LEVELS: readonly DegradationLevel[];
+/** What a replica past its `valid_until` is tightened to, at least. */
+export declare const EXPIRED_FLOOR: DegradationLevel;
+/**
+ * The level an organization entry carries. Anything that is not one of the five values (missing, another
+ * string, not a string) is read as RESTRICT_USAGE: a level this client does not know is never read as looser.
+ */
+export declare function levelOf(entry: OrganizationSnapshot): DegradationLevel;
+/** `valid_until` in epoch milliseconds, or undefined when missing or unparsable (read as already expired). */
+export declare function validUntilOf(entry: OrganizationSnapshot): number | undefined;
+/**
+ * Combines an entry with what the client observes:
+ *
+ * - answered (online, or a pull of this organization just succeeded): the entry's level;
+ * - not answered and `now < valid_until`: the entry's level, marked degraded;
+ * - not answered and `now >= valid_until` (or no usable `valid_until`): at least RESTRICT_USAGE, marked expired.
+ */
+export declare function combineLevel(entry: OrganizationSnapshot, answered: boolean, now: number): EffectiveLevel;
+/** True when two effective levels are the same triple. */
+export declare function sameLevel(a: EffectiveLevel | undefined, b: EffectiveLevel | undefined): boolean;

package/dist/mirror/degradation.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXPIRED_FLOOR = exports.DEGRADATION_LEVELS = void 0;
+exports.levelOf = levelOf;
+exports.validUntilOf = validUntilOf;
+exports.combineLevel = combineLevel;
+exports.sameLevel = sameLevel;
+/** The five levels in their strict order; each blocks what the one before it blocks, and more. */
+exports.DEGRADATION_LEVELS = [
+    'NONE',
+    'RESTRICT_NEW',
+    'RESTRICT_USAGE',
+    'RESTRICT_READ',
+    'SUSPENDED',
+];
+/** What a replica past its `valid_until` is tightened to, at least. */
+exports.EXPIRED_FLOOR = 'RESTRICT_USAGE';
+function rank(level) {
+    return exports.DEGRADATION_LEVELS.indexOf(level);
+}
+/**
+ * The level an organization entry carries. Anything that is not one of the five values (missing, another
+ * string, not a string) is read as RESTRICT_USAGE: a level this client does not know is never read as looser.
+ */
+function levelOf(entry) {
+    const raw = entry.degradation_level;
+    return typeof raw === 'string' && exports.DEGRADATION_LEVELS.includes(raw)
+        ? raw
+        : exports.EXPIRED_FLOOR;
+}
+/** `valid_until` in epoch milliseconds, or undefined when missing or unparsable (read as already expired). */
+function validUntilOf(entry) {
+    const raw = entry.valid_until;
+    if (typeof raw !== 'string')
+        return undefined;
+    const at = Date.parse(raw);
+    return Number.isFinite(at) ? at : undefined;
+}
+/**
+ * Combines an entry with what the client observes:
+ *
+ * - answered (online, or a pull of this organization just succeeded): the entry's level;
+ * - not answered and `now < valid_until`: the entry's level, marked degraded;
+ * - not answered and `now >= valid_until` (or no usable `valid_until`): at least RESTRICT_USAGE, marked expired.
+ */
+function combineLevel(entry, answered, now) {
+    const level = levelOf(entry);
+    if (answered) {
+        return { level, source: 'answer', expired: false };
+    }
+    const validUntil = validUntilOf(entry);
+    if (validUntil !== undefined && now < validUntil) {
+        return { level, source: 'degraded', expired: false };
+    }
+    return {
+        level: rank(level) >= rank(exports.EXPIRED_FLOOR) ? level : exports.EXPIRED_FLOOR,
+        source: 'degraded',
+        expired: true,
+    };
+}
+/** True when two effective levels are the same triple. */
+function sameLevel(a, b) {
+    if (!a || !b)
+        return a === b;
+    return a.level === b.level && a.source === b.source && a.expired === b.expired;
+}
+//# sourceMappingURL=degradation.js.map

package/dist/mirror/entitlement-mirror.d.ts

@@ -1,14 +1,22 @@
-import { Snapshot, SnapshotItem } from '../types';
+import { OrganizationSnapshot, Snapshot, SnapshotItem } from '../types';
 export declare const MAX_SUPPORTED_SCHEMA_VERSION = 1;
 /**
  * In-memory replica of the application-level entitlement snapshot served by
  * `GET /sdk/v1/entitlements/snapshot`, indexed by organization and capability.
  */
 export declare class EntitlementMirror {
+    private readonly onChange?;
     private readonly organizations;
+    /** When each organization's entry was received (local clock). */
+    private readonly receivedAt;
     private currentSchemaVersion;
     private projectId;
     private lastUpdatedAt;
+    /**
+     * @param onChange called after the mirror changed: with the organizations whose entry was replaced or
+     *   removed, or with `null` when the whole mirror was replaced.
+     */
+    constructor(onChange?: ((organizationIds: string[] | null) => void) | undefined);
     /**
      * Replaces the mirror with an application-level snapshot envelope.
      * If schema_version is higher than supported, the update is rejected and the existing mirror is retained.
@@ -23,6 +31,12 @@ export declare class EntitlementMirror {
      * Removes an organization, for a refill whose envelope no longer holds it (unsubscribed or deleted).
      */
     removeOrganization(organizationId: string): void;
+    /** The entry of one organization, or `undefined` when the mirror does not hold it. */
+    getOrganization(organizationId: string): OrganizationSnapshot | undefined;
+    /** When the entry of one organization was received (local clock), or `undefined`. */
+    getReceivedAt(organizationId: string): number | undefined;
+    /** The organizations the mirror holds. */
+    organizationIds(): string[];
     /**
      * Revision of one organization, or `undefined` when the mirror does not hold it.
      */

package/dist/mirror/entitlement-mirror.js

@@ -7,10 +7,20 @@ exports.MAX_SUPPORTED_SCHEMA_VERSION = 1;
  * `GET /sdk/v1/entitlements/snapshot`, indexed by organization and capability.
  */
 class EntitlementMirror {
+    onChange;
     organizations = new Map();
+    /** When each organization's entry was received (local clock). */
+    receivedAt = new Map();
     currentSchemaVersion = exports.MAX_SUPPORTED_SCHEMA_VERSION;
     projectId = '';
     lastUpdatedAt = 0;
+    /**
+     * @param onChange called after the mirror changed: with the organizations whose entry was replaced or
+     *   removed, or with `null` when the whole mirror was replaced.
+     */
+    constructor(onChange) {
+        this.onChange = onChange;
+    }
     /**
      * Replaces the mirror with an application-level snapshot envelope.
      * If schema_version is higher than supported, the update is rejected and the existing mirror is retained.
@@ -19,13 +29,17 @@ class EntitlementMirror {
         if (!this.acceptsEnvelope(snapshot)) {
             return false;
         }
+        const now = Date.now();
         this.organizations.clear();
+        this.receivedAt.clear();
         this.projectId = snapshot.project_id;
         this.currentSchemaVersion = snapshot.schema_version;
         for (const [organizationId, organization] of Object.entries(snapshot.organizations ?? {})) {
             this.organizations.set(organizationId, organization);
+            this.receivedAt.set(organizationId, now);
         }
-        this.lastUpdatedAt = Date.now();
+        this.lastUpdatedAt = now;
+        this.onChange?.(null);
         return true;
     }
     /**
@@ -39,14 +53,20 @@ class EntitlementMirror {
         if (this.projectId && snapshot.project_id !== this.projectId) {
             return false;
         }
+        const now = Date.now();
+        const changed = [];
         this.projectId = snapshot.project_id;
         for (const [organizationId, organization] of Object.entries(snapshot.organizations ?? {})) {
             const known = this.organizations.get(organizationId);
             if (!known || organization.revision >= known.revision) {
                 this.organizations.set(organizationId, organization);
+                this.receivedAt.set(organizationId, now);
+                changed.push(organizationId);
             }
         }
-        this.lastUpdatedAt = Date.now();
+        this.lastUpdatedAt = now;
+        if (changed.length > 0)
+            this.onChange?.(changed);
         return true;
     }
     /**
@@ -54,9 +74,23 @@ class EntitlementMirror {
      */
     removeOrganization(organizationId) {
         if (this.organizations.delete(organizationId)) {
+            this.receivedAt.delete(organizationId);
             this.lastUpdatedAt = Date.now();
+            this.onChange?.([organizationId]);
         }
     }
+    /** The entry of one organization, or `undefined` when the mirror does not hold it. */
+    getOrganization(organizationId) {
+        return this.organizations.get(organizationId);
+    }
+    /** When the entry of one organization was received (local clock), or `undefined`. */
+    getReceivedAt(organizationId) {
+        return this.receivedAt.get(organizationId);
+    }
+    /** The organizations the mirror holds. */
+    organizationIds() {
+        return [...this.organizations.keys()];
+    }
     /**
      * Revision of one organization, or `undefined` when the mirror does not hold it.
      */

package/dist/ruling/adjudicator.js

@@ -86,17 +86,9 @@ class Adjudicator {
                     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,
-                };
-            }
+            // Beyond the remaining allowance the call is not decided here, whatever the policy: whether credits (and, for
+            // ALLOW_AND_BILL, an overdraft) cover it is state the mirror does not hold. The local answer is a refusal;
+            // adjudicateAsync() asks the service on it, and without an answer the call stays refused (fail closed).
             return {
                 allowed: false,
                 remaining: (0, decimal_1.decimalToNumber)(item.remaining),

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

@@ -1,4 +1,4 @@
-import { AdjudicationLookupRequest, AdjudicationLookupResponse, ConfirmReservationResult, JwksResponse, ReleaseReservationResult, ReservationResult, ReserveOptions, Snapshot, UsageEventItem, UsageEventsResponse } from '../types';
+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;
@@ -37,6 +37,11 @@ export declare class HttpTransport {
      * 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.
      */

package/dist/transport/http.transport.js

@@ -97,6 +97,26 @@ class HttpTransport {
             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.
      */
@@ -129,7 +149,7 @@ class HttpTransport {
         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,
+            status: body.status,
             expires_at: body.expires_at,
         };
     }

package/dist/types.d.ts

@@ -50,7 +50,54 @@ 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;
     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 +164,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 +197,25 @@ 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);
 }
+/**
+ * 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.DisconnectedWriteError = void 0;
 class DisconnectedWriteError extends Error {
     reason = 'disconnected_write';
     constructor(message = 'Write operation denied while client is disconnected') {
@@ -9,6 +9,18 @@ class DisconnectedWriteError extends Error {
     }
 }
 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.

package/package.json

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