@clocknext/sdk 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -8,12 +8,44 @@
  */
 type SignalType = "wallet" | "credit" | "outcome";
 type SignalStatus = "SUCCESS" | "FAILURE" | "PENDING";
-/** Token counts for a signal. All default to 0. */
+/**
+ * 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.
+ */
 interface Tokens {
-    input?: number;
-    output?: number;
+    input: number;
+    output: number;
     cache?: number;
 }
+/** The organisation + key behind a request — `cnk.workspace.me()`. */
+interface WorkspaceIdentity {
+    organization: {
+        id: string;
+        name: string;
+        slug: string | null;
+        /** `sandbox` is a disposable staging twin; `live` bills for real. Check
+         *  this before sending production traffic. */
+        environment: "sandbox" | "live";
+    };
+    apiKey: {
+        prefix: string;
+        lastFour: string;
+        expiresAt: string | null;
+    } | null;
+}
+/** One model the org has enabled — `cnk.workspace.models()`. The `modelId` is
+ *  what you put in a signal's `model`. Prices are USD per 1,000,000 tokens. */
+interface Model {
+    modelId: string;
+    modelName: string;
+    provider: string;
+    providerName: string;
+    isActive: boolean;
+    inputPrice: number;
+    outputPrice: number;
+    cachePrice: number;
+}
 interface SignalBase {
     /** The customer this usage belongs to (required). */
     customerId: string;
@@ -22,14 +54,21 @@ interface SignalBase {
      * (Settings → Models). Matched case-insensitively against `OrgModel.modelId`.
      */
     model: string;
-    /** Token counts for this call. */
-    tokens?: Tokens;
+    /** Token counts for this call — required; every metered signal is priced on
+     *  tokens. (`cache` within is optional; `input`/`output` are not.) */
+    tokens: Tokens;
     /** Optional member (email) this usage is attributed to. */
     member?: string;
-    /** Defaults to SUCCESS. */
-    status?: SignalStatus;
     /** Free-form metadata. Credit rules can target `custom.<key>` paths. */
     custom?: Record<string, unknown>;
+    /**
+     * Idempotency key for safe retries. **Auto-generated (UUID v4) if omitted**
+     * and reused across every retry of this signal, so a retried send is
+     * deduplicated server-side instead of double-recording. Supply your own — a
+     * stable id for this logical event — to also dedup across process restarts or
+     * at-least-once redelivery, which an in-memory auto key can't survive.
+     */
+    idempotencyKey?: string;
 }
 /** Meters a credit, identified by the credit's stable `agentKey`. */
 interface CreditSignal extends SignalBase {
@@ -150,9 +189,10 @@ interface CustomerProfileInput {
     /** ISO 4217 (3 letters); must be enabled for the org. */
     currencyCode?: string;
 }
-/** `name` is required on create. */
+/** `name` and `email` are required on create; every other field is optional. */
 type CreateCustomerInput = CustomerProfileInput & {
     name: string;
+    email: string;
 };
 interface CustomerList {
     customers: ApiCustomer[];
@@ -219,18 +259,68 @@ type PlanKind = "FLAT_PRICE" | "PAY_AS_YOU_GO" | "PAY_PER_SEAT";
 type ComponentType = "WALLET" | "CREDIT" | "OUTCOME" | "UNIT" | "FLAT";
 /** ADVANCE bills up-front for the cycle; ARREAR bills for what was consumed. */
 type BillingMode = "ADVANCE" | "ARREAR";
-/** One entitlement line in a plan. Set the id matching `type` (creditId for CREDIT, …). */
-interface PlanComponentInput {
-    type: ComponentType;
+/** Prepaid USD wallet. `amount` is the funded balance (required). Max one
+ *  wallet component per plan. */
+interface WalletComponentInput {
+    type: "WALLET";
     billingMode: BillingMode;
-    creditId?: string | null;
-    outcomeId?: string | null;
-    unitId?: string | null;
-    /** Granted quantity (ADVANCE components). */
-    quantity?: number | null;
-    /** Flat amount (FLAT / WALLET components). */
-    amount?: number | null;
+    amount: number;
+}
+/** A one-off flat fee — `amount` is required. Max one flat component per plan;
+ *  not allowed on FREE plans. */
+interface FlatComponentInput {
+    type: "FLAT";
+    billingMode: BillingMode;
+    amount: number;
 }
+/** A credit entitlement, referenced by `creditId`. Billed ADVANCE it needs a
+ *  granted `quantity`; billed ARREAR it meters usage with no upfront grant. */
+type CreditComponentInput = {
+    type: "CREDIT";
+    billingMode: "ADVANCE";
+    creditId: string;
+    quantity: number;
+} | {
+    type: "CREDIT";
+    billingMode: "ARREAR";
+    creditId: string;
+    quantity?: number | null;
+};
+/** An outcome entitlement, referenced by `outcomeId`. ADVANCE needs a granted
+ *  `quantity`; ARREAR meters usage. */
+type OutcomeComponentInput = {
+    type: "OUTCOME";
+    billingMode: "ADVANCE";
+    outcomeId: string;
+    quantity: number;
+} | {
+    type: "OUTCOME";
+    billingMode: "ARREAR";
+    outcomeId: string;
+    quantity?: number | null;
+};
+/** A unit entitlement, referenced by `unitId`. ADVANCE needs a granted
+ *  `quantity`; ARREAR meters usage. */
+type UnitComponentInput = {
+    type: "UNIT";
+    billingMode: "ADVANCE";
+    unitId: string;
+    quantity: number;
+} | {
+    type: "UNIT";
+    billingMode: "ARREAR";
+    unitId: string;
+    quantity?: number | null;
+};
+/**
+ * One entitlement line in a plan — a discriminated union on `type` (and, where
+ * it matters, `billingMode`) so the per-type fields the server requires are
+ * enforced at compile time instead of surfacing as runtime 422s:
+ *   - CREDIT / OUTCOME / UNIT require their matching id;
+ *   - CREDIT / OUTCOME / UNIT require `quantity` when billed ADVANCE;
+ *   - WALLET / FLAT require `amount`.
+ */
+type PlanComponentInput = WalletComponentInput | FlatComponentInput | CreditComponentInput | OutcomeComponentInput | UnitComponentInput;
 interface CreatePlanInput {
     name: string;
     description?: string | null;
@@ -543,7 +633,8 @@ interface UnitAdjustInput {
 /** A per-model token bundle attached to a credit or outcome step. */
 interface ModelBundleEntry {
     orgModelId: string;
-    modelName: string;
+    /** Display label; the server defaults it from the model when omitted. */
+    modelName?: string;
     tokens: number;
     input: number;
     output: number;
@@ -671,25 +762,50 @@ interface UnitDetail extends Unit {
     /** First page (≤10) of customers currently metered on this unit. */
     customers: Record<string, unknown>[];
 }
-interface CreateUnitInput {
+/** Flat per-event pricing — a single `flatPrice` (defaults to 0), no tiers. */
+interface FlatUnitInput {
     name: string;
-    pricingType: UnitPricingType;
-    /** Required for FLAT pricing. */
+    /** Stable per-org report key (`signals.unit({ agentKey })`); `[a-z0-9._-]`. */
+    agentKey: string;
+    pricingType: "FLAT";
+    /** Price per event; defaults to 0. */
     flatPrice?: number;
-    /** Required for SLAB/VOLUME pricing (≤50 tiers). */
-    tiers?: UnitTierInput[];
     description?: string | null;
     isActive?: boolean;
 }
+/** Tiered pricing (SLAB or VOLUME) — at least one tier is required. */
+interface TieredUnitInput {
+    name: string;
+    /** Stable per-org report key (`signals.unit({ agentKey })`); `[a-z0-9._-]`. */
+    agentKey: string;
+    pricingType: "SLAB" | "VOLUME";
+    /** At least one tier (≤50). Only the last tier may have `upTo: null`. */
+    tiers: UnitTierInput[];
+    description?: string | null;
+    isActive?: boolean;
+}
+/**
+ * Create a unit type — a discriminated union on `pricingType`: `FLAT` takes an
+ * optional `flatPrice` (defaults to 0); `SLAB`/`VOLUME` require `tiers`, so the
+ * server's "add at least one tier" rule is enforced at compile time.
+ */
+type CreateUnitInput = FlatUnitInput | TieredUnitInput;
 type UpdateUnitInput = CreateUnitInput;
-/** Record one unit-metered event. `unit` matches a catalog unit name (case-insensitive). */
+/**
+ * Record one unit-metered event. The unit is addressed by its `agentKey` (the
+ * stable key set when the unit was created) — the ONLY accepted identifier;
+ * the display name is deliberately not accepted, so a rename can never redirect
+ * a live integration. Keys are matched exactly (they are stored lowercased).
+ */
 interface UnitInput {
     customerId: string;
-    unit: string;
+    agentKey: string;
     member?: string;
 }
 interface UnitUsageRow {
     unit: string;
+    /** The unit's stable agent key — what to send to report against it. */
+    agentKey: string | null;
     billingMode: BillingMode;
     granted?: number;
     used: number;
@@ -918,10 +1034,6 @@ declare class Customers {
         transaction: WalletTransaction;
         balanceUsd: number;
     }>;
-    /** Set the customer's currency. `PUT …/:id/currency`. */
-    setCurrency(id: string, currencyCode: string): Promise<void>;
-    /** Set which credit types the customer is billed against. `PUT …/:id/credits`. */
-    setCreditTypes(id: string, creditIds: string[]): Promise<void>;
     /** Grant or claw back a credit balance. `POST …/:id/credits/adjust`. */
     adjustCredit(id: string, input: CreditAdjustInput): Promise<void>;
     /** Grant or claw back an outcome balance. Returns the remaining balance. */
@@ -1122,6 +1234,12 @@ declare class Signals {
     track(signal: Signal, opts?: {
         wait?: boolean;
     }): Promise<TrackResult>;
+    /**
+     * Validate + price a signal WITHOUT recording it (server `dryRun`). Returns
+     * the projected usage log so an integration can preflight before sending real
+     * traffic — no inbox row, wallet / outcome writes, or webhooks fire.
+     */
+    verify(signal: Signal): Promise<SerializedUsageLog | null>;
     /** Meter a named credit. */
     credit(input: CreditInput, opts?: {
         wait?: boolean;
@@ -1140,9 +1258,9 @@ declare class Signals {
         limit?: number;
     }): Promise<UsageList>;
     /**
-     * Record one unit-metered event (a fixed-price meter with no tokens), matched
-     * to a catalog unit by name. Sent immediately — unit events are not buffered.
-     * `POST /api/v1/units`.
+     * Record one unit-metered event (a fixed-price meter with no tokens),
+     * addressed to a catalog unit by its `agentKey`. Sent immediately — unit
+     * events are not buffered. `POST /api/v1/units`.
      */
     unit(input: UnitInput): Promise<{
         unitUsage: Record<string, unknown>;
@@ -1193,6 +1311,23 @@ declare class Webhooks {
     delete(kind: ThresholdKind): Promise<void>;
 }
 
+/**
+ * The `workspace` resource — read-only introspection of the org behind the API
+ * key. Grounds an integration (which workspace, and is it `sandbox` or `live`?)
+ * and lists the models it may meter against. `/api/v1/me`, `/api/v1/models`.
+ */
+declare class Workspace {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** Identify the org + key behind the request, incl. `sandbox` | `live`. */
+    me(): Promise<WorkspaceIdentity>;
+    /** The org's enabled models with live prices. `{ active: true }` returns only
+     *  the models that can be metered right now. */
+    models(params?: {
+        active?: boolean;
+    }): Promise<Model[]>;
+}
+
 /**
  * The ClockNext client.
  *
@@ -1233,6 +1368,8 @@ declare class ClockNext {
     readonly webhooks: Webhooks;
     /** Mint customer-portal embed tokens. */
     readonly portal: Portal;
+    /** Identify the workspace (sandbox/live) + list its models. `/me`, `/models`. */
+    readonly workspace: Workspace;
     private readonly cfg;
     private readonly flusher;
     constructor(config: ClockNextConfig);
@@ -1293,4 +1430,4 @@ declare class NetworkError extends ClockNextError {
     constructor(message: string);
 }
 
-export { type AddMemberInput, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ComponentType, ConflictError, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditDetail, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerProfileInput, type CustomerRevenue, type DropReason, type FetchLike, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberRole, type ModelBundleEntry, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeDetail, type OutcomeInput, type OutcomeSignal, type OutcomeStepInput, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanComponentInput, type PlanDetail, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RevenueRange, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUsageLog, ServerError, type Signal, type SignalStatus, type SignalType, type ThresholdKind, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitDetail, type UnitInput, type UnitPricingType, type UnitTier, type UnitTierInput, type UnitUsageList, type UnitUsageRow, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateUnitInput, type UpsertWebhookInput, type UsageList, ValidationError, type WalletEntryInput, type WalletInput, type WalletList, type WalletSignal, type WalletTransaction, type WalletTransactionType, type Webhook, signalToWire };
+export { type AddMemberInput, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ComponentType, ConflictError, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditComponentInput, type CreditDetail, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerProfileInput, type CustomerRevenue, type DropReason, type FetchLike, type FlatComponentInput, type FlatUnitInput, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberRole, type Model, type ModelBundleEntry, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeComponentInput, type OutcomeDetail, type OutcomeInput, type OutcomeSignal, type OutcomeStepInput, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanComponentInput, type PlanDetail, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RevenueRange, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUsageLog, ServerError, type Signal, type SignalStatus, type SignalType, type ThresholdKind, type TieredUnitInput, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitComponentInput, type UnitDetail, type UnitInput, type UnitPricingType, type UnitTier, type UnitTierInput, type UnitUsageList, type UnitUsageRow, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateUnitInput, type UpsertWebhookInput, type UsageList, ValidationError, type WalletComponentInput, type WalletEntryInput, type WalletInput, type WalletList, type WalletSignal, type WalletTransaction, type WalletTransactionType, type Webhook, type WorkspaceIdentity, signalToWire };

package/dist/index.d.ts

@@ -8,12 +8,44 @@
  */
 type SignalType = "wallet" | "credit" | "outcome";
 type SignalStatus = "SUCCESS" | "FAILURE" | "PENDING";
-/** Token counts for a signal. All default to 0. */
+/**
+ * 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.
+ */
 interface Tokens {
-    input?: number;
-    output?: number;
+    input: number;
+    output: number;
     cache?: number;
 }
+/** The organisation + key behind a request — `cnk.workspace.me()`. */
+interface WorkspaceIdentity {
+    organization: {
+        id: string;
+        name: string;
+        slug: string | null;
+        /** `sandbox` is a disposable staging twin; `live` bills for real. Check
+         *  this before sending production traffic. */
+        environment: "sandbox" | "live";
+    };
+    apiKey: {
+        prefix: string;
+        lastFour: string;
+        expiresAt: string | null;
+    } | null;
+}
+/** One model the org has enabled — `cnk.workspace.models()`. The `modelId` is
+ *  what you put in a signal's `model`. Prices are USD per 1,000,000 tokens. */
+interface Model {
+    modelId: string;
+    modelName: string;
+    provider: string;
+    providerName: string;
+    isActive: boolean;
+    inputPrice: number;
+    outputPrice: number;
+    cachePrice: number;
+}
 interface SignalBase {
     /** The customer this usage belongs to (required). */
     customerId: string;
@@ -22,14 +54,21 @@ interface SignalBase {
      * (Settings → Models). Matched case-insensitively against `OrgModel.modelId`.
      */
     model: string;
-    /** Token counts for this call. */
-    tokens?: Tokens;
+    /** Token counts for this call — required; every metered signal is priced on
+     *  tokens. (`cache` within is optional; `input`/`output` are not.) */
+    tokens: Tokens;
     /** Optional member (email) this usage is attributed to. */
     member?: string;
-    /** Defaults to SUCCESS. */
-    status?: SignalStatus;
     /** Free-form metadata. Credit rules can target `custom.<key>` paths. */
     custom?: Record<string, unknown>;
+    /**
+     * Idempotency key for safe retries. **Auto-generated (UUID v4) if omitted**
+     * and reused across every retry of this signal, so a retried send is
+     * deduplicated server-side instead of double-recording. Supply your own — a
+     * stable id for this logical event — to also dedup across process restarts or
+     * at-least-once redelivery, which an in-memory auto key can't survive.
+     */
+    idempotencyKey?: string;
 }
 /** Meters a credit, identified by the credit's stable `agentKey`. */
 interface CreditSignal extends SignalBase {
@@ -150,9 +189,10 @@ interface CustomerProfileInput {
     /** ISO 4217 (3 letters); must be enabled for the org. */
     currencyCode?: string;
 }
-/** `name` is required on create. */
+/** `name` and `email` are required on create; every other field is optional. */
 type CreateCustomerInput = CustomerProfileInput & {
     name: string;
+    email: string;
 };
 interface CustomerList {
     customers: ApiCustomer[];
@@ -219,18 +259,68 @@ type PlanKind = "FLAT_PRICE" | "PAY_AS_YOU_GO" | "PAY_PER_SEAT";
 type ComponentType = "WALLET" | "CREDIT" | "OUTCOME" | "UNIT" | "FLAT";
 /** ADVANCE bills up-front for the cycle; ARREAR bills for what was consumed. */
 type BillingMode = "ADVANCE" | "ARREAR";
-/** One entitlement line in a plan. Set the id matching `type` (creditId for CREDIT, …). */
-interface PlanComponentInput {
-    type: ComponentType;
+/** Prepaid USD wallet. `amount` is the funded balance (required). Max one
+ *  wallet component per plan. */
+interface WalletComponentInput {
+    type: "WALLET";
     billingMode: BillingMode;
-    creditId?: string | null;
-    outcomeId?: string | null;
-    unitId?: string | null;
-    /** Granted quantity (ADVANCE components). */
-    quantity?: number | null;
-    /** Flat amount (FLAT / WALLET components). */
-    amount?: number | null;
+    amount: number;
+}
+/** A one-off flat fee — `amount` is required. Max one flat component per plan;
+ *  not allowed on FREE plans. */
+interface FlatComponentInput {
+    type: "FLAT";
+    billingMode: BillingMode;
+    amount: number;
 }
+/** A credit entitlement, referenced by `creditId`. Billed ADVANCE it needs a
+ *  granted `quantity`; billed ARREAR it meters usage with no upfront grant. */
+type CreditComponentInput = {
+    type: "CREDIT";
+    billingMode: "ADVANCE";
+    creditId: string;
+    quantity: number;
+} | {
+    type: "CREDIT";
+    billingMode: "ARREAR";
+    creditId: string;
+    quantity?: number | null;
+};
+/** An outcome entitlement, referenced by `outcomeId`. ADVANCE needs a granted
+ *  `quantity`; ARREAR meters usage. */
+type OutcomeComponentInput = {
+    type: "OUTCOME";
+    billingMode: "ADVANCE";
+    outcomeId: string;
+    quantity: number;
+} | {
+    type: "OUTCOME";
+    billingMode: "ARREAR";
+    outcomeId: string;
+    quantity?: number | null;
+};
+/** A unit entitlement, referenced by `unitId`. ADVANCE needs a granted
+ *  `quantity`; ARREAR meters usage. */
+type UnitComponentInput = {
+    type: "UNIT";
+    billingMode: "ADVANCE";
+    unitId: string;
+    quantity: number;
+} | {
+    type: "UNIT";
+    billingMode: "ARREAR";
+    unitId: string;
+    quantity?: number | null;
+};
+/**
+ * One entitlement line in a plan — a discriminated union on `type` (and, where
+ * it matters, `billingMode`) so the per-type fields the server requires are
+ * enforced at compile time instead of surfacing as runtime 422s:
+ *   - CREDIT / OUTCOME / UNIT require their matching id;
+ *   - CREDIT / OUTCOME / UNIT require `quantity` when billed ADVANCE;
+ *   - WALLET / FLAT require `amount`.
+ */
+type PlanComponentInput = WalletComponentInput | FlatComponentInput | CreditComponentInput | OutcomeComponentInput | UnitComponentInput;
 interface CreatePlanInput {
     name: string;
     description?: string | null;
@@ -543,7 +633,8 @@ interface UnitAdjustInput {
 /** A per-model token bundle attached to a credit or outcome step. */
 interface ModelBundleEntry {
     orgModelId: string;
-    modelName: string;
+    /** Display label; the server defaults it from the model when omitted. */
+    modelName?: string;
     tokens: number;
     input: number;
     output: number;
@@ -671,25 +762,50 @@ interface UnitDetail extends Unit {
     /** First page (≤10) of customers currently metered on this unit. */
     customers: Record<string, unknown>[];
 }
-interface CreateUnitInput {
+/** Flat per-event pricing — a single `flatPrice` (defaults to 0), no tiers. */
+interface FlatUnitInput {
     name: string;
-    pricingType: UnitPricingType;
-    /** Required for FLAT pricing. */
+    /** Stable per-org report key (`signals.unit({ agentKey })`); `[a-z0-9._-]`. */
+    agentKey: string;
+    pricingType: "FLAT";
+    /** Price per event; defaults to 0. */
     flatPrice?: number;
-    /** Required for SLAB/VOLUME pricing (≤50 tiers). */
-    tiers?: UnitTierInput[];
     description?: string | null;
     isActive?: boolean;
 }
+/** Tiered pricing (SLAB or VOLUME) — at least one tier is required. */
+interface TieredUnitInput {
+    name: string;
+    /** Stable per-org report key (`signals.unit({ agentKey })`); `[a-z0-9._-]`. */
+    agentKey: string;
+    pricingType: "SLAB" | "VOLUME";
+    /** At least one tier (≤50). Only the last tier may have `upTo: null`. */
+    tiers: UnitTierInput[];
+    description?: string | null;
+    isActive?: boolean;
+}
+/**
+ * Create a unit type — a discriminated union on `pricingType`: `FLAT` takes an
+ * optional `flatPrice` (defaults to 0); `SLAB`/`VOLUME` require `tiers`, so the
+ * server's "add at least one tier" rule is enforced at compile time.
+ */
+type CreateUnitInput = FlatUnitInput | TieredUnitInput;
 type UpdateUnitInput = CreateUnitInput;
-/** Record one unit-metered event. `unit` matches a catalog unit name (case-insensitive). */
+/**
+ * Record one unit-metered event. The unit is addressed by its `agentKey` (the
+ * stable key set when the unit was created) — the ONLY accepted identifier;
+ * the display name is deliberately not accepted, so a rename can never redirect
+ * a live integration. Keys are matched exactly (they are stored lowercased).
+ */
 interface UnitInput {
     customerId: string;
-    unit: string;
+    agentKey: string;
     member?: string;
 }
 interface UnitUsageRow {
     unit: string;
+    /** The unit's stable agent key — what to send to report against it. */
+    agentKey: string | null;
     billingMode: BillingMode;
     granted?: number;
     used: number;
@@ -918,10 +1034,6 @@ declare class Customers {
         transaction: WalletTransaction;
         balanceUsd: number;
     }>;
-    /** Set the customer's currency. `PUT …/:id/currency`. */
-    setCurrency(id: string, currencyCode: string): Promise<void>;
-    /** Set which credit types the customer is billed against. `PUT …/:id/credits`. */
-    setCreditTypes(id: string, creditIds: string[]): Promise<void>;
     /** Grant or claw back a credit balance. `POST …/:id/credits/adjust`. */
     adjustCredit(id: string, input: CreditAdjustInput): Promise<void>;
     /** Grant or claw back an outcome balance. Returns the remaining balance. */
@@ -1122,6 +1234,12 @@ declare class Signals {
     track(signal: Signal, opts?: {
         wait?: boolean;
     }): Promise<TrackResult>;
+    /**
+     * Validate + price a signal WITHOUT recording it (server `dryRun`). Returns
+     * the projected usage log so an integration can preflight before sending real
+     * traffic — no inbox row, wallet / outcome writes, or webhooks fire.
+     */
+    verify(signal: Signal): Promise<SerializedUsageLog | null>;
     /** Meter a named credit. */
     credit(input: CreditInput, opts?: {
         wait?: boolean;
@@ -1140,9 +1258,9 @@ declare class Signals {
         limit?: number;
     }): Promise<UsageList>;
     /**
-     * Record one unit-metered event (a fixed-price meter with no tokens), matched
-     * to a catalog unit by name. Sent immediately — unit events are not buffered.
-     * `POST /api/v1/units`.
+     * Record one unit-metered event (a fixed-price meter with no tokens),
+     * addressed to a catalog unit by its `agentKey`. Sent immediately — unit
+     * events are not buffered. `POST /api/v1/units`.
      */
     unit(input: UnitInput): Promise<{
         unitUsage: Record<string, unknown>;
@@ -1193,6 +1311,23 @@ declare class Webhooks {
     delete(kind: ThresholdKind): Promise<void>;
 }
 
+/**
+ * The `workspace` resource — read-only introspection of the org behind the API
+ * key. Grounds an integration (which workspace, and is it `sandbox` or `live`?)
+ * and lists the models it may meter against. `/api/v1/me`, `/api/v1/models`.
+ */
+declare class Workspace {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** Identify the org + key behind the request, incl. `sandbox` | `live`. */
+    me(): Promise<WorkspaceIdentity>;
+    /** The org's enabled models with live prices. `{ active: true }` returns only
+     *  the models that can be metered right now. */
+    models(params?: {
+        active?: boolean;
+    }): Promise<Model[]>;
+}
+
 /**
  * The ClockNext client.
  *
@@ -1233,6 +1368,8 @@ declare class ClockNext {
     readonly webhooks: Webhooks;
     /** Mint customer-portal embed tokens. */
     readonly portal: Portal;
+    /** Identify the workspace (sandbox/live) + list its models. `/me`, `/models`. */
+    readonly workspace: Workspace;
     private readonly cfg;
     private readonly flusher;
     constructor(config: ClockNextConfig);
@@ -1293,4 +1430,4 @@ declare class NetworkError extends ClockNextError {
     constructor(message: string);
 }
 
-export { type AddMemberInput, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ComponentType, ConflictError, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditDetail, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerProfileInput, type CustomerRevenue, type DropReason, type FetchLike, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberRole, type ModelBundleEntry, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeDetail, type OutcomeInput, type OutcomeSignal, type OutcomeStepInput, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanComponentInput, type PlanDetail, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RevenueRange, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUsageLog, ServerError, type Signal, type SignalStatus, type SignalType, type ThresholdKind, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitDetail, type UnitInput, type UnitPricingType, type UnitTier, type UnitTierInput, type UnitUsageList, type UnitUsageRow, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateUnitInput, type UpsertWebhookInput, type UsageList, ValidationError, type WalletEntryInput, type WalletInput, type WalletList, type WalletSignal, type WalletTransaction, type WalletTransactionType, type Webhook, signalToWire };
+export { type AddMemberInput, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ComponentType, ConflictError, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditComponentInput, type CreditDetail, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerProfileInput, type CustomerRevenue, type DropReason, type FetchLike, type FlatComponentInput, type FlatUnitInput, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberRole, type Model, type ModelBundleEntry, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeComponentInput, type OutcomeDetail, type OutcomeInput, type OutcomeSignal, type OutcomeStepInput, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanComponentInput, type PlanDetail, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RevenueRange, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUsageLog, ServerError, type Signal, type SignalStatus, type SignalType, type ThresholdKind, type TieredUnitInput, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitComponentInput, type UnitDetail, type UnitInput, type UnitPricingType, type UnitTier, type UnitTierInput, type UnitUsageList, type UnitUsageRow, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateUnitInput, type UpsertWebhookInput, type UsageList, ValidationError, type WalletComponentInput, type WalletEntryInput, type WalletInput, type WalletList, type WalletSignal, type WalletTransaction, type WalletTransactionType, type Webhook, type WorkspaceIdentity, signalToWire };