@clocknext/sdk 0.1.0 → 0.4.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,35 +54,37 @@ 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>;
     /**
-     * Stable, unique id for this logical event. Generated automatically if
-     * omitted. Pass a deterministic value to dedupe across process restarts.
+     * 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 `key`. */
+/** Meters a credit, identified by the credit's stable `agentKey`. */
 interface CreditSignal extends SignalBase {
     type: "credit";
-    /** The Credit's stable key (assigned when the credit was created). */
-    key: string;
+    /** The Credit's stable agent key (assigned when the credit was created). */
+    agentKey: string;
 }
 /** Debits the customer's wallet in USD at the model's cost. */
 interface WalletSignal extends SignalBase {
     type: "wallet";
 }
-/** Advances one step of a multi-call outcome workflow, by the step's `key`. */
+/** Advances one step of a multi-call outcome workflow, by the step's `agentKey`. */
 interface OutcomeSignal extends SignalBase {
     type: "outcome";
-    /** The OutcomeStep's stable key — identifies the outcome AND the step. */
-    key: string;
+    /** The OutcomeStep's stable agent key — identifies the outcome AND the step. */
+    agentKey: string;
 }
 type Signal = CreditSignal | WalletSignal | OutcomeSignal;
 /** Helper input shapes for the per-type convenience methods. */
@@ -91,8 +125,6 @@ interface SerializedUsageLog {
 }
 /** Result of a single signal send (sync mode, or `{ wait: true }`). */
 interface TrackResult {
-    /** The idempotency key the event was sent with. */
-    idempotencyKey: string;
     /** True when the signal was buffered (async mode) and not yet sent. */
     queued: boolean;
     /** The computed usage log — present only once the signal has been sent. */
@@ -157,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[];
@@ -218,6 +251,589 @@ interface PortalToken {
     /** Seconds until expiry. */
     expiresIn: number;
 }
+/** How often a plan bills. `FREE` is a one-time grant; `EVERY_5_MIN` is a test cadence. */
+type BillingCycle = "MONTHLY" | "QUARTERLY" | "SEMI_ANNUAL" | "YEARLY" | "EVERY_5_MIN" | "FREE";
+type PlanType = "WALLET" | "BUNDLE";
+type PlanKind = "FLAT_PRICE" | "PAY_AS_YOU_GO" | "PAY_PER_SEAT";
+/** A plan component's meter type. */
+type ComponentType = "WALLET" | "CREDIT" | "OUTCOME" | "UNIT" | "FLAT";
+/** ADVANCE bills up-front for the cycle; ARREAR bills for what was consumed. */
+type BillingMode = "ADVANCE" | "ARREAR";
+/** Prepaid USD wallet. `amount` is the funded balance (required). Max one
+ *  wallet component per plan. */
+interface WalletComponentInput {
+    type: "WALLET";
+    billingMode: BillingMode;
+    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;
+    billingCycle: BillingCycle;
+    /** Carry an unused balance into the next cycle. Default true. */
+    carryForward?: boolean;
+    /** ISO 4217 (3 letters). Default "USD". */
+    currencyCode?: string;
+    isActive?: boolean;
+    /** At least one component. FREE plans must be ADVANCE-only with no FLAT component. */
+    components: PlanComponentInput[];
+}
+/** A full-rewrite update carries the complete plan (same shape as create). */
+type UpdatePlanInput = CreatePlanInput;
+interface PlanComponent {
+    id: string;
+    type: ComponentType;
+    billingMode: BillingMode;
+    creditId: string | null;
+    outcomeId: string | null;
+    unitId: string | null;
+    targetName: string | null;
+    quantity: number | null;
+    amount: number | null;
+}
+interface Plan {
+    id: string;
+    name: string;
+    description: string | null;
+    type: PlanType;
+    kind: PlanKind;
+    billingCycle: BillingCycle;
+    cost: number;
+    currencyCode: string;
+    isActive: boolean;
+    components: PlanComponent[];
+}
+/** The richer plan returned by `plans.get()` (adds aggregate stats). */
+interface PlanDetail extends Plan {
+    createdAt: string;
+    createdByName: string | null;
+    customerCount: number;
+    invoiceCount: number;
+    stats: {
+        totalInvoiced: number;
+        totalCollected: number;
+        openBalance: number;
+    };
+}
+type PurchaseStatus = "SCHEDULED" | "ACTIVE" | "CANCELLED";
+interface CreatePurchaseInput {
+    customerId: string;
+    planId: string;
+    /** `YYYY-MM-DD`. Defaults to today; must be a valid non-past date. */
+    billingDate?: string;
+    notes?: string;
+    autoPayment?: boolean;
+    /** Auto-void the purchase if unpaid after N minutes. */
+    voidAfterMinutes?: number;
+}
+interface Purchase {
+    id: string;
+    purchaseNumber: string;
+    customerId: string;
+    customerName: string;
+    planId: string | null;
+    planName: string;
+    planType: PlanType;
+    hasWallet: boolean;
+    hasCredit: boolean;
+    hasOutcome: boolean;
+    hasUnit: boolean;
+    billingCycle: BillingCycle;
+    cost: number;
+    currencyCode: string;
+    billingDate: string;
+    status: PurchaseStatus;
+    autoPayment: boolean;
+    autoPaymentPauseReason: string | null;
+    createdAt: string;
+}
+/** The purchase returned by `purchases.get()` — a different, detail-oriented shape. */
+interface PurchaseDetail {
+    id: string;
+    purchaseNumber: string;
+    status: PurchaseStatus;
+    cost: number;
+    billingCycle: BillingCycle;
+    planName: string;
+    billingDate: string;
+    nextBillingDate: string;
+    createdAt: string;
+    createdByName: string;
+    customer: {
+        id: string;
+        name: string;
+    };
+    autoPayment: boolean;
+    autoPaymentPauseReason: string | null;
+    autoPaymentPausedAt: string | null;
+    plan: {
+        id: string;
+    } | null;
+    stats: {
+        invoiceCount: number;
+        paidCount: number;
+    };
+}
+type InvoiceStatus = "OPEN" | "PAID" | "VOID";
+/** Trimmed row from `invoices.list()`. */
+interface InvoiceListRow {
+    id: string;
+    invoiceNumber: string;
+    purchaseNumber: string | null;
+    purchaseId: string | null;
+    customerId: string;
+    customerName: string;
+    planName: string;
+    billingCycle: BillingCycle;
+    cycleIndex: number;
+    amount: number;
+    currencyCode: string;
+    status: InvoiceStatus;
+    issuedAt: string;
+    paidAt: string | null;
+}
+/** A billing party (your org, or the customer) on an invoice. */
+interface InvoiceParty {
+    name: string;
+    logoUrl: string | null;
+    legalName: string | null;
+    email: string | null;
+    phone: string | null;
+    website: string | null;
+    taxId: string | null;
+    addressLine1: string | null;
+    city: string | null;
+    state: string | null;
+    country: string | null;
+    pincode: string | null;
+}
+interface InvoiceLineItem {
+    kind: "credit" | "outcome";
+    label: string;
+    quantity: number;
+}
+/** The plan snapshot embedded in a full invoice. */
+interface InvoicePlanSnapshot {
+    name: string;
+    type: PlanType;
+    hasWallet: boolean;
+    hasCredit: boolean;
+    hasOutcome: boolean;
+    hasUnit: boolean;
+    kind: PlanKind;
+    billingCycle: BillingCycle;
+    cost: number;
+    currencyCode: string;
+    spendingLimit: number | null;
+    seatScope: "CUSTOMER" | "MEMBER" | null;
+    carryForward: boolean;
+    billingDate: string;
+    status: "SCHEDULED" | "ACTIVE";
+}
+/** The full invoice from `invoices.get()` (also the `payment` in `payments.get()`). */
+interface Invoice {
+    id: string;
+    invoiceNumber: string;
+    paymentNumber: string | null;
+    purchaseNumber: string | null;
+    customerId: string;
+    customerName: string;
+    customerSlug: string;
+    customerParty: InvoiceParty;
+    orgParty: InvoiceParty;
+    purchaseId: string | null;
+    stream: BillingMode;
+    planId: string | null;
+    planName: string;
+    planType: PlanType;
+    plan: InvoicePlanSnapshot | null;
+    billingCycle: BillingCycle;
+    cycleIndex: number;
+    lineItems: InvoiceLineItem[];
+    hasWallet: boolean;
+    hasCredit: boolean;
+    hasOutcome: boolean;
+    hasUnit: boolean;
+    amount: number;
+    currencyCode: string;
+    currencyRateUsd: number;
+    status: InvoiceStatus;
+    issuedAt: string;
+    paidAt: string | null;
+    voidedAt: string | null;
+    /** One of the server `PaymentMode` values (e.g. "CASH", "STRIPE", …). */
+    paymentMode: string | null;
+    paymentReference: string | null;
+    stripePaymentIntentId: string | null;
+    autoPaid: boolean;
+    notes: string | null;
+    createdAt: string;
+    createdByName: string;
+    paidByName: string | null;
+    voidedByName: string | null;
+}
+/** A short `{ id, name }` plan reference alongside a full invoice/payment. */
+interface PlanRef {
+    id: string;
+    name: string;
+}
+interface InvoiceDetail {
+    invoice: Invoice;
+    plan: PlanRef | null;
+}
+/** A hosted pay link for an OPEN invoice. */
+interface PayLink {
+    url: string;
+    invoiceId: string;
+    invoiceNumber: string;
+}
+/** Trimmed row from `payments.list()` (a payment is a PAID invoice). */
+interface PaymentRow {
+    id: string;
+    paymentNumber: string;
+    invoiceNumber: string;
+    purchaseNumber: string | null;
+    customerId: string;
+    customerName: string;
+    planName: string;
+    amount: number;
+    currencyCode: string;
+    paymentMode: string | null;
+    paymentReference: string | null;
+    paidAt: string;
+    paidByName: string | null;
+}
+interface PaymentDetail {
+    payment: Invoice;
+    plan: PlanRef | null;
+}
+type MemberRole = "OWNER" | "ADMIN" | "MEMBER";
+interface Member {
+    id: string;
+    role: MemberRole;
+    name: string;
+    email: string | null;
+    employeeId: string | null;
+    phone: string | null;
+    /** True once the member has linked a login. */
+    isLinked: boolean;
+    joinedAt: string;
+}
+interface AddMemberInput {
+    name: string;
+    role: "ADMIN" | "MEMBER";
+    email?: string;
+    employeeId?: string;
+    phone?: string;
+}
+/** Role is fixed after creation; omit it here. */
+interface UpdateMemberInput {
+    name: string;
+    email?: string;
+    employeeId?: string;
+    phone?: string;
+}
+type WalletTransactionType = "CREDIT" | "DEBIT";
+interface WalletTransaction {
+    id: string;
+    type: WalletTransactionType;
+    amount: number;
+    amountUsd: number;
+    currencyCode: string;
+    currencyRateUsd: number;
+    notes: string | null;
+    batchId: string | null;
+    createdAt: string;
+    createdByName: string | null;
+}
+interface WalletList {
+    balanceUsd: number;
+    transactions: WalletTransaction[];
+}
+interface WalletEntryInput {
+    /** DEBIT spends, CREDIT tops up. */
+    type: WalletTransactionType;
+    /** Always positive; the sign comes from `type`. */
+    amount: number;
+    notes?: string;
+}
+/** Grant (positive) or claw back (negative) a credit balance. `delta` must be a non-zero whole number. */
+interface CreditAdjustInput {
+    creditId: string;
+    delta: number;
+    notes?: string;
+}
+/** Grant/claw an outcome balance. `delta` is a non-zero whole number; floored at 0. */
+interface OutcomeAdjustInput {
+    outcomeId: string;
+    delta: number;
+    notes?: string;
+}
+/** Grant/claw a unit balance. `delta` is non-zero (fractional allowed); floored at 0. */
+interface UnitAdjustInput {
+    unitId: string;
+    delta: number;
+    notes?: string;
+}
+/** A per-model token bundle attached to a credit or outcome step. */
+interface ModelBundleEntry {
+    orgModelId: string;
+    /** Display label; the server defaults it from the model when omitted. */
+    modelName?: string;
+    tokens: number;
+    input: number;
+    output: number;
+    cache: number;
+}
+interface Credit {
+    id: string;
+    name: string;
+    agentKey: string;
+    description: string | null;
+    tokensPerCredit: number;
+    basePrice: number;
+    marginPercent: number;
+    pricePerCredit: number;
+    isActive: boolean;
+    createdAt: string;
+}
+/** `credits.get()` — adds the model bundle plus usage stats/analytics. */
+interface CreditDetail extends Credit {
+    modelBundle: ModelBundleEntry[];
+    createdByName: string;
+    stats: {
+        customerCount: number;
+        planCount: number;
+        totalGranted: number;
+        totalUsed: number;
+        revenue: number;
+        usageLogCount: number;
+    };
+    /** Cost-over-time analytics; shape is server-defined. */
+    analytics: Record<string, unknown>;
+}
+interface CreateCreditInput {
+    name: string;
+    /** Lowercased stable key used by `signals.credit({ agentKey })`. */
+    agentKey: string;
+    basePrice: number;
+    marginPercent: number;
+    pricePerCredit: number;
+    description?: string;
+    tokensPerCredit?: number;
+    modelBundle?: ModelBundleEntry[];
+}
+type UpdateCreditInput = CreateCreditInput;
+interface OutcomeStepInput {
+    id?: string;
+    name: string;
+    /** Lowercased stable key used by `signals.outcome({ agentKey })`. */
+    agentKey: string;
+    basePrice: number;
+    modelBundle?: ModelBundleEntry[];
+}
+interface Outcome {
+    id: string;
+    name: string;
+    description: string | null;
+    isActive: boolean;
+    marginPercent: number;
+    pricePerOutcome: number;
+    createdAt: string;
+    steps?: {
+        name: string;
+        agentKey: string;
+    }[];
+}
+/** `outcomes.get()` — adds steps plus in-flight/completed stats. */
+interface OutcomeDetail extends Outcome {
+    createdByName: string | null;
+    steps: {
+        name: string;
+        agentKey: string;
+    }[];
+    stats: {
+        stepCount: number;
+        customerCount: number;
+        inFlight: number;
+        completed: number;
+        totalRemaining: number;
+    };
+    analytics: Record<string, unknown>;
+}
+interface CreateOutcomeInput {
+    name: string;
+    basePrice: number;
+    marginPercent: number;
+    pricePerOutcome: number;
+    description?: string | null;
+    isActive?: boolean;
+    /** 1–50 steps; step names and agent keys must be unique. */
+    steps: OutcomeStepInput[];
+}
+type UpdateOutcomeInput = CreateOutcomeInput;
+type UnitPricingType = "FLAT" | "SLAB" | "VOLUME";
+/** A tier for SLAB/VOLUME pricing; only the last tier may have `upTo: null`. */
+interface UnitTierInput {
+    id?: string;
+    upTo: number | null;
+    price: number;
+}
+interface UnitTier {
+    id: string;
+    upTo: number | null;
+    price: number;
+    order: number;
+}
+interface Unit {
+    id: string;
+    name: string;
+    description: string | null;
+    pricingType: UnitPricingType;
+    flatPrice: number;
+    tiers: UnitTier[];
+    isActive: boolean;
+    createdAt: string;
+}
+/** `units.get()` — adds linked-customer sample plus stats. */
+interface UnitDetail extends Unit {
+    createdByName: string | null;
+    stats: {
+        planCount: number;
+        customerCount: number;
+        totalRemaining: number;
+        totalUsed: number;
+    };
+    /** First page (≤10) of customers currently metered on this unit. */
+    customers: Record<string, unknown>[];
+}
+/** Flat per-event pricing — a single `flatPrice` (defaults to 0), no tiers. */
+interface FlatUnitInput {
+    name: string;
+    /** Stable per-org report key (`signals.unit({ agentKey })`); `[a-z0-9._-]`. */
+    agentKey: string;
+    pricingType: "FLAT";
+    /** Price per event; defaults to 0. */
+    flatPrice?: number;
+    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. 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;
+    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;
+    remaining?: number;
+}
+interface UnitUsageList {
+    customer: {
+        id: string;
+        name: string;
+    };
+    units: UnitUsageRow[];
+    events: unknown[];
+}
+type ThresholdKind = "CREDIT" | "OUTCOME" | "WALLET";
+interface Webhook {
+    kind: ThresholdKind;
+    threshold: number;
+    url: string;
+    isActive: boolean;
+}
+interface UpsertWebhookInput {
+    kind: ThresholdKind;
+    /** Fire when the balance crosses this value. */
+    threshold: number;
+    /** http(s) URL to POST the alert to. */
+    url: string;
+    isActive?: boolean;
+}
 type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 interface Logger {
     debug?: (...args: unknown[]) => void;
@@ -228,7 +844,7 @@ type DropReason = "queue_full" | "send_failed";
 interface ClockNextConfig {
     /** The org API key (`cnk_…`). Required. */
     apiKey: string;
-    /** API base URL. Defaults to https://app.clocknext.com */
+    /** API base URL. Defaults to https://payments.clocknext.com */
     baseUrl?: string;
     /**
      * "async" (default) buffers signals and flushes in the background.
@@ -303,20 +919,23 @@ interface ResolvedConfig {
 }
 
 interface RequestOptions {
-    method: "GET" | "POST" | "PATCH" | "DELETE";
+    method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
     path: string;
     query?: Record<string, string | number | undefined>;
     body?: unknown;
-    /** Reused across retries — what makes a retried write safe. */
-    idempotencyKey?: string;
-    /** Disable retries for this call (rarely needed). */
+    /**
+     * Whether this call may be auto-retried on a transient failure. Defaults to
+     * method-based safety: reads (GET), idempotent replaces (PUT), and DELETE are
+     * replay-safe. Non-idempotent writes (POST/PATCH) default to NOT retried so a
+     * transient failure can't duplicate the write; callers that tolerate a retry
+     * opt in explicitly.
+     */
     retry?: boolean;
 }
 /**
  * The single HTTP seam. Builds the authenticated request, enforces a timeout,
  * unwraps the `{ ok, ... }` envelope, maps failures to typed errors, and retries
- * transient ones with backoff + jitter — reusing the same idempotency key on
- * every attempt.
+ * transient ones with backoff + jitter.
  */
 declare class Transport {
     private readonly cfg;
@@ -328,6 +947,30 @@ declare class Transport {
     private buildUrl;
 }
 
+/**
+ * The `credits` resource — manage the org's credit *types* (the catalog). A
+ * credit's stable `agentKey` is what you pass to `signals.credit()` when
+ * recording usage against it. `/api/v1/credits`.
+ */
+declare class Credits {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** List credit types. Pass `{ active: true }` to only return active ones. */
+    list(params?: {
+        active?: boolean;
+    }): Promise<Credit[]>;
+    /** Create a credit type. `POST /api/v1/credits`. */
+    create(input: CreateCreditInput): Promise<void>;
+    /** 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>;
+    /** 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. */
+    delete(id: string): Promise<void>;
+}
+
 /**
  * The `customers` resource — full CRUD over the org's customers plus the
  * read-only insight endpoints (usage / balances / plan / revenue). Every call
@@ -371,6 +1014,123 @@ declare class Customers {
     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. */
+    addMember(id: string, input: AddMemberInput): Promise<Member>;
+    /** Update a member's profile (role is fixed). `PATCH …/:id/members/:memberId`. */
+    updateMember(id: string, memberId: string, input: UpdateMemberInput): Promise<Member>;
+    /** Remove a member from a customer. `DELETE …/:id/members/:memberId`. */
+    removeMember(id: string, memberId: string): Promise<void>;
+    /** The customer's wallet balance + transactions. `GET …/:id/wallet`. */
+    wallet(id: string, params?: {
+        limit?: number;
+    }): Promise<WalletList>;
+    /**
+     * Record a manual wallet entry (top-up or deduction). `amount` is always
+     * positive; the sign comes from `type`. `POST …/:id/wallet`.
+     */
+    addWalletEntry(id: string, input: WalletEntryInput): Promise<{
+        transaction: WalletTransaction;
+        balanceUsd: number;
+    }>;
+    /** 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. */
+    adjustOutcome(id: string, input: OutcomeAdjustInput): Promise<{
+        remaining: number;
+    }>;
+    /** Grant or claw back a unit balance. Returns the remaining balance. */
+    adjustUnit(id: string, input: UnitAdjustInput): Promise<{
+        remaining: number;
+    }>;
+}
+
+/**
+ * The `invoices` resource — read-only. Invoices are generated by the billing
+ * engine from purchases; you list them, read one, or mint a hosted pay link for
+ * an OPEN invoice. `/api/v1/invoices`.
+ */
+declare class Invoices {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** List invoices, most-recent first. Filter by customer and/or status. */
+    list(params?: {
+        customerId?: string;
+        status?: InvoiceStatus;
+        limit?: number;
+    }): Promise<InvoiceListRow[]>;
+    /** Fetch one full invoice + its plan snapshot. `GET /api/v1/invoices/:id`. */
+    get(id: string): Promise<InvoiceDetail>;
+    /**
+     * Mint a hosted pay link for an OPEN invoice. PAID/VOID invoices are rejected
+     * with a `ConflictError`. `GET /api/v1/invoices/:id/pay-link`.
+     */
+    payLink(id: string): Promise<PayLink>;
+}
+
+/**
+ * The `outcomes` resource — manage the org's outcome *types* (the catalog). An
+ * outcome is a multi-step workflow; each step has a stable `agentKey` you pass
+ * to `signals.outcome()`. `/api/v1/outcomes`.
+ */
+declare class Outcomes {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** List outcome types. Pass `{ active: true }` to only return active ones. */
+    list(params?: {
+        active?: boolean;
+    }): Promise<Outcome[]>;
+    /** Create an outcome type with its steps. `POST /api/v1/outcomes`. */
+    create(input: CreateOutcomeInput): Promise<Outcome>;
+    /** Fetch one outcome type with steps + stats. `GET /api/v1/outcomes/:id`. */
+    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>;
+    /** Delete an outcome type. */
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * The `payments` resource — read-only. A payment is a PAID invoice; the `id`
+ * used here is that underlying invoice id. `/api/v1/payments`.
+ */
+declare class Payments {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** List payments (paid invoices), most-recent first. Filter by customer. */
+    list(params?: {
+        customerId?: string;
+        limit?: number;
+    }): Promise<PaymentRow[]>;
+    /** Fetch one payment + its plan snapshot. `GET /api/v1/payments/:id`. */
+    get(id: string): Promise<PaymentDetail>;
+}
+
+/**
+ * The `plans` resource — define and manage the billing plans customers
+ * subscribe to. Each plan is a set of entitlement components (wallet / credit /
+ * outcome / unit / flat) billed on a cycle. `/api/v1/plans`.
+ */
+declare class Plans {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** List plans, oldest-first. Pass `{ active: true }` to only return active plans. */
+    list(params?: {
+        active?: boolean;
+    }): Promise<Plan[]>;
+    /** Create a plan. `POST /api/v1/plans`. */
+    create(input: CreatePlanInput): Promise<Plan>;
+    /** Fetch one plan with aggregate subscriber/invoice stats. `GET /api/v1/plans/:id`. */
+    get(id: string): Promise<PlanDetail>;
+    /** Replace a plan's definition (components + settings). `PATCH /api/v1/plans/:id`. */
+    update(id: string, input: UpdatePlanInput): Promise<Plan>;
+    /** Activate or deactivate a plan without rewriting it. */
+    setActive(id: string, isActive: boolean): Promise<Plan>;
+    /** Delete a plan. Refused once any customer has purchased it. */
+    delete(id: string): Promise<void>;
 }
 
 /**
@@ -385,25 +1145,44 @@ declare class Portal {
     createToken(input: PortalTokenInput): Promise<PortalToken>;
 }
 
+/**
+ * The `purchases` resource — a purchase is a customer's subscription to a plan.
+ * Creating one auto-cancels the customer's existing scheduled/active purchase
+ * (this is also how you "change plan"). `/api/v1/purchases`.
+ */
+declare class Purchases {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** List purchases, most-recent first. Filter by customer and/or status. */
+    list(params?: {
+        customerId?: string;
+        status?: PurchaseStatus;
+        limit?: number;
+    }): Promise<Purchase[]>;
+    /** Subscribe a customer to a plan. `POST /api/v1/purchases`. */
+    create(input: CreatePurchaseInput): Promise<Purchase>;
+    /** Fetch one purchase. `GET /api/v1/purchases/:id`. */
+    get(id: string): Promise<PurchaseDetail>;
+    /**
+     * Turn automatic billing on or off for a purchase. When pausing, an optional
+     * `pauseReason` is recorded. `PATCH /api/v1/purchases/:id`.
+     */
+    setAutoPayment(id: string, autoPayment: boolean, opts?: {
+        pauseReason?: string;
+    }): Promise<{
+        autoPayment: boolean;
+    }>;
+    /** Cancel a purchase (voids any open invoice). `POST /api/v1/purchases/:id/cancel`. */
+    cancel(id: string): Promise<void>;
+}
+
 /** One buffered, wire-ready signal awaiting a background flush. */
 interface QueuedSignal {
     /** The exact JSON body to POST to /api/v1/usage. */
     body: Record<string, unknown>;
-    /** Reused across retries. */
-    idempotencyKey: string;
     /** The original signal — passed to onError/onDrop hooks. */
     signal: Signal;
 }
-/**
- * Pluggable buffer. The default is in-memory; a host that needs to survive a
- * crash *before* send can implement this against disk/Redis/SQLite.
- */
-interface QueueStore {
-    push(item: QueuedSignal): void;
-    /** Remove and return up to `n` items (FIFO). */
-    take(n: number): QueuedSignal[];
-    size(): number;
-}
 
 /**
  * Background send engine for async-mode signals. Buffers wire-ready signals and
@@ -455,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;
@@ -472,6 +1257,75 @@ declare class Signals {
         customerId: string;
         limit?: number;
     }): Promise<UsageList>;
+    /**
+     * 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>;
+    }>;
+    /** A customer's unit balances + recent unit events. `GET /api/v1/units`. */
+    unitUsage(params: {
+        customerId: string;
+        limit?: number;
+    }): Promise<UnitUsageList>;
+}
+
+/**
+ * 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`.
+ */
+declare class Units {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** List unit types. Pass `{ active: true }` to only return active ones. */
+    list(params?: {
+        active?: boolean;
+    }): Promise<Unit[]>;
+    /** Create a unit type. `POST /api/v1/units-catalog`. */
+    create(input: CreateUnitInput): Promise<Unit>;
+    /** Fetch one unit type with stats. `GET /api/v1/units-catalog/:id`. */
+    get(id: string): Promise<UnitDetail>;
+    /** Update a unit type's definition. `PATCH /api/v1/units-catalog/:id`. */
+    update(id: string, input: UpdateUnitInput): Promise<Unit>;
+    /** Activate or deactivate a unit type. */
+    setActive(id: string, isActive: boolean): Promise<Unit>;
+    /** Delete a unit type. */
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * The `webhooks` resource — threshold alerts. At most one webhook per kind
+ * (CREDIT / OUTCOME / WALLET); posting a kind again upserts it. `/api/v1/webhooks`.
+ */
+declare class Webhooks {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** List configured webhooks. `GET /api/v1/webhooks`. */
+    list(): Promise<Webhook[]>;
+    /** Create or replace the webhook for a kind. `POST /api/v1/webhooks`. */
+    upsert(input: UpsertWebhookInput): Promise<Webhook>;
+    /** Delete the webhook for a kind (idempotent). `DELETE /api/v1/webhooks/:kind`. */
+    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[]>;
 }
 
 /**
@@ -483,7 +1337,7 @@ declare class Signals {
  * await cnk.signals.credit({
  *   customerId: "cus_123",
  *   model: "gpt-4o",          // catalog model id
- *   key: "api_credit",        // the credit's stable key
+ *   agentKey: "api_credit",   // the credit's stable agent key
  *   tokens: { input: 1200, output: 340 },
  * });
  *
@@ -492,12 +1346,30 @@ declare class Signals {
  * ```
  */
 declare class ClockNext {
-    /** Record + read usage signals. */
+    /** Record + read usage signals (credit / wallet / outcome / unit). */
     readonly signals: Signals;
-    /** Manage customers and read their insights. */
+    /** Manage customers, their members, wallet, and balances. */
     readonly customers: Customers;
+    /** Define and manage billing plans. */
+    readonly plans: Plans;
+    /** Subscribe customers to plans (purchases). */
+    readonly purchases: Purchases;
+    /** Read invoices and mint hosted pay links. */
+    readonly invoices: Invoices;
+    /** Read payments (paid invoices). */
+    readonly payments: Payments;
+    /** Manage the credit-type catalog. */
+    readonly credits: Credits;
+    /** Manage the outcome-type catalog. */
+    readonly outcomes: Outcomes;
+    /** Manage the unit-type catalog. */
+    readonly units: Units;
+    /** Configure threshold webhooks. */
+    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);
@@ -518,13 +1390,10 @@ declare class ClockNext {
 declare class ClockNextError extends Error {
     /** HTTP status, when the failure came from a server response. */
     readonly status?: number;
-    /** The idempotency key of the offending signal, when applicable. */
-    readonly idempotencyKey?: string;
     /** Whether the SDK considers this failure worth retrying. */
     readonly retryable: boolean;
     constructor(message: string, opts?: {
         status?: number;
-        idempotencyKey?: string;
         retryable?: boolean;
     });
 }
@@ -543,14 +1412,13 @@ declare class PlanError extends ClockNextError {
 /** 422 — insufficient credits / units / outcomes for the call. */
 declare class AllowanceError extends ClockNextError {
 }
-/** 409 — conflict (e.g. idempotency-key reuse with a different payload). */
+/** 409 — conflict. */
 declare class ConflictError extends ClockNextError {
 }
 /** 429 — rate limited. */
 declare class RateLimitError extends ClockNextError {
     readonly retryAfterMs?: number;
     constructor(message: string, opts?: {
-        idempotencyKey?: string;
         retryAfterMs?: number;
     });
 }
@@ -559,22 +1427,7 @@ declare class ServerError extends ClockNextError {
 }
 /** fetch threw / request timed out — request never completed. */
 declare class NetworkError extends ClockNextError {
-    constructor(message: string, opts?: {
-        idempotencyKey?: string;
-    });
+    constructor(message: string);
 }
 
-/**
- * Generates a stable idempotency key for one logical event. Generated ONCE at
- * enqueue/track time and reused across every retry of that event — regenerating
- * per HTTP attempt would defeat dedup (the documented foot-gun in most usage
- * SDKs).
- *
- * Uses the Web Crypto global (`globalThis.crypto`), which is present on Node 18+
- * and every edge runtime — and, unlike a static `node:crypto` import, never
- * fails to load on runtimes that lack Node built-ins. Degrades through
- * `getRandomValues` to `Math.random` so it always returns a v4 UUID.
- */
-declare function newIdempotencyKey(): string;
-
-export { AllowanceError, type ApiCustomer, AuthError, ClockNext, type ClockNextConfig, ClockNextError, ConflictError, type CreateCustomerInput, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerProfileInput, type CustomerRevenue, type DropReason, type FetchLike, type Logger, NetworkError, NotFoundError, type OutcomeInput, type OutcomeSignal, PlanError, type PortalToken, type PortalTokenInput, type QueueStore, type QueuedSignal, RateLimitError, type RevenueRange, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUsageLog, ServerError, type Signal, type SignalStatus, type SignalType, type Tokens, type TrackResult, type UsageList, ValidationError, type WalletInput, type WalletSignal, newIdempotencyKey, 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 };