Skip to content

README.md

Latest commit

 

History

History
402 lines (306 loc) · 9.61 KB

README.md

File metadata and controls

402 lines (306 loc) · 9.61 KB

@prosdevlab/sdk-kit-plugins

npm version npm downloads License: MIT

Essential plugins for SDK Kit providing battle-tested functionality for modern web SDKs.

Overview

This package contains 6 essential plugins that cover common SDK needs:

  • Storage - Multi-backend storage (localStorage, sessionStorage, cookies, memory)
  • Consent - GDPR/CCPA consent management with platform adapters
  • Context - Automatic page, device, screen, and environment context collection
  • Poll - Promise-based async polling utilities
  • Queue - Event batching and queuing with persistence
  • Transport - HTTP transport abstraction with retry logic

Installation

npm install @prosdevlab/sdk-kit @prosdevlab/sdk-kit-plugins

Quick Start

import { SDK } from '@prosdevlab/sdk-kit';
import { 
  storagePlugin,
  consentPlugin,
  contextPlugin,
  pollPlugin,
  queuePlugin,
  transportPlugin
} from '@prosdevlab/sdk-kit-plugins';

const sdk = new SDK();

// Use all plugins
sdk.use(storagePlugin);
sdk.use(consentPlugin);
sdk.use(contextPlugin);
sdk.use(pollPlugin);
sdk.use(queuePlugin);
sdk.use(transportPlugin);

// Initialize
await sdk.init({
  storage: {
    namespace: 'myapp',
    defaultBackend: 'localStorage'
  },
  consent: {
    categories: {
      analytics: 'pending',
      marketing: 'pending'
    },
    persist: true
  },
  queue: {
    maxSize: 50,
    flushInterval: 5000
  },
  transport: {
    retries: 3,
    timeout: 5000
  }
});

Individual Plugin Imports

You can also import plugins individually for better tree-shaking:

// Import specific plugins
import { storagePlugin } from '@prosdevlab/sdk-kit-plugins/storage';
import { consentPlugin } from '@prosdevlab/sdk-kit-plugins/consent';
import { contextPlugin } from '@prosdevlab/sdk-kit-plugins/context';
import { pollPlugin } from '@prosdevlab/sdk-kit-plugins/poll';
import { queuePlugin } from '@prosdevlab/sdk-kit-plugins/queue';
import { transportPlugin } from '@prosdevlab/sdk-kit-plugins/transport';

Plugins

Storage Plugin

Multi-backend storage with TTL, namespacing, and JSON serialization.

import { storagePlugin } from '@prosdevlab/sdk-kit-plugins';

sdk.use(storagePlugin);

// Use storage
sdk.storage.set('key', 'value', { backend: 'localStorage', ttl: 3600 });
const value = sdk.storage.get('key');
sdk.storage.remove('key');

Features:

  • Multiple backends (localStorage, sessionStorage, cookies, memory)
  • Automatic TTL expiration
  • Namespace isolation
  • JSON serialization
  • Graceful degradation

Full Documentation

Consent Plugin

State-based consent management with platform adapters for OneTrust, Cookiebot, and Usercentrics.

import { consentPlugin } from '@prosdevlab/sdk-kit-plugins';

sdk.use(consentPlugin);

// Check consent
if (sdk.consent.isGranted('analytics')) {
  // Track analytics
}

// Wait for consent
const granted = await sdk.consent.waitForConsent('marketing', { timeout: 5000 });

// Update consent
sdk.consent.grant(['analytics', 'marketing']);
sdk.consent.deny('social');

Features:

  • Category-based consent (necessary, functional, analytics, marketing, social)
  • Inferred consent (reduces banner fatigue)
  • Platform adapters (OneTrust, Cookiebot, Usercentrics)
  • Promise-based waitForConsent() API
  • Cookie/localStorage persistence
  • Nuclear opt-out with revoke()
  • Metadata tracking and policy versioning

Full Documentation

Context Plugin

Automatic collection of page, device, screen, and environment context.

import { contextPlugin } from '@prosdevlab/sdk-kit-plugins';

sdk.use(contextPlugin);

// Collect all context
const context = sdk.context.collect();
// { page, device, screen, environment }

// Individual collectors
const page = sdk.context.getPage();
const device = sdk.context.getDevice();
const screen = sdk.context.getScreen();
const env = sdk.context.getEnvironment();

Features:

  • Page context (URL, path, query params, referrer, title, session)
  • Device context (type, user agent)
  • Screen context (dimensions)
  • Environment context (timezone, language, cookies, DNT, storage)
  • Privacy-first query parameter handling (UTM-only by default)
  • External referrer filtering
  • Cookie-based session detection
  • Caching with manual refresh

Full Documentation

Poll Plugin

Promise-based async polling for DOM elements, globals, or custom conditions.

import { pollPlugin } from '@prosdevlab/sdk-kit-plugins';

sdk.use(pollPlugin);

// Poll for DOM element
await sdk.poll.element('#my-element');

// Poll for global variable
await sdk.poll.global('myLib');

// Custom condition
await sdk.poll.waitFor(
  () => document.readyState === 'complete',
  { interval: 100, timeout: 5000 }
);

Features:

  • Promise-based API (modern async/await)
  • Immediate check (no delay on first attempt)
  • Configurable interval and timeout
  • Event emission (poll:start, poll:success, poll:timeout)
  • Lifecycle integration (cleanup on destroy)
  • Convenience methods for DOM and globals

Full Documentation

Queue Plugin

Event batching and queuing with automatic flushing, persistence, and retry support.

import { queuePlugin } from '@prosdevlab/sdk-kit-plugins';

sdk.use(queuePlugin);

// Add items to queue
sdk.queue.add({ event: 'click', target: 'button' });

// Manual flush
sdk.queue.flush();

// Queue auto-flushes when maxSize or flushInterval reached
sdk.on('queue:flush', (items) => {
  // Send items via transport
  sdk.transport.fetch('/events', {
    method: 'POST',
    body: JSON.stringify(items)
  });
});

Features:

  • Auto-flush based on size or interval
  • Persistence to storage (survives page reloads)
  • FIFO limiting when maxQueueSize reached
  • Lifecycle integration (flush on destroy)
  • Event emission (queue:add, queue:flush, queue:error)
  • beforeunload handling (flush before page unload)

Full Documentation

Transport Plugin

HTTP transport abstraction with automatic transport selection, retry logic, and hooks.

import { transportPlugin } from '@prosdevlab/sdk-kit-plugins';

sdk.use(transportPlugin);

// Fetch transport (modern, default)
await sdk.transport.fetch('/api/events', {
  method: 'POST',
  body: JSON.stringify({ event: 'pageview' })
});

// Beacon transport (for unload events)
sdk.transport.beacon('/api/events', {
  event: 'page_exit'
});

// XHR transport (fallback for older browsers)
await sdk.transport.xhr('/api/events', {
  method: 'POST',
  body: JSON.stringify({ event: 'click' })
});

// Pixel transport (ultimate fallback)
sdk.transport.pixel('/api/track.gif?event=pageview');

Features:

  • Multiple transports (fetch, beacon, XHR, pixel)
  • Automatic transport selection
  • Retry logic with exponential backoff
  • Request/response hooks (beforeSend, afterSend)
  • Event emission (transport:success, transport:error, transport:retry)
  • Timeout handling

Full Documentation

Plugin Combinations

Plugins work together seamlessly:

Consent + Queue

// Queue events until consent is granted
sdk.queue.add({ event: 'pageview' });

sdk.on('queue:flush', async (items) => {
  // Only send if analytics consent granted
  if (sdk.consent.isGranted('analytics')) {
    await sdk.transport.fetch('/events', {
      method: 'POST',
      body: JSON.stringify(items)
    });
  }
});

Context + Transport

// Auto-attach context to every request
sdk.transport.configure({
  beforeSend: (request) => {
    const context = sdk.context.collect();
    return {
      ...request,
      body: JSON.stringify({
        ...JSON.parse(request.body || '{}'),
        context
      })
    };
  }
});

Poll + Queue

// Wait for third-party library, then initialize queue
await sdk.poll.global('AnalyticsLib');
sdk.use(queuePlugin); // Safe to use now

Browser Compatibility

All plugins support:

  • Modern browsers (Chrome, Firefox, Safari, Edge)
  • ES2015+ (transpile for older browsers if needed)
  • jsdom for testing

Individual plugin compatibility:

  • Storage: Graceful fallback to memory when storage unavailable
  • Consent: Cookie and localStorage fallback
  • Context: Works without browser APIs (returns defaults)
  • Poll: Requires setTimeout/DOM APIs
  • Queue: Requires storage for persistence
  • Transport: Fetch → Beacon → XHR → Pixel fallback

TypeScript

All plugins are fully typed. Import types alongside plugins:

import type { 
  StoragePlugin,
  ConsentPlugin,
  ContextPlugin,
  PollPlugin,
  QueuePlugin,
  TransportPlugin
} from '@prosdevlab/sdk-kit-plugins';

// Extended SDK interface
interface MySDK extends SDK {
  storage: StoragePlugin;
  consent: ConsentPlugin;
  context: ContextPlugin;
  poll: PollPlugin;
  queue: QueuePlugin;
  transport: TransportPlugin;
}

const sdk = new SDK() as MySDK;

Testing

All plugins include comprehensive unit tests. To run tests:

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run with coverage
pnpm test:coverage

License

MIT

Contributing

See CONTRIBUTING.md for guidelines.

Links