@clocknext/sdk 0.15.0 → 0.17.0

package/src/types.ts

@@ -21,12 +21,15 @@ export type SignalStatus = "SUCCESS" | "FAILURE" | "PENDING";
 /**
  * Token counts for a signal. `input` and `output` are required — every metered
  * call has them, and the server requires them. `cache` (provider-specific
- * prompt-cache reads) is optional and defaults to 0 server-side when omitted.
+ * prompt-cache reads) and `cacheWrite` (tokens written into the prompt cache,
+ * priced at the model's separate cache-write rate) are optional and default to
+ * 0 server-side when omitted.
  */
 export interface Tokens {
   input: number;
   output: number;
   cache?: number;
+  cacheWrite?: number;
 }
 
 /**
@@ -273,7 +276,10 @@ export interface SerializedUsageLog {
   member: string | null;
   inputTokens: number;
   outputTokens: number;
+  /** Cache-read tokens. */
   cacheTokens: number;
+  /** Cache-write tokens, priced separately from cache reads. */
+  cacheWriteTokens: number;
   /** Total credits deducted: the call's real per-model provider cost as a
    *  fraction of the credit's base price (i.e. cost + your margin), plus any
    *  credit-rule add-ons; 0 for wallet-money calls. */
@@ -431,7 +437,14 @@ export interface UsageLogEntry {
   typeName: string | null;
   member: string | null;
   model: { name: string | null; provider: string | null } | null;
-  usage: { inputTokens: number; outputTokens: number; cacheTokens: number };
+  usage: {
+    inputTokens: number;
+    outputTokens: number;
+    /** Cache-read tokens. */
+    cacheTokens: number;
+    /** Cache-write tokens, priced separately from cache reads. */
+    cacheWriteTokens: number;
+  };
   /** Formatted USD strings (e.g. `"$0.0064"`). */
   cost: { providedCost: string; customerCost: string };
   /** Populated only when `kind === "credit"`. `amount` is a formatted credit
@@ -564,20 +577,45 @@ export interface UnitBalance {
   remaining: number;
 }
 
-/** Wallet / credit / outcome / unit balances for a customer's active plan
- *  (`customers.balances()`). */
+/** One prepaid (ADVANCE) composite pool on a customer's plan. */
+export interface CompositeBalance {
+  compositeId: string;
+  /** The tag signals send in their `composite` block. */
+  refId: string;
+  name: string;
+  /** The pool size the plan grants this cycle. */
+  granted: number;
+  /** Slots claimed this cycle — one per distinct tag value. */
+  used: number;
+  /** `granted - used` plus this cycle's manual adjustments. May be negative:
+   *  running past the pool is allowed and carries into the next cycle. */
+  remaining: number;
+  /** What `granted` was before the pool was ever resized for this customer;
+   *  `null` if it never was. */
+  originalGranted: number | null;
+}
+
+/** Wallet / credit / outcome / unit balances and composite pools for a
+ *  customer's active plan (`customers.balances()`). */
 export interface CustomerBalances {
   customerId: string;
   currency: { code: string; rateUsd: number };
   hasPlan: boolean;
-  /** `null` when the plan has no Wallet component. */
-  wallet: { balanceUsd: number } | null;
-  /** The Reserved Wallet; `null` when the org hasn't enabled it. Independent
-   *  of `wallet` — present whether or not the plan has a Wallet. */
-  reservedWallet: { balanceUsd: number } | null;
+  /** Both wallet balances, in USD. Always present. */
+  wallet: {
+    /** The ordinary wallet — always reported, also when the plan has no
+     *  Wallet component or there's no plan. May be negative. */
+    balance: number;
+    /** The Reserved Wallet; absent when the org hasn't enabled it, otherwise
+     *  present whether or not the plan has a Wallet. Never negative. */
+    reservedBalance?: number;
+  };
   credits: CreditBalance[];
   outcomes: OutcomeBalance[];
   units: UnitBalance[];
+  /** ADVANCE composite pools. A composite billed in ARREAR has no pool and
+   *  isn't listed. */
+  composites: CompositeBalance[];
 }
 
 /** The customer's active plan (the `plan` field of `customers.plan()`);
@@ -626,13 +664,12 @@ export interface PortalToken {
 // Plans
 // ---------------------------------------------------------------------------
 
-/** How often a plan bills. `FREE` is a one-time grant; `EVERY_5_MIN` is a test cadence. */
+/** How often a plan bills. `FREE` is a one-time grant. */
 export type BillingCycle =
   | "MONTHLY"
   | "QUARTERLY"
   | "SEMI_ANNUAL"
   | "YEARLY"
-  | "EVERY_5_MIN"
   | "FREE";
 export type PlanType = "WALLET" | "BUNDLE";
 export type PlanKind = "FLAT_PRICE" | "PAY_AS_YOU_GO" | "PAY_PER_SEAT";
@@ -654,7 +691,8 @@ export type ComponentType =
 /** ADVANCE bills up-front for the cycle; ARREAR bills for what was consumed. */
 export type BillingMode = "ADVANCE" | "ARREAR";
 
-export interface PlanComponent {
+/** One line of a plan (`plan.entitlements[]`). */
+export interface PlanEntitlement {
   id: string;
   type: ComponentType;
   billingMode: BillingMode;
@@ -667,14 +705,19 @@ export interface PlanComponent {
   targetName: string | null;
   quantity: number | null;
   amount: number | null;
+  /** ADVANCE credit / outcome / composite / wallet components: what's left at
+   *  the end of a cycle carries into the next one instead of resetting.
+   *  Always false for unit, flat and ARREAR components and on FREE plans. */
+  rollover: boolean;
 }
 
+/** @deprecated Renamed to {@link PlanEntitlement} — a plan's lines are `entitlements` now. */
+export type PlanComponent = PlanEntitlement;
+
 export interface Plan {
   id: string;
   name: string;
   description: string | null;
-  type: PlanType;
-  kind: PlanKind;
   billingCycle: BillingCycle;
   cost: number;
   /** Signed adjustment applied to the plan's headline price (default 0). */
@@ -682,11 +725,290 @@ export interface Plan {
   /** When true, ARREAR consumption is funded from the customer's wallet as it
    *  happens instead of being invoiced at cycle end. All-or-nothing per plan. */
   walletFundedArrear: boolean;
+  /** The workspace's primary currency when the plan was created. */
   currencyCode: string;
   isActive: boolean;
-  components: PlanComponent[];
+  createdAt: string;
+  updatedAt: string;
+  /** The plan's lines — what a customer on it is granted or metered for. */
+  entitlements: PlanEntitlement[];
+}
+
+/** One line of a plan, as you send it to `plans.create()` / `plans.update()`.
+ *  Set the id that matches `type`: `creditId` (CREDIT), `outcomeId`
+ *  (OUTCOME), `unitId` (UNIT) or `compositeId` (PRICING_METRIC — a
+ *  composite). The lines `plans.get()` returns can be sent back as they are. */
+export interface PlanEntitlementInput {
+  type: ComponentType;
+  billingMode: BillingMode;
+  creditId?: string | null;
+  outcomeId?: string | null;
+  unitId?: string | null;
+  compositeId?: string | null;
+  /** ADVANCE credit / outcome / unit / composite: granted each cycle (0 allowed). */
+  quantity?: number | null;
+  /** WALLET (ADVANCE prepaid balance, $0 allowed) or FLAT (fee, above $0), in USD. */
+  amount?: number | null;
+  /** ADVANCE credit / outcome / composite / wallet: carry leftovers into the next cycle. */
+  rollover?: boolean;
+}
+
+/** `plans.create()` body. The plan's currency is the workspace's primary
+ *  currency — it can't be chosen. A new plan is active; retire it with
+ *  `plans.archive()`. */
+export interface CreatePlanInput {
+  name: string;
+  billingCycle: BillingCycle;
+  description?: string | null;
+  /** Pay ARREAR usage from the prepaid wallet as it happens. Needs an ADVANCE
+   *  WALLET line and at least one ARREAR credit / outcome / unit / composite. */
+  walletFundedArrear?: boolean;
+  /** Signed rounding nudge (USD) on the due-at-purchase total. */
+  priceAdjustment?: number;
+  /** At least one line. At most one WALLET and one FLAT. */
+  entitlements: PlanEntitlementInput[];
+}
+
+/** `plans.update()` body — a PARTIAL update: only the fields you send change.
+ *  `entitlements`, when sent, is the complete new list. */
+export type UpdatePlanInput = Partial<CreatePlanInput>;
+
+// ---------------------------------------------------------------------------
+// Catalogue: credits, outcomes, units, composites
+//
+// Every catalogue resource has the same six calls — list, get, create,
+// update (a PARTIAL update: only the fields you send change), archive and
+// unarchive — and NO delete: the API never deletes catalogue items, so usage
+// history never loses what it points at. Archiving is the only way to retire
+// one, and `isActive` is read-only.
+// ---------------------------------------------------------------------------
+
+/** One model line of a credit's / outcome step's pricing bundle, as returned. */
+export interface ModelBundleLine {
+  /** The model's id — the same one a usage signal sends as `usage.model`.
+   *  `null` only when the model was removed from the workspace after this
+   *  bundle was saved (the line keeps its name and stored price). */
+  modelId: string | null;
+  /** The model's display name, filled in by the server. */
+  modelName: string;
+  /** Average tokens one LLM call uses on this model. */
+  averageTokensPerLLMCall: number;
+  /** Whole-percent split of those tokens; the four add up to 100. */
+  input: number;
+  output: number;
+  cache: number;
+  /** 0 on a model with no cache-write price. */
+  cacheWrite: number;
+}
+
+/** One model line as you send it. Several lines (one per model) are allowed;
+ *  the price is the sum of their costs, worked out on the server from the
+ *  models' live prices. */
+export interface ModelBundleLineInput {
+  /** The model's id, e.g. `"gpt-4o"` — the same one a usage signal sends as
+   *  `usage.model`. Matched ignoring case; it must be enabled in your
+   *  workspace. */
+  modelId: string;
+  /** Above 0. */
+  averageTokensPerLLMCall: number;
+  input: number;
+  output: number;
+  cache: number;
+  /** Default 0. Only on a model that has a cache-write price. */
+  cacheWrite?: number;
+}
+
+/** A credit — a token-metered entitlement your product draws down by its
+ *  `agentKey`. */
+export interface Credit {
+  id: string;
+  name: string;
+  /** What a credit signal names; unique in the workspace. */
+  agentKey: string;
+  description: string | null;
+  /** Sum of the bundle lines' tokens (display figure). */
+  tokensPerCredit: number;
+  /** Cost of one credit, worked out from `modelBundle`. */
+  basePrice: number;
+  modelBundle: ModelBundleLine[];
+  marginPercent: number;
+  /** `basePrice` plus the margin — what a customer pays per credit. */
+  pricePerCredit: number;
+  isActive: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** `credits.create()` body. The price is always worked out on the server from
+ *  `modelBundle` — it is never typed in. */
+export interface CreateCreditInput {
+  name: string;
+  agentKey: string;
+  /** -100 or more. */
+  marginPercent: number;
+  /** At least one line. */
+  modelBundle: ModelBundleLineInput[];
+  description?: string | null;
+}
+
+/** `credits.update()` body — PARTIAL. Send `modelBundle` to re-price; leave it
+ *  out to keep the stored base price (a new margin is applied on top). */
+export type UpdateCreditInput = Partial<CreateCreditInput>;
+
+/** An outcome — a multi-step deliverable billed per completed outcome. */
+export interface Outcome {
+  id: string;
+  name: string;
+  /** The outcome's own key (unique in the workspace) — not what a step signal
+   *  names; each step has its own `agentKey`. */
+  agentKey: string;
+  description: string | null;
+  isActive: boolean;
+  /** Sum of the steps' base prices. */
+  basePrice: number;
+  marginPercent: number;
+  pricePerOutcome: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** One step of an outcome. */
+export interface OutcomeStep {
+  /** Send it back on `outcomes.update()` to keep this step. */
+  id: string;
+  name: string;
+  /** What an outcome step signal names; unique in the workspace. */
+  agentKey: string;
+  order: number;
+  basePrice: number;
+  modelBundle: ModelBundleLine[];
+}
+
+/** `outcomes.get()` — the outcome with its steps in full. */
+export interface OutcomeWithSteps extends Outcome {
+  steps: OutcomeStep[];
+}
+
+/** One step as you send it. */
+export interface OutcomeStepInput {
+  /** An existing step's id, to keep that step (update only). A step sent
+   *  without an id but with an existing step's `agentKey` is that step too. */
+  id?: string;
+  name: string;
+  agentKey: string;
+  /** Required for a new step. Leave it out on an existing step to keep its
+   *  price. */
+  modelBundle?: ModelBundleLineInput[];
+}
+
+/** `outcomes.create()` body. */
+export interface CreateOutcomeInput {
+  name: string;
+  agentKey: string;
+  /** -100 or more. */
+  marginPercent: number;
+  /** 1–50 steps; names and agent keys unique. */
+  steps: OutcomeStepInput[];
+  description?: string | null;
+}
+
+/** `outcomes.update()` body — PARTIAL. Leave `steps` out to leave the steps
+ *  alone; send it and it is the complete step list (stored steps left out are
+ *  removed). */
+export type UpdateOutcomeInput = Partial<CreateOutcomeInput>;
+
+/** How a unit is priced. */
+export type UnitPricingType = "FLAT" | "SLAB" | "VOLUME";
+
+/** One price band of a SLAB / VOLUME unit. */
+export interface UnitTier {
+  id: string;
+  /** Inclusive upper bound; `null` on the last tier ("and above"). */
+  upTo: number | null;
+  /** Per-unit price for this band. */
+  price: number;
+  order: number;
+}
+
+/** A unit — a fixed-price, non-LLM event (an upload, a seat, an API call). */
+export interface Unit {
+  id: string;
+  name: string;
+  /** What a unit signal names; unique in the workspace. */
+  agentKey: string;
+  description: string | null;
+  pricingType: UnitPricingType;
+  /** FLAT only. */
+  flatPrice: number;
+  /** SLAB / VOLUME only. */
+  tiers: UnitTier[];
+  isActive: boolean;
+  createdAt: string;
+  updatedAt: string;
+  createdByName: string | null;
+}
+
+/** `units.create()` body. */
+export interface CreateUnitInput {
+  name: string;
+  agentKey: string;
+  pricingType: UnitPricingType;
+  /** FLAT only. */
+  flatPrice?: number;
+  /** SLAB / VOLUME: 1–50 tiers, `upTo` rising; the last one `upTo: null`. */
+  tiers?: { upTo: number | null; price: number }[];
+  description?: string | null;
+}
+
+/** `units.update()` body — PARTIAL. `tiers`, when sent, is the complete list. */
+export type UpdateUnitInput = Partial<CreateUnitInput>;
+
+/** A catalogue item a composite wraps. */
+export interface CompositeItem {
+  id: string;
+  name: string;
+  agentKey: string;
+}
+
+/** A composite — several credits / outcomes / units grouped under one tag and
+ *  billed as ONE thing, per completed occurrence, once a plan sells it. */
+export interface Composite {
+  id: string;
+  name: string;
+  /** The tag your signals send in their `composite` block. */
+  refId: string;
+  description: string | null;
+  /** USD per completed occurrence, once a plan sells it. */
+  price: number;
+  isActive: boolean;
+  createdAt: string;
+  updatedAt: string;
+  entitlements: {
+    credits: CompositeItem[];
+    outcomes: CompositeItem[];
+    units: CompositeItem[];
+  };
 }
 
+/** `composites.create()` body. */
+export interface CreateCompositeInput {
+  name: string;
+  refId: string;
+  price: number;
+  description?: string | null;
+  /** At least one id across the three lists. Every item must be active, and a
+   *  unit must be FLAT-priced. */
+  entitlements: {
+    creditIds?: string[];
+    outcomeIds?: string[];
+    unitIds?: string[];
+  };
+}
+
+/** `composites.update()` body — PARTIAL. `entitlements`, when sent, is the
+ *  complete new set. */
+export type UpdateCompositeInput = Partial<CreateCompositeInput>;
+
 // ---------------------------------------------------------------------------
 // Purchases (subscriptions)
 // ---------------------------------------------------------------------------
@@ -948,11 +1270,12 @@ export interface UpdateMemberInput {
 // ---------------------------------------------------------------------------
 
 /**
- * Which of a customer's two wallet balances an entry moves: `MAIN` (the
- * ordinary wallet) or `RESERVED` (the Reserved Wallet — an org-gated second
- * balance behind it; see {@link WalletAdjustInput.pool}).
+ * Which of a customer's two wallet balances an entry moves: `"main"` (the
+ * ordinary wallet) or `"reserved"` (the Reserved Wallet — an org-gated second
+ * balance behind it; see {@link WalletAdjustInput.pool}). Lowercase only —
+ * the API refuses `"MAIN"` / `"RESERVED"`.
  */
-export type WalletPool = "MAIN" | "RESERVED";
+export type WalletPool = "main" | "reserved";
 
 /** Top up (positive) or draw down (negative) a customer's wallet. `delta` is
  *  a non-zero amount in USD (cents allowed); absolute value ≤ 10,000,000. No
@@ -964,16 +1287,17 @@ export interface WalletAdjustInput {
   delta: number;
   notes?: string;
   /**
-   * Which balance to move. Default `"MAIN"`, the ordinary wallet.
+   * Which balance to move. Default `"main"`, the ordinary wallet (leave it
+   * out; `null` is refused).
    *
-   * `"RESERVED"` moves the Reserved Wallet instead — a second balance behind
+   * `"reserved"` moves the Reserved Wallet instead — a second balance behind
    * the wallet that a wallet-funded Arrear charge draws on once the wallet
    * runs out (Wallet → Reserved down to 0 → Wallet goes negative). It must be
    * switched on for the org (Settings → Organisation → "Enable Reserved
    * balance in wallet"), else this is a `PlanError`. It never goes negative:
    * a reduce below zero is refused (an `AllowanceError`), not capped — drawing
    * down to exactly 0 is fine. `remaining` is then the Reserved balance. A
-   * `"MAIN"` adjustment never touches it.
+   * `"main"` adjustment never touches it.
    */
   pool?: WalletPool;
   /**