@naturali/sdk 0.141.5 → 0.141.7

package/dist/index.cjs

@@ -875,7 +875,8 @@ var Channels = class {
 	/**
 	* Replace a route
 	*
-	* Full replace, the same validation as create.
+	* Full replace, the same validation as create: an omitted field takes its create default. Where that default would widen a value the route sets, omission is `400 replace_omits_fields`, naming the fields in `details.fields`, and nothing is written: a set `surface` (the default is any surface), a non-empty `match` (every message), a non-empty `config` (it carries the Discord allowlist), and `status` on a `disabled` route (the default re-activates it). Send the value to keep it, or `"surface": null`, `"match": {}`, `"config": null`, `"status": "active"` to clear it.
+	*
 	*/
 	static updateChannelRoute(options) {
 		return (options.client ?? client).patch({
@@ -1238,7 +1239,7 @@ var Agents = class {
 	/**
 	* Run an agent generation
 	*
-	* Sends messages to the agent, resolves its tools, and runs the AI model loop. Background by default: returns `202 Accepted` with a `generation_id` to poll via `GET /v1/projects/{project_id}/generations/{generation_id}`. Pass `?wait=true` to block and receive the result inline, where client tools pause the generation and return `requires_action`. Streaming (`stream: true`) implies waiting.
+	* Sends messages to the agent, resolves its tools, and runs the AI model loop. Background by default: returns `202 Accepted` with a `generation_id` to poll via `GET /v1/projects/{project_id}/generations/{generation_id}`. Pass `?wait=true` to block and receive the result inline, where client tools pause the generation and return `requires_action`. Streaming (`stream: true`) implies waiting. Pass `idempotency_key` to make a retry safe: a request whose key is already claimed runs nothing and answers `202` with the generation the key names.
 	*
 	*/
 	static createAgentGeneration(options) {

package/dist/index.d.cts

@@ -1225,6 +1225,12 @@ type CreateAgentGenerationRequest = {
    * Caller-supplied key/value metadata attached to the generation record for per-run audit attribution (e.g. the knowledge-corpus version that produced this action). Round-trips verbatim when the generation is fetched via the generations API. The bag is caller-owned and no key is reserved: server-owned state (usage attribution, the served agent version, the model route's record, the extraction summary) lives in its own top-level generation fields and cannot be written from here. Use the request's own `action_id` field to set the usage-attribution label.
    */
   metadata?: NullableMetadataBag;
+  /**
+   * Deduplication key, unique within the project, that makes a retry of an at-least-once delivery or an ambiguous failure safe. The first request under a key runs the generation; any later request carrying it runs nothing and answers `202` with the generation the key names, whatever state it has reached — including a retry that arrives while the original is still running. The key is claimed by the generation record for as long as the record exists.
+   *
+   * Every other body field except `stream` is the request the key names: reusing a key with any of them changed, or on another agent of the project, is `409 IDEMPOTENCY_KEY_REUSED`. `stream` and `wait` say how the caller receives the generation, not what it is, so a retry may flip them.
+   */
+  idempotency_key?: string;
   /**
    * Per-generation knowledge retrieval override. Array filters (memory_store_ids, document_ids, document_paths) are unioned with the agent's stored knowledge_config; `tags` pairs are merged with the override winning per key; scalar fields (min_score, rrf_k, recency_half_life_days, limit) use the per-generation value when present.
    */
@@ -2210,7 +2216,7 @@ type ChannelRouteWrite = {
    */
   config?: {
     [key: string]: unknown;
-  };
+  } | null;
   status?: 'active' | 'disabled';
 };
 type ChannelRouteList = {
@@ -3836,7 +3842,7 @@ type TriggerResourceProperties = {
     [key: string]: unknown;
   } | null;
   /**
-   * Caller context every firing forwards to the run it starts, so an agent whose tools authorize through `{{context:<key>}}` can be scheduled. Write-only. A value may be a `{{secret:...}}` reference, which is what a template should carry — the credential stays in the secret store and only its name is checked in
+   * Caller context every firing forwards to the run it starts, so an agent whose tools authorize through `{{context:<key>}}` can be scheduled. Write-only. A value may be a `{{secret:sec_...}}` reference, which is what a template should carry — the credential stays in the secret store and only its id is checked in (a `sub` such as `{{secret:${MySecret}}}` for a template secret); a secret's name does not resolve and is refused
    */
   tool_context?: {
     [key: string]: string;
@@ -4586,6 +4592,10 @@ type Generation = {
      */
     estimated_tokens?: number;
   } | null;
+  /**
+   * The deduplication key the generation was started under, unique within the project and claimed for as long as the generation record exists. Null for a generation started without one.
+   */
+  idempotency_key?: string | null;
   /**
    * What the turn cost: token counts and `cost_usd` for every event metered against this generation. Present on the single-generation read; omitted from the listing, where it would be a query per row.
    *
@@ -5557,6 +5567,10 @@ type OrchestrationNode = {
    * For loop nodes — number of items to process in parallel.
    */
   parallelism?: number;
+  /**
+   * For loop nodes — what a failed item does. `fail` (the default) fails the node on the first item whose child run settles `failed`, `cancelled` or `expired`. `collect` keeps going: that item's entry in `results` becomes `{ "error": { "code", "message" }, "orchestration_run_id" }`, in its original position. Either way the artifact carries `failed_count`. A child run that could not be started (for example past the nesting depth bound) fails the node in both modes.
+   */
+  on_item_error?: 'fail' | 'collect';
   /**
    * For loop and sub_orchestration nodes — allowlist of the run's `tool_context` keys the child run inherits. When `null` (the default), the child inherits the parent's whole bag. When set, only the listed keys are handed down, so a run holding a broad credential can delegate one step to a shared sub-graph without passing on what that sub-graph does not need; `[]` hands down nothing. Matching is case-insensitive, since an entry names a key that becomes an HTTP header name; an entry outside that grammar is rejected at write time with `INVALID_TOOL_CONTEXT_KEY`. The server-derived identity keys (`session_id`, `actor_id`, `actor_external_id`) are unaffected — they are re-derived per generation in the child regardless of this list. Ignored for other node types.
    */
@@ -7352,7 +7366,7 @@ type CreateTriggerRequest = {
    *
    * **Write-only.** It is accepted here and never returned on a read, so the record cannot be used to recover a value.
    *
-   * A value may be a `{{secret:...}}` reference, which keeps the credential in the [secret](/docs/modules/secrets) store and leaves only its name on the trigger; it is resolved at fire time, so rotating the secret changes the next firing without touching the trigger. A reference naming a secret that does not exist in this project is refused here rather than at fire time.
+   * A value may be a `{{secret:sec_...}}` reference, which keeps the credential in the [secret](/docs/modules/secrets) store and leaves only its id on the trigger; it is resolved at fire time, so rotating the secret changes the next firing without touching the trigger. A reference is refused here rather than at fire time when it is not in that id form (a secret's name does not resolve) or names a secret that does not exist in this project.
    *
    */
   tool_context?: {
@@ -9288,7 +9302,7 @@ type CreateAgentGenerationData = {
 };
 type CreateAgentGenerationErrors = {
   /**
-   * Bad Request
+   * Bad Request (e.g. an `idempotency_key` that is not a non-empty string of at most 255 characters)
    */
   400: ErrorResponse;
   /**
@@ -9303,6 +9317,10 @@ type CreateAgentGenerationErrors = {
    * Agent or AI provider not found
    */
   404: ErrorResponse;
+  /**
+   * `IDEMPOTENCY_KEY_REUSED` — the key is already claimed by a generation started from a different request. Nothing runs.
+   */
+  409: ErrorResponse;
   /**
    * Upstream AI provider error (AI_PROVIDER_ERROR); model output that does not satisfy the agent's `output_schema` (OUTPUT_SCHEMA_VALIDATION_FAILED — the violated field is named in the message); or a model that wrote a tool invocation out as plain assistant text instead of calling the tool, so the tool never ran (TEXT_ENCODED_TOOL_CALL — `meta.tool_name` names the tool). The error `meta` includes the `generation_id` and `trace_id` of the failed generation for post-mortem debugging via GET /v1/projects/{project_id}/generations/{generation_id}. Streaming requests report the provider error in a terminal SSE frame instead, since their status line is already on the wire.
    *
@@ -9316,7 +9334,7 @@ type CreateAgentGenerationResponses = {
    */
   200: AgentGenerationResponse;
   /**
-   * Generation accepted and running in the background (default, when `wait` is omitted or `false`). Poll `GET /v1/projects/{project_id}/generations/{generation_id}` for the result.
+   * Generation accepted and running in the background (default, when `wait` is omitted or `false`), or — in every mode, streamed included — a duplicate request: the generation the `idempotency_key` already names is returned in whatever state it has reached and nothing runs. Poll `GET /v1/projects/{project_id}/generations/{generation_id}` for the result.
    */
   202: AcceptedGenerationResponse;
 };
@@ -22472,7 +22490,8 @@ export declare class Channels {
   /**
    * Replace a route
    *
-   * Full replace, the same validation as create.
+   * Full replace, the same validation as create: an omitted field takes its create default. Where that default would widen a value the route sets, omission is `400 replace_omits_fields`, naming the fields in `details.fields`, and nothing is written: a set `surface` (the default is any surface), a non-empty `match` (every message), a non-empty `config` (it carries the Discord allowlist), and `status` on a `disabled` route (the default re-activates it). Send the value to keep it, or `"surface": null`, `"match": {}`, `"config": null`, `"status": "active"` to clear it.
+   *
    */
   static updateChannelRoute<ThrowOnError extends boolean = false>(options: Options<UpdateChannelRouteData, ThrowOnError>): RequestResult<UpdateChannelRouteResponses, UpdateChannelRouteErrors, ThrowOnError>;
   /**
@@ -22670,7 +22689,7 @@ export declare class Agents {
   /**
    * Run an agent generation
    *
-   * Sends messages to the agent, resolves its tools, and runs the AI model loop. Background by default: returns `202 Accepted` with a `generation_id` to poll via `GET /v1/projects/{project_id}/generations/{generation_id}`. Pass `?wait=true` to block and receive the result inline, where client tools pause the generation and return `requires_action`. Streaming (`stream: true`) implies waiting.
+   * Sends messages to the agent, resolves its tools, and runs the AI model loop. Background by default: returns `202 Accepted` with a `generation_id` to poll via `GET /v1/projects/{project_id}/generations/{generation_id}`. Pass `?wait=true` to block and receive the result inline, where client tools pause the generation and return `requires_action`. Streaming (`stream: true`) implies waiting. Pass `idempotency_key` to make a retry safe: a request whose key is already claimed runs nothing and answers `202` with the generation the key names.
    *
    */
   static createAgentGeneration<ThrowOnError extends boolean = false>(options: Options<CreateAgentGenerationData, ThrowOnError>): RequestResult<CreateAgentGenerationResponses, CreateAgentGenerationErrors, ThrowOnError>;

package/dist/index.d.mts

@@ -1225,6 +1225,12 @@ type CreateAgentGenerationRequest = {
    * Caller-supplied key/value metadata attached to the generation record for per-run audit attribution (e.g. the knowledge-corpus version that produced this action). Round-trips verbatim when the generation is fetched via the generations API. The bag is caller-owned and no key is reserved: server-owned state (usage attribution, the served agent version, the model route's record, the extraction summary) lives in its own top-level generation fields and cannot be written from here. Use the request's own `action_id` field to set the usage-attribution label.
    */
   metadata?: NullableMetadataBag;
+  /**
+   * Deduplication key, unique within the project, that makes a retry of an at-least-once delivery or an ambiguous failure safe. The first request under a key runs the generation; any later request carrying it runs nothing and answers `202` with the generation the key names, whatever state it has reached — including a retry that arrives while the original is still running. The key is claimed by the generation record for as long as the record exists.
+   *
+   * Every other body field except `stream` is the request the key names: reusing a key with any of them changed, or on another agent of the project, is `409 IDEMPOTENCY_KEY_REUSED`. `stream` and `wait` say how the caller receives the generation, not what it is, so a retry may flip them.
+   */
+  idempotency_key?: string;
   /**
    * Per-generation knowledge retrieval override. Array filters (memory_store_ids, document_ids, document_paths) are unioned with the agent's stored knowledge_config; `tags` pairs are merged with the override winning per key; scalar fields (min_score, rrf_k, recency_half_life_days, limit) use the per-generation value when present.
    */
@@ -2210,7 +2216,7 @@ type ChannelRouteWrite = {
    */
   config?: {
     [key: string]: unknown;
-  };
+  } | null;
   status?: 'active' | 'disabled';
 };
 type ChannelRouteList = {
@@ -3836,7 +3842,7 @@ type TriggerResourceProperties = {
     [key: string]: unknown;
   } | null;
   /**
-   * Caller context every firing forwards to the run it starts, so an agent whose tools authorize through `{{context:<key>}}` can be scheduled. Write-only. A value may be a `{{secret:...}}` reference, which is what a template should carry — the credential stays in the secret store and only its name is checked in
+   * Caller context every firing forwards to the run it starts, so an agent whose tools authorize through `{{context:<key>}}` can be scheduled. Write-only. A value may be a `{{secret:sec_...}}` reference, which is what a template should carry — the credential stays in the secret store and only its id is checked in (a `sub` such as `{{secret:${MySecret}}}` for a template secret); a secret's name does not resolve and is refused
    */
   tool_context?: {
     [key: string]: string;
@@ -4586,6 +4592,10 @@ type Generation = {
      */
     estimated_tokens?: number;
   } | null;
+  /**
+   * The deduplication key the generation was started under, unique within the project and claimed for as long as the generation record exists. Null for a generation started without one.
+   */
+  idempotency_key?: string | null;
   /**
    * What the turn cost: token counts and `cost_usd` for every event metered against this generation. Present on the single-generation read; omitted from the listing, where it would be a query per row.
    *
@@ -5557,6 +5567,10 @@ type OrchestrationNode = {
    * For loop nodes — number of items to process in parallel.
    */
   parallelism?: number;
+  /**
+   * For loop nodes — what a failed item does. `fail` (the default) fails the node on the first item whose child run settles `failed`, `cancelled` or `expired`. `collect` keeps going: that item's entry in `results` becomes `{ "error": { "code", "message" }, "orchestration_run_id" }`, in its original position. Either way the artifact carries `failed_count`. A child run that could not be started (for example past the nesting depth bound) fails the node in both modes.
+   */
+  on_item_error?: 'fail' | 'collect';
   /**
    * For loop and sub_orchestration nodes — allowlist of the run's `tool_context` keys the child run inherits. When `null` (the default), the child inherits the parent's whole bag. When set, only the listed keys are handed down, so a run holding a broad credential can delegate one step to a shared sub-graph without passing on what that sub-graph does not need; `[]` hands down nothing. Matching is case-insensitive, since an entry names a key that becomes an HTTP header name; an entry outside that grammar is rejected at write time with `INVALID_TOOL_CONTEXT_KEY`. The server-derived identity keys (`session_id`, `actor_id`, `actor_external_id`) are unaffected — they are re-derived per generation in the child regardless of this list. Ignored for other node types.
    */
@@ -7352,7 +7366,7 @@ type CreateTriggerRequest = {
    *
    * **Write-only.** It is accepted here and never returned on a read, so the record cannot be used to recover a value.
    *
-   * A value may be a `{{secret:...}}` reference, which keeps the credential in the [secret](/docs/modules/secrets) store and leaves only its name on the trigger; it is resolved at fire time, so rotating the secret changes the next firing without touching the trigger. A reference naming a secret that does not exist in this project is refused here rather than at fire time.
+   * A value may be a `{{secret:sec_...}}` reference, which keeps the credential in the [secret](/docs/modules/secrets) store and leaves only its id on the trigger; it is resolved at fire time, so rotating the secret changes the next firing without touching the trigger. A reference is refused here rather than at fire time when it is not in that id form (a secret's name does not resolve) or names a secret that does not exist in this project.
    *
    */
   tool_context?: {
@@ -9288,7 +9302,7 @@ type CreateAgentGenerationData = {
 };
 type CreateAgentGenerationErrors = {
   /**
-   * Bad Request
+   * Bad Request (e.g. an `idempotency_key` that is not a non-empty string of at most 255 characters)
    */
   400: ErrorResponse;
   /**
@@ -9303,6 +9317,10 @@ type CreateAgentGenerationErrors = {
    * Agent or AI provider not found
    */
   404: ErrorResponse;
+  /**
+   * `IDEMPOTENCY_KEY_REUSED` — the key is already claimed by a generation started from a different request. Nothing runs.
+   */
+  409: ErrorResponse;
   /**
    * Upstream AI provider error (AI_PROVIDER_ERROR); model output that does not satisfy the agent's `output_schema` (OUTPUT_SCHEMA_VALIDATION_FAILED — the violated field is named in the message); or a model that wrote a tool invocation out as plain assistant text instead of calling the tool, so the tool never ran (TEXT_ENCODED_TOOL_CALL — `meta.tool_name` names the tool). The error `meta` includes the `generation_id` and `trace_id` of the failed generation for post-mortem debugging via GET /v1/projects/{project_id}/generations/{generation_id}. Streaming requests report the provider error in a terminal SSE frame instead, since their status line is already on the wire.
    *
@@ -9316,7 +9334,7 @@ type CreateAgentGenerationResponses = {
    */
   200: AgentGenerationResponse;
   /**
-   * Generation accepted and running in the background (default, when `wait` is omitted or `false`). Poll `GET /v1/projects/{project_id}/generations/{generation_id}` for the result.
+   * Generation accepted and running in the background (default, when `wait` is omitted or `false`), or — in every mode, streamed included — a duplicate request: the generation the `idempotency_key` already names is returned in whatever state it has reached and nothing runs. Poll `GET /v1/projects/{project_id}/generations/{generation_id}` for the result.
    */
   202: AcceptedGenerationResponse;
 };
@@ -22472,7 +22490,8 @@ export declare class Channels {
   /**
    * Replace a route
    *
-   * Full replace, the same validation as create.
+   * Full replace, the same validation as create: an omitted field takes its create default. Where that default would widen a value the route sets, omission is `400 replace_omits_fields`, naming the fields in `details.fields`, and nothing is written: a set `surface` (the default is any surface), a non-empty `match` (every message), a non-empty `config` (it carries the Discord allowlist), and `status` on a `disabled` route (the default re-activates it). Send the value to keep it, or `"surface": null`, `"match": {}`, `"config": null`, `"status": "active"` to clear it.
+   *
    */
   static updateChannelRoute<ThrowOnError extends boolean = false>(options: Options<UpdateChannelRouteData, ThrowOnError>): RequestResult<UpdateChannelRouteResponses, UpdateChannelRouteErrors, ThrowOnError>;
   /**
@@ -22670,7 +22689,7 @@ export declare class Agents {
   /**
    * Run an agent generation
    *
-   * Sends messages to the agent, resolves its tools, and runs the AI model loop. Background by default: returns `202 Accepted` with a `generation_id` to poll via `GET /v1/projects/{project_id}/generations/{generation_id}`. Pass `?wait=true` to block and receive the result inline, where client tools pause the generation and return `requires_action`. Streaming (`stream: true`) implies waiting.
+   * Sends messages to the agent, resolves its tools, and runs the AI model loop. Background by default: returns `202 Accepted` with a `generation_id` to poll via `GET /v1/projects/{project_id}/generations/{generation_id}`. Pass `?wait=true` to block and receive the result inline, where client tools pause the generation and return `requires_action`. Streaming (`stream: true`) implies waiting. Pass `idempotency_key` to make a retry safe: a request whose key is already claimed runs nothing and answers `202` with the generation the key names.
    *
    */
   static createAgentGeneration<ThrowOnError extends boolean = false>(options: Options<CreateAgentGenerationData, ThrowOnError>): RequestResult<CreateAgentGenerationResponses, CreateAgentGenerationErrors, ThrowOnError>;

package/dist/index.mjs

@@ -874,7 +874,8 @@ var Channels = class {
 	/**
 	* Replace a route
 	*
-	* Full replace, the same validation as create.
+	* Full replace, the same validation as create: an omitted field takes its create default. Where that default would widen a value the route sets, omission is `400 replace_omits_fields`, naming the fields in `details.fields`, and nothing is written: a set `surface` (the default is any surface), a non-empty `match` (every message), a non-empty `config` (it carries the Discord allowlist), and `status` on a `disabled` route (the default re-activates it). Send the value to keep it, or `"surface": null`, `"match": {}`, `"config": null`, `"status": "active"` to clear it.
+	*
 	*/
 	static updateChannelRoute(options) {
 		return (options.client ?? client).patch({
@@ -1237,7 +1238,7 @@ var Agents = class {
 	/**
 	* Run an agent generation
 	*
-	* Sends messages to the agent, resolves its tools, and runs the AI model loop. Background by default: returns `202 Accepted` with a `generation_id` to poll via `GET /v1/projects/{project_id}/generations/{generation_id}`. Pass `?wait=true` to block and receive the result inline, where client tools pause the generation and return `requires_action`. Streaming (`stream: true`) implies waiting.
+	* Sends messages to the agent, resolves its tools, and runs the AI model loop. Background by default: returns `202 Accepted` with a `generation_id` to poll via `GET /v1/projects/{project_id}/generations/{generation_id}`. Pass `?wait=true` to block and receive the result inline, where client tools pause the generation and return `requires_action`. Streaming (`stream: true`) implies waiting. Pass `idempotency_key` to make a retry safe: a request whose key is already claimed runs nothing and answers `202` with the generation the key names.
 	*
 	*/
 	static createAgentGeneration(options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/sdk",
-  "version": "0.141.5",
+  "version": "0.141.7",
   "description": "TypeScript SDK for the naturali.ai API, generated from its OpenAPI specs",
   "type": "module",
   "sideEffects": false,
@@ -31,7 +31,7 @@
   },
   "devDependencies": {
     "@hey-api/openapi-ts": "^0.99.0",
-    "@naturali/api": "0.141.5",
+    "@naturali/api": "0.141.7",
     "@ttoss/openapi-codegen": "^0.3.1",
     "@types/node": "^26.5.1",
     "tsdown": "^0.23.0",