@sendmailos/sdk 1.1.0 → 1.1.1

package/README.md

@@ -33,7 +33,8 @@ await client.emails.send({
 
 - **Type-safe**: Full TypeScript support with exported types
 - **Lightweight**: Zero dependencies for core SDK
-- **React Components**: Pre-built components for common patterns
+- **Pixel Tracking**: Track website visitors and link to email campaigns
+- **React Components**: Pre-built components and hooks
 - **Webhook Verification**: Secure signature verification utilities
 - **Error Handling**: Custom error classes for different scenarios
 
@@ -101,6 +102,123 @@ const { domain } = await client.domains.create({
 console.log('DNS Records to add:', domain.dnsRecords);
 ```
 
+## Pixel Tracking
+
+Track website visitors and connect their behavior to email campaigns.
+
+### Basic Setup
+
+```typescript
+import { SendmailPixel } from '@sendmailos/sdk';
+
+const pixel = new SendmailPixel({
+  token: 'pk_live_your_public_key',
+  debug: false // Set true for console logging
+});
+
+pixel.init();
+```
+
+### Track Events
+
+```typescript
+// Track custom events
+pixel.track('button_clicked', { button_id: 'cta-signup' });
+
+// Track page views (called automatically on init)
+pixel.pageView();
+
+// Identify a visitor by email
+pixel.identify('user@example.com', {
+  first_name: 'John',
+  plan: 'premium'
+});
+```
+
+### Privacy Controls
+
+```typescript
+// Opt out of tracking (e.g., user declines cookies)
+pixel.optOut();
+
+// Opt back in
+pixel.optIn();
+
+// Check opt-out status
+if (pixel.isOptedOut()) {
+  console.log('Tracking disabled');
+}
+
+// Reset identity (e.g., on logout)
+pixel.reset();
+```
+
+### Global smp() Function
+
+For script tag usage, use `createGlobalPixel` to set up a global `smp()` function:
+
+```typescript
+import { createGlobalPixel } from '@sendmailos/sdk';
+
+createGlobalPixel({ token: 'pk_live_...' });
+
+// Now use anywhere:
+smp('track', 'event_name', { property: 'value' });
+smp('identify', 'user@example.com');
+smp('optOut');
+smp('optIn');
+```
+
+### React Pixel Hooks
+
+```tsx
+import { usePixel, usePageTracking, useIdentifyOnLogin } from '@sendmailos/sdk/react';
+
+// Basic usage
+function MyComponent() {
+  const { track, identify, optOut } = usePixel('pk_live_...');
+
+  return (
+    <button onClick={() => track('button_clicked', { id: 'cta' })}>
+      Click Me
+    </button>
+  );
+}
+
+// Auto page tracking (Next.js App Router)
+function Layout({ children }) {
+  const pathname = usePathname();
+  usePageTracking('pk_live_...', pathname);
+  return <>{children}</>;
+}
+
+// Auto identify on login
+function App() {
+  const { user } = useAuth();
+  useIdentifyOnLogin('pk_live_...', user?.email, {
+    first_name: user?.firstName,
+    plan: user?.plan
+  });
+  return <Main />;
+}
+```
+
+### Data Attributes
+
+Track clicks without JavaScript using HTML data attributes:
+
+```html
+<button data-smp-track="signup_clicked">Sign Up</button>
+
+<button
+  data-smp-track="button_clicked"
+  data-smp-track-button-id="cta-main"
+  data-smp-track-variant="blue"
+>
+  Get Started
+</button>
+```
+
 ## React Integration
 
 ```tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendmailos/sdk",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Official JavaScript/TypeScript SDK for SendMailOS email API",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",