@schematichq/schematic-react 1.8.0 → 1.9.0

package/dist/schematic-react.d.ts

@@ -45,6 +45,20 @@ declare type BaseSchematicProviderProps = Omit<SchematicJS.SchematicOptions, "cl
     initialData?: BillingData;
 } & SchematicI18nConfig;
 
+/**
+ * The writes a source can carry out. Each rejects with the failure; a source
+ * that reads only (a prefetch with no client) leaves the object off, and the
+ * hooks reject every write with `BILLING_ACTION_UNAVAILABLE_MESSAGE`.
+ */
+export declare interface BillingActions {
+    /** Makes `externalId` the default payment method and reloads the list. */
+    setDefaultPaymentMethod(externalId: string): Promise<void>;
+    /** Removes payment method `id` and reloads the list. */
+    removePaymentMethod(id: string): Promise<void>;
+    /** Mints a new setup intent every call; nothing is cached. */
+    createSetupIntent(): Promise<SetupIntent>;
+}
+
 declare namespace billingApi {
     export {
         instanceOfApiError,
@@ -53,6 +67,12 @@ declare namespace billingApi {
         ApiErrorToJSON,
         ApiErrorToJSONTyped,
         ApiError,
+        instanceOfBillingProviderType,
+        BillingProviderTypeFromJSON,
+        BillingProviderTypeFromJSONTyped,
+        BillingProviderTypeToJSON,
+        BillingProviderTypeToJSONTyped,
+        BillingProviderType,
         instanceOfCompanyDiscountResponseData,
         CompanyDiscountResponseDataFromJSON,
         CompanyDiscountResponseDataFromJSONTyped,
@@ -71,12 +91,42 @@ declare namespace billingApi {
         CompanyInvoicesResponseDataToJSON,
         CompanyInvoicesResponseDataToJSONTyped,
         CompanyInvoicesResponseData,
+        instanceOfCompanyPaymentMethodResponseData,
+        CompanyPaymentMethodResponseDataFromJSON,
+        CompanyPaymentMethodResponseDataFromJSONTyped,
+        CompanyPaymentMethodResponseDataToJSON,
+        CompanyPaymentMethodResponseDataToJSONTyped,
+        CompanyPaymentMethodResponseData,
+        instanceOfCompanyPaymentMethodsResponseData,
+        CompanyPaymentMethodsResponseDataFromJSON,
+        CompanyPaymentMethodsResponseDataFromJSONTyped,
+        CompanyPaymentMethodsResponseDataToJSON,
+        CompanyPaymentMethodsResponseDataToJSONTyped,
+        CompanyPaymentMethodsResponseData,
         instanceOfCompanyUpcomingInvoiceResponseData,
         CompanyUpcomingInvoiceResponseDataFromJSON,
         CompanyUpcomingInvoiceResponseDataFromJSONTyped,
         CompanyUpcomingInvoiceResponseDataToJSON,
         CompanyUpcomingInvoiceResponseDataToJSONTyped,
         CompanyUpcomingInvoiceResponseData,
+        instanceOfCreateSetupIntentResponse,
+        CreateSetupIntentResponseFromJSON,
+        CreateSetupIntentResponseFromJSONTyped,
+        CreateSetupIntentResponseToJSON,
+        CreateSetupIntentResponseToJSONTyped,
+        CreateSetupIntentResponse,
+        instanceOfDeletePaymentMethodResponse,
+        DeletePaymentMethodResponseFromJSON,
+        DeletePaymentMethodResponseFromJSONTyped,
+        DeletePaymentMethodResponseToJSON,
+        DeletePaymentMethodResponseToJSONTyped,
+        DeletePaymentMethodResponse,
+        instanceOfDeleteResponse,
+        DeleteResponseFromJSON,
+        DeleteResponseFromJSONTyped,
+        DeleteResponseToJSON,
+        DeleteResponseToJSONTyped,
+        DeleteResponse,
         instanceOfGetCompanyInvoicesParams,
         GetCompanyInvoicesParamsFromJSON,
         GetCompanyInvoicesParamsFromJSONTyped,
@@ -89,6 +139,12 @@ declare namespace billingApi {
         GetCompanyInvoicesResponseToJSON,
         GetCompanyInvoicesResponseToJSONTyped,
         GetCompanyInvoicesResponse,
+        instanceOfGetCompanyPaymentMethodsResponse,
+        GetCompanyPaymentMethodsResponseFromJSON,
+        GetCompanyPaymentMethodsResponseFromJSONTyped,
+        GetCompanyPaymentMethodsResponseToJSON,
+        GetCompanyPaymentMethodsResponseToJSONTyped,
+        GetCompanyPaymentMethodsResponse,
         instanceOfGetCompanyUpcomingInvoiceResponse,
         GetCompanyUpcomingInvoiceResponseFromJSON,
         GetCompanyUpcomingInvoiceResponseFromJSONTyped,
@@ -100,19 +156,52 @@ declare namespace billingApi {
         InvoiceStatusFromJSONTyped,
         InvoiceStatusToJSON,
         InvoiceStatusToJSONTyped,
-        InvoiceStatus
+        InvoiceStatus,
+        instanceOfPaymentMethodResponseData,
+        PaymentMethodResponseDataFromJSON,
+        PaymentMethodResponseDataFromJSONTyped,
+        PaymentMethodResponseDataToJSON,
+        PaymentMethodResponseDataToJSONTyped,
+        PaymentMethodResponseData,
+        instanceOfSetupIntentResponseData,
+        SetupIntentResponseDataFromJSON,
+        SetupIntentResponseDataFromJSONTyped,
+        SetupIntentResponseDataToJSON,
+        SetupIntentResponseDataToJSONTyped,
+        SetupIntentResponseData,
+        instanceOfUpdatePaymentMethodRequestBody,
+        UpdatePaymentMethodRequestBodyFromJSON,
+        UpdatePaymentMethodRequestBodyFromJSONTyped,
+        UpdatePaymentMethodRequestBodyToJSON,
+        UpdatePaymentMethodRequestBodyToJSONTyped,
+        UpdatePaymentMethodRequestBody,
+        instanceOfUpdatePaymentMethodResponse,
+        UpdatePaymentMethodResponseFromJSON,
+        UpdatePaymentMethodResponseFromJSONTyped,
+        UpdatePaymentMethodResponseToJSON,
+        UpdatePaymentMethodResponseToJSONTyped,
+        UpdatePaymentMethodResponse
     }
 }
 
 /**
- * What a reader of billing data can ask for. Subscription and usage — the
- * rest of what `hydrate` serves — and the checkout calls that change them
- * join this interface as their endpoints ship.
+ * What a reader of billing data can ask for, and the few writes beside it.
+ * Subscription and usage — the rest of what `hydrate` serves — and the
+ * checkout calls that change them join this interface as their endpoints
+ * ship.
  */
 declare interface BillingClient {
     fetchInvoices(params: InvoicesRequest): Promise<InvoicesResult>;
     /** `null` when the company has no next bill. */
     fetchUpcomingInvoice(): Promise<UpcomingInvoice | null>;
+    /** Empty when the company has no method on file. */
+    fetchPaymentMethods(): Promise<PaymentMethod[]>;
+    /** What a provider's card form is mounted with to add a method. */
+    createSetupIntent(): Promise<SetupIntent>;
+    /** Makes the method the default, by the provider's id (`externalId`). */
+    updatePaymentMethod(externalId: string): Promise<void>;
+    /** Removes the method, by Schematic's id (`id`). */
+    deletePaymentMethod(id: string): Promise<void>;
     readonly sessionStatus: SessionStatus;
     readonly sessionKey: string | undefined;
     setSession(session: SessionInput): void;
@@ -138,7 +227,7 @@ export declare type BillingData = {
     sessionKey?: string;
 };
 
-export declare function BillingDataProvider({ children, data, locale, onLoadMoreInvoices, onMissingString, onRefetch, status, strings, translate, }: BillingDataProviderProps): React_2.JSX.Element;
+export declare function BillingDataProvider({ actions, children, data, locale, onLoadMoreInvoices, onMissingString, onRefetch, status, strings, translate, }: BillingDataProviderProps): React_2.JSX.Element;
 
 declare interface BillingDataProviderDataProps {
     /** A missing key reports as pending. */
@@ -147,6 +236,13 @@ declare interface BillingDataProviderDataProps {
     status?: BillingDataStatus;
     onRefetch?: (name: BillingResourceName) => void;
     onLoadMoreInvoices?: (query: InvoiceQuery) => void;
+    /**
+     * What the write hooks call. Each rejects on its own; an action left out
+     * rejects with `BILLING_ACTION_UNAVAILABLE_MESSAGE`. Nothing here touches
+     * `data`: a fixture that wants the list to change after a write hands in
+     * new `data`.
+     */
+    actions?: Partial<BillingActions>;
     children?: React_2.ReactNode;
 }
 
@@ -171,6 +267,8 @@ export declare interface BillingDataSource {
     /** Never rejects: a failure lands on the resource's `error`. */
     loadMoreInvoices: (query: InvoiceQuery) => Promise<void>;
     invalidateAll: () => void;
+    /** Absent on a source that only reads. */
+    actions?: BillingActions;
 }
 
 /** Per-resource status overrides, for fixtures that simulate loading and failure. */
@@ -200,13 +298,14 @@ declare interface BillingPrefetchOptions {
 export declare function BillingProvider({ billingClient, children, initialData, locale, onMissingString, session, strings, translate, }: BillingProviderProps): React_2.JSX.Element;
 
 /**
- * What `BillingProvider` asks of its client: the session it reads under, and
- * the fetch behind each resource above. schematic-js's `SchematicBillingClient`
+ * What `BillingProvider` asks of its client: the session it reads under, the
+ * fetch behind each resource above, and the payment-method actions the hooks
+ * expose. schematic-js's `SchematicBillingClient`
  * satisfies it, and so does a host's own client that implements only this
  * much. Named apart from schematic-js's `BillingClient`, which is the whole
  * interface; this is the part the hooks here call.
  */
-export declare type BillingProviderClient = Pick<BillingClient, "sessionStatus" | "sessionKey" | "setSession" | "onSessionChange" | "fetchInvoices" | "fetchUpcomingInvoice">;
+export declare type BillingProviderClient = Pick<BillingClient, "sessionStatus" | "sessionKey" | "setSession" | "onSessionChange" | "fetchInvoices" | "fetchUpcomingInvoice" | "fetchPaymentMethods" | "createSetupIntent" | "updatePaymentMethod" | "deletePaymentMethod">;
 
 declare interface BillingProviderDataProps {
     /**
@@ -246,7 +345,7 @@ declare interface BillingProviderDataProps {
 export declare type BillingProviderProps = BillingProviderDataProps & SchematicI18nConfig;
 
 /** The resources this package serves; a key of schematic-js's contract. */
-export declare type BillingResourceName = "invoices" | "upcomingInvoice";
+export declare type BillingResourceName = "invoices" | "upcomingInvoice" | "paymentMethods";
 
 declare type BillingResourceName_2 = keyof BillingResources_2;
 
@@ -256,6 +355,7 @@ export declare type BillingResourceParams = Pick<BillingResourceParams_2, Billin
 declare interface BillingResourceParams_2 {
     invoices: InvoiceQuery;
     upcomingInvoice: Record<string, never>;
+    paymentMethods: Record<string, never>;
 }
 
 export declare type BillingResources = Pick<BillingResources_2, BillingResourceName>;
@@ -276,6 +376,11 @@ declare interface BillingResources_2 {
      * `undefined` means the resource has not loaded.
      */
     upcomingInvoice: UpcomingInvoice | null;
+    /**
+     * `GET /company/payment-methods`. Empty is a loaded value — the company
+     * has no method on file — so only `undefined` means not loaded.
+     */
+    paymentMethods: PaymentMethod[];
 }
 
 declare type BooleanListenerFn = (value: boolean) => void;
@@ -669,6 +774,109 @@ declare interface CompanyInvoiceResponseData {
     url?: string | null;
 }
 
+/**
+ * Schematic API
+ * Schematic API
+ *
+ * The version of the OpenAPI document: 0.1
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+/**
+ *
+ * @export
+ * @interface CompanyPaymentMethodResponseData
+ */
+declare interface CompanyPaymentMethodResponseData {
+    /**
+     *
+     * @type {string}
+     * @memberof CompanyPaymentMethodResponseData
+     */
+    accountLast4?: string | null;
+    /**
+     *
+     * @type {string}
+     * @memberof CompanyPaymentMethodResponseData
+     */
+    accountName?: string | null;
+    /**
+     *
+     * @type {string}
+     * @memberof CompanyPaymentMethodResponseData
+     */
+    bankName?: string | null;
+    /**
+     *
+     * @type {string}
+     * @memberof CompanyPaymentMethodResponseData
+     */
+    billingEmail?: string | null;
+    /**
+     *
+     * @type {string}
+     * @memberof CompanyPaymentMethodResponseData
+     */
+    billingName?: string | null;
+    /**
+     * Whether DELETE /checkout/paymentmethod/:id would succeed. False only for the sole method while an active paid subscription needs it; the default can be removed like any other.
+     * @type {boolean}
+     * @memberof CompanyPaymentMethodResponseData
+     */
+    canRemove: boolean;
+    /**
+     *
+     * @type {string}
+     * @memberof CompanyPaymentMethodResponseData
+     */
+    cardBrand?: string | null;
+    /**
+     *
+     * @type {number}
+     * @memberof CompanyPaymentMethodResponseData
+     */
+    cardExpMonth?: number | null;
+    /**
+     *
+     * @type {number}
+     * @memberof CompanyPaymentMethodResponseData
+     */
+    cardExpYear?: number | null;
+    /**
+     *
+     * @type {string}
+     * @memberof CompanyPaymentMethodResponseData
+     */
+    cardLast4?: string | null;
+    /**
+     *
+     * @type {string}
+     * @memberof CompanyPaymentMethodResponseData
+     */
+    externalId: string;
+    /**
+     *
+     * @type {string}
+     * @memberof CompanyPaymentMethodResponseData
+     */
+    id: string;
+    /**
+     * Whether this is the method the company is billed with: the subscription's own when it has one, else the customer default. At most one method is the default.
+     * @type {boolean}
+     * @memberof CompanyPaymentMethodResponseData
+     */
+    isDefault: boolean;
+    /**
+     * The Stripe payment method type, such as card or us_bank_account.
+     * @type {string}
+     * @memberof CompanyPaymentMethodResponseData
+     */
+    type: string;
+}
+
 /**
  *
  * @export
@@ -700,7 +908,7 @@ declare interface CompanyUpcomingInvoiceResponseData {
      */
     customerBalanceRemaining: number;
     /**
-     * Only active discounts that reduce the bill.
+     * The subscription's active discounts, to show beside the bill. Informational: the amounts come from the provider's preview and already reflect whatever it applied, so subtotal less these need not equal amount_due.
      * @type {Array<CompanyDiscountResponseData>}
      * @memberof CompanyUpcomingInvoiceResponseData
      */
@@ -1146,6 +1354,35 @@ export declare function normalizeInvoiceQuery(query: InvoiceQuery): InvoiceQuery
  */
 declare function normalizeInvoiceQuery_2(query: InvoiceQuery): InvoiceQuery;
 
+/**
+ * One way the company pays. Two flags the server has already decided, so a
+ * consumer never re-derives a provider's rules:
+ *
+ * * `isDefault` — the subscription's default method, or, when the
+ *   subscription names none, the customer's.
+ * * `canRemove` — whether a delete would be accepted; the server's rule,
+ *   not `!isDefault`.
+ *
+ * `id` is Schematic's, and is what a delete takes; `externalId` is the
+ * provider's, and is what making it the default takes.
+ */
+export declare type PaymentMethod = CompanyPaymentMethodResponseData;
+
+export declare interface PaymentMethodsHandle extends ResourceHandle<PaymentMethod[]> {
+    /**
+     * Makes `externalId` the default; `data` reloads once it has. Rejects
+     * with the failure and records it on `mutationError`, so a caller can
+     * await it or read it, whichever the component does.
+     */
+    setDefault: (externalId: string) => Promise<void>;
+    /** Removes payment method `id`; `data` reloads once it has. Rejects as `setDefault` does. */
+    remove: (id: string) => Promise<void>;
+    /** A write is in flight. Distinct from `isPending`, which is the list loading. */
+    isMutating: boolean;
+    /** The last write's failure; cleared when the next write starts. */
+    mutationError: Error | undefined;
+}
+
 declare type PendingListenerFn = BooleanListenerFn | EmptyListenerFn;
 
 declare type PlanListenerFn = CheckPlanReturnListenerFn | EmptyListenerFn;
@@ -1491,6 +1728,10 @@ declare class SchematicBillingClient implements BillingClient {
     onSessionChange(listener: (event: SessionEvent) => void): () => void;
     fetchInvoices(params: InvoicesRequest): Promise<InvoicesResult>;
     fetchUpcomingInvoice(): Promise<UpcomingInvoice | null>;
+    fetchPaymentMethods(): Promise<PaymentMethod[]>;
+    createSetupIntent(): Promise<SetupIntent>;
+    updatePaymentMethod(externalId: string): Promise<void>;
+    deletePaymentMethod(id: string): Promise<void>;
 }
 
 /** Context for checking flags and sending events */
@@ -1574,6 +1815,7 @@ declare namespace SchematicJS {
         CompanyCreditBalance,
         CompanyDiscountResponseData,
         CompanyInvoiceResponseData,
+        CompanyPaymentMethodResponseData,
         CompanyUpcomingInvoiceResponseData,
         CreditBalance,
         CreditBalanceListenerFn,
@@ -1600,6 +1842,7 @@ declare namespace SchematicJS {
         InvoicesResult,
         InvoiceStatus,
         Keys,
+        PaymentMethod,
         PendingListenerFn,
         PlanListenerFn,
         RequestOptions,
@@ -1616,6 +1859,8 @@ declare namespace SchematicJS {
         SessionInput,
         SessionOptions,
         SessionStatus,
+        SetupIntent,
+        SetupIntentResponseData,
         SINGLETON,
         StoragePersister,
         TOKEN_CACHE_SIZE,
@@ -1796,6 +2041,57 @@ declare interface SessionOptions {
 
 export declare type SessionStatus = "pending" | "active" | "ended";
 
+/** What a provider's card form is mounted with to add a method. */
+export declare type SetupIntent = SetupIntentResponseData;
+
+export declare interface SetupIntentHandle {
+    /** A new intent every call: an intent is single-use, so none is kept. */
+    create: () => Promise<SetupIntent>;
+}
+
+/**
+ * Schematic API
+ * Schematic API
+ *
+ * The version of the OpenAPI document: 0.1
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+/**
+ *
+ * @export
+ * @interface SetupIntentResponseData
+ */
+declare interface SetupIntentResponseData {
+    /**
+     *
+     * @type {string}
+     * @memberof SetupIntentResponseData
+     */
+    accountId?: string | null;
+    /**
+     *
+     * @type {string}
+     * @memberof SetupIntentResponseData
+     */
+    publishableKey?: string | null;
+    /**
+     *
+     * @type {string}
+     * @memberof SetupIntentResponseData
+     */
+    schematicPublishableKey: string;
+    /**
+     *
+     * @type {string}
+     * @memberof SetupIntentResponseData
+     */
+    setupIntentClientSecret?: string | null;
+}
+
 /** The params of every singleton resource. */
 export declare const SINGLETON: Record<string, never>;
 
@@ -1876,6 +2172,19 @@ export declare function useInvalidateBillingData(): () => void;
  */
 export declare function useInvoices(query?: InvoiceQuery): InvoicesHandle;
 
+/**
+ * The company's payment methods, with the writes on them. `data` is the
+ * list, `isPending` and `error` its load, and `isMutating` and
+ * `mutationError` the last write; a write's failure never lands on `error`,
+ * which stays the list's own.
+ *
+ * Writes are not coalesced: a second call while one is in flight runs too,
+ * the store reloads the list after each, and `isMutating` stays true until
+ * the last lands. A component that wants one at a time disables its buttons
+ * on `isMutating`.
+ */
+export declare function usePaymentMethods(): PaymentMethodsHandle;
+
 export declare const useSchematic: () => SchematicContextProps;
 
 export declare const useSchematicContext: (opts?: SchematicHookOpts) => {
@@ -1928,6 +2237,14 @@ export declare function useSchematicStrings(): StringOverrides | undefined;
 
 export declare function useSchematicTranslate(): Translate | undefined;
 
+/**
+ * Mints setup intents for adding a payment method. Subscribes to no
+ * resource, reports no state, and rejects with the failure. Once the
+ * provider confirms the intent, the list is reloaded by whoever adds the
+ * method — `refetch` on `usePaymentMethods`, or `useInvalidateBillingData`.
+ */
+export declare function useSetupIntent(): SetupIntentHandle;
+
 /**
  * The company's next bill. `data` is `null` when there is nothing to bill —
  * no subscription, which the endpoint reports as a 204 — so an element can