@paceful/sdk 1.0.0

package/README.md

@@ -0,0 +1,433 @@
+# @paceful/sdk
+
+Official JavaScript/TypeScript SDK for the Paceful Partner API.
+
+## Installation
+
+```bash
+npm install @paceful/sdk
+# or
+yarn add @paceful/sdk
+# or
+pnpm add @paceful/sdk
+```
+
+## Quick Start
+
+```typescript
+import { PacefulClient } from '@paceful/sdk';
+
+const paceful = new PacefulClient({
+  apiKey: process.env.PACEFUL_API_KEY,
+});
+
+// Register a user
+const user = await paceful.users.register({
+  externalId: 'user_123',
+  email: 'user@example.com',
+});
+
+// Log mood data
+await paceful.mood.log({
+  externalId: 'user_123',
+  mood: 4,
+  note: 'Feeling productive today',
+  factors: ['work', 'exercise'],
+});
+
+// Get ERS score
+const ers = await paceful.ers.get('user_123');
+console.log(`ERS Score: ${ers.ersScore}`);
+console.log(`Stage: ${ers.stage}`);
+console.log(`Trend: ${ers.trend?.direction}`);
+```
+
+## Modules
+
+### Users
+
+Manage partner users in the Paceful system.
+
+```typescript
+// Register a new user
+const user = await paceful.users.register({
+  externalId: 'user_123',
+  email: 'user@example.com',
+  metadata: { plan: 'premium' },
+});
+
+// Get a user
+const user = await paceful.users.get('user_123');
+
+// Update user metadata
+await paceful.users.update('user_123', {
+  metadata: { plan: 'enterprise' },
+});
+
+// List all users
+const { items, total, hasMore } = await paceful.users.list({ limit: 50 });
+
+// Delete a user
+await paceful.users.delete('user_123');
+```
+
+### Mood
+
+Track and retrieve mood data for users.
+
+```typescript
+// Log a mood entry
+const entry = await paceful.mood.log({
+  externalId: 'user_123',
+  mood: 4, // 1-5 scale
+  note: 'Great day!',
+  factors: ['exercise', 'sleep'],
+});
+
+// Get mood history
+const history = await paceful.mood.history({
+  externalId: 'user_123',
+  startDate: '2024-01-01',
+  limit: 30,
+});
+
+// Get latest mood
+const latest = await paceful.mood.latest('user_123');
+
+// Get mood statistics
+const stats = await paceful.mood.stats('user_123', '30d');
+```
+
+### Journal
+
+Create and retrieve journal entries.
+
+```typescript
+// Create a journal entry
+const entry = await paceful.journal.create({
+  externalId: 'user_123',
+  content: 'Today I reflected on my progress...',
+  mood: 4,
+});
+
+// Entry includes AI analysis
+console.log('Themes:', entry.themes);
+console.log('Sentiment:', entry.sentimentScore);
+
+// Get journal history
+const entries = await paceful.journal.history({
+  externalId: 'user_123',
+  limit: 10,
+});
+
+// Get available prompts
+const prompts = await paceful.journal.prompts();
+```
+
+### ERS (Emotional Readiness Score)
+
+Calculate and retrieve ERS scores.
+
+```typescript
+// Get current ERS score (cached if recent)
+const ers = await paceful.ers.get('user_123');
+
+// Force fresh calculation
+const result = await paceful.ers.calculate('user_123');
+
+// Batch get scores for multiple users
+const batch = await paceful.ers.batch(['user_1', 'user_2', 'user_3']);
+
+// Get score history
+const history = await paceful.ers.history('user_123', {
+  period: '30d',
+  granularity: 'daily',
+});
+
+// Set up threshold alerts
+await paceful.ers.setThresholdAlert({
+  externalId: 'user_123',
+  threshold: 40,
+  direction: 'below',
+});
+```
+
+### Analytics
+
+Get aggregate analytics for your partner account.
+
+```typescript
+// Get summary analytics
+const summary = await paceful.analytics.summary('30d');
+console.log(`Total users: ${summary.totalUsers}`);
+console.log(`Average ERS: ${summary.averageErs}`);
+
+// Get engagement metrics
+const engagement = await paceful.analytics.engagement({
+  period: '30d',
+  granularity: 'daily',
+});
+
+// Get ERS distribution
+const distribution = await paceful.analytics.ersDistribution('30d');
+
+// Get retention metrics
+const retention = await paceful.analytics.retention('30d');
+
+// Export data
+const { downloadUrl } = await paceful.analytics.export({
+  type: 'user_summary',
+  period: '30d',
+  format: 'csv',
+});
+```
+
+### Webhooks
+
+Manage webhook endpoints for real-time notifications.
+
+```typescript
+// Register a webhook
+const webhook = await paceful.webhooks.register({
+  url: 'https://yourapp.com/webhooks/paceful',
+  events: ['ers.stage_changed', 'mood.critical'],
+});
+
+// Save the secret for signature verification
+console.log('Secret:', webhook.secret);
+
+// List webhooks
+const webhooks = await paceful.webhooks.list();
+
+// Update a webhook
+await paceful.webhooks.update(webhook.webhookId, {
+  events: ['ers.stage_changed', 'mood.critical', 'journal.created'],
+});
+
+// Test a webhook
+const result = await paceful.webhooks.test(webhook.webhookId);
+
+// Verify webhook signatures
+import { Webhooks } from '@paceful/sdk';
+
+const isValid = Webhooks.verifySignature(
+  rawBody,
+  request.headers['x-paceful-signature'],
+  process.env.PACEFUL_WEBHOOK_SECRET
+);
+```
+
+## Webhook Events
+
+| Event | Description |
+|-------|-------------|
+| `ers.stage_changed` | User's ERS stage changed (healing, rebuilding, ready) |
+| `ers.score_threshold` | User's ERS crossed a configured threshold |
+| `mood.critical` | User logged a critical mood (1-2) |
+| `mood.logged` | User logged any mood entry |
+| `journal.created` | User created a journal entry |
+
+## React Widgets
+
+The SDK includes embeddable React widgets for quick integration. Widgets use inline styles and have no external dependencies.
+
+### PacefulProvider
+
+Wrap your app to provide context to all widgets:
+
+```tsx
+import { PacefulProvider } from '@paceful/sdk';
+
+function App() {
+  return (
+    <PacefulProvider
+      apiKey={process.env.PACEFUL_API_KEY}
+      userId="user_123"
+    >
+      <YourApp />
+    </PacefulProvider>
+  );
+}
+```
+
+### MoodWidget
+
+Self-contained mood check-in component:
+
+```tsx
+import { MoodWidget } from '@paceful/sdk';
+
+// With PacefulProvider context
+<MoodWidget
+  theme="light"
+  brandColor="#5B8A72"
+  showStreak={true}
+  onComplete={(mood) => console.log('Logged:', mood)}
+/>
+
+// Standalone (without provider)
+<MoodWidget
+  apiKey="your_api_key"
+  userId="user_123"
+  theme="dark"
+  compact={true}
+/>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiKey` | string | - | API key (optional if using PacefulProvider) |
+| `userId` | string | - | User ID (optional if using PacefulProvider) |
+| `theme` | 'light' \| 'dark' | 'light' | Color theme |
+| `brandColor` | string | '#5B8A72' | Primary accent color |
+| `compact` | boolean | false | Skip emotion selection step |
+| `showStreak` | boolean | false | Show mood logging streak |
+| `onComplete` | function | - | Callback when mood is logged |
+| `onError` | function | - | Callback on error |
+
+### JournalWidget
+
+Journal entry component with AI reflection:
+
+```tsx
+import { JournalWidget } from '@paceful/sdk';
+
+<JournalWidget
+  theme="light"
+  brandColor="#5B8A72"
+  showPrompt={true}
+  showAIReflection={true}
+  maxLength={2000}
+  onComplete={(entry) => console.log('Saved:', entry)}
+/>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiKey` | string | - | API key (optional if using PacefulProvider) |
+| `userId` | string | - | User ID (optional if using PacefulProvider) |
+| `theme` | 'light' \| 'dark' | 'light' | Color theme |
+| `brandColor` | string | '#5B8A72' | Primary accent color |
+| `showPrompt` | boolean | true | Show random journal prompt |
+| `showAIReflection` | boolean | true | Show AI reflection after saving |
+| `maxLength` | number | 2000 | Maximum character length |
+| `placeholder` | string | "What's on your mind?" | Textarea placeholder |
+| `onComplete` | function | - | Callback when entry is saved |
+| `onError` | function | - | Callback on error |
+
+### ERSDisplay
+
+ERS score visualization component:
+
+```tsx
+import { ERSDisplay } from '@paceful/sdk';
+
+<ERSDisplay
+  theme="light"
+  brandColor="#5B8A72"
+  showDimensions={true}
+  showTrend={true}
+  compact={false}
+  onLoad={(ers) => console.log('ERS:', ers)}
+/>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiKey` | string | - | API key (optional if using PacefulProvider) |
+| `userId` | string | - | User ID (optional if using PacefulProvider) |
+| `theme` | 'light' \| 'dark' | 'light' | Color theme |
+| `brandColor` | string | '#5B8A72' | Primary accent color |
+| `showDimensions` | boolean | true | Show 5 ERS dimension bars |
+| `showTrend` | boolean | true | Show weekly trend badge |
+| `compact` | boolean | false | Smaller ring, hide dimensions |
+| `onLoad` | function | - | Callback when ERS loads |
+| `onError` | function | - | Callback on error |
+
+## Error Handling
+
+The SDK throws typed errors for different failure scenarios:
+
+```typescript
+import {
+  PacefulError,
+  PacefulAuthError,
+  PacefulRateLimitError,
+  PacefulNotFoundError,
+  PacefulValidationError,
+  PacefulNetworkError,
+} from '@paceful/sdk';
+
+try {
+  const ers = await paceful.ers.get('user_123');
+} catch (error) {
+  if (error instanceof PacefulAuthError) {
+    // Invalid API key
+    console.error('Authentication failed');
+  } else if (error instanceof PacefulRateLimitError) {
+    // Rate limited - retry after error.retryAfter seconds
+    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
+  } else if (error instanceof PacefulNotFoundError) {
+    // User not found
+    console.error('User not found');
+  } else if (error instanceof PacefulValidationError) {
+    // Invalid request parameters
+    console.error('Validation error:', error.message);
+  } else if (error instanceof PacefulNetworkError) {
+    // Network failure
+    console.error('Network error:', error.message);
+  } else if (error instanceof PacefulError) {
+    // Generic API error
+    console.error(`Error ${error.code}:`, error.message);
+  }
+}
+```
+
+## Configuration
+
+```typescript
+const paceful = new PacefulClient({
+  // Required: Your API key
+  apiKey: process.env.PACEFUL_API_KEY,
+
+  // Optional: Custom base URL (for testing)
+  baseUrl: 'https://api.paceful.app',
+
+  // Optional: Request timeout in ms (default: 30000)
+  timeout: 30000,
+
+  // Optional: Number of retries for failed requests (default: 3)
+  retries: 3,
+});
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides full type definitions:
+
+```typescript
+import type {
+  PacefulConfig,
+  PartnerUser,
+  MoodEntry,
+  JournalEntry,
+  ERSScore,
+  ERSStage,
+  ERSDimensions,
+  AnalyticsSummary,
+  WebhookEvent,
+} from '@paceful/sdk';
+```
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+- TypeScript 5.0+ (for TypeScript users)
+- React 17.0.0+ (for widget components, optional)
+
+## License
+
+MIT