@schematichq/schematic-react 1.4.1 → 1.6.0

package/dist/schematic-react.d.ts

@@ -1,9 +1,234 @@
 import { default as React_2 } from 'react';
 
+export declare type AccessToken = string | AccessTokenProvider;
+
+/**
+ * The machinery every temporary-access-token surface shares: which session is
+ * being read, the credential for it, and the request that carries it. It
+ * knows nothing about invoices, subscriptions, or checkout — a domain client
+ * (see `SchematicBillingClient`) is constructed over it, and several may
+ * share one session rather than each minting tokens of its own.
+ */
+/** Called once per session, and again when a request comes back 401. */
+export declare type AccessTokenProvider = () => Promise<string | AccessTokenResult>;
+
+/**
+ * A bare token, or one that says when it expires and who it was minted for.
+ * `company`/`user` are the host restating the pair it asked for; stated, they
+ * are checked against the session the resolution was started for.
+ */
+declare interface AccessTokenResult {
+    token: string;
+    expiresAt?: Date | string | null;
+    company?: string;
+    user?: string;
+}
+
 declare type BaseSchematicProviderProps = Omit<SchematicJS.SchematicOptions, "client" | "publishableKey" | "useWebSocket"> & {
     children: React_2.ReactNode;
+    /**
+     * The billing session: which (company, user) pair the `/company/*`
+     * endpoints are read for and the credential for it, `null` when nobody is
+     * signed in, and `undefined` while the host is finding out. Held alongside
+     * the publishable key, which keeps serving flags.
+     */
+    session?: SessionInput;
+    /** A billing client; schematic-js supplies one when omitted. */
+    billingClient?: BillingClient;
+    /**
+     * Prefetched billing data, so the first render is complete (SSR). Rows
+     * stamped with their session paint on the first render only if `session`
+     * is stated on that render; under `undefined` they are held until it
+     * starts. State the pair on the first client render — `token` may be an
+     * async provider — or hydration will not match.
+     */
+    initialData?: BillingData;
+} & SchematicI18nConfig;
+
+declare namespace billingApi {
+    export {
+        instanceOfApiError,
+        ApiErrorFromJSON,
+        ApiErrorFromJSONTyped,
+        ApiErrorToJSON,
+        ApiErrorToJSONTyped,
+        ApiError,
+        instanceOfCompanyInvoiceResponseData,
+        CompanyInvoiceResponseDataFromJSON,
+        CompanyInvoiceResponseDataFromJSONTyped,
+        CompanyInvoiceResponseDataToJSON,
+        CompanyInvoiceResponseDataToJSONTyped,
+        CompanyInvoiceResponseData,
+        instanceOfCompanyInvoicesResponseData,
+        CompanyInvoicesResponseDataFromJSON,
+        CompanyInvoicesResponseDataFromJSONTyped,
+        CompanyInvoicesResponseDataToJSON,
+        CompanyInvoicesResponseDataToJSONTyped,
+        CompanyInvoicesResponseData,
+        instanceOfGetCompanyInvoicesParams,
+        GetCompanyInvoicesParamsFromJSON,
+        GetCompanyInvoicesParamsFromJSONTyped,
+        GetCompanyInvoicesParamsToJSON,
+        GetCompanyInvoicesParamsToJSONTyped,
+        GetCompanyInvoicesParams,
+        instanceOfGetCompanyInvoicesResponse,
+        GetCompanyInvoicesResponseFromJSON,
+        GetCompanyInvoicesResponseFromJSONTyped,
+        GetCompanyInvoicesResponseToJSON,
+        GetCompanyInvoicesResponseToJSONTyped,
+        GetCompanyInvoicesResponse,
+        instanceOfInvoiceStatus,
+        InvoiceStatusFromJSON,
+        InvoiceStatusFromJSONTyped,
+        InvoiceStatusToJSON,
+        InvoiceStatusToJSONTyped,
+        InvoiceStatus
+    }
+}
+
+/**
+ * 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.
+ */
+export declare interface BillingClient {
+    fetchInvoices(params: InvoicesRequest): Promise<InvoicesResult>;
+    readonly sessionStatus: SessionStatus;
+    readonly sessionKey: string | undefined;
+    setSession(session: SessionInput): void;
+    onSessionChange(listener: (event: SessionEvent) => void): () => void;
+}
+
+declare type BillingClientOptions = SessionOptions;
+
+/**
+ * A prefetch or fixture. An omitted key reports as pending; a keyed resource
+ * seeds under `params`, or its defaults when absent, so a prefetch for a
+ * non-default query is claimed rather than refetched by the element.
+ */
+export declare type BillingData = {
+    [K in BillingResourceName]?: BillingResources[K];
+} & {
+    params?: Partial<BillingResourceParams>;
+    /**
+     * A prefetch outlives the render that made it — a cached page, a session
+     * resolving to somebody else — so a store adopts it only for the session
+     * it names. `fetchBillingData` fills it in; a fixture need not.
+     */
+    sessionKey?: string;
+};
+
+export declare function BillingDataProvider({ children, data, locale, onLoadMoreInvoices, onMissingString, onRefetch, status, strings, translate, }: BillingDataProviderProps): React_2.JSX.Element;
+
+declare interface BillingDataProviderDataProps {
+    /** A missing key reports as pending. */
+    data: BillingData;
+    /** Simulated loading / failure per resource; wins over `data`. */
+    status?: BillingDataStatus;
+    onRefetch?: (name: BillingResourceName) => void;
+    onLoadMoreInvoices?: (query: InvoiceQuery) => void;
+    children?: React_2.ReactNode;
+}
+
+/**
+ * Feeds the billing hooks from plain data with no fetching: fixtures,
+ * stories, tests, or a fully prefetched page. The i18n props configure a
+ * `SchematicI18nProvider` around the children and never touch the data seam.
+ */
+export declare type BillingDataProviderProps = BillingDataProviderDataProps & SchematicI18nConfig;
+
+/**
+ * The seam between the hooks and whatever supplies data: the provider's
+ * store, a server prefetch, or fixtures.
+ */
+export declare interface BillingDataSource {
+    /**
+     * Sources that hold one value per resource (fixtures, prefetch) serve it
+     * for every parameter set.
+     */
+    subscribe<K extends BillingResourceName>(name: K, params: BillingResourceParams[K], listener: () => void): () => void;
+    handle<K extends BillingResourceName>(name: K, params: BillingResourceParams[K]): ResourceHandle<BillingResources[K]>;
+    /** Never rejects: a failure lands on the resource's `error`. */
+    loadMoreInvoices: (query: InvoiceQuery) => Promise<void>;
+    invalidateAll: () => void;
+}
+
+/** Per-resource status overrides, for fixtures that simulate loading and failure. */
+export declare type BillingDataStatus = {
+    [K in BillingResourceName]?: {
+        isPending?: boolean;
+        error?: Error;
+    };
 };
 
+declare interface BillingPrefetchOptions {
+    names?: BillingResourceName[];
+    /** The invoice query to prefetch for; the element must ask the same one. */
+    invoices?: InvoiceQuery;
+}
+
+/**
+ * Provides the billing hooks from a `BillingStore` over a `BillingClient`.
+ * Rendered by `SchematicProvider`; usable on its own with a client.
+ */
+export declare function BillingProvider({ billingClient, children, initialData, locale, onMissingString, session, strings, translate, }: BillingProviderProps): React_2.JSX.Element;
+
+declare interface BillingProviderDataProps {
+    /**
+     * Required: this provider does not build one, and without it every hook
+     * reports the missing-source error and `session` has nowhere to go.
+     * `SchematicProvider` constructs one from its publishable key and renders
+     * this underneath, which is the usual path.
+     */
+    billingClient?: BillingClient;
+    /**
+     * Read once, at mount. A prefetch stamped with its session paints on the
+     * first render only if `session` is stated on that render; under
+     * `undefined` it is held until the session starts. On a server-rendered
+     * page, state the pair on the first client render — `token` may be an
+     * async provider — or hydration will not match.
+     */
+    initialData?: BillingData;
+    /**
+     * Who is being read, and the credential for it: `{ company, user?, token }`
+     * while someone is signed in, `null` when nobody is, and `undefined` while
+     * the host is still finding out.
+     *
+     * The (company, user) pair is the identity, so a token that rotates — a
+     * provider called again, a closure rebuilt on a render — is the same
+     * session and keeps what is loaded, while another pair drops it.
+     * `undefined` states nothing, which is what an auth resolving
+     * asynchronously renders first.
+     */
+    session?: SessionInput;
+    children?: React_2.ReactNode;
+}
+
+/**
+ * The i18n props are forwarded to a `SchematicI18nProvider` and never reach
+ * the data seam.
+ */
+export declare type BillingProviderProps = BillingProviderDataProps & SchematicI18nConfig;
+
+export declare type BillingResourceName = keyof BillingResources;
+
+/** `Record<string, never>` marks a singleton; anything else is keyed. */
+export declare interface BillingResourceParams {
+    invoices: InvoiceQuery;
+}
+
+/**
+ * Nothing in the store, the hooks, or the resource keys may be addressed by
+ * company or user id: users and companies are many-to-many, and a token names
+ * the pair. What is loaded belongs to the session it was read under — the
+ * pair, as `sessionKey` writes it — and a store that keeps more than one
+ * session's data keys it by that and serves only the active one.
+ */
+export declare interface BillingResources {
+    /** `GET /company/invoices?limit&offset&include_pending`. */
+    invoices: InvoicePage;
+}
+
 declare type BooleanListenerFn = (value: boolean) => void;
 
 /**
@@ -73,11 +298,11 @@ declare interface CheckFlagResponseData {
     featureUsageEvent?: string | null;
     /**
      * Deprecated: Use Entitlement.MetricPeriod instead.
-     * @type {string}
+     * @type {MetricPeriod}
      * @memberof CheckFlagResponseData
      * @deprecated
      */
-    featureUsagePeriod?: string | null;
+    featureUsagePeriod?: MetricPeriod | null;
     /**
      * Deprecated: Use Entitlement.MetricResetAt instead.
      * @type {Date}
@@ -111,10 +336,10 @@ declare interface CheckFlagResponseData {
     ruleId?: string | null;
     /**
      * If a rule was found, its type
-     * @type {string}
+     * @type {RuleType}
      * @memberof CheckFlagResponseData
      */
-    ruleType?: string | null;
+    ruleType?: RuleType_2 | null;
     /**
      * If user keys were provided and matched a user, its ID
      * @type {string}
@@ -136,8 +361,14 @@ export declare type CheckFlagReturn = {
     featureUsageExceeded?: boolean;
     /** If company keys were provided and matched a company, its ID */
     companyId?: string;
-    /** If the company has a credit-based entitlement for this feature, the remaining credit amount */
+    /** If the company has a credit-based entitlement for this feature, the ID of the credit */
+    creditId?: string;
+    /** If the company has a credit-based entitlement for this feature, the credit available to fund new consumption excluding any open lease hold (the value lease-holding SDKs gate on) */
     creditRemaining?: number;
+    /** If the company has a credit-based entitlement for this feature, the unspent amount held by an open credit lease, 0 when none is open */
+    creditReserved?: number;
+    /** If the company has a credit-based entitlement for this feature, the spendable balance including any open lease hold (creditRemaining + creditReserved); the number to display to end users */
+    creditSettled?: number;
     /** If an error occurred while checking the flag, the error message */
     error?: string;
     /** If a numeric feature entitlement rule was matched, its allocation */
@@ -198,6 +429,14 @@ declare interface CheckFlagsResponse {
  * @interface CheckFlagsResponseData
  */
 declare interface CheckFlagsResponseData {
+    /**
+     * Lease-aware credit balances keyed by credit ID, covering every credit type the company holds a balance in
+     * @type {{ [key: string]: CompanyCreditBalance; }}
+     * @memberof CheckFlagsResponseData
+     */
+    creditBalances?: {
+        [key: string]: CompanyCreditBalance;
+    };
     /**
      *
      * @type {Array<CheckFlagResponseData>}
@@ -231,6 +470,112 @@ declare const CheckPlanReturnFromJSON: (json: any) => CheckPlanReturn;
 
 declare type CheckPlanReturnListenerFn = (value: CheckPlanReturn) => void;
 
+/**
+ * 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 CompanyCreditBalance
+ */
+export declare interface CompanyCreditBalance {
+    /**
+     * Remaining credit, excluding any open lease hold (the value SDKs gate on)
+     * @type {number}
+     * @memberof CompanyCreditBalance
+     */
+    remaining: number;
+    /**
+     * Amount held by the company's open credit lease, 0 when none is open
+     * @type {number}
+     * @memberof CompanyCreditBalance
+     */
+    reserved: number;
+    /**
+     * Spendable balance including the open lease hold (remaining + reserved)
+     * @type {number}
+     * @memberof CompanyCreditBalance
+     */
+    settled: number;
+}
+
+/**
+ *
+ * @export
+ * @interface CompanyInvoiceResponseData
+ */
+declare interface CompanyInvoiceResponseData {
+    /**
+     *
+     * @type {number}
+     * @memberof CompanyInvoiceResponseData
+     */
+    amountDue: number;
+    /**
+     *
+     * @type {Date}
+     * @memberof CompanyInvoiceResponseData
+     */
+    createdAt: Date;
+    /**
+     *
+     * @type {string}
+     * @memberof CompanyInvoiceResponseData
+     */
+    currency: string;
+    /**
+     *
+     * @type {Date}
+     * @memberof CompanyInvoiceResponseData
+     */
+    dueDate?: Date | null;
+    /**
+     *
+     * @type {string}
+     * @memberof CompanyInvoiceResponseData
+     */
+    id: string;
+    /**
+     *
+     * @type {InvoiceStatus}
+     * @memberof CompanyInvoiceResponseData
+     */
+    status?: InvoiceStatus | null;
+    /**
+     *
+     * @type {string}
+     * @memberof CompanyInvoiceResponseData
+     */
+    url?: string | null;
+}
+
+/** A company's lease-aware balance for a single credit type */
+export declare type CreditBalance = {
+    /** Spendable balance including any open lease hold (remaining + reserved); the number to display to end users */
+    settled: number;
+    /** Remaining credit excluding any open lease hold (the value lease-holding SDKs gate on) */
+    remaining: number;
+    /** Amount held by the company's open credit lease, 0 when none is open */
+    reserved: number;
+};
+
+declare type CreditBalanceListenerFn = CreditBalancesListenerFn | EmptyListenerFn;
+
+/** A company's lease-aware credit balances keyed by credit ID */
+export declare type CreditBalances = Record<string, CreditBalance>;
+
+declare const CreditBalancesFromJSON: (json: any) => CreditBalances;
+
+declare type CreditBalancesListenerFn = (value: CreditBalances) => void;
+
 /**
  *
  * @export
@@ -265,6 +610,8 @@ declare interface DatastreamCompanyPlan {
 
 declare function DatastreamCompanyPlanFromJSON(json: any): DatastreamCompanyPlan;
 
+export declare const DEFAULT_INVOICE_QUERY: InvoiceQuery;
+
 declare type EmptyListenerFn = () => void;
 
 /**
@@ -337,6 +684,12 @@ declare interface EventBodyFlagCheck {
      * @memberof EventBodyFlagCheck
      */
     flagKey: string;
+    /**
+     * Whether the check was a preflight, asking whether an action would be allowed rather than reporting one that happened. Absent on ordinary checks
+     * @type {boolean}
+     * @memberof EventBodyFlagCheck
+     */
+    preflight?: boolean;
     /**
      * The reason why the value was returned
      * @type {string}
@@ -412,6 +765,12 @@ declare interface FeatureEntitlement {
      * @memberof FeatureEntitlement
      */
     allocation?: number | null;
+    /**
+     * If the company has a credit-based entitlement for this feature, the credit cost per unit of usage
+     * @type {number}
+     * @memberof FeatureEntitlement
+     */
+    consumptionRate?: number | null;
     /**
      * If the company has a credit-based entitlement for this feature, the ID of the credit
      * @type {string}
@@ -419,11 +778,23 @@ declare interface FeatureEntitlement {
      */
     creditId?: string | null;
     /**
-     * If the company has a credit-based entitlement for this feature, the remaining credit amount
+     * If the company has a credit-based entitlement for this feature, the credit available to fund new consumption or a new lease hold — open lease holds are excluded. Clients that hold a lease should gate on this plus their own unspent hold; clients with no lease awareness should use credit_settled instead
      * @type {number}
      * @memberof FeatureEntitlement
      */
     creditRemaining?: number | null;
+    /**
+     * If the company has a credit-based entitlement for this feature, the unspent amount held by an open credit lease. Returns to credit_remaining when the lease is released
+     * @type {number}
+     * @memberof FeatureEntitlement
+     */
+    creditReserved?: number | null;
+    /**
+     * If the company has a credit-based entitlement for this feature, the balance net of actual consumption, unaffected by open lease holds (credit_remaining plus credit_reserved). The number to display to end users
+     * @type {number}
+     * @memberof FeatureEntitlement
+     */
+    creditSettled?: number | null;
     /**
      * If the company has a credit-based entitlement for this feature, the total credit amount
      * @type {number}
@@ -442,6 +813,12 @@ declare interface FeatureEntitlement {
      * @memberof FeatureEntitlement
      */
     eventName?: string | null;
+    /**
+     * For event-based or credit-metered feature entitlements, the event subtype whose usage is tracked
+     * @type {string}
+     * @memberof FeatureEntitlement
+     */
+    eventSubtype?: string | null;
     /**
      * The ID of the feature
      * @type {string}
@@ -456,10 +833,10 @@ declare interface FeatureEntitlement {
     featureKey: string;
     /**
      * For event-based feature entitlements, the period over which usage is tracked
-     * @type {string}
+     * @type {MetricPeriod}
      * @memberof FeatureEntitlement
      */
-    metricPeriod?: FeatureEntitlementMetricPeriodEnum | null;
+    metricPeriod?: MetricPeriod | null;
     /**
      * For event-based feature entitlements, when the usage period will reset
      * @type {Date}
@@ -468,10 +845,10 @@ declare interface FeatureEntitlement {
     metricResetAt?: Date | null;
     /**
      * For event-based feature entitlements that have a monthly period, whether that monthly reset is based on the calendar month or a billing cycle
-     * @type {string}
+     * @type {MetricPeriodMonthReset}
      * @memberof FeatureEntitlement
      */
-    monthReset?: FeatureEntitlementMonthResetEnum | null;
+    monthReset?: MetricPeriodMonthReset | null;
     /**
      * For usage-based pricing, the soft limit for overage charges or the next tier boundary
      * @type {number}
@@ -490,41 +867,143 @@ declare interface FeatureEntitlement {
      * @memberof FeatureEntitlement
      */
     valueType: EntitlementValueType;
+    /**
+     * Customer-defined usage warning thresholds configured on this entitlement
+     * @type {Array<WarningTier>}
+     * @memberof FeatureEntitlement
+     */
+    warningTiers?: Array<WarningTier>;
+}
+
+/**
+ * Server prefetch for a provider's `initialData`. A resource that fails is
+ * left out rather than thrown, so one of them cannot block a page.
+ */
+declare function fetchBillingData(client: BillingClient, options?: BillingPrefetchOptions): Promise<BillingData>;
+
+declare type FlagCheckListenerFn = CheckFlagReturnListenerFn | EmptyListenerFn;
+
+declare type FlagValueListenerFn = BooleanListenerFn | EmptyListenerFn;
+
+export declare type Invoice = CompanyInvoiceResponseData;
+
+/** A `limit` above this is a 400 (PaginationFilter in schematic-api). */
+declare const INVOICE_MAX_PAGE_SIZE = 250;
+
+export declare const INVOICE_PAGE_SIZE = 12;
+
+export declare interface InvoicePage {
+    invoices: Invoice[];
+    /** Matching the query on the server, not the number loaded here. */
+    count: number;
+    hasMore: boolean;
+}
+
+/** Each distinct query is its own row set with its own paging. */
+export declare interface InvoiceQuery {
+    /** Include unpaid invoices that are not yet due. Default false. */
+    includePending?: boolean;
 }
 
+export declare interface InvoicesHandle extends ResourceHandle<InvoicePage> {
+    /**
+     * Requests the next page; appended to `data.invoices` when it arrives.
+     * `isPending` is true while it is on the wire and `error` records a
+     * failure, so a caller can track both without awaiting — the promise
+     * never rejects.
+     */
+    loadMore: () => Promise<void>;
+}
+
+declare interface InvoicesRequest extends InvoiceQuery {
+    limit: number;
+    offset: number;
+}
+
+/**
+ * The rows asked for, and how many the query matches in total. `hasMore` is
+ * the page's, and only the caller knows its offset.
+ */
+declare type InvoicesResult = Omit<InvoicePage, "hasMore">;
+
+/**
+ *
+ * @export
+ */
+export declare const InvoiceStatus: {
+    readonly Draft: "draft";
+    readonly Open: "open";
+    readonly Paid: "paid";
+    readonly Uncollectible: "uncollectible";
+    readonly Void: "void";
+};
+
+export declare type InvoiceStatus = (typeof InvoiceStatus)[keyof typeof InvoiceStatus];
+
+/** A record of unique key-value pairs used for identifying a company or user */
+export declare type Keys = Record<string, string>;
+
 /**
+ *
  * @export
  */
-declare const FeatureEntitlementMetricPeriodEnum: {
+declare const MetricPeriod: {
     readonly AllTime: "all_time";
     readonly CurrentDay: "current_day";
     readonly CurrentMonth: "current_month";
     readonly CurrentWeek: "current_week";
 };
 
-declare type FeatureEntitlementMetricPeriodEnum = (typeof FeatureEntitlementMetricPeriodEnum)[keyof typeof FeatureEntitlementMetricPeriodEnum];
+declare type MetricPeriod = (typeof MetricPeriod)[keyof typeof MetricPeriod];
 
 /**
+ *
  * @export
  */
-declare const FeatureEntitlementMonthResetEnum: {
-    readonly FirstOfMonth: "first_of_month";
+declare const MetricPeriodMonthReset: {
     readonly BillingCycle: "billing_cycle";
+    readonly FirstOfMonth: "first_of_month";
 };
 
-declare type FeatureEntitlementMonthResetEnum = (typeof FeatureEntitlementMonthResetEnum)[keyof typeof FeatureEntitlementMonthResetEnum];
-
-declare type FlagCheckListenerFn = CheckFlagReturnListenerFn | EmptyListenerFn;
+declare type MetricPeriodMonthReset = (typeof MetricPeriodMonthReset)[keyof typeof MetricPeriodMonthReset];
 
-declare type FlagValueListenerFn = BooleanListenerFn | EmptyListenerFn;
+/**
+ * Keeps only the fields the request reads. The store keys a row set by the
+ * query's shape, so a field the API never sees would key a row set of its
+ * own, and a varying one a row set per render. schematic-js's normalizer
+ * passes unknown fields through; this export shadows it on purpose.
+ */
+export declare function normalizeInvoiceQuery(query: InvoiceQuery): InvoiceQuery;
 
-/** A record of unique key-value pairs used for identifying a company or user */
-export declare type Keys = Record<string, string>;
+/**
+ * The store keys a resource by the query's shape, so without this
+ * `{ includePending: false }` is a different row set from `{}` — it would
+ * miss the seed and refetch rows identical to those already on screen.
+ */
+declare function normalizeInvoiceQuery_2(query: InvoiceQuery): InvoiceQuery;
 
 declare type PendingListenerFn = BooleanListenerFn | EmptyListenerFn;
 
 declare type PlanListenerFn = CheckPlanReturnListenerFn | EmptyListenerFn;
 
+declare interface RequestOptions {
+    method?: string;
+    body?: unknown;
+}
+
+export declare interface ResourceHandle<T> extends ResourceState<T> {
+    refetch: () => void;
+}
+
+export declare interface ResourceState<T> {
+    /** `undefined` until the first successful load; retained across later errors. */
+    data: T | undefined;
+    /** The latest failure; cleared by the next success. */
+    error: Error | undefined;
+    /** A request is in flight and no data has arrived yet, or a refetch is running. */
+    isPending: boolean;
+}
+
 export declare enum RuleType {
     /** A global rule that, if present, will override all other rules for a flag */
     GLOBAL_OVERRIDE = "global_override",
@@ -542,10 +1021,26 @@ export declare enum RuleType {
     DEFAULT = "default"
 }
 
+/**
+ *
+ * @export
+ */
+declare const RuleType_2: {
+    readonly CompanyOverride: "company_override";
+    readonly CompanyOverrideUsageExceeded: "company_override_usage_exceeded";
+    readonly Default: "default";
+    readonly GlobalOverride: "global_override";
+    readonly PlanEntitlement: "plan_entitlement";
+    readonly PlanEntitlementUsageExceeded: "plan_entitlement_usage_exceeded";
+    readonly Standard: "standard";
+};
+
+declare type RuleType_2 = (typeof RuleType_2)[keyof typeof RuleType_2];
+
 export declare class Schematic {
-    private additionalHeaders;
+    private _additionalHeaders;
     private apiKey;
-    private apiUrl;
+    private _apiUrl;
     private conn;
     private context;
     private debugEnabled;
@@ -558,11 +1053,17 @@ export declare class Schematic {
     private isPending;
     private isPendingListeners;
     private planListeners;
+    private creditBalanceListeners;
     private storage;
+    private persistFlagState;
+    private flagStateCacheKey;
+    private flagStateCacheMaxAgeMs;
+    private cachedFlagState;
     private useWebSocket;
     private checks;
     private featureUsageEventMap;
     private planChecks;
+    private creditBalances;
     private webSocketUrl;
     private webSocketConnectionTimeout;
     private webSocketReconnect;
@@ -584,6 +1085,8 @@ export declare class Schematic {
     private flagCheckDefaults;
     private fallbackCheckCache;
     constructor(apiKey: string, options?: SchematicOptions);
+    get apiUrl(): string;
+    get additionalHeaders(): Record<string, string>;
     /**
      * Resolve fallback value according to priority order:
      * 1. Callsite fallback value (if provided)
@@ -669,6 +1172,13 @@ export declare class Schematic {
     private stopRetryTimer;
     private flushEventQueue;
     private getAnonymousId;
+    private hasCachedValuesForContext;
+    private readFlagStateCache;
+    private reviveCachedCheck;
+    private reviveCachedPlan;
+    private reviveCachedCreditBalances;
+    private hydrateFlagStateFromCache;
+    private persistContextToCache;
     private handleEvent;
     private sendEvent;
     private storeEvent;
@@ -768,6 +1278,10 @@ export declare class Schematic {
     addIsPendingListener: (listener: PendingListenerFn) => () => void;
     private setIsPending;
     getPlan: () => CheckPlanReturn | undefined;
+    /** Get the company's lease-aware credit balances for the current context, keyed by credit ID */
+    getCreditBalances: () => CreditBalances;
+    /** Get the company's lease-aware balance for a single credit type in the current context */
+    getCreditBalance: (creditId: string) => CreditBalance | undefined;
     getFlagCheck: (flagKey: string) => CheckFlagReturn | undefined;
     getFlagValue: (flagKey: string) => boolean | undefined;
     /** Register an event listener that will be notified with the boolean value for a given flag when this value changes */
@@ -775,11 +1289,35 @@ export declare class Schematic {
     /** Register an event listener that will be notified with the full flag check response for a given flag whenever this value changes */
     addFlagCheckListener: (flagKey: string, listener: FlagCheckListenerFn) => () => void;
     addPlanListener: (listener: PlanListenerFn) => () => void;
+    /** Register an event listener that will be notified with the company's credit balances (keyed by credit ID) whenever they change */
+    addCreditBalanceListener: (listener: CreditBalanceListenerFn) => () => void;
     private notifyFlagCheckListeners;
     /** Add or update a CheckFlagReturn in the featureUsageEventMap */
     private updateFeatureUsageEventMap;
     private notifyFlagValueListeners;
     private notifyPlanListeners;
+    private notifyCreditBalanceListeners;
+}
+
+declare class SchematicApiError extends Error {
+    readonly status: number;
+    readonly path: string;
+    readonly body: unknown;
+    constructor(status: number, path: string, body: unknown);
+}
+
+declare class SchematicBillingClient implements BillingClient {
+    /**
+     * Public so a second client over the same surface can be constructed on
+     * this one rather than minting tokens of its own.
+     */
+    readonly session: SchematicSession;
+    constructor(options?: BillingClientOptions | SchematicSession);
+    get sessionKey(): string | undefined;
+    get sessionStatus(): SessionStatus;
+    setSession(session: SessionInput): void;
+    onSessionChange(listener: (event: SessionEvent) => void): () => void;
+    fetchInvoices(params: InvoicesRequest): Promise<InvoicesResult>;
 }
 
 /** Context for checking flags and sending events */
@@ -792,16 +1330,65 @@ declare interface SchematicContextProps {
     client: SchematicJS.Schematic;
 }
 
+/** A company's credit balance for a single credit type, plus a loading flag */
+export declare type SchematicCreditBalance = {
+    /** The spendable balance; 0 while loading or when the company holds no balance in this credit */
+    balance: number;
+    /** True while the balance is still loading and no value has arrived yet */
+    isLoading: boolean;
+};
+
 export declare interface SchematicHookOpts {
     client?: SchematicJS.Schematic;
 }
 
+export declare interface SchematicI18nConfig {
+    /** BCP 47 tag the elements format in; defaults to the runtime's locale. */
+    locale?: string;
+    /** Routes element copy to the host's i18n stack — pass i18next's `t`. */
+    translate?: Translate;
+    /**
+     * Copy by key, for a host renaming strings rather than translating them.
+     * Wins over `translate`; an element's own `strings` prop wins over both.
+     */
+    strings?: StringOverrides;
+    /** Reports a mis-wired catalogue that would otherwise look correct. */
+    onMissingString?: (key: string) => void;
+}
+
+export declare const SchematicI18nContext: React_2.Context<SchematicI18nConfig>;
+
+/**
+ * `SchematicProvider` renders one of these, so most hosts never name it.
+ * Nesting merges rather than replaces: a provider setting only `locale`
+ * keeps the translator above it, and `strings` layers key by key.
+ */
+export declare function SchematicI18nProvider({ children, locale, onMissingString, strings, translate, }: SchematicI18nProviderProps): React_2.JSX.Element;
+
+export declare interface SchematicI18nProviderProps extends SchematicI18nConfig {
+    children?: React_2.ReactNode;
+}
+
 declare namespace SchematicJS {
     export {
         CheckFlagResponseFromJSON,
         CheckFlagsResponseFromJSON,
         DatastreamCompanyPlanFromJSON,
         EventBodyFlagCheckToJSON,
+        fetchBillingData,
+        normalizeInvoiceQuery_2 as normalizeInvoiceQuery,
+        sessionKey,
+        AccessToken,
+        AccessTokenProvider,
+        AccessTokenResult,
+        billingApi,
+        BillingClient,
+        BillingClientOptions,
+        BillingData,
+        BillingPrefetchOptions,
+        BillingResourceName,
+        BillingResourceParams,
+        BillingResources,
         BooleanListenerFn,
         CheckFlagResponseData,
         CheckFlagReturn,
@@ -811,6 +1398,14 @@ declare namespace SchematicJS {
         CheckPlanReturn,
         CheckPlanReturnFromJSON,
         CheckPlanReturnListenerFn,
+        CompanyCreditBalance,
+        CompanyInvoiceResponseData,
+        CreditBalance,
+        CreditBalanceListenerFn,
+        CreditBalances,
+        CreditBalancesFromJSON,
+        CreditBalancesListenerFn,
+        DEFAULT_INVOICE_QUERY,
         EmptyListenerFn,
         Event_2 as Event,
         EventBody,
@@ -820,14 +1415,33 @@ declare namespace SchematicJS {
         EventType,
         FlagCheckListenerFn,
         FlagValueListenerFn,
+        Invoice,
+        INVOICE_MAX_PAGE_SIZE,
+        INVOICE_PAGE_SIZE,
+        InvoicePage,
+        InvoiceQuery,
+        InvoicesRequest,
+        InvoicesResult,
+        InvoiceStatus,
         Keys,
         PendingListenerFn,
         PlanListenerFn,
+        RequestOptions,
+        ResourceState,
         RuleType,
         Schematic,
+        SchematicApiError,
+        SchematicBillingClient,
         SchematicContext,
         SchematicOptions,
+        SchematicSession,
+        Session,
+        SessionEvent,
+        SessionInput,
+        SessionOptions,
+        SessionStatus,
         StoragePersister,
+        TOKEN_CACHE_SIZE,
         Traits,
         TrialStatus,
         UsagePeriod
@@ -850,6 +1464,12 @@ export declare type SchematicOptions = {
     offline?: boolean;
     /** Optionally provide a custom storage persister for client-side storage */
     storage?: StoragePersister;
+    /** Persist flag check results (and plan) keyed by context to the storage persister so subsequent page loads can boot with last-known values rather than fallbacks. Defaults to true; set false to disable.
+     *
+     * When a cache hit is found on `setContext`, `isPending` flips to false synchronously even if the cache only contains a subset of the flags the app subscribes to — uncached flags will resolve via configured fallbacks (`flagCheckDefaults`/`flagValueDefaults`) until the WebSocket reconciles. */
+    persistFlagState?: boolean;
+    /** Maximum age (ms) of a persisted cache entry before it is treated as stale on hydration. Per-context; older entries are dropped at construction time and on the next persist. Defaults to 7 days. */
+    flagStateCacheMaxAgeMs?: number;
     /** Use a WebSocket connection for real-time flag checks; if using this, run the cleanup function to close the connection */
     useWebSocket?: boolean;
     /** Optionally provide a custom WebSocket URL */
@@ -892,6 +1512,111 @@ declare type SchematicProviderPropsWithPublishableKey = BaseSchematicProviderPro
     publishableKey: string;
 };
 
+/**
+ * Session identity is the (company, user) pair alone: a freshly minted token,
+ * a rebuilt provider closure, and a refresh this session asked for itself are
+ * all the same session. Nothing in a token says who it was minted for, so
+ * that question is the host's to answer.
+ *
+ * Credentials survive a change of session, keyed by pair — switching back to
+ * a company reads with the token already in hand. They do not survive the
+ * session ending: after a sign-out the next person at this page is somebody
+ * else, and nothing minted for the last one is theirs to send.
+ */
+declare class SchematicSession {
+    private readonly _apiUrl;
+    private readonly _headers;
+    private readonly _fetch;
+    private _session;
+    private readonly _tokens;
+    private readonly _resolving;
+    /**
+     * Bumped when the session's identity changes, and only then — the object
+     * itself is replaced on every render. Anything asking "is this still the
+     * session I started under?" counts generations rather than comparing.
+     */
+    private _generation;
+    private readonly _listeners;
+    constructor(options?: SessionOptions);
+    get key(): string | undefined;
+    get status(): SessionStatus;
+    /** Only a statement that changes which pair is read counts as a change. */
+    set(session: SessionInput): void;
+    onChange(listener: (event: SessionEvent) => void): () => void;
+    private _emit;
+    private _cached;
+    private _cache;
+    /**
+     * The credential for a session, minted if this one is not held. `force`
+     * retires what is held first: the caller is a request the API has just
+     * rejected.
+     */
+    resolveToken(session: Session, force: boolean): Promise<string>;
+    /**
+     * Sends a request under the active session's credential, refreshing once
+     * and retrying if the API rejects it. Rejects rather than answering when
+     * the session changes while the request is in flight: the rows would
+     * otherwise come back as the answer to a question asked for another pair.
+     */
+    request(path: string, options?: RequestOptions): Promise<unknown>;
+}
+
+/**
+ * Who is being read. Users and companies are many-to-many: the same person
+ * reads one company's billing and then another's, and the same company is
+ * read by several people. A token is minted for the pair, so the pair — not
+ * the company alone — is the session's identity.
+ */
+export declare interface Session {
+    /** The host's name for the company, its id in their own system say. */
+    company: string;
+    /**
+     * The user, where the host mints per (company, user). Left out by a host
+     * whose tokens are company-wide, and then every reader of that company
+     * shares one session.
+     */
+    user?: string;
+    token: AccessToken;
+}
+
+/**
+ * What happened to the session, for anything holding data that belongs to
+ * one. `started`: whatever is loaded belongs to the new session — a prefetch
+ * the host seeded before its auth resolved. `changed`: another pair is being
+ * read, and what is loaded belongs to the pair being left. `ended`: nobody is
+ * signed in, and what is loaded belongs to nobody.
+ */
+export declare type SessionEvent = {
+    type: "started" | "changed" | "ended";
+};
+
+/**
+ * Three states that are not interchangeable:
+ *
+ * * `Session` — active: this pair, read with this credential.
+ * * `null` — ended: nobody is signed in; what is loaded is dropped.
+ * * `undefined` — pending: the host's auth has not resolved. It states
+ *   nothing, so the session in hand stands.
+ */
+export declare type SessionInput = Session | null | undefined;
+
+/**
+ * The pair as one string, for anything that has to compare sessions or key
+ * something by one — a prefetch stating which session it was fetched for, a
+ * store keeping a page per session. Opaque: read it only by equality.
+ */
+declare function sessionKey(session: Session): string;
+
+declare interface SessionOptions {
+    session?: SessionInput;
+    apiUrl?: string;
+    additionalHeaders?: Record<string, string>;
+    /** Override for tests and non-browser runtimes. */
+    fetch?: typeof fetch;
+}
+
+export declare type SessionStatus = "pending" | "active" | "ended";
+
 /** Optional type for implementing custom client-side storage */
 export declare type StoragePersister = {
     setItem(key: string, value: any): void;
@@ -899,11 +1624,44 @@ export declare type StoragePersister = {
     removeItem(key: string): void;
 };
 
+/** Copy overrides by key. Keys are the element package's `StringKey`s. */
+export declare type StringOverrides = Record<string, string | undefined>;
+
+/**
+ * Sessions whose credentials are kept. A reader switching between the
+ * organizations they belong to walks a handful of them and comes back, and
+ * re-minting on every step is a round trip to the host's token endpoint for
+ * a token this client already holds and has not seen expire. The same
+ * handful the flag cache bounds its contexts at.
+ */
+declare const TOKEN_CACHE_SIZE = 10;
+
 /**
  * A flexible key/value type that can store any type of value on a company or user.
  */
 export declare type Traits = Record<string, any>;
 
+/**
+ * Locale and copy live in their own context, not on the billing data source:
+ * a host's `t` changes identity whenever its language does, and a source
+ * rebuilt for that takes its cached snapshots with it, leaving
+ * `useSyncExternalStore` a new handle every render.
+ *
+ * Nothing here interprets a key — the element package owns the key list and
+ * the English copy.
+ */
+/**
+ * Shaped like i18next's `t` so `translate={t}` is the whole integration.
+ * `vars` reaches it as the options object, which is what lets `{ count }`
+ * resolve a language's plural forms in the host's own stack rather than in
+ * ours.
+ *
+ * Returning `undefined` means "no translation" and the caller falls back to
+ * its English default. Elements also pass a sentinel `defaultValue`, so a stack
+ * that answers every key with something still reports a real miss.
+ */
+export declare type Translate = (key: string, vars?: Record<string, unknown>) => string | undefined;
+
 /**
  *
  * @export
@@ -923,12 +1681,38 @@ export declare enum UsagePeriod {
     CURRENT_WEEK = "current_week"
 }
 
+export declare function useBillingDataSource(): BillingDataSource;
+
+/** Reloads every loaded billing resource (after a plan change, for instance). */
+export declare function useInvalidateBillingData(): () => void;
+
+/**
+ * The invoice list for `query`. Each distinct query is its own list with its
+ * own paging; an inline object literal is fine, the hook keys by value.
+ */
+export declare function useInvoices(query?: InvoiceQuery): InvoicesHandle;
+
 export declare const useSchematic: () => SchematicContextProps;
 
 export declare const useSchematicContext: (opts?: SchematicHookOpts) => {
     setContext: (context: SchematicJS.SchematicContext) => Promise<void>;
 };
 
+/**
+ * Returns a company's live, lease-aware credit balance for a single credit type.
+ *
+ * Surfaces the spendable `settled` balance, sourced from the streamed
+ * `credit_balances` map (keyed by credit ID). It re-renders as partials arrive
+ * over the DataStream, so it stays accurate during an open lease — when the raw
+ * `remaining` would otherwise read stale / falsely "exhausted".
+ *
+ * `creditId` accepts `undefined` so it can be fed straight from an
+ * entitlement's `creditId`, which is undefined until the check arrives and for
+ * features that are not credit-based. While the ID is undefined the hook
+ * reports the client's loading state and a balance of 0.
+ */
+export declare const useSchematicCreditBalance: (creditId: string | undefined, opts?: SchematicHookOpts) => SchematicCreditBalance;
+
 export declare const useSchematicEntitlement: (key: string, opts?: UseSchematicFlagOpts) => SchematicJS.CheckFlagReturn;
 
 export declare const useSchematicEvents: (opts?: SchematicHookOpts) => {
@@ -942,12 +1726,53 @@ export declare type UseSchematicFlagOpts = SchematicHookOpts & {
     fallback?: boolean;
 };
 
+/** Empty, never undefined, outside a provider. */
+export declare function useSchematicI18n(): SchematicI18nConfig;
+
 export declare const useSchematicIsPending: (opts?: SchematicHookOpts) => boolean;
 
+/** Unresolved: elements call `useResolvedLocale`, which applies the fallback. */
+export declare function useSchematicLocale(): string | undefined;
+
 export declare const useSchematicPlan: (opts?: UseSchematicPlanOpts) => SchematicJS.CheckPlanReturn | undefined;
 
 export declare type UseSchematicPlanOpts = SchematicHookOpts & {
     fallback?: SchematicJS.CheckPlanReturn;
 };
 
+export declare function useSchematicStrings(): StringOverrides | undefined;
+
+export declare function useSchematicTranslate(): Translate | undefined;
+
+/**
+ * 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 WarningTier
+ */
+declare interface WarningTier {
+    /**
+     * A customer-defined identifier for the warning tier
+     * @type {string}
+     * @memberof WarningTier
+     */
+    key: string;
+    /**
+     * The warning threshold, in the entitlement's usage units
+     * @type {number}
+     * @memberof WarningTier
+     */
+    value: number;
+}
+
 export { }