npm package: @forgehq/payments-sdk
Description: ## Installation
Latest version: 0.0.5

# Forge Payments JS SDK

## Installation

Install the package using your favorite package manager:

### npm

```bash
npm install @forgehq/payments-sdk
```

### yarn

```bash
yarn add @forgehq/payments-sdk
```

### pnpm

```bash
pnpm add @forgehq/payments-sdk
```

## Usage

To initiate a checkout process, import and use the `startCheckout` function. This function takes a `CheckoutDetails` object as an argument, which includes campaign and payment information, as well as the products to be included in the checkout.

Here is an example of how to use it:

```typescript
import { startCheckout, CheckoutDetails } from '@forgehq/payments-sdk';

const checkoutDetails: CheckoutDetails = {
  campaignId: 'your-campaign-id',
  paymentId: 'your-payment-id',
  email: 'customer@example.com',
  userId: 'user-123',
  entries: [
    {
      productId: 'product-a',
      quantity: 1,
    },
    {
      productId: 'product-b',
      quantity: 2,
    },
  ],
};

await startCheckout(checkoutDetails);
```

This will redirect the user to the checkout page to complete their payment.

### `CheckoutDetails`

The `CheckoutDetails` object has the following fields:

- `campaignId` (string, required): The unique identifier of the campaign.
- `paymentId` (string, required): An arbitrary value that uniquely identifies the payment. This ID should not be repeated between different payments. It will be sent via webhook to communicate the completion of the operation to the backend.
- `email` (string, optional): The email address of the Forge user.
- `userId` (string, optional): The unique identifier of the Forge user.
- `entries` (`CheckoutEntry[]`, required): An array of entries for the checkout.

### `CheckoutEntry`

A `CheckoutEntry` represents a line in the checkout. Each `CheckoutEntry` object in the `entries` array has the following fields:

- `productId` (string, required): The unique identifier of the product.
- `quantity` (number, required): The quantity of the product.

## Error Handling

Here is an example of how to handle the different error types to identify specific failure scenarios:

```typescript
import {
  startCheckout,
  CheckoutDetails,
  ProductNotFoundError,
  InsufficientStockError,
  PaymentIdAlreadyUsedError,
  InvalidPaymentMethodError,
  PaymentsNotEnabledError,
  ForgeApiError,
} from '@forgehq/payments-sdk';

// ... checkoutDetails definition

try {
  await startCheckout(checkoutDetails);
} catch (error) {
  if (error instanceof ProductNotFoundError) {
    // This error is thrown when one or more product IDs do not exist.
    console.error('Products not found:', error.productIds);
    // You can update the UI to inform the user which products are invalid.
  } else if (error instanceof InsufficientStockError) {
    // This error is thrown when the requested quantity for one or more products
    // cannot be satisfied.
    console.error('Insufficient stock for products:', error.productIds);
    // You could inform the user about the stock issue.
  } else if (error instanceof PaymentIdAlreadyUsedError) {
    // This error is thrown when the payment ID has already been used.
    console.error('Payment ID already used:', error.paymentId);
  } else if (error instanceof InvalidPaymentMethodError) {
    // This error is thrown when a payment method is invalid for the requested products.
    console.error('Invalid payment method for products:', error.productIds);
  } else if (error instanceof PaymentsNotEnabledError) {
    // This error is thrown when payments are not enabled for a campaign.
    console.error('Payments not enabled for campaign:', error.campaignId);
  } else if (error instanceof ForgeApiError) {
    // This is a generic error for problems when communicating with the Forge API.
    console.error('A Forge API error occurred:', error.message);
    console.error('HTTP Status:', error.httpStatusCode);
    console.error('Forge Error Code:', error.errorCode);
    // This can be used to handle server-side issues or invalid requests.
  } else {
    // Handle any other unexpected errors.
    console.error('An unexpected error occurred:', error);
  }
}
```