# Vouch SDK

[![Static Badge](https://img.shields.io/badge/Vouch-read_docs-green?style=for-the-badge)](https://docs.getvouch.io/introduction)

This is the Vouch SDK, a TypeScript library for interacting with Vouch. Currently, it allows you to generate links to start the web proof flow or direct users to a widget page.

## Installation

To install the Vouch SDK, you can use npm or other package managers.

```bash
npm install @getvouch/sdk
yarn add @getvouch/sdk
pnpm add @getvouch/sdk
bun add @getvouch/sdk
```

## Usage

Create a Vouch instance with your `customerId` and `apiKey`:

```typescript
import { Vouch } from "@getvouch/sdk";
const vouch = new Vouch({
  customerId: "customer-id", // Your unique customer ID.
  apiKey: "your-api-key", // Your API key for authentication.
});
```

You may also provide additional configuration options:

```typescript
import { Vouch } from "@getvouch/sdk";
const vouch = new Vouch({
  customerId: "customer-id",
  apiKey: "your-api-key",
  vouchHost: "https://app.getvouch.io", // The base URL for the Vouch API. Can be a string or an URL object. Defaults to "https://app.getvouch.io".
});
```

### Get data source URL

[Generate a link to start the Vouch flow](https://docs.getvouch.io/getting-started/first-steps#redirect-user-to-vouch).

```typescript
const { verificationUrl, requestId } = await vouch.getDataSourceUrl({
  datasourceId: "93826be6-6c7d-495a-9859-de5a1d17f30b", // Datasource ID. Here we use example.com data source. Must be a UUIDv4.
  redirectBackUrl: "https://docs.getvouch.io/getting-started/first-steps", // Return destination.
  webhookUrl: "https://docs.getvouch.io/api/web-proof", // (Optional) Proof delivery endpoint.
  requestId: "your-uuid-v4", // (Optional) Provide your own UUIDv4 to use as the proof request ID. If omitted, the server generates one.
});
```

#### Adding inputs

[Learn more about inputs](https://docs.getvouch.io/getting-started/handling-inputs).

Suppose, you want to use a datasource with the following inputs schema:

```typescript
{
  name: string;
  minFollowersCount: number;
}
```

You'd then need to provide the inputs when generating the data source URL:

```typescript
const { verificationUrl, requestId } = await vouch.getDataSourceUrl({
  /// ...similar to the previous example
  inputs: {
    name: "John Doe",
    minFollowersCount: 1337,
  },
});
```

The inputs will be encoded to base64, so you'd see something like this inside the URL:
`inputs=eyJuYW1lIjoiSm9obiBEb2UiLCJtaW5Gb2xsb3dlcnNDb3VudCI6MTMzN30`

### Get widget URL

Generate a link to a widget page where users can choose from available data sources. Requires `customerId` and `apiKey` in the constructor.

```typescript
const { verificationUrl, requestId } = await vouch.getWidgetUrl({
  widgetId: "41b9a0c3-1234-4678-9abc-def012345678", // Your widget ID. Must be a UUIDv4.
  redirectBackUrl: "https://example.com/callback", // Return destination after proof completion.
  webhookUrl: "https://example.com/webhook", // (Optional) Proof delivery endpoint.
});
```