@helmr/sdk 0.1.0-preview.g4db36b8f.b35308518307

package/dist/logger.d.ts

@@ -0,0 +1,9 @@
+import type { JsonValue } from "./contract.js";
+export type RunLogLevel = "debug" | "info" | "warn" | "error";
+export type LogAttributes = Readonly<Record<string, JsonValue>>;
+export declare const logger: Readonly<{
+    debug(message: string, attributes?: LogAttributes): Promise<void>;
+    info(message: string, attributes?: LogAttributes): Promise<void>;
+    warn(message: string, attributes?: LogAttributes): Promise<void>;
+    error(message: string, attributes?: LogAttributes): Promise<void>;
+}>;

package/dist/metadata.d.ts

@@ -0,0 +1,6 @@
+import type { JsonValue, Metadata } from "./contract.js";
+export declare const metadata: Readonly<{
+    set(key: string, value: JsonValue): Promise<void>;
+    patch(values: Metadata): Promise<void>;
+    increment(key: string, amount?: number): Promise<void>;
+}>;

package/dist/request.d.ts

@@ -0,0 +1,3 @@
+export interface RequestOptions {
+    readonly signal?: AbortSignal;
+}

package/dist/schedules.d.ts

@@ -0,0 +1,33 @@
+import type { RunDefaults, JsonValue, MaybePromise, Task, TaskContext } from "./contract.js";
+import { type Sandbox, type WorkspaceSecretBinding } from "./workspace.js";
+export type Cron = Readonly<{
+    pattern: string;
+    timezone: string;
+}>;
+export type ScheduledTaskInput = Readonly<{
+    scheduledAt: string;
+    lastScheduledAt?: string;
+    timezone: string;
+    scheduleId: string;
+    upcoming: readonly string[];
+}>;
+export interface ScheduledTaskPayload {
+    readonly scheduledAt: Date;
+    readonly lastScheduledAt?: Date;
+    readonly timezone: string;
+    readonly scheduleId: string;
+    readonly upcoming: readonly Date[];
+}
+export type ScheduledTaskConfig<TIdentifier extends string, TOutput extends JsonValue> = RunDefaults & Readonly<{
+    id: TIdentifier;
+    cron: Cron;
+    workspace: Readonly<{
+        sandbox: Sandbox;
+        secrets?: readonly WorkspaceSecretBinding[];
+    }>;
+    run(payload: ScheduledTaskPayload, ctx: TaskContext): MaybePromise<TOutput>;
+}>;
+export declare function scheduledTask<TIdentifier extends string, TOutput extends JsonValue>(config: ScheduledTaskConfig<TIdentifier, TOutput>): Task<TIdentifier, ScheduledTaskInput, TOutput>;
+export declare const schedules: Readonly<{
+    task: typeof scheduledTask;
+}>;

package/dist/schema/payload.d.ts

@@ -0,0 +1,39 @@
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        validate(value: unknown): StandardSchemaV1.Result<Output> | PromiseLike<StandardSchemaV1.Result<Output>>;
+        readonly types?: StandardSchemaV1.Types<Input, Output> | undefined;
+    };
+}
+export declare namespace StandardSchemaV1 {
+    interface Types<Input = unknown, Output = Input> {
+        readonly input: Input;
+        readonly output: Output;
+    }
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    interface SuccessResult<Output> {
+        readonly value: Output;
+        readonly issues?: undefined;
+    }
+    interface FailureResult {
+        readonly issues: readonly Issue[];
+    }
+    interface Issue {
+        readonly message: string;
+        readonly path?: readonly (PropertyKey | PathSegment)[];
+    }
+    interface PathSegment {
+        readonly key: PropertyKey;
+    }
+}
+export type PayloadSchema<Input = unknown, Output = Input> = StandardSchemaV1<Input, Output>;
+export type PayloadSchemaInput<TSchema> = TSchema extends StandardSchemaV1<infer Input, any> ? Input : unknown;
+export type PayloadSchemaOutput<TSchema> = TSchema extends StandardSchemaV1<any, infer Output> ? Output : unknown;
+export declare class PayloadSchemaValidationError extends Error {
+    readonly issues: readonly StandardSchemaV1.Issue[];
+    constructor(label: string, issues: readonly StandardSchemaV1.Issue[]);
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+export declare function assertPayloadSchema(value: unknown, label?: string): asserts value is PayloadSchema;
+export declare function parsePayloadWithSchema<TSchema extends StandardSchemaV1<any, any>>(schema: TSchema, payload: unknown, label: string): Promise<PayloadSchemaOutput<TSchema>>;

package/dist/schema/task.d.ts

@@ -0,0 +1,3 @@
+export declare function validateTaskId(value: string): void;
+export declare function validateQueueName(value: string): void;
+export declare function validateOptionalQueueConcurrencyLimit(value: unknown): void;

package/dist/secret.d.ts

@@ -0,0 +1 @@
+export declare function validateSecretName(value: string): void;

package/dist/session.d.ts

@@ -0,0 +1,5 @@
+import type { SessionRef } from "./contract.js";
+export declare function createRuntimeSessionRef(id: string): SessionRef;
+export declare const sessions: Readonly<{
+    ref(id: string): SessionRef;
+}>;

package/dist/task.d.ts

@@ -0,0 +1,2 @@
+export { queue, task } from "./definitions.js";
+export type { Queue, QueueConfig, TaskCallOptions, TaskConfig, TaskConfigWithPayload, TaskConfigWithoutPayload, Task, TaskInput, TaskOutput, TaskStartOptions, } from "./contract.js";

package/dist/timers.d.ts

@@ -0,0 +1,6 @@
+import type { Duration } from "./contract.js";
+export interface Timers {
+    waitFor(duration: Duration): Promise<void>;
+    waitUntil(date: Date): Promise<void>;
+}
+export declare const timers: Timers;

package/dist/tokens.d.ts

@@ -0,0 +1,77 @@
+import type { Duration, HelmrError, JsonValue, Metadata, WaitTimeoutError } from "./contract.js";
+import { type PayloadSchemaOutput, type StandardSchemaV1 } from "./schema/payload.js";
+export interface TokenCreateRequest {
+    readonly timeout?: Duration;
+    readonly metadata?: Metadata;
+    readonly tags?: readonly string[];
+    readonly idempotencyKey?: string;
+}
+export interface TokenWaitOptions {
+    readonly timeout?: Duration;
+    readonly idleTimeout?: Duration;
+    readonly metadata?: Metadata;
+    readonly tags?: readonly string[];
+}
+export type TokenStatus = "pending" | "completed" | "cancelled" | "expired";
+export interface Token {
+    readonly id: string;
+    readonly status: TokenStatus;
+    readonly result?: JsonValue;
+    readonly metadata: Metadata;
+    readonly tags: readonly string[];
+    readonly timeoutAt: string;
+    readonly completedAt?: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface TokenListItem {
+    readonly id: string;
+    readonly status: TokenStatus;
+    readonly tags: readonly string[];
+    readonly timeoutAt: string;
+    readonly completedAt?: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface TokenListQuery {
+    readonly status?: TokenStatus;
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+export interface TokenCancelledError extends HelmrError {
+    readonly code: "token_cancelled";
+}
+export interface TokenExpiredError extends HelmrError {
+    readonly code: "token_expired";
+}
+export type TokenWaitError = WaitTimeoutError | TokenCancelledError | TokenExpiredError;
+export type TokenWaitResult<T> = Readonly<{
+    ok: true;
+    data: T;
+    unwrap(): T;
+}> | Readonly<{
+    ok: false;
+    error: TokenWaitError;
+    unwrap(): never;
+}>;
+export interface TokenWait<T> extends PromiseLike<TokenWaitResult<T>> {
+    unwrap(): Promise<T>;
+}
+export interface TokenCreateResult extends Token {
+    readonly status: "pending";
+    readonly callbackUrl: string;
+    readonly publicAccessToken: string;
+}
+export interface TokenRef {
+    readonly id: string;
+    wait(options?: TokenWaitOptions): TokenWait<JsonValue>;
+    wait<TSchema extends StandardSchemaV1<any, any>>(options: TokenWaitOptions & Readonly<{
+        schema: TSchema;
+    }>): TokenWait<PayloadSchemaOutput<TSchema>>;
+}
+interface Tokens {
+    create(request?: TokenCreateRequest): Promise<TokenCreateResult & TokenRef>;
+    ref(id: string): TokenRef;
+}
+export declare const tokens: Tokens;
+export {};

package/dist/workspace.d.ts

@@ -0,0 +1,142 @@
+import type { Duration, WorkspaceAddress } from "./contract.js";
+import { type ImageBuilder, type InternalImage } from "./image.js";
+import type { RequestOptions } from "./request.js";
+declare const sandboxTypeBrand: unique symbol;
+export type WorkspaceMemory = `${bigint}MiB` | `${bigint}GiB`;
+export interface WorkspaceResources {
+    readonly cpu: number;
+    readonly memory: WorkspaceMemory;
+}
+export interface SandboxConfig {
+    readonly id: string;
+}
+export interface SandboxBuilder {
+    readonly id: string;
+    image(value: ImageBuilder): SandboxResourceBuilder;
+}
+export interface SandboxResourceBuilder {
+    readonly id: string;
+    resources(value: WorkspaceResources): Sandbox;
+}
+export type WorkspaceStatus = "available" | "recovery_required" | "deleting";
+/** A fixed Workspace binding. Protected material rotates per HTTP request;
+ * raw values resolve per execution admission and remain unchanged in restored memory.
+ */
+export type WorkspaceSecretBinding = Readonly<{
+    secret: string;
+}> & (Readonly<{
+    env: Readonly<{
+        name: string;
+        mode: "raw";
+        allowedOrigins?: never;
+    }>;
+    file?: never;
+}> | Readonly<{
+    env: Readonly<{
+        name: string;
+        mode: "protected";
+        allowedOrigins: readonly string[];
+    }>;
+    file?: never;
+}> | Readonly<{
+    file: Readonly<{
+        path: string;
+    }>;
+    env?: never;
+}>);
+export interface WorkspaceCreateRequest {
+    readonly key?: string;
+    readonly secrets?: readonly WorkspaceSecretBinding[];
+    readonly idempotencyKey?: string;
+}
+export type EncodedWorkspaceSecret = Readonly<{
+    secret: string;
+}> & (Readonly<{
+    env: Readonly<{
+        name: string;
+        mode: "raw" | "protected";
+        allowed_origins?: readonly string[];
+    }>;
+    file?: never;
+}> | Readonly<{
+    file: Readonly<{
+        path: string;
+    }>;
+    env?: never;
+}>);
+/**
+ * The Session or Run that currently owns a Workspace. Absent on an unowned
+ * Workspace.
+ */
+export type WorkspaceOwner = Readonly<{
+    sessionId: string;
+    runId?: never;
+}> | Readonly<{
+    runId: string;
+    sessionId?: never;
+}>;
+export interface Workspace {
+    readonly id: string;
+    readonly key?: string;
+    readonly sandboxId: string;
+    readonly deploymentId: string;
+    readonly status: WorkspaceStatus;
+    readonly owner?: WorkspaceOwner;
+    readonly secrets: readonly WorkspaceSecretBinding[];
+    readonly lastActivityAt: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface WorkspaceExecRequest {
+    readonly command: readonly string[];
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly stdin?: Uint8Array;
+    readonly timeout?: Duration;
+    readonly idempotencyKey: string;
+}
+export interface WorkspaceExecResult {
+    readonly exitCode: number;
+    readonly stdout: Uint8Array;
+    readonly stderr: Uint8Array;
+}
+export interface WorkspaceDeleteRequest {
+    readonly idempotencyKey?: string;
+}
+export interface WorkspaceDeleteReceipt {
+    readonly workspaceId: string;
+}
+export interface WorkspaceRef extends WorkspaceAddress {
+    retrieve(options?: RequestOptions): Promise<Workspace>;
+    exec(request: WorkspaceExecRequest, options?: RequestOptions): Promise<WorkspaceExecResult>;
+    delete(request?: WorkspaceDeleteRequest, options?: RequestOptions): Promise<WorkspaceDeleteReceipt>;
+}
+export interface Sandbox {
+    readonly [sandboxTypeBrand]: true;
+    readonly id: string;
+    createWorkspace(request?: WorkspaceCreateRequest, options?: RequestOptions): Promise<WorkspaceRef>;
+}
+interface Workspaces {
+    ref(id: string): WorkspaceRef;
+}
+export interface InternalSandboxDefinition {
+    readonly kind: "sandbox";
+    readonly id: string;
+    readonly image: InternalImage;
+    readonly resources: WorkspaceResources;
+}
+export declare function sandbox(config: SandboxConfig): SandboxBuilder;
+export declare const workspaces: Workspaces;
+export declare function inspectWorkspaceAddress(value: unknown): WorkspaceAddress | undefined;
+export declare function workspaceRefID(value: unknown): string;
+export declare function encodeWorkspaceSecrets(inputs: readonly WorkspaceSecretBinding[] | undefined): readonly EncodedWorkspaceSecret[];
+export declare function inspectSandboxDefinition(value: unknown): InternalSandboxDefinition | undefined;
+export declare function createWorkspaceRef(id: string): WorkspaceRef;
+export declare function brandWorkspaceAddress<T extends {
+    readonly id: string;
+}>(value: T): T & WorkspaceAddress;
+export declare function parseWorkspace(value: unknown): Workspace;
+export declare function parseWorkspaceOwner(value: unknown, label: string): WorkspaceOwner | undefined;
+export declare function parseWorkspaceExecResult(value: unknown): WorkspaceExecResult;
+export declare function parseWorkspaceDeleteReceipt(value: unknown): WorkspaceDeleteReceipt;
+export {};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@helmr/sdk",
+  "version": "0.1.0-preview.g4db36b8f.b35308518307",
+  "description": "TypeScript SDK for authoring and starting 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/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-preview.g4db36b8f.b35308518307"
+  },
+  "helmr": {
+    "formatVersion": 0,
+    "sourceCommit": "4db36b8f10d59cefa39075e8502762a460c1e3f6",
+    "buildId": "35308518307"
+  }
+}