@mesub/node 0.0.0-stage → 0.1.0

package/dist/subscriptions-D1hE7MUc.d.cts

@@ -0,0 +1,768 @@
+/**
+ * What `GET /v1/access` answers, copied from the back's `AccessAnswer`, which
+ * stays the source of truth. The contract test of #8 checks the two agree.
+ * Snake case, as the API serves it.
+ */
+/**
+ * `superseded` is a stopped subscription the wallet came back over
+ * (Mesub-io/backend#213): the row that replaced it is the one in force, so
+ * `/v1/access` answers that one, but the back's type allows it.
+ *
+ * `cancelled` only while the cancellation runs: once its end date passed it
+ * reads `ended`, with `end_reason` `cancelled` (Mesub-io/backend#236).
+ *
+ * For a few minutes past a plan's end, `active` or `unpaid` is still read
+ * with `access` false, until Mesub ends the row: a guard reads `access`.
+ */
+type SubscriptionStatus = 'pending' | 'active' | 'cancelled' | 'unpaid' | 'stopped' | 'ended' | 'failed' | 'superseded' | 'none';
+/** `late` only while a pull failed and a retry is pending. */
+type PaymentStatus = 'paid' | 'late' | 'none';
+/**
+ * Why a subscription ended (Mesub-io/backend#236): cancelled and past its end
+ * date, the plan deleted, replaced by another at its address or past its own
+ * end, its subscription account closed outside Mesub (`closed_elsewhere`) or
+ * through it (`closed`). `authority_closed` is what Mesub served for
+ * `closed_elsewhere` before Mesub-io/backend#476: read the same way, it goes
+ * once no Mesub serves it.
+ */
+type EndReason = 'cancelled' | 'plan_removed' | 'plan_replaced' | 'plan_ended' | 'closed_elsewhere' | 'authority_closed' | 'closed';
+/**
+ * Why a payment is late (Mesub-io/backend#264), as the last failed pull found
+ * it: the wallet holds too little (adding funds fixes it), Mesub's approval on
+ * the token account was revoked or replaced by another app's (adding funds
+ * does not fix it), or the wallet's authorisation was closed, which is final.
+ */
+type LateReason = 'insufficient_balance' | 'approval_revoked' | 'authority_closed';
+/**
+ * Why a subscription stopped (Mesub-io/backend#402): every retry of the
+ * missed payment failed (`out_of_retries`), on Free the last day to pay it
+ * passed (`retry_deadline_passed`), or the wallet closed its subscription
+ * authority for good (`authority_closed`). After the first two the
+ * subscription stays open on chain and the subscriber can come back over it;
+ * after the third nobody can charge it again, the subscriber cannot come
+ * back over it, and can close it at once (`closable`).
+ */
+type StopReason = 'out_of_retries' | 'retry_deadline_passed' | 'authority_closed';
+/**
+ * Why every charge of a subscription is blocked, none of it the subscriber's
+ * doing (Mesub-io/backend#398). The merchant's own setup, theirs to fix, by
+ * name: Mesub's puller taken off the plan on chain, a receiving wallet that
+ * is not in the plan's destinations, has no token account for the plan's
+ * token or whose token account is frozen (Mesub-io/backend#395), a token
+ * that no longer exists. `mesub` for every cause of Mesub's.
+ */
+type BlockedReason = 'puller_not_allowed' | 'receiver_not_allowed' | 'receiver_account_missing' | 'receiver_account_frozen' | 'mint_gone' | 'mesub';
+/**
+ * `blocked` is a pull nothing was tried for, none of it the subscriber's
+ * doing (Mesub's fee payer, the network): it never counts against them.
+ */
+type PullOutcome = 'paid' | 'skipped' | 'rejected' | 'blocked';
+/** One pull attempt, newest first, as the subscriber it concerns may see it. */
+interface ServedAttempt {
+    outcome: PullOutcome;
+    /**
+     * Mesub's short reason, null on a paid one: snake case
+     * (`insufficient_balance`) since Mesub-io/backend#475. An open string:
+     * besides the named ones, two families carry a code, `program_${number}`
+     * (a program refused the transfer, `program_4`) and `solana_${number}`
+     * (any other failure, `solana_7050005`), and new names get added.
+     */
+    reason: string | null;
+    /** In the mint's smallest unit, as a string: a u64 does not survive JSON. */
+    amount: string;
+    attempted_at: string;
+    signature: string | null;
+}
+interface AccessAnswer {
+    /**
+     * The wallet the answer is about. Asked by external id or email, the one
+     * that pays, and null when the customer has nothing on this plan.
+     */
+    wallet: string | null;
+    plan: string;
+    /**
+     * The subscription this answer is about (Mesub-io/backend#469), the one
+     * to `cancel`, `resume`, `close` or `retry` without listing the
+     * customer's subscriptions first. Null with `status` `none`. Read as null
+     * from a back that predates it.
+     */
+    subscription_id: string | null;
+    /**
+     * The only field a guard needs. False from the plan's end on, for a plan
+     * that has one, whatever `status` still reads.
+     */
+    access: boolean;
+    status: SubscriptionStatus;
+    /**
+     * A seat parked over the project's cap (Mesub-io/backend#236): `status`
+     * stays as it was, nothing is charged, and access runs to the end of the
+     * paid period. Read as false from a back that predates it.
+     */
+    paused: boolean;
+    /**
+     * Why it ended, only when `status` is `ended`; null on one that ended
+     * before the back recorded reasons. Read as null from a back that
+     * predates it.
+     */
+    end_reason: EndReason | null;
+    /**
+     * Why it is late, when `status` is `unpaid`, or `stopped` for the payment
+     * it stopped on; null on a refusal Mesub cannot place.
+     */
+    late_reason: LateReason | null;
+    /**
+     * Why it stopped, only when `status` is `stopped`; null on one that
+     * stopped before Mesub recorded why. Read as null from a back that
+     * predates it (Mesub-io/backend#402).
+     */
+    stop_reason: StopReason | null;
+    /** `none` on a paused seat: nothing is billed, so nothing is late. */
+    payment_status: PaymentStatus;
+    /**
+     * Since when every charge is blocked for a reason that is not the
+     * subscriber's (Mesub-io/backend#398), and whose cause it is; both null
+     * unless blocked. `status` and `payment_status` do not move for it, and
+     * Mesub keeps trying. `access` does: it ends at `access_until`, the end
+     * of the period after the one paid for, or sooner under a cause of the
+     * merchant's setup, and comes back with the first charge that goes
+     * through, nothing to sign. Read as null from a back that predates them.
+     */
+    blocked_since: string | null;
+    blocked_reason: BlockedReason | null;
+    subscribed_since: string | null;
+    first_subscribed_at: string | null;
+    current_period_end: string | null;
+    cancelled_at: string | null;
+    /**
+     * When access ends unless a pull renews it; null while `access` is false.
+     * Never later than the plan's end, where access stops for everyone, the
+     * last period being charged in full all the same. On a blocked one
+     * (`blocked_since`), when access ends if nothing is collected by then.
+     */
+    access_until: string | null;
+    /**
+     * A pull Mesub will run: the next charge, or the next retry on a late
+     * one, never both. Neither once the plan's end leaves no pull to run
+     * (Mesub-io/backend#362): the last period has no `next_charge_at`.
+     */
+    next_charge_at: string | null;
+    next_retry_at: string | null;
+    /**
+     * Free only (Mesub-io/backend#191): when hand retries of a missed pull
+     * close, two minutes before the end of its period, or the plan's end
+     * when that comes first; past it the subscription stops. Null on every
+     * other tier, whose retries are in `next_retry_at`. Read as null from a
+     * back that predates it. Like
+     * `paused` and `end_reason`, undefined only on an answer cached by an
+     * older SDK.
+     */
+    retry_deadline: string | null;
+    /**
+     * Whether the subscriber can close the subscription on chain now, which
+     * returns its deposit to their wallet (Mesub-io/backend#402): a
+     * cancellation past its end, one ended with its plan, or one stopped
+     * with `stop_reason` `authority_closed`. As Mesub last read the chain:
+     * `close` reads it again, and may still refuse. Read as false from a back
+     * that predates it.
+     */
+    closable: boolean;
+    /**
+     * When it can be closed, if not now: the end of the period a
+     * cancellation set. Null when `closable` is true, and when no date is
+     * known yet (a running one, or one stopped with `out_of_retries`, is
+     * cancelled first). Read as null from a back that predates it.
+     */
+    closable_from: string | null;
+    /** Only when asked for with `{ attempts: true }`. */
+    attempts?: ServedAttempt[];
+    /** Seconds this answer stays true: how long it is cached. */
+    revalidate_after: number;
+}
+/**
+ * Every plan of the project a customer has, when no plan is named: what
+ * `accessList` answers. Plans they never subscribed to are left out.
+ */
+interface AccessList {
+    plans: AccessAnswer[];
+    /** The soonest of the plans', so one cached list goes stale with its first. */
+    revalidate_after: number;
+}
+/**
+ * Who an access question is about: exactly one of the wallet that pays, your
+ * own id for the customer (the `external_id` given at checkout), or the email
+ * given at checkout. A string alone is a wallet, as before.
+ */
+type Customer = {
+    wallet: string;
+} | {
+    external_id: string;
+} | {
+    email: string;
+};
+interface AccessOptions {
+    /** Also answer the last pull attempts. Skips the cache both ways. */
+    attempts?: boolean;
+}
+
+type QueryValue = string | number | boolean | undefined;
+interface TransportConfig {
+    apiKey: string;
+    baseUrl: string;
+    /** Sent with every call, before the SDK's own, which they never replace. */
+    headers: Record<string, string>;
+    fetch: typeof fetch;
+    timeout: number;
+    maxRetries: number;
+}
+/** What any one call may set for itself. */
+interface RequestOptions {
+    /** Per attempt, in milliseconds. Defaults to the client's `timeout`. */
+    timeout?: number;
+    /**
+     * Stops the call, and any wait for a retry: it then rejects with the
+     * signal's reason, and is never sent again.
+     */
+    signal?: AbortSignal;
+}
+/** What one GET may change from the client's configuration. */
+interface CallOptions extends RequestOptions {
+    maxRetries?: number;
+    /**
+     * Epoch ms by which the call settles, retries and waits included: each
+     * attempt is cut at it, and a wait that would outlast it is not waited.
+     */
+    deadline?: number;
+    /**
+     * False to throw a 429 at once, whatever it asks: a guard falls back
+     * rather than wait for the rate limit, and send more on top of it.
+     */
+    retryRateLimited?: boolean;
+}
+/** @internal Authenticated JSON calls to the Mesub API, with timeouts and retries. */
+declare class Transport {
+    #private;
+    constructor(config: TransportConfig);
+    get(path: string, query?: Record<string, QueryValue>, options?: CallOptions): Promise<unknown>;
+    /**
+     * A POST with a JSON body, sent once: never retried here, whatever the
+     * status, a timeout or a network error. A write that got no answer may
+     * still have been done: its caller decides, knowing the route, whether
+     * the same body may be sent again (`submit` does, Mesub-io/backend#190)
+     * or the state read back.
+     */
+    post(path: string, body: unknown, options?: Omit<CallOptions, 'maxRetries'>): Promise<unknown>;
+}
+
+/**
+ * Subscribing from your own server, with the API key (Mesub-io/backend#143):
+ * `POST /v1/subscriptions`, a fresh transaction, its submit, the reads, and what stops one
+ * (Mesub-io/backend#276): cancel, resume and close. The types copy the
+ * back's `server-subscriptions.service.ts`, which stays the source of truth.
+ * Snake case, as the API serves it.
+ */
+/**
+ * A subscription's status. Unlike `/v1/access`, may be `expired`: a checkout
+ * nobody signed (Mesub-io/backend#139). `superseded` is a stopped one the
+ * wallet came back over (Mesub-io/backend#213): a newer row holds the
+ * subscription. Never `none`: a row exists. `cancelled` reads `ended` once
+ * its end date passed, as on `/v1/access` (Mesub-io/backend#236).
+ */
+type ServerSubscriptionStatus = 'pending' | 'active' | 'cancelled' | 'unpaid' | 'stopped' | 'ended' | 'failed' | 'expired' | 'superseded';
+/** One subscription to your project's plans, as `GET /v1/subscriptions/:id` answers it. */
+interface ServerSubscription {
+    id: string;
+    status: ServerSubscriptionStatus;
+    /** A seat parked over the project's cap, status unchanged, as `/v1/access` answers it. */
+    paused: boolean;
+    /** Why it ended, only on `ended`, as `/v1/access` answers it. */
+    end_reason: EndReason | null;
+    /** Why it is late, on `unpaid` or `stopped`, as `/v1/access` answers it. */
+    late_reason: LateReason | null;
+    /** Why it stopped, only on `stopped`, as `/v1/access` answers it. */
+    stop_reason: StopReason | null;
+    /** Whether it grants access now, as `/v1/access` answers it. */
+    access: boolean;
+    /** `paid`, `late` or `none`, as `/v1/access` answers it. */
+    payment_status: PaymentStatus;
+    /**
+     * Since when its charges are blocked for a reason that is not the
+     * subscriber's, and whose cause it is, as `/v1/access` answers them
+     * (Mesub-io/backend#398): both null unless blocked. Read as null from a
+     * back that predates them.
+     */
+    blocked_since: string | null;
+    blocked_reason: BlockedReason | null;
+    /** The plan's slug. */
+    plan: string | null;
+    wallet: string;
+    email: string | null;
+    external_id: string | null;
+    /** The period paid for last; null before the first. */
+    current_period_start: string | null;
+    current_period_end: string | null;
+    /**
+     * The next charge on a running one, the next retry on a late one: never
+     * both, and neither once the plan's end leaves no pull to run.
+     */
+    next_charge_at: string | null;
+    next_retry_at: string | null;
+    /**
+     * Free only, as `/v1/access` answers it (Mesub-io/backend#191): when hand
+     * retries close, the plan's end when that comes first; past it the
+     * subscription stops. Read as null from a back that predates it.
+     */
+    retry_deadline: string | null;
+    /**
+     * The retry due at `next_retry_at` and how many the missed period gets
+     * (Mesub-io/backend#289): 2 and 3 before the second retry of three. Both
+     * null unless Mesub retries on its own: not late, paused, stopped, on
+     * Free, or on a plan that ends before the retry. Read as null from a
+     * back that predates them.
+     */
+    next_retry_number: number | null;
+    retries_allowed: number | null;
+    /**
+     * When access ends unless a pull renews it; null while `access` is false.
+     * Never later than the plan's end.
+     */
+    access_until: string | null;
+    /** Whether the subscriber can close it now, as `/v1/access` answers it. */
+    closable: boolean;
+    /** When it can be closed, if not now and a date is known, as `/v1/access` answers it. */
+    closable_from: string | null;
+    created_at: string;
+    confirmed_at: string | null;
+}
+/** What subscribing costs in SOL, in lamports, as strings: a u64 does not survive JSON. */
+interface SubscribeCosts {
+    /** Given back to the subscriber when the accounts are closed. `authority` is null if it exists. */
+    rent: {
+        subscription: string;
+        authority: string | null;
+        total: string;
+    };
+    /** Spent: the network's fee per signature, the wallet's and Mesub's. */
+    fee: {
+        signatures: number;
+        per_signature: string;
+        priority: string;
+        total: string;
+    };
+    total: string;
+}
+/** What `create` and `transaction` answer: what the wallet signs, terms first, then the transaction. */
+interface SubscribeTransaction {
+    subscription: {
+        id: string;
+        status: ServerSubscriptionStatus;
+    };
+    /** Base64, signed by nobody: the wallet signs it with signTransaction, without sending it. */
+    transaction: string;
+    last_valid_block_height: string;
+    /**
+     * When `last_valid_block_height` is expected to pass, about half a minute
+     * after the answer (Mesub-io/backend#471): an estimate that errs early,
+     * for a countdown or to ask `transaction` for a fresh one in time. The
+     * height is the truth: rebuild after `transaction_expired`, before this
+     * time as after it. Null from a back that predates it.
+     */
+    transaction_expires_at: string | null;
+    costs: SubscribeCosts;
+    /** Signed as is with the wallet's signMessage, over its UTF-8 bytes, before `expires_at`. */
+    terms: {
+        message: string;
+        expires_at: string;
+    };
+}
+/**
+ * What `submit` settled on: what Mesub answered, or, when its answer was lost
+ * and the subscription read back is `active` or `cancelled`, that one.
+ */
+interface SubmitResult {
+    /**
+     * `active`, or `cancelled` if the wallet set an end (`ended` once that
+     * end passed); `pending` or `failed` with a `reason`.
+     */
+    subscription: ServerSubscription;
+    /**
+     * Mesub's own, set when nothing landed (`pending`) or what landed is not
+     * Mesub's (`failed`). Never made up by the SDK. A sentence for a person,
+     * which Mesub may reword: branch on `reason_code`.
+     */
+    reason?: string;
+    /** Why, for a program: set exactly when `reason` is, from a back that serves it. */
+    reason_code?: ConfirmReasonCode;
+}
+/**
+ * What `cancel`, `resume` and `close` answer: a transaction only the wallet
+ * signs, and sends itself. Mesub signs nothing of it.
+ */
+interface WalletTransaction {
+    /** Base64, signed by nobody: the wallet signs and sends it, then names its signature. */
+    transaction: string;
+    /** The block height past which it can no longer land. */
+    last_valid_block_height: string;
+    /** When that height is expected to pass, as `SubscribeTransaction` says it. */
+    transaction_expires_at: string | null;
+}
+/** What the wallet answered when it sent the transaction of `cancel`, `resume` or `close`. */
+interface ConfirmParams {
+    /** The transaction's signature, base58. */
+    signature: string;
+}
+/** What `confirmCancel`, `confirmResume` and `confirmClose` settled on. */
+interface ConfirmResult {
+    /** The subscription as it is now: moved, or as it was with a `reason`. */
+    subscription: ServerSubscription;
+    /**
+     * Mesub's own, set when nothing changed: the transaction failed, expired
+     * before it landed, or the subscription moved on meanwhile. A sentence
+     * for a person, which Mesub may reword: branch on `reason_code`.
+     */
+    reason?: string;
+    /** Why, for a program: set exactly when `reason` is, from a back that serves it. */
+    reason_code?: ConfirmReasonCode;
+}
+/**
+ * Why a submit or a confirm settled nothing, or not what was built
+ * (Mesub-io/backend#470): stable, snake case, never reworded. An open family:
+ * Mesub adds codes, so keep a default branch; one newer than this release is
+ * handed on as it is.
+ *
+ * - `not_our_transaction`: not a transaction Mesub co-signed over terms the
+ *   wallet signed for this subscription.
+ * - `transaction_failed`: it landed and the chain refused it.
+ * - `transaction_expired`: its blockhash ran out before it landed.
+ * - `nothing_landed`: on a submit, nothing stands at its address yet.
+ * - `subscription_not_on_chain`: on a cancel or a resume, it is gone on chain.
+ * - `subscription_mismatch`: what landed names another wallet, plan, amount
+ *   or period: now `failed`.
+ * - `dev_not_running`: Mesub's own Dev plan landed cancelled or part paid.
+ * - `earlier_subscription_running`: a comeback paid while the one it came
+ *   back over ran again.
+ * - `subscription_remade`: on a submit, closed and made again without Mesub.
+ * - `cancellation_not_landed`, `resume_not_landed`, `close_not_landed`: the
+ *   chain does not show the action.
+ * - `subscription_changed`: it moved on while the cancellation was read.
+ * - `subscription_not_cancelled`: on a resume, nothing to resume.
+ * - `cancelled_subscription_remade`: on a resume, closed and made again
+ *   without Mesub: it stays `cancelled`.
+ * - `resume_unverified`: on a resume, the one on chain cannot be told to be
+ *   the one cancelled: it stays `cancelled`.
+ */
+type ConfirmReasonCode = 'not_our_transaction' | 'transaction_failed' | 'transaction_expired' | 'nothing_landed' | 'subscription_not_on_chain' | 'subscription_mismatch' | 'dev_not_running' | 'earlier_subscription_running' | 'subscription_remade' | 'cancellation_not_landed' | 'resume_not_landed' | 'close_not_landed' | 'subscription_changed' | 'subscription_not_cancelled' | 'cancelled_subscription_remade' | 'resume_unverified' | (string & {});
+/** One page of a customer's subscriptions, newest first. */
+interface ServerSubscriptionList {
+    data: ServerSubscription[];
+    /** Ask for the next page with `starting_after` set to the last id of this one. */
+    has_more: boolean;
+}
+/**
+ * One pull attempt of a subscription, as `GET /v1/subscriptions/:id/attempts`
+ * answers it (Mesub-io/backend#289): an attempt of `/v1/access`, with its id,
+ * whether it was a retry and the period it was for.
+ */
+interface SubscriptionAttempt {
+    id: string;
+    attempted_at: string;
+    /** One of `PullOutcome` today; a newer one is handed on as is. */
+    outcome: PullOutcome;
+    /**
+     * Mesub's short reason, null on a paid one, as on `ServedAttempt`: snake
+     * case, an open string with the `program_${number}` and
+     * `solana_${number}` families.
+     */
+    reason: string | null;
+    /**
+     * In the mint's smallest unit, as a string. What was asked for; on a
+     * `paid` one that is what the transfer moved.
+     */
+    amount: string;
+    /**
+     * That amount in dollars at the price of the instant it was attempted, a
+     * decimal string such as `"9.99"`. Null until Mesub priced it, when it
+     * knows no price, and from a Mesub that predates it.
+     */
+    amount_usd: string | null;
+    /** The transaction that paid. Null on every outcome but `paid`, a refused one included. */
+    signature: string | null;
+    /** The subscription had already failed on this period. */
+    retry: boolean;
+    /**
+     * On a retry of the plan's, which one and out of how many, as recorded
+     * when it ran: 1 is the first after the missed charge. Both null on a
+     * first try, on a hand retry on Dev or Business, on an attempt that kept
+     * none, and from a back that does not serve them.
+     */
+    retry_number: number | null;
+    retries_allowed: number | null;
+    /** The start of the period it was for; null when Mesub recorded none. */
+    period_start: string | null;
+}
+/** One page of a subscription's attempts, newest first, and what it paid in all. */
+interface SubscriptionAttemptList {
+    data: SubscriptionAttempt[];
+    /** Ask for the next page with `starting_after` set to the last id of this one. */
+    has_more: boolean;
+    /**
+     * Its `paid` attempts since it began and the sum of what they moved, in
+     * the mint's smallest unit: counted by Mesub over all of them, not this page.
+     */
+    paid: {
+        count: number;
+        amount: string;
+    };
+}
+/** Which page of a subscription's attempts. */
+interface AttemptsParams {
+    /** 1 to 100, 20 by default. */
+    limit?: number;
+    /** The id of the last attempt of the previous page. */
+    starting_after?: string;
+}
+interface SubscribeParams {
+    /** The plan's slug. */
+    plan: string;
+    /** The wallet that signs and pays. */
+    wallet: string;
+    /** Where the subscriber's notices go. Not verified by Mesub. */
+    email?: string;
+    /** Your own id for this customer, handed back as given. */
+    external_id?: string;
+}
+interface SubmitParams {
+    /** The transaction of `create`, signed by the wallet, base64. */
+    transaction: string;
+    /** The wallet's signMessage over `terms.message`, base58. */
+    terms_signature: string;
+}
+interface SubmitOptions extends RequestOptions {
+    /**
+     * Per send, in milliseconds: 90 s by default. Lower it behind a proxy
+     * or a function with a shorter limit (Cloudflare cuts at 100 s); a send
+     * cut short may still be co-signed and land, so read the subscription
+     * back afterwards.
+     */
+    timeout?: number;
+    /**
+     * The whole submit in milliseconds, its sends and the waits between
+     * them: `timeout` plus 30 s by default, so 120 s. A send is cut at it,
+     * and a wait that would outlast it is not waited. Reading the
+     * subscription back once it is spent takes 10 s more at most, retries
+     * included: 130 s in all by default.
+     */
+    budget?: number;
+}
+interface ConfirmOptions extends RequestOptions {
+    /**
+     * In milliseconds: 90 s by default. Mesub waits for the transaction to
+     * land or its blockhash to expire, about a minute. A confirm cut short
+     * changed nothing: send it again with the same signature.
+     */
+    timeout?: number;
+}
+/**
+ * Whose subscriptions to list: a `Customer`, named exactly one way and
+ * normalised as `access` names them, and what narrows the page.
+ */
+type ListParams = Customer & {
+    /** Only this plan's, by slug. */
+    plan?: string;
+    /** 1 to 100, 20 by default. */
+    limit?: number;
+    /** The id of the last subscription of the previous page. */
+    starting_after?: string;
+};
+declare class Subscriptions {
+    #private;
+    /** @internal */
+    constructor(transport: Transport, seen?: (subscription: ServerSubscription) => Promise<void>, changed?: (subscription: ServerSubscription) => Promise<void>);
+    /**
+     * Reserves a subscription to that plan for that wallet, and builds what
+     * it signs: `terms.message`, then `transaction`. Hand both to your front,
+     * then their signatures to `submit`. Called again for the same plan,
+     * wallet and customer (`external_id`, else `email`) while nothing landed,
+     * it answers the same subscription with a fresh transaction; by its id,
+     * `transaction` does. Another
+     * customer naming that wallet gets a subscription of its own
+     * (Mesub-io/backend#311): only the one the wallet signs for lands, and
+     * the others then expire. Sent once, never retried.
+     */
+    create(params: SubscribeParams, options?: RequestOptions): Promise<SubscribeTransaction>;
+    /**
+     * Relays what the wallet signed. Mesub checks it, co-signs, sends it and
+     * waits for the chain, so one send takes up to a minute or so: 90 s
+     * unless `options.timeout` says otherwise.
+     *
+     * When the send gets no answer that says what became of it (a timeout,
+     * a network error, a 5xx), or an error Mesub marks `retryable`, the same
+     * request, the same body, is sent again, up to twice, after the
+     * `Retry-After` Mesub asked for or 10 s, within `options.budget` (120 s
+     * by default). That is safe since Mesub-io/backend#190 and #202: Mesub
+     * recognises the transaction and the terms signature it already
+     * co-signed, signs nothing again, and answers from the chain or from the
+     * subscription it settled. Its answer is then returned as if the first
+     * send had got it, a `pending` with Mesub's own `reason` included.
+     *
+     * When no send got an answer, the subscription is read back once, within
+     * 10 s: it is returned if `active` or `cancelled` (it landed), and
+     * otherwise a `MesubSubmitError` `unavailable` is thrown with it attached
+     * as `subscription` (null if that read failed too): the wallet may have
+     * paid and the transaction may still land, so read it again with
+     * `retrieve` rather than create anew. A 2xx this SDK cannot read is read
+     * back the same way, and thrown as `unexpected`; so is a replay refused
+     * with `not_awaiting_signature` after a send that got no answer, thrown
+     * as that `conflict`.
+     *
+     * A 503 `unavailable` (too many submits waiting on the project,
+     * Mesub-io/backend#505) says nothing was signed or sent: it is replayed
+     * after its `Retry-After` (2 s) like any retryable refusal, and when the
+     * replays run out it is thrown as is, `retryable`, with no read back,
+     * unless an earlier send got no answer.
+     *
+     * Any other refusal (`terms_expired`, `transaction_expired`, ...) is
+     * thrown as is. After `transaction_expired` nothing was sent and the same
+     * submit cannot land: call `transaction(id)` for a new one, never
+     * `create` again.
+     * An abort through `options.signal` stops everything, sends, waits and
+     * the read back, and rejects with the signal's reason; a send already out
+     * may have been co-signed, so read the subscription back.
+     *
+     * A subscription returned with `access` (`active`, or `cancelled` before
+     * its end) drops the `/v1/access` answers cached for that customer (its
+     * wallet, external id and email) that still say no: `hasAccess` right
+     * after asks Mesub again.
+     */
+    submit(id: string, params: SubmitParams, options?: SubmitOptions): Promise<SubmitResult>;
+    /**
+     * A fresh transaction for a subscription still `pending`, with the terms
+     * it names (Mesub-io/backend#427). A transaction lives about half a
+     * minute, the terms five: have the terms signed first, call this when the
+     * wallet is ready, have it sign the transaction at once, then `submit`.
+     * Always sign the transaction of the last call. It is also what follows
+     * a submit refused with `transaction_expired`.
+     *
+     * A terms signature you hold is still good when `terms.message` is, to
+     * the letter, the message the wallet signed. Another text is new terms:
+     * have the wallet sign it, the old signature is refused
+     * (`invalid_terms_signature`).
+     *
+     * Reserves nothing and sends no body: the wallet, the plan and the
+     * customer are the subscription's own. Refused with `apiCode`
+     * `not_awaiting_signature` once it is signed, expired or ended (call
+     * `create` again for an expired one), and with what `create` refuses of
+     * a plan or a wallet (`plan_ended`, `insufficient_balance`,
+     * `already_subscribed`, ...). Sent once, never retried: asking twice is
+     * safe, only the last transaction is to be signed.
+     */
+    transaction(id: string, options?: RequestOptions): Promise<SubscribeTransaction>;
+    /**
+     * Builds the transaction that cancels an `active`, `unpaid` or `stopped`
+     * subscription. Hand it to your front: the subscription's wallet signs
+     * and sends it, then `confirmCancel` takes the signature. Nothing is
+     * cancelled until then. Sent once, never retried.
+     *
+     * One paid up keeps its access to the end of its period; a late or
+     * stopped one has none, and its missed period is never collected.
+     */
+    cancel(id: string, options?: RequestOptions): Promise<WalletTransaction>;
+    /**
+     * Settles a cancellation the wallet sent, by the signature it answered:
+     * `cancelled`, or the subscription as it was with a `reason` when nothing
+     * landed. Mesub waits for the chain, so up to a minute or so: 90 s unless
+     * `options.timeout` says otherwise. Sent once, never retried; the same
+     * confirm sent again is answered the same.
+     *
+     * Settled without a `reason`, it drops every `/v1/access` answer cached
+     * for that customer on that plan: `access` right after asks Mesub again.
+     */
+    confirmCancel(id: string, params: ConfirmParams, options?: ConfirmOptions): Promise<ConfirmResult>;
+    /**
+     * Builds the transaction that takes a `cancelled` subscription back,
+     * before the period it paid for is over. Hand it to your front: the
+     * wallet signs and sends it, then `confirmResume` takes the signature.
+     * Sent once, never retried.
+     */
+    resume(id: string, options?: RequestOptions): Promise<WalletTransaction>;
+    /** As `confirmCancel`, for a resume: `active` again, or a `reason`. */
+    confirmResume(id: string, params: ConfirmParams, options?: ConfirmOptions): Promise<ConfirmResult>;
+    /**
+     * Builds the transaction that closes the wallet's authorisation on a
+     * subscription that is over: its rent goes back to the wallet. Mesub
+     * builds it for a cancelled one past its end; for a stopped one
+     * cancelled on chain and past its end, or whose authority is closed for
+     * good; and for one `ended` with its plan (`end_reason` `plan_removed`,
+     * `plan_replaced` or `plan_ended`). A stopped one that nothing cancelled
+     * is refused with `subscription_not_cancelled`: cancel it first.
+     * Hand the transaction to your front: the wallet signs and sends it,
+     * then `confirmClose` takes the signature. Sent once, never retried.
+     */
+    close(id: string, options?: RequestOptions): Promise<WalletTransaction>;
+    /** As `confirmCancel`, for a close: `ended` with `end_reason` `closed`, or a `reason`. */
+    confirmClose(id: string, params: ConfirmParams, options?: ConfirmOptions): Promise<ConfirmResult>;
+    /**
+     * Pays a late payment now (Mesub-io/backend#354): the pull of the missed
+     * period runs at once rather than at its next retry, with nothing for the
+     * wallet to sign, since it approved the plan when it subscribed. Answers
+     * the subscription, still `unpaid`: the outcome comes with the pull, as
+     * the `subscription.renewed` or `subscription.payment_failed` webhook.
+     *
+     * The merchant's hand retry from the dashboard follows the same rules: on
+     * Free it is one of the missed period's three, whoever fires it; on Dev
+     * and Business it runs beside the schedule, the wait between two doubling.
+     * Mesub refuses it first when it cannot succeed, so it never spends a
+     * retry for nothing: `apiCode` `insufficient_balance` (top up, then pay
+     * again), `retry_cannot_succeed` (the wallet no longer approves it, its
+     * token account is frozen, or its authority is closed), `retry_too_soon`
+     * (`retryAfter` says when), `retries_spent`, `retry_deadline_passed`,
+     * `subscription_not_late`, `subscription_paused`, `plan_ended`. Two more
+     * are `retryable`: `subscription_changed` (two retries met, or a pull
+     * moved the subscription on) and, on Free, `pull_running` (a pull runs
+     * now). Read the subscription back before you ask again. A 503 is
+     * `retryable` too, and nothing changed: `unavailable` (the charge could
+     * not be queued) or `network_unavailable`, with `retryAfter` saying when
+     * to ask again (20 s and 10 s). Sent once, never retried: a second one is
+     * a second retry.
+     */
+    retry(id: string, options?: RequestOptions): Promise<ServerSubscription>;
+    /**
+     * One subscription of your project, by id. Found with `access`, it drops
+     * the access answers cached that still say no, as `submit` does.
+     */
+    retrieve(id: string, options?: RequestOptions): Promise<ServerSubscription>;
+    /**
+     * A customer's subscriptions, newest first, one page at a time; expired
+     * checkouts included. `listAll` walks every page.
+     *
+     * The customer is named as for `access`, and normalised the same way;
+     * none or two of `wallet`, `external_id` and `email` throws a TypeError.
+     * Each one with `access` drops the access answers cached that still say
+     * no, as `submit` does.
+     */
+    list(params: ListParams, options?: RequestOptions): Promise<ServerSubscriptionList>;
+    /**
+     * Every subscription `list` would answer, page after page, for `for await`.
+     * Each page is one call, made when the previous one is used up.
+     */
+    listAll(params: ListParams, options?: RequestOptions): AsyncGenerator<ServerSubscription, void, undefined>;
+    /**
+     * That subscription's own pull attempts, newest first, one page at a
+     * time, and `paid`: what it paid since it began, whatever the page.
+     * `allAttempts` walks every page.
+     *
+     * The id asked and no other: a subscription the wallet came back over
+     * (`superseded`) keeps its own payments, and the one that replaced it
+     * starts from its first pull. Needs a Mesub that serves the route
+     * (Mesub-io/backend#289): from an older one it throws a `not_found`
+     * whose `apiCode` is null, where an id it does not hold is a `not_found`
+     * whose `apiCode` is `subscription_not_found`.
+     */
+    attempts(id: string, params?: AttemptsParams, options?: RequestOptions): Promise<SubscriptionAttemptList>;
+    /**
+     * Every attempt `attempts` would answer, page after page, for `for await`.
+     * Each page is one call, made when the previous one is used up.
+     */
+    allAttempts(id: string, params?: AttemptsParams, options?: RequestOptions): AsyncGenerator<SubscriptionAttempt, void, undefined>;
+}
+
+export { type AccessAnswer as A, type BlockedReason as B, type Customer as C, type EndReason as E, type LateReason as L, type PaymentStatus as P, type RequestOptions as R, type ServedAttempt as S, Transport as T, type WalletTransaction as W, type AccessList as a, type AccessOptions as b, type AttemptsParams as c, type ConfirmOptions as d, type ConfirmParams as e, type ConfirmReasonCode as f, type ConfirmResult as g, type ListParams as h, type PullOutcome as i, type ServerSubscription as j, type ServerSubscriptionList as k, type ServerSubscriptionStatus as l, type StopReason as m, type SubmitOptions as n, type SubmitParams as o, type SubmitResult as p, type SubscribeCosts as q, type SubscribeParams as r, type SubscribeTransaction as s, type SubscriptionAttempt as t, type SubscriptionAttemptList as u, type SubscriptionStatus as v, Subscriptions as w };