@helmr/sdk 0.1.0-preview.g52eb0eef.b35190749915

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+export interface HelmrConfigInput {
+    readonly dirs?: readonly string[];
+    readonly ignorePatterns?: readonly string[];
+}
+export interface HelmrConfig {
+    readonly dirs: readonly string[];
+    readonly ignorePatterns: readonly string[];
+}
+export declare function defineConfig(input: HelmrConfigInput): HelmrConfig;
+export declare function inspectConfig(value: unknown): HelmrConfig;
+export declare function matchesIgnorePattern(pattern: string, path: string): boolean;

package/dist/contract.d.ts

@@ -0,0 +1,341 @@
+import type { PayloadSchema } from "./schema/payload.js";
+import type { RequestOptions } from "./request.js";
+import type { WorkspaceRef } from "./workspace.js";
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export type Serializable = JsonValue;
+export type Metadata = Readonly<Record<string, JsonValue>>;
+export type MaybePromise<T> = T | Promise<T>;
+export type { PayloadSchema };
+export interface CursorPage<T> {
+    readonly items: readonly T[];
+    readonly nextCursor?: string;
+}
+export type Duration = string;
+export type RetryPolicy = Readonly<{
+    enabled?: true;
+    maxAttempts: number;
+    backoff?: Readonly<{
+        minDelay?: Duration;
+        maxDelay?: Duration;
+        factor?: number;
+        jitter?: "none" | "full";
+    }>;
+}> | Readonly<{
+    enabled: false;
+}>;
+declare const queueTypeBrand: unique symbol;
+export interface QueueConfig {
+    readonly name: string;
+    readonly concurrencyLimit?: number | null;
+}
+export interface Queue extends QueueConfig {
+    readonly [queueTypeBrand]: true;
+}
+export interface RunOptions {
+    readonly queue?: string;
+    readonly concurrencyKey?: string;
+    readonly priority?: number;
+    readonly ttl?: Duration;
+    readonly retry?: RetryPolicy;
+    readonly metadata?: Metadata;
+    readonly tags?: readonly string[];
+}
+export interface RunDefaults {
+    readonly queue?: Queue | string;
+    readonly maxDuration?: Duration;
+    readonly ttl?: Duration;
+    readonly retry?: RetryPolicy;
+}
+declare const workspaceAddressTypeBrand: unique symbol;
+export interface WorkspaceAddress {
+    readonly [workspaceAddressTypeBrand]: true;
+    readonly id: string;
+}
+export type RunCause = Readonly<{
+    type: "api" | "manual";
+}> | Readonly<{
+    type: "child";
+    parentRunId: string;
+}> | Readonly<{
+    type: "schedule";
+    scheduleId: string;
+    scheduledAt: string;
+    lastScheduledAt?: string;
+    timezone: string;
+}> | Readonly<{
+    type: "actor_start" | "continuation";
+}>;
+interface RunContext {
+    readonly signal: AbortSignal;
+    readonly run: Readonly<{
+        id: string;
+        attemptNumber: number;
+        cause: RunCause;
+    }>;
+    readonly deployment: Readonly<{
+        id: string;
+        version: string;
+    }>;
+    readonly workspace: WorkspaceRef;
+}
+export interface TaskContext extends RunContext {
+    readonly task: Readonly<{
+        id: string;
+    }>;
+    readonly actor?: never;
+}
+export interface ActorContext extends RunContext {
+    readonly task?: never;
+    readonly actor: Readonly<{
+        id: string;
+    }>;
+}
+export interface HelmrError extends Error {
+    readonly code: string;
+    readonly requestId?: string;
+}
+export interface APIError extends HelmrError {
+    readonly details?: Readonly<Record<string, JsonValue>>;
+}
+export type RunStatus = "queued" | "running" | "waiting" | "retry_delayed" | "cancel_requested" | "succeeded" | "failed" | "cancelled" | "expired" | "system_failed";
+declare const runHandleOutputBrand: unique symbol;
+export interface RunHandle<TOutput extends JsonValue = JsonValue> {
+    readonly id: string;
+    readonly [runHandleOutputBrand]: TOutput;
+}
+export interface RunFailure {
+    readonly code: string;
+    readonly message: string;
+    readonly details: Readonly<Record<string, JsonValue>>;
+}
+export interface Run<TOutput extends JsonValue = JsonValue> extends RunHandle<TOutput> {
+    readonly status: RunStatus;
+    readonly entrypoint: Readonly<{
+        kind: "task" | "actor";
+        id: string;
+    }>;
+    readonly deployment: Readonly<{
+        id: string;
+        version: string;
+    }>;
+    readonly workspaceId: string;
+    readonly sessionId?: string;
+    readonly parentRunId?: string;
+    readonly currentAttemptNumber: number;
+    readonly cause: RunCause;
+    readonly metadata: Metadata;
+    readonly tags: readonly string[];
+    readonly output?: TOutput;
+    readonly failure?: RunFailure;
+    readonly createdAt: string;
+    readonly startedAt?: string;
+    readonly terminalAt?: string;
+}
+export type TaskResult<T extends JsonValue> = Readonly<{
+    ok: true;
+    output: T;
+    run: RunHandle<T>;
+}> | Readonly<{
+    ok: false;
+    failure: RunFailure;
+    run: RunHandle<T>;
+}>;
+export interface TaskWait<T extends JsonValue> extends PromiseLike<TaskResult<T>> {
+    unwrap(): Promise<T>;
+}
+export interface TaskStartOptions extends RunOptions {
+    readonly idempotencyKey?: string;
+    readonly workspace: WorkspaceRef;
+    readonly signal?: AbortSignal;
+}
+export interface TaskCallOptions extends RunOptions {
+    readonly idempotencyKey: string;
+    readonly workspace: WorkspaceRef;
+    readonly signal?: AbortSignal;
+}
+declare const taskBrand: unique symbol;
+interface TaskTypeInfo<TIdentifier extends string, TInput extends JsonValue, TOutput extends JsonValue> {
+    readonly identifier: TIdentifier;
+    readonly input: TInput;
+    readonly output: TOutput;
+}
+export interface Task<TIdentifier extends string = string, TInput extends JsonValue = JsonValue, TOutput extends JsonValue = JsonValue> {
+    readonly [taskBrand]: TaskTypeInfo<TIdentifier, TInput, TOutput>;
+    readonly id: TIdentifier;
+    readonly hasPayload: boolean;
+    start(...args: [TInput] extends [never] ? [options: TaskStartOptions] : [payload: TInput, options: TaskStartOptions]): Promise<RunHandle<TOutput>>;
+    call(...args: [TInput] extends [never] ? [options: TaskCallOptions] : [payload: TInput, options: TaskCallOptions]): TaskWait<TOutput>;
+}
+export type TaskInput<TTask extends Task> = TTask[typeof taskBrand]["input"];
+export type TaskOutput<TTask extends Task> = TTask[typeof taskBrand]["output"];
+export type TaskConfigWithPayload<TIdentifier extends string, TInput extends JsonValue, TPayload, TOutput extends JsonValue> = RunDefaults & Readonly<{
+    id: TIdentifier;
+    payload: PayloadSchema<TInput, TPayload>;
+    run(payload: TPayload, ctx: TaskContext): MaybePromise<TOutput>;
+}>;
+export type TaskConfigWithoutPayload<TIdentifier extends string, TOutput extends JsonValue> = RunDefaults & Readonly<{
+    id: TIdentifier;
+    payload?: never;
+    run(ctx: TaskContext): MaybePromise<TOutput>;
+}>;
+export type TaskConfig<TIdentifier extends string = string, TInput extends JsonValue = never, TPayload = never, TOutput extends JsonValue = JsonValue> = TaskConfigWithPayload<TIdentifier, TInput, TPayload, TOutput> | TaskConfigWithoutPayload<TIdentifier, TOutput>;
+export type SessionInputSource = Readonly<{
+    type: "external";
+}> | Readonly<{
+    type: "run";
+    runId: string;
+}>;
+export interface WaitTimeoutError extends HelmrError {
+    readonly code: "wait_timeout";
+}
+export interface SessionClosedError extends HelmrError {
+    readonly code: "session_closed";
+}
+export interface SessionInputMetadata {
+    readonly id: string;
+    readonly sequence: number;
+    readonly createdAt: string;
+    readonly source: SessionInputSource;
+}
+export interface SessionInputRecord extends SessionInputMetadata {
+    readonly data: JsonValue;
+}
+export type ActorSessionInputResult = Readonly<{
+    ok: true;
+    value: JsonValue;
+    record: SessionInputMetadata;
+}> | Readonly<{
+    ok: false;
+    error: WaitTimeoutError | SessionClosedError;
+}>;
+export interface ActorSessionReceive extends PromiseLike<ActorSessionInputResult> {
+    unwrap(): Promise<JsonValue>;
+}
+export interface SessionInputSendRequest {
+    readonly idempotencyKey?: string;
+}
+export interface ActorSessionReceiveOptions {
+    readonly timeout?: Duration;
+    readonly idleTimeout?: Duration;
+    readonly metadata?: Metadata;
+    readonly tags?: readonly string[];
+}
+export interface ActorSessionInput {
+    receive(options?: ActorSessionReceiveOptions): ActorSessionReceive;
+}
+export interface SessionOutputRecord {
+    readonly id: string;
+    readonly sequence: number;
+    readonly data: unknown;
+    readonly contentType: string;
+    readonly createdAt: string;
+    readonly provenance: Readonly<{
+        runId: string;
+        attemptNumber: number;
+        deploymentId: string;
+    }>;
+}
+export interface ActorSessionOutputAppendOptions {
+    readonly contentType?: string;
+    readonly idempotencyKey?: string;
+}
+export interface ActorSessionOutputSequenceOptions {
+    readonly contentType?: string;
+}
+export interface SessionOutputQuery {
+    readonly after?: number;
+    readonly limit?: number;
+}
+export interface SessionInputQuery {
+    readonly after?: number;
+    readonly limit?: number;
+}
+export interface SessionOutputWriter {
+    write(value: Serializable): Promise<SessionOutputRecord>;
+    close(): Promise<void>;
+}
+export interface ActorSessionOutput {
+    append(value: Serializable, options?: ActorSessionOutputAppendOptions): Promise<SessionOutputRecord>;
+    pipe(source: AsyncIterable<Serializable> | Iterable<Serializable>, options?: ActorSessionOutputSequenceOptions): Promise<void>;
+    writer(options?: ActorSessionOutputSequenceOptions): SessionOutputWriter;
+}
+export interface SessionOutputPage {
+    readonly records: readonly SessionOutputRecord[];
+    readonly nextAfter: number;
+    readonly hasMore: boolean;
+}
+export interface SessionInputPage {
+    readonly records: readonly SessionInputRecord[];
+    readonly nextAfter: number;
+    readonly hasMore: boolean;
+}
+export interface ActorSession {
+    readonly id: string;
+    readonly key?: string;
+    readonly input: ActorSessionInput;
+    readonly output: ActorSessionOutput;
+}
+export interface ActorConfig extends RunDefaults {
+    readonly id: string;
+    readonly idleTimeout?: Duration;
+    readonly run: (session: ActorSession, ctx: ActorContext) => MaybePromise<void>;
+}
+export interface ActorStartOptions {
+    readonly key?: string;
+    readonly input?: JsonValue;
+    readonly idempotencyKey?: string;
+    readonly workspace: WorkspaceRef;
+    readonly run?: RunOptions;
+    readonly signal?: AbortSignal;
+}
+export type SessionStatus = "open" | "closed" | "cancelled" | "failed";
+export type SessionFailureCode = string;
+export interface SessionFailure {
+    readonly code: SessionFailureCode;
+    readonly message: string;
+    readonly details: Readonly<{
+        runId?: string;
+    }>;
+}
+export interface Session {
+    readonly id: string;
+    readonly actorId: string;
+    readonly deploymentId: string;
+    readonly workspaceId: string;
+    readonly key?: string;
+    readonly status: SessionStatus;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly currentRunId?: string;
+    readonly failure?: SessionFailure;
+}
+export interface SessionCloseRequest {
+    readonly idempotencyKey?: string;
+}
+export interface SessionCloseReceipt {
+    readonly sessionId: string;
+    readonly acceptedAt: string;
+}
+export interface SessionRef {
+    readonly id: string;
+    readonly input: Readonly<{
+        send(input: JsonValue, request?: SessionInputSendRequest, options?: RequestOptions): Promise<SessionInputRecord>;
+    }>;
+    readonly output: Readonly<{
+        list(query?: SessionOutputQuery, options?: RequestOptions): Promise<SessionOutputPage>;
+    }>;
+    retrieve(options?: RequestOptions): Promise<Session>;
+    close(request?: SessionCloseRequest, options?: RequestOptions): Promise<SessionCloseReceipt>;
+}
+declare const actorTypeBrand: unique symbol;
+export interface ActorStartResult {
+    readonly session: SessionRef;
+    readonly run: RunHandle<null>;
+}
+export interface Actor {
+    readonly [actorTypeBrand]: true;
+    readonly id: string;
+    start(options: ActorStartOptions): Promise<ActorStartResult>;
+}

package/dist/definitions.d.ts

@@ -0,0 +1,42 @@
+import { type ActorConfig, type Actor, type JsonValue, type Queue, type QueueConfig, type Task, type TaskConfigWithPayload, type TaskConfigWithoutPayload } from "./contract.js";
+import { type PayloadSchema } from "./schema/payload.js";
+export type InternalTaskDefinition = Readonly<{
+    kind: "task";
+    id: string;
+    hasPayload: boolean;
+    handler: (...args: readonly unknown[]) => unknown;
+    payloadSchema?: PayloadSchema;
+    queue?: Queue | string;
+    maxDuration?: import("./contract.js").Duration;
+    ttl?: import("./contract.js").Duration;
+    retry?: ActorConfig["retry"];
+    schedule?: Readonly<{
+        cron: string;
+        timezone: string;
+        workspace: Readonly<{
+            sandbox: import("./workspace.js").Sandbox;
+            secrets: readonly import("./workspace.js").EncodedWorkspaceSecret[];
+        }>;
+    }>;
+}>;
+export type InternalActorDefinition = Readonly<{
+    kind: "actor";
+    id: string;
+    handler: ActorConfig["run"];
+    queue?: Queue | string;
+    maxDuration?: import("./contract.js").Duration;
+    ttl?: import("./contract.js").Duration;
+    retry?: ActorConfig["retry"];
+    idleTimeout?: ActorConfig["idleTimeout"];
+}>;
+export type InternalDefinition = InternalTaskDefinition | InternalActorDefinition;
+export declare function inspectDefinition(value: unknown): InternalDefinition | undefined;
+export declare function isQueue(value: unknown): value is Queue;
+export declare function queue(config: QueueConfig): Queue;
+export declare function task<TIdentifier extends string, TInput extends JsonValue, TPayload, TOutput extends JsonValue>(config: TaskConfigWithPayload<TIdentifier, TInput, TPayload, TOutput>): Task<TIdentifier, TInput, TOutput>;
+export declare function task<TIdentifier extends string, TOutput extends JsonValue>(config: TaskConfigWithoutPayload<TIdentifier, TOutput>): Task<TIdentifier, never, TOutput>;
+export declare function actor(config: ActorConfig): Actor;
+export declare function createScheduledTask<TIdentifier extends string, TInput extends JsonValue, TPayload, TOutput extends JsonValue>(config: Omit<TaskConfigWithPayload<TIdentifier, TInput, TPayload, TOutput>, "payload"> & {
+    readonly payload: PayloadSchema<TInput, TPayload>;
+    readonly schedule: NonNullable<InternalTaskDefinition["schedule"]>;
+}): Task<TIdentifier, TInput, TOutput>;

package/dist/fuzzy.d.ts

@@ -0,0 +1 @@
+export declare function levenshteinDistance(left: string, right: string): number;

package/dist/fuzzy.js

@@ -0,0 +1,29 @@
+// sdk/typescript/src/fuzzy.ts
+function levenshteinDistance(left, right) {
+  if (left === right) {
+    return 0;
+  }
+  if (left.length === 0) {
+    return right.length;
+  }
+  if (right.length === 0) {
+    return left.length;
+  }
+  const previous = new Array(right.length + 1);
+  const current = new Array(right.length + 1);
+  for (let column = 0;column <= right.length; column += 1) {
+    previous[column] = column;
+  }
+  for (let row = 1;row <= left.length; row += 1) {
+    current[0] = row;
+    for (let column = 1;column <= right.length; column += 1) {
+      const cost = left[row - 1] === right[column - 1] ? 0 : 1;
+      current[column] = Math.min(current[column - 1] + 1, previous[column] + 1, previous[column - 1] + cost);
+    }
+    previous.splice(0, previous.length, ...current);
+  }
+  return previous[right.length] ?? right.length;
+}
+export {
+  levenshteinDistance
+};

package/dist/image.d.ts

@@ -0,0 +1,63 @@
+declare const sourceFileTypeBrand: unique symbol;
+declare const sourceDirectoryTypeBrand: unique symbol;
+declare const imageBuilderTypeBrand: unique symbol;
+export interface SourceFile {
+    readonly [sourceFileTypeBrand]: true;
+    readonly path: string;
+}
+export interface SourceDirectory {
+    readonly [sourceDirectoryTypeBrand]: true;
+    readonly path: string;
+}
+export interface ImageBuilder {
+    readonly [imageBuilderTypeBrand]: true;
+    readonly key: string;
+    from(ref: string): ImageBuilder;
+    run(argv: readonly string[]): ImageBuilder;
+    copy(destination: string, source: SourceFile | SourceDirectory): ImageBuilder;
+    copyFrom(destination: string, source: ImageBuilder, sourcePath: string): ImageBuilder;
+    workdir(path: string): ImageBuilder;
+    env(key: string, value: string): ImageBuilder;
+    user(name: string): ImageBuilder;
+}
+export type InternalImageStep = Readonly<{
+    kind: "from";
+    ref: string;
+}> | Readonly<{
+    kind: "run";
+    argv: readonly string[];
+}> | Readonly<{
+    kind: "copy_source_file";
+    destination: string;
+    source: SourceFile;
+}> | Readonly<{
+    kind: "copy_source_directory";
+    destination: string;
+    source: SourceDirectory;
+}> | Readonly<{
+    kind: "copy_from_image";
+    destination: string;
+    source: ImageBuilder;
+    sourcePath: string;
+}> | Readonly<{
+    kind: "workdir";
+    path: string;
+}> | Readonly<{
+    kind: "env";
+    key: string;
+    value: string;
+}> | Readonly<{
+    kind: "user";
+    name: string;
+}>;
+export interface InternalImage {
+    readonly key: string;
+    readonly steps: readonly InternalImageStep[];
+}
+export declare function image(key: string): ImageBuilder;
+export declare const source: Readonly<{
+    file(path: string): SourceFile;
+    directory(path: string): SourceDirectory;
+}>;
+export declare function inspectImage(value: unknown): InternalImage | undefined;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+export { actor } from "./actor.js";
+export { sessions } from "./session.js";
+export { HelmrClient } from "./client.js";
+export { image, source } from "./image.js";
+export { logger } from "./logger.js";
+export { metadata } from "./metadata.js";
+export { defineConfig } from "./config.js";
+export { schedules } from "./schedules.js";
+export { queue, task } from "./task.js";
+export { timers } from "./timers.js";
+export { tokens } from "./tokens.js";
+export { sandbox, workspaces } from "./workspace.js";
+export type { ActorInfo, ActorListItem, ActorListQuery, ActorPage, ActorRetrieveQuery, ActorStartRequest, } from "./client-actor.js";
+export type { ClientSessionRef, SessionListQuery, } from "./client-session.js";
+export type { SandboxInfo, SandboxListItem, SandboxListQuery, SandboxPage, SandboxRetrieveQuery, } from "./client-sandbox.js";
+export type { WorkspaceListItem, WorkspaceListQuery, } from "./client-workspace.js";
+export type { DeploymentListItem, DeploymentListQuery, Deployment, } from "./client-deployment.js";
+export type { ScheduleFailure, ScheduleListQuery, Schedule, ScheduleStatus, } from "./client-schedule.js";
+export type { SecretRef, SecretCreateRequest, SecretListQuery, SecretRevokeRequest, SecretRotateRequest, Secret, SecretStatus, } from "./client-secret.js";
+export type { RunEntrypointKind, RunListQuery, RunLogQuery, RunEventQuery, TaskStartRequest, HelmrClientOptions, TaskInfo, TaskListItem, TaskListQuery, TaskPage, TaskRetrieveQuery, RunEventRecord, RunListItem, RunLogRecord, StreamRunLogRecord, StructuredRunLogRecord, TokenCancelRequest, TokenCompleteRequest, } from "./client.js";
+export type { RequestOptions } from "./request.js";
+export type { LogAttributes, RunLogLevel, } from "./logger.js";
+export type { HelmrConfig, HelmrConfigInput, } from "./config.js";
+export type { SessionClosedError, APIError, ActorConfig, Actor, ActorContext, ActorSession, ActorSessionInput, ActorSessionOutput, ActorSessionOutputAppendOptions, ActorSessionOutputSequenceOptions, ActorSessionInputResult, ActorSessionReceiveOptions, ActorSessionReceive, SessionInputMetadata, SessionInputPage, SessionInputQuery, SessionInputRecord, SessionInputSendRequest, SessionInputSource, SessionFailure, SessionFailureCode, SessionStatus, SessionCloseRequest, SessionCloseReceipt, SessionOutputRecord, SessionOutputPage, SessionOutputQuery, SessionOutputWriter, SessionRef, ActorStartOptions, ActorStartResult, Session, CursorPage, Duration, HelmrError, JsonValue, MaybePromise, Metadata, PayloadSchema, Queue, QueueConfig, RetryPolicy, RunCause, RunFailure, RunHandle, RunOptions, Run, RunStatus, Serializable, TaskCallOptions, TaskConfig, TaskConfigWithPayload, TaskConfigWithoutPayload, Task, TaskContext, TaskInput, TaskOutput, TaskResult, TaskStartOptions, TaskWait, WaitTimeoutError, } from "./contract.js";
+export type { ImageBuilder, SourceDirectory, SourceFile, } from "./image.js";
+export type { Cron, ScheduledTaskConfig, ScheduledTaskInput, ScheduledTaskPayload, } from "./schedules.js";
+export type { TokenCreateRequest, TokenCreateResult, TokenCancelledError, TokenExpiredError, TokenRef, TokenListItem, TokenListQuery, Token, TokenStatus, TokenWait, TokenWaitError, TokenWaitOptions, TokenWaitResult, } from "./tokens.js";
+export type { SandboxBuilder, SandboxConfig, SandboxResourceBuilder, WorkspaceCreateRequest, WorkspaceDeleteRequest, WorkspaceDeleteReceipt, Sandbox, WorkspaceExecRequest, WorkspaceExecResult, WorkspaceMemory, WorkspaceRef, WorkspaceResources, WorkspaceSecretBinding, Workspace, WorkspaceOwner, WorkspaceStatus, } from "./workspace.js";
+export type { PayloadSchemaInput, PayloadSchemaOutput, StandardSchemaV1, } from "./schema/payload.js";