@renderinc/sdk 0.1.0 → 0.2.1

package/examples/task/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "NodeNext",
+    "resolveJsonModule": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/package.json

@@ -1,17 +1,18 @@
 {
   "name": "@renderinc/sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Render SDK for TypeScript",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
-    "build": "tsc",
+    "build": "tsc -p tsconfig.build.json",
     "test": "vitest",
-    "lint": "biome lint src",
-    "lint:fix": "biome lint --write src",
-    "format": "biome format --write src",
-    "format:check": "biome format src",
-    "check": "biome check --write src",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint",
+    "lint:fix": "biome lint --write",
+    "format": "biome format --write",
+    "format:check": "biome format",
+    "check": "biome check --write",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -22,21 +23,12 @@
   ],
   "author": "Render",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/render-oss/sdk.git",
-    "directory": "typescript"
-  },
-  "homepage": "https://github.com/render-oss/sdk/tree/main/typescript#readme",
-  "bugs": {
-    "url": "https://github.com/render-oss/sdk/issues"
-  },
   "devDependencies": {
     "@biomejs/biome": "2.3.8",
     "@types/node": "^20.0.0",
     "openapi-typescript": "^7.10.1",
     "typescript": "^5.9.3",
-    "vitest": "^1.0.0"
+    "vitest": "^4.0.18"
   },
   "dependencies": {
     "eventsource": "^4.0.0",
@@ -47,19 +39,19 @@
   },
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.js"
     },
     "./workflows": {
+      "types": "./dist/workflows/index.d.ts",
       "import": "./dist/workflows/index.js",
-      "require": "./dist/workflows/index.js",
-      "types": "./dist/workflows/index.d.ts"
+      "require": "./dist/workflows/index.js"
+    },
+    "./experimental": {
+      "types": "./dist/experimental/index.d.ts",
+      "import": "./dist/experimental/index.js",
+      "require": "./dist/experimental/index.js"
     }
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ]
+  }
 }

package/src/errors.test.ts

@@ -0,0 +1,75 @@
+import {
+  AbortError,
+  ClientError,
+  RenderError,
+  ServerError,
+  TaskRunError,
+  TimeoutError,
+} from "./errors.js";
+
+describe("errors", () => {
+  describe("RenderError", () => {
+    it("has correct name and message", () => {
+      const err = new RenderError("test message");
+      expect(err.name).toBe("RenderError");
+      expect(err.message).toBe("test message");
+      expect(err instanceof Error).toBe(true);
+      expect(err instanceof RenderError).toBe(true);
+    });
+  });
+
+  describe("TaskRunError", () => {
+    it("has correct name and properties", () => {
+      const err = new TaskRunError("task failed", "run-123", "internal error");
+      expect(err.name).toBe("TaskRunError");
+      expect(err.message).toBe("task failed");
+      expect(err.taskRunId).toBe("run-123");
+      expect(err.taskError).toBe("internal error");
+      expect(err instanceof RenderError).toBe(true);
+    });
+
+    it("works with optional properties", () => {
+      const err = new TaskRunError("task failed");
+      expect(err.taskRunId).toBeUndefined();
+      expect(err.taskError).toBeUndefined();
+    });
+  });
+
+  describe("ClientError", () => {
+    it("has correct name and properties", () => {
+      const err = new ClientError("not found", 404, { detail: "missing" });
+      expect(err.name).toBe("ClientError");
+      expect(err.statusCode).toBe(404);
+      expect(err.response).toEqual({ detail: "missing" });
+      expect(err instanceof RenderError).toBe(true);
+    });
+  });
+
+  describe("ServerError", () => {
+    it("has correct name and properties", () => {
+      const err = new ServerError("server error", 500, { detail: "crash" });
+      expect(err.name).toBe("ServerError");
+      expect(err.statusCode).toBe(500);
+      expect(err.response).toEqual({ detail: "crash" });
+      expect(err instanceof RenderError).toBe(true);
+    });
+  });
+
+  describe("TimeoutError", () => {
+    it("has correct name and inherits from RenderError", () => {
+      const err = new TimeoutError("request timed out");
+      expect(err.name).toBe("TimeoutError");
+      expect(err.message).toBe("request timed out");
+      expect(err instanceof RenderError).toBe(true);
+    });
+  });
+
+  describe("AbortError", () => {
+    it("has correct name and fixed message", () => {
+      const err = new AbortError();
+      expect(err.name).toBe("AbortError");
+      expect(err.message).toBe("The operation was aborted.");
+      expect(err instanceof Error).toBe(true);
+    });
+  });
+});

package/src/errors.ts

@@ -0,0 +1,73 @@
+/**
+ * Base error class for all Render SDK errors
+ */
+export class RenderError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RenderError";
+    Object.setPrototypeOf(this, RenderError.prototype);
+  }
+}
+
+/**
+ * Error for task execution failures
+ */
+export class TaskRunError extends RenderError {
+  constructor(
+    message: string,
+    public taskRunId?: string,
+    public taskError?: string,
+  ) {
+    super(message);
+    this.name = "TaskRunError";
+    Object.setPrototypeOf(this, TaskRunError.prototype);
+  }
+}
+
+/**
+ * Error for HTTP client errors (4xx)
+ */
+export class ClientError extends RenderError {
+  constructor(
+    message: string,
+    public statusCode: number,
+    public response?: any,
+  ) {
+    super(message);
+    this.name = "ClientError";
+    Object.setPrototypeOf(this, ClientError.prototype);
+  }
+}
+
+/**
+ * Error for HTTP server errors (5xx)
+ */
+export class ServerError extends RenderError {
+  constructor(
+    message: string,
+    public statusCode: number,
+    public response?: any,
+  ) {
+    super(message);
+    this.name = "ServerError";
+    Object.setPrototypeOf(this, ServerError.prototype);
+  }
+}
+
+/**
+ * Error for request timeouts
+ */
+export class TimeoutError extends RenderError {
+  constructor(message: string) {
+    super(message);
+    this.name = "TimeoutError";
+    Object.setPrototypeOf(this, TimeoutError.prototype);
+  }
+}
+
+export class AbortError extends Error {
+  constructor() {
+    super("The operation was aborted.");
+    this.name = "AbortError";
+  }
+}

package/src/experimental/experimental.ts

@@ -0,0 +1,56 @@
+import type { Client } from "openapi-fetch";
+import type { paths } from "../generated/schema.js";
+import { ObjectClient } from "./object/client.js";
+
+/**
+ * StorageClient provides access to experimental storage features
+ *
+ * @example
+ * ```typescript
+ * // Access object storage
+ * await render.experimental.storage.objects.put({
+ *   ownerId: "tea-xxxxx",
+ *   region: "oregon",
+ *   key: "file.png",
+ *   data: buffer
+ * });
+ * ```
+ */
+export class StorageClient {
+  /** Object storage client for managing binary objects */
+  public readonly objects: ObjectClient;
+
+  constructor(apiClient: Client<paths>) {
+    this.objects = new ObjectClient(apiClient);
+  }
+}
+
+/**
+ * ExperimentalClient provides access to experimental Render SDK features
+ *
+ * Features in this namespace may change or be removed without a migration plan.
+ * When a feature stabilizes, it will be promoted to the main SDK namespace.
+ *
+ * @example
+ * ```typescript
+ * import { Render } from '@renderinc/sdk';
+ *
+ * const render = new Render();
+ *
+ * // Access experimental object storage
+ * await render.experimental.storage.objects.put({
+ *   ownerId: "tea-xxxxx",
+ *   region: "oregon",
+ *   key: "file.png",
+ *   data: buffer
+ * });
+ * ```
+ */
+export class ExperimentalClient {
+  /** Storage client for managing storage features */
+  public readonly storage: StorageClient;
+
+  constructor(apiClient: Client<paths>) {
+    this.storage = new StorageClient(apiClient);
+  }
+}

package/src/experimental/index.ts

@@ -0,0 +1,24 @@
+// Experimental client
+
+export { ExperimentalClient, StorageClient } from "./experimental.js";
+// Object storage exports
+export {
+  type DeleteObjectInput,
+  type GetObjectInput,
+  ObjectApi,
+  ObjectClient,
+  type ObjectData,
+  type ObjectIdentifier,
+  type ObjectScope,
+  type PresignedDownloadUrl,
+  type PresignedUploadUrl,
+  type PutObjectInput,
+  type PutObjectInputBuffer,
+  type PutObjectInputStream,
+  type PutObjectResult,
+  Region,
+  type ScopedDeleteObjectInput,
+  type ScopedGetObjectInput,
+  ScopedObjectClient,
+  type ScopedPutObjectInput,
+} from "./object/index.js";

package/src/experimental/object/api.ts

@@ -0,0 +1,91 @@
+import type { Client } from "openapi-fetch";
+import { RenderError } from "../../errors.js";
+import type { paths } from "../../generated/schema.js";
+import type { PresignedDownloadUrl, PresignedUploadUrl, Region } from "./types.js";
+
+/**
+ * Layer 2: Typed Object API Client
+ *
+ * Provides idiomatic TypeScript wrapper around the raw OpenAPI client.
+ * Handles presigned URL flow but still exposes the two-step nature
+ * (get URL, then upload/download). Useful for advanced use cases
+ * requiring fine-grained control.
+ */
+export class ObjectApi {
+  constructor(private readonly apiClient: Client<paths>) {}
+
+  /**
+   * Get a presigned URL for uploading an object
+   *
+   * @param ownerId - Owner ID (workspace team ID)
+   * @param region - Storage region
+   * @param key - Object key (path)
+   * @param sizeBytes - Size of the object in bytes
+   * @returns Presigned upload URL with expiration and size limit
+   */
+  async getUploadUrl(
+    ownerId: string,
+    region: Region | string,
+    key: string,
+    sizeBytes: number,
+  ): Promise<PresignedUploadUrl> {
+    const { data, error } = await this.apiClient.PUT("/blobs/{ownerId}/{region}/{key}", {
+      params: { path: { ownerId, region: region as Region, key } },
+      body: { sizeBytes },
+    });
+
+    if (error) {
+      throw new RenderError(`Failed to get upload URL: ${error.message || "Unknown error"}`);
+    }
+
+    return {
+      url: data.url,
+      expiresAt: new Date(data.expiresAt),
+      maxSizeBytes: data.maxSizeBytes,
+    };
+  }
+
+  /**
+   * Get a presigned URL for downloading an object
+   *
+   * @param ownerId - Owner ID (workspace team ID)
+   * @param region - Storage region
+   * @param key - Object key (path)
+   * @returns Presigned download URL with expiration
+   */
+  async getDownloadUrl(
+    ownerId: string,
+    region: Region | string,
+    key: string,
+  ): Promise<PresignedDownloadUrl> {
+    const { data, error } = await this.apiClient.GET("/blobs/{ownerId}/{region}/{key}", {
+      params: { path: { ownerId, region: region as Region, key } },
+    });
+
+    if (error) {
+      throw new RenderError(`Failed to get download URL: ${error.message || "Unknown error"}`);
+    }
+
+    return {
+      url: data.url,
+      expiresAt: new Date(data.expiresAt),
+    };
+  }
+
+  /**
+   * Delete an object
+   *
+   * @param ownerId - Owner ID (workspace team ID)
+   * @param region - Storage region
+   * @param key - Object key (path)
+   */
+  async delete(ownerId: string, region: Region | string, key: string): Promise<void> {
+    const { error } = await this.apiClient.DELETE("/blobs/{ownerId}/{region}/{key}", {
+      params: { path: { ownerId, region: region as Region, key } },
+    });
+
+    if (error) {
+      throw new RenderError(`Failed to delete object: ${error.message || "Unknown error"}`);
+    }
+  }
+}

package/src/experimental/object/client.test.ts

@@ -0,0 +1,138 @@
+import { Readable } from "node:stream";
+import type { Client } from "openapi-fetch";
+import { RenderError } from "../../errors.js";
+import type { paths } from "../../generated/schema.js";
+import { ObjectClient } from "./client.js";
+import type { PutObjectInput } from "./types.js";
+
+describe("ObjectClient", () => {
+  describe("resolveSize (via put validation)", () => {
+    // Test resolveSize indirectly by calling put() which will fail
+    // at the API call stage, but size validation happens first.
+    const putMock = vi.fn().mockRejectedValue(new Error("should not reach API"));
+    const mockApiClient = { PUT: putMock } as unknown as Client<paths>;
+
+    const client = new ObjectClient(mockApiClient);
+
+    it("auto-calculates Buffer size", async () => {
+      const buffer = Buffer.from("hello");
+      putMock.mockResolvedValueOnce({
+        data: { url: "http://test" },
+        error: null,
+      });
+
+      // Will fail at fetch, but that's after size validation
+      await expect(
+        client.put({
+          ownerId: "tea-test",
+          region: "oregon",
+          key: "test.txt",
+          data: buffer,
+        }),
+      ).rejects.toThrow(); // fetch not available in test
+
+      expect(putMock).toHaveBeenCalledWith(
+        "/blobs/{ownerId}/{region}/{key}",
+        expect.objectContaining({
+          body: { sizeBytes: 5 },
+        }),
+      );
+    });
+
+    it("auto-calculates Uint8Array size", async () => {
+      const arr = new Uint8Array([1, 2, 3, 4]);
+      putMock.mockResolvedValueOnce({
+        data: { url: "http://test" },
+        error: null,
+      });
+
+      await expect(
+        client.put({
+          ownerId: "tea-test",
+          region: "oregon",
+          key: "test.bin",
+          data: arr,
+        }),
+      ).rejects.toThrow();
+
+      expect(putMock).toHaveBeenCalledWith(
+        "/blobs/{ownerId}/{region}/{key}",
+        expect.objectContaining({
+          body: { sizeBytes: 4 },
+        }),
+      );
+    });
+
+    it("throws on size mismatch for Buffer", async () => {
+      const buffer = Buffer.from("hello");
+      await expect(
+        client.put({
+          ownerId: "tea-test",
+          region: "oregon",
+          key: "test.txt",
+          data: buffer,
+          size: 10,
+        }),
+      ).rejects.toThrow(RenderError);
+      await expect(
+        client.put({
+          ownerId: "tea-test",
+          region: "oregon",
+          key: "test.txt",
+          data: buffer,
+          size: 10,
+        }),
+      ).rejects.toThrow("Size mismatch");
+    });
+
+    it("requires size for stream input", async () => {
+      const stream = Readable.from(["hello"]);
+      const invalidInput = {
+        ownerId: "tea-test",
+        region: "oregon",
+        key: "test.txt",
+        data: stream,
+        // Intentionally omit size to test validation (invalid at runtime)
+      } as unknown as PutObjectInput;
+      await expect(client.put(invalidInput)).rejects.toThrow(RenderError);
+      await expect(client.put(invalidInput)).rejects.toThrow("Size is required");
+    });
+
+    it("requires size for string input", async () => {
+      await expect(
+        client.put({
+          ownerId: "tea-test",
+          region: "oregon",
+          key: "test.txt",
+          data: "hello",
+        }),
+      ).rejects.toThrow("Size is required");
+    });
+
+    it("throws on zero size", async () => {
+      const stream = Readable.from(["hello"]);
+      await expect(
+        client.put({
+          ownerId: "tea-test",
+          region: "oregon",
+          key: "test.txt",
+          data: stream,
+          size: 0,
+        }),
+      ).rejects.toThrow("Size must be a positive integer");
+    });
+
+    it("throws on negative size", async () => {
+      const stream = Readable.from(["hello"]);
+      await expect(
+        client.put({
+          ownerId: "tea-test",
+          region: "oregon",
+          key: "test.txt",
+          data: stream,
+          size: -1,
+        }),
+      ).rejects.toThrow("Size must be a positive integer");
+    });
+  });
+});