@helmr/sdk 0.1.0

package/dist/runtime/run.d.ts

@@ -0,0 +1,195 @@
+export type RunStatus = "queued" | "claimed" | "running" | "waiting" | "succeeded" | "failed" | "cancelled";
+declare const runOutputBrand: unique symbol;
+export interface RunHandle<TOutput = unknown> {
+    readonly id: string;
+    readonly taskId: string;
+    readonly [runOutputBrand]?: TOutput;
+}
+export type RunOutput<T> = T extends {
+    readonly [runOutputBrand]?: infer TOutput;
+} ? TOutput : unknown;
+export interface RunStateBooleans {
+    readonly isQueued: boolean;
+    readonly isRunning: boolean;
+    readonly isWaiting: boolean;
+    readonly isTerminal: boolean;
+    readonly isSuccess: boolean;
+    readonly isFailed: boolean;
+    readonly isCancelled: boolean;
+}
+export interface RunSnapshot<TOutput = unknown> extends RunStateBooleans {
+    readonly id: string;
+    readonly taskId: string;
+    readonly status: RunStatus;
+    readonly exitCode: number | null;
+    readonly createdAt: string | null;
+    readonly updatedAt: string | null;
+    readonly pendingWaitpoint: PendingWaitpoint | null;
+    readonly output?: TOutput;
+}
+export type RunSummary<TOutput = unknown> = RunSnapshot<TOutput>;
+export type PendingWaitpoint = PendingApprovalWaitpoint | PendingMessageWaitpoint;
+interface PendingWaitpointBase {
+    readonly runId: string;
+    readonly waitpointId: string;
+    readonly timeout: number | null;
+    readonly requestedAt: string;
+}
+export interface PendingApprovalWaitpoint extends PendingWaitpointBase {
+    readonly kind: "approval";
+    readonly message: string;
+}
+export interface PendingMessageWaitpoint extends PendingWaitpointBase {
+    readonly kind: "message";
+    readonly prompt: string | null;
+}
+export interface WaitpointRef {
+    readonly runId: string;
+    readonly waitpointId: string;
+}
+export interface WaitpointApprovalOptions {
+    readonly reason?: string;
+}
+export interface WaitpointReplyOptions {
+    readonly text: string;
+}
+export interface RunWaitOptions {
+    readonly timeoutMs?: number;
+    readonly intervalMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface RetrieveRunOptions {
+    readonly signal?: AbortSignal;
+}
+export interface ListRunsOptions {
+    readonly status?: RunStatus | "live" | "all";
+    readonly limit?: number;
+    readonly projectId?: string;
+    readonly environmentId?: string;
+    readonly signal?: AbortSignal;
+}
+export interface ListRunEventsOptions {
+    readonly cursor?: number;
+    readonly pageSize?: number;
+    readonly signal?: AbortSignal;
+}
+export interface SubscribeRunEventsOptions {
+    readonly cursor?: number;
+    readonly signal?: AbortSignal;
+}
+export type RunEvent = {
+    readonly type: "log";
+    readonly run_id: string;
+    readonly stream: "stdout" | "stderr";
+    readonly bytes: number;
+    readonly observed_seq: number;
+    readonly at: string;
+} | {
+    readonly type: "approval_request";
+    readonly run_id: string;
+    readonly waitpoint_id: string;
+    readonly message: string;
+    readonly timeout?: number;
+    readonly at: string;
+} | {
+    readonly type: "approval_decided";
+    readonly run_id: string;
+    readonly waitpoint_id: string;
+    readonly decision: "approved" | "denied";
+    readonly reason?: string;
+    readonly at: string;
+} | {
+    readonly type: "message_request";
+    readonly run_id: string;
+    readonly waitpoint_id: string;
+    readonly prompt?: string;
+    readonly timeout?: number;
+    readonly at: string;
+} | {
+    readonly type: "message_received";
+    readonly run_id: string;
+    readonly waitpoint_id: string;
+    readonly text: string;
+    readonly at: string;
+} | {
+    readonly type: "emit";
+    readonly run_id: string;
+    readonly event_type: string;
+    readonly content: unknown;
+    readonly at: string;
+} | {
+    readonly type: "task_complete";
+    readonly run_id: string;
+    readonly exit_code: number;
+    readonly at: string;
+} | {
+    readonly type: "run_failed";
+    readonly run_id: string;
+    readonly failure_kind: string;
+    readonly detail?: unknown;
+    readonly at: string;
+} | {
+    readonly type: "run_timeout";
+    readonly run_id: string;
+    readonly elapsed_secs: number;
+    readonly limit_secs: number;
+    readonly at: string;
+} | {
+    readonly type: "run_cancelled";
+    readonly run_id: string;
+    readonly reason?: string;
+    readonly at: string;
+};
+export interface RunEventRecord {
+    readonly id: string;
+    readonly run_id?: string | null;
+    readonly kind: string;
+    readonly message: string;
+    readonly at: string;
+    readonly attributes: unknown;
+}
+export interface RunEventRecordPage {
+    readonly events: readonly RunEventRecord[];
+    readonly cursor: number;
+    readonly next_cursor?: number | null;
+}
+export interface RunEventPage {
+    readonly events: readonly RunEvent[];
+    readonly cursor: number;
+    readonly nextCursor: number | null;
+}
+export interface LogSnapshot {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly cursor: string;
+    readonly truncated: boolean;
+}
+export type PendingWaitpointResponse = {
+    readonly kind: "approval";
+    readonly waitpoint_id: string;
+    readonly message?: string | null;
+    readonly timeout?: number | null;
+    readonly requested_at: string;
+} | {
+    readonly kind: "message";
+    readonly waitpoint_id: string;
+    readonly prompt?: string | null;
+    readonly timeout?: number | null;
+    readonly requested_at: string;
+};
+export declare function runHandle<TOutput = unknown>(id: string, taskId: string): RunHandle<TOutput>;
+export declare function runSnapshot<TOutput = unknown>(snapshot: {
+    readonly id: string;
+    readonly taskId: string;
+    readonly status: string;
+    readonly exitCode?: number | null;
+    readonly createdAt?: string | null;
+    readonly updatedAt?: string | null;
+    readonly pendingWaitpoint?: PendingWaitpoint | null;
+    readonly output?: TOutput;
+}): RunSnapshot<TOutput>;
+export declare function pendingWaitpointFromResponse(runId: string, wait: PendingWaitpointResponse | null | undefined): PendingWaitpoint | null;
+export declare function isTerminalRunStatus(status: RunStatus): boolean;
+export declare function runId(value: string | RunHandle<unknown>): string;
+export declare function runStateBooleans(status: RunStatus): RunStateBooleans;
+export {};

package/dist/runtime/source.d.ts

@@ -0,0 +1,7 @@
+import type { WorkspaceSpec } from "../internal.js";
+export type RunWorkspace = {
+    readonly repository: string;
+    readonly ref: string;
+    readonly subpath?: string;
+};
+export declare function runWorkspaceFromSpec(spec: WorkspaceSpec): RunWorkspace;

package/dist/sandbox.d.ts

@@ -0,0 +1,3 @@
+import { type SandboxBuilder } from "./internal.js";
+export declare const sandbox: (id: string) => SandboxBuilder;
+export type { SandboxBuilder };

package/dist/schema/task.d.ts

@@ -0,0 +1,20 @@
+export declare const TASK_ID_PATTERN: "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$";
+export declare const TASK_ID_MAX_LENGTH = 128;
+export declare const DEFAULT_MAX_DURATION_SECONDS = 900;
+export declare const MIN_MAX_DURATION_SECONDS = 5;
+export declare const MAX_DURATION_SECONDS = 86400;
+export declare class TaskIdError extends Error {
+    readonly name = "TaskIdError";
+    readonly value: string;
+    constructor(value: string);
+}
+export declare function validateTaskId(value: string): void;
+export declare function isValidTaskId(value: string): boolean;
+export declare class TaskMaxDurationError extends Error {
+    readonly name = "TaskMaxDurationError";
+    readonly value: unknown;
+    readonly label: string;
+    constructor(value: unknown, label?: string);
+}
+export declare function readOptionalMaxDurationSeconds(value: unknown, label?: string): number;
+export declare function validateOptionalMaxDurationSeconds(value: unknown, label?: string): void;

package/dist/task.d.ts

@@ -0,0 +1,3 @@
+import { type SecretDecls, type Task, type TaskConfig, type TaskOutput, type TaskPayload } from "./internal.js";
+export declare function task<TPayload, TOutput, TSecrets extends SecretDecls = Record<never, never>>(config: TaskConfig<TPayload, TOutput, TSecrets>): Task<TPayload, Awaited<TOutput>, TSecrets>;
+export type { Task, TaskConfig, TaskOutput, TaskPayload };

package/dist/trigger.d.ts

@@ -0,0 +1,25 @@
+import type { SecretDecls, Task, WorkspaceSpec } from "./internal.js";
+import { HelmrClient } from "./runtime/client.js";
+import type { RunHandle } from "./runtime/run.js";
+export declare function getDefaultClient(): HelmrClient;
+export type TriggerSecrets<TSecrets extends SecretDecls> = {
+    readonly [K in keyof TSecrets]: string;
+};
+export type TriggerOptions<TPayload, TSecrets extends SecretDecls> = {
+    /**
+     * 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.
+     */
+    readonly payload: TPayload;
+    readonly workspace: WorkspaceSpec;
+} & ([keyof TSecrets] extends [never] ? {
+    readonly secrets?: Record<never, never>;
+} : {
+    readonly secrets: TriggerSecrets<TSecrets>;
+});
+export declare const tasks: {
+    trigger<TPayload, TOutput, TSecrets extends SecretDecls>(task: Task<TPayload, TOutput, TSecrets>, opts: TriggerOptions<TPayload, TSecrets>): Promise<RunHandle<TOutput>>;
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@helmr/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for authoring and triggering Helmr tasks.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/helmrdotdev/helmr.git",
+    "directory": "sdk/typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/helmrdotdev/helmr/issues"
+  },
+  "homepage": "https://helmr.dev",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js"
+    },
+    "./internal/compile": {
+      "types": "./dist/compile.d.ts",
+      "import": "./dist/compile.js"
+    },
+    "./internal/fuzzy": {
+      "types": "./dist/fuzzy.d.ts",
+      "import": "./dist/fuzzy.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@bufbuild/protobuf": "^2.11.0",
+    "@helmr/proto": "0.1.0"
+  }
+}