@naturali/cli 0.94.0 → 0.96.0

package/dist/index.mjs

@@ -14,7 +14,7 @@ var __exportAll = (all, no_symbols) => {
 };
 //#endregion
 //#region package.json
-var version = "0.94.0";
+var version = "0.96.0";
 //#endregion
 //#region ../sdk/src/generated/core/bodySerializer.gen.ts
 const serializeFormDataPair = (data, key, value) => {
@@ -1054,11 +1054,24 @@ var Admin = class {
 		});
 	}
 	/**
+	* Read a user's plan history
+	*
+	* A cursor page of the account's plan history, newest first, and the rung it is on now. Needs the `admin` role.
+	* The history is append-only, so this is the record of who put the account where and why — nothing edits or removes a line. `plan` at the top level is the same value every entitlement check resolves, so one response answers both "what plan is this?" and "how did it get there?".
+	*
+	*/
+	static listUserPlanHistory(options) {
+		return (options.client ?? client).get({
+			url: "/v1/admin/users/{user_id}/plan",
+			...options
+		});
+	}
+	/**
 	* Grant a user a plan
 	*
 	* Puts the account on a rung of the infra ladder. Needs the `admin` role.
-	* `PUT` because a user has exactly one plan: setting it twice leaves one subscription, never two (two rows for one payer is a state where "which plan is this?" has no answer).
-	* The rung is recorded and read back, and **nothing enforces it yet** — no route refuses a feature for the plan an account is on. Downgrading is the same call with a lower rung, and what becomes of resources a lower plan would not hold is a separate mechanism that is not built.
+	* `PUT` because an account is on exactly one rung at a time, but the change is **recorded rather than overwritten**: the plan history is append-only and the newest line is the account's plan. Setting the rung it already holds still writes a line — a re-confirmation is an act worth a record, and the `reason` given with it would otherwise have nowhere to go. Read the history back with `GET` on this path.
+	* The rung is what the feature gate and the resource caps resolve against. Downgrading is the same call with a lower rung; what becomes of resources a lower plan would not hold is a separate mechanism that is not built.
 	*
 	*/
 	static grantUserPlan(options) {
@@ -1088,7 +1101,8 @@ var Admin = class {
 	* Grant a user credit
 	*
 	* Writes one `granted` line to the account's credit ledger and answers with the balance it produced. Needs the `admin` role.
-	* The ledger is append-only and the balance is its sum — there is no balance to set and no line to edit or delete. A mistake is corrected by granting a **negative** `amount_usd`, which leaves the wrong line on the record beside the one that compensates for it. Granted credit is customer-acquisition cost rather than revenue, which is why each line records its kind and the operator who authorized it.
+	* The ledger is append-only and the balance is its sum — there is no balance to set and no line to edit or delete. A mistake is corrected by writing a **negative** `amount_usd`, which leaves the wrong line on the record beside the one that compensates for it.
+	* `kind` is required. Money received and credit given away report differently — one is revenue, the other customer-acquisition cost — so the line says which it is rather than defaulting to one of them.
 	* The balance this moves is not yet a ceiling anything enforces; turning it into one is a separate mechanism.
 	*
 	*/
@@ -5641,27 +5655,69 @@ const routes = {
 			"in": "body"
 		}]
 	},
+	"list-user-plan-history": {
+		serviceClass: "Admin",
+		operationId: "listUserPlanHistory",
+		description: "A cursor page of the account's plan history, newest first, and the rung it is on now. Needs the `admin` role. The history is append-only, so this is the record of who put the account where and why — nothing edits or removes a line. `plan` at the top level is the same value every entitlement check resolves, so one response answers both \"what plan is this?\" and \"how did it get there?\".",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/admin",
+		httpMethod: "get",
+		pathParams: ["user_id"],
+		queryParams: ["limit", "cursor"],
+		flags: [
+			{
+				"name": "user_id",
+				"description": "",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "limit",
+				"description": "Maximum items per page — an integer from 1 to 100 (default 20).",
+				"required": false,
+				"type": "integer",
+				"in": "query"
+			},
+			{
+				"name": "cursor",
+				"description": "The `next_cursor` of the previous page.",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			}
+		]
+	},
 	"grant-user-plan": {
 		serviceClass: "Admin",
 		operationId: "grantUserPlan",
-		description: "Puts the account on a rung of the infra ladder. Needs the `admin` role. `PUT` because a user has exactly one plan: setting it twice leaves one subscription, never two (two rows for one payer is a state where \"which plan is this?\" has no answer). The rung is recorded and read back, and **nothing enforces it yet** — no route refuses a feature for the plan an account is on. Downgrading is the same call with a lower rung, and what becomes of resources a lower plan would not hold is a separate mechanism that is not built.",
+		description: "Puts the account on a rung of the infra ladder. Needs the `admin` role. `PUT` because an account is on exactly one rung at a time, but the change is **recorded rather than overwritten**: the plan history is append-only and the newest line is the account's plan. Setting the rung it already holds still writes a line — a re-confirmation is an act worth a record, and the `reason` given with it would otherwise have nowhere to go. Read the history back with `GET` on this path. The rung is what the feature gate and the resource caps resolve against. Downgrading is the same call with a lower rung; what becomes of resources a lower plan would not hold is a separate mechanism that is not built.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/admin",
 		httpMethod: "put",
 		pathParams: ["user_id"],
 		queryParams: [],
-		flags: [{
-			"name": "user_id",
-			"description": "",
-			"required": true,
-			"type": "string",
-			"in": "path"
-		}, {
-			"name": "plan",
-			"description": "The rung to put the account on.",
-			"required": true,
-			"type": "string",
-			"in": "body"
-		}]
+		flags: [
+			{
+				"name": "user_id",
+				"description": "",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "plan",
+				"description": "The rung to put the account on.",
+				"required": true,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "reason",
+				"description": "Why the account was moved. Recorded on the line and never edited, so it is the only account of intent the history carries.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			}
+		]
 	},
 	"list-user-credits": {
 		serviceClass: "Admin",
@@ -5698,7 +5754,7 @@ const routes = {
 	"grant-user-credit": {
 		serviceClass: "Admin",
 		operationId: "grantUserCredit",
-		description: "Writes one `granted` line to the account's credit ledger and answers with the balance it produced. Needs the `admin` role. The ledger is append-only and the balance is its sum — there is no balance to set and no line to edit or delete. A mistake is corrected by granting a **negative** `amount_usd`, which leaves the wrong line on the record beside the one that compensates for it. Granted credit is customer-acquisition cost rather than revenue, which is why each line records its kind and the operator who authorized it. The balance this moves is not yet a ceiling anything enforces; turning it into one is a separate mechanism.",
+		description: "Writes one `granted` line to the account's credit ledger and answers with the balance it produced. Needs the `admin` role. The ledger is append-only and the balance is its sum — there is no balance to set and no line to edit or delete. A mistake is corrected by writing a **negative** `amount_usd`, which leaves the wrong line on the record beside the one that compensates for it. `kind` is required. Money received and credit given away report differently — one is revenue, the other customer-acquisition cost — so the line says which it is rather than defaulting to one of them. The balance this moves is not yet a ceiling anything enforces; turning it into one is a separate mechanism.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/admin",
 		httpMethod: "post",
 		pathParams: ["user_id"],
@@ -5711,6 +5767,13 @@ const routes = {
 				"type": "string",
 				"in": "path"
 			},
+			{
+				"name": "kind",
+				"description": "What this line is. `purchased` for money that arrived, `granted` for credit naturali gave away — the two report differently, so it is required rather than defaulted. `included` is not accepted here: a plan's monthly allowance is the billing cycle's to write.",
+				"required": true,
+				"type": "string",
+				"in": "body"
+			},
 			{
 				"name": "amount_usd",
 				"description": "US dollars to grant, rounded to the cent. Negative corrects an earlier grant; zero is refused, because a grant of nothing records no intent.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/cli",
-  "version": "0.94.0",
+  "version": "0.96.0",
   "description": "Command-line interface for the naturali.ai API, generated from its OpenAPI specs",
   "type": "module",
   "bin": {
@@ -30,7 +30,7 @@
     "tsx": "^4.23.1",
     "typescript": "~6.0.3",
     "vitest": "^4.1.10",
-    "@naturali/sdk": "0.94.0"
+    "@naturali/sdk": "0.96.0"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts",