@clocknext/sdk 0.11.0 → 0.12.1

package/examples/node-basic.ts

@@ -0,0 +1,93 @@
+/**
+ * Basic usage: record a few signals from a long-lived Node process.
+ * Run with: CLOCKNEXT_API_KEY=cnk_… npx tsx examples/node-basic.ts
+ *
+ * Note the discovery step first. `customerId`, `model` and `agentKey` are not
+ * strings you can invent — they name rows that must already exist in your
+ * workspace, and a signal naming one that does not is rejected. So this example
+ * reads them out of the API rather than hard-coding placeholders that are
+ * guaranteed to 422 on someone else's workspace.
+ */
+import { ClockNext } from "@clocknext/sdk";
+
+const cnk = new ClockNext({
+  apiKey: process.env.CLOCKNEXT_API_KEY!,
+  // baseUrl: "http://localhost:3000", // point at local dev if needed
+  onError: (err, signal) =>
+    console.error("[clocknext] signal failed:", signal?.type, err),
+});
+
+async function main() {
+  // 0. Ground the integration. Check WHICH workspace this key points at before
+  //    sending anything — a live key bills for real.
+  const { organization } = await cnk.workspace.me();
+  console.log(`workspace: ${organization.name} (${organization.environment})`);
+
+  // 1. Discover real ids instead of guessing them.
+  const [models, credits, customers] = await Promise.all([
+    cnk.workspace.models({ active: true }),
+    cnk.credits.list({ active: true }),
+    cnk.customers.list({ limit: 1 }),
+  ]);
+
+  const model = models[0];
+  const credit = credits[0];
+  const customer = customers.customers[0];
+  if (!model || !credit || !customer) {
+    throw new Error(
+      "This workspace needs at least one enabled model, one credit type, and one customer before it can meter anything.",
+    );
+  }
+  console.log(`metering ${credit.agentKey} on ${model.modelId}`);
+
+  // 2. Credit usage — metered against a credit by its stable `agentKey`, priced
+  //    by tokens. Optionally group it into a composite occurrence, billed once
+  //    on close.
+  await cnk.signals.credit({
+    customerId: customer.id,
+    model: model.modelId,
+    agentKey: credit.agentKey,
+    tokens: { input: 1200, output: 340, cache: 0 },
+    custom: { feature: "summarize", tier: "pro" },
+  });
+
+  // 3. Wallet usage (debits the customer's USD wallet at model cost).
+  await cnk.signals.wallet({
+    customerId: customer.id,
+    model: model.modelId,
+    tokens: { input: 800, output: 5000 },
+  });
+
+  // 4. Outcome run — every step shares a `runId`; mark the last one `complete`
+  //    to bill the run. `agentKey` is the OutcomeStep's key, which you read off
+  //    `cnk.outcomes.list()` the same way.
+  // `outcomes.list()` returns catalogue rows WITHOUT their steps; the step
+  // agent keys — which is what a signal reports against — are on the detail.
+  const outcomeRow = (await cnk.outcomes.list({ active: true }))[0];
+  const outcome = outcomeRow ? await cnk.outcomes.get(outcomeRow.id) : undefined;
+  if (outcome?.steps[0]) {
+    const runId = `demo_run_${Date.now()}`;
+    await cnk.signals.outcome({
+      customerId: customer.id,
+      model: model.modelId,
+      agentKey: outcome.steps[0].agentKey,
+      runId,
+      complete: true, // closes the RUN; a composite still needs its own close
+      tokens: { input: 600, output: 150 },
+    });
+  }
+
+  // 5. Flush the background buffer, then read the signals back. Ingestion is
+  //    asynchronous, so this — not the track() return value — is what proves a
+  //    signal actually landed.
+  await cnk.flush();
+  const usage = await cnk.signals.list({ customerId: customer.id, limit: 10 });
+  console.log("recent logs:", usage.logs.length, "totals:", usage.totals);
+
+  await cnk.close();
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/serverless-flush.ts

@@ -0,0 +1,47 @@
+/**
+ * Serverless (Vercel / AWS Lambda): the process can freeze the instant the
+ * handler returns, so you MUST await a flush before responding — otherwise
+ * buffered signals are lost. Either construct the client in `sync` mode, or
+ * (better for throughput) buffer and `await cnk.flush()` at the end.
+ */
+import { ClockNext } from "@clocknext/sdk";
+
+// Construct ONCE at module scope so the client is reused across warm
+// invocations; a per-request client buffers into an instance that is thrown
+// away before the timer ever fires.
+const cnk = new ClockNext({
+  apiKey: process.env.CLOCKNEXT_API_KEY!,
+  // In a serverless runtime a dropped signal is invisible unless you log it —
+  // there is no console to watch after the function freezes.
+  onError: (err, signal) =>
+    console.error("[clocknext] signal failed", { type: signal?.type, err }),
+});
+
+export async function handler(req: {
+  customerId: string;
+  model: string;
+  agentKey: string;
+  requestId: string;
+  tokens: { input: number; output: number };
+}) {
+  // ... do the LLM call, then record usage without blocking the hot path ...
+  await cnk.signals.credit({
+    customerId: req.customerId,
+    model: req.model,
+    agentKey: req.agentKey,
+    tokens: req.tokens,
+    // A stable key tied to the logical event. The SDK generates one anyway, but
+    // an auto key lives in memory — it cannot dedup a retry of the whole
+    // invocation, which is exactly what a serverless platform does on failure.
+    idempotencyKey: `req:${req.requestId}`,
+  });
+
+  // CRITICAL in serverless: drain the buffer before the function returns. Put
+  // it in a `finally` so an error on the path above still flushes what was
+  // already metered.
+  try {
+    return { ok: true };
+  } finally {
+    await cnk.flush();
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clocknext/sdk",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "Official ClockNext SDK — record usage signals and manage plans, purchases, invoices, customers, and billing from your backend.",
   "license": "MIT",
   "type": "module",
@@ -21,6 +21,8 @@
   },
   "files": [
     "dist",
+    "src",
+    "examples",
     "README.md"
   ],
   "engines": {

package/src/client.ts

@@ -0,0 +1,107 @@
+import { resolveConfig } from "./config.js";
+import { Flusher } from "./flusher.js";
+import { Transport } from "./http.js";
+import { Composites } from "./resources/composites.js";
+import { Credits } from "./resources/credits.js";
+import { Customers } from "./resources/customers.js";
+import { Invoices } from "./resources/invoices.js";
+import { Outcomes } from "./resources/outcomes.js";
+import { Payments } from "./resources/payments.js";
+import { Plans } from "./resources/plans.js";
+import { Portal } from "./resources/portal.js";
+import { Purchases } from "./resources/purchases.js";
+import { Signals } from "./resources/signals.js";
+import { Units } from "./resources/units.js";
+import { Webhooks } from "./resources/webhooks.js";
+import { Workspace } from "./resources/workspace.js";
+import type { ClockNextConfig, ResolvedConfig } from "./types.js";
+
+/**
+ * The ClockNext client.
+ *
+ * ```ts
+ * const cnk = new ClockNext({ apiKey: process.env.CLOCKNEXT_API_KEY! });
+ *
+ * await cnk.signals.credit({
+ *   customerId: "cus_123",
+ *   model: "gpt-4o",          // catalog model id
+ *   agentKey: "api_credit",   // the credit's stable agent key
+ *   tokens: { input: 1200, output: 340 },
+ * });
+ *
+ * // before a serverless function returns / on shutdown:
+ * await cnk.flush();
+ * ```
+ */
+export class ClockNext {
+  /** Record + read usage signals (credit / wallet / outcome / unit). */
+  readonly signals: Signals;
+  /** Manage customers, their members, wallet, and balances. */
+  readonly customers: Customers;
+  /** Define and manage billing plans. */
+  readonly plans: Plans;
+  /** Subscribe customers to plans (purchases). */
+  readonly purchases: Purchases;
+  /** Read invoices and mint hosted pay links. */
+  readonly invoices: Invoices;
+  /** Read payments (paid invoices). */
+  readonly payments: Payments;
+  /** Manage the credit-type catalog. */
+  readonly credits: Credits;
+  /** Manage the composite catalog — bundles billed as one thing. */
+  readonly composites: Composites;
+  /** Manage the outcome-type catalog. */
+  readonly outcomes: Outcomes;
+  /** Manage the unit-type catalog. */
+  readonly units: Units;
+  /** Configure threshold webhooks. */
+  readonly webhooks: Webhooks;
+  /** Mint customer-portal embed tokens. */
+  readonly portal: Portal;
+  /** Identify the workspace (sandbox/live) + list its models. `/me`, `/models`. */
+  readonly workspace: Workspace;
+
+  private readonly cfg: ResolvedConfig;
+  private readonly flusher: Flusher;
+
+  constructor(config: ClockNextConfig) {
+    this.cfg = resolveConfig(config);
+
+    if (typeof window !== "undefined") {
+      this.cfg.logger.warn?.(
+        "[clocknext] Running in a browser exposes your secret API key. Use this SDK only on a server/backend.",
+      );
+    }
+
+    const transport = new Transport(this.cfg);
+    this.flusher = new Flusher(transport, this.cfg);
+    this.signals = new Signals(transport, this.flusher, this.cfg);
+    this.customers = new Customers(transport);
+    this.plans = new Plans(transport);
+    this.purchases = new Purchases(transport);
+    this.invoices = new Invoices(transport);
+    this.payments = new Payments(transport);
+    this.credits = new Credits(transport);
+    this.composites = new Composites(transport);
+    this.outcomes = new Outcomes(transport);
+    this.units = new Units(transport);
+    this.webhooks = new Webhooks(transport);
+    this.portal = new Portal(transport);
+    this.workspace = new Workspace(transport);
+  }
+
+  /** Number of signals currently buffered (async mode). */
+  get pending(): number {
+    return this.flusher.size;
+  }
+
+  /** Force-send all buffered signals now. Await before a serverless return. */
+  flush(): Promise<void> {
+    return this.flusher.flush();
+  }
+
+  /** Flush and stop the background timer. Call on graceful shutdown. */
+  close(): Promise<void> {
+    return this.flusher.close();
+  }
+}

package/src/config.ts

@@ -0,0 +1,116 @@
+import { ValidationError } from "./errors.js";
+import type {
+  ClockNextConfig,
+  DropReason,
+  FetchLike,
+  ResolvedConfig,
+  Signal,
+} from "./types.js";
+
+const DEFAULT_BASE_URL = "https://payments.clocknext.com";
+
+/**
+ * Default failure reporters.
+ *
+ * In the default `async` mode a signal is sent by the background flusher, long
+ * after `signals.credit()` resolved `{ status: "buffered" }`. There is no
+ * promise left to reject into, so a failed REQUEST — a bad API key, an
+ * unreachable host, a timeout — has nowhere to surface except these hooks.
+ *
+ * They do not cover a signal the server accepted (`202`) and then refused while
+ * pricing it: that request succeeded as far as this SDK can tell. Those
+ * rejections are recorded on the workspace's signal log in the ClockNext
+ * dashboard, which is owner-only by design.
+ *
+ * They used to default to nothing at all, which meant a misconfigured
+ * integration compiled, ran, returned success-shaped results, and metered
+ * NOTHING, with not one line of output to say so. A billing client whose
+ * default is silent data loss has its defaults inverted, so failures are now
+ * reported on `console.error` unless the caller takes ownership by supplying
+ * their own hook.
+ *
+ * Pass `onError: () => {}` to silence them deliberately.
+ */
+function defaultOnError(error: unknown, signal?: Signal): void {
+  const what = signal ? `${signal.type} signal` : "request";
+  const who = signal ? ` customer=${signal.customerId}` : "";
+  const key =
+    signal?.idempotencyKey != null
+      ? ` idempotencyKey=${signal.idempotencyKey}`
+      : "";
+  console.error(
+    `[clocknext] ${what} permanently failed and was NOT recorded.${who}${key}`,
+    error,
+  );
+  console.error(
+    "[clocknext] Pass `onError` to handle this yourself, or `onError: () => {}` to silence it.",
+  );
+}
+
+/** Drops that never reach `onError` — nothing was sent, so there is no send
+ *  failure to report. `send_failed` is skipped here because the error hook has
+ *  already reported it. */
+function defaultOnDrop(signal: Signal, reason: DropReason): void {
+  if (reason === "send_failed") return;
+  const why =
+    reason === "queue_full"
+      ? "the local queue is full — raise `batch.maxQueueSize` or flush more often"
+      : "the client is closed — this signal was tracked after `close()`";
+  console.error(
+    `[clocknext] dropped a ${signal.type} signal without sending it: ${why}.`,
+    `customer=${signal.customerId}`,
+  );
+}
+
+/** Use `value` only if it's a finite number `>= min`; otherwise fall back. */
+function num(value: number | undefined, fallback: number, min: number): number {
+  return typeof value === "number" && Number.isFinite(value) && value >= min
+    ? value
+    : fallback;
+}
+
+/** Applies defaults and validates required config. */
+export function resolveConfig(config: ClockNextConfig): ResolvedConfig {
+  if (!config.apiKey || typeof config.apiKey !== "string") {
+    // A ClockNextError, not a bare Error: a caller wrapping setup in
+    // `catch (e) { if (e instanceof ClockNextError) … }` should not have this
+    // one class of failure escape the net.
+    throw new ValidationError("ClockNext: `apiKey` is required.");
+  }
+
+  const fetchImpl: FetchLike | undefined =
+    config.fetch ??
+    (typeof globalThis.fetch === "function"
+      ? (globalThis.fetch.bind(globalThis) as FetchLike)
+      : undefined);
+  if (!fetchImpl) {
+    throw new ValidationError(
+      "ClockNext: no global `fetch` found. Use Node 18+, or pass a `fetch` implementation.",
+    );
+  }
+
+  return {
+    apiKey: config.apiKey,
+    baseUrl: (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ""),
+    mode: config.mode ?? "async",
+    timeoutMs: num(config.timeoutMs, 10_000, 1),
+    batch: {
+      maxSize: num(config.batch?.maxSize, 20, 1),
+      maxIntervalMs: num(config.batch?.maxIntervalMs, 2000, 0),
+      maxConcurrency: num(config.batch?.maxConcurrency, 5, 1),
+      maxQueueSize: num(config.batch?.maxQueueSize, 10_000, 1),
+    },
+    retry: {
+      maxAttempts: num(config.retry?.maxAttempts, 5, 1),
+      baseDelayMs: num(config.retry?.baseDelayMs, 200, 0),
+      maxDelayMs: num(config.retry?.maxDelayMs, 10_000, 0),
+    },
+    fetch: fetchImpl,
+    logger: config.logger ?? {},
+    // Both default to loud. See the note above `defaultOnError`.
+    onError: config.onError ?? defaultOnError,
+    onFlush: config.onFlush,
+    onRetry: config.onRetry,
+    onDrop: config.onDrop ?? defaultOnDrop,
+  };
+}

package/src/errors.ts

@@ -0,0 +1,215 @@
+/**
+ * Typed error hierarchy. The server returns `{ statusCode, statusDetail, result }`
+ * with a meaningful HTTP status; we map that status to a class so callers can
+ * branch on the *kind* of failure (e.g. allowance exhausted ⇒ upsell; network ⇒
+ * ignore, it's queued) rather than string-matching messages.
+ */
+
+/** Machine-readable failure code, when the server sends one
+ *  (`statusDetail.code`). Preferred over any message heuristic. */
+export type ClockNextErrorCode =
+  | "ALLOWANCE_EXHAUSTED"
+  | "PLAN_REJECTED"
+  | "IDEMPOTENCY_UNRESOLVED"
+  | (string & {});
+
+export class ClockNextError extends Error {
+  /** HTTP status, when the failure came from a server response. */
+  readonly status?: number;
+  /** Whether the SDK considers this failure worth retrying. */
+  readonly retryable: boolean;
+  /**
+   * The server's machine-readable code, when it sent one. Branch on this in
+   * preference to `.message`, which is human copy and may be reworded.
+   */
+  readonly code?: ClockNextErrorCode;
+  /**
+   * The idempotency key of the request that failed, for metering calls.
+   *
+   * This is what makes a dead-letter retry safe: re-send the failed signal with
+   * this SAME key and the server deduplicates it instead of billing twice. A
+   * fresh key would double-bill, so never generate one when replaying.
+   */
+  readonly idempotencyKey?: string;
+
+  constructor(
+    message: string,
+    opts: {
+      status?: number;
+      retryable?: boolean;
+      code?: ClockNextErrorCode;
+      idempotencyKey?: string;
+    } = {},
+  ) {
+    super(message);
+    this.name = new.target.name;
+    this.status = opts.status;
+    this.retryable = opts.retryable ?? false;
+    this.code = opts.code;
+    this.idempotencyKey = opts.idempotencyKey;
+    // Restore prototype chain for instanceof across transpile targets.
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/** 401 — missing / invalid / expired API key. */
+export class AuthError extends ClockNextError {}
+
+/** 403 — the key is valid but cannot perform this operation. */
+export class ForbiddenError extends ClockNextError {}
+
+/** 400 — malformed request / schema validation failure. */
+export class ValidationError extends ClockNextError {}
+
+/** 404 — unknown customer (also returned for cross-org access). */
+export class NotFoundError extends ClockNextError {}
+
+/** 422 — no active plan, meter not in plan, model not enabled, member missing. */
+export class PlanError extends ClockNextError {}
+
+/** 422 — the entitlement ran out: no credits / units / outcomes / composite
+ *  slots left. Distinct from {@link PlanError} because the fix is different —
+ *  this one is a top-up or an upsell, not a configuration change. */
+export class AllowanceError extends ClockNextError {}
+
+/** 409 — conflict. Almost always permanent (an archived customer); only the
+ *  idempotency-resolution conflict is transient, and only that one retries. */
+export class ConflictError extends ClockNextError {}
+
+/** 429 — rate limited. */
+export class RateLimitError extends ClockNextError {
+  readonly retryAfterMs?: number;
+  constructor(
+    message: string,
+    opts: { retryAfterMs?: number; idempotencyKey?: string } = {},
+  ) {
+    super(message, {
+      status: 429,
+      retryable: true,
+      idempotencyKey: opts.idempotencyKey,
+    });
+    this.retryAfterMs = opts.retryAfterMs;
+  }
+}
+
+/** 5xx — server-side error. */
+export class ServerError extends ClockNextError {}
+
+/** fetch threw / request timed out — request never completed. */
+export class NetworkError extends ClockNextError {
+  constructor(message: string, opts: { idempotencyKey?: string } = {}) {
+    super(message, { retryable: true, idempotencyKey: opts.idempotencyKey });
+  }
+}
+
+/**
+ * Wire field path → the SDK field the caller actually wrote.
+ *
+ * The server validates the WIRE body and names the offending path in its 400
+ * (`usage.inputTokens: Expected number…`). But the SDK groups those fields
+ * differently — `tokens: { input, output, cache }` — so the path it reports
+ * names something that does not exist anywhere in this SDK's API. A caller
+ * (human or LLM) then searches their own code for `usage.inputTokens`, finds
+ * nothing, and has no next move.
+ *
+ * Rewriting the path closes that loop: the error names the property the caller
+ * typed. Ordered longest-first so `usage.model` is rewritten before a bare
+ * `usage` prefix could shadow it.
+ */
+const FIELD_PATHS: ReadonlyArray<readonly [RegExp, string]> = [
+  [/\busage\.inputTokens\b/g, "tokens.input"],
+  [/\busage\.outputTokens\b/g, "tokens.output"],
+  [/\busage\.cacheTokens\b/g, "tokens.cache"],
+  [/\busage\.model\b/g, "model"],
+  // A missing/invalid `usage` block as a whole: the caller's equivalent is
+  // `tokens` (plus `model`, which the SDK hoists to the top level).
+  [/^usage:/, "tokens:"],
+];
+
+/** Rewrite wire field paths in a validation message to SDK field paths. */
+export function translateFieldPaths(message: string): string {
+  let out = message;
+  for (const [pattern, replacement] of FIELD_PATHS) {
+    out = out.replace(pattern, replacement);
+  }
+  return out;
+}
+
+/**
+ * Whether a 422 means "the entitlement ran out" rather than "the plan does not
+ * allow this".
+ *
+ * Both share a status, so they have to be told apart from the body. Prefer the
+ * server's `code`; fall back to matching the exhaustion messages the signal
+ * engine actually emits:
+ *
+ *   No <name> outcomes remaining for this customer. Top up the allowance, …
+ *   No allowance left for "<unit>" — N of M remaining. Top up the balance, …
+ *   No slots left in composite "<name>" — all N are claimed for this cycle.
+ *
+ * Note what is NOT here: `insufficient`. Earlier versions of this SDK tested
+ * for that word alone, and it appears nowhere in the ClockNext API — so
+ * `AllowanceError` was unreachable and every exhaustion arrived as a
+ * `PlanError`. The word is kept in the pattern only so a future rewording
+ * toward it still classifies, never as the sole test.
+ */
+const ALLOWANCE_MESSAGE =
+  /\binsufficient\b|\bno allowance left\b|\bno slots left\b|\boutcomes remaining\b|\btop up the (?:allowance|balance)\b/i;
+
+export function isAllowanceFailure(message: string, code?: string): boolean {
+  if (code) return code === "ALLOWANCE_EXHAUSTED";
+  return ALLOWANCE_MESSAGE.test(message);
+}
+
+/**
+ * The one 409 that is worth retrying.
+ *
+ * Every other conflict this API returns is `Customer "<id>" is archived.` —
+ * permanent, and retrying it only burns `retry.maxAttempts` rounds of backoff
+ * before failing anyway. This one is a lost race while resolving an idempotent
+ * replay, and it does clear.
+ */
+const TRANSIENT_CONFLICT = /could not resolve the idempotent request/i;
+
+/**
+ * Maps a server response to a typed error.
+ *
+ * `code` is the server's machine-readable failure code when it sent one; it
+ * takes precedence over every message heuristic below.
+ */
+export function errorFromResponse(
+  status: number,
+  message: string,
+  retryAfterMs?: number,
+  meta: { code?: ClockNextErrorCode; idempotencyKey?: string } = {},
+): ClockNextError {
+  const raw = message || `Request failed with status ${status}.`;
+  const { code, idempotencyKey } = meta;
+  const opts = { status, code, idempotencyKey };
+
+  if (status === 400) {
+    // Only validation messages carry wire field paths worth rewriting.
+    return new ValidationError(translateFieldPaths(raw), opts);
+  }
+  if (status === 401) return new AuthError(raw, opts);
+  if (status === 403) return new ForbiddenError(raw, opts);
+  if (status === 404) return new NotFoundError(raw, opts);
+  // 408 Request Timeout — transient; the request never produced a result, so
+  // a retry is safe.
+  if (status === 408) return new ClockNextError(raw, { ...opts, retryable: true });
+  if (status === 409) {
+    return new ConflictError(raw, {
+      ...opts,
+      retryable:
+        code === "IDEMPOTENCY_UNRESOLVED" || TRANSIENT_CONFLICT.test(raw),
+    });
+  }
+  if (status === 422) {
+    return isAllowanceFailure(raw, code)
+      ? new AllowanceError(raw, opts)
+      : new PlanError(raw, opts);
+  }
+  if (status === 429) return new RateLimitError(raw, { retryAfterMs, idempotencyKey });
+  if (status >= 500) return new ServerError(raw, { ...opts, retryable: true });
+  return new ClockNextError(raw, opts);
+}

package/src/filters.ts

@@ -0,0 +1,33 @@
+/**
+ * The `active` list filter, shared by every catalog resource.
+ *
+ * The API offers exactly ONE filter: `?active=true` narrows a list to active
+ * rows. There is no inactive-only parameter — the server tests
+ * `searchParams.get("active") === "true"` and returns everything otherwise.
+ *
+ * That made `{ active: false }` a trap. It reads as "only the archived ones",
+ * but it serialised to `active=false`, failed the server's equality test, and
+ * returned EVERY row — including all the active ones the caller was trying to
+ * exclude. The opposite of the request, with no error to notice.
+ *
+ * Rather than leave a boolean whose `false` branch means the reverse of what it
+ * says, `false` is honoured here instead: the query parameter is omitted and
+ * the active rows are filtered out client-side. Omitting `active` entirely
+ * still means "everything", which is the API's own default.
+ */
+
+/** The `active` query value to send: only `true` narrows server-side. */
+export function activeQuery(active?: boolean): string | undefined {
+  return active === true ? "true" : undefined;
+}
+
+/**
+ * Apply the half of the filter the API cannot do. A no-op unless `active` is
+ * explicitly `false`, in which case only archived rows survive.
+ */
+export function filterByActive<T extends { isActive: boolean }>(
+  rows: T[],
+  active?: boolean,
+): T[] {
+  return active === false ? rows.filter((row) => !row.isActive) : rows;
+}