@zendfi/sdk 0.1.1

package/dist/index.mjs

@@ -0,0 +1,640 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/client.ts
+import fetch from "cross-fetch";
+import { createHmac, timingSafeEqual } from "crypto";
+
+// src/types.ts
+var ZendFiError = class extends Error {
+  constructor(message, statusCode, code, details) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.details = details;
+    this.name = "ZendFiError";
+  }
+};
+var AuthenticationError = class extends ZendFiError {
+  constructor(message = "Authentication failed") {
+    super(message, 401, "AUTHENTICATION_ERROR");
+    this.name = "AuthenticationError";
+  }
+};
+var ValidationError = class extends ZendFiError {
+  constructor(message, details) {
+    super(message, 400, "VALIDATION_ERROR", details);
+    this.name = "ValidationError";
+  }
+};
+var NetworkError = class extends ZendFiError {
+  constructor(message) {
+    super(message, 0, "NETWORK_ERROR");
+    this.name = "NetworkError";
+  }
+};
+var RateLimitError = class extends ZendFiError {
+  constructor(message = "Rate limit exceeded") {
+    super(message, 429, "RATE_LIMIT_ERROR");
+    this.name = "RateLimitError";
+  }
+};
+
+// src/utils.ts
+var ConfigLoader = class {
+  /**
+   * Load configuration from various sources
+   */
+  static load(options) {
+    const environment = this.detectEnvironment();
+    const apiKey = this.loadApiKey(options?.apiKey);
+    const baseURL = this.getBaseURL(environment, options?.baseURL);
+    return {
+      apiKey,
+      baseURL,
+      environment,
+      timeout: options?.timeout ?? 3e4,
+      retries: options?.retries ?? 3,
+      idempotencyEnabled: options?.idempotencyEnabled ?? true
+    };
+  }
+  /**
+   * Detect environment based on various signals
+   */
+  static detectEnvironment() {
+    const envVar = process.env.ZENDFI_ENVIRONMENT || process.env.NEXT_PUBLIC_ZENDFI_ENVIRONMENT;
+    if (envVar) {
+      return envVar;
+    }
+    if (typeof process !== "undefined" && process.env) {
+      const nodeEnv = process.env.NODE_ENV;
+      if (nodeEnv === "production") return "production";
+      if (nodeEnv === "staging") return "staging";
+      if (nodeEnv === "development" || nodeEnv === "test") return "development";
+    }
+    if (typeof window !== "undefined") {
+      const hostname = window.location.hostname;
+      if (hostname === "yourdomain.com" || hostname === "www.yourdomain.com") {
+        return "production";
+      }
+      if (hostname.includes("staging") || hostname.includes(".vercel.app")) {
+        return "staging";
+      }
+      if (hostname === "localhost" || hostname === "127.0.0.1") {
+        return "development";
+      }
+    }
+    return "development";
+  }
+  /**
+   * Load API key from various sources
+   */
+  static loadApiKey(explicitKey) {
+    if (explicitKey) return explicitKey;
+    if (typeof process !== "undefined" && process.env) {
+      const envKey = process.env.ZENDFI_API_KEY || process.env.NEXT_PUBLIC_ZENDFI_API_KEY || process.env.REACT_APP_ZENDFI_API_KEY;
+      if (envKey) return envKey;
+    }
+    try {
+      const credentials = this.loadCLICredentials();
+      if (credentials?.apiKey) return credentials.apiKey;
+    } catch {
+    }
+    throw new Error(
+      "ZendFi API key not found. Set ZENDFI_API_KEY environment variable or pass apiKey in constructor."
+    );
+  }
+  /**
+   * Get base URL for API
+   */
+  static getBaseURL(_environment, explicitURL) {
+    if (explicitURL) return explicitURL;
+    return process.env.ZENDFI_API_URL || "https://api.zendfi.tech";
+  }
+  /**
+   * Load credentials from CLI config file (~/.zendfi/credentials.json)
+   */
+  static loadCLICredentials() {
+    if (typeof process === "undefined" || !process.env.HOME) {
+      return null;
+    }
+    try {
+      const fs = __require("fs");
+      const path = __require("path");
+      const credentialsPath = path.join(process.env.HOME, ".zendfi", "credentials.json");
+      if (fs.existsSync(credentialsPath)) {
+        const data = fs.readFileSync(credentialsPath, "utf-8");
+        return JSON.parse(data);
+      }
+    } catch (error) {
+    }
+    return null;
+  }
+  /**
+   * Validate API key format
+   */
+  static validateApiKey(apiKey) {
+    if (!apiKey.startsWith("zfi_test_") && !apiKey.startsWith("zfi_live_")) {
+      throw new Error(
+        'Invalid API key format. ZendFi API keys should start with "zfi_test_" or "zfi_live_"'
+      );
+    }
+    if (apiKey.startsWith("zfi_live_")) {
+      const env = this.detectEnvironment();
+      if (env === "development") {
+        console.warn(
+          "\u26A0\uFE0F  Warning: Using a live API key (zfi_live_) in development environment. This will create real transactions. Use a test key (zfi_test_) for development."
+        );
+      }
+    }
+  }
+};
+function parseError(response, body) {
+  const statusCode = response.status;
+  const errorMessage = body?.error || body?.message || response.statusText || "Unknown error";
+  const errorCode = body?.code;
+  const details = body?.details;
+  switch (statusCode) {
+    case 401:
+    case 403:
+      return new AuthenticationError(errorMessage);
+    case 400:
+      return new ValidationError(errorMessage, details);
+    case 429:
+      return new RateLimitError(errorMessage);
+    case 500:
+    case 502:
+    case 503:
+    case 504:
+      return new NetworkError(errorMessage);
+    default:
+      return new ZendFiError(errorMessage, statusCode, errorCode, details);
+  }
+}
+function generateIdempotencyKey() {
+  const timestamp = Date.now();
+  const random = Math.random().toString(36).substring(2, 15);
+  return `zfi_idem_${timestamp}_${random}`;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/client.ts
+var ZendFiClient = class {
+  config;
+  constructor(options) {
+    this.config = ConfigLoader.load(options);
+    ConfigLoader.validateApiKey(this.config.apiKey);
+  }
+  /**
+   * Create a new payment
+   */
+  async createPayment(request) {
+    return this.request("POST", "/api/v1/payments", {
+      ...request,
+      currency: request.currency || "USD",
+      token: request.token || "USDC"
+    });
+  }
+  /**
+   * Get payment by ID
+   */
+  async getPayment(paymentId) {
+    return this.request("GET", `/api/v1/payments/${paymentId}`);
+  }
+  /**
+   * List all payments with pagination
+   */
+  async listPayments(request) {
+    const params = new URLSearchParams();
+    if (request?.page) params.append("page", request.page.toString());
+    if (request?.limit) params.append("limit", request.limit.toString());
+    if (request?.status) params.append("status", request.status);
+    if (request?.from_date) params.append("from_date", request.from_date);
+    if (request?.to_date) params.append("to_date", request.to_date);
+    const query = params.toString() ? `?${params.toString()}` : "";
+    return this.request("GET", `/api/v1/payments${query}`);
+  }
+  /**
+   * Create a subscription plan
+   */
+  async createSubscriptionPlan(request) {
+    return this.request("POST", "/api/v1/subscriptions/plans", {
+      ...request,
+      currency: request.currency || "USD",
+      interval_count: request.interval_count || 1,
+      trial_days: request.trial_days || 0
+    });
+  }
+  /**
+   * Get subscription plan by ID
+   */
+  async getSubscriptionPlan(planId) {
+    return this.request("GET", `/api/v1/subscriptions/plans/${planId}`);
+  }
+  /**
+   * Create a subscription
+   */
+  async createSubscription(request) {
+    return this.request("POST", "/api/v1/subscriptions", request);
+  }
+  /**
+   * Get subscription by ID
+   */
+  async getSubscription(subscriptionId) {
+    return this.request("GET", `/api/v1/subscriptions/${subscriptionId}`);
+  }
+  /**
+   * Cancel a subscription
+   */
+  async cancelSubscription(subscriptionId) {
+    return this.request(
+      "POST",
+      `/api/v1/subscriptions/${subscriptionId}/cancel`
+    );
+  }
+  /**
+   * Create a payment link (shareable checkout URL)
+   */
+  async createPaymentLink(request) {
+    const response = await this.request("POST", "/api/v1/payment-links", {
+      ...request,
+      currency: request.currency || "USD",
+      token: request.token || "USDC"
+    });
+    return {
+      ...response,
+      url: response.hosted_page_url
+    };
+  }
+  /**
+   * Get payment link by link code
+   */
+  async getPaymentLink(linkCode) {
+    const response = await this.request("GET", `/api/v1/payment-links/${linkCode}`);
+    return {
+      ...response,
+      url: response.hosted_page_url
+    };
+  }
+  /**
+   * List all payment links
+   */
+  async listPaymentLinks() {
+    return [];
+  }
+  // ===================================================================
+  // INSTALLMENT PLANS - Pay over time
+  // ===================================================================
+  /**
+   * Create an installment plan
+   * Split a purchase into multiple scheduled payments
+   */
+  async createInstallmentPlan(request) {
+    const response = await this.request(
+      "POST",
+      "/api/v1/installment-plans",
+      request
+    );
+    return {
+      id: response.plan_id,
+      plan_id: response.plan_id,
+      status: response.status
+    };
+  }
+  /**
+   * Get installment plan by ID
+   */
+  async getInstallmentPlan(planId) {
+    return this.request("GET", `/api/v1/installment-plans/${planId}`);
+  }
+  /**
+   * List all installment plans for merchant
+   */
+  async listInstallmentPlans(params) {
+    const query = new URLSearchParams();
+    if (params?.limit) query.append("limit", params.limit.toString());
+    if (params?.offset) query.append("offset", params.offset.toString());
+    const queryString = query.toString() ? `?${query.toString()}` : "";
+    return this.request("GET", `/api/v1/installment-plans${queryString}`);
+  }
+  /**
+   * List installment plans for a specific customer
+   */
+  async listCustomerInstallmentPlans(customerWallet) {
+    return this.request(
+      "GET",
+      `/api/v1/customers/${customerWallet}/installment-plans`
+    );
+  }
+  /**
+   * Cancel an installment plan
+   */
+  async cancelInstallmentPlan(planId) {
+    return this.request(
+      "POST",
+      `/api/v1/installment-plans/${planId}/cancel`
+    );
+  }
+  // ===================================================================
+  // ESCROW - Secure fund holding
+  // ===================================================================
+  /**
+   * Create an escrow transaction
+   * Hold funds until conditions are met
+   */
+  async createEscrow(request) {
+    return this.request("POST", "/api/v1/escrows", {
+      ...request,
+      currency: request.currency || "USD",
+      token: request.token || "USDC"
+    });
+  }
+  /**
+   * Get escrow by ID
+   */
+  async getEscrow(escrowId) {
+    return this.request("GET", `/api/v1/escrows/${escrowId}`);
+  }
+  /**
+   * List all escrows for merchant
+   */
+  async listEscrows(params) {
+    const query = new URLSearchParams();
+    if (params?.limit) query.append("limit", params.limit.toString());
+    if (params?.offset) query.append("offset", params.offset.toString());
+    const queryString = query.toString() ? `?${query.toString()}` : "";
+    return this.request("GET", `/api/v1/escrows${queryString}`);
+  }
+  /**
+   * Approve escrow release to seller
+   */
+  async approveEscrow(escrowId, request) {
+    return this.request(
+      "POST",
+      `/api/v1/escrows/${escrowId}/approve`,
+      request
+    );
+  }
+  /**
+   * Refund escrow to buyer
+   */
+  async refundEscrow(escrowId, request) {
+    return this.request("POST", `/api/v1/escrows/${escrowId}/refund`, request);
+  }
+  /**
+   * Raise a dispute for an escrow
+   */
+  async disputeEscrow(escrowId, request) {
+    return this.request("POST", `/api/v1/escrows/${escrowId}/dispute`, request);
+  }
+  // ===================================================================
+  // INVOICES - Professional billing
+  // ===================================================================
+  /**
+   * Create an invoice
+   */
+  async createInvoice(request) {
+    return this.request("POST", "/api/v1/invoices", {
+      ...request,
+      token: request.token || "USDC"
+    });
+  }
+  /**
+   * Get invoice by ID
+   */
+  async getInvoice(invoiceId) {
+    return this.request("GET", `/api/v1/invoices/${invoiceId}`);
+  }
+  /**
+   * List all invoices for merchant
+   */
+  async listInvoices() {
+    return this.request("GET", "/api/v1/invoices");
+  }
+  /**
+   * Send invoice to customer via email
+   */
+  async sendInvoice(invoiceId) {
+    return this.request("POST", `/api/v1/invoices/${invoiceId}/send`);
+  }
+  /**
+   * Verify webhook signature using HMAC-SHA256
+   * 
+   * @param request - Webhook verification request containing payload, signature, and secret
+   * @returns true if signature is valid, false otherwise
+   * 
+   * @example
+   * ```typescript
+   * const isValid = zendfi.verifyWebhook({
+   *   payload: req.body,
+   *   signature: req.headers['x-zendfi-signature'],
+   *   secret: process.env.ZENDFI_WEBHOOK_SECRET
+   * });
+   * 
+   * if (!isValid) {
+   *   return res.status(401).json({ error: 'Invalid signature' });
+   * }
+   * ```
+   */
+  verifyWebhook(request) {
+    try {
+      if (!request.payload || !request.signature || !request.secret) {
+        return false;
+      }
+      const parsedPayload = JSON.parse(request.payload);
+      if (!parsedPayload.event || !parsedPayload.merchant_id || !parsedPayload.timestamp) {
+        return false;
+      }
+      const computedSignature = this.computeHmacSignature(request.payload, request.secret);
+      return this.timingSafeEqual(request.signature, computedSignature);
+    } catch (error) {
+      if (this.config.environment === "development") {
+        console.error("Webhook verification error:", error);
+      }
+      return false;
+    }
+  }
+  /**
+   * Compute HMAC-SHA256 signature
+   * Works in both Node.js and browser environments
+   */
+  computeHmacSignature(payload, secret) {
+    if (typeof process !== "undefined" && process.versions?.node) {
+      return createHmac("sha256", secret).update(payload, "utf8").digest("hex");
+    }
+    throw new Error(
+      "Webhook verification in browser is not supported. Use this method in your backend/server environment."
+    );
+  }
+  /**
+   * Timing-safe string comparison to prevent timing attacks
+   */
+  timingSafeEqual(a, b) {
+    if (a.length !== b.length) {
+      return false;
+    }
+    if (typeof process !== "undefined" && process.versions?.node) {
+      try {
+        const bufferA = Buffer.from(a, "utf8");
+        const bufferB = Buffer.from(b, "utf8");
+        return timingSafeEqual(bufferA, bufferB);
+      } catch {
+      }
+    }
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+      result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return result === 0;
+  }
+  /**
+   * Make an HTTP request with retry logic
+   */
+  async request(method, endpoint, data, options = {}) {
+    const attempt = options.attempt || 1;
+    const idempotencyKey = options.idempotencyKey || (this.config.idempotencyEnabled && method !== "GET" ? generateIdempotencyKey() : void 0);
+    try {
+      const url = `${this.config.baseURL}${endpoint}`;
+      const headers = {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.config.apiKey}`
+      };
+      if (idempotencyKey) {
+        headers["Idempotency-Key"] = idempotencyKey;
+      }
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: data ? JSON.stringify(data) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      let body;
+      try {
+        body = await response.json();
+      } catch {
+        body = null;
+      }
+      if (!response.ok) {
+        const error = parseError(response, body);
+        if (response.status >= 500 && attempt < this.config.retries) {
+          const delay = Math.pow(2, attempt) * 1e3;
+          await sleep(delay);
+          return this.request(method, endpoint, data, {
+            idempotencyKey,
+            attempt: attempt + 1
+          });
+        }
+        throw error;
+      }
+      return body;
+    } catch (error) {
+      if (error.name === "AbortError") {
+        throw new Error(`Request timeout after ${this.config.timeout}ms`);
+      }
+      if (attempt < this.config.retries && error.message?.includes("fetch")) {
+        const delay = Math.pow(2, attempt) * 1e3;
+        await sleep(delay);
+        return this.request(method, endpoint, data, {
+          idempotencyKey,
+          attempt: attempt + 1
+        });
+      }
+      throw error;
+    }
+  }
+};
+var zendfi = (() => {
+  try {
+    return new ZendFiClient();
+  } catch (error) {
+    if (process.env.NODE_ENV === "test" || !process.env.ZENDFI_API_KEY) {
+      return new Proxy({}, {
+        get() {
+          throw new Error(
+            'ZendFi singleton not initialized. Set ZENDFI_API_KEY environment variable or create a custom instance: new ZendFiClient({ apiKey: "..." })'
+          );
+        }
+      });
+    }
+    throw error;
+  }
+})();
+
+// src/webhooks.ts
+async function verifyNextWebhook(request, secret) {
+  try {
+    const payload = await request.text();
+    const signature = request.headers.get("x-zendfi-signature");
+    if (!signature) {
+      return null;
+    }
+    const webhookSecret = secret || process.env.ZENDFI_WEBHOOK_SECRET;
+    if (!webhookSecret) {
+      throw new Error("ZENDFI_WEBHOOK_SECRET not configured");
+    }
+    const isValid = zendfi.verifyWebhook({
+      payload,
+      signature,
+      secret: webhookSecret
+    });
+    if (!isValid) {
+      return null;
+    }
+    return JSON.parse(payload);
+  } catch {
+    return null;
+  }
+}
+async function verifyExpressWebhook(request, secret) {
+  try {
+    const payload = request.rawBody || JSON.stringify(request.body);
+    const signature = request.headers["x-zendfi-signature"];
+    if (!signature) {
+      return null;
+    }
+    const webhookSecret = secret || process.env.ZENDFI_WEBHOOK_SECRET;
+    if (!webhookSecret) {
+      throw new Error("ZENDFI_WEBHOOK_SECRET not configured");
+    }
+    const isValid = zendfi.verifyWebhook({
+      payload,
+      signature,
+      secret: webhookSecret
+    });
+    if (!isValid) {
+      return null;
+    }
+    return JSON.parse(payload);
+  } catch {
+    return null;
+  }
+}
+function verifyWebhookSignature(payload, signature, secret) {
+  return zendfi.verifyWebhook({
+    payload,
+    signature,
+    secret
+  });
+}
+export {
+  AuthenticationError,
+  ConfigLoader,
+  NetworkError,
+  RateLimitError,
+  ValidationError,
+  ZendFiClient,
+  ZendFiError,
+  verifyExpressWebhook,
+  verifyNextWebhook,
+  verifyWebhookSignature,
+  zendfi
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@zendfi/sdk",
+  "version": "0.1.1",
+  "description": "Zero-config TypeScript SDK for ZendFi crypto payments",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "zendfi",
+    "crypto",
+    "payments",
+    "solana",
+    "sdk",
+    "typescript"
+  ],
+  "author": "ZendFi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zendfi/zendfi-toolkit.git",
+    "directory": "packages/sdk"
+  },
+  "dependencies": {
+    "cross-fetch": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.19",
+    "tsup": "^8.0.2",
+    "typescript": "^5.3.3",
+    "vitest": "^1.3.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}