@seenn/node 0.1.1 → 0.2.1

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+export type ChildProgressMode = 'average' | 'weighted' | 'sequential';
 export interface StartJobParams {
     /** Unique job type identifier (e.g., 'video-generation', 'image-processing') */
     jobType: string;
@@ -5,16 +6,28 @@ export interface StartJobParams {
     userId: string;
     /** Human-readable title for the job */
     title: string;
+    /** Optional version for ETA tracking (e.g., '1.0', '2.1.0') */
+    version?: 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) */
+    /** Optional estimated completion time (ISO 8601) - overrides auto ETA */
     estimatedCompletionAt?: string;
+    /** Optional estimated duration in ms - overrides auto ETA */
+    estimatedDuration?: number;
     /** Optional TTL in seconds (default: 30 days) */
     ttlSeconds?: number;
+    /** Parent job ID (for child jobs) */
+    parentJobId?: string;
+    /** 0-based index within parent (for child jobs) */
+    childIndex?: number;
+    /** Total number of children (for parent jobs) */
+    totalChildren?: number;
+    /** How to calculate parent progress from children (default: 'average') */
+    childProgressMode?: ChildProgressMode;
 }
 export interface ProgressParams {
     /** Progress percentage (0-100) */
@@ -76,12 +89,97 @@ export interface JobError {
     /** Additional error details */
     details?: Record<string, unknown>;
 }
+/** Summary of a child job */
+export interface ChildJobSummary {
+    id: string;
+    childIndex: number;
+    title: string;
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    progress: number;
+    message?: string;
+    result?: JobResult;
+    error?: JobError;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+}
+/** Parent info included in child job responses */
+export interface ParentInfo {
+    parentJobId: string;
+    childIndex: number;
+}
+/** Children stats included in parent job responses */
+export interface ChildrenStats {
+    total: number;
+    completed: number;
+    failed: number;
+    running: number;
+    pending: number;
+}
+/** Parameters for creating a parent job */
+export interface CreateParentParams {
+    /** Unique job type identifier */
+    jobType: string;
+    /** User ID who owns this job */
+    userId: string;
+    /** Human-readable title for the parent job */
+    title: string;
+    /** Total number of children this parent will have */
+    childCount: number;
+    /** How to calculate parent progress from children (default: 'average') */
+    childProgressMode?: ChildProgressMode;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+    /** Optional TTL in seconds */
+    ttlSeconds?: number;
+}
+/** Parameters for creating a child job */
+export interface CreateChildParams {
+    /** Parent job ID */
+    parentJobId: string;
+    /** 0-based index within parent */
+    childIndex: number;
+    /** Unique job type identifier */
+    jobType: string;
+    /** User ID who owns this job */
+    userId: string;
+    /** Human-readable title for the child job */
+    title: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+    /** Optional TTL in seconds */
+    ttlSeconds?: number;
+}
+/** Parameters for creating a batch of jobs */
+export interface CreateBatchParams {
+    /** Unique job type identifier for all jobs */
+    jobType: string;
+    /** User ID who owns these jobs */
+    userId: string;
+    /** Human-readable title for the parent job */
+    parentTitle: string;
+    /** Titles for each child job */
+    childTitles: string[];
+    /** How to calculate parent progress from children (default: 'average') */
+    childProgressMode?: ChildProgressMode;
+    /** Optional metadata for parent job */
+    metadata?: Record<string, unknown>;
+    /** Optional TTL in seconds */
+    ttlSeconds?: number;
+}
+/** Parent job with all its children */
+export interface ParentWithChildren {
+    parent: JobResponse;
+    children: ChildJobSummary[];
+}
 export interface JobResponse {
     id: string;
     appId: string;
     userId: string;
     jobType: string;
     title: string;
+    /** Job version for ETA tracking */
+    version?: string;
     status: 'pending' | 'running' | 'completed' | 'failed';
     progress: number;
     message?: string;
@@ -90,9 +188,54 @@ export interface JobResponse {
     result?: JobResult;
     error?: JobError;
     metadata?: Record<string, unknown>;
+    /** Estimated completion time (ISO 8601) */
     estimatedCompletionAt?: string;
+    /** ETA confidence score (0.0 - 1.0) */
+    etaConfidence?: number;
+    /** Number of historical jobs used to calculate ETA */
+    etaBasedOn?: number;
     createdAt: string;
     updatedAt: string;
+    /** When the job actually started running */
+    startedAt?: string;
     completedAt?: string;
+    /** Parent info (if this is a child job) */
+    parent?: ParentInfo;
+    /** Children stats (if this is a parent job) */
+    children?: ChildrenStats;
+    /** Child progress mode (if this is a parent job) */
+    childProgressMode?: ChildProgressMode;
+}
+/** ETA statistics for a job type */
+export interface EtaStats {
+    /** Job type identifier */
+    jobType: string;
+    /** Version (or 'default') */
+    version: string;
+    /** Number of completed jobs in statistics */
+    count: number;
+    /** Average duration in milliseconds */
+    avgDuration: number;
+    /** Median duration (50th percentile) in milliseconds */
+    p50Duration: number;
+    /** 95th percentile duration in milliseconds */
+    p95Duration: number;
+    /** Minimum recorded duration */
+    minDuration: number;
+    /** Maximum recorded duration */
+    maxDuration: number;
+    /** Confidence score for ETA predictions (0.0 - 1.0) */
+    confidence: number;
+    /** Last time stats were updated */
+    lastUpdated: string;
+}
+/** Default ETA configuration for job types */
+export interface DefaultEtaConfig {
+    /** Job type identifier */
+    jobType: string;
+    /** Default duration in milliseconds (used when no history) */
+    defaultDuration: number;
+    /** Optional version */
+    version?: string;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAC7B,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,yCAAyC;IACzC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,yCAAyC;IACzC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,oDAAoD;IACpD,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,yCAAyC;IACzC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,2BAA2B;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,wBAAwB;IACxB,KAAK,EAAE,QAAQ,CAAC;IAChB,qCAAqC;IACrC,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAID,MAAM,WAAW,SAAS;IACxB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,QAAQ;IACvB,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAID,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -1,3 +1,2 @@
-// Job Parameters
 export {};
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,iBAAiB"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seenn/node",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Seenn Node.js Backend SDK - Open source job state transport for real-time progress tracking",
   "type": "module",
   "main": "dist/index.js",
@@ -30,6 +30,8 @@
     "ulid": "^2.3.0"
   },
   "devDependencies": {
+    "@types/node": "^25.0.10",
+    "typescript": "^5.9.3",
     "vitest": "^2.1.0"
   },
   "keywords": [

package/src/client.ts

@@ -1,6 +1,16 @@
 import { Job } from './job.js';
 import { HttpClient } from './http.js';
-import type { StartJobParams, JobResponse } from './types.js';
+import type {
+  StartJobParams,
+  JobResponse,
+  CreateParentParams,
+  CreateChildParams,
+  CreateBatchParams,
+  ParentWithChildren,
+  ChildJobSummary,
+  EtaStats,
+  DefaultEtaConfig,
+} from './types.js';
 
 export interface SeennConfig {
   /** API key (sk_live_xxx or sk_test_xxx) */
@@ -78,6 +88,145 @@ export class SeennClient {
           nextCursor: response.nextCursor,
         };
       },
+
+      /**
+       * Create a parent job (batch container)
+       */
+      createParent: async (params: CreateParentParams): Promise<Job> => {
+        const response = await this.http.post<JobResponse>('/v1/jobs', {
+          jobType: params.jobType,
+          userId: params.userId,
+          title: params.title,
+          totalChildren: params.childCount,
+          childProgressMode: params.childProgressMode,
+          metadata: params.metadata,
+          ttlSeconds: params.ttlSeconds,
+        });
+        return new Job(response, this.http);
+      },
+
+      /**
+       * Create a child job under a parent
+       */
+      createChild: async (params: CreateChildParams): Promise<Job> => {
+        const response = await this.http.post<JobResponse>('/v1/jobs', {
+          jobType: params.jobType,
+          userId: params.userId,
+          title: params.title,
+          parentJobId: params.parentJobId,
+          childIndex: params.childIndex,
+          metadata: params.metadata,
+          ttlSeconds: params.ttlSeconds,
+        });
+        return new Job(response, this.http);
+      },
+
+      /**
+       * Get a parent job with all its children
+       */
+      getWithChildren: async (parentJobId: string): Promise<{ parent: Job; children: ChildJobSummary[] }> => {
+        const response = await this.http.get<ParentWithChildren>(
+          `/v1/jobs/${parentJobId}/children`
+        );
+        return {
+          parent: new Job(response.parent, this.http),
+          children: response.children,
+        };
+      },
+
+      /**
+       * Create a batch of jobs (parent + children) in one go
+       * Returns the parent job and all child jobs
+       */
+      createBatch: async (params: CreateBatchParams): Promise<{ parent: Job; children: Job[] }> => {
+        // Create parent job first
+        const parent = await this.jobs.createParent({
+          jobType: params.jobType,
+          userId: params.userId,
+          title: params.parentTitle,
+          childCount: params.childTitles.length,
+          childProgressMode: params.childProgressMode,
+          metadata: params.metadata,
+          ttlSeconds: params.ttlSeconds,
+        });
+
+        // Create all children in parallel
+        const childPromises = params.childTitles.map((title, index) =>
+          this.jobs.createChild({
+            parentJobId: parent.id,
+            childIndex: index,
+            jobType: params.jobType,
+            userId: params.userId,
+            title,
+            ttlSeconds: params.ttlSeconds,
+          })
+        );
+
+        const children = await Promise.all(childPromises);
+
+        // Refresh parent to get updated counters
+        await parent.refresh();
+
+        return { parent, children };
+      },
+    };
+  }
+
+  /**
+   * ETA (Estimated Time of Arrival) resource
+   */
+  get eta() {
+    return {
+      /**
+       * Get ETA statistics for a job type
+       */
+      getStats: async (jobType: string, version?: string): Promise<EtaStats | null> => {
+        const params = new URLSearchParams({ jobType });
+        if (version) params.set('version', version);
+
+        try {
+          const response = await this.http.get<EtaStats>(`/v1/eta/stats?${params}`);
+          return response;
+        } catch (error: unknown) {
+          // Return null if no stats exist yet
+          if (error && typeof error === 'object' && 'status' in error && error.status === 404) {
+            return null;
+          }
+          throw error;
+        }
+      },
+
+      /**
+       * List all ETA statistics for the app
+       */
+      list: async (): Promise<EtaStats[]> => {
+        const response = await this.http.get<{ stats: EtaStats[] }>('/v1/eta/stats');
+        return response.stats;
+      },
+
+      /**
+       * Set default ETA for a job type (used when no history exists)
+       */
+      setDefault: async (config: DefaultEtaConfig): Promise<void> => {
+        await this.http.post('/v1/eta/defaults', config);
+      },
+
+      /**
+       * Get default ETA configurations
+       */
+      getDefaults: async (): Promise<DefaultEtaConfig[]> => {
+        const response = await this.http.get<{ defaults: DefaultEtaConfig[] }>('/v1/eta/defaults');
+        return response.defaults;
+      },
+
+      /**
+       * Reset ETA statistics for a job type (admin use)
+       */
+      reset: async (jobType: string, version?: string): Promise<void> => {
+        const params = new URLSearchParams({ jobType });
+        if (version) params.set('version', version);
+        await this.http.post(`/v1/eta/reset?${params}`, {});
+      },
     };
   }
 }

package/src/index.ts

@@ -15,6 +15,18 @@ export type {
   StageInfo,
   JobResult,
   JobError,
+  // Parent-child types
+  ChildProgressMode,
+  ChildJobSummary,
+  ParentInfo,
+  ChildrenStats,
+  CreateParentParams,
+  CreateChildParams,
+  CreateBatchParams,
+  ParentWithChildren,
+  // ETA types
+  EtaStats,
+  DefaultEtaConfig,
 } from './types.js';
 
 export { SeennError, RateLimitError, ValidationError, NotFoundError } from './errors.js';

package/src/job.ts

@@ -8,6 +8,9 @@ import type {
   StageInfo,
   JobResult,
   JobError,
+  ParentInfo,
+  ChildrenStats,
+  ChildProgressMode,
 } from './types.js';
 
 export type JobStatus = 'pending' | 'running' | 'completed' | 'failed';
@@ -18,6 +21,7 @@ export interface JobData {
   userId: string;
   jobType: string;
   title: string;
+  version?: string;
   status: JobStatus;
   progress: number;
   message?: string;
@@ -27,9 +31,16 @@ export interface JobData {
   error?: JobError;
   metadata?: Record<string, unknown>;
   estimatedCompletionAt?: string;
+  etaConfidence?: number;
+  etaBasedOn?: number;
   createdAt: Date;
   updatedAt: Date;
+  startedAt?: Date;
   completedAt?: Date;
+  // Parent-child fields
+  parent?: ParentInfo;
+  children?: ChildrenStats;
+  childProgressMode?: ChildProgressMode;
 }
 
 export interface ProgressOptions {
@@ -59,6 +70,7 @@ export class Job implements JobData {
   readonly userId: string;
   readonly jobType: string;
   readonly title: string;
+  readonly version?: string;
   status: JobStatus;
   progress: number;
   message?: string;
@@ -68,9 +80,16 @@ export class Job implements JobData {
   error?: JobError;
   metadata?: Record<string, unknown>;
   estimatedCompletionAt?: string;
+  etaConfidence?: number;
+  etaBasedOn?: number;
   readonly createdAt: Date;
   updatedAt: Date;
+  startedAt?: Date;
   completedAt?: Date;
+  // Parent-child fields
+  parent?: ParentInfo;
+  children?: ChildrenStats;
+  childProgressMode?: ChildProgressMode;
 
   private readonly http: HttpClient;
 
@@ -80,6 +99,7 @@ export class Job implements JobData {
     this.userId = data.userId;
     this.jobType = data.jobType;
     this.title = data.title;
+    this.version = data.version;
     this.status = data.status;
     this.progress = data.progress;
     this.message = data.message;
@@ -89,9 +109,16 @@ export class Job implements JobData {
     this.error = data.error;
     this.metadata = data.metadata;
     this.estimatedCompletionAt = data.estimatedCompletionAt;
+    this.etaConfidence = data.etaConfidence;
+    this.etaBasedOn = data.etaBasedOn;
     this.createdAt = new Date(data.createdAt);
     this.updatedAt = new Date(data.updatedAt);
+    this.startedAt = data.startedAt ? new Date(data.startedAt) : undefined;
     this.completedAt = data.completedAt ? new Date(data.completedAt) : undefined;
+    // Parent-child fields
+    this.parent = data.parent;
+    this.children = data.children;
+    this.childProgressMode = data.childProgressMode;
 
     this.http = http;
   }
@@ -160,6 +187,51 @@ export class Job implements JobData {
     return this.status === 'completed' || this.status === 'failed';
   }
 
+  /**
+   * Check if this is a parent job (has children)
+   */
+  get isParent(): boolean {
+    return this.children !== undefined;
+  }
+
+  /**
+   * Check if this is a child job (has a parent)
+   */
+  get isChild(): boolean {
+    return this.parent !== undefined;
+  }
+
+  /**
+   * Get child progress summary (only for parent jobs)
+   */
+  get childProgress(): { completed: number; failed: number; running: number; pending: number; total: number } | null {
+    if (!this.children) return null;
+    return {
+      completed: this.children.completed,
+      failed: this.children.failed,
+      running: this.children.running,
+      pending: this.children.pending,
+      total: this.children.total,
+    };
+  }
+
+  /**
+   * Get remaining time until ETA in milliseconds (null if no ETA)
+   */
+  get etaRemaining(): number | null {
+    if (!this.estimatedCompletionAt) return null;
+    const eta = new Date(this.estimatedCompletionAt).getTime();
+    return Math.max(0, eta - Date.now());
+  }
+
+  /**
+   * Check if job is past its ETA but still running
+   */
+  get isPastEta(): boolean {
+    if (!this.estimatedCompletionAt || this.isTerminal) return false;
+    return new Date(this.estimatedCompletionAt).getTime() < Date.now();
+  }
+
   /**
    * Get plain object representation
    */
@@ -170,6 +242,7 @@ export class Job implements JobData {
       userId: this.userId,
       jobType: this.jobType,
       title: this.title,
+      version: this.version,
       status: this.status,
       progress: this.progress,
       message: this.message,
@@ -179,9 +252,15 @@ export class Job implements JobData {
       error: this.error,
       metadata: this.metadata,
       estimatedCompletionAt: this.estimatedCompletionAt,
+      etaConfidence: this.etaConfidence,
+      etaBasedOn: this.etaBasedOn,
       createdAt: this.createdAt,
       updatedAt: this.updatedAt,
+      startedAt: this.startedAt,
       completedAt: this.completedAt,
+      parent: this.parent,
+      children: this.children,
+      childProgressMode: this.childProgressMode,
     };
   }
 
@@ -195,7 +274,13 @@ export class Job implements JobData {
     this.error = response.error;
     this.metadata = response.metadata;
     this.estimatedCompletionAt = response.estimatedCompletionAt;
+    this.etaConfidence = response.etaConfidence;
+    this.etaBasedOn = response.etaBasedOn;
     this.updatedAt = new Date(response.updatedAt);
+    this.startedAt = response.startedAt ? new Date(response.startedAt) : undefined;
     this.completedAt = response.completedAt ? new Date(response.completedAt) : undefined;
+    this.parent = response.parent;
+    this.children = response.children;
+    this.childProgressMode = response.childProgressMode;
   }
 }