ordainer 1.0.0 → 1.2.5

package/examples/express-server.js

@@ -0,0 +1,18 @@
+'use strict';
+// Quickstart example: one paid tool behind Ordainer.
+//   npm install express            (in your own project)
+//   ORDAINER_KEY=ord_test_... ORDAINER_BASE_URL=https://api.ordainer.dev node express-server.js
+//   curl -X POST localhost:3001/tools/research
+const express = require('express');
+const { Ordainer } = require('ordainer');
+
+const ordainer = new Ordainer(); // reads ORDAINER_KEY and ORDAINER_BASE_URL; mode follows the plan in the console
+
+const app = express();
+app.post('/tools/research', ordainer.middleware({ tool: 'research.run' }), (req, res) => {
+  // Only reached when Ordainer allows (or in shadow mode, or when Ordainer is unreachable).
+  res.json({ result: 'expensive research done', ordainer: req.ordainer.decision, remaining: req.ordainer.remaining });
+});
+
+const port = Number(process.env.PORT || 3001);
+app.listen(port, () => console.log(`vendor tool on http://localhost:${port}/tools/research`));

package/index.d.ts

@@ -0,0 +1,146 @@
+export type Mode = 'enforce' | 'shadow';
+export type FailMode = 'open' | 'closed';
+/** Billing-lapse setting (Terms 10.3(b)): what to do on 403 subscription_inactive. Separate from FailMode. Default 'open'. */
+export type BillingLapse = 'open' | 'closed';
+/** Quota-deny status: 429 Too Many Requests (default) or 402 Payment Required. Anything else throws at construction. */
+export type DenyStatus = 429 | 402;
+type Resolvable<T, A extends unknown[]> = T | ((...args: A) => T | Promise<T>);
+
+export interface DecideResult {
+  /** Run the tool? Accounts for mode, fail mode and the billing-lapse setting. */
+  allowed: boolean;
+  /** Ordainer's answer, or null if Ordainer could not answer. */
+  decision: 'allow' | 'deny' | null;
+  reason: string | null;
+  /** Allows left this period. null when the plan has no cap (D1) or Ordainer didn't answer: check before doing arithmetic. */
+  remaining: number | null;
+  /** The plan's cap for this period. null when the plan has no cap (D1) or Ordainer didn't answer. */
+  limit: number | null;
+  resetsAt: string | null;
+  requestId: string | null;
+  /** Effective mode ('shadow' never blocks). */
+  mode: Mode | null;
+  /** A shadow deny: Ordainer said deny, mode is 'shadow', and the call ran (allowed true). False on an enforce deny (allowed false; check decision === 'deny') and on an allow. Before 1.2.2 it was true on every deny. */
+  wouldDeny: boolean;
+  /** failMode 'open' let the call run without a decision: Ordainer couldn't answer (timeout, network error, 5xx, malformed 200). Never true for 403 subscription_inactive (see billingLapse). Never true together with failClosed or rejected. */
+  failOpen: boolean;
+  /** failMode 'closed' blocked the call because there was no decision: an outage (timeout, network error, 5xx, malformed 200; the block response is 503 ordainer_unavailable with Retry-After: 5). False for a rejected call and for the subscription_inactive lapse: failMode didn't decide those. */
+  failClosed: boolean;
+  /** Ordainer refused the call (any 4xx, except 403 subscription_inactive under billingLapse 'open'), or no agent key / tool was given. Blocked whatever failMode says; failClosed stays false. A retry won't fix it, so the block response is plan_check_rejected (403 with the neutral message for subscription_required or the lapse under billingLapse 'closed', 500 otherwise) with no Retry-After, except 429 rate_limited (see rateLimited). */
+  rejected: boolean;
+  /** The server answered from a stored decision for this idempotency key (header Idempotent-Replayed), not counted again. */
+  replayed: boolean;
+  /** Sticky deny: Ordainer couldn't answer (would fail open), but this (agent key, tool) got quota_exceeded within stickyDenyMs, so the call is denied (allowed false, reason 'quota_exceeded', 429 plan_limit_reached), or in shadow allowed and reported (wouldDeny). `error` says why there was no answer. */
+  stickyDeny: boolean;
+  /** The agent key's label (its name), sent by the API on denies only, cleaned and at most 64 characters. null on allows, errors, older servers, or unless exposeKeyLabel: true. Shown on the 429 plan_limit_reached body as error.label. The message does not include it. */
+  label: string | null;
+  /** HTTP attempts made (retries reuse the same idempotency key). 0 when no request was sent. */
+  attempts: number;
+  /** Ordainer answered 403 subscription_inactive (subscription inactive; follows billingLapse, Terms 10.3(b)) or subscription_required (never paid; always blocked): billing, not an outage. `reason` is that code. */
+  billingInactive: boolean;
+  /** The billing-lapse setting applied to a 403 subscription_inactive answer ('open': the call ran unchecked; 'closed': blocked, rejected true). null for every other answer. */
+  billingLapse: BillingLapse | null;
+  /** Ordainer denied with test_limit_reached: the account's free monthly test-key decisions are used up. Not an error. Enforce: blocked. Shadow (1.2.0; the server answers mode 'shadow'): the call runs as a would-deny (allowed true, wouldDeny true). */
+  testLimitReached: boolean;
+  /** 1.2.0: Ordainer answered 429 safety_limit_reached (shadow calls past the safety ceiling, 10x the account's monthly test limit). A safety limit, not a deny: the call RUNS in every failMode (allowed true, failOpen false, rejected false), unchecked and not recorded. error.limitScope 'org_safety'; resetsAt and retryAfterSec say when it ends (the start of next month, UTC). */
+  safetyLimited: boolean;
+  /** Ordainer answered 429 rate_limited (this agent key is over the per-key abuse limit; error.limitScope 'per_key') or 429 concurrency_limited (too many decides in flight at once for this key; error.limitScope 'per_key_concurrency', reason 'concurrency_limited'): a rate limit, not an outage. Blocked in any failMode; always warned. False for the per-address 429 too_many_failed_auth (a bad key: rejected, error.limitScope 'per_address'). */
+  rateLimited: boolean;
+  /** Seconds from the 429's Retry-After header when rateLimited or safetyLimited, else null. */
+  retryAfterSec: number | null;
+  /**
+   * Why there was no decision. `limitScope` only on a 429 (not `limit`: result.limit is the plan's cap): 'per_key' (rate_limited: this key is over its request rate),
+   * 'per_key_concurrency' (concurrency_limited: too many decides in flight at once for this key) or
+   * 'per_address' (too_many_failed_auth: too many missing/unknown keys from your server's address; never sent for a valid key) or
+   * 'org_safety' (safety_limit_reached: shadow calls past the safety ceiling; the call ran).
+   * `dnsCode` (1.2.0): 'ENOTFOUND' or 'EAI_AGAIN' on a network_error where the base URL's host didn't resolve.
+   */
+  error: { code: string; message: string; status?: number; limitScope?: 'per_key' | 'per_key_concurrency' | 'per_address' | 'org_safety'; dnsCode?: 'ENOTFOUND' | 'EAI_AGAIN' } | null;
+  /** HTTP status a blocked quota deny answers with: 429 (default) or 402. */
+  denyStatus: DenyStatus;
+  tool: string;
+  idempotencyKey: string;
+  latencyMs: number;
+}
+
+export interface OrdainerOptions {
+  apiKey?: Resolvable<string | undefined, any[]>;
+  baseUrl?: string;
+  timeoutMs?: number;
+  mode?: Mode;
+  /** Applies ONLY to timeouts, network errors, 5xx and malformed answers; a 4xx always blocks, except 403 subscription_inactive (billingLapse). Default 'open'. */
+  failMode?: FailMode;
+  /** Terms 10.3(b): on 403 subscription_inactive (your Ordainer subscription is inactive), 'open' (default) runs the call unchecked; 'closed' blocks it with 403 plan_check_rejected (no Retry-After, neutral message). Separate from failMode. */
+  billingLapse?: BillingLapse;
+  /** Extra attempts after a timeout, network error or 503, with the same idempotency key (0-5, default 1). 4xx and other 5xx are never retried. */
+  retries?: number;
+  /** Total time (ms) for all attempts of one decide(), default 650. A retry starts only with at least 50 ms left. */
+  retryBudgetMs?: number;
+  /** Sticky deny window (ms) after a quota_exceeded deny for an (agent key, tool): a would-be fail-open for that pair is denied (shadow: reported). Default 60000, 0 = off, max 300000. Ends early at the plan's reset or on an allow. */
+  stickyDenyMs?: number;
+  denyStatus?: DenyStatus;
+  /** Put the agent key's label on the 429 plan_limit_reached body (error.label) when the API sends it. The message does not include it. Default false (labels stay out of caller responses and result.label is null); set true to opt in. */
+  exposeKeyLabel?: boolean;
+  onDecision?: (result: DecideResult) => void | Promise<void>;
+  /** Called on every call answered 403 subscription_inactive (subscription inactive, under either billingLapse setting) OR 403 subscription_required (live key, no paid subscription yet); check result.error.code. The log warning is rate-limited; this hook is not. */
+  onBillingInactive?: (result: DecideResult) => void | Promise<void>;
+  /** Called on every call denied with test_limit_reached (not rate-limited). */
+  onTestLimit?: (result: DecideResult) => void | Promise<void>;
+  /** Called on every call answered 429 rate_limited (not rate-limited itself). */
+  onRateLimited?: (result: DecideResult) => void | Promise<void>;
+  /** 1.2.0: called on every call answered 429 safety_limit_reached (the call ran; not rate-limited itself). */
+  onSafetyLimit?: (result: DecideResult) => void | Promise<void>;
+  /** Minimum gap between log warnings of one kind (fail-open/closed per error code, billing, test limit, rate limit, safety limit). Default 60000. */
+  warningIntervalMs?: number;
+  /** @deprecated old name of warningIntervalMs */
+  billingWarningIntervalMs?: number;
+  /** Default console; false = silent. error() (if present, else warn()) gets the one-time "base URL host doesn't resolve" line (1.2.0). */
+  logger?: { warn(message: string): void; error?(message: string): void } | false;
+  fetch?: typeof fetch;
+}
+
+export interface CallOptions<A extends unknown[]> {
+  tool: Resolvable<string, A>;
+  apiKey?: Resolvable<string | undefined, A>;
+  /**
+   * From your own trusted data only, one key per real operation. Default: a fresh random key per call.
+   * The middleware never forwards the incoming request's Idempotency-Key header.
+   */
+  idempotencyKey?: Resolvable<string | undefined, A>;
+  mode?: Mode;
+  failMode?: FailMode;
+  billingLapse?: BillingLapse;
+  retries?: number;
+}
+
+export class Ordainer {
+  constructor(opts?: OrdainerOptions);
+  decide(opts: { tool: string; apiKey?: string; idempotencyKey?: string; mode?: Mode; failMode?: FailMode; billingLapse?: BillingLapse; retries?: number }): Promise<DecideResult>;
+  middleware(opts: CallOptions<[any]> & { denyStatus?: DenyStatus; onDeny?: (req: any, res: any, result: DecideResult) => void }): (req: any, res: any, next: (err?: unknown) => void) => void;
+  wrap<A extends unknown[], R>(fn: (...args: A) => R | Promise<R>, opts: CallOptions<A> & { onDeny?: (result: DecideResult, ...args: A) => R | Promise<R> }): (...args: A) => Promise<R>;
+}
+
+export class OrdainerDeniedError extends Error {
+  result: DecideResult;
+  status: number;
+  headers: Record<string, string>;
+  body: { error: { code: string; message: string; request_id: string | null; [k: string]: unknown } };
+}
+
+export function denyResponse(result: DecideResult): { status: number; headers: Record<string, string>; body: OrdainerDeniedError['body'] };
+export function sendDeny(res: any, result: DecideResult): void;
+export const DEFAULT_TIMEOUT_MS: number;
+export const BILLING_WARNING_INTERVAL_MS: number;
+export const TEST_LIMIT_REASON: 'test_limit_reached';
+export const SAFETY_LIMIT_CODE: 'safety_limit_reached';
+export const MAX_IDEMPOTENCY_LEN: 255;
+export const MAX_RETRIES: number;
+/** Longest agent label the SDK shows (characters); longer ones are cut and end with "…". */
+export const MAX_LABEL_LENGTH: 64;
+/** The cleaned label as the SDK shows it, or null. */
+export function safeKeyLabel(label: unknown): string | null;
+/** The neutral, Legal-approved message a blocked end user gets when the vendor's Ordainer billing blocks the call (Terms 10.3(b)). */
+export const BILLING_BLOCKED_MESSAGE: string;
+export function idempotencyKeyFor(tool: string, raw: string, opts?: { prefixTool?: boolean }): string;
+/** User-facing brand strings (working name; the rename sweep edits this one block). */
+export const BRAND: Readonly<{ name: string; baseUrl: string; envKey: string; envBaseUrl: string; logPrefix: string; userAgent: string; unavailableCode: string; rejectedCode: string }>;