@renderinc/sdk 0.1.0

package/README.md

@@ -0,0 +1,580 @@
+# Render Workflow SDK for TypeScript
+
+The official TypeScript SDK for Render Workflows, providing a simple and intuitive API for managing and executing tasks.
+
+## Features
+
+- **REST API Client**: Run, monitor, and manage task runs
+- **Task Definition SDK**: Define and register tasks with decorators
+- **Server-Sent Events**: Real-time streaming of task run events
+- **Async/Await Support**: Modern Promise-based API
+- **TypeScript First**: Full type safety and IntelliSense support
+- **Retry Logic**: Configurable retry behavior for tasks
+- **Subtask Execution**: Execute tasks from within other tasks
+
+## Installation
+
+```bash
+npm install @renderinc/sdk
+```
+
+Or with yarn:
+
+```bash
+yarn add @renderinc/sdk
+```
+
+Or with pnpm:
+
+```bash
+pnpm add @renderinc/sdk
+```
+
+## Quick Start
+
+### REST API Client
+
+Use the Render SDK to run tasks and monitor their execution:
+
+```typescript
+import { Render } from '@renderinc/sdk';
+
+// Create a Render SDK instance (uses RENDER_API_KEY from environment)
+const render = new Render();
+
+// Run a task and wait for completion
+const result = await render.workflows.runTask('my-workflow/my-task', [42, 'hello']);
+console.log('Status:', result.status);
+console.log('Results:', result.results);
+
+// List recent task runs
+const taskRuns = await render.workflows.listTaskRuns({ limit: 10 });
+
+// Get specific task run
+const details = await render.workflows.getTaskRun(result.id);
+```
+
+Alternatively, you can create a workflows client directly:
+
+```typescript
+import { createWorkflowsClient } from '@renderinc/sdk/workflows';
+
+const client = createWorkflowsClient();
+const result = await client.runTask('my-workflow/my-task', [42, 'hello']);
+```
+
+### Task Definition
+
+Define tasks that can be executed by the workflow system:
+
+```typescript
+import { task, startTaskServer } from '@renderinc/sdk/workflows';
+
+// Simple task
+const square = task(
+  { name: 'square' },
+  function square(a: number): number {
+    return a * a;
+  }
+);
+
+// Async task with subtask execution
+task(
+  { name: 'addSquares' },
+  async function addSquares(a: number, b: number): Promise<number> {
+    const result1 = await square(a);
+    const result2 = await square(b);
+    return result1 + result2;
+  }
+);
+
+// Task with custom options
+task(
+  {
+    name: 'retryableTask',
+    retry: {
+      maxRetries: 3,
+      waitDurationMs: 1000,
+      factor: 1.5,
+    },
+  },
+  async function retryableTask(input: string): Promise<string> {
+    // Task implementation
+    return input.toUpperCase();
+  }
+);
+
+// Start the task server
+await startTaskServer();
+```
+
+## API Reference
+
+### Render SDK
+
+#### `new Render(options?)`
+
+Creates a new Render SDK instance with access to all Render products.
+
+**Options:**
+- `token?: string` - API token (defaults to `RENDER_API_KEY` env var)
+- `baseUrl?: string` - Base URL (defaults to `https://api.render.com`)
+- `useLocalDev?: boolean` - Use local development mode
+- `localDevUrl?: string` - Local development URL
+
+**Properties:**
+- `workflows` - WorkflowsClient instance for managing workflow tasks
+
+**Example:**
+```typescript
+import { Render } from '@renderinc/sdk';
+
+const render = new Render({
+  token: 'your-api-token',
+  baseUrl: 'https://api.render.com',
+});
+
+// Access workflows client
+const result = await render.workflows.runTask('my-workflow/task', [42]);
+```
+
+### Workflows Client API
+
+The workflows client is accessible via `render.workflows` or can be created directly using `createWorkflowsClient`:
+
+```typescript
+import { createWorkflowsClient } from '@renderinc/sdk/workflows';
+
+const client = createWorkflowsClient({
+  token: 'your-api-token',
+  baseUrl: 'https://api.render.com',
+});
+```
+
+### Workflows Client Methods
+
+#### `render.workflows.runTask(taskIdentifier, inputData, signal?)`
+
+Runs a task and waits for completion.
+
+**Parameters:**
+- `taskIdentifier: string` - Task identifier in format "workflow-slug/task-name"
+- `inputData: any[]` - Input data as array of parameters
+- `signal?: AbortSignal` - Optional abort signal for cancellation
+
+**Returns:** `Promise<TaskRunDetails>`
+
+**Example:**
+```typescript
+const render = new Render();
+const result = await render.workflows.runTask('my-workflow/square', [5]);
+console.log('Results:', result.results);
+```
+
+#### `render.workflows.getTaskRun(taskRunId)`
+
+Gets task run details by ID.
+
+**Parameters:**
+- `taskRunId: string` - Task run ID
+
+**Returns:** `Promise<TaskRunDetails>`
+
+**Example:**
+```typescript
+const render = new Render();
+const details = await render.workflows.getTaskRun('task-run-id');
+```
+
+#### `render.workflows.listTaskRuns(params)`
+
+Lists task runs with optional filters.
+
+**Parameters:**
+- `params.limit?: number` - Maximum number of results
+- `params.cursor?: string` - Pagination cursor
+- `params.ownerId?: string[]` - Filter by owner IDs
+
+**Returns:** `Promise<TaskRun[]>`
+
+**Example:**
+```typescript
+const render = new Render();
+const taskRuns = await render.workflows.listTaskRuns({ limit: 10 });
+```
+
+### Task API
+
+#### `task(options, func)`
+
+Registers a function as a task.
+
+**Parameters:**
+- `options: RegisterTaskOptions` - Task configuration
+  - `name: string` - Task name (required)
+  - `retry?: RetryOptions` - Optional retry configuration
+    - `maxRetries: number` - Maximum number of retries
+    - `waitDurationMs: number` - Wait duration between retries in milliseconds
+    - `factor?: number` - Backoff factor (default: 1.5)
+- `func: TaskFunction` - The task function to register
+
+**Returns:** The registered function with the same signature
+
+**Usage:**
+```typescript
+// Basic usage
+const myTask = task(
+  { name: 'myTask' },
+  function myTask(arg: string): string {
+    return arg.toUpperCase();
+  }
+);
+
+// With retry options
+task(
+  {
+    name: 'retryableTask',
+    retry: {
+      maxRetries: 3,
+      waitDurationMs: 1000,
+      factor: 1.5,
+    },
+  },
+  function retryableTask(arg: string): string {
+    return arg.toUpperCase();
+  }
+);
+
+// Async task with subtasks
+const square = task(
+  { name: 'square' },
+  function square(a: number): number {
+    return a * a;
+  }
+);
+
+task(
+  { name: 'addSquares' },
+  async function addSquares(a: number, b: number): Promise<number> {
+    const result1 = await square(a);
+    const result2 = await square(b);
+    return result1 + result2;
+  }
+);
+```
+
+#### `startTaskServer()`
+
+Starts the task server and listens for task execution requests.
+
+**Returns:** `Promise<void>`
+
+**Example:**
+```typescript
+await startTaskServer();
+```
+
+### Types
+
+#### `TaskRunStatus`
+
+```typescript
+enum TaskRunStatus {
+  PENDING = 'pending',
+  RUNNING = 'running',
+  COMPLETED = 'completed',
+  FAILED = 'failed',
+}
+```
+
+#### `TaskRun`
+
+```typescript
+interface TaskRun {
+  id: string;
+  status: TaskRunStatus;
+  created_at: string;
+  updated_at: string;
+  task_identifier: string;
+}
+```
+
+#### `TaskRunDetails`
+
+```typescript
+interface TaskRunDetails extends TaskRun {
+  completed_at?: string;
+  results?: any[];
+  error?: string;
+}
+```
+
+#### `RegisterTaskOptions`
+
+```typescript
+interface RegisterTaskOptions {
+  name: string;
+  retry?: {
+    maxRetries: number;
+    waitDurationMs: number;
+    factor?: number; // default 1.5
+  };
+}
+```
+
+### Error Handling
+
+The SDK provides several error classes:
+
+```typescript
+import { Render } from '@renderinc/sdk';
+import {
+  RenderError,
+  ClientError,
+  ServerError,
+  AbortError,
+} from '@renderinc/sdk';
+
+const render = new Render();
+
+try {
+  const result = await render.workflows.runTask('my-workflow/task', [42]);
+} catch (error) {
+  if (error instanceof ClientError) {
+    console.error('Client error:', error.statusCode, error.cause);
+  } else if (error instanceof ServerError) {
+    console.error('Server error:', error.statusCode, error.cause);
+  } else if (error instanceof AbortError) {
+    console.error('Request was aborted');
+  } else if (error instanceof RenderError) {
+    console.error('General SDK error:', error.message);
+  }
+}
+```
+
+## Environment Variables
+
+- `RENDER_API_KEY` - Your Render API key (required)
+- `RENDER_USE_LOCAL_DEV` - Enable local development mode (`true`/`false`)
+- `RENDER_LOCAL_DEV_URL` - Local development URL (default: `http://localhost:8120`)
+- `RENDER_SDK_MODE` - Task execution mode (`run` or `register`)
+- `RENDER_SDK_SOCKET_PATH` - Unix socket path for task communication
+
+## Examples
+
+### Example 1: Running a Task
+
+```typescript
+import { Render } from '@renderinc/sdk';
+
+const render = new Render();
+
+async function runSquareTask() {
+  const result = await render.workflows.runTask('my-workflow/square', [5]);
+  console.log('Square of 5 is:', result.results[0]); // 25
+}
+
+runSquareTask();
+```
+
+### Example 2: Defining Tasks with Subtasks
+
+```typescript
+import { task, startTaskServer } from '@renderinc/sdk/workflows';
+
+const square = task(
+  { name: 'square' },
+  function square(a: number): number {
+    return a * a;
+  }
+);
+
+task(
+  { name: 'pythagorean' },
+  async function pythagorean(a: number, b: number): Promise<number> {
+    const aSquared = await square(a);
+    const bSquared = await square(b);
+    return Math.sqrt(aSquared + bSquared);
+  }
+);
+
+await startTaskServer();
+```
+
+### Example 3: Error Handling in Tasks
+
+```typescript
+import { task } from '@renderinc/sdk/workflows';
+
+const divide = task(
+  { name: 'divide' },
+  async function divide(a: number, b: number): Promise<number> {
+    if (b === 0) {
+      throw new Error('Cannot divide by zero');
+    }
+    return a / b;
+  }
+);
+
+task(
+  {
+    name: 'safeDivide',
+    retry: {
+      maxRetries: 3,
+      waitDurationMs: 1000,
+    },
+  },
+  async function safeDivide(a: number, b: number): Promise<number> {
+    try {
+      return await divide(a, b);
+    } catch (error) {
+      console.error('Division failed:', error);
+      return 0; // Return default value
+    }
+  }
+);
+```
+
+### Example 4: Using AbortSignal for Cancellation
+
+```typescript
+import { Render, AbortError } from '@renderinc/sdk';
+
+const render = new Render();
+
+async function runTaskWithCancellation() {
+  const abortController = new AbortController();
+
+  // Cancel the task after 5 seconds
+  setTimeout(() => abortController.abort(), 5000);
+
+  try {
+    const result = await render.workflows.runTask(
+      'my-workflow/long-running-task',
+      [42],
+      abortController.signal
+    );
+    console.log('Task completed:', result.results);
+  } catch (error) {
+    if (error instanceof AbortError) {
+      console.log('Task was cancelled');
+    } else {
+      console.error('Task failed:', error);
+    }
+  }
+}
+
+runTaskWithCancellation();
+```
+
+### Example 5: Using the Unified Render SDK
+
+```typescript
+import { Render } from '@renderinc/sdk';
+
+// Single entry point for all Render products
+const render = new Render({
+  token: process.env.RENDER_API_KEY,
+});
+
+async function workflowExample() {
+  try {
+    // Run a workflow task
+    const result = await render.workflows.runTask('my-workflow/process-data', [
+      { userId: 123, data: 'example' },
+    ]);
+
+    console.log('Workflow completed:', result.status);
+    console.log('Results:', result.results);
+
+    // List and monitor recent task runs
+    const recentRuns = await render.workflows.listTaskRuns({ limit: 5 });
+    console.log(`\nRecent task runs: ${recentRuns.length}`);
+
+    for (const run of recentRuns) {
+      const details = await render.workflows.getTaskRun(run.id);
+      console.log(`- ${run.taskId}: ${details.status}`);
+    }
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+workflowExample();
+```
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+npm test
+```
+
+### Linting
+
+```bash
+npm run lint
+```
+
+### Formatting
+
+```bash
+npm run format
+```
+
+## Project Structure
+
+```
+typescript/
+├── src/
+│   ├── render.ts            # Main Render SDK class
+│   ├── index.ts             # Main exports
+│   └── workflows/           # Workflows functionality
+│       ├── client/          # REST API client
+│       │   ├── client.ts    # WorkflowsClient class
+│       │   ├── workflows.ts # WorkflowsService
+│       │   ├── sse.ts       # SSE client
+│       │   ├── types.ts     # Type definitions
+│       │   ├── errors.ts    # Error classes
+│       │   └── index.ts     # Exports
+│       ├── task/            # Task execution SDK
+│       │   ├── task.ts      # task() function
+│       │   ├── runner.ts    # start() and run()
+│       │   ├── executor.ts  # TaskExecutor
+│       │   ├── registry.ts  # TaskRegistry
+│       │   ├── uds.ts       # Unix socket client
+│       │   ├── types.ts     # Type definitions
+│       │   └── index.ts     # Exports
+│       └── index.ts         # Workflows exports
+├── examples/
+│   ├── client/              # Client example
+│   │   ├── main.ts
+│   │   └── package.json
+│   └── task/                # Task example
+│       ├── main.ts
+│       └── package.json
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## License
+
+MIT
+
+## Support
+
+For issues and questions, please visit:
+- GitHub Issues: https://github.com/renderinc/workflow-sdk/issues
+- Documentation: https://render.com/docs/workflows
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting pull requests.

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+export declare class RenderError extends Error {
+    constructor(message: string);
+}
+export declare class TaskRunError extends RenderError {
+    taskRunId?: string | undefined;
+    taskError?: string | undefined;
+    constructor(message: string, taskRunId?: string | undefined, taskError?: string | undefined);
+}
+export declare class ClientError extends RenderError {
+    statusCode: number;
+    response?: any | undefined;
+    constructor(message: string, statusCode: number, response?: any | undefined);
+}
+export declare class ServerError extends RenderError {
+    statusCode: number;
+    response?: any | undefined;
+    constructor(message: string, statusCode: number, response?: any | undefined);
+}
+export declare class TimeoutError extends RenderError {
+    constructor(message: string);
+}
+export declare class AbortError extends Error {
+    constructor();
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAK5B;AAKD,qBAAa,YAAa,SAAQ,WAAW;IAGlC,SAAS,CAAC,EAAE,MAAM;IAClB,SAAS,CAAC,EAAE,MAAM;gBAFzB,OAAO,EAAE,MAAM,EACR,SAAS,CAAC,EAAE,MAAM,YAAA,EAClB,SAAS,CAAC,EAAE,MAAM,YAAA;CAM5B;AAKD,qBAAa,WAAY,SAAQ,WAAW;IAGjC,UAAU,EAAE,MAAM;IAClB,QAAQ,CAAC,EAAE,GAAG;gBAFrB,OAAO,EAAE,MAAM,EACR,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,GAAG,YAAA;CAMxB;AAKD,qBAAa,WAAY,SAAQ,WAAW;IAGjC,UAAU,EAAE,MAAM;IAClB,QAAQ,CAAC,EAAE,GAAG;gBAFrB,OAAO,EAAE,MAAM,EACR,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,GAAG,YAAA;CAMxB;AAKD,qBAAa,YAAa,SAAQ,WAAW;gBAC/B,OAAO,EAAE,MAAM;CAK5B;AAED,qBAAa,UAAW,SAAQ,KAAK;;CAKpC"}

package/dist/errors.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbortError = exports.TimeoutError = exports.ServerError = exports.ClientError = exports.TaskRunError = exports.RenderError = void 0;
+class RenderError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RenderError";
+        Object.setPrototypeOf(this, RenderError.prototype);
+    }
+}
+exports.RenderError = RenderError;
+class TaskRunError extends RenderError {
+    constructor(message, taskRunId, taskError) {
+        super(message);
+        this.taskRunId = taskRunId;
+        this.taskError = taskError;
+        this.name = "TaskRunError";
+        Object.setPrototypeOf(this, TaskRunError.prototype);
+    }
+}
+exports.TaskRunError = TaskRunError;
+class ClientError extends RenderError {
+    constructor(message, statusCode, response) {
+        super(message);
+        this.statusCode = statusCode;
+        this.response = response;
+        this.name = "ClientError";
+        Object.setPrototypeOf(this, ClientError.prototype);
+    }
+}
+exports.ClientError = ClientError;
+class ServerError extends RenderError {
+    constructor(message, statusCode, response) {
+        super(message);
+        this.statusCode = statusCode;
+        this.response = response;
+        this.name = "ServerError";
+        Object.setPrototypeOf(this, ServerError.prototype);
+    }
+}
+exports.ServerError = ServerError;
+class TimeoutError extends RenderError {
+    constructor(message) {
+        super(message);
+        this.name = "TimeoutError";
+        Object.setPrototypeOf(this, TimeoutError.prototype);
+    }
+}
+exports.TimeoutError = TimeoutError;
+class AbortError extends Error {
+    constructor() {
+        super("The operation was aborted.");
+        this.name = "AbortError";
+    }
+}
+exports.AbortError = AbortError;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Render } from "./render.js";
+export * from "./errors.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Render = void 0;
+var render_js_1 = require("./render.js");
+Object.defineProperty(exports, "Render", { enumerable: true, get: function () { return render_js_1.Render; } });
+__exportStar(require("./errors.js"), exports);

package/dist/render.d.ts

@@ -0,0 +1,8 @@
+import { WorkflowsClient } from "./workflows/client/index.js";
+import type { ClientOptions } from "./workflows/client/types.js";
+export declare class Render {
+    readonly workflows: WorkflowsClient;
+    private readonly apiClient;
+    constructor(options?: ClientOptions);
+}
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AASjE,qBAAa,MAAM;IACjB,SAAgB,SAAS,EAAE,eAAe,CAAC;IAE3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;gBAM9B,OAAO,CAAC,EAAE,aAAa;CAWpC"}