@rooguy/browser

v1.0.1

Published

12 days ago

Rooguy Drop-In UI SDK for vanilla JavaScript (Web Components)

0High
0Medium
0Low

@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

npm install @rooguy/browser

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

CDN (script tag)

<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:

<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

<!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

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

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

Teardown

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():

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

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@rooguy/browser

Installation

npm

CDN (script tag)

Quick Start

CDN Example

SDK Initialization

Accessing the Instance

Teardown

Web Components

<rooguy-leaderboard>

<rooguy-quest-list>

<rooguy-user-widget>

<rooguy-storefront>

<rooguy-user-profile>

<rooguy-toast-provider>

<rooguy-group>

<rooguy-group-leaderboard>

<rooguy-tournament-bracket>

<rooguy-notification-center>

<rooguy-badge-showcase>

<rooguy-streak-widget>

<rooguy-achievement-timeline>

<rooguy-aha-score>

<rooguy-profile-share>

<rooguy-questionnaire>

Theming

Custom Event Tracking

Accessibility

`<rooguy-leaderboard>`

`<rooguy-quest-list>`

`<rooguy-user-widget>`

`<rooguy-storefront>`

`<rooguy-user-profile>`

`<rooguy-toast-provider>`

`<rooguy-group>`

`<rooguy-group-leaderboard>`

`<rooguy-tournament-bracket>`

`<rooguy-notification-center>`

`<rooguy-badge-showcase>`

`<rooguy-streak-widget>`

`<rooguy-achievement-timeline>`

`<rooguy-aha-score>`

`<rooguy-profile-share>`

`<rooguy-questionnaire>`