@clocknext/sdk 0.10.0 → 0.12.0

package/src/flusher.ts

@@ -0,0 +1,144 @@
+import type { Transport } from "./http.js";
+import { InMemoryQueue, type QueueStore, type QueuedSignal } from "./queue.js";
+import type { ResolvedConfig } from "./types.js";
+
+/**
+ * Background send engine for async-mode signals. Buffers wire-ready signals and
+ * flushes them when the buffer reaches `maxSize` OR every `maxIntervalMs`,
+ * whichever comes first — the Segment/Amberflo pattern. The Transport owns
+ * retries; `close()` drains and awaits in-flight sends so a serverless process
+ * can flush before it freezes.
+ */
+export class Flusher {
+  private readonly queue: QueueStore = new InMemoryQueue();
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private draining: Promise<void> | null = null;
+  private closed = false;
+
+  constructor(
+    private readonly transport: Transport,
+    private readonly cfg: ResolvedConfig,
+  ) {}
+
+  /**
+   * Buffer one signal. Drops (with onDrop) when closed or the queue is full.
+   * Returns whether it was actually buffered, so `track()` can report a drop
+   * honestly instead of answering "buffered" for a signal it threw away.
+   */
+  enqueue(item: QueuedSignal): boolean {
+    if (this.closed) {
+      // Not `send_failed` — nothing was ever sent. Reporting a send failure for
+      // a signal that never left the buffer sends a caller looking for a
+      // network problem that does not exist.
+      this.cfg.onDrop?.(item.signal, "closed");
+      return false;
+    }
+    if (this.queue.size() >= this.cfg.batch.maxQueueSize) {
+      this.cfg.logger.warn?.("[clocknext] queue full — dropping signal");
+      this.cfg.onDrop?.(item.signal, "queue_full");
+      return false;
+    }
+    this.queue.push(item);
+    if (this.queue.size() >= this.cfg.batch.maxSize) void this.flush();
+    else this.arm();
+    return true;
+  }
+
+  /** Arm the interval timer if it isn't already running. */
+  private arm(): void {
+    if (this.timer || this.closed) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.flush();
+    }, this.cfg.batch.maxIntervalMs);
+    // Don't keep the event loop alive just for the flush timer.
+    (this.timer as { unref?: () => void }).unref?.();
+  }
+
+  /** Cancel the interval timer if one is armed. */
+  private clearTimer(): void {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /**
+   * Send everything buffered at the moment this resolves.
+   *
+   * Overlapping calls CHAIN onto the in-flight drain rather than sharing it.
+   * Sharing looks equivalent and is not: a drain that has already passed its
+   * final `size() > 0` check cannot see a signal enqueued a moment later, so
+   * handing that same promise back would resolve `flush()` — and therefore
+   * `close()` — with the buffer non-empty. Since `close()` has already set
+   * `closed`, `arm()` will not re-arm, and the timer it did arm is `unref`'d,
+   * so the process is free to exit and that signal is simply lost. Chaining
+   * guarantees at least one full drain begins after this call.
+   *
+   * Concurrency is unaffected: drains run one after another, and each one
+   * sends at most `maxConcurrency` signals at a time.
+   */
+  flush(): Promise<void> {
+    this.clearTimer();
+    // A prior drain that rejected must not poison the chain, hence the catch.
+    const prior = this.draining ?? Promise.resolve();
+    const tracked: Promise<void> = prior
+      .catch(() => {})
+      .then(() => this.drain())
+      .finally(() => {
+        if (this.draining === tracked) this.draining = null;
+      });
+    this.draining = tracked;
+    return tracked;
+  }
+
+  /** Drain the buffer in concurrency-bounded waves until it's empty. */
+  private async drain(): Promise<void> {
+    let sent = 0;
+    while (this.queue.size() > 0) {
+      const wave = this.queue.take(this.cfg.batch.maxConcurrency);
+      const results = await Promise.all(wave.map((item) => this.send(item)));
+      sent += results.filter(Boolean).length;
+    }
+    if (sent > 0) this.cfg.onFlush?.(sent);
+  }
+
+  /** Send one item; never throws — failures surface via onError/onDrop. */
+  private async send(item: QueuedSignal): Promise<boolean> {
+    try {
+      await this.transport.request({
+        method: "POST",
+        // Per-item, not per-Flusher: one route per meter. See `QueuedSignal`.
+        path: item.path,
+        body: item.body,
+        // Best-effort metering opts into retries on transient failures.
+        retry: true,
+        // Rides onto any thrown error so `onError` can replay this exact
+        // signal without minting a new key (which would bill it twice).
+        idempotencyKey:
+          typeof item.body.idempotencyKey === "string"
+            ? item.body.idempotencyKey
+            : undefined,
+      });
+      return true;
+    } catch (error) {
+      this.cfg.onError?.(error, item.signal);
+      this.cfg.onDrop?.(item.signal, "send_failed");
+      return false;
+    }
+  }
+
+  get size(): number {
+    return this.queue.size();
+  }
+
+  /** Flush remaining signals, then refuse further enqueues. */
+  async close(): Promise<void> {
+    this.closed = true;
+    await this.flush();
+    // Nothing can be enqueued now, so the buffer is empty for good and a timer
+    // armed just before close has nothing left to do. Clearing it lets a
+    // process exit immediately instead of waiting on a stray handle.
+    this.clearTimer();
+  }
+}

package/src/http.ts

@@ -0,0 +1,178 @@
+import { NetworkError, RateLimitError, errorFromResponse } from "./errors.js";
+import { computeBackoff, isRetryable, parseRetryAfter, sleep } from "./retry.js";
+import type { ResolvedConfig } from "./types.js";
+
+/**
+ * Injected from package.json at build time (see tsup `define`) so it can't
+ * drift. Falls back to a dev marker when run un-bundled (tests, ts-node).
+ */
+declare const __SDK_VERSION__: string | undefined;
+const SDK_VERSION =
+  typeof __SDK_VERSION__ !== "undefined" ? __SDK_VERSION__ : "0.0.0-dev";
+
+interface RequestOptions {
+  method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+  path: string;
+  query?: Record<string, string | number | undefined>;
+  body?: unknown;
+  /**
+   * Whether this call may be auto-retried on a transient failure. Defaults to
+   * method-based safety: reads (GET), idempotent replaces (PUT), and DELETE are
+   * replay-safe. Non-idempotent writes (POST/PATCH) default to NOT retried so a
+   * transient failure can't duplicate the write; callers that tolerate a retry
+   * opt in explicitly.
+   */
+  retry?: boolean;
+  /**
+   * The idempotency key carried in this request's body, for metering calls.
+   *
+   * Copied onto any error thrown, so a caller handling a permanent failure can
+   * replay the signal with the SAME key instead of minting a fresh one — which
+   * would defeat server-side dedup and bill twice. See
+   * `ClockNextError.idempotencyKey`.
+   */
+  idempotencyKey?: string;
+}
+
+/**
+ * The single HTTP seam. Builds the authenticated request, enforces a timeout,
+ * unwraps the `{ ok, ... }` envelope, maps failures to typed errors, and retries
+ * transient ones with backoff + jitter.
+ */
+export class Transport {
+  constructor(private readonly cfg: ResolvedConfig) {}
+
+  async request<T = unknown>(opts: RequestOptions): Promise<T> {
+    const url = this.buildUrl(opts.path, opts.query);
+    // Reads, idempotent PUT replaces, and DELETE are replay-safe by default;
+    // non-idempotent writes are retried only when the caller opts in (e.g.
+    // best-effort metering signals).
+    const replaySafe =
+      opts.method === "GET" ||
+      opts.method === "PUT" ||
+      opts.method === "DELETE";
+    const allowRetry = opts.retry ?? replaySafe;
+    const maxAttempts = allowRetry ? this.cfg.retry.maxAttempts : 1;
+
+    let attempt = 0;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      attempt++;
+      try {
+        return await this.once<T>(url, opts);
+      } catch (error) {
+        const canRetry = attempt < maxAttempts && isRetryable(error);
+        if (!canRetry) throw error;
+        const retryAfterMs =
+          error instanceof RateLimitError ? error.retryAfterMs : undefined;
+        const delayMs = computeBackoff(attempt, this.cfg.retry, retryAfterMs);
+        this.cfg.onRetry?.({ attempt, delayMs, error });
+        this.cfg.logger.debug?.(
+          `[clocknext] retry ${attempt}/${maxAttempts - 1} in ${delayMs}ms`,
+          error instanceof Error ? error.message : error,
+        );
+        await sleep(delayMs);
+      }
+    }
+  }
+
+  /** One attempt: fetch + timeout + envelope/status handling. */
+  private async once<T>(url: string, opts: RequestOptions): Promise<T> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.cfg.timeoutMs);
+
+    let res: Response;
+    try {
+      res = await this.cfg.fetch(url, {
+        method: opts.method,
+        headers: this.headers(opts),
+        body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+        signal: controller.signal,
+      });
+    } catch (err) {
+      const message =
+        controller.signal.aborted
+          ? `Request to ${opts.path} timed out after ${this.cfg.timeoutMs}ms.`
+          : `Network error calling ${opts.path}: ${
+              err instanceof Error ? err.message : String(err)
+            }`;
+      throw new NetworkError(message, { idempotencyKey: opts.idempotencyKey });
+    } finally {
+      clearTimeout(timer);
+    }
+
+    const text = await res.text();
+    let json: unknown = undefined;
+    if (text) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        // Non-JSON body — only an error if the status is also bad.
+      }
+    }
+
+    // Every `/api/v1` route answers through `v1Success`/`v1Error`:
+    //   { statusCode, statusDetail: { status, message, code? }, result }
+    // The `{ ok, error, ...payload }` shape below is a defensive fallback for a
+    // route that has not been migrated (or a proxy that rewrites the body), not
+    // a contract the current API still speaks.
+    const obj = (json ?? {}) as Record<string, unknown>;
+    const meta = { idempotencyKey: opts.idempotencyKey };
+    const isEnveloped =
+      typeof obj === "object" && obj !== null && "statusDetail" in obj;
+
+    if (isEnveloped) {
+      const detail = obj.statusDetail as
+        | { status?: string; message?: string; code?: string }
+        | undefined;
+      if (res.ok && detail?.status === "SUCCESS") {
+        return ((obj.result as T | undefined) ?? ({} as T));
+      }
+      const message =
+        detail?.message ?? `Request failed with status ${res.status}.`;
+      throw errorFromResponse(res.status, message, parseRetryAfter(res.headers), {
+        ...meta,
+        code: detail?.code,
+      });
+    }
+
+    const envelope = obj as { ok?: boolean; error?: string };
+    if (res.ok && envelope.ok !== false) {
+      return envelope as T;
+    }
+    const message =
+      envelope.error ?? text ?? `Request failed with status ${res.status}.`;
+    throw errorFromResponse(
+      res.status,
+      message,
+      parseRetryAfter(res.headers),
+      meta,
+    );
+  }
+
+  private headers(opts: RequestOptions): Record<string, string> {
+    const h: Record<string, string> = {
+      Authorization: `Bearer ${this.cfg.apiKey}`,
+      "User-Agent": `clocknext-sdk-js/${SDK_VERSION}`,
+    };
+    if (opts.body !== undefined) h["Content-Type"] = "application/json";
+    return h;
+  }
+
+  private buildUrl(
+    path: string,
+    query?: Record<string, string | number | undefined>,
+  ): string {
+    // baseUrl already has trailing slashes stripped in resolveConfig.
+    let url = `${this.cfg.baseUrl}${path}`;
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== undefined && v !== "") params.set(k, String(v));
+      }
+      const qs = params.toString();
+      if (qs) url += `?${qs}`;
+    }
+    return url;
+  }
+}

package/src/idempotency.ts

@@ -0,0 +1,33 @@
+/**
+ * Idempotency-key generation for usage signals.
+ *
+ * Every signal carries an idempotency key so that a retry — whether a
+ * Transport-level replay of one send, or a re-flush of the buffered body — is
+ * deduplicated on the server instead of recording a second, double-billed
+ * event. The server keys `RawUsageLog` on `(organizationId, idempotencyKey)`
+ * and replays the original result on a repeat.
+ *
+ * The key is generated ONCE, before the signal is buffered or sent, and the
+ * same key rides every retry of that signal (see ARCHITECTURE AD-4). A caller
+ * may instead supply their own key on the signal — a stable id for the logical
+ * event — to also dedup across process restarts / at-least-once redelivery,
+ * which an in-memory auto-generated key cannot survive.
+ */
+
+/**
+ * A fresh idempotency key. A UUID v4 when the runtime exposes Web Crypto
+ * (Node ≥ 18, browsers, edge runtimes), with a non-cryptographic fallback for
+ * exotic runtimes that lack it. The value is opaque to the server — only its
+ * uniqueness matters, not its randomness quality.
+ */
+export function newKey(): string {
+  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;
+  if (typeof c?.randomUUID === "function") return c.randomUUID();
+  // Fallback: an RFC-4122-shaped v4 from Math.random. Uniqueness (not security)
+  // is all that's required for deduplication.
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (ch) => {
+    const r = (Math.random() * 16) | 0;
+    const v = ch === "x" ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}

package/src/index.ts

@@ -0,0 +1,165 @@
+/**
+ * @clocknext/sdk — official ClockNext SDK.
+ *
+ * Record usage signals and manage customers from your backend. Server-side
+ * only: your `cnk_…` API key is a secret with org-wide write access.
+ */
+
+export { ClockNext } from "./client.js";
+
+export {
+  ClockNextError,
+  AuthError,
+  ForbiddenError,
+  ValidationError,
+  NotFoundError,
+  PlanError,
+  AllowanceError,
+  ConflictError,
+  RateLimitError,
+  ServerError,
+  NetworkError,
+} from "./errors.js";
+
+export type { ClockNextErrorCode } from "./errors.js";
+
+export { signalToWire } from "./resources/signals.js";
+
+export type {
+  // config
+  ClockNextConfig,
+  FetchLike,
+  Logger,
+  DropReason,
+  // signals
+  Signal,
+  SignalType,
+  SignalStatus,
+  SignalDelivery,
+  Tokens,
+  CompositeTag,
+  CreditSignal,
+  WalletSignal,
+  OutcomeSignal,
+  CreditInput,
+  WalletInput,
+  OutcomeInput,
+  TrackResult,
+  UsageList,
+  SerializedUsageLog,
+  UsageBalance,
+  SerializedRuleApplication,
+  SerializedOutcomeAttribution,
+  UnitInput,
+  UnitTrackResult,
+  CompositeCompletionInput,
+  CompositeCompletionResult,
+  UnitUsageRow,
+  UnitUsageList,
+  SerializedUnitUsage,
+  // workspace
+  WorkspaceIdentity,
+  Model,
+  // customers
+  ApiCustomer,
+  CustomerProfileInput,
+  CreateCustomerInput,
+  CustomerList,
+  CustomerBalances,
+  CreditBalance,
+  OutcomeBalance,
+  UnitBalance,
+  CustomerPlan,
+  CustomerPlanDetails,
+  // members
+  Member,
+  MemberProfile,
+  RemovedMember,
+  AddMemberInput,
+  UpdateMemberInput,
+  // wallet & balance adjustments
+  WalletTransaction,
+  WalletTransactionType,
+  WalletTransactionSource,
+  WalletEntitlementKind,
+  WalletList,
+  WalletEntryInput,
+  CreditAdjustInput,
+  OutcomeAdjustInput,
+  UnitAdjustInput,
+  // plans
+  Plan,
+  PlanDetail,
+  PlanComponent,
+  PlanComponentInput,
+  WalletComponentInput,
+  FlatComponentInput,
+  CreditComponentInput,
+  OutcomeComponentInput,
+  UnitComponentInput,
+  CompositeComponentInput,
+  CreatePlanInput,
+  UpdatePlanInput,
+  BillingCycle,
+  PlanType,
+  PlanKind,
+  ComponentType,
+  BillingMode,
+  // purchases
+  Purchase,
+  PurchaseDetail,
+  PurchaseStatus,
+  CreatePurchaseInput,
+  // invoices
+  Invoice,
+  InvoiceDetail,
+  InvoiceListRow,
+  InvoiceStatus,
+  InvoiceParty,
+  InvoiceLineItem,
+  InvoicePlanSnapshot,
+  PlanRef,
+  PayLink,
+  // payments
+  PaymentRow,
+  PaymentDetail,
+  // cost analytics (credits / outcomes)
+  CostPoint,
+  CostStats,
+  CreditAnalytics,
+  OutcomeAnalytics,
+  // credits catalog
+  Credit,
+  CreditDetail,
+  CreateCreditInput,
+  UpdateCreditInput,
+  ModelBundleEntry,
+  // outcomes catalog
+  Outcome,
+  OutcomeDetail,
+  OutcomeStepInput,
+  CreateOutcomeInput,
+  UpdateOutcomeInput,
+  // composites catalog
+  Composite,
+  CompositeCatalogueRef,
+  CreateCompositeInput,
+  // units catalog
+  Unit,
+  UnitDetail,
+  UnitCustomerRow,
+  UnitTier,
+  UnitTierInput,
+  UnitPricingType,
+  CreateUnitInput,
+  FlatUnitInput,
+  TieredUnitInput,
+  UpdateUnitInput,
+  // webhooks
+  Webhook,
+  UpsertWebhookInput,
+  ThresholdKind,
+  // portal
+  PortalTokenInput,
+  PortalToken,
+} from "./types.js";

package/src/queue.ts

@@ -0,0 +1,48 @@
+import type { Signal } from "./types.js";
+
+/** One buffered, wire-ready signal awaiting a background flush. */
+export interface QueuedSignal {
+  /**
+   * The route this signal posts to (`/api/v1/signal/credit` etc.), decided by
+   * `track()` when the signal was buffered.
+   *
+   * It is stored per item rather than fixed on the Flusher because each meter
+   * now has its own endpoint. A single hardcoded path was fine when everything
+   * went to `/api/v1/usage`; keeping one would have meant async mode silently
+   * posting to the deprecated route while sync mode used the new ones.
+   */
+  path: string;
+  /** The exact JSON body to POST. */
+  body: Record<string, unknown>;
+  /** The original signal — passed to onError/onDrop hooks. */
+  signal: Signal;
+}
+
+/**
+ * Internal buffer seam. Currently in-memory only — this interface exists so a
+ * durable (disk/Redis/SQLite) implementation can be slotted in later without
+ * touching the Flusher. It is NOT part of the public API and is not yet
+ * injectable; don't rely on it externally.
+ */
+export interface QueueStore {
+  push(item: QueuedSignal): void;
+  /** Remove and return up to `n` items (FIFO). */
+  take(n: number): QueuedSignal[];
+  size(): number;
+}
+
+export class InMemoryQueue implements QueueStore {
+  private items: QueuedSignal[] = [];
+
+  push(item: QueuedSignal): void {
+    this.items.push(item);
+  }
+
+  take(n: number): QueuedSignal[] {
+    return this.items.splice(0, n);
+  }
+
+  size(): number {
+    return this.items.length;
+  }
+}

package/src/resources/composites.ts

@@ -0,0 +1,47 @@
+import { activeQuery, filterByActive } from "../filters.js";
+import type { Transport } from "../http.js";
+import type { Composite, CreateCompositeInput } from "../types.js";
+
+/**
+ * The `composites` resource — manage the org's composite *catalogue*: the
+ * bundles of credits / outcomes / units that are grouped under one tag and
+ * sold on a plan as a single thing. `/api/v1/composites`.
+ *
+ * Two things live elsewhere, deliberately:
+ *   • Tagging a signal into a composite occurrence is `composite: { ref, value }`
+ *     on the signal itself (see `signals.credit()` / `.outcome()` / `.unit()`).
+ *   • Closing an occurrence — the moment it is billed — is
+ *     `signals.completeComposite()`.
+ *
+ * This resource only defines what composites EXIST. Creating one prices it but
+ * charges nobody: an invoice is built from plan components, never from a
+ * catalogue entry, so a composite starts costing money only once a plan sells
+ * it (`quantity × price`, frozen into the purchase at buy time).
+ */
+export class Composites {
+  constructor(private readonly transport: Transport) {}
+
+  /** List composites. Pass `{ active: true }` for only the ones a signal can
+   *  still be tagged with — the default list INCLUDES archived ones, which
+   *  keep every row they already own.
+   *  `{ active: false }` returns only archived ones; omitting it returns
+   *  both. See `activeQuery` — the API itself only supports `true`. */
+  async list(params: { active?: boolean } = {}): Promise<Composite[]> {
+    const res = await this.transport.request<{ composites: Composite[] }>({
+      method: "GET",
+      path: "/api/v1/composites",
+      query: { active: activeQuery(params.active) },
+    });
+    return filterByActive(res.composites, params.active);
+  }
+
+  /** Create a composite. `POST /api/v1/composites`. */
+  async create(input: CreateCompositeInput): Promise<Composite> {
+    const res = await this.transport.request<{ composite: Composite }>({
+      method: "POST",
+      path: "/api/v1/composites",
+      body: input,
+    });
+    return res.composite;
+  }
+}

package/src/resources/credits.ts

@@ -0,0 +1,76 @@
+import { activeQuery, filterByActive } from "../filters.js";
+import type { Transport } from "../http.js";
+import type {
+  CreateCreditInput,
+  Credit,
+  CreditDetail,
+  UpdateCreditInput,
+} from "../types.js";
+
+/**
+ * The `credits` resource — manage the org's credit *types* (the catalog). A
+ * credit's stable `agentKey` is what you pass to `signals.credit()` when
+ * recording usage against it. `/api/v1/credits`.
+ */
+export class Credits {
+  constructor(private readonly transport: Transport) {}
+
+  /** List credit types. Pass `{ active: true }` to only return active ones.
+   *  `{ active: false }` returns only archived ones; omitting it returns
+   *  both. See `activeQuery` — the API itself only supports `true`. */
+  async list(params: { active?: boolean } = {}): Promise<Credit[]> {
+    const res = await this.transport.request<{ credits: Credit[] }>({
+      method: "GET",
+      path: "/api/v1/credits",
+      query: { active: activeQuery(params.active) },
+    });
+    return filterByActive(res.credits, params.active);
+  }
+
+  /** Create a credit type; returns the created credit. `POST /api/v1/credits`. */
+  async create(input: CreateCreditInput): Promise<Credit> {
+    const res = await this.transport.request<{ credit: Credit }>({
+      method: "POST",
+      path: "/api/v1/credits",
+      body: input,
+    });
+    return res.credit;
+  }
+
+  /** Fetch one credit type with usage stats. `GET /api/v1/credits/:id`. */
+  async get(id: string): Promise<CreditDetail> {
+    const res = await this.transport.request<{ credit: CreditDetail }>({
+      method: "GET",
+      path: `/api/v1/credits/${encodeURIComponent(id)}`,
+    });
+    return res.credit;
+  }
+
+  /** Update a credit type's definition; returns the updated credit. `PATCH /api/v1/credits/:id`. */
+  async update(id: string, input: UpdateCreditInput): Promise<Credit> {
+    const res = await this.transport.request<{ credit: Credit }>({
+      method: "PATCH",
+      path: `/api/v1/credits/${encodeURIComponent(id)}`,
+      body: input,
+    });
+    return res.credit;
+  }
+
+  /** Activate or deactivate a credit type. */
+  async setActive(id: string, isActive: boolean): Promise<Credit> {
+    const res = await this.transport.request<{ credit: Credit }>({
+      method: "PATCH",
+      path: `/api/v1/credits/${encodeURIComponent(id)}`,
+      body: { isActive },
+    });
+    return res.credit;
+  }
+
+  /** Delete a credit type. Refused while a customer is linked to it. */
+  async delete(id: string): Promise<void> {
+    await this.transport.request({
+      method: "DELETE",
+      path: `/api/v1/credits/${encodeURIComponent(id)}`,
+    });
+  }
+}