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

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,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 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 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
 
@@ -200,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
 
@@ -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
@@ -55,8 +59,34 @@ export declare class ShipRevClient {
      */
     adjudicateAsync(options: AdjudicateOptions): Promise<Ruling>;
     /**
-     * Guard for write operations (fail-closed).
-     * Intercepts action if write operation is denied (e.g. disconnected).
+     * 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): 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>;
     /**
@@ -101,6 +131,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;
 }