From d147c2ae908e13b3eaceb2543a340a386a720704 Mon Sep 17 00:00:00 2001 From: prosdevlab Date: Fri, 26 Dec 2025 01:29:59 -0800 Subject: [PATCH 1/5] fix: replace workspace:* with actual version for plugins dependency Fixes npm install error where workspace protocol doesn't work in published packages. Bump version to 0.1.1. --- packages/core/package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/core/package.json b/packages/core/package.json index 427e0ff..5a5b299 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -1,6 +1,6 @@ { "name": "@prosdevlab/experience-sdk", - "version": "0.1.0", + "version": "0.1.1", "description": "A lightweight, explainable client-side experience runtime", "private": false, "type": "module", @@ -45,7 +45,7 @@ "dependencies": { "@lytics/sdk-kit": "^0.1.1", "@lytics/sdk-kit-plugins": "^0.1.2", - "@prosdevlab/experience-sdk-plugins": "workspace:*" + "@prosdevlab/experience-sdk-plugins": "^0.1.0" }, "devDependencies": { "@types/node": "^24.0.0", From 5c3be9722a43c6a0047bc47f33594e15e66d5726 Mon Sep 17 00:00:00 2001 From: prosdevlab Date: Fri, 26 Dec 2025 01:32:13 -0800 Subject: [PATCH 2/5] chore: add changeset for v0.1.1 --- .changeset/v0-1-1-fixes.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 .changeset/v0-1-1-fixes.md diff --git a/.changeset/v0-1-1-fixes.md b/.changeset/v0-1-1-fixes.md new file mode 100644 index 0000000..1e7fe80 --- /dev/null +++ b/.changeset/v0-1-1-fixes.md @@ -0,0 +1,10 @@ +--- +"@prosdevlab/experience-sdk": patch +--- + +Fix workspace dependency protocol causing npm install errors. Add README and improve workflows. + +- Fix: Replace `workspace:*` with `^0.1.0` for plugins dependency +- Add: README with installation instructions and examples +- Fix: Remove pnpm version conflicts in GitHub workflows + From d7a28c63668b1a1c2959afa4cd2927ceee01bc7a Mon Sep 17 00:00:00 2001 From: prosdevlab Date: Fri, 26 Dec 2025 01:39:41 -0800 Subject: [PATCH 3/5] chore: revert to workspace protocol, let changesets handle conversion Changeset will automatically convert workspace:* to proper version during publish. --- .changeset/v0-1-1-fixes.md | 9 ++++++--- packages/core/package.json | 4 ++-- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/.changeset/v0-1-1-fixes.md b/.changeset/v0-1-1-fixes.md index 1e7fe80..9af11f7 100644 --- a/.changeset/v0-1-1-fixes.md +++ b/.changeset/v0-1-1-fixes.md @@ -2,9 +2,12 @@ "@prosdevlab/experience-sdk": patch --- -Fix workspace dependency protocol causing npm install errors. Add README and improve workflows. +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. -- Fix: Replace `workspace:*` with `^0.1.0` for plugins dependency - Add: README with installation instructions and examples -- Fix: Remove pnpm version conflicts in GitHub workflows +- Add: READMEs for plugins package +- Fix: pnpm version conflicts in GitHub workflows +- Add: Release banner to docs homepage diff --git a/packages/core/package.json b/packages/core/package.json index 5a5b299..427e0ff 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -1,6 +1,6 @@ { "name": "@prosdevlab/experience-sdk", - "version": "0.1.1", + "version": "0.1.0", "description": "A lightweight, explainable client-side experience runtime", "private": false, "type": "module", @@ -45,7 +45,7 @@ "dependencies": { "@lytics/sdk-kit": "^0.1.1", "@lytics/sdk-kit-plugins": "^0.1.2", - "@prosdevlab/experience-sdk-plugins": "^0.1.0" + "@prosdevlab/experience-sdk-plugins": "workspace:*" }, "devDependencies": { "@types/node": "^24.0.0", From 12155efd286663c570dd75dca3c4b3e69e236b1d Mon Sep 17 00:00:00 2001 From: prosdevlab Date: Fri, 26 Dec 2025 01:42:30 -0800 Subject: [PATCH 4/5] docs: add READMEs for npm packages --- docs/components/ReleaseBanner.tsx | 43 +++++++++ docs/content/latest-version.ts | 19 ++++ docs/pages/index.mdx | 4 + packages/core/README.md | 147 ++++++++++++++++++++++++++++++ packages/plugins/README.md | 125 +++++++++++++++++++++++++ 5 files changed, 338 insertions(+) create mode 100644 docs/components/ReleaseBanner.tsx create mode 100644 docs/content/latest-version.ts create mode 100644 packages/core/README.md create mode 100644 packages/plugins/README.md diff --git a/docs/components/ReleaseBanner.tsx b/docs/components/ReleaseBanner.tsx new file mode 100644 index 0000000..bdb199a --- /dev/null +++ b/docs/components/ReleaseBanner.tsx @@ -0,0 +1,43 @@ +import { latestVersion } from '../content/latest-version'; + +export function ReleaseBanner() { + return ( +
+
+ 🎉 v{latestVersion.version} Released! +
+
+ {latestVersion.summary} +
+
+ {latestVersion.features.map((feature, i) => ( + + {i > 0 && ' • '} + {feature} + + ))} +
+
+ + npm install @prosdevlab/experience-sdk + +
+
+ ); +} diff --git a/docs/content/latest-version.ts b/docs/content/latest-version.ts new file mode 100644 index 0000000..4cf44a4 --- /dev/null +++ b/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; diff --git a/docs/pages/index.mdx b/docs/pages/index.mdx index 2963eee..100b303 100644 --- a/docs/pages/index.mdx +++ b/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). + + ## Key Features - **Explainability-First** - Every decision returns structured reasons diff --git a/packages/core/README.md b/packages/core/README.md new file mode 100644 index 0000000..d9e1631 --- /dev/null +++ b/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 + +``` + +## 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 + + +``` + +## 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 + diff --git a/packages/plugins/README.md b/packages/plugins/README.md new file mode 100644 index 0000000..47d4cb3 --- /dev/null +++ b/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 + From 8d72486338278a8e176e2220b1e9a1e429fe3d39 Mon Sep 17 00:00:00 2001 From: prosdevlab Date: Fri, 26 Dec 2025 01:46:04 -0800 Subject: [PATCH 5/5] fix: remove pnpm version from workflows to use packageManager field --- .github/workflows/ci.yml | 4 +--- .github/workflows/docs.yml | 2 -- .github/workflows/release.yml | 2 +- 3 files changed, 2 insertions(+), 6 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 95b106f..f640021 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 94822bb..80906fe 100644 --- a/.github/workflows/docs.yml +++ b/.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 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 30a7ed1..50ad855 100644 --- a/.github/workflows/release.yml +++ b/.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