@mesub/react 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,152 @@
+import * as react from 'react';
+import { ReactNode, ButtonHTMLAttributes, HTMLAttributes } from 'react';
+
+/**
+ * What the merchant's routes serve, as `@mesub/node` writes it: snake case,
+ * dates as ISO strings, chain numbers as strings.
+ */
+/** What Mesub knows of a plan's token. Never the merchant's words. */
+interface MesubToken {
+    symbol: string | null;
+    name: string | null;
+    logo_url: string | null;
+    verified: boolean;
+}
+/** A plan, as `GET /plans/:slug` serves it. */
+interface MesubPlan {
+    slug: string;
+    name: string;
+    description: string | null;
+    project_name: string;
+    logo_url: string | null;
+    amount: string;
+    amount_display: string;
+    decimals: number;
+    symbol: string | null;
+    mint: string;
+    token?: MesubToken | null | undefined;
+    amount_usd?: string | null | undefined;
+    period_hours: number;
+    network: 'devnet' | 'mainnet-beta';
+    status: 'active' | 'sunset';
+    available: boolean;
+    ends_at: string | null;
+}
+type MesubSubscriptionStatus = 'pending' | 'active' | 'cancelled' | 'unpaid' | 'stopped' | 'ended' | 'failed' | 'expired' | 'superseded';
+/** Why charges are held back: the merchant's own setup by name, `mesub` for any cause of Mesub's. */
+type MesubBlockedReason = 'puller_not_allowed' | 'receiver_not_allowed' | 'receiver_account_missing' | 'receiver_account_frozen' | 'mint_gone' | 'mesub';
+/**
+ * Why a `stopped` one stopped (Mesub-io/backend#402): every retry failed, the
+ * Free date to pay by passed, or the wallet closed the account that lets
+ * Mesub charge it, for good. A newer one may come.
+ */
+type MesubStopReason = 'out_of_retries' | 'retry_deadline_passed' | 'authority_closed';
+/** A subscription of the signed-in customer, as `GET /subscriptions` lists it. */
+interface MesubSubscription {
+    id: string;
+    status: MesubSubscriptionStatus;
+    paused: boolean;
+    end_reason: string | null;
+    late_reason: string | null;
+    stop_reason?: MesubStopReason | null;
+    access: boolean;
+    payment_status: 'paid' | 'late' | 'none';
+    blocked_since?: string | null;
+    blocked_reason?: MesubBlockedReason | null;
+    plan: string | null;
+    wallet: string;
+    current_period_start: string | null;
+    current_period_end: string | null;
+    next_charge_at: string | null;
+    next_retry_at: string | null;
+    retry_deadline: string | null;
+    access_until: string | null;
+    closable?: boolean;
+    closable_from?: string | null;
+    created_at: string;
+    confirmed_at: string | null;
+}
+/** What a subscription allows now. */
+type MesubAction = 'cancel' | 'resume' | 'close';
+
+type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+
+/** A Wallet Standard chain, such as `solana:mainnet` or `solana:devnet`. */
+type SolanaChain = `solana:${string}`;
+
+type MesubTheme = 'light' | 'dark' | 'auto';
+/** Where a subscribe stands: `open` is the dialog up with nothing being signed. */
+type SubscribeState = 'idle' | 'open' | 'signing' | 'confirming' | 'subscribed';
+
+interface MesubProviderProps {
+    endpoint: string;
+    chain?: SolanaChain | undefined;
+    fetch?: FetchLike | undefined;
+    theme?: MesubTheme | undefined;
+    manageUrl?: string | null | undefined;
+    children?: ReactNode;
+}
+/** Says where the merchant's routes are, and renders the one dialog the hooks open. */
+declare function MesubProvider({ endpoint, chain, fetch, theme, manageUrl, children, }: MesubProviderProps): react.JSX.Element;
+
+interface UseSubscribeOptions {
+    onSubscribed?: ((subscription: MesubSubscription) => void) | undefined;
+}
+/** What `useSubscribe()` returns. */
+interface UseSubscribeResult {
+    state: SubscribeState;
+    subscription: MesubSubscription | null;
+    signature: string | null;
+    subscribe(): Promise<MesubSubscription | null>;
+}
+/** The subscribe flow, for a button of your own: `subscribe()` opens the Mesub checkout. */
+declare function useSubscribe(plan: string, options?: UseSubscribeOptions): UseSubscribeResult;
+interface SubscribeButtonProps extends UseSubscribeOptions, ButtonHTMLAttributes<HTMLButtonElement> {
+    plan: string;
+}
+/**
+ * Opens the Mesub checkout for a plan. Busy is aria-disabled, not disabled, so
+ * the keyboard focus stays on it; only subscribed disables it.
+ */
+declare const SubscribeButton: react.ForwardRefExoticComponent<SubscribeButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+/** A subscription the customer holds, with what it allows now. */
+interface MesubHeldSubscription extends MesubSubscription {
+    action: MesubAction | null;
+    payable: boolean;
+}
+/** What a "Pay now" came to, in the words the widget shows. */
+interface PayNowResult {
+    ok: boolean;
+    message: string;
+    retryAfter?: number;
+}
+/** What `useSubscriptions()` returns. */
+interface UseSubscriptionsResult {
+    state: 'loading' | 'ready' | 'signed-out' | 'error';
+    subscriptions: MesubHeldSubscription[];
+    error: string | null;
+    reload(): Promise<void>;
+    payNow(id: string): Promise<PayNowResult>;
+    manage(id: string): Promise<MesubSubscription | null>;
+}
+/** The signed-in customer's subscriptions, read from the merchant's server, and what each allows. */
+declare function useSubscriptions(): UseSubscriptionsResult;
+interface ManageSubscriptionsProps extends HTMLAttributes<HTMLDivElement> {
+    onChanged?: ((subscription: MesubSubscription) => void) | undefined;
+}
+/**
+ * The signed-in customer's subscriptions, each with its status, its next date
+ * and the one thing it allows now. Styled by its data-mesub-* attributes.
+ */
+declare function ManageSubscriptions({ onChanged, ...rest }: ManageSubscriptionsProps): react.JSX.Element;
+interface ManageButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    plan?: string | undefined;
+}
+/**
+ * Opens the customer's subscription to a plan in the Mesub window: how it
+ * stands, what comes next, what was charged, and cancel, resume or close.
+ */
+declare const ManageButton: react.ForwardRefExoticComponent<ManageButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+export { type FetchLike, ManageButton, type ManageButtonProps, ManageSubscriptions, type ManageSubscriptionsProps, type MesubAction, type MesubBlockedReason, type MesubHeldSubscription, type MesubPlan, MesubProvider, type MesubProviderProps, type MesubStopReason, type MesubSubscription, type MesubSubscriptionStatus, type MesubTheme, type MesubToken, type PayNowResult, type SolanaChain, SubscribeButton, type SubscribeButtonProps, type SubscribeState, type UseSubscribeOptions, type UseSubscribeResult, type UseSubscriptionsResult, useSubscribe, useSubscriptions };

package/dist/index.d.ts

@@ -0,0 +1,152 @@
+import * as react from 'react';
+import { ReactNode, ButtonHTMLAttributes, HTMLAttributes } from 'react';
+
+/**
+ * What the merchant's routes serve, as `@mesub/node` writes it: snake case,
+ * dates as ISO strings, chain numbers as strings.
+ */
+/** What Mesub knows of a plan's token. Never the merchant's words. */
+interface MesubToken {
+    symbol: string | null;
+    name: string | null;
+    logo_url: string | null;
+    verified: boolean;
+}
+/** A plan, as `GET /plans/:slug` serves it. */
+interface MesubPlan {
+    slug: string;
+    name: string;
+    description: string | null;
+    project_name: string;
+    logo_url: string | null;
+    amount: string;
+    amount_display: string;
+    decimals: number;
+    symbol: string | null;
+    mint: string;
+    token?: MesubToken | null | undefined;
+    amount_usd?: string | null | undefined;
+    period_hours: number;
+    network: 'devnet' | 'mainnet-beta';
+    status: 'active' | 'sunset';
+    available: boolean;
+    ends_at: string | null;
+}
+type MesubSubscriptionStatus = 'pending' | 'active' | 'cancelled' | 'unpaid' | 'stopped' | 'ended' | 'failed' | 'expired' | 'superseded';
+/** Why charges are held back: the merchant's own setup by name, `mesub` for any cause of Mesub's. */
+type MesubBlockedReason = 'puller_not_allowed' | 'receiver_not_allowed' | 'receiver_account_missing' | 'receiver_account_frozen' | 'mint_gone' | 'mesub';
+/**
+ * Why a `stopped` one stopped (Mesub-io/backend#402): every retry failed, the
+ * Free date to pay by passed, or the wallet closed the account that lets
+ * Mesub charge it, for good. A newer one may come.
+ */
+type MesubStopReason = 'out_of_retries' | 'retry_deadline_passed' | 'authority_closed';
+/** A subscription of the signed-in customer, as `GET /subscriptions` lists it. */
+interface MesubSubscription {
+    id: string;
+    status: MesubSubscriptionStatus;
+    paused: boolean;
+    end_reason: string | null;
+    late_reason: string | null;
+    stop_reason?: MesubStopReason | null;
+    access: boolean;
+    payment_status: 'paid' | 'late' | 'none';
+    blocked_since?: string | null;
+    blocked_reason?: MesubBlockedReason | null;
+    plan: string | null;
+    wallet: string;
+    current_period_start: string | null;
+    current_period_end: string | null;
+    next_charge_at: string | null;
+    next_retry_at: string | null;
+    retry_deadline: string | null;
+    access_until: string | null;
+    closable?: boolean;
+    closable_from?: string | null;
+    created_at: string;
+    confirmed_at: string | null;
+}
+/** What a subscription allows now. */
+type MesubAction = 'cancel' | 'resume' | 'close';
+
+type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+
+/** A Wallet Standard chain, such as `solana:mainnet` or `solana:devnet`. */
+type SolanaChain = `solana:${string}`;
+
+type MesubTheme = 'light' | 'dark' | 'auto';
+/** Where a subscribe stands: `open` is the dialog up with nothing being signed. */
+type SubscribeState = 'idle' | 'open' | 'signing' | 'confirming' | 'subscribed';
+
+interface MesubProviderProps {
+    endpoint: string;
+    chain?: SolanaChain | undefined;
+    fetch?: FetchLike | undefined;
+    theme?: MesubTheme | undefined;
+    manageUrl?: string | null | undefined;
+    children?: ReactNode;
+}
+/** Says where the merchant's routes are, and renders the one dialog the hooks open. */
+declare function MesubProvider({ endpoint, chain, fetch, theme, manageUrl, children, }: MesubProviderProps): react.JSX.Element;
+
+interface UseSubscribeOptions {
+    onSubscribed?: ((subscription: MesubSubscription) => void) | undefined;
+}
+/** What `useSubscribe()` returns. */
+interface UseSubscribeResult {
+    state: SubscribeState;
+    subscription: MesubSubscription | null;
+    signature: string | null;
+    subscribe(): Promise<MesubSubscription | null>;
+}
+/** The subscribe flow, for a button of your own: `subscribe()` opens the Mesub checkout. */
+declare function useSubscribe(plan: string, options?: UseSubscribeOptions): UseSubscribeResult;
+interface SubscribeButtonProps extends UseSubscribeOptions, ButtonHTMLAttributes<HTMLButtonElement> {
+    plan: string;
+}
+/**
+ * Opens the Mesub checkout for a plan. Busy is aria-disabled, not disabled, so
+ * the keyboard focus stays on it; only subscribed disables it.
+ */
+declare const SubscribeButton: react.ForwardRefExoticComponent<SubscribeButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+/** A subscription the customer holds, with what it allows now. */
+interface MesubHeldSubscription extends MesubSubscription {
+    action: MesubAction | null;
+    payable: boolean;
+}
+/** What a "Pay now" came to, in the words the widget shows. */
+interface PayNowResult {
+    ok: boolean;
+    message: string;
+    retryAfter?: number;
+}
+/** What `useSubscriptions()` returns. */
+interface UseSubscriptionsResult {
+    state: 'loading' | 'ready' | 'signed-out' | 'error';
+    subscriptions: MesubHeldSubscription[];
+    error: string | null;
+    reload(): Promise<void>;
+    payNow(id: string): Promise<PayNowResult>;
+    manage(id: string): Promise<MesubSubscription | null>;
+}
+/** The signed-in customer's subscriptions, read from the merchant's server, and what each allows. */
+declare function useSubscriptions(): UseSubscriptionsResult;
+interface ManageSubscriptionsProps extends HTMLAttributes<HTMLDivElement> {
+    onChanged?: ((subscription: MesubSubscription) => void) | undefined;
+}
+/**
+ * The signed-in customer's subscriptions, each with its status, its next date
+ * and the one thing it allows now. Styled by its data-mesub-* attributes.
+ */
+declare function ManageSubscriptions({ onChanged, ...rest }: ManageSubscriptionsProps): react.JSX.Element;
+interface ManageButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    plan?: string | undefined;
+}
+/**
+ * Opens the customer's subscription to a plan in the Mesub window: how it
+ * stands, what comes next, what was charged, and cancel, resume or close.
+ */
+declare const ManageButton: react.ForwardRefExoticComponent<ManageButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+export { type FetchLike, ManageButton, type ManageButtonProps, ManageSubscriptions, type ManageSubscriptionsProps, type MesubAction, type MesubBlockedReason, type MesubHeldSubscription, type MesubPlan, MesubProvider, type MesubProviderProps, type MesubStopReason, type MesubSubscription, type MesubSubscriptionStatus, type MesubTheme, type MesubToken, type PayNowResult, type SolanaChain, SubscribeButton, type SubscribeButtonProps, type SubscribeState, type UseSubscribeOptions, type UseSubscribeResult, type UseSubscriptionsResult, useSubscribe, useSubscriptions };