@mesub/node 0.0.0-stage → 0.1.2

package/dist/testing.d.ts

@@ -0,0 +1,331 @@
+import { A as AccessAnswer, j as ServerSubscription, C as Customer, t as SubscriptionAttempt } from './subscriptions-B6Lin6i_.js';
+import { n as Plan, p as PlanToken, m as MesubOptions, M as Mesub, U as WebhookEventType, j as EventType, l as MesubEvent } from './client-CXQLkSAJ.js';
+
+/**
+ * `@mesub/node/testing`: a fake Mesub, for a merchant's own tests. It answers
+ * what the SDK calls (`/v1/access`, `/v1/plans`, `/v1/subscriptions`, its
+ * fresh transaction, its attempts and its cancel, resume and close, and
+ * `/v1/events`) from what the test sets, through a `fetch` handed to the
+ * client: no network, no backend, no test framework of its own.
+ *
+ * ```ts
+ * import { FakeMesub } from '@mesub/node/testing';
+ *
+ * const fake = new FakeMesub();
+ * fake.grant(wallet, 'pro');
+ * const mesub = fake.client();
+ * await mesub.hasAccess(wallet, 'pro'); // true
+ *
+ * const { body, headers } = await fake.webhook('subscription.renewed');
+ * await mesub.webhooks.verify(body, headers); // the event
+ * ```
+ */
+
+interface FakeMesubOptions {
+    /** Where the fake answers. Defaults to `https://api.mesub.test`. */
+    baseUrl?: string;
+    /** The only key it accepts; any other is answered 401. Defaults to `SUB_test_fake`. */
+    apiKey?: string;
+    /**
+     * The plans that exist: any other slug is answered 404 `plan_not_found`.
+     * By default every slug exists. A slug alone, or the fields `plans.list`
+     * and `plans.retrieve` should answer for it: the rest is filled in.
+     * Name them to test the widget routes, which read `plans.list`: left
+     * out, the list is empty. A plan given an `ends_at` is served as Mesub
+     * serves one: no `access_until` later than it, no pull dated from it
+     * on, and no access once it has passed. A plan's token is USDC, verified,
+     * and its `amount_usd` its `amount_display`: give a `token` (some of its
+     * fields are enough) and an `amount_usd` for any other, such as an
+     * unverified one with a null `symbol`.
+     */
+    plans?: Array<string | FakePlanFields>;
+    /** What `webhook()` signs with, and `client()` verifies with. Defaults to a fixed `whsec_` secret. */
+    webhookSecret?: string;
+    /**
+     * False to act as a Mesub that predates
+     * `GET /v1/subscriptions/:id/attempts`: it answers Nest's 404 for a route
+     * it does not have, and attempts are only served through `/v1/access`.
+     */
+    attemptsRoute?: boolean;
+    /**
+     * Mesub's `available_since`: events created before it are not served on
+     * `/v1/events`. Defaults to 30 days before the fake was made, so every
+     * event of the window is.
+     */
+    eventsSince?: string | Date;
+    /**
+     * The `revalidate_after` of every `/v1/access` answer, in seconds: 0 for
+     * a test that wants each change seen on the next call of the same
+     * client. Left out, Mesub's own: 10 for a no, and for a yes the time to
+     * its next charge, retry or end, from 10 to 300, so a client keeps a yes
+     * up to five minutes. One set on an answer with `setAccess` wins.
+     */
+    revalidateAfter?: number;
+    /**
+     * True to raise `subscription.access_granted` and
+     * `subscription.access_revoked` (Mesub-io/backend#507) when a change the
+     * fake makes flips access, right after the event that says why, one
+     * `sequence` later: a submit grants. False by default, as on Mesub until
+     * it turns them on. The fake moves no clock, so a date
+     * passing revokes nothing: record that with `addEvent`, which, like
+     * `webhook`, makes either type whatever this says.
+     */
+    accessEvents?: boolean;
+    /**
+     * The project's tier, `dev` by default. It decides what Pay now
+     * (`subscriptions.retry`) refuses, as on Mesub: on `free` a wait of 10
+     * minutes after each hand retry, three per missed period, none past
+     * `retry_deadline`; on `dev` and `business` none for the first, then a
+     * wait of 20 minutes doubling after each. And what `addSubscription`
+     * gives a late row: no access on `free`, access through its retries
+     * otherwise.
+     */
+    tier?: FakeTier;
+}
+/** A project's tier, as Mesub names them. */
+type FakeTier = 'free' | 'dev' | 'business';
+/** A plan as declared to the fake: its slug, and any field to set, a token's included. */
+type FakePlanFields = Partial<Omit<Plan, 'token'>> & {
+    slug: string;
+    token?: Partial<PlanToken>;
+};
+/** A webhook as Mesub posts it: the exact body, and the three headers that sign it. */
+interface SignedWebhook {
+    body: string;
+    headers: Record<string, string>;
+}
+interface SignWebhookOptions {
+    /** The endpoint's secret, `whsec_...`. */
+    secret: string;
+    /**
+     * `webhook-id`. Defaults to a new `msg_signed_...` each time, never one
+     * a fake's `webhook()` gives.
+     */
+    id?: string;
+    /** `webhook-timestamp`, Unix seconds. Defaults to now. */
+    timestamp?: number;
+}
+/** What `FakeMesub.addEvent` records, on top of a made-up event of that type. */
+interface FakeEventFields {
+    /**
+     * Fields of the subscription it carries, on top of the one the fake
+     * holds under that `id`, else of an active, paid one on `pro`.
+     */
+    subscription?: Partial<ServerSubscription>;
+    /** The event's detail. Defaults to a plausible one for the type. */
+    detail?: Record<string, unknown>;
+    /** When the event happened. Defaults to now. */
+    created_at?: string;
+    /** The event's id. Defaults to a new `evt_fake_...`. */
+    id?: string;
+    /**
+     * Its place among its subscription's events. Defaults to the next one
+     * for that subscription; null leaves it out, as on an event Mesub could
+     * not number.
+     */
+    sequence?: number | null;
+}
+/** What `FakeMesub.webhook` sends, on top of a made-up event of that type. */
+interface FakeWebhookFields {
+    /**
+     * Fields of the subscription it carries, on top of the one the fake
+     * holds under that `id`, else of an active, paid one on `pro`. The
+     * `test` event carries Mesub's sample one (`sub_test`, `user_123`).
+     */
+    subscription?: Partial<ServerSubscription>;
+    /** The event's detail. Defaults to a plausible one for the type. */
+    detail?: Record<string, unknown>;
+    /** When the event happened. Defaults to now. */
+    created_at?: string;
+    /**
+     * The event's id. Defaults to a new `evt_fake_...`, and to `evt_test` for
+     * the `test` event, as Mesub's test deliveries carry.
+     */
+    id?: string;
+    /**
+     * Its place among its subscription's events. Defaults to the next one
+     * for that subscription, and to 1 on the `test` event, as Mesub's test
+     * deliveries carry; null leaves it out, as on an event Mesub could not
+     * number.
+     */
+    sequence?: number | null;
+    /**
+     * The delivery's id, the `webhook-id` header. Defaults to the fake's
+     * next `msg_fake_...`, from `msg_fake_1`, and again after `reset()`.
+     */
+    delivery_id?: string;
+    /** `webhook-timestamp`, Unix seconds. Defaults to now. */
+    timestamp?: number;
+}
+/** One call the fake received. */
+interface FakeRequest {
+    method: string;
+    /** Under the base URL, e.g. `/v1/access`. */
+    path: string;
+    query: Record<string, string>;
+    headers: Headers;
+    /** The parsed JSON body of a POST, undefined otherwise. */
+    body: unknown;
+}
+/** An error the fake answers instead, as Mesub would send it. */
+interface FakeFailure {
+    status: number;
+    /** Mesub's own code, e.g. `network_unavailable`. */
+    code: string;
+    message?: string;
+    /**
+     * Defaults to what Mesub says of the code, e.g. true for
+     * `subscription_changed`; for a code Mesub does not have, to what the
+     * status says: true for 408, 429 and 5xx.
+     */
+    retryable?: boolean;
+    /**
+     * Seconds, sent as `Retry-After`. A 503 on a route that builds, sends or
+     * queues (every POST under `/v1/subscriptions`) defaults to Mesub's own:
+     * 2 for `unavailable` on submit (too many submits waiting), 20 for
+     * `unavailable` on retry (the charge could not be queued), 10 otherwise.
+     * `retry_too_soon` defaults to the first wait of the fake's `tier`: 600
+     * on `free`, 1200 on `dev` and `business`.
+     */
+    retryAfter?: number;
+}
+/** What a test may set of an access answer: all but the plan, named apart. */
+type FakeAccess = Partial<Omit<AccessAnswer, 'plan'>>;
+/**
+ * A fake Mesub API. Each test sets what a customer has with `grant`, `deny`
+ * or `setAccess`, gets a client wired to it with `client()`, and makes it
+ * fail with `fail()`. A plan with an end is `grantLastPeriod`, `endPlan`, or
+ * an `ends_at` in `plans`.
+ *
+ * It answers and refuses as Mesub does, `revalidate_after` included: a
+ * client keeps a yes up to five minutes and a no 10 seconds, so a change
+ * made after a client asked shows to a new client, or to every client with
+ * `revalidateAfter: 0`. Every answer carries a `Mesub-Request-Id`, and every
+ * error body its `request_id`.
+ *
+ * `closable` and `closable_from` are worked out from what the fake's close
+ * would take, unless a test set them on an answer. A subscription it moves
+ * raises the event Mesub raises (`subscription.created` on a submit,
+ * `cancelled`, `resumed` and `ended` on a confirm), which `/v1/events`
+ * serves; `addEvent` records any other.
+ */
+declare class FakeMesub {
+    #private;
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly webhookSecret: string;
+    /** Every call received, oldest first. */
+    readonly requests: FakeRequest[];
+    /** Hand it to `new Mesub({ fetch })`, or use `client()`. */
+    readonly fetch: typeof globalThis.fetch;
+    constructor(options?: FakeMesubOptions);
+    /**
+     * A client wired to this fake: its key, base URL and fetch, and no retry
+     * unless asked, so a failure shows at once. Any other option is passed on.
+     */
+    client(options?: Omit<MesubOptions, 'apiKey' | 'baseUrl' | 'fetch' | 'webhookSecret'>): Mesub;
+    /**
+     * That customer has access to that plan: active and paid, unless `fields`
+     * say otherwise. The customer is named as `access` names them, and only
+     * that way answers: a wallet granted is not found by its external id.
+     */
+    grant(customer: Customer | string, plan: string, fields?: FakeAccess): AccessAnswer;
+    /** That customer has no access to that plan: `status` says why, `none` by default. */
+    deny(customer: Customer | string, plan: string, fields?: FakeAccess): AccessAnswer;
+    /**
+     * That customer is in the last period of a plan that ends at `endsAt`:
+     * active and paid, access until the end and no charge ahead, unless
+     * `fields` say otherwise. The plan gets that `ends_at`, and from then on
+     * the fake refuses everyone on it, as Mesub does, whatever `status` reads.
+     */
+    grantLastPeriod(customer: Customer | string, plan: string, endsAt: string | Date, fields?: FakeAccess): AccessAnswer;
+    /**
+     * That plan reached its end, at `at` or now: it takes nobody new, and
+     * what the fake holds on it is ended as Mesub ends it, `plan_ended` for a
+     * running or late one, `cancelled` for one that had cancelled. Before
+     * this is called, a plan past its `ends_at` already refuses everyone,
+     * with `status` unchanged: the minutes Mesub takes to end the rows.
+     */
+    endPlan(plan: string, at?: string | Date): void;
+    /**
+     * Parks that subscription's seat, as Mesub does when a project holds more
+     * subscribers than its tier allows: `paused`, no next charge, access and
+     * status unchanged (the fake moves no clock, so the paid period never
+     * runs out). With `accessEvents`, raises `subscription.paused`
+     * (Mesub-io/backend#509), sent behind the same flag. Throws for an id the
+     * fake does not hold.
+     */
+    park(id: string): ServerSubscription;
+    /**
+     * Brings a parked seat back: not `paused`, charged again at the end of
+     * its period. With `accessEvents`, raises `subscription.unpaused`.
+     */
+    unpark(id: string): ServerSubscription;
+    /**
+     * What `/v1/access` answers that customer on that plan, on top of the
+     * answer for a customer with nothing. `wallet` defaults to the wallet
+     * asked about, and to null for an external id or an email.
+     */
+    setAccess(customer: Customer | string, plan: string, fields: FakeAccess): AccessAnswer;
+    /**
+     * A subscription `retrieve` and `list` answer, active by default, dated
+     * as Mesub dates a row of that `status` unless `fields` say otherwise:
+     * active, paid for a period ending in 30 days and charged then; unpaid,
+     * that period over, late, with access and a retry tomorrow, or on `free`
+     * no access and hand retries until `retry_deadline`; cancelled, access to
+     * the end of the period; stopped (`out_of_retries`) or ended (`closed`),
+     * no access. Its access answer is left as it is: set it with `grant`.
+     * Throws for a wallet Mesub would refuse. Its plan may be one `plans`
+     * leaves out: Mesub serves the rows of a plan it no longer has.
+     */
+    addSubscription(fields: Partial<ServerSubscription> & {
+        wallet: string;
+        plan: string;
+    }): ServerSubscription;
+    /**
+     * The pull attempts of that subscription, every one it ever had: what
+     * `subscriptions.attempts` answers for it, with their `paid` total, and
+     * the five newest through `/v1/access` with `attempts`, whose answer
+     * becomes about that subscription. Each is a paid one of 9.99 USDC now,
+     * priced 9.99 dollars, not a retry, unless told otherwise; one given
+     * another `amount` and no `amount_usd` is not priced. Newest first.
+     * Throws for an id the fake does not hold.
+     */
+    setAttempts(id: string, attempts: Array<Partial<SubscriptionAttempt>>): SubscriptionAttempt[];
+    /**
+     * A webhook of that type, as Mesub posts it to an endpoint: the event's
+     * body (Mesub-io/backend#482), on a made-up subscription and detail
+     * unless `fields` say otherwise, the subscription the fake holds under
+     * `fields.subscription.id` when it holds one, signed with
+     * `webhookSecret`. The `test` event is Mesub's test delivery: `test:
+     * true`, `evt_test`, on its sample subscription (`sub_test`,
+     * `user_123`). Post it to your own handler, or hand it to
+     * `webhooks.verify` of a `client()`. Nothing is added to the fake.
+     */
+    webhook(type: WebhookEventType, fields?: FakeWebhookFields): Promise<SignedWebhook>;
+    /**
+     * An event `/v1/events` serves from now on, as Mesub would have raised
+     * it: a made-up subscription and detail unless `fields` say otherwise,
+     * the subscription the fake holds under `fields.subscription.id` when it
+     * holds one. Nothing else changes: what it says happened is not done.
+     */
+    addEvent(type: EventType, fields?: FakeEventFields): MesubEvent;
+    /**
+     * Every call answers that error from now on, `'outage'` a 503, until
+     * `fail(null)`.
+     */
+    fail(failure: FakeFailure | 'outage' | null): void;
+    /**
+     * Forgets every answer, subscription, failure and request, and starts
+     * every id over: the same test makes the same ids, whatever ran before.
+     */
+    reset(): void;
+}
+/**
+ * Signs a body as Mesub does (Standard Webhooks, HMAC-SHA256 of
+ * `id.timestamp.body`), for a webhook of your own making: an object is sent
+ * as its JSON, a string as is. `FakeMesub.webhook` builds the body for you.
+ */
+declare function signWebhook(payload: unknown, options: SignWebhookOptions): Promise<SignedWebhook>;
+
+export { type FakeAccess, type FakeEventFields, type FakeFailure, FakeMesub, type FakeMesubOptions, type FakePlanFields, type FakeRequest, type FakeTier, type FakeWebhookFields, type SignWebhookOptions, type SignedWebhook, signWebhook };