sawfish-payment-react-widget/README.md

A payment widget for processing payments through the Sawfish API

# Sawfish Payments React Widget

A React payment widget for processing payments through the Sawfish API. Supports React 18.2+ and React 19+.

## Installation

To install the package, run:

```bash
npm install sawfish-payment-react-widget
```

### Version Compatibility

This package is compatible with:

- React 18.2+
- React 19+
- TypeScript 5.0+
- Node.js 16.0+

## Usage

### PaymentForm Component

The `PaymentForm` component is used to process payments through the Sawfish API.

#### Props

- `environment` (optional): The environment to use. Can be "production", "staging", or "dev". Default is "dev".
- `endpoint`: The GraphQL endpoint. this plugin make use of GraphQL to communicate with the Sawfish API.
- `apiToken`: The API token.
- `clientId`: The client ID.
- `amount`: The payment amount.
- `contact`: The contact information.
- `metadata` (optional): Additional data to send to the server.
- `onPaymentSuccess` (optional): Callback function to handle successful payments.
- `onPaymentError` (optional): Callback function to handle payment errors.

#### Environment Variables

Create a `.env` file in your project root:

```env
# Sawfish API Configuration

# For Next.js (use NEXT_PUBLIC_ prefix)
NEXT_PUBLIC_SAWFISH_ENVIRONMENT=staging
NEXT_PUBLIC_SAWFISH_ENDPOINT=https://api.sawfish.2mm.io/graphql
NEXT_PUBLIC_SAWFISH_API_TOKEN=your-api-token-here
NEXT_PUBLIC_SAWFISH_CLIENT_ID=your-client-id-here

# For Create React App (use REACT_APP_ prefix)
# REACT_APP_SAWFISH_ENVIRONMENT=staging
# REACT_APP_SAWFISH_ENDPOINT=https://api.sawfish.2mm.io/graphql
# REACT_APP_SAWFISH_API_TOKEN=your-api-token-here
# REACT_APP_SAWFISH_CLIENT_ID=your-client-id-here

# For Vite (use VITE_ prefix)
# VITE_SAWFISH_ENVIRONMENT=staging
# VITE_SAWFISH_ENDPOINT=https://api.sawfish.2mm.io/graphql
# VITE_SAWFISH_API_TOKEN=your-api-token-here
# VITE_SAWFISH_CLIENT_ID=your-client-id-here
```

#### Example ReactJs Component

```tsx
import React from "react";
import { PaymentForm } from "sawfish-payment-react-widget";

const App = () => {
  const handlePaymentSuccess = (response: any) => {
    console.log("Payment successful:", response);
  };

  const handlePaymentError = (error: any) => {
    console.error("Payment error:", error);
  };

  return (
    <PaymentForm
      environment={process.env.NEXT_PUBLIC_SAWFISH_ENVIRONMENT || "staging"}
      endpoint={process.env.NEXT_PUBLIC_SAWFISH_ENDPOINT || ""}
      apiToken={process.env.NEXT_PUBLIC_SAWFISH_API_TOKEN || ""}
      clientId={process.env.NEXT_PUBLIC_SAWFISH_CLIENT_ID || ""}
      amount={100}
      contact={{
        first_name: "John",
        last_name: "Doe",
        email: "john.doe@example.com",
        description: "Payment for services", // description of the payment
        reference_no: "INV-001", // internal reference number like invoice number
        address_line1: "123 Main St",
        city: "Sydney",
        state: "NSW",
        zip: "2000",
        country: "Australia",
      }}
      onPaymentSuccess={handlePaymentSuccess}
      onPaymentError={handlePaymentError}
      metadata={{
        // any additional data you want to send to the server
        // currently used to send the invoice id
        invoice_id: "1234",
      }}
    />
  );
};

export default App;
```

#### Environment Variables Best Practices

1. **Security**: Never commit your `.env` file to version control
2. **Production**: Use different environment variables for production and staging
3. **Validation**: Always validate that required environment variables are present
4. **Fallbacks**: Provide sensible defaults for optional variables
5. **Framework Prefixes**: Use the correct prefix for your framework:
   - **Next.js**: `NEXT_PUBLIC_`
   - **Create React App**: `REACT_APP_`
   - **Vite**: `VITE_`

#### Example Payment Response

```JSON
{
    "amount": 604.72,
    "application_fee_amount": 11.08,
    "payment_gateway_fee": 11.08,
    "payment_at": "2025-03-04 00:00:00",
    "status": {
        "name": "payment_initiated"
    },
    "uuid": "...-...-...-...-..",
}
```

## Development

To start the development server, run:

```bash
npm run dev
```

To build the package, run:

```bash
npm run build
```

To clean the build artifacts, run:

```bash
npm run clean
```

## Publish

To publish the package, run:

```bash
npm run publish
```

## License

The Sprint Sawfish payments plugin is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).