@clocknext/sdk 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -103,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;
@@ -121,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 }`). */
@@ -185,7 +200,6 @@ interface CustomerProfileInput {
     taxId?: string | null;
     notes?: string | null;
     logoUrl?: string | null;
-    creditAllowance?: number;
     /** ISO 4217 (3 letters); must be enabled for the org. */
     currencyCode?: string;
 }
@@ -198,10 +212,46 @@ 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;
@@ -211,34 +261,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;
@@ -354,6 +410,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[];
@@ -364,6 +422,7 @@ interface PlanDetail extends Plan {
     createdByName: string | null;
     customerCount: number;
     invoiceCount: number;
+    openInvoiceCount: number;
     stats: {
         totalInvoiced: number;
         totalCollected: number;
@@ -386,6 +445,7 @@ interface Purchase {
     purchaseNumber: string;
     customerId: string;
     customerName: string;
+    customerLogoUrl: string | null;
     planId: string | null;
     planName: string;
     planType: PlanType;
@@ -397,9 +457,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. */
@@ -417,7 +480,10 @@ interface PurchaseDetail {
     customer: {
         id: string;
         name: string;
+        logoUrl: string | null;
     };
+    voidAfterMinutes: number;
+    notes: string | null;
     autoPayment: boolean;
     autoPaymentPauseReason: string | null;
     autoPaymentPausedAt: string | null;
@@ -612,21 +678,28 @@ 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;
 }
@@ -640,6 +713,43 @@ interface ModelBundleEntry {
     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;
@@ -664,8 +774,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;
@@ -714,7 +823,7 @@ interface OutcomeDetail extends Outcome {
         completed: number;
         totalRemaining: number;
     };
-    analytics: Record<string, unknown>;
+    analytics: OutcomeAnalytics;
 }
 interface CreateOutcomeInput {
     name: string;
@@ -742,6 +851,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;
@@ -749,10 +861,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;
@@ -760,7 +885,7 @@ interface UnitDetail extends Unit {
         totalUsed: number;
     };
     /** First page (≤10) of customers currently metered on this unit. */
-    customers: Record<string, unknown>[];
+    customers: UnitCustomerRow[];
 }
 /** Flat per-event pricing — a single `flatPrice` (defaults to 0), no tiers. */
 interface FlatUnitInput {
@@ -802,6 +927,22 @@ interface UnitInput {
     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. */
@@ -817,7 +958,7 @@ interface UnitUsageList {
         name: string;
     };
     units: UnitUsageRow[];
-    events: unknown[];
+    events: SerializedUnitUsage[];
 }
 type ThresholdKind = "CREDIT" | "OUTCOME" | "WALLET";
 interface Webhook {
@@ -959,12 +1100,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. */
@@ -973,9 +1114,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;
@@ -1002,18 +1143,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. */
@@ -1087,8 +1249,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>;
 }
@@ -1263,7 +1425,7 @@ declare class Signals {
      * 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: {
@@ -1430,4 +1592,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 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 };
+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 };