@mesub/node 0.0.0-stage → 0.1.0

package/dist/client-BQuRYSdB.d.ts

@@ -0,0 +1,759 @@
+import { j as ServerSubscription, B as BlockedReason, T as Transport, R as RequestOptions, w as Subscriptions, A as AccessAnswer, a as AccessList, C as Customer, b as AccessOptions } from './subscriptions-D1hE7MUc.js';
+
+/** One cached answer, with the two moments that decide what it is still good for. */
+interface CacheEntry<T> {
+    value: T;
+    /** Epoch ms. Before it, the answer is served without calling Mesub. */
+    freshUntil: number;
+    /** Epoch ms. Until then a stale answer is kept for the outage fallback, then dropped. */
+    keepUntil: number;
+}
+/**
+ * Where answers are kept. The memory store is the default; a merchant plugs
+ * Redis or anything else by implementing `get` and `set`, and `delete` if it
+ * can. Each may be sync or async.
+ *
+ * A store that throws or rejects costs a cached answer, never the request. One
+ * that hangs without failing, as a saturated Redis, costs no more under a
+ * guard (#132): its `get` is given until the guard's `guardTimeout` runs out,
+ * then read as a miss, and an answer never waits for its `set`.
+ */
+interface CacheStore<T = unknown> {
+    /**
+     * Under a guard, read as a miss when it has not answered within
+     * `guardTimeout`: the guard then has no time left to ask Mesub, and
+     * answers from nothing, a 503.
+     */
+    get(key: string): CacheEntry<T> | undefined | Promise<CacheEntry<T> | undefined>;
+    /**
+     * `ttlMs` is how long until `keepUntil`, for a store that expires keys
+     * itself. Not awaited: the answer is handed back while it runs, so a read
+     * right after may not find it yet.
+     */
+    set(key: string, entry: CacheEntry<T>, ttlMs: number): void | Promise<void>;
+    /**
+     * Drops a key, when a subscription that grants access lands and the
+     * answer cached says no. Optional: without it, that answer is rewritten
+     * as stale instead, which also makes the next call ask Mesub.
+     */
+    delete?(key: string): void | Promise<void>;
+}
+
+/** How long a stale answer is kept for the outage fallback, then dropped. */
+declare const DEFAULT_MAX_STALE_MS: number;
+/** The one field the cache reads from an answer: seconds it stays true. */
+interface Revalidating {
+    revalidate_after: number;
+}
+interface AccessCacheOptions {
+    maxStaleMs?: number;
+    now?: () => number;
+}
+/** What a read found: the answer, and whether it can be served without calling Mesub. */
+interface CachedAnswer<T> {
+    value: T;
+    fresh: boolean;
+}
+/**
+ * The `/v1/access` answers, by customer and plan, over any store.
+ *
+ * A store that fails never breaks a request: a read that throws is a miss,
+ * a write that throws is dropped. A merchant whose Redis is down still gets
+ * answers, straight from Mesub. Nor does one that hangs hold a guard: given a
+ * deadline, a read not answered by then is a miss too (#132).
+ */
+declare class AccessCache<T extends Revalidating> {
+    private readonly store;
+    private readonly maxStaleMs;
+    private readonly now;
+    constructor(store: CacheStore<T>, options?: AccessCacheOptions);
+    /**
+     * `mesub:access:<scope>:<plan>:<who>`, prefixed so it can share a Redis
+     * with anything. The scope (the client passes a hash of its API key) keeps
+     * two projects sharing one store apart; without one, `mesub:access:<plan>:<who>`.
+     *
+     * `who` is whatever names the customer, the client's being
+     * `<kind>:<wallet or hash>`. A null plan is the list of every plan they
+     * have, under its own prefix, `mesub:access-list:`: no plan slug can reach it.
+     */
+    static key(who: string, plan: string | null, scope?: string): string;
+    /** With a `deadline` (epoch ms), a store that has not answered by then is a miss. */
+    read(who: string, plan: string | null, scope?: string, deadline?: number): Promise<CachedAnswer<T> | undefined>;
+    /** What `pending` gives by `deadline`, or undefined, as a miss, when it has not answered. */
+    private within;
+    write(who: string, plan: string | null, value: T, scope?: string): Promise<void>;
+    /**
+     * Drops the cached answer when `outdated` says it no longer holds, so the
+     * next call asks Mesub. A store without `delete` gets it back as stale
+     * instead: never served as is again, only as the outage fallback.
+     */
+    forget(who: string, plan: string | null, scope: string | undefined, outdated: (value: T) => boolean): Promise<void>;
+}
+
+/**
+ * Webhooks, as Mesub-io/backend#144 sends them: Standard Webhooks
+ * (https://www.standardwebhooks.com), a POST whose body is signed with the
+ * endpoint's secret. Since Mesub-io/backend#482 the body is the event, as
+ * `GET /v1/events` serves it. The types copy the back's `event-body.ts`,
+ * `webhook-payload.ts`, `webhook-events.ts` and `pull-events.ts`, which stay
+ * the source of truth. Snake case, as the API serves it.
+ */
+/** A Fetch `Headers` (Next, route handlers) or Node's plain object (Express). */
+type HeaderSource = Headers | Record<string, string | string[] | undefined>;
+/** The v1 events an endpoint subscribes to, and `test`, sent from the dashboard on request. */
+type WebhookEventType = WebhookEvent['type'];
+/** The v1 events `GET /v1/events` serves: every type but `test`. */
+type EventType = MesubEvent['type'];
+/** The Solana network a subscription is on, as `/v1` spells it. */
+type EventNetwork = 'devnet' | 'mainnet-beta';
+/**
+ * One event, as `GET /v1/events` serves it and its webhooks carry it
+ * (Mesub-io/backend#482): written once, the same bytes for every endpoint,
+ * every retry and every read.
+ */
+interface EventOf<Type extends string, Detail> {
+    /**
+     * The event's own id, the same for every endpoint and every delivery:
+     * what `events.retrieve` takes.
+     */
+    id: string;
+    object: 'event';
+    type: Type;
+    /** When the event happened (ISO 8601), not when it was sent. */
+    created_at: string;
+    /** The Solana network the subscription is on. */
+    network: EventNetwork;
+    /** The `Mesub-Version` `data` and `detail` are written in, kept with the body. */
+    api_version: string;
+    /**
+     * Its place among this subscription's events (Mesub-io/backend#502): 1,
+     * 2, 3... in the order they happened, two events of one change included.
+     * Deliveries arrive in any order: apply one subscription's events by
+     * `sequence`, and skip one lower than the last you applied for it.
+     * Absent on a body written before Mesub numbered events, and on one it
+     * could not number: such an event cannot be placed, so read the
+     * subscription now (`subscriptions.retrieve` or `access`) rather than
+     * applying its `data`. Always 1 on a test delivery.
+     */
+    sequence?: number;
+    /**
+     * The subscription as it stood right after the change that raised the
+     * event, as `GET /v1/subscriptions/:id` would have answered it then,
+     * however late the delivery. Events raised by one change share it:
+     * `detail` says what each is about.
+     */
+    data: ServerSubscription;
+    /** What the event is about, beyond its type. */
+    detail: Detail;
+}
+/**
+ * One event as `verify` hands it back: the body Mesub signed, and
+ * `delivery_id`, its `webhook-id` header.
+ *
+ * A body written before the event shape (before `available_since`, see
+ * `events.list`) keeps the shape it was sent in, `{ type, created_at, data }`
+ * with the detail inside `data`. It is handed back in this shape all the
+ * same: `detail` moved to the top, and `id`, `network` and `api_version`
+ * null, since it carried none. Its `data` is the subscription as it stood at
+ * the delivery's first attempt.
+ */
+interface WebhookEventOf<Type extends string, Detail> extends Omit<EventOf<Type, Detail>, 'id' | 'network' | 'api_version'> {
+    /** The event's id, as `EventOf`'s; null on a body written in the older shape. */
+    id: string | null;
+    /**
+     * The delivery's id, from the `webhook-id` header: one per event and per
+     * endpoint, the same on every retry and resend. Drop a delivery you
+     * already handled by it; across endpoints, by `id`.
+     */
+    delivery_id: string;
+    /** Null on a body written in the older shape. */
+    network: EventNetwork | null;
+    /** Null on a body written in the older shape. */
+    api_version: string | null;
+    /**
+     * True on a body sent by hand from the dashboard: the `test` event, or
+     * a sample of a real type on a made-up subscription (`sub_test`,
+     * `user_123`), with the id `evt_test`. Absent on a real event. Change
+     * nothing for it.
+     */
+    test?: true;
+}
+/** No detail: the subscription says it all. */
+type NoDetail = Record<string, never>;
+/** `subscription.created`: the first payment landed. */
+interface CreatedDetail {
+    /** On a wallet coming back after a stop, the subscription it replaces. */
+    previous_id?: string;
+    /**
+     * What the first payment paid (Mesub-io/backend#509). Null when Mesub
+     * recorded none at the confirmation (a period paid only in part, which
+     * the next charge collects); absent on an event written before it.
+     */
+    first_payment?: FirstPayment | null;
+}
+/** The first payment of a subscription: the transfer its own transaction carried. */
+interface FirstPayment {
+    /** In the token's smallest unit, as a string. */
+    amount: string;
+    mint: string | null;
+    /** The transaction that paid it. */
+    signature: string | null;
+}
+/**
+ * `subscription.ended`: `changed_at` only on a cancellation that reached its
+ * end (Mesub-io/backend#509), its expiry to the millisecond, the moment
+ * `data` describes. Absent on any other end.
+ */
+interface EndedDetail {
+    changed_at?: string;
+    /**
+     * `cancelled` on a cancellation that reached its end, as `data.end_reason`
+     * says it (Mesub-io/backend#511); absent otherwise, and on an older event.
+     */
+    end_reason?: 'cancelled';
+}
+/**
+ * `subscription.renewed`: a period paid. Amounts in the mint's base units, as
+ * strings. It can come late: a transfer whose send failed may land later, and
+ * Mesub sends `renewed` then. By that time the subscription may no longer be
+ * `active`. Ask `hasAccess` before granting access.
+ */
+interface RenewedDetail {
+    amount: string;
+    mint: string;
+    period_start: string;
+    period_end: string;
+    /** The transaction that paid it. */
+    signature: string;
+}
+/** `subscription.payment_failed`: a pull missed, and what comes next. */
+interface PaymentFailedDetail {
+    /** Why, e.g. `insufficient_balance`: an attempt's reason (`ServedAttempt`). */
+    reason: string;
+    amount: string;
+    mint: string;
+    /** The period it was for; null when unknown. */
+    period_start: string | null;
+    period_end: string | null;
+    /**
+     * When Mesub retries; null when it will not (the plan ends before the
+     * retry, among others), or on Free, where retries are by hand.
+     */
+    next_retry_at: string | null;
+    /** Free only: when hand retries close, the plan's end when that comes first. */
+    retry_deadline: string | null;
+    /**
+     * Pulls still to come before the subscription stops, the next one
+     * included; 0 with `next_retry_at` null when the plan ends before any.
+     */
+    retries_left: number;
+    /** Who retries: Mesub on its schedule, or you by hand (Free). Null once none is left. */
+    retry_mode: 'scheduled' | 'manual' | null;
+}
+/**
+ * `subscription.stopped`: no more pulls. `data.stop_reason` says why it
+ * stopped, the reading a program branches on.
+ */
+interface StoppedDetail {
+    /** Why, e.g. `insufficient_balance` or, on Free, `retry_deadline_passed`. */
+    reason: string;
+}
+/**
+ * Why the coming charge would not pay: the wallet holds too little or has no
+ * account of the token (`balance`), or Mesub's approval can no longer move
+ * the tokens (`authority`). One newer than this release is handed back as it is.
+ */
+type RenewalIssue = 'balance' | 'authority';
+/**
+ * `subscription.renewal_upcoming`: the charge due next, and whether the wallet
+ * can pay it as it stood at the event's `created_at`. A reading, not a promise.
+ */
+interface RenewalUpcomingDetail {
+    can_pay: boolean;
+    /** Why not; null when it can. */
+    renewal_issue: RenewalIssue | null;
+    amount: string;
+    mint: string;
+    /** When the charge is due. */
+    due_at: string;
+}
+/**
+ * `subscription.access_granted` and `subscription.access_revoked`: when
+ * access actually changed. A date that passed with nothing else happening
+ * (the end of a paid period, of a cancellation, of the plan) is that date to
+ * the millisecond, even when Mesub wrote the event later; `created_at` is
+ * when it was written.
+ */
+interface AccessChangedDetail {
+    changed_at: string;
+    /**
+     * Why the subscription's charges were held when access changed, in the
+     * words of `data.blocked_reason`; null when they were not. Absent on an
+     * event written before Mesub-io/backend#511. Keep a default branch: Mesub
+     * may add a reason.
+     */
+    blocked_reason?: BlockedReason | null;
+    /**
+     * On `access_revoked`, the date access ended: the end of a paid period,
+     * of a cancellation, of the plan, or of the access a held subscription
+     * keeps; never after `changed_at`, and null when access ended with no
+     * date of its own (a stop). On `access_granted`, on a held subscription,
+     * the date access ends if nothing is collected by then; null otherwise.
+     * Absent on an event written before Mesub-io/backend#511.
+     */
+    access_until?: string | null;
+}
+/** Each event type and its `detail`. */
+interface EventDetails {
+    'subscription.created': CreatedDetail;
+    'subscription.renewal_upcoming': RenewalUpcomingDetail;
+    'subscription.renewed': RenewedDetail;
+    'subscription.payment_failed': PaymentFailedDetail;
+    'subscription.stopped': StoppedDetail;
+    'subscription.cancelled': NoDetail;
+    'subscription.resumed': NoDetail;
+    'subscription.ended': EndedDetail;
+    'subscription.expired': NoDetail;
+    'subscription.access_granted': AccessChangedDetail;
+    'subscription.access_revoked': AccessChangedDetail;
+    'subscription.paused': NoDetail;
+    'subscription.unpaused': NoDetail;
+}
+/**
+ * Every event `GET /v1/events` serves. Narrow it with `switch (event.type)`,
+ * and keep a default branch: a type newer than this release is handed back
+ * too, its subscription checked.
+ */
+type MesubEvent = {
+    [Type in keyof EventDetails]: EventOf<Type, EventDetails[Type]>;
+}[keyof EventDetails];
+type SubscriptionCreatedEvent = WebhookEventOf<'subscription.created', CreatedDetail>;
+/** Once per period, in its last quarter and three days before the charge at most. */
+type SubscriptionRenewalUpcomingEvent = WebhookEventOf<'subscription.renewal_upcoming', RenewalUpcomingDetail>;
+type SubscriptionRenewedEvent = WebhookEventOf<'subscription.renewed', RenewedDetail>;
+type SubscriptionPaymentFailedEvent = WebhookEventOf<'subscription.payment_failed', PaymentFailedDetail>;
+type SubscriptionStoppedEvent = WebhookEventOf<'subscription.stopped', StoppedDetail>;
+type SubscriptionCancelledEvent = WebhookEventOf<'subscription.cancelled', NoDetail>;
+type SubscriptionResumedEvent = WebhookEventOf<'subscription.resumed', NoDetail>;
+/**
+ * Sent when the plan ends, is removed or replaced, and when a subscription is
+ * closed. Once Mesub turns the access events on, also when a cancellation
+ * reaches its end (Mesub-io/backend#509): `end_reason` `cancelled`,
+ * `detail.changed_at` its expiry, usually within half an hour of it, after
+ * that expiry's `subscription.access_revoked`. Closing it later sends it
+ * again, `end_reason` `closed`: one subscription can end twice.
+ */
+type SubscriptionEndedEvent = WebhookEventOf<'subscription.ended', EndedDetail>;
+/** A checkout nobody signed in time. */
+type SubscriptionExpiredEvent = WebhookEventOf<'subscription.expired', NoDetail>;
+/**
+ * Access started (Mesub-io/backend#507): the subscription grants access now
+ * and did not just before. Its first access, a payment that gives access
+ * back, a resume after a cancellation ended. A renewal paid on time, or a
+ * resume while the period runs, sends none. `data.access` is true.
+ *
+ * With `subscription.access_revoked`, the one pair to drive access from:
+ * sent exactly when access changes, and every change sends one. Apply them
+ * by `sequence`; the last one applied says whether the customer has access.
+ * The other events say why. Off until Mesub turns them on (`ACCESS_EVENTS`).
+ */
+type SubscriptionAccessGrantedEvent = WebhookEventOf<'subscription.access_granted', AccessChangedDetail>;
+/**
+ * Access ended (Mesub-io/backend#507): the subscription grants no access now
+ * and did just before. It stopped or ended, a cancellation or the plan
+ * reached its end, or a blocked collection reached its `access_until`. For a
+ * date that passed, sent a few seconds after it. `data.access` is false.
+ * Off until Mesub turns it on.
+ */
+type SubscriptionAccessRevokedEvent = WebhookEventOf<'subscription.access_revoked', AccessChangedDetail>;
+/**
+ * A seat parked (Mesub-io/backend#509): the project holds more subscribers
+ * than its tier allows, and Mesub stopped charging the newest. Not a pause
+ * the subscriber asked for; the status stays. `data.paused` is true,
+ * `data.next_charge_at` null; access runs to the end of the paid period,
+ * and its `subscription.access_revoked` comes then. Off until Mesub turns
+ * the access events on.
+ */
+type SubscriptionPausedEvent = WebhookEventOf<'subscription.paused', NoDetail>;
+/**
+ * A parked seat back (Mesub-io/backend#509): the tier has room again, and
+ * Mesub charges it again. `data.paused` is false; a
+ * `subscription.access_granted` follows when its access had ended. Off until
+ * Mesub turns the access events on.
+ */
+type SubscriptionUnpausedEvent = WebhookEventOf<'subscription.unpaused', NoDetail>;
+/**
+ * Sent from the dashboard on request, with a made-up subscription (`sub_test`).
+ * The dashboard also sends samples of the other types, with `test: true`.
+ */
+type TestEvent = WebhookEventOf<'test', NoDetail>;
+/**
+ * Every event Mesub sends. Narrow it with `switch (event.type)`, and keep a
+ * default branch: an event type newer than this release is handed back too,
+ * its subscription checked, typed as one of these.
+ */
+type WebhookEvent = SubscriptionCreatedEvent | SubscriptionRenewalUpcomingEvent | SubscriptionRenewedEvent | SubscriptionPaymentFailedEvent | SubscriptionStoppedEvent | SubscriptionCancelledEvent | SubscriptionResumedEvent | SubscriptionEndedEvent | SubscriptionExpiredEvent | SubscriptionAccessGrantedEvent | SubscriptionAccessRevokedEvent | SubscriptionPausedEvent | SubscriptionUnpausedEvent | TestEvent;
+/** The body as received, never parsed: a string, a Buffer or any Uint8Array, an ArrayBuffer. */
+type WebhookBody = string | Uint8Array | ArrayBuffer;
+interface VerifyWebhookOptions {
+    /**
+     * The endpoint's signing secret, `whsec_...`. Defaults to the client's
+     * `webhookSecret`, then to `process.env.MESUB_WEBHOOK_SECRET`.
+     */
+    secret?: string;
+    /**
+     * How far `webhook-timestamp` may be from now, either way, in
+     * milliseconds, above 0: older is refused as a replay. Defaults to 5 minutes.
+     */
+    tolerance?: number;
+}
+/**
+ * Checks a webhook Mesub sent and hands back its event: the signature over
+ * the raw body, against the endpoint's secret, then the timestamp, then the
+ * body's shape.
+ *
+ * Throws a MesubError `invalid_webhook` when it is not Mesub's, or not now:
+ * a header missing, no signature matching, a timestamp outside `tolerance`.
+ * Answer it with a 400.
+ *
+ * Throws `unexpected` for a body Mesub signed that this release cannot read.
+ * Never answer it with a 400. Log it, update `@mesub/node`, and answer a
+ * 5xx: Mesub retries the same body for 3 days, so the event gets through
+ * once the update is out. Past 3 days of failures, Mesub disables the
+ * endpoint.
+ *
+ * A TypeError is an integration error: a body already parsed, no secret,
+ * one that is not `whsec_...`.
+ */
+declare function verifyWebhook(body: WebhookBody, headers: HeaderSource, options?: VerifyWebhookOptions): Promise<WebhookEvent>;
+/** `mesub.webhooks`: `verifyWebhook` with the client's own secret. */
+declare class Webhooks {
+    #private;
+    /** @internal */
+    constructor(secret: string | undefined, received: (event: WebhookEvent) => Promise<void>);
+    /**
+     * `verifyWebhook`, with `webhookSecret` unless `options.secret` says
+     * otherwise. A verified event also drops every access answer cached for
+     * its customer, the yes and the no, so the next check asks Mesub.
+     * Three drop nothing: `subscription.renewal_upcoming`, which moves no
+     * access, the `test` event, and any body with `test: true`, whose
+     * subscription is made up.
+     */
+    verify(body: WebhookBody, headers: HeaderSource, options?: VerifyWebhookOptions): Promise<WebhookEvent>;
+}
+
+/**
+ * Your project's subscription events (Mesub-io/backend#482): `GET /v1/events`
+ * and `GET /v1/events/:id`, each event the very body its webhooks carry. The
+ * types copy the back's `server-events.service.ts`, which stays the source
+ * of truth. Snake case, as the API serves it.
+ */
+/** One page of events, newest first. */
+interface EventList {
+    data: MesubEvent[];
+    /** Ask for the next page with `starting_after` set to the last id of this one. */
+    has_more: boolean;
+    /**
+     * When Mesub began keeping events in this shape: events before it are
+     * never served, whatever the window. Their webhooks carried the older
+     * shape, with no event id.
+     */
+    available_since: string;
+}
+/** Which events, and which page of them. */
+interface EventListParams {
+    /** Only events of this type. */
+    type?: EventType;
+    /** Only events about this subscription, by its id. */
+    subscription?: string;
+    /** 1 to 100, 25 by default. */
+    limit?: number;
+    /** The id of the last event of the previous page. */
+    starting_after?: string;
+}
+declare class Events {
+    #private;
+    /** @internal */
+    constructor(transport: Transport);
+    /**
+     * Your project's events of the last 30 days, newest first, one page at a
+     * time: each the very body its webhooks carried, the same `id`, `data`
+     * and `detail`. Read it to catch up on what an endpoint missed while it
+     * was down or turned off. Events before `available_since` are never
+     * served, whatever the window.
+     *
+     * An event is listed a moment after its `created_at`, so one can appear
+     * below one already read: when polling for what is new, page on until
+     * `created_at` is a minute older than the newest you held, and skip the
+     * ids you have seen.
+     *
+     * Needs a Mesub that serves the route (Mesub-io/backend#482): from an
+     * older one it throws a `not_found` whose `apiCode` is null.
+     */
+    list(params?: EventListParams, options?: RequestOptions): Promise<EventList>;
+    /**
+     * One event, by the `id` its webhook body carries, as `list` serves it.
+     * A `not_found` whose `apiCode` is `event_not_found` for an id older than
+     * 30 days or than `available_since`, or of another project. A delivery's
+     * `webhook-id` is not an event id: read `event.id`, not `delivery_id`.
+     */
+    retrieve(id: string, options?: RequestOptions): Promise<MesubEvent>;
+}
+
+/** A plan a subscriber can hold: taking new ones (`active`), or ending (`sunset`). */
+type PlanStatus = 'active' | 'sunset';
+/**
+ * What Mesub knows of a plan's token, resolved by its mint: never from the
+ * merchant nor the client. A symbol is free text on chain and a fake "USDC"
+ * is a known scam: show an unverified token as unverified, with its mint.
+ */
+interface PlanToken {
+    /** Null when Mesub found none, and on an unverified token named like a vouched stablecoin. */
+    symbol: string | null;
+    name: string | null;
+    logo_url: string | null;
+    /** True for a mint Mesub vouches for, or one Jupiter marks verified. */
+    verified: boolean;
+}
+/** A plan of your project, as a pricing page needs it. */
+interface Plan {
+    /** What `access`, the guards and `subscriptions.create` name it by. */
+    slug: string;
+    /** The plan's name, or its slug when none was given. */
+    name: string;
+    description: string | null;
+    project_name: string;
+    logo_url: string | null;
+    /** The price in the token's base units, a string: a u64 does not survive a float. */
+    amount: string;
+    /** The price as a person counts it: `"9.99"`. */
+    amount_display: string;
+    /**
+     * The plan's amount in dollars at the latest price Mesub knows, a decimal
+     * string such as `"9.99"`: an estimate to show beside the amount, never
+     * what is charged. Null when Mesub knows no price, and from a Mesub that
+     * predates it.
+     */
+    amount_usd: string | null;
+    decimals: number;
+    /** Set only for a mint Mesub vouches for (USDC, USDT, PYUSD), null for any other. */
+    symbol: string | null;
+    /**
+     * The token's symbol, name and logo for any mint, and whether it is
+     * verified: when it is not, say so and keep `mint` visible. All null and
+     * unverified from a Mesub that predates it.
+     */
+    token: PlanToken;
+    mint: string;
+    period_hours: number;
+    network: 'devnet' | 'mainnet-beta';
+    status: PlanStatus;
+    /** Whether it takes new subscribers now: show "Subscribe" only when true. */
+    available: boolean;
+    /**
+     * When the plan ends, null when it has no end: nobody has access past
+     * it, and the last period before it is charged in full.
+     */
+    ends_at: string | null;
+}
+/** `mesub.plans`: the plans of your project, for a pricing page. */
+declare class Plans {
+    #private;
+    /** @internal */
+    constructor(transport: Transport);
+    /**
+     * Every plan of your project a subscriber can hold, sorted by slug: the
+     * active ones, and the ones ending (`sunset`, `available: false`). Never
+     * cached: call it where you render, and cache it your way.
+     */
+    list(options?: RequestOptions): Promise<Plan[]>;
+    /** One plan by its slug. A slug your project lacks throws `plan_not_found`. */
+    retrieve(slug: string, options?: RequestOptions): Promise<Plan>;
+}
+
+/** What a guard decided, and on which answer. */
+interface Decision {
+    access: boolean;
+    answer: AccessAnswer | null;
+    /** The answer came from the outage fallback, not from Mesub just now. */
+    stale: boolean;
+    /**
+     * Mesub did not answer (an outage, a rate limit, or the guard's time
+     * budget running out) and no answer was cached for that customer: nobody
+     * knows yet, so the guards answer 503, not 402.
+     */
+    unavailable?: boolean;
+    /**
+     * With `unavailable`, the milliseconds Mesub's `Retry-After` asked for,
+     * when it sent one: a guard's 503 hands it on (#132).
+     */
+    retryAfter?: number;
+}
+interface MesubOptions {
+    /** API key. Defaults to `process.env.MESUB_API_KEY`. */
+    apiKey?: string;
+    /**
+     * Defaults to `https://api.mesub.io`. May carry a path, e.g. behind a
+     * proxy at `https://proxy.example.com/mesub`: every call is made under it.
+     */
+    baseUrl?: string;
+    /**
+     * Extra headers sent with every call to Mesub: e.g. a Cloudflare Access
+     * service token for the proxy in front. Cannot set Authorization,
+     * User-Agent, Accept, Content-Type nor Mesub-Version.
+     */
+    headers?: Record<string, string>;
+    /** A custom `fetch`, e.g. one bound to your own agent. Defaults to the global one. */
+    fetch?: typeof fetch;
+    /** Per attempt, in milliseconds. Defaults to 5000. */
+    timeout?: number;
+    /**
+     * How many times a failed call to Mesub is sent again, after the first
+     * attempt. Defaults to 2. HTTP retries only: nothing to do with a plan's
+     * pull retries, which Mesub runs on its side (and a Free plan has none).
+     */
+    maxRetries?: number;
+    /**
+     * Where `/v1/access` answers are kept. Defaults to a memory store of
+     * 10,000 entries, emptied on restart; a Redis store keeps the outage
+     * fallback across restarts and servers.
+     */
+    cache?: CacheStore<AccessAnswer | AccessList>;
+    /**
+     * How long an answer is kept once stale, for the outage fallback of
+     * `hasAccess` and the guards, in milliseconds. Defaults to 24 hours. 0
+     * turns the fallback off: an outage then keeps everyone out.
+     */
+    maxStaleMs?: number;
+    /**
+     * How long the guards (`requirePlan`, `withMesub`, `RequirePlan`) give
+     * Mesub to answer, retries and waits included, in milliseconds. Defaults
+     * to 2000. Once it runs out, or Mesub fails, the guard answers from the
+     * cache, even stale, or 503 with Retry-After for a wallet it never saw. `access` and
+     * `hasAccess`, called directly, are not bound by it.
+     */
+    guardTimeout?: number;
+    /**
+     * The webhook endpoint's signing secret, `whsec_...`, for
+     * `webhooks.verify`. Defaults to `process.env.MESUB_WEBHOOK_SECRET`; none
+     * is needed until a webhook is verified.
+     */
+    webhookSecret?: string;
+}
+declare class Mesub {
+    /** Subscribing from your server: create, submit, retrieve and list. */
+    readonly subscriptions: Subscriptions;
+    /** The plans of your project, for a pricing page: `list` and `retrieve`. */
+    readonly plans: Plans;
+    /** Checking the webhooks Mesub sends: `verify`. */
+    readonly webhooks: Webhooks;
+    /** The events of the last 30 days, as their webhooks carried them: `list` and `retrieve`. */
+    readonly events: Events;
+    /** @internal */
+    protected readonly transport: Transport;
+    /** @internal */
+    protected readonly cache: AccessCache<AccessAnswer>;
+    /** The lists of `accessList`, in the same store, under their own keys. */
+    private readonly lists;
+    /** What the cache keys are scoped by: a hash of the API key, computed once. */
+    private readonly cacheScope;
+    /** What hashes emails and external ids in the cache keys: the API key, imported once. */
+    private readonly cacheSecret;
+    private readonly guardTimeout;
+    /**
+     * The `/v1/access` requests in flight, by cache key: a call for the same
+     * answer waits for that one rather than send its own (#34).
+     */
+    private readonly flights;
+    constructor(options?: MesubOptions);
+    /**
+     * Everything Mesub knows about that customer on that plan: whether they
+     * have access, their status, their dates. Served from the cache while fresh.
+     *
+     * The customer is `{ wallet }`, `{ external_id }` or `{ email }`, or a
+     * wallet as a string. Asked by external id or email, the answer is about
+     * the wallet that grants access, if any: `wallet` is null when they have
+     * nothing on that plan.
+     *
+     * Throws a `MesubError` whenever Mesub cannot answer: it is for screens.
+     * A guard calls `hasAccess`, which falls back instead.
+     */
+    access(customer: Customer | string, plan: string, options?: AccessOptions): Promise<AccessAnswer>;
+    /**
+     * Every plan of the project that customer has anything on, each answered
+     * like `access`, for a page listing their entitlements in one call. Cached
+     * apart from the answers by plan, for its own `revalidate_after`.
+     *
+     * Throws a `MesubError` whenever Mesub cannot answer, like `access`.
+     */
+    accessList(customer: Customer | string, options?: AccessOptions): Promise<AccessList>;
+    /**
+     * `access` from Mesub, cached in the slot its caller computed once and
+     * already read, or without the cache at all (`null`) for an answer with
+     * its attempts.
+     */
+    private ask;
+    /**
+     * One request in flight per key (#34): fifty calls for a customer not in
+     * the cache made fifty requests to Mesub, and as many 429s to retry. The
+     * first sends it, the others wait for its answer or its error. Its answer
+     * is cached once, unless a subscription that landed dropped the flight
+     * meanwhile: then it is answered, not cached.
+     */
+    private shared;
+    /**
+     * Where a customer's answers are cached: the project's scope, and who
+     * they are as the key reads it. A wallet is public on chain and stays
+     * readable; an email or an external id is never written in clear, only
+     * as an HMAC under the API key, which a leaked Redis alone cannot reverse
+     * by guessing.
+     */
+    private slotOf;
+    /**
+     * A subscription `submit`, `retrieve` or `list` answered (#33): once it
+     * grants access (`active`, or `cancelled` before its end), the answers
+     * cached for its customer that say no are dropped, by wallet, external
+     * id and email, for its plan and in the list of every plan. Without it, a
+     * `hasAccess` right after a submit kept answering the cached no until
+     * `revalidate_after` ran out. A store that fails costs nothing more than
+     * that: it never throws.
+     *
+     * With `moved`, one a confirm just cancelled, resumed or closed, or one a
+     * verified webhook carried: every answer cached for its customer is
+     * dropped, the yes too, since its status and dates changed whatever its
+     * access. A `stopped` or `ended` event must not leave a yes behind.
+     */
+    private landed;
+    /**
+     * Whether that customer has access to that plan, for a guard. The
+     * customer is the same as for `access`, a wallet string included.
+     *
+     * When Mesub is unavailable after the retries (`unavailable` or
+     * `rate_limited`), it answers the last answer it knew, even stale, and
+     * `false` for a customer it never saw. Any other error is thrown, never
+     * turned into `false`: a bad key or an unknown plan is a broken
+     * integration, not a denial.
+     *
+     * No time budget: it waits out the client's timeout and retries, and a
+     * 429's `Retry-After`. A guard answers within `guardTimeout` instead.
+     */
+    hasAccess(customer: Customer | string, plan: string): Promise<boolean>;
+    /**
+     * `hasAccess`, with the answer it decided on, within `guardTimeout`: what
+     * the middlewares hand the route. `answer` is null only for a customer
+     * never seen during an outage, which is then `unavailable`; `stale` is
+     * true when the answer came from the fallback.
+     *
+     * @internal
+     */
+    decide(customer: Customer | string, plan: string): Promise<Decision>;
+    /**
+     * The decision itself. With a deadline (the guards), every call to Mesub
+     * fits before it: attempts are cut at it and a Retry-After that would
+     * outlast it is not waited. Without one (`hasAccess` called directly),
+     * the client's timeout and retries, as configured.
+     */
+    private decideBy;
+}
+
+export { AccessCache as A, type SubscriptionPausedEvent as B, type CacheStore as C, DEFAULT_MAX_STALE_MS as D, type EndedDetail as E, type FirstPayment as F, type SubscriptionPaymentFailedEvent as G, type HeaderSource as H, type SubscriptionRenewalUpcomingEvent as I, type SubscriptionRenewedEvent as J, type SubscriptionResumedEvent as K, type SubscriptionStoppedEvent as L, Mesub as M, type NoDetail as N, type SubscriptionUnpausedEvent as O, type PaymentFailedDetail as P, type WebhookEvent as Q, type RenewalIssue as R, type StoppedDetail as S, type TestEvent as T, type WebhookEventType as U, type VerifyWebhookOptions as V, type WebhookBody as W, Webhooks as X, verifyWebhook as Y, type CacheEntry as a, type AccessCacheOptions as b, type AccessChangedDetail as c, type CachedAnswer as d, type CreatedDetail as e, type Decision as f, type EventList as g, type EventListParams as h, type EventNetwork as i, type EventType as j, Events as k, type MesubEvent as l, type MesubOptions as m, type Plan as n, type PlanStatus as o, type PlanToken as p, Plans as q, type RenewalUpcomingDetail as r, type RenewedDetail as s, type Revalidating as t, type SubscriptionAccessGrantedEvent as u, type SubscriptionAccessRevokedEvent as v, type SubscriptionCancelledEvent as w, type SubscriptionCreatedEvent as x, type SubscriptionEndedEvent as y, type SubscriptionExpiredEvent as z };