@runlot/api 0.1.0-rc.210 → 0.1.0-rc.211

package/dist/schema.d.ts

@@ -3762,12 +3762,19 @@ export interface paths {
          *     charge Y to the saved card, at most N times a day" and takes a checkbox, because card network
          *     rules require prior consent for off-session charges.
          *
-         *     The server checks three things: whether a payment method is saved (409 if not), whether the
-         *     amount is one of the offered top-up amounts, and whether the threshold is **greater than 0 and
-         *     smaller than the top-up amount**. A threshold of 0 makes every automatic charge fail with 402,
+         *     The server checks: whether a payment method is saved (409 if not), whether the amount is one
+         *     of the offered top-up amounts, whether the threshold is **greater than 0 and smaller than the
+         *     top-up amount**, and `perDay` — the most top-ups a day, a whole number of at least 1 or `null`
+         *     for unlimited (5 when left out). Unlimited has no daily count: charges go on for as long as
+         *     the balance keeps falling below the threshold, one at a time. A threshold of 0 makes every automatic charge fail with 402,
          *     and a threshold at or above the top-up amount leaves the balance still below the threshold
          *     after a top-up, so it would keep topping up until it hit the daily cap.
          *
+         *     **A refused charge turns it off.** When the payment provider refuses an automatic charge — a
+         *     declined card, no valid saved card, or a provider setting that refuses off-session charges —
+         *     auto top-up is turned off at once, `autoTopupStopped` on `getAICredit` says when and why, and
+         *     the org's admins get `ai_autotopup_disabled`. Saving this setting again, on or off, clears it.
+         *
          *     Requires admin. Audited as `ai.autotopup.on` / `ai.autotopup.off`.
          */
         put: operations["setAIAutoTopup"];
@@ -4641,6 +4648,119 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/orgs/{orgSlug}/billing/payment-methods": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                orgSlug: components["parameters"]["OrgSlug"];
+            };
+            cookie?: never;
+        };
+        /**
+         * The organization's saved cards, read from Polar
+         * @description The cards saved on the organization's Polar customer, with brand, last four digits, expiry and
+         *     which one is the **default** — the card automatic charges (AI credit top-up, Pro overage,
+         *     domain renewal) are made to. Read live from Polar on every request: runlot stores no card data.
+         *
+         *     `customer: false` means the organization has no billing account with Polar yet;
+         *     `addBillingPaymentMethod` makes one. A one-time AI credit top-up does not save its card — add
+         *     cards with `addBillingPaymentMethod`. Requires admin.
+         */
+        get: operations["getBillingPaymentMethods"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/orgs/{orgSlug}/billing/payment-methods/default": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                orgSlug: components["parameters"]["OrgSlug"];
+            };
+            cookie?: never;
+        };
+        get?: never;
+        /**
+         * Makes a saved card the default
+         * @description Sets Polar's default payment method for the organization's customer. Automatic charges and the
+         *     Pro subscription use the default. `id` is one of the organization's own saved cards
+         *     (`getBillingPaymentMethods`); an expired card is refused with 409 `card_expired`. Requires
+         *     admin. Audited as `billing.card.default`.
+         */
+        put: operations["setBillingDefaultPaymentMethod"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/orgs/{orgSlug}/billing/payment-methods/add": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                orgSlug: components["parameters"]["OrgSlug"];
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Opens Polar's page to add a card
+         * @description Returns a one-time `url` for Polar's hosted customer portal, where the card is entered — the card
+         *     never passes through runlot. The browser comes back to `returnTo` (under this deployment's public
+         *     URL), and the screen reads `getBillingPaymentMethods` again.
+         *
+         *     An organization with no billing account yet (a free organization that never paid, or a Pro plan
+         *     provided by Runlot) gets one made with the signed-in admin's email; when that email already has
+         *     one, the organization shares it. Requires admin.
+         */
+        post: operations["addBillingPaymentMethod"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/orgs/{orgSlug}/billing/payment-methods/remove": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                orgSlug: components["parameters"]["OrgSlug"];
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Removes a saved card
+         * @description Removes a saved card from the organization's Polar customer. The card's `id` is in the body,
+         *     not the URL, so it never appears in a request log.
+         *
+         *     - A paid **Pro** organization always keeps a valid (unexpired) card: removing its last one is
+         *       refused with 409 `replacement_required`. Add the replacement first.
+         *     - While **auto top-up** is on, the last valid card cannot be removed either: 409
+         *       `autotopup_needs_card`. Turn auto top-up off first, or add another card.
+         *     - Removing the **default** makes another valid card the default first; `promotedDefault` is then
+         *       true and `methods` shows which one.
+         *
+         *     Requires admin. Audited as `billing.card.remove`.
+         */
+        post: operations["removeBillingPaymentMethod"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/orgs/{orgSlug}/billing/cancel": {
         parameters: {
             query?: never;
@@ -13254,6 +13374,52 @@ export interface components {
             belowMicroCents: number;
             /** Format: int64 */
             microCents: number;
+            /** @description The most automatic top-ups a day the organization agreed to; null is unlimited */
+            perDay: number | null;
+        };
+        /**
+         * @description Present when auto top-up is off because the payment provider refused a charge (not when an admin
+         *     turned it off). It stays until auto top-up is saved again. `provider_setting` is the payment
+         *     provider refusing automatic charges because of a setting on runlot's side — not the card;
+         *     manual top-up still works. `action_required` is a charge the bank wanted the cardholder to
+         *     confirm (3-D Secure), which cannot happen with nobody present. `billing_address` is an
+         *     incomplete billing address, which the provider needs to calculate tax.
+         */
+        AIAutoTopupStopped: {
+            /** Format: date-time */
+            at: string;
+            /** @enum {string} */
+            reason: "provider_setting" | "card_declined" | "action_required" | "no_card" | "billing_address" | "charge_refused";
+        };
+        /** @description One saved card, as Polar reports it. Nothing here is stored by runlot. */
+        PaymentMethod: {
+            /** @description Polar's id, to name this card in a default change or a removal */
+            id: string;
+            /** @description `card`, `kr_card`, or another payment method type */
+            type: string;
+            /** @example visa */
+            brand?: string;
+            /** @example 4242 */
+            last4?: string;
+            expMonth?: number;
+            expYear?: number;
+            /** @description e.g. apple_pay, when the card came from a wallet */
+            wallet?: string;
+            /** @description The card automatic charges are made to */
+            isDefault: boolean;
+            /** @description Past its expiry month — it cannot be charged */
+            expired: boolean;
+        };
+        PaymentMethodList: {
+            /** @description Whether the billing address is enough for the payment provider to calculate tax — automatic charges need it as well as a card. Completed on the provider's page (`addBillingPaymentMethod`) */
+            billingAddressComplete: boolean;
+            /** @description false means the organization has no billing account with Polar yet — the first checkout creates it */
+            customer: boolean;
+            methods: components["schemas"]["PaymentMethod"][];
+        };
+        PaymentMethodChange: components["schemas"]["PaymentMethodList"] & {
+            /** @description The removed card was the default, and another card became it */
+            promotedDefault: boolean;
         };
         AICredit: {
             /** @description false means AI credit is not available here — the top-up endpoints answer 501 */
@@ -13278,9 +13444,10 @@ export interface components {
             /** @description When false, auto top-up cannot be turned on — your first top-up is what saves the card */
             hasPaymentMethod: boolean;
             autoTopup?: components["schemas"]["AIAutoTopup"];
+            autoTopupStopped?: components["schemas"]["AIAutoTopupStopped"];
             autoTopupsToday: number;
-            /** @description the most automatic top-ups that can run in one day */
-            autoTopupPerDay: number;
+            /** @description The most automatic top-ups in one day — the organization's choice, 5 until it chooses. Null is unlimited */
+            autoTopupPerDay: number | null;
         };
         StorageObject: {
             /**
@@ -21645,6 +21812,8 @@ export interface operations {
                     belowMicroCents?: number;
                     /** Format: int64 */
                     microCents?: number;
+                    /** @description The most automatic top-ups a day, at least 1; null for unlimited. Left out, it is 5 */
+                    perDay?: number | null;
                 };
             };
         };
@@ -21677,7 +21846,7 @@ export interface operations {
                 };
             };
             403: components["responses"]["Forbidden"];
-            /** @description `no_payment_method` — there is no saved card. Top up manually once first */
+            /** @description `no_payment_method` — the org has no valid saved card (read from Polar); `billing_address_required` — its billing address is incomplete. Fix either on the billing page first */
             409: {
                 headers: {
                     [name: string]: unknown;
@@ -23326,6 +23495,202 @@ export interface operations {
             };
         };
     };
+    getBillingPaymentMethods: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                orgSlug: components["parameters"]["OrgSlug"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Saved cards */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PaymentMethodList"];
+                };
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            /** @description `billing_off` */
+            501: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description `billing_unavailable` */
+            502: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    setBillingDefaultPaymentMethod: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                orgSlug: components["parameters"]["OrgSlug"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    id: string;
+                };
+            };
+        };
+        responses: {
+            /** @description The cards after the change */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PaymentMethodChange"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            /** @description `card_expired` */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description `billing_off` */
+            501: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description `billing_unavailable` */
+            502: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    addBillingPaymentMethod: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                orgSlug: components["parameters"]["OrgSlug"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** Format: uri */
+                    returnTo: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Portal session */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** Format: uri */
+                        url: string;
+                    };
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            403: components["responses"]["Forbidden"];
+            /** @description `email_required` — the signed-in account has no email address */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description `billing_off` */
+            501: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description `billing_unavailable` */
+            502: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    removeBillingPaymentMethod: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                orgSlug: components["parameters"]["OrgSlug"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    id: string;
+                };
+            };
+        };
+        responses: {
+            /** @description The cards after the removal */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PaymentMethodChange"];
+                };
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            /** @description `replacement_required` or `autotopup_needs_card` */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description `billing_off` */
+            501: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description `billing_unavailable` */
+            502: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     cancelBilling: {
         parameters: {
             query?: never;