@clocknext/sdk 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -30,27 +30,22 @@ interface SignalBase {
     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.
-     */
-    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 +86,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. */
@@ -218,6 +211,513 @@ 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";
+/** One entitlement line in a plan. Set the id matching `type` (creditId for CREDIT, …). */
+interface PlanComponentInput {
+    type: ComponentType;
+    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;
+}
+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;
+    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>[];
+}
+interface CreateUnitInput {
+    name: string;
+    pricingType: UnitPricingType;
+    /** Required for FLAT pricing. */
+    flatPrice?: number;
+    /** Required for SLAB/VOLUME pricing (≤50 tiers). */
+    tiers?: UnitTierInput[];
+    description?: string | null;
+    isActive?: boolean;
+}
+type UpdateUnitInput = CreateUnitInput;
+/** Record one unit-metered event. `unit` matches a catalog unit name (case-insensitive). */
+interface UnitInput {
+    customerId: string;
+    unit: string;
+    member?: string;
+}
+interface UnitUsageRow {
+    unit: string;
+    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 +728,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 +803,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 +831,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 +898,127 @@ 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;
+    }>;
+    /** 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. */
+    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 +1033,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
@@ -472,6 +1139,58 @@ declare class Signals {
         customerId: string;
         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`.
+     */
+    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>;
 }
 
 /**
@@ -483,7 +1202,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,10 +1211,26 @@ 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;
     private readonly cfg;
@@ -518,13 +1253,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 +1275,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 +1290,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 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 };