@clocknext/sdk 0.13.0 → 0.14.0

package/dist/index.d.cts

@@ -356,6 +356,93 @@ interface UsageList {
     };
     logs: SerializedUsageLog[];
 }
+/** 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. */
+    limit?: number;
+    /** 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"`. */
+    from?: string;
+    /** `YYYY-MM-DD`, only used when `period` is `"custom"`. */
+    to?: string;
+}
+interface UsageLogAppliedRule {
+    ruleId: string | null;
+    ruleName: string;
+    mode: "MARGIN" | "CREDIT" | null;
+    marginPercentApplied: number | null;
+    /** Formatted, same as {@link UsageLogEntry.credit}'s `amount`. */
+    creditsApplied: string;
+}
+interface UsageLogOutcomeAttribution {
+    /** "2 / 4" — the step this call performed, and the outcome's total step
+     *  count. Not a progress target: a step may repeat within a run. */
+    step: string | null;
+    stepName: string | null;
+    runId: string | null;
+    /** How many signals the run holds. */
+    runSignals: number;
+    /** True once the run closed (`complete: true` was sent for it). */
+    closedRun: boolean;
+}
+/**
+ * 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.
+ */
+interface UsageLogEntry {
+    id: string;
+    createdAt: string;
+    kind: "credit" | "outcome" | "unit" | "wallet" | "composite";
+    status: SignalStatus;
+    typeName: string | null;
+    member: string | null;
+    model: {
+        name: string | null;
+        provider: string | null;
+    } | null;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheTokens: number;
+    };
+    /** Formatted USD strings (e.g. `"$0.0064"`). */
+    cost: {
+        providedCost: string;
+        customerCost: string;
+    };
+    /** Populated only when `kind === "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"`. */
+    outcome: UsageLogOutcomeAttribution | null;
+    /** Populated only when `kind === "unit"`. `quantity` is formatted. */
+    unit: {
+        quantity: string;
+    } | null;
+    /** Populated only when `kind === "composite"`. `amount` is a formatted USD
+     *  price — the composite's flat price, read live, not stored per row. */
+    composite: {
+        amount: string;
+    } | null;
+}
+interface UsageLogPage {
+    usageLogs: UsageLogEntry[];
+    /** Pass this back as `cursor` to fetch the next page; `null` on the last
+     *  page. */
+    nextCursor: string | null;
+}
 interface ApiCustomer {
     id: string;
     slug: string;
@@ -2119,6 +2206,24 @@ declare class Signals {
         customerId: string;
         limit?: number;
     }): Promise<UnitUsageList>;
+    /**
+     * One customer's usage history, merged from every meter kind — credit,
+     * outcome, unit, wallet, and completed composite occurrences — into one
+     * feed sorted by time. `GET /api/v1/signal/usage-log`. Exactly the same
+     * rows the customer portal's own "Usage logs" table shows, so a caller can
+     * build against this instead of the portal UI.
+     *
+     * Cursor-paginated, NOT page-numbered: `limit` + `cursor` in, `nextCursor`
+     * out. Omit `cursor` for the first page; pass the previous page's
+     * `nextCursor` back to fetch the next one, and stop once it comes back
+     * `null`. Unlike offset pagination, the cost of a page never grows with how
+     * deep you've paged — each page only asks for rows strictly before the
+     * cursor's position.
+     *
+     * Read-only; unlike {@link track}/{@link unit}/etc., there is nothing to
+     * buffer or retry here.
+     */
+    usageLog(params: UsageLogListParams): Promise<UsageLogPage>;
 }
 
 /**
@@ -2312,4 +2417,4 @@ declare class NetworkError extends ClockNextError {
     });
 }
 
-export { type AddMemberInput, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeAdjustInput, type CompositeCatalogueRef, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeComponentInput, type CompositeTag, ConflictError, type CostPoint, type CostStats, type CreateCompositeInput, 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, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type Model, type ModelBundleEntry, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeAnalytics, type OutcomeBalance, type OutcomeCompletionInput, type OutcomeCompletionResult, 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 RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, 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 UnitTrackResult, type UnitUsageList, type UnitUsageRow, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateUnitInput, type UpsertWebhookInput, type UsageBalance, type UsageList, ValidationError, type WalletComponentInput, type WalletEntitlementKind, type WalletEntryInput, type WalletInput, type WalletList, type WalletSignal, type WalletTransaction, type WalletTransactionSource, type WalletTransactionType, type Webhook, type WorkspaceIdentity, signalToWire };
+export { type AddMemberInput, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeAdjustInput, type CompositeCatalogueRef, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeComponentInput, type CompositeTag, ConflictError, type CostPoint, type CostStats, type CreateCompositeInput, 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, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type Model, type ModelBundleEntry, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeAnalytics, type OutcomeBalance, type OutcomeCompletionInput, type OutcomeCompletionResult, 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 RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, 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 UnitTrackResult, type UnitUsageList, type UnitUsageRow, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateUnitInput, type UpsertWebhookInput, type UsageBalance, type UsageList, type UsageLogAppliedRule, type UsageLogEntry, type UsageLogListParams, type UsageLogOutcomeAttribution, type UsageLogPage, type UsageLogPeriod, ValidationError, type WalletComponentInput, type WalletEntitlementKind, type WalletEntryInput, type WalletInput, type WalletList, type WalletSignal, type WalletTransaction, type WalletTransactionSource, type WalletTransactionType, type Webhook, type WorkspaceIdentity, signalToWire };

package/dist/index.d.ts

@@ -356,6 +356,93 @@ interface UsageList {
     };
     logs: SerializedUsageLog[];
 }
+/** 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. */
+    limit?: number;
+    /** 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"`. */
+    from?: string;
+    /** `YYYY-MM-DD`, only used when `period` is `"custom"`. */
+    to?: string;
+}
+interface UsageLogAppliedRule {
+    ruleId: string | null;
+    ruleName: string;
+    mode: "MARGIN" | "CREDIT" | null;
+    marginPercentApplied: number | null;
+    /** Formatted, same as {@link UsageLogEntry.credit}'s `amount`. */
+    creditsApplied: string;
+}
+interface UsageLogOutcomeAttribution {
+    /** "2 / 4" — the step this call performed, and the outcome's total step
+     *  count. Not a progress target: a step may repeat within a run. */
+    step: string | null;
+    stepName: string | null;
+    runId: string | null;
+    /** How many signals the run holds. */
+    runSignals: number;
+    /** True once the run closed (`complete: true` was sent for it). */
+    closedRun: boolean;
+}
+/**
+ * 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.
+ */
+interface UsageLogEntry {
+    id: string;
+    createdAt: string;
+    kind: "credit" | "outcome" | "unit" | "wallet" | "composite";
+    status: SignalStatus;
+    typeName: string | null;
+    member: string | null;
+    model: {
+        name: string | null;
+        provider: string | null;
+    } | null;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheTokens: number;
+    };
+    /** Formatted USD strings (e.g. `"$0.0064"`). */
+    cost: {
+        providedCost: string;
+        customerCost: string;
+    };
+    /** Populated only when `kind === "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"`. */
+    outcome: UsageLogOutcomeAttribution | null;
+    /** Populated only when `kind === "unit"`. `quantity` is formatted. */
+    unit: {
+        quantity: string;
+    } | null;
+    /** Populated only when `kind === "composite"`. `amount` is a formatted USD
+     *  price — the composite's flat price, read live, not stored per row. */
+    composite: {
+        amount: string;
+    } | null;
+}
+interface UsageLogPage {
+    usageLogs: UsageLogEntry[];
+    /** Pass this back as `cursor` to fetch the next page; `null` on the last
+     *  page. */
+    nextCursor: string | null;
+}
 interface ApiCustomer {
     id: string;
     slug: string;
@@ -2119,6 +2206,24 @@ declare class Signals {
         customerId: string;
         limit?: number;
     }): Promise<UnitUsageList>;
+    /**
+     * One customer's usage history, merged from every meter kind — credit,
+     * outcome, unit, wallet, and completed composite occurrences — into one
+     * feed sorted by time. `GET /api/v1/signal/usage-log`. Exactly the same
+     * rows the customer portal's own "Usage logs" table shows, so a caller can
+     * build against this instead of the portal UI.
+     *
+     * Cursor-paginated, NOT page-numbered: `limit` + `cursor` in, `nextCursor`
+     * out. Omit `cursor` for the first page; pass the previous page's
+     * `nextCursor` back to fetch the next one, and stop once it comes back
+     * `null`. Unlike offset pagination, the cost of a page never grows with how
+     * deep you've paged — each page only asks for rows strictly before the
+     * cursor's position.
+     *
+     * Read-only; unlike {@link track}/{@link unit}/etc., there is nothing to
+     * buffer or retry here.
+     */
+    usageLog(params: UsageLogListParams): Promise<UsageLogPage>;
 }
 
 /**
@@ -2312,4 +2417,4 @@ declare class NetworkError extends ClockNextError {
     });
 }
 
-export { type AddMemberInput, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeAdjustInput, type CompositeCatalogueRef, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeComponentInput, type CompositeTag, ConflictError, type CostPoint, type CostStats, type CreateCompositeInput, 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, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type Model, type ModelBundleEntry, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeAnalytics, type OutcomeBalance, type OutcomeCompletionInput, type OutcomeCompletionResult, 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 RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, 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 UnitTrackResult, type UnitUsageList, type UnitUsageRow, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateUnitInput, type UpsertWebhookInput, type UsageBalance, type UsageList, ValidationError, type WalletComponentInput, type WalletEntitlementKind, type WalletEntryInput, type WalletInput, type WalletList, type WalletSignal, type WalletTransaction, type WalletTransactionSource, type WalletTransactionType, type Webhook, type WorkspaceIdentity, signalToWire };
+export { type AddMemberInput, AllowanceError, type ApiCustomer, AuthError, type BillingCycle, type BillingMode, ClockNext, type ClockNextConfig, ClockNextError, type ClockNextErrorCode, type ComponentType, type Composite, type CompositeAdjustInput, type CompositeCatalogueRef, type CompositeCompletionInput, type CompositeCompletionResult, type CompositeComponentInput, type CompositeTag, ConflictError, type CostPoint, type CostStats, type CreateCompositeInput, 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, ForbiddenError, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListRow, type InvoiceParty, type InvoicePlanSnapshot, type InvoiceStatus, type Logger, type Member, type MemberProfile, type Model, type ModelBundleEntry, NetworkError, NotFoundError, type Outcome, type OutcomeAdjustInput, type OutcomeAnalytics, type OutcomeBalance, type OutcomeCompletionInput, type OutcomeCompletionResult, 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 RemovedMember, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUnitUsage, type SerializedUsageLog, ServerError, type Signal, type SignalDelivery, 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 UnitTrackResult, type UnitUsageList, type UnitUsageRow, type UpdateCreditInput, type UpdateMemberInput, type UpdateOutcomeInput, type UpdatePlanInput, type UpdateUnitInput, type UpsertWebhookInput, type UsageBalance, type UsageList, type UsageLogAppliedRule, type UsageLogEntry, type UsageLogListParams, type UsageLogOutcomeAttribution, type UsageLogPage, type UsageLogPeriod, ValidationError, type WalletComponentInput, type WalletEntitlementKind, type WalletEntryInput, type WalletInput, type WalletList, type WalletSignal, type WalletTransaction, type WalletTransactionSource, type WalletTransactionType, type Webhook, type WorkspaceIdentity, signalToWire };

package/dist/index.js

@@ -326,7 +326,7 @@ function sleep(ms) {
 }
 
 // src/http.ts
-var SDK_VERSION = "0.13.0" ;
+var SDK_VERSION = "0.14.0" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;
@@ -1029,6 +1029,7 @@ var SIGNAL_PATHS = {
 var UNIT_PATH = "/api/v1/signal/unit";
 var COMPOSITE_COMPLETE_PATH = "/api/v1/signal/composite/complete";
 var OUTCOME_COMPLETE_PATH = "/api/v1/signal/outcome/complete";
+var USAGE_LOG_PATH = "/api/v1/signal/usage-log";
 function signalToWire(signal) {
   const t = signal.tokens;
   const body = {
@@ -1287,6 +1288,37 @@ var Signals = class {
       query: { customerId: params.customerId, limit: params.limit }
     });
   }
+  /**
+   * One customer's usage history, merged from every meter kind — credit,
+   * outcome, unit, wallet, and completed composite occurrences — into one
+   * feed sorted by time. `GET /api/v1/signal/usage-log`. Exactly the same
+   * rows the customer portal's own "Usage logs" table shows, so a caller can
+   * build against this instead of the portal UI.
+   *
+   * Cursor-paginated, NOT page-numbered: `limit` + `cursor` in, `nextCursor`
+   * out. Omit `cursor` for the first page; pass the previous page's
+   * `nextCursor` back to fetch the next one, and stop once it comes back
+   * `null`. Unlike offset pagination, the cost of a page never grows with how
+   * deep you've paged — each page only asks for rows strictly before the
+   * cursor's position.
+   *
+   * Read-only; unlike {@link track}/{@link unit}/etc., there is nothing to
+   * buffer or retry here.
+   */
+  usageLog(params) {
+    return this.transport.request({
+      method: "GET",
+      path: USAGE_LOG_PATH,
+      query: {
+        customerId: params.customerId,
+        limit: params.limit,
+        cursor: params.cursor,
+        period: params.period,
+        from: params.from,
+        to: params.to
+      }
+    });
+  }
 };
 
 // src/resources/units.ts