@encorekit/web-sdk 0.1.1 → 0.1.7

package/examples/README.md

@@ -0,0 +1,149 @@
+# Encore Web SDK Examples
+
+Welcome to the Encore Web SDK examples! This directory contains complete, standalone example projects demonstrating how to integrate the Encore SDK into various web frameworks.
+
+## 📦 Available Examples
+
+| Framework | Description | Build Tool | Package Manager |
+|-----------|-------------|------------|-----------------|
+| [React](./react) | React 18 + TypeScript with custom hook | Vite | npm |
+| [Vue](./vue) | Vue 3 Composition API + TypeScript | Vite | npm |
+| [Angular](./angular) | Angular 17+ standalone components | Angular CLI | npm |
+| [Svelte](./svelte) | Svelte 4 + TypeScript | Vite | npm |
+| [Vanilla JS](./vanilla-js) | Plain JavaScript with CDN | None | None |
+
+## 🚀 Quick Start
+
+Each example is self-contained and ready to run. Choose your preferred framework:
+
+### React
+```bash
+cd react
+npm install
+npm run dev
+```
+
+### Vue
+```bash
+cd vue
+npm install
+npm run dev
+```
+
+### Angular
+```bash
+cd angular
+npm install
+npm start
+```
+
+### Svelte
+```bash
+cd svelte
+npm install
+npm run dev
+```
+
+### Vanilla JavaScript
+```bash
+cd vanilla-js
+# Open index.html in your browser (no build step required)
+open index.html
+```
+
+## 🎯 What Each Example Demonstrates
+
+All examples show the core Encore SDK features:
+
+1. **SDK Configuration** - Initialize the SDK with your API key
+2. **User Identification** - Identify users with custom IDs and attributes
+3. **Offer Presentation** - Display targeted offers to users
+4. **State Management** - Track SDK state and user information
+
+## 📋 Prerequisites
+
+- Node.js 18+ (not required for vanilla-js example)
+- npm or yarn
+- An Encore API key (get one at [dashboard.encorekit.com](https://dashboard.encorekit.com))
+
+## 🔑 Setup Your API Key
+
+Before running any example, you'll need to configure your Encore API key:
+
+1. Sign up at [dashboard.encorekit.com](https://dashboard.encorekit.com)
+2. Create a new application
+3. Copy your public API key
+4. Replace `'YOUR_API_KEY_HERE'` in the example code with your actual key
+
+## 🏗️ Framework-Specific Patterns
+
+### React Pattern
+Uses a custom `useEncore()` hook for SDK lifecycle management:
+```typescript
+const { userId, initialize, presentOffer } = useEncore();
+```
+
+### Vue Pattern
+Uses a composable function with Vue's Composition API:
+```typescript
+const { userId, initialize, presentOffer } = useEncore();
+```
+
+### Angular Pattern
+Uses a service with dependency injection:
+```typescript
+constructor(private encoreService: EncoreService) {}
+```
+
+### Svelte Pattern
+Uses reactive stores for state management:
+```typescript
+import { encoreStore } from './stores/encore';
+```
+
+### Vanilla JS Pattern
+Direct SDK usage with DOM manipulation:
+```javascript
+Encore.configure({ apiKey: 'your-key' });
+```
+
+## 📚 Documentation
+
+For complete SDK documentation, visit:
+- [Full Documentation](https://docs.encorekit.com)
+
+## 🔧 Troubleshooting
+
+### "Module not found" errors
+Make sure you've run `npm install` in the example directory.
+
+### SDK not loading
+Check that you've replaced `'YOUR_API_KEY_HERE'` with your actual API key.
+
+### CORS errors
+The Encore SDK is configured to work with CORS. If you see CORS errors, check your API key and environment settings.
+
+### No offers available
+Ensure you have:
+1. Created at least one offer campaign in your dashboard
+2. Set up targeting rules that match your user
+3. Activated the campaign
+
+## 💡 Best Practices
+
+1. **Never commit API keys** - Use environment variables in production
+2. **Server-side validation** - Always validate entitlements on your backend
+3. **Error handling** - Wrap SDK calls in try-catch blocks
+4. **User privacy** - Only collect necessary user attributes
+5. **Testing** - Use test mode for development
+
+## 🆘 Support
+
+Need help? Reach out:
+- 📧 Email: admin@encorekit.com
+- 📖 Docs: https://docs.encorekit.com
+
+## 📄 License
+
+These examples are provided as-is for demonstration purposes. The Encore SDK itself is covered by its own license terms.
+

package/examples/angular/README.md

@@ -0,0 +1,210 @@
+# Encore SDK - Angular Example
+
+This example demonstrates how to integrate the Encore Web SDK into an Angular 17+ application using standalone components and services.
+
+## 🚀 Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm start
+
+# Build for production
+npm run build
+```
+
+The app will be available at `http://localhost:4200`
+
+## 📁 Project Structure
+
+```
+angular/
+├── src/
+│   ├── app/
+│   │   ├── app.component.ts       # Main application component
+│   │   ├── app.component.html     # Component template
+│   │   └── encore.service.ts      # Encore SDK service
+│   ├── main.ts                    # Application entry point
+│   ├── styles.css                 # Global styles
+│   └── index.html                 # HTML template
+├── angular.json                   # Angular CLI configuration
+├── package.json                   # Dependencies and scripts
+└── tsconfig.json                  # TypeScript configuration
+```
+
+## 🔑 Configuration
+
+Before running the example, replace `'YOUR_API_KEY_HERE'` in `src/app/app.component.ts` with your actual Encore API key:
+
+```typescript
+this.encoreService.initialize('YOUR_API_KEY_HERE', 'production');
+```
+
+## 🎯 Features Demonstrated
+
+### 1. Service-Based Architecture
+The SDK is wrapped in an Angular service for better organization:
+
+```typescript
+@Injectable({
+  providedIn: 'root'
+})
+export class EncoreService {
+  initialize(apiKey: string): void {
+    Encore.configure({ apiKey });
+  }
+  
+  async presentOffer(): Promise<any> {
+    return await Encore.presentOffer();
+  }
+}
+```
+
+### 2. Dependency Injection
+The service is injected into components:
+
+```typescript
+constructor(private encoreService: EncoreService) {}
+```
+
+### 3. Lifecycle Hooks
+SDK initialization happens in `ngOnInit`:
+
+```typescript
+ngOnInit() {
+  this.encoreService.initialize('YOUR_API_KEY_HERE');
+  this.userId = this.encoreService.getCurrentUserId() || '';
+  this.isInitialized = true;
+}
+```
+
+### 4. Two-Way Data Binding
+Angular's `[(ngModel)]` for form inputs:
+
+```html
+<input [(ngModel)]="customUserId" />
+```
+
+### 5. Async Operations
+Proper handling of async SDK methods:
+
+```typescript
+async handlePresentOffer() {
+  const result = await this.encoreService.presentOffer();
+  if (result.granted) {
+    console.log('Offer granted!');
+  }
+}
+```
+
+## 🏗️ Angular Patterns
+
+This example uses Angular best practices:
+
+- **Standalone Components** - Modern Angular 17+ approach
+- **Services** - Separation of concerns with injectable services
+- **Dependency Injection** - Angular's DI system
+- **TypeScript** - Full type safety
+- **Reactive Forms** - Two-way data binding with FormsModule
+- **Template Syntax** - Angular's declarative templates
+
+## 📦 Dependencies
+
+- `@angular/core` ^17.3.0 - Angular framework
+- `@angular/common` ^17.3.0 - Angular common utilities
+- `@angular/platform-browser` ^17.3.0 - Browser platform
+- `@encorekit/web-sdk` ^0.2.0 - Encore Web SDK
+- `rxjs` ~7.8.0 - Reactive extensions
+- `zone.js` ~0.14.3 - Zone execution context
+
+## 🔧 Available Scripts
+
+- `npm start` - Start development server (alias for `ng serve`)
+- `npm run build` - Build for production
+- `npm run watch` - Build and watch for changes
+
+## 💡 Best Practices
+
+1. **Service Layer** - Wrap the SDK in an Angular service
+2. **Dependency Injection** - Use Angular's DI for service access
+3. **Error Handling** - Always wrap SDK calls in try-catch blocks
+4. **Type Safety** - Define interfaces for SDK responses
+5. **Lifecycle Management** - Initialize in `ngOnInit`, cleanup if needed
+6. **Environment Variables** - Use Angular's environment files for configuration
+
+## 🎨 Customization
+
+### Using Environment Files
+
+Create `src/environments/environment.ts`:
+
+```typescript
+export const environment = {
+  production: false,
+  encoreApiKey: 'your-api-key-here',
+};
+```
+
+Create `src/environments/environment.prod.ts`:
+
+```typescript
+export const environment = {
+  production: true,
+  encoreApiKey: 'your-production-api-key',
+};
+```
+
+Update `app.component.ts`:
+
+```typescript
+import { environment } from '../environments/environment';
+
+ngOnInit() {
+  this.encoreService.initialize(environment.encoreApiKey);
+}
+```
+
+### Using RxJS Observables
+
+For better reactive patterns, you can enhance the service:
+
+```typescript
+import { Injectable } from '@angular/core';
+import { BehaviorSubject, Observable } from 'rxjs';
+import Encore from '@encorekit/web-sdk';
+
+@Injectable({
+  providedIn: 'root'
+})
+export class EncoreService {
+  private userIdSubject = new BehaviorSubject<string>('');
+  userId$: Observable<string> = this.userIdSubject.asObservable();
+
+  initialize(apiKey: string): void {
+    Encore.configure({ apiKey });
+    const userId = Encore.getCurrentUserId() || '';
+    this.userIdSubject.next(userId);
+  }
+
+  identify(userId: string, attributes?: Record<string, any>): void {
+    Encore.identify(userId, attributes);
+    this.userIdSubject.next(userId);
+  }
+}
+```
+
+## 📚 Learn More
+
+- [Encore SDK Documentation](https://docs.encorekit.com)
+- [Angular Documentation](https://angular.io)
+- [Angular CLI Documentation](https://angular.io/cli)
+- [RxJS Documentation](https://rxjs.dev)
+
+## 🆘 Support
+
+- 📧 Email: admin@encorekit.com
+- 📖 Docs: https://docs.encorekit.com
+
+

package/examples/angular/angular.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "newProjectRoot": "projects",
+  "projects": {
+    "encore-sdk-angular-example": {
+      "projectType": "application",
+      "schematics": {
+        "@schematics/angular:component": {
+          "style": "css"
+        }
+      },
+      "root": "",
+      "sourceRoot": "src",
+      "prefix": "app",
+      "architect": {
+        "build": {
+          "builder": "@angular-devkit/build-angular:browser",
+          "options": {
+            "outputPath": "dist/encore-sdk-angular-example",
+            "index": "src/index.html",
+            "main": "src/main.ts",
+            "tsConfig": "tsconfig.json",
+            "assets": [],
+            "styles": [
+              "src/styles.css"
+            ],
+            "scripts": []
+          },
+          "configurations": {
+            "production": {
+              "budgets": [
+                {
+                  "type": "initial",
+                  "maximumWarning": "500kb",
+                  "maximumError": "1mb"
+                },
+                {
+                  "type": "anyComponentStyle",
+                  "maximumWarning": "2kb",
+                  "maximumError": "4kb"
+                }
+              ],
+              "outputHashing": "all"
+            },
+            "development": {
+              "optimization": false,
+              "extractLicenses": false,
+              "sourceMap": true
+            }
+          },
+          "defaultConfiguration": "production"
+        },
+        "serve": {
+          "builder": "@angular-devkit/build-angular:dev-server",
+          "configurations": {
+            "production": {
+              "buildTarget": "encore-sdk-angular-example:build:production"
+            },
+            "development": {
+              "buildTarget": "encore-sdk-angular-example:build:development"
+            }
+          },
+          "defaultConfiguration": "development"
+        }
+      }
+    }
+  },
+  "cli": {
+    "analytics": false
+  }
+}
+

package/examples/angular/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "encore-sdk-angular-example",
+  "version": "1.0.0",
+  "description": "Angular example for Encore Web SDK",
+  "scripts": {
+    "ng": "ng",
+    "start": "ng serve",
+    "build": "ng build",
+    "watch": "ng build --watch --configuration development"
+  },
+  "private": true,
+  "dependencies": {
+    "@angular/animations": "^17.3.0",
+    "@angular/common": "^17.3.0",
+    "@angular/compiler": "^17.3.0",
+    "@angular/core": "^17.3.0",
+    "@angular/forms": "^17.3.0",
+    "@angular/platform-browser": "^17.3.0",
+    "@angular/platform-browser-dynamic": "^17.3.0",
+    "@encorekit/web-sdk": "^0.1.1",
+    "rxjs": "~7.8.0",
+    "tslib": "^2.3.0",
+    "zone.js": "~0.14.3"
+  },
+  "devDependencies": {
+    "@angular-devkit/build-angular": "^17.3.0",
+    "@angular/cli": "^17.3.0",
+    "@angular/compiler-cli": "^17.3.0",
+    "typescript": "~5.4.2"
+  }
+}
+

package/examples/angular/src/app/app.component.html

@@ -0,0 +1,56 @@
+<div class="app">
+  <h1>🎯 Encore SDK</h1>
+  <p>Angular Example</p>
+
+  <div class="card">
+    <h2>SDK Status</h2>
+    <div class="user-info">
+      <strong>Status:</strong> {{ isInitialized ? '✓ Initialized' : '✗ Not Initialized' }}
+      <br />
+      <strong>User ID:</strong> {{ userId || 'Not set' }}
+    </div>
+
+    <div *ngIf="status" [class]="'status ' + status.type">
+      {{ status.message }}
+    </div>
+  </div>
+
+  <div class="card">
+    <h2>User Identification</h2>
+    <div class="input-group">
+      <label for="userId">Custom User ID:</label>
+      <input
+        id="userId"
+        type="text"
+        placeholder="Enter user ID (e.g., user-123)"
+        [(ngModel)]="customUserId"
+        [disabled]="!isInitialized"
+      />
+    </div>
+    <button
+      (click)="handleIdentifyUser()"
+      [disabled]="!isInitialized"
+      class="primary"
+    >
+      Identify User
+    </button>
+  </div>
+
+  <div class="card">
+    <h2>Present Offer</h2>
+    <p>Click the button below to display an offer to the user.</p>
+    <button
+      (click)="handlePresentOffer()"
+      [disabled]="!isInitialized"
+      class="success"
+    >
+      🎁 Present Offer
+    </button>
+  </div>
+
+  <div class="card">
+    <h2>Code Example</h2>
+    <pre>{{ codeExample }}</pre>
+  </div>
+</div>
+

package/examples/angular/src/app/app.component.ts

@@ -0,0 +1,114 @@
+import { Component, OnInit } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { FormsModule } from '@angular/forms';
+import { EncoreService } from './encore.service';
+
+interface Status {
+  message: string;
+  type: 'info' | 'success' | 'error';
+}
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [CommonModule, FormsModule],
+  templateUrl: './app.component.html',
+})
+export class AppComponent implements OnInit {
+  isInitialized = false;
+  userId = '';
+  customUserId = '';
+  status: Status | null = null;
+
+  codeExample = `// Initialize SDK
+Encore.configure({
+  apiKey: 'your-api-key',
+  userId: 'user-123',
+  environment: 'production',
+})
+
+// Identify user with attributes
+Encore.identify('user-123', {
+  email: 'user@example.com'
+})
+
+// Present offer
+const result = await Encore.presentOffer()
+if (result.granted) {
+  console.log('Offer granted!')
+}`;
+
+  constructor(private encoreService: EncoreService) {}
+
+  ngOnInit() {
+    try {
+      this.encoreService.initialize('ENCORE_PUBLIC_API_KEY', 'production');
+      this.userId = this.encoreService.getCurrentUserId() || '';
+      this.isInitialized = true;
+      this.status = {
+        message: 'Encore SDK initialized successfully!',
+        type: 'success',
+      };
+    } catch (error) {
+      this.status = {
+        message: `Failed to initialize SDK: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        type: 'error',
+      };
+    }
+  }
+
+  handleIdentifyUser() {
+    if (!this.customUserId.trim()) {
+      this.status = {
+        message: 'Please enter a user ID',
+        type: 'error',
+      };
+      return;
+    }
+
+    try {
+      this.encoreService.identify(this.customUserId, {
+        email: 'user@example.com',
+      });
+      this.userId = this.customUserId;
+      this.status = {
+        message: `User identified as: ${this.customUserId}`,
+        type: 'success',
+      };
+    } catch (error) {
+      this.status = {
+        message: `Failed to identify user: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        type: 'error',
+      };
+    }
+  }
+
+  async handlePresentOffer() {
+    this.status = {
+      message: 'Presenting offer...',
+      type: 'info',
+    };
+
+    try {
+      const result = await this.encoreService.presentOffer();
+
+      if (result.granted) {
+        this.status = {
+          message: 'Offer granted successfully!',
+          type: 'success',
+        };
+      } else {
+        this.status = {
+          message: `Offer not granted: ${JSON.stringify(result.reason)}`,
+          type: 'info',
+        };
+      }
+    } catch (error) {
+      this.status = {
+        message: `Failed to present offer: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        type: 'error',
+      };
+    }
+  }
+}
+