@soat/sdk 0.16.1 → 0.16.3

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

@@ -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;
   /**
@@ -3260,9 +3260,9 @@ type MemoryEntryWriteResult = MemoryEntry & {
  */
 type QueueStats = {
   /**
-   * The active queue driver.
+   * The active queue driver (`ORCHESTRATION_QUEUE_DRIVER`). Under `sqs`, `oldest_queued_age_seconds` is always `null` and `per_project` is always empty — SQS exposes neither.
    */
-  driver?: string;
+  driver?: 'postgres' | 'sqs';
   /**
    * Tasks waiting to be claimed now (unclaimed and past their `available_at`). Backoff-delayed tasks are excluded.
    */
@@ -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;
@@ -11289,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.
      */
@@ -12984,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
      */
@@ -13037,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.
      *
@@ -14985,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>;
   /**
@@ -15284,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

@@ -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;
   /**
@@ -3260,9 +3260,9 @@ type MemoryEntryWriteResult = MemoryEntry & {
  */
 type QueueStats = {
   /**
-   * The active queue driver.
+   * The active queue driver (`ORCHESTRATION_QUEUE_DRIVER`). Under `sqs`, `oldest_queued_age_seconds` is always `null` and `per_project` is always empty — SQS exposes neither.
    */
-  driver?: string;
+  driver?: 'postgres' | 'sqs';
   /**
    * Tasks waiting to be claimed now (unclaimed and past their `available_at`). Backoff-delayed tasks are excluded.
    */
@@ -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;
@@ -11289,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.
      */
@@ -12984,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
      */
@@ -13037,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.
      *
@@ -14985,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>;
   /**
@@ -15284,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.1",
+  "version": "0.16.3",
   "description": "TypeScript SDK for the SOAT API",
   "type": "module",
   "main": "dist/index.mjs",