@beinfi/pulse-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1094 @@
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(apiKey: string, baseUrl?: string);
+    request<T>(method: string, path: string, options?: {
+        body?: unknown;
+        query?: Record<string, string | number | undefined>;
+    }): Promise<T>;
+    private parseRateLimit;
+    private safeJson;
+    private handleError;
+}
+
+/**
+ * Configuration options for the Pulse SDK client.
+ *
+ * @example
+ * ```typescript
+ * const pulse = new Pulse({
+ *   apiKey: 'sk_live_...',
+ *   baseUrl: 'https://api.beinfi.com'
+ * })
+ * ```
+ */
+interface PulseConfig {
+    /** API key starting with `sk_live_`. Obtain from the Pulse dashboard under Developers > API Keys. */
+    apiKey: string;
+    /** Override the API base URL. Defaults to `https://api.beinfi.com`. */
+    baseUrl?: string;
+}
+/**
+ * Parameters for creating a new payment link.
+ *
+ * @example
+ * ```typescript
+ * const link = await pulse.paymentLinks.create({
+ *   title: 'Web Development',
+ *   amount: '150.00',
+ *   currency: 'USD',
+ *   description: 'Landing page development'
+ * })
+ * ```
+ */
+interface CreatePaymentLinkParams {
+    /** Human-readable title shown to the payer (e.g. "Order #42"). */
+    title: string;
+    /** Payment amount as a decimal string (e.g. `"99.90"`). */
+    amount: string;
+    /** Optional description shown on the checkout page. */
+    description?: string;
+    /** Currency code. Defaults to `"USD"`. */
+    currency?: 'USD' | 'BRL';
+}
+/**
+ * A payment link object returned by the API.
+ *
+ * @example
+ * ```typescript
+ * const link = await pulse.paymentLinks.get('link-id')
+ * console.log(link.title, link.amount, link.status)
+ * ```
+ */
+interface PaymentLink {
+    /** Unique identifier (UUID). */
+    id: string;
+    /** Human-readable title. */
+    title: string;
+    /** Optional description, or `null` if not set. */
+    description: string | null;
+    /** Payment amount as a decimal string (e.g. `"100.00"`). */
+    amount: string;
+    /** Currency code (e.g. `"USD"`, `"BRL"`). */
+    currency: string;
+    /** Current status of the link (e.g. `"active"`, `"inactive"`). */
+    status: string;
+    /** URL-friendly slug for the payment page. */
+    slug: string;
+    /** ID of the user who created this link. */
+    userId: string;
+    /** ISO 8601 timestamp of creation. */
+    createdAt: string;
+    /** ISO 8601 timestamp of last update. */
+    updatedAt: string;
+}
+/**
+ * Query parameters for listing payment links.
+ *
+ * @example
+ * ```typescript
+ * const links = await pulse.paymentLinks.list({ limit: 10, offset: 0 })
+ * ```
+ */
+interface ListPaymentLinksParams {
+    /** Maximum number of results to return. Defaults to 20. */
+    limit?: number;
+    /** Number of results to skip (for pagination). Defaults to 0. */
+    offset?: number;
+}
+/**
+ * A payment intent represents a single payment attempt against a payment link.
+ *
+ * @example
+ * ```typescript
+ * const intents = await pulse.paymentLinks.listIntents('link-id')
+ * for (const intent of intents) {
+ *   console.log(intent.status, intent.amount, intent.method)
+ * }
+ * ```
+ */
+interface PaymentIntent {
+    /** Unique identifier (UUID). */
+    id: string;
+    /** ID of the parent payment link. */
+    paymentLinkId: string;
+    /** Payment amount as a decimal string, or `null` if not yet determined. */
+    amount: string;
+    /** Currency code (e.g. `"USD"`). */
+    currency: string;
+    /** Intent status: `"pending"` | `"observed"` | `"confirmed"` | `"failed"` | `"expired"`. */
+    status: string;
+    /** Payment method used (e.g. `"crypto"`, `"pix"`), or `null` if not yet selected. */
+    method: string | null;
+    /** Blockchain transaction hash, or `null` if not a crypto payment. */
+    txHash: string | null;
+    /** ISO 8601 timestamp when the payment was confirmed, or `null`. */
+    confirmedAt: string | null;
+    /** ISO 8601 timestamp of creation. */
+    createdAt: string;
+    /** ISO 8601 timestamp of last update. */
+    updatedAt: string;
+}
+/**
+ * A confirmed payment that has been received and credited.
+ *
+ * @example
+ * ```typescript
+ * // Received payments are delivered via webhook payloads
+ * // or can be queried from the dashboard
+ * ```
+ */
+interface ReceivedPayment {
+    /** Unique identifier (UUID). */
+    id: string;
+    /** Payment amount as a decimal string. */
+    amount: string;
+    /** Currency code. */
+    currency: string;
+    /** Payment method (e.g. `"crypto"`, `"pix"`). */
+    method: string;
+    /** Blockchain transaction hash, or `null` for non-crypto payments. */
+    txHash: string | null;
+    /** ISO 8601 timestamp when the payment was confirmed. */
+    confirmedAt: string;
+    /** ID of the payment link this payment belongs to. */
+    paymentLinkId: string;
+    /** ISO 8601 timestamp of creation. */
+    createdAt: string;
+}
+/**
+ * Query parameters for listing received payments.
+ */
+interface ListReceivedPaymentsParams {
+    /** Maximum number of results to return. */
+    limit?: number;
+    /** Number of results to skip (for pagination). */
+    offset?: number;
+}
+/**
+ * Parameters for creating a new webhook subscription.
+ *
+ * @example
+ * ```typescript
+ * const wh = await pulse.webhooks.create({
+ *   url: 'https://example.com/webhook',
+ *   events: ['payment.confirmed']
+ * })
+ * // Save wh.secret — it's only returned once at creation time
+ * ```
+ */
+interface CreateWebhookParams {
+    /** The HTTPS URL that will receive webhook POST requests. */
+    url: string;
+    /** Array of event types to subscribe to (e.g. `["payment.confirmed"]`). */
+    events: string[];
+}
+/**
+ * A webhook subscription object.
+ *
+ * @example
+ * ```typescript
+ * const webhooks = await pulse.webhooks.list()
+ * for (const wh of webhooks) {
+ *   console.log(wh.url, wh.events, wh.isActive)
+ * }
+ * ```
+ */
+interface Webhook {
+    /** Unique identifier (UUID). */
+    id: string;
+    /** The URL receiving webhook deliveries. */
+    url: string;
+    /** Event types this webhook is subscribed to. */
+    events: string[];
+    /** Whether the webhook is currently active. */
+    isActive: boolean;
+    /** ISO 8601 timestamp of creation. */
+    createdAt: string;
+}
+/**
+ * Webhook object returned after creation, includes the signing secret.
+ * The `secret` is only returned once — store it securely.
+ *
+ * @example
+ * ```typescript
+ * const wh = await pulse.webhooks.create({
+ *   url: 'https://example.com/webhook',
+ *   events: ['payment.confirmed']
+ * })
+ * console.log(wh.secret) // "a1b2c3..." (64-char hex) — save this!
+ * ```
+ */
+interface WebhookCreated extends Webhook {
+    /** HMAC signing secret (64-character hex string). Only returned at creation time. */
+    secret: string;
+}
+/**
+ * The payload delivered to your webhook endpoint when a `payment.confirmed` event fires.
+ * Sent as a JSON POST with `X-Pulse-Signature` and `X-Pulse-Event` headers.
+ *
+ * @example
+ * ```typescript
+ * // In your webhook handler:
+ * app.post('/webhook', (req) => {
+ *   const isValid = Pulse.webhooks.verifySignature(
+ *     req.rawBody,
+ *     req.headers['x-pulse-signature'],
+ *     process.env.WEBHOOK_SECRET
+ *   )
+ *   if (!isValid) return res.status(401).send('Invalid signature')
+ *
+ *   const payload: WebhookPayload = req.body
+ *   console.log('Payment confirmed:', payload.paymentIntentId, payload.amount)
+ * })
+ * ```
+ */
+interface WebhookPayload {
+    /** ID of the confirmed payment intent. */
+    paymentIntentId: string;
+    /** Payment amount as a decimal string. */
+    amount: string;
+    /** Currency code. */
+    currency: string;
+    /** Payment method used (e.g. `"crypto"`, `"pix"`). */
+    method: string;
+    /** ISO 8601 timestamp when the payment was confirmed. */
+    confirmedAt: string;
+    /** Blockchain transaction hash (present for crypto payments). */
+    txHash?: string;
+}
+/**
+ * Parameters for tracking a usage event.
+ *
+ * @example
+ * ```typescript
+ * await pulse.metering.track({
+ *   meterId: 'tokens',
+ *   customerId: 'user_123',
+ *   value: 1500,
+ *   metadata: { model: 'gpt-4' }
+ * })
+ * ```
+ */
+interface TrackEventParams {
+    /** Idempotency key. Auto-generated if not provided. */
+    eventId?: string;
+    /** Meter ID or slug to track against. */
+    meterId: string;
+    /** Your customer's identifier (externalId). */
+    customerId: string;
+    /** Quantity consumed (e.g. number of tokens). */
+    value: number | string;
+    /** When the event occurred. Defaults to now. */
+    timestamp?: Date;
+    /** Additional metadata attached to the event. */
+    metadata?: Record<string, unknown>;
+}
+/** A tracked event as returned by the API. */
+interface TrackEventResponse {
+    id: string;
+    eventId: string;
+    meterId: string;
+    customerId: string;
+    value: string;
+    timestamp: string;
+    createdAt: string;
+}
+/** Result of a batch track operation. */
+interface BatchTrackResponse {
+    accepted: number;
+    failed: number;
+    results: TrackEventResponse[];
+    errors?: Array<{
+        eventId?: string;
+        error: string;
+    }>;
+}
+/** Query parameters for aggregated usage. */
+interface UsageQuery {
+    customerId?: string;
+    startDate?: string;
+    endDate?: string;
+}
+/** A single meter's aggregated usage. */
+interface UsageItem {
+    meterId: string;
+    meterName: string;
+    unit: string;
+    unitPrice: string;
+    totalValue: string;
+    totalAmount: string;
+    eventCount: number;
+}
+/** Aggregated usage response. */
+interface UsageResponse {
+    data: UsageItem[];
+}
+/** Parameters for creating a customer on a product. */
+interface CreateCustomerParams {
+    externalId: string;
+    name?: string;
+    email?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Parameters for creating a product. */
+interface CreateProductParams {
+    name: string;
+    description?: string;
+}
+/** Parameters for creating a meter on a product. */
+interface CreateMeterParams {
+    name: string;
+    displayName: string;
+    unit: string;
+    unitPrice: string;
+}
+/** A meter object returned by the API. */
+interface Meter {
+    id: string;
+    name: string;
+    displayName: string;
+    unit: string;
+    unitPrice: string;
+    status: string;
+}
+/** A product with meters. */
+interface MeteringProduct {
+    id: string;
+    name: string;
+    description?: string;
+    status: string;
+    meters: Array<{
+        id: string;
+        name: string;
+        displayName: string;
+        unit: string;
+        unitPrice: string;
+    }>;
+}
+/** A customer linked to a product. */
+interface ProductCustomer {
+    id: string;
+    externalId: string;
+    name?: string | null;
+    email?: string | null;
+    createdAt: string;
+}
+/**
+ * Rate limit information returned in API response headers.
+ * Available on every response as `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
+ */
+interface RateLimitInfo {
+    /** Maximum requests allowed per minute for your tier (free=100, pro=1000, enterprise=5000). */
+    limit: number;
+    /** Remaining requests in the current window. */
+    remaining: number;
+    /** Unix timestamp (seconds) when the rate limit window resets. */
+    reset: number;
+}
+/**
+ * Shape of error responses returned by the Pulse API.
+ *
+ * @example
+ * ```json
+ * { "error": "unauthorized", "message": "Invalid API key" }
+ * ```
+ */
+interface ApiErrorResponse {
+    /** Machine-readable error code (e.g. `"unauthorized"`, `"rate_limit_exceeded"`). */
+    error: string;
+    /** Human-readable error description. */
+    message: string;
+}
+
+/**
+ * Resource for managing payment links.
+ * Access via `pulse.paymentLinks`.
+ *
+ * @example
+ * ```typescript
+ * const pulse = new Pulse('sk_live_...')
+ *
+ * // Create a payment link
+ * const link = await pulse.paymentLinks.create({
+ *   title: 'Order #42',
+ *   amount: '100.00',
+ * })
+ *
+ * // List all links
+ * const links = await pulse.paymentLinks.list({ limit: 10 })
+ * ```
+ */
+declare class PaymentLinksResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Create a new payment link.
+     *
+     * @param params - Payment link parameters (title, amount, optional currency and description).
+     * @returns The created payment link object.
+     * @throws {PulseAuthenticationError} If the API key is invalid.
+     * @throws {PulseApiError} If validation fails (e.g. invalid currency).
+     *
+     * @example
+     * ```typescript
+     * const link = await pulse.paymentLinks.create({
+     *   title: 'Web Development',
+     *   amount: '150.00',
+     *   currency: 'USD',
+     *   description: 'Landing page development',
+     * })
+     * console.log(link.id, link.slug)
+     * ```
+     */
+    create(params: CreatePaymentLinkParams): Promise<PaymentLink>;
+    /**
+     * List payment links for the authenticated user.
+     *
+     * @param params - Optional pagination parameters (limit, offset).
+     * @returns Array of payment link objects.
+     * @throws {PulseAuthenticationError} If the API key is invalid.
+     *
+     * @example
+     * ```typescript
+     * const links = await pulse.paymentLinks.list({ limit: 10, offset: 0 })
+     * for (const link of links) {
+     *   console.log(link.title, link.amount, link.status)
+     * }
+     * ```
+     */
+    list(params?: ListPaymentLinksParams): Promise<PaymentLink[]>;
+    /**
+     * Get a single payment link by ID.
+     *
+     * @param linkId - The payment link UUID.
+     * @returns The payment link object.
+     * @throws {PulseAuthenticationError} If the API key is invalid.
+     * @throws {PulseApiError} With status 404 if the link doesn't exist.
+     *
+     * @example
+     * ```typescript
+     * const link = await pulse.paymentLinks.get('abc-123-def')
+     * console.log(link.title, link.amount)
+     * ```
+     */
+    get(linkId: string): Promise<PaymentLink>;
+    /**
+     * List payment intents (payment attempts) for a specific payment link.
+     *
+     * @param linkId - The payment link UUID.
+     * @returns Array of payment intent objects.
+     * @throws {PulseAuthenticationError} If the API key is invalid.
+     *
+     * @example
+     * ```typescript
+     * const intents = await pulse.paymentLinks.listIntents('abc-123-def')
+     * const confirmed = intents.filter(i => i.status === 'confirmed')
+     * console.log(`${confirmed.length} confirmed payments`)
+     * ```
+     */
+    listIntents(linkId: string): Promise<PaymentIntent[]>;
+}
+
+/**
+ * Resource for managing webhook subscriptions.
+ * Access via `pulse.webhooks`.
+ *
+ * @example
+ * ```typescript
+ * const pulse = new Pulse('sk_live_...')
+ *
+ * // Create a webhook
+ * const wh = await pulse.webhooks.create({
+ *   url: 'https://example.com/webhook',
+ *   events: ['payment.confirmed'],
+ * })
+ * console.log(wh.secret) // save this!
+ *
+ * // List webhooks
+ * const list = await pulse.webhooks.list()
+ * ```
+ */
+declare class WebhooksResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Create a new webhook subscription.
+     * The response includes a `secret` field (64-char hex) used to verify signatures.
+     * **Store this secret securely** — it is only returned once at creation time.
+     *
+     * @param params - Webhook URL and event types to subscribe to.
+     * @returns The created webhook with its signing secret.
+     * @throws {PulseAuthenticationError} If the API key is invalid.
+     *
+     * @example
+     * ```typescript
+     * const wh = await pulse.webhooks.create({
+     *   url: 'https://example.com/webhook',
+     *   events: ['payment.confirmed'],
+     * })
+     * // Save wh.secret to your environment/secrets manager
+     * console.log('Webhook secret:', wh.secret)
+     * ```
+     */
+    create(params: CreateWebhookParams): Promise<WebhookCreated>;
+    /**
+     * List all webhook subscriptions for the authenticated user.
+     *
+     * @returns Array of webhook objects (without secrets).
+     * @throws {PulseAuthenticationError} If the API key is invalid.
+     *
+     * @example
+     * ```typescript
+     * const webhooks = await pulse.webhooks.list()
+     * for (const wh of webhooks) {
+     *   console.log(wh.url, wh.events, wh.isActive)
+     * }
+     * ```
+     */
+    list(): Promise<Webhook[]>;
+    /**
+     * Delete a webhook subscription.
+     *
+     * @param id - The webhook UUID to delete.
+     * @throws {PulseAuthenticationError} If the API key is invalid.
+     *
+     * @example
+     * ```typescript
+     * await pulse.webhooks.delete('webhook-id')
+     * ```
+     */
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * Resource for usage-based metering and billing.
+ * Access via `pulse.metering`.
+ *
+ * @example
+ * ```typescript
+ * const pulse = new Pulse('sk_live_...')
+ *
+ * // Track a usage event
+ * await pulse.metering.track({
+ *   meterId: 'meter_id',
+ *   customerId: 'user_123',
+ *   value: 1500,
+ * })
+ *
+ * // Query aggregated usage
+ * const usage = await pulse.metering.getUsage({ customerId: 'user_123' })
+ * ```
+ */
+declare class MeteringResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Track a single usage event.
+     *
+     * @param params - Event parameters (meterId, customerId, value).
+     * @returns The created event object.
+     *
+     * @example
+     * ```typescript
+     * await pulse.metering.track({
+     *   meterId: 'tokens',
+     *   customerId: 'user_123',
+     *   value: 1500,
+     *   metadata: { model: 'gpt-4' }
+     * })
+     * ```
+     */
+    track(params: TrackEventParams): Promise<TrackEventResponse>;
+    /**
+     * Track multiple usage events in a single request.
+     *
+     * @param events - Array of event parameters.
+     * @returns Batch result with accepted/failed counts.
+     *
+     * @example
+     * ```typescript
+     * await pulse.metering.trackBatch([
+     *   { meterId: 'tokens', customerId: 'user_1', value: 500 },
+     *   { meterId: 'tokens', customerId: 'user_2', value: 1200 },
+     * ])
+     * ```
+     */
+    trackBatch(events: TrackEventParams[]): Promise<BatchTrackResponse>;
+    /**
+     * Query aggregated usage data.
+     *
+     * @param query - Optional filters (customerId, date range).
+     * @returns Aggregated usage by meter.
+     *
+     * @example
+     * ```typescript
+     * const usage = await pulse.metering.getUsage({ customerId: 'user_123' })
+     * for (const item of usage.data) {
+     *   console.log(item.meterName, item.totalValue, item.totalAmount)
+     * }
+     * ```
+     */
+    getUsage(query?: UsageQuery): Promise<UsageResponse>;
+    /**
+     * List all products.
+     *
+     * @returns Array of product objects with meters.
+     */
+    listProducts(): Promise<MeteringProduct[]>;
+    /**
+     * Create a new product.
+     *
+     * @param data - Product data (name, optional description).
+     * @returns The created product object.
+     *
+     * @example
+     * ```typescript
+     * const product = await pulse.metering.createProduct({
+     *   name: 'AI Agent',
+     *   description: 'Usage-based AI agent billing',
+     * })
+     * ```
+     */
+    createProduct(data: CreateProductParams): Promise<MeteringProduct>;
+    /**
+     * Create a new meter on a product.
+     *
+     * @param productId - The product UUID.
+     * @param data - Meter data (name, displayName, unit, unitPrice).
+     * @returns The created meter object.
+     *
+     * @example
+     * ```typescript
+     * const meter = await pulse.metering.createMeter('product-id', {
+     *   name: 'tokens',
+     *   displayName: 'AI Tokens',
+     *   unit: 'token',
+     *   unitPrice: '0.0001',
+     * })
+     * ```
+     */
+    createMeter(productId: string, data: CreateMeterParams): Promise<Meter>;
+    /**
+     * Create a customer for a product.
+     *
+     * @param productId - The product UUID.
+     * @param data - Customer data (externalId, name, email, metadata).
+     * @returns The created customer object.
+     *
+     * @example
+     * ```typescript
+     * const customer = await pulse.metering.createCustomer('product-id', {
+     *   externalId: 'user_123',
+     *   name: 'John Doe',
+     *   email: 'john@example.com',
+     * })
+     * ```
+     */
+    createCustomer(productId: string, data: CreateCustomerParams): Promise<ProductCustomer>;
+    /**
+     * Get customer usage for a specific product.
+     *
+     * @param productId - The product UUID.
+     * @param customerId - The customer external ID.
+     * @param query - Optional date range filters.
+     * @returns Aggregated usage by meter for the customer.
+     */
+    getCustomerUsage(productId: string, customerId: string, query?: {
+        startDate?: string;
+        endDate?: string;
+    }): Promise<UsageResponse>;
+    /**
+     * Create a session for tracking multiple events for a customer.
+     * Events are accumulated and sent as a batch when `.end()` is called.
+     *
+     * @param customerId - The customer external ID.
+     * @returns A session instance.
+     *
+     * @example
+     * ```typescript
+     * const session = pulse.metering.session('user_123')
+     * session.track('tokens', 500)
+     * session.track('tokens', 300)
+     * session.track('requests', 1)
+     * await session.end() // sends batch: tokens=800, requests=1
+     * ```
+     */
+    session(customerId: string): MeteringSession;
+}
+/**
+ * A session accumulates track calls and sends them as a batch.
+ */
+declare class MeteringSession {
+    private readonly metering;
+    private readonly customerId;
+    private events;
+    constructor(metering: MeteringResource, customerId: string);
+    /**
+     * Queue a tracking event in this session.
+     */
+    track(meterId: string, value: number | string, metadata?: Record<string, unknown>): this;
+    /**
+     * Send all accumulated events as a batch and clear the session.
+     */
+    end(): Promise<BatchTrackResponse>;
+}
+
+/**
+ * Verify the HMAC-SHA256 signature of an incoming webhook request.
+ * Use this to ensure the request came from Pulse and wasn't tampered with.
+ *
+ * The signature is sent in the `X-Pulse-Signature` header as `sha256={hex}`.
+ *
+ * @param rawBody - The raw request body as a string (not parsed JSON).
+ * @param signatureHeader - The `X-Pulse-Signature` header value (e.g. `"sha256=abc123..."`).
+ * @param secret - Your webhook signing secret (64-char hex, from webhook creation).
+ * @returns `true` if the signature is valid, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * import { Pulse } from '@beinfi/pulse-sdk'
+ *
+ * // Express/Node.js example
+ * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const isValid = Pulse.webhooks.verifySignature(
+ *     req.body.toString(),
+ *     req.headers['x-pulse-signature'] as string,
+ *     process.env.PULSE_WEBHOOK_SECRET!
+ *   )
+ *
+ *   if (!isValid) {
+ *     return res.status(401).send('Invalid signature')
+ *   }
+ *
+ *   const event = JSON.parse(req.body.toString())
+ *   console.log('Payment confirmed:', event.paymentIntentId)
+ *   res.sendStatus(200)
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Standalone import
+ * import { verifyWebhookSignature } from '@beinfi/pulse-sdk'
+ *
+ * const valid = verifyWebhookSignature(rawBody, signatureHeader, secret)
+ * ```
+ */
+declare function verifyWebhookSignature(rawBody: string, signatureHeader: string, secret: string): boolean;
+
+/**
+ * Successful payment data returned by the checkout widget.
+ */
+interface CheckoutPayment {
+    /** ID of the completed payment intent. */
+    paymentIntentId: string;
+    /** Payment amount as a decimal string. */
+    amount: string;
+    /** Currency code (e.g. `"USD"`). */
+    currency: string;
+    /** Payment method used (e.g. `"crypto"`, `"pix"`). */
+    method: string;
+    /** Blockchain transaction hash (present for crypto payments). */
+    txHash?: string;
+}
+/**
+ * Error object emitted by the checkout widget.
+ */
+interface CheckoutError {
+    /** Human-readable error message. */
+    message: string;
+    /** Machine-readable error code. */
+    code?: string;
+}
+/**
+ * Theme customization for the checkout widget.
+ * All values are CSS color strings (hex, rgb, hsl, etc.).
+ *
+ * @example
+ * ```typescript
+ * const instance = Pulse.checkout.mount('#checkout', {
+ *   linkId: 'link-id',
+ *   theme: {
+ *     background: '#1a1a2e',
+ *     foreground: '#ffffff',
+ *     accent: '#e94560',
+ *   }
+ * })
+ * ```
+ */
+interface CheckoutTheme {
+    /** Background color of the checkout widget. */
+    background?: string;
+    /** Primary text color. */
+    foreground?: string;
+    /** Card/surface background color. */
+    card?: string;
+    /** Accent color for buttons and interactive elements. */
+    accent?: string;
+    /** Text color on accent-colored elements. */
+    accentForeground?: string;
+}
+/**
+ * Options for mounting the Pulse checkout widget.
+ *
+ * @example
+ * ```typescript
+ * const instance = Pulse.checkout.mount('#checkout', {
+ *   linkId: 'abc-123',
+ *   onSuccess: (payment) => console.log('Paid!', payment),
+ *   onError: (err) => console.error('Failed:', err.message),
+ * })
+ * ```
+ */
+interface CheckoutMountOptions {
+    /** The payment link ID to load in the checkout widget. */
+    linkId: string;
+    /** Override the checkout base URL. Defaults to `https://pulse.beinfi.com`. */
+    baseUrl?: string;
+    /** Custom theme colors for the checkout widget. */
+    theme?: CheckoutTheme;
+    /** Called when the checkout iframe is ready and rendered. */
+    onReady?: () => void;
+    /** Called when the payment is successfully confirmed. */
+    onSuccess?: (payment: CheckoutPayment) => void;
+    /** Called when a payment error occurs. */
+    onError?: (error: CheckoutError) => void;
+    /** Called when the checkout widget is unmounted/closed. */
+    onClose?: () => void;
+}
+/**
+ * Handle returned by {@link mountCheckout}. Use it to control the checkout widget lifecycle.
+ *
+ * @example
+ * ```typescript
+ * const instance = Pulse.checkout.mount('#checkout', { linkId: 'abc-123' })
+ *
+ * // Listen for events
+ * instance.on('success', (payment) => console.log('Paid!', payment))
+ *
+ * // Clean up when done
+ * instance.unmount()
+ * ```
+ */
+interface CheckoutInstance {
+    /** Remove the checkout iframe and clean up event listeners. */
+    unmount: () => void;
+    /** Subscribe to checkout events: `"ready"`, `"success"`, `"error"`, `"close"`. */
+    on: (event: 'ready' | 'success' | 'error' | 'close', handler: (...args: any[]) => void) => void;
+}
+
+/**
+ * Mount the Pulse checkout widget into a DOM element.
+ * Embeds an iframe-based checkout that handles payment flow (crypto, PIX)
+ * and communicates back via postMessage events.
+ *
+ * @param selector - A CSS selector string or an HTMLElement to mount the checkout into.
+ * @param options - Checkout configuration including the payment link ID and event callbacks.
+ * @returns A {@link CheckoutInstance} with `unmount()` and `on()` methods.
+ * @throws {Error} If the container element is not found.
+ *
+ * @example
+ * ```typescript
+ * import { Pulse } from '@beinfi/pulse-sdk'
+ *
+ * // Mount into a div
+ * const checkout = Pulse.checkout.mount('#checkout-container', {
+ *   linkId: 'abc-123',
+ *   theme: {
+ *     background: '#0f0f23',
+ *     accent: '#6366f1',
+ *   },
+ *   onReady: () => console.log('Checkout loaded'),
+ *   onSuccess: (payment) => {
+ *     console.log('Payment confirmed!', payment.paymentIntentId)
+ *     checkout.unmount()
+ *   },
+ *   onError: (err) => console.error('Payment failed:', err.message),
+ * })
+ *
+ * // Alternative: use .on() event listeners
+ * checkout.on('success', (payment) => {
+ *   window.location.href = '/thank-you'
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Standalone import
+ * import { mountCheckout } from '@beinfi/pulse-sdk'
+ *
+ * const instance = mountCheckout('#checkout', { linkId: 'abc-123' })
+ * ```
+ */
+declare function mountCheckout(selector: string | HTMLElement, options: CheckoutMountOptions): CheckoutInstance;
+
+/**
+ * Base error class for all Pulse SDK errors.
+ * All errors thrown by the SDK extend this class.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await pulse.paymentLinks.create({ title: 'Test', amount: '10.00' })
+ * } catch (err) {
+ *   if (err instanceof PulseError) {
+ *     console.error('Pulse SDK error:', err.message)
+ *   }
+ * }
+ * ```
+ */
+declare class PulseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when the Pulse API returns a non-2xx response.
+ * Contains the HTTP status code, machine-readable error code, and optional rate limit info.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await pulse.paymentLinks.create({ title: 'Test', amount: '10.00' })
+ * } catch (err) {
+ *   if (err instanceof PulseApiError) {
+ *     console.error(`API error ${err.status}: [${err.errorCode}] ${err.message}`)
+ *   }
+ * }
+ * ```
+ */
+declare class PulseApiError extends PulseError {
+    /** HTTP status code (e.g. 400, 404, 500). */
+    readonly status: number;
+    /** Machine-readable error code (e.g. `"unauthorized"`, `"not_found"`). */
+    readonly errorCode: string;
+    /** Rate limit info from response headers, if available. */
+    readonly rateLimit?: RateLimitInfo;
+    constructor(status: number, errorCode: string, message: string, rateLimit?: RateLimitInfo);
+}
+/**
+ * Error thrown when the API key is invalid, expired, or revoked (HTTP 401).
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await pulse.paymentLinks.list()
+ * } catch (err) {
+ *   if (err instanceof PulseAuthenticationError) {
+ *     console.error('Bad API key — check your sk_live_ key')
+ *   }
+ * }
+ * ```
+ */
+declare class PulseAuthenticationError extends PulseApiError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when the rate limit is exceeded (HTTP 429).
+ * Check `retryAfter` for the number of seconds to wait before retrying.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await pulse.paymentLinks.list()
+ * } catch (err) {
+ *   if (err instanceof PulseRateLimitError) {
+ *     console.log(`Rate limited. Retry in ${err.retryAfter}s`)
+ *     await new Promise(r => setTimeout(r, err.retryAfter * 1000))
+ *   }
+ * }
+ * ```
+ */
+declare class PulseRateLimitError extends PulseApiError {
+    /** Number of seconds to wait before retrying. */
+    readonly retryAfter: number;
+    constructor(retryAfter: number, rateLimit?: RateLimitInfo);
+}
+
+/**
+ * Main entry point for the Pulse SDK.
+ * Create an instance with your API key to access payment links and webhooks.
+ *
+ * @example
+ * ```typescript
+ * import { Pulse } from '@beinfi/pulse-sdk'
+ *
+ * // Quick setup with just an API key
+ * const pulse = new Pulse('sk_live_...')
+ *
+ * // Or with full config
+ * const pulse = new Pulse({
+ *   apiKey: 'sk_live_...',
+ *   baseUrl: 'https://api.beinfi.com',
+ * })
+ *
+ * // Create a payment link
+ * const link = await pulse.paymentLinks.create({
+ *   title: 'Order #42',
+ *   amount: '100.00',
+ * })
+ *
+ * // Verify webhook signatures (static method, no instance needed)
+ * const isValid = Pulse.webhooks.verifySignature(rawBody, signature, secret)
+ *
+ * // Mount checkout widget (static method, browser only)
+ * const checkout = Pulse.checkout.mount('#container', { linkId: link.id })
+ * ```
+ */
+declare class Pulse {
+    /** Resource for creating, listing, and fetching payment links. */
+    readonly paymentLinks: PaymentLinksResource;
+    /** Resource for creating, listing, and deleting webhook subscriptions. */
+    readonly webhooks: WebhooksResource;
+    /** Resource for usage-based metering, tracking events, and querying usage. */
+    readonly metering: MeteringResource;
+    private readonly client;
+    /**
+     * Static utilities for verifying webhook signatures.
+     * Does not require a Pulse instance — useful in webhook handler endpoints.
+     *
+     * @example
+     * ```typescript
+     * const isValid = Pulse.webhooks.verifySignature(
+     *   rawBody,
+     *   req.headers['x-pulse-signature'],
+     *   process.env.PULSE_WEBHOOK_SECRET
+     * )
+     * ```
+     */
+    static webhooks: {
+        verifySignature: typeof verifyWebhookSignature;
+    };
+    /**
+     * Static utilities for mounting the checkout widget.
+     * Browser-only — embeds an iframe-based checkout for a payment link.
+     *
+     * @example
+     * ```typescript
+     * const instance = Pulse.checkout.mount('#checkout', {
+     *   linkId: 'abc-123',
+     *   onSuccess: (payment) => console.log('Paid!', payment),
+     * })
+     * ```
+     */
+    static checkout: {
+        mount: typeof mountCheckout;
+    };
+    /**
+     * Create a new Pulse SDK client.
+     *
+     * @param config - Either an API key string (`"sk_live_..."`) or a {@link PulseConfig} object.
+     * @throws {PulseError} If the API key doesn't start with `"sk_live_"`.
+     *
+     * @example
+     * ```typescript
+     * // String shorthand
+     * const pulse = new Pulse('sk_live_...')
+     *
+     * // Config object
+     * const pulse = new Pulse({ apiKey: 'sk_live_...', baseUrl: 'https://api.beinfi.com' })
+     * ```
+     */
+    constructor(config: string | PulseConfig);
+}
+
+export { type ApiErrorResponse, type BatchTrackResponse, type CheckoutError, type CheckoutInstance, type CheckoutMountOptions, type CheckoutPayment, type CheckoutTheme, type CreateCustomerParams, type CreateMeterParams, type CreatePaymentLinkParams, type CreateProductParams, type CreateWebhookParams, type ListPaymentLinksParams, type ListReceivedPaymentsParams, type Meter, type MeteringProduct, type PaymentIntent, type PaymentLink, type ProductCustomer, Pulse, PulseApiError, PulseAuthenticationError, type PulseConfig, PulseError, PulseRateLimitError, type RateLimitInfo, type ReceivedPayment, type TrackEventParams, type TrackEventResponse, type UsageItem, type UsageQuery, type UsageResponse, type Webhook, type WebhookCreated, type WebhookPayload, mountCheckout, verifyWebhookSignature };