@clocknext/sdk 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -18,6 +18,21 @@ interface Tokens {
     output: number;
     cache?: number;
 }
+/**
+ * Tags a signal with a pricing metric for reporting. `ref` is the metric's
+ * `refId` (defined in Settings → Pricing metrics) and `value` is your own
+ * correlation id — a session, a call, a tenant — which the metric rolls up one
+ * row per distinct value. Reporting only: a metric never affects billing, a bad
+ * tag never fails the signal, and a `ref` naming no live metric is simply
+ * ignored. Applies to credit and outcome signals (ignored on wallet).
+ */
+interface MetricTag {
+    /** The metric's `refId`. Case-insensitive; must not collide with a reserved
+     *  ingest field (e.g. `model`, `member`, `agentKey`, `runId`, `custom`). */
+    ref: string;
+    /** Your correlation value for this metric, stored verbatim. */
+    value: string | number;
+}
 /** The organisation + key behind a request — `cnk.workspace.me()`. */
 interface WorkspaceIdentity {
     organization: {
@@ -75,16 +90,36 @@ interface CreditSignal extends SignalBase {
     type: "credit";
     /** The Credit's stable agent key (assigned when the credit was created). */
     agentKey: string;
+    /** Optional pricing-metric tag for reporting. */
+    metric?: MetricTag;
 }
 /** 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 `agentKey`. */
+/**
+ * Records one step of a multi-call outcome run. The `agentKey` identifies the
+ * step (and the outcome); `runId` groups every signal of a single run, so a step
+ * may repeat freely. The run bills once, when the caller marks it `complete`.
+ */
 interface OutcomeSignal extends SignalBase {
     type: "outcome";
     /** The OutcomeStep's stable agent key — identifies the outcome AND the step. */
     agentKey: string;
+    /**
+     * Correlates every signal of one workflow run. Required. A step may fire more
+     * than once within a run (a "verify" loop firing 3× is three signals, one
+     * outcome). Opaque to ClockNext — any string you can correlate; unique per org.
+     */
+    runId: string;
+    /**
+     * Set `true` on the LAST step signal to declare the run finished — completion
+     * is never inferred from step coverage. Sending it twice is a safe no-op and
+     * can't bill again.
+     */
+    complete?: boolean;
+    /** Optional pricing-metric tag for reporting. */
+    metric?: MetricTag;
 }
 type Signal = CreditSignal | WalletSignal | OutcomeSignal;
 /** Helper input shapes for the per-type convenience methods. */
@@ -98,9 +133,21 @@ interface SerializedRuleApplication {
 }
 interface SerializedOutcomeAttribution {
     name: string;
+    /** The step of the outcome this signal performed. */
     step: string;
+    /** The caller's run id — every signal of one run shares it. `null` on logs
+     *  recorded before the run-based flow. */
+    runId: string | null;
+    /** True when this signal ended the run (`complete: true`). */
+    closedRun: boolean;
+    /** True once the run's completion was counted against the allowance. Diverges
+     *  from `closedRun` only when a run closes with no allowance left — it waits,
+     *  then flips true once a top-up settles it. */
     completed: boolean;
-    progressSteps: string[];
+    /** How many signals the run holds after this one. */
+    signalCount: number;
+    /** The outcome's catalogue step count — not a progress target, since steps
+     *  may repeat within a run. */
     totalSteps: number;
 }
 /** The customer's remaining balance for the dimension a signal metered, AFTER
@@ -1592,4 +1639,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 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 };
+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 MetricTag, 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 };

package/dist/index.d.ts

@@ -18,6 +18,21 @@ interface Tokens {
     output: number;
     cache?: number;
 }
+/**
+ * Tags a signal with a pricing metric for reporting. `ref` is the metric's
+ * `refId` (defined in Settings → Pricing metrics) and `value` is your own
+ * correlation id — a session, a call, a tenant — which the metric rolls up one
+ * row per distinct value. Reporting only: a metric never affects billing, a bad
+ * tag never fails the signal, and a `ref` naming no live metric is simply
+ * ignored. Applies to credit and outcome signals (ignored on wallet).
+ */
+interface MetricTag {
+    /** The metric's `refId`. Case-insensitive; must not collide with a reserved
+     *  ingest field (e.g. `model`, `member`, `agentKey`, `runId`, `custom`). */
+    ref: string;
+    /** Your correlation value for this metric, stored verbatim. */
+    value: string | number;
+}
 /** The organisation + key behind a request — `cnk.workspace.me()`. */
 interface WorkspaceIdentity {
     organization: {
@@ -75,16 +90,36 @@ interface CreditSignal extends SignalBase {
     type: "credit";
     /** The Credit's stable agent key (assigned when the credit was created). */
     agentKey: string;
+    /** Optional pricing-metric tag for reporting. */
+    metric?: MetricTag;
 }
 /** 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 `agentKey`. */
+/**
+ * Records one step of a multi-call outcome run. The `agentKey` identifies the
+ * step (and the outcome); `runId` groups every signal of a single run, so a step
+ * may repeat freely. The run bills once, when the caller marks it `complete`.
+ */
 interface OutcomeSignal extends SignalBase {
     type: "outcome";
     /** The OutcomeStep's stable agent key — identifies the outcome AND the step. */
     agentKey: string;
+    /**
+     * Correlates every signal of one workflow run. Required. A step may fire more
+     * than once within a run (a "verify" loop firing 3× is three signals, one
+     * outcome). Opaque to ClockNext — any string you can correlate; unique per org.
+     */
+    runId: string;
+    /**
+     * Set `true` on the LAST step signal to declare the run finished — completion
+     * is never inferred from step coverage. Sending it twice is a safe no-op and
+     * can't bill again.
+     */
+    complete?: boolean;
+    /** Optional pricing-metric tag for reporting. */
+    metric?: MetricTag;
 }
 type Signal = CreditSignal | WalletSignal | OutcomeSignal;
 /** Helper input shapes for the per-type convenience methods. */
@@ -98,9 +133,21 @@ interface SerializedRuleApplication {
 }
 interface SerializedOutcomeAttribution {
     name: string;
+    /** The step of the outcome this signal performed. */
     step: string;
+    /** The caller's run id — every signal of one run shares it. `null` on logs
+     *  recorded before the run-based flow. */
+    runId: string | null;
+    /** True when this signal ended the run (`complete: true`). */
+    closedRun: boolean;
+    /** True once the run's completion was counted against the allowance. Diverges
+     *  from `closedRun` only when a run closes with no allowance left — it waits,
+     *  then flips true once a top-up settles it. */
     completed: boolean;
-    progressSteps: string[];
+    /** How many signals the run holds after this one. */
+    signalCount: number;
+    /** The outcome's catalogue step count — not a progress target, since steps
+     *  may repeat within a run. */
     totalSteps: number;
 }
 /** The customer's remaining balance for the dimension a signal metered, AFTER
@@ -1592,4 +1639,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 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 };
+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 MetricTag, 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 };

package/dist/index.js

@@ -227,7 +227,7 @@ function sleep(ms) {
 }
 
 // src/http.ts
-var SDK_VERSION = "0.6.0" ;
+var SDK_VERSION = "0.7.0" ;
 var Transport = class {
   constructor(cfg) {
     this.cfg = cfg;
@@ -868,6 +868,13 @@ function signalToWire(signal) {
   if (signal.type === "credit" || signal.type === "outcome") {
     body.agentKey = signal.agentKey;
   }
+  if (signal.type === "outcome") {
+    body.runId = signal.runId;
+    if (signal.complete != null) body.complete = signal.complete;
+  }
+  if (signal.type !== "wallet" && signal.metric) {
+    body[signal.metric.ref] = signal.metric.value;
+  }
   if (signal.idempotencyKey) body.idempotencyKey = signal.idempotencyKey;
   return body;
 }