@imerchantsolutions/sdk 1.0.0

package/dist/index.mjs

@@ -0,0 +1,706 @@
+// src/errors.ts
+var iMerchantError = class _iMerchantError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "iMerchantError";
+    Object.setPrototypeOf(this, _iMerchantError.prototype);
+  }
+};
+var APIError = class _APIError extends iMerchantError {
+  constructor(message, statusCode, code, details) {
+    super(message);
+    this.name = "APIError";
+    this.statusCode = statusCode;
+    this.code = code;
+    this.details = details;
+    Object.setPrototypeOf(this, _APIError.prototype);
+  }
+};
+var AuthenticationError = class _AuthenticationError extends iMerchantError {
+  constructor(message = "Invalid API key provided") {
+    super(message);
+    this.name = "AuthenticationError";
+    Object.setPrototypeOf(this, _AuthenticationError.prototype);
+  }
+};
+var NotFoundError = class _NotFoundError extends APIError {
+  constructor(resource, id) {
+    super(`${resource} with ID '${id}' not found`, 404, "not_found");
+    this.name = "NotFoundError";
+    Object.setPrototypeOf(this, _NotFoundError.prototype);
+  }
+};
+var ValidationError = class _ValidationError extends APIError {
+  constructor(message, errors) {
+    super(message, 400, "validation_error", { errors });
+    this.name = "ValidationError";
+    this.errors = errors;
+    Object.setPrototypeOf(this, _ValidationError.prototype);
+  }
+};
+var RateLimitError = class _RateLimitError extends APIError {
+  constructor(retryAfter) {
+    super(
+      "Rate limit exceeded. Please slow down your requests.",
+      429,
+      "rate_limit_exceeded",
+      { retryAfter }
+    );
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+    Object.setPrototypeOf(this, _RateLimitError.prototype);
+  }
+};
+var WebhookSignatureError = class _WebhookSignatureError extends iMerchantError {
+  constructor(message = "Invalid webhook signature") {
+    super(message);
+    this.name = "WebhookSignatureError";
+    Object.setPrototypeOf(this, _WebhookSignatureError.prototype);
+  }
+};
+
+// src/http.ts
+var DEFAULT_BASE_URL = "https://api.imerchant.com";
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_API_VERSION = "v1";
+var HttpClient = class {
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new AuthenticationError("API key is required");
+    }
+    this.config = {
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl || DEFAULT_BASE_URL,
+      timeout: config.timeout || DEFAULT_TIMEOUT,
+      apiVersion: config.apiVersion || DEFAULT_API_VERSION
+    };
+  }
+  getUrl(path) {
+    const baseUrl = this.config.baseUrl.replace(/\/$/, "");
+    const cleanPath = path.startsWith("/") ? path : `/${path}`;
+    return `${baseUrl}/${this.config.apiVersion}${cleanPath}`;
+  }
+  async handleResponse(response) {
+    const contentType = response.headers.get("content-type");
+    const isJson = contentType?.includes("application/json");
+    if (!response.ok) {
+      let errorData = {};
+      if (isJson) {
+        try {
+          const jsonData = await response.json();
+          errorData = jsonData;
+        } catch {
+        }
+      }
+      const message = errorData.message || `Request failed with status ${response.status}`;
+      const code = errorData.code || "unknown_error";
+      switch (response.status) {
+        case 401:
+          throw new AuthenticationError(message);
+        case 400:
+          if (errorData.errors) {
+            throw new ValidationError(message, errorData.errors);
+          }
+          throw new APIError(message, response.status, code);
+        case 429:
+          const retryAfter = response.headers.get("retry-after");
+          throw new RateLimitError(retryAfter ? parseInt(retryAfter, 10) : void 0);
+        default:
+          throw new APIError(message, response.status, code);
+      }
+    }
+    if (!isJson) {
+      return {};
+    }
+    return response.json();
+  }
+  async request(method, path, data, options) {
+    const url = this.getUrl(path);
+    const timeout = options?.timeout || this.config.timeout;
+    const headers = {
+      "Authorization": `Bearer ${this.config.apiKey}`,
+      "Content-Type": "application/json",
+      "X-SDK-Version": "1.0.0"
+    };
+    if (options?.idempotencyKey) {
+      headers["Idempotency-Key"] = options.idempotencyKey;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: data ? JSON.stringify(data) : void 0,
+        signal: controller.signal
+      });
+      return this.handleResponse(response);
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new APIError("Request timed out", 408, "timeout");
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  get(path, options) {
+    return this.request("GET", path, void 0, options);
+  }
+  post(path, data, options) {
+    return this.request("POST", path, data, options);
+  }
+  put(path, data, options) {
+    return this.request("PUT", path, data, options);
+  }
+  patch(path, data, options) {
+    return this.request("PATCH", path, data, options);
+  }
+  delete(path, options) {
+    return this.request("DELETE", path, void 0, options);
+  }
+};
+
+// src/resources/payments.ts
+var Payments = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Create a new payment
+   *
+   * @example
+   * ```typescript
+   * const payment = await client.payments.create({
+   *   amount: 1000, // $10.00 in cents
+   *   currency: 'usd',
+   *   reference: 'order_123',
+   *   description: 'Test payment',
+   * });
+   * ```
+   */
+  async create(params, options) {
+    return this.http.post("/payments", params, options);
+  }
+  /**
+   * Retrieve a payment by ID
+   *
+   * @example
+   * ```typescript
+   * const payment = await client.payments.retrieve('pay_abc123');
+   * console.log(payment.status);
+   * ```
+   */
+  async retrieve(id, options) {
+    return this.http.get(`/payments/${id}`, options);
+  }
+  /**
+   * List all payments with optional filters
+   *
+   * @example
+   * ```typescript
+   * const { data, hasMore } = await client.payments.list({
+   *   status: 'captured',
+   *   limit: 10,
+   * });
+   * ```
+   */
+  async list(params, options) {
+    const searchParams = new URLSearchParams();
+    if (params?.limit) searchParams.set("limit", params.limit.toString());
+    if (params?.cursor) searchParams.set("cursor", params.cursor);
+    if (params?.status) searchParams.set("status", params.status);
+    if (params?.customerId) searchParams.set("customerId", params.customerId);
+    if (params?.createdAfter) searchParams.set("createdAfter", params.createdAfter);
+    if (params?.createdBefore) searchParams.set("createdBefore", params.createdBefore);
+    const query = searchParams.toString();
+    const path = query ? `/payments?${query}` : "/payments";
+    return this.http.get(path, options);
+  }
+  /**
+   * Capture an authorized payment
+   *
+   * @example
+   * ```typescript
+   * // Capture full amount
+   * const payment = await client.payments.capture('pay_abc123');
+   *
+   * // Capture partial amount
+   * const payment = await client.payments.capture('pay_abc123', { amount: 500 });
+   * ```
+   */
+  async capture(id, params, options) {
+    return this.http.post(`/payments/${id}/capture`, params || {}, options);
+  }
+  /**
+   * Cancel an authorized payment
+   *
+   * @example
+   * ```typescript
+   * const payment = await client.payments.cancel('pay_abc123');
+   * ```
+   */
+  async cancel(id, options) {
+    return this.http.post(`/payments/${id}/cancel`, {}, options);
+  }
+};
+
+// src/resources/refunds.ts
+var Refunds = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Create a refund for a payment
+   *
+   * @example
+   * ```typescript
+   * // Full refund
+   * const refund = await client.refunds.create({
+   *   paymentId: 'pay_abc123',
+   *   reason: 'Customer request',
+   * });
+   *
+   * // Partial refund
+   * const refund = await client.refunds.create({
+   *   paymentId: 'pay_abc123',
+   *   amount: 500, // $5.00 in cents
+   *   reason: 'Partial return',
+   * });
+   * ```
+   */
+  async create(params, options) {
+    return this.http.post("/refunds", params, options);
+  }
+  /**
+   * Retrieve a refund by ID
+   *
+   * @example
+   * ```typescript
+   * const refund = await client.refunds.retrieve('ref_abc123');
+   * console.log(refund.status);
+   * ```
+   */
+  async retrieve(id, options) {
+    return this.http.get(`/refunds/${id}`, options);
+  }
+  /**
+   * List all refunds with optional filters
+   *
+   * @example
+   * ```typescript
+   * // List all refunds for a payment
+   * const { data } = await client.refunds.list({
+   *   paymentId: 'pay_abc123',
+   * });
+   *
+   * // List refunds by status
+   * const { data } = await client.refunds.list({
+   *   status: 'completed',
+   *   limit: 20,
+   * });
+   * ```
+   */
+  async list(params, options) {
+    const searchParams = new URLSearchParams();
+    if (params?.limit) searchParams.set("limit", params.limit.toString());
+    if (params?.cursor) searchParams.set("cursor", params.cursor);
+    if (params?.paymentId) searchParams.set("paymentId", params.paymentId);
+    if (params?.status) searchParams.set("status", params.status);
+    const query = searchParams.toString();
+    const path = query ? `/refunds?${query}` : "/refunds";
+    return this.http.get(path, options);
+  }
+};
+
+// src/resources/customers.ts
+var Customers = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Create a new customer
+   *
+   * @example
+   * ```typescript
+   * const customer = await client.customers.create({
+   *   email: 'john@example.com',
+   *   firstName: 'John',
+   *   lastName: 'Doe',
+   *   metadata: { userId: '12345' },
+   * });
+   * ```
+   */
+  async create(params, options) {
+    return this.http.post("/customers", params, options);
+  }
+  /**
+   * Retrieve a customer by ID
+   *
+   * @example
+   * ```typescript
+   * const customer = await client.customers.retrieve('cus_abc123');
+   * console.log(customer.email);
+   * ```
+   */
+  async retrieve(id, options) {
+    return this.http.get(`/customers/${id}`, options);
+  }
+  /**
+   * Update a customer
+   *
+   * @example
+   * ```typescript
+   * const customer = await client.customers.update('cus_abc123', {
+   *   firstName: 'Jane',
+   *   phone: '+1234567890',
+   * });
+   * ```
+   */
+  async update(id, params, options) {
+    return this.http.patch(`/customers/${id}`, params, options);
+  }
+  /**
+   * Delete a customer
+   *
+   * @example
+   * ```typescript
+   * await client.customers.delete('cus_abc123');
+   * ```
+   */
+  async delete(id, options) {
+    await this.http.delete(`/customers/${id}`, options);
+  }
+  /**
+   * List all customers with optional filters
+   *
+   * @example
+   * ```typescript
+   * const { data, hasMore } = await client.customers.list({
+   *   limit: 20,
+   * });
+   *
+   * // Search by email
+   * const { data } = await client.customers.list({
+   *   email: 'john@example.com',
+   * });
+   * ```
+   */
+  async list(params, options) {
+    const searchParams = new URLSearchParams();
+    if (params?.limit) searchParams.set("limit", params.limit.toString());
+    if (params?.cursor) searchParams.set("cursor", params.cursor);
+    if (params?.email) searchParams.set("email", params.email);
+    if (params?.createdAfter) searchParams.set("createdAfter", params.createdAfter);
+    if (params?.createdBefore) searchParams.set("createdBefore", params.createdBefore);
+    const query = searchParams.toString();
+    const path = query ? `/customers?${query}` : "/customers";
+    return this.http.get(path, options);
+  }
+};
+
+// src/resources/subscriptions.ts
+var Subscriptions = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Create a new subscription
+   *
+   * @example
+   * ```typescript
+   * const subscription = await client.subscriptions.create({
+   *   customerId: 'cus_abc123',
+   *   amount: 2999, // $29.99 in cents
+   *   currency: 'usd',
+   *   interval: 'month',
+   * });
+   * ```
+   */
+  async create(params, options) {
+    return this.http.post("/subscriptions", params, options);
+  }
+  /**
+   * Retrieve a subscription by ID
+   *
+   * @example
+   * ```typescript
+   * const subscription = await client.subscriptions.retrieve('sub_abc123');
+   * console.log(subscription.status);
+   * ```
+   */
+  async retrieve(id, options) {
+    return this.http.get(`/subscriptions/${id}`, options);
+  }
+  /**
+   * Cancel a subscription
+   *
+   * @example
+   * ```typescript
+   * // Cancel immediately
+   * const subscription = await client.subscriptions.cancel('sub_abc123');
+   *
+   * // Cancel at end of billing period
+   * const subscription = await client.subscriptions.cancel('sub_abc123', {
+   *   atPeriodEnd: true,
+   * });
+   * ```
+   */
+  async cancel(id, params, options) {
+    return this.http.post(
+      `/subscriptions/${id}/cancel`,
+      params || {},
+      options
+    );
+  }
+  /**
+   * Pause a subscription
+   *
+   * @example
+   * ```typescript
+   * const subscription = await client.subscriptions.pause('sub_abc123');
+   * ```
+   */
+  async pause(id, options) {
+    return this.http.post(`/subscriptions/${id}/pause`, {}, options);
+  }
+  /**
+   * Resume a paused subscription
+   *
+   * @example
+   * ```typescript
+   * const subscription = await client.subscriptions.resume('sub_abc123');
+   * ```
+   */
+  async resume(id, options) {
+    return this.http.post(`/subscriptions/${id}/resume`, {}, options);
+  }
+  /**
+   * List all subscriptions with optional filters
+   *
+   * @example
+   * ```typescript
+   * // List all active subscriptions
+   * const { data } = await client.subscriptions.list({
+   *   status: 'active',
+   * });
+   *
+   * // List subscriptions for a customer
+   * const { data } = await client.subscriptions.list({
+   *   customerId: 'cus_abc123',
+   * });
+   * ```
+   */
+  async list(params, options) {
+    const searchParams = new URLSearchParams();
+    if (params?.limit) searchParams.set("limit", params.limit.toString());
+    if (params?.cursor) searchParams.set("cursor", params.cursor);
+    if (params?.customerId) searchParams.set("customerId", params.customerId);
+    if (params?.status) searchParams.set("status", params.status);
+    const query = searchParams.toString();
+    const path = query ? `/subscriptions?${query}` : "/subscriptions";
+    return this.http.get(path, options);
+  }
+};
+
+// src/resources/webhooks.ts
+var Webhooks = class {
+  /**
+   * Verify webhook signature and parse the event
+   *
+   * @example
+   * ```typescript
+   * // Express.js example
+   * app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
+   *   const signature = req.headers['imerchant-signature'] as string;
+   *
+   *   try {
+   *     const event = iMerchant.webhooks.verify({
+   *       body: req.body.toString(),
+   *       signature,
+   *     }, process.env.WEBHOOK_SECRET);
+   *
+   *     switch (event.type) {
+   *       case 'payment.captured':
+   *         // Handle successful payment
+   *         break;
+   *       case 'payment.failed':
+   *         // Handle failed payment
+   *         break;
+   *     }
+   *
+   *     res.json({ received: true });
+   *   } catch (err) {
+   *     res.status(400).send('Invalid signature');
+   *   }
+   * });
+   * ```
+   *
+   * @param payload - The webhook payload containing body and signature
+   * @param secret - Your webhook signing secret
+   * @returns The verified and parsed webhook event
+   * @throws {WebhookSignatureError} If signature verification fails
+   */
+  static verify(payload, secret) {
+    if (!payload.body || !payload.signature) {
+      throw new WebhookSignatureError("Missing payload body or signature");
+    }
+    if (!secret) {
+      throw new WebhookSignatureError("Webhook secret is required");
+    }
+    const parts = payload.signature.split(",");
+    const signatureParts = {};
+    for (const part of parts) {
+      const [key, value] = part.split("=");
+      if (key && value) {
+        signatureParts[key] = value;
+      }
+    }
+    const timestamp = signatureParts["t"];
+    const signature = signatureParts["v1"];
+    if (!timestamp || !signature) {
+      throw new WebhookSignatureError("Invalid signature format");
+    }
+    const timestampAge = Date.now() - parseInt(timestamp, 10) * 1e3;
+    if (timestampAge > 5 * 60 * 1e3) {
+      throw new WebhookSignatureError("Webhook timestamp too old");
+    }
+    const expectedSignature = this.computeSignature(
+      `${timestamp}.${payload.body}`,
+      secret
+    );
+    if (!this.secureCompare(signature, expectedSignature)) {
+      throw new WebhookSignatureError("Signature verification failed");
+    }
+    try {
+      return JSON.parse(payload.body);
+    } catch {
+      throw new WebhookSignatureError("Invalid JSON payload");
+    }
+  }
+  /**
+   * Compute HMAC-SHA256 signature
+   * Uses Node.js crypto module (available in Node.js environments)
+   */
+  static computeSignature(data, secret) {
+    if (typeof process !== "undefined" && process.versions?.node) {
+      try {
+        const requireFn = new Function("moduleName", "return require(moduleName)");
+        const cryptoModule = requireFn("crypto");
+        return cryptoModule.createHmac("sha256", secret).update(data).digest("hex");
+      } catch {
+        throw new WebhookSignatureError(
+          "Unable to load crypto module. Ensure you are running in Node.js."
+        );
+      }
+    }
+    throw new WebhookSignatureError(
+      "Synchronous signature verification is only available in Node.js. Use verifyAsync() in browser environments."
+    );
+  }
+  /**
+   * Timing-safe string comparison to prevent timing attacks
+   */
+  static secureCompare(a, b) {
+    if (a.length !== b.length) {
+      return false;
+    }
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+      result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return result === 0;
+  }
+  /**
+   * Async signature verification using Web Crypto API
+   * Use this in environments that support Web Crypto
+   *
+   * @example
+   * ```typescript
+   * const event = await iMerchant.webhooks.verifyAsync(payload, secret);
+   * ```
+   */
+  static async verifyAsync(payload, secret) {
+    if (!payload.body || !payload.signature) {
+      throw new WebhookSignatureError("Missing payload body or signature");
+    }
+    if (!secret) {
+      throw new WebhookSignatureError("Webhook secret is required");
+    }
+    const parts = payload.signature.split(",");
+    const signatureParts = {};
+    for (const part of parts) {
+      const [key2, value] = part.split("=");
+      if (key2 && value) {
+        signatureParts[key2] = value;
+      }
+    }
+    const timestamp = signatureParts["t"];
+    const signature = signatureParts["v1"];
+    if (!timestamp || !signature) {
+      throw new WebhookSignatureError("Invalid signature format");
+    }
+    const timestampAge = Date.now() - parseInt(timestamp, 10) * 1e3;
+    if (timestampAge > 5 * 60 * 1e3) {
+      throw new WebhookSignatureError("Webhook timestamp too old");
+    }
+    const encoder = new TextEncoder();
+    const key = await crypto.subtle.importKey(
+      "raw",
+      encoder.encode(secret),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"]
+    );
+    const signatureData = encoder.encode(`${timestamp}.${payload.body}`);
+    const signatureBuffer = await crypto.subtle.sign("HMAC", key, signatureData);
+    const expectedSignature = Array.from(new Uint8Array(signatureBuffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+    if (!this.secureCompare(signature, expectedSignature)) {
+      throw new WebhookSignatureError("Signature verification failed");
+    }
+    try {
+      return JSON.parse(payload.body);
+    } catch {
+      throw new WebhookSignatureError("Invalid JSON payload");
+    }
+  }
+};
+
+// src/client.ts
+var iMerchant = class {
+  /**
+   * Create a new iMerchant client
+   *
+   * @param config - Client configuration
+   * @param config.apiKey - Your iMerchant API key (required)
+   * @param config.baseUrl - API base URL (optional, defaults to https://api.imerchant.com)
+   * @param config.timeout - Request timeout in ms (optional, defaults to 30000)
+   * @param config.apiVersion - API version (optional, defaults to 'v1')
+   */
+  constructor(config) {
+    this.http = new HttpClient(config);
+    this.payments = new Payments(this.http);
+    this.refunds = new Refunds(this.http);
+    this.customers = new Customers(this.http);
+    this.subscriptions = new Subscriptions(this.http);
+  }
+};
+/**
+ * Static webhook utilities for signature verification
+ */
+iMerchant.webhooks = Webhooks;
+export {
+  APIError,
+  AuthenticationError,
+  Customers,
+  NotFoundError,
+  Payments,
+  RateLimitError,
+  Refunds,
+  Subscriptions,
+  ValidationError,
+  WebhookSignatureError,
+  Webhooks,
+  iMerchant,
+  iMerchantError
+};