fix: v0.1.1 - workspace dependency and improvements

.changeset/v0-1-1-fixes.md

@@ -0,0 +1,13 @@
+---
+"@prosdevlab/experience-sdk": patch
+---
+
+Fix npm install error from v0.1.0. Add README and improve workflows.
+
+v0.1.0 was published with `workspace:*` dependency which doesn't work outside the monorepo. This release fixes that by letting changesets automatically convert it to the proper version range during publish.
+
+- Add: README with installation instructions and examples
+- Add: READMEs for plugins package
+- Fix: pnpm version conflicts in GitHub workflows
+- Add: Release banner to docs homepage
+

.github/workflows/ci.yml

@@ -18,9 +18,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@v3
-        with:
-          version: 10
+        uses: pnpm/action-setup@v4
 
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4

.github/workflows/docs.yml

@@ -32,8 +32,6 @@ jobs:
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
-        with:
-          version: 10
 
       - name: Get pnpm store directory
         shell: bash

.github/workflows/release.yml

@@ -39,7 +39,7 @@ jobs:
           fetch-depth: 0
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@v3
+        uses: pnpm/action-setup@v4
 
       - name: Setup Node.js
         uses: actions/setup-node@v4

docs/components/ReleaseBanner.tsx

@@ -0,0 +1,43 @@
+import { latestVersion } from '../content/latest-version';
+
+export function ReleaseBanner() {
+  return (
+    <div
+      style={{
+        background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+        color: 'white',
+        padding: '24px',
+        borderRadius: '12px',
+        marginTop: '24px',
+        marginBottom: '32px',
+      }}
+    >
+      <div style={{ fontSize: '24px', fontWeight: 'bold', marginBottom: '8px' }}>
+        🎉 v{latestVersion.version} Released!
+      </div>
+      <div style={{ fontSize: '16px', opacity: 0.95, marginBottom: '12px' }}>
+        {latestVersion.summary}
+      </div>
+      <div style={{ fontSize: '14px', opacity: 0.9 }}>
+        {latestVersion.features.map((feature, i) => (
+          <span key={i}>
+            {i > 0 && ' • '}
+            {feature}
+          </span>
+        ))}
+      </div>
+      <div style={{ marginTop: '16px', fontSize: '14px' }}>
+        <code
+          style={{
+            background: 'rgba(255,255,255,0.2)',
+            padding: '8px 12px',
+            borderRadius: '6px',
+            fontFamily: 'monospace',
+          }}
+        >
+          npm install @prosdevlab/experience-sdk
+        </code>
+      </div>
+    </div>
+  );
+}

docs/content/latest-version.ts

@@ -0,0 +1,19 @@
+/**
+ * Latest version information
+ * Update this file when releasing a new version
+ */
+
+export const latestVersion = {
+  version: '0.1.0',
+  title: 'Initial Release',
+  date: 'December 26, 2024',
+  summary:
+    'Experience SDK is now available on npm with multiple button variants, frequency capping, and responsive layout. Only 6.9 KB gzipped.',
+  features: [
+    'Multiple buttons with variants (primary, secondary, link)',
+    'Responsive layout (desktop inline, mobile stack)',
+    'Frequency capping per session/day/week',
+    'Complete TypeScript support',
+    'Only 6.9 KB gzipped',
+  ],
+} as const;

docs/pages/index.mdx

@@ -1,7 +1,11 @@
 # Experience SDK
 
+import { ReleaseBanner } from '../components/ReleaseBanner';
+
 A lightweight, explainable, plugin-based client-side experience runtime built on [@lytics/sdk-kit](https://github.com/Lytics/sdk-kit).
 
+<ReleaseBanner />
+
 ## Key Features
 
 - **Explainability-First** - Every decision returns structured reasons

packages/core/README.md

@@ -0,0 +1,147 @@
+# @prosdevlab/experience-sdk
+
+A lightweight, explainable client-side experience runtime built on [@lytics/sdk-kit](https://github.com/lytics/sdk-kit).
+
+**Size:** 6.9 KB gzipped (includes core + 3 plugins)
+
+## Features
+
+- **Explainability-First** - Every decision includes structured reasons
+- **Plugin-Based** - Built on sdk-kit's powerful plugin system
+- **Multiple Buttons** - Primary, secondary, and link variants
+- **Frequency Capping** - Control impression limits per session/day/week
+- **Responsive Layout** - Automatically adapts to mobile/desktop
+- **Script Tag Ready** - Works without build tools
+- **Type-Safe** - Full TypeScript support
+
+## Installation
+
+### npm
+
+```bash
+npm install @prosdevlab/experience-sdk
+```
+
+### Script Tag
+
+```html
+<script src="https://unpkg.com/@prosdevlab/experience-sdk/dist/experience-sdk.global.js"></script>
+```
+
+## Quick Start
+
+### For Bundlers (ESM)
+
+```typescript
+import { createInstance } from '@prosdevlab/experience-sdk';
+
+// Create instance
+const experiences = createInstance({ debug: true });
+
+// Initialize
+await experiences.init();
+
+// Register a banner
+experiences.register('welcome', {
+  type: 'banner',
+  targeting: {
+    url: { contains: '/' }
+  },
+  content: {
+    title: 'Welcome!',
+    message: 'Thanks for visiting.',
+    buttons: [
+      { text: 'Get Started', url: '/start', variant: 'primary' }
+    ]
+  },
+  frequency: {
+    max: 3,
+    per: 'session'
+  }
+});
+
+// Evaluate and show
+const decision = experiences.evaluate();
+console.log(decision.reasons);
+```
+
+### For Script Tag
+
+```html
+<script src="https://unpkg.com/@prosdevlab/experience-sdk/dist/experience-sdk.global.js"></script>
+<script>
+  // Global 'experiences' available
+  experiences.init({ debug: true });
+
+  experiences.register('cookie-consent', {
+    type: 'banner',
+    content: {
+      message: 'We use cookies to improve your experience',
+      buttons: [
+        { text: 'Accept', action: 'accept', variant: 'primary' },
+        { text: 'Reject', action: 'reject', variant: 'secondary' }
+      ],
+      position: 'bottom'
+    }
+  });
+
+  experiences.evaluate();
+</script>
+```
+
+## Multiple Buttons
+
+Banners support multiple buttons with visual variants:
+
+```typescript
+buttons: [
+  { text: 'Accept all', variant: 'primary', action: 'accept' },
+  { text: 'Reject', variant: 'secondary', action: 'reject' },
+  { text: 'Preferences', variant: 'link', url: '/preferences' }
+]
+```
+
+- **primary** - Blue button for main actions
+- **secondary** - Gray outlined button for secondary actions
+- **link** - Text link style for tertiary actions
+
+## Events
+
+Listen to experience interactions:
+
+```typescript
+// Banner shown
+experiences.on('experiences:shown', ({ experienceId }) => {
+  console.log('Shown:', experienceId);
+});
+
+// Button clicked
+experiences.on('experiences:action', ({ experienceId, action, variant, metadata }) => {
+  analytics.track('Experience Action', { experienceId, action });
+});
+
+// Banner dismissed
+experiences.on('experiences:dismissed', ({ experienceId }) => {
+  console.log('Dismissed:', experienceId);
+});
+```
+
+## Included Plugins
+
+This package includes three official plugins:
+
+- **Banner Plugin** - DOM rendering with responsive layout
+- **Frequency Plugin** - Impression tracking and capping
+- **Debug Plugin** - Logging and window events
+
+## Documentation
+
+- [Full Documentation](https://prosdevlab.github.io/experience-sdk)
+- [API Reference](https://prosdevlab.github.io/experience-sdk/reference)
+- [Plugins Guide](https://prosdevlab.github.io/experience-sdk/reference/plugins)
+- [Examples](https://prosdevlab.github.io/experience-sdk/demo)
+
+## License
+
+MIT
+

packages/plugins/README.md

@@ -0,0 +1,125 @@
+# @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
+
+```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
+  }
+});
+```
+
+### 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
+