@archildata/api-types 0.0.63 → 0.0.65

package/index.d.ts

@@ -4,6 +4,66 @@
  */
 
 export interface paths {
+    "/api/billing/subscription": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get the subscription's state and the actions it allows
+         * @description Returns the selected account's subscription state and available actions. Accounts that share billing also share subscription and open-invoice information.
+         */
+        get: operations["getBillingSubscription"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/billing/usage": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get metered usage over a window
+         * @description Returns what the account's meters recorded over a window, for the window as a whole and per interval, in each meter's own unit (vCPU-hours, GiB-hours, GiB-months, calls) with no prices applied. Usage reaches billing once per reporter interval from every region, so an interval's figures can still grow for a few minutes after it ends, longer if a region's reporter is behind. The default window is the seven days (hourly: 24 hours) up to now; a window may be at most 31 days, and is widened to whole intervals.
+         */
+        get: operations["getBillingUsage"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/billing/costs": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get the cost of metered usage over a window
+         * @description Returns the same usage as `/api/billing/usage` priced at the account's rates, for the window and per interval and meter, before the plan's included credits and base price: the cost of what was used, not what will be invoiced. Summed over the billing period it is the usage line of the invoice; `/api/billing/summary` applies the plan's base price and included credits on top. Money is in integer cents. On a plan that prices no usage, `priced` is false and every cost is zero.
+         */
+        get: operations["getBillingCosts"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/billing/summary": {
         parameters: {
             query?: never;
@@ -12,8 +72,8 @@ export interface paths {
             cookie?: never;
         };
         /**
-         * Get billing summary
-         * @description Returns the selected account's billing state and available actions. Accounts that share billing also share subscription and open-invoice information.
+         * Get a billing period's statement as a sum
+         * @description Returns a billing period's statement as a sum: `meteredCostCents`, the period's usage at the account's rates with a breakdown by meter; `adjustments`, the lines the plan applies (the included credits taken off, the base price added); and `billedCostCents`, what they come to, which is what the period invoices or would if it ended now. Also the account's standing on the plan's credit pool and, for the current period, a projection to its end at the recent daily pace. A past period's lines are read from the invoices issued for it. The only billing route where the plan's base price and included credits enter. Money is in integer cents. On a plan that prices no usage, `priced` is false and the amounts are zero.
          */
         get: operations["getBillingSummary"];
         put?: never;
@@ -325,7 +385,8 @@ export interface paths {
         };
         /**
          * Get the account credit balance
-         * @description Returns the customer credit balance and one page of balance transactions, newest first, such as credit notes applied to the balance. Pass nextCursor as cursor to continue.
+         * @deprecated
+         * @description Deprecated: the plan's credit pool on `/api/billing/summary` replaces the Stripe customer balance, and credit notes are on each invoice under `/api/billing/invoices/{invoiceID}`; this route goes once the console no longer calls it. Returns the customer credit balance and one page of balance transactions, newest first, such as credit notes applied to the balance. Pass nextCursor as cursor to continue.
          */
         get: operations["getBillingCredits"];
         put?: never;
@@ -1195,6 +1256,239 @@ export interface components {
              */
             end: number;
         };
+        BillingUsageQuantity: {
+            /** @description In the meter's own unit. */
+            quantity: number;
+            /** @description vCPU-hours, GiB-hours, GiB-months or calls. */
+            unit: string;
+        };
+        BillingUsageInterval: {
+            /**
+             * Format: int64
+             * @description Unix timestamp in seconds.
+             */
+            start: number;
+            /**
+             * Format: int64
+             * @description Unix timestamp in seconds, exclusive.
+             */
+            end: number;
+            /** @description Quantity per meter in the interval, keyed by feature id. */
+            features: {
+                [key: string]: components["schemas"]["BillingUsageQuantity"];
+            };
+        };
+        /** @description The window as a whole, the summary the intervals break down. */
+        BillingUsageWindow: {
+            /**
+             * Format: int64
+             * @description Unix timestamp in seconds.
+             */
+            start: number;
+            /**
+             * Format: int64
+             * @description Unix timestamp in seconds, exclusive.
+             */
+            end: number;
+            /** @description Quantity per meter over the window, keyed by feature id; the intervals' sums. */
+            features: {
+                [key: string]: components["schemas"]["BillingUsageQuantity"];
+            };
+        };
+        BillingUsage: {
+            /** @enum {string} */
+            granularity: "1d" | "1h";
+            timezone: string;
+            window: components["schemas"]["BillingUsageWindow"];
+            /** @description Newest first, each the window's share of one interval. Intervals after now are left out. */
+            intervals: components["schemas"]["BillingUsageInterval"][];
+        };
+        ApiResponse_BillingUsage: {
+            success: boolean;
+            data: components["schemas"]["BillingUsage"];
+        };
+        BillingFeatureCost: {
+            /** @description In the meter's own unit. */
+            quantity: number;
+            unit: string;
+            /**
+             * Format: int64
+             * @description Quantity at the account's rate, in integer cents.
+             */
+            costCents: number;
+        };
+        BillingCostInterval: {
+            /**
+             * Format: int64
+             * @description Unix timestamp in seconds.
+             */
+            start: number;
+            /**
+             * Format: int64
+             * @description Unix timestamp in seconds, exclusive.
+             */
+            end: number;
+            /**
+             * Format: int64
+             * @description The interval's usage at the account's rates, in integer cents; the sum of `features`.
+             */
+            costCents: number;
+            /** @description Quantity and cost per meter in the interval, keyed by feature id. */
+            features: {
+                [key: string]: components["schemas"]["BillingFeatureCost"];
+            };
+        };
+        /** @description The window as a whole, the summary the intervals break down. Its figures are priced over the whole span and rounded once per meter, so they are the same at any granularity and agree with `summary` over the billing period; the intervals, each rounded on its own, can add up to a little less. */
+        BillingCostWindow: {
+            /**
+             * Format: int64
+             * @description Unix timestamp in seconds.
+             */
+            start: number;
+            /**
+             * Format: int64
+             * @description Unix timestamp in seconds, exclusive.
+             */
+            end: number;
+            /**
+             * Format: int64
+             * @description Usage over the window at the account's rates, in integer cents.
+             */
+            costCents: number;
+            /** @description Quantity and cost per meter over the window, keyed by feature id. */
+            features: {
+                [key: string]: components["schemas"]["BillingFeatureCost"];
+            };
+        };
+        BillingCosts: {
+            /** @enum {string} */
+            granularity: "1d" | "1h";
+            timezone: string;
+            currency: string;
+            /** @description False when the plan prices no usage; every cost is then zero. */
+            priced: boolean;
+            /** @description Cost of one unit of each meter, in cents per unit as a decimal (a rate can be below a cent), keyed by feature id. */
+            ratesCentsPerUnit: {
+                [key: string]: number;
+            };
+            window: components["schemas"]["BillingCostWindow"];
+            /** @description Newest first, each the window's share of one interval. Intervals after now are left out. */
+            intervals: components["schemas"]["BillingCostInterval"][];
+            /** @description The current billing period, which `/api/billing/summary` sums; absent on a plan without one. */
+            billingPeriod?: components["schemas"]["BillingPeriod"];
+        };
+        ApiResponse_BillingCosts: {
+            success: boolean;
+            data: components["schemas"]["BillingCosts"];
+        };
+        BillingSummaryPlan: {
+            /** @description The plan id, such as `enterprise`. */
+            id: string;
+            /**
+             * Format: int64
+             * @description The recurring fee per billing period, in integer cents.
+             */
+            basePriceCents: number;
+            /** @description Credits the plan grants each period. */
+            includedCredits: number;
+            /**
+             * Format: int64
+             * @description What each credit past the granted ones costs, in integer cents.
+             */
+            overagePricePerCreditCents: number;
+        };
+        BillingCreditStanding: {
+            /** @description Credits the period grants. */
+            granted: number;
+            /** @description Credits drawn so far, rounded to two decimals. */
+            used: number;
+            /** @description Credits left before overage, rounded to two decimals. */
+            remaining: number;
+        };
+        BillingAdjustment: {
+            /**
+             * @description Which plan term the line applies; the key to branch on. `other` is a line the processor billed on a past period that is neither, such as a proration, carried with its own `name`.
+             * @enum {string}
+             */
+            type: "included_credits" | "base_price" | "other";
+            /** @description The line's label, such as `Included credits` or `Base price`. */
+            name: string;
+            /**
+             * Format: int64
+             * @description In integer cents; negative for a discount.
+             */
+            amountCents: number;
+        };
+        BillingSummaryProjection: {
+            /**
+             * Format: int64
+             * @description Usage at the account's rates the period is projected to reach, in integer cents.
+             */
+            meteredCostCents: number;
+            /**
+             * Format: int64
+             * @description What that usage would invoice, in integer cents.
+             */
+            billedCostCents: number;
+            /**
+             * Format: int64
+             * @description The pace the projection extends, in integer cents per day; `meteredCostCents` so far plus `dailyRateCents` × `daysRemaining`.
+             */
+            dailyRateCents: number;
+            /**
+             * Format: int64
+             * @description Unix timestamp in seconds; the pace is the mean over the elapsed UTC days from here to `paceEnd`, the last ones before now inside the period.
+             */
+            paceStart: number;
+            /**
+             * Format: int64
+             * @description Unix timestamp in seconds, exclusive.
+             */
+            paceEnd: number;
+            /** @description Days from now to the period end. */
+            daysRemaining: number;
+        };
+        BillingIssuedInvoice: {
+            id: string;
+            /** @description open, paid or uncollectible. */
+            status: string;
+            /** @description The invoice as the billing processor hosts it. */
+            hostedInvoiceUrl?: string;
+        };
+        BillingSummary: {
+            /** @description False when the plan prices no usage; the quantities are still reported, the amounts are zero, and `credit` and `projected` are absent. */
+            priced: boolean;
+            currency: string;
+            /** @description The period read; the UTC calendar month for an account without a billing cycle. */
+            billingPeriod: components["schemas"]["BillingPeriod"];
+            plan: components["schemas"]["BillingSummaryPlan"];
+            /** @description Billing's own standing on the plan's credit pool, in credits, on the current period only (a past period's is not kept; its `adjustments` show the credits drawn). `used` equals `meteredCostCents` at the overage price unless a usage report arrived after a period boundary, which billing credits to the period it arrived in. */
+            credit?: components["schemas"]["BillingCreditStanding"];
+            /**
+             * Format: int64
+             * @description The period's usage at the account's rates, before any adjustment, in integer cents; the sum of `meteredCostBreakdown`. On a past period, as its invoice billed it.
+             */
+            meteredCostCents: number;
+            /** @description The metered cost by meter, with quantities, keyed by feature id. Sums to `meteredCostCents`. */
+            meteredCostBreakdown: {
+                [key: string]: components["schemas"]["BillingFeatureCost"];
+            };
+            /** @description The lines between `meteredCostCents` and `billedCostCents`, which sum to their difference. */
+            adjustments: components["schemas"]["BillingAdjustment"][];
+            /**
+             * Format: int64
+             * @description What the period invoices, or would if it ended now; `meteredCostCents` plus the adjustments, to the cent.
+             */
+            billedCostCents: number;
+            /** @description The period end at the recent daily pace; absent for a past period or without an elapsed day of usage. */
+            projected?: components["schemas"]["BillingSummaryProjection"];
+            /** @description On a past period, the invoices its lines were read from, oldest first; the base price is billed as a period starts and the usage as it ends. Absent on the current period, which is not invoiced yet. */
+            invoices?: components["schemas"]["BillingIssuedInvoice"][];
+        };
+        ApiResponse_BillingSummary: {
+            success: boolean;
+            data: components["schemas"]["BillingSummary"];
+        };
         BillingScheduledChange: {
             /** @enum {string} */
             type: "schedule_transition" | "plan_change";
@@ -1224,7 +1518,7 @@ export interface components {
             /** @description Unfinished purchase or plan change awaiting payment; resume it with GET /api/billing/operations/{operationID}. */
             pendingOperationId?: string;
         };
-        BillingSummaryActions: {
+        BillingSubscriptionActions: {
             canStartCheckout: boolean;
             canManagePaymentMethods: boolean;
             canUpdateBillingProfile: boolean;
@@ -1235,7 +1529,7 @@ export interface components {
             canPayOpenInvoice: boolean;
             canWithdrawScheduledChange: boolean;
         };
-        BillingSummary: {
+        BillingSubscription: {
             billingOwner: components["schemas"]["BillingOwner"];
             /** @enum {string} */
             billingMode: "not_setup" | "self_serve" | "managed";
@@ -1252,12 +1546,12 @@ export interface components {
             scheduledChange?: components["schemas"]["BillingScheduledChange"];
             hasPendingUpdate: boolean;
             paymentHealth: components["schemas"]["BillingPaymentHealth"];
-            actions: components["schemas"]["BillingSummaryActions"];
+            actions: components["schemas"]["BillingSubscriptionActions"];
         };
-        ApiResponse_BillingSummary: {
+        ApiResponse_BillingSubscription: {
             /** @example true */
             success: boolean;
-            data: components["schemas"]["BillingSummary"];
+            data: components["schemas"]["BillingSubscription"];
         };
         BillingPaymentMethod: {
             id: string;
@@ -1466,7 +1760,7 @@ export interface components {
             consent: true;
             paymentMethodId?: string;
             setupIntentId?: string;
-            /** @description Start Team on its free trial instead of billing it now. The card in paymentMethodId or setupIntentId is charged when the trial ends. Team only. Refused with trial_unavailable once the account has had the trial, and with trial_not_offered where free trials are not offered. */
+            /** @description Start Team on its free trial instead of billing it now. The card in paymentMethodId or setupIntentId is charged when the trial ends. Team only. Refused with trial_unavailable once the account has had the trial. */
             trial?: boolean;
         };
         BillingChangeRequest: {
@@ -2926,6 +3220,18 @@ export interface components {
         };
     };
     parameters: {
+        /** @description Start of the window, inclusive: an RFC 3339 timestamp, or a YYYY-MM-DD date taken at midnight in `timezone`. Defaults to seven days (hourly: 24 hours) before `end`. Not with `for`. */
+        UsageStart: string;
+        /** @description End of the window, exclusive, in the same forms as `start`. Defaults to now. Not with `for`. */
+        UsageEnd: string;
+        /** @description A named window relative to now in `timezone`, instead of `start` and `end`. Weeks start on Monday. A window may run past now; the intervals after it are left out. */
+        UsageFor: "today" | "yesterday" | "this-week" | "last-week" | "this-month" | "last-month";
+        /** @description Which billing period: `current` (the default), or a YYYY-MM-DD date (UTC) inside a past period that has been invoiced; the day a period starts on selects it. A past period is read whole from the invoices issued for it, named in `invoices`: its metered quantities and cost as billed, the included credits taken off, the base price, and any other line under its own name. */
+        SummaryPeriod: string;
+        /** @description Width of each interval. Days are aligned to `timezone`; hours are UTC. */
+        UsageGranularity: "1d" | "1h";
+        /** @description IANA timezone that day intervals and dates are aligned to. */
+        UsageTimezone: string;
         /** @description Disk ID (format `dsk-{16 hex chars}`) */
         DiskId: string;
         /** @description Sandbox UUID */
@@ -2943,7 +3249,7 @@ export interface components {
 }
 export type $defs = Record<string, never>;
 export interface operations {
-    getBillingSummary: {
+    getBillingSubscription: {
         parameters: {
             query?: never;
             header?: never;
@@ -2952,13 +3258,13 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Billing summary */
+            /** @description Subscription state */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ApiResponse_BillingSummary"];
+                    "application/json": components["schemas"]["ApiResponse_BillingSubscription"];
                 };
             };
             /** @description Missing, invalid, or disallowed credential */
@@ -2981,6 +3287,100 @@ export interface operations {
             };
         };
     };
+    getBillingUsage: {
+        parameters: {
+            query?: {
+                /** @description Start of the window, inclusive: an RFC 3339 timestamp, or a YYYY-MM-DD date taken at midnight in `timezone`. Defaults to seven days (hourly: 24 hours) before `end`. Not with `for`. */
+                start?: components["parameters"]["UsageStart"];
+                /** @description End of the window, exclusive, in the same forms as `start`. Defaults to now. Not with `for`. */
+                end?: components["parameters"]["UsageEnd"];
+                /** @description A named window relative to now in `timezone`, instead of `start` and `end`. Weeks start on Monday. A window may run past now; the intervals after it are left out. */
+                for?: components["parameters"]["UsageFor"];
+                /** @description Width of each interval. Days are aligned to `timezone`; hours are UTC. */
+                granularity?: components["parameters"]["UsageGranularity"];
+                /** @description IANA timezone that day intervals and dates are aligned to. */
+                timezone?: components["parameters"]["UsageTimezone"];
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Usage over the window and per interval */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiResponse_BillingUsage"];
+                };
+            };
+            400: components["responses"]["ValidationError"];
+            401: components["responses"]["Unauthorized"];
+            502: components["responses"]["InternalError"];
+        };
+    };
+    getBillingCosts: {
+        parameters: {
+            query?: {
+                /** @description Start of the window, inclusive: an RFC 3339 timestamp, or a YYYY-MM-DD date taken at midnight in `timezone`. Defaults to seven days (hourly: 24 hours) before `end`. Not with `for`. */
+                start?: components["parameters"]["UsageStart"];
+                /** @description End of the window, exclusive, in the same forms as `start`. Defaults to now. Not with `for`. */
+                end?: components["parameters"]["UsageEnd"];
+                /** @description A named window relative to now in `timezone`, instead of `start` and `end`. Weeks start on Monday. A window may run past now; the intervals after it are left out. */
+                for?: components["parameters"]["UsageFor"];
+                /** @description Width of each interval. Days are aligned to `timezone`; hours are UTC. */
+                granularity?: components["parameters"]["UsageGranularity"];
+                /** @description IANA timezone that day intervals and dates are aligned to. */
+                timezone?: components["parameters"]["UsageTimezone"];
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Cost over the window and per interval */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiResponse_BillingCosts"];
+                };
+            };
+            400: components["responses"]["ValidationError"];
+            401: components["responses"]["Unauthorized"];
+            502: components["responses"]["InternalError"];
+        };
+    };
+    getBillingSummary: {
+        parameters: {
+            query?: {
+                /** @description Which billing period: `current` (the default), or a YYYY-MM-DD date (UTC) inside a past period that has been invoiced; the day a period starts on selects it. A past period is read whole from the invoices issued for it, named in `invoices`: its metered quantities and cost as billed, the included credits taken off, the base price, and any other line under its own name. */
+                period?: components["parameters"]["SummaryPeriod"];
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The period's statement as a sum, with a projection for the current period */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiResponse_BillingSummary"];
+                };
+            };
+            400: components["responses"]["ValidationError"];
+            401: components["responses"]["Unauthorized"];
+            502: components["responses"]["InternalError"];
+        };
+    };
     listBillingPaymentMethods: {
         parameters: {
             query?: {
@@ -3405,7 +3805,7 @@ export interface operations {
             400: components["responses"]["ValidationError"];
             401: components["responses"]["Unauthorized"];
             404: components["responses"]["NotFound"];
-            /** @description The account already has a subscription (`already_subscribed`), the operationId was used for a different request (`operation_conflict`), or the setup is incomplete (`setup_incomplete`); the current state is in data. A trial is refused when the account has had it (`trial_unavailable`) or free trials are not offered (`trial_not_offered`). */
+            /** @description The account already has a subscription (`already_subscribed`), the operationId was used for a different request (`operation_conflict`), or the setup is incomplete (`setup_incomplete`); the current state is in data. A trial is refused when the account has had it (`trial_unavailable`). */
             409: {
                 headers: {
                     [name: string]: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archildata/api-types",
-  "version": "0.0.63",
+  "version": "0.0.65",
   "description": "API types for the Archil control plane",
   "type": "module",
   "types": "index.d.ts",