@leaflow/sdk 0.46.0 → 0.48.0

package/dist/billing/v1/index.d.ts

@@ -30,10 +30,14 @@ export type StartTopUpResult = operations["start-top-up"]["responses"][200]["con
 export type StartTopUpBody = NonNullable<operations["start-top-up"]["requestBody"]>["content"]["application/json"];
 /** `GET /account/v1/billing-accounts/{accountKey}/charges` 成功时的响应体。 */
 export type ListChargesResult = operations["list-charges"]["responses"][200]["content"]["application/json"];
+/** `GET /account/v1/billing-accounts/{accountKey}/charges/{chargeId}/usage` 成功时的响应体。 */
+export type GetChargeUsageResult = operations["get-charge-usage"]["responses"][200]["content"]["application/json"];
 /** `GET /account/v1/billing-accounts/{accountKey}/invoices` 成功时的响应体。 */
 export type ListInvoicesResult = operations["list-invoices"]["responses"][200]["content"]["application/json"];
 /** `GET /account/v1/billing-accounts/{accountKey}/invoices/{invoiceId}` 成功时的响应体。 */
 export type GetInvoiceResult = operations["get-invoice"]["responses"][200]["content"]["application/json"];
+/** `GET /account/v1/projects/{projectId}/billing-account` 成功时的响应体。 */
+export type ReadProjectBillingAccountResult = operations["read-project-billing-account"]["responses"][200]["content"]["application/json"];
 /** `POST /account/v1/projects/{projectId}/quote` 成功时的响应体。 */
 export type QuoteProjectUsageResult = operations["quote-project-usage"]["responses"][200]["content"]["application/json"];
 /** `POST /account/v1/projects/{projectId}/quote` 的请求体。 */

package/dist/billing/v1/schema.d.ts

@@ -282,6 +282,63 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/account/v1/billing-accounts/{accountKey}/charges/{chargeId}/usage": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * What produced this charge
+         * @description Splits one charge back into the projects that produced it, and lists the resources it could
+         *     have come from.
+         *
+         *     ## Why this is not a field on the charge
+         *
+         *     A charge has no project, and that is not an omission: the billing subject is the **account**,
+         *     and the project is a dimension on each usage event. When three of an account's projects use
+         *     the same product, their usage aggregates into one charge — that charge genuinely spans three
+         *     projects, and stamping any single project id on it would be wrong.
+         *
+         *     A split is also more useful than a label would be: it gives proportions, and proportions are
+         *     what decide which project's resources to switch off.
+         *
+         *     ## The quantity here is what was reported, not what was billed
+         *
+         *     Conversion (machine-seconds to machine-hours) happens on the pricing side, and the engine
+         *     does not echo `unit_config` back on a charge. So this figure times the unit price does not
+         *     equal the total — a step is missing in between, and that step only becomes visible on the
+         *     invoice, where the whole pricing configuration is frozen onto each line.
+         *
+         *     Reported quantity is still the right number for "which project is burning this", which is
+         *     what the split is for.
+         *
+         *     ## The resource list says which, not how much
+         *
+         *     Usage events carry no resource id — it is not a grouping dimension, and making it one would
+         *     mean one time series per machine per hour. So the engine cannot attribute a charge to a
+         *     machine. What it can be attributed to is a product, and which resources of that product
+         *     exist is something billing knows from its own records.
+         *
+         *     Destroyed resources are listed too: this period's charge includes the part they ran for.
+         *     Leaving them out is what makes the numbers fail to add up for someone who deleted a machine
+         *     mid-month — which is exactly the case they are trying to explain.
+         *
+         *     ## A flat fee answers with an empty split
+         *
+         *     There is no meter behind it, so there is nothing to attribute. That is an answer, not an
+         *     error.
+         */
+        get: operations["get-charge-usage"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/account/v1/billing-accounts/{accountKey}/invoices": {
         parameters: {
             query?: never;
@@ -326,6 +383,49 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/account/v1/projects/{projectId}/billing-account": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Which account pays for this project
+         * @description The account a project's resources are charged to, resolved from the project rather than
+         *     guessed.
+         *
+         *     ## Why a console needs this
+         *
+         *     Everything in a console happens inside a project, while billing accounts belong to a person —
+         *     and a person can have many. Showing "the first one" next to a sentence like *you are
+         *     overdrawn, new resources will be refused* pairs one account's balance with another account's
+         *     rule. Both directions are wrong and one of them is silent: the figures look healthy while
+         *     creating anything is refused, and the refusal names a reason the page just contradicted.
+         *
+         *     ## Being a member is enough to ask, but not to see the money
+         *
+         *     The answer is the account's identity, not its balance. A project's members are not
+         *     necessarily the people paying for it — a company account can pay for a project someone else
+         *     works in — and their balance is not those members' business. Whoever owns the account reads
+         *     the figures from the balance route as before; `owned_by_me` says which case this is, so a
+         *     page can tell "you are overdrawn" apart from "ask whoever pays for this project".
+         *
+         *     ## A project with no account is a normal state, and it answers 404
+         *
+         *     A project nobody has bound yet cannot create resources at all — admission refuses it. That is
+         *     worth saying plainly ("this project has no billing account, bind one") rather than falling
+         *     back to some other account of theirs, which is how the wrong-account problem started.
+         */
+        get: operations["read-project-billing-account"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/account/v1/projects/{projectId}/quote": {
         parameters: {
             query?: never;
@@ -1231,6 +1331,19 @@ export interface components {
              */
             available: string;
         };
+        /** @description The account a project's resources are charged to */
+        ProjectBillingAccount: {
+            account_key: string;
+            project_id: string;
+            display_name: string;
+            currency: components["schemas"]["Currency"];
+            /**
+             * @description Whether the caller owns this account, and therefore whether the balance routes will
+             *     answer for it. False means someone else pays for this project: the figures are theirs,
+             *     not the caller's, and a page should say so rather than showing nothing.
+             */
+            owned_by_me: boolean;
+        };
         /** @description Which account pays for which project, as it stands once the request has been applied */
         ProjectBinding: {
             account_key: string;
@@ -1315,6 +1428,93 @@ export interface components {
              *     just started as zero
              */
             total: string;
+            /**
+             * @description Which meter it is for, when the charge came from usage. A hash, not something to show —
+             *     it is here so two rows can be told apart programmatically and so support can line a row
+             *     up with the catalogue.
+             */
+            feature_key?: string;
+            /**
+             * @description Whether this figure moves. A usage charge climbs through the period; a flat fee does not.
+             *     Without it, the same number on two refreshes could mean "nobody used it" or "it never
+             *     moves", and those need different next steps.
+             * @enum {string}
+             */
+            type: "usage_based" | "flat_fee";
+            /**
+             * Format: date-time
+             * @description Start of the service period this charge covers.
+             *
+             *     This is what tells two same-named rows apart. Something billed by the hour produces
+             *     hundreds of identically named charges in a month, and a list carrying only a name and an
+             *     amount shows them as a wall of duplicates — which is what it looks like today.
+             */
+            period_from: string;
+            /**
+             * Format: date-time
+             * @description End of the service period this charge covers.
+             */
+            period_to: string;
+            /**
+             * @description How much of this charge was covered by credit, as a decimal string.
+             *
+             *     It is the answer to "I have a balance, why am I still being charged". Without it the
+             *     customer sees a number that disagrees with what they expected and the only thing that
+             *     explains it is on our side.
+             */
+            credits?: string;
+            /**
+             * @description How much was taken off by a discount, as a decimal string. A usage allowance (the first N
+             *     units free) lands here too.
+             */
+            discounts?: string;
+            /** @description Free text from the charge, usually empty. Set on charges raised by hand. */
+            description?: string;
+            /**
+             * @description What one unit costs, as a decimal string. Absent when the line has no single unit price
+             *     — a flat fee, or a tiered price whose rate changes with volume.
+             *
+             *     The conversion between reported and billed quantity is deliberately not here: the engine
+             *     does not echo it back on a charge, only on an invoice line. So a charge answers "what
+             *     does a unit cost", and an invoice answers "how the total was reached".
+             */
+            unit_price?: string;
+        };
+        /** @description What produced one charge */
+        ChargeUsage: {
+            charge_id: string;
+            /**
+             * @description Total reported quantity for the period, as a decimal string. Empty on a charge with no
+             *     meter behind it.
+             *
+             *     Reported, not billed: see the route's description.
+             */
+            quantity: string;
+            /**
+             * @description The same quantity split by project. Empty when the charge has no meter behind it — a
+             *     flat fee has nothing to attribute.
+             */
+            by_project: components["schemas"]["ProjectUsage"][];
+            /**
+             * @description Resources of this product in the account's projects — candidates for what produced the
+             *     charge, not a per-resource breakdown. Absent when billing could not look them up; the
+             *     charge itself is still answered.
+             */
+            resources?: components["schemas"]["ChargeResource"][];
+        };
+        ProjectUsage: {
+            project_id: string;
+            /** @description Decimal string. */
+            quantity: string;
+        };
+        ChargeResource: {
+            project_id: string;
+            /** @description Which service holds it, and therefore which console manages it. */
+            service: string;
+            product_id: string;
+            resource_id: string;
+            /** @enum {string} */
+            state: "pending" | "active" | "suspended" | "terminated";
         };
         ChargeList: {
             currency: components["schemas"]["Currency"];
@@ -1354,6 +1554,33 @@ export interface components {
             /** @description Before discounts and credit */
             amount: string;
             discounts_total?: string;
+            /**
+             * @description The billed quantity for this line, as a decimal string — after conversion. A machine
+             *     billed by the hour reports machine-seconds; this is machine-hours.
+             *
+             *     It comes from the line's detailed segments summed together: the engine splits a line
+             *     into segments (different cost categories, different sub-periods) and the quantity lives
+             *     on those.
+             */
+            quantity?: string;
+            /**
+             * @description What one unit cost, as a decimal string, frozen at billing time. Absent on a flat fee,
+             *     whose amount is the amount, and on tiered prices, whose rate changes with volume.
+             */
+            unit_price?: string;
+            /**
+             * @description How reported quantity became billed quantity — 3600 for a machine billed by the hour
+             *     from machine-seconds, 1000000 for a price per million tokens.
+             *
+             *     Without it, `quantity` disagrees with what the customer remembers doing, by whole orders
+             *     of magnitude, and there is nothing on the page that explains the gap.
+             */
+            conversion_factor?: string;
+            /**
+             * @description What was done with the factor.
+             * @enum {string}
+             */
+            conversion_operation?: "divide" | "multiply";
             /** @description How much of this line credit covered */
             credits_total?: string;
             total: string;
@@ -1888,6 +2115,43 @@ export interface operations {
             };
         };
     };
+    "get-charge-usage": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /**
+                 * @description The account's key, of the form `u_<user_id>_<seq>`. Ownership is stated by the key itself,
+                 *     which is why the key is what addresses the account.
+                 */
+                accountKey: components["parameters"]["AccountKey"];
+                /** @description Which charge, from the charges list */
+                chargeId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ChargeUsage"];
+                };
+            };
+            /** @description Error */
+            default: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     "list-invoices": {
         parameters: {
             query?: never;
@@ -1959,6 +2223,38 @@ export interface operations {
             };
         };
     };
+    "read-project-billing-account": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description The project being worked in */
+                projectId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProjectBillingAccount"];
+                };
+            };
+            /** @description Error */
+            default: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     "quote-project-usage": {
         parameters: {
             query?: never;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leaflow/sdk",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "description": "Leaflow 平台 API 的 TypeScript SDK",
   "license": "MIT",
   "repository": {