npm package: @rooguy/browser
Description: Rooguy Drop-In UI SDK for vanilla JavaScript (Web Components)
Latest version: 1.0.1

# @rooguy/browser

Drop-in Web Components for adding gamification UI to any website or framework. Zero runtime dependencies — works with vanilla HTML, Vue, Svelte, Angular, or any other framework.

## Installation

### npm

```bash
npm install @rooguy/browser
```

```js
import { RooguySdk } from "@rooguy/browser";
```

### CDN (script tag)

```html
<script src="https://cdn.jsdelivr.net/npm/@rooguy/browser@latest/dist/index.global.js"></script>
```

When loaded via `<script>`, the SDK is available as `window.RooguySdk`.

## Quick Start

Initialize the SDK once, then use Web Components anywhere in your HTML:

```html
<script type="module">
  import { RooguySdk } from "@rooguy/browser";

  await RooguySdk.init({
    publishableKey: "pk_live_abc123",
    userToken: "eyJhbGciOi...",
    baseUrl: "https://api.rooguy.com",
  });
</script>

<rooguy-leaderboard timeframe="weekly"></rooguy-leaderboard>
<rooguy-quest-list status="in_progress"></rooguy-quest-list>
<rooguy-user-widget layout="compact"></rooguy-user-widget>
```

### CDN Example

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <script src="https://cdn.jsdelivr.net/npm/@rooguy/browser@latest/dist/index.global.js"></script>
  </head>
  <body>
    <rooguy-leaderboard timeframe="weekly"></rooguy-leaderboard>

    <script>
      Rooguy.RooguySdk.init({
        publishableKey: "pk_live_abc123",
        userToken: "eyJhbGciOi...",
      });
    </script>
  </body>
</html>
```

## SDK Initialization

```js
const sdk = await RooguySdk.init(config);
```

| Option           | Type                      | Required | Description                                                         |
| ---------------- | ------------------------- | -------- | ------------------------------------------------------------------- |
| `publishableKey` | `string`                  | Yes      | Your project's publishable API key                                  |
| `userToken`      | `string`                  | No       | JWT identifying the current user. Omit for anonymous read-only mode |
| `baseUrl`        | `string`                  | No       | API base URL                                                        |
| `theme`          | `ThemeConfig`             | No       | Custom theme overrides                                              |
| `i18n`           | `Partial<I18nDictionary>` | No       | Translation overrides                                               |

`init()` is idempotent — calling it multiple times returns the same instance.

### Accessing the Instance

```js
// After init() has resolved:
const sdk = RooguySdk.getInstance();
console.log(sdk.userId);
console.log(sdk.connectionStatus);
```

### Teardown

```js
RooguySdk.destroy();
```

## Web Components

All components use Shadow DOM for style encapsulation and render semantic HTML with ARIA attributes.

### `<rooguy-leaderboard>`

| Attribute                | Description                                          |
| ------------------------ | ---------------------------------------------------- |
| `leaderboard-id`         | Specific leaderboard ID (omit for global)            |
| `timeframe`              | `all_time`, `weekly`, or `monthly`                   |
| `limit`                  | Number of entries per page                           |
| `highlight-current-user` | Highlight the current user's row (boolean attribute) |

### `<rooguy-quest-list>`

| Attribute | Description                                                        |
| --------- | ------------------------------------------------------------------ |
| `status`  | Filter by quest status: `in_progress`, `ready_to_claim`, `claimed` |

### `<rooguy-user-widget>`

| Attribute | Description            |
| --------- | ---------------------- |
| `layout`  | `default` or `compact` |

### `<rooguy-storefront>`

| Attribute | Description    |
| --------- | -------------- |
| `limit`   | Items per page |

### `<rooguy-user-profile>`

| Attribute  | Description                                                  |
| ---------- | ------------------------------------------------------------ |
| `user-id`  | Target user ID (defaults to current user)                    |
| `sections` | Comma-separated list: `header,stats,badges,quests,inventory` |

### `<rooguy-toast-provider>`

| Attribute     | Description                                                                           |
| ------------- | ------------------------------------------------------------------------------------- |
| `position`    | `top-right`, `top-left`, `top-center`, `bottom-right`, `bottom-left`, `bottom-center` |
| `duration`    | Auto-dismiss time in ms (default: 5000)                                               |
| `max-visible` | Max simultaneous toasts (default: 3)                                                  |

### `<rooguy-group>`

| Attribute  | Description                                                  |
| ---------- | ------------------------------------------------------------ |
| `group-id` | Group ID (omit for user's primary group)                     |
| `sections` | Comma-separated: `header,members,leaderboard,quests,streaks` |
| `layout`   | `card`, `full-page`, or `sidebar`                            |

### `<rooguy-group-leaderboard>`

| Attribute    | Description               |
| ------------ | ------------------------- |
| `group-type` | Filter by group type      |
| `limit`      | Number of groups per page |

### `<rooguy-tournament-bracket>`

| Attribute       | Description                                                 |
| --------------- | ----------------------------------------------------------- |
| `tournament-id` | Tournament ID (required)                                    |
| `layout`        | `bracket` (connected nodes) or `list` (flat round-by-round) |

### `<rooguy-notification-center>`

| Attribute | Description                         |
| --------- | ----------------------------------- |
| `layout`  | `dropdown`, `panel`, or `full-page` |
| `limit`   | Notifications per page              |

### `<rooguy-badge-showcase>`

| Attribute            | Description                           |
| -------------------- | ------------------------------------- |
| `sort-by`            | Sort field (e.g. `earned_at`, `name`) |
| `filter-by-category` | Filter by badge category              |
| `filter-by-tier`     | Filter by badge tier                  |
| `layout`             | `grid`, `list`, or `carousel`         |

### `<rooguy-streak-widget>`

| Attribute | Description                               |
| --------- | ----------------------------------------- |
| `user-id` | Target user ID (defaults to current user) |
| `layout`  | `compact`, `card`, or `ring`              |

### `<rooguy-achievement-timeline>`

| Attribute | Description                               |
| --------- | ----------------------------------------- |
| `user-id` | Target user ID (defaults to current user) |
| `limit`   | Achievements per page                     |

### `<rooguy-aha-score>`

| Attribute | Description                  |
| --------- | ---------------------------- |
| `layout`  | `gauge`, `bar`, or `compact` |

### `<rooguy-profile-share>`

| Attribute            | Description                                    |
| -------------------- | ---------------------------------------------- |
| `share-type`         | Share type (e.g. `full`, `badges`, `stats`)    |
| `expires-in-days`    | Link expiration in days                        |
| `password-protected` | Enable password protection (boolean attribute) |

### `<rooguy-questionnaire>`

| Attribute          | Description                                                |
| ------------------ | ---------------------------------------------------------- |
| `questionnaire-id` | Questionnaire ID (omit for active questionnaire)           |
| `mode`             | `paginated`, `scroll`, or `stepper`                        |
| `allow-retake`     | Allow retaking completed questionnaire (boolean attribute) |

## Theming

Pass a `theme` object to `init()`:

```js
await RooguySdk.init({
  publishableKey: "pk_live_abc123",
  theme: {
    primaryColor: "#6366f1",
    borderRadius: "12px",
    fontFamily: "Inter, sans-serif",
  },
});
```

Theme values are applied as `--rooguy-*` CSS custom properties inside each component's Shadow DOM.

## Custom Event Tracking

```js
const sdk = RooguySdk.getInstance();
sdk.eventTracker?.trackEvent("purchase_completed", {
  itemId: "sword-01",
  price: 100,
});
```

## Accessibility

- Shadow DOM with semantic HTML
- ARIA attributes on all interactive elements
- Keyboard navigable
- `aria-live` regions for dynamic content