@schematichq/schematic-js 1.5.0 → 1.7.0

package/dist/schematic.d.ts

@@ -1,3 +1,158 @@
+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.
+ */
+export declare interface AccessTokenResult {
+    token: string;
+    expiresAt?: Date | string | null;
+    company?: string;
+    user?: string;
+}
+
+/**
+ * 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 ApiError
+ */
+declare interface ApiError {
+    /**
+     * Error message
+     * @type {string}
+     * @memberof ApiError
+     */
+    error: string;
+}
+
+declare function ApiErrorFromJSON(json: any): ApiError;
+
+declare function ApiErrorFromJSONTyped(json: any, ignoreDiscriminator: boolean): ApiError;
+
+declare function ApiErrorToJSON(json: any): ApiError;
+
+declare function ApiErrorToJSONTyped(value?: ApiError | null, ignoreDiscriminator?: boolean): any;
+
+export 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;
+}
+
+export 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 interface BillingPrefetchOptions {
+    names?: BillingResourceName[];
+    /** The invoice query to prefetch for; the element must ask the same one. */
+    invoices?: InvoiceQuery;
+}
+
+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;
+}
+
 export declare type BooleanListenerFn = (value: boolean) => void;
 
 /**
@@ -276,6 +431,92 @@ export declare interface CompanyCreditBalance {
     settled: number;
 }
 
+/**
+ *
+ * @export
+ * @interface CompanyInvoiceResponseData
+ */
+export 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;
+}
+
+declare function CompanyInvoiceResponseDataFromJSON(json: any): CompanyInvoiceResponseData;
+
+declare function CompanyInvoiceResponseDataFromJSONTyped(json: any, ignoreDiscriminator: boolean): CompanyInvoiceResponseData;
+
+declare function CompanyInvoiceResponseDataToJSON(json: any): CompanyInvoiceResponseData;
+
+declare function CompanyInvoiceResponseDataToJSONTyped(value?: CompanyInvoiceResponseData | null, ignoreDiscriminator?: boolean): any;
+
+/**
+ *
+ * @export
+ * @interface CompanyInvoicesResponseData
+ */
+declare interface CompanyInvoicesResponseData {
+    /**
+     *
+     * @type {number}
+     * @memberof CompanyInvoicesResponseData
+     */
+    count: number;
+    /**
+     *
+     * @type {Array<CompanyInvoiceResponseData>}
+     * @memberof CompanyInvoicesResponseData
+     */
+    invoices: Array<CompanyInvoiceResponseData>;
+}
+
+declare function CompanyInvoicesResponseDataFromJSON(json: any): CompanyInvoicesResponseData;
+
+declare function CompanyInvoicesResponseDataFromJSONTyped(json: any, ignoreDiscriminator: boolean): CompanyInvoicesResponseData;
+
+declare function CompanyInvoicesResponseDataToJSON(json: any): CompanyInvoicesResponseData;
+
+declare function CompanyInvoicesResponseDataToJSONTyped(value?: CompanyInvoicesResponseData | null, ignoreDiscriminator?: boolean): any;
+
 /** 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 */
@@ -329,6 +570,8 @@ declare interface DatastreamCompanyPlan {
 
 export declare function DatastreamCompanyPlanFromJSON(json: any): DatastreamCompanyPlan;
 
+export declare const DEFAULT_INVOICE_QUERY: InvoiceQuery;
+
 export declare type EmptyListenerFn = () => void;
 
 /**
@@ -401,6 +644,12 @@ export 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}
@@ -578,12 +827,177 @@ 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.
+ */
+export declare function fetchBillingData(client: BillingClient, options?: BillingPrefetchOptions): Promise<BillingData>;
+
 export declare type FlagCheckListenerFn = CheckFlagReturnListenerFn | EmptyListenerFn;
 
 export declare type FlagValueListenerFn = BooleanListenerFn | EmptyListenerFn;
 
+/**
+ * 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.
+ */
+/**
+ * Input parameters
+ * @export
+ * @interface GetCompanyInvoicesParams
+ */
+declare interface GetCompanyInvoicesParams {
+    /**
+     * Include unpaid invoices that are not yet due. The default set is time-varying — an invoice passing its due date enters it and shifts later offsets — so page from the response count and stop on an empty page.
+     * @type {boolean}
+     * @memberof GetCompanyInvoicesParams
+     */
+    includePending?: boolean;
+    /**
+     * Page limit (default 100)
+     * @type {number}
+     * @memberof GetCompanyInvoicesParams
+     */
+    limit?: number;
+    /**
+     * Page offset (default 0)
+     * @type {number}
+     * @memberof GetCompanyInvoicesParams
+     */
+    offset?: number;
+}
+
+declare function GetCompanyInvoicesParamsFromJSON(json: any): GetCompanyInvoicesParams;
+
+declare function GetCompanyInvoicesParamsFromJSONTyped(json: any, ignoreDiscriminator: boolean): GetCompanyInvoicesParams;
+
+declare function GetCompanyInvoicesParamsToJSON(json: any): GetCompanyInvoicesParams;
+
+declare function GetCompanyInvoicesParamsToJSONTyped(value?: GetCompanyInvoicesParams | null, ignoreDiscriminator?: boolean): any;
+
+/**
+ *
+ * @export
+ * @interface GetCompanyInvoicesResponse
+ */
+declare interface GetCompanyInvoicesResponse {
+    /**
+     *
+     * @type {CompanyInvoicesResponseData}
+     * @memberof GetCompanyInvoicesResponse
+     */
+    data: CompanyInvoicesResponseData;
+    /**
+     *
+     * @type {GetCompanyInvoicesParams}
+     * @memberof GetCompanyInvoicesResponse
+     */
+    params: GetCompanyInvoicesParams;
+}
+
+declare function GetCompanyInvoicesResponseFromJSON(json: any): GetCompanyInvoicesResponse;
+
+declare function GetCompanyInvoicesResponseFromJSONTyped(json: any, ignoreDiscriminator: boolean): GetCompanyInvoicesResponse;
+
+declare function GetCompanyInvoicesResponseToJSON(json: any): GetCompanyInvoicesResponse;
+
+declare function GetCompanyInvoicesResponseToJSONTyped(value?: GetCompanyInvoicesResponse | null, ignoreDiscriminator?: boolean): any;
+
+/**
+ * Check if a given object implements the ApiError interface.
+ */
+declare function instanceOfApiError(value: object): value is ApiError;
+
+/**
+ * Check if a given object implements the CompanyInvoiceResponseData interface.
+ */
+declare function instanceOfCompanyInvoiceResponseData(value: object): value is CompanyInvoiceResponseData;
+
+/**
+ * Check if a given object implements the CompanyInvoicesResponseData interface.
+ */
+declare function instanceOfCompanyInvoicesResponseData(value: object): value is CompanyInvoicesResponseData;
+
+/**
+ * Check if a given object implements the GetCompanyInvoicesParams interface.
+ */
+declare function instanceOfGetCompanyInvoicesParams(value: object): value is GetCompanyInvoicesParams;
+
+/**
+ * Check if a given object implements the GetCompanyInvoicesResponse interface.
+ */
+declare function instanceOfGetCompanyInvoicesResponse(value: object): value is GetCompanyInvoicesResponse;
+
+declare function instanceOfInvoiceStatus(value: any): boolean;
+
+export declare type Invoice = CompanyInvoiceResponseData;
+
+/** A `limit` above this is a 400 (PaginationFilter in schematic-api). */
+export 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 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.
+ */
+export 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];
+
+declare function InvoiceStatusFromJSON(json: any): InvoiceStatus;
+
+declare function InvoiceStatusFromJSONTyped(json: any, ignoreDiscriminator: boolean): InvoiceStatus;
+
+declare function InvoiceStatusToJSON(value?: InvoiceStatus | null): any;
+
+declare function InvoiceStatusToJSONTyped(value: any, ignoreDiscriminator: boolean): InvoiceStatus;
+
 /** A record of unique key-value pairs used for identifying a company or user */
 export declare type Keys = Record<string, string>;
 
@@ -611,10 +1025,31 @@ declare const MetricPeriodMonthReset: {
 
 declare type MetricPeriodMonthReset = (typeof MetricPeriodMonthReset)[keyof typeof MetricPeriodMonthReset];
 
+/**
+ * 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.
+ */
+export declare function normalizeInvoiceQuery(query: InvoiceQuery): InvoiceQuery;
+
 export declare type PendingListenerFn = BooleanListenerFn | EmptyListenerFn;
 
 export declare type PlanListenerFn = CheckPlanReturnListenerFn | EmptyListenerFn;
 
+export declare interface RequestOptions {
+    method?: string;
+    body?: unknown;
+}
+
+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",
@@ -649,9 +1084,9 @@ declare const RuleType_2: {
 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;
@@ -696,6 +1131,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)
@@ -908,6 +1345,27 @@ export declare class Schematic {
     private notifyCreditBalanceListeners;
 }
 
+export declare class SchematicApiError extends Error {
+    readonly status: number;
+    readonly path: string;
+    readonly body: unknown;
+    constructor(status: number, path: string, body: unknown);
+}
+
+export 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 */
 export declare type SchematicContext = {
     company?: Keys;
@@ -964,6 +1422,111 @@ export declare type SchematicOptions = {
     flagCheckDefaults?: Record<string, CheckFlagReturn>;
 };
 
+/**
+ * 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.
+ */
+export 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.
+ */
+export declare function sessionKey(session: Session): string;
+
+export 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;
@@ -971,6 +1534,15 @@ export declare type StoragePersister = {
     removeItem(key: string): void;
 };
 
+/**
+ * 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.
+ */
+export declare const TOKEN_CACHE_SIZE = 10;
+
 /**
  * A flexible key/value type that can store any type of value on a company or user.
  */
@@ -995,4 +1567,35 @@ export declare enum UsagePeriod {
     CURRENT_WEEK = "current_week"
 }
 
+/**
+ * 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 { }