@elapse/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,359 @@
+/**
+ * Event types (FR-SDK-023; detailed doc §5.1, §5.3). The union is exhaustive
+ * for the six MVP types and keeps a fallback member for types this SDK version
+ * does not know: a valid signature on a new type is still a genuine event.
+ */
+type EventType = "checkout.session.completed" | "subscription.created" | "subscription.updated" | "subscription.canceled" | "invoice.settled" | "invoice.payment_failed";
+type SubscriptionStatus = "incomplete" | "active" | "paused" | "canceled";
+interface EventBase {
+    id: `evt_${string}` | string;
+    object: "event";
+    created: number;
+    livemode: boolean;
+    pending_webhooks: number;
+    request?: {
+        id: string | null;
+        idempotency_key: string | null;
+    };
+}
+interface SubscriptionObject {
+    id: string;
+    object: "subscription";
+    status: SubscriptionStatus;
+    product: string;
+    customer: string;
+    rate_usd_per_second: string;
+    started_at: number | null;
+    paused_at: number | null;
+    canceled_at: number | null;
+    ended_reason: "canceled" | "cap_reached" | null;
+    max_duration_seconds: number | null;
+    max_escrow_usd: string | null;
+    funded_usd: string;
+    settled_usd: string;
+    seconds_elapsed: number;
+    currency: "ausd";
+    livemode: boolean;
+    created: number;
+    [extra: string]: unknown;
+}
+/** §5.3: cumulative totals for the subscription (BR-API-008). */
+interface CanceledSubscriptionObject extends SubscriptionObject {
+    status: "canceled";
+    seconds_elapsed: number;
+    amount_settled: string;
+}
+interface InvoiceObject {
+    id: string;
+    object: "invoice";
+    subscription: string;
+    period_start: number;
+    period_end: number;
+    seconds: number;
+    amount_settled: string;
+    gross: string;
+    fee: string;
+    net: string;
+    currency: "ausd";
+    status: "paid" | "failed";
+    livemode: boolean;
+    created: number;
+    [extra: string]: unknown;
+}
+interface CheckoutSessionCompletedObject {
+    id: string;
+    object: "checkout.session";
+    status: "complete";
+    subscription: string;
+    customer: string;
+    product: string;
+    livemode: boolean;
+    created: number;
+    [extra: string]: unknown;
+}
+type ElapseEvent = (EventBase & {
+    type: "checkout.session.completed";
+    data: {
+        object: CheckoutSessionCompletedObject;
+    };
+}) | (EventBase & {
+    type: "subscription.created";
+    data: {
+        object: SubscriptionObject;
+    };
+}) | (EventBase & {
+    type: "subscription.updated";
+    data: {
+        object: SubscriptionObject;
+    };
+}) | (EventBase & {
+    type: "subscription.canceled";
+    data: {
+        object: CanceledSubscriptionObject;
+    };
+}) | (EventBase & {
+    type: "invoice.settled";
+    data: {
+        object: InvoiceObject;
+    };
+}) | (EventBase & {
+    type: "invoice.payment_failed";
+    data: {
+        object: InvoiceObject;
+    };
+})
+/**
+ * A type newer than this SDK version. It is verified and returned all the
+ * same (a valid signature is what makes it genuine); switch on `type` and
+ * ignore what you do not handle. `data.object` is typed `never` here so that
+ * narrowing on a known `type` still gives you the known shape; in a
+ * `default` branch cast it, e.g. `evt.data.object as Record<string, unknown>`.
+ */
+ | (EventBase & {
+    type: string;
+    data: {
+        object: never;
+    };
+});
+
+/** Per-request options accepted as the last argument of every method (FR-SDK-014). */
+interface RequestOptions {
+    /** Reused across this call's retries. Generated as a UUID for create/cancel when absent (FR-SDK-013). */
+    idempotencyKey?: string;
+    /** Overrides the client default (30 s). */
+    timeoutMs?: number;
+}
+interface TransportConfig {
+    secretKey: string;
+    baseUrl: string;
+    maxRetries: number;
+    timeoutMs: number;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * The one HTTP path (FR-SDK-010–014). Retries network errors, 429 and 5xx
+ * with `500 ms × 2ⁿ ± 25 %` jitter up to `maxRetries`, honouring `Retry-After`
+ * on 429. 4xx other than 429 are thrown at once. Non-2xx bodies in the
+ * FR-API-082 shape map to the error classes.
+ */
+declare class Transport {
+    #private;
+    constructor(cfg: TransportConfig);
+    /** Overridable for tests. */
+    _sleep(ms: number): Promise<void>;
+    request<T>(method: "GET" | "POST" | "DELETE", path: string, body?: Record<string, unknown>, opts?: RequestOptions): Promise<T>;
+}
+
+/** Stripe-style list page (API FR-API-080). */
+interface List<T> {
+    object: "list";
+    data: T[];
+    has_more: boolean;
+    url: string;
+}
+interface ListParams {
+    /** 1–100, default 10. */
+    limit?: number;
+    /** Id of the last object of the previous page. */
+    startingAfter?: string;
+}
+interface Product {
+    id: string;
+    object: "product";
+    name: string;
+    description: string | null;
+    /** USD per second, decimal string. Never parse it to a number for money math. */
+    rate_usd_per_second: string;
+    rate_per_second_wei: string;
+    currency: "ausd";
+    allow_pause: boolean;
+    active: boolean;
+    livemode: boolean;
+    created: number;
+}
+interface CheckoutSession {
+    id: string;
+    object: "checkout.session";
+    status: "open" | "complete" | "expired";
+    /** Send the subscriber here. */
+    url: string;
+    livemode: boolean;
+    created: number;
+    expires_at: number;
+    success_url: string;
+    cancel_url: string;
+    product: Product;
+    merchant: {
+        name: string;
+        logo_url: string | null;
+        accent: string | null;
+        support_url: string | null;
+    };
+    customer: string | null;
+    subscription: string | null;
+    max_duration_seconds: number | null;
+    max_escrow_usd: string | null;
+}
+type Subscription = SubscriptionObject;
+interface Customer {
+    id: string;
+    object: "customer";
+    email: string | null;
+    livemode: boolean;
+    created: number;
+    [extra: string]: unknown;
+}
+interface Invoice {
+    id: string;
+    object: "invoice";
+    subscription: string;
+    period_start: number;
+    period_end: number;
+    seconds: number;
+    amount_settled: string;
+    gross: string;
+    fee: string;
+    net: string;
+    currency: "ausd";
+    status: "paid" | "failed";
+    livemode: boolean;
+    created: number;
+}
+/** `products.create/retrieve/list` (FR-SDK-002, FR-SDK-003). */
+declare function products(t: Transport): {
+    create(params: {
+        name: string;
+        rateUsdPerSecond: string;
+        allowPause?: boolean;
+        description?: string;
+    }, opts?: RequestOptions): Promise<Product>;
+    retrieve(id: string, opts?: RequestOptions): Promise<Product>;
+    list(params?: ListParams, opts?: RequestOptions): Promise<List<Product>>;
+};
+/** `checkout.sessions.create` (FR-SDK-004). */
+declare function checkout(t: Transport): {
+    sessions: {
+        create(params: {
+            product: string;
+            successUrl: string;
+            cancelUrl: string;
+            maxDurationSeconds?: number;
+        }, opts?: RequestOptions): Promise<CheckoutSession>;
+    };
+};
+/** `subscriptions.retrieve/list/cancel` (FR-SDK-005, FR-SDK-008). No pause or resume. */
+declare function subscriptions(t: Transport): {
+    retrieve(id: string, opts?: RequestOptions): Promise<Subscription>;
+    list(params?: ListParams & {
+        customer?: string;
+        product?: string;
+        status?: SubscriptionStatus;
+    }, opts?: RequestOptions): Promise<List<Subscription>>;
+    /** Asks the platform to end the meter; the `canceled` status arrives via webhook once the chain confirms (API FR-API-042). */
+    cancel(id: string, opts?: RequestOptions): Promise<Subscription>;
+};
+/** `customers.retrieve` (FR-SDK-006). */
+declare function customers(t: Transport): {
+    retrieve(id: string, opts?: RequestOptions): Promise<Customer>;
+};
+/** `invoices.list` (FR-SDK-006). */
+declare function invoices(t: Transport): {
+    list(params?: ListParams & {
+        subscription?: string;
+        customer?: string;
+    }, opts?: RequestOptions): Promise<List<Invoice>>;
+};
+
+/** FR-SDK-022: test hooks. Defaults: 300 s tolerance, wall clock. */
+interface ConstructEventOptions {
+    /** Seconds. `Infinity` disables the age check (tests only). */
+    tolerance?: number;
+    /** Unix seconds. */
+    now?: () => number;
+}
+/**
+ * Verify `X-Elapse-Signature` and parse the event (FR-SDK-020, FR-SDK-021;
+ * detailed doc §4.4). Header: `t=<unix>,v1=<hex>[,v1=<hex>…]`. The signed
+ * string is `${t}.${rawBody}`. Every `v1` is collected and every
+ * (secret, v1) pair is compared in constant time with no early exit, so a
+ * merchant mid secret-roll verifies against either secret and timing reveals
+ * nothing about which matched. Always pass the raw request body: never a
+ * re-serialised object (BR-SDK-003).
+ */
+declare function constructEvent(rawBody: string | Uint8Array, header: string | undefined, secret: string | readonly string[] | undefined, options?: ConstructEventOptions): ElapseEvent;
+
+/**
+ * Error classes (FR-SDK-011, FR-SDK-021). Every error the SDK throws extends
+ * `ElapseError`, so `catch (e) { if (e instanceof ElapseError) … }` is enough.
+ * Messages never contain the secret key, a webhook secret, or a payload body.
+ */
+declare class ElapseError extends Error {
+    /** HTTP status, when the error came from a response. */
+    readonly status: number | undefined;
+    /** The API's `error.type` (`invalid_request_error`, …), when present. */
+    readonly type: string | undefined;
+    readonly code: string | undefined;
+    readonly param: string | undefined;
+    readonly requestId: string | undefined;
+    constructor(message: string, fields?: {
+        status?: number;
+        type?: string;
+        code?: string;
+        param?: string;
+        requestId?: string;
+    });
+}
+/** 401/403: bad, missing or revoked key. */
+declare class ElapseAuthenticationError extends ElapseError {
+}
+/** 400/404/422, and client-side validation before a request is sent. */
+declare class ElapseInvalidRequestError extends ElapseError {
+}
+/** 429. `retryAfter` in seconds when the API sent it. */
+declare class ElapseRateLimitError extends ElapseError {
+    readonly retryAfter: number | undefined;
+    constructor(message: string, fields?: ConstructorParameters<typeof ElapseError>[1] & {
+        retryAfter?: number;
+    });
+}
+/** 5xx, unparseable bodies, network failures and timeouts (`code: "timeout"`). */
+declare class ElapseAPIError extends ElapseError {
+}
+/** `constructEvent` refused the payload; the reason is in the message, never the body. */
+declare class ElapseSignatureVerificationError extends ElapseError {
+}
+
+interface ElapseConfig {
+    /** `sk_test_…` or `sk_live_…`, usually `process.env.ELAPSE_SECRET_KEY`. Server-side only. `undefined` throws at construction. */
+    secretKey: string | undefined;
+    /** Defaults to `https://api.elapse.dev`. */
+    baseUrl?: string;
+    /** Transient-failure retries (network, 429, 5xx). Default 2. */
+    maxRetries?: number;
+    /** Per-request timeout in ms. Default 30 000. */
+    timeoutMs?: number;
+}
+declare class Elapse {
+    #private;
+    readonly baseUrl: string;
+    readonly maxRetries: number;
+    readonly timeoutMs: number;
+    readonly products: ReturnType<typeof products>;
+    readonly checkout: ReturnType<typeof checkout>;
+    readonly subscriptions: ReturnType<typeof subscriptions>;
+    readonly customers: ReturnType<typeof customers>;
+    readonly invoices: ReturnType<typeof invoices>;
+    readonly webhooks: {
+        /** Verify a webhook and parse the event. Pass the raw body, never a parsed object. */
+        constructEvent: (rawBody: string | Uint8Array, header: string | undefined, secret: string | readonly string[] | undefined, options?: ConstructEventOptions) => ElapseEvent;
+    };
+    constructor(config: ElapseConfig);
+    /** Test hook: override the retry sleep. Not part of the public surface. */
+    set _sleep(fn: (ms: number) => Promise<void>);
+    /** Never leak the key through logging (BR-SDK-002). */
+    toJSON(): {
+        baseUrl: string;
+    };
+}
+
+export { type CanceledSubscriptionObject, type CheckoutSession, type CheckoutSessionCompletedObject, type ConstructEventOptions, type Customer, Elapse, ElapseAPIError, ElapseAuthenticationError, type ElapseConfig, ElapseError, type ElapseEvent, ElapseInvalidRequestError, ElapseRateLimitError, ElapseSignatureVerificationError, type EventType, type Invoice, type InvoiceObject, type List, type ListParams, type Product, type RequestOptions, type Subscription, type SubscriptionObject, type SubscriptionStatus, constructEvent };