@clocknext/sdk 0.14.0 → 0.16.0

package/src/resources/signals.ts

@@ -1,5 +1,6 @@
 import type { Transport } from "../http.js";
 import type { Flusher } from "../flusher.js";
+import { customerRefToWire } from "../customer-ref.js";
 import { newKey } from "../idempotency.js";
 import type {
   CompositeCompletionInput,
@@ -15,8 +16,6 @@ import type {
   TrackResult,
   UnitInput,
   UnitTrackResult,
-  UnitUsageList,
-  UsageList,
   UsageLogListParams,
   UsageLogPage,
   WalletInput,
@@ -68,14 +67,16 @@ const USAGE_LOG_PATH = "/api/v1/signal/usage-log";
 export function signalToWire(signal: Signal): Record<string, unknown> {
   const t = signal.tokens;
   const body: Record<string, unknown> = {
-    customerId: signal.customerId,
+    ...customerRefToWire(signal),
     // `usage` is required on all three model-priced kinds. input/output are
-    // always sent; `cacheTokens` only when provided (the server defaults 0).
+    // always sent; `cacheTokens` / `cacheWriteTokens` only when provided (the
+    // server defaults each to 0).
     usage: {
       model: signal.model,
       inputTokens: t.input,
       outputTokens: t.output,
       ...(t.cache != null ? { cacheTokens: t.cache } : {}),
+      ...(t.cacheWrite != null ? { cacheWriteTokens: t.cacheWrite } : {}),
     },
   };
   if (signal.member) body.member = signal.member;
@@ -282,9 +283,8 @@ export class Signals {
       path: OUTCOME_COMPLETE_PATH,
       idempotencyKey,
       body: {
-        customerId: input.customerId,
+        ...customerRefToWire(input),
         runId: input.runId,
-        complete: true,
         ...(input.member ? { member: input.member } : {}),
         idempotencyKey,
       },
@@ -300,27 +300,6 @@ export class Signals {
     };
   }
 
-  /**
-   * Recent usage logs + totals for a customer. `GET /api/v1/usage`.
-   *
-   * Still the legacy path, deliberately. The `/api/v1/signal/*` family is
-   * POST-only — it replaced how usage is INGESTED, not how it is read — so
-   * `GET /api/v1/usage` has no successor and is not deprecated. It is also the
-   * only way to prove a signal landed, which matters more now that ingestion
-   * answers `202` for everything.
-   */
-  async list(params: {
-    customerId: string;
-    limit?: number;
-  }): Promise<UsageList> {
-    const res = await this.transport.request<UsageList>({
-      method: "GET",
-      path: "/api/v1/usage",
-      query: { customerId: params.customerId, limit: params.limit },
-    });
-    return { customer: res.customer, totals: res.totals, logs: res.logs };
-  }
-
   /**
    * Record one unit-metered event (a fixed-price meter with no tokens),
    * addressed to a catalog unit by its `agentKey`. Sent immediately — unit
@@ -342,7 +321,7 @@ export class Signals {
       path: UNIT_PATH,
       idempotencyKey,
       body: {
-        customerId: input.customerId,
+        ...customerRefToWire(input),
         agentKey: input.agentKey,
         ...(input.quantity != null ? { quantity: input.quantity } : {}),
         ...(input.member ? { member: input.member } : {}),
@@ -410,7 +389,7 @@ export class Signals {
       path: COMPOSITE_COMPLETE_PATH,
       idempotencyKey,
       body: {
-        customerId: input.customerId,
+        ...customerRefToWire(input),
         composite: { [input.composite.ref]: input.composite.value },
         // Auto-assigned like the others. A retry here could not double-BILL
         // even without it — closing a closed occurrence is a server-side
@@ -432,23 +411,6 @@ export class Signals {
     };
   }
 
-  /**
-   * A customer's unit balances + recent unit events. `GET /api/v1/units`.
-   *
-   * Legacy path for the same reason as {@link list}: the signal family is
-   * POST-only, so the read side has no successor and is not deprecated.
-   */
-  unitUsage(params: {
-    customerId: string;
-    limit?: number;
-  }): Promise<UnitUsageList> {
-    return this.transport.request<UnitUsageList>({
-      method: "GET",
-      path: "/api/v1/units",
-      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

package/src/resources/units.ts

@@ -1,76 +1,76 @@
 import { activeQuery, filterByActive } from "../filters.js";
 import type { Transport } from "../http.js";
-import type {
-  CreateUnitInput,
-  Unit,
-  UnitDetail,
-  UpdateUnitInput,
-} from "../types.js";
+import type { CreateUnitInput, Unit, UpdateUnitInput } from "../types.js";
 
 /**
- * The `units` resource — manage the org's unit *types* (the catalog): named,
- * quantity-priced meters (FLAT / SLAB / VOLUME). Record consumption against a
- * unit with `signals.unit()`. `/api/v1/units-catalog`.
+ * The `units` resource — fixed-price, non-LLM events (uploads, seats, API
+ * calls), priced FLAT, SLAB or VOLUME. `/api/v1/units`.
+ *
+ * There is no `delete()` — the API never deletes catalogue items. Retire a
+ * unit with `archive()`; `unarchive()` brings it back unchanged.
  */
 export class Units {
   constructor(private readonly transport: Transport) {}
 
-  /** List unit 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`. */
+  /** List them. `{ active: true }` returns only active ones, `{ active: false }`
+   *  only archived ones; omit it for both. */
   async list(params: { active?: boolean } = {}): Promise<Unit[]> {
     const res = await this.transport.request<{ units: Unit[] }>({
       method: "GET",
-      path: "/api/v1/units-catalog",
+      path: "/api/v1/units",
       query: { active: activeQuery(params.active) },
     });
     return filterByActive(res.units, params.active);
   }
 
-  /** Create a unit type. `POST /api/v1/units-catalog`. */
-  async create(input: CreateUnitInput): Promise<Unit> {
+  /** One unit's configuration. */
+  async get(id: string): Promise<Unit> {
     const res = await this.transport.request<{ unit: Unit }>({
-      method: "POST",
-      path: "/api/v1/units-catalog",
-      body: input,
+      method: "GET",
+      path: `/api/v1/units/${encodeURIComponent(id)}`,
     });
     return res.unit;
   }
 
-  /** Fetch one unit type with stats. `GET /api/v1/units-catalog/:id`. */
-  async get(id: string): Promise<UnitDetail> {
-    const res = await this.transport.request<{ unit: UnitDetail }>({
-      method: "GET",
-      path: `/api/v1/units-catalog/${encodeURIComponent(id)}`,
+  /** Create one. It starts active. Not retried on failure — a retry could
+   *  create a second row. */
+  async create(input: CreateUnitInput): Promise<Unit> {
+    const res = await this.transport.request<{ created: true; unit: Unit }>({
+      method: "POST",
+      path: "/api/v1/units",
+      body: input,
     });
     return res.unit;
   }
 
-  /** Update a unit type's definition. `PATCH /api/v1/units-catalog/:id`. */
+  /** PARTIAL update: only the fields you send change. `tiers`, when sent, is
+   *  the complete new tier list. */
   async update(id: string, input: UpdateUnitInput): Promise<Unit> {
-    const res = await this.transport.request<{ unit: Unit }>({
+    const res = await this.transport.request<{ updated: true; unit: Unit }>({
       method: "PATCH",
-      path: `/api/v1/units-catalog/${encodeURIComponent(id)}`,
+      path: `/api/v1/units/${encodeURIComponent(id)}`,
       body: input,
     });
     return res.unit;
   }
 
-  /** Activate or deactivate a unit type. */
-  async setActive(id: string, isActive: boolean): Promise<Unit> {
-    const res = await this.transport.request<{ unit: Unit }>({
-      method: "PATCH",
-      path: `/api/v1/units-catalog/${encodeURIComponent(id)}`,
-      body: { isActive },
+  /** Retire it (`isActive` → false). Nothing is deleted. Safe to retry. */
+  async archive(id: string): Promise<Unit> {
+    const res = await this.transport.request<{ archived: true; unit: Unit }>({
+      method: "POST",
+      path: `/api/v1/units/${encodeURIComponent(id)}/archive`,
+      retry: true,
     });
     return res.unit;
   }
 
-  /** Delete a unit type. */
-  async delete(id: string): Promise<void> {
-    await this.transport.request({
-      method: "DELETE",
-      path: `/api/v1/units-catalog/${encodeURIComponent(id)}`,
+  /** Bring an archived one back (`isActive` → true). Safe to retry. */
+  async unarchive(id: string): Promise<Unit> {
+    const res = await this.transport.request<{ unarchived: true; unit: Unit }>({
+      method: "POST",
+      path: `/api/v1/units/${encodeURIComponent(id)}/unarchive`,
+      retry: true,
     });
+    return res.unit;
   }
 }