@seenn/node 0.1.0

package/src/http.ts

@@ -0,0 +1,179 @@
+import {
+  SeennError,
+  RateLimitError,
+  ValidationError,
+  NotFoundError,
+  AuthenticationError,
+} from './errors.js';
+import type { SeennConfig } from './client.js';
+
+interface RequestOptions {
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  path: string;
+  body?: unknown;
+  idempotencyKey?: string;
+}
+
+interface ErrorResponse {
+  error: {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+  };
+}
+
+export class HttpClient {
+  private readonly config: Required<SeennConfig>;
+
+  constructor(config: Required<SeennConfig>) {
+    this.config = config;
+  }
+
+  async get<T>(path: string): Promise<T> {
+    return this.request<T>({ method: 'GET', path });
+  }
+
+  async post<T>(path: string, body?: unknown): Promise<T> {
+    return this.request<T>({ method: 'POST', path, body });
+  }
+
+  async put<T>(path: string, body?: unknown): Promise<T> {
+    return this.request<T>({ method: 'PUT', path, body });
+  }
+
+  async delete<T>(path: string): Promise<T> {
+    return this.request<T>({ method: 'DELETE', path });
+  }
+
+  private async request<T>(options: RequestOptions): Promise<T> {
+    const { method, path, body } = options;
+    const url = `${this.config.baseUrl}${path}`;
+
+    const headers: Record<string, string> = {
+      'Authorization': `Bearer ${this.config.apiKey}`,
+      'Content-Type': 'application/json',
+      'User-Agent': '@seenn/node',
+    };
+
+    if (options.idempotencyKey) {
+      headers['Idempotency-Key'] = options.idempotencyKey;
+    }
+
+    return this.executeWithRetry<T>(async () => {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+
+      try {
+        const response = await fetch(url, {
+          method,
+          headers,
+          body: body ? JSON.stringify(body) : undefined,
+          signal: controller.signal,
+        });
+
+        clearTimeout(timeoutId);
+
+        if (!response.ok) {
+          await this.handleErrorResponse(response);
+        }
+
+        return (await response.json()) as T;
+      } catch (error) {
+        clearTimeout(timeoutId);
+
+        if (error instanceof SeennError) {
+          throw error;
+        }
+
+        if (error instanceof Error) {
+          if (error.name === 'AbortError') {
+            throw new SeennError('Request timeout', 'TIMEOUT', 408);
+          }
+          throw new SeennError(error.message, 'NETWORK_ERROR', 0);
+        }
+
+        throw new SeennError('Unknown error', 'UNKNOWN', 0);
+      }
+    }, method === 'GET' || !!options.idempotencyKey);
+  }
+
+  private async executeWithRetry<T>(
+    fn: () => Promise<T>,
+    idempotent: boolean
+  ): Promise<T> {
+    let lastError: Error | undefined;
+    const maxRetries = idempotent ? this.config.maxRetries : 1;
+
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error as Error;
+
+        // Don't retry on client errors (4xx) except rate limits
+        if (error instanceof SeennError) {
+          if (error.statusCode >= 400 && error.statusCode < 500) {
+            if (!(error instanceof RateLimitError)) {
+              throw error;
+            }
+          }
+        }
+
+        // Calculate delay with exponential backoff + jitter
+        if (attempt < maxRetries - 1) {
+          const baseDelay = 1000; // 1 second
+          const exponentialDelay = baseDelay * Math.pow(2, attempt);
+          const jitter = Math.random() * 0.2 * exponentialDelay;
+          const delay = Math.min(exponentialDelay + jitter, 30000); // Max 30s
+
+          if (this.config.debug) {
+            console.log(`[seenn] Retry attempt ${attempt + 1}/${maxRetries} after ${delay}ms`);
+          }
+
+          await this.sleep(delay);
+        }
+      }
+    }
+
+    throw lastError;
+  }
+
+  private async handleErrorResponse(response: Response): Promise<never> {
+    let errorData: ErrorResponse | undefined;
+
+    try {
+      errorData = (await response.json()) as ErrorResponse;
+    } catch {
+      // Response might not be JSON
+    }
+
+    const message = errorData?.error?.message || response.statusText;
+    const code = errorData?.error?.code || 'UNKNOWN';
+    const details = errorData?.error?.details;
+
+    switch (response.status) {
+      case 400:
+        throw new ValidationError(message, details);
+
+      case 401:
+        throw new AuthenticationError(message);
+
+      case 404:
+        throw new NotFoundError('Resource', details?.id as string || 'unknown');
+
+      case 429: {
+        const retryAfter = parseInt(response.headers.get('Retry-After') || '60', 10);
+        const limit = parseInt(response.headers.get('X-RateLimit-Limit') || '0', 10);
+        const remaining = parseInt(response.headers.get('X-RateLimit-Remaining') || '0', 10);
+        throw new RateLimitError(retryAfter, limit, remaining);
+      }
+
+      default:
+        throw new SeennError(message, code, response.status, details);
+    }
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// @seenn/node - Job State Transport SDK
+
+export { SeennClient } from './client.js';
+export type { SeennConfig } from './client.js';
+
+export { Job } from './job.js';
+export type { JobStatus, JobData, ProgressOptions, CompleteOptions, FailOptions } from './job.js';
+
+export type {
+  StartJobParams,
+  ProgressParams,
+  CompleteParams,
+  FailParams,
+  QueueInfo,
+  StageInfo,
+  JobResult,
+  JobError,
+} from './types.js';
+
+export { SeennError, RateLimitError, ValidationError, NotFoundError } from './errors.js';

package/src/job.ts

@@ -0,0 +1,201 @@
+import type { HttpClient } from './http.js';
+import type {
+  JobResponse,
+  ProgressParams,
+  CompleteParams,
+  FailParams,
+  QueueInfo,
+  StageInfo,
+  JobResult,
+  JobError,
+} from './types.js';
+
+export type JobStatus = 'pending' | 'running' | 'completed' | 'failed';
+
+export interface JobData {
+  id: string;
+  appId: string;
+  userId: string;
+  jobType: string;
+  title: string;
+  status: JobStatus;
+  progress: number;
+  message?: string;
+  queue?: QueueInfo;
+  stage?: StageInfo;
+  result?: JobResult;
+  error?: JobError;
+  metadata?: Record<string, unknown>;
+  estimatedCompletionAt?: string;
+  createdAt: Date;
+  updatedAt: Date;
+  completedAt?: Date;
+}
+
+export interface ProgressOptions {
+  message?: string;
+  queue?: QueueInfo;
+  stage?: StageInfo;
+  estimatedCompletionAt?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CompleteOptions {
+  result?: JobResult;
+  message?: string;
+}
+
+export interface FailOptions {
+  error: JobError;
+  retryable?: boolean;
+}
+
+/**
+ * Job instance with fluent API for updates
+ */
+export class Job implements JobData {
+  readonly id: string;
+  readonly appId: string;
+  readonly userId: string;
+  readonly jobType: string;
+  readonly title: string;
+  status: JobStatus;
+  progress: number;
+  message?: string;
+  queue?: QueueInfo;
+  stage?: StageInfo;
+  result?: JobResult;
+  error?: JobError;
+  metadata?: Record<string, unknown>;
+  estimatedCompletionAt?: string;
+  readonly createdAt: Date;
+  updatedAt: Date;
+  completedAt?: Date;
+
+  private readonly http: HttpClient;
+
+  constructor(data: JobResponse, http: HttpClient) {
+    this.id = data.id;
+    this.appId = data.appId;
+    this.userId = data.userId;
+    this.jobType = data.jobType;
+    this.title = data.title;
+    this.status = data.status;
+    this.progress = data.progress;
+    this.message = data.message;
+    this.queue = data.queue;
+    this.stage = data.stage;
+    this.result = data.result;
+    this.error = data.error;
+    this.metadata = data.metadata;
+    this.estimatedCompletionAt = data.estimatedCompletionAt;
+    this.createdAt = new Date(data.createdAt);
+    this.updatedAt = new Date(data.updatedAt);
+    this.completedAt = data.completedAt ? new Date(data.completedAt) : undefined;
+
+    this.http = http;
+  }
+
+  /**
+   * Update job progress (0-100)
+   */
+  async setProgress(progress: number, options?: ProgressOptions): Promise<this> {
+    const params: ProgressParams = {
+      progress,
+      ...options,
+    };
+
+    const response = await this.http.post<JobResponse>(
+      `/v1/jobs/${this.id}/progress`,
+      params
+    );
+
+    this.updateFromResponse(response);
+    return this;
+  }
+
+  /**
+   * Mark job as completed
+   */
+  async complete(options?: CompleteOptions): Promise<this> {
+    const params: CompleteParams = options || {};
+
+    const response = await this.http.post<JobResponse>(
+      `/v1/jobs/${this.id}/complete`,
+      params
+    );
+
+    this.updateFromResponse(response);
+    return this;
+  }
+
+  /**
+   * Mark job as failed
+   */
+  async fail(options: FailOptions): Promise<this> {
+    const params: FailParams = options;
+
+    const response = await this.http.post<JobResponse>(
+      `/v1/jobs/${this.id}/fail`,
+      params
+    );
+
+    this.updateFromResponse(response);
+    return this;
+  }
+
+  /**
+   * Refresh job data from server
+   */
+  async refresh(): Promise<this> {
+    const response = await this.http.get<JobResponse>(`/v1/jobs/${this.id}`);
+    this.updateFromResponse(response);
+    return this;
+  }
+
+  /**
+   * Check if job is in a terminal state
+   */
+  get isTerminal(): boolean {
+    return this.status === 'completed' || this.status === 'failed';
+  }
+
+  /**
+   * Get plain object representation
+   */
+  toJSON(): JobData {
+    return {
+      id: this.id,
+      appId: this.appId,
+      userId: this.userId,
+      jobType: this.jobType,
+      title: this.title,
+      status: this.status,
+      progress: this.progress,
+      message: this.message,
+      queue: this.queue,
+      stage: this.stage,
+      result: this.result,
+      error: this.error,
+      metadata: this.metadata,
+      estimatedCompletionAt: this.estimatedCompletionAt,
+      createdAt: this.createdAt,
+      updatedAt: this.updatedAt,
+      completedAt: this.completedAt,
+    };
+  }
+
+  private updateFromResponse(response: JobResponse): void {
+    this.status = response.status;
+    this.progress = response.progress;
+    this.message = response.message;
+    this.queue = response.queue;
+    this.stage = response.stage;
+    this.result = response.result;
+    this.error = response.error;
+    this.metadata = response.metadata;
+    this.estimatedCompletionAt = response.estimatedCompletionAt;
+    this.updatedAt = new Date(response.updatedAt);
+    this.completedAt = response.completedAt ? new Date(response.completedAt) : undefined;
+  }
+}

package/src/types.ts

@@ -0,0 +1,111 @@
+// Job Parameters
+
+export interface StartJobParams {
+  /** Unique job type identifier (e.g., 'video-generation', 'image-processing') */
+  jobType: string;
+  /** User ID who owns this job */
+  userId: string;
+  /** Human-readable title for the job */
+  title: string;
+  /** Optional metadata (max 10KB) */
+  metadata?: Record<string, unknown>;
+  /** Optional initial queue information */
+  queue?: QueueInfo;
+  /** Optional initial stage information */
+  stage?: StageInfo;
+  /** Optional estimated completion time (ISO 8601) */
+  estimatedCompletionAt?: string;
+  /** Optional TTL in seconds (default: 30 days) */
+  ttlSeconds?: number;
+}
+
+export interface ProgressParams {
+  /** Progress percentage (0-100) */
+  progress: number;
+  /** Optional status message */
+  message?: string;
+  /** Optional updated queue information */
+  queue?: QueueInfo;
+  /** Optional updated stage information */
+  stage?: StageInfo;
+  /** Optional updated ETA */
+  estimatedCompletionAt?: string;
+  /** Optional metadata update (merged with existing) */
+  metadata?: Record<string, unknown>;
+}
+
+export interface CompleteParams {
+  /** Result data (max 100KB) */
+  result?: JobResult;
+  /** Optional completion message */
+  message?: string;
+}
+
+export interface FailParams {
+  /** Error information */
+  error: JobError;
+  /** Whether the job can be retried */
+  retryable?: boolean;
+}
+
+// Nested Types
+
+export interface QueueInfo {
+  /** Current position in queue (1-based) */
+  position: number;
+  /** Total items in queue */
+  total?: number;
+  /** Optional queue name/tier */
+  queueName?: string;
+}
+
+export interface StageInfo {
+  /** Current stage name */
+  name: string;
+  /** Current stage number (1-based) */
+  current: number;
+  /** Total number of stages */
+  total: number;
+  /** Optional stage description */
+  description?: string;
+}
+
+export interface JobResult {
+  /** Result type identifier */
+  type?: string;
+  /** Result URL (e.g., generated video URL) */
+  url?: string;
+  /** Additional result data */
+  data?: Record<string, unknown>;
+}
+
+export interface JobError {
+  /** Error code */
+  code: string;
+  /** Human-readable error message */
+  message: string;
+  /** Additional error details */
+  details?: Record<string, unknown>;
+}
+
+// API Response Types
+
+export interface JobResponse {
+  id: string;
+  appId: string;
+  userId: string;
+  jobType: string;
+  title: string;
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  progress: number;
+  message?: string;
+  queue?: QueueInfo;
+  stage?: StageInfo;
+  result?: JobResult;
+  error?: JobError;
+  metadata?: Record<string, unknown>;
+  estimatedCompletionAt?: string;
+  createdAt: string;
+  updatedAt: string;
+  completedAt?: string;
+}