@naturali/sdk 0.123.1 → 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({
@@ -3615,6 +3639,8 @@ var Projects = class {
 	*
 	* Every bucket also carries components — the amounts actually measured. The token counts describe LLM usage alone, so that is where a storage, api_request or compute_execution bucket reports its real quantity instead of zeroed token fields.
 	*
+	* The rollup can also be narrowed to one session or one end user before it is bucketed. That is the question no dimension answers: group_by splits the project's whole spend, so "what did this conversation cost, per day" and "what has this end user spent across every session" are reachable only by narrowing. The narrowings intersect, apply to the totals as well as the buckets, and are echoed back complete — null for each one not applied — because a rollup of zeros is otherwise indistinguishable from a project that spent nothing.
+	*
 	*/
 	static getProjectUsage(options) {
 		return (options.client ?? client).get({
@@ -3798,7 +3824,7 @@ var Sessions = class {
 	/**
 	* Get a 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.
+	* Returns details of a single session, including a `usage` roll-up of what its generations cost. The listing omits `usage`; for a window, a split by day or model, or one end user across every session, narrow `GET /v1/projects/{project_id}/usage` with `session_id` / `actor_id` instead.
 	*/
 	static getSession(options) {
 		return (options.client ?? client).get({
@@ -4356,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.
 	*
@@ -4436,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({