@bigstrider/transcodes-sdk

A frontend client SDK for the Transcodes platform. This wrapper library provides simple access to WebAuthn Passkey authentication, RBAC IDP, audit logging, and PWA detection features in host web applications.

The actual SDK implementation (Dynamic SDK) is dynamically loaded from the CDN on a per-project basis when init() is called. This package only includes type definitions and a loader (script injection + polling).

Installation

npm install @bigstrider/transcodes-sdk

Quick Start

import { init, openAuthLoginModal, on } from '@bigstrider/transcodes-sdk';

// 1. Initialize (loads Dynamic SDK from CDN)
await init('YOUR_PROJECT_ID');

// 2. Open login modal
const result = await openAuthLoginModal({ webhookNotification: false });
if (result.success) {
  console.log('Login successful:', result.payload[0].user);
}

// 3. Subscribe to auth state changes
const unsubscribe = on('AUTH_STATE_CHANGED', ({ isAuthenticated, user }) => {
  console.log('Auth state:', isAuthenticated, user);
});

// 4. Unsubscribe
unsubscribe();

API

init(projectId, options?)

Loads and initializes the project-specific Dynamic SDK from the CDN. Automatically skipped in SSR environments.

await init('YOUR_PROJECT_ID');
await init('YOUR_PROJECT_ID', { customUserId: 'user-123', debug: true });

| Option | Type | Description | |---|---|---| | customUserId | string | External user ID to associate with the authenticated user | | debug | boolean | Enable debug logging |

Auth Modals

// Login (WebAuthn Passkey)
const result = await openAuthLoginModal({ webhookNotification: false });
// result: ApiResponse<AuthResult[]>

// User console (after authentication)
await openAuthConsoleModal();

// Admin console (includes RBAC role check)
await openAuthAdminModal({ allowedRoles: ['admin', 'manager'] });

// IDP auth modal (RBAC resource access)
await openAuthIdpModal({ resource: 'invoice', action: 'read' });

Token / User

const isLoggedIn = await isAuthenticated();   // boolean
const user = await getCurrentUser();          // User | null
const token = await getAccessToken();         // string | null
const hasSession = hasToken();                // boolean (synchronous)

await signOut({ webhookNotification: false });

User Lookup

const res = await getUser({ email: '[email protected]' });
// res: ApiResponse<User[]>

Event Subscription

on() returns an unsubscribe function.

const unsubscribe = on('AUTH_STATE_CHANGED', (payload) => {
  // payload: { isAuthenticated, accessToken, expiresAt, user }
});

on('TOKEN_REFRESHED', ({ accessToken, expiresAt }) => { ... });
on('TOKEN_EXPIRED', ({ expiredAt }) => { ... });
on('ERROR', ({ code, message }) => { ... });

// Unsubscribe
unsubscribe();
// Or
off('AUTH_STATE_CHANGED', callback);

| Event | Payload Type | |---|---| | AUTH_STATE_CHANGED | AuthStateChangedPayload | | TOKEN_REFRESHED | TokenRefreshedPayload | | TOKEN_EXPIRED | TokenExpiredPayload | | ERROR | ErrorPayload |

Audit Log

await trackUserAction(
  { tag: 'export_report', severity: 'medium', status: true },
  { requireAuth: true, webhookNotification: true }
);

PWA

const installed = isPwaInstalled(); // boolean

Framework Usage Patterns

Next.js 15 (App Router)

The SDK uses window, so it must only be called inside 'use client' components.

// components/TranscodesDemo.tsx
'use client';
import { useEffect, useRef } from 'react';
import { init, on } from '@bigstrider/transcodes-sdk';

export function TranscodesDemo() {
  const unsubRef = useRef<(() => void) | null>(null);

  useEffect(() => {
    // init must be called inside a component — do not call from a Server Component
    unsubRef.current = on('AUTH_STATE_CHANGED', (payload) => {
      console.log(payload);
    });
    return () => unsubRef.current?.();
  }, []);
  // ...
}

SvelteKit (Svelte 5)

In SSR environments, exclude the SDK using a browser check + dynamic import.

<script lang="ts">
  import { browser } from '$app/environment';
  import { onDestroy } from 'svelte';

  let unsubscribe: (() => void) | null = null;

  async function initSdk() {
    if (!browser) return;
    const sdk = await import('@bigstrider/transcodes-sdk');
    await sdk.init('YOUR_PROJECT_ID');
    unsubscribe = sdk.on('AUTH_STATE_CHANGED', (payload) => {
      console.log(payload);
    });
  }

  onDestroy(() => unsubscribe?.());
</script>

React (Vite / CRA)

Pure CSR, so static imports can be used directly.

import { useEffect, useRef } from 'react';
import { init, on } from '@bigstrider/transcodes-sdk';

function App() {
  const unsubRef = useRef<(() => void) | null>(null);

  useEffect(() => {
    init('YOUR_PROJECT_ID').then(() => {
      unsubRef.current = on('AUTH_STATE_CHANGED', console.log);
    });
    return () => unsubRef.current?.();
  }, []);
}

Vue 3 (Vite)

// composables/useTranscodes.ts
import { onUnmounted } from 'vue';
import { init, on } from '@bigstrider/transcodes-sdk';

export function useTranscodes() {
  let unsubscribe: (() => void) | null = null;

  async function initSdk(projectId: string) {
    await init(projectId);
    unsubscribe = on('AUTH_STATE_CHANGED', console.log);
  }

  onUnmounted(() => unsubscribe?.());
  return { initSdk };
}

Types

interface ApiResponse<T> {
  success: boolean;
  payload: T;
  error?: string;
  message?: string;
  status?: number;
}

interface User {
  id: string;
  email: string;
  name?: string;
  role?: string;
  projectId: string;
  metadata?: Record<string, string | number | boolean | null | undefined>;
}

interface AuthResult {
  token: string;
  user: User;
}

For the complete type definitions, refer to src/types.ts or node_modules/@bigstrider/transcodes-sdk/lib/types/ after installation.

Example Apps

For integration examples across 4 frameworks, see the examples/ directory.

License

MIT