@seenn/types 0.1.0

package/src/index.ts

@@ -0,0 +1,525 @@
+/**
+ * @seenn/types - Shared TypeScript types for Seenn SDKs
+ *
+ * This package is the single source of truth for all Seenn type definitions.
+ * All SDK packages (react-native, node, flutter) should depend on this package.
+ *
+ * @version 0.1.0
+ * @license MIT
+ */
+
+// ============================================
+// Core Job Types
+// ============================================
+
+/**
+ * Job status values
+ */
+export type JobStatus =
+  | 'pending'
+  | 'queued'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled';
+
+/**
+ * How parent job progress is calculated from children
+ */
+export type ChildProgressMode = 'average' | 'weighted' | 'sequential';
+
+/**
+ * Main job object returned by API and SSE
+ */
+export interface SeennJob {
+  /** Unique job identifier (ULID format) */
+  jobId: string;
+  /** User who owns this job */
+  userId: string;
+  /** Application ID */
+  appId: string;
+  /** Current job status */
+  status: JobStatus;
+  /** Human-readable job title */
+  title: string;
+  /** Job type for categorization */
+  jobType: string;
+  /** Workflow ID for ETA tracking (default: jobType) */
+  workflowId?: string;
+  /** Progress percentage (0-100) */
+  progress: number;
+  /** Current status message */
+  message?: string;
+  /** Stage information for multi-step jobs */
+  stage?: StageInfo;
+  /** Estimated completion timestamp (ISO 8601) */
+  estimatedCompletionAt?: string;
+  /** ETA confidence score (0.0 - 1.0) */
+  etaConfidence?: number;
+  /** Number of historical jobs used to calculate ETA */
+  etaBasedOn?: number;
+  /** Queue position info */
+  queue?: QueueInfo;
+  /** Job result on completion */
+  result?: JobResult;
+  /** Error details on failure */
+  error?: JobError;
+  /** Custom metadata */
+  metadata?: Record<string, unknown>;
+  /** Parent info (if this is a child job) */
+  parent?: ParentInfo;
+  /** Children stats (if this is a parent job) */
+  children?: ChildrenStats;
+  /** Progress calculation mode for parent jobs */
+  childProgressMode?: ChildProgressMode;
+  /** Job creation timestamp (ISO 8601) */
+  createdAt: string;
+  /** Last update timestamp (ISO 8601) */
+  updatedAt: string;
+  /** When the job started running (ISO 8601) */
+  startedAt?: string;
+  /** Job completion timestamp (ISO 8601) */
+  completedAt?: string;
+}
+
+// ============================================
+// Stage & Queue Types
+// ============================================
+
+/**
+ * Stage information for multi-step jobs
+ */
+export interface StageInfo {
+  /** Current stage name */
+  name: string;
+  /** Current stage index (1-based) */
+  current: number;
+  /** Total number of stages */
+  total: number;
+  /** Optional stage description */
+  description?: string;
+}
+
+/**
+ * Queue position information
+ */
+export interface QueueInfo {
+  /** Position in queue (1-based) */
+  position: number;
+  /** Total items in queue */
+  total?: number;
+  /** Queue name/identifier */
+  queueName?: string;
+}
+
+// ============================================
+// Result & Error Types
+// ============================================
+
+/**
+ * Job result on successful completion
+ */
+export interface JobResult {
+  /** Result type (e.g., 'video', 'image', 'file') */
+  type?: string;
+  /** Result URL if applicable */
+  url?: string;
+  /** Additional result data */
+  data?: Record<string, unknown>;
+}
+
+/**
+ * Error details on job failure
+ */
+export interface JobError {
+  /** Error code for programmatic handling */
+  code: string;
+  /** Human-readable error message */
+  message: string;
+  /** Additional error details */
+  details?: Record<string, unknown>;
+}
+
+// ============================================
+// Parent-Child Types
+// ============================================
+
+/**
+ * Parent info for child jobs
+ */
+export interface ParentInfo {
+  /** Parent job ID */
+  parentJobId: string;
+  /** Child index within parent (0-based) */
+  childIndex: number;
+}
+
+/**
+ * Children stats for parent jobs
+ */
+export interface ChildrenStats {
+  /** Total number of children */
+  total: number;
+  /** Number of completed children */
+  completed: number;
+  /** Number of failed children */
+  failed: number;
+  /** Number of running children */
+  running: number;
+  /** Number of pending children */
+  pending: number;
+}
+
+/**
+ * Summary of a child job (used in parent.children array)
+ */
+export interface ChildJobSummary {
+  /** Child job ID */
+  id: string;
+  /** Child index within parent (0-based) */
+  childIndex: number;
+  /** Child job title */
+  title: string;
+  /** Child job status */
+  status: JobStatus;
+  /** Child progress (0-100) */
+  progress: number;
+  /** Child status message */
+  message?: string;
+  /** Child result */
+  result?: JobResult;
+  /** Child error */
+  error?: JobError;
+  /** Child creation timestamp */
+  createdAt: string;
+  /** Child last update timestamp */
+  updatedAt: string;
+  /** Child completion timestamp */
+  completedAt?: string;
+}
+
+/**
+ * Parent job with all its children
+ */
+export interface ParentWithChildren {
+  /** Parent job */
+  parent: SeennJob;
+  /** List of child jobs */
+  children: ChildJobSummary[];
+}
+
+// ============================================
+// SSE Types
+// ============================================
+
+/**
+ * Connection state for SSE
+ */
+export type ConnectionState =
+  | 'disconnected'
+  | 'connecting'
+  | 'connected'
+  | 'reconnecting';
+
+/**
+ * SSE event types
+ */
+export type SSEEventType =
+  | 'connected'
+  | 'job.sync'
+  | 'job.started'
+  | 'job.progress'
+  | 'job.completed'
+  | 'job.failed'
+  | 'job.cancelled'
+  | 'child.progress'
+  | 'parent.updated'
+  | 'in_app_message'
+  | 'connection.idle'
+  | 'heartbeat'
+  | 'error';
+
+/**
+ * SSE event wrapper
+ */
+export interface SSEEvent {
+  /** Event type */
+  event: SSEEventType;
+  /** Event data */
+  data: unknown;
+  /** Event ID for replay */
+  id?: string;
+}
+
+// ============================================
+// In-App Message Types
+// ============================================
+
+/**
+ * In-app message types
+ */
+export type InAppMessageType =
+  | 'job_complete_banner'
+  | 'job_failed_modal'
+  | 'job_toast';
+
+/**
+ * In-app message for UI notifications
+ */
+export interface InAppMessage {
+  /** Message ID */
+  messageId: string;
+  /** Message type */
+  type: InAppMessageType;
+  /** Associated job ID */
+  jobId: string;
+  /** Message title */
+  title: string;
+  /** Message body */
+  body?: string;
+  /** Call-to-action text */
+  cta?: string;
+  /** Call-to-action URL */
+  ctaUrl?: string;
+}
+
+// ============================================
+// API Types
+// ============================================
+
+/**
+ * Create job request parameters
+ */
+export interface CreateJobParams {
+  /** User ID */
+  userId: string;
+  /** Job type */
+  jobType: string;
+  /** Job title */
+  title: string;
+  /** Workflow ID for ETA tracking (default: jobType) */
+  workflowId?: string;
+  /** Initial message */
+  message?: string;
+  /** Custom metadata */
+  metadata?: Record<string, unknown>;
+  /** Estimated duration in ms (for ETA default) */
+  estimatedDuration?: number;
+  /** Parent job ID (for child jobs) */
+  parentJobId?: string;
+  /** Child index (for child jobs) */
+  childIndex?: number;
+  /** Total children (for parent jobs) */
+  totalChildren?: number;
+  /** Child progress mode (for parent jobs) */
+  childProgressMode?: ChildProgressMode;
+}
+
+/**
+ * Update job request parameters
+ */
+export interface UpdateJobParams {
+  /** New progress (0-100) */
+  progress?: number;
+  /** New message */
+  message?: string;
+  /** New stage info */
+  stage?: StageInfo;
+  /** Custom metadata to merge */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Complete job request parameters
+ */
+export interface CompleteJobParams {
+  /** Job result */
+  result?: JobResult;
+  /** Final message */
+  message?: string;
+}
+
+/**
+ * Fail job request parameters
+ */
+export interface FailJobParams {
+  /** Error details */
+  error: JobError;
+}
+
+// ============================================
+// Webhook Types
+// ============================================
+
+/**
+ * Webhook event types
+ */
+export type WebhookEventType =
+  | 'job.started'
+  | 'job.progress'
+  | 'job.completed'
+  | 'job.failed'
+  | 'job.cancelled';
+
+/**
+ * Webhook payload
+ */
+export interface WebhookPayload {
+  /** Event type */
+  event: WebhookEventType;
+  /** Job data */
+  job: SeennJob;
+  /** Event timestamp (ISO 8601) */
+  timestamp: string;
+  /** Webhook delivery ID */
+  deliveryId: string;
+}
+
+// ============================================
+// ETA Types
+// ============================================
+
+/**
+ * ETA statistics for a workflow/jobType
+ */
+export interface EtaStats {
+  /** ETA key (workflowId or jobType) */
+  etaKey: string;
+  /** Number of completed jobs */
+  count: number;
+  /** Average duration in ms */
+  avgDuration: number;
+  /** Minimum duration in ms */
+  minDuration: number;
+  /** Maximum duration in ms */
+  maxDuration: number;
+  /** Default duration if no history */
+  defaultDuration?: number;
+  /** Last updated timestamp */
+  lastUpdated: string;
+}
+
+// ============================================
+// SDK Configuration Types
+// ============================================
+
+/**
+ * Base SDK configuration
+ */
+export interface SeennConfig {
+  /** API base URL */
+  baseUrl: string;
+  /** Authentication token (pk_* for client, sk_* for server) */
+  authToken?: string;
+  /** SSE endpoint URL (default: baseUrl + /v1/sse) */
+  sseUrl?: string;
+  /** Enable auto-reconnect (default: true) */
+  reconnect?: boolean;
+  /** Reconnect interval in ms (default: 1000) */
+  reconnectInterval?: number;
+  /** Max reconnect attempts (default: 10) */
+  maxReconnectAttempts?: number;
+  /** Enable debug logging (default: false) */
+  debug?: boolean;
+}
+
+// ============================================
+// Live Activity Types (iOS/Android)
+// ============================================
+
+/**
+ * Live Activity start parameters
+ */
+export interface LiveActivityStartParams {
+  /** Job ID */
+  jobId: string;
+  /** Activity title */
+  title: string;
+  /** Job type for icon selection */
+  jobType?: string;
+  /** Initial progress (0-100) */
+  initialProgress?: number;
+  /** Initial message */
+  initialMessage?: string;
+}
+
+/**
+ * Live Activity update parameters
+ */
+export interface LiveActivityUpdateParams {
+  /** Job ID */
+  jobId: string;
+  /** New progress (0-100) */
+  progress?: number;
+  /** New status */
+  status?: JobStatus;
+  /** New message */
+  message?: string;
+  /** Stage info */
+  stage?: StageInfo;
+  /** ETA timestamp (Unix ms) */
+  estimatedEndTime?: number;
+}
+
+/**
+ * Live Activity end parameters
+ */
+export interface LiveActivityEndParams {
+  /** Job ID */
+  jobId: string;
+  /** Final status */
+  finalStatus?: JobStatus;
+  /** Final progress */
+  finalProgress?: number;
+  /** Final message */
+  message?: string;
+  /** Result URL */
+  resultUrl?: string;
+  /** Error message */
+  errorMessage?: string;
+  /** Dismiss after seconds (default: 300) */
+  dismissAfter?: number;
+}
+
+/**
+ * Live Activity result
+ */
+export interface LiveActivityResult {
+  /** Success flag */
+  success: boolean;
+  /** Activity ID (platform-specific) */
+  activityId?: string;
+  /** Associated job ID */
+  jobId?: string;
+  /** Error message if failed */
+  error?: string;
+}
+
+/**
+ * Push token event for Live Activity updates
+ */
+export interface LiveActivityPushTokenEvent {
+  /** Job ID */
+  jobId: string;
+  /** APNs push token */
+  token: string;
+}
+
+// ============================================
+// Version & Compatibility
+// ============================================
+
+/**
+ * SDK version info
+ */
+export const SDK_VERSION = '0.1.0';
+
+/**
+ * Minimum API version required
+ */
+export const MIN_API_VERSION = '1.0.0';
+
+/**
+ * SSE protocol version
+ */
+export const SSE_PROTOCOL_VERSION = '1.0';