@naturali/sdk 0.226.1 → 0.226.3

package/dist/index.d.cts

@@ -451,9 +451,21 @@ type TagBag = {
   [key: string]: string;
 };
 type Address = ChannelAction & {
+  /**
+   * Public address ID.
+   */
   id: string;
+  /**
+   * The owning project.
+   */
   project_id: string;
+  /**
+   * The prefixed, self-describing channel identifier.
+   */
   identifier: string;
+  /**
+   * A human-friendly name, as the channel reported it.
+   */
   display_name: string | null;
   /**
    * The actor this address speaks as: the one bound with `actor_id`, else one naturali creates when it first needs it (null until then).
@@ -563,8 +575,17 @@ type User = {
    * Public user ID (user_ prefix).
    */
   id: string;
+  /**
+   * The address sign-in codes are sent to. Read-only here.
+   */
   email: string;
+  /**
+   * Display name.
+   */
   name?: string | null;
+  /**
+   * Whether the address has completed a sign-in code exchange.
+   */
   email_verified: boolean;
   /**
    * Roles on naturali itself, not on a project. Empty for almost every account; `admin` marks a naturali operator. Changed only through `PUT /v1/admin/users/{user_id}/roles`, by a caller holding the role that grants each one.
@@ -932,6 +953,9 @@ type ListingPricingNext = {
  * A listing, as its publisher reads it.
  */
 type Listing = {
+  /**
+   * Public listing ID (lst_ prefix).
+   */
   id: string;
   /**
    * The publishing project.
@@ -942,7 +966,13 @@ type Listing = {
    * The published tool or agent.
    */
   resource_id: string;
+  /**
+   * Up to 120 characters.
+   */
   title: string;
+  /**
+   * Up to 2,000 characters.
+   */
   description: string | null;
   /**
    * What an installing project is charged per call. Empty is free.
@@ -2069,6 +2099,9 @@ type ApiKeyRecord = {
    * Public API key ID (key_ prefix).
    */
   id: string;
+  /**
+   * Human-readable label.
+   */
   name: string;
   /**
    * Leading characters of the raw key, for identification.
@@ -2276,7 +2309,7 @@ type AssistantGrant = {
    */
   display_name: string | null;
   /**
-   * What the Assistant may do on the account. Deliberately coarse: the consent for a specific dangerous action is asked for when it happens, through the approval queue, rather than pre-granted here.
+   * What the Assistant may do on the account. Deliberately coarse: the consent for a specific dangerous action is asked for when it happens, through the approval queue, rather than pre-granted here. A link grants `read`.
    *
    */
   scopes: Array<AssistantScope>;
@@ -2581,16 +2614,34 @@ type ChannelPredicate = {
   type: string;
 };
 type ChannelKind = {
+  /**
+   * The channel kind.
+   */
   kind: 'whatsapp' | 'discord';
+  /**
+   * This kind's conversational shapes.
+   */
   surfaces: Array<ChannelSurface>;
+  /**
+   * The `match` keys a route on this kind can use.
+   */
   predicates: Array<ChannelPredicate>;
 };
 type ChannelKindList = {
   data: Array<ChannelKind>;
 };
 type ChannelRoute = ChannelAction & {
+  /**
+   * Public route ID.
+   */
   id: string;
+  /**
+   * The owning project.
+   */
   project_id: string;
+  /**
+   * The channel this route belongs to.
+   */
   channel_id: string;
   /**
    * The surface this route matches, or null for "any" (`GET /v1/channel-kinds`).
@@ -2658,7 +2709,13 @@ type Channel = {
    * Public channel ID (chan_ prefix).
    */
   id: string;
+  /**
+   * The owning project.
+   */
   project_id: string;
+  /**
+   * The channel kind.
+   */
   channel: 'whatsapp' | 'discord';
   status: 'active' | 'disabled';
   /**
@@ -5193,7 +5250,7 @@ type FormationResource = {
    */
   resource_type?: string;
   /**
-   * Public ID of the physical the runtime resource
+   * Public ID of the physical resource
    */
   physical_resource_id?: string | null;
   /**
@@ -5559,7 +5616,7 @@ type Generation = {
    */
   node_attempt?: number | null;
   /**
-   * Agent config version that served this generation, resolved by the served-version resolver (see [agent versions](/docs/modules/agents#versions-and-releases)).
+   * Agent config version that served this generation, resolved by the served-version resolver (see [agent versions](/docs/modules/agents#versioning-and-staged-rollout)).
    *
    */
   agent_version?: number | null;
@@ -5569,7 +5626,7 @@ type Generation = {
    */
   source?: string | null;
   /**
-   * What each [memory rule](/docs/modules/memories#memory-rules) bound to `generations.completed` wrote for this turn, keyed by the rule's id — a store may have several rules, and one flat pair of counts could not say which produced them. Absent when no rule fired. Rules bound to `conversation_messages.generated` are recorded only as memory assertions. The rows behind every count are listed by `GET /v1/projects/{project_id}/generations/{generation_id}/memory-assertions`, so the summary and what it summarizes can be reconciled.
+   * What each [memory rule](/docs/modules/memory-rules) bound to `generations.completed` wrote for this turn, keyed by the rule's id — a store may have several rules, and one flat pair of counts could not say which produced them. Absent when no rule fired. Rules bound to `conversation_messages.generated` are recorded only as memory assertions. The rows behind every count are listed by `GET /v1/projects/{project_id}/generations/{generation_id}/memory-assertions`, so the summary and what it summarizes can be reconciled.
    *
    */
   extraction?: {
@@ -6157,11 +6214,17 @@ type IngestionRule = {
  * A listing installed in a project.
  */
 type Install = {
+  /**
+   * Public install ID (ins_ prefix).
+   */
   id: string;
   /**
    * The installing project.
    */
   project_id: string;
+  /**
+   * The installed listing.
+   */
   listing_id: string;
   resource_type: 'tool' | 'agent';
   /**
@@ -6485,6 +6548,9 @@ type McpServerAuthWrite = {
    */
   header_name?: string;
 };
+/**
+ * Who may connect. See [Auth](/docs/modules/mcp-servers#auth).
+ */
 type McpServerAuth = {
   type: 'oauth' | 'header' | 'none';
   mode?: 'members' | 'allowlist';
@@ -6505,6 +6571,9 @@ type McpServer = {
    * Public MCP server ID (mcps_ prefix).
    */
   id: string;
+  /**
+   * The owning project.
+   */
   project_id: string;
   /**
    * Where MCP clients connect (Streamable HTTP). An `oauth` server answers `401` without a token, naming its OAuth protected resource metadata (RFC 9728) at `/.well-known/oauth-protected-resource/servers/{id}` on the same host, which names the issuer to sign in at.
@@ -6530,6 +6599,9 @@ type McpServer = {
    * `serverInfo.websiteUrl`.
    */
   website_url: string | null;
+  /**
+   * `tool_id`, `action`, and the `name` and `description` clients see; at most 100.
+   */
   tools: Array<McpServerToolEntry>;
   /**
    * `list` lists every tool; `compact` serves `search`, `describe` and `call` over them.
@@ -6537,13 +6609,16 @@ type McpServer = {
   tool_mode: 'list' | 'compact';
   context_keys: McpContextKeys;
   auth: McpServerAuth;
+  /**
+   * Calls per UTC day. Required when `auth` is `none`.
+   */
   daily_call_limit: number | null;
   created_at: Date;
   updated_at: Date;
 };
 type McpServerDetail = McpServer & {
   /**
-   * Items the server does not serve now: the tool is gone, or the action is no longer one of its available actions. `tools/list` leaves them out and a call to one is a tool error.
+   * Items the server does not serve now: the tool is gone, or the action is no longer one of its available actions. `tools/list` leaves them out and a call to one is a tool error. Returned by get, create and update, not by list.
    */
   unavailable_tools: Array<McpServerToolEntry>;
 };
@@ -6582,8 +6657,17 @@ type McpServerKey = {
    * Public key ID (mcpk_ prefix).
    */
   id: string;
+  /**
+   * The owning project.
+   */
   project_id: string;
+  /**
+   * The server the key opens.
+   */
   mcp_server_id: string;
+  /**
+   * Label.
+   */
   name: string | null;
   /**
    * The start of the key, to tell keys apart.
@@ -6594,7 +6678,7 @@ type McpServerKey = {
 };
 type McpServerKeyWithSecret = McpServerKey & {
   /**
-   * The key, returned only here.
+   * The key (nat_mcp_ prefix), returned only by the create response.
    */
   key: string;
 };
@@ -6783,7 +6867,13 @@ type Model = {
    * Accepted input modalities.
    */
   input_modalities: Array<string>;
+  /**
+   * Modalities the model can produce.
+   */
   output_modalities: Array<string>;
+  /**
+   * Whether the model supports streaming responses.
+   */
   streaming: boolean;
   /**
    * Lifecycle status, from the provider's own listing at the last sync. A model the provider stops listing — or reports as legacy or deprecated — flips to `deprecated` and stays in the catalog, so a project already generating on it can see what happened to it. A `deprecated` model cannot be chosen as the `default_model` of a new `provider: "naturali"` provider.
@@ -8009,7 +8099,13 @@ type Project = {
    * Public project ID (proj_ prefix).
    */
   id: string;
+  /**
+   * Human-readable label.
+   */
   name: string;
+  /**
+   * Lifecycle status.
+   */
   status: 'active' | 'archived';
   role: ProjectRole;
   /**
@@ -9633,9 +9729,21 @@ type TopUp = {
   expires_at: Date | null;
 };
 type PaymentMethod = {
+  /**
+   * Card brand, such as `visa`.
+   */
   brand: string;
+  /**
+   * Last four digits.
+   */
   last4: string;
+  /**
+   * Expiry month.
+   */
   exp_month: number;
+  /**
+   * Expiry year.
+   */
   exp_year: number;
   /**
    * What the card is charged in, from its issuing country.
@@ -9661,6 +9769,9 @@ type PaymentMethodSetup = {
   expires_at: Date;
 };
 type AutoRecharge = {
+  /**
+   * Whether the balance is topped up automatically.
+   */
   enabled: boolean;
   /**
    * What each recharge buys. `null` while off.
@@ -9718,7 +9829,7 @@ type UserPlanChange = {
   expires_at: Date | null;
 };
 /**
- * A naturali event type. The set below is what this API emits — deliberately only the events it can itself cause, so no declared name is one that never fires. It grows as modules land.
+ * A naturali event type. Its values are what this API emits — deliberately only the events it can itself cause, so no declared name is one that never fires. It grows as modules land.
  *
  */
 type EventType = 'conversation.started' | 'message.received' | 'generation.completed' | 'generation.failed' | 'usage.threshold_crossed' | 'project.paused' | 'project.resumed' | 'decision.completed' | 'decision.failed' | 'task.created' | 'task.transitioned' | 'task.closed' | 'task.migrated' | 'task.stalled' | 'task.paused' | 'task.resumed' | 'task.approval_failed' | 'task.automation_retrying' | 'task.automation_rejected' | 'task.automation_unrouted' | 'approval.created' | 'approval.approved' | 'approval.rejected' | 'approval.expired';
@@ -9761,9 +9872,12 @@ type Webhook = {
    * Public webhook ID (whk_ prefix).
    */
   id: string;
+  /**
+   * The owning project.
+   */
   project_id: string;
   /**
-   * Where deliveries are POSTed.
+   * Where deliveries are POSTed: an `https://` URL on a public internet host. A host that is, or resolves to, a loopback, private or link-local address is refused, at save and at each delivery; redirects are not followed.
    */
   url: string;
   events: EventSubscription;
@@ -9820,7 +9934,13 @@ type WebhookDelivery = {
    *
    */
   id: string;
+  /**
+   * The owning project.
+   */
   project_id: string;
+  /**
+   * The endpoint the delivery is addressed to.
+   */
   webhook_id: string;
   /**
    * The event's id; shared by every delivery and redelivery of it.

package/dist/index.d.mts

@@ -451,9 +451,21 @@ type TagBag = {
   [key: string]: string;
 };
 type Address = ChannelAction & {
+  /**
+   * Public address ID.
+   */
   id: string;
+  /**
+   * The owning project.
+   */
   project_id: string;
+  /**
+   * The prefixed, self-describing channel identifier.
+   */
   identifier: string;
+  /**
+   * A human-friendly name, as the channel reported it.
+   */
   display_name: string | null;
   /**
    * The actor this address speaks as: the one bound with `actor_id`, else one naturali creates when it first needs it (null until then).
@@ -563,8 +575,17 @@ type User = {
    * Public user ID (user_ prefix).
    */
   id: string;
+  /**
+   * The address sign-in codes are sent to. Read-only here.
+   */
   email: string;
+  /**
+   * Display name.
+   */
   name?: string | null;
+  /**
+   * Whether the address has completed a sign-in code exchange.
+   */
   email_verified: boolean;
   /**
    * Roles on naturali itself, not on a project. Empty for almost every account; `admin` marks a naturali operator. Changed only through `PUT /v1/admin/users/{user_id}/roles`, by a caller holding the role that grants each one.
@@ -932,6 +953,9 @@ type ListingPricingNext = {
  * A listing, as its publisher reads it.
  */
 type Listing = {
+  /**
+   * Public listing ID (lst_ prefix).
+   */
   id: string;
   /**
    * The publishing project.
@@ -942,7 +966,13 @@ type Listing = {
    * The published tool or agent.
    */
   resource_id: string;
+  /**
+   * Up to 120 characters.
+   */
   title: string;
+  /**
+   * Up to 2,000 characters.
+   */
   description: string | null;
   /**
    * What an installing project is charged per call. Empty is free.
@@ -2069,6 +2099,9 @@ type ApiKeyRecord = {
    * Public API key ID (key_ prefix).
    */
   id: string;
+  /**
+   * Human-readable label.
+   */
   name: string;
   /**
    * Leading characters of the raw key, for identification.
@@ -2276,7 +2309,7 @@ type AssistantGrant = {
    */
   display_name: string | null;
   /**
-   * What the Assistant may do on the account. Deliberately coarse: the consent for a specific dangerous action is asked for when it happens, through the approval queue, rather than pre-granted here.
+   * What the Assistant may do on the account. Deliberately coarse: the consent for a specific dangerous action is asked for when it happens, through the approval queue, rather than pre-granted here. A link grants `read`.
    *
    */
   scopes: Array<AssistantScope>;
@@ -2581,16 +2614,34 @@ type ChannelPredicate = {
   type: string;
 };
 type ChannelKind = {
+  /**
+   * The channel kind.
+   */
   kind: 'whatsapp' | 'discord';
+  /**
+   * This kind's conversational shapes.
+   */
   surfaces: Array<ChannelSurface>;
+  /**
+   * The `match` keys a route on this kind can use.
+   */
   predicates: Array<ChannelPredicate>;
 };
 type ChannelKindList = {
   data: Array<ChannelKind>;
 };
 type ChannelRoute = ChannelAction & {
+  /**
+   * Public route ID.
+   */
   id: string;
+  /**
+   * The owning project.
+   */
   project_id: string;
+  /**
+   * The channel this route belongs to.
+   */
   channel_id: string;
   /**
    * The surface this route matches, or null for "any" (`GET /v1/channel-kinds`).
@@ -2658,7 +2709,13 @@ type Channel = {
    * Public channel ID (chan_ prefix).
    */
   id: string;
+  /**
+   * The owning project.
+   */
   project_id: string;
+  /**
+   * The channel kind.
+   */
   channel: 'whatsapp' | 'discord';
   status: 'active' | 'disabled';
   /**
@@ -5193,7 +5250,7 @@ type FormationResource = {
    */
   resource_type?: string;
   /**
-   * Public ID of the physical the runtime resource
+   * Public ID of the physical resource
    */
   physical_resource_id?: string | null;
   /**
@@ -5559,7 +5616,7 @@ type Generation = {
    */
   node_attempt?: number | null;
   /**
-   * Agent config version that served this generation, resolved by the served-version resolver (see [agent versions](/docs/modules/agents#versions-and-releases)).
+   * Agent config version that served this generation, resolved by the served-version resolver (see [agent versions](/docs/modules/agents#versioning-and-staged-rollout)).
    *
    */
   agent_version?: number | null;
@@ -5569,7 +5626,7 @@ type Generation = {
    */
   source?: string | null;
   /**
-   * What each [memory rule](/docs/modules/memories#memory-rules) bound to `generations.completed` wrote for this turn, keyed by the rule's id — a store may have several rules, and one flat pair of counts could not say which produced them. Absent when no rule fired. Rules bound to `conversation_messages.generated` are recorded only as memory assertions. The rows behind every count are listed by `GET /v1/projects/{project_id}/generations/{generation_id}/memory-assertions`, so the summary and what it summarizes can be reconciled.
+   * What each [memory rule](/docs/modules/memory-rules) bound to `generations.completed` wrote for this turn, keyed by the rule's id — a store may have several rules, and one flat pair of counts could not say which produced them. Absent when no rule fired. Rules bound to `conversation_messages.generated` are recorded only as memory assertions. The rows behind every count are listed by `GET /v1/projects/{project_id}/generations/{generation_id}/memory-assertions`, so the summary and what it summarizes can be reconciled.
    *
    */
   extraction?: {
@@ -6157,11 +6214,17 @@ type IngestionRule = {
  * A listing installed in a project.
  */
 type Install = {
+  /**
+   * Public install ID (ins_ prefix).
+   */
   id: string;
   /**
    * The installing project.
    */
   project_id: string;
+  /**
+   * The installed listing.
+   */
   listing_id: string;
   resource_type: 'tool' | 'agent';
   /**
@@ -6485,6 +6548,9 @@ type McpServerAuthWrite = {
    */
   header_name?: string;
 };
+/**
+ * Who may connect. See [Auth](/docs/modules/mcp-servers#auth).
+ */
 type McpServerAuth = {
   type: 'oauth' | 'header' | 'none';
   mode?: 'members' | 'allowlist';
@@ -6505,6 +6571,9 @@ type McpServer = {
    * Public MCP server ID (mcps_ prefix).
    */
   id: string;
+  /**
+   * The owning project.
+   */
   project_id: string;
   /**
    * Where MCP clients connect (Streamable HTTP). An `oauth` server answers `401` without a token, naming its OAuth protected resource metadata (RFC 9728) at `/.well-known/oauth-protected-resource/servers/{id}` on the same host, which names the issuer to sign in at.
@@ -6530,6 +6599,9 @@ type McpServer = {
    * `serverInfo.websiteUrl`.
    */
   website_url: string | null;
+  /**
+   * `tool_id`, `action`, and the `name` and `description` clients see; at most 100.
+   */
   tools: Array<McpServerToolEntry>;
   /**
    * `list` lists every tool; `compact` serves `search`, `describe` and `call` over them.
@@ -6537,13 +6609,16 @@ type McpServer = {
   tool_mode: 'list' | 'compact';
   context_keys: McpContextKeys;
   auth: McpServerAuth;
+  /**
+   * Calls per UTC day. Required when `auth` is `none`.
+   */
   daily_call_limit: number | null;
   created_at: Date;
   updated_at: Date;
 };
 type McpServerDetail = McpServer & {
   /**
-   * Items the server does not serve now: the tool is gone, or the action is no longer one of its available actions. `tools/list` leaves them out and a call to one is a tool error.
+   * Items the server does not serve now: the tool is gone, or the action is no longer one of its available actions. `tools/list` leaves them out and a call to one is a tool error. Returned by get, create and update, not by list.
    */
   unavailable_tools: Array<McpServerToolEntry>;
 };
@@ -6582,8 +6657,17 @@ type McpServerKey = {
    * Public key ID (mcpk_ prefix).
    */
   id: string;
+  /**
+   * The owning project.
+   */
   project_id: string;
+  /**
+   * The server the key opens.
+   */
   mcp_server_id: string;
+  /**
+   * Label.
+   */
   name: string | null;
   /**
    * The start of the key, to tell keys apart.
@@ -6594,7 +6678,7 @@ type McpServerKey = {
 };
 type McpServerKeyWithSecret = McpServerKey & {
   /**
-   * The key, returned only here.
+   * The key (nat_mcp_ prefix), returned only by the create response.
    */
   key: string;
 };
@@ -6783,7 +6867,13 @@ type Model = {
    * Accepted input modalities.
    */
   input_modalities: Array<string>;
+  /**
+   * Modalities the model can produce.
+   */
   output_modalities: Array<string>;
+  /**
+   * Whether the model supports streaming responses.
+   */
   streaming: boolean;
   /**
    * Lifecycle status, from the provider's own listing at the last sync. A model the provider stops listing — or reports as legacy or deprecated — flips to `deprecated` and stays in the catalog, so a project already generating on it can see what happened to it. A `deprecated` model cannot be chosen as the `default_model` of a new `provider: "naturali"` provider.
@@ -8009,7 +8099,13 @@ type Project = {
    * Public project ID (proj_ prefix).
    */
   id: string;
+  /**
+   * Human-readable label.
+   */
   name: string;
+  /**
+   * Lifecycle status.
+   */
   status: 'active' | 'archived';
   role: ProjectRole;
   /**
@@ -9633,9 +9729,21 @@ type TopUp = {
   expires_at: Date | null;
 };
 type PaymentMethod = {
+  /**
+   * Card brand, such as `visa`.
+   */
   brand: string;
+  /**
+   * Last four digits.
+   */
   last4: string;
+  /**
+   * Expiry month.
+   */
   exp_month: number;
+  /**
+   * Expiry year.
+   */
   exp_year: number;
   /**
    * What the card is charged in, from its issuing country.
@@ -9661,6 +9769,9 @@ type PaymentMethodSetup = {
   expires_at: Date;
 };
 type AutoRecharge = {
+  /**
+   * Whether the balance is topped up automatically.
+   */
   enabled: boolean;
   /**
    * What each recharge buys. `null` while off.
@@ -9718,7 +9829,7 @@ type UserPlanChange = {
   expires_at: Date | null;
 };
 /**
- * A naturali event type. The set below is what this API emits — deliberately only the events it can itself cause, so no declared name is one that never fires. It grows as modules land.
+ * A naturali event type. Its values are what this API emits — deliberately only the events it can itself cause, so no declared name is one that never fires. It grows as modules land.
  *
  */
 type EventType = 'conversation.started' | 'message.received' | 'generation.completed' | 'generation.failed' | 'usage.threshold_crossed' | 'project.paused' | 'project.resumed' | 'decision.completed' | 'decision.failed' | 'task.created' | 'task.transitioned' | 'task.closed' | 'task.migrated' | 'task.stalled' | 'task.paused' | 'task.resumed' | 'task.approval_failed' | 'task.automation_retrying' | 'task.automation_rejected' | 'task.automation_unrouted' | 'approval.created' | 'approval.approved' | 'approval.rejected' | 'approval.expired';
@@ -9761,9 +9872,12 @@ type Webhook = {
    * Public webhook ID (whk_ prefix).
    */
   id: string;
+  /**
+   * The owning project.
+   */
   project_id: string;
   /**
-   * Where deliveries are POSTed.
+   * Where deliveries are POSTed: an `https://` URL on a public internet host. A host that is, or resolves to, a loopback, private or link-local address is refused, at save and at each delivery; redirects are not followed.
    */
   url: string;
   events: EventSubscription;
@@ -9820,7 +9934,13 @@ type WebhookDelivery = {
    *
    */
   id: string;
+  /**
+   * The owning project.
+   */
   project_id: string;
+  /**
+   * The endpoint the delivery is addressed to.
+   */
   webhook_id: string;
   /**
    * The event's id; shared by every delivery and redelivery of it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/sdk",
-  "version": "0.226.1",
+  "version": "0.226.3",
   "description": "TypeScript SDK for the naturali.ai API, generated from its OpenAPI specs",
   "keywords": [
     "naturali",
@@ -38,7 +38,7 @@
   },
   "devDependencies": {
     "@hey-api/openapi-ts": "^0.99.0",
-    "@naturali/api": "0.226.1",
+    "@naturali/api": "0.226.3",
     "@ttoss/openapi-codegen": "^0.10.0",
     "@types/node": "^26.5.1",
     "tsdown": "^0.23.0",