@leaflow/sdk 0.30.0 → 0.32.0

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

@@ -38,8 +38,12 @@ export type CancelSubscriptionResult = operations["cancel-subscription"]["respon
 export type CancelSubscriptionQuery = operations["cancel-subscription"]["parameters"]["query"];
 /** `GET /account/v1/billing-accounts/{accountKey}/top-ups/{paymentId}` 成功时的响应体。 */
 export type ReadTopUpResult = operations["read-top-up"]["responses"][200]["content"]["application/json"];
-/** `POST /account/v1/billing-accounts/{accountKey}/card` 成功时的响应体。 */
-export type StartCardSetupResult = operations["start-card-setup"]["responses"][200]["content"]["application/json"];
+/** `GET /account/v1/billing-accounts/{accountKey}/payment-method` 成功时的响应体。 */
+export type ReadPaymentMethodResult = operations["read-payment-method"]["responses"][200]["content"]["application/json"];
+/** `POST /account/v1/billing-accounts/{accountKey}/payment-method` 成功时的响应体。 */
+export type StartPaymentMethodSetupResult = operations["start-payment-method-setup"]["responses"][200]["content"]["application/json"];
+/** `POST /account/v1/billing-accounts/{accountKey}/billing-portal` 成功时的响应体。 */
+export type StartBillingPortalResult = operations["start-billing-portal"]["responses"][200]["content"]["application/json"];
 /** `GET /account/v1/billing-accounts/{accountKey}/offers` 成功时的响应体。 */
 export type ListOffersResult = operations["list-offers"]["responses"][200]["content"]["application/json"];
 /** `POST /account/v1/billing-accounts/{accountKey}/offers/{offerKey}/purchase` 成功时的响应体。 */

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

@@ -363,32 +363,102 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/account/v1/billing-accounts/{accountKey}/card": {
+    "/account/v1/billing-accounts/{accountKey}/payment-method": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get?: never;
+        /**
+         * Whether this account can be charged
+         * @description Answers whether a payment method is on file, and nothing else.
+         *
+         *     ## It is a payment method, not a card
+         *
+         *     A card is one kind. Direct debit and the recurring-payment mandates offered by regional
+         *     wallets are others, and they occupy the same slot: something the provider can charge later
+         *     without the account holder present. Naming the slot after cards would put an assumption
+         *     into the contract that stops being true the day a second kind is accepted.
+         *
+         *     ## Why there is no brand, no last four digits, no expiry
+         *
+         *     Those would have to be read from the payment provider, and the two answers can disagree: a
+         *     method present at the provider that the billing engine has not recorded as the default is
+         *     exactly the state in which money cannot be collected — while a page built on the provider's
+         *     answer would be showing one. What matters here is whether the party that will run the
+         *     charge believes it can, so the answer comes from that party alone.
+         *
+         *     To see it, replace it, or remove it, open the billing portal.
+         *
+         *     ## Read this before offering a paid plan, not after
+         *
+         *     `ready` being false is why the engine refuses to start a paid subscription. Discovering it
+         *     at purchase time turns a missing payment method into a rejection whose wording is about
+         *     something else entirely.
+         *
+         *     An account that has never had one returns `ready: false`. That is the normal state of a
+         *     new account, not an error.
+         */
+        get: operations["read-payment-method"];
         put?: never;
         /**
-         * Add or replace the card on file
-         * @description Begins adding a card. Returns a URL to send the browser to; the card is entered there, on the
-         *     payment provider's own page, and **no card data ever reaches this platform**.
+         * Add or replace the payment method on file
+         * @description Begins adding a payment method. Returns a URL to send the browser to; the details are
+         *     entered there, on the payment provider's own page, and **no card data ever reaches this
+         *     platform**.
+         *
+         *     Which kinds are offered is the provider's decision, not this API's — a card today, a
+         *     wallet mandate or a direct debit wherever the provider supports charging one later without
+         *     the account holder present.
          *
          *     ## This is a prerequisite for buying a plan, not a convenience
          *
-         *     A plan is charged by invoice, and the invoice is collected from the card on file. The billing
-         *     a subscription cannot start for an account that has none — so "add a card, then
+         *     A plan is charged by invoice, and the invoice is collected from the method on file. A
+         *     subscription cannot start for an account that has none — so "add a payment method, then
          *     buy" is the order the system requires, not a flow that was chosen.
          *
          *     It is *not* a prerequisite for topping up: a top-up collects the money there and then.
          *
-         *     Replacing the card uses the same operation. The new card becomes the default and the old one
-         *     stops being used; nothing else about the account changes.
+         *     Replacing uses the same operation. The new method becomes the default and the old one stops
+         *     being used; nothing else about the account changes.
          */
-        post: operations["start-card-setup"];
+        post: operations["start-payment-method-setup"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/account/v1/billing-accounts/{accountKey}/billing-portal": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Open the hosted billing portal
+         * @description Returns a URL to the payment provider's own portal, where the card can be replaced or
+         *     removed, the billing address changed, and past invoices downloaded.
+         *
+         *     ## Why replacing a card is not a form on this platform
+         *
+         *     A form would mean a card number field, and no card data ever reaches this platform. The
+         *     portal moves the whole interaction to the provider; only a session URL comes back.
+         *
+         *     ## Something has to be able to replace an expiring card
+         *
+         *     Cards expire. Once one does, the invoices for a plan stop being collectable, dunning runs
+         *     out, and the projects paid for by this account are suspended for non-payment. Without this
+         *     operation the account holder watches that happen with nowhere to fix it — adding a card
+         *     does not help, since that operation only makes sense when there is none.
+         *
+         *     The URL is single-use and expires. Do not store it.
+         */
+        post: operations["start-billing-portal"];
         delete?: never;
         options?: never;
         head?: never;
@@ -732,13 +802,43 @@ export interface components {
              */
             offer_key?: string;
         };
-        CardSetupSession: {
+        PaymentMethodSetupSession: {
+            /**
+             * Format: uri
+             * @description Send the browser here. It expires, so do not store it
+             */
+            url: string;
+        };
+        BillingPortalSession: {
             /**
              * Format: uri
              * @description Send the browser here. It expires, so do not store it
              */
             url: string;
         };
+        /**
+         * @description Whether money can be collected from this account later, without the account holder present.
+         *
+         *     Deliberately not called a card: a card is one kind of payment method, and direct debit and
+         *     the recurring mandates offered by regional wallets occupy the same slot.
+         */
+        PaymentMethod: {
+            /**
+             * @description True when the billing engine holds a default payment method for this account and can
+             *     therefore collect an invoice.
+             *
+             *     This is the precondition for a paid plan. While it is false, starting a paid
+             *     subscription is refused, and the refusal is about billing setup rather than about the
+             *     plan — so check this first and say what is actually missing.
+             *
+             *     It says nothing about which kind is on file. To show or change that, send the account
+             *     holder to the billing portal.
+             *
+             *     A free plan does not require it, which is what allows a new account to be placed on the
+             *     default tier before anyone has entered a card.
+             */
+            ready: boolean;
+        };
         TopUpSession: {
             /**
              * @description Identifies this attempt. Quote it in a support conversation — it is what ties the payment
@@ -1441,7 +1541,77 @@ export interface operations {
             };
         };
     };
-    "start-card-setup": {
+    "read-payment-method": {
+        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"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PaymentMethod"];
+                };
+            };
+            /** @description Error */
+            default: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    "start-payment-method-setup": {
+        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"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PaymentMethodSetupSession"];
+                };
+            };
+            /** @description Error */
+            default: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    "start-billing-portal": {
         parameters: {
             query?: never;
             header?: never;
@@ -1462,7 +1632,7 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["CardSetupSession"];
+                    "application/json": components["schemas"]["BillingPortalSession"];
                 };
             };
             /** @description Error */

package/package.json

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