@naturali/sdk 0.124.0 → 0.125.0

package/dist/index.cjs

@@ -739,6 +739,9 @@ var Actors = class {
 var Channels = class {
 	/**
 	* List addresses
+	*
+	* Every identifier this project has seen. An address appears the first time a message arrives from it, so this is what naturali has observed rather than a roster you maintain — most rows carry no `action` of their own and defer to the route table.
+	*
 	*/
 	static listAddresses(options) {
 		return (options.client ?? client).get({
@@ -760,6 +763,9 @@ var Channels = class {
 	}
 	/**
 	* Get an address
+	*
+	* Reads one identifier's own action, if it has one. An identifier naturali has never seen is a `404`; to set an action without knowing whether it exists, use [`PUT /v1/projects/{project_id}/addresses/{identifier}`](/docs/api/addresses/set-address-action), which upserts.
+	*
 	*/
 	static getAddress(options) {
 		return (options.client ?? client).get({
@@ -809,6 +815,9 @@ var Channels = class {
 	}
 	/**
 	* List a channel's routes
+	*
+	* One channel's routes, newest first, `disabled` ones included — only `active` routes take part in resolution. For every route in the project in one read, use [`GET /v1/projects/{project_id}/channel-routes`](/docs/api/channel-routes/list-project-channel-routes).
+	*
 	*/
 	static listChannelRoutes(options) {
 		return (options.client ?? client).get({
@@ -834,6 +843,9 @@ var Channels = class {
 	}
 	/**
 	* Delete a route
+	*
+	* Conversations opened under this route keep its id and stay where they are; the next inbound resolves to the next most specific route, or the channel default, and opens a new conversation there. To stop a route from matching while keeping it readable, `PATCH` it to `status: disabled` instead.
+	*
 	*/
 	static deleteChannelRoute(options) {
 		return (options.client ?? client).delete({
@@ -843,6 +855,9 @@ var Channels = class {
 	}
 	/**
 	* Get a route
+	*
+	* A route id is only meaningful inside its own channel: the same id under another `channel_id` is a `404`. A conversation's `route_id` may instead be one of the two sentinels for the address's own action and the channel default — those name no route and are not readable here.
+	*
 	*/
 	static getChannelRoute(options) {
 		return (options.client ?? client).get({
@@ -931,6 +946,9 @@ var Channels = class {
 	}
 	/**
 	* Get a channel
+	*
+	* The channel's state, its transport modes and its default action. The access token is never returned — `has_credential` is all a read says about it.
+	*
 	*/
 	static getChannel(options) {
 		return (options.client ?? client).get({
@@ -985,6 +1003,9 @@ var Channels = class {
 	}
 	/**
 	* Get a conversation
+	*
+	* Where the conversation points: the address it belongs to, the route (or sentinel) whose action opened it, and the runtime session it maps 1:1 to. The messages are not here — read them with [`GET /v1/projects/{project_id}/channels/{channel_id}/conversations/{conversation_id}/messages`](/docs/api/channels/list-channel-conversation-messages).
+	*
 	*/
 	static getChannelConversation(options) {
 		return (options.client ?? client).get({
@@ -3217,6 +3238,9 @@ var Models = class {
 	}
 	/**
 	* Get a model
+	*
+	* `{model}` is naturali's own name for the model, the same value [`GET /v1/models`](/docs/api/models/list-models) returns — a vendor's invocation string is a `404`. A `deprecated` model still reads here, so a project already generating on one can see what happened to it.
+	*
 	*/
 	static getModel(options) {
 		return (options.client ?? client).get({
@@ -4358,9 +4382,11 @@ var Users = class {
 	/**
 	* Get the current account's billing standing
 	*
-	* The plan the account is on, how long its projects may keep content, and the credit it has left — the figures the platform already enforces against, readable by the account they are enforced against.
+	* The plan the account is on, how long its projects may keep content, how much indexed storage it is holding, and the credit it has left — the figures the platform already enforces against, readable by the account they are enforced against.
+	*
+	* A managed-model generation is refused with `402 insufficient_credit` while `credit_balance_usd` is negative, and a feature or a resource count outside the plan is refused with `403`, as is a retention window wider than `retention_days` or an ingest past `storage_limit_gb`. Every refusal names what is missing; this is where the numbers behind them are read.
 	*
-	* A managed-model generation is refused with `402 insufficient_credit` while `credit_balance_usd` is negative, and a feature or a resource count outside the plan is refused with `403`, as is a retention window wider than `retention_days`. Every refusal names what is missing; this is where the numbers behind them are read.
+	* Every figure here is a local read, which is what keeps this route cheap enough to poll — unlike `GET /v1/users/me/usage`, which asks the meter once per project.
 	*
 	* Answers for the caller's own account only, and always the account the credential resolves to — an API key answers for the user that minted it. The plan gating a *project* is that project's billing owner's, so a member of someone else's project reads their own rung here, not that project's.
 	*
@@ -4438,6 +4464,9 @@ var Webhooks = class {
 	}
 	/**
 	* Get a webhook
+	*
+	* The endpoint, the events it is subscribed to and whether deliveries are attempted. The signing secret is not returned: it is shown once by [`POST /v1/projects/{project_id}/webhooks`](/docs/api/webhooks/create-webhook) and again by [`POST /v1/projects/{project_id}/webhooks/{webhook_id}:rotate-secret`](/docs/api/webhooks/rotate-webhook-secret).
+	*
 	*/
 	static getWebhook(options) {
 		return (options.client ?? client).get({

package/dist/index.d.cts

@@ -499,6 +499,18 @@ type AdminUser = User & {
    * When this account's spend was last read off the meter, which is how current `credit_balance_usd` is. `null` when it has never been read for at least one of the account's projects, or the account has none. The same figure the account reads about itself at `GET /v1/users/me/billing`.
    */
   spend_reconciled_at: Date | null;
+  /**
+   * Indexed storage the account is holding, in the metered gigabytes the ceiling is enforced in — the account's pooled total across every project it pays for, not any one project's. The figure behind a `403 plan_limit_reached` on `resource: "storage"`, and the same one the account reads at `GET /v1/users/me/billing`.
+   */
+  storage_gb: number;
+  /**
+   * The pool the account's plan allows. `null` where a contract sets the ceiling, or where the plan sets none.
+   */
+  storage_limit_gb: number | null;
+  /**
+   * When the oldest sample behind `storage_gb` was taken — a total is only as current as its stalest part. `null` when a project the account pays for has never been sampled, or it has none.
+   */
+  storage_sampled_at: Date | null;
 };
 type AdminUserPage = {
   data: Array<AdminUser>;
@@ -6485,6 +6497,22 @@ type UserBilling = {
    * When spend was last read off the meter and written to the ledger. `null` when it has never been read for at least one of the account's projects, or the account has none — a balance whose spend has never been read is not current as of anything.
    */
   spend_reconciled_at: Date | null;
+  /**
+   * Indexed storage the account is holding, in the metered gigabytes the ceiling is enforced in — the raw file plus every chunk's text and its embedding vector, so not the size of what you uploaded.
+   *
+   * **The account's total, not a project's.** The ceiling is pooled across every project the account pays for, so one project may hold all of it. Per project, read the `gb_day` component of `GET /v1/projects/{project_id}/usage`.
+   */
+  storage_gb: number;
+  /**
+   * The pool the account's plan allows. An ingest past it is refused with `403 plan_limit_reached` and `resource: "storage"`, whose `details` carry this figure as `limit` and what you are holding as `storage_gb`. Null where a contract sets the ceiling, or where the plan sets none.
+   */
+  storage_limit_gb: number | null;
+  /**
+   * When the **oldest** of the samples behind `storage_gb` was taken — the total is only as current as its stalest part. Measured every few minutes per project rather than on this request, so read the two together, exactly as with the balance and `spend_reconciled_at`.
+   *
+   * Null when a project the account pays for has never been sampled, or it has no projects: a total missing a component is not current as of anything. The figure itself still reports what the samples that do exist add up to.
+   */
+  storage_sampled_at: Date | null;
 };
 type UserUsage = {
   /**
@@ -19445,6 +19473,9 @@ declare class Actors {
 declare class Channels {
   /**
    * List addresses
+   *
+   * Every identifier this project has seen. An address appears the first time a message arrives from it, so this is what naturali has observed rather than a roster you maintain — most rows carry no `action` of their own and defer to the route table.
+   *
    */
   static listAddresses<ThrowOnError extends boolean = false>(options: Options<ListAddressesData, ThrowOnError>): RequestResult<ListAddressesResponses, ListAddressesErrors, ThrowOnError>;
   /**
@@ -19456,6 +19487,9 @@ declare class Channels {
   static deleteAddress<ThrowOnError extends boolean = false>(options: Options<DeleteAddressData, ThrowOnError>): RequestResult<DeleteAddressResponses, DeleteAddressErrors, ThrowOnError>;
   /**
    * Get an address
+   *
+   * Reads one identifier's own action, if it has one. An identifier naturali has never seen is a `404`; to set an action without knowing whether it exists, use [`PUT /v1/projects/{project_id}/addresses/{identifier}`](/docs/api/addresses/set-address-action), which upserts.
+   *
    */
   static getAddress<ThrowOnError extends boolean = false>(options: Options<GetAddressData, ThrowOnError>): RequestResult<GetAddressResponses, GetAddressErrors, ThrowOnError>;
   /**
@@ -19481,6 +19515,9 @@ declare class Channels {
   static listChannelKinds<ThrowOnError extends boolean = false>(options?: Options<ListChannelKindsData, ThrowOnError>): RequestResult<ListChannelKindsResponses, ListChannelKindsErrors, ThrowOnError>;
   /**
    * List a channel's routes
+   *
+   * One channel's routes, newest first, `disabled` ones included — only `active` routes take part in resolution. For every route in the project in one read, use [`GET /v1/projects/{project_id}/channel-routes`](/docs/api/channel-routes/list-project-channel-routes).
+   *
    */
   static listChannelRoutes<ThrowOnError extends boolean = false>(options: Options<ListChannelRoutesData, ThrowOnError>): RequestResult<ListChannelRoutesResponses, ListChannelRoutesErrors, ThrowOnError>;
   /**
@@ -19492,10 +19529,16 @@ declare class Channels {
   static createChannelRoute<ThrowOnError extends boolean = false>(options: Options<CreateChannelRouteData, ThrowOnError>): RequestResult<CreateChannelRouteResponses, CreateChannelRouteErrors, ThrowOnError>;
   /**
    * Delete a route
+   *
+   * Conversations opened under this route keep its id and stay where they are; the next inbound resolves to the next most specific route, or the channel default, and opens a new conversation there. To stop a route from matching while keeping it readable, `PATCH` it to `status: disabled` instead.
+   *
    */
   static deleteChannelRoute<ThrowOnError extends boolean = false>(options: Options<DeleteChannelRouteData, ThrowOnError>): RequestResult<DeleteChannelRouteResponses, DeleteChannelRouteErrors, ThrowOnError>;
   /**
    * Get a route
+   *
+   * A route id is only meaningful inside its own channel: the same id under another `channel_id` is a `404`. A conversation's `route_id` may instead be one of the two sentinels for the address's own action and the channel default — those name no route and are not readable here.
+   *
    */
   static getChannelRoute<ThrowOnError extends boolean = false>(options: Options<GetChannelRouteData, ThrowOnError>): RequestResult<GetChannelRouteResponses, GetChannelRouteErrors, ThrowOnError>;
   /**
@@ -19546,6 +19589,9 @@ declare class Channels {
   static deleteChannel<ThrowOnError extends boolean = false>(options: Options<DeleteChannelData, ThrowOnError>): RequestResult<DeleteChannelResponses, DeleteChannelErrors, ThrowOnError>;
   /**
    * Get a channel
+   *
+   * The channel's state, its transport modes and its default action. The access token is never returned — `has_credential` is all a read says about it.
+   *
    */
   static getChannel<ThrowOnError extends boolean = false>(options: Options<GetChannelData, ThrowOnError>): RequestResult<GetChannelResponses, GetChannelErrors, ThrowOnError>;
   /**
@@ -19572,6 +19618,9 @@ declare class Channels {
   static openChannelConversation<ThrowOnError extends boolean = false>(options: Options<OpenChannelConversationData, ThrowOnError>): RequestResult<OpenChannelConversationResponses, OpenChannelConversationErrors, ThrowOnError>;
   /**
    * Get a conversation
+   *
+   * Where the conversation points: the address it belongs to, the route (or sentinel) whose action opened it, and the runtime session it maps 1:1 to. The messages are not here — read them with [`GET /v1/projects/{project_id}/channels/{channel_id}/conversations/{conversation_id}/messages`](/docs/api/channels/list-channel-conversation-messages).
+   *
    */
   static getChannelConversation<ThrowOnError extends boolean = false>(options: Options<GetChannelConversationData, ThrowOnError>): RequestResult<GetChannelConversationResponses, GetChannelConversationErrors, ThrowOnError>;
   /**
@@ -20741,6 +20790,9 @@ declare class Models {
   static listModels<ThrowOnError extends boolean = false>(options?: Options<ListModelsData, ThrowOnError>): RequestResult<ListModelsResponses, ListModelsErrors, ThrowOnError>;
   /**
    * Get a model
+   *
+   * `{model}` is naturali's own name for the model, the same value [`GET /v1/models`](/docs/api/models/list-models) returns — a vendor's invocation string is a `404`. A `deprecated` model still reads here, so a project already generating on one can see what happened to it.
+   *
    */
   static getModel<ThrowOnError extends boolean = false>(options: Options<GetModelData, ThrowOnError>): RequestResult<GetModelResponses, GetModelErrors, ThrowOnError>;
 }
@@ -21332,9 +21384,11 @@ declare class Users {
   /**
    * Get the current account's billing standing
    *
-   * The plan the account is on, how long its projects may keep content, and the credit it has left — the figures the platform already enforces against, readable by the account they are enforced against.
+   * The plan the account is on, how long its projects may keep content, how much indexed storage it is holding, and the credit it has left — the figures the platform already enforces against, readable by the account they are enforced against.
+   *
+   * A managed-model generation is refused with `402 insufficient_credit` while `credit_balance_usd` is negative, and a feature or a resource count outside the plan is refused with `403`, as is a retention window wider than `retention_days` or an ingest past `storage_limit_gb`. Every refusal names what is missing; this is where the numbers behind them are read.
    *
-   * A managed-model generation is refused with `402 insufficient_credit` while `credit_balance_usd` is negative, and a feature or a resource count outside the plan is refused with `403`, as is a retention window wider than `retention_days`. Every refusal names what is missing; this is where the numbers behind them are read.
+   * Every figure here is a local read, which is what keeps this route cheap enough to poll — unlike `GET /v1/users/me/usage`, which asks the meter once per project.
    *
    * Answers for the caller's own account only, and always the account the credential resolves to — an API key answers for the user that minted it. The plan gating a *project* is that project's billing owner's, so a member of someone else's project reads their own rung here, not that project's.
    *
@@ -21383,6 +21437,9 @@ declare class Webhooks {
   static deleteWebhook<ThrowOnError extends boolean = false>(options: Options<DeleteWebhookData, ThrowOnError>): RequestResult<DeleteWebhookResponses, DeleteWebhookErrors, ThrowOnError>;
   /**
    * Get a webhook
+   *
+   * The endpoint, the events it is subscribed to and whether deliveries are attempted. The signing secret is not returned: it is shown once by [`POST /v1/projects/{project_id}/webhooks`](/docs/api/webhooks/create-webhook) and again by [`POST /v1/projects/{project_id}/webhooks/{webhook_id}:rotate-secret`](/docs/api/webhooks/rotate-webhook-secret).
+   *
    */
   static getWebhook<ThrowOnError extends boolean = false>(options: Options<GetWebhookData, ThrowOnError>): RequestResult<GetWebhookResponses, GetWebhookErrors, ThrowOnError>;
   /**

package/dist/index.d.mts

@@ -499,6 +499,18 @@ type AdminUser = User & {
    * When this account's spend was last read off the meter, which is how current `credit_balance_usd` is. `null` when it has never been read for at least one of the account's projects, or the account has none. The same figure the account reads about itself at `GET /v1/users/me/billing`.
    */
   spend_reconciled_at: Date | null;
+  /**
+   * Indexed storage the account is holding, in the metered gigabytes the ceiling is enforced in — the account's pooled total across every project it pays for, not any one project's. The figure behind a `403 plan_limit_reached` on `resource: "storage"`, and the same one the account reads at `GET /v1/users/me/billing`.
+   */
+  storage_gb: number;
+  /**
+   * The pool the account's plan allows. `null` where a contract sets the ceiling, or where the plan sets none.
+   */
+  storage_limit_gb: number | null;
+  /**
+   * When the oldest sample behind `storage_gb` was taken — a total is only as current as its stalest part. `null` when a project the account pays for has never been sampled, or it has none.
+   */
+  storage_sampled_at: Date | null;
 };
 type AdminUserPage = {
   data: Array<AdminUser>;
@@ -6485,6 +6497,22 @@ type UserBilling = {
    * When spend was last read off the meter and written to the ledger. `null` when it has never been read for at least one of the account's projects, or the account has none — a balance whose spend has never been read is not current as of anything.
    */
   spend_reconciled_at: Date | null;
+  /**
+   * Indexed storage the account is holding, in the metered gigabytes the ceiling is enforced in — the raw file plus every chunk's text and its embedding vector, so not the size of what you uploaded.
+   *
+   * **The account's total, not a project's.** The ceiling is pooled across every project the account pays for, so one project may hold all of it. Per project, read the `gb_day` component of `GET /v1/projects/{project_id}/usage`.
+   */
+  storage_gb: number;
+  /**
+   * The pool the account's plan allows. An ingest past it is refused with `403 plan_limit_reached` and `resource: "storage"`, whose `details` carry this figure as `limit` and what you are holding as `storage_gb`. Null where a contract sets the ceiling, or where the plan sets none.
+   */
+  storage_limit_gb: number | null;
+  /**
+   * When the **oldest** of the samples behind `storage_gb` was taken — the total is only as current as its stalest part. Measured every few minutes per project rather than on this request, so read the two together, exactly as with the balance and `spend_reconciled_at`.
+   *
+   * Null when a project the account pays for has never been sampled, or it has no projects: a total missing a component is not current as of anything. The figure itself still reports what the samples that do exist add up to.
+   */
+  storage_sampled_at: Date | null;
 };
 type UserUsage = {
   /**
@@ -19445,6 +19473,9 @@ declare class Actors {
 declare class Channels {
   /**
    * List addresses
+   *
+   * Every identifier this project has seen. An address appears the first time a message arrives from it, so this is what naturali has observed rather than a roster you maintain — most rows carry no `action` of their own and defer to the route table.
+   *
    */
   static listAddresses<ThrowOnError extends boolean = false>(options: Options<ListAddressesData, ThrowOnError>): RequestResult<ListAddressesResponses, ListAddressesErrors, ThrowOnError>;
   /**
@@ -19456,6 +19487,9 @@ declare class Channels {
   static deleteAddress<ThrowOnError extends boolean = false>(options: Options<DeleteAddressData, ThrowOnError>): RequestResult<DeleteAddressResponses, DeleteAddressErrors, ThrowOnError>;
   /**
    * Get an address
+   *
+   * Reads one identifier's own action, if it has one. An identifier naturali has never seen is a `404`; to set an action without knowing whether it exists, use [`PUT /v1/projects/{project_id}/addresses/{identifier}`](/docs/api/addresses/set-address-action), which upserts.
+   *
    */
   static getAddress<ThrowOnError extends boolean = false>(options: Options<GetAddressData, ThrowOnError>): RequestResult<GetAddressResponses, GetAddressErrors, ThrowOnError>;
   /**
@@ -19481,6 +19515,9 @@ declare class Channels {
   static listChannelKinds<ThrowOnError extends boolean = false>(options?: Options<ListChannelKindsData, ThrowOnError>): RequestResult<ListChannelKindsResponses, ListChannelKindsErrors, ThrowOnError>;
   /**
    * List a channel's routes
+   *
+   * One channel's routes, newest first, `disabled` ones included — only `active` routes take part in resolution. For every route in the project in one read, use [`GET /v1/projects/{project_id}/channel-routes`](/docs/api/channel-routes/list-project-channel-routes).
+   *
    */
   static listChannelRoutes<ThrowOnError extends boolean = false>(options: Options<ListChannelRoutesData, ThrowOnError>): RequestResult<ListChannelRoutesResponses, ListChannelRoutesErrors, ThrowOnError>;
   /**
@@ -19492,10 +19529,16 @@ declare class Channels {
   static createChannelRoute<ThrowOnError extends boolean = false>(options: Options<CreateChannelRouteData, ThrowOnError>): RequestResult<CreateChannelRouteResponses, CreateChannelRouteErrors, ThrowOnError>;
   /**
    * Delete a route
+   *
+   * Conversations opened under this route keep its id and stay where they are; the next inbound resolves to the next most specific route, or the channel default, and opens a new conversation there. To stop a route from matching while keeping it readable, `PATCH` it to `status: disabled` instead.
+   *
    */
   static deleteChannelRoute<ThrowOnError extends boolean = false>(options: Options<DeleteChannelRouteData, ThrowOnError>): RequestResult<DeleteChannelRouteResponses, DeleteChannelRouteErrors, ThrowOnError>;
   /**
    * Get a route
+   *
+   * A route id is only meaningful inside its own channel: the same id under another `channel_id` is a `404`. A conversation's `route_id` may instead be one of the two sentinels for the address's own action and the channel default — those name no route and are not readable here.
+   *
    */
   static getChannelRoute<ThrowOnError extends boolean = false>(options: Options<GetChannelRouteData, ThrowOnError>): RequestResult<GetChannelRouteResponses, GetChannelRouteErrors, ThrowOnError>;
   /**
@@ -19546,6 +19589,9 @@ declare class Channels {
   static deleteChannel<ThrowOnError extends boolean = false>(options: Options<DeleteChannelData, ThrowOnError>): RequestResult<DeleteChannelResponses, DeleteChannelErrors, ThrowOnError>;
   /**
    * Get a channel
+   *
+   * The channel's state, its transport modes and its default action. The access token is never returned — `has_credential` is all a read says about it.
+   *
    */
   static getChannel<ThrowOnError extends boolean = false>(options: Options<GetChannelData, ThrowOnError>): RequestResult<GetChannelResponses, GetChannelErrors, ThrowOnError>;
   /**
@@ -19572,6 +19618,9 @@ declare class Channels {
   static openChannelConversation<ThrowOnError extends boolean = false>(options: Options<OpenChannelConversationData, ThrowOnError>): RequestResult<OpenChannelConversationResponses, OpenChannelConversationErrors, ThrowOnError>;
   /**
    * Get a conversation
+   *
+   * Where the conversation points: the address it belongs to, the route (or sentinel) whose action opened it, and the runtime session it maps 1:1 to. The messages are not here — read them with [`GET /v1/projects/{project_id}/channels/{channel_id}/conversations/{conversation_id}/messages`](/docs/api/channels/list-channel-conversation-messages).
+   *
    */
   static getChannelConversation<ThrowOnError extends boolean = false>(options: Options<GetChannelConversationData, ThrowOnError>): RequestResult<GetChannelConversationResponses, GetChannelConversationErrors, ThrowOnError>;
   /**
@@ -20741,6 +20790,9 @@ declare class Models {
   static listModels<ThrowOnError extends boolean = false>(options?: Options<ListModelsData, ThrowOnError>): RequestResult<ListModelsResponses, ListModelsErrors, ThrowOnError>;
   /**
    * Get a model
+   *
+   * `{model}` is naturali's own name for the model, the same value [`GET /v1/models`](/docs/api/models/list-models) returns — a vendor's invocation string is a `404`. A `deprecated` model still reads here, so a project already generating on one can see what happened to it.
+   *
    */
   static getModel<ThrowOnError extends boolean = false>(options: Options<GetModelData, ThrowOnError>): RequestResult<GetModelResponses, GetModelErrors, ThrowOnError>;
 }
@@ -21332,9 +21384,11 @@ declare class Users {
   /**
    * Get the current account's billing standing
    *
-   * The plan the account is on, how long its projects may keep content, and the credit it has left — the figures the platform already enforces against, readable by the account they are enforced against.
+   * The plan the account is on, how long its projects may keep content, how much indexed storage it is holding, and the credit it has left — the figures the platform already enforces against, readable by the account they are enforced against.
+   *
+   * A managed-model generation is refused with `402 insufficient_credit` while `credit_balance_usd` is negative, and a feature or a resource count outside the plan is refused with `403`, as is a retention window wider than `retention_days` or an ingest past `storage_limit_gb`. Every refusal names what is missing; this is where the numbers behind them are read.
    *
-   * A managed-model generation is refused with `402 insufficient_credit` while `credit_balance_usd` is negative, and a feature or a resource count outside the plan is refused with `403`, as is a retention window wider than `retention_days`. Every refusal names what is missing; this is where the numbers behind them are read.
+   * Every figure here is a local read, which is what keeps this route cheap enough to poll — unlike `GET /v1/users/me/usage`, which asks the meter once per project.
    *
    * Answers for the caller's own account only, and always the account the credential resolves to — an API key answers for the user that minted it. The plan gating a *project* is that project's billing owner's, so a member of someone else's project reads their own rung here, not that project's.
    *
@@ -21383,6 +21437,9 @@ declare class Webhooks {
   static deleteWebhook<ThrowOnError extends boolean = false>(options: Options<DeleteWebhookData, ThrowOnError>): RequestResult<DeleteWebhookResponses, DeleteWebhookErrors, ThrowOnError>;
   /**
    * Get a webhook
+   *
+   * The endpoint, the events it is subscribed to and whether deliveries are attempted. The signing secret is not returned: it is shown once by [`POST /v1/projects/{project_id}/webhooks`](/docs/api/webhooks/create-webhook) and again by [`POST /v1/projects/{project_id}/webhooks/{webhook_id}:rotate-secret`](/docs/api/webhooks/rotate-webhook-secret).
+   *
    */
   static getWebhook<ThrowOnError extends boolean = false>(options: Options<GetWebhookData, ThrowOnError>): RequestResult<GetWebhookResponses, GetWebhookErrors, ThrowOnError>;
   /**

package/dist/index.mjs

@@ -738,6 +738,9 @@ var Actors = class {
 var Channels = class {
 	/**
 	* List addresses
+	*
+	* Every identifier this project has seen. An address appears the first time a message arrives from it, so this is what naturali has observed rather than a roster you maintain — most rows carry no `action` of their own and defer to the route table.
+	*
 	*/
 	static listAddresses(options) {
 		return (options.client ?? client).get({
@@ -759,6 +762,9 @@ var Channels = class {
 	}
 	/**
 	* Get an address
+	*
+	* Reads one identifier's own action, if it has one. An identifier naturali has never seen is a `404`; to set an action without knowing whether it exists, use [`PUT /v1/projects/{project_id}/addresses/{identifier}`](/docs/api/addresses/set-address-action), which upserts.
+	*
 	*/
 	static getAddress(options) {
 		return (options.client ?? client).get({
@@ -808,6 +814,9 @@ var Channels = class {
 	}
 	/**
 	* List a channel's routes
+	*
+	* One channel's routes, newest first, `disabled` ones included — only `active` routes take part in resolution. For every route in the project in one read, use [`GET /v1/projects/{project_id}/channel-routes`](/docs/api/channel-routes/list-project-channel-routes).
+	*
 	*/
 	static listChannelRoutes(options) {
 		return (options.client ?? client).get({
@@ -833,6 +842,9 @@ var Channels = class {
 	}
 	/**
 	* Delete a route
+	*
+	* Conversations opened under this route keep its id and stay where they are; the next inbound resolves to the next most specific route, or the channel default, and opens a new conversation there. To stop a route from matching while keeping it readable, `PATCH` it to `status: disabled` instead.
+	*
 	*/
 	static deleteChannelRoute(options) {
 		return (options.client ?? client).delete({
@@ -842,6 +854,9 @@ var Channels = class {
 	}
 	/**
 	* Get a route
+	*
+	* A route id is only meaningful inside its own channel: the same id under another `channel_id` is a `404`. A conversation's `route_id` may instead be one of the two sentinels for the address's own action and the channel default — those name no route and are not readable here.
+	*
 	*/
 	static getChannelRoute(options) {
 		return (options.client ?? client).get({
@@ -930,6 +945,9 @@ var Channels = class {
 	}
 	/**
 	* Get a channel
+	*
+	* The channel's state, its transport modes and its default action. The access token is never returned — `has_credential` is all a read says about it.
+	*
 	*/
 	static getChannel(options) {
 		return (options.client ?? client).get({
@@ -984,6 +1002,9 @@ var Channels = class {
 	}
 	/**
 	* Get a conversation
+	*
+	* Where the conversation points: the address it belongs to, the route (or sentinel) whose action opened it, and the runtime session it maps 1:1 to. The messages are not here — read them with [`GET /v1/projects/{project_id}/channels/{channel_id}/conversations/{conversation_id}/messages`](/docs/api/channels/list-channel-conversation-messages).
+	*
 	*/
 	static getChannelConversation(options) {
 		return (options.client ?? client).get({
@@ -3216,6 +3237,9 @@ var Models = class {
 	}
 	/**
 	* Get a model
+	*
+	* `{model}` is naturali's own name for the model, the same value [`GET /v1/models`](/docs/api/models/list-models) returns — a vendor's invocation string is a `404`. A `deprecated` model still reads here, so a project already generating on one can see what happened to it.
+	*
 	*/
 	static getModel(options) {
 		return (options.client ?? client).get({
@@ -4357,9 +4381,11 @@ var Users = class {
 	/**
 	* Get the current account's billing standing
 	*
-	* The plan the account is on, how long its projects may keep content, and the credit it has left — the figures the platform already enforces against, readable by the account they are enforced against.
+	* The plan the account is on, how long its projects may keep content, how much indexed storage it is holding, and the credit it has left — the figures the platform already enforces against, readable by the account they are enforced against.
+	*
+	* A managed-model generation is refused with `402 insufficient_credit` while `credit_balance_usd` is negative, and a feature or a resource count outside the plan is refused with `403`, as is a retention window wider than `retention_days` or an ingest past `storage_limit_gb`. Every refusal names what is missing; this is where the numbers behind them are read.
 	*
-	* A managed-model generation is refused with `402 insufficient_credit` while `credit_balance_usd` is negative, and a feature or a resource count outside the plan is refused with `403`, as is a retention window wider than `retention_days`. Every refusal names what is missing; this is where the numbers behind them are read.
+	* Every figure here is a local read, which is what keeps this route cheap enough to poll — unlike `GET /v1/users/me/usage`, which asks the meter once per project.
 	*
 	* Answers for the caller's own account only, and always the account the credential resolves to — an API key answers for the user that minted it. The plan gating a *project* is that project's billing owner's, so a member of someone else's project reads their own rung here, not that project's.
 	*
@@ -4437,6 +4463,9 @@ var Webhooks = class {
 	}
 	/**
 	* Get a webhook
+	*
+	* The endpoint, the events it is subscribed to and whether deliveries are attempted. The signing secret is not returned: it is shown once by [`POST /v1/projects/{project_id}/webhooks`](/docs/api/webhooks/create-webhook) and again by [`POST /v1/projects/{project_id}/webhooks/{webhook_id}:rotate-secret`](/docs/api/webhooks/rotate-webhook-secret).
+	*
 	*/
 	static getWebhook(options) {
 		return (options.client ?? client).get({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/sdk",
-  "version": "0.124.0",
+  "version": "0.125.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.124.0"
+    "@naturali/api": "0.125.0"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts",