@fastaar/nextjs 0.1.2 → 0.1.4

package/README.md

@@ -32,6 +32,10 @@ FASTAAR_API_KEY="fk_live_..."
 FASTAAR_WEBHOOK_SECRET="whsec_..."
 ```
 
+Keys are scoped to abilities (`payments:read`/`write`/`refund`, `customers:read`/`write`) and can have an
+expiry date, set in the merchant panel. Calls outside the key's abilities return `403 ability_denied`;
+calls with an expired key return `401 authentication_error`.
+
 ---
 
 ## Usage
@@ -86,6 +90,7 @@ export default function CheckoutPage() {
     const payment = await fastaar.createPayment({
       amount: 1250,
       invoice_number: 'ORDER-42',
+      customer_id: customer?.id, // optional — attach an existing customer
       success_url: 'https://your-site.com/thanks',
       cancel_url: 'https://your-site.com/cart',
     });
@@ -164,6 +169,11 @@ import { getFastaarClient } from '@fastaar/nextjs';
 const fastaar = getFastaarClient();
 const payment = await fastaar.refundPayment('01jxyz...');
 // payment.status === 'refunded'
+
+const partial = await fastaar.refundPayment('01jxyz...', 200); // refund only part of it
+// partial.status === 'partially_refunded'
+
+const refunds = await fastaar.listRefunds('01jxyz...'); // full refund history, newest first
 ```
 
 ### 6. Customers

package/dist/client.cjs

@@ -61,9 +61,11 @@ class FastaarClient {
    * Create a payment intent. Returns the payment object including
    * `id`, `status`, and `checkout_url`.
    *
-   * Reusing the same `invoice_number` 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.
+   * Reusing the same `invoice_number` while a previous payment for it is still
+   * active (not `failed`/`expired`) throws a FastaarError with errorType
+   * `duplicate_invoice_number` (HTTP 409) instead of creating a duplicate — look
+   * the existing payment up with `findByInvoiceNumber()` rather than retrying blindly.
+   * 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);
@@ -95,13 +97,28 @@ class FastaarClient {
     return payments[0] ?? null;
   }
   /**
-   * Refund a completed payment. Only payments with status `completed` can be refunded.
+   * Refund a payment, in full or in part. Only payments with status `completed` or
+   * `partially_refunded` can be refunded. Pass an amount to refund only part of the
+   * remaining balance; omit it to refund whatever is still refundable.
    *
-   * @returns The updated payment object with status `refunded`.
-   * @throws FastaarError if the payment is not in a refundable state.
+   * @returns The updated payment object. `status` is `refunded` once fully refunded,
+   * or `partially_refunded` if some balance remains.
+   * @throws FastaarError if the payment is not in a refundable state, or the amount
+   * exceeds the remaining refundable balance.
    */
-  async refundPayment(paymentId) {
-    return this.request("POST", `/api/v1/payments/${encodeURIComponent(paymentId)}/refund`);
+  async refundPayment(paymentId, amount) {
+    return this.request(
+      "POST",
+      `/api/v1/payments/${encodeURIComponent(paymentId)}/refund`,
+      amount !== void 0 ? { amount } : void 0
+    );
+  }
+  /**
+   * List a payment's refund history, newest first — one entry per refund call, even
+   * across several partial refunds.
+   */
+  async listRefunds(paymentId) {
+    return this.request("GET", `/api/v1/payments/${encodeURIComponent(paymentId)}/refunds`);
   }
   // ---------------------------------------------------------------------------
   // Customers

package/dist/client.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import {\n  CreateCustomerParams,\n  CreatePaymentParams,\n  Customer,\n  CustomerParams,\n  FastaarClientOptions,\n  ListCustomersParams,\n  ListPaymentsParams,\n  Payment,\n} 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  // Payments\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_number` 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 numbers, or null if none exist.\n   */\n  async findByInvoiceNumber(invoiceNumber: string): Promise<Payment | null> {\n    const payments = await this.listPayments({ invoice_number: invoiceNumber });\n    return payments[0] ?? null;\n  }\n\n  /**\n   * Refund a completed payment. Only payments with status `completed` can be refunded.\n   *\n   * @returns The updated payment object with status `refunded`.\n   * @throws FastaarError if the payment is not in a refundable state.\n   */\n  async refundPayment(paymentId: string): Promise<Payment> {\n    return this.request<Payment>('POST', `/api/v1/payments/${encodeURIComponent(paymentId)}/refund`);\n  }\n\n  // ---------------------------------------------------------------------------\n  // Customers\n  // ---------------------------------------------------------------------------\n\n  async listCustomers(params: ListCustomersParams = {}): Promise<Customer[]> {\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<Customer[]>('GET', `/api/v1/customers${query ? `?${query}` : ''}`);\n  }\n\n  async createCustomer(params: CreateCustomerParams): Promise<Customer> {\n    return this.request<Customer>('POST', '/api/v1/customers', params);\n  }\n\n  async getCustomer(customerId: number): Promise<Customer> {\n    return this.request<Customer>('GET', `/api/v1/customers/${customerId}`);\n  }\n\n  async updateCustomer(customerId: number, params: CustomerParams): Promise<Customer> {\n    return this.request<Customer>('PATCH', `/api/v1/customers/${customerId}`, params);\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":[]}
+{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import {\n  CreateCustomerParams,\n  CreatePaymentParams,\n  Customer,\n  CustomerParams,\n  FastaarClientOptions,\n  ListCustomersParams,\n  ListPaymentsParams,\n  Payment,\n  Refund,\n} 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  // Payments\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_number` while a previous payment for it is still\n   * active (not `failed`/`expired`) throws a FastaarError with errorType\n   * `duplicate_invoice_number` (HTTP 409) instead of creating a duplicate — look\n   * the existing payment up with `findByInvoiceNumber()` rather than retrying blindly.\n   * Supply `success_url`/`cancel_url` 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 numbers, or null if none exist.\n   */\n  async findByInvoiceNumber(invoiceNumber: string): Promise<Payment | null> {\n    const payments = await this.listPayments({ invoice_number: invoiceNumber });\n    return payments[0] ?? null;\n  }\n\n  /**\n   * Refund a payment, in full or in part. Only payments with status `completed` or\n   * `partially_refunded` can be refunded. Pass an amount to refund only part of the\n   * remaining balance; omit it to refund whatever is still refundable.\n   *\n   * @returns The updated payment object. `status` is `refunded` once fully refunded,\n   * or `partially_refunded` if some balance remains.\n   * @throws FastaarError if the payment is not in a refundable state, or the amount\n   * exceeds the remaining refundable balance.\n   */\n  async refundPayment(paymentId: string, amount?: number | string): Promise<Payment> {\n    return this.request<Payment>(\n      'POST',\n      `/api/v1/payments/${encodeURIComponent(paymentId)}/refund`,\n      amount !== undefined ? { amount } : undefined,\n    );\n  }\n\n  /**\n   * List a payment's refund history, newest first — one entry per refund call, even\n   * across several partial refunds.\n   */\n  async listRefunds(paymentId: string): Promise<Refund[]> {\n    return this.request<Refund[]>('GET', `/api/v1/payments/${encodeURIComponent(paymentId)}/refunds`);\n  }\n\n  // ---------------------------------------------------------------------------\n  // Customers\n  // ---------------------------------------------------------------------------\n\n  async listCustomers(params: ListCustomersParams = {}): Promise<Customer[]> {\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<Customer[]>('GET', `/api/v1/customers${query ? `?${query}` : ''}`);\n  }\n\n  async createCustomer(params: CreateCustomerParams): Promise<Customer> {\n    return this.request<Customer>('POST', '/api/v1/customers', params);\n  }\n\n  async getCustomer(customerId: number): Promise<Customer> {\n    return this.request<Customer>('GET', `/api/v1/customers/${customerId}`);\n  }\n\n  async updateCustomer(customerId: number, params: CustomerParams): Promise<Customer> {\n    return this.request<Customer>('PATCH', `/api/v1/customers/${customerId}`, params);\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

@@ -1,4 +1,4 @@
-import { FastaarClientOptions, CreatePaymentParams, Payment, ListPaymentsParams, ListCustomersParams, Customer, CreateCustomerParams, CustomerParams } from './types.cjs';
+import { FastaarClientOptions, CreatePaymentParams, Payment, ListPaymentsParams, Refund, ListCustomersParams, Customer, CreateCustomerParams, CustomerParams } from './types.cjs';
 
 /**
  * Custom error class for Fastaar API errors.
@@ -29,9 +29,11 @@ declare class FastaarClient {
      * Create a payment intent. Returns the payment object including
      * `id`, `status`, and `checkout_url`.
      *
-     * Reusing the same `invoice_number` 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.
+     * Reusing the same `invoice_number` while a previous payment for it is still
+     * active (not `failed`/`expired`) throws a FastaarError with errorType
+     * `duplicate_invoice_number` (HTTP 409) instead of creating a duplicate — look
+     * the existing payment up with `findByInvoiceNumber()` rather than retrying blindly.
+     * Supply `success_url`/`cancel_url` to return the customer to your site after checkout.
      */
     createPayment(params: CreatePaymentParams): Promise<Payment>;
     /**
@@ -47,12 +49,21 @@ declare class FastaarClient {
      */
     findByInvoiceNumber(invoiceNumber: string): Promise<Payment | null>;
     /**
-     * Refund a completed payment. Only payments with status `completed` can be refunded.
+     * Refund a payment, in full or in part. Only payments with status `completed` or
+     * `partially_refunded` can be refunded. Pass an amount to refund only part of the
+     * remaining balance; omit it to refund whatever is still refundable.
      *
-     * @returns The updated payment object with status `refunded`.
-     * @throws FastaarError if the payment is not in a refundable state.
+     * @returns The updated payment object. `status` is `refunded` once fully refunded,
+     * or `partially_refunded` if some balance remains.
+     * @throws FastaarError if the payment is not in a refundable state, or the amount
+     * exceeds the remaining refundable balance.
      */
-    refundPayment(paymentId: string): Promise<Payment>;
+    refundPayment(paymentId: string, amount?: number | string): Promise<Payment>;
+    /**
+     * List a payment's refund history, newest first — one entry per refund call, even
+     * across several partial refunds.
+     */
+    listRefunds(paymentId: string): Promise<Refund[]>;
     listCustomers(params?: ListCustomersParams): Promise<Customer[]>;
     createCustomer(params: CreateCustomerParams): Promise<Customer>;
     getCustomer(customerId: number): Promise<Customer>;

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { FastaarClientOptions, CreatePaymentParams, Payment, ListPaymentsParams, ListCustomersParams, Customer, CreateCustomerParams, CustomerParams } from './types.js';
+import { FastaarClientOptions, CreatePaymentParams, Payment, ListPaymentsParams, Refund, ListCustomersParams, Customer, CreateCustomerParams, CustomerParams } from './types.js';
 
 /**
  * Custom error class for Fastaar API errors.
@@ -29,9 +29,11 @@ declare class FastaarClient {
      * Create a payment intent. Returns the payment object including
      * `id`, `status`, and `checkout_url`.
      *
-     * Reusing the same `invoice_number` 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.
+     * Reusing the same `invoice_number` while a previous payment for it is still
+     * active (not `failed`/`expired`) throws a FastaarError with errorType
+     * `duplicate_invoice_number` (HTTP 409) instead of creating a duplicate — look
+     * the existing payment up with `findByInvoiceNumber()` rather than retrying blindly.
+     * Supply `success_url`/`cancel_url` to return the customer to your site after checkout.
      */
     createPayment(params: CreatePaymentParams): Promise<Payment>;
     /**
@@ -47,12 +49,21 @@ declare class FastaarClient {
      */
     findByInvoiceNumber(invoiceNumber: string): Promise<Payment | null>;
     /**
-     * Refund a completed payment. Only payments with status `completed` can be refunded.
+     * Refund a payment, in full or in part. Only payments with status `completed` or
+     * `partially_refunded` can be refunded. Pass an amount to refund only part of the
+     * remaining balance; omit it to refund whatever is still refundable.
      *
-     * @returns The updated payment object with status `refunded`.
-     * @throws FastaarError if the payment is not in a refundable state.
+     * @returns The updated payment object. `status` is `refunded` once fully refunded,
+     * or `partially_refunded` if some balance remains.
+     * @throws FastaarError if the payment is not in a refundable state, or the amount
+     * exceeds the remaining refundable balance.
      */
-    refundPayment(paymentId: string): Promise<Payment>;
+    refundPayment(paymentId: string, amount?: number | string): Promise<Payment>;
+    /**
+     * List a payment's refund history, newest first — one entry per refund call, even
+     * across several partial refunds.
+     */
+    listRefunds(paymentId: string): Promise<Refund[]>;
     listCustomers(params?: ListCustomersParams): Promise<Customer[]>;
     createCustomer(params: CreateCustomerParams): Promise<Customer>;
     getCustomer(customerId: number): Promise<Customer>;

package/dist/client.js

@@ -36,9 +36,11 @@ class FastaarClient {
    * Create a payment intent. Returns the payment object including
    * `id`, `status`, and `checkout_url`.
    *
-   * Reusing the same `invoice_number` 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.
+   * Reusing the same `invoice_number` while a previous payment for it is still
+   * active (not `failed`/`expired`) throws a FastaarError with errorType
+   * `duplicate_invoice_number` (HTTP 409) instead of creating a duplicate — look
+   * the existing payment up with `findByInvoiceNumber()` rather than retrying blindly.
+   * 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);
@@ -70,13 +72,28 @@ class FastaarClient {
     return payments[0] ?? null;
   }
   /**
-   * Refund a completed payment. Only payments with status `completed` can be refunded.
+   * Refund a payment, in full or in part. Only payments with status `completed` or
+   * `partially_refunded` can be refunded. Pass an amount to refund only part of the
+   * remaining balance; omit it to refund whatever is still refundable.
    *
-   * @returns The updated payment object with status `refunded`.
-   * @throws FastaarError if the payment is not in a refundable state.
+   * @returns The updated payment object. `status` is `refunded` once fully refunded,
+   * or `partially_refunded` if some balance remains.
+   * @throws FastaarError if the payment is not in a refundable state, or the amount
+   * exceeds the remaining refundable balance.
    */
-  async refundPayment(paymentId) {
-    return this.request("POST", `/api/v1/payments/${encodeURIComponent(paymentId)}/refund`);
+  async refundPayment(paymentId, amount) {
+    return this.request(
+      "POST",
+      `/api/v1/payments/${encodeURIComponent(paymentId)}/refund`,
+      amount !== void 0 ? { amount } : void 0
+    );
+  }
+  /**
+   * List a payment's refund history, newest first — one entry per refund call, even
+   * across several partial refunds.
+   */
+  async listRefunds(paymentId) {
+    return this.request("GET", `/api/v1/payments/${encodeURIComponent(paymentId)}/refunds`);
   }
   // ---------------------------------------------------------------------------
   // Customers

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import {\n  CreateCustomerParams,\n  CreatePaymentParams,\n  Customer,\n  CustomerParams,\n  FastaarClientOptions,\n  ListCustomersParams,\n  ListPaymentsParams,\n  Payment,\n} 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  // Payments\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_number` 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 numbers, or null if none exist.\n   */\n  async findByInvoiceNumber(invoiceNumber: string): Promise<Payment | null> {\n    const payments = await this.listPayments({ invoice_number: invoiceNumber });\n    return payments[0] ?? null;\n  }\n\n  /**\n   * Refund a completed payment. Only payments with status `completed` can be refunded.\n   *\n   * @returns The updated payment object with status `refunded`.\n   * @throws FastaarError if the payment is not in a refundable state.\n   */\n  async refundPayment(paymentId: string): Promise<Payment> {\n    return this.request<Payment>('POST', `/api/v1/payments/${encodeURIComponent(paymentId)}/refund`);\n  }\n\n  // ---------------------------------------------------------------------------\n  // Customers\n  // ---------------------------------------------------------------------------\n\n  async listCustomers(params: ListCustomersParams = {}): Promise<Customer[]> {\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<Customer[]>('GET', `/api/v1/customers${query ? `?${query}` : ''}`);\n  }\n\n  async createCustomer(params: CreateCustomerParams): Promise<Customer> {\n    return this.request<Customer>('POST', '/api/v1/customers', params);\n  }\n\n  async getCustomer(customerId: number): Promise<Customer> {\n    return this.request<Customer>('GET', `/api/v1/customers/${customerId}`);\n  }\n\n  async updateCustomer(customerId: number, params: CustomerParams): Promise<Customer> {\n    return this.request<Customer>('PATCH', `/api/v1/customers/${customerId}`, params);\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":[]}
+{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import {\n  CreateCustomerParams,\n  CreatePaymentParams,\n  Customer,\n  CustomerParams,\n  FastaarClientOptions,\n  ListCustomersParams,\n  ListPaymentsParams,\n  Payment,\n  Refund,\n} 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  // Payments\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_number` while a previous payment for it is still\n   * active (not `failed`/`expired`) throws a FastaarError with errorType\n   * `duplicate_invoice_number` (HTTP 409) instead of creating a duplicate — look\n   * the existing payment up with `findByInvoiceNumber()` rather than retrying blindly.\n   * Supply `success_url`/`cancel_url` 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 numbers, or null if none exist.\n   */\n  async findByInvoiceNumber(invoiceNumber: string): Promise<Payment | null> {\n    const payments = await this.listPayments({ invoice_number: invoiceNumber });\n    return payments[0] ?? null;\n  }\n\n  /**\n   * Refund a payment, in full or in part. Only payments with status `completed` or\n   * `partially_refunded` can be refunded. Pass an amount to refund only part of the\n   * remaining balance; omit it to refund whatever is still refundable.\n   *\n   * @returns The updated payment object. `status` is `refunded` once fully refunded,\n   * or `partially_refunded` if some balance remains.\n   * @throws FastaarError if the payment is not in a refundable state, or the amount\n   * exceeds the remaining refundable balance.\n   */\n  async refundPayment(paymentId: string, amount?: number | string): Promise<Payment> {\n    return this.request<Payment>(\n      'POST',\n      `/api/v1/payments/${encodeURIComponent(paymentId)}/refund`,\n      amount !== undefined ? { amount } : undefined,\n    );\n  }\n\n  /**\n   * List a payment's refund history, newest first — one entry per refund call, even\n   * across several partial refunds.\n   */\n  async listRefunds(paymentId: string): Promise<Refund[]> {\n    return this.request<Refund[]>('GET', `/api/v1/payments/${encodeURIComponent(paymentId)}/refunds`);\n  }\n\n  // ---------------------------------------------------------------------------\n  // Customers\n  // ---------------------------------------------------------------------------\n\n  async listCustomers(params: ListCustomersParams = {}): Promise<Customer[]> {\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<Customer[]>('GET', `/api/v1/customers${query ? `?${query}` : ''}`);\n  }\n\n  async createCustomer(params: CreateCustomerParams): Promise<Customer> {\n    return this.request<Customer>('POST', '/api/v1/customers', params);\n  }\n\n  async getCustomer(customerId: number): Promise<Customer> {\n    return this.request<Customer>('GET', `/api/v1/customers/${customerId}`);\n  }\n\n  async updateCustomer(customerId: number, params: CustomerParams): Promise<Customer> {\n    return this.request<Customer>('PATCH', `/api/v1/customers/${customerId}`, params);\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/index.d.cts

@@ -1,4 +1,4 @@
-export { CreateCustomerParams, CreatePaymentParams, Customer, CustomerParams, FastaarClientOptions, ListCustomersParams, ListPaymentsParams, Payment, WebhookEvent } from './types.cjs';
+export { CreateCustomerParams, CreatePaymentParams, Customer, CustomerParams, FastaarClientOptions, ListCustomersParams, ListPaymentsParams, Payment, Refund, WebhookEvent } from './types.cjs';
 export { FastaarClient, FastaarError, getFastaarClient } from './client.cjs';
 export { verifyNextWebhook, verifyWebhookSignature } from './webhook.cjs';
 export { createCheckoutRedirect } from './actions.cjs';

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { CreateCustomerParams, CreatePaymentParams, Customer, CustomerParams, FastaarClientOptions, ListCustomersParams, ListPaymentsParams, Payment, WebhookEvent } from './types.js';
+export { CreateCustomerParams, CreatePaymentParams, Customer, CustomerParams, FastaarClientOptions, ListCustomersParams, ListPaymentsParams, Payment, Refund, WebhookEvent } from './types.js';
 export { FastaarClient, FastaarError, getFastaarClient } from './client.js';
 export { verifyNextWebhook, verifyWebhookSignature } from './webhook.js';
 export { createCheckoutRedirect } from './actions.js';

package/dist/types.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * Configuration options for the Fastaar client.\n */\nexport interface FastaarClientOptions {\n  /**\n   * Timeout in milliseconds for API requests. Defaults to 15000.\n   */\n  timeoutMs?: number;\n}\n\n/**\n * Parameters for creating a new payment.\n */\nexport interface CreatePaymentParams {\n  /**\n   * The amount to charge (can be a number or string representation of a decimal).\n   */\n  amount: number | string;\n\n  /**\n   * Your order reference / idempotency key.\n   * Retrying with the same invoice_number returns the existing payment instead of creating a duplicate.\n   */\n  invoice_number: string;\n\n  /**\n   * The URL to redirect the customer to upon successful payment completion.\n   */\n  success_url?: string;\n\n  /**\n   * The URL to redirect the customer to if they cancel the checkout process.\n   */\n  cancel_url?: string;\n\n  /**\n   * Arbitrary key-value metadata to attach to the payment.\n   */\n  metadata?: Record<string, string>;\n}\n\n/**\n * Parameters for querying the list of payments.\n */\nexport interface ListPaymentsParams extends Record<string, string | number | undefined> {\n  /**\n   * Filter payments by status (e.g., 'completed', 'pending', 'cancelled').\n   */\n  status?: string;\n\n  /**\n   * Filter payments by your custom invoice/order reference.\n   */\n  invoice_number?: string;\n\n  /**\n   * Number of payments to return per page.\n   */\n  per_page?: number;\n\n  /**\n   * Page number to retrieve (for pagination).\n   */\n  page?: number;\n}\n\n/**\n * Representation of a payment object returned by the Fastaar API.\n */\nexport interface Payment {\n  id: string;\n  amount: string;\n  amount_due: string;\n  gateway_charge: string;\n  gateway_charge_type: 'percentage' | 'fixed' | null;\n  gateway_charge_value: string | null;\n  currency: string;\n  livemode: boolean;\n  source: string;\n  status: string;\n  invoice_number: string;\n  customer_id?: number;\n  provider?: string;\n  payment_method?: string;\n  customer_trx_id?: string;\n  customer_sender_number?: string;\n  metadata?: Record<string, string>;\n  failure_reason?: string;\n  success_url?: string;\n  cancel_url?: string;\n  checkout_url: string;\n  expires_at: string;\n  verified_at?: string;\n  created_at: string;\n}\n\n/**\n * Parameters for updating a customer (all fields optional).\n */\nexport interface CustomerParams {\n  name?: string;\n  phone?: string;\n  email?: string | null;\n  address?: string | null;\n  notes?: string | null;\n}\n\n/**\n * Parameters for creating a customer.\n */\nexport interface CreateCustomerParams {\n  name: string;\n  phone: string;\n  email?: string;\n  address?: string;\n  notes?: string;\n}\n\n/**\n * A customer object returned by the Fastaar API.\n */\nexport interface Customer {\n  id: number;\n  name: string;\n  email?: string;\n  phone: string;\n  address?: string;\n  notes?: string;\n  created_at: string;\n  updated_at: string;\n}\n\n/**\n * Parameters for querying the list of customers.\n */\nexport interface ListCustomersParams extends Record<string, string | number | undefined> {\n  email?: string;\n  phone?: string;\n  per_page?: number;\n  page?: number;\n}\n\n/**\n * Structure of a Fastaar Webhook event request body.\n */\nexport interface WebhookEvent {\n  /**\n   * The type of event (e.g., 'payment.completed').\n   */\n  event: string;\n\n  /**\n   * Indicates whether this event occurred in live mode or test mode.\n   */\n  livemode: boolean;\n\n  /**\n   * The payment object details associated with this event.\n   */\n  data: Payment;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * Configuration options for the Fastaar client.\n */\nexport interface FastaarClientOptions {\n  /**\n   * Timeout in milliseconds for API requests. Defaults to 15000.\n   */\n  timeoutMs?: number;\n}\n\n/**\n * Parameters for creating a new payment.\n */\nexport interface CreatePaymentParams {\n  /**\n   * The amount to charge (can be a number or string representation of a decimal).\n   */\n  amount: number | string;\n\n  /**\n   * Your order reference / idempotency key.\n   * Retrying with the same invoice_number while a previous payment for it is still\n   * active (not `failed`/`expired`) throws a FastaarError with errorType\n   * `duplicate_invoice_number` (HTTP 409) instead of creating a duplicate.\n   */\n  invoice_number: string;\n\n  /**\n   * An existing customer to attach to this payment. Must belong to your merchant account.\n   */\n  customer_id?: number;\n\n  /**\n   * The URL to redirect the customer to upon successful payment completion.\n   */\n  success_url?: string;\n\n  /**\n   * The URL to redirect the customer to if they cancel the checkout process.\n   */\n  cancel_url?: string;\n\n  /**\n   * Arbitrary key-value metadata to attach to the payment.\n   */\n  metadata?: Record<string, string>;\n}\n\n/**\n * Parameters for querying the list of payments.\n */\nexport interface ListPaymentsParams extends Record<string, string | number | undefined> {\n  /**\n   * Filter payments by status (e.g., 'completed', 'pending', 'cancelled').\n   */\n  status?: string;\n\n  /**\n   * Filter payments by your custom invoice/order reference.\n   */\n  invoice_number?: string;\n\n  /**\n   * Number of payments to return per page.\n   */\n  per_page?: number;\n\n  /**\n   * Page number to retrieve (for pagination).\n   */\n  page?: number;\n}\n\n/**\n * Representation of a payment object returned by the Fastaar API.\n */\nexport interface Payment {\n  id: string;\n  amount: string;\n  amount_due: string;\n  refunded_amount: string;\n  gateway_charge: string;\n  gateway_charge_type: 'percentage' | 'fixed' | null;\n  gateway_charge_value: string | null;\n  currency: string;\n  livemode: boolean;\n  source: string;\n  status: string;\n  invoice_number: string;\n  customer_id?: number;\n  provider?: string;\n  payment_method?: string;\n  customer_trx_id?: string;\n  customer_sender_number?: string;\n  metadata?: Record<string, string>;\n  failure_reason?: string;\n  success_url?: string;\n  cancel_url?: string;\n  checkout_url: string;\n  expires_at: string;\n  verified_at?: string;\n  created_at: string;\n}\n\n/**\n * A single refund event on a payment — one per refund call, even across several\n * partial refunds.\n */\nexport interface Refund {\n  id: number;\n  amount: string;\n  source: 'api' | 'panel';\n  created_at: string;\n}\n\n/**\n * Parameters for updating a customer (all fields optional).\n */\nexport interface CustomerParams {\n  name?: string;\n  phone?: string;\n  email?: string | null;\n  address?: string | null;\n  notes?: string | null;\n}\n\n/**\n * Parameters for creating a customer.\n */\nexport interface CreateCustomerParams {\n  name: string;\n  phone: string;\n  email?: string;\n  address?: string;\n  notes?: string;\n}\n\n/**\n * A customer object returned by the Fastaar API.\n */\nexport interface Customer {\n  id: number;\n  name: string;\n  email?: string;\n  phone: string;\n  address?: string;\n  notes?: string;\n  created_at: string;\n  updated_at: string;\n}\n\n/**\n * Parameters for querying the list of customers.\n */\nexport interface ListCustomersParams extends Record<string, string | number | undefined> {\n  email?: string;\n  phone?: string;\n  per_page?: number;\n  page?: number;\n}\n\n/**\n * Structure of a Fastaar Webhook event request body.\n */\nexport interface WebhookEvent {\n  /**\n   * The type of event (e.g., 'payment.completed').\n   */\n  event: string;\n\n  /**\n   * Indicates whether this event occurred in live mode or test mode.\n   */\n  livemode: boolean;\n\n  /**\n   * The payment object details associated with this event.\n   */\n  data: Payment;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/types.d.cts

@@ -17,9 +17,15 @@ interface CreatePaymentParams {
     amount: number | string;
     /**
      * Your order reference / idempotency key.
-     * Retrying with the same invoice_number returns the existing payment instead of creating a duplicate.
+     * Retrying with the same invoice_number while a previous payment for it is still
+     * active (not `failed`/`expired`) throws a FastaarError with errorType
+     * `duplicate_invoice_number` (HTTP 409) instead of creating a duplicate.
      */
     invoice_number: string;
+    /**
+     * An existing customer to attach to this payment. Must belong to your merchant account.
+     */
+    customer_id?: number;
     /**
      * The URL to redirect the customer to upon successful payment completion.
      */
@@ -61,6 +67,7 @@ interface Payment {
     id: string;
     amount: string;
     amount_due: string;
+    refunded_amount: string;
     gateway_charge: string;
     gateway_charge_type: 'percentage' | 'fixed' | null;
     gateway_charge_value: string | null;
@@ -83,6 +90,16 @@ interface Payment {
     verified_at?: string;
     created_at: string;
 }
+/**
+ * A single refund event on a payment — one per refund call, even across several
+ * partial refunds.
+ */
+interface Refund {
+    id: number;
+    amount: string;
+    source: 'api' | 'panel';
+    created_at: string;
+}
 /**
  * Parameters for updating a customer (all fields optional).
  */
@@ -143,4 +160,4 @@ interface WebhookEvent {
     data: Payment;
 }
 
-export type { CreateCustomerParams, CreatePaymentParams, Customer, CustomerParams, FastaarClientOptions, ListCustomersParams, ListPaymentsParams, Payment, WebhookEvent };
+export type { CreateCustomerParams, CreatePaymentParams, Customer, CustomerParams, FastaarClientOptions, ListCustomersParams, ListPaymentsParams, Payment, Refund, WebhookEvent };

package/dist/types.d.ts

@@ -17,9 +17,15 @@ interface CreatePaymentParams {
     amount: number | string;
     /**
      * Your order reference / idempotency key.
-     * Retrying with the same invoice_number returns the existing payment instead of creating a duplicate.
+     * Retrying with the same invoice_number while a previous payment for it is still
+     * active (not `failed`/`expired`) throws a FastaarError with errorType
+     * `duplicate_invoice_number` (HTTP 409) instead of creating a duplicate.
      */
     invoice_number: string;
+    /**
+     * An existing customer to attach to this payment. Must belong to your merchant account.
+     */
+    customer_id?: number;
     /**
      * The URL to redirect the customer to upon successful payment completion.
      */
@@ -61,6 +67,7 @@ interface Payment {
     id: string;
     amount: string;
     amount_due: string;
+    refunded_amount: string;
     gateway_charge: string;
     gateway_charge_type: 'percentage' | 'fixed' | null;
     gateway_charge_value: string | null;
@@ -83,6 +90,16 @@ interface Payment {
     verified_at?: string;
     created_at: string;
 }
+/**
+ * A single refund event on a payment — one per refund call, even across several
+ * partial refunds.
+ */
+interface Refund {
+    id: number;
+    amount: string;
+    source: 'api' | 'panel';
+    created_at: string;
+}
 /**
  * Parameters for updating a customer (all fields optional).
  */
@@ -143,4 +160,4 @@ interface WebhookEvent {
     data: Payment;
 }
 
-export type { CreateCustomerParams, CreatePaymentParams, Customer, CustomerParams, FastaarClientOptions, ListCustomersParams, ListPaymentsParams, Payment, WebhookEvent };
+export type { CreateCustomerParams, CreatePaymentParams, Customer, CustomerParams, FastaarClientOptions, ListCustomersParams, ListPaymentsParams, Payment, Refund, WebhookEvent };

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@fastaar/nextjs",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Next.js React Server Components & Route Handlers integration for Fastaar payment gateway",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fastaar/fastaar-nextjs.git"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",