@renderinc/sdk 0.2.1 → 0.3.0

package/src/index.ts

@@ -1,7 +0,0 @@
-// Main Render SDK class
-
-export * from "./errors.js";
-// Experimental features - types only (instances accessed via render.experimental)
-export type { ExperimentalClient } from "./experimental/index.js";
-export { Render } from "./render.js";
-export { getUserAgent, VERSION } from "./version.js";

package/src/render.ts

@@ -1,35 +0,0 @@
-import type { Client } from "openapi-fetch";
-import { RenderError } from "./errors.js";
-import { ExperimentalClient } from "./experimental/experimental.js";
-import type { paths } from "./generated/schema.js";
-import { createApiClient } from "./utils/create-api-client.js";
-import { getBaseUrl } from "./utils/get-base-url.js";
-import { WorkflowsClient } from "./workflows/client/index.js";
-import type { ClientOptions } from "./workflows/client/types.js";
-
-/**
- * Main Render SDK class providing access to all Render products
- */
-export class Render {
-  public readonly workflows: WorkflowsClient;
-  public readonly experimental: ExperimentalClient;
-
-  private readonly apiClient: Client<paths>;
-
-  /**
-   * Create a new Render SDK instance
-   * @param options Client configuration options
-   */
-  constructor(options?: ClientOptions) {
-    const token = options?.token || process.env.RENDER_API_KEY;
-    if (!token) {
-      throw new RenderError(
-        "API token is required. Provide it via options.token or RENDER_API_KEY environment variable.",
-      );
-    }
-    const baseUrl = getBaseUrl(options);
-    this.apiClient = createApiClient(baseUrl, token);
-    this.workflows = new WorkflowsClient(this.apiClient, baseUrl, token);
-    this.experimental = new ExperimentalClient(this.apiClient);
-  }
-}

package/src/utils/create-api-client.ts

@@ -1,13 +0,0 @@
-import createClient, { type Client } from "openapi-fetch";
-import type { paths } from "../generated/schema";
-import { getUserAgent } from "../version.js";
-
-export function createApiClient(baseUrl: string, token: string): Client<paths> {
-  return createClient<paths>({
-    baseUrl: `${baseUrl}/v1`,
-    headers: {
-      Authorization: `Bearer ${token}`,
-      "User-Agent": getUserAgent(),
-    },
-  });
-}

package/src/utils/get-base-url.test.ts

@@ -1,58 +0,0 @@
-import { getBaseUrl } from "./get-base-url.js";
-
-describe("getBaseUrl", () => {
-  const originalEnv = process.env;
-
-  beforeEach(() => {
-    process.env = { ...originalEnv };
-    process.env.RENDER_USE_LOCAL_DEV = undefined;
-    process.env.RENDER_LOCAL_DEV_URL = undefined;
-  });
-
-  afterEach(() => {
-    process.env = originalEnv;
-  });
-
-  it("returns production URL by default", () => {
-    expect(getBaseUrl()).toBe("https://api.render.com");
-  });
-
-  it("returns custom baseUrl when provided", () => {
-    expect(getBaseUrl({ baseUrl: "https://custom.api.com" })).toBe("https://custom.api.com");
-  });
-
-  it("returns local dev URL when useLocalDev is true", () => {
-    expect(getBaseUrl({ useLocalDev: true })).toBe("http://localhost:8120");
-  });
-
-  it("respects custom localDevUrl", () => {
-    expect(getBaseUrl({ useLocalDev: true, localDevUrl: "http://localhost:9000" })).toBe(
-      "http://localhost:9000",
-    );
-  });
-
-  it("respects RENDER_USE_LOCAL_DEV env var", () => {
-    process.env.RENDER_USE_LOCAL_DEV = "true";
-    expect(getBaseUrl()).toBe("http://localhost:8120");
-  });
-
-  it("respects RENDER_LOCAL_DEV_URL env var", () => {
-    process.env.RENDER_USE_LOCAL_DEV = "true";
-    process.env.RENDER_LOCAL_DEV_URL = "http://localhost:7777";
-    expect(getBaseUrl()).toBe("http://localhost:7777");
-  });
-
-  it("option overrides env var for localDevUrl", () => {
-    process.env.RENDER_USE_LOCAL_DEV = "true";
-    process.env.RENDER_LOCAL_DEV_URL = "http://localhost:7777";
-    expect(getBaseUrl({ useLocalDev: true, localDevUrl: "http://localhost:9999" })).toBe(
-      "http://localhost:9999",
-    );
-  });
-
-  it("ignores baseUrl option when in local dev mode", () => {
-    expect(getBaseUrl({ useLocalDev: true, baseUrl: "https://custom.api.com" })).toBe(
-      "http://localhost:8120",
-    );
-  });
-});

package/src/utils/get-base-url.ts

@@ -1,16 +0,0 @@
-interface GetBaseUrlProps {
-  useLocalDev?: boolean;
-  localDevUrl?: string;
-  baseUrl?: string;
-}
-export function getBaseUrl(options?: GetBaseUrlProps): string {
-  let baseUrl: string;
-  const useLocalDev = options?.useLocalDev ?? process.env.RENDER_USE_LOCAL_DEV === "true";
-
-  if (useLocalDev) {
-    baseUrl = options?.localDevUrl || process.env.RENDER_LOCAL_DEV_URL || "http://localhost:8120";
-  } else {
-    baseUrl = options?.baseUrl || "https://api.render.com";
-  }
-  return baseUrl;
-}

package/src/version.ts

@@ -1,37 +0,0 @@
-/**
- * Version information for the Render SDK.
- */
-
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-
-/**
- * Get the SDK version from package.json.
- * __dirname points to dist/ after compilation, package.json is one level up.
- */
-function getVersion(): string {
-  try {
-    const pkgPath = join(__dirname, "..", "package.json");
-    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { version?: string };
-    return pkg.version ?? "unknown";
-  } catch {
-    return "unknown";
-  }
-}
-
-/** The current version of the Render TypeScript SDK. */
-export const VERSION = getVersion();
-
-/**
- * Get the User-Agent string for the SDK.
- *
- * Returns a string like:
- *   render-sdk-typescript/0.1.0 (node/20.10.0; darwin/arm64)
- */
-export function getUserAgent(): string {
-  const nodeVersion = process.version.replace("v", "");
-  const platform = process.platform;
-  const arch = process.arch;
-
-  return `render-sdk-typescript/${VERSION} (node/${nodeVersion}; ${platform}/${arch})`;
-}

package/src/workflows/client/client.test.ts

@@ -1,68 +0,0 @@
-import type { Client } from "openapi-fetch";
-import { AbortError, ClientError, ServerError } from "../../errors.js";
-import type { paths } from "../../generated/schema.js";
-import { WorkflowsClient } from "./client.js";
-
-describe("WorkflowsClient", () => {
-  describe("runTask", () => {
-    it("throws AbortError if signal already aborted", async () => {
-      // No API calls occur; client throws before using the client
-      const mockApiClient = {} as unknown as Client<paths>;
-      const client = new WorkflowsClient(mockApiClient, "http://test", "token");
-
-      const controller = new AbortController();
-      controller.abort();
-      await expect(client.runTask("task-1", ["data"], controller.signal)).rejects.toBeInstanceOf(
-        AbortError,
-      );
-    });
-  });
-
-  describe("handleApiError (via getTaskRun)", () => {
-    it("throws ServerError for 5xx status", async () => {
-      const mockApiClient = {
-        GET: vi.fn().mockResolvedValue({
-          error: { message: "Internal error" },
-          response: { status: 500 },
-        }),
-      } as unknown as Client<paths>;
-
-      const client = new WorkflowsClient(mockApiClient, "http://test", "token");
-
-      await expect(client.getTaskRun("run-123")).rejects.toBeInstanceOf(ServerError);
-      await expect(client.getTaskRun("run-123")).rejects.toMatchObject({
-        statusCode: 500,
-      });
-    });
-
-    it("throws ClientError for 4xx status", async () => {
-      const mockApiClient = {
-        GET: vi.fn().mockResolvedValue({
-          error: { message: "Not found" },
-          response: { status: 404 },
-        }),
-      } as unknown as Client<paths>;
-
-      const client = new WorkflowsClient(mockApiClient, "http://test", "token");
-
-      await expect(client.getTaskRun("run-123")).rejects.toBeInstanceOf(ClientError);
-      await expect(client.getTaskRun("run-123")).rejects.toMatchObject({
-        statusCode: 404,
-      });
-    });
-  });
-
-  describe("listTaskRuns", () => {
-    it("throws ClientError for 400 status", async () => {
-      const mockApiClient = {
-        GET: vi.fn().mockResolvedValue({
-          error: { message: "Bad request" },
-          response: { status: 400 },
-        }),
-      } as unknown as Client<paths>;
-
-      const client = new WorkflowsClient(mockApiClient, "http://test", "token");
-      await expect(client.listTaskRuns({ taskId: ["task-1"] })).rejects.toBeInstanceOf(ClientError);
-    });
-  });
-});

package/src/workflows/client/client.ts

@@ -1,142 +0,0 @@
-import type { Client as ApiClient } from "openapi-fetch";
-import { AbortError, ClientError, ServerError } from "../../errors.js";
-import type { paths } from "../../generated/schema.js";
-import { SSEClient } from "./sse.js";
-import type {
-  ListTaskRunsParams,
-  TaskData,
-  TaskIdentifier,
-  TaskRun,
-  TaskRunDetails,
-} from "./types.js";
-
-/**
- * Helper function to handle API errors and throw appropriate custom error types
- */
-function handleApiError(error: any, response: Response, context: string): never {
-  const statusCode = response.status;
-  const errorMessage = `${context}: ${error}`;
-
-  if (statusCode >= 500) {
-    throw new ServerError(errorMessage, statusCode, error);
-  } else if (statusCode >= 400) {
-    throw new ClientError(errorMessage, statusCode, error);
-  }
-  throw new ClientError(errorMessage, statusCode, error);
-}
-
-/**
- * Main Render SDK Client
- */
-export class WorkflowsClient {
-  private readonly sse: SSEClient;
-  private readonly apiClient: ApiClient<paths>;
-
-  /**
-   * Create a new Render SDK client
-   * @param options Client configuration options
-   * @returns New client instance
-   */
-  constructor(apiClient: ApiClient<paths>, baseUrl: string, token: string) {
-    this.sse = new SSEClient(baseUrl, token);
-    this.apiClient = apiClient;
-  }
-
-  async runTask(
-    taskIdentifier: TaskIdentifier,
-    inputData: TaskData,
-    signal?: AbortSignal,
-  ): Promise<TaskRunDetails> {
-    if (signal?.aborted) {
-      throw new AbortError();
-    }
-
-    let taskRunId: string | null = null;
-    const abortHandler = async () => {
-      if (taskRunId) {
-        await this.cancelTaskRun(taskRunId);
-        throw new AbortError();
-      }
-    };
-
-    try {
-      // Register abort handler before making the request
-      signal?.addEventListener("abort", abortHandler);
-
-      const { data, error, response } = await this.apiClient.POST("/task-runs", {
-        body: {
-          task: taskIdentifier,
-          input: inputData,
-        },
-        signal,
-      });
-
-      if (error) {
-        handleApiError(error, response, "Failed to run task");
-      }
-
-      taskRunId = data.id;
-
-      // Pass signal to waitForTask so it can handle cancellation during wait
-      return await this.waitForTask(data.id, signal);
-    } catch (err) {
-      // Handle DOMException AbortError from fetch
-      if (err instanceof DOMException && err.name === "AbortError") {
-        throw new AbortError();
-      }
-      throw err;
-    } finally {
-      signal?.removeEventListener("abort", abortHandler);
-    }
-  }
-
-  private async waitForTask(taskRunId: string, signal?: AbortSignal): Promise<TaskRunDetails> {
-    return this.sse.waitOnTaskRun(taskRunId, signal);
-  }
-
-  /**
-   * Get task run details by ID
-   * @param taskRunId Task run ID
-   * @returns Task run details
-   */
-
-  async getTaskRun(taskRunId: string): Promise<TaskRunDetails> {
-    const { data, error, response } = await this.apiClient.GET("/task-runs/{taskRunId}", {
-      params: { path: { taskRunId } },
-    });
-    if (error) {
-      handleApiError(error, response, "Failed to get task run");
-    }
-    return data;
-  }
-
-  /**
-   * Cancel a task run
-   * @param taskRunId Task run ID
-   */
-
-  private async cancelTaskRun(taskRunId: string): Promise<void> {
-    const { error, response } = await this.apiClient.DELETE("/task-runs/{taskRunId}", {
-      params: { path: { taskRunId } },
-    });
-    if (error) {
-      handleApiError(error, response, "Failed to cancel task run");
-    }
-  }
-
-  /**
-   * List task runs with optional filters
-   * @param params Filter parameters
-   * @returns List of task runs
-   */
-
-  async listTaskRuns(params: ListTaskRunsParams): Promise<TaskRun[]> {
-    const { data, error, response } = await this.apiClient.GET("/task-runs", {
-      params: { query: params },
-    });
-    if (error) {
-      handleApiError(error, response, "Failed to list task runs");
-    }
-    return data;
-  }
-}

package/src/workflows/client/create-client.ts

@@ -1,17 +0,0 @@
-import { RenderError } from "../../errors";
-import { createApiClient } from "../../utils/create-api-client";
-import { getBaseUrl } from "../../utils/get-base-url";
-import { WorkflowsClient } from "./client";
-import type { ClientOptions } from "./types";
-
-export function createWorkflowsClient(options?: ClientOptions): WorkflowsClient {
-  const token = options?.token || process.env.RENDER_API_KEY;
-  if (!token) {
-    throw new RenderError(
-      "API token is required. Provide it via options.token or RENDER_API_KEY environment variable.",
-    );
-  }
-  const baseUrl = getBaseUrl(options);
-  const apiClient = createApiClient(baseUrl, token);
-  return new WorkflowsClient(apiClient, baseUrl, token);
-}

package/src/workflows/client/index.ts

@@ -1,3 +0,0 @@
-export { WorkflowsClient } from "./client.js";
-export { createWorkflowsClient } from "./create-client.js";
-export * from "./types.js";

package/src/workflows/client/sse.ts

@@ -1,95 +0,0 @@
-import { EventSource } from "eventsource";
-import { AbortError } from "../../errors.js";
-import { getUserAgent } from "../../version.js";
-import type { TaskRunDetails } from "./types.js";
-
-/**
- * Task event types emitted by the SSE stream
- */
-export enum TaskEventType {
-  COMPLETED = "task.completed",
-  FAILED = "task.failed",
-  RUNNING = "task.running",
-  PENDING = "task.pending",
-}
-
-/**
- * SSE Client for streaming task run events
- */
-export class SSEClient {
-  constructor(
-    private readonly baseUrl: string,
-    private readonly token: string,
-  ) {}
-
-  async waitOnTaskRun(taskRunId: string, signal?: AbortSignal): Promise<TaskRunDetails> {
-    return new Promise((resolve, reject) => {
-      let eventSource: EventSource | null = null;
-
-      const abortHandler = () => {
-        cleanup();
-        reject(new AbortError());
-      };
-
-      const cleanup = () => {
-        if (eventSource) {
-          eventSource.removeEventListener(TaskEventType.COMPLETED, eventHandler);
-          eventSource.removeEventListener(TaskEventType.FAILED, eventHandler);
-          eventSource.removeEventListener("error", errorHandler);
-          eventSource.close();
-          eventSource = null;
-        }
-        signal?.removeEventListener("abort", abortHandler);
-      };
-
-      const eventHandler = (event: MessageEvent) => {
-        try {
-          const details = JSON.parse(event.data) as TaskRunDetails;
-          cleanup();
-          resolve(details);
-        } catch (e) {
-          cleanup();
-          reject(new Error(`Failed to parse task run details: ${e}`));
-        }
-      };
-
-      const errorHandler = (error: any) => {
-        cleanup();
-        reject(new Error(`SSE connection error: ${error.message || "Unknown error"}`));
-      };
-
-      // Check if already aborted
-      if (signal?.aborted) {
-        reject(new AbortError());
-        return;
-      }
-
-      // Listen for abort signal
-      signal?.addEventListener("abort", abortHandler);
-
-      try {
-        const url = new URL("/v1/task-runs/events", this.baseUrl);
-        url.searchParams.append("taskRunIds", taskRunId);
-
-        eventSource = new EventSource(url.toString(), {
-          fetch: (input, init) =>
-            fetch(input, {
-              ...init,
-              headers: {
-                ...init?.headers,
-                Authorization: `Bearer ${this.token}`,
-                "User-Agent": getUserAgent(),
-              },
-            }),
-        });
-
-        eventSource.addEventListener(TaskEventType.COMPLETED, eventHandler);
-        eventSource.addEventListener(TaskEventType.FAILED, eventHandler);
-        eventSource.addEventListener("error", errorHandler);
-      } catch (e) {
-        cleanup();
-        reject(e);
-      }
-    });
-  }
-}

package/src/workflows/client/types.ts

@@ -1,56 +0,0 @@
-import type { components, paths } from "../../generated/schema";
-
-/**
- * Task identifier in the format "workflow-slug/task-name"
- */
-export type TaskIdentifier = string;
-
-/**
- * Task input data as an array of parameters
- */
-export type TaskData = Array<any>;
-
-/**
- * Task run status enum
- */
-export enum TaskRunStatus {
-  PENDING = "pending",
-  RUNNING = "running",
-  COMPLETED = "completed",
-  FAILED = "failed",
-}
-
-/**
- * Basic task run information
- */
-
-export type TaskRun = components["schemas"]["TaskRun"];
-
-/**
- * Detailed task run information including results and errors
- */
-
-export type TaskRunDetails = components["schemas"]["TaskRunDetails"];
-
-/**
- * Parameters for listing task runs
- */
-export type ListTaskRunsParams = paths["/task-runs"]["get"]["parameters"]["query"];
-
-/**
- * Request body for running a task
- */
-export interface RunTaskRequest {
-  task: TaskIdentifier;
-  input: TaskData;
-}
-
-/**
- * Client configuration options
- */
-export interface ClientOptions {
-  token?: string;
-  baseUrl?: string;
-  useLocalDev?: boolean;
-  localDevUrl?: string;
-}

package/src/workflows/executor.ts

@@ -1,124 +0,0 @@
-import { RenderError } from "../errors.js";
-import { TaskRegistry } from "./registry.js";
-import { setCurrentContext } from "./task.js";
-import type { TaskContext, TaskFunction, TaskResult } from "./types.js";
-import { UDSClient } from "./uds.js";
-
-/**
- * Implementation of TaskResult
- */
-class TaskResultImpl<T> implements TaskResult<T> {
-  constructor(
-    private readonly subtaskId: string,
-    private readonly udsClient: UDSClient,
-  ) {}
-
-  async get(): Promise<T> {
-    // Poll for subtask result
-    const pollInterval = 500; // half a second
-
-    while (true) {
-      const result = await this.udsClient.getSubtaskResult(this.subtaskId);
-
-      if (!result.still_running && result.complete) {
-        if (result.complete.output) {
-          const json = Buffer.from(result.complete.output, "base64").toString();
-          const decoded = JSON.parse(json);
-          return decoded[0];
-        }
-        return undefined as T;
-      } else if (!result.still_running && result.error) {
-        throw new RenderError(`Subtask failed: ${result.error}`);
-      }
-
-      // Still pending, wait and retry
-      await new Promise((resolve) => setTimeout(resolve, pollInterval));
-    }
-  }
-}
-
-/**
- * Implementation of TaskContext
- */
-class TaskContextImpl implements TaskContext {
-  constructor(private readonly udsClient: UDSClient) {}
-
-  executeTask<TArgs extends any[], TResult>(
-    _task: TaskFunction<TArgs, TResult>,
-    taskName: string,
-    ...args: TArgs
-  ): TaskResult<TResult> {
-    const registry = TaskRegistry.getInstance();
-
-    if (!registry.has(taskName)) {
-      throw new RenderError(`Task '${taskName}' is not registered`);
-    }
-
-    // Execute subtask via UDS
-    const subtaskIdPromise = this.udsClient.runSubtask(taskName, args);
-
-    // Return a TaskResult that will poll for completion
-    return {
-      get: async () => {
-        const subtaskId = await subtaskIdPromise;
-        const result = new TaskResultImpl<TResult>(subtaskId, this.udsClient);
-        return result.get();
-      },
-    };
-  }
-}
-
-/**
- * Task executor that runs tasks via Unix socket communication
- */
-export class TaskExecutor {
-  private readonly udsClient: UDSClient;
-  private readonly context: TaskContext;
-
-  constructor(socketPath: string) {
-    this.udsClient = new UDSClient(socketPath);
-    this.context = new TaskContextImpl(this.udsClient);
-  }
-
-  /**
-   * Execute a single task
-   */
-  async executeTask(): Promise<void> {
-    const registry = TaskRegistry.getInstance();
-
-    try {
-      // Get task input
-      const input = await this.udsClient.getInput();
-      const taskName = input.task_name;
-      const inputData = JSON.parse(Buffer.from(input.input, "base64").toString());
-
-      // Get task from registry
-      const taskMetadata = registry.get(taskName);
-      if (!taskMetadata) {
-        throw new RenderError(`Task '${taskName}' not found in registry`);
-      }
-
-      // Execute task with context
-      const result = await setCurrentContext(this.context, async () => {
-        return await taskMetadata.func(...inputData);
-      });
-
-      // Send result
-      await this.udsClient.sendCallback(result);
-    } catch (error) {
-      // Send error
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      await this.udsClient.sendCallback(undefined, errorMessage);
-      throw error;
-    }
-  }
-
-  /**
-   * Register all tasks with the workflow system
-   */
-  async registerTasks(): Promise<void> {
-    const registry = TaskRegistry.getInstance();
-    const tasks = registry.getAllTasks();
-    await this.udsClient.registerTasks(tasks);
-  }
-}

package/src/workflows/index.ts

@@ -1,7 +0,0 @@
-// Export client API
-export * from "./client/index.js";
-export { TaskExecutor } from "./executor.js";
-export { TaskRegistry } from "./registry.js";
-export { run, startTaskServer } from "./runner.js";
-export { getCurrentContext, setCurrentContext, task } from "./task.js";
-export * from "./types.js";