@prosdevlab/experience-sdk-plugins 0.1.0 → 0.1.4

package/.turbo/turbo-build.log

@@ -0,0 +1,17 @@
+
+> @prosdevlab/experience-sdk-plugins@0.1.4 build /home/runner/work/experience-sdk/experience-sdk/packages/plugins
+> tsup
+
+CLI Building entry: src/index.ts
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.1
+CLI Using tsup config: /home/runner/work/experience-sdk/experience-sdk/packages/plugins/tsup.config.ts
+CLI Target: es2024
+CLI Cleaning output folder
+ESM Build start
+ESM dist/index.js     19.53 KB
+ESM dist/index.js.map 48.09 KB
+ESM ⚡️ Build success in 140ms
+DTS Build start
+DTS ⚡️ Build success in 857ms
+DTS dist/index.d.ts 5.46 KB

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# @prosdevlab/experience-sdk-plugins
+
+## 0.1.4
+
+### Patch Changes
+
+- df2c286: feat(banner): add pushDown option to push content down instead of overlay
+
+  Add optional `pushDown` config to banner plugin that allows top banners to smoothly push page content down (add margin-top) instead of overlaying it.
+
+  **Usage:**
+
+  ```typescript
+  init({
+    banner: {
+      position: "top",
+      pushDown: "header", // CSS selector of element to push down
+    },
+  });
+  ```
+
+  **Benefits:**
+
+  - Opt-in feature (default behavior unchanged)
+  - Smooth transition with CSS animations
+  - Improves UX for sticky navigation
+  - Automatically removes margin when banner is dismissed
+
+## 0.1.3
+
+### Patch Changes
+
+- 41c0aa5: Fix npm publishing error by adding repository field to package.json
+
+  - Add repository field required for npm provenance verification
+
+## 0.1.2
+
+### Patch Changes
+
+- a6842e2: Fix npm publishing error by adding repository field to package.json
+
+  - Add repository field required for npm provenance verification
+
+## 0.1.1
+
+### Patch Changes
+
+- c5e46c0: Fix BannerContent type definition, add CSS customization support, and implement HTML sanitization:
+
+  - Add `buttons` array property with variant and metadata support
+  - Add `position` property (top/bottom)
+  - Make `title` optional (message is the only required field)
+  - Add `className` and `style` props for banner and buttons
+  - Update banner plugin to use `.xp-*` CSS classes
+  - Provide minimal, functional default styles
+  - Add HTML sanitizer for XSS prevention in title and message fields
+  - Support safe HTML tags (strong, em, a, br, span, b, i, p)
+  - Block dangerous tags and event handlers
+  - Sanitize URLs to prevent javascript: and data: attacks
+  - Aligns core types with banner plugin implementation
+
+  This enables users to customize banners with Tailwind, design systems, or CSS frameworks while maintaining SDK's focus on targeting logic. HTML sanitization ensures safe rendering of user-provided content.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 prosdevlab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# @prosdevlab/experience-sdk-plugins
+
+Official plugins for [Experience SDK](https://github.com/prosdevlab/experience-sdk).
+
+**Size:** 13.4 KB (ESM)
+
+## Included Plugins
+
+### Banner Plugin
+
+Renders banner experiences in the DOM with automatic positioning, theming, and responsive layout.
+
+**Features:**
+- Multiple buttons with variants (primary, secondary, link)
+- Responsive layout (desktop inline, mobile stack)
+- Automatic theme detection (light/dark mode)
+- Top/bottom positioning
+- Dismissable with close button
+- **CSS customization** via `className` and `style` props
+- Stable `.xp-*` CSS classes for styling
+
+```typescript
+import { createInstance, bannerPlugin } from '@prosdevlab/experience-sdk-plugins';
+
+const sdk = createInstance();
+sdk.use(bannerPlugin);
+
+sdk.banner.show({
+  id: 'welcome',
+  type: 'banner',
+  content: {
+    title: 'Welcome!',
+    message: 'Thanks for visiting.',
+    buttons: [
+      { text: 'Get Started', url: '/start', variant: 'primary' }
+    ],
+    position: 'top',
+    dismissable: true
+  }
+});
+```
+
+**Customization:**
+
+The banner plugin uses `.xp-*` CSS classes and supports custom styling:
+
+```typescript
+// With Tailwind
+content: {
+  message: 'Flash Sale!',
+  className: 'bg-gradient-to-r from-blue-600 to-purple-600 text-white',
+  buttons: [{
+    text: 'Shop Now',
+    className: 'bg-white text-blue-600 hover:bg-gray-100'
+  }]
+}
+
+// With inline styles
+content: {
+  message: 'Flash Sale!',
+  style: {
+    background: 'linear-gradient(90deg, #667eea 0%, #764ba2 100%)',
+    color: 'white'
+  }
+}
+```
+
+See the [Plugins documentation](https://prosdevlab.github.io/experience-sdk/reference/plugins#customization) for more customization examples.
+
+### Frequency Plugin
+
+Manages impression tracking and frequency capping with persistent storage.
+
+**Features:**
+- Session/day/week impression tracking
+- Automatic storage management
+- Manual impression recording
+- Reset capabilities
+
+```typescript
+import { createInstance, frequencyPlugin } from '@prosdevlab/experience-sdk-plugins';
+
+const sdk = createInstance();
+sdk.use(frequencyPlugin);
+
+// Check impression count
+const count = sdk.frequency.getImpressionCount('welcome', 'session');
+
+// Record impression
+sdk.frequency.recordImpression('welcome');
+
+// Reset counts
+sdk.frequency.reset('welcome');
+```
+
+### Debug Plugin
+
+Provides console logging and window event emission for debugging and Chrome extension integration.
+
+**Features:**
+- Console logging with prefix
+- Window event emission
+- Automatic decision logging
+- Configurable logging levels
+
+```typescript
+import { createInstance, debugPlugin } from '@prosdevlab/experience-sdk-plugins';
+
+const sdk = createInstance({ debug: true });
+sdk.use(debugPlugin);
+
+// Manual logging
+sdk.debug.log('Custom message', { foo: 'bar' });
+
+// Listen to debug events
+window.addEventListener('experiences:debug', (event) => {
+  console.log(event.detail);
+});
+```
+
+## Installation
+
+```bash
+npm install @prosdevlab/experience-sdk-plugins
+```
+
+Or use the main package which includes these plugins:
+
+```bash
+npm install @prosdevlab/experience-sdk
+```
+
+## Usage
+
+These plugins are automatically included when using `@prosdevlab/experience-sdk`. You only need this package if you want to use the plugins separately with a custom sdk-kit setup.
+
+```typescript
+import { createInstance } from '@prosdevlab/experience-sdk';
+
+// Plugins are already included and available
+const experiences = createInstance({ debug: true });
+experiences.register('banner', { ... });
+```
+
+## Documentation
+
+- [Full Documentation](https://prosdevlab.github.io/experience-sdk)
+- [Plugins Guide](https://prosdevlab.github.io/experience-sdk/reference/plugins)
+- [Banner Examples](https://prosdevlab.github.io/experience-sdk/demo/banner)
+
+## License
+
+MIT
+

package/dist/index.d.ts

@@ -0,0 +1,230 @@
+import { PluginFunction } from '@lytics/sdk-kit';
+
+/**
+ * Shared types for Experience SDK plugins
+ * These types are re-exported by core for user convenience
+ */
+/**
+ * Experience content - varies by type
+ */
+type ExperienceContent = BannerContent | ModalContent | TooltipContent;
+/**
+ * Banner content configuration
+ */
+interface BannerContent {
+    title?: string;
+    message: string;
+    buttons?: Array<{
+        text: string;
+        action?: string;
+        url?: string;
+        variant?: 'primary' | 'secondary' | 'link';
+        metadata?: Record<string, any>;
+        className?: string;
+        style?: Record<string, string>;
+    }>;
+    dismissable?: boolean;
+    position?: 'top' | 'bottom';
+    className?: string;
+    style?: Record<string, string>;
+}
+/**
+ * Modal content configuration
+ */
+interface ModalContent {
+    title: string;
+    message: string;
+    confirmText?: string;
+    cancelText?: string;
+}
+/**
+ * Modal content configuration
+ */
+interface ModalContent {
+    title: string;
+    message: string;
+    confirmText?: string;
+    cancelText?: string;
+}
+/**
+ * Tooltip content configuration
+ */
+interface TooltipContent {
+    message: string;
+    position?: 'top' | 'bottom' | 'left' | 'right';
+}
+/**
+ * Tooltip content configuration
+ */
+interface TooltipContent {
+    message: string;
+    position?: 'top' | 'bottom' | 'left' | 'right';
+}
+/**
+ * Experience definition
+ */
+interface Experience {
+    id: string;
+    type: 'banner' | 'modal' | 'tooltip';
+    targeting: Record<string, any>;
+    content: ExperienceContent;
+    frequency?: {
+        max: number;
+        per: 'session' | 'day' | 'week';
+    };
+    priority?: number;
+}
+/**
+ * Decision output from evaluation
+ */
+interface Decision {
+    show: boolean;
+    experienceId?: string;
+    reasons: string[];
+    trace: TraceStep[];
+    context: Record<string, any>;
+    metadata: DecisionMetadata;
+}
+/**
+ * Trace step for decision path
+ */
+interface TraceStep {
+    step: string;
+    timestamp: number;
+    duration: number;
+    input?: any;
+    output?: any;
+    passed: boolean;
+}
+/**
+ * Decision metadata
+ */
+interface DecisionMetadata {
+    evaluatedAt: number;
+    experienceCount: number;
+    evaluationTimeMs: number;
+}
+
+/**
+ * Banner Plugin
+ *
+ * Renders banner experiences at the top or bottom of the page.
+ * Auto-shows banners when experiences are evaluated.
+ */
+
+interface BannerPluginConfig {
+    banner?: {
+        position?: 'top' | 'bottom';
+        dismissable?: boolean;
+        zIndex?: number;
+        pushDown?: string;
+    };
+}
+interface BannerPlugin {
+    show(experience: Experience): void;
+    remove(): void;
+    isShowing(): boolean;
+}
+/**
+ * Banner Plugin
+ *
+ * Automatically renders banner experiences when they are evaluated.
+ *
+ * @example
+ * ```typescript
+ * import { createInstance } from '@prosdevlab/experience-sdk';
+ * import { bannerPlugin } from '@prosdevlab/experience-sdk-plugins';
+ *
+ * // Basic usage (banner overlays at top)
+ * const sdk = createInstance({
+ *   banner: {
+ *     position: 'top',
+ *     dismissable: true
+ *   }
+ * });
+ * sdk.use(bannerPlugin);
+ *
+ * // With pushDown (pushes navigation down instead of overlaying)
+ * const sdk = createInstance({
+ *   banner: {
+ *     position: 'top',
+ *     dismissable: true,
+ *     pushDown: 'header' // CSS selector of element to push down
+ *   }
+ * });
+ * sdk.use(bannerPlugin);
+ * ```
+ */
+declare const bannerPlugin: PluginFunction;
+
+/**
+ * Debug Plugin
+ *
+ * Emits structured debug events to window and optionally logs to console.
+ * Useful for debugging and Chrome extension integration.
+ */
+
+interface DebugPluginConfig {
+    debug?: {
+        enabled?: boolean;
+        console?: boolean;
+        window?: boolean;
+    };
+}
+interface DebugPlugin {
+    log(message: string, data?: unknown): void;
+    isEnabled(): boolean;
+}
+/**
+ * Debug Plugin
+ *
+ * Listens to all SDK events and emits them as window events for debugging.
+ * Also optionally logs to console.
+ *
+ * @example
+ * ```typescript
+ * import { createInstance } from '@prosdevlab/experience-sdk';
+ * import { debugPlugin } from '@prosdevlab/experience-sdk-plugins';
+ *
+ * const sdk = createInstance({ debug: { enabled: true, console: true } });
+ * sdk.use(debugPlugin);
+ * ```
+ */
+declare const debugPlugin: PluginFunction;
+
+/**
+ * Frequency Capping Plugin
+ *
+ * Tracks experience impressions and enforces frequency caps.
+ * Uses sdk-kit's storage plugin for persistence.
+ */
+
+interface FrequencyPluginConfig {
+    frequency?: {
+        enabled?: boolean;
+        namespace?: string;
+    };
+}
+interface FrequencyPlugin {
+    getImpressionCount(experienceId: string): number;
+    hasReachedCap(experienceId: string, max: number, per: 'session' | 'day' | 'week'): boolean;
+    recordImpression(experienceId: string): void;
+}
+/**
+ * Frequency Capping Plugin
+ *
+ * Automatically tracks impressions and enforces frequency caps.
+ * Requires storage plugin for persistence.
+ *
+ * @example
+ * ```typescript
+ * import { createInstance } from '@prosdevlab/experience-sdk';
+ * import { frequencyPlugin } from '@prosdevlab/experience-sdk-plugins';
+ *
+ * const sdk = createInstance({ frequency: { enabled: true } });
+ * sdk.use(frequencyPlugin);
+ * ```
+ */
+declare const frequencyPlugin: PluginFunction;
+
+export { type BannerContent, type BannerPlugin, type BannerPluginConfig, type DebugPlugin, type DebugPluginConfig, type Decision, type DecisionMetadata, type Experience, type ExperienceContent, type FrequencyPlugin, type FrequencyPluginConfig, type ModalContent, type TooltipContent, type TraceStep, bannerPlugin, debugPlugin, frequencyPlugin };