@clocknext/sdk - npm Package Compare versions

Comparing version 0.6.0 to 0.7.0

dist/index.cjs

@@ -232,3 +232,3 @@ 'use strict';
 // src/http.ts
-var SDK_VERSION = "0.6.0" ;
+var SDK_VERSION = "0.7.0" ;
 var Transport = class {
@@ -874,2 +874,9 @@ constructor(cfg) {
   }
+  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;
@@ -876,0 +883,0 @@ return body;

dist/index.d.cts

@@ -21,2 +21,17 @@ /**
 }
+/**
+ * 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()`. */
@@ -79,2 +94,4 @@ interface WorkspaceIdentity {
     agentKey: string;
+    /** Optional pricing-metric tag for reporting. */
+    metric?: MetricTag;
 }
@@ -85,3 +102,7 @@ /** Debits the customer's wallet in USD at the model's cost. */
 }
-/** 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 {
@@ -91,2 +112,16 @@ type: "outcome";
     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;
 }
@@ -105,5 +140,17 @@ type Signal = CreditSignal | WalletSignal | OutcomeSignal;
     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;
@@ -1600,2 +1647,2 @@ }
 
-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 };

dist/index.d.ts

@@ -21,2 +21,17 @@ /**
 }
+/**
+ * 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()`. */
@@ -79,2 +94,4 @@ interface WorkspaceIdentity {
     agentKey: string;
+    /** Optional pricing-metric tag for reporting. */
+    metric?: MetricTag;
 }
@@ -85,3 +102,7 @@ /** Debits the customer's wallet in USD at the model's cost. */
 }
-/** 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 {
@@ -91,2 +112,16 @@ type: "outcome";
     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;
 }
@@ -105,5 +140,17 @@ type Signal = CreditSignal | WalletSignal | OutcomeSignal;
     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;
@@ -1600,2 +1647,2 @@ }
 
-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 };

dist/index.js

@@ -230,3 +230,3 @@ // src/config.ts
 // src/http.ts
-var SDK_VERSION = "0.6.0" ;
+var SDK_VERSION = "0.7.0" ;
 var Transport = class {
@@ -872,2 +872,9 @@ constructor(cfg) {
   }
+  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;
@@ -874,0 +881,0 @@ return body;

package.json

 {
   "name": "@clocknext/sdk",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Official ClockNext SDK — record usage signals and manage plans, purchases, invoices, customers, and billing from your backend.",
@@ -5,0 +5,0 @@ "license": "MIT",

README.md

@@ -58,6 +58,41 @@ # @clocknext/sdk
 
-// Outcome — advances one step of a workflow (agentKey = the OutcomeStep's agent key)
-await cnk.signals.outcome({ customerId, model: "llama-3.3-70b-versatile", agentKey: "resolved_ticket.triage" });
+// Outcome — one step of a run (agentKey = the OutcomeStep's agent key)
+await cnk.signals.outcome({ customerId, model: "llama-3.3-70b-versatile", agentKey: "resolved_ticket.triage", runId: "ticket_9021", tokens: { input: 600, output: 150 } });
 ```
 
+### Outcome runs
+
+An outcome is billed per **run**, not per step. Every signal for one run shares a
+`runId` (opaque — any id you can correlate, e.g. your ticket/session id), so a
+step can fire as many times as it needs to. The run bills **once**, when you mark
+the final step `complete: true` — completion is never inferred from step
+coverage. Sending `complete` twice is a safe no-op.
+
+```ts
+const runId = "ticket_9021";
+// each step of the run carries the same runId…
+await cnk.signals.outcome({ customerId, model, agentKey: "resolved_ticket.triage", runId, tokens: { input: 600, output: 150 } });
+await cnk.signals.outcome({ customerId, model, agentKey: "resolved_ticket.verify", runId, tokens: { input: 200, output: 80 } }); // may repeat
+// …and the last one closes (and bills) the run:
+await cnk.signals.outcome({ customerId, model, agentKey: "resolved_ticket.resolve", runId, complete: true, tokens: { input: 500, output: 200 } });
+```
+
+### Pricing metrics
+
+Tag any credit or outcome signal with a **pricing metric** for reporting. `ref`
+is the metric's ref ID (Settings → Pricing metrics) and `value` is your own
+correlation id; the metric rolls usage up one row per distinct value.
+
+```ts
+await cnk.signals.credit({
+  customerId, model: "llama-3.3-70b-versatile", agentKey: "api_credit",
+  tokens: { input: 1200, output: 340 },
+  metric: { ref: "voice_ai", value: "call_5f3a" },
+});
+```
+
+Metric tags are **reporting only** — they never change what's billed, a tag that
+names no live metric is silently ignored, and a bad tag never fails the signal.
+Tags on wallet signals are ignored.
+
 ### Async vs sync
@@ -64,0 +99,0 @@

No alert changes

Improved metrics

Total package byte prevSize

392444

2.23%

Lines of code

3922

1.58%

Number of lines in readme file

314

12.54%

No dependency changes