@encorekit/web-sdk 0.1.1 → 0.1.7

package/examples/react/README.md

@@ -0,0 +1,186 @@
+# Encore SDK - React Example
+
+This example demonstrates how to integrate the Encore Web SDK into a React application using Vite and TypeScript.
+
+## 🚀 Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Build for production
+npm run build
+```
+
+The app will be available at `http://localhost:5173`
+
+## 📁 Project Structure
+
+```
+react/
+├── src/
+│   ├── App.tsx          # Main application component
+│   ├── main.tsx         # Application entry point
+│   ├── index.css        # Global styles
+│   └── vite-env.d.ts    # Vite type definitions
+├── index.html           # HTML template
+├── package.json         # Dependencies and scripts
+├── tsconfig.json        # TypeScript configuration
+└── vite.config.ts       # Vite configuration
+```
+
+## 🔑 Configuration
+
+Before running the example, replace `'YOUR_API_KEY_HERE'` in `src/App.tsx` with your actual Encore API key:
+
+```typescript
+Encore.configure({
+  apiKey: 'YOUR_API_KEY_HERE', // Get this from dashboard.encorekit.com
+  environment: 'production',
+  logLevel: 'debug',
+})
+```
+
+## 🎯 Features Demonstrated
+
+### 1. SDK Initialization
+The SDK is initialized when the component mounts using `useEffect`:
+
+```typescript
+useEffect(() => {
+  Encore.configure({
+    apiKey: 'YOUR_API_KEY_HERE',
+    environment: 'production',
+    logLevel: 'debug',
+  })
+  
+  const currentUserId = Encore.getCurrentUserId()
+  setUserId(currentUserId || '')
+  setIsInitialized(true)
+}, [])
+```
+
+### 2. User Identification
+Users can be identified with custom IDs and attributes:
+
+```typescript
+const handleIdentifyUser = () => {
+  Encore.identify(customUserId, {
+    email: 'user@example.com',
+  })
+  setUserId(customUserId)
+}
+```
+
+### 3. Presenting Offers
+Display targeted offers to users:
+
+```typescript
+const handlePresentOffer = async () => {
+  const result = await Encore.presentOffer()
+  
+  if (result.granted) {
+    console.log('Offer granted!')
+  }
+}
+```
+
+## 🏗️ React Patterns
+
+This example uses React best practices:
+
+- **Hooks** - `useState` and `useEffect` for state and lifecycle management
+- **TypeScript** - Full type safety with TypeScript
+- **Error Handling** - Try-catch blocks for SDK operations
+- **User Feedback** - Status messages for all actions
+- **Disabled States** - Buttons disabled until SDK is initialized
+
+## 📦 Dependencies
+
+- `react` ^18.3.1 - React library
+- `react-dom` ^18.3.1 - React DOM renderer
+- `@encorekit/web-sdk` ^0.2.0 - Encore Web SDK
+- `vite` ^5.4.1 - Build tool and dev server
+- `typescript` ^5.5.3 - TypeScript compiler
+
+## 🔧 Available Scripts
+
+- `npm run dev` - Start development server with hot reload
+- `npm run build` - Build for production
+- `npm run preview` - Preview production build locally
+
+## 💡 Best Practices
+
+1. **Initialize Once** - Initialize the SDK in a top-level component or custom hook
+2. **Error Handling** - Always wrap SDK calls in try-catch blocks
+3. **User Feedback** - Provide clear feedback for all SDK operations
+4. **Environment Variables** - In production, use environment variables for the API key
+5. **Type Safety** - Use TypeScript for better developer experience
+
+## 🎨 Customization
+
+### Using Environment Variables
+
+Create a `.env` file:
+
+```env
+VITE_ENCORE_API_KEY=your-api-key-here
+```
+
+Update `App.tsx`:
+
+```typescript
+Encore.configure({
+  apiKey: import.meta.env.VITE_ENCORE_API_KEY,
+  environment: 'production',
+})
+```
+
+### Creating a Custom Hook
+
+For better reusability, create a custom hook:
+
+```typescript
+// hooks/useEncore.ts
+import { useState, useEffect } from 'react'
+import Encore from '@encorekit/web-sdk'
+
+export function useEncore(apiKey: string) {
+  const [isInitialized, setIsInitialized] = useState(false)
+  const [userId, setUserId] = useState<string>('')
+
+  useEffect(() => {
+    Encore.configure({ apiKey })
+    setUserId(Encore.getCurrentUserId() || '')
+    setIsInitialized(true)
+  }, [apiKey])
+
+  const presentOffer = async () => {
+    return await Encore.presentOffer()
+  }
+
+  const identify = (userId: string, attributes?: Record<string, any>) => {
+    Encore.identify(userId, attributes)
+    setUserId(userId)
+  }
+
+  return { isInitialized, userId, presentOffer, identify }
+}
+```
+
+## 📚 Learn More
+
+- [Encore SDK Documentation](https://docs.encorekit.com)
+- [React Documentation](https://react.dev)
+- [Vite Documentation](https://vitejs.dev)
+- [TypeScript Documentation](https://www.typescriptlang.org)
+
+## 🆘 Support
+
+- 📧 Email: admin@encorekit.com
+- 📖 Docs: https://docs.encorekit.com
+
+

package/examples/react/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Encore SDK - React Example</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+

package/examples/react/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "encore-sdk-react-example",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "React example for Encore Web SDK",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@encorekit/web-sdk": "^0.1.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.1",
+    "typescript": "^5.5.3",
+    "vite": "^5.4.1"
+  }
+}
+

package/examples/react/src/App.tsx

@@ -0,0 +1,173 @@
+import { useState, useEffect } from 'react'
+import Encore from '@encorekit/web-sdk'
+
+function App() {
+  const [isInitialized, setIsInitialized] = useState(false)
+  const [userId, setUserId] = useState<string>('')
+  const [customUserId, setCustomUserId] = useState('')
+  const [status, setStatus] = useState<{
+    message: string
+    type: 'info' | 'success' | 'error'
+  } | null>(null)
+
+  // Initialize SDK on mount
+  useEffect(() => {
+    try {      
+      Encore.configure({
+        apiKey: 'ENCORE_PUBLIC_API_KEY', // Replace with your actual API key
+        userId: 'test-react',
+        environment: 'production',
+        logLevel: 'debug',
+      })
+      
+      const currentUserId = Encore.getCurrentUserId()
+      setUserId(currentUserId || '')
+      setIsInitialized(true)
+      setStatus({
+        message: 'Encore SDK initialized successfully!',
+        type: 'success',
+      })
+    } catch (error) {
+      setStatus({
+        message: `Failed to initialize SDK: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        type: 'error',
+      })
+    }
+  }, [])
+
+  const handleIdentifyUser = () => {
+    if (!customUserId.trim()) {
+      setStatus({
+        message: 'Please enter a user ID',
+        type: 'error',
+      })
+      return
+    }
+
+    try {
+      Encore.identify(customUserId, {
+        email: 'user@example.com',
+      })
+      setUserId(customUserId)
+      setStatus({
+        message: `User identified as: ${customUserId}`,
+        type: 'success',
+      })
+    } catch (error) {
+      setStatus({
+        message: `Failed to identify user: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        type: 'error',
+      })
+    }
+  }
+
+  const handlePresentOffer = async () => {
+    setStatus({
+      message: 'Presenting offer...',
+      type: 'info',
+    })
+
+    try {
+      const result = await Encore.presentOffer()
+      
+      if (result.granted) {
+        setStatus({
+          message: 'Offer granted successfully!',
+          type: 'success',
+        })
+      } else {
+        setStatus({
+          message: `Offer not granted: ${JSON.stringify(result.reason)}`,
+          type: 'info',
+        })
+      }
+    } catch (error) {
+      setStatus({
+        message: `Failed to present offer: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        type: 'error',
+      })
+    }
+  }
+
+  return (
+    <div className="app">
+      <h1>🎯 Encore SDK</h1>
+      <p>React Example</p>
+
+      <div className="card">
+        <h2>SDK Status</h2>
+        <div className="user-info">
+          <strong>Status:</strong> {isInitialized ? '✓ Initialized' : '✗ Not Initialized'}
+          <br />
+          <strong>User ID:</strong> {userId || 'Not set'}
+        </div>
+
+        {status && (
+          <div className={`status ${status.type}`}>
+            {status.message}
+          </div>
+        )}
+      </div>
+
+      <div className="card">
+        <h2>User Identification</h2>
+        <div className="input-group">
+          <label htmlFor="userId">Custom User ID:</label>
+          <input
+            id="userId"
+            type="text"
+            placeholder="Enter user ID (e.g., user-123)"
+            value={customUserId}
+            onChange={(e) => setCustomUserId(e.target.value)}
+            disabled={!isInitialized}
+          />
+        </div>
+        <button
+          onClick={handleIdentifyUser}
+          disabled={!isInitialized}
+          className="primary"
+        >
+          Identify User
+        </button>
+      </div>
+
+      <div className="card">
+        <h2>Present Offer</h2>
+        <p>Click the button below to display an offer to the user.</p>
+        <button
+          onClick={handlePresentOffer}
+          disabled={!isInitialized}
+          className="success"
+        >
+          🎁 Present Offer
+        </button>
+      </div>
+
+      <div className="card">
+        <h2>Code Example</h2>
+        <pre>
+{`// Initialize SDK
+Encore.configure({
+  apiKey: 'your-api-key',
+  userId: 'user-123',
+  environment: 'production',
+})
+
+// Identify user
+Encore.identify('user-123', {
+  email: 'user@example.com'
+})
+
+// Present offer
+const result = await Encore.presentOffer()
+if (result.granted) {
+  console.log('Offer granted!')
+}`}
+        </pre>
+      </div>
+    </div>
+  )
+}
+
+export default App
+

package/examples/react/src/index.css

@@ -0,0 +1,227 @@
+:root {
+  font-family: Inter, system-ui, Avenir, Helvetica, Arial, sans-serif;
+  line-height: 1.5;
+  font-weight: 400;
+
+  color-scheme: light dark;
+  color: rgba(255, 255, 255, 0.87);
+  background-color: #242424;
+
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  display: flex;
+  place-items: center;
+  min-width: 320px;
+  min-height: 100vh;
+}
+
+#root {
+  width: 100%;
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 2rem;
+}
+
+h1 {
+  font-size: 3.2em;
+  line-height: 1.1;
+  margin-bottom: 1rem;
+}
+
+h2 {
+  font-size: 1.8em;
+  margin-top: 2rem;
+  margin-bottom: 1rem;
+}
+
+.app {
+  text-align: center;
+}
+
+.card {
+  padding: 2em;
+  background-color: #1a1a1a;
+  border-radius: 8px;
+  margin-bottom: 2rem;
+}
+
+.user-info {
+  margin: 1.5rem 0;
+  padding: 1rem;
+  background-color: #2a2a2a;
+  border-radius: 4px;
+  font-family: monospace;
+}
+
+.user-info strong {
+  color: #646cff;
+}
+
+.button-group {
+  display: flex;
+  gap: 1rem;
+  justify-content: center;
+  flex-wrap: wrap;
+  margin: 1.5rem 0;
+}
+
+button {
+  border-radius: 8px;
+  border: 1px solid transparent;
+  padding: 0.6em 1.2em;
+  font-size: 1em;
+  font-weight: 500;
+  font-family: inherit;
+  background-color: #1a1a1a;
+  cursor: pointer;
+  transition: border-color 0.25s;
+}
+
+button:hover {
+  border-color: #646cff;
+}
+
+button:focus,
+button:focus-visible {
+  outline: 4px auto -webkit-focus-ring-color;
+}
+
+button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+button:disabled:hover {
+  border-color: transparent;
+}
+
+.primary {
+  background-color: #646cff;
+  color: white;
+}
+
+.primary:hover {
+  background-color: #535bf2;
+  border-color: #535bf2;
+}
+
+.success {
+  background-color: #059669;
+  color: white;
+}
+
+.success:hover {
+  background-color: #047857;
+  border-color: #047857;
+}
+
+.status {
+  margin: 1rem 0;
+  padding: 0.8rem;
+  border-radius: 4px;
+  font-size: 0.9em;
+}
+
+.status.info {
+  background-color: #1e40af;
+  color: white;
+}
+
+.status.success {
+  background-color: #059669;
+  color: white;
+}
+
+.status.error {
+  background-color: #dc2626;
+  color: white;
+}
+
+.input-group {
+  margin: 1rem 0;
+  text-align: left;
+}
+
+.input-group label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+}
+
+.input-group input {
+  width: 100%;
+  padding: 0.6em;
+  border-radius: 4px;
+  border: 1px solid #444;
+  background-color: #1a1a1a;
+  color: inherit;
+  font-size: 1em;
+  font-family: inherit;
+}
+
+.input-group input:focus {
+  outline: 2px solid #646cff;
+  border-color: #646cff;
+}
+
+code {
+  background-color: #2a2a2a;
+  padding: 0.2em 0.4em;
+  border-radius: 3px;
+  font-family: monospace;
+  font-size: 0.9em;
+}
+
+pre {
+  text-align: left;
+  background-color: #1a1a1a;
+  padding: 1rem;
+  border-radius: 4px;
+  overflow-x: auto;
+  margin: 1rem 0;
+}
+
+@media (prefers-color-scheme: light) {
+  :root {
+    color: #213547;
+    background-color: #ffffff;
+  }
+  
+  button {
+    background-color: #f9f9f9;
+  }
+  
+  .card {
+    background-color: #f9f9f9;
+  }
+  
+  .user-info {
+    background-color: #efefef;
+  }
+  
+  .input-group input {
+    background-color: #ffffff;
+    border-color: #ccc;
+  }
+  
+  code {
+    background-color: #efefef;
+  }
+  
+  pre {
+    background-color: #f5f5f5;
+  }
+}
+

package/examples/react/src/main.tsx

@@ -0,0 +1,11 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App'
+import './index.css'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)
+

package/examples/react/src/vite-env.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="vite/client" />
+

package/examples/react/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}
+

package/examples/react/vite.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [react()],
+})
+