@clocknext/sdk 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clocknext/sdk",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Official ClockNext SDK — record usage signals and manage plans, purchases, invoices, customers, and billing from your backend.",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -59,6 +59,12 @@ export type {
   UnitUsageRow,
   UnitUsageList,
   SerializedUnitUsage,
+  UsageLogPeriod,
+  UsageLogListParams,
+  UsageLogAppliedRule,
+  UsageLogOutcomeAttribution,
+  UsageLogEntry,
+  UsageLogPage,
   // workspace
   WorkspaceIdentity,
   Model,

package/src/resources/signals.ts

@@ -17,6 +17,8 @@ import type {
   UnitTrackResult,
   UnitUsageList,
   UsageList,
+  UsageLogListParams,
+  UsageLogPage,
   WalletInput,
 } from "../types.js";
 
@@ -44,6 +46,7 @@ const SIGNAL_PATHS: Record<SignalType, string> = {
 const UNIT_PATH = "/api/v1/signal/unit";
 const COMPOSITE_COMPLETE_PATH = "/api/v1/signal/composite/complete";
 const OUTCOME_COMPLETE_PATH = "/api/v1/signal/outcome/complete";
+const USAGE_LOG_PATH = "/api/v1/signal/usage-log";
 
 /**
  * Builds the request body for a typed Signal.
@@ -445,4 +448,36 @@ export class Signals {
       query: { customerId: params.customerId, limit: params.limit },
     });
   }
+
+  /**
+   * One customer's usage history, merged from every meter kind — credit,
+   * outcome, unit, wallet, and completed composite occurrences — into one
+   * feed sorted by time. `GET /api/v1/signal/usage-log`. Exactly the same
+   * rows the customer portal's own "Usage logs" table shows, so a caller can
+   * build against this instead of the portal UI.
+   *
+   * Cursor-paginated, NOT page-numbered: `limit` + `cursor` in, `nextCursor`
+   * out. Omit `cursor` for the first page; pass the previous page's
+   * `nextCursor` back to fetch the next one, and stop once it comes back
+   * `null`. Unlike offset pagination, the cost of a page never grows with how
+   * deep you've paged — each page only asks for rows strictly before the
+   * cursor's position.
+   *
+   * Read-only; unlike {@link track}/{@link unit}/etc., there is nothing to
+   * buffer or retry here.
+   */
+  usageLog(params: UsageLogListParams): Promise<UsageLogPage> {
+    return this.transport.request<UsageLogPage>({
+      method: "GET",
+      path: USAGE_LOG_PATH,
+      query: {
+        customerId: params.customerId,
+        limit: params.limit,
+        cursor: params.cursor,
+        period: params.period,
+        from: params.from,
+        to: params.to,
+      },
+    });
+  }
 }

package/src/types.ts

@@ -385,6 +385,86 @@ export interface UsageList {
   logs: SerializedUsageLog[];
 }
 
+// ---------------------------------------------------------------------------
+// Usage log (mirrors GET /api/v1/signal/usage-log)
+// ---------------------------------------------------------------------------
+
+/** A preset time window, or `"custom"` for an explicit `from`/`to` range. */
+export type UsageLogPeriod = "all" | "today" | "7d" | "30d" | "90d" | "custom";
+
+export interface UsageLogListParams {
+  customerId: string;
+  /** Default 50, max 200. */
+  limit?: number;
+  /** Pass back a previous page's `nextCursor` to fetch the next page. Omit for
+   *  the first page. */
+  cursor?: string;
+  /** Default `"all"`. Pair `"custom"` with `from`/`to`. */
+  period?: UsageLogPeriod;
+  /** `YYYY-MM-DD`, only used when `period` is `"custom"`. */
+  from?: string;
+  /** `YYYY-MM-DD`, only used when `period` is `"custom"`. */
+  to?: string;
+}
+
+export interface UsageLogAppliedRule {
+  ruleId: string | null;
+  ruleName: string;
+  mode: "MARGIN" | "CREDIT" | null;
+  marginPercentApplied: number | null;
+  /** Formatted, same as {@link UsageLogEntry.credit}'s `amount`. */
+  creditsApplied: string;
+}
+
+export interface UsageLogOutcomeAttribution {
+  /** "2 / 4" — the step this call performed, and the outcome's total step
+   *  count. Not a progress target: a step may repeat within a run. */
+  step: string | null;
+  stepName: string | null;
+  runId: string | null;
+  /** How many signals the run holds. */
+  runSignals: number;
+  /** True once the run closed (`complete: true` was sent for it). */
+  closedRun: boolean;
+}
+
+/**
+ * One row of a customer's usage history, merged from every meter kind
+ * (`UsageLog`, `UnitUsageLog`, completed composite occurrences) into one
+ * feed and sorted by time — the same rows the customer portal's own "Usage
+ * logs" table shows. `model`, `credit`, `outcome`, `unit` and `composite` are
+ * each `null` unless `kind` matches that group.
+ */
+export interface UsageLogEntry {
+  id: string;
+  createdAt: string;
+  kind: "credit" | "outcome" | "unit" | "wallet" | "composite";
+  status: SignalStatus;
+  typeName: string | null;
+  member: string | null;
+  model: { name: string | null; provider: string | null } | null;
+  usage: { inputTokens: number; outputTokens: number; cacheTokens: number };
+  /** Formatted USD strings (e.g. `"$0.0064"`). */
+  cost: { providedCost: string; customerCost: string };
+  /** Populated only when `kind === "credit"`. `amount` is a formatted credit
+   *  value, honouring the org's credit-decimals display setting. */
+  credit: { amount: string; appliedRules: UsageLogAppliedRule[] } | null;
+  /** Populated only when `kind === "outcome"`. */
+  outcome: UsageLogOutcomeAttribution | null;
+  /** Populated only when `kind === "unit"`. `quantity` is formatted. */
+  unit: { quantity: string } | null;
+  /** Populated only when `kind === "composite"`. `amount` is a formatted USD
+   *  price — the composite's flat price, read live, not stored per row. */
+  composite: { amount: string } | null;
+}
+
+export interface UsageLogPage {
+  usageLogs: UsageLogEntry[];
+  /** Pass this back as `cursor` to fetch the next page; `null` on the last
+   *  page. */
+  nextCursor: string | null;
+}
+
 // ---------------------------------------------------------------------------
 // Customers (mirrors src/lib/customers/api.ts)
 // ---------------------------------------------------------------------------