@vizbeetv/homesso-sdk-qa 1.0.1

package/README.md

@@ -0,0 +1,319 @@
+# @vizbeetv/homesso-sdk-qa
+
+TV app authentication library — enables mobile-to-TV Single Sign-On (SSO) via the Vizbee platform.
+
+> **This is the QA build.** For production use, install [`@vizbeetv/homesso-sdk`](https://www.npmjs.com/package/@vizbeetv/homesso-sdk) instead.
+
+## Installation
+
+```bash
+npm install @vizbeetv/homesso-sdk-qa
+```
+
+The default entry point ships ES5 output, safe for all TV platforms. An explicit ES6 subpath is available for modern engines.
+
+## Prerequisites
+
+This SDK requires the [Vizbee SDK (`@vizbeetv/sdk-qa`)](https://www.npmjs.com/package/@vizbeetv/sdk-qa) to be loaded first. That SDK populates `window.vizbee.continuity` and fires the `VIZBEE_SDK_READY` event, which this SDK listens for during initialisation.
+
+Install it alongside this package:
+
+```bash
+npm install @vizbeetv/sdk-qa @vizbeetv/homesso-sdk-qa
+```
+
+---
+
+## Quick start
+
+```typescript
+import { HomeSSOContext, ProgressStatus, SuccessStatus, FailureStatus } from '@vizbeetv/homesso-sdk-qa';
+
+const manager = HomeSSOContext.getInstance().getHomeSSOManager();
+
+// Provide current sign-in state for the device
+manager.setSignInInfoGetter(async () => [
+  { userLoginType: 'email', isSignedIn: true, userLogin: 'user@example.com' },
+]);
+
+// Handle an incoming sign-in request from a mobile device
+manager.setSignInHandler((signInInfo, statusCallback) => {
+  const { signInType } = signInInfo;
+
+  statusCallback(new ProgressStatus(signInType, { regcode: 'ABC123' }));
+
+  performSignIn(signInInfo)
+    .then(user => statusCallback(new SuccessStatus(signInType, user.id, { email: user.email })))
+    .catch(() => statusCallback(new FailureStatus(signInType, false, 'Sign-in failed')));
+});
+
+// Initialise the session (call after the Vizbee Continuity SDK is ready)
+manager.init();
+```
+
+---
+
+## Package variants
+
+| Import path | JS target | Use when |
+|---|---|---|
+| `@vizbeetv/homesso-sdk-qa` | ES5 (default) | All TV platforms, legacy engines |
+| `@vizbeetv/homesso-sdk-qa/es5` | ES5 | Same as default, explicit |
+| `@vizbeetv/homesso-sdk-qa/es6` | ES6 | Tizen 5.5+, webOS 6+, Chrome 72+ |
+
+```typescript
+// ES6 build — modern bundlers / TV platforms that support ES2015+
+import { HomeSSOContext } from '@vizbeetv/homesso-sdk-qa/es6';
+```
+
+---
+
+## API reference
+
+### `HomeSSOContext`
+
+The main entry point. Use `getInstance()` to get the singleton.
+
+```typescript
+const context = HomeSSOContext.getInstance();
+const manager = context.getHomeSSOManager();
+const uiManager = context.getHomeSSOUIManager();
+
+// Toggle logging
+context.enableLogger(true);
+context.setLoggerLevel(LogLevel.DEBUG);
+```
+
+---
+
+### `VizbeeHomeSSOManager`
+
+Retrieved via `HomeSSOContext.getInstance().getHomeSSOManager()`.
+
+#### `init()`
+
+Connects to the Vizbee session. Call this after `window.vizbee.continuity` is available (i.e. inside your app's Vizbee ready callback).
+
+```typescript
+manager.init();
+```
+
+#### `setSignInInfoGetter(getter)`
+
+Provides the current sign-in state of the TV device. Called internally before deciding whether to trigger a sign-in flow.
+
+```typescript
+import type { VizbeeSignInInfo } from '@vizbeetv/homesso-sdk-qa';
+
+manager.setSignInInfoGetter(async (): Promise<VizbeeSignInInfo[]> => {
+  return [
+    {
+      userLoginType: 'email',        // must match the signInType sent by the mobile app
+      isSignedIn: isUserLoggedIn(),
+      userLogin: getCurrentUserEmail(),
+    },
+  ];
+});
+```
+
+#### `setSignInHandler(handler)`
+
+Receives sign-in requests from mobile devices. The handler is called with a `signInInfo` payload and a `statusCallback` to report progress.
+
+```typescript
+import { ProgressStatus, SuccessStatus, FailureStatus } from '@vizbeetv/homesso-sdk-qa';
+
+manager.setSignInHandler((signInInfo, statusCallback) => {
+  const { signInType } = signInInfo;
+
+  // Report in-progress (shows the progress snackbar; regcode is required)
+  statusCallback(new ProgressStatus(signInType, { regcode: 'ABC123' }));
+
+  // Later, report success (email in customData is required to show success UI)
+  statusCallback(new SuccessStatus(signInType, 'user-id-123', { email: 'user@example.com' }));
+
+  // Or report failure / cancellation
+  statusCallback(new FailureStatus(signInType, false, 'Authentication failed'));
+  statusCallback(new FailureStatus(signInType, true));   // isCancelled = true
+});
+```
+
+#### `addCustomEventAttributes(attributes)`
+
+Attaches custom key/value pairs to all analytics events emitted by the SDK.
+
+```typescript
+manager.addCustomEventAttributes({ appVersion: '3.2.1', platform: 'tizen' });
+```
+
+---
+
+### Status classes
+
+#### `ProgressStatus`
+
+Signals that sign-in is in progress. `customData.regcode` is **required** to trigger the progress UI.
+
+```typescript
+new ProgressStatus(
+  signInType,          // string — matches the mobile app's sign-in type
+  { regcode: 'XYZ' }, // customData — must include regcode
+)
+```
+
+#### `SuccessStatus`
+
+Signals a successful sign-in. `customData.email` is **required** to trigger the success UI.
+
+```typescript
+new SuccessStatus(
+  signInType,                         // string
+  'user-id-123',                      // userId (optional)
+  { email: 'user@example.com' },      // customData — must include email
+)
+```
+
+#### `FailureStatus`
+
+Signals a failed or cancelled sign-in.
+
+```typescript
+new FailureStatus(
+  signInType,          // string
+  false,               // isCancelled
+  'Reason string',     // reason (optional)
+  new Error('...'),    // exception (optional)
+  { key: 'value' },   // customData (optional)
+)
+```
+
+---
+
+### `VizbeeHomeSSOUIManager`
+
+Retrieved via `HomeSSOContext.getInstance().getHomeSSOUIManager()`.
+
+Controls the appearance of the three snackbar states: **informational** (sign-in requested), **progress** (sign-in underway), and **success** (sign-in complete).
+
+#### Apply a theme
+
+```typescript
+import type { VizbeeHomeSSOTheme } from '@vizbeetv/homesso-sdk-qa';
+
+uiManager.setTheme({
+  primaryColor: '#1a1a2e',
+  secondaryColor: '#16213e',
+  tertiaryColor: '#e94560',
+  subTextColor: '#ffffff',
+  primaryFont: 'Roboto, sans-serif',
+  direction: 'ltr',                  // 'ltr' | 'rtl'
+});
+```
+
+Default theme:
+
+| Property | Default |
+|---|---|
+| `primaryColor` | `#000000` |
+| `secondaryColor` | `#262626` |
+| `tertiaryColor` | `#FFFFFF` |
+| `subTextColor` | `undefined` (inherits tertiary) |
+| `direction` | `ltr` |
+
+#### Override common modal options
+
+```typescript
+uiManager.setCommonModalConfig({
+  borderRadius: '16px',
+  borderWidth: '2px',
+  boxShadow: '0 0 20px rgba(0, 200, 83, 0.6)',
+  width: '480px',
+  padding: '24px',
+  iconWidth: '64px',
+  iconHeight: '64px',
+});
+```
+
+#### Override per-state modal options
+
+```typescript
+uiManager.setInformationalSignInModalConfig({
+  titleText: 'Sign in with your phone',
+  descriptionText: 'Open the app on your mobile device to continue.',
+  position: 'bottom-right',
+  iconBase64String: '<your-base64-icon>',
+});
+
+uiManager.setProgressSignInModalConfig({
+  descriptionText: 'Signing you in…',
+  position: 'bottom-right',
+});
+
+uiManager.setSuccessSignInModalConfig({
+  titleText: 'Welcome!',
+  descriptionText: 'Sign-in successful. Start watching.',
+  duration: 5000,
+  position: 'bottom-right',
+});
+```
+
+Default modal copy:
+
+| State | Title | Description |
+|---|---|---|
+| Informational | `Mobile Sign In` | `Please use your mobile app to complete the sign in process.` |
+| Progress | _(none)_ | `Signing in using your mobile app ...` |
+| Success | `Mobile Sign In Successful!` | `Cast or select any content to start watching.` |
+
+---
+
+### Logging
+
+```typescript
+import { LogLevel } from '@vizbeetv/homesso-sdk-qa';
+
+const context = HomeSSOContext.getInstance();
+
+context.enableLogger(true);
+context.setLoggerLevel(LogLevel.DEBUG);
+```
+
+| `LogLevel` | Value | Description |
+|---|---|---|
+| `ERROR` | 0 | Critical errors |
+| `WARN` | 1 | Non-fatal warnings |
+| `INFO` | 2 | General operational info |
+| `DEBUG` | 3 | Detailed diagnostics |
+| `TRACE` | 4 | Verbose execution flow |
+
+---
+
+## TypeScript types
+
+All public types are exported from the package root:
+
+```typescript
+import type {
+  VizbeeSignInInfo,
+  VizbeeSignInStatusCallback,
+  MessagePayload,
+  VizbeeSenderDevice,
+  IVizbeeMessagingClient,
+  IVizbeeSession,
+  IVizbeeBicastSessionManager,
+  ISessionStateListener,
+  IVizbeeAnalyticsProvider,
+  IVizbeeXMessages,
+  VizbeeHomeSSOTheme,
+  CommonModalPreferenceOptions,
+  InformationalSignInPreferenceOptions,
+  ProgressSignInPreferenceOptions,
+  SuccessSignInPreferenceOptions,
+} from '@vizbeetv/homesso-sdk-qa';
+```
+
+---
+
+## License
+
+MIT