@returningai/widget-sdk 1.5.0 → 1.6.0

package/dist/types/BaseWidget.d.ts

@@ -17,6 +17,7 @@ export declare abstract class BaseWidget extends HTMLElement {
     private initGeneration;
     private lottieInstances;
     private callbackRegistry;
+    private bannerNode;
     constructor();
     registerCallback(callbackName: string, callback: ReturningAIWidgetCallback): void;
     lockCallbacks(): void;
@@ -92,6 +93,15 @@ export declare abstract class BaseWidget extends HTMLElement {
     private deferLoaderRemovalUntilReactPaints;
     private showError;
     private renderCustomError;
+    private resolveBannerApiUrl;
+    private removeBanner;
+    /**
+     * After the widget mounts, fetch + render any eligible sdk-surface banner
+     * targeted at this widget type. Core widgets send their communityId + type;
+     * custom widgets send the decoded widget id so the server resolves the precise
+     * sub-type + community. Best-effort: never throws into the host page.
+     */
+    private mountBannerForWidget;
     private init;
     private isCurrentInit;
     private teardownMountedWidget;

package/dist/types/banner/BannerRuntime.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `<rai-banner>` — the external SDK runtime (M5).
+ *
+ * Drop-in custom element for partner sites. On connect it: mints/loads an
+ * anonymous visitor id, asks the eligibility engine for a banner on the `sdk`
+ * surface, renders it (overlay → portaled to <body>, inline → into a target or
+ * itself), and fires impression/click/dismiss tracking. Emits DOM events so the
+ * host page can react. Never throws into the host page.
+ *
+ * Attributes:
+ *   community-id   (required)  the community ObjectId
+ *   api-url        explicit API base (overrides domain-key)
+ *   domain-key     LOCAL | SGTR | STG | GEN  (default LOCAL)
+ *   surface        defaults to 'sdk'
+ *   page-path / page-hostname / page-url   override page context (default: window.location)
+ *   storage-prefix override the localStorage key prefix
+ *
+ * Events: rai-banner-impression | rai-banner-click | rai-banner-dismiss |
+ *         rai-banner-empty | rai-banner-error
+ */
+export declare class BannerRuntime extends HTMLElement {
+    private rendered;
+    private impressionFired;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private resolveApiUrl;
+    private device;
+    private init;
+    private mount;
+    private cleanup;
+    private dispatch;
+}

package/dist/types/banner/api.d.ts

@@ -0,0 +1,33 @@
+import type { BannerSurface, EligibilityResult } from './types';
+export interface EligibleRequest {
+    /** Optional when `widgetId` is supplied (custom widgets resolve community server-side). */
+    communityId?: string;
+    surface: BannerSurface;
+    /** Widget-type key for the sdk surface (e.g. 'channel', 'store'). */
+    widgetType?: string;
+    /** Custom-widget id (raw ObjectId) — server resolves its sub-type + community. */
+    widgetId?: string;
+    channelId?: string;
+    page?: {
+        url?: string;
+        hostname?: string;
+        path?: string;
+    };
+    viewport?: {
+        width: number;
+        height: number;
+        device: 'desktop' | 'tablet' | 'mobile';
+    };
+    identifier?: {
+        type: 'anonymous_session';
+        value: string;
+    };
+    /** SDK embed token — gates `access: 'domain' | 'authenticated'` banners server-side. */
+    embedToken?: string;
+}
+/**
+ * Calls the public eligibility endpoint. CORS is `origin: '*'` server-side, so a
+ * plain cross-origin `fetch` works from any embedding site. Returns
+ * `{ banner: null }` on any failure — the SDK must never throw into the host page.
+ */
+export declare function fetchEligibleBanner(apiUrl: string, request: EligibleRequest): Promise<EligibilityResult>;

package/dist/types/banner/render.d.ts

@@ -0,0 +1,12 @@
+import type { EligibleBanner } from "./types";
+export interface BannerHandlers {
+    onCtaClick: () => void;
+    onDismiss: () => void;
+}
+/**
+ * Builds the banner DOM (plain elements + inline styles, so it renders correctly
+ * on any host site without external CSS). Honors `placement.mode`:
+ *   overlay/popup → fixed centered card; inline → in-flow full-width bar.
+ * The caller decides where to attach it (body for overlay, target for inline).
+ */
+export declare function renderBanner(banner: EligibleBanner, handlers: BannerHandlers): HTMLElement;

package/dist/types/banner/sanitize.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Sanitize admin-authored banner HTML before injecting it into the host page.
+ *
+ * Mirrors the allow-list used by the in-app renderer (tradingroom banner-preview)
+ * and the M6 server-side sanitizer. With M6 the server is the primary gate; this
+ * is defense-in-depth on the client so a compromised/legacy response can never
+ * inject script into an embedding site.
+ */
+export declare function sanitizeBannerHtml(html: string | undefined): string;

package/dist/types/banner/session.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Anonymous visitor identity for the SDK surface.
+ *
+ * External sites have no logged-in user, so we mint a stable per-community UUID
+ * and persist it in localStorage (same `storagePrefix` convention as core/storage).
+ * This becomes the `anonymous_session` identifier the eligibility engine hashes —
+ * enabling per-visitor frequency caps and dismiss-memory without any PII.
+ */
+export declare function getOrCreateVisitorId(communityId: string, storagePrefix: string): string;

package/dist/types/banner/track.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Fire a signed tracking URL (impression / click / dismiss). These are one-time,
+ * HMAC-signed GET URLs from the eligibility response. An image beacon avoids a
+ * CORS preflight and survives navigation. Best-effort: tracking must never break
+ * rendering or throw into the host page.
+ */
+export declare function fireTracking(url: string | undefined): void;

package/dist/types/banner/types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Banner SDK runtime types — mirror the server's `RenderableBanner` contract
+ * (tradingroom `bannerEligibility.service.ts`). Kept in sync by hand; there is no
+ * shared types package between the two repos.
+ */
+export type BannerSurface = 'channel' | 'community' | 'sdk';
+export interface BannerPlacement {
+    mode: 'overlay' | 'inline' | 'popup';
+    position: 'top' | 'bottom' | 'center';
+    pushPage?: boolean;
+    targetSelector?: string | null;
+    insertion?: 'prepend' | 'append' | 'before' | 'after';
+    zIndex?: number;
+    mobileBehavior?: 'same' | 'bottom_overlay' | 'hide';
+}
+export interface BannerCta {
+    enabled: boolean;
+    label?: string;
+    url?: string;
+    openInNewTab?: boolean;
+    style?: Record<string, string>;
+    backgroundColor?: string;
+    buttonColor?: string;
+    textColor?: string;
+    color?: string;
+    position?: string;
+}
+export interface BannerImage {
+    desktopUrl?: string;
+    mobileUrl?: string;
+    format?: string;
+    linkUrl?: string;
+    openInNewTab?: boolean;
+    cornerRadius?: string;
+    horizontalAlignment?: 'left' | 'center' | 'right';
+    verticalAlignment?: 'top' | 'center' | 'bottom';
+}
+export interface BannerStyle {
+    backgroundColor?: string;
+    color?: string;
+}
+export interface BannerTracking {
+    impressionUrl: string;
+    clickUrl: string;
+    dismissUrl: string;
+}
+export interface EligibleBanner {
+    id: string;
+    communityId: string;
+    type: 'text' | 'image';
+    title?: string;
+    text?: string;
+    style?: BannerStyle;
+    cta?: BannerCta;
+    ctaStyle?: Record<string, string>;
+    image?: BannerImage;
+    placement: BannerPlacement;
+    tracking: BannerTracking;
+}
+export interface EligibilityResult {
+    banner: EligibleBanner | null;
+    reason?: string;
+    nextCheckAfterMs?: number;
+}

package/dist/types/banner-index.d.ts

@@ -0,0 +1,2 @@
+import { BannerRuntime } from './banner/BannerRuntime';
+export { BannerRuntime };

package/dist/types/jsx.d.ts

@@ -22,20 +22,32 @@ interface RaiWidgetAttributes {
   style?: string
 }
 
+type RaiWidgetElementAttributes = RaiWidgetAttributes & {
+  [attributeName: string]: unknown
+}
+
+interface RaiWidgetIntrinsicElements {
+  'rai-store-widget': RaiWidgetElementAttributes
+  'rai-channel-widget': RaiWidgetElementAttributes
+  'rai-milestone-widget': RaiWidgetElementAttributes
+  'rai-social-widget': RaiWidgetElementAttributes
+  'rai-currency-widget': RaiWidgetElementAttributes
+  'rai-referral-widget': RaiWidgetElementAttributes
+  'rai-custom-widget': RaiWidgetElementAttributes
+  'rai-widget': RaiWidgetElementAttributes // deprecated
+}
+
 // ── React ──────────────────────────────────────────────────────────────────
-declare namespace React {
-  namespace JSX {
-    interface IntrinsicElements {
-      'rai-store-widget':    React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & RaiWidgetAttributes
-      'rai-channel-widget':  React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & RaiWidgetAttributes
-      'rai-milestone-widget': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & RaiWidgetAttributes
-      'rai-social-widget':   React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & RaiWidgetAttributes
-      'rai-currency-widget':  React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & RaiWidgetAttributes
-      'rai-referral-widget': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & RaiWidgetAttributes
-      'rai-custom-widget':   React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & RaiWidgetAttributes
-      'rai-widget':          React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & RaiWidgetAttributes // deprecated
+declare global {
+  namespace React {
+    namespace JSX {
+      interface IntrinsicElements extends RaiWidgetIntrinsicElements {}
     }
   }
+
+  namespace JSX {
+    interface IntrinsicElements extends RaiWidgetIntrinsicElements {}
+  }
 }
 
 // ── Vue 3 (Volar / vue-tsc) ────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@returningai/widget-sdk",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Shadow DOM isolated widget SDK for ReturningAI",
   "main": "dist/rai-widget.iife.js",
   "module": "dist/rai-widget.js",
@@ -21,10 +21,15 @@
     "dev": "vite",
     "build": "vite build",
     "build:min": "vite build --mode production",
+    "build:banner": "vite build --config vite.banner.config.ts",
+    "build:banner:min": "vite build --config vite.banner.config.ts --mode production",
+    "build:all": "npm run build && npm run build:banner",
+    "build:all:min": "npm run build:min && npm run build:banner:min",
     "types": "tsc --emitDeclarationOnly --outDir dist/types && cp src/jsx.d.ts dist/types/jsx.d.ts",
-    "test": "npm run test:host-callback",
+    "test": "npm run test:host-callback && npm run test:jsx-types",
     "test:host-callback": "rm -rf test/.tmp && tsc -p test/tsconfig.json && node test/.tmp/test/postmessage-host-callback.test.js",
-    "prepublishOnly": "npm run build:min && npm run types"
+    "test:jsx-types": "tsc --noEmit --strict --lib ES2020,DOM --skipLibCheck false src/jsx.d.ts",
+    "prepublishOnly": "npm run build:all:min && npm run types"
   },
   "devDependencies": {
     "terser": "^5.46.0",
@@ -32,6 +37,7 @@
     "vite": "^5.1.0"
   },
   "dependencies": {
+    "dompurify": "^3.4.9",
     "lottie-web": "^5.13.0"
   }
 }