@clocknext/sdk 0.17.0 → 0.19.0

package/dist/index.d.cts

@@ -164,6 +164,8 @@ type OutcomeCompletionInput = CustomerRef & {
     runId: string;
     /** Optional member (email) this completion is attributed to. */
     member?: string;
+    /** Free-form metadata, stored as-is with this completion. Never priced. */
+    custom?: Record<string, unknown>;
     /** Idempotency key, auto-generated if omitted. Sending this completion twice
      *  for the same run is already a safe no-op server-side, so this only
      *  collapses a retry into one attempt rather than protecting against a
@@ -342,8 +344,6 @@ interface TrackResult {
      */
     rawId?: string;
 }
-/** A preset time window, or `"custom"` for an explicit `from`/`to` range. */
-type UsageLogPeriod = "all" | "today" | "7d" | "30d" | "90d" | "custom";
 interface UsageLogListParams {
     customerId: string;
     /** Default 50, max 200. */
@@ -351,11 +351,11 @@ interface UsageLogListParams {
     /** Pass back a previous page's `nextCursor` to fetch the next page. Omit for
      *  the first page. */
     cursor?: string;
-    /** Default `"all"`. Pair `"custom"` with `from`/`to`. */
-    period?: UsageLogPeriod;
-    /** `YYYY-MM-DD`, only used when `period` is `"custom"`. */
+    /** First day to include, `YYYY-MM-DD` (UTC). The whole day is included.
+     *  Keep sending the same value while paging with `cursor`. */
     from?: string;
-    /** `YYYY-MM-DD`, only used when `period` is `"custom"`. */
+    /** Last day to include, `YYYY-MM-DD` (UTC). The whole day is included.
+     *  Must not be before `from`. */
     to?: string;
 }
 interface UsageLogAppliedRule {
@@ -381,13 +381,15 @@ interface UsageLogOutcomeAttribution {
  * One row of a customer's usage history, merged from every meter kind
  * (`UsageLog`, `UnitUsageLog`, completed composite occurrences) into one
  * feed and sorted by time — the same rows the customer portal's own "Usage
- * logs" table shows. `model`, `credit`, `outcome`, `unit` and `composite` are
- * each `null` unless `kind` matches that group.
+ * logs" table shows. `credit`, `outcome`, `unit` and `composite` are each
+ * `null` unless `type` matches that group.
  */
 interface UsageLogEntry {
     id: string;
     createdAt: string;
-    kind: "credit" | "outcome" | "unit" | "wallet" | "composite";
+    /** Which meter this row is. `"outcome"` is one step of a run;
+     *  `"outcome_completion"` is the finished run itself (one per run). */
+    type: "credit" | "outcome" | "outcome_completion" | "unit" | "wallet" | "composite";
     status: SignalStatus;
     typeName: string | null;
     member: string | null;
@@ -408,23 +410,40 @@ interface UsageLogEntry {
         providedCost: string;
         customerCost: string;
     };
-    /** Populated only when `kind === "credit"`. `amount` is a formatted credit
+    /** Populated only when `type === "credit"`. `amount` is a formatted credit
      *  value, honouring the org's credit-decimals display setting. */
     credit: {
         amount: string;
         appliedRules: UsageLogAppliedRule[];
     } | null;
-    /** Populated only when `kind === "outcome"`. */
+    /** Populated only when `type === "outcome"`. */
     outcome: UsageLogOutcomeAttribution | null;
-    /** Populated only when `kind === "unit"`. `quantity` is formatted. */
+    /** Populated only when `type === "unit"`. `quantity` is formatted. */
     unit: {
         quantity: string;
     } | null;
-    /** Populated only when `kind === "composite"`. `amount` is a formatted USD
+    /** Populated only when `type === "composite"`. `amount` is a formatted USD
      *  price — the composite's flat price, read live, not stored per row. */
     composite: {
         amount: string;
     } | null;
+    /** Populated only when `type === "outcome_completion"`. `amount` is the
+     *  price frozen when the run completed (your plan price, else the catalogue
+     *  price). */
+    outcomeCompletion: {
+        runId: string | null;
+        amount: string;
+        runSignals: number;
+    } | null;
+    /** The composite that covers this row's billing, by name — the row's price
+     *  is then included in that composite's own charge, not billed on top. Set
+     *  on credit / outcome / unit / outcome_completion rows tagged into a
+     *  composite on the customer's plan; `null` otherwise. */
+    coveredByComposite: string | null;
+    /** The `custom` object sent, as sent — on the signal itself, or on the
+     *  `completeComposite()` / `completeOutcome()` call that closed a composite /
+     *  outcome_completion row. `null` when none was sent. */
+    custom: Record<string, unknown> | null;
 }
 interface UsageLogPage {
     usageLogs: UsageLogEntry[];
@@ -452,8 +471,6 @@ interface ApiCustomer {
     taxId: string | null;
     currencyCode: string;
     creditAllowance: number;
-    recurringTransactionEmail: boolean;
-    autoRecurring: boolean;
     createdAt: string;
     updatedAt: string;
 }
@@ -483,10 +500,6 @@ interface CustomerProfileInput {
     taxId?: string | null;
     /** ISO 4217 (3 letters); must be enabled for the org. */
     currencyCode?: string;
-    /** Send the invoice, payment receipt and card-payment-failed emails for recurring invoices. Defaults to `true` on create. */
-    recurringTransactionEmail?: boolean;
-    /** Issue every recurring invoice as `AUTO_CLOSED` (applied as if paid, never payable). Defaults to `false` on create. */
-    autoRecurring?: boolean;
 }
 /** `name` and `email` are required on create; every other field is optional. */
 type CreateCustomerInput = CustomerProfileInput & {
@@ -578,6 +591,79 @@ interface CustomerBalances {
      *  isn't listed. */
     composites: CompositeBalance[];
 }
+/** What caused a wallet ledger row (`WalletTransaction.source`). */
+type WalletTransactionSource = 
+/** Wallet money from a new plan purchase. */
+"SUBSCRIPTION"
+/** Wallet money from a plan renewal, or unused money removed at renewal. */
+ | "RENEWAL"
+/** Changed in the ClockNext dashboard. */
+ | "MANUAL"
+/** Changed with `customers.adjustWallet()`. */
+ | "API"
+/** Top-up paid by the customer in the customer portal. */
+ | "CUSTOMER_PORTAL"
+/** Charged by a signal; `usageLogId` links the signal. */
+ | "USAGE_LOG"
+/** Usage cleared by a paid pay-as-you-go invoice. */
+ | "INVOICE_SETTLEMENT"
+/** Settlement undone by a voided invoice. */
+ | "INVOICE_VOID";
+/** One row of a customer's wallet ledger (`customers.wallet()`). */
+interface WalletTransaction {
+    id: string;
+    /** ISO 8601. */
+    createdAt: string;
+    /** `CREDIT` adds money, `DEBIT` takes it out. */
+    type: "CREDIT" | "DEBIT";
+    /** Which balance moved: the ordinary wallet or the Reserved Wallet. */
+    pool: "main" | "reserved";
+    source: WalletTransactionSource;
+    /** Always positive — `type` gives the direction. In `currencyCode`. */
+    amount: number;
+    /** The same amount in USD. */
+    amountUsd: number;
+    currencyCode: string;
+    /** 1 USD = this many units of `currencyCode`, at write time. */
+    currencyRateUsd: number;
+    /** Only text a person wrote: your own note on an `API` row, the admin's
+     *  note on a `MANUAL` row. `null` on every row the system writes itself —
+     *  `source` says what those are. */
+    notes: string | null;
+    /** On a usage charge for an entitlement: which kind. `null` otherwise. */
+    entitlementType: "CREDIT" | "OUTCOME" | "UNIT" | "COMPOSITE" | null;
+    /** Id of that credit / outcome / unit / composite. */
+    entitlementId: string | null;
+    /** Its name when the row was written. */
+    entitlementName: string | null;
+    /** On a `USAGE_LOG` row: the id of the matching row in
+     *  `signals.usageLog()`. */
+    usageLogId: string | null;
+    /** On a `SUBSCRIPTION` / `RENEWAL` grant: the purchase it came from. */
+    purchaseId: string | null;
+    purchaseNumber: string | null;
+}
+/** One page of a customer's wallet ledger, newest first. */
+interface WalletLedgerPage {
+    /** Ordinary wallet balance, USD. May be negative. */
+    balanceUsd: number;
+    /** Reserved Wallet balance, USD; `null` when the workspace hasn't enabled
+     *  it. */
+    reservedBalanceUsd: number | null;
+    transactions: WalletTransaction[];
+    /** Pass back as `cursor` for the next page; `null` on the last page. */
+    nextCursor: string | null;
+}
+interface WalletLedgerParams {
+    /** Default 50, max 200. */
+    limit?: number;
+    /** A previous page's `nextCursor`. Omit for the first page. */
+    cursor?: string;
+    /** First day to include, `YYYY-MM-DD` (UTC). The whole day is included. */
+    from?: string;
+    /** Last day to include, `YYYY-MM-DD` (UTC). The whole day is included. */
+    to?: string;
+}
 /** The customer's active plan (the `plan` field of `customers.plan()`);
  *  `null` when the customer is unsubscribed. */
 interface CustomerPlanDetails {
@@ -878,6 +964,42 @@ interface CreateUnitInput {
 }
 /** `units.update()` body — PARTIAL. `tiers`, when sent, is the complete list. */
 type UpdateUnitInput = Partial<CreateUnitInput>;
+/** How a tax applies: `"inclusive"` — already inside the price;
+ *  `"exclusive"` — added on top. Lower case only. */
+type TaxBehavior = "inclusive" | "exclusive";
+/** A tax rate, charged to customers whose billing country matches. */
+interface Tax {
+    id: string;
+    /** Shown on invoices. Unique among active taxes in the same country,
+     *  ignoring case. */
+    name: string;
+    /** A note for your team; not shown to customers. */
+    description: string | null;
+    /** 0–100. */
+    percentage: number;
+    /** ISO 3166-1 alpha-2, upper case (e.g. `"IN"`). */
+    countryCode: string;
+    behavior: TaxBehavior;
+    /** `false` once archived in the dashboard (Settings → Taxes): it no longer
+     *  applies to new invoices. */
+    isActive: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** `taxes.create()` body. */
+interface CreateTaxInput {
+    /** 1–100 characters. */
+    name: string;
+    /** 0–100. */
+    percentage: number;
+    /** ISO 3166-1 alpha-2 (lower case is accepted). A country name is refused. */
+    countryCode: string;
+    behavior: TaxBehavior;
+    /** Up to 500 characters. */
+    description?: string | null;
+}
+/** `taxes.update()` body — PARTIAL: only the fields you send change. */
+type UpdateTaxInput = Partial<CreateTaxInput>;
 /** A catalogue item a composite wraps. */
 interface CompositeItem {
     id: string;
@@ -987,7 +1109,8 @@ interface PurchaseDetail {
         paidCount: number;
     };
 }
-/** `AUTO_CLOSED` — a recurring invoice for a customer with `autoRecurring` on:
+/** `AUTO_CLOSED` — a recurring invoice of an organisation with "Auto close
+ *  invoices on recurring" on (dashboard: Settings → Organisation → Billing):
  *  applied as if paid, but never payable. */
 type InvoiceStatus = "OPEN" | "PAID" | "VOID" | "AUTO_CLOSED";
 /** Trimmed row from `invoices.list()`. */
@@ -1360,6 +1483,8 @@ type UnitInput = CustomerRef & {
     quantity?: number;
     /** Optional composite this unit report belongs to. See {@link CompositeTag}. */
     composite?: CompositeTag;
+    /** Free-form metadata, stored as-is with this unit report. Never priced. */
+    custom?: Record<string, unknown>;
     /**
      * Idempotency key for safe retries — a repeat carrying the same key returns
      * the original result instead of drawing the balance down twice.
@@ -1409,6 +1534,9 @@ type CompositeCompletionInput = CustomerRef & {
     /** Which occurrence to close: the composite's `refId` and the correlation
      *  value the signals were tagged with. */
     composite: CompositeTag;
+    /** Free-form metadata, stored as-is on the occurrence this call closes.
+     *  Never priced. */
+    custom?: Record<string, unknown>;
     /** Idempotency key, auto-generated if omitted. Closing twice is already a
      *  safe no-op, so this only collapses retries into one recorded attempt
      *  rather than protecting against a double charge. */
@@ -1709,6 +1837,22 @@ declare class Customers {
     delete(id: string): Promise<void>;
     /** Wallet / credit / outcome / unit balances. `GET …/:id/balances`. */
     balances(id: string): Promise<CustomerBalances>;
+    /**
+     * One page of the customer's wallet ledger — every movement of wallet
+     * money, newest first — plus both wallet balances. Cursor-paginated: pass
+     * back `nextCursor` as `cursor`. `GET /api/v1/customers/:id/wallet`.
+     */
+    wallet(id: string, params?: WalletLedgerParams): Promise<WalletLedgerPage>;
+    /** {@link wallet}, addressing the customer by its `externalId`.
+     *  `GET /api/v1/customers/ext/:externalId/wallet`. */
+    walletByExternalId(externalId: string, params?: WalletLedgerParams): Promise<WalletLedgerPage>;
+    /**
+     * Async iterator over the customer's WHOLE wallet ledger, newest first,
+     * following the cursor. `params.cursor` is ignored.
+     * `for await (const t of cnk.customers.iterateWallet(id)) { … }`
+     */
+    iterateWallet(id: string, params?: Omit<WalletLedgerParams, "cursor">): AsyncGenerator<WalletTransaction>;
+    private walletPage;
     /** {@link balances}, addressing the customer by its `externalId`.
      *  `GET /api/v1/customers/ext/:externalId/balances`. */
     balancesByExternalId(externalId: string): Promise<CustomerBalances>;
@@ -2211,6 +2355,34 @@ declare class Units {
     unarchive(id: string): Promise<Unit>;
 }
 
+/**
+ * The `taxes` resource — the tax rates charged to customers by billing
+ * country (the same rates as Settings → Taxes). `/api/v1/taxes`.
+ *
+ * Every active tax for a customer's country is applied to their invoices and
+ * portal purchases automatically. There is no `delete()`, `archive()` or
+ * `unarchive()` — archiving and restoring a tax is done in the dashboard.
+ */
+declare class Taxes {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** List them, oldest first. `{ active: true }` returns only active ones,
+     *  `{ active: false }` only archived ones; omit it for both. */
+    list(params?: {
+        active?: boolean;
+    }): Promise<Tax[]>;
+    /** One tax. */
+    get(id: string): Promise<Tax>;
+    /** Create one. It starts active. Two active taxes can't share a name
+     *  (ignoring case) in the same country — that's a `ConflictError`. Not
+     *  retried on failure — a retry could create a second row. */
+    create(input: CreateTaxInput): Promise<Tax>;
+    /** PARTIAL update: only the fields you send change. Archived taxes can be
+     *  edited and stay archived. Only invoices issued afterwards use the new
+     *  values. */
+    update(id: string, input: UpdateTaxInput): Promise<Tax>;
+}
+
 /**
  * The ClockNext client.
  *
@@ -2243,6 +2415,8 @@ declare class ClockNext {
     readonly units: Units;
     /** Composites: list, get, create, update, archive, unarchive (no delete). */
     readonly composites: Composites;
+    /** Tax rates by country: list, get, create, update (archive in the dashboard). */
+    readonly taxes: Taxes;
     /** Subscribe customers to plans (purchases). */
     readonly purchases: Purchases;
     /** Read invoices and mint hosted pay links. */
@@ -2338,4 +2512,4 @@ declare class NetworkError extends ClockNextError {
     });
 }
 
-export { type AddMemberInput, type AdjustResult, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeAdjustInput, type CompositeBalance, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeItem, type CompositeTag, ConflictError, type CreateCompositeInput, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditBalance, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerPlanDetails, type CustomerProfileInput, type CustomerRef, type DropReason, type FetchLike, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type ModelBundleLine, type ModelBundleLineInput, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeBalance, type OutcomeCompletionInput, type OutcomeCompletionResult, type OutcomeInput, type OutcomeSignal, type OutcomeStep, type OutcomeStepInput, type OutcomeWithSteps, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanEntitlement, type PlanEntitlementInput, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RecurringGrantInput, type RecurringGrantResult, type RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, type SignalStatus, type SignalType, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitBalance, type UnitInput, type UnitPricingType, type UnitTier, type UnitTrackResult, type UpdateCompositeInput, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateUnitInput, type UsageBalance, type UsageLogAppliedRule, type UsageLogEntry, type UsageLogListParams, type UsageLogOutcomeAttribution, type UsageLogPage, type UsageLogPeriod, ValidationError, type WalletAdjustInput, type WalletInput, type WalletPool, type WalletSignal, signalToWire };
+export { type AddMemberInput, type AdjustResult, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeAdjustInput, type CompositeBalance, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeItem, type CompositeTag, ConflictError, type CreateCompositeInput, type CreateCreditInput, type CreateCustomerInput, type CreateOutcomeInput, type CreatePlanInput, type CreatePurchaseInput, type CreateTaxInput, type CreateUnitInput, type Credit, type CreditAdjustInput, type CreditBalance, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerPlanDetails, type CustomerProfileInput, type CustomerRef, type DropReason, type FetchLike, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type ModelBundleLine, type ModelBundleLineInput, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeBalance, type OutcomeCompletionInput, type OutcomeCompletionResult, type OutcomeInput, type OutcomeSignal, type OutcomeStep, type OutcomeStepInput, type OutcomeWithSteps, type PayLink, type PaymentDetail, type PaymentRow, type Plan, type PlanComponent, type PlanEntitlement, type PlanEntitlementInput, PlanError, type PlanKind, type PlanRef, type PlanType, type PortalToken, type PortalTokenInput, type Purchase, type PurchaseDetail, type PurchaseStatus, RateLimitError, type RecurringGrantInput, type RecurringGrantResult, type RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, type SignalStatus, type SignalType, type Tax, type TaxBehavior, type Tokens, type TrackResult, type Unit, type UnitAdjustInput, type UnitBalance, type UnitInput, type UnitPricingType, type UnitTier, type UnitTrackResult, type UpdateCompositeInput, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateTaxInput, type UpdateUnitInput, type UsageBalance, type UsageLogAppliedRule, type UsageLogEntry, type UsageLogListParams, type UsageLogOutcomeAttribution, type UsageLogPage, ValidationError, type WalletAdjustInput, type WalletInput, type WalletLedgerPage, type WalletLedgerParams, type WalletPool, type WalletSignal, type WalletTransaction, type WalletTransactionSource, signalToWire };