Skip to main content

Types — TypeScript SDK

All request and response types used by FlareClient. Types are hand-rolled to match the Zeridion Flare REST API surface and exported from @zeridion/flare.

Enums​

JobState​

type JobState =
  | "pending"
  | "scheduled"
  | "processing"
  | "succeeded"
  | "failed"
  | "cancelled"
  | "dead_letter";

See the .NET SDK JobState reference for the full lifecycle state machine and transition rules — the states are identical across SDKs.

Request types​

CreateJobRequest​

Passed to flare.createJob().

interface CreateJobRequest {
  /** Job handler type name (e.g. "SendWelcomeEmail"). Required. */
  job_type: string;
  /** Arbitrary JSON payload passed to the handler. */
  payload?: unknown;
  /** Target queue name. Defaults to "default". */
  queue?: string;
  /** ISO-8601 datetime — schedule the job for later execution. */
  run_at?: string;
  /** Maximum retry attempts. Defaults to 3. */
  max_attempts?: number;
  /** Per-execution timeout in seconds. */
  timeout_seconds?: number;
  /** Idempotency key — a second create with the same key returns the existing job. */
  idempotency_key?: string;
  /** Arbitrary string tags visible in the dashboard. */
  tags?: Record<string, string>;
  /** Parent job ID — this job runs after the parent succeeds. */
  parent_job_id?: string;
}

ListJobsOptions​

Passed to flare.listJobs(). All fields are optional.

interface ListJobsOptions {
  state?: JobState;
  queue?: string;
  job_type?: string;
  created_after?: string;   // ISO-8601
  created_before?: string;  // ISO-8601
  limit?: number;
  cursor?: string;          // opaque pagination cursor from previous response
}

PollRequest​

Passed to flare.pollWorker().

interface PollRequest {
  worker_id: string;         // stable identifier for this worker process
  queues: string[];          // queues to poll; must be non-empty
  capacity?: number;         // max jobs to return (default: server-determined)
  job_types?: string[];      // restrict to specific job type names
}

AckRequest​

Passed to flare.ackWorker().

interface AckRequest {
  job_id: string;
  worker_id: string;
  /**
   * Three terminal values accepted by the server:
   * - "succeeded" — job ran to completion
   * - "failed"    — job threw; server decides retry vs dead-letter
   * - "cancelled" — worker observed `action: "cancel"` on a heartbeat and aborted
   * Do not confuse with AckResponse.action, which is "done" | "retry".
   */
  status: "succeeded" | "failed" | "cancelled";
  duration_ms?: number;
  error?: {
    type?: string;
    message?: string;
    stack_trace?: string;
  };
}

Response types​

CreateJobResponse​

Returned by flare.createJob().

interface CreateJobResponse {
  id: string;
  state: JobState;
  job_type: string;
  queue: string;
  created_at: string;    // ISO-8601
  run_at?: string;       // ISO-8601; present when scheduled
  attempt: number;
  max_attempts: number;
}

JobDetail​

Returned by flare.getJob() and in ListJobsResponse.jobs.

interface JobDetail {
  id: string;
  state: JobState;
  job_type: string;
  queue: string;
  payload?: unknown;
  created_at: string;
  started_at?: string;
  completed_at?: string;
  attempt: number;
  max_attempts: number;
  progress?: number;      // 0.0–1.0
  duration_ms?: number;
  error?: {
    type?: string;
    message?: string;
    stack_trace?: string;
  };
  tags?: Record<string, string>;
}

ListJobsResponse​

Returned by flare.listJobs().

interface ListJobsResponse {
  jobs: JobDetail[];
  cursor?: string;    // pass as opts.cursor for the next page
  has_more: boolean;
}

CancelJobResponse​

Returned by flare.cancelJob() on success.

interface CancelJobResponse {
  id: string;
  state: JobState;  // "cancelled"
}

RetryJobResponse​

Returned by flare.retryJob() on success.

interface RetryJobResponse {
  id: string;
  state: JobState;  // "pending"
  attempt: number;
}

PollResponse​

Returned by flare.pollWorker().

interface PollResponse {
  jobs: Array<{
    id: string;
    job_type: string;
    payload?: unknown;
    attempt: number;
    max_attempts: number;
    timeout_seconds: number;
    enqueued_at: string;
  }>;
}

AckResponse​

Returned by flare.ackWorker().

interface AckResponse {
  action: string;       // "completed" | "failed" | "retrying"
  retry_at?: string;    // ISO-8601; present when action is "retrying"
}

Pagination example​

let cursor: string | undefined;

do {
  const page = await flare.listJobs({ state: "failed", limit: 50, cursor });
  for (const job of page.jobs) {
    console.log(job.id, job.state);
  }
  cursor = page.cursor;
} while (cursor);

See also​