@naturali/sdk 0.121.0 → 0.122.0

package/dist/index.cjs

@@ -3742,7 +3742,7 @@ var Sessions = class {
 	/**
 	* Get a session
 	*
-	* Returns details of a single session.
+	* Returns details of a single session, including a `usage` roll-up of what its generations cost. The listing omits `usage`; for a window, or a split by day, model, agent, provider or run, read `GET /v1/projects/{project_id}/usage` instead.
 	*/
 	static getSession(options) {
 		return (options.client ?? client).get({

package/dist/index.d.cts

@@ -3928,6 +3928,16 @@ type Generation = {
    *
    */
   chain_id?: string | null;
+  /**
+   * Public ID of the session this generation was dispatched through, or null for a generation started outside one. This is the link a per-session cost reading follows; the session's own `usage` field reports the roll-up directly.
+   *
+   */
+  session_id?: string | null;
+  /**
+   * Public ID of the end-user actor the generation was attributed to, or null when none was. Copied onto the generation's usage event.
+   *
+   */
+  actor_id?: string | null;
   /**
    * Type of the principal that started the generation
    */
@@ -5596,6 +5606,12 @@ type SessionRecord = {
    *
    */
   forked_from_position?: number | null;
+  /**
+   * What the session's generations cost: token counts and `cost_usd` summed across every metered generation dispatched through it. Present on the single-session read; omitted from session and fork list responses.
+   *
+   * A fork is a session of its own, so it starts at zero rather than inheriting what the history it copied cost — summing `usage` across a session and its forks therefore never double-counts. Work the platform does around a session without a generation of its own (a memory extraction pass, for instance) is metered on the project, not here.
+   */
+  usage?: UsageTotals;
 };
 type ForkSessionRequest = {
   /**
@@ -6887,6 +6903,10 @@ type ListActorsData = {
      * External ID to filter by (e.g. WhatsApp phone number)
      */
     external_id?: string;
+    /**
+     * Case-insensitive substring match on the actor name
+     */
+    name?: string;
     /**
      * Return only actors linked to this agent
      */
@@ -12904,7 +12924,12 @@ type DownloadFileData = {
      */
     file_id: string;
   };
-  query?: never;
+  query?: {
+    /**
+     * Signed single-file download token, an alternative to a bearer credential (issued for ingestion-rule converters).
+     */
+    token?: string;
+  };
   url: '/v1/projects/{project_id}/files/{file_id}/download';
 };
 type DownloadFileErrors = {
@@ -12997,7 +13022,12 @@ type DownloadFileBase64Data = {
      */
     file_id: string;
   };
-  query?: never;
+  query?: {
+    /**
+     * Signed single-file download token, an alternative to a bearer credential (issued for ingestion-rule converters).
+     */
+    token?: string;
+  };
   url: '/v1/projects/{project_id}/files/{file_id}/download/base64';
 };
 type DownloadFileBase64Errors = {
@@ -13530,6 +13560,16 @@ type ListGenerationsData = {
      * Filter by trace public ID
      */
     trace_id?: string;
+    /**
+     * Return only the generations dispatched through one session — the turns behind that conversation's spend. A session that does not exist in scope yields an empty page.
+     *
+     */
+    session_id?: string;
+    /**
+     * Return only the generations one end user started, across every session they appear in. An actor that does not exist in scope yields an empty page.
+     *
+     */
+    actor_id?: string;
     /**
      * Filter by the public ID of the parent generation. Returns all generations triggered by that generation — sub-agent invocations. Null-initiated (top-level) generations are not returned.
      *
@@ -16540,7 +16580,12 @@ type DeleteSecretData = {
      */
     secret_id: string;
   };
-  query?: never;
+  query?: {
+    /**
+     * Delete the secret even when AI providers reference it, destroying those providers too. Without it a referenced secret answers SECRET_HAS_DEPENDENTS.
+     */
+    force?: boolean;
+  };
   url: '/v1/projects/{project_id}/secrets/{secret_id}';
 };
 type DeleteSecretErrors = {
@@ -20700,7 +20745,7 @@ declare class Sessions {
   /**
    * Get a session
    *
-   * Returns details of a single session.
+   * Returns details of a single session, including a `usage` roll-up of what its generations cost. The listing omits `usage`; for a window, or a split by day, model, agent, provider or run, read `GET /v1/projects/{project_id}/usage` instead.
    */
   static getSession<ThrowOnError extends boolean = false>(options: Options<GetSessionData, ThrowOnError>): RequestResult<GetSessionResponses, GetSessionErrors, ThrowOnError>;
   /**

package/dist/index.d.mts

@@ -3928,6 +3928,16 @@ type Generation = {
    *
    */
   chain_id?: string | null;
+  /**
+   * Public ID of the session this generation was dispatched through, or null for a generation started outside one. This is the link a per-session cost reading follows; the session's own `usage` field reports the roll-up directly.
+   *
+   */
+  session_id?: string | null;
+  /**
+   * Public ID of the end-user actor the generation was attributed to, or null when none was. Copied onto the generation's usage event.
+   *
+   */
+  actor_id?: string | null;
   /**
    * Type of the principal that started the generation
    */
@@ -5596,6 +5606,12 @@ type SessionRecord = {
    *
    */
   forked_from_position?: number | null;
+  /**
+   * What the session's generations cost: token counts and `cost_usd` summed across every metered generation dispatched through it. Present on the single-session read; omitted from session and fork list responses.
+   *
+   * A fork is a session of its own, so it starts at zero rather than inheriting what the history it copied cost — summing `usage` across a session and its forks therefore never double-counts. Work the platform does around a session without a generation of its own (a memory extraction pass, for instance) is metered on the project, not here.
+   */
+  usage?: UsageTotals;
 };
 type ForkSessionRequest = {
   /**
@@ -6887,6 +6903,10 @@ type ListActorsData = {
      * External ID to filter by (e.g. WhatsApp phone number)
      */
     external_id?: string;
+    /**
+     * Case-insensitive substring match on the actor name
+     */
+    name?: string;
     /**
      * Return only actors linked to this agent
      */
@@ -12904,7 +12924,12 @@ type DownloadFileData = {
      */
     file_id: string;
   };
-  query?: never;
+  query?: {
+    /**
+     * Signed single-file download token, an alternative to a bearer credential (issued for ingestion-rule converters).
+     */
+    token?: string;
+  };
   url: '/v1/projects/{project_id}/files/{file_id}/download';
 };
 type DownloadFileErrors = {
@@ -12997,7 +13022,12 @@ type DownloadFileBase64Data = {
      */
     file_id: string;
   };
-  query?: never;
+  query?: {
+    /**
+     * Signed single-file download token, an alternative to a bearer credential (issued for ingestion-rule converters).
+     */
+    token?: string;
+  };
   url: '/v1/projects/{project_id}/files/{file_id}/download/base64';
 };
 type DownloadFileBase64Errors = {
@@ -13530,6 +13560,16 @@ type ListGenerationsData = {
      * Filter by trace public ID
      */
     trace_id?: string;
+    /**
+     * Return only the generations dispatched through one session — the turns behind that conversation's spend. A session that does not exist in scope yields an empty page.
+     *
+     */
+    session_id?: string;
+    /**
+     * Return only the generations one end user started, across every session they appear in. An actor that does not exist in scope yields an empty page.
+     *
+     */
+    actor_id?: string;
     /**
      * Filter by the public ID of the parent generation. Returns all generations triggered by that generation — sub-agent invocations. Null-initiated (top-level) generations are not returned.
      *
@@ -16540,7 +16580,12 @@ type DeleteSecretData = {
      */
     secret_id: string;
   };
-  query?: never;
+  query?: {
+    /**
+     * Delete the secret even when AI providers reference it, destroying those providers too. Without it a referenced secret answers SECRET_HAS_DEPENDENTS.
+     */
+    force?: boolean;
+  };
   url: '/v1/projects/{project_id}/secrets/{secret_id}';
 };
 type DeleteSecretErrors = {
@@ -20700,7 +20745,7 @@ declare class Sessions {
   /**
    * Get a session
    *
-   * Returns details of a single session.
+   * Returns details of a single session, including a `usage` roll-up of what its generations cost. The listing omits `usage`; for a window, or a split by day, model, agent, provider or run, read `GET /v1/projects/{project_id}/usage` instead.
    */
   static getSession<ThrowOnError extends boolean = false>(options: Options<GetSessionData, ThrowOnError>): RequestResult<GetSessionResponses, GetSessionErrors, ThrowOnError>;
   /**

package/dist/index.mjs

@@ -3741,7 +3741,7 @@ var Sessions = class {
 	/**
 	* Get a session
 	*
-	* Returns details of a single session.
+	* Returns details of a single session, including a `usage` roll-up of what its generations cost. The listing omits `usage`; for a window, or a split by day, model, agent, provider or run, read `GET /v1/projects/{project_id}/usage` instead.
 	*/
 	static getSession(options) {
 		return (options.client ?? client).get({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/sdk",
-  "version": "0.121.0",
+  "version": "0.122.0",
   "description": "TypeScript SDK for the naturali.ai API, generated from its OpenAPI specs",
   "type": "module",
   "sideEffects": false,
@@ -37,7 +37,7 @@
     "tsx": "^4.23.1",
     "typescript": "~6.0.3",
     "vitest": "^4.1.10",
-    "@naturali/api": "0.121.0"
+    "@naturali/api": "0.122.0"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts",