@clocknext/sdk 0.3.0 → 0.5.0

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 {
@@ -64,6 +103,18 @@ interface SerializedOutcomeAttribution {
     progressSteps: string[];
     totalSteps: number;
 }
+/** The customer's remaining balance for the dimension a signal metered, AFTER
+ *  the signal was applied — update an on-screen meter straight from the record
+ *  response. Populated on recorded (inline / `{ wait: true }`) signals; `null`
+ *  on dry runs and on read-back. */
+interface UsageBalance {
+    dimension: "credit" | "outcome" | "wallet";
+    /** Post-signal remaining. `null` when the meter is uncapped — an ARREAR
+     *  (pay-as-you-go) credit or outcome has no fixed allowance. */
+    remaining: number | null;
+    /** The credit / outcome name; `null` for the wallet. */
+    name: string | null;
+}
 interface SerializedUsageLog {
     id: string;
     customerId: string;
@@ -82,6 +133,9 @@ interface SerializedUsageLog {
     status: SignalStatus;
     appliedRules: SerializedRuleApplication[];
     outcome: SerializedOutcomeAttribution | null;
+    /** Post-signal balance for the metered dimension. Null on dry runs and
+     *  read-back. */
+    balance: UsageBalance | null;
     createdAt: string;
 }
 /** Result of a single signal send (sync mode, or `{ wait: true }`). */
@@ -150,18 +204,55 @@ 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[];
     nextCursor: string | null;
 }
-type RevenueRange = "30d" | "6m" | "1y" | "all";
-/** Loosely typed insight payloads (revenue/balances/plan) — server shapes the
- *  detail; we surface the whole envelope minus the `ok` flag. */
-type CustomerBalances = {
+/** One credit type's running balance for a customer (an element of
+ *  `customers.balances().credits`). */
+interface CreditBalance {
+    creditId: string;
+    /** The credit's stable agent key — the same key used to record usage and to
+     *  adjust this balance. */
+    agentKey: string;
+    creditName: string;
+    granted: number;
+    used: number;
+    remaining: number;
+}
+/** One outcome's running balance for a customer. Unlike a credit balance it
+ *  has no `used`, and it carries the outcome's ordered step list. */
+interface OutcomeBalance {
+    outcomeId: string;
+    outcomeName: string;
+    granted: number;
+    remaining: number;
+    /** Each step's `agentKey` is what `signals.outcome()` and the outcome adjust
+     *  API use to address this outcome (outcomes have no key of their own). */
+    steps: {
+        id: string;
+        name: string;
+        agentKey: string;
+    }[];
+}
+/** One unit's advance allowance for a customer. No `used` field. */
+interface UnitBalance {
+    unitId: string;
+    /** The unit's stable agent key — the same key used to record usage and to
+     *  adjust this balance. */
+    agentKey: string;
+    unitName: string;
+    granted: number;
+    remaining: number;
+}
+/** Wallet / credit / outcome / unit balances for a customer's active plan
+ *  (`customers.balances()`). */
+interface CustomerBalances {
     customerId: string;
     currency: {
         code: string;
@@ -171,34 +262,40 @@ type CustomerBalances = {
     wallet: {
         balanceUsd: number;
     } | null;
-    credits: unknown[];
-    outcomes: unknown[];
-    units: unknown[];
-};
-type CustomerPlan = {
-    customerId: string;
-    currency: {
-        code: string;
-        rateUsd: number;
+    credits: CreditBalance[];
+    outcomes: OutcomeBalance[];
+    units: UnitBalance[];
+}
+/** The customer's active plan (the `plan` field of `customers.plan()`);
+ *  `null` when the customer is unsubscribed. */
+interface CustomerPlanDetails {
+    purchaseId: string;
+    planId: string | null;
+    planName: string;
+    planType: PlanType;
+    planKind: PlanKind;
+    seatScope: "CUSTOMER" | "MEMBER" | null;
+    billingCycle: BillingCycle;
+    cost: number;
+    status: "SCHEDULED" | "ACTIVE";
+    billingDate: string;
+    spendingLimit: number | null;
+    spentThisCycle: number | null;
+    meters: {
+        wallet: boolean;
+        credit: boolean;
+        outcome: boolean;
+        unit: boolean;
     };
-    plan: Record<string, unknown> | null;
-};
-type CustomerRevenue = {
+}
+interface CustomerPlan {
     customerId: string;
-    range: RevenueRange;
-    window: unknown;
-    bucket: unknown;
     currency: {
         code: string;
         rateUsd: number;
     };
-    revenue: number;
-    cost: number;
-    profit: number;
-    grossMargin: number;
-    deltas: Record<string, unknown>;
-    trend: unknown[];
-};
+    plan: CustomerPlanDetails | null;
+}
 interface PortalTokenInput {
     customerId: string;
     ttlSeconds?: number;
@@ -219,18 +316,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;
@@ -264,6 +411,8 @@ interface Plan {
     kind: PlanKind;
     billingCycle: BillingCycle;
     cost: number;
+    /** Signed adjustment applied to the plan's headline price (default 0). */
+    priceAdjustment: number;
     currencyCode: string;
     isActive: boolean;
     components: PlanComponent[];
@@ -274,6 +423,7 @@ interface PlanDetail extends Plan {
     createdByName: string | null;
     customerCount: number;
     invoiceCount: number;
+    openInvoiceCount: number;
     stats: {
         totalInvoiced: number;
         totalCollected: number;
@@ -296,6 +446,7 @@ interface Purchase {
     purchaseNumber: string;
     customerId: string;
     customerName: string;
+    customerLogoUrl: string | null;
     planId: string | null;
     planName: string;
     planType: PlanType;
@@ -307,9 +458,12 @@ interface Purchase {
     cost: number;
     currencyCode: string;
     billingDate: string;
+    nextBillingDate: string;
     status: PurchaseStatus;
+    voidAfterMinutes: number;
     autoPayment: boolean;
     autoPaymentPauseReason: string | null;
+    notes: string | null;
     createdAt: string;
 }
 /** The purchase returned by `purchases.get()` — a different, detail-oriented shape. */
@@ -327,7 +481,10 @@ interface PurchaseDetail {
     customer: {
         id: string;
         name: string;
+        logoUrl: string | null;
     };
+    voidAfterMinutes: number;
+    notes: string | null;
     autoPayment: boolean;
     autoPaymentPauseReason: string | null;
     autoPaymentPausedAt: string | null;
@@ -522,33 +679,78 @@ interface WalletEntryInput {
     amount: number;
     notes?: string;
 }
-/** Grant (positive) or claw back (negative) a credit balance. `delta` must be a non-zero whole number. */
+/** Grant (positive) or claw back (negative) a credit balance. `delta` must be a
+ *  non-zero whole number. The credit is addressed by its stable `agentKey`. */
 interface CreditAdjustInput {
-    creditId: string;
+    /** The credit's stable agent key (the same key used to record usage). */
+    agentKey: string;
     delta: number;
     notes?: string;
 }
-/** Grant/claw an outcome balance. `delta` is a non-zero whole number; floored at 0. */
+/** Grant/claw an outcome balance. `delta` is a non-zero whole number; floored at
+ *  0. The outcome is addressed by a STEP's `agentKey` (outcomes have no key of
+ *  their own). */
 interface OutcomeAdjustInput {
-    outcomeId: string;
+    /** An outcome step's stable agent key — identifies the parent outcome. */
+    agentKey: string;
     delta: number;
     notes?: string;
 }
-/** Grant/claw a unit balance. `delta` is non-zero (fractional allowed); floored at 0. */
+/** Grant/claw a unit balance. `delta` is non-zero (fractional allowed); floored
+ *  at 0. The unit is addressed by its stable `agentKey`. */
 interface UnitAdjustInput {
-    unitId: string;
+    /** The unit's stable agent key (the same key used to record usage). */
+    agentKey: string;
     delta: number;
     notes?: string;
 }
 /** 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;
     cache: number;
 }
+/** One point on a cost-over-time analytics series. */
+interface CostPoint {
+    /** UTC day, `YYYY-MM-DD`. */
+    dateIso: string;
+    /** Short display label, e.g. "Jun 24". */
+    label: string;
+    /** Average cost that day, or `null` on days with no usage. */
+    cost: number | null;
+    reqs: number;
+}
+/** Summary stats across a cost-over-time series. */
+interface CostStats {
+    activeDays: number;
+    avgCost: number | null;
+    peakCost: number | null;
+    troughCost: number | null;
+    deviationPct: number | null;
+}
+/** Cost-over-time analytics for a credit (`credits.get().analytics`). */
+interface CreditAnalytics {
+    basePrice: number;
+    pricePerCredit: number;
+    marginPercent: number;
+    points: CostPoint[];
+    stats: CostStats;
+}
+/** Cost-over-time analytics for an outcome (`outcomes.get().analytics`).
+ *  Each point adds `completions` (workflows finished that day). */
+interface OutcomeAnalytics {
+    basePrice: number;
+    pricePerOutcome: number;
+    marginPercent: number;
+    points: (CostPoint & {
+        completions: number;
+    })[];
+    stats: CostStats;
+}
 interface Credit {
     id: string;
     name: string;
@@ -573,8 +775,7 @@ interface CreditDetail extends Credit {
         revenue: number;
         usageLogCount: number;
     };
-    /** Cost-over-time analytics; shape is server-defined. */
-    analytics: Record<string, unknown>;
+    analytics: CreditAnalytics;
 }
 interface CreateCreditInput {
     name: string;
@@ -623,7 +824,7 @@ interface OutcomeDetail extends Outcome {
         completed: number;
         totalRemaining: number;
     };
-    analytics: Record<string, unknown>;
+    analytics: OutcomeAnalytics;
 }
 interface CreateOutcomeInput {
     name: string;
@@ -651,6 +852,9 @@ interface UnitTier {
 }
 interface Unit {
     id: string;
+    /** Stable per-org report key — what `signals.unit({ agentKey })` sends.
+     *  The ONLY identifier accepted when reporting unit consumption. */
+    agentKey: string;
     name: string;
     description: string | null;
     pricingType: UnitPricingType;
@@ -658,10 +862,23 @@ interface Unit {
     tiers: UnitTier[];
     isActive: boolean;
     createdAt: string;
+    createdByName: string | null;
+}
+/** One row in a unit's linked-customer sample (`units.get().customers`). */
+interface UnitCustomerRow {
+    customerId: string;
+    name: string;
+    legalName: string | null;
+    slug: string;
+    logoUrl: string | null;
+    granted: number;
+    used: number;
+    remaining: number;
+    currentlyMetered: boolean;
 }
-/** `units.get()` — adds linked-customer sample plus stats. */
+/** `units.get()` — adds linked-customer sample plus stats.
+ *  `createdByName` is inherited from `Unit`. */
 interface UnitDetail extends Unit {
-    createdByName: string | null;
     stats: {
         planCount: number;
         customerCount: number;
@@ -669,27 +886,68 @@ interface UnitDetail extends Unit {
         totalUsed: number;
     };
     /** First page (≤10) of customers currently metered on this unit. */
-    customers: Record<string, unknown>[];
+    customers: UnitCustomerRow[];
 }
-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;
 }
+/** One serialized unit-consumption event — the result of `signals.unit()` and
+ *  each element of `UnitUsageList.events`. */
+interface SerializedUnitUsage {
+    id: string;
+    customerId: string;
+    /** Display name of the unit. */
+    unit: string;
+    /** The unit's stable agent key; `null` if the unit was deleted. */
+    agentKey: string | null;
+    billingMode: BillingMode;
+    /** Remaining ADVANCE allowance after this event; `null` for ARREAR. */
+    remaining: number | null;
+    customerCost: number;
+    member: string | null;
+    createdAt: 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;
@@ -701,7 +959,7 @@ interface UnitUsageList {
         name: string;
     };
     units: UnitUsageRow[];
-    events: unknown[];
+    events: SerializedUnitUsage[];
 }
 type ThresholdKind = "CREDIT" | "OUTCOME" | "WALLET";
 interface Webhook {
@@ -843,12 +1101,12 @@ declare class Credits {
     list(params?: {
         active?: boolean;
     }): Promise<Credit[]>;
-    /** Create a credit type. `POST /api/v1/credits`. */
-    create(input: CreateCreditInput): Promise<void>;
+    /** Create a credit type; returns the created credit. `POST /api/v1/credits`. */
+    create(input: CreateCreditInput): Promise<Credit>;
     /** Fetch one credit type with usage stats. `GET /api/v1/credits/:id`. */
     get(id: string): Promise<CreditDetail>;
-    /** Update a credit type's definition. `PATCH /api/v1/credits/:id`. */
-    update(id: string, input: UpdateCreditInput): Promise<void>;
+    /** Update a credit type's definition; returns the updated credit. `PATCH /api/v1/credits/:id`. */
+    update(id: string, input: UpdateCreditInput): Promise<Credit>;
     /** Activate or deactivate a credit type. */
     setActive(id: string, isActive: boolean): Promise<Credit>;
     /** Delete a credit type. Refused while a customer is linked to it. */
@@ -857,9 +1115,9 @@ declare class Credits {
 
 /**
  * The `customers` resource — full CRUD over the org's customers plus the
- * read-only insight endpoints (usage / balances / plan / revenue). Every call
- * is scoped to the API key's organisation server-side; a customer in another
- * org resolves as a NotFoundError.
+ * read-only insight endpoints (usage / balances / plan). Every call is scoped
+ * to the API key's organisation server-side; a customer in another org
+ * resolves as a NotFoundError.
  */
 declare class Customers {
     private readonly transport;
@@ -886,18 +1144,39 @@ declare class Customers {
     update(id: string, input: CustomerProfileInput): Promise<ApiCustomer>;
     /** Delete a customer (members, invitations, usage logs cascade). */
     delete(id: string): Promise<void>;
-    /** A customer's usage history. `GET /api/v1/customers/:id/usage`. */
+    /** A customer's usage history. `GET /api/v1/usage?customerId=`. */
     usage(id: string, params?: {
         limit?: number;
     }): Promise<UsageList>;
     /** Wallet / credit / outcome / unit balances. `GET …/:id/balances`. */
     balances(id: string): Promise<CustomerBalances>;
+    /**
+     * One credit balance for a customer, matched by `creditId` or `creditName`;
+     * `null` when the customer has no plan or no matching credit. Convenience
+     * over `balances()` + `Array.find` — it fetches the FULL balances under the
+     * hood (there is no server-side scoped read), so prefer `balances()` when you
+     * need several rows from the same customer.
+     */
+    creditBalance(customerId: string, match: {
+        creditId?: string;
+        creditName?: string;
+    }): Promise<CreditBalance | null>;
+    /** One outcome balance for a customer, matched by `outcomeId` or
+     *  `outcomeName`; `null` when absent. See {@link creditBalance} for the
+     *  fetch-then-filter caveat. */
+    outcomeBalance(customerId: string, match: {
+        outcomeId?: string;
+        outcomeName?: string;
+    }): Promise<OutcomeBalance | null>;
+    /** One unit balance for a customer, matched by `unitId` or `unitName`;
+     *  `null` when absent. See {@link creditBalance} for the fetch-then-filter
+     *  caveat. */
+    unitBalance(customerId: string, match: {
+        unitId?: string;
+        unitName?: string;
+    }): Promise<UnitBalance | null>;
     /** The customer's current plan. `GET …/:id/plan`. */
     plan(id: string): Promise<CustomerPlan>;
-    /** Revenue / cost / profit / margin over a window. `GET …/:id/revenue`. */
-    revenue(id: string, params?: {
-        range?: RevenueRange;
-    }): Promise<CustomerRevenue>;
     /** List a customer's members. `GET …/:id/members`. */
     listMembers(id: string): Promise<Member[]>;
     /** Add a member to a customer. Duplicate `employeeId` → ConflictError. */
@@ -918,10 +1197,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. */
@@ -975,8 +1250,8 @@ declare class Outcomes {
     get(id: string): Promise<OutcomeDetail>;
     /** Update an outcome type's definition. `PATCH /api/v1/outcomes/:id`. */
     update(id: string, input: UpdateOutcomeInput): Promise<Outcome>;
-    /** Activate or deactivate an outcome type. */
-    setActive(id: string, isActive: boolean): Promise<void>;
+    /** Activate or deactivate an outcome type; returns the updated outcome. */
+    setActive(id: string, isActive: boolean): Promise<Outcome>;
     /** Delete an outcome type. */
     delete(id: string): Promise<void>;
 }
@@ -1122,6 +1397,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,12 +1421,12 @@ 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>;
+        unitUsage: SerializedUnitUsage;
     }>;
     /** A customer's unit balances + recent unit events. `GET /api/v1/units`. */
     unitUsage(params: {
@@ -1193,6 +1474,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 +1531,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 +1593,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 CostPoint, type CostStats, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditAnalytics, type CreditBalance, type CreditComponentInput, type CreditDetail, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerPlanDetails, type CustomerProfileInput, 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 OutcomeAnalytics, type OutcomeBalance, 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 SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalStatus, type SignalType, type ThresholdKind, type TieredUnitInput, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitBalance, type UnitComponentInput, type UnitCustomerRow, 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 UsageBalance, type UsageList, ValidationError, type WalletComponentInput, type WalletEntryInput, type WalletInput, type WalletList, type WalletSignal, type WalletTransaction, type WalletTransactionType, type Webhook, type WorkspaceIdentity, signalToWire };