@kiauth/web-sdk 1.0.0

package/README.md

@@ -0,0 +1,109 @@
+# @kiauth/web-sdk
+
+Framework-agnostic "Login with Kiauth" button for any website (React, Vue, Angular,
+Svelte, or plain HTML). Renders a button, runs the QR approval flow, and hands your
+frontend a one-time authorization `code`. Your **server** exchanges that code for the
+verified user.
+
+> Test backend: `https://api.kiauth.com` — pass it as `baseUrl`.
+
+## Install
+
+**Option A — script tag (no build tooling):**
+```html
+<script src="/path/to/kiauth-sdk.min.js"></script>
+<script>
+  const kiauth = new KiauthSDK({
+    clientId: 'YOUR_CLIENT_ID',
+    scopes: ['name', 'email'],
+    environment: 'production',
+    baseUrl: 'https://api.kiauth.com'
+  });
+  kiauth.renderButton('#login-container', {
+    text: 'Login with Kiauth',
+    onSuccess: (user) => {
+      // user.code -> send to YOUR backend to exchange (see below)
+    },
+    onError: (err) => console.error(err.message)
+  });
+</script>
+<div id="login-container"></div>
+```
+
+**Option B — local tarball (import workflow):**
+```bash
+npm install ./kiauth-web-sdk-1.0.0.tgz
+```
+```js
+import { KiauthSDK } from '@kiauth/web-sdk';
+
+const kiauth = new KiauthSDK({
+  clientId: process.env.KIAUTH_CLIENT_ID,
+  scopes: ['name', 'email'],
+  environment: 'production',
+  baseUrl: 'https://api.kiauth.com'
+});
+```
+
+## Config
+
+| Field | Required | Notes |
+|---|---|---|
+| `clientId` | yes | From your app in the Kiauth dev portal |
+| `scopes` | yes | Subset of `name`, `email`, `dob`, `gender`, `phone` |
+| `environment` | yes | `'production'` or `'sandbox'` |
+| `baseUrl` | recommended | Backend URL. Overrides the env default. `/api/v1` is appended automatically. |
+| `redirectUri` | optional | Where to return after approval |
+
+## Button customization (white-label)
+
+`renderButton(selector, options)` accepts optional styling so the button can match
+your brand. All are optional and backward-compatible (omit them for the default look).
+
+| Option | Type | Notes |
+|---|---|---|
+| `text` | string | Button label (default `"Login with Kiauth"`) |
+| `theme` | `'purple' \| 'white' \| 'dark'` | Preset look |
+| `size` | `'small' \| 'medium' \| 'large'` | |
+| `color` | string (CSS color) | Custom background/brand color — overrides `theme` |
+| `textColor` | string (CSS color) | Custom label + icon color |
+| `shape` | `'rounded' \| 'pill' \| 'square'` | Corner style |
+| `fullWidth` | boolean | Stretch to the container width |
+| `logo` | boolean | Show the Kiauth lock mark (default `true`) |
+
+```js
+kiauth.renderButton('#login-container', {
+  text: 'Continue with Kiauth',
+  color: '#0F172A',
+  textColor: '#FFFFFF',
+  shape: 'pill',
+  fullWidth: true,
+  onSuccess: (user) => { /* ... */ },
+  onError: (err) => console.error(err.message)
+});
+```
+
+> Prefer a redirect-based integration with your existing auth library (Auth.js, etc.)?
+> Kiauth is also a standard **OpenID Connect** provider — see the dev-portal docs for the
+> "Login with Kiauth" OIDC option. The embedded button (this SDK) gives full white-label
+> control; OIDC is the lowest-friction drop-in.
+
+## Server-side token exchange (required)
+
+The `code` from `onSuccess` is exchanged on **your backend** — never expose your Client Secret in the browser.
+
+```js
+const res = await fetch('https://api.kiauth.com/api/v1/auth/token', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    grantType: 'authorization_code',
+    code,
+    clientId: process.env.KIAUTH_CLIENT_ID,
+    clientSecret: process.env.KIAUTH_CLIENT_SECRET
+  })
+});
+const { user } = await res.json(); // { name, email, verified, userToken }
+```
+
+Use `user.userToken` (a stable per-user id) to create your own app session.