@clocknext/sdk 0.19.0 → 0.19.1

package/dist/index.d.cts

@@ -451,6 +451,104 @@ interface UsageLogPage {
      *  page. */
     nextCursor: string | null;
 }
+/** What a {@link UsageLogLookupEntry} row is. `"outcome"` is one step of a
+ *  run; `"outcome_completion"` and `"composite_completion"` are the finished
+ *  runs themselves. */
+type UsageLogLookupEntitlementType = "credit" | "outcome" | "outcome_completion" | "unit" | "composite_completion" | "wallet";
+/**
+ * One row of `signals.lookupUsageLogs()`. Only the group that matches
+ * `entitlement.type` holds data; the others are `null`.
+ */
+interface UsageLogLookupEntry {
+    id: string;
+    /** The customer this row belongs to — a lookup can span customers. */
+    customerId: string;
+    /** For a finished run (`outcome_completion`, `composite_completion`), when
+     *  it completed. */
+    createdAt: string;
+    status: SignalStatus;
+    /** The credit / outcome / unit / composite this row is for. A wallet row has
+     *  `id: null` and `name: "Wallet"`. */
+    entitlement: {
+        type: UsageLogLookupEntitlementType;
+        id: string | null;
+        name: string | null;
+    };
+    member: string | null;
+    model: {
+        name: string | null;
+        provider: string | null;
+    } | null;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        /** Cache-read tokens. */
+        cacheTokens: number;
+        /** Cache-write tokens, priced separately from cache reads. */
+        cacheWriteTokens: number;
+    };
+    /** Formatted USD strings. `customerCost` is what this row charged:
+     *  `"$0.00"` on an outcome step (the run is billed at completion) and on any
+     *  row a composite pays for. On a unit row it is what the wallet paid for
+     *  that report (debits minus refunds), `"$0.00"` when the wallet paid
+     *  nothing. */
+    cost: {
+        providedCost: string;
+        customerCost: string;
+    };
+    /** `entitlement.type === "credit"`. */
+    credit: {
+        amount: string;
+        appliedRules: UsageLogAppliedRule[];
+    } | null;
+    /** `entitlement.type === "outcome"`. `runCompleted` is true once the run is
+     *  finished — on every step row of that run. */
+    outcome: {
+        step: string | null;
+        stepName: string | null;
+        runId: string | null;
+        runCompleted: boolean;
+    } | null;
+    /** `entitlement.type === "outcome_completion"`. `amount` is the price frozen
+     *  when the run completed. */
+    outcomeCompletion: {
+        runId: string | null;
+        amount: string;
+    } | null;
+    /** `entitlement.type === "unit"`. `quantity` is formatted. */
+    unit: {
+        quantity: string;
+    } | null;
+    /** `entitlement.type === "composite_completion"`. `refId` is the
+     *  composite's tag key, `runId` the tag value you sent. */
+    compositeCompletion: {
+        refId: string | null;
+        runId: string | null;
+        amount: string;
+        startedAt: string;
+    } | null;
+    /** `entitlement.type === "wallet"`. What the wallet paid, formatted USD —
+     *  the same value as `cost.customerCost`. */
+    wallet: {
+        amount: string;
+    } | null;
+    /** The composite that pays for this row — its id, its tag key (`refId`) and
+     *  the tag value you sent (`runId`). `null` when the row is billed by
+     *  itself. */
+    composite: {
+        id: string | null;
+        refId: string | null;
+        runId: string | null;
+    } | null;
+    /** The `custom` object sent, as sent. `null` when none was sent. */
+    custom: Record<string, unknown> | null;
+}
+interface UsageLogLookupResult {
+    /** The rows found, in the order of the ids you asked for. */
+    usageLogs: UsageLogLookupEntry[];
+    /** The ids that matched nothing in your org, in the order you asked. */
+    notFound: string[];
+}
 interface ApiCustomer {
     id: string;
     /** Your own id for this customer, or `null` when unset. See
@@ -2324,6 +2422,20 @@ declare class Signals {
      * buffer or retry here.
      */
     usageLog(params: UsageLogListParams): Promise<UsageLogPage>;
+    /**
+     * Fetches up to 100 usage-log rows by id, in one call.
+     * `GET /api/v1/signal/usage-log/lookup`.
+     *
+     * Built for linking a wallet debit to its usage: pass the `usageLogId`s
+     * from `customers.wallet()` instead of paging through
+     * {@link usageLog}. Scoped to your org, not to one customer — every row
+     * carries its own `customerId`.
+     *
+     * Rows come back in the order of `ids`; duplicates are removed. Ids that
+     * match nothing in your org are listed in `notFound`. More than 100
+     * distinct ids is a 400.
+     */
+    lookupUsageLogs(ids: string[]): Promise<UsageLogLookupResult>;
 }
 
 /**
@@ -2512,4 +2624,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 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 };
+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 UsageLogLookupEntitlementType, type UsageLogLookupEntry, type UsageLogLookupResult, type UsageLogOutcomeAttribution, type UsageLogPage, ValidationError, type WalletAdjustInput, type WalletInput, type WalletLedgerPage, type WalletLedgerParams, type WalletPool, type WalletSignal, type WalletTransaction, type WalletTransactionSource, signalToWire };

package/dist/index.d.ts

@@ -451,6 +451,104 @@ interface UsageLogPage {
      *  page. */
     nextCursor: string | null;
 }
+/** What a {@link UsageLogLookupEntry} row is. `"outcome"` is one step of a
+ *  run; `"outcome_completion"` and `"composite_completion"` are the finished
+ *  runs themselves. */
+type UsageLogLookupEntitlementType = "credit" | "outcome" | "outcome_completion" | "unit" | "composite_completion" | "wallet";
+/**
+ * One row of `signals.lookupUsageLogs()`. Only the group that matches
+ * `entitlement.type` holds data; the others are `null`.
+ */
+interface UsageLogLookupEntry {
+    id: string;
+    /** The customer this row belongs to — a lookup can span customers. */
+    customerId: string;
+    /** For a finished run (`outcome_completion`, `composite_completion`), when
+     *  it completed. */
+    createdAt: string;
+    status: SignalStatus;
+    /** The credit / outcome / unit / composite this row is for. A wallet row has
+     *  `id: null` and `name: "Wallet"`. */
+    entitlement: {
+        type: UsageLogLookupEntitlementType;
+        id: string | null;
+        name: string | null;
+    };
+    member: string | null;
+    model: {
+        name: string | null;
+        provider: string | null;
+    } | null;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        /** Cache-read tokens. */
+        cacheTokens: number;
+        /** Cache-write tokens, priced separately from cache reads. */
+        cacheWriteTokens: number;
+    };
+    /** Formatted USD strings. `customerCost` is what this row charged:
+     *  `"$0.00"` on an outcome step (the run is billed at completion) and on any
+     *  row a composite pays for. On a unit row it is what the wallet paid for
+     *  that report (debits minus refunds), `"$0.00"` when the wallet paid
+     *  nothing. */
+    cost: {
+        providedCost: string;
+        customerCost: string;
+    };
+    /** `entitlement.type === "credit"`. */
+    credit: {
+        amount: string;
+        appliedRules: UsageLogAppliedRule[];
+    } | null;
+    /** `entitlement.type === "outcome"`. `runCompleted` is true once the run is
+     *  finished — on every step row of that run. */
+    outcome: {
+        step: string | null;
+        stepName: string | null;
+        runId: string | null;
+        runCompleted: boolean;
+    } | null;
+    /** `entitlement.type === "outcome_completion"`. `amount` is the price frozen
+     *  when the run completed. */
+    outcomeCompletion: {
+        runId: string | null;
+        amount: string;
+    } | null;
+    /** `entitlement.type === "unit"`. `quantity` is formatted. */
+    unit: {
+        quantity: string;
+    } | null;
+    /** `entitlement.type === "composite_completion"`. `refId` is the
+     *  composite's tag key, `runId` the tag value you sent. */
+    compositeCompletion: {
+        refId: string | null;
+        runId: string | null;
+        amount: string;
+        startedAt: string;
+    } | null;
+    /** `entitlement.type === "wallet"`. What the wallet paid, formatted USD —
+     *  the same value as `cost.customerCost`. */
+    wallet: {
+        amount: string;
+    } | null;
+    /** The composite that pays for this row — its id, its tag key (`refId`) and
+     *  the tag value you sent (`runId`). `null` when the row is billed by
+     *  itself. */
+    composite: {
+        id: string | null;
+        refId: string | null;
+        runId: string | null;
+    } | null;
+    /** The `custom` object sent, as sent. `null` when none was sent. */
+    custom: Record<string, unknown> | null;
+}
+interface UsageLogLookupResult {
+    /** The rows found, in the order of the ids you asked for. */
+    usageLogs: UsageLogLookupEntry[];
+    /** The ids that matched nothing in your org, in the order you asked. */
+    notFound: string[];
+}
 interface ApiCustomer {
     id: string;
     /** Your own id for this customer, or `null` when unset. See
@@ -2324,6 +2422,20 @@ declare class Signals {
      * buffer or retry here.
      */
     usageLog(params: UsageLogListParams): Promise<UsageLogPage>;
+    /**
+     * Fetches up to 100 usage-log rows by id, in one call.
+     * `GET /api/v1/signal/usage-log/lookup`.
+     *
+     * Built for linking a wallet debit to its usage: pass the `usageLogId`s
+     * from `customers.wallet()` instead of paging through
+     * {@link usageLog}. Scoped to your org, not to one customer — every row
+     * carries its own `customerId`.
+     *
+     * Rows come back in the order of `ids`; duplicates are removed. Ids that
+     * match nothing in your org are listed in `notFound`. More than 100
+     * distinct ids is a 400.
+     */
+    lookupUsageLogs(ids: string[]): Promise<UsageLogLookupResult>;
 }
 
 /**
@@ -2512,4 +2624,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 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 };
+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 UsageLogLookupEntitlementType, type UsageLogLookupEntry, type UsageLogLookupResult, type UsageLogOutcomeAttribution, type UsageLogPage, ValidationError, type WalletAdjustInput, type WalletInput, type WalletLedgerPage, type WalletLedgerParams, type WalletPool, type WalletSignal, type WalletTransaction, type WalletTransactionSource, signalToWire };

package/dist/index.js

@@ -331,7 +331,7 @@ function sleep(ms) {
 }
 
 // src/http.ts
-var SDK_VERSION = "0.19.0" ;
+var SDK_VERSION = "0.19.1" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;
@@ -1226,6 +1226,7 @@ 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";
+var USAGE_LOG_LOOKUP_PATH = "/api/v1/signal/usage-log/lookup";
 function signalToWire(signal) {
   const t = signal.tokens;
   const body = {
@@ -1488,6 +1489,26 @@ var Signals = class {
       }
     });
   }
+  /**
+   * Fetches up to 100 usage-log rows by id, in one call.
+   * `GET /api/v1/signal/usage-log/lookup`.
+   *
+   * Built for linking a wallet debit to its usage: pass the `usageLogId`s
+   * from `customers.wallet()` instead of paging through
+   * {@link usageLog}. Scoped to your org, not to one customer — every row
+   * carries its own `customerId`.
+   *
+   * Rows come back in the order of `ids`; duplicates are removed. Ids that
+   * match nothing in your org are listed in `notFound`. More than 100
+   * distinct ids is a 400.
+   */
+  lookupUsageLogs(ids) {
+    return this.transport.request({
+      method: "GET",
+      path: USAGE_LOG_LOOKUP_PATH,
+      query: { ids: ids.join(",") }
+    });
+  }
 };
 
 // src/resources/units.ts