@clocknext/sdk 0.19.0 → 0.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clocknext/sdk",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "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

@@ -61,6 +61,9 @@ export type {
   UsageLogOutcomeAttribution,
   UsageLogEntry,
   UsageLogPage,
+  UsageLogLookupEntitlementType,
+  UsageLogLookupEntry,
+  UsageLogLookupResult,
   // customers
   CustomerRef,
   ApiCustomer,

package/src/resources/signals.ts

@@ -18,6 +18,7 @@ import type {
   UnitTrackResult,
   UsageLogListParams,
   UsageLogPage,
+  UsageLogLookupResult,
   WalletInput,
 } from "../types.js";
 
@@ -46,6 +47,7 @@ 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";
+const USAGE_LOG_LOOKUP_PATH = "/api/v1/signal/usage-log/lookup";
 
 /**
  * Builds the request body for a typed Signal.
@@ -444,4 +446,25 @@ export class Signals {
       },
     });
   }
+
+  /**
+   * Fetches up to 100 usage-log rows by id, in one call.
+   * `GET /api/v1/signal/usage-log/lookup`.
+   *
+   * Built for linking a wallet debit to its usage: pass the `usageLogId`s
+   * from `customers.wallet()` instead of paging through
+   * {@link usageLog}. Scoped to your org, not to one customer — every row
+   * carries its own `customerId`.
+   *
+   * Rows come back in the order of `ids`; duplicates are removed. Ids that
+   * match nothing in your org are listed in `notFound`. More than 100
+   * distinct ids is a 400.
+   */
+  lookupUsageLogs(ids: string[]): Promise<UsageLogLookupResult> {
+    return this.transport.request<UsageLogLookupResult>({
+      method: "GET",
+      path: USAGE_LOG_LOOKUP_PATH,
+      query: { ids: ids.join(",") },
+    });
+  }
 }

package/src/types.ts

@@ -484,6 +484,83 @@ export interface UsageLogPage {
   nextCursor: string | null;
 }
 
+// ---------------------------------------------------------------------------
+// Usage log lookup (mirrors GET /api/v1/signal/usage-log/lookup)
+// ---------------------------------------------------------------------------
+
+/** What a {@link UsageLogLookupEntry} row is. `"outcome"` is one step of a
+ *  run; `"outcome_completion"` and `"composite_completion"` are the finished
+ *  runs themselves. */
+export type UsageLogLookupEntitlementType =
+  | "credit"
+  | "outcome"
+  | "outcome_completion"
+  | "unit"
+  | "composite_completion"
+  | "wallet";
+
+/**
+ * One row of `signals.lookupUsageLogs()`. Only the group that matches
+ * `entitlement.type` holds data; the others are `null`.
+ */
+export interface UsageLogLookupEntry {
+  id: string;
+  /** The customer this row belongs to — a lookup can span customers. */
+  customerId: string;
+  /** For a finished run (`outcome_completion`, `composite_completion`), when
+   *  it completed. */
+  createdAt: string;
+  status: SignalStatus;
+  /** The credit / outcome / unit / composite this row is for. A wallet row has
+   *  `id: null` and `name: "Wallet"`. */
+  entitlement: { type: UsageLogLookupEntitlementType; id: string | null; name: string | null };
+  member: string | null;
+  model: { name: string | null; provider: string | null } | null;
+  usage: {
+    inputTokens: number;
+    outputTokens: number;
+    /** Cache-read tokens. */
+    cacheTokens: number;
+    /** Cache-write tokens, priced separately from cache reads. */
+    cacheWriteTokens: number;
+  };
+  /** Formatted USD strings. `customerCost` is what this row charged:
+   *  `"$0.00"` on an outcome step (the run is billed at completion) and on any
+   *  row a composite pays for. On a unit row it is what the wallet paid for
+   *  that report (debits minus refunds), `"$0.00"` when the wallet paid
+   *  nothing. */
+  cost: { providedCost: string; customerCost: string };
+  /** `entitlement.type === "credit"`. */
+  credit: { amount: string; appliedRules: UsageLogAppliedRule[] } | null;
+  /** `entitlement.type === "outcome"`. `runCompleted` is true once the run is
+   *  finished — on every step row of that run. */
+  outcome: { step: string | null; stepName: string | null; runId: string | null; runCompleted: boolean } | null;
+  /** `entitlement.type === "outcome_completion"`. `amount` is the price frozen
+   *  when the run completed. */
+  outcomeCompletion: { runId: string | null; amount: string } | null;
+  /** `entitlement.type === "unit"`. `quantity` is formatted. */
+  unit: { quantity: string } | null;
+  /** `entitlement.type === "composite_completion"`. `refId` is the
+   *  composite's tag key, `runId` the tag value you sent. */
+  compositeCompletion: { refId: string | null; runId: string | null; amount: string; startedAt: string } | null;
+  /** `entitlement.type === "wallet"`. What the wallet paid, formatted USD —
+   *  the same value as `cost.customerCost`. */
+  wallet: { amount: string } | null;
+  /** The composite that pays for this row — its id, its tag key (`refId`) and
+   *  the tag value you sent (`runId`). `null` when the row is billed by
+   *  itself. */
+  composite: { id: string | null; refId: string | null; runId: string | null } | null;
+  /** The `custom` object sent, as sent. `null` when none was sent. */
+  custom: Record<string, unknown> | null;
+}
+
+export interface UsageLogLookupResult {
+  /** The rows found, in the order of the ids you asked for. */
+  usageLogs: UsageLogLookupEntry[];
+  /** The ids that matched nothing in your org, in the order you asked. */
+  notFound: string[];
+}
+
 // ---------------------------------------------------------------------------
 // Customers (mirrors src/lib/customers/api.ts)
 // ---------------------------------------------------------------------------