# Fungies JavaScript SDK

The Fungies JavaScript SDK provides easy integration for Fungies checkout in your web applications.

## Installation

```bash
npm install @fungies/fungies-js
```

```bash
yarn add @fungies/fungies-js
```

```bash
pnpm add @fungies/fungies-js
```

## Usage

### JavaScript Initialization

```javascript
import { Fungies } from "@fungies/fungies-js";

// Initialize Fungies
Fungies.Initialize({
  // Optional: Disable data attribute support
  // enableDataAttributes: false
});

// Open a checkout programmatically
Fungies.Checkout.open({
  checkoutUrl: "https://store.example.com/checkout-element/my-checkout-id",
  settings: {
    mode: "overlay", // 'overlay' | 'embed'
    frameTarget: "target-element-id", // Optional, for embed mode
  },
});

// Close the checkout
Fungies.Checkout.close();
```

### Listening to checkout events

The SDK listens for messages from the checkout iframe and dispatches DOM events on `document`. This happens automatically when you call `Fungies.Initialize()` or use the `data-auto-init` script attribute — no extra setup is required.

Use these events to run your own logic after a purchase (redirect, show a thank-you page, refresh entitlements, etc.).

| Event | When it fires |
| --- | --- |
| `fungies:checkout:complete` | The customer completed checkout successfully |
| `fungies:checkout:close` | The checkout was closed (by the customer or after completion) |

```javascript
import { DOM_CHECKOUT_EVENTS, Fungies } from "@fungies/fungies-js";

Fungies.Initialize();

document.addEventListener(DOM_CHECKOUT_EVENTS.COMPLETE, () => {
  // Payment succeeded — e.g. redirect to a thank-you page
  window.location.href = "/thank-you";
});

document.addEventListener(DOM_CHECKOUT_EVENTS.CLOSE, () => {
  // Checkout overlay/embed was dismissed
  console.log("Checkout closed");
});

Fungies.Checkout.open({
  checkoutUrl: "https://store.example.com/checkout-element/my-checkout-id",
  settings: { mode: "overlay" },
});
```

When using the CDN script tag, register listeners after the SDK loads:

```html
<script
  src="https://cdn.jsdelivr.net/npm/@fungies/fungies-js@CURRENT_VERSION"
  defer
  data-auto-init
></script>
<script>
  document.addEventListener("fungies:checkout:complete", () => {
    window.location.href = "/thank-you";
  });
</script>
```

In React, attach listeners in a `useEffect` and clean them up on unmount:

```tsx
import { useEffect } from "react";
import { DOM_CHECKOUT_EVENTS, Fungies } from "@fungies/fungies-js";

function App() {
  useEffect(() => {
    Fungies.Initialize();

    const onComplete = () => {
      window.location.href = "/thank-you";
    };

    document.addEventListener(DOM_CHECKOUT_EVENTS.COMPLETE, onComplete);
    return () => {
      document.removeEventListener(DOM_CHECKOUT_EVENTS.COMPLETE, onComplete);
    };
  }, []);

  return <button onClick={() => Fungies.Checkout.open({ /* ... */ })}>Buy</button>;
}
```

### HTML Data Attribute Support

You can also use HTML data attributes to create checkout buttons without writing JavaScript:

```html
<!-- Basic checkout button -->
<button
  data-fungies-checkout-url="https://store.example.com/checkout-element/my-checkout-id"
  data-fungies-mode="overlay"
>
  Open Checkout
</button>

<!-- Script tag to initialize the SDK -->
<script
  src="https://cdn.jsdelivr.net/npm/@fungies/fungies-js@CURRENT_VERSION"
  defer
  data-auto-init
></script>

<!-- Embed checkout with target element -->
<div id="target-element-id"></div>

<!-- Script tag to initialize and display checkout automatically -->
<script
  src="https://cdn.jsdelivr.net/npm/@fungies/fungies-js@CURRENT_VERSION"
  defer
  data-auto-init
  data-auto-display-checkout
  data-fungies-checkout-url="https://demo.dev.fungies.net/checkout-element/a85d8c76-bc30-48a3-9861-be68952a1eca"
  data-fungies-mode="embed"
  data-fungies-frame-target="target-element-id"
></script>
```

### Manual DOM Scanning

If you dynamically add checkout elements after page load, you can manually trigger a DOM scan:

```javascript
// Scan the page for new checkout elements
Fungies.ScanDOM();
```

## Data Attributes Reference

- `data-fungies-checkout-url`: (Required for new format) The checkout URL
- `data-fungies-mode`: (Optional) The checkout mode ('overlay' or 'embed')
- `data-fungies-frame-target`: (Optional) Target element ID for embed checkouts
- `data-fungies-discount-code`: (Optional) Discount code to be applied
- `data-fungies-customer-email`: (Optional) Customer email to pre-fill (deprecated, use data-fungies-billing-email)
- `data-fungies-billing-email`: (Optional) Billing email to pre-fill
- `data-fungies-billing-first-name`: (Optional) Billing first name to pre-fill
- `data-fungies-billing-last-name`: (Optional) Billing last name to pre-fill
- `data-fungies-billing-country`: (Optional) Billing country code (ISO 3166-1 alpha-2) to pre-fill
- `data-fungies-billing-state`: (Optional) Billing state/province to pre-fill
- `data-fungies-billing-city`: (Optional) Billing city to pre-fill
- `data-fungies-billing-zip-code`: (Optional) Billing zip/postal code to pre-fill
- `data-fungies-quantity`: (Optional) Default quantity for the checkout
- `data-fungies-items`: (Optional) JSON string of items to be purchased
- `data-fungies-custom-fields`: (Optional) JSON string of custom fields
- `data-fungies-button`: (Legacy format) Contains a checkout URL like "https://STORE_URL/checkout-element/:checkoutID" or "https://STORE_URL/overlay/:checkoutID"

## TypeScript Support

This package includes TypeScript definitions. You can take advantage of type checking and IntelliSense in supported editors:

```typescript
import { DOM_CHECKOUT_EVENTS, Fungies } from "@fungies/fungies-js";
import type { DomCheckoutEvent, InitialCheckoutOpenOptions } from "@fungies/fungies-js";

const onComplete = (event: Event) => {
  const checkoutEvent = event.type as DomCheckoutEvent;
  if (checkoutEvent === DOM_CHECKOUT_EVENTS.COMPLETE) {
    window.location.href = "/thank-you";
  }
};

document.addEventListener(DOM_CHECKOUT_EVENTS.COMPLETE, onComplete);

// TypeScript will validate all parameters
const openOptions: InitialCheckoutOpenOptions = {
  checkoutUrl: "https://store.example.com/checkout-element/my-checkout-id",
  settings: {
    mode: "overlay",
    // frameTarget is optional and only used with embed mode
    frameTarget: "container-id",
  },
};

Fungies.Checkout.open(openOptions);
```