@seenn/types 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# @seenn/types
+
+Shared TypeScript types for all Seenn SDKs. This package is the **single source of truth** for type definitions.
+
+## Installation
+
+```bash
+npm install @seenn/types
+# or
+pnpm add @seenn/types
+```
+
+## Usage
+
+```typescript
+import type {
+  SeennJob,
+  JobStatus,
+  StageInfo,
+  ConnectionState,
+  SSEEventType,
+} from '@seenn/types';
+```
+
+## SDK Sync Guidelines
+
+When updating types in this package:
+
+1. **Bump version** in package.json
+2. **Publish** to npm: `npm publish`
+3. **Update all SDKs** to use new version:
+   - `@seenn/react-native`
+   - `@seenn/node`
+   - `seenn_flutter` (generate from TypeScript)
+
+### Version Compatibility
+
+| @seenn/types | @seenn/react-native | @seenn/node | seenn_flutter |
+|--------------|---------------------|-------------|---------------|
+| 0.1.0        | 0.2.6+              | 0.2.2+      | 0.1.0+        |
+
+## Type Categories
+
+### Core Types
+- `SeennJob` - Main job object
+- `JobStatus` - Status enum
+- `StageInfo`, `QueueInfo` - Progress info
+- `JobResult`, `JobError` - Completion data
+
+### Parent-Child Types
+- `ParentInfo`, `ChildrenStats` - Relationship data
+- `ChildJobSummary` - Child job info
+- `ParentWithChildren` - Full parent with children
+
+### SSE Types
+- `ConnectionState` - SSE connection states
+- `SSEEventType` - All SSE event types
+- `SSEEvent` - Event wrapper
+
+### API Types
+- `CreateJobParams`, `UpdateJobParams` - Request types
+- `CompleteJobParams`, `FailJobParams` - Completion types
+
+### Live Activity Types
+- `LiveActivityStartParams`, `LiveActivityUpdateParams`
+- `LiveActivityEndParams`, `LiveActivityResult`
+
+## Flutter Integration
+
+For Flutter SDK, generate Dart types from this package:
+
+```bash
+# In seenn-platform root
+pnpm run generate:flutter-types
+```
+
+This runs `scripts/generate-flutter-types.ts` which converts TypeScript to Dart.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,416 @@
+/**
+ * @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
+ */
+/**
+ * Job status values
+ */
+type JobStatus = 'pending' | 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+/**
+ * How parent job progress is calculated from children
+ */
+type ChildProgressMode = 'average' | 'weighted' | 'sequential';
+/**
+ * Main job object returned by API and SSE
+ */
+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 information for multi-step jobs
+ */
+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
+ */
+interface QueueInfo {
+    /** Position in queue (1-based) */
+    position: number;
+    /** Total items in queue */
+    total?: number;
+    /** Queue name/identifier */
+    queueName?: string;
+}
+/**
+ * Job result on successful completion
+ */
+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
+ */
+interface JobError {
+    /** Error code for programmatic handling */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Additional error details */
+    details?: Record<string, unknown>;
+}
+/**
+ * Parent info for child jobs
+ */
+interface ParentInfo {
+    /** Parent job ID */
+    parentJobId: string;
+    /** Child index within parent (0-based) */
+    childIndex: number;
+}
+/**
+ * Children stats for parent jobs
+ */
+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)
+ */
+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
+ */
+interface ParentWithChildren {
+    /** Parent job */
+    parent: SeennJob;
+    /** List of child jobs */
+    children: ChildJobSummary[];
+}
+/**
+ * Connection state for SSE
+ */
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+/**
+ * SSE event types
+ */
+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
+ */
+interface SSEEvent {
+    /** Event type */
+    event: SSEEventType;
+    /** Event data */
+    data: unknown;
+    /** Event ID for replay */
+    id?: string;
+}
+/**
+ * In-app message types
+ */
+type InAppMessageType = 'job_complete_banner' | 'job_failed_modal' | 'job_toast';
+/**
+ * In-app message for UI notifications
+ */
+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;
+}
+/**
+ * Create job request parameters
+ */
+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
+ */
+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
+ */
+interface CompleteJobParams {
+    /** Job result */
+    result?: JobResult;
+    /** Final message */
+    message?: string;
+}
+/**
+ * Fail job request parameters
+ */
+interface FailJobParams {
+    /** Error details */
+    error: JobError;
+}
+/**
+ * Webhook event types
+ */
+type WebhookEventType = 'job.started' | 'job.progress' | 'job.completed' | 'job.failed' | 'job.cancelled';
+/**
+ * Webhook payload
+ */
+interface WebhookPayload {
+    /** Event type */
+    event: WebhookEventType;
+    /** Job data */
+    job: SeennJob;
+    /** Event timestamp (ISO 8601) */
+    timestamp: string;
+    /** Webhook delivery ID */
+    deliveryId: string;
+}
+/**
+ * ETA statistics for a workflow/jobType
+ */
+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;
+}
+/**
+ * Base SDK configuration
+ */
+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 start parameters
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+interface LiveActivityPushTokenEvent {
+    /** Job ID */
+    jobId: string;
+    /** APNs push token */
+    token: string;
+}
+/**
+ * SDK version info
+ */
+declare const SDK_VERSION = "0.1.0";
+/**
+ * Minimum API version required
+ */
+declare const MIN_API_VERSION = "1.0.0";
+/**
+ * SSE protocol version
+ */
+declare const SSE_PROTOCOL_VERSION = "1.0";
+
+export { type ChildJobSummary, type ChildProgressMode, type ChildrenStats, type CompleteJobParams, type ConnectionState, type CreateJobParams, type EtaStats, type FailJobParams, type InAppMessage, type InAppMessageType, type JobError, type JobResult, type JobStatus, type LiveActivityEndParams, type LiveActivityPushTokenEvent, type LiveActivityResult, type LiveActivityStartParams, type LiveActivityUpdateParams, MIN_API_VERSION, type ParentInfo, type ParentWithChildren, type QueueInfo, SDK_VERSION, type SSEEvent, type SSEEventType, SSE_PROTOCOL_VERSION, type SeennConfig, type SeennJob, type StageInfo, type UpdateJobParams, type WebhookEventType, type WebhookPayload };