@beinfi/pulse-sdk 0.1.0

package/dist/index.mjs

@@ -0,0 +1,679 @@
+// src/errors.ts
+var PulseError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PulseError";
+  }
+};
+var PulseApiError = class extends PulseError {
+  /** HTTP status code (e.g. 400, 404, 500). */
+  status;
+  /** Machine-readable error code (e.g. `"unauthorized"`, `"not_found"`). */
+  errorCode;
+  /** Rate limit info from response headers, if available. */
+  rateLimit;
+  constructor(status, errorCode, message, rateLimit) {
+    super(message);
+    this.name = "PulseApiError";
+    this.status = status;
+    this.errorCode = errorCode;
+    this.rateLimit = rateLimit;
+  }
+};
+var PulseAuthenticationError = class extends PulseApiError {
+  constructor(message = "Invalid API key") {
+    super(401, "unauthorized", message);
+    this.name = "PulseAuthenticationError";
+  }
+};
+var PulseRateLimitError = class extends PulseApiError {
+  /** Number of seconds to wait before retrying. */
+  retryAfter;
+  constructor(retryAfter, rateLimit) {
+    super(429, "rate_limit_exceeded", "Rate limit exceeded", rateLimit);
+    this.name = "PulseRateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.beinfi.com";
+var HttpClient = class {
+  apiKey;
+  baseUrl;
+  constructor(apiKey, baseUrl) {
+    if (!apiKey.startsWith("sk_live_")) {
+      throw new PulseError(
+        'Invalid API key format. Keys must start with "sk_live_"'
+      );
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = (baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  }
+  async request(method, path, options) {
+    let url = `${this.baseUrl}/api/v1${path}`;
+    if (options?.query) {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(options.query)) {
+        if (value !== void 0) {
+          params.set(key, String(value));
+        }
+      }
+      const qs = params.toString();
+      if (qs) url += `?${qs}`;
+    }
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json"
+    };
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: options?.body ? JSON.stringify(options.body) : void 0
+    });
+    const rateLimit = this.parseRateLimit(response.headers);
+    if (!response.ok) {
+      this.handleError(response.status, await this.safeJson(response), rateLimit);
+    }
+    if (response.status === 204) {
+      return void 0;
+    }
+    const json = await response.json();
+    if (json && typeof json === "object" && "data" in json) {
+      return json.data;
+    }
+    return json;
+  }
+  parseRateLimit(headers) {
+    const limit = headers.get("X-RateLimit-Limit");
+    const remaining = headers.get("X-RateLimit-Remaining");
+    const reset = headers.get("X-RateLimit-Reset");
+    if (limit && remaining && reset) {
+      return {
+        limit: Number(limit),
+        remaining: Number(remaining),
+        reset: Number(reset)
+      };
+    }
+    return void 0;
+  }
+  async safeJson(response) {
+    try {
+      return await response.json();
+    } catch {
+      return null;
+    }
+  }
+  handleError(status, body, rateLimit) {
+    const errorCode = body?.error ?? "unknown_error";
+    const message = body?.message ?? `Request failed with status ${status}`;
+    if (status === 401) {
+      throw new PulseAuthenticationError(message);
+    }
+    if (status === 429) {
+      const retryAfter = rateLimit?.reset ? Math.max(0, rateLimit.reset - Math.floor(Date.now() / 1e3)) : 60;
+      throw new PulseRateLimitError(retryAfter, rateLimit);
+    }
+    throw new PulseApiError(status, errorCode, message, rateLimit);
+  }
+};
+
+// src/resources/payment-links.ts
+var PaymentLinksResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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)
+   * ```
+   */
+  async create(params) {
+    return this.client.request("POST", "/payment-links", {
+      body: params
+    });
+  }
+  /**
+   * 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)
+   * }
+   * ```
+   */
+  async list(params) {
+    return this.client.request("GET", "/payment-links", {
+      query: {
+        limit: params?.limit,
+        offset: params?.offset
+      }
+    });
+  }
+  /**
+   * 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)
+   * ```
+   */
+  async get(linkId) {
+    return this.client.request("GET", `/payment-links/${linkId}`);
+  }
+  /**
+   * 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`)
+   * ```
+   */
+  async listIntents(linkId) {
+    return this.client.request(
+      "GET",
+      `/payment-links/${linkId}/intents`
+    );
+  }
+};
+
+// src/resources/webhooks.ts
+var WebhooksResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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)
+   * ```
+   */
+  async create(params) {
+    return this.client.request("POST", "/webhooks", {
+      body: params
+    });
+  }
+  /**
+   * 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)
+   * }
+   * ```
+   */
+  async list() {
+    return this.client.request("GET", "/webhooks");
+  }
+  /**
+   * 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')
+   * ```
+   */
+  async delete(id) {
+    return this.client.request("DELETE", `/webhooks/${id}`);
+  }
+};
+
+// src/resources/metering.ts
+function generateId() {
+  const hex = "0123456789abcdef";
+  let id = "";
+  for (let i = 0; i < 32; i++) {
+    id += hex[Math.floor(Math.random() * 16)];
+    if (i === 7 || i === 11 || i === 15 || i === 19) id += "-";
+  }
+  return id;
+}
+var MeteringResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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' }
+   * })
+   * ```
+   */
+  async track(params) {
+    return this.client.request(
+      "POST",
+      "/metering/events",
+      {
+        body: {
+          eventId: params.eventId || generateId(),
+          meterId: params.meterId,
+          customerId: params.customerId,
+          value: typeof params.value === "number" ? String(params.value) : params.value,
+          timestamp: params.timestamp?.toISOString(),
+          metadata: params.metadata
+        }
+      }
+    );
+  }
+  /**
+   * 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 },
+   * ])
+   * ```
+   */
+  async trackBatch(events) {
+    return this.client.request(
+      "POST",
+      "/metering/events/batch",
+      {
+        body: {
+          events: events.map((e) => ({
+            eventId: e.eventId || generateId(),
+            meterId: e.meterId,
+            customerId: e.customerId,
+            value: typeof e.value === "number" ? String(e.value) : e.value,
+            timestamp: e.timestamp?.toISOString(),
+            metadata: e.metadata
+          }))
+        }
+      }
+    );
+  }
+  /**
+   * 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)
+   * }
+   * ```
+   */
+  async getUsage(query) {
+    return this.client.request("GET", "/metering/usage", {
+      query: {
+        customerId: query?.customerId,
+        startDate: query?.startDate,
+        endDate: query?.endDate
+      }
+    });
+  }
+  /**
+   * List all products.
+   *
+   * @returns Array of product objects with meters.
+   */
+  async listProducts() {
+    return this.client.request("GET", "/metering/products");
+  }
+  /**
+   * 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',
+   * })
+   * ```
+   */
+  async createProduct(data) {
+    return this.client.request(
+      "POST",
+      "/metering/products",
+      { body: data }
+    );
+  }
+  /**
+   * 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',
+   * })
+   * ```
+   */
+  async createMeter(productId, data) {
+    return this.client.request(
+      "POST",
+      `/metering/products/${productId}/meters`,
+      { body: data }
+    );
+  }
+  /**
+   * 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',
+   * })
+   * ```
+   */
+  async createCustomer(productId, data) {
+    return this.client.request(
+      "POST",
+      `/metering/products/${productId}/customers`,
+      { body: data }
+    );
+  }
+  /**
+   * 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.
+   */
+  async getCustomerUsage(productId, customerId, query) {
+    return this.client.request(
+      "GET",
+      `/metering/products/${productId}/customers/${customerId}/usage`,
+      {
+        query: {
+          startDate: query?.startDate,
+          endDate: query?.endDate
+        }
+      }
+    );
+  }
+  /**
+   * 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) {
+    return new MeteringSession(this, customerId);
+  }
+};
+var MeteringSession = class {
+  constructor(metering, customerId) {
+    this.metering = metering;
+    this.customerId = customerId;
+  }
+  events = [];
+  /**
+   * Queue a tracking event in this session.
+   */
+  track(meterId, value, metadata) {
+    this.events.push({
+      meterId,
+      customerId: this.customerId,
+      value,
+      metadata
+    });
+    return this;
+  }
+  /**
+   * Send all accumulated events as a batch and clear the session.
+   */
+  async end() {
+    if (this.events.length === 0) {
+      return { accepted: 0, failed: 0, results: [] };
+    }
+    const result = await this.metering.trackBatch(this.events);
+    this.events = [];
+    return result;
+  }
+};
+
+// src/webhooks/verify.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function verifyWebhookSignature(rawBody, signatureHeader, secret) {
+  const expectedSig = createHmac("sha256", secret).update(rawBody).digest("hex");
+  const receivedSig = signatureHeader.startsWith("sha256=") ? signatureHeader.slice(7) : signatureHeader;
+  if (expectedSig.length !== receivedSig.length) {
+    return false;
+  }
+  return timingSafeEqual(
+    Buffer.from(expectedSig, "hex"),
+    Buffer.from(receivedSig, "hex")
+  );
+}
+
+// src/checkout/checkout.ts
+var DEFAULT_BASE_URL2 = "https://pulse.beinfi.com";
+function mountCheckout(selector, options) {
+  const container = typeof selector === "string" ? document.querySelector(selector) : selector;
+  if (!container) {
+    throw new Error(`[Pulse Checkout] Container not found: ${selector}`);
+  }
+  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL2).replace(/\/$/, "");
+  const allowedOrigin = new URL(baseUrl).origin;
+  const handlers = {};
+  function emit(event, ...args) {
+    for (const handler of handlers[event] ?? []) {
+      handler(...args);
+    }
+  }
+  const iframe = document.createElement("iframe");
+  iframe.src = `${baseUrl}/embed/pay/${options.linkId}`;
+  iframe.style.width = "100%";
+  iframe.style.border = "none";
+  iframe.style.colorScheme = "normal";
+  iframe.setAttribute("allowtransparency", "true");
+  iframe.allow = "clipboard-write";
+  function handleMessage(event) {
+    if (event.origin !== allowedOrigin) return;
+    const { type, ...data } = event.data ?? {};
+    switch (type) {
+      case "pulse:ready":
+        if (options.theme) {
+          iframe.contentWindow?.postMessage(
+            { type: "pulse:config", theme: options.theme },
+            allowedOrigin
+          );
+        }
+        options.onReady?.();
+        emit("ready");
+        break;
+      case "pulse:resize":
+        if (typeof data.height === "number") {
+          iframe.style.height = `${data.height}px`;
+        }
+        break;
+      case "pulse:success": {
+        const payment = data.payment;
+        options.onSuccess?.(payment);
+        emit("success", payment);
+        break;
+      }
+      case "pulse:error": {
+        const error = data.error;
+        options.onError?.(error);
+        emit("error", error);
+        break;
+      }
+    }
+  }
+  window.addEventListener("message", handleMessage);
+  container.appendChild(iframe);
+  return {
+    unmount() {
+      window.removeEventListener("message", handleMessage);
+      iframe.remove();
+      options.onClose?.();
+      emit("close");
+    },
+    on(event, handler) {
+      if (!handlers[event]) handlers[event] = [];
+      handlers[event].push(handler);
+    }
+  };
+}
+
+// src/index.ts
+var Pulse = class {
+  /** Resource for creating, listing, and fetching payment links. */
+  paymentLinks;
+  /** Resource for creating, listing, and deleting webhook subscriptions. */
+  webhooks;
+  /** Resource for usage-based metering, tracking events, and querying usage. */
+  metering;
+  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: 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: 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) {
+    const apiKey = typeof config === "string" ? config : config.apiKey;
+    const baseUrl = typeof config === "string" ? void 0 : config.baseUrl;
+    this.client = new HttpClient(apiKey, baseUrl);
+    this.paymentLinks = new PaymentLinksResource(this.client);
+    this.webhooks = new WebhooksResource(this.client);
+    this.metering = new MeteringResource(this.client);
+  }
+};
+export {
+  Pulse,
+  PulseApiError,
+  PulseAuthenticationError,
+  PulseError,
+  PulseRateLimitError,
+  mountCheckout,
+  verifyWebhookSignature
+};