veryfront 0.1.75 → 0.1.76

package/src/src/jobs/jobs-client.ts

@@ -0,0 +1,503 @@
+/**
+ * Jobs client SDK for project-scoped background execution.
+ *
+ * Provides a stable public client for one-off jobs, cron jobs, job batches,
+ * and job target discovery on the Veryfront Jobs API.
+ */
+
+import { getVeryfrontCloudBootstrap } from "../platform/cloud/resolver.js";
+import {
+  requestWithRetry,
+  type RetryConfig,
+} from "../platform/adapters/veryfront-api-client/retry-handler.js";
+import { API_CLIENT_ERROR } from "../platform/adapters/veryfront-api-client/types.js";
+import { z } from "zod";
+import {
+  type CronJob,
+  CronJobSchema,
+  type CronJobStatus,
+  type Job,
+  type JobBatch,
+  JobBatchSchema,
+  type JobEventsResponse,
+  JobEventsResponseSchema,
+  type JobLogsResponse,
+  JobLogsResponseSchema,
+  JobSchema,
+  type JobStatus,
+  type JobTargetDefinition,
+  JobTargetDefinitionSchema,
+  type JobTargetDefinitionsResponse,
+  JobTargetDefinitionsResponseSchema,
+  type PaginatedCronJobsResponse,
+  PaginatedCronJobsResponseSchema,
+  type PaginatedJobsResponse,
+  PaginatedJobsResponseSchema,
+} from "./schemas.js";
+
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_INITIAL_RETRY_DELAY_MS = 1_000;
+const DEFAULT_MAX_RETRY_DELAY_MS = 10_000;
+
+export interface VeryfrontJobsClientConfig {
+  apiUrl?: string;
+  authToken?: string;
+  projectReference?: string;
+  retry?: Partial<RetryConfig>;
+}
+
+export interface ProjectScopedOptions {
+  projectReference?: string;
+}
+
+export interface ListJobsOptions extends ProjectScopedOptions {
+  cursor?: string;
+  limit?: number;
+  status?: JobStatus;
+  cronJobId?: string;
+  environmentId?: string;
+  batchId?: string;
+}
+
+export interface ListJobEventsOptions extends ProjectScopedOptions {
+  cursor?: string;
+  limit?: number;
+  direction?: "forward" | "backward";
+}
+
+export interface CreateJobInput extends ProjectScopedOptions {
+  name: string;
+  target: string;
+  environmentId?: string;
+  batchId?: string;
+  config?: Record<string, unknown>;
+  timeoutSeconds?: number;
+  backoffLimit?: number;
+}
+
+export interface ListBatchJobsOptions extends ProjectScopedOptions {
+  cursor?: string;
+  limit?: number;
+  status?: JobStatus;
+}
+
+export interface CreateCronJobInput extends ProjectScopedOptions {
+  name: string;
+  target: string;
+  environmentId?: string;
+  schedule: string;
+  timezone?: string;
+  config?: Record<string, unknown>;
+  timeoutSeconds?: number;
+  backoffLimit?: number;
+  concurrencyPolicy?: "Allow" | "Forbid" | "Replace";
+}
+
+export interface ListCronJobsOptions extends ProjectScopedOptions {
+  cursor?: string;
+  limit?: number;
+  status?: CronJobStatus;
+  environmentId?: string;
+}
+
+export interface UpdateCronJobInput extends ProjectScopedOptions {
+  name?: string;
+  schedule?: string;
+  timezone?: string;
+  config?: Record<string, unknown>;
+  timeoutSeconds?: number;
+  backoffLimit?: number;
+  concurrencyPolicy?: "Allow" | "Forbid" | "Replace";
+  status?: "active" | "paused";
+}
+
+type NamespaceMethod<TArgs extends unknown[], TResult> = (...args: TArgs) => Promise<TResult>;
+
+function toQueryParams(
+  values: Record<string, string | number | undefined>,
+): URLSearchParams {
+  const params = new URLSearchParams();
+
+  for (const [key, value] of Object.entries(values)) {
+    if (value == null) {
+      continue;
+    }
+    params.set(key, String(value));
+  }
+
+  return params;
+}
+
+function withQuery(path: string, params: URLSearchParams): string {
+  const query = params.toString();
+  return query.length > 0 ? `${path}?${query}` : path;
+}
+
+export class VeryfrontJobsClient {
+  private readonly retryConfig: RetryConfig;
+  private requestToken?: string;
+  private requestProjectReference?: string;
+
+  readonly cron: {
+    create: NamespaceMethod<[CreateCronJobInput], CronJob>;
+    list: NamespaceMethod<[ListCronJobsOptions?], PaginatedCronJobsResponse>;
+    get: NamespaceMethod<[cronJobId: string, options?: ProjectScopedOptions], CronJob>;
+    update: NamespaceMethod<[cronJobId: string, input: UpdateCronJobInput], CronJob>;
+    delete: NamespaceMethod<[cronJobId: string, options?: ProjectScopedOptions], CronJob>;
+    trigger: NamespaceMethod<[cronJobId: string, options?: ProjectScopedOptions], Job>;
+  };
+
+  readonly batches: {
+    get: NamespaceMethod<[batchId: string, options?: ProjectScopedOptions], JobBatch>;
+    listJobs: NamespaceMethod<
+      [batchId: string, options?: ListBatchJobsOptions],
+      PaginatedJobsResponse
+    >;
+  };
+
+  readonly targets: {
+    list: NamespaceMethod<[options?: ProjectScopedOptions], JobTargetDefinitionsResponse>;
+    get: NamespaceMethod<[target: string, options?: ProjectScopedOptions], JobTargetDefinition>;
+  };
+
+  constructor(private readonly config: VeryfrontJobsClientConfig = {}) {
+    this.retryConfig = {
+      maxRetries: config.retry?.maxRetries ?? DEFAULT_MAX_RETRIES,
+      initialDelay: config.retry?.initialDelay ?? DEFAULT_INITIAL_RETRY_DELAY_MS,
+      maxDelay: config.retry?.maxDelay ?? DEFAULT_MAX_RETRY_DELAY_MS,
+    };
+
+    this.cron = {
+      create: (input) => this.createCronJob(input),
+      list: (options) => this.listCronJobs(options),
+      get: (cronJobId, options) => this.getCronJob(cronJobId, options),
+      update: (cronJobId, input) => this.updateCronJob(cronJobId, input),
+      delete: (cronJobId, options) => this.deleteCronJob(cronJobId, options),
+      trigger: (cronJobId, options) => this.triggerCronJob(cronJobId, options),
+    };
+
+    this.batches = {
+      get: (batchId, options) => this.getBatch(batchId, options),
+      listJobs: (batchId, options) => this.listBatchJobs(batchId, options),
+    };
+
+    this.targets = {
+      list: (options) => this.listTargets(options),
+      get: (target, options) => this.getTarget(target, options),
+    };
+  }
+
+  setRequestToken(token: string): void {
+    this.requestToken = token;
+  }
+
+  clearRequestToken(): void {
+    this.requestToken = undefined;
+  }
+
+  setProjectReference(projectReference: string): void {
+    this.requestProjectReference = projectReference;
+  }
+
+  getProjectReference(): string | undefined {
+    return this.requestProjectReference ?? this.config.projectReference;
+  }
+
+  clearProjectReference(): void {
+    this.requestProjectReference = undefined;
+  }
+
+  create(input: CreateJobInput): Promise<Job> {
+    const { projectReference, environmentId, batchId, timeoutSeconds, backoffLimit, ...rest } =
+      input;
+
+    return this.requestProjectJson(
+      projectReference,
+      "/jobs",
+      JobSchema,
+      {
+        method: "POST",
+        body: {
+          ...rest,
+          environment_id: environmentId,
+          batch_id: batchId,
+          timeout_seconds: timeoutSeconds,
+          backoff_limit: backoffLimit,
+        },
+      },
+    );
+  }
+
+  list(options: ListJobsOptions = {}): Promise<PaginatedJobsResponse> {
+    const { projectReference, cursor, limit, status, cronJobId, environmentId, batchId } = options;
+
+    return this.requestProjectJson(
+      projectReference,
+      withQuery(
+        "/jobs",
+        toQueryParams({
+          cursor,
+          limit,
+          status,
+          cron_job_id: cronJobId,
+          environment_id: environmentId,
+          batch_id: batchId,
+        }),
+      ),
+      PaginatedJobsResponseSchema,
+    );
+  }
+
+  get(jobId: string, options: ProjectScopedOptions = {}): Promise<Job> {
+    return this.requestProjectJson(
+      options.projectReference,
+      `/jobs/${encodeURIComponent(jobId)}`,
+      JobSchema,
+    );
+  }
+
+  /**
+   * Canonical user-visible operational output for a job.
+   * Prefer this over raw logs for status, progress, and per-file activity.
+   */
+  events(jobId: string, options: ListJobEventsOptions = {}): Promise<JobEventsResponse> {
+    const { projectReference, cursor, limit, direction } = options;
+
+    return this.requestProjectJson(
+      projectReference,
+      withQuery(
+        `/jobs/${encodeURIComponent(jobId)}/events`,
+        toQueryParams({ cursor, limit, direction }),
+      ),
+      JobEventsResponseSchema,
+    );
+  }
+
+  /**
+   * Raw debugging output for a job.
+   * This is secondary to `events()` for operational UX.
+   */
+  logs(jobId: string, options: ProjectScopedOptions = {}): Promise<JobLogsResponse> {
+    return this.requestProjectJson(
+      options.projectReference,
+      `/jobs/${encodeURIComponent(jobId)}/logs`,
+      JobLogsResponseSchema,
+    );
+  }
+
+  cancel(jobId: string, options: ProjectScopedOptions = {}): Promise<Job> {
+    return this.requestProjectJson(
+      options.projectReference,
+      `/jobs/${encodeURIComponent(jobId)}/cancel`,
+      JobSchema,
+      { method: "POST" },
+    );
+  }
+
+  private createCronJob(input: CreateCronJobInput): Promise<CronJob> {
+    const {
+      projectReference,
+      environmentId,
+      timeoutSeconds,
+      backoffLimit,
+      concurrencyPolicy,
+      ...rest
+    } = input;
+
+    return this.requestProjectJson(
+      projectReference,
+      "/cron-jobs",
+      CronJobSchema,
+      {
+        method: "POST",
+        body: {
+          ...rest,
+          environment_id: environmentId,
+          timeout_seconds: timeoutSeconds,
+          backoff_limit: backoffLimit,
+          concurrency_policy: concurrencyPolicy,
+        },
+      },
+    );
+  }
+
+  private listCronJobs(options: ListCronJobsOptions = {}): Promise<PaginatedCronJobsResponse> {
+    const { projectReference, cursor, limit, status, environmentId } = options;
+
+    return this.requestProjectJson(
+      projectReference,
+      withQuery(
+        "/cron-jobs",
+        toQueryParams({
+          cursor,
+          limit,
+          status,
+          environment_id: environmentId,
+        }),
+      ),
+      PaginatedCronJobsResponseSchema,
+    );
+  }
+
+  private getCronJob(cronJobId: string, options: ProjectScopedOptions = {}): Promise<CronJob> {
+    return this.requestProjectJson(
+      options.projectReference,
+      `/cron-jobs/${encodeURIComponent(cronJobId)}`,
+      CronJobSchema,
+    );
+  }
+
+  private updateCronJob(cronJobId: string, input: UpdateCronJobInput): Promise<CronJob> {
+    const {
+      projectReference,
+      timeoutSeconds,
+      backoffLimit,
+      concurrencyPolicy,
+      ...rest
+    } = input;
+
+    return this.requestProjectJson(
+      projectReference,
+      `/cron-jobs/${encodeURIComponent(cronJobId)}`,
+      CronJobSchema,
+      {
+        method: "PATCH",
+        body: {
+          ...rest,
+          timeout_seconds: timeoutSeconds,
+          backoff_limit: backoffLimit,
+          concurrency_policy: concurrencyPolicy,
+        },
+      },
+    );
+  }
+
+  private deleteCronJob(cronJobId: string, options: ProjectScopedOptions = {}): Promise<CronJob> {
+    return this.requestProjectJson(
+      options.projectReference,
+      `/cron-jobs/${encodeURIComponent(cronJobId)}`,
+      CronJobSchema,
+      { method: "DELETE" },
+    );
+  }
+
+  private triggerCronJob(cronJobId: string, options: ProjectScopedOptions = {}): Promise<Job> {
+    return this.requestProjectJson(
+      options.projectReference,
+      `/cron-jobs/${encodeURIComponent(cronJobId)}/trigger`,
+      JobSchema,
+      { method: "POST" },
+    );
+  }
+
+  private getBatch(batchId: string, options: ProjectScopedOptions = {}): Promise<JobBatch> {
+    return this.requestProjectJson(
+      options.projectReference,
+      `/job-batches/${encodeURIComponent(batchId)}`,
+      JobBatchSchema,
+    );
+  }
+
+  private listBatchJobs(
+    batchId: string,
+    options: ListBatchJobsOptions = {},
+  ): Promise<PaginatedJobsResponse> {
+    const { projectReference, cursor, limit, status } = options;
+
+    return this.requestProjectJson(
+      projectReference,
+      withQuery(
+        `/job-batches/${encodeURIComponent(batchId)}/jobs`,
+        toQueryParams({
+          cursor,
+          limit,
+          status,
+        }),
+      ),
+      PaginatedJobsResponseSchema,
+    );
+  }
+
+  private listTargets(
+    options: ProjectScopedOptions = {},
+  ): Promise<JobTargetDefinitionsResponse> {
+    return this.requestProjectJson(
+      options.projectReference,
+      "/job-targets",
+      JobTargetDefinitionsResponseSchema,
+    );
+  }
+
+  private getTarget(
+    target: string,
+    options: ProjectScopedOptions = {},
+  ): Promise<JobTargetDefinition> {
+    return this.requestProjectJson(
+      options.projectReference,
+      `/job-targets/${encodeURIComponent(target)}`,
+      JobTargetDefinitionSchema,
+    );
+  }
+
+  private resolveApiUrl(): string {
+    return this.config.apiUrl ?? getVeryfrontCloudBootstrap().apiBaseUrl;
+  }
+
+  private resolveAuthToken(): string {
+    const token = this.requestToken ?? this.config.authToken ??
+      getVeryfrontCloudBootstrap().apiToken;
+    if (token) {
+      return token;
+    }
+
+    throw API_CLIENT_ERROR.create({
+      detail:
+        "Jobs auth not configured. Set VERYFRONT_API_TOKEN, provide request-scoped Veryfront credentials, or pass authToken explicitly.",
+      status: 401,
+    });
+  }
+
+  private resolveProjectReference(projectReference?: string): string {
+    const resolved = projectReference ??
+      this.requestProjectReference ??
+      this.config.projectReference ??
+      getVeryfrontCloudBootstrap().projectSlug;
+
+    if (resolved) {
+      return resolved;
+    }
+
+    throw API_CLIENT_ERROR.create({
+      detail:
+        "Jobs project reference not configured. Pass projectReference explicitly, set VERYFRONT_PROJECT_SLUG, or provide request-scoped Veryfront project context.",
+      status: 400,
+    });
+  }
+
+  private async requestProjectJson<TSchema extends z.ZodTypeAny>(
+    projectReference: string | undefined,
+    path: string,
+    schema: TSchema,
+    options: {
+      method?: "GET" | "POST" | "PATCH" | "DELETE";
+      body?: Record<string, unknown>;
+    } = {},
+  ): Promise<z.infer<TSchema>> {
+    const resolvedProjectReference = this.resolveProjectReference(projectReference);
+    const raw = await requestWithRetry(
+      `${this.resolveApiUrl()}/projects/${encodeURIComponent(resolvedProjectReference)}${path}`,
+      this.resolveAuthToken(),
+      this.retryConfig,
+      {
+        method: options.method,
+        body: options.body == null ? undefined : JSON.stringify(options.body),
+      },
+    );
+
+    return schema.parse(raw);
+  }
+}
+
+export function createJobsClient(config?: VeryfrontJobsClientConfig): VeryfrontJobsClient {
+  return new VeryfrontJobsClient(config);
+}

package/src/src/jobs/schemas.ts

@@ -0,0 +1,202 @@
+import { z } from "zod";
+
+export const JobStatusSchema = z.enum([
+  "submitted",
+  "working",
+  "completed",
+  "failed",
+  "canceled",
+]);
+
+export const CronJobStatusSchema = z.enum(["active", "paused", "deleting"]);
+
+export const ReservedJobTargetFamilySchema = z.enum(["task:*", "workflow:*", "deploy:*"]);
+
+export const PageInfoSchema = z.object({
+  self: z.string().nullable(),
+  first: z.literal(null),
+  next: z.string().nullable(),
+  prev: z.string().nullable(),
+});
+
+const JsonObjectSchema = z.record(z.unknown());
+
+export const KnowledgeIngestFileResultSchema = z.object({
+  source: z.string(),
+  localSourcePath: z.string(),
+  outputPath: z.string(),
+  remotePath: z.string(),
+  slug: z.string(),
+  sourceType: z.string(),
+  summary: z.string(),
+  stats: JsonObjectSchema,
+  warnings: z.array(z.string()),
+});
+
+export const JobResultSchema = z
+  .discriminatedUnion("kind", [
+    z.object({
+      kind: z.literal("knowledge_ingest"),
+      files: z.array(KnowledgeIngestFileResultSchema),
+    }),
+    z.object({
+      kind: z.literal("artifacts"),
+      artifacts: z.array(z.unknown()),
+    }),
+  ])
+  .nullable();
+
+export const JobSchema = z.object({
+  id: z.string().uuid(),
+  project_id: z.string().uuid(),
+  environment_id: z.string().uuid().nullable(),
+  cron_job_id: z.string().uuid().nullable(),
+  batch_id: z.string().uuid().nullable(),
+  name: z.string(),
+  status: JobStatusSchema,
+  target: z.string(),
+  config: JsonObjectSchema,
+  context_id: z.string().uuid().nullable(),
+  timeout_seconds: z.number(),
+  backoff_limit: z.number(),
+  exit_code: z.number().nullable(),
+  failed_reason: z.string().nullable(),
+  failure_detail: z.string().nullable(),
+  result: JobResultSchema,
+  started_at: z.string().nullable(),
+  completed_at: z.string().nullable(),
+  created_by: z.string().uuid().nullable(),
+  created_at: z.string(),
+  updated_at: z.string(),
+});
+
+export const PaginatedJobsResponseSchema = z.object({
+  data: z.array(JobSchema),
+  page_info: PageInfoSchema,
+});
+
+export const JobEventSchema = z.object({
+  timestamp: z.string(),
+  level: z.string(),
+  message: z.string(),
+  service: z.string(),
+  trace_id: z.string().optional(),
+  request_id: z.string().optional(),
+  metadata: z.record(z.string()).optional(),
+});
+
+export const JobEventsResponseSchema = z.object({
+  entries: z.array(JobEventSchema),
+  next_cursor: z.string().nullable(),
+  stats: z.object({
+    bytes_processed: z.number(),
+    lines_processed: z.number(),
+    query_time_ms: z.number(),
+  }),
+});
+
+export const JobLogsResponseSchema = z.object({
+  logs: z.string().nullable(),
+});
+
+export const KnowledgeIngestBatchSourceSchema = z.object({
+  label: z.string(),
+  path: z.string().nullable(),
+  upload_id: z.string().uuid().nullable(),
+  remote_path: z.string().nullable(),
+  warning_count: z.number().int().nonnegative(),
+});
+
+export const JobBatchStatusCountsSchema = z.object({
+  submitted: z.number().int().nonnegative(),
+  working: z.number().int().nonnegative(),
+  completed: z.number().int().nonnegative(),
+  failed: z.number().int().nonnegative(),
+  canceled: z.number().int().nonnegative(),
+});
+
+export const JobBatchResultSchema = z
+  .discriminatedUnion("kind", [
+    z.object({
+      kind: z.literal("knowledge_ingest"),
+      total_count: z.number().int().nonnegative(),
+      completed_count: z.number().int().nonnegative(),
+      processing: z.array(KnowledgeIngestBatchSourceSchema),
+      completed: z.array(KnowledgeIngestBatchSourceSchema),
+      remaining: z.array(KnowledgeIngestBatchSourceSchema),
+      remaining_label: z.enum(["Remaining Files", "Not Ingested Files"]),
+    }),
+  ])
+  .nullable();
+
+export const JobBatchSchema = z.object({
+  id: z.string().uuid(),
+  project_id: z.string().uuid(),
+  target: z.string().nullable(),
+  job_count: z.number().int().nonnegative(),
+  status_counts: JobBatchStatusCountsSchema,
+  created_at: z.string(),
+  updated_at: z.string(),
+  result: JobBatchResultSchema,
+});
+
+export const JobTargetDefinitionSchema = z.object({
+  target: z.string(),
+  family: z.string(),
+  description: z.string(),
+  input_schema: JsonObjectSchema,
+  output_schema: JsonObjectSchema.nullable(),
+});
+
+export const JobTargetDefinitionsResponseSchema = z.object({
+  reserved_families: z.array(ReservedJobTargetFamilySchema),
+  data: z.array(JobTargetDefinitionSchema),
+});
+
+export const CronJobSchema = z.object({
+  id: z.string().uuid(),
+  project_id: z.string().uuid(),
+  environment_id: z.string().uuid().nullable(),
+  name: z.string(),
+  status: CronJobStatusSchema,
+  target: z.string(),
+  schedule: z.string(),
+  timezone: z.string(),
+  config: JsonObjectSchema,
+  timeout_seconds: z.number(),
+  backoff_limit: z.number(),
+  concurrency_policy: z.string(),
+  last_scheduled_at: z.string().nullable(),
+  last_successful_at: z.string().nullable(),
+  created_by: z.string().uuid().nullable(),
+  created_at: z.string(),
+  updated_at: z.string(),
+});
+
+export const PaginatedCronJobsResponseSchema = z.object({
+  data: z.array(CronJobSchema),
+  page_info: PageInfoSchema,
+});
+
+export type JobStatus = z.infer<typeof JobStatusSchema>;
+export type CronJobStatus = z.infer<typeof CronJobStatusSchema>;
+export type ReservedJobTargetFamily = z.infer<typeof ReservedJobTargetFamilySchema>;
+
+export type KnowledgeIngestFileResult = z.infer<typeof KnowledgeIngestFileResultSchema>;
+export type JobResult = z.infer<typeof JobResultSchema>;
+export type Job = z.infer<typeof JobSchema>;
+export type PaginatedJobsResponse = z.infer<typeof PaginatedJobsResponseSchema>;
+export type JobEvent = z.infer<typeof JobEventSchema>;
+export type JobEventsResponse = z.infer<typeof JobEventsResponseSchema>;
+export type JobLogsResponse = z.infer<typeof JobLogsResponseSchema>;
+
+export type KnowledgeIngestBatchSource = z.infer<typeof KnowledgeIngestBatchSourceSchema>;
+export type JobBatchStatusCounts = z.infer<typeof JobBatchStatusCountsSchema>;
+export type JobBatchResult = z.infer<typeof JobBatchResultSchema>;
+export type JobBatch = z.infer<typeof JobBatchSchema>;
+
+export type JobTargetDefinition = z.infer<typeof JobTargetDefinitionSchema>;
+export type JobTargetDefinitionsResponse = z.infer<typeof JobTargetDefinitionsResponseSchema>;
+
+export type CronJob = z.infer<typeof CronJobSchema>;
+export type PaginatedCronJobsResponse = z.infer<typeof PaginatedCronJobsResponseSchema>;