@helmr/sdk 0.1.1-rc.4 → 0.1.1-rc.5

package/README.md

@@ -19,7 +19,7 @@ Schemes such as `env:` and `file:` are local runner sources and are rejected for
 
 ## TypeScript Runtime Client
 
-External TypeScript processes create runs with `tasks.trigger()`. Triggering returns a lightweight `RunHandle`; retrieve or wait on that handle to get a `RunSnapshot`.
+External TypeScript processes create runs with `task.trigger()` or the id-based `client.tasks.trigger()`. Triggering returns a lightweight `RunHandle`; retrieve or wait on that handle to get a `RunSnapshot`.
 
 ```ts
 import { HelmrClient, workspace } from "@helmr/sdk"
@@ -30,15 +30,20 @@ const client = new HelmrClient({
   apiKey: process.env.HELMR_API_KEY,
 })
 
-const handle = await client.tasks.trigger(impl, {
-  payload: { issue: 123 },
-  workspace: workspace.github("OWNER/REPO", { ref: "main", subpath: "tasks" }),
-})
+const handle = await client.tasks.trigger<typeof impl>(
+  "impl",
+  { issue: 123 },
+  {
+    workspace: workspace.github("OWNER/REPO", { ref: "main", subpath: "tasks" }),
+  },
+)
 
 const current = await client.runs.retrieve(handle)
 const pendingWaitpoint = current.pendingWaitpoint
-if (pendingWaitpoint !== null && pendingWaitpoint.kind === "approval") {
-  await client.waitpoints.approve(pendingWaitpoint, { reason: "reviewed" })
+if (pendingWaitpoint !== null && pendingWaitpoint.kind === "manual") {
+  await client.waitpoints.respond(pendingWaitpoint, {
+    value: { approved: true },
+  })
 }
 
 const finished = await client.runs.wait(handle, { timeoutMs: 10 * 60_000, intervalMs: 1_000 })
@@ -52,19 +57,22 @@ for await (const event of await client.runs.events.subscribe(handle)) {
 console.log(finished.status, logs.stdout, events.length)
 ```
 
-Waitpoint actions live on `client.waitpoints`. Pass either a pending waitpoint from a run snapshot or a run id plus waitpoint id:
+Waitpoint responses live on `client.waitpoints`. Pass either a pending waitpoint from a run snapshot or a waitpoint id:
 
 ```ts
-await client.waitpoints.approve("run-123", "waitpoint-456", { reason: "ok" })
-await client.waitpoints.deny("run-123", "waitpoint-456", { reason: "needs changes" })
-await client.waitpoints.reply("run-123", "waitpoint-456", { text: "Use the smaller rollout." })
+await client.waitpoints.respond("waitpoint-456", {
+  value: { approved: true },
+})
+await client.waitpoints.respond("waitpoint-456", {
+  value: { text: "Use the smaller rollout." },
+})
 ```
 
 ## API Reference
 
 ### `POST /api/runs`
 
-`payload` is a required JSON field. Payload is audit data: Helmr persists it in plaintext in the `run.created` event, DB, and events stream. Do not put secret values (tokens, API keys, credentials, or PII) in payload; use `secrets:` instead. Use payload for business context such as PR numbers, repo names, ticket ids, and other identifiers.
+`payload` is a JSON field for tasks that accept payload. Payload is audit data: Helmr persists it in plaintext in the `run.created` event, DB, and events stream. Do not put secret values (tokens, API keys, credentials, or PII) in payload; use `secrets:` instead. Use payload for business context such as PR numbers, repo names, ticket ids, and other identifiers.
 
 `secrets` maps declared task secret names to vault URIs:
 

package/dist/compile.js

@@ -16,6 +16,7 @@ import {
   ImageStepSchema,
   PlacementSchema as BundlePlacementSchema,
   PlatformSchema,
+  QueueSpecSchema,
   ResourcesSchema,
   RunSchema,
   SandboxSpecSchema,
@@ -25,11 +26,16 @@ import {
   SourceDirRefSchema,
   SourceFileRefSchema,
   TaskSpecSchema,
+  TaskScheduleSpecSchema,
+  TaskScheduleWorkspaceSpecSchema,
   UserSchema,
   WorkdirSchema,
   WorkspaceRuntimeBindingSchema
 } from "@helmr/proto";
 
+// sdk/typescript/src/schema/payload.ts
+var payloadSchemaValidationErrorBrand = Symbol.for("helmr.sdk.PayloadSchemaValidationError");
+
 // sdk/typescript/src/schema/task.ts
 var DEFAULT_MAX_DURATION_SECONDS = 900;
 var MIN_MAX_DURATION_SECONDS = 5;
@@ -55,8 +61,6 @@ function readOptionalMaxDurationSeconds(value, label = "task maxDuration") {
 }
 
 // sdk/typescript/src/internal.ts
-var approvalTimeoutErrorBrand = Symbol.for("helmr.sdk.ApprovalTimeoutError");
-var messageTimeoutErrorBrand = Symbol.for("helmr.sdk.MessageTimeoutError");
 var concurrentWaitErrorBrand = Symbol.for("helmr.sdk.ConcurrentWaitError");
 function validateSecretName(name, label = "secret name") {
   if (name.length === 0) {
@@ -80,6 +84,9 @@ var imageBuilderBrand = Symbol.for("helmr.sdk.ImageBuilder");
 var sandboxBuilderBrand = Symbol.for("helmr.sdk.SandboxBuilder");
 var sourceFileRefBrand = Symbol.for("helmr.sdk.SourceFileRef");
 var sourceDirRefBrand = Symbol.for("helmr.sdk.SourceDirRef");
+function defaultTaskQueueName(taskId) {
+  return `task/${taskId}`;
+}
 function isImageBuilder(value) {
   return hasBrand(value, imageBuilderBrand);
 }
@@ -131,6 +138,12 @@ function compile(opts) {
       modulePath: opts.modulePath,
       exportName: opts.exportName ?? "default",
       maxDurationSeconds,
+      queue: create(QueueSpecSchema, {
+        name: task.queue?.name ?? defaultTaskQueueName(task.id),
+        ...task.queue?.concurrencyLimit === undefined || task.queue.concurrencyLimit === null ? {} : { concurrencyLimit: task.queue.concurrencyLimit }
+      }),
+      ...task.ttl === undefined ? {} : { ttl: task.ttl },
+      schedules: compileTaskSchedules(task.schedule),
       secrets: Object.entries(readSecretDecls(task.secrets)).map(([name, placement]) => create(BundleSecretPlacementSchema, {
         name,
         placement: compilePlacement(placement)
@@ -138,6 +151,24 @@ function compile(opts) {
     })
   });
 }
+function compileTaskSchedules(schedule) {
+  if (schedule === undefined) {
+    return [];
+  }
+  return [
+    create(TaskScheduleSpecSchema, {
+      id: "",
+      cron: schedule.cron,
+      timezone: schedule.timezone ?? "UTC",
+      workspace: create(TaskScheduleWorkspaceSpecSchema, {
+        repository: schedule.workspace.repository,
+        ref: schedule.workspace.ref,
+        subpath: schedule.workspace.subpath ?? ""
+      }),
+      secretBindings: { ...schedule.secretBindings }
+    })
+  ];
+}
 function compilePlacement(placement) {
   if ("env" in placement) {
     return create(BundlePlacementSchema, {

package/dist/idempotency.d.ts

@@ -0,0 +1,30 @@
+export type IdempotencyKeyScope = "global" | "run" | "attempt";
+export type IdempotencyKeyMaterial = string | readonly string[];
+export type IdempotencyKeyCreateOptions = {
+    readonly scope?: "global";
+} | {
+    readonly scope?: "run";
+    readonly runId?: string;
+} | {
+    readonly scope: "attempt";
+    readonly runId: string;
+    readonly attemptNumber: number;
+};
+export interface IdempotencyKey {
+    readonly value: string;
+    readonly key: IdempotencyKeyMaterial;
+    readonly scope: IdempotencyKeyScope;
+}
+export type IdempotencyKeyInput = IdempotencyKeyMaterial | IdempotencyKey;
+export interface RunIdempotencyRequestFields {
+    readonly idempotency_key?: string;
+    readonly idempotency_key_ttl?: string;
+    readonly idempotency_key_options?: {
+        readonly key: IdempotencyKeyMaterial;
+        readonly scope: IdempotencyKeyScope;
+    };
+}
+export declare const idempotencyKeys: {
+    create(key: IdempotencyKeyMaterial, options?: IdempotencyKeyCreateOptions): IdempotencyKey;
+};
+export declare function runIdempotencyRequestFields(input: IdempotencyKeyInput | undefined, ttl: string | undefined): RunIdempotencyRequestFields;

package/dist/index.d.ts

@@ -1,15 +1,20 @@
-import { ApprovalTimeoutError, ConcurrentWaitError, MessageTimeoutError, validateSecretName, type CacheBuilder, type CacheMount, type CacheMountBinding, type EmitContent, type EmitEvent, type ImageBuilder, type ImageRunOptions, type Placement, type SandboxBuilder, type SecretDecls, type SecretMountBinding, type SourceCapabilities, type SourceDirRef, type SourceDirectoryOptions, type SourceFileRef, type TaskContext, type TaskSource, type TaskWorkspace, type GitHubRefKind, type GitHubPullRequestMetadata, type GitHubTaskSource, type TaskOutput, type TaskPayload, type WorkspaceCapabilities, type WorkspaceSpec } from "./internal.js";
+import { ConcurrentWaitError, validateSecretName, type CacheBuilder, type CacheMount, type CacheMountBinding, type EmitContent, type EmitEvent, type ImageBuilder, type ImageRunOptions, type NoPayload, type Placement, type SandboxBuilder, type SecretDecls, type SecretMountBinding, type SourceCapabilities, type SourceDirRef, type SourceDirectoryOptions, type SourceFileRef, type TaskContext, type TaskSource, type TaskWorkspace, type GitHubRefKind, type GitHubPullRequestMetadata, type GitHubTaskSource, type TaskOutput, type TaskPayload, type TaskTriggerPayload, type WaitCapabilities, type WaitForInput, type WaitJson, type WaitOptions, type WaitResolution, type WaitManualOptions, type WaitUntilInput, type WorkspaceCapabilities, type WorkspaceSpec } from "./internal.js";
+import { PayloadSchemaValidationError } from "./schema/payload.js";
+import { idempotencyKeys } from "./idempotency.js";
+export type { IdempotencyKey, IdempotencyKeyCreateOptions, IdempotencyKeyInput, IdempotencyKeyScope } from "./idempotency.js";
+import type { PayloadSchema, StandardSchemaV1 } from "./schema/payload.js";
 import { HelmrClient } from "./runtime/client.js";
-export type { WaitpointResponseToken, WaitpointTokenAction, WaitpointTokenCompleteOptions, WaitpointTokenCreateOptions, } from "./runtime/client.js";
+export type { ListSchedulesOptions, RetrieveScheduleOptions, Schedule, ScheduleCreateOptions, ScheduleUpdateOptions, SchedulesApi, WaitpointResponseToken, WaitpointTokenRespondOptions, WaitpointTokenCreateOptions, } from "./runtime/client.js";
 import { sandbox } from "./sandbox.js";
 import { defineConfig, type HelmrConfig, type HelmrConfigInput } from "./config.js";
-import { task, type Task, type TaskConfig } from "./task.js";
+import { queue, task, type Task, type TaskConfig, type TaskQueueConfig } from "./task.js";
+import { task as scheduledTask, type ScheduleCron, type ScheduledTaskConfig, type ScheduledTaskPayload } from "./schedules.js";
 import { tasks } from "./trigger.js";
 export { AuthError, RunNotFoundError, TimeoutError, UnsupportedTransportError } from "./runtime/errors.js";
-export { ApprovalTimeoutError, ConcurrentWaitError, MessageTimeoutError };
-export { type LogSnapshot, type ListRunEventsOptions, type ListRunsOptions, type PendingApprovalWaitpoint, type PendingMessageWaitpoint, type PendingWaitpoint, type RetrieveRunOptions, type RunEvent, type RunEventRecord, type RunEventRecordPage, type RunHandle, type RunSnapshot, type RunStatus, type RunSummary, type RunWaitOptions, type SubscribeRunEventsOptions, type WaitpointApprovalOptions, type WaitpointRef, type WaitpointReplyOptions, } from "./runtime/run.js";
-export { defineConfig, sandbox, task, tasks };
-export type { HelmrConfig, HelmrConfigInput, Placement, SecretDecls, Task, TaskConfig, TaskOutput, TaskPayload, };
+export { ConcurrentWaitError, PayloadSchemaValidationError };
+export { type LogSnapshot, type ListRunEventsOptions, type ListRunsOptions, type PendingDelayWaitpoint, type PendingManualWaitpoint, type PendingWaitpoint, type RetrieveRunOptions, type RunEvent, type RunEventRecord, type RunEventRecordPage, type RunHandle, type RunSnapshot, type RunStatus, type RunSummary, type RunWaitOptions, type SubscribeRunEventsOptions, type WaitpointRespondOptions, type WaitpointRef, } from "./runtime/run.js";
+export { defineConfig, idempotencyKeys, queue, sandbox, task, tasks };
+export type { HelmrConfig, HelmrConfigInput, Placement, SecretDecls, Task, TaskConfig, TaskQueueConfig, TaskOutput, TaskPayload, TaskTriggerPayload, WaitCapabilities, WaitForInput, WaitJson, WaitOptions, WaitResolution, WaitManualOptions, WaitUntilInput, PayloadSchema, StandardSchemaV1, NoPayload, };
 export declare const image: (id: string) => ImageBuilder;
 export declare const cache: (id: string) => CacheBuilder;
 export declare const source: SourceCapabilities;
@@ -31,4 +36,17 @@ export declare const runs: {
     };
 };
 export declare const waitpoints: import("./runtime/client.js").WaitpointsApi;
+export declare const schedules: Readonly<{
+    task: typeof scheduledTask;
+    create: (opts: import("./index.js").ScheduleCreateOptions) => Promise<import("./index.js").Schedule>;
+    update: (id: string, opts: Omit<import("./index.js").ScheduleCreateOptions, "deduplicationKey"> & {
+        readonly externalId?: string;
+    } & import("./index.js").RetrieveScheduleOptions) => Promise<import("./index.js").Schedule>;
+    list: (opts?: import("./index.js").ListSchedulesOptions | undefined) => Promise<import("./index.js").Schedule[]>;
+    retrieve: (id: string, opts?: import("./index.js").RetrieveScheduleOptions | undefined) => Promise<import("./index.js").Schedule>;
+    activate: (id: string, opts?: import("./index.js").RetrieveScheduleOptions | undefined) => Promise<import("./index.js").Schedule>;
+    deactivate: (id: string, opts?: import("./index.js").RetrieveScheduleOptions | undefined) => Promise<import("./index.js").Schedule>;
+    delete: (id: string, opts?: import("./index.js").RetrieveScheduleOptions | undefined) => Promise<void>;
+}>;
+export type { ScheduleCron, ScheduledTaskConfig, ScheduledTaskPayload, };
 export type { CacheBuilder, CacheMount, CacheMountBinding, EmitContent, EmitEvent, ImageBuilder, ImageRunOptions, SandboxBuilder, SecretMountBinding, SourceCapabilities, SourceDirRef, SourceDirectoryOptions, SourceFileRef, WorkspaceCapabilities, WorkspaceSpec, TaskContext, TaskSource, TaskWorkspace, GitHubRefKind, GitHubPullRequestMetadata, GitHubTaskSource, };