veryfront 0.1.75 → 0.1.76

package/README.md

@@ -18,6 +18,8 @@ Purpose-built for TypeScript and React, Veryfront gives you everything you need
 
 - [**Workflows**](https://veryfront.com/docs/code/guides/workflows) — Orchestrate multi-step AI pipelines with branching, parallelism, and human-in-the-loop approval gates.
 
+- [**Jobs & Cron Jobs**](https://veryfront.com/docs/code/guides/jobs) — Run durable project-scoped background work now or on a schedule through the Veryfront platform.
+
 - [**Multi-Agent**](https://veryfront.com/docs/code/guides/multi-agent) — Compose agents that delegate to each other as tools for complex, coordinated tasks.
 
 - [**Memory & Streaming**](https://veryfront.com/docs/code/guides/memory-and-streaming) — Give agents conversation history and streaming responses. Built-in chat UI components for React.

package/esm/cli/commands/files/command.d.ts

@@ -31,8 +31,8 @@ declare const FilesGetArgsSchema: z.ZodObject<{
     quiet: z.ZodDefault<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     json: boolean;
-    quiet: boolean;
     remotePath: string;
+    quiet: boolean;
     projectSlug?: string | undefined;
     projectDir?: string | undefined;
     output?: string | undefined;
@@ -54,8 +54,8 @@ declare const FilesPutArgsSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     json: boolean;
     from: string;
-    quiet: boolean;
     remotePath: string;
+    quiet: boolean;
     projectSlug?: string | undefined;
     projectDir?: string | undefined;
 }, {
@@ -74,8 +74,8 @@ declare const FilesDeleteArgsSchema: z.ZodObject<{
     quiet: z.ZodDefault<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     json: boolean;
-    quiet: boolean;
     remotePath: string;
+    quiet: boolean;
     projectSlug?: string | undefined;
     projectDir?: string | undefined;
 }, {

package/esm/deno.d.ts

@@ -22,6 +22,7 @@ declare namespace _default {
         "./workflow/discovery": string;
         "./prompt": string;
         "./resource": string;
+        "./jobs": string;
         "./mcp": string;
         "./middleware": string;
         "./utils": string;
@@ -51,6 +52,7 @@ declare namespace _default {
         "veryfront/components/ai": string;
         "veryfront/sandbox": string;
         "veryfront/embedding": string;
+        "veryfront/jobs": string;
         "veryfront/agent/react": string;
         "veryfront/agent/testing": string;
         "veryfront/agent/middleware": string;
@@ -124,6 +126,7 @@ declare namespace _default {
         "#veryfront/react": string;
         "#veryfront/rendering": string;
         "#veryfront/resource": string;
+        "#veryfront/jobs": string;
         "#veryfront/routing": string;
         "#veryfront/security": string;
         "#veryfront/skill": string;
@@ -243,6 +246,7 @@ declare namespace _default {
         "tailwindcss/colors": string;
         redis: string;
         pg: string;
+        jose: string;
         "@opentelemetry/api": string;
         "@opentelemetry/core": string;
         "@opentelemetry/context-async-hooks": string;
@@ -291,6 +295,7 @@ declare namespace _default {
         "test:coverage:integration": string;
         "coverage:report": string;
         "coverage:html": string;
+        bench: string;
         clean: string;
         lint: string;
         fmt: string;

package/esm/deno.js

@@ -1,6 +1,6 @@
 export default {
     "name": "veryfront",
-    "version": "0.1.75",
+    "version": "0.1.76",
     "license": "Apache-2.0",
     "nodeModulesDir": "auto",
     "exclude": [
@@ -32,6 +32,7 @@ export default {
         "./workflow/discovery": "./src/workflow/discovery/index.ts",
         "./prompt": "./src/prompt/index.ts",
         "./resource": "./src/resource/index.ts",
+        "./jobs": "./src/jobs/index.ts",
         "./mcp": "./src/mcp/index.ts",
         "./middleware": "./src/middleware/index.ts",
         "./utils": "./src/utils/index.ts",
@@ -61,6 +62,7 @@ export default {
         "veryfront/components/ai": "./src/react/components/ai/index.ts",
         "veryfront/sandbox": "./src/sandbox/index.ts",
         "veryfront/embedding": "./src/embedding/index.ts",
+        "veryfront/jobs": "./src/jobs/index.ts",
         "veryfront/agent/react": "./src/agent/react/index.ts",
         "veryfront/agent/testing": "./src/agent/testing/index.ts",
         "veryfront/agent/middleware": "./src/agent/middleware/index.ts",
@@ -134,6 +136,7 @@ export default {
         "#veryfront/react": "./src/react/index.ts",
         "#veryfront/rendering": "./src/rendering/index.ts",
         "#veryfront/resource": "./src/resource/index.ts",
+        "#veryfront/jobs": "./src/jobs/index.ts",
         "#veryfront/routing": "./src/routing/index.ts",
         "#veryfront/security": "./src/security/index.ts",
         "#veryfront/skill": "./src/skill/index.ts",
@@ -253,6 +256,7 @@ export default {
         "tailwindcss/colors": "https://esm.sh/tailwindcss@4.1.8/colors",
         "redis": "npm:redis@4.6.13",
         "pg": "npm:pg",
+        "jose": "npm:jose@5.9.6",
         "@opentelemetry/api": "npm:@opentelemetry/api@1",
         "@opentelemetry/core": "npm:@opentelemetry/core@1",
         "@opentelemetry/context-async-hooks": "npm:@opentelemetry/context-async-hooks@1",
@@ -290,11 +294,11 @@ export default {
     "tasks": {
         "setup": "deno run --allow-all scripts/setup.ts",
         "generate": "deno run -A scripts/build/generate-templates-manifest.ts && deno run -A scripts/build/generate-dev-ui-manifest.ts && deno run -A scripts/build/prebundle-client-scripts.ts && deno run -A scripts/build/prebundle-bridge.ts",
-        "start": "deno task generate && deno run --allow-all cli/main.ts",
-        "start:headless": "deno task generate && deno run --allow-all cli/main.ts --headless",
-        "proxy": "deno task generate && deno run --allow-all cli/main.ts serve --mode=proxy",
+        "start": "deno task generate && deno run --allow-read --allow-write --allow-net --allow-env --allow-run --allow-sys --unstable-worker-options --unstable-net cli/main.ts",
+        "start:headless": "deno task generate && deno run --allow-read --allow-write --allow-net --allow-env --allow-run --allow-sys --unstable-worker-options --unstable-net cli/main.ts --headless",
+        "proxy": "deno task generate && deno run --allow-read --allow-write --allow-net --allow-env --allow-run --allow-sys --unstable-worker-options --unstable-net cli/main.ts serve --mode=proxy",
         "dev": "deno task generate && deno run --allow-all cli/main.ts dev",
-        "production": "deno task generate && deno run --allow-all cli/main.ts serve --mode=production",
+        "production": "deno task generate && deno run --allow-read --allow-write --allow-net --allow-env --allow-run --allow-sys --unstable-worker-options --unstable-net cli/main.ts serve --mode=production",
         "build:prepare": "deno run -A scripts/build/generate-integrations-module.ts && deno task generate && deno run -A scripts/build/prepare-framework-sources.ts",
         "build": "deno task build:prepare && deno run -A scripts/build/compile-binary.ts --output ./bin/veryfront",
         "build:npm": "deno run -A scripts/build/generate-integrations-module.ts && deno task generate && deno run -A scripts/build/build-npm-dnt.ts",
@@ -309,11 +313,12 @@ export default {
         "test:coverage:integration": "rm -rf coverage && VF_DISABLE_LRU_INTERVAL=1 SSR_TRANSFORM_PER_PROJECT_LIMIT=0 REVALIDATION_PER_PROJECT_LIMIT=0 NODE_ENV=production LOG_FORMAT=text deno test --no-check --parallel --fail-fast --allow-all --coverage=coverage '--ignore=tests/e2e,tests/integration/compiled-binary-e2e.test.ts' tests --unstable-worker-options --unstable-net || exit 1",
         "coverage:report": "deno coverage coverage --include=src/ --exclude=tests --exclude=src/**/*_test.ts --exclude=src/**/*_test.tsx --exclude=src/**/*.test.ts --exclude=src/**/*.test.tsx --lcov > coverage/lcov.info && deno run --allow-read scripts/lint/check-coverage.ts 80",
         "coverage:html": "deno coverage coverage --include=src/ --exclude=tests --exclude=src/**/*_test.ts --exclude=src/**/*_test.tsx --exclude=src/**/*.test.ts --exclude=src/**/*.test.tsx --html",
+        "bench": "VF_DISABLE_LRU_INTERVAL=1 NODE_ENV=production LOG_FORMAT=text deno bench --no-check --allow-all --unstable-worker-options --unstable-net $(find src -name '*.bench.ts')",
         "clean": "rm -rf .cache/",
         "lint": "DENO_NO_PACKAGE_JSON=1 deno lint src/ cli/",
         "fmt": "deno fmt src/ cli/",
         "fmt:check": "deno fmt --check src/ cli/",
-        "typecheck": "deno task generate && deno check src/index.ts cli/main.ts src/server/index.ts src/routing/api/index.ts src/rendering/index.ts src/platform/index.ts src/platform/adapters/index.ts src/build/index.ts src/build/production-build/index.ts src/transforms/index.ts src/config/index.ts src/utils/index.ts src/data/index.ts src/security/index.ts src/middleware/index.ts src/server/handlers/dev/index.ts src/server/handlers/request/api/index.ts src/rendering/cache/index.ts src/rendering/cache/stores/index.ts src/rendering/rsc/actions/index.ts src/html/index.ts src/modules/index.ts src/proxy/main.ts src/chat/index.ts src/markdown/index.ts src/mdx/index.ts src/fs/index.ts src/oauth/index.ts src/agent/index.ts src/tool/index.ts src/workflow/index.ts src/prompt/index.ts src/resource/index.ts src/mcp/index.ts src/provider/index.ts",
+        "typecheck": "deno task generate && deno check src/index.ts cli/main.ts src/server/index.ts src/routing/api/index.ts src/rendering/index.ts src/platform/index.ts src/platform/adapters/index.ts src/build/index.ts src/build/production-build/index.ts src/transforms/index.ts src/config/index.ts src/utils/index.ts src/data/index.ts src/security/index.ts src/middleware/index.ts src/server/handlers/dev/index.ts src/server/handlers/request/api/index.ts src/rendering/cache/index.ts src/rendering/cache/stores/index.ts src/rendering/rsc/actions/index.ts src/html/index.ts src/modules/index.ts src/proxy/main.ts src/chat/index.ts src/markdown/index.ts src/mdx/index.ts src/fs/index.ts src/oauth/index.ts src/agent/index.ts src/tool/index.ts src/workflow/index.ts src/prompt/index.ts src/resource/index.ts src/jobs/index.ts src/mcp/index.ts src/provider/index.ts",
         "verify": "deno task generate && deno fmt --check src/ cli/ && DENO_NO_PACKAGE_JSON=1 deno lint src/ cli/ && deno task lint:style && deno task lint:cli-boundary && deno task lint:wildcard-exports && deno task lint:barrel-jsdoc && deno task docs:validate && deno task typecheck && deno task test && deno task test:e2e:binary",
         "verify:quick": "deno task generate && deno fmt --check src/ cli/ && DENO_NO_PACKAGE_JSON=1 deno lint src/ cli/ && deno task lint:style && deno task lint:cli-boundary && deno task lint:wildcard-exports && deno task lint:barrel-jsdoc && deno task docs:validate && deno task typecheck",
         "docs": "rm -rf docs/reference && deno run --allow-read --allow-write --allow-run scripts/docs/generate-api-reference.ts",

package/esm/src/data/server-data-fetcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-data-fetcher.d.ts","sourceRoot":"","sources":["../../../src/src/data/server-data-fetcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AASxE;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,iBAAiB;IAC5B,KAAK,CACH,UAAU,EAAE,YAAY,EACxB,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,UAAU,CAAC;IA8EtB;;OAEG;YACW,aAAa;IA2C3B;;;OAGG;IACH,OAAO,CAAC,QAAQ;CAGjB"}
+{"version":3,"file":"server-data-fetcher.d.ts","sourceRoot":"","sources":["../../../src/src/data/server-data-fetcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAYxE;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,iBAAiB;IAC5B,KAAK,CACH,UAAU,EAAE,YAAY,EACxB,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,UAAU,CAAC;IA8EtB;;OAEG;YACW,aAAa;IAoE3B;;;OAGG;IACH,OAAO,CAAC,QAAQ;CAGjB"}

package/esm/src/data/server-data-fetcher.js

@@ -5,6 +5,7 @@ import { TimeoutError, withTimeoutThrow } from "../rendering/utils/stream-utils.
 import { withSpan } from "../observability/tracing/otlp-setup.js";
 import { CircuitBreakerOpen, getCircuitBreaker } from "../utils/circuit-breaker.js";
 import { getWorkerPool, isDataIsolationEnabled } from "../security/sandbox/worker-pool.js";
+import { MAX_WORKER_BODY_BYTES, } from "../security/sandbox/worker-types.js";
 export class ServerDataFetcher {
     fetch(pageModule, context, options) {
         if (typeof pageModule.getServerData !== "function") {
@@ -71,7 +72,22 @@ export class ServerDataFetcher {
      */
     async fetchIsolated(modulePath, projectDir, context) {
         const pool = getWorkerPool();
-        const body = context.request?.body ? new Uint8Array(await context.request.arrayBuffer()) : null;
+        let body = null;
+        if (context.request?.body) {
+            // Fast path: reject before buffering if Content-Length is known
+            const contentLength = context.request.headers?.get("content-length");
+            if (contentLength) {
+                const bytes = parseInt(contentLength, 10);
+                if (bytes > MAX_WORKER_BODY_BYTES) {
+                    throw new Error(`Request body too large for isolated data fetch (${(bytes / 1024 / 1024).toFixed(1)} MB, limit ${MAX_WORKER_BODY_BYTES / 1024 / 1024} MB)`);
+                }
+            }
+            body = new Uint8Array(await context.request.arrayBuffer());
+            // Fallback: check actual size for chunked/streaming bodies
+            if (body.byteLength > MAX_WORKER_BODY_BYTES) {
+                throw new Error(`Request body too large for isolated data fetch (${(body.byteLength / 1024 / 1024).toFixed(1)} MB, limit ${MAX_WORKER_BODY_BYTES / 1024 / 1024} MB)`);
+            }
+        }
         const workerResponse = await pool.execute(projectDir, [projectDir], {
             type: "fetch-data",
             id: dntShim.crypto.randomUUID(),

package/esm/src/jobs/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Jobs module for durable project-scoped background execution.
+ *
+ * Provides a public SDK surface for one-off jobs, cron jobs, batch summaries,
+ * job target discovery, and the canonical split between user-visible `events`
+ * and raw debugging `logs`.
+ *
+ * @module
+ *
+ * @example
+ * ```ts
+ * import { VeryfrontJobsClient } from "veryfront/jobs";
+ *
+ * const jobs = new VeryfrontJobsClient({
+ *   authToken: process.env.VERYFRONT_API_TOKEN,
+ *   projectReference: "my-project",
+ * });
+ *
+ * const job = await jobs.create({
+ *   name: "Ingest 1 file",
+ *   target: "task:knowledge-ingest",
+ *   config: {
+ *     file_count: 1,
+ *     upload_ids: ["00000000-0000-0000-0000-000000000000"],
+ *   },
+ * });
+ *
+ * const events = await jobs.events(job.id);
+ * ```
+ */
+import "../../_dnt.polyfills.js";
+export { type CreateCronJobInput, type CreateJobInput, createJobsClient, type ListBatchJobsOptions, type ListCronJobsOptions, type ListJobEventsOptions, type ListJobsOptions, type ProjectScopedOptions, type UpdateCronJobInput, VeryfrontJobsClient, type VeryfrontJobsClientConfig, } from "./jobs-client.js";
+export { type CronJob, CronJobSchema, type CronJobStatus, CronJobStatusSchema, type Job, type JobBatch, type JobBatchResult, JobBatchResultSchema, JobBatchSchema, type JobBatchStatusCounts, JobBatchStatusCountsSchema, type JobEvent, JobEventSchema, type JobEventsResponse, JobEventsResponseSchema, type JobLogsResponse, JobLogsResponseSchema, type JobResult, JobResultSchema, JobSchema, type JobStatus, JobStatusSchema, type JobTargetDefinition, JobTargetDefinitionSchema, type JobTargetDefinitionsResponse, JobTargetDefinitionsResponseSchema, type KnowledgeIngestBatchSource, KnowledgeIngestBatchSourceSchema, type KnowledgeIngestFileResult, KnowledgeIngestFileResultSchema, PageInfoSchema, type PaginatedCronJobsResponse, PaginatedCronJobsResponseSchema, type PaginatedJobsResponse, PaginatedJobsResponseSchema, type ReservedJobTargetFamily, ReservedJobTargetFamilySchema, } from "./schemas.js";
+//# sourceMappingURL=index.d.ts.map

package/esm/src/jobs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/jobs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,yBAAyB,CAAC;AAGjC,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,gBAAgB,EAChB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,mBAAmB,EACnB,KAAK,yBAAyB,GAC/B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,OAAO,EACZ,aAAa,EACb,KAAK,aAAa,EAClB,mBAAmB,EACnB,KAAK,GAAG,EACR,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,oBAAoB,EACpB,cAAc,EACd,KAAK,oBAAoB,EACzB,0BAA0B,EAC1B,KAAK,QAAQ,EACb,cAAc,EACd,KAAK,iBAAiB,EACtB,uBAAuB,EACvB,KAAK,eAAe,EACpB,qBAAqB,EACrB,KAAK,SAAS,EACd,eAAe,EACf,SAAS,EACT,KAAK,SAAS,EACd,eAAe,EACf,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,KAAK,4BAA4B,EACjC,kCAAkC,EAClC,KAAK,0BAA0B,EAC/B,gCAAgC,EAChC,KAAK,yBAAyB,EAC9B,+BAA+B,EAC/B,cAAc,EACd,KAAK,yBAAyB,EAC9B,+BAA+B,EAC/B,KAAK,qBAAqB,EAC1B,2BAA2B,EAC3B,KAAK,uBAAuB,EAC5B,6BAA6B,GAC9B,MAAM,cAAc,CAAC"}

package/esm/src/jobs/index.js

@@ -0,0 +1,33 @@
+/**
+ * Jobs module for durable project-scoped background execution.
+ *
+ * Provides a public SDK surface for one-off jobs, cron jobs, batch summaries,
+ * job target discovery, and the canonical split between user-visible `events`
+ * and raw debugging `logs`.
+ *
+ * @module
+ *
+ * @example
+ * ```ts
+ * import { VeryfrontJobsClient } from "veryfront/jobs";
+ *
+ * const jobs = new VeryfrontJobsClient({
+ *   authToken: process.env.VERYFRONT_API_TOKEN,
+ *   projectReference: "my-project",
+ * });
+ *
+ * const job = await jobs.create({
+ *   name: "Ingest 1 file",
+ *   target: "task:knowledge-ingest",
+ *   config: {
+ *     file_count: 1,
+ *     upload_ids: ["00000000-0000-0000-0000-000000000000"],
+ *   },
+ * });
+ *
+ * const events = await jobs.events(job.id);
+ * ```
+ */
+import "../../_dnt.polyfills.js";
+export { createJobsClient, VeryfrontJobsClient, } from "./jobs-client.js";
+export { CronJobSchema, CronJobStatusSchema, JobBatchResultSchema, JobBatchSchema, JobBatchStatusCountsSchema, JobEventSchema, JobEventsResponseSchema, JobLogsResponseSchema, JobResultSchema, JobSchema, JobStatusSchema, JobTargetDefinitionSchema, JobTargetDefinitionsResponseSchema, KnowledgeIngestBatchSourceSchema, KnowledgeIngestFileResultSchema, PageInfoSchema, PaginatedCronJobsResponseSchema, PaginatedJobsResponseSchema, ReservedJobTargetFamilySchema, } from "./schemas.js";

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

@@ -0,0 +1,134 @@
+/**
+ * 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 { type RetryConfig } from "../platform/adapters/veryfront-api-client/retry-handler.js";
+import { type CronJob, type CronJobStatus, type Job, type JobBatch, type JobEventsResponse, type JobLogsResponse, type JobStatus, type JobTargetDefinition, type JobTargetDefinitionsResponse, type PaginatedCronJobsResponse, type PaginatedJobsResponse } from "./schemas.js";
+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>;
+export declare class VeryfrontJobsClient {
+    private readonly config;
+    private readonly retryConfig;
+    private requestToken?;
+    private requestProjectReference?;
+    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(config?: VeryfrontJobsClientConfig);
+    setRequestToken(token: string): void;
+    clearRequestToken(): void;
+    setProjectReference(projectReference: string): void;
+    getProjectReference(): string | undefined;
+    clearProjectReference(): void;
+    create(input: CreateJobInput): Promise<Job>;
+    list(options?: ListJobsOptions): Promise<PaginatedJobsResponse>;
+    get(jobId: string, options?: ProjectScopedOptions): Promise<Job>;
+    /**
+     * 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>;
+    /**
+     * Raw debugging output for a job.
+     * This is secondary to `events()` for operational UX.
+     */
+    logs(jobId: string, options?: ProjectScopedOptions): Promise<JobLogsResponse>;
+    cancel(jobId: string, options?: ProjectScopedOptions): Promise<Job>;
+    private createCronJob;
+    private listCronJobs;
+    private getCronJob;
+    private updateCronJob;
+    private deleteCronJob;
+    private triggerCronJob;
+    private getBatch;
+    private listBatchJobs;
+    private listTargets;
+    private getTarget;
+    private resolveApiUrl;
+    private resolveAuthToken;
+    private resolveProjectReference;
+    private requestProjectJson;
+}
+export declare function createJobsClient(config?: VeryfrontJobsClientConfig): VeryfrontJobsClient;
+export {};
+//# sourceMappingURL=jobs-client.d.ts.map

package/esm/src/jobs/jobs-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs-client.d.ts","sourceRoot":"","sources":["../../../src/src/jobs/jobs-client.ts"],"names":[],"mappings":"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"}

package/esm/src/jobs/jobs-client.js

@@ -0,0 +1,218 @@
+/**
+ * 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, } from "../platform/adapters/veryfront-api-client/retry-handler.js";
+import { API_CLIENT_ERROR } from "../platform/adapters/veryfront-api-client/types.js";
+import { CronJobSchema, JobBatchSchema, JobEventsResponseSchema, JobLogsResponseSchema, JobSchema, JobTargetDefinitionSchema, JobTargetDefinitionsResponseSchema, PaginatedCronJobsResponseSchema, 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;
+function toQueryParams(values) {
+    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, params) {
+    const query = params.toString();
+    return query.length > 0 ? `${path}?${query}` : path;
+}
+export class VeryfrontJobsClient {
+    config;
+    retryConfig;
+    requestToken;
+    requestProjectReference;
+    cron;
+    batches;
+    targets;
+    constructor(config = {}) {
+        this.config = config;
+        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) {
+        this.requestToken = token;
+    }
+    clearRequestToken() {
+        this.requestToken = undefined;
+    }
+    setProjectReference(projectReference) {
+        this.requestProjectReference = projectReference;
+    }
+    getProjectReference() {
+        return this.requestProjectReference ?? this.config.projectReference;
+    }
+    clearProjectReference() {
+        this.requestProjectReference = undefined;
+    }
+    create(input) {
+        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 = {}) {
+        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, options = {}) {
+        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, options = {}) {
+        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, options = {}) {
+        return this.requestProjectJson(options.projectReference, `/jobs/${encodeURIComponent(jobId)}/logs`, JobLogsResponseSchema);
+    }
+    cancel(jobId, options = {}) {
+        return this.requestProjectJson(options.projectReference, `/jobs/${encodeURIComponent(jobId)}/cancel`, JobSchema, { method: "POST" });
+    }
+    createCronJob(input) {
+        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,
+            },
+        });
+    }
+    listCronJobs(options = {}) {
+        const { projectReference, cursor, limit, status, environmentId } = options;
+        return this.requestProjectJson(projectReference, withQuery("/cron-jobs", toQueryParams({
+            cursor,
+            limit,
+            status,
+            environment_id: environmentId,
+        })), PaginatedCronJobsResponseSchema);
+    }
+    getCronJob(cronJobId, options = {}) {
+        return this.requestProjectJson(options.projectReference, `/cron-jobs/${encodeURIComponent(cronJobId)}`, CronJobSchema);
+    }
+    updateCronJob(cronJobId, input) {
+        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,
+            },
+        });
+    }
+    deleteCronJob(cronJobId, options = {}) {
+        return this.requestProjectJson(options.projectReference, `/cron-jobs/${encodeURIComponent(cronJobId)}`, CronJobSchema, { method: "DELETE" });
+    }
+    triggerCronJob(cronJobId, options = {}) {
+        return this.requestProjectJson(options.projectReference, `/cron-jobs/${encodeURIComponent(cronJobId)}/trigger`, JobSchema, { method: "POST" });
+    }
+    getBatch(batchId, options = {}) {
+        return this.requestProjectJson(options.projectReference, `/job-batches/${encodeURIComponent(batchId)}`, JobBatchSchema);
+    }
+    listBatchJobs(batchId, options = {}) {
+        const { projectReference, cursor, limit, status } = options;
+        return this.requestProjectJson(projectReference, withQuery(`/job-batches/${encodeURIComponent(batchId)}/jobs`, toQueryParams({
+            cursor,
+            limit,
+            status,
+        })), PaginatedJobsResponseSchema);
+    }
+    listTargets(options = {}) {
+        return this.requestProjectJson(options.projectReference, "/job-targets", JobTargetDefinitionsResponseSchema);
+    }
+    getTarget(target, options = {}) {
+        return this.requestProjectJson(options.projectReference, `/job-targets/${encodeURIComponent(target)}`, JobTargetDefinitionSchema);
+    }
+    resolveApiUrl() {
+        return this.config.apiUrl ?? getVeryfrontCloudBootstrap().apiBaseUrl;
+    }
+    resolveAuthToken() {
+        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,
+        });
+    }
+    resolveProjectReference(projectReference) {
+        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,
+        });
+    }
+    async requestProjectJson(projectReference, path, schema, options = {}) {
+        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) {
+    return new VeryfrontJobsClient(config);
+}