@clocknext/sdk 0.19.0 → 0.19.1

package/README.md

@@ -655,6 +655,34 @@ for await (const t of cnk.customers.iterateWallet(customerId)) {
 }
 ```
 
+### Look up usage rows by id
+
+`signals.lookupUsageLogs(ids)` returns up to 100 usage-log rows in one call —
+for example the row behind each wallet debit's `usageLogId`. It is scoped to
+your org, not one customer: every row has its own `customerId`. Rows come back
+in the order of `ids`; ids with no row in your org are listed in `notFound`.
+
+Each row has `entitlement: { type, id, name }` — `type` is `credit`, `outcome`,
+`outcome_completion`, `unit`, `composite_completion` or `wallet` (a wallet row
+is named `"Wallet"`) — and only the matching group (`credit`, `outcome`,
+`outcomeCompletion`, `unit`, `compositeCompletion`, `wallet`) is set.
+`composite: { id, refId, runId }` names the composite that pays for a row.
+`cost.customerCost` is what the row charged, so it matches the wallet debit.
+
+```ts
+const ledger = await cnk.customers.wallet(customerId);
+const ids = ledger.transactions
+  .filter((t) => t.source === "USAGE_LOG" && t.usageLogId)
+  .map((t) => t.usageLogId!);
+
+const { usageLogs, notFound } = await cnk.signals.lookupUsageLogs(ids);
+for (const row of usageLogs) {
+  row.entitlement.type;   // what was charged
+  row.cost.customerCost;  // what it charged
+  row.composite;          // { id, refId, runId } | null
+}
+```
+
 To change how much a customer is granted **every billing cycle** (not just
 their balance right now), use `updateRecurringGrant`. Any increase or decrease
 applies to their balance immediately. `quantity` is USD for the wallet and a

package/dist/index.cjs

@@ -333,7 +333,7 @@ function sleep(ms) {
 }
 
 // src/http.ts
-var SDK_VERSION = "0.19.0" ;
+var SDK_VERSION = "0.19.1" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;
@@ -1228,6 +1228,7 @@ var UNIT_PATH = "/api/v1/signal/unit";
 var COMPOSITE_COMPLETE_PATH = "/api/v1/signal/composite/complete";
 var OUTCOME_COMPLETE_PATH = "/api/v1/signal/outcome/complete";
 var USAGE_LOG_PATH = "/api/v1/signal/usage-log";
+var USAGE_LOG_LOOKUP_PATH = "/api/v1/signal/usage-log/lookup";
 function signalToWire(signal) {
   const t = signal.tokens;
   const body = {
@@ -1490,6 +1491,26 @@ var Signals = class {
       }
     });
   }
+  /**
+   * 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) {
+    return this.transport.request({
+      method: "GET",
+      path: USAGE_LOG_LOOKUP_PATH,
+      query: { ids: ids.join(",") }
+    });
+  }
 };
 
 // src/resources/units.ts