deepline 0.3.144 → 0.3.145

package/dist/bundling-sources/sdk/src/client.ts

@@ -1960,6 +1960,21 @@ export type WorkspacesNamespace = {
   }) => Promise<WorkspaceCreateResult>;
 };
 
+/** One authenticated per-request usage event from `/api/v2/usage/events`. */
+export type BillingUsageEvent = {
+  id: string | null;
+  provider: string;
+  operation: string;
+  status: string;
+  request_id: string;
+  billing_outcome_reason: string | null;
+  credits: number | null;
+  billing_mode: string | null;
+  pricing_model: string | null;
+  policy_id: string | null;
+  created_at: string;
+};
+
 /**
  * Public `client.billing` namespace for CLI commands and programmatic callers.
  * Covers plans, subscription state, cancellation, and invoice/receipt history.
@@ -1989,6 +2004,8 @@ export type BillingNamespace = {
     /** Subscription invoices plus credit purchase receipts, newest first. */
     list: (options?: { limit?: number }) => Promise<BillingInvoicesResult>;
   };
+  /** Read one exact execution outcome using the request_id returned by executeTool. */
+  usageEvent: (requestId: string) => Promise<BillingUsageEvent>;
   /** Metronome-authored target catalog and current Contract projection. */
   targetPlans: () => Promise<TargetBillingPlansResult>;
   /** Normalized target billing state. */
@@ -2600,6 +2617,7 @@ export class DeeplineClient {
       invoices: {
         list: (options) => this.listBillingInvoices(options),
       },
+      usageEvent: (requestId) => this.getBillingUsageEvent(requestId),
       targetPlans: () => this.getTargetBillingPlans(),
       targetStatus: () => this.getTargetBillingStatus(),
       autoRecharge: {
@@ -5803,6 +5821,40 @@ export class DeeplineClient {
     return this.http.get<BillingPlansResult>('/api/v2/billing/catalog/current');
   }
 
+  /**
+   * Read the authenticated usage record for one execution request. The
+   * request id comes from the original `executeTool` result and is not a
+   * retry or idempotency token.
+   */
+  async getBillingUsageEvent(requestId: string): Promise<BillingUsageEvent> {
+    const normalizedRequestId = requestId.trim();
+    if (
+      normalizedRequestId.length === 0 ||
+      normalizedRequestId.length > 200 ||
+      normalizedRequestId !== requestId
+    ) {
+      throw new DeeplineError(
+        'Usage request_id must contain 1–200 characters with no leading or trailing whitespace.',
+        undefined,
+        'INVALID_USAGE_REQUEST_ID',
+      );
+    }
+    const response = await this.http.get<{
+      entries?: BillingUsageEvent[];
+    }>(
+      `/api/v2/usage/events?request_id=${encodeURIComponent(normalizedRequestId)}`,
+    );
+    const event = response.entries?.[0];
+    if (!event) {
+      throw new DeeplineError(
+        'No usage event was found for this request_id.',
+        undefined,
+        'USAGE_EVENT_NOT_FOUND',
+      );
+    }
+    return event;
+  }
+
   /**
    * Charge the saved payment method and add Deepline credits to the active
    * workspace. Prefer `client.billing.topUp(...)`.

package/dist/bundling-sources/sdk/src/index.ts

@@ -73,6 +73,7 @@ export type {
   BillingSubscriptionCancelResult,
   BillingSubscriptionStatus,
   BillingTopUpResult,
+  BillingUsageEvent,
   WorkspaceCreateResult,
   WorkspacesNamespace,
   MonitorsNamespace,

package/dist/bundling-sources/sdk/src/release.ts

@@ -200,7 +200,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.144',
+  version: '0.3.145',
   updateSummary:
     'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {

package/dist/bundling-sources/shared_libs/play-runtime/tool-result.ts

@@ -664,6 +664,21 @@ function findFirstTargetByPath(
   return null;
 }
 
+function findFirstExplicitNullTargetByPath(
+  result: unknown,
+  paths: readonly string[] | undefined,
+): ToolResultTargetMetadata | null {
+  for (const path of paths ?? []) {
+    for (const candidate of candidateResultPaths(path)) {
+      const explicitNull = valuesAtSegments(result, parsePath(candidate)).find(
+        (entry) => entry.value === null,
+      );
+      if (explicitNull) return { value: null, path: explicitNull.path };
+    }
+  }
+  return null;
+}
+
 function firstValueForPaths(
   result: unknown,
   paths: readonly string[] | undefined,
@@ -1015,7 +1030,15 @@ function buildTargets(
       continue;
     }
     const fromExtractor = findFirstTargetByPath(result, descriptor.paths);
-    if (!fromExtractor) continue;
+    if (!fromExtractor) {
+      // A declared null is an explicit provider answer, not permission to
+      // guess from a similarly named sibling such as `emailDomain`.
+      const explicitNull = isSemanticStatus
+        ? null
+        : findFirstExplicitNullTargetByPath(result, descriptor.paths);
+      if (explicitNull) targets[target] = explicitNull;
+      continue;
+    }
     const transformed = coerceToEnum(
       applyExtractorTransforms(fromExtractor.value, descriptor),
       descriptor,
@@ -1038,6 +1061,14 @@ function buildTargets(
       targets[target] = fromMetadata;
       continue;
     }
+    const explicitNull = findFirstExplicitNullTargetByPath(
+      result,
+      targetGetters?.[target],
+    );
+    if (explicitNull) {
+      targets[target] = explicitNull;
+      continue;
+    }
     // Declared paths are routinely incomplete against the shape a provider
     // actually returns (zerobounce declares `result.data.email` and answers
     // with `address`), so the key scan stays as the rescue. It is bounded by
@@ -1053,6 +1084,7 @@ function buildTargets(
   }
   if (metadataTargets.size === 0) {
     for (const target of ['email', 'phone', 'linkedin', 'domain', 'status']) {
+      if (targets[target]) continue;
       const found = findFirstTargetByKey(result, target);
       if (found) targets[target] = found;
     }
@@ -1333,8 +1365,8 @@ export function readValue(
   selector: readonly string[] | string,
 ): unknown {
   if (typeof selector === 'string') {
-    const declared = result.extractedValues[selector]?.get();
-    if (declared != null) return declared;
+    const declared = result.extractedValues[selector];
+    if (declared) return declared.get();
   }
   const root = resultRootOf(result);
   const paths = Array.isArray(selector) ? selector : [selector];

package/dist/bundling-sources/shared_libs/plays/tool-result-types.ts

@@ -13,7 +13,17 @@ export type ToolResultBilling = {
   cost_usd?: number;
   /** Missing on historical responses. Pending pricing has no final amount. */
   pricing_status?: 'final' | 'pending';
-  settlement_status?: 'pending' | 'queued' | 'settled' | 'requires_recovery';
+  settlement_status?:
+    | 'pending'
+    | 'queued'
+    | 'settled'
+    | 'released'
+    | 'requires_recovery';
+  billing_outcome_reason?:
+    | 'free_operation'
+    | 'provider_no_billable_result'
+    | 'provider_reported_zero_usage'
+    | 'zero_price';
   estimated_credits?: number;
   estimated_cost_usd?: number;
   /** Preserve additive public pricing details across runtime/deployment skew. */

package/dist/cli/index.js

@@ -3068,7 +3068,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.144",
+  version: "0.3.145",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
@@ -7100,6 +7100,7 @@ var DeeplineClient = class _DeeplineClient {
       invoices: {
         list: (options2) => this.listBillingInvoices(options2)
       },
+      usageEvent: (requestId) => this.getBillingUsageEvent(requestId),
       targetPlans: () => this.getTargetBillingPlans(),
       targetStatus: () => this.getTargetBillingStatus(),
       autoRecharge: {
@@ -9471,6 +9472,33 @@ var DeeplineClient = class _DeeplineClient {
   async getBillingPlans() {
     return this.http.get("/api/v2/billing/catalog/current");
   }
+  /**
+   * Read the authenticated usage record for one execution request. The
+   * request id comes from the original `executeTool` result and is not a
+   * retry or idempotency token.
+   */
+  async getBillingUsageEvent(requestId) {
+    const normalizedRequestId = requestId.trim();
+    if (normalizedRequestId.length === 0 || normalizedRequestId.length > 200 || normalizedRequestId !== requestId) {
+      throw new DeeplineError(
+        "Usage request_id must contain 1\u2013200 characters with no leading or trailing whitespace.",
+        void 0,
+        "INVALID_USAGE_REQUEST_ID"
+      );
+    }
+    const response = await this.http.get(
+      `/api/v2/usage/events?request_id=${encodeURIComponent(normalizedRequestId)}`
+    );
+    const event = response.entries?.[0];
+    if (!event) {
+      throw new DeeplineError(
+        "No usage event was found for this request_id.",
+        void 0,
+        "USAGE_EVENT_NOT_FOUND"
+      );
+    }
+    return event;
+  }
   /**
    * Charge the saved payment method and add Deepline credits to the active
    * workspace. Prefer `client.billing.topUp(...)`.

package/dist/cli/index.mjs

@@ -3063,7 +3063,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.144",
+  version: "0.3.145",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
@@ -7095,6 +7095,7 @@ var DeeplineClient = class _DeeplineClient {
       invoices: {
         list: (options2) => this.listBillingInvoices(options2)
       },
+      usageEvent: (requestId) => this.getBillingUsageEvent(requestId),
       targetPlans: () => this.getTargetBillingPlans(),
       targetStatus: () => this.getTargetBillingStatus(),
       autoRecharge: {
@@ -9466,6 +9467,33 @@ var DeeplineClient = class _DeeplineClient {
   async getBillingPlans() {
     return this.http.get("/api/v2/billing/catalog/current");
   }
+  /**
+   * Read the authenticated usage record for one execution request. The
+   * request id comes from the original `executeTool` result and is not a
+   * retry or idempotency token.
+   */
+  async getBillingUsageEvent(requestId) {
+    const normalizedRequestId = requestId.trim();
+    if (normalizedRequestId.length === 0 || normalizedRequestId.length > 200 || normalizedRequestId !== requestId) {
+      throw new DeeplineError(
+        "Usage request_id must contain 1\u2013200 characters with no leading or trailing whitespace.",
+        void 0,
+        "INVALID_USAGE_REQUEST_ID"
+      );
+    }
+    const response = await this.http.get(
+      `/api/v2/usage/events?request_id=${encodeURIComponent(normalizedRequestId)}`
+    );
+    const event = response.entries?.[0];
+    if (!event) {
+      throw new DeeplineError(
+        "No usage event was found for this request_id.",
+        void 0,
+        "USAGE_EVENT_NOT_FOUND"
+      );
+    }
+    return event;
+  }
   /**
    * Charge the saved payment method and add Deepline credits to the active
    * workspace. Prefer `client.billing.topUp(...)`.

package/dist/{compiler-manifest-BIqRyj5m.d.mts → compiler-manifest-BJBNPTWt.d.mts}

@@ -334,7 +334,8 @@ type ToolResultBilling = {
     cost_usd?: number;
     /** Missing on historical responses. Pending pricing has no final amount. */
     pricing_status?: 'final' | 'pending';
-    settlement_status?: 'pending' | 'queued' | 'settled' | 'requires_recovery';
+    settlement_status?: 'pending' | 'queued' | 'settled' | 'released' | 'requires_recovery';
+    billing_outcome_reason?: 'free_operation' | 'provider_no_billable_result' | 'provider_reported_zero_usage' | 'zero_price';
     estimated_credits?: number;
     estimated_cost_usd?: number;
     /** Preserve additive public pricing details across runtime/deployment skew. */

package/dist/{compiler-manifest-BIqRyj5m.d.ts → compiler-manifest-BJBNPTWt.d.ts}

@@ -334,7 +334,8 @@ type ToolResultBilling = {
     cost_usd?: number;
     /** Missing on historical responses. Pending pricing has no final amount. */
     pricing_status?: 'final' | 'pending';
-    settlement_status?: 'pending' | 'queued' | 'settled' | 'requires_recovery';
+    settlement_status?: 'pending' | 'queued' | 'settled' | 'released' | 'requires_recovery';
+    billing_outcome_reason?: 'free_operation' | 'provider_no_billable_result' | 'provider_reported_zero_usage' | 'zero_price';
     estimated_credits?: number;
     estimated_cost_usd?: number;
     /** Preserve additive public pricing details across runtime/deployment skew. */

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 /// <reference path="./text-imports.d.ts" />
-import { c as PlayCompilerManifest, T as ToolResultBilling, A as AsyncPlayRunRef$1, i as PlayAuthoringColumnMap, j as PlayAuthoringColumnResolver, k as PlayAuthoringRuntimeContext, l as PlayAuthoringConditionalStepResolver, m as PlayAuthoringCsvInput, n as PlayAuthoringCsvOptions, o as PlayAuthoringDatasetBuilder, p as PlayAuthoringDatasetColumnDefinition, q as PlayAuthoringDatasetColumnRunInput, r as ToolExecuteResult, s as PlayAuthoringReferenceLike, t as PlayReturnObject$1, u as PlayAuthoringDefineConfig, v as PlayAuthoringDefinedPlay, w as PlayAuthoringFetchOptions, x as PlayAuthoringFileInput, y as PlayAuthoringAsyncCallOptions, z as PlayAuthoringBindings, B as PlayAuthoringCallExecution, C as PlayAuthoringCallOptions, D as PlayAuthoringFetchResponse, E as PlayAuthoringInputContract, F as PlayRunId$1, G as PlayAuthoringStepProgramStep, H as PlayAuthoringRuntimeStepOptions, I as PlaySqlListenerDeclaration, J as PlaySqlListenerEvent, K as PlaySqlListenerOperation, L as PlaySqlQuery, M as PlayAuthoringStepOptions, N as PlayAuthoringStepProgram, O as PlayAuthoringStepProgramResolver, Q as PlayAuthoringStepResolver, R as PlayToolExecutionRequest, S as PlayAuthoringStepProgramOptions, U as DeeplineError, V as ToolExecutionError, W as ToolExecutionErrorOptions } from './compiler-manifest-BIqRyj5m.mjs';
-export { X as CtxFetchHttpError, Y as DEEPLINE_EXTRACTOR_TARGETS, Z as DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, _ as DeeplineEmailStatusGetterValue, $ as DeeplineExtractorTarget, a0 as DeeplineGetterValue, a1 as DeeplineGetterValueMap, a2 as JOB_CHANGE_STATUS_VALUES, a3 as JobChangeStatus, a4 as PHONE_STATUS_VALUES, a5 as PhoneStatus, a6 as PlayDataset, a7 as PlayDatasetInput, a8 as PreviousCell, a9 as ProviderTransientError, aa as ProviderTransientErrorCategory, ab as ProviderUnavailableError, ac as ProviderUnavailableReason, ad as ToolExecutionErrorCategory, ae as ToolExecutionErrorOrigin, af as ToolExecutionFailureV1, ag as ToolExecutionNetworkKind, ah as ToolExecutionNetworkScope, ai as ToolExecutionPublicDetails, aj as getProviderUnavailableReason, ak as isDeeplineExtractorTarget, al as isProviderUnavailable, am as isProviderWaterfallUnavailableError } from './compiler-manifest-BIqRyj5m.mjs';
+import { c as PlayCompilerManifest, T as ToolResultBilling, A as AsyncPlayRunRef$1, i as PlayAuthoringColumnMap, j as PlayAuthoringColumnResolver, k as PlayAuthoringRuntimeContext, l as PlayAuthoringConditionalStepResolver, m as PlayAuthoringCsvInput, n as PlayAuthoringCsvOptions, o as PlayAuthoringDatasetBuilder, p as PlayAuthoringDatasetColumnDefinition, q as PlayAuthoringDatasetColumnRunInput, r as ToolExecuteResult, s as PlayAuthoringReferenceLike, t as PlayReturnObject$1, u as PlayAuthoringDefineConfig, v as PlayAuthoringDefinedPlay, w as PlayAuthoringFetchOptions, x as PlayAuthoringFileInput, y as PlayAuthoringAsyncCallOptions, z as PlayAuthoringBindings, B as PlayAuthoringCallExecution, C as PlayAuthoringCallOptions, D as PlayAuthoringFetchResponse, E as PlayAuthoringInputContract, F as PlayRunId$1, G as PlayAuthoringStepProgramStep, H as PlayAuthoringRuntimeStepOptions, I as PlaySqlListenerDeclaration, J as PlaySqlListenerEvent, K as PlaySqlListenerOperation, L as PlaySqlQuery, M as PlayAuthoringStepOptions, N as PlayAuthoringStepProgram, O as PlayAuthoringStepProgramResolver, Q as PlayAuthoringStepResolver, R as PlayToolExecutionRequest, S as PlayAuthoringStepProgramOptions, U as DeeplineError, V as ToolExecutionError, W as ToolExecutionErrorOptions } from './compiler-manifest-BJBNPTWt.mjs';
+export { X as CtxFetchHttpError, Y as DEEPLINE_EXTRACTOR_TARGETS, Z as DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, _ as DeeplineEmailStatusGetterValue, $ as DeeplineExtractorTarget, a0 as DeeplineGetterValue, a1 as DeeplineGetterValueMap, a2 as JOB_CHANGE_STATUS_VALUES, a3 as JobChangeStatus, a4 as PHONE_STATUS_VALUES, a5 as PhoneStatus, a6 as PlayDataset, a7 as PlayDatasetInput, a8 as PreviousCell, a9 as ProviderTransientError, aa as ProviderTransientErrorCategory, ab as ProviderUnavailableError, ac as ProviderUnavailableReason, ad as ToolExecutionErrorCategory, ae as ToolExecutionErrorOrigin, af as ToolExecutionFailureV1, ag as ToolExecutionNetworkKind, ah as ToolExecutionNetworkScope, ai as ToolExecutionPublicDetails, aj as getProviderUnavailableReason, ak as isDeeplineExtractorTarget, al as isProviderUnavailable, am as isProviderWaterfallUnavailableError } from './compiler-manifest-BJBNPTWt.mjs';
 import { MonitorFleetDefinition } from './monitor-fleet-contract.mjs';
 export { AdmittedMonitorFleetAuthoringContract, MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG, MONITOR_FLEET_AUTHORING_CONTRACT_EDITION, MONITOR_FLEET_DOCUMENTATION, MONITOR_FLEET_FRONTIER_MAX_ROWS, MONITOR_FLEET_MAX_MEMBERS, MonitorFleetAuthoringContractEdition, MonitorFleetAuthoringContractResult, MonitorFleetColumn, MonitorFleetContractIssue, MonitorFleetExpression, MonitorFleetTemplate, admitMonitorFleetAuthoringContract, defineMonitorFleet, fleetColumn, fleetKey, lintMonitorFleetInput, validateMonitorFleetDefinition } from './monitor-fleet-contract.mjs';
 export { BatchMonitorInput, MonitorInputIssue, MonitorSpec as MonitorInputSpec, lintMonitorBatchInput, lintMonitorSpecTemplate, renderMonitorSpecTemplate } from './monitor-input-contract.mjs';
@@ -4273,6 +4273,20 @@ type WorkspacesNamespace = {
         idempotencyKey: string;
     }) => Promise<WorkspaceCreateResult>;
 };
+/** One authenticated per-request usage event from `/api/v2/usage/events`. */
+type BillingUsageEvent = {
+    id: string | null;
+    provider: string;
+    operation: string;
+    status: string;
+    request_id: string;
+    billing_outcome_reason: string | null;
+    credits: number | null;
+    billing_mode: string | null;
+    pricing_model: string | null;
+    policy_id: string | null;
+    created_at: string;
+};
 /**
  * Public `client.billing` namespace for CLI commands and programmatic callers.
  * Covers plans, subscription state, cancellation, and invoice/receipt history.
@@ -4304,6 +4318,8 @@ type BillingNamespace = {
             limit?: number;
         }) => Promise<BillingInvoicesResult>;
     };
+    /** Read one exact execution outcome using the request_id returned by executeTool. */
+    usageEvent: (requestId: string) => Promise<BillingUsageEvent>;
     /** Metronome-authored target catalog and current Contract projection. */
     targetPlans: () => Promise<TargetBillingPlansResult>;
     /** Normalized target billing state. */
@@ -5368,6 +5384,12 @@ declare class DeeplineClient {
      * @returns Snake_case catalog from `GET /api/v2/billing/catalog/current`
      */
     getBillingPlans(): Promise<BillingPlansResult>;
+    /**
+     * Read the authenticated usage record for one execution request. The
+     * request id comes from the original `executeTool` result and is not a
+     * retry or idempotency token.
+     */
+    getBillingUsageEvent(requestId: string): Promise<BillingUsageEvent>;
     /**
      * Charge the saved payment method and add Deepline credits to the active
      * workspace. Prefer `client.billing.topUp(...)`.
@@ -6570,4 +6592,4 @@ declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem:
  */
 declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
 
-export { type AsyncPlayRunRef, AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CreateNotificationGroupInput, type CreateNotificationGroupResult, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, type DbNamespace, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FetchOptions, type FileInput, type IngestionStorageRepairResult, type LegacyMonitorStatusFilter, type LiveEventEnvelope, MONITOR_JOB_PHASES, MONITOR_JOB_RECONCILIATION_STATES, MONITOR_JOB_STATES, type MonitorBatchNamespace, type MonitorCheckResult, type MonitorDefinition, type MonitorDeleteResult, type MonitorDependents, type MonitorDeployResult, type MonitorDetail, type MonitorFleetDeactivateOptions, MonitorFleetDefinition, type MonitorFleetGetOptions, type MonitorFleetReactivateOptions, type MonitorFleetResult, type MonitorFleetStatus, type MonitorFleetSyncOptions, type MonitorFleetWaitOptions, type MonitorFleetsNamespace, type MonitorJobDeployOptions, type MonitorJobLogsOptions, type MonitorJobPhase, type MonitorJobReconciliationState, type MonitorJobResult, type MonitorJobState, type MonitorJobWaitOptions, type MonitorJobsNamespace, type MonitorListEntry, type MonitorPayload, type MonitorReactivateResult, type MonitorSpec, type MonitorState, type MonitorStateFilter, type MonitorUpdateChangeSummary, type MonitorUpdateResult, type MonitorsAccessStatus, type MonitorsAvailableOptions, type MonitorsAvailableResult, type MonitorsListOptions, type MonitorsListResult, type MonitorsNamespace, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PlayActivityObservation, type PlayActivityState, type PlayActivityTarget, type PlayAsyncCallOptions, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayCostEstimate, type PlayFetchResponse, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayReferenceLike, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunId, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PlaysListOptions, type PlaysListPage, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type RerunOptions, type RerunPlayRunResult, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsListPage, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, type RuntimeStepOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopAllCandidate, type StopAllPlayRunsDryRunResult, type StopAllPlayRunsResult, type StopAllPlayRunsStopResult, type StopAllRunsOptions, type StopPlayRunResult, type ToolDefinition, ToolExecuteResult, type ToolExecution, ToolExecutionError, ToolExecutionErrorOptions, type ToolExecutionRequest, type ToolMetadata, ToolRateLimitError, ToolResultBilling, type ToolSearchOptions, type ToolSearchResult, type WorkspaceCreateResult, type WorkspacesNamespace, defineInput, defineMonitor, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, isStopAllPlayRunsDryRunResult, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };
+export { type AsyncPlayRunRef, AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type BillingUsageEvent, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CreateNotificationGroupInput, type CreateNotificationGroupResult, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, type DbNamespace, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FetchOptions, type FileInput, type IngestionStorageRepairResult, type LegacyMonitorStatusFilter, type LiveEventEnvelope, MONITOR_JOB_PHASES, MONITOR_JOB_RECONCILIATION_STATES, MONITOR_JOB_STATES, type MonitorBatchNamespace, type MonitorCheckResult, type MonitorDefinition, type MonitorDeleteResult, type MonitorDependents, type MonitorDeployResult, type MonitorDetail, type MonitorFleetDeactivateOptions, MonitorFleetDefinition, type MonitorFleetGetOptions, type MonitorFleetReactivateOptions, type MonitorFleetResult, type MonitorFleetStatus, type MonitorFleetSyncOptions, type MonitorFleetWaitOptions, type MonitorFleetsNamespace, type MonitorJobDeployOptions, type MonitorJobLogsOptions, type MonitorJobPhase, type MonitorJobReconciliationState, type MonitorJobResult, type MonitorJobState, type MonitorJobWaitOptions, type MonitorJobsNamespace, type MonitorListEntry, type MonitorPayload, type MonitorReactivateResult, type MonitorSpec, type MonitorState, type MonitorStateFilter, type MonitorUpdateChangeSummary, type MonitorUpdateResult, type MonitorsAccessStatus, type MonitorsAvailableOptions, type MonitorsAvailableResult, type MonitorsListOptions, type MonitorsListResult, type MonitorsNamespace, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PlayActivityObservation, type PlayActivityState, type PlayActivityTarget, type PlayAsyncCallOptions, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayCostEstimate, type PlayFetchResponse, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayReferenceLike, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunId, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PlaysListOptions, type PlaysListPage, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type RerunOptions, type RerunPlayRunResult, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsListPage, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, type RuntimeStepOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopAllCandidate, type StopAllPlayRunsDryRunResult, type StopAllPlayRunsResult, type StopAllPlayRunsStopResult, type StopAllRunsOptions, type StopPlayRunResult, type ToolDefinition, ToolExecuteResult, type ToolExecution, ToolExecutionError, ToolExecutionErrorOptions, type ToolExecutionRequest, type ToolMetadata, ToolRateLimitError, ToolResultBilling, type ToolSearchOptions, type ToolSearchResult, type WorkspaceCreateResult, type WorkspacesNamespace, defineInput, defineMonitor, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, isStopAllPlayRunsDryRunResult, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /// <reference path="./text-imports.d.ts" />
-import { c as PlayCompilerManifest, T as ToolResultBilling, A as AsyncPlayRunRef$1, i as PlayAuthoringColumnMap, j as PlayAuthoringColumnResolver, k as PlayAuthoringRuntimeContext, l as PlayAuthoringConditionalStepResolver, m as PlayAuthoringCsvInput, n as PlayAuthoringCsvOptions, o as PlayAuthoringDatasetBuilder, p as PlayAuthoringDatasetColumnDefinition, q as PlayAuthoringDatasetColumnRunInput, r as ToolExecuteResult, s as PlayAuthoringReferenceLike, t as PlayReturnObject$1, u as PlayAuthoringDefineConfig, v as PlayAuthoringDefinedPlay, w as PlayAuthoringFetchOptions, x as PlayAuthoringFileInput, y as PlayAuthoringAsyncCallOptions, z as PlayAuthoringBindings, B as PlayAuthoringCallExecution, C as PlayAuthoringCallOptions, D as PlayAuthoringFetchResponse, E as PlayAuthoringInputContract, F as PlayRunId$1, G as PlayAuthoringStepProgramStep, H as PlayAuthoringRuntimeStepOptions, I as PlaySqlListenerDeclaration, J as PlaySqlListenerEvent, K as PlaySqlListenerOperation, L as PlaySqlQuery, M as PlayAuthoringStepOptions, N as PlayAuthoringStepProgram, O as PlayAuthoringStepProgramResolver, Q as PlayAuthoringStepResolver, R as PlayToolExecutionRequest, S as PlayAuthoringStepProgramOptions, U as DeeplineError, V as ToolExecutionError, W as ToolExecutionErrorOptions } from './compiler-manifest-BIqRyj5m.js';
-export { X as CtxFetchHttpError, Y as DEEPLINE_EXTRACTOR_TARGETS, Z as DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, _ as DeeplineEmailStatusGetterValue, $ as DeeplineExtractorTarget, a0 as DeeplineGetterValue, a1 as DeeplineGetterValueMap, a2 as JOB_CHANGE_STATUS_VALUES, a3 as JobChangeStatus, a4 as PHONE_STATUS_VALUES, a5 as PhoneStatus, a6 as PlayDataset, a7 as PlayDatasetInput, a8 as PreviousCell, a9 as ProviderTransientError, aa as ProviderTransientErrorCategory, ab as ProviderUnavailableError, ac as ProviderUnavailableReason, ad as ToolExecutionErrorCategory, ae as ToolExecutionErrorOrigin, af as ToolExecutionFailureV1, ag as ToolExecutionNetworkKind, ah as ToolExecutionNetworkScope, ai as ToolExecutionPublicDetails, aj as getProviderUnavailableReason, ak as isDeeplineExtractorTarget, al as isProviderUnavailable, am as isProviderWaterfallUnavailableError } from './compiler-manifest-BIqRyj5m.js';
+import { c as PlayCompilerManifest, T as ToolResultBilling, A as AsyncPlayRunRef$1, i as PlayAuthoringColumnMap, j as PlayAuthoringColumnResolver, k as PlayAuthoringRuntimeContext, l as PlayAuthoringConditionalStepResolver, m as PlayAuthoringCsvInput, n as PlayAuthoringCsvOptions, o as PlayAuthoringDatasetBuilder, p as PlayAuthoringDatasetColumnDefinition, q as PlayAuthoringDatasetColumnRunInput, r as ToolExecuteResult, s as PlayAuthoringReferenceLike, t as PlayReturnObject$1, u as PlayAuthoringDefineConfig, v as PlayAuthoringDefinedPlay, w as PlayAuthoringFetchOptions, x as PlayAuthoringFileInput, y as PlayAuthoringAsyncCallOptions, z as PlayAuthoringBindings, B as PlayAuthoringCallExecution, C as PlayAuthoringCallOptions, D as PlayAuthoringFetchResponse, E as PlayAuthoringInputContract, F as PlayRunId$1, G as PlayAuthoringStepProgramStep, H as PlayAuthoringRuntimeStepOptions, I as PlaySqlListenerDeclaration, J as PlaySqlListenerEvent, K as PlaySqlListenerOperation, L as PlaySqlQuery, M as PlayAuthoringStepOptions, N as PlayAuthoringStepProgram, O as PlayAuthoringStepProgramResolver, Q as PlayAuthoringStepResolver, R as PlayToolExecutionRequest, S as PlayAuthoringStepProgramOptions, U as DeeplineError, V as ToolExecutionError, W as ToolExecutionErrorOptions } from './compiler-manifest-BJBNPTWt.js';
+export { X as CtxFetchHttpError, Y as DEEPLINE_EXTRACTOR_TARGETS, Z as DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, _ as DeeplineEmailStatusGetterValue, $ as DeeplineExtractorTarget, a0 as DeeplineGetterValue, a1 as DeeplineGetterValueMap, a2 as JOB_CHANGE_STATUS_VALUES, a3 as JobChangeStatus, a4 as PHONE_STATUS_VALUES, a5 as PhoneStatus, a6 as PlayDataset, a7 as PlayDatasetInput, a8 as PreviousCell, a9 as ProviderTransientError, aa as ProviderTransientErrorCategory, ab as ProviderUnavailableError, ac as ProviderUnavailableReason, ad as ToolExecutionErrorCategory, ae as ToolExecutionErrorOrigin, af as ToolExecutionFailureV1, ag as ToolExecutionNetworkKind, ah as ToolExecutionNetworkScope, ai as ToolExecutionPublicDetails, aj as getProviderUnavailableReason, ak as isDeeplineExtractorTarget, al as isProviderUnavailable, am as isProviderWaterfallUnavailableError } from './compiler-manifest-BJBNPTWt.js';
 import { MonitorFleetDefinition } from './monitor-fleet-contract.js';
 export { AdmittedMonitorFleetAuthoringContract, MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG, MONITOR_FLEET_AUTHORING_CONTRACT_EDITION, MONITOR_FLEET_DOCUMENTATION, MONITOR_FLEET_FRONTIER_MAX_ROWS, MONITOR_FLEET_MAX_MEMBERS, MonitorFleetAuthoringContractEdition, MonitorFleetAuthoringContractResult, MonitorFleetColumn, MonitorFleetContractIssue, MonitorFleetExpression, MonitorFleetTemplate, admitMonitorFleetAuthoringContract, defineMonitorFleet, fleetColumn, fleetKey, lintMonitorFleetInput, validateMonitorFleetDefinition } from './monitor-fleet-contract.js';
 export { BatchMonitorInput, MonitorInputIssue, MonitorSpec as MonitorInputSpec, lintMonitorBatchInput, lintMonitorSpecTemplate, renderMonitorSpecTemplate } from './monitor-input-contract.js';
@@ -4273,6 +4273,20 @@ type WorkspacesNamespace = {
         idempotencyKey: string;
     }) => Promise<WorkspaceCreateResult>;
 };
+/** One authenticated per-request usage event from `/api/v2/usage/events`. */
+type BillingUsageEvent = {
+    id: string | null;
+    provider: string;
+    operation: string;
+    status: string;
+    request_id: string;
+    billing_outcome_reason: string | null;
+    credits: number | null;
+    billing_mode: string | null;
+    pricing_model: string | null;
+    policy_id: string | null;
+    created_at: string;
+};
 /**
  * Public `client.billing` namespace for CLI commands and programmatic callers.
  * Covers plans, subscription state, cancellation, and invoice/receipt history.
@@ -4304,6 +4318,8 @@ type BillingNamespace = {
             limit?: number;
         }) => Promise<BillingInvoicesResult>;
     };
+    /** Read one exact execution outcome using the request_id returned by executeTool. */
+    usageEvent: (requestId: string) => Promise<BillingUsageEvent>;
     /** Metronome-authored target catalog and current Contract projection. */
     targetPlans: () => Promise<TargetBillingPlansResult>;
     /** Normalized target billing state. */
@@ -5368,6 +5384,12 @@ declare class DeeplineClient {
      * @returns Snake_case catalog from `GET /api/v2/billing/catalog/current`
      */
     getBillingPlans(): Promise<BillingPlansResult>;
+    /**
+     * Read the authenticated usage record for one execution request. The
+     * request id comes from the original `executeTool` result and is not a
+     * retry or idempotency token.
+     */
+    getBillingUsageEvent(requestId: string): Promise<BillingUsageEvent>;
     /**
      * Charge the saved payment method and add Deepline credits to the active
      * workspace. Prefer `client.billing.topUp(...)`.
@@ -6570,4 +6592,4 @@ declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem:
  */
 declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
 
-export { type AsyncPlayRunRef, AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CreateNotificationGroupInput, type CreateNotificationGroupResult, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, type DbNamespace, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FetchOptions, type FileInput, type IngestionStorageRepairResult, type LegacyMonitorStatusFilter, type LiveEventEnvelope, MONITOR_JOB_PHASES, MONITOR_JOB_RECONCILIATION_STATES, MONITOR_JOB_STATES, type MonitorBatchNamespace, type MonitorCheckResult, type MonitorDefinition, type MonitorDeleteResult, type MonitorDependents, type MonitorDeployResult, type MonitorDetail, type MonitorFleetDeactivateOptions, MonitorFleetDefinition, type MonitorFleetGetOptions, type MonitorFleetReactivateOptions, type MonitorFleetResult, type MonitorFleetStatus, type MonitorFleetSyncOptions, type MonitorFleetWaitOptions, type MonitorFleetsNamespace, type MonitorJobDeployOptions, type MonitorJobLogsOptions, type MonitorJobPhase, type MonitorJobReconciliationState, type MonitorJobResult, type MonitorJobState, type MonitorJobWaitOptions, type MonitorJobsNamespace, type MonitorListEntry, type MonitorPayload, type MonitorReactivateResult, type MonitorSpec, type MonitorState, type MonitorStateFilter, type MonitorUpdateChangeSummary, type MonitorUpdateResult, type MonitorsAccessStatus, type MonitorsAvailableOptions, type MonitorsAvailableResult, type MonitorsListOptions, type MonitorsListResult, type MonitorsNamespace, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PlayActivityObservation, type PlayActivityState, type PlayActivityTarget, type PlayAsyncCallOptions, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayCostEstimate, type PlayFetchResponse, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayReferenceLike, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunId, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PlaysListOptions, type PlaysListPage, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type RerunOptions, type RerunPlayRunResult, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsListPage, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, type RuntimeStepOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopAllCandidate, type StopAllPlayRunsDryRunResult, type StopAllPlayRunsResult, type StopAllPlayRunsStopResult, type StopAllRunsOptions, type StopPlayRunResult, type ToolDefinition, ToolExecuteResult, type ToolExecution, ToolExecutionError, ToolExecutionErrorOptions, type ToolExecutionRequest, type ToolMetadata, ToolRateLimitError, ToolResultBilling, type ToolSearchOptions, type ToolSearchResult, type WorkspaceCreateResult, type WorkspacesNamespace, defineInput, defineMonitor, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, isStopAllPlayRunsDryRunResult, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };
+export { type AsyncPlayRunRef, AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type BillingUsageEvent, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CreateNotificationGroupInput, type CreateNotificationGroupResult, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, type DbNamespace, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FetchOptions, type FileInput, type IngestionStorageRepairResult, type LegacyMonitorStatusFilter, type LiveEventEnvelope, MONITOR_JOB_PHASES, MONITOR_JOB_RECONCILIATION_STATES, MONITOR_JOB_STATES, type MonitorBatchNamespace, type MonitorCheckResult, type MonitorDefinition, type MonitorDeleteResult, type MonitorDependents, type MonitorDeployResult, type MonitorDetail, type MonitorFleetDeactivateOptions, MonitorFleetDefinition, type MonitorFleetGetOptions, type MonitorFleetReactivateOptions, type MonitorFleetResult, type MonitorFleetStatus, type MonitorFleetSyncOptions, type MonitorFleetWaitOptions, type MonitorFleetsNamespace, type MonitorJobDeployOptions, type MonitorJobLogsOptions, type MonitorJobPhase, type MonitorJobReconciliationState, type MonitorJobResult, type MonitorJobState, type MonitorJobWaitOptions, type MonitorJobsNamespace, type MonitorListEntry, type MonitorPayload, type MonitorReactivateResult, type MonitorSpec, type MonitorState, type MonitorStateFilter, type MonitorUpdateChangeSummary, type MonitorUpdateResult, type MonitorsAccessStatus, type MonitorsAvailableOptions, type MonitorsAvailableResult, type MonitorsListOptions, type MonitorsListResult, type MonitorsNamespace, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PlayActivityObservation, type PlayActivityState, type PlayActivityTarget, type PlayAsyncCallOptions, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayCostEstimate, type PlayFetchResponse, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayReferenceLike, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunId, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PlaysListOptions, type PlaysListPage, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type RerunOptions, type RerunPlayRunResult, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsListPage, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, type RuntimeStepOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopAllCandidate, type StopAllPlayRunsDryRunResult, type StopAllPlayRunsResult, type StopAllPlayRunsStopResult, type StopAllRunsOptions, type StopPlayRunResult, type ToolDefinition, ToolExecuteResult, type ToolExecution, ToolExecutionError, ToolExecutionErrorOptions, type ToolExecutionRequest, type ToolMetadata, ToolRateLimitError, ToolResultBilling, type ToolSearchOptions, type ToolSearchResult, type WorkspaceCreateResult, type WorkspacesNamespace, defineInput, defineMonitor, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, isStopAllPlayRunsDryRunResult, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };

package/dist/index.js

@@ -864,7 +864,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.144",
+  version: "0.3.145",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
@@ -4774,6 +4774,7 @@ var DeeplineClient = class _DeeplineClient {
       invoices: {
         list: (options2) => this.listBillingInvoices(options2)
       },
+      usageEvent: (requestId) => this.getBillingUsageEvent(requestId),
       targetPlans: () => this.getTargetBillingPlans(),
       targetStatus: () => this.getTargetBillingStatus(),
       autoRecharge: {
@@ -7145,6 +7146,33 @@ var DeeplineClient = class _DeeplineClient {
   async getBillingPlans() {
     return this.http.get("/api/v2/billing/catalog/current");
   }
+  /**
+   * Read the authenticated usage record for one execution request. The
+   * request id comes from the original `executeTool` result and is not a
+   * retry or idempotency token.
+   */
+  async getBillingUsageEvent(requestId) {
+    const normalizedRequestId = requestId.trim();
+    if (normalizedRequestId.length === 0 || normalizedRequestId.length > 200 || normalizedRequestId !== requestId) {
+      throw new DeeplineError(
+        "Usage request_id must contain 1\u2013200 characters with no leading or trailing whitespace.",
+        void 0,
+        "INVALID_USAGE_REQUEST_ID"
+      );
+    }
+    const response = await this.http.get(
+      `/api/v2/usage/events?request_id=${encodeURIComponent(normalizedRequestId)}`
+    );
+    const event = response.entries?.[0];
+    if (!event) {
+      throw new DeeplineError(
+        "No usage event was found for this request_id.",
+        void 0,
+        "USAGE_EVENT_NOT_FOUND"
+      );
+    }
+    return event;
+  }
   /**
    * Charge the saved payment method and add Deepline credits to the active
    * workspace. Prefer `client.billing.topUp(...)`.
@@ -8844,6 +8872,17 @@ function findFirstTargetByPath(result, paths) {
   }
   return null;
 }
+function findFirstExplicitNullTargetByPath(result, paths) {
+  for (const path of paths ?? []) {
+    for (const candidate of candidateResultPaths(path)) {
+      const explicitNull = valuesAtSegments(result, parsePath(candidate)).find(
+        (entry) => entry.value === null
+      );
+      if (explicitNull) return { value: null, path: explicitNull.path };
+    }
+  }
+  return null;
+}
 function firstValueForPaths(result, paths) {
   return findFirstTargetByPath(result, paths);
 }
@@ -9103,7 +9142,11 @@ function buildTargets(result, extractors, targetGetters) {
       continue;
     }
     const fromExtractor = findFirstTargetByPath(result, descriptor.paths);
-    if (!fromExtractor) continue;
+    if (!fromExtractor) {
+      const explicitNull = isSemanticStatus ? null : findFirstExplicitNullTargetByPath(result, descriptor.paths);
+      if (explicitNull) targets[target] = explicitNull;
+      continue;
+    }
     const transformed = coerceToEnum(
       applyExtractorTransforms(fromExtractor.value, descriptor),
       descriptor
@@ -9126,6 +9169,14 @@ function buildTargets(result, extractors, targetGetters) {
       targets[target] = fromMetadata;
       continue;
     }
+    const explicitNull = findFirstExplicitNullTargetByPath(
+      result,
+      targetGetters?.[target]
+    );
+    if (explicitNull) {
+      targets[target] = explicitNull;
+      continue;
+    }
     const fallback = findFirstTargetByKey(result, target);
     if (fallback) {
       targets[target] = fallback;
@@ -9133,6 +9184,7 @@ function buildTargets(result, extractors, targetGetters) {
   }
   if (metadataTargets.size === 0) {
     for (const target of ["email", "phone", "linkedin", "domain", "status"]) {
+      if (targets[target]) continue;
       const found = findFirstTargetByKey(result, target);
       if (found) targets[target] = found;
     }

package/dist/index.mjs

@@ -768,7 +768,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.144",
+  version: "0.3.145",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
@@ -4678,6 +4678,7 @@ var DeeplineClient = class _DeeplineClient {
       invoices: {
         list: (options2) => this.listBillingInvoices(options2)
       },
+      usageEvent: (requestId) => this.getBillingUsageEvent(requestId),
       targetPlans: () => this.getTargetBillingPlans(),
       targetStatus: () => this.getTargetBillingStatus(),
       autoRecharge: {
@@ -7049,6 +7050,33 @@ var DeeplineClient = class _DeeplineClient {
   async getBillingPlans() {
     return this.http.get("/api/v2/billing/catalog/current");
   }
+  /**
+   * Read the authenticated usage record for one execution request. The
+   * request id comes from the original `executeTool` result and is not a
+   * retry or idempotency token.
+   */
+  async getBillingUsageEvent(requestId) {
+    const normalizedRequestId = requestId.trim();
+    if (normalizedRequestId.length === 0 || normalizedRequestId.length > 200 || normalizedRequestId !== requestId) {
+      throw new DeeplineError(
+        "Usage request_id must contain 1\u2013200 characters with no leading or trailing whitespace.",
+        void 0,
+        "INVALID_USAGE_REQUEST_ID"
+      );
+    }
+    const response = await this.http.get(
+      `/api/v2/usage/events?request_id=${encodeURIComponent(normalizedRequestId)}`
+    );
+    const event = response.entries?.[0];
+    if (!event) {
+      throw new DeeplineError(
+        "No usage event was found for this request_id.",
+        void 0,
+        "USAGE_EVENT_NOT_FOUND"
+      );
+    }
+    return event;
+  }
   /**
    * Charge the saved payment method and add Deepline credits to the active
    * workspace. Prefer `client.billing.topUp(...)`.
@@ -8748,6 +8776,17 @@ function findFirstTargetByPath(result, paths) {
   }
   return null;
 }
+function findFirstExplicitNullTargetByPath(result, paths) {
+  for (const path of paths ?? []) {
+    for (const candidate of candidateResultPaths(path)) {
+      const explicitNull = valuesAtSegments(result, parsePath(candidate)).find(
+        (entry) => entry.value === null
+      );
+      if (explicitNull) return { value: null, path: explicitNull.path };
+    }
+  }
+  return null;
+}
 function firstValueForPaths(result, paths) {
   return findFirstTargetByPath(result, paths);
 }
@@ -9007,7 +9046,11 @@ function buildTargets(result, extractors, targetGetters) {
       continue;
     }
     const fromExtractor = findFirstTargetByPath(result, descriptor.paths);
-    if (!fromExtractor) continue;
+    if (!fromExtractor) {
+      const explicitNull = isSemanticStatus ? null : findFirstExplicitNullTargetByPath(result, descriptor.paths);
+      if (explicitNull) targets[target] = explicitNull;
+      continue;
+    }
     const transformed = coerceToEnum(
       applyExtractorTransforms(fromExtractor.value, descriptor),
       descriptor
@@ -9030,6 +9073,14 @@ function buildTargets(result, extractors, targetGetters) {
       targets[target] = fromMetadata;
       continue;
     }
+    const explicitNull = findFirstExplicitNullTargetByPath(
+      result,
+      targetGetters?.[target]
+    );
+    if (explicitNull) {
+      targets[target] = explicitNull;
+      continue;
+    }
     const fallback = findFirstTargetByKey(result, target);
     if (fallback) {
       targets[target] = fallback;
@@ -9037,6 +9088,7 @@ function buildTargets(result, extractors, targetGetters) {
   }
   if (metadataTargets.size === 0) {
     for (const target of ["email", "phone", "linkedin", "domain", "status"]) {
+      if (targets[target]) continue;
       const found = findFirstTargetByKey(result, target);
       if (found) targets[target] = found;
     }

package/dist/install-integrity.json

@@ -552,8 +552,8 @@
     "dist/cli/index.js",
     "dist/cli/index.mjs",
     "dist/cli/text-imports.d.ts",
-    "dist/compiler-manifest-BIqRyj5m.d.mts",
-    "dist/compiler-manifest-BIqRyj5m.d.ts",
+    "dist/compiler-manifest-BJBNPTWt.d.mts",
+    "dist/compiler-manifest-BJBNPTWt.d.ts",
     "dist/helpers.d.mts",
     "dist/helpers.d.ts",
     "dist/helpers.js",

package/dist/plays/bundle-play-file.d.mts

@@ -1,6 +1,6 @@
 /// <reference path="./text-imports.d.ts" />
-import { P as PlayArtifactKind, a as PlayBundleArtifact, b as PlaySandboxRuntimeDeclaration, c as PlayCompilerManifest } from '../compiler-manifest-BIqRyj5m.mjs';
-export { d as PLAY_ARTIFACT_KINDS, e as PlayArtifactCompatibility, f as PlayImportPolicy, g as PlayPackageImport, h as PlayRuntimeFeature } from '../compiler-manifest-BIqRyj5m.mjs';
+import { P as PlayArtifactKind, a as PlayBundleArtifact, b as PlaySandboxRuntimeDeclaration, c as PlayCompilerManifest } from '../compiler-manifest-BJBNPTWt.mjs';
+export { d as PLAY_ARTIFACT_KINDS, e as PlayArtifactCompatibility, f as PlayImportPolicy, g as PlayPackageImport, h as PlayRuntimeFeature } from '../compiler-manifest-BJBNPTWt.mjs';
 import '@sinclair/typebox';
 
 type ImportedPlayDependency = {

package/dist/plays/bundle-play-file.d.ts

@@ -1,6 +1,6 @@
 /// <reference path="./text-imports.d.ts" />
-import { P as PlayArtifactKind, a as PlayBundleArtifact, b as PlaySandboxRuntimeDeclaration, c as PlayCompilerManifest } from '../compiler-manifest-BIqRyj5m.js';
-export { d as PLAY_ARTIFACT_KINDS, e as PlayArtifactCompatibility, f as PlayImportPolicy, g as PlayPackageImport, h as PlayRuntimeFeature } from '../compiler-manifest-BIqRyj5m.js';
+import { P as PlayArtifactKind, a as PlayBundleArtifact, b as PlaySandboxRuntimeDeclaration, c as PlayCompilerManifest } from '../compiler-manifest-BJBNPTWt.js';
+export { d as PLAY_ARTIFACT_KINDS, e as PlayArtifactCompatibility, f as PlayImportPolicy, g as PlayPackageImport, h as PlayRuntimeFeature } from '../compiler-manifest-BJBNPTWt.js';
 import '@sinclair/typebox';
 
 type ImportedPlayDependency = {

package/dist/release.d.mts

@@ -149,7 +149,7 @@ type SdkRelease = {
     supportPolicy: SdkSupportPolicy;
 };
 declare const SDK_RELEASE: {
-    readonly version: "0.3.144";
+    readonly version: "0.3.145";
     readonly updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.";
     readonly packageCapabilities: {
         readonly updatePreferences: 1;

package/dist/release.d.ts

@@ -149,7 +149,7 @@ type SdkRelease = {
     supportPolicy: SdkSupportPolicy;
 };
 declare const SDK_RELEASE: {
-    readonly version: "0.3.144";
+    readonly version: "0.3.145";
     readonly updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.";
     readonly packageCapabilities: {
         readonly updatePreferences: 1;

package/dist/release.js

@@ -74,7 +74,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.144",
+  version: "0.3.145",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/release.mjs

@@ -48,7 +48,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.144",
+  version: "0.3.145",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.3.144",
+  "version": "0.3.145",
   "description": "GTM data CLI and TypeScript SDK for coding agents",
   "license": "MIT",
   "homepage": "https://code.deepline.com",