npm package: @indicina1/decide-sdk
Description: The Decide Widget SDK allows you to easily integrate identity verification and spooling flows into your web application.
Latest version: 1.4.2

# Decide Widget SDK

The Decide Widget SDK allows you to easily integrate identity verification and spooling flows into your web application.

## Installation

```bash
npm install @indicina1/decide-sdk
```

### CDN / Script Tag

If you prefer not to use a package manager, you can include the SDK directly via a script tag. Using this method, the SDK as exposed as a global `DecideWidget` object.

```html
<script src="https://uploads.indicina.co/public/decide/prod/spool/sdk/widget.min.js"></script>

<!-- Popup Mode -->
<script>
  const controller = DecideWidget.popup({
    widgetUrl: "https://your-decide-app.com/widgets/application/...",
    customerIdentifier: "customer-123",
  });

  controller.open();
</script>

<!-- Inline Mode -->
<div id="widget-container"></div>
<script>
  DecideWidget.renderInline({
    widgetUrl: "https://your-decide-app.com/widgets/application/...",
    containerId: "widget-container", // Must match the ID above
    customerIdentifier: "customer-123",
  });
</script>
```

## Usage

### Popup Mode

```typescript
import { DecideWidget } from "@indicina1/decide-sdk";

const controller = DecideWidget.popup({
  widgetUrl: "https://your-decide-app.com/widgets/application/...",
  customerIdentifier: "customer-123",
  onLoad: () => {
    console.log("Widget loaded");
  },
  onMessage: (message) => {
    console.log("Message from widget:", message);
  },
  onClose: () => {
    console.log("Widget closed");
  },
  onError: (error) => {
    console.error("Widget error:", error);
  },
});

controller.open();
```

### Inline Mode

```typescript
import { DecideWidget } from "@indicina1/decide-sdk";

DecideWidget.renderInline({
  widgetUrl: "https://your-decide-app.com/widgets/application/...",
  containerId: "widget-container",
  customerIdentifier: "customer-123",
  onLoad: () => {
    console.log("Inline widget loaded");
  },
});
```

## Configuration

The `popup` and `renderInline` methods accept a configuration object with the following properties:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `widgetUrl` | `string` | **Yes** | The full URL of the Decide widget application you want to load. |
| `customerIdentifier` | `string` | No | A unique identifier for the customer (e.g., email or UUID). Used to pre-fill or link sessions. |
| `containerId` | `string` | **Yes** (Inline only) | The ID of the HTML element where the widget should be rendered. |
| `workflowConfiguration` | `object` | No | Optional settings to override workflow behavior. See below. |
| `metadata` | `object` | No | Additional JSON data to pass to the widget session. |
| `autoOpen` | `boolean` | No | If `true`, the popup opens immediately upon initialization. Defaults to `false`. |
| `onLoad` | `() => void` | No | Callback fired when the widget iframe finishes loading. |
| `onClose` | `() => void` | No | Callback fired when the user closes the popup or gets a close event. |
| `onMessage` | `(data: any) => void` | No | Callback for receiving custom messages/events from the widget. |
| `onError` | `(error: any) => void` | No | Callback fired if the widget encounters an initialization error. |

### Workflow Configuration
You can pass an optional `workflowConfiguration` object to customize specific behaviors:

```typescript
workflowConfiguration: {
  revalidateNin: true,      // Force NIN revalidation
  revalidateBvn: false,     // Skip BVN revalidation
  mbsValidityPeriod: 30,    // Days MBS data remains valid
  bvnAccountValidity: 30,   // Days BVN account data remains valid
  theme: "outside"          // Theme preference ('inside' or 'outside')
}
```

## Setup & Development

### 1. Building

Build the SDK and Demo application for specific environments:

- **Local Build**: `npm run build`
- **Sandbox Build**: `npm run build:sandbox`
- **Production Build**: `npm run build:prod`

The build output is isolated:

- `dist/sdk/`: SDK library files.
- `dist/demo/`: Standalone demo application.

### 2. Testing the Demo

To preview the demo application locally:

```bash
npm run start
```

This serves `dist/demo` at `http://localhost:4173`.

## Local NPM Testing

Before publishing to the real NPM registry, you can test the package locally using these methods:

### Method A: Using `npm pack` (Recommended)

1. **Build the SDK**:
   ```bash
   npm run build:sdk
   ```
2. **Generate Tarball**:
   ```bash
   npm pack
   ```
   This creates a file like `decide-sdk-0.0.0.tgz` in your root folder.
3. **Install in another project**:
   ```bash
   npm install /path/to/decide-sdk-0.0.0.tgz
   ```

### Method B: Using `npm link`

1. **Link the SDK**:
   ```bash
   npm link
   ```
2. **Use in another project**:
   ```bash
   cd /path/to/your-app
   npm link @indicina1/decide-sdk
   ```

## License

MIT