@renderinc/sdk 0.1.0 → 0.2.0

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,17 @@
 {
   "name": "@renderinc/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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",
+    "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,15 +22,6 @@
   ],
   "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",
@@ -55,11 +46,11 @@
       "import": "./dist/workflows/index.js",
       "require": "./dist/workflows/index.js",
       "types": "./dist/workflows/index.d.ts"
+    },
+    "./experimental": {
+      "import": "./dist/experimental/index.js",
+      "require": "./dist/experimental/index.js",
+      "types": "./dist/experimental/index.d.ts"
     }
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ]
+  }
 }

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/blob/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 Blob 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 BlobApi {
+  constructor(private readonly apiClient: Client<paths>) {}
+
+  /**
+   * Get a presigned URL for uploading a blob
+   *
+   * @param ownerId - Owner ID (workspace team ID)
+   * @param region - Storage region
+   * @param key - Object key (path)
+   * @param sizeBytes - Size of the blob 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 a blob
+   *
+   * @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 a blob
+   *
+   * @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 blob: ${error.message || "Unknown error"}`);
+    }
+  }
+}

package/src/experimental/blob/client.ts

@@ -0,0 +1,317 @@
+import type { Client } from "openapi-fetch";
+import { RenderError } from "../../errors.js";
+import type { paths } from "../../generated/schema.js";
+import type {
+  BlobData,
+  BlobScope,
+  DeleteBlobInput,
+  GetBlobInput,
+  PutBlobInput,
+  PutBlobResult,
+  Region,
+  ScopedDeleteBlobInput,
+  ScopedGetBlobInput,
+  ScopedPutBlobInput,
+} from "./types.js";
+
+/**
+ * Layer 3: High-Level Blob Client
+ *
+ * User-facing API that abstracts presigned URLs completely.
+ * Provides simple put/get/delete operations that handle the
+ * two-step presigned URL flow internally.
+ */
+export class BlobClient {
+  constructor(private readonly apiClient: Client<paths>) {}
+
+  /**
+   * Upload a blob to storage
+   *
+   * @param input - Upload parameters including blob identifier and data
+   * @returns Result with optional ETag
+   *
+   * @example
+   * ```typescript
+   * // Upload a Buffer
+   * const data = Buffer.from("binary content");
+   * await blobClient.put({
+   *   ownerId: "tea-xxxxx",
+   *   region: "oregon",
+   *   key: "path/to/file.png",
+   *   data,
+   *   contentType: "image/png"
+   * });
+   *
+   * // Upload from stream
+   * const stream = createReadStream("/path/to/file.zip");
+   * const stats = statSync("/path/to/file.zip");
+   * await blobClient.put({
+   *   ownerId: "tea-xxxxx",
+   *   region: "oregon",
+   *   key: "file.zip",
+   *   data: stream,
+   *   size: stats.size
+   * });
+   * ```
+   */
+  async put(input: PutBlobInput): Promise<PutBlobResult> {
+    // Resolve and validate size
+    const size = this.resolveSize(input);
+
+    // Step 1: Get presigned upload URL from Render API
+    const { data, error } = await this.apiClient.PUT("/blobs/{ownerId}/{region}/{key}", {
+      params: {
+        path: {
+          ownerId: input.ownerId,
+          region: input.region as Region,
+          key: input.key,
+        },
+      },
+      body: { sizeBytes: size },
+    });
+
+    if (error) {
+      throw new RenderError(`Failed to get upload URL: ${error.message || "Unknown error"}`);
+    }
+
+    // Step 2: Upload to storage via presigned URL
+    const headers: Record<string, string> = {
+      "Content-Length": size.toString(),
+    };
+
+    if (input.contentType) {
+      headers["Content-Type"] = input.contentType;
+    }
+
+    const response = await fetch(data.url, {
+      method: "PUT",
+      headers,
+      body: input.data,
+      duplex: "half",
+    });
+
+    if (!response.ok) {
+      throw new RenderError(`Upload failed: ${response.status} ${response.statusText}`);
+    }
+
+    return {
+      etag: response.headers.get("ETag") ?? undefined,
+    };
+  }
+
+  /**
+   * Download a blob from storage
+   *
+   * @param input - Download parameters including blob identifier
+   * @returns Blob data with content
+   *
+   * @example
+   * ```typescript
+   * const blob = await blobClient.get({
+   *   ownerId: "tea-xxxxx",
+   *   region: "oregon",
+   *   key: "path/to/file.png"
+   * });
+   *
+   * console.log(blob.size);           // Size in bytes
+   * console.log(blob.contentType);    // MIME type if available
+   * // blob.data is a Buffer
+   * ```
+   */
+  async get(input: GetBlobInput): Promise<BlobData> {
+    // Step 1: Get presigned download URL from Render API
+    const { data, error } = await this.apiClient.GET("/blobs/{ownerId}/{region}/{key}", {
+      params: {
+        path: {
+          ownerId: input.ownerId,
+          region: input.region as Region,
+          key: input.key,
+        },
+      },
+    });
+
+    if (error) {
+      throw new RenderError(`Failed to get download URL: ${error.message || "Unknown error"}`);
+    }
+
+    // Step 2: Download from storage via presigned URL
+    const response = await fetch(data.url);
+
+    if (!response.ok) {
+      throw new RenderError(`Download failed: ${response.status} ${response.statusText}`);
+    }
+
+    const arrayBuffer = await response.arrayBuffer();
+    const buffer = Buffer.from(arrayBuffer);
+
+    return {
+      data: buffer,
+      size: buffer.byteLength,
+      contentType: response.headers.get("Content-Type") ?? undefined,
+    };
+  }
+
+  /**
+   * Delete a blob from storage
+   *
+   * @param input - Delete parameters including blob identifier
+   *
+   * @example
+   * ```typescript
+   * await blobClient.delete({
+   *   ownerId: "tea-xxxxx",
+   *   region: "oregon",
+   *   key: "path/to/file.png"
+   * });
+   * ```
+   */
+  async delete(input: DeleteBlobInput): Promise<void> {
+    // DELETE goes directly to Render API (no presigned URL)
+    const { error } = await this.apiClient.DELETE("/blobs/{ownerId}/{region}/{key}", {
+      params: {
+        path: {
+          ownerId: input.ownerId,
+          region: input.region as Region,
+          key: input.key,
+        },
+      },
+    });
+
+    if (error) {
+      throw new RenderError(`Failed to delete blob: ${error.message || "Unknown error"}`);
+    }
+  }
+
+  /**
+   * Create a scoped blob client for a specific owner and region
+   *
+   * @param scope - Owner ID and region to scope operations to
+   * @returns Scoped blob client that doesn't require ownerId/region on each call
+   *
+   * @example
+   * ```typescript
+   * const scoped = blobClient.scoped({
+   *   ownerId: "tea-xxxxx",
+   *   region: "oregon"
+   * });
+   *
+   * // Subsequent calls only need the key
+   * await scoped.put({ key: "file.png", data: buffer });
+   * await scoped.get({ key: "file.png" });
+   * await scoped.delete({ key: "file.png" });
+   * ```
+   */
+  scoped(scope: BlobScope): ScopedBlobClient {
+    return new ScopedBlobClient(this.apiClient, scope);
+  }
+
+  /**
+   * Resolve and validate the size for a put operation
+   *
+   * - For Buffer/Uint8Array: auto-calculate size, validate if provided
+   * - For streams/strings: require explicit size
+   */
+  private resolveSize(input: PutBlobInput): number {
+    if (Buffer.isBuffer(input.data) || input.data instanceof Uint8Array) {
+      const actualSize = input.data.byteLength;
+
+      if (input.size !== undefined && input.size !== actualSize) {
+        throw new RenderError(
+          `Size mismatch: provided size ${input.size} does not match actual size ${actualSize}`,
+        );
+      }
+
+      return actualSize;
+    }
+
+    // For Readable streams or strings, size must be provided
+    if (input.size === undefined) {
+      throw new RenderError(
+        "Size is required for stream and string inputs. Provide the size parameter.",
+      );
+    }
+
+    if (input.size <= 0) {
+      throw new RenderError("Size must be a positive integer");
+    }
+
+    return input.size;
+  }
+}
+
+/**
+ * Scoped Blob Client
+ *
+ * Pre-configured client for a specific owner and region.
+ * Eliminates the need to specify ownerId and region on every operation.
+ */
+export class ScopedBlobClient {
+  private readonly blobClient: BlobClient;
+
+  constructor(
+    apiClient: Client<paths>,
+    private readonly scope: BlobScope,
+  ) {
+    this.blobClient = new BlobClient(apiClient);
+  }
+
+  /**
+   * Upload a blob to storage using scoped owner and region
+   *
+   * @param input - Upload parameters (key and data only)
+   * @returns Result with optional ETag
+   *
+   * @example
+   * ```typescript
+   * const scoped = blobClient.scoped({ ownerId: "tea-xxxxx", region: "oregon" });
+   * await scoped.put({
+   *   key: "file.png",
+   *   data: Buffer.from("content"),
+   *   contentType: "image/png"
+   * });
+   * ```
+   */
+  async put(input: ScopedPutBlobInput): Promise<PutBlobResult> {
+    return this.blobClient.put({
+      ...this.scope,
+      ...input,
+    } as PutBlobInput);
+  }
+
+  /**
+   * Download a blob from storage using scoped owner and region
+   *
+   * @param input - Download parameters (key only)
+   * @returns Blob data with content
+   *
+   * @example
+   * ```typescript
+   * const scoped = blobClient.scoped({ ownerId: "tea-xxxxx", region: "oregon" });
+   * const blob = await scoped.get({ key: "file.png" });
+   * ```
+   */
+  async get(input: ScopedGetBlobInput): Promise<BlobData> {
+    return this.blobClient.get({
+      ...this.scope,
+      ...input,
+    } as GetBlobInput);
+  }
+
+  /**
+   * Delete a blob from storage using scoped owner and region
+   *
+   * @param input - Delete parameters (key only)
+   *
+   * @example
+   * ```typescript
+   * const scoped = blobClient.scoped({ ownerId: "tea-xxxxx", region: "oregon" });
+   * await scoped.delete({ key: "file.png" });
+   * ```
+   */
+  async delete(input: ScopedDeleteBlobInput): Promise<void> {
+    return this.blobClient.delete({
+      ...this.scope,
+      ...input,
+    } as DeleteBlobInput);
+  }
+}

package/src/experimental/blob/index.ts

@@ -0,0 +1,22 @@
+// Blob storage client exports
+export { BlobApi } from "./api.js";
+export { BlobClient, ScopedBlobClient } from "./client.js";
+// Type exports
+export type {
+  BlobData,
+  BlobIdentifier,
+  BlobScope,
+  DeleteBlobInput,
+  GetBlobInput,
+  PresignedDownloadUrl,
+  PresignedUploadUrl,
+  PutBlobInput,
+  PutBlobInputBuffer,
+  PutBlobInputStream,
+  PutBlobResult,
+  ScopedDeleteBlobInput,
+  ScopedGetBlobInput,
+  ScopedPutBlobInput,
+} from "./types.js";
+// Re-export the Region enum (both type and value)
+export { Region } from "./types.js";

package/src/experimental/blob/types.ts

@@ -0,0 +1,131 @@
+import type { Readable } from "node:stream";
+
+/**
+ * Supported regions for blob storage
+ */
+export type Region = "frankfurt" | "oregon" | "ohio" | "singapore" | "virginia";
+
+/**
+ * Base identifier for a blob object
+ */
+export interface BlobIdentifier {
+  /** Owner ID (workspace team ID) in format tea-xxxxx */
+  ownerId: `tea-${string}`;
+  /** Region where the blob is stored */
+  region: Region | string;
+  /** Object key (path) for the blob */
+  key: string;
+}
+
+/**
+ * Base options for putting a blob
+ */
+interface PutBlobInputBase extends BlobIdentifier {
+  /** MIME type of the content (optional, will be auto-detected if not provided) */
+  contentType?: string;
+}
+
+/**
+ * Put blob input for Buffer, Uint8Array, or string data
+ * Size is optional and will be auto-calculated
+ */
+export interface PutBlobInputBuffer extends PutBlobInputBase {
+  /** Binary data as Buffer, Uint8Array, or string */
+  data: Buffer | Uint8Array | string;
+  /** Size in bytes (optional, auto-calculated for Buffer/Uint8Array) */
+  size?: number;
+}
+
+/**
+ * Put blob input for readable streams
+ * Size is required for streams
+ */
+export interface PutBlobInputStream extends PutBlobInputBase {
+  /** Readable stream */
+  data: Readable;
+  /** Size in bytes (required for streams) */
+  size: number;
+}
+
+/**
+ * Input for uploading a blob
+ * Discriminated union: size is optional for Buffer/Uint8Array, required for streams
+ */
+export type PutBlobInput = PutBlobInputBuffer | PutBlobInputStream;
+
+/**
+ * Input for downloading a blob
+ */
+export interface GetBlobInput extends BlobIdentifier {}
+
+/**
+ * Input for deleting a blob
+ */
+export interface DeleteBlobInput extends BlobIdentifier {}
+
+/**
+ * Presigned URL for uploading
+ */
+export interface PresignedUploadUrl {
+  /** Presigned upload URL */
+  url: string;
+  /** Expiration timestamp */
+  expiresAt: Date;
+  /** Maximum size allowed for upload */
+  maxSizeBytes: number;
+}
+
+/**
+ * Presigned URL for downloading
+ */
+export interface PresignedDownloadUrl {
+  /** Presigned download URL */
+  url: string;
+  /** Expiration timestamp */
+  expiresAt: Date;
+}
+
+/**
+ * Downloaded blob data
+ */
+export interface BlobData {
+  /** Binary content */
+  data: Buffer;
+  /** MIME type if available */
+  contentType?: string;
+  /** Size in bytes */
+  size: number;
+}
+
+/**
+ * Result from uploading a blob
+ */
+export interface PutBlobResult {
+  /** ETag from storage provider */
+  etag?: string;
+}
+
+/**
+ * Scope configuration for scoped blob client
+ */
+export interface BlobScope {
+  /** Owner ID (workspace team ID) in format tea-xxxxx */
+  ownerId: `tea-${string}`;
+  /** Region where the blob is stored */
+  region: Region | string;
+}
+
+/**
+ * Scoped input for uploading a blob (without ownerId/region)
+ */
+export type ScopedPutBlobInput = Omit<PutBlobInput, keyof BlobScope>;
+
+/**
+ * Scoped input for downloading a blob (without ownerId/region)
+ */
+export type ScopedGetBlobInput = Omit<GetBlobInput, keyof BlobScope>;
+
+/**
+ * Scoped input for deleting a blob (without ownerId/region)
+ */
+export type ScopedDeleteBlobInput = Omit<DeleteBlobInput, keyof BlobScope>;