@relipay/node 0.1.0-beta.0

package/dist/index.d.ts

@@ -0,0 +1,677 @@
+/**
+ * @relipay/node — server SDK for ReliPay.
+ *
+ * One client instance per Application. Construct with the Application's
+ * secret key (`rp_live_…` or `rp_test_…`) and the URL of your ReliPay
+ * deployment. Never ship the secret key to the browser — for browser code
+ * use `@relipay/react` with the Application's public key instead.
+ *
+ * @example Smoke-test your credentials
+ * ```ts
+ * import { ReliPay } from "@relipay/node";
+ *
+ * const relipay = new ReliPay({
+ *   apiUrl: process.env.RELIPAY_URL!,
+ *   secretKey: process.env.RELIPAY_SECRET!,
+ * });
+ *
+ * const me = await relipay.applications.me();
+ * console.log(`Connected to "${me.name}" (${me.slug})`);
+ * ```
+ */
+import type { ApplicationDto, AuthResultDto, ChangePasswordRequest, CheckoutResultDto, ConsumeCreditsRequest, CreateCheckoutRequest, CreditBalanceDto, CreditLedgerEntryDto, EndUserDto, ForgotPasswordRequest, ForgotPasswordResultDto, MfaVerifyRequest, PlanDto, ProvidersListDto, RelipayError as RelipayErrorShape, ResetPasswordRequest, SignInOutcomeDto, SignInRequest, SignUpRequest, SubscriptionDto, ValidateCouponRequest, ValidateCouponResultDto } from '@relipay/shared-types';
+export type { ApplicationDto, EndUserDto, ApiKeyDto, AuthResultDto, MfaChallengeResultDto, MfaVerifyRequest, SignInOutcomeDto, SignInRequest, SignUpRequest, RefreshRequest, ForgotPasswordRequest, ForgotPasswordResultDto, ResetPasswordRequest, ChangePasswordRequest, PlanDto, SubscriptionDto, CreateCheckoutRequest, CheckoutResultDto, CouponDto, ValidateCouponRequest, ValidateCouponResultDto, CouponDiscountTypeValue, PlanIntervalType, PlanKindType, LicenseKindType, CreditReasonType, CreditBalanceDto, CreditLedgerEntryDto, ConsumeCreditsRequest, SubscriptionStatusType, RelipayError as RelipayErrorShape, AuthConfig, BillingConfig, BillingProvider, } from '@relipay/shared-types';
+/** Configuration for a ReliPay client instance. */
+export interface ReliPayConfig {
+    /** Base URL of the ReliPay API. e.g. `https://relipay.example.com` */
+    apiUrl: string;
+    /** Secret key for one Application — `rp_live_…` or `rp_test_…`. Never ship to the browser. */
+    secretKey: string;
+    /** Optional fetch override (test stubs, custom keep-alive agents, etc.). */
+    fetch?: typeof fetch;
+}
+/**
+ * An error thrown by the ReliPay SDK. Always carries a stable `code` and
+ * (when the server provided one) a concrete `fix` field. **Read `error.fix`
+ * first** when debugging — it is by far the most actionable piece of data.
+ */
+export declare class RelipayError extends Error implements RelipayErrorShape {
+    readonly code: string;
+    readonly fix: string | undefined;
+    readonly docs: string | undefined;
+    readonly statusCode: number | undefined;
+    /** Server-assigned request id — share with support to look up the matching log entry. */
+    readonly requestId: string | undefined;
+    constructor(error: RelipayErrorShape & {
+        statusCode?: number;
+        requestId?: string;
+    });
+}
+/**
+ * Top-level ReliPay client. Auth and billing live as namespaces
+ * (`relipay.applications`, `relipay.auth`, `relipay.billing`) so an agent
+ * reading `relipay.` in an editor sees a discoverable surface.
+ */
+export declare class ReliPay {
+    private readonly apiUrl;
+    private readonly secretKey;
+    private readonly fetchImpl;
+    /** Operations on the calling Application itself. */
+    readonly applications: ApplicationsClient;
+    /** Auth operations — sign-in, sign-up, sessions, passkeys, magic-link. */
+    readonly auth: AuthClient;
+    /** Billing operations — plans, checkout, subscriptions, coupons. */
+    readonly billing: BillingClient;
+    /** End-user organizations — create, invite, members, role changes. */
+    readonly organizations: OrganizationsClient;
+    /** License key verification + activation. */
+    readonly licenses: LicensesClient;
+    /** Usage metering — record events, aggregate windows. */
+    readonly usage: UsageClient;
+    /** Prepaid credits — balance reads, idempotent drawdown, ledger. */
+    readonly credits: CreditsClient;
+    constructor(config: ReliPayConfig);
+    /** @internal */
+    request<T>(method: string, path: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<T>;
+}
+declare class ApplicationsClient {
+    private readonly client;
+    constructor(client: ReliPay);
+    /**
+     * Verify credentials and fetch the calling Application. Use this as your
+     * SDK smoke test — if it returns, your secret key is good and you're
+     * pointed at the right ReliPay deployment.
+     *
+     * @example
+     * ```ts
+     * const me = await relipay.applications.me();
+     * console.log(`Connected to "${me.name}" (${me.slug})`);
+     * ```
+     *
+     * @throws {RelipayError} with `code: "API_KEY_INVALID"` if the key is wrong/revoked/expired.
+     */
+    me(): Promise<ApplicationDto>;
+}
+declare class AuthClient {
+    private readonly client;
+    constructor(client: ReliPay);
+    /**
+     * Create a new end-user in the calling Application via email + password.
+     * Returns the user and a JWT to use for subsequent per-user calls
+     * (e.g. `getCurrentUser(token)`).
+     *
+     * @example
+     * ```ts
+     * const { endUser, token } = await relipay.auth.signUp({
+     *   email: 'alice@example.com',
+     *   password: 'correct-horse-battery-staple',
+     * });
+     * // store token in your session, return it to the browser, etc.
+     * ```
+     *
+     * @throws {RelipayError} `EMAIL_ALREADY_EXISTS` (409) if the email is taken in this Application.
+     * @throws {RelipayError} `PASSWORD_TOO_SHORT` (400) if shorter than the Application's `passwordMinLength`.
+     * @throws {RelipayError} `AUTH_METHOD_DISABLED` (400) if the Application doesn't have `"password"` enabled.
+     */
+    signUp(input: SignUpRequest): Promise<AuthResultDto>;
+    /**
+     * Authenticate an existing end-user with email + password.
+     *
+     * Returns a discriminated union over `mfaRequired`:
+     *   - `mfaRequired === false` → full `AuthResultDto` with access+refresh.
+     *   - `mfaRequired === true`  → `mfaChallengeToken` (5-minute lifetime).
+     *     Prompt the user for their TOTP / backup code and call
+     *     `mfaVerify({ mfaChallengeToken, code })` to receive a real session.
+     *
+     * **Branch on `result.mfaRequired` before reading `accessToken`** — the
+     * MFA-required branch has no session tokens.
+     *
+     * @throws {RelipayError} `INVALID_CREDENTIALS` (401) — single code on purpose.
+     *   Don't try to distinguish wrong-email from wrong-password from the SDK side either.
+     */
+    signIn(input: SignInRequest): Promise<SignInOutcomeDto>;
+    /**
+     * Exchange an MFA challenge token + TOTP/backup code for a real session.
+     * Use after `signIn` (or OAuth callback) returns `mfaRequired: true`.
+     *
+     * @throws {RelipayError} `MFA_CHALLENGE_INVALID` (401) if the token is
+     *   forged, expired, or signed with a different secret.
+     * @throws {RelipayError} `MFA_CHALLENGE_WRONG_APPLICATION` (401) if the
+     *   token was issued under a different Application.
+     * @throws {RelipayError} `MFA_CODE_INVALID` (401) if the code doesn't
+     *   verify against the user's TOTP secret or remaining backup codes.
+     */
+    mfaVerify(input: MfaVerifyRequest): Promise<AuthResultDto>;
+    /**
+     * Request a magic-link sign-in email. Enumeration-safe: same response
+     * shape whether the email exists or not. When the Application has
+     * email transport configured, the link is sent and `magicLinkToken`
+     * is null; otherwise the raw token is returned for you to forward.
+     */
+    requestMagicLink(input: {
+        email: string;
+        signInUrl?: string;
+    }): Promise<{
+        delivered: boolean;
+        emailSent: boolean;
+        magicLinkToken: string | null;
+    }>;
+    /**
+     * Consume a magic-link token. Returns `SignInOutcome` — branch on
+     * `mfaRequired` before reading `accessToken`. For MFA-enrolled users
+     * the response carries `mfaChallengeToken` and you must complete via
+     * `mfaVerify(...)`.
+     */
+    verifyMagicLink(input: {
+        token: string;
+    }): Promise<SignInOutcomeDto>;
+    /**
+     * Begin a passkey authentication ceremony. Returns the WebAuthn options
+     * to forward to the browser (`navigator.credentials.get(...)`) along
+     * with `expectedChallenge` — bind the challenge to your session and
+     * pass both back via `verifyPasskeyAuthentication(...)`.
+     */
+    startPasskeyAuthentication(input?: {
+        email?: string;
+    }): Promise<{
+        options: unknown;
+        expectedChallenge: string;
+    }>;
+    /**
+     * Complete a passkey authentication. Returns the same `SignInOutcome`
+     * shape as `signIn` — but passkeys are themselves a strong factor, so
+     * `mfaRequired` will always be `false` in practice.
+     */
+    verifyPasskeyAuthentication(input: {
+        response: unknown;
+        expectedChallenge: string;
+    }): Promise<SignInOutcomeDto>;
+    /**
+     * Begin a passkey registration ceremony for an authenticated user.
+     * Forward `options` to `navigator.credentials.create(...)`; store
+     * `expectedChallenge` in session; POST both back via
+     * `verifyPasskeyRegistration(...)`.
+     */
+    startPasskeyRegistration(accessToken: string): Promise<{
+        options: unknown;
+        expectedChallenge: string;
+    }>;
+    verifyPasskeyRegistration(accessToken: string, input: {
+        response: unknown;
+        expectedChallenge: string;
+        deviceName?: string;
+    }): Promise<{
+        credentialId: string;
+        deviceName: string | null;
+    }>;
+    /** List the user's registered passkeys. */
+    listPasskeys(accessToken: string): Promise<Array<{
+        id: string;
+        credentialId: string;
+        deviceName: string | null;
+        lastUsedAt: string | null;
+        createdAt: string;
+    }>>;
+    /** Remove a passkey. Returns `{deleted: false}` if the row doesn't belong to this user. */
+    deletePasskey(accessToken: string, credentialRowId: string): Promise<{
+        deleted: boolean;
+    }>;
+    createOrganization(accessToken: string, input: {
+        name: string;
+        slug: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        organization: {
+            id: string;
+            name: string;
+            slug: string;
+            metadata: unknown;
+            createdAt: string;
+            updatedAt: string;
+        };
+        membership: {
+            id: string;
+            role: 'OWNER' | 'ADMIN' | 'MEMBER';
+        };
+    }>;
+    listMyOrganizations(accessToken: string): Promise<Array<{
+        id: string;
+        name: string;
+        slug: string;
+        role: 'OWNER' | 'ADMIN' | 'MEMBER';
+        createdAt: string;
+    }>>;
+    inviteToOrganization(accessToken: string, organizationId: string, input: {
+        email: string;
+        role: 'OWNER' | 'ADMIN' | 'MEMBER';
+    }): Promise<{
+        invitation: {
+            id: string;
+            email: string;
+            role: 'OWNER' | 'ADMIN' | 'MEMBER';
+            expiresAt: string;
+        };
+        token: string;
+    }>;
+    acceptOrganizationInvitation(accessToken: string, input: {
+        token: string;
+    }): Promise<{
+        membership: {
+            id: string;
+            organizationId: string;
+            role: 'OWNER' | 'ADMIN' | 'MEMBER';
+        };
+    }>;
+    /**
+     * Resolve the end-user behind a presented access token.
+     *
+     * @throws {RelipayError} `USER_TOKEN_INVALID` (401) if expired/forged/wrong-secret.
+     * @throws {RelipayError} `USER_TOKEN_WRONG_APPLICATION` (401) if the token was issued
+     *   by a different Application than the calling secret key represents.
+     */
+    getCurrentUser(accessToken: string): Promise<EndUserDto>;
+    /**
+     * Exchange a refresh token for a fresh {access, refresh} pair. The presented
+     * refresh is revoked atomically — call this **once** and store the new
+     * `refreshToken` from the response immediately.
+     *
+     * @throws {RelipayError} `REFRESH_TOKEN_REUSED` (401) if you replay an already-used token.
+     *   This is a strong signal the original was leaked; treat as compromise.
+     * @throws {RelipayError} `REFRESH_TOKEN_EXPIRED` (401) after the 30-day refresh window.
+     */
+    refresh(refreshToken: string): Promise<AuthResultDto>;
+    /**
+     * Revoke a refresh token. Idempotent — no-op for unknown tokens. The
+     * access token paired with this refresh remains valid until its short
+     * (15 min) expiry; for true "log out everywhere" semantics, also clear
+     * the access token from your client.
+     */
+    signOut(refreshToken: string): Promise<{
+        signedOut: true;
+    }>;
+    /**
+     * Request a password-reset token for an email. Always succeeds — never
+     * tells you whether the email exists. **You must email the returned
+     * `resetToken` to the user**: ReliPay does not send email.
+     *
+     * @example
+     * ```ts
+     * const { resetToken } = await relipay.auth.requestPasswordReset({ email });
+     * if (resetToken) await sendgrid.send({ to: email, subject: 'Reset', text: `link: ${url(resetToken)}` });
+     * ```
+     */
+    requestPasswordReset(input: ForgotPasswordRequest): Promise<ForgotPasswordResultDto>;
+    /**
+     * Consume a reset token + set a new password. Single-use. On success,
+     * every refresh token for the user is revoked.
+     *
+     * @throws {RelipayError} `PASSWORD_RESET_TOKEN_INVALID` / `_USED` / `_EXPIRED` / `_WRONG_APPLICATION`
+     * @throws {RelipayError} `PASSWORD_TOO_SHORT` if below the Application's `passwordMinLength`
+     */
+    resetPassword(input: ResetPasswordRequest): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Authenticated password change. Pass the user's *current* access token.
+     * On success, every refresh token for the user is revoked — other devices
+     * are signed out.
+     */
+    changePassword(accessToken: string, input: ChangePasswordRequest): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Revoke every refresh token for the calling user. "Sign out of all
+     * devices." The caller's access token remains valid until 15-min expiry
+     * — clear it client-side for full logout.
+     */
+    signOutEverywhere(accessToken: string): Promise<{
+        revokedCount: number;
+    }>;
+    /**
+     * Send (or re-send) an email-verification link to the current user.
+     * If email transport is configured on the Application, ReliPay sends
+     * the email and `verificationToken` is null. Otherwise the raw token
+     * is returned for the caller to forward via their own provider.
+     *
+     * Pass `verifyUrl` containing `{token}` to template the link target
+     * (e.g. `https://app.example.com/verify?t={token}`).
+     */
+    sendVerificationEmail(accessToken: string, input?: {
+        verifyUrl?: string;
+    }): Promise<{
+        emailSent: boolean;
+        verificationToken: string | null;
+    }>;
+    /**
+     * Consume an email-verification token. Single-use, 24-hour lifetime.
+     * Marks `emailVerified: true` on the user record. Cross-Application
+     * tokens are refused with `EMAIL_VERIFICATION_TOKEN_WRONG_APPLICATION`.
+     */
+    verifyEmail(input: {
+        token: string;
+    }): Promise<{
+        verified: true;
+        endUser: EndUserDto;
+    }>;
+}
+interface OrganizationDto {
+    id: string;
+    name: string;
+    slug: string;
+    metadata: unknown;
+    createdAt: string;
+    updatedAt: string;
+}
+interface OrganizationWithRoleDto extends OrganizationDto {
+    role: 'OWNER' | 'ADMIN' | 'MEMBER';
+}
+interface OrganizationMemberDto {
+    id: string;
+    organizationId: string;
+    endUserId: string;
+    email: string;
+    role: 'OWNER' | 'ADMIN' | 'MEMBER';
+    createdAt: string;
+}
+interface OrganizationInvitationDto {
+    id: string;
+    organizationId: string;
+    email: string;
+    role: 'OWNER' | 'ADMIN' | 'MEMBER';
+    expiresAt: string;
+    createdAt: string;
+}
+declare class OrganizationsClient {
+    private readonly client;
+    constructor(client: ReliPay);
+    /** Create an organization; the calling user becomes the OWNER. */
+    create(accessToken: string, input: {
+        name: string;
+        slug: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        organization: OrganizationDto;
+        membership: {
+            id: string;
+            role: 'OWNER';
+        };
+    }>;
+    /** List organizations the calling user belongs to, with their role. */
+    listMine(accessToken: string): Promise<OrganizationWithRoleDto[]>;
+    /** Fetch one organization the caller belongs to. */
+    get(accessToken: string, organizationId: string): Promise<OrganizationWithRoleDto>;
+    /** Update org name / metadata. OWNER + ADMIN only. */
+    update(accessToken: string, organizationId: string, input: {
+        name?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<OrganizationDto>;
+    /** List members of an organization the caller belongs to. */
+    listMembers(accessToken: string, organizationId: string): Promise<OrganizationMemberDto[]>;
+    /**
+     * Invite a user. Returns the raw token ONCE — surface via your own
+     * email/share channel. OWNER + ADMIN only.
+     */
+    invite(accessToken: string, organizationId: string, input: {
+        email: string;
+        role: 'OWNER' | 'ADMIN' | 'MEMBER';
+    }): Promise<{
+        invitation: OrganizationInvitationDto;
+        token: string;
+    }>;
+    /** Revoke a pending invitation. OWNER + ADMIN only. Idempotent. */
+    revokeInvitation(accessToken: string, organizationId: string, invitationId: string): Promise<{
+        revoked: boolean;
+    }>;
+    /**
+     * Change a member's role. OWNER manages anyone; ADMIN manages MEMBER
+     * only. Last-OWNER guard refuses demoting the only OWNER.
+     */
+    setMemberRole(accessToken: string, organizationId: string, targetEndUserId: string, input: {
+        role: 'OWNER' | 'ADMIN' | 'MEMBER';
+    }): Promise<{
+        id: string;
+        organizationId: string;
+        endUserId: string;
+        role: 'OWNER' | 'ADMIN' | 'MEMBER';
+    }>;
+    /** Remove a member (or self). Refuses removing the last OWNER. */
+    removeMember(accessToken: string, organizationId: string, targetEndUserId: string): Promise<{
+        removed: true;
+    }>;
+    /** Self-leave. Refuses leaving as the last OWNER. */
+    leave(accessToken: string, organizationId: string): Promise<{
+        left: true;
+    }>;
+    /**
+     * Accept an organization invitation by raw token. Refuses cross-
+     * Application invitations. Idempotent if the caller is already a member.
+     */
+    acceptInvitation(accessToken: string, input: {
+        token: string;
+    }): Promise<{
+        membership: {
+            id: string;
+            organizationId: string;
+            role: 'OWNER' | 'ADMIN' | 'MEMBER';
+        };
+    }>;
+}
+interface LicenseShape {
+    id: string;
+    applicationId: string;
+    endUserId: string;
+    planId: string | null;
+    kind: 'PERPETUAL' | 'TIMED' | 'SEATS';
+    status: 'ACTIVE' | 'EXPIRED' | 'REVOKED';
+    keyPrefix: string;
+    expiresAt: string | null;
+    seatsAllowed: number | null;
+    metadata: unknown;
+    createdAt: string;
+    updatedAt: string;
+    revokedAt: string | null;
+}
+interface LicenseVerifyOk {
+    ok: true;
+    license: LicenseShape;
+}
+interface LicenseVerifyFail {
+    ok: false;
+    reason: 'unknown' | 'wrong_application' | 'revoked' | 'expired' | 'seats_exhausted';
+    license?: LicenseShape;
+}
+type LicenseVerifyResult = LicenseVerifyOk | LicenseVerifyFail;
+declare class LicensesClient {
+    private readonly client;
+    constructor(client: ReliPay);
+    /**
+     * Verify a license key + record an activation for this machine. Call
+     * once at app startup; you'll get a deterministic body (`ok=false` for
+     * invalid licenses — never an HTTP error — so your software can loop
+     * on the result without try/catch noise).
+     *
+     * `machineFingerprint` should be a stable identifier you derive client-
+     * side (hostname + OS + mac address, hashed). The same fingerprint
+     * across re-verifications does NOT consume a new seat.
+     *
+     * @example
+     * ```ts
+     * const result = await relipay.licenses.verify({
+     *   key,
+     *   machineFingerprint,
+     *   label: 'Adam\'s MacBook',
+     * });
+     * if (!result.ok) showLicenseError(result.reason);
+     * ```
+     */
+    verify(input: {
+        key: string;
+        machineFingerprint: string;
+        label?: string;
+    }): Promise<LicenseVerifyResult>;
+}
+interface UsageRecordDto {
+    id: string;
+    applicationId: string;
+    meterSlug: string;
+    quantity: number;
+    endUserId: string | null;
+    occurredAt: string;
+}
+interface UsageAggregateDto {
+    meterSlug: string;
+    total: number;
+    from: string | null;
+    to: string | null;
+}
+declare class UsageClient {
+    private readonly client;
+    constructor(client: ReliPay);
+    /**
+     * Record a usage event against a named meter. `quantity` can be
+     * negative to credit back (e.g. refunds). `occurredAt` defaults to
+     * server time; pass an ISO string when ingesting historical events.
+     */
+    record(input: {
+        meterSlug: string;
+        quantity: number;
+        endUserId?: string;
+        occurredAt?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<UsageRecordDto>;
+    /**
+     * Sum recorded quantity for a meter, optionally bounded by a time
+     * window and/or scoped to one end-user. Use to drive in-app "you've
+     * used X of your Y quota this month" displays.
+     */
+    aggregate(input: {
+        meterSlug: string;
+        from?: string;
+        to?: string;
+        endUserId?: string;
+    }): Promise<UsageAggregateDto>;
+}
+/**
+ * Prepaid credits — the "lead pack" / pay-as-you-go drawdown model. The
+ * customer's backend grants credits (by selling a CREDIT-kind plan, which
+ * grants automatically on payment) and draws them down per unit consumed.
+ *
+ * All calls are server-to-server (secret key) and scoped to an end-user id.
+ */
+declare class CreditsClient {
+    private readonly client;
+    constructor(client: ReliPay);
+    /** Current spendable balance for an end-user (0 if they've never held credits). */
+    getBalance(endUserId: string): Promise<CreditBalanceDto>;
+    /**
+     * Deduct credits from an end-user. Throws `RelipayError` with
+     * `code: "CREDITS_INSUFFICIENT"` (HTTP 402) when the balance is too low.
+     *
+     * Pass `idempotencyKey` (e.g. the lead id) so a retried call never
+     * double-charges — a repeat with the same key returns the original result
+     * with `applied: false`.
+     */
+    consume(input: ConsumeCreditsRequest & {
+        endUserId: string;
+    }): Promise<{
+        balance: number;
+        entryId: string;
+        applied: boolean;
+    }>;
+    /** Recent ledger entries for an end-user, newest first. */
+    listLedger(endUserId: string, limit?: number): Promise<CreditLedgerEntryDto[]>;
+}
+/**
+ * Verify the HMAC signature on an inbound webhook from ReliPay. Returns
+ * `true` only when (a) the timestamp is fresh (within `toleranceSeconds`,
+ * default 300) AND (b) the signature matches a constant-time compare.
+ *
+ * Use against the `X-Relipay-Signature` header and the raw request body
+ * BYTES (not the parsed JSON — any reserialization breaks the HMAC).
+ *
+ * @example
+ * ```ts
+ * import { verifyWebhookSignature } from '@relipay/node';
+ *
+ * app.post('/webhooks/relipay', { config: { rawBody: true } }, (req) => {
+ *   const ok = verifyWebhookSignature({
+ *     header: req.headers['x-relipay-signature'] as string,
+ *     payload: req.rawBody!,
+ *     secret: process.env.RELIPAY_WEBHOOK_SECRET!,
+ *   });
+ *   if (!ok) return reply.status(401).send({ error: 'bad signature' });
+ *   // safe to act on req.body
+ * });
+ * ```
+ */
+export declare function verifyWebhookSignature(args: {
+    header: string | null | undefined;
+    payload: string | Buffer;
+    secret: string;
+    toleranceSeconds?: number;
+    now?: () => number;
+}): boolean;
+declare class BillingClient {
+    private readonly client;
+    constructor(client: ReliPay);
+    /**
+     * List the calling Application's active plans. Public — pricing pages
+     * typically render straight from this. Application API key only; no
+     * user JWT needed.
+     *
+     * `amount` is in the smallest currency unit (cents/paise/sen) — never
+     * a float. Format on display: `${amount / 100} ${currency}`.
+     */
+    getPlans(): Promise<PlanDto[]>;
+    /**
+     * Fetch the current end-user's active subscription, or `null` if they
+     * have none. Returns the most recent ACTIVE / PENDING / PAST_DUE row.
+     *
+     * Pass the user's access token (the SDK puts it in `X-Relipay-User-Token`).
+     */
+    getSubscription(accessToken: string): Promise<SubscriptionDto | null>;
+    /**
+     * Start a hosted-checkout session. Returns the URL to redirect the user
+     * to and the local PENDING Subscription row. Subscription activation
+     * happens via the provider's webhook — not synchronously here.
+     *
+     * Pass `couponCode` to apply a discount. The whole checkout fails if the
+     * coupon doesn't validate (typed `RelipayError` with the precise reason).
+     *
+     * @example
+     * ```ts
+     * const { url, discountAmount } = await relipay.billing.createCheckout(userAccessToken, {
+     *   planSlug: 'pro_monthly',
+     *   successUrl: 'https://yourapp.com/billing?status=ok',
+     *   cancelUrl:  'https://yourapp.com/billing?status=cancel',
+     *   couponCode: 'LAUNCH50', // optional
+     * });
+     * res.redirect(url);
+     * ```
+     */
+    createCheckout(accessToken: string, input: CreateCheckoutRequest & {
+        couponCode?: string;
+    }): Promise<CheckoutResultDto>;
+    /**
+     * Validate a coupon for the current user against a plan, *without*
+     * applying it. Render "$50 off" on a pricing page before submit.
+     *
+     * @throws {RelipayError} with one of `COUPON_NOT_FOUND` / `COUPON_INACTIVE`
+     *   / `COUPON_NOT_YET_STARTED` / `COUPON_EXPIRED` / `COUPON_NOT_APPLICABLE`
+     *   / `COUPON_CURRENCY_MISMATCH` / `COUPON_REDEMPTION_LIMIT_REACHED` /
+     *   `COUPON_USER_LIMIT_REACHED`. Surface the message + fix to the user.
+     */
+    validateCoupon(accessToken: string, input: ValidateCouponRequest): Promise<ValidateCouponResultDto>;
+    /**
+     * List the billing providers configured + enabled for this Application,
+     * in the order the geo router would prefer them. Forward the end-user's
+     * `country` (ISO 3166-1 alpha-2) when you have it — the panel/SDK will
+     * surface India-specific providers (Razorpay) for IN-country users, etc.
+     *
+     * Returns the resolved country (echoed back from the server's view of
+     * `CF-IPCountry` etc.) plus the ordered provider list. Use this to render
+     * a "Pay with..." picker on your pricing page.
+     */
+    getProviders(country?: string): Promise<ProvidersListDto>;
+}
+//# sourceMappingURL=index.d.ts.map