@beinfi/pulse-sdk 0.1.0

package/dist/ai.d.mts

@@ -0,0 +1,934 @@
+import { LanguageModelV3Middleware } from '@ai-sdk/provider';
+
+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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+
+/**
+ * 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;
+
+/**
+ * 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);
+}
+
+interface PulseMiddlewareConfig {
+    /** Pulse SDK instance (already configured with API key) */
+    pulse: Pulse;
+    /** Customer ID — string or function that resolves at call time */
+    customerId: string | (() => string | Promise<string>);
+    /** Meter IDs for input and output tokens */
+    meters: {
+        input: string;
+        output: string;
+    };
+    /** Optional metadata to attach to every event */
+    metadata?: Record<string, unknown>;
+}
+declare function pulseMiddleware(config: PulseMiddlewareConfig): LanguageModelV3Middleware;
+
+export { type PulseMiddlewareConfig, pulseMiddleware };