@soat/sdk 0.16.0 → 0.16.2

package/dist/index.cjs

@@ -2715,7 +2715,7 @@ var Quotas = class {
 	/**
 	* Create a quota
 	*
-	* Creates a project-scoped quota. `scope: agent` with `metric: requests` and `scope: api_key` with `metric: tokens`/`cost_usd` are both rejected with 400 (no attribution exists to enforce them). A duplicate quota (same project, scope, scope_ref, metric, window) is rejected with 409.
+	* Creates a project-scoped quota. `requests` is valid for `scope: project`/`api_key`; `tokens` and `cost_usd` are valid for `scope: project`/`agent`/`actor`. Any other scope/metric pair is rejected with 400 (no attribution exists to enforce it). An `actor` quota caps one end user's spend, matched from the generation's session; a null `scope_ref` means one budget *per* actor rather than a pooled project total. A duplicate quota (same project, scope, scope_ref, metric, window) is rejected with 409.
 	*/
 	static createQuota(options) {
 		return (options.client ?? client).post({
@@ -3324,7 +3324,7 @@ var Usage = class {
 	/**
 	* List usage meters
 	*
-	* Returns the raw usage-meter rows the caller can access, most recent first, optionally filtered by agent and generation. Each row is the per-generation token usage as reported by the provider, for audit and reconciliation.
+	* Returns the raw usage-meter rows the caller can access, most recent first, optionally filtered by agent, generation, trace, actor, or session. Each row is the per-generation token usage as reported by the provider, for audit and reconciliation.
 	*
 	*/
 	static listUsageMeters(options) {

package/dist/index.d.cts

@@ -1576,7 +1576,7 @@ type ExceptionItem = {
   /**
    * How the exception was filed
    */
-  kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'manual';
+  kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'manual';
   /**
    * Human-readable one-line summary
    */
@@ -2622,9 +2622,9 @@ type QuotaResourceProperties = {
   /**
    * The scope the quota applies to
    */
-  scope: 'project' | 'api_key' | 'agent';
+  scope: 'project' | 'api_key' | 'agent' | 'actor';
   /**
-   * Public id of the api key / agent the quota applies to. NULL means all entities of that scope type in the project.
+   * Public id of the api key / agent / actor the quota applies to. NULL means all entities of that scope type in the project — for `actor` scope that is one budget per actor, not a pooled total.
    */
   scope_ref?: string | null;
   /**
@@ -3847,7 +3847,7 @@ type UpsertProjectPricesRequest = {
 type Quota = {
   id?: string;
   project_id?: string;
-  scope?: 'project' | 'api_key' | 'agent';
+  scope?: 'project' | 'api_key' | 'agent' | 'actor';
   scope_ref?: string | null;
   metric?: 'requests' | 'tokens' | 'cost_usd';
   window?: 'rolling_1m' | 'rolling_1h' | 'rolling_24h' | 'calendar_month';
@@ -4634,6 +4634,16 @@ type UsageEvent = {
    * Public ID of the trace this usage belongs to
    */
   trace_id?: string | null;
+  /**
+   * Public ID of the actor (end user) the metered occurrence was produced for, frozen at write time. Null when no end user is behind the work — orchestration runs, triggers, direct API generations.
+   *
+   */
+  actor_id?: string | null;
+  /**
+   * Public ID of the session the metered occurrence ran in, frozen at write time. Null for work not dispatched through a session.
+   *
+   */
+  session_id?: string | null;
   /**
    * Public ID of the AI provider instance billed. Null if the provider was later deleted; the `provider`/`model` snapshot still records what was billed.
    *
@@ -4697,13 +4707,13 @@ type UsageAggregate = {
    * Upper bound applied, echoed back; null when unbounded
    */
   to?: Date | null;
-  group_by?: 'model' | 'agent' | 'run' | 'day' | 'meter_type';
+  group_by?: 'model' | 'agent' | 'run' | 'day' | 'meter_type' | 'actor' | 'session';
   /**
    * One entry per distinct value in the chosen dimension.
    */
   groups?: Array<{
     /**
-     * The bucket's value in the chosen dimension (a model id, meter type, agent/run public id, or `YYYY-MM-DD` UTC day). Null when the dimension does not apply to an event.
+     * The bucket's value in the chosen dimension (a model id, meter type, agent/run/actor/session public id, or `YYYY-MM-DD` UTC day). Null when the dimension does not apply to an event — under `actor`/`session` this is the bucket holding everything with no end user behind it.
      *
      */
     key?: string | null;
@@ -6506,6 +6516,10 @@ type ListAuditEntriesData = {
   url: '/api/v1/audit-log';
 };
 type ListAuditEntriesErrors = {
+  /**
+   * `from` or `to` is present but not a valid ISO 8601 date
+   */
+  400: unknown;
   /**
    * Unauthorized
    */
@@ -6568,7 +6582,7 @@ type ExportAuditEntriesData = {
 };
 type ExportAuditEntriesErrors = {
   /**
-   * project_id is required
+   * `project_id` is required, or `from`/`to` is present but not a valid ISO 8601 date
    */
   400: unknown;
   /**
@@ -8251,7 +8265,7 @@ type ListExceptionsData = {
     /**
      * Filter by how the exception was filed
      */
-    kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'manual';
+    kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'manual';
     /**
      * Maximum number of results to return
      */
@@ -11285,7 +11299,7 @@ type CreateQuotaData = {
     /**
      * The scope the quota applies to
      */
-    scope: 'project' | 'api_key' | 'agent';
+    scope: 'project' | 'api_key' | 'agent' | 'actor';
     /**
      * Public id of the api key / agent the quota applies to. NULL means all entities of that scope type in the project.
      */
@@ -11303,7 +11317,7 @@ type CreateQuotaData = {
      */
     limit: number;
     /**
-     * enforce blocks with 429 (requests at the middleware, tokens/cost_usd at the pre-generation check); monitor is a pass-through no-op until the webhook phase ships.
+     * enforce blocks with 429 (requests at the middleware, tokens/cost_usd at the pre-generation check); monitor observes without blocking — a breach fires the quota.exceeded webhook and writes a quotas:MonitorBreach audit entry, but the request is let through.
      */
     mode?: 'enforce' | 'monitor';
   };
@@ -12980,6 +12994,16 @@ type ListUsageMetersData = {
      * Filter by trace public ID
      */
     trace_id?: string;
+    /**
+     * Filter by the actor (end user) the usage is attributed to. An actor that does not exist in scope yields an empty page.
+     *
+     */
+    actor_id?: string;
+    /**
+     * Filter by the session the usage was produced in. A session that does not exist in scope yields an empty page.
+     *
+     */
+    session_id?: string;
     /**
      * Filter by the trigger that initiated the generation
      */
@@ -13033,7 +13057,7 @@ type GetUsageData = {
      * Dimension to bucket by. `day` buckets on the event's UTC calendar day; the others bucket on the matching column.
      *
      */
-    group_by: 'model' | 'agent' | 'run' | 'day' | 'meter_type';
+    group_by: 'model' | 'agent' | 'run' | 'day' | 'meter_type' | 'actor' | 'session';
     /**
      * Inclusive lower bound (ISO-8601 timestamp) on the event created_at. Omit for no lower bound.
      *
@@ -14981,7 +15005,7 @@ declare class Quotas {
   /**
    * Create a quota
    *
-   * Creates a project-scoped quota. `scope: agent` with `metric: requests` and `scope: api_key` with `metric: tokens`/`cost_usd` are both rejected with 400 (no attribution exists to enforce them). A duplicate quota (same project, scope, scope_ref, metric, window) is rejected with 409.
+   * Creates a project-scoped quota. `requests` is valid for `scope: project`/`api_key`; `tokens` and `cost_usd` are valid for `scope: project`/`agent`/`actor`. Any other scope/metric pair is rejected with 400 (no attribution exists to enforce it). An `actor` quota caps one end user's spend, matched from the generation's session; a null `scope_ref` means one budget *per* actor rather than a pooled project total. A duplicate quota (same project, scope, scope_ref, metric, window) is rejected with 409.
    */
   static createQuota<ThrowOnError extends boolean = false>(options: Options<CreateQuotaData, ThrowOnError>): RequestResult<CreateQuotaResponses, CreateQuotaErrors, ThrowOnError>;
   /**
@@ -15280,7 +15304,7 @@ declare class Usage {
   /**
    * List usage meters
    *
-   * Returns the raw usage-meter rows the caller can access, most recent first, optionally filtered by agent and generation. Each row is the per-generation token usage as reported by the provider, for audit and reconciliation.
+   * Returns the raw usage-meter rows the caller can access, most recent first, optionally filtered by agent, generation, trace, actor, or session. Each row is the per-generation token usage as reported by the provider, for audit and reconciliation.
    *
    */
   static listUsageMeters<ThrowOnError extends boolean = false>(options?: Options<ListUsageMetersData, ThrowOnError>): RequestResult<ListUsageMetersResponses, ListUsageMetersErrors, ThrowOnError>;

package/dist/index.d.mts

@@ -1576,7 +1576,7 @@ type ExceptionItem = {
   /**
    * How the exception was filed
    */
-  kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'manual';
+  kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'manual';
   /**
    * Human-readable one-line summary
    */
@@ -2622,9 +2622,9 @@ type QuotaResourceProperties = {
   /**
    * The scope the quota applies to
    */
-  scope: 'project' | 'api_key' | 'agent';
+  scope: 'project' | 'api_key' | 'agent' | 'actor';
   /**
-   * Public id of the api key / agent the quota applies to. NULL means all entities of that scope type in the project.
+   * Public id of the api key / agent / actor the quota applies to. NULL means all entities of that scope type in the project — for `actor` scope that is one budget per actor, not a pooled total.
    */
   scope_ref?: string | null;
   /**
@@ -3847,7 +3847,7 @@ type UpsertProjectPricesRequest = {
 type Quota = {
   id?: string;
   project_id?: string;
-  scope?: 'project' | 'api_key' | 'agent';
+  scope?: 'project' | 'api_key' | 'agent' | 'actor';
   scope_ref?: string | null;
   metric?: 'requests' | 'tokens' | 'cost_usd';
   window?: 'rolling_1m' | 'rolling_1h' | 'rolling_24h' | 'calendar_month';
@@ -4634,6 +4634,16 @@ type UsageEvent = {
    * Public ID of the trace this usage belongs to
    */
   trace_id?: string | null;
+  /**
+   * Public ID of the actor (end user) the metered occurrence was produced for, frozen at write time. Null when no end user is behind the work — orchestration runs, triggers, direct API generations.
+   *
+   */
+  actor_id?: string | null;
+  /**
+   * Public ID of the session the metered occurrence ran in, frozen at write time. Null for work not dispatched through a session.
+   *
+   */
+  session_id?: string | null;
   /**
    * Public ID of the AI provider instance billed. Null if the provider was later deleted; the `provider`/`model` snapshot still records what was billed.
    *
@@ -4697,13 +4707,13 @@ type UsageAggregate = {
    * Upper bound applied, echoed back; null when unbounded
    */
   to?: Date | null;
-  group_by?: 'model' | 'agent' | 'run' | 'day' | 'meter_type';
+  group_by?: 'model' | 'agent' | 'run' | 'day' | 'meter_type' | 'actor' | 'session';
   /**
    * One entry per distinct value in the chosen dimension.
    */
   groups?: Array<{
     /**
-     * The bucket's value in the chosen dimension (a model id, meter type, agent/run public id, or `YYYY-MM-DD` UTC day). Null when the dimension does not apply to an event.
+     * The bucket's value in the chosen dimension (a model id, meter type, agent/run/actor/session public id, or `YYYY-MM-DD` UTC day). Null when the dimension does not apply to an event — under `actor`/`session` this is the bucket holding everything with no end user behind it.
      *
      */
     key?: string | null;
@@ -6506,6 +6516,10 @@ type ListAuditEntriesData = {
   url: '/api/v1/audit-log';
 };
 type ListAuditEntriesErrors = {
+  /**
+   * `from` or `to` is present but not a valid ISO 8601 date
+   */
+  400: unknown;
   /**
    * Unauthorized
    */
@@ -6568,7 +6582,7 @@ type ExportAuditEntriesData = {
 };
 type ExportAuditEntriesErrors = {
   /**
-   * project_id is required
+   * `project_id` is required, or `from`/`to` is present but not a valid ISO 8601 date
    */
   400: unknown;
   /**
@@ -8251,7 +8265,7 @@ type ListExceptionsData = {
     /**
      * Filter by how the exception was filed
      */
-    kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'manual';
+    kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'manual';
     /**
      * Maximum number of results to return
      */
@@ -11285,7 +11299,7 @@ type CreateQuotaData = {
     /**
      * The scope the quota applies to
      */
-    scope: 'project' | 'api_key' | 'agent';
+    scope: 'project' | 'api_key' | 'agent' | 'actor';
     /**
      * Public id of the api key / agent the quota applies to. NULL means all entities of that scope type in the project.
      */
@@ -11303,7 +11317,7 @@ type CreateQuotaData = {
      */
     limit: number;
     /**
-     * enforce blocks with 429 (requests at the middleware, tokens/cost_usd at the pre-generation check); monitor is a pass-through no-op until the webhook phase ships.
+     * enforce blocks with 429 (requests at the middleware, tokens/cost_usd at the pre-generation check); monitor observes without blocking — a breach fires the quota.exceeded webhook and writes a quotas:MonitorBreach audit entry, but the request is let through.
      */
     mode?: 'enforce' | 'monitor';
   };
@@ -12980,6 +12994,16 @@ type ListUsageMetersData = {
      * Filter by trace public ID
      */
     trace_id?: string;
+    /**
+     * Filter by the actor (end user) the usage is attributed to. An actor that does not exist in scope yields an empty page.
+     *
+     */
+    actor_id?: string;
+    /**
+     * Filter by the session the usage was produced in. A session that does not exist in scope yields an empty page.
+     *
+     */
+    session_id?: string;
     /**
      * Filter by the trigger that initiated the generation
      */
@@ -13033,7 +13057,7 @@ type GetUsageData = {
      * Dimension to bucket by. `day` buckets on the event's UTC calendar day; the others bucket on the matching column.
      *
      */
-    group_by: 'model' | 'agent' | 'run' | 'day' | 'meter_type';
+    group_by: 'model' | 'agent' | 'run' | 'day' | 'meter_type' | 'actor' | 'session';
     /**
      * Inclusive lower bound (ISO-8601 timestamp) on the event created_at. Omit for no lower bound.
      *
@@ -14981,7 +15005,7 @@ declare class Quotas {
   /**
    * Create a quota
    *
-   * Creates a project-scoped quota. `scope: agent` with `metric: requests` and `scope: api_key` with `metric: tokens`/`cost_usd` are both rejected with 400 (no attribution exists to enforce them). A duplicate quota (same project, scope, scope_ref, metric, window) is rejected with 409.
+   * Creates a project-scoped quota. `requests` is valid for `scope: project`/`api_key`; `tokens` and `cost_usd` are valid for `scope: project`/`agent`/`actor`. Any other scope/metric pair is rejected with 400 (no attribution exists to enforce it). An `actor` quota caps one end user's spend, matched from the generation's session; a null `scope_ref` means one budget *per* actor rather than a pooled project total. A duplicate quota (same project, scope, scope_ref, metric, window) is rejected with 409.
    */
   static createQuota<ThrowOnError extends boolean = false>(options: Options<CreateQuotaData, ThrowOnError>): RequestResult<CreateQuotaResponses, CreateQuotaErrors, ThrowOnError>;
   /**
@@ -15280,7 +15304,7 @@ declare class Usage {
   /**
    * List usage meters
    *
-   * Returns the raw usage-meter rows the caller can access, most recent first, optionally filtered by agent and generation. Each row is the per-generation token usage as reported by the provider, for audit and reconciliation.
+   * Returns the raw usage-meter rows the caller can access, most recent first, optionally filtered by agent, generation, trace, actor, or session. Each row is the per-generation token usage as reported by the provider, for audit and reconciliation.
    *
    */
   static listUsageMeters<ThrowOnError extends boolean = false>(options?: Options<ListUsageMetersData, ThrowOnError>): RequestResult<ListUsageMetersResponses, ListUsageMetersErrors, ThrowOnError>;

package/dist/index.mjs

@@ -2714,7 +2714,7 @@ var Quotas = class {
 	/**
 	* Create a quota
 	*
-	* Creates a project-scoped quota. `scope: agent` with `metric: requests` and `scope: api_key` with `metric: tokens`/`cost_usd` are both rejected with 400 (no attribution exists to enforce them). A duplicate quota (same project, scope, scope_ref, metric, window) is rejected with 409.
+	* Creates a project-scoped quota. `requests` is valid for `scope: project`/`api_key`; `tokens` and `cost_usd` are valid for `scope: project`/`agent`/`actor`. Any other scope/metric pair is rejected with 400 (no attribution exists to enforce it). An `actor` quota caps one end user's spend, matched from the generation's session; a null `scope_ref` means one budget *per* actor rather than a pooled project total. A duplicate quota (same project, scope, scope_ref, metric, window) is rejected with 409.
 	*/
 	static createQuota(options) {
 		return (options.client ?? client).post({
@@ -3323,7 +3323,7 @@ var Usage = class {
 	/**
 	* List usage meters
 	*
-	* Returns the raw usage-meter rows the caller can access, most recent first, optionally filtered by agent and generation. Each row is the per-generation token usage as reported by the provider, for audit and reconciliation.
+	* Returns the raw usage-meter rows the caller can access, most recent first, optionally filtered by agent, generation, trace, actor, or session. Each row is the per-generation token usage as reported by the provider, for audit and reconciliation.
 	*
 	*/
 	static listUsageMeters(options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soat/sdk",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "description": "TypeScript SDK for the SOAT API",
   "type": "module",
   "main": "dist/index.mjs",