Server SDK reference

This page lists what @shiprev/server-sdk-node exposes and the values it can return. For a walkthrough, start with Backend and the Server SDK.

Version

The current version is 0.1.0-beta.0, installed with the beta tag (npm install @shiprev/server-sdk-node@beta). It is a beta: the interface may change before 1.0. New versions are listed in the changelog. The Server SDK is published for Node.js only; it needs Node.js 20 or later.

The main entry never loads NestJS. The /nest entry needs @nestjs/common and @nestjs/core (9, 10 or 11) and reflect-metadata.

Options

createClient(options) and new ShipRevClient(options) take the same options. ShipRevModule.forRoot(options) takes them as well, and ShipRevModule.forRootAsync() builds them with a useFactory from other providers; both start the client in the background.

presets.cold_start

A cold start is a process that has not yet loaded anything from the region and cannot reach it. Writes are then always refused with disconnected_write. Reads follow presets.cold_start: with 'deny', the default, they are refused with cold_start_denied; with 'allow', they are allowed with source client_default. Choose 'allow' only for reads that may be served to anyone while your service is cut off.

const shiprev = createClient({
  base_url: process.env.SHIPREV_BASE_URL!,
  api_key: process.env.SHIPREV_API_KEY!,
  presets: { cold_start: 'allow' },
});

Client methods

loadSnapshot(), setOnline(), setM2MToken() and setPublicKey() exist for tests and fault injection; do not call them in production code.

adjudicate()

const ruling = shiprev.adjudicate({
  organization_id: claims.organization_id, // from the verified token only
  capability_key: 'report_exports',
  quantity: 1, // default 1; 0 checks that the capability is granted
  operation: 'write', // 'read' or 'write', required
});

operation is required: a ruling without 'read' or 'write', or with a negative or non-finite quantity, is refused with invalid_request. The organization must come from the verified session token, never from a header, parameter or body field the caller controls.

reportUsage()

await shiprev.reportUsage({
  usage_event_id: randomUUID(), // your unique ID; the region drops repeats
  organization_id: claims.organization_id,
  capability_key: 'report_exports',
  quantity: 1, // a finite number greater than 0
  occurred_at: new Date().toISOString(),
});

reportUsage() throws a RangeError for a quantity that is not a finite number. The event may also carry properties, an object kept with the event.

reserve(), confirm() and release()

For work whose cost is known only once it is done, reserve an amount first, then confirm what was used or release the reservation:

const reservation = await shiprev.reserve({
  organization_id: claims.organization_id,
  capability_key: 'report_exports',
  amount: 10, // what the work may use at most
  ttl_seconds: 300, // optional; default presets.reservation_ttl_s, then the region's default
});

try {
  const used = await runExport(); // your work
  await shiprev.confirm(reservation.reservation_id, used); // settles the amount actually used
} catch (error) {
  await shiprev.release(reservation.reservation_id); // gives the whole reservation back
  throw error;
}

confirm() without actualAmount confirms the amount that this client reserved; for a reservation made by another process, pass the amount. A refusal by the region, for example an allowance that cannot cover the amount, throws (see Errors).

Rulings

adjudicate() and adjudicateAsync() return a Ruling:

ruling.source

ruling.reason

remaining and limit

remaining and limit are present on rulings made from a capability the mirror or the region holds, and absent on refusals with disconnected_write, cold_start_denied, invalid_request and capability_not_granted. Every capability a plan grants has a numeric allowance; there is no unlimited allowance, so remaining is always a number when present. Beyond the allowance, a capability whose overage policy is allow and bill is allowed locally with remaining at 0; a capability that blocks, or prompts to upgrade, is refused with quota_exhausted.

Refused usage events

The region checks each usage event it receives. A refused event is not retried: it is passed to on_rejected, with usage_event_id and reason, and dropped from the buffer.

const shiprev = createClient({
  base_url: process.env.SHIPREV_BASE_URL!,
  api_key: process.env.SHIPREV_API_KEY!,
  on_rejected: (rejected) => {
    for (const event of rejected) logger.warn({ usage_event_id: event.usage_event_id, reason: event.reason }, 'usage refused');
  },
});

Most reasons point at a bug in the code that builds the event: log them, and fix the event rather than resending it. An event sent again with the same usage_event_id after it was accepted is counted once.

The backlog

While the region is unreachable, the events of a failed send move into a backlog, and the first send back online delivers the backlog before new events.

BacklogAdapter

For 'host_adapter', implement this interface on a store all your replicas share, for example Redis or your database:

import type { BacklogAdapter, BacklogItem, UsageEventItem } from '@shiprev/server-sdk-node';

export interface BacklogAdapter {
  /** Store one event that could not be delivered. */
  enqueue(event: UsageEventItem): Promise<void>;
  /** Return up to `limit` of the oldest stored items, without removing them. */
  peek(limit: number): Promise<BacklogItem[]>;
  /** Remove the items with these IDs: they were delivered or refused. */
  ack(ids: string[]): Promise<void>;
  /** Keep the items with these IDs for a later attempt, and count one more attempt on each. */
  nack(ids: string[]): Promise<void>;
  /** How many items are stored. */
  size(): Promise<number>;
}

// One stored event: the ID is yours to assign in enqueue().
interface BacklogItemShape {
  id: string;
  event: UsageEventItem;
  enqueued_at: number; // milliseconds since the epoch
  attempts: number;
}

peek() must return items oldest first, and ack() and nack() receive IDs that peek() returned. Every event carries its usage_event_id, so an event delivered twice because of a crash between delivery and ack() is counted once.

const shiprev = createClient({
  base_url: process.env.SHIPREV_BASE_URL!,
  api_key: process.env.SHIPREV_API_KEY!,
  backlog: { mode: 'host_adapter', adapter: new RedisBacklog(redis) }, // your implementation
});

Client state

state() returns { state, snapshot_revision, last_sync_at }, and is meant for your health endpoint:

{ "state": "LIVE", "snapshot_revision": 42, "last_sync_at": 1767225600000 }

snapshot_revision is the revision of the mirror; last_sync_at is the time of its last update in milliseconds since the epoch, absent before the first one.

The push stream is the only online signal. The client renews its service token before it expires and once on any 401, and reconnects with backoff (1, 2, 4, 8 and 16 seconds, then every 30 seconds). Back online, it reloads the whole snapshot and delivers the backlog before new events. Its timers never keep your process alive.

Session tokens

verifyToken() resolves to TokenClaims: account_id, organization_id, project_id, tenant_id, key_version, scope, exp, and the standard claims iat, iss, sub and aud when the token carries them. Rule and report with organization_id from these claims.

TokenRejectedError.reason

A correctly signed, unexpired token that this client does not accept throws TokenRejectedError. Its message names the reason and never contains the token.

NestJS bindings

• ShipRevModule.forRoot(options) and ShipRevModule.forRootAsync() register one global client and start it in the background, so your service boots even while the region is unreachable.
• ShipRevAuthGuard reads Authorization: Bearer <session token>, verifies it with verifyToken(), and puts the claims on the request as authClaims. Any failure is a 401.
• ShipRevCapabilityGuard rules with adjudicateAsync() on what RequireCapability() names, for the organization in the verified claims only, and puts the ruling on the request as ruling. A refusal is a 403; claims without an organization are a 403 before any ruling. A route without RequireCapability() passes this guard.
• RequireCapability(capabilityKey, operation, quantity): operation defaults to 'read' and quantity to 1. Name 'write' for anything that consumes quota, changes state or costs money.
• InjectShipRevClient() injects the client.

Errors

Treat every failure of verifyToken() as a 401. The error codes the region can return are listed in Error codes.