@roarkanalytics/sdk 5.9.0 → 5.11.0

package/src/resources/call.ts

@@ -38,6 +38,22 @@ export class Call extends APIResource {
     return this._client.get('/v1/call', { query, ...options });
   }
 
+  /**
+   * Deletes a call by its ID. The call, its metrics and its analysis are hidden from
+   * every read, and any analysis still running on it is cancelled. Returns 404 when
+   * the call does not exist in this project or was already deleted.
+   *
+   * @example
+   * ```ts
+   * const call = await client.call.delete(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
+   */
+  delete(callID: string, options?: RequestOptions): APIPromise<CallDeleteResponse> {
+    return this._client.delete(path`/v1/call/${callID}`, options);
+  }
+
   /**
    * Attach tool invocations that fired during a call to an already-existing call,
    * asynchronously after the call was created. Use this when the tool-call data
@@ -73,6 +89,27 @@ export class Call extends APIResource {
     return this._client.post(path`/v1/call/${callID}/tool-invocations`, { body, ...options });
   }
 
+  /**
+   * Deletes up to 100 calls by ID in one request. Each deleted call, its metrics and
+   * its analysis are hidden from every read, and any analysis still running on it is
+   * cancelled. IDs that do not exist in this project, or were already deleted, are
+   * returned in notFoundCallIds and left untouched. The request succeeds even when
+   * none of the calls are found. IDs are returned lowercase, each once.
+   *
+   * @example
+   * ```ts
+   * const response = await client.call.batchDelete({
+   *   callIds: [
+   *     '550e8400-e29b-41d4-a716-446655440000',
+   *     '660e8400-e29b-41d4-a716-446655440001',
+   *   ],
+   * });
+   * ```
+   */
+  batchDelete(body: CallBatchDeleteParams, options?: RequestOptions): APIPromise<CallBatchDeleteResponse> {
+    return this._client.post('/v1/call/batch-delete', { body, ...options });
+  }
+
   /**
    * Retrieve an existing call by its unique identifier
    *
@@ -87,6 +124,24 @@ export class Call extends APIResource {
     return this._client.get(path`/v1/call/${callID}`, options);
   }
 
+  /**
+   * The billable spend attributed to one call, split by cost type, with every cost
+   * line behind it. Simulated calls include the costs their simulation incurred
+   * before the call connected. Amounts are billable spend only, in exact
+   * micro-dollars (`\*UsdMicros`) and dollars (`\*Usd`, for display). Requires an
+   * API key with the `billing:read` permission.
+   *
+   * @example
+   * ```ts
+   * const response = await client.call.getCost(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
+   */
+  getCost(callID: string, options?: RequestOptions): APIPromise<CallGetCostResponse> {
+    return this._client.get(path`/v1/call/${callID}/cost`, options);
+  }
+
   /**
    * Fetch the full transcript for a specific call. Optionally specify a
    * transcription source; otherwise the best available source is used automatically.
@@ -428,6 +483,24 @@ export namespace CallListResponse {
   }
 }
 
+export interface CallDeleteResponse {
+  data: CallDeleteResponse.Data;
+}
+
+export namespace CallDeleteResponse {
+  export interface Data {
+    /**
+     * ID of the deleted call
+     */
+    id: string;
+
+    /**
+     * Always true when the call was deleted
+     */
+    deleted: true;
+  }
+}
+
 export interface CallAppendToolInvocationsResponse {
   /**
    * Result of appending tool invocations to a call.
@@ -539,6 +612,25 @@ export namespace CallAppendToolInvocationsResponse {
   }
 }
 
+export interface CallBatchDeleteResponse {
+  data: CallBatchDeleteResponse.Data;
+}
+
+export namespace CallBatchDeleteResponse {
+  export interface Data {
+    /**
+     * Calls this request deleted
+     */
+    deletedCallIds: Array<string>;
+
+    /**
+     * Requested calls that were not deleted because they do not exist in this project
+     * or were already deleted
+     */
+    notFoundCallIds: Array<string>;
+  }
+}
+
 export interface CallGetByIDResponse {
   /**
    * Response containing call information
@@ -707,6 +799,123 @@ export namespace CallGetByIDResponse {
   }
 }
 
+export interface CallGetCostResponse {
+  data: CallGetCostResponse.Data;
+}
+
+export namespace CallGetCostResponse {
+  export interface Data {
+    /**
+     * Spend by cost type. Sums to totalUsdMicros.
+     */
+    breakdown: Array<Data.Breakdown>;
+
+    callId: string;
+
+    currency: 'usd';
+
+    /**
+     * Every billable cost line attributed to the call.
+     */
+    items: Array<Data.Item>;
+
+    totalUsd: number;
+
+    /**
+     * Total billable spend for this call, in micro-dollars.
+     */
+    totalUsdMicros: number;
+  }
+
+  export namespace Data {
+    export interface Breakdown {
+      /**
+       * The same figure in US dollars.
+       */
+      amountUsd: number;
+
+      /**
+       * Billable spend for this type, in micro-dollars.
+       */
+      amountUsdMicros: number;
+
+      /**
+       * Units billed (see the line items for the unit).
+       */
+      quantity: number;
+
+      /**
+       * The cost source, e.g. SIM_PLATFORM_FEE, SIM_LLM, METRIC.
+       */
+      source:
+        | 'SIM_PLATFORM_FEE'
+        | 'SIM_TTS'
+        | 'SIM_STT'
+        | 'SIM_LLM'
+        | 'SIM_TELEPHONY'
+        | 'METRIC'
+        | 'TRANSCRIPTION'
+        | 'INTERNAL_LLM'
+        | 'INTERNAL_STT';
+
+      /**
+       * SIMULATION or POST_CALL.
+       */
+      surface: 'SIMULATION' | 'POST_CALL';
+    }
+
+    export interface Item {
+      amountUsd: number;
+
+      amountUsdMicros: number;
+
+      /**
+       * Stable id of the cost event. Use it to deduplicate.
+       */
+      eventId: string;
+
+      /**
+       * The grading pass a METRIC line paid for. A call graded twice carries one line
+       * per pass.
+       */
+      metricCollectionJobId: string | null;
+
+      /**
+       * The metric a METRIC line was charged for.
+       */
+      metricDefinitionId: string | null;
+
+      model: string | null;
+
+      /**
+       * When the cost was incurred, ISO 8601.
+       */
+      occurredAt: string;
+
+      provider: string | null;
+
+      quantity: number;
+
+      quantityUnit: 'MINUTES' | 'INPUT_TOKENS' | 'OUTPUT_TOKENS' | 'CHARACTERS' | 'AUDIO_SECONDS' | 'UNITS';
+
+      simulationJobId: string | null;
+
+      source:
+        | 'SIM_PLATFORM_FEE'
+        | 'SIM_TTS'
+        | 'SIM_STT'
+        | 'SIM_LLM'
+        | 'SIM_TELEPHONY'
+        | 'METRIC'
+        | 'TRANSCRIPTION'
+        | 'INTERNAL_LLM'
+        | 'INTERNAL_STT';
+
+      surface: 'SIMULATION' | 'POST_CALL';
+    }
+  }
+}
+
 export interface CallGetTranscriptResponse {
   /**
    * Call transcript response
@@ -2099,6 +2308,17 @@ export interface CallListParams {
    */
   limit?: number;
 
+  /**
+   * Filter on custom properties, one entry per property name:
+   * properties[<name>][exists]=true keeps calls that have the property set (whatever
+   * the value), properties[<name>][exists]=false keeps calls missing it (never sent,
+   * sent as null, or removed). A property the project has never seen is missing on
+   * every call. Names match the way properties are stored, so planTier and plan_tier
+   * are one property. At most 20 properties; a name taken by a built-in call filter,
+   * such as status, is rejected with 400.
+   */
+  properties?: { [key: string]: CallListParams.Property };
+
   /**
    * Search text to filter calls by title, summary, or transcript
    */
@@ -2137,6 +2357,24 @@ export interface CallListParams {
   status?: 'RINGING' | 'IN_PROGRESS' | 'ENDED';
 }
 
+export namespace CallListParams {
+  /**
+   * Filter on custom properties, one entry per property name:
+   * properties[<name>][exists]=true keeps calls that have the property set (whatever
+   * the value), properties[<name>][exists]=false keeps calls missing it (never sent,
+   * sent as null, or removed). A property the project has never seen is missing on
+   * every call. Names match the way properties are stored, so planTier and plan_tier
+   * are one property. At most 20 properties; a name taken by a built-in call filter,
+   * such as status, is rejected with 400.
+   */
+  export interface Property {
+    /**
+     * true: the property is set. false: the property is missing.
+     */
+    exists?: boolean;
+  }
+}
+
 export interface CallAppendToolInvocationsParams {
   /**
    * Tool invocations that fired during the call, to attach to it. Max 500 per
@@ -2225,6 +2463,13 @@ export namespace CallAppendToolInvocationsParams {
   }
 }
 
+export interface CallBatchDeleteParams {
+  /**
+   * IDs of the calls to delete, at most 100. Repeated IDs are counted once.
+   */
+  callIds: Array<string>;
+}
+
 export interface CallGetTranscriptParams {
   /**
    * Transcription source to fetch. When omitted, uses the preferred source based on
@@ -2281,8 +2526,11 @@ export declare namespace Call {
   export {
     type CallCreateResponse as CallCreateResponse,
     type CallListResponse as CallListResponse,
+    type CallDeleteResponse as CallDeleteResponse,
     type CallAppendToolInvocationsResponse as CallAppendToolInvocationsResponse,
+    type CallBatchDeleteResponse as CallBatchDeleteResponse,
     type CallGetByIDResponse as CallGetByIDResponse,
+    type CallGetCostResponse as CallGetCostResponse,
     type CallGetTranscriptResponse as CallGetTranscriptResponse,
     type CallListMetricsResponse as CallListMetricsResponse,
     type CallListSentimentRunsResponse as CallListSentimentRunsResponse,
@@ -2290,6 +2538,7 @@ export declare namespace Call {
     type CallCreateParams as CallCreateParams,
     type CallListParams as CallListParams,
     type CallAppendToolInvocationsParams as CallAppendToolInvocationsParams,
+    type CallBatchDeleteParams as CallBatchDeleteParams,
     type CallGetTranscriptParams as CallGetTranscriptParams,
     type CallListMetricsParams as CallListMetricsParams,
     type CallUpdatePropertiesParams as CallUpdatePropertiesParams,