@fastaar/nextjs 0.1.0

package/README.md

@@ -0,0 +1,159 @@
+# Fastaar Next.js integration
+
+Accept bKash & Nagad payments in your Next.js application using [Fastaar](https://fastaar.com).
+
+This package is optimized for the Next.js App Router, featuring full support for **React Server Components (RSC)**, **Server Actions**, and Next.js **Route Handlers** for webhook signature verification. Written entirely in TypeScript.
+
+## Features
+
+- **React Server Components**: `<CheckoutButton>` for instant checkout forms.
+- **Server Actions**: Clean integration with server redirects.
+- **Route Handlers Webhook Helper**: Automatically reads, verifies, and parses incoming webhooks.
+- **Client Caching**: Singleton instance caching to prevent multiple instances during fast-refresh in development.
+- **Full TypeScript Support**: Auto-complete and strict types for payments, config, and webhooks.
+
+## Install
+
+Install the package and its peer dependencies (if not already installed):
+
+```bash
+npm install @fastaar/nextjs
+```
+
+## Configuration
+
+Set the following environment variables in your `.env.local` or hosting provider:
+
+```env
+# Required: Your Fastaar Live/Test API key
+FASTAAR_API_KEY="fk_live_..."
+
+# Optional: Your Webhook secret for signature verification
+FASTAAR_WEBHOOK_SECRET="whsec_..."
+```
+
+---
+
+## Usage
+
+### 1. Simple Checkout Button (Server Component)
+
+Use the built-in `<CheckoutButton>` React Server Component. It renders a HTML form that invokes a Server Action to create the payment intent and automatically redirects the customer.
+
+```tsx
+import { CheckoutButton } from '@fastaar/nextjs';
+
+export default function CheckoutPage() {
+  return (
+    <main style={{ padding: '2rem' }}>
+      <h1>Complete your purchase</h1>
+      <p>Amount: 1,250 BDT</p>
+      
+      <CheckoutButton
+        paymentParams={{
+          amount: 1250,
+          invoice_id: 'ORDER-42',
+          success_url: 'https://your-site.com/thanks',
+          cancel_url: 'https://your-site.com/cart',
+          metadata: { userId: 'usr_1001' },
+        }}
+        className="px-4 py-2 bg-green-600 text-white rounded hover:bg-green-700"
+      >
+        Pay with bKash / Nagad
+      </CheckoutButton>
+    </main>
+  );
+}
+```
+
+### 2. Custom Flow (Server Actions)
+
+If you need to perform additional server-side operations (like saving the order in your database as "pending" before redirecting), use `getFastaarClient` in your own Server Action:
+
+```tsx
+import { getFastaarClient } from '@fastaar/nextjs';
+import { redirect } from 'next/navigation';
+
+export default function CheckoutPage() {
+  async function handleCheckout() {
+    'use server';
+
+    // 1. Create order in your database
+    // const order = await db.order.create(...);
+
+    // 2. Initialize Fastaar client and create payment
+    const fastaar = getFastaarClient();
+    const payment = await fastaar.createPayment({
+      amount: 1250,
+      invoice_id: 'ORDER-42',
+      success_url: 'https://your-site.com/thanks',
+      cancel_url: 'https://your-site.com/cart',
+    });
+
+    // 3. Redirect to checkout page
+    redirect(payment.checkout_url);
+  }
+
+  return (
+    <form action={handleCheckout}>
+      <button type="submit">Pay Now</button>
+    </form>
+  );
+}
+```
+
+### 3. Webhook Route Handler (Next.js App Router)
+
+Handle payment status notifications securely using Next.js Route Handlers. The `verifyNextWebhook` helper handles raw stream reading and signature verification using your `FASTAAR_WEBHOOK_SECRET`.
+
+Create a file at `app/api/webhooks/fastaar/route.ts`:
+
+```typescript
+import { verifyNextWebhook } from '@fastaar/nextjs';
+import { NextResponse } from 'next/server';
+
+export async function POST(req: Request) {
+  const { isValid, event } = await verifyNextWebhook(req);
+
+  if (!isValid || !event) {
+    return new NextResponse('Invalid signature', { status: 400 });
+  }
+
+  // Handle the webhook event
+  if (event.event === 'payment.completed') {
+    const payment = event.data;
+    const invoiceId = payment.invoice_id; // e.g. 'ORDER-42'
+    const trxId = payment.trx_id;         // operator transaction ID
+    
+    // Mark order as paid in database idempotently
+    // await db.order.update({ where: { id: invoiceId }, data: { paid: true, trxId } });
+    
+    console.log(`Payment completed for invoice ${invoiceId}`);
+  }
+
+  return new NextResponse('OK', { status: 200 });
+}
+```
+
+### 4. Fetching Payment Details
+
+To manually fetch details for a payment or invoice:
+
+```typescript
+import { getFastaarClient } from '@fastaar/nextjs';
+
+const fastaar = getFastaarClient();
+
+// Get by Fastaar payment ID
+const payment = await fastaar.getPayment('01jxyz...');
+
+// Look up by your own invoice ID
+const payment = await fastaar.findByInvoiceId('ORDER-42');
+
+// List payments
+const payments = await fastaar.listPayments({ status: 'completed', per_page: 10 });
+```
+
+## License
+
+MIT

package/dist/actions.cjs

@@ -0,0 +1,36 @@
+"use strict";
+"use server";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var actions_exports = {};
+__export(actions_exports, {
+  createCheckoutRedirect: () => createCheckoutRedirect
+});
+module.exports = __toCommonJS(actions_exports);
+var import_navigation = require("next/navigation");
+var import_client = require("./client");
+async function createCheckoutRedirect(params) {
+  const client = (0, import_client.getFastaarClient)();
+  const payment = await client.createPayment(params);
+  (0, import_navigation.redirect)(payment.checkout_url);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createCheckoutRedirect
+});
+//# sourceMappingURL=actions.cjs.map

package/dist/actions.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/actions.ts"],"sourcesContent":["\"use server\";\n\nimport { redirect } from 'next/navigation';\nimport { getFastaarClient } from './client';\nimport { CreatePaymentParams } from './types';\n\n/**\n * Server Action to create a payment intent and redirect the user to the checkout URL.\n * \n * @param params Payment creation parameters\n */\nexport async function createCheckoutRedirect(params: CreatePaymentParams): Promise<never> {\n  const client = getFastaarClient();\n  const payment = await client.createPayment(params);\n  redirect(payment.checkout_url);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAEA,wBAAyB;AACzB,oBAAiC;AAQjC,eAAsB,uBAAuB,QAA6C;AACxF,QAAM,aAAS,gCAAiB;AAChC,QAAM,UAAU,MAAM,OAAO,cAAc,MAAM;AACjD,kCAAS,QAAQ,YAAY;AAC/B;","names":[]}

package/dist/actions.d.cts

@@ -0,0 +1,10 @@
+import { CreatePaymentParams } from './types.cjs';
+
+/**
+ * Server Action to create a payment intent and redirect the user to the checkout URL.
+ *
+ * @param params Payment creation parameters
+ */
+declare function createCheckoutRedirect(params: CreatePaymentParams): Promise<never>;
+
+export { createCheckoutRedirect };

package/dist/actions.d.ts

@@ -0,0 +1,10 @@
+import { CreatePaymentParams } from './types.js';
+
+/**
+ * Server Action to create a payment intent and redirect the user to the checkout URL.
+ *
+ * @param params Payment creation parameters
+ */
+declare function createCheckoutRedirect(params: CreatePaymentParams): Promise<never>;
+
+export { createCheckoutRedirect };

package/dist/actions.js

@@ -0,0 +1,12 @@
+"use server";
+import { redirect } from "next/navigation";
+import { getFastaarClient } from "./client";
+async function createCheckoutRedirect(params) {
+  const client = getFastaarClient();
+  const payment = await client.createPayment(params);
+  redirect(payment.checkout_url);
+}
+export {
+  createCheckoutRedirect
+};
+//# sourceMappingURL=actions.js.map

package/dist/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/actions.ts"],"sourcesContent":["\"use server\";\n\nimport { redirect } from 'next/navigation';\nimport { getFastaarClient } from './client';\nimport { CreatePaymentParams } from './types';\n\n/**\n * Server Action to create a payment intent and redirect the user to the checkout URL.\n * \n * @param params Payment creation parameters\n */\nexport async function createCheckoutRedirect(params: CreatePaymentParams): Promise<never> {\n  const client = getFastaarClient();\n  const payment = await client.createPayment(params);\n  redirect(payment.checkout_url);\n}\n"],"mappings":";AAEA,SAAS,gBAAgB;AACzB,SAAS,wBAAwB;AAQjC,eAAsB,uBAAuB,QAA6C;AACxF,QAAM,SAAS,iBAAiB;AAChC,QAAM,UAAU,MAAM,OAAO,cAAc,MAAM;AACjD,WAAS,QAAQ,YAAY;AAC/B;","names":[]}

package/dist/client.cjs

@@ -0,0 +1,145 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var client_exports = {};
+__export(client_exports, {
+  FastaarClient: () => FastaarClient,
+  FastaarError: () => FastaarError,
+  getFastaarClient: () => getFastaarClient
+});
+module.exports = __toCommonJS(client_exports);
+const API_BASE_URL = "https://fastaar.com";
+class FastaarError extends Error {
+  /**
+   * The type of the error returned by the API (e.g. 'authentication_error', 'validation_error').
+   */
+  errorType;
+  /**
+   * The HTTP status code returned by the API.
+   */
+  statusCode;
+  constructor(message, errorType = "api_error", statusCode = 0) {
+    super(message);
+    this.name = "FastaarError";
+    this.errorType = errorType;
+    this.statusCode = statusCode;
+  }
+}
+class FastaarClient {
+  apiKey;
+  timeoutMs;
+  /**
+   * @param apiKey Your Fastaar API Key (fk_live_... or fk_test_...)
+   * @param options Client configuration options
+   */
+  constructor(apiKey, options = {}) {
+    if (!apiKey) {
+      throw new FastaarError("API key is required to initialize FastaarClient.", "authentication_error");
+    }
+    this.apiKey = apiKey;
+    this.timeoutMs = options.timeoutMs ?? 15e3;
+  }
+  /**
+   * Create a payment intent. Returns the payment object including
+   * `id`, `status`, and `checkout_url`.
+   *
+   * Reusing the same `invoice_id` returns the existing payment instead of
+   * creating a duplicate, so retries are safe. Supply `success_url`/`cancel_url`
+   * to return the customer to your site after checkout.
+   */
+  async createPayment(params) {
+    return this.request("POST", "/api/v1/payments", params);
+  }
+  /**
+   * Retrieve a payment by its reference ID.
+   */
+  async getPayment(paymentId) {
+    return this.request("GET", `/api/v1/payments/${encodeURIComponent(paymentId)}`);
+  }
+  /**
+   * List payments, newest first.
+   */
+  async listPayments(params = {}) {
+    const stringParams = {};
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== void 0) {
+        stringParams[key] = String(value);
+      }
+    }
+    const query = new URLSearchParams(stringParams).toString();
+    return this.request("GET", `/api/v1/payments${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Find the most recent payment for one of your invoice IDs, or null if none exist.
+   */
+  async findByInvoiceId(invoiceId) {
+    const payments = await this.listPayments({ invoice_id: invoiceId });
+    return payments[0] ?? null;
+  }
+  /**
+   * Helper to perform HTTP request to Fastaar API.
+   */
+  async request(method, path, body) {
+    let response;
+    try {
+      response = await fetch(API_BASE_URL + path, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          Accept: "application/json",
+          ...body ? { "Content-Type": "application/json" } : {}
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+    } catch (error) {
+      throw new FastaarError(`Could not reach the Fastaar API: ${error.message}`, "connection_error");
+    }
+    const payload = await response.json().catch(() => null);
+    if (!response.ok || payload === null) {
+      throw new FastaarError(
+        payload?.error?.message ?? `Fastaar API returned HTTP ${response.status}.`,
+        payload?.error?.type ?? "api_error",
+        response.status
+      );
+    }
+    return payload.data ?? payload;
+  }
+}
+const globalForFastaar = globalThis;
+function getFastaarClient() {
+  if (!globalForFastaar.fastaarClient) {
+    const apiKey = process.env.FASTAAR_API_KEY;
+    if (!apiKey) {
+      throw new FastaarError(
+        "FASTAAR_API_KEY environment variable is not defined.",
+        "authentication_error"
+      );
+    }
+    const timeoutMs = process.env.FASTAAR_TIMEOUT_MS ? parseInt(process.env.FASTAAR_TIMEOUT_MS, 10) : void 0;
+    globalForFastaar.fastaarClient = new FastaarClient(apiKey, { timeoutMs });
+  }
+  return globalForFastaar.fastaarClient;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FastaarClient,
+  FastaarError,
+  getFastaarClient
+});
+//# sourceMappingURL=client.cjs.map

package/dist/client.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import { CreatePaymentParams, FastaarClientOptions, ListPaymentsParams, Payment } from './types';\n\nconst API_BASE_URL = 'https://fastaar.com';\n\n/**\n * Custom error class for Fastaar API errors.\n */\nexport class FastaarError extends Error {\n  /**\n   * The type of the error returned by the API (e.g. 'authentication_error', 'validation_error').\n   */\n  errorType: string;\n\n  /**\n   * The HTTP status code returned by the API.\n   */\n  statusCode: number;\n\n  constructor(message: string, errorType = 'api_error', statusCode = 0) {\n    super(message);\n    this.name = 'FastaarError';\n    this.errorType = errorType;\n    this.statusCode = statusCode;\n  }\n}\n\n/**\n * Client for interacting with the Fastaar Payment Gateway API.\n */\nexport class FastaarClient {\n  private apiKey: string;\n  private timeoutMs: number;\n\n  /**\n   * @param apiKey Your Fastaar API Key (fk_live_... or fk_test_...)\n   * @param options Client configuration options\n   */\n  constructor(apiKey: string, options: FastaarClientOptions = {}) {\n    if (!apiKey) {\n      throw new FastaarError('API key is required to initialize FastaarClient.', 'authentication_error');\n    }\n    this.apiKey = apiKey;\n    this.timeoutMs = options.timeoutMs ?? 15000;\n  }\n\n  /**\n   * Create a payment intent. Returns the payment object including\n   * `id`, `status`, and `checkout_url`.\n   *\n   * Reusing the same `invoice_id` returns the existing payment instead of\n   * creating a duplicate, so retries are safe. Supply `success_url`/`cancel_url`\n   * to return the customer to your site after checkout.\n   */\n  async createPayment(params: CreatePaymentParams): Promise<Payment> {\n    return this.request<Payment>('POST', '/api/v1/payments', params);\n  }\n\n  /**\n   * Retrieve a payment by its reference ID.\n   */\n  async getPayment(paymentId: string): Promise<Payment> {\n    return this.request<Payment>('GET', `/api/v1/payments/${encodeURIComponent(paymentId)}`);\n  }\n\n  /**\n   * List payments, newest first.\n   */\n  async listPayments(params: ListPaymentsParams = {}): Promise<Payment[]> {\n    const stringParams: Record<string, string> = {};\n    for (const [key, value] of Object.entries(params)) {\n      if (value !== undefined) {\n        stringParams[key] = String(value);\n      }\n    }\n    const query = new URLSearchParams(stringParams).toString();\n    return this.request<Payment[]>('GET', `/api/v1/payments${query ? `?${query}` : ''}`);\n  }\n\n  /**\n   * Find the most recent payment for one of your invoice IDs, or null if none exist.\n   */\n  async findByInvoiceId(invoiceId: string): Promise<Payment | null> {\n    const payments = await this.listPayments({ invoice_id: invoiceId });\n    return payments[0] ?? null;\n  }\n\n  /**\n   * Helper to perform HTTP request to Fastaar API.\n   */\n  private async request<T>(method: string, path: string, body?: any): Promise<T> {\n    let response: Response;\n\n    try {\n      response = await fetch(API_BASE_URL + path, {\n        method,\n        headers: {\n          Authorization: `Bearer ${this.apiKey}`,\n          Accept: 'application/json',\n          ...(body ? { 'Content-Type': 'application/json' } : {}),\n        },\n        body: body ? JSON.stringify(body) : undefined,\n        signal: AbortSignal.timeout(this.timeoutMs),\n      });\n    } catch (error: any) {\n      throw new FastaarError(`Could not reach the Fastaar API: ${error.message}`, 'connection_error');\n    }\n\n    const payload = await response.json().catch(() => null);\n\n    if (!response.ok || payload === null) {\n      throw new FastaarError(\n        payload?.error?.message ?? `Fastaar API returned HTTP ${response.status}.`,\n        payload?.error?.type ?? 'api_error',\n        response.status,\n      );\n    }\n\n    return (payload.data ?? payload) as T;\n  }\n}\n\n// Global caching pattern for Next.js hot-reloading\nconst globalForFastaar = globalThis as unknown as {\n  fastaarClient?: FastaarClient;\n};\n\n/**\n * Retrieves a cached singleton instance of FastaarClient initialized with\n * environment variables (FASTAAR_API_KEY, FASTAAR_TIMEOUT_MS).\n * Useful in Next.js API route handlers, Server Actions, and Server Components.\n */\nexport function getFastaarClient(): FastaarClient {\n  if (!globalForFastaar.fastaarClient) {\n    const apiKey = process.env.FASTAAR_API_KEY;\n    if (!apiKey) {\n      throw new FastaarError(\n        'FASTAAR_API_KEY environment variable is not defined.',\n        'authentication_error'\n      );\n    }\n\n    const timeoutMs = process.env.FASTAAR_TIMEOUT_MS\n      ? parseInt(process.env.FASTAAR_TIMEOUT_MS, 10)\n      : undefined;\n\n    globalForFastaar.fastaarClient = new FastaarClient(apiKey, { timeoutMs });\n  }\n\n  return globalForFastaar.fastaarClient;\n}\n"],"mappings":"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","names":[]}

package/dist/client.d.cts

@@ -0,0 +1,61 @@
+import { FastaarClientOptions, CreatePaymentParams, Payment, ListPaymentsParams } from './types.cjs';
+
+/**
+ * Custom error class for Fastaar API errors.
+ */
+declare class FastaarError extends Error {
+    /**
+     * The type of the error returned by the API (e.g. 'authentication_error', 'validation_error').
+     */
+    errorType: string;
+    /**
+     * The HTTP status code returned by the API.
+     */
+    statusCode: number;
+    constructor(message: string, errorType?: string, statusCode?: number);
+}
+/**
+ * Client for interacting with the Fastaar Payment Gateway API.
+ */
+declare class FastaarClient {
+    private apiKey;
+    private timeoutMs;
+    /**
+     * @param apiKey Your Fastaar API Key (fk_live_... or fk_test_...)
+     * @param options Client configuration options
+     */
+    constructor(apiKey: string, options?: FastaarClientOptions);
+    /**
+     * Create a payment intent. Returns the payment object including
+     * `id`, `status`, and `checkout_url`.
+     *
+     * Reusing the same `invoice_id` returns the existing payment instead of
+     * creating a duplicate, so retries are safe. Supply `success_url`/`cancel_url`
+     * to return the customer to your site after checkout.
+     */
+    createPayment(params: CreatePaymentParams): Promise<Payment>;
+    /**
+     * Retrieve a payment by its reference ID.
+     */
+    getPayment(paymentId: string): Promise<Payment>;
+    /**
+     * List payments, newest first.
+     */
+    listPayments(params?: ListPaymentsParams): Promise<Payment[]>;
+    /**
+     * Find the most recent payment for one of your invoice IDs, or null if none exist.
+     */
+    findByInvoiceId(invoiceId: string): Promise<Payment | null>;
+    /**
+     * Helper to perform HTTP request to Fastaar API.
+     */
+    private request;
+}
+/**
+ * Retrieves a cached singleton instance of FastaarClient initialized with
+ * environment variables (FASTAAR_API_KEY, FASTAAR_TIMEOUT_MS).
+ * Useful in Next.js API route handlers, Server Actions, and Server Components.
+ */
+declare function getFastaarClient(): FastaarClient;
+
+export { FastaarClient, FastaarError, getFastaarClient };

package/dist/client.d.ts

@@ -0,0 +1,61 @@
+import { FastaarClientOptions, CreatePaymentParams, Payment, ListPaymentsParams } from './types.js';
+
+/**
+ * Custom error class for Fastaar API errors.
+ */
+declare class FastaarError extends Error {
+    /**
+     * The type of the error returned by the API (e.g. 'authentication_error', 'validation_error').
+     */
+    errorType: string;
+    /**
+     * The HTTP status code returned by the API.
+     */
+    statusCode: number;
+    constructor(message: string, errorType?: string, statusCode?: number);
+}
+/**
+ * Client for interacting with the Fastaar Payment Gateway API.
+ */
+declare class FastaarClient {
+    private apiKey;
+    private timeoutMs;
+    /**
+     * @param apiKey Your Fastaar API Key (fk_live_... or fk_test_...)
+     * @param options Client configuration options
+     */
+    constructor(apiKey: string, options?: FastaarClientOptions);
+    /**
+     * Create a payment intent. Returns the payment object including
+     * `id`, `status`, and `checkout_url`.
+     *
+     * Reusing the same `invoice_id` returns the existing payment instead of
+     * creating a duplicate, so retries are safe. Supply `success_url`/`cancel_url`
+     * to return the customer to your site after checkout.
+     */
+    createPayment(params: CreatePaymentParams): Promise<Payment>;
+    /**
+     * Retrieve a payment by its reference ID.
+     */
+    getPayment(paymentId: string): Promise<Payment>;
+    /**
+     * List payments, newest first.
+     */
+    listPayments(params?: ListPaymentsParams): Promise<Payment[]>;
+    /**
+     * Find the most recent payment for one of your invoice IDs, or null if none exist.
+     */
+    findByInvoiceId(invoiceId: string): Promise<Payment | null>;
+    /**
+     * Helper to perform HTTP request to Fastaar API.
+     */
+    private request;
+}
+/**
+ * Retrieves a cached singleton instance of FastaarClient initialized with
+ * environment variables (FASTAAR_API_KEY, FASTAAR_TIMEOUT_MS).
+ * Useful in Next.js API route handlers, Server Actions, and Server Components.
+ */
+declare function getFastaarClient(): FastaarClient;
+
+export { FastaarClient, FastaarError, getFastaarClient };

package/dist/client.js

@@ -0,0 +1,119 @@
+const API_BASE_URL = "https://fastaar.com";
+class FastaarError extends Error {
+  /**
+   * The type of the error returned by the API (e.g. 'authentication_error', 'validation_error').
+   */
+  errorType;
+  /**
+   * The HTTP status code returned by the API.
+   */
+  statusCode;
+  constructor(message, errorType = "api_error", statusCode = 0) {
+    super(message);
+    this.name = "FastaarError";
+    this.errorType = errorType;
+    this.statusCode = statusCode;
+  }
+}
+class FastaarClient {
+  apiKey;
+  timeoutMs;
+  /**
+   * @param apiKey Your Fastaar API Key (fk_live_... or fk_test_...)
+   * @param options Client configuration options
+   */
+  constructor(apiKey, options = {}) {
+    if (!apiKey) {
+      throw new FastaarError("API key is required to initialize FastaarClient.", "authentication_error");
+    }
+    this.apiKey = apiKey;
+    this.timeoutMs = options.timeoutMs ?? 15e3;
+  }
+  /**
+   * Create a payment intent. Returns the payment object including
+   * `id`, `status`, and `checkout_url`.
+   *
+   * Reusing the same `invoice_id` returns the existing payment instead of
+   * creating a duplicate, so retries are safe. Supply `success_url`/`cancel_url`
+   * to return the customer to your site after checkout.
+   */
+  async createPayment(params) {
+    return this.request("POST", "/api/v1/payments", params);
+  }
+  /**
+   * Retrieve a payment by its reference ID.
+   */
+  async getPayment(paymentId) {
+    return this.request("GET", `/api/v1/payments/${encodeURIComponent(paymentId)}`);
+  }
+  /**
+   * List payments, newest first.
+   */
+  async listPayments(params = {}) {
+    const stringParams = {};
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== void 0) {
+        stringParams[key] = String(value);
+      }
+    }
+    const query = new URLSearchParams(stringParams).toString();
+    return this.request("GET", `/api/v1/payments${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Find the most recent payment for one of your invoice IDs, or null if none exist.
+   */
+  async findByInvoiceId(invoiceId) {
+    const payments = await this.listPayments({ invoice_id: invoiceId });
+    return payments[0] ?? null;
+  }
+  /**
+   * Helper to perform HTTP request to Fastaar API.
+   */
+  async request(method, path, body) {
+    let response;
+    try {
+      response = await fetch(API_BASE_URL + path, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          Accept: "application/json",
+          ...body ? { "Content-Type": "application/json" } : {}
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+    } catch (error) {
+      throw new FastaarError(`Could not reach the Fastaar API: ${error.message}`, "connection_error");
+    }
+    const payload = await response.json().catch(() => null);
+    if (!response.ok || payload === null) {
+      throw new FastaarError(
+        payload?.error?.message ?? `Fastaar API returned HTTP ${response.status}.`,
+        payload?.error?.type ?? "api_error",
+        response.status
+      );
+    }
+    return payload.data ?? payload;
+  }
+}
+const globalForFastaar = globalThis;
+function getFastaarClient() {
+  if (!globalForFastaar.fastaarClient) {
+    const apiKey = process.env.FASTAAR_API_KEY;
+    if (!apiKey) {
+      throw new FastaarError(
+        "FASTAAR_API_KEY environment variable is not defined.",
+        "authentication_error"
+      );
+    }
+    const timeoutMs = process.env.FASTAAR_TIMEOUT_MS ? parseInt(process.env.FASTAAR_TIMEOUT_MS, 10) : void 0;
+    globalForFastaar.fastaarClient = new FastaarClient(apiKey, { timeoutMs });
+  }
+  return globalForFastaar.fastaarClient;
+}
+export {
+  FastaarClient,
+  FastaarError,
+  getFastaarClient
+};
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import { CreatePaymentParams, FastaarClientOptions, ListPaymentsParams, Payment } from './types';\n\nconst API_BASE_URL = 'https://fastaar.com';\n\n/**\n * Custom error class for Fastaar API errors.\n */\nexport class FastaarError extends Error {\n  /**\n   * The type of the error returned by the API (e.g. 'authentication_error', 'validation_error').\n   */\n  errorType: string;\n\n  /**\n   * The HTTP status code returned by the API.\n   */\n  statusCode: number;\n\n  constructor(message: string, errorType = 'api_error', statusCode = 0) {\n    super(message);\n    this.name = 'FastaarError';\n    this.errorType = errorType;\n    this.statusCode = statusCode;\n  }\n}\n\n/**\n * Client for interacting with the Fastaar Payment Gateway API.\n */\nexport class FastaarClient {\n  private apiKey: string;\n  private timeoutMs: number;\n\n  /**\n   * @param apiKey Your Fastaar API Key (fk_live_... or fk_test_...)\n   * @param options Client configuration options\n   */\n  constructor(apiKey: string, options: FastaarClientOptions = {}) {\n    if (!apiKey) {\n      throw new FastaarError('API key is required to initialize FastaarClient.', 'authentication_error');\n    }\n    this.apiKey = apiKey;\n    this.timeoutMs = options.timeoutMs ?? 15000;\n  }\n\n  /**\n   * Create a payment intent. Returns the payment object including\n   * `id`, `status`, and `checkout_url`.\n   *\n   * Reusing the same `invoice_id` returns the existing payment instead of\n   * creating a duplicate, so retries are safe. Supply `success_url`/`cancel_url`\n   * to return the customer to your site after checkout.\n   */\n  async createPayment(params: CreatePaymentParams): Promise<Payment> {\n    return this.request<Payment>('POST', '/api/v1/payments', params);\n  }\n\n  /**\n   * Retrieve a payment by its reference ID.\n   */\n  async getPayment(paymentId: string): Promise<Payment> {\n    return this.request<Payment>('GET', `/api/v1/payments/${encodeURIComponent(paymentId)}`);\n  }\n\n  /**\n   * List payments, newest first.\n   */\n  async listPayments(params: ListPaymentsParams = {}): Promise<Payment[]> {\n    const stringParams: Record<string, string> = {};\n    for (const [key, value] of Object.entries(params)) {\n      if (value !== undefined) {\n        stringParams[key] = String(value);\n      }\n    }\n    const query = new URLSearchParams(stringParams).toString();\n    return this.request<Payment[]>('GET', `/api/v1/payments${query ? `?${query}` : ''}`);\n  }\n\n  /**\n   * Find the most recent payment for one of your invoice IDs, or null if none exist.\n   */\n  async findByInvoiceId(invoiceId: string): Promise<Payment | null> {\n    const payments = await this.listPayments({ invoice_id: invoiceId });\n    return payments[0] ?? null;\n  }\n\n  /**\n   * Helper to perform HTTP request to Fastaar API.\n   */\n  private async request<T>(method: string, path: string, body?: any): Promise<T> {\n    let response: Response;\n\n    try {\n      response = await fetch(API_BASE_URL + path, {\n        method,\n        headers: {\n          Authorization: `Bearer ${this.apiKey}`,\n          Accept: 'application/json',\n          ...(body ? { 'Content-Type': 'application/json' } : {}),\n        },\n        body: body ? JSON.stringify(body) : undefined,\n        signal: AbortSignal.timeout(this.timeoutMs),\n      });\n    } catch (error: any) {\n      throw new FastaarError(`Could not reach the Fastaar API: ${error.message}`, 'connection_error');\n    }\n\n    const payload = await response.json().catch(() => null);\n\n    if (!response.ok || payload === null) {\n      throw new FastaarError(\n        payload?.error?.message ?? `Fastaar API returned HTTP ${response.status}.`,\n        payload?.error?.type ?? 'api_error',\n        response.status,\n      );\n    }\n\n    return (payload.data ?? payload) as T;\n  }\n}\n\n// Global caching pattern for Next.js hot-reloading\nconst globalForFastaar = globalThis as unknown as {\n  fastaarClient?: FastaarClient;\n};\n\n/**\n * Retrieves a cached singleton instance of FastaarClient initialized with\n * environment variables (FASTAAR_API_KEY, FASTAAR_TIMEOUT_MS).\n * Useful in Next.js API route handlers, Server Actions, and Server Components.\n */\nexport function getFastaarClient(): FastaarClient {\n  if (!globalForFastaar.fastaarClient) {\n    const apiKey = process.env.FASTAAR_API_KEY;\n    if (!apiKey) {\n      throw new FastaarError(\n        'FASTAAR_API_KEY environment variable is not defined.',\n        'authentication_error'\n      );\n    }\n\n    const timeoutMs = process.env.FASTAAR_TIMEOUT_MS\n      ? parseInt(process.env.FASTAAR_TIMEOUT_MS, 10)\n      : undefined;\n\n    globalForFastaar.fastaarClient = new FastaarClient(apiKey, { timeoutMs });\n  }\n\n  return globalForFastaar.fastaarClient;\n}\n"],"mappings":"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","names":[]}