diff --git a/.changeset/v0-1-1-fixes.md b/.changeset/v0-1-1-fixes.md new file mode 100644 index 0000000..9af11f7 --- /dev/null +++ b/.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 + 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 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 +