@openlifelog/sdk 1.0.0

package/types/workout.ts

@@ -0,0 +1,97 @@
+import type { DateTime, UUID, ListParams, WorkoutFormat } from './common';
+
+/**
+ * Workout template types
+ */
+
+/**
+ * Set data structure (flexible for different workout formats)
+ */
+export interface SetData {
+  order: number;
+  reps?: number;
+  weight?: number;
+  restSeconds?: number;
+  distance?: number;
+  duration?: number;
+  tempo?: string;
+  rpe?: number;
+  notes?: string;
+  [key: string]: any; // Allow additional format-specific fields
+}
+
+/**
+ * Workout exercise (exercise within a workout template)
+ */
+export interface WorkoutExercise {
+  id: UUID;
+  workoutId: UUID;
+  exerciseId: UUID;
+  orderIndex: number;
+  workoutFormat: WorkoutFormat | string;
+  setsData: SetData[];
+  isSuperset: boolean;
+  notes?: string;
+  exerciseName?: string;
+  exerciseDescription?: string;
+}
+
+/**
+ * Workout template
+ */
+export interface Workout {
+  id: UUID;
+  name: string;
+  description?: string;
+  type: string;
+  createdBy: UUID;
+  createdAt: DateTime;
+  updatedAt: DateTime;
+  exercises?: WorkoutExercise[];
+}
+
+/**
+ * Create workout request
+ */
+export interface CreateWorkoutRequest {
+  name: string;
+  description?: string;
+  type: string;
+}
+
+/**
+ * Update workout request
+ */
+export type UpdateWorkoutRequest = Partial<CreateWorkoutRequest>;
+
+/**
+ * Add exercises to workout request
+ */
+export interface AddExercisesToWorkoutRequest {
+  exercises: Array<{
+    exerciseId: UUID;
+    orderIndex: number;
+    workoutFormat: WorkoutFormat | string;
+    setsData: SetData[];
+    isSuperset?: boolean;
+    notes?: string;
+  }>;
+}
+
+/**
+ * Update workout exercise request
+ */
+export interface UpdateWorkoutExerciseRequest {
+  orderIndex?: number;
+  workoutFormat?: WorkoutFormat | string;
+  setsData?: SetData[];
+  isSuperset?: boolean;
+  notes?: string;
+}
+
+/**
+ * List workouts parameters
+ */
+export interface ListWorkoutsParams extends ListParams {
+  search?: string;
+}

package/utils/errors.ts

@@ -0,0 +1,159 @@
+/**
+ * Custom error classes for the OpenLifeLog SDK
+ */
+
+/**
+ * Base error class for all SDK errors
+ */
+export class OpenLifeLogError extends Error {
+  public readonly statusCode?: number;
+  public readonly code?: string;
+  public readonly rawError?: any;
+
+  constructor(message: string, statusCode?: number, code?: string, rawError?: any) {
+    super(message);
+    this.name = 'OpenLifeLogError';
+    this.statusCode = statusCode;
+    this.code = code;
+    this.rawError = rawError;
+
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+/**
+ * Authentication error (401)
+ */
+export class AuthenticationError extends OpenLifeLogError {
+  constructor(message: string = 'Authentication failed. Please check your credentials.', rawError?: any) {
+    super(message, 401, 'AUTHENTICATION_ERROR', rawError);
+    this.name = 'AuthenticationError';
+  }
+}
+
+/**
+ * Authorization error (403)
+ */
+export class AuthorizationError extends OpenLifeLogError {
+  constructor(message: string = 'You do not have permission to access this resource.', rawError?: any) {
+    super(message, 403, 'AUTHORIZATION_ERROR', rawError);
+    this.name = 'AuthorizationError';
+  }
+}
+
+/**
+ * Not found error (404)
+ */
+export class NotFoundError extends OpenLifeLogError {
+  constructor(message: string = 'The requested resource was not found.', rawError?: any) {
+    super(message, 404, 'NOT_FOUND', rawError);
+    this.name = 'NotFoundError';
+  }
+}
+
+/**
+ * Validation error (400)
+ */
+export class ValidationError extends OpenLifeLogError {
+  public readonly validationErrors?: Record<string, string[]>;
+
+  constructor(
+    message: string = 'Validation failed.',
+    validationErrors?: Record<string, string[]>,
+    rawError?: any
+  ) {
+    super(message, 400, 'VALIDATION_ERROR', rawError);
+    this.name = 'ValidationError';
+    this.validationErrors = validationErrors;
+  }
+}
+
+/**
+ * Rate limit error (429)
+ */
+export class RateLimitError extends OpenLifeLogError {
+  public readonly retryAfter?: number;
+
+  constructor(message: string = 'Rate limit exceeded. Please try again later.', retryAfter?: number, rawError?: any) {
+    super(message, 429, 'RATE_LIMIT_ERROR', rawError);
+    this.name = 'RateLimitError';
+    this.retryAfter = retryAfter;
+  }
+}
+
+/**
+ * Server error (500)
+ */
+export class ServerError extends OpenLifeLogError {
+  constructor(message: string = 'An internal server error occurred.', rawError?: any) {
+    super(message, 500, 'SERVER_ERROR', rawError);
+    this.name = 'ServerError';
+  }
+}
+
+/**
+ * Network error
+ */
+export class NetworkError extends OpenLifeLogError {
+  constructor(message: string = 'A network error occurred. Please check your connection.', rawError?: any) {
+    super(message, undefined, 'NETWORK_ERROR', rawError);
+    this.name = 'NetworkError';
+  }
+}
+
+/**
+ * Timeout error
+ */
+export class TimeoutError extends OpenLifeLogError {
+  constructor(message: string = 'The request timed out.', rawError?: any) {
+    super(message, 408, 'TIMEOUT_ERROR', rawError);
+    this.name = 'TimeoutError';
+  }
+}
+
+/**
+ * Unit conversion error
+ */
+export class UnitConversionError extends OpenLifeLogError {
+  constructor(message: string = 'Failed to convert units.', rawError?: any) {
+    super(message, undefined, 'UNIT_CONVERSION_ERROR', rawError);
+    this.name = 'UnitConversionError';
+  }
+}
+
+/**
+ * Parse the error response and create appropriate error instance
+ */
+export function parseErrorResponse(error: any, statusCode?: number): OpenLifeLogError {
+  const message = error?.message || error?.error || 'An unknown error occurred';
+  const rawError = error;
+
+  if (statusCode === 401) {
+    return new AuthenticationError(message, rawError);
+  }
+
+  if (statusCode === 403) {
+    return new AuthorizationError(message, rawError);
+  }
+
+  if (statusCode === 404) {
+    return new NotFoundError(message, rawError);
+  }
+
+  if (statusCode === 400) {
+    return new ValidationError(message, error?.validationErrors, rawError);
+  }
+
+  if (statusCode === 429) {
+    return new RateLimitError(message, error?.retryAfter, rawError);
+  }
+
+  if (statusCode && statusCode >= 500) {
+    return new ServerError(message, rawError);
+  }
+
+  return new OpenLifeLogError(message, statusCode, error?.code, rawError);
+}

package/utils/http.ts

@@ -0,0 +1,313 @@
+import type { ResolvedConfig } from '../config';
+import { NetworkError, TimeoutError, parseErrorResponse } from './errors';
+
+/**
+ * HTTP request options
+ */
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  headers?: Record<string, string>;
+  body?: any;
+  params?: Record<string, any>;
+  timeout?: number;
+  skipRetry?: boolean;
+}
+
+/**
+ * HTTP response wrapper
+ */
+export interface HttpResponse<T = any> {
+  data: T;
+  status: number;
+  headers: Headers;
+}
+
+/**
+ * HTTP client with automatic retries, error handling, and timeout support
+ */
+export class HttpClient {
+  private config: ResolvedConfig;
+  private baseUrl: string;
+
+  constructor(config: ResolvedConfig) {
+    this.config = config;
+    this.baseUrl = config.baseUrl.replace(/\/$/, ''); // Remove trailing slash
+  }
+
+  /**
+   * Update the API key (token)
+   */
+  setApiKey(apiKey: string): void {
+    this.config.apiKey = apiKey;
+  }
+
+  /**
+   * Get the current API key
+   */
+  getApiKey(): string | undefined {
+    return this.config.apiKey;
+  }
+
+  /**
+   * Convert camelCase to snake_case
+   */
+  private toSnakeCase(str: string): string {
+    return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+  }
+
+  /**
+   * Build full URL with query parameters
+   */
+  private buildUrl(path: string, params?: Record<string, any>): string {
+    const url = new URL(path.startsWith('/') ? `${this.baseUrl}${path}` : `${this.baseUrl}/${path}`);
+
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null) {
+          // Convert camelCase to snake_case for API compatibility
+          const snakeKey = this.toSnakeCase(key);
+
+          // Handle arrays
+          if (Array.isArray(value)) {
+            value.forEach((v) => url.searchParams.append(snakeKey, String(v)));
+          } else {
+            url.searchParams.append(snakeKey, String(value));
+          }
+        }
+      });
+    }
+
+    return url.toString();
+  }
+
+  /**
+   * Build request headers
+   */
+  private buildHeaders(customHeaders?: Record<string, string>): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      ...this.config.headers,
+      ...customHeaders,
+    };
+
+    // Add authorization header if API key is present
+    if (this.config.apiKey) {
+      headers['Authorization'] = `Bearer ${this.config.apiKey}`;
+    }
+
+    return headers;
+  }
+
+  /**
+   * Execute request with timeout support
+   */
+  private async executeWithTimeout(
+    url: string,
+    init: RequestInit,
+    timeout: number
+  ): Promise<Response> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    try {
+      const response = await this.config.fetch(url, {
+        ...init,
+        signal: controller.signal,
+      });
+      clearTimeout(timeoutId);
+      return response;
+    } catch (error: any) {
+      clearTimeout(timeoutId);
+      if (error.name === 'AbortError') {
+        throw new TimeoutError(`Request timed out after ${timeout}ms`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Sleep for exponential backoff
+   */
+  private async sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Determine if error is retryable
+   */
+  private isRetryableError(error: any, statusCode?: number): boolean {
+    // Network errors are retryable
+    if (error instanceof NetworkError || error instanceof TimeoutError) {
+      return true;
+    }
+
+    // 5xx errors are retryable
+    if (statusCode && statusCode >= 500 && statusCode < 600) {
+      return true;
+    }
+
+    // 429 (rate limit) is retryable
+    if (statusCode === 429) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Calculate exponential backoff delay
+   */
+  private getRetryDelay(attempt: number): number {
+    // Exponential backoff: 2^attempt * 1000ms (with jitter)
+    const baseDelay = Math.pow(2, attempt) * 1000;
+    const jitter = Math.random() * 1000;
+    return baseDelay + jitter;
+  }
+
+  /**
+   * Make HTTP request with automatic retries
+   */
+  async request<T = any>(path: string, options: RequestOptions = {}): Promise<HttpResponse<T>> {
+    const {
+      method = 'GET',
+      headers: customHeaders,
+      body,
+      params,
+      timeout = this.config.timeout,
+      skipRetry = false,
+    } = options;
+
+    const url = this.buildUrl(path, params);
+    const headers = this.buildHeaders(customHeaders);
+
+    const requestInit: RequestInit = {
+      method,
+      headers,
+    };
+
+    // Add body for POST, PUT, PATCH requests
+    if (body && (method === 'POST' || method === 'PUT' || method === 'PATCH')) {
+      requestInit.body = JSON.stringify(body);
+    }
+
+    const maxAttempts = skipRetry || !this.config.enableRetries ? 1 : this.config.maxRetries + 1;
+    let lastError: any;
+
+    // Debug logging
+    if (this.config.debug) {
+      console.log(`[OpenLifeLog SDK] ${method} ${url}`, body ? { body } : '');
+    }
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      try {
+        // Wait for exponential backoff (except first attempt)
+        if (attempt > 0) {
+          const delay = this.getRetryDelay(attempt - 1);
+          if (this.config.debug) {
+            console.log(`[OpenLifeLog SDK] Retry attempt ${attempt}/${maxAttempts - 1}, waiting ${delay}ms`);
+          }
+          await this.sleep(delay);
+        }
+
+        // Execute request with timeout
+        const response = await this.executeWithTimeout(url, requestInit, timeout);
+
+        // Handle non-OK responses
+        if (!response.ok) {
+          let errorData: any;
+          try {
+            errorData = await response.json();
+          } catch {
+            errorData = { error: response.statusText };
+          }
+
+          const error = parseErrorResponse(errorData, response.status);
+
+          // Check if error is retryable
+          if (this.isRetryableError(error, response.status) && attempt < maxAttempts - 1) {
+            lastError = error;
+            continue; // Retry
+          }
+
+          throw error;
+        }
+
+        // Parse response
+        let data: any;
+        const contentType = response.headers.get('content-type');
+        if (contentType?.includes('application/json')) {
+          data = await response.json();
+        } else {
+          data = await response.text();
+        }
+
+        // Debug logging
+        if (this.config.debug) {
+          console.log(`[OpenLifeLog SDK] Response ${response.status}`, data);
+        }
+
+        return {
+          data,
+          status: response.status,
+          headers: response.headers,
+        };
+      } catch (error: any) {
+        // Convert network errors
+        if (error.name === 'TypeError' && error.message.includes('fetch')) {
+          lastError = new NetworkError(error.message, error);
+        } else if (error instanceof TimeoutError) {
+          lastError = error;
+        } else if (error.name === 'AbortError') {
+          lastError = new TimeoutError('Request was aborted', error);
+        } else {
+          lastError = error;
+        }
+
+        // Check if error is retryable
+        if (this.isRetryableError(lastError) && attempt < maxAttempts - 1) {
+          continue; // Retry
+        }
+
+        throw lastError;
+      }
+    }
+
+    // If we get here, all retries failed
+    throw lastError;
+  }
+
+  /**
+   * GET request
+   */
+  async get<T = any>(path: string, params?: Record<string, any>, options?: Omit<RequestOptions, 'method' | 'body' | 'params'>): Promise<HttpResponse<T>> {
+    return this.request<T>(path, { ...options, method: 'GET', params });
+  }
+
+  /**
+   * POST request
+   */
+  async post<T = any>(path: string, body?: any, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<HttpResponse<T>> {
+    return this.request<T>(path, { ...options, method: 'POST', body });
+  }
+
+  /**
+   * PUT request
+   */
+  async put<T = any>(path: string, body?: any, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<HttpResponse<T>> {
+    return this.request<T>(path, { ...options, method: 'PUT', body });
+  }
+
+  /**
+   * PATCH request
+   */
+  async patch<T = any>(path: string, body?: any, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<HttpResponse<T>> {
+    return this.request<T>(path, { ...options, method: 'PATCH', body });
+  }
+
+  /**
+   * DELETE request
+   */
+  async delete<T = any>(path: string, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<HttpResponse<T>> {
+    return this.request<T>(path, { ...options, method: 'DELETE' });
+  }
+}

package/utils/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Export utility functions and classes
+ */
+
+export * from './errors';
+export * from './units';
+export * from './http';
+export * from './pagination';

package/utils/pagination.ts

@@ -0,0 +1,106 @@
+import type { ListResponse, PageInfo } from '../types/common';
+
+/**
+ * Pagination helper utilities
+ */
+
+/**
+ * Async iterator for automatic pagination
+ */
+export class PaginatedIterator<T> {
+  private fetchPage: (cursor?: string) => Promise<ListResponse<T>>;
+  private currentPage: T[] = [];
+  private currentIndex = 0;
+  private nextCursor?: string;
+  private hasMore = true;
+  private isFirstFetch = true;
+
+  constructor(fetchPage: (cursor?: string) => Promise<ListResponse<T>>) {
+    this.fetchPage = fetchPage;
+  }
+
+  /**
+   * Async iterator implementation
+   */
+  async *[Symbol.asyncIterator](): AsyncIterator<T> {
+    while (this.hasMore || this.currentIndex < this.currentPage.length) {
+      // Fetch next page if current page is exhausted
+      if (this.currentIndex >= this.currentPage.length) {
+        if (!this.hasMore) {
+          break;
+        }
+
+        const response = await this.fetchPage(this.isFirstFetch ? undefined : this.nextCursor);
+        this.isFirstFetch = false;
+        this.currentPage = response.data;
+        this.currentIndex = 0;
+        this.nextCursor = response.pageInfo.nextCursor;
+        this.hasMore = response.pageInfo.hasMore;
+
+        // If no items in this page, stop iteration
+        if (this.currentPage.length === 0) {
+          break;
+        }
+      }
+
+      // Yield current item and advance index
+      yield this.currentPage[this.currentIndex++];
+    }
+  }
+
+  /**
+   * Get all items from all pages (be careful with large datasets!)
+   */
+  async toArray(): Promise<T[]> {
+    const items: T[] = [];
+    for await (const item of this) {
+      items.push(item);
+    }
+    return items;
+  }
+}
+
+/**
+ * Create a paginated iterator
+ */
+export function createPaginatedIterator<T>(
+  fetchPage: (cursor?: string) => Promise<ListResponse<T>>
+): PaginatedIterator<T> {
+  return new PaginatedIterator(fetchPage);
+}
+
+/**
+ * Helper to fetch all pages at once
+ */
+export async function fetchAllPages<T>(
+  fetchPage: (cursor?: string) => Promise<ListResponse<T>>,
+  maxPages?: number
+): Promise<T[]> {
+  const allItems: T[] = [];
+  let cursor: string | undefined;
+  let hasMore = true;
+  let pageCount = 0;
+
+  while (hasMore && (!maxPages || pageCount < maxPages)) {
+    const response = await fetchPage(cursor);
+    allItems.push(...response.data);
+
+    cursor = response.pageInfo.nextCursor;
+    hasMore = response.pageInfo.hasMore;
+    pageCount++;
+
+    // Safety check
+    if (!hasMore || !cursor) {
+      break;
+    }
+  }
+
+  return allItems;
+}
+
+/**
+ * Helper to check if there are more pages
+ */
+export function hasMorePages(pageInfo: PageInfo): boolean {
+  return pageInfo.hasMore && !!pageInfo.nextCursor;
+}