@openlifelog/sdk 1.0.0

package/EXAMPLES.md

@@ -0,0 +1,624 @@
+# OpenLifeLog SDK - Quick Examples
+
+## Table of Contents
+
+- [Authentication](#authentication)
+- [Food Logging](#food-logging)
+- [Workout Tracking](#workout-tracking)
+- [Goals & Progress](#goals--progress)
+- [Metrics](#metrics)
+- [External Auth Integration](#external-auth-integration)
+
+## Authentication
+
+### Using with JWT Token (External Auth)
+
+If your app already handles authentication:
+
+```typescript
+import { OpenLifeLog } from '@openlifelog/sdk';
+
+// Simply pass your JWT token
+const client = new OpenLifeLog({
+  apiKey: 'your-jwt-token-here',
+  baseUrl: 'http://localhost:8080',
+});
+
+// Ready to use!
+const user = await client.users.me();
+```
+
+### Set Token Later
+
+```typescript
+const client = new OpenLifeLog({
+  baseUrl: 'http://localhost:8080',
+});
+
+// After your auth flow completes
+client.setApiKey('jwt-token-from-your-system');
+
+// Now ready
+await client.logFood({ ... });
+```
+
+### Sign Up
+
+```typescript
+const { token, user } = await client.auth.signup({
+  name: 'John Doe',
+  email: 'john@example.com',
+  password: 'securePassword123',
+});
+```
+
+### Login
+
+```typescript
+const { token, user } = await client.auth.login({
+  email: 'john@example.com',
+  password: 'securePassword123',
+});
+```
+
+## Food Logging
+
+### Simple Food Logging
+
+```typescript
+// Quick and easy
+await client.logFood({
+  foodId: 'chicken-breast-id',
+  name: 'Chicken Breast',
+  quantity: 1.5,
+  unitGrams: 200,
+  mealType: 'lunch',
+});
+```
+
+### Search and Log Food
+
+```typescript
+// Search for food
+const { data: foods } = await client.foods.search({
+  q: 'chicken breast',
+  limit: 5,
+});
+
+// Log the first result
+if (foods.length > 0) {
+  const food = foods[0];
+  await client.logFood({
+    foodId: food.id,
+    name: food.name,
+    servingSizeName: food.servingSizes[0].name,
+    quantity: 1,
+    unitGrams: food.servingSizes[0].grams,
+    mealType: 'lunch',
+  });
+}
+```
+
+### Get Daily Summary
+
+```typescript
+// Today's nutrition
+const summary = await client.getTodayNutrition();
+console.log(`
+  Calories: ${summary.totalCalories}
+  Protein: ${summary.totalProtein}g
+  Carbs: ${summary.totalCarbs}g
+  Fat: ${summary.totalFat}g
+`);
+```
+
+### List Today's Meals
+
+```typescript
+const today = new Date().toISOString().split('T')[0];
+const { data: logs } = await client.foodLogs.list({
+  date: today,
+});
+
+console.log('Meals:');
+logs.forEach((log) => {
+  console.log(`${log.mealType}: ${log.name} - ${log.nutrients.calories} cal`);
+});
+```
+
+## Workout Tracking
+
+### Create and Start Workout Session
+
+```typescript
+// Option 1: From a workout template
+const session = await client.sessions.start({
+  workoutId: 'my-workout-template-id',
+  userBodyweight: 82.5,
+  notes: 'Feeling strong',
+  mood: 'energetic',
+  location: 'Home gym',
+});
+
+// Option 2: Quick workout without template
+const session = await client.sessions.start({
+  name: 'Quick Upper Body',
+  userBodyweight: 82.5,
+});
+```
+
+### Complete a Workout
+
+```typescript
+await client.sessions.complete(session.id, 'Great workout! Hit new PR.');
+```
+
+### View Workout History
+
+```typescript
+const { data: sessions } = await client.sessions.list({
+  startDate: '2024-01-01',
+  endDate: '2024-01-31',
+  status: 'completed',
+});
+
+console.log(`Completed ${sessions.length} workouts this month`);
+```
+
+### Get Personal Records
+
+```typescript
+const { data: prs } = await client.sessions.getPersonalRecords();
+
+prs.forEach((pr) => {
+  console.log(`${pr.exerciseName}: ${pr.value} ${pr.unit} (${pr.achievedDate})`);
+});
+```
+
+### Exercise Performance History
+
+```typescript
+const history = await client.sessions.getExerciseHistory('bench-press-id');
+
+console.log(`Bench Press History:`);
+history.history.forEach((entry) => {
+  console.log(`${entry.date}: ${entry.totalVolume}kg total volume`);
+});
+```
+
+## Goals & Progress
+
+### Set Daily Nutrition Goals
+
+```typescript
+await client.goals.createNutritionGoals({
+  effectiveDate: '2024-01-15',
+  goals: {
+    calories: { type: 'exact', value: 2200 },
+    protein: { type: 'min', value: 180 },
+    carbs: { type: 'range', min: 200, max: 300 },
+    fat: { type: 'range', min: 60, max: 80 },
+  },
+  notes: 'Maintenance phase',
+});
+```
+
+### Check Today's Progress
+
+```typescript
+const progress = await client.getTodayNutritionProgress();
+
+console.log(`Goal Progress:`);
+progress.progress.forEach((p) => {
+  const emoji = p.status === 'on_track' ? '✅' : p.status === 'below' ? '⬇️' : '⬆️';
+  console.log(`${emoji} ${p.nutrientKey}: ${p.current}/${p.target || 'goal'}`);
+});
+```
+
+### Set Body Weight Goal
+
+```typescript
+await client.goals.create({
+  metricKey: 'body_weight',
+  targetValue: 75.0,
+  targetType: 'exact',
+  effectiveFrom: '2024-01-15',
+});
+```
+
+## Metrics
+
+### Log Body Weight
+
+```typescript
+await client.metrics.log({
+  metricKey: 'body_weight',
+  value: 82.5,
+  metadata: {
+    time: 'morning',
+    conditions: 'fasted',
+  },
+});
+```
+
+### Log Multiple Metrics at Once
+
+```typescript
+await client.metrics.bulkCreateEvents({
+  metrics: [
+    { metricKey: 'body_weight', value: 82.5 },
+    { metricKey: 'body_fat_percentage', value: 15.2 },
+    { metricKey: 'sleep_hours', value: 7.5 },
+  ],
+});
+```
+
+### View Metric History
+
+```typescript
+const { data: events } = await client.metrics.listEvents({
+  metricKey: 'body_weight',
+  startDate: '2024-01-01',
+  endDate: '2024-01-31',
+});
+
+console.log('Weight History:');
+events.forEach((event) => {
+  console.log(`${event.loggedAt}: ${event.value}kg`);
+});
+```
+
+## Complete Daily Routine Example
+
+```typescript
+import { OpenLifeLog } from '@openlifelog/sdk';
+
+const client = new OpenLifeLog({
+  baseUrl: 'http://localhost:8080',
+});
+
+async function dailyRoutine() {
+  // Login
+  await client.auth.login({
+    email: 'athlete@example.com',
+    password: 'password123',
+  });
+
+  // Morning: Log weight
+  await client.metrics.log({
+    metricKey: 'body_weight',
+    value: 82.3,
+    metadata: { time: 'morning' },
+  });
+
+  // Breakfast
+  await client.logFood({
+    foodId: 'oatmeal-id',
+    name: 'Oatmeal',
+    quantity: 1,
+    unitGrams: 250,
+    mealType: 'breakfast',
+  });
+
+  // Morning workout
+  const session = await client.sessions.start({
+    workoutId: 'upper-body-id',
+    userBodyweight: 82.3,
+  });
+
+  // After workout
+  await client.sessions.complete(session.id);
+
+  // Post-workout shake
+  await client.logFood({
+    foodId: 'protein-shake-id',
+    name: 'Protein Shake',
+    quantity: 1,
+    unitGrams: 300,
+    mealType: 'snack',
+  });
+
+  // Check progress
+  const summary = await client.getTodayNutrition();
+  const progress = await client.getTodayNutritionProgress();
+
+  console.log('Daily Summary:', summary);
+  console.log('Goal Progress:', progress);
+}
+
+dailyRoutine().catch(console.error);
+```
+
+## Pagination Examples
+
+### Auto-pagination for All Foods
+
+```typescript
+// Automatically handles pagination
+for await (const food of client.foods.listAutoPaginate()) {
+  console.log(food.name);
+}
+```
+
+### Manual Pagination
+
+```typescript
+let cursor: string | undefined;
+let hasMore = true;
+
+while (hasMore) {
+  const { data, pageInfo } = await client.foods.list({
+    limit: 100,
+    cursor,
+  });
+
+  data.forEach((food) => console.log(food.name));
+
+  cursor = pageInfo.nextCursor;
+  hasMore = pageInfo.hasMore;
+}
+```
+
+## Error Handling Example
+
+```typescript
+import {
+  OpenLifeLogError,
+  AuthenticationError,
+  ValidationError,
+  NotFoundError,
+} from '@openlifelog/sdk';
+
+async function safeApiCall() {
+  try {
+    const food = await client.foods.get('food-id');
+    return food;
+  } catch (error) {
+    if (error instanceof NotFoundError) {
+      console.error('Food not found');
+      return null;
+    } else if (error instanceof AuthenticationError) {
+      console.error('Please login');
+      // Redirect to login
+      return null;
+    } else if (error instanceof ValidationError) {
+      console.error('Validation error:', error.validationErrors);
+      return null;
+    } else if (error instanceof OpenLifeLogError) {
+      console.error('API error:', error.message);
+      return null;
+    } else {
+      console.error('Unknown error:', error);
+      throw error;
+    }
+  }
+}
+```
+
+## Unit Conversion Examples
+
+```typescript
+// Set measurement system
+client.setMeasurementSystem('imperial');
+
+// Get converter
+const converter = client.getUnitConverter();
+
+// Weight conversion
+const kgToLbs = converter.weightFromMetric(82.5); // 181.88 lbs
+const lbsToKg = converter.weightToMetric(180); // 81.65 kg
+
+// Distance conversion
+const metersToMiles = converter.distanceFromMetric(5000, true); // 3.11 miles
+const milesToMeters = converter.distanceToMetric(3.1, true); // 4989.0 meters
+
+// Get unit labels
+console.log(converter.getWeightUnit()); // 'lbs'
+console.log(converter.getDistanceUnit(true)); // 'mi'
+```
+
+## External Auth Integration
+
+### Using with Auth0
+
+```typescript
+import { useAuth0 } from '@auth0/auth0-react';
+import { OpenLifeLog } from '@openlifelog/sdk';
+import { useMemo } from 'react';
+
+function useOpenLifeLog() {
+  const { getAccessTokenSilently, isAuthenticated } = useAuth0();
+
+  return useMemo(() => {
+    if (!isAuthenticated) return null;
+
+    return {
+      getClient: async () => {
+        const token = await getAccessTokenSilently();
+        return new OpenLifeLog({
+          apiKey: token,
+          baseUrl: process.env.NEXT_PUBLIC_API_URL!,
+        });
+      },
+    };
+  }, [isAuthenticated, getAccessTokenSilently]);
+}
+
+// Usage in component
+function MyComponent() {
+  const openlifelog = useOpenLifeLog();
+
+  const loadData = async () => {
+    if (!openlifelog) return;
+
+    const client = await openlifelog.getClient();
+    const user = await client.users.me();
+    const summary = await client.getTodayNutrition();
+    // ...
+  };
+
+  return <div>...</div>;
+}
+```
+
+### Using with Clerk
+
+```typescript
+import { useAuth } from '@clerk/nextjs';
+import { OpenLifeLog } from '@openlifelog/sdk';
+
+function useOpenLifeLog() {
+  const { getToken } = useAuth();
+
+  const getClient = async () => {
+    const token = await getToken();
+    return new OpenLifeLog({
+      apiKey: token!,
+      baseUrl: process.env.NEXT_PUBLIC_API_URL!,
+    });
+  };
+
+  return { getClient };
+}
+```
+
+### Using with NextAuth.js
+
+```typescript
+// app/api/nutrition/route.ts
+import { getServerSession } from 'next-auth/next';
+import { OpenLifeLog } from '@openlifelog/sdk';
+import { authOptions } from '@/lib/auth';
+
+export async function GET() {
+  const session = await getServerSession(authOptions);
+
+  if (!session?.accessToken) {
+    return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const client = new OpenLifeLog({
+    apiKey: session.accessToken,
+    baseUrl: process.env.API_URL!,
+  });
+
+  const summary = await client.getTodayNutrition();
+  return Response.json(summary);
+}
+```
+
+### Using with Firebase Auth
+
+```typescript
+import { getAuth } from 'firebase/auth';
+import { OpenLifeLog } from '@openlifelog/sdk';
+
+async function getClient() {
+  const auth = getAuth();
+  const user = auth.currentUser;
+
+  if (!user) {
+    throw new Error('Not authenticated');
+  }
+
+  const token = await user.getIdToken();
+
+  return new OpenLifeLog({
+    apiKey: token,
+    baseUrl: process.env.NEXT_PUBLIC_API_URL!,
+  });
+}
+
+// Usage
+const client = await getClient();
+const user = await client.users.me();
+```
+
+### Using with Supabase Auth
+
+```typescript
+import { createClient } from '@supabase/supabase-js';
+import { OpenLifeLog } from '@openlifelog/sdk';
+
+const supabase = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+);
+
+async function getClient() {
+  const {
+    data: { session },
+  } = await supabase.auth.getSession();
+
+  if (!session) {
+    throw new Error('Not authenticated');
+  }
+
+  return new OpenLifeLog({
+    apiKey: session.access_token,
+    baseUrl: process.env.NEXT_PUBLIC_API_URL!,
+  });
+}
+```
+
+### Custom Token Refresh
+
+```typescript
+import { OpenLifeLog } from '@openlifelog/sdk';
+
+class AuthenticatedOpenLifeLog {
+  private client: OpenLifeLog;
+  private refreshToken: string;
+
+  constructor(token: string, refreshToken: string) {
+    this.client = new OpenLifeLog({
+      apiKey: token,
+      baseUrl: process.env.API_URL!,
+    });
+    this.refreshToken = refreshToken;
+  }
+
+  async refreshAccessToken() {
+    // Your token refresh logic
+    const response = await fetch('/api/auth/refresh', {
+      method: 'POST',
+      body: JSON.stringify({ refreshToken: this.refreshToken }),
+    });
+
+    const { accessToken } = await response.json();
+
+    // Update client with new token
+    this.client.setApiKey(accessToken);
+
+    return accessToken;
+  }
+
+  async withRetry<T>(operation: () => Promise<T>): Promise<T> {
+    try {
+      return await operation();
+    } catch (error: any) {
+      // If auth error, try refreshing token once
+      if (error.statusCode === 401) {
+        await this.refreshAccessToken();
+        return await operation();
+      }
+      throw error;
+    }
+  }
+
+  // Expose client methods with auto-refresh
+  async logFood(data: any) {
+    return this.withRetry(() => this.client.logFood(data));
+  }
+
+  async getTodayNutrition() {
+    return this.withRetry(() => this.client.getTodayNutrition());
+  }
+
+  // Add more methods as needed...
+}
+
+// Usage
+const client = new AuthenticatedOpenLifeLog(accessToken, refreshToken);
+await client.logFood({ ... }); // Automatically refreshes token if needed
+```