npm package: @kwik-id/sdk-web
Description: CDN-ready Web Component for [KwikID](https://kwik-id.com) identity verification. Add KYC verification to any website with a single `<script>` tag — no framework required.
Latest version: 0.1.0

# @kwik-id/sdk-web

CDN-ready Web Component for [KwikID](https://kwik-id.com) identity verification. Add KYC verification to any website with a single `<script>` tag — no framework required.

The `<kwik-id-verification>` element wraps the full React-powered SDK, so it's feature-identical to `@kwik-id/sdk-react`.

## CDN Usage (Recommended)

Add one script tag — CSS is injected automatically:

```html
<script src="https://cdn.jsdelivr.net/npm/@kwik-id/sdk-web/dist/kwik-id-sdk.umd.cjs"></script>

<kwik-id-verification
  client-secret="your-client-secret"
  app-name="My App"
  theme-primary="#2563EB"
></kwik-id-verification>

<script>
  const el = document.querySelector("kwik-id-verification");

  // Fires immediately when documents are uploaded and processing begins
  el.addEventListener("kwik-id:submitted", (e) => {
    console.log("Submitted! Job ID:", e.detail.jobId);
  });

  // Fires when the user dismisses the result screen
  el.addEventListener("kwik-id:complete", (e) => {
    console.log("User finished:", e.detail);
  });

  el.addEventListener("kwik-id:error", (e) => {
    console.error("Verification error:", e.detail);
  });
</script>
```

## npm Installation

```bash
npm install @kwik-id/sdk-web
# or
pnpm add @kwik-id/sdk-web
# or
yarn add @kwik-id/sdk-web
```

```js
// The import auto-registers the <kwik-id-verification> custom element
import "@kwik-id/sdk-web";
```

## Integration Flow

### 1. Create a session on your backend

Use [`@kwik-id/sdk-node`](https://www.npmjs.com/package/@kwik-id/sdk-node) to create a verification session:

```js
// Your backend
const session = await kwikId.createSession({
  referenceId: "user_123",
  userName: "Jane Doe",
});
// Return session.token to the frontend as the clientSecret
```

### 2. Render the Web Component

```html
<kwik-id-verification
  client-secret="<token from your backend>"
  app-name="My App"
  theme-primary="#1E3A8A"
  theme-accent="#FBBF24"
></kwik-id-verification>
```

### 3. Listen for events

```js
const el = document.querySelector("kwik-id-verification");

// Documents uploaded, processing started — save the jobId
el.addEventListener("kwik-id:submitted", (e) => {
  console.log("Job ID:", e.detail.jobId);
  // You'll receive final results via webhook on your backend
});

// User dismissed the result screen
el.addEventListener("kwik-id:complete", (e) => {
  console.log("Done", e.detail);
});

el.addEventListener("kwik-id:error", (e) => {
  console.error(e.detail);
});
```

## Attributes

| Attribute | Description |
|---|---|
| `client-secret` | **Required.** Session token from your backend |
| `app-name` | App name shown in the verification header |
| `theme-primary` | Primary brand color (hex, e.g. `#2563EB`) |
| `theme-accent` | Accent color (hex) |
| `theme-background` | Background color (hex) |
| `theme-foreground` | Foreground/text color (hex) |
| `show-logo` | Show org logo in header (`"true"` or `"false"`) |

## Events

| Event | Description | `e.detail` |
|---|---|---|
| `kwik-id:submitted` | Documents uploaded, background processing started | `{ jobId: string }` |
| `kwik-id:complete` | User dismissed the result screen | `KYCFormData` |
| `kwik-id:error` | An error occurred | `Error` |

## Vanilla JavaScript Example

```html
<!DOCTYPE html>
<html>
  <head>
    <title>KYC Verification</title>
  </head>
  <body>
    <div id="verification-container">
      <button id="start-btn">Start Verification</button>
    </div>

    <script src="https://cdn.jsdelivr.net/npm/@kwik-id/sdk-web/dist/kwik-id-sdk.umd.cjs"></script>
    <script>
      document.getElementById("start-btn").addEventListener("click", async () => {
        // Get session from your backend
        const res = await fetch("/api/create-session", { method: "POST" });
        const { clientSecret } = await res.json();

        // Create and inject the verification element
        const el = document.createElement("kwik-id-verification");
        el.setAttribute("client-secret", clientSecret);
        el.setAttribute("app-name", "My App");
        el.setAttribute("theme-primary", "#2563EB");

        el.addEventListener("kwik-id:submitted", (e) => {
          console.log("Job ID:", e.detail.jobId);
        });

        el.addEventListener("kwik-id:complete", () => {
          el.remove();
        });

        const container = document.getElementById("verification-container");
        container.innerHTML = "";
        container.appendChild(el);
      });
    </script>
  </body>
</html>
```

## WordPress / No-Build Usage

```html
<!-- In your page template or custom HTML block -->
<script src="https://cdn.jsdelivr.net/npm/@kwik-id/sdk-web/dist/kwik-id-sdk.umd.cjs"></script>

<kwik-id-verification
  client-secret="your-client-secret"
  app-name="My Business"
  theme-primary="#1E3A8A"
></kwik-id-verification>
```

## Advanced: Direct SDK Access

The package also re-exports the full `@kwik-id/sdk-core` API for advanced use cases:

```js
import { KwikIdSDK, CameraEngine, QualityAnalyzer, FaceDetector } from "@kwik-id/sdk-web";

const sdk = new KwikIdSDK({
  clientSecret: "...",
  baseUrl: "https://api.kwik-id.com",
});

await sdk.initialize();
// Use camera, quality, face detection, liveness APIs directly
```

## Supported Document Types

- National ID Card
- Passport
- Driver's License
- Voter's Card

## Browser Support

- Chrome 80+
- Firefox 78+
- Safari 14+
- Edge 80+

Camera access requires HTTPS in production (except `localhost` for development).

## License

MIT