@renderinc/sdk 0.1.0 → 0.2.1

package/src/experimental/object/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 {
+  DeleteObjectInput,
+  GetObjectInput,
+  ObjectData,
+  ObjectScope,
+  PutObjectInput,
+  PutObjectResult,
+  Region,
+  ScopedDeleteObjectInput,
+  ScopedGetObjectInput,
+  ScopedPutObjectInput,
+} from "./types.js";
+
+/**
+ * Layer 3: High-Level Object 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 ObjectClient {
+  constructor(private readonly apiClient: Client<paths>) {}
+
+  /**
+   * Upload an object to storage
+   *
+   * @param input - Upload parameters including object identifier and data
+   * @returns Result with optional ETag
+   *
+   * @example
+   * ```typescript
+   * // Upload a Buffer
+   * const data = Buffer.from("binary content");
+   * await objectClient.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 objectClient.put({
+   *   ownerId: "tea-xxxxx",
+   *   region: "oregon",
+   *   key: "file.zip",
+   *   data: stream,
+   *   size: stats.size
+   * });
+   * ```
+   */
+  async put(input: PutObjectInput): Promise<PutObjectResult> {
+    // 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 an object from storage
+   *
+   * @param input - Download parameters including object identifier
+   * @returns Object data with content
+   *
+   * @example
+   * ```typescript
+   * const obj = await objectClient.get({
+   *   ownerId: "tea-xxxxx",
+   *   region: "oregon",
+   *   key: "path/to/file.png"
+   * });
+   *
+   * console.log(obj.size);           // Size in bytes
+   * console.log(obj.contentType);    // MIME type if available
+   * // obj.data is a Buffer
+   * ```
+   */
+  async get(input: GetObjectInput): Promise<ObjectData> {
+    // 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 an object from storage
+   *
+   * @param input - Delete parameters including object identifier
+   *
+   * @example
+   * ```typescript
+   * await objectClient.delete({
+   *   ownerId: "tea-xxxxx",
+   *   region: "oregon",
+   *   key: "path/to/file.png"
+   * });
+   * ```
+   */
+  async delete(input: DeleteObjectInput): 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 object: ${error.message || "Unknown error"}`);
+    }
+  }
+
+  /**
+   * Create a scoped object client for a specific owner and region
+   *
+   * @param scope - Owner ID and region to scope operations to
+   * @returns Scoped object client that doesn't require ownerId/region on each call
+   *
+   * @example
+   * ```typescript
+   * const scoped = objectClient.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: ObjectScope): ScopedObjectClient {
+    return new ScopedObjectClient(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: PutObjectInput): 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 Object Client
+ *
+ * Pre-configured client for a specific owner and region.
+ * Eliminates the need to specify ownerId and region on every operation.
+ */
+export class ScopedObjectClient {
+  private readonly objectClient: ObjectClient;
+
+  constructor(
+    apiClient: Client<paths>,
+    private readonly scope: ObjectScope,
+  ) {
+    this.objectClient = new ObjectClient(apiClient);
+  }
+
+  /**
+   * Upload an object to storage using scoped owner and region
+   *
+   * @param input - Upload parameters (key and data only)
+   * @returns Result with optional ETag
+   *
+   * @example
+   * ```typescript
+   * const scoped = objectClient.scoped({ ownerId: "tea-xxxxx", region: "oregon" });
+   * await scoped.put({
+   *   key: "file.png",
+   *   data: Buffer.from("content"),
+   *   contentType: "image/png"
+   * });
+   * ```
+   */
+  async put(input: ScopedPutObjectInput): Promise<PutObjectResult> {
+    return this.objectClient.put({
+      ...this.scope,
+      ...input,
+    } as PutObjectInput);
+  }
+
+  /**
+   * Download an object from storage using scoped owner and region
+   *
+   * @param input - Download parameters (key only)
+   * @returns Object data with content
+   *
+   * @example
+   * ```typescript
+   * const scoped = objectClient.scoped({ ownerId: "tea-xxxxx", region: "oregon" });
+   * const obj = await scoped.get({ key: "file.png" });
+   * ```
+   */
+  async get(input: ScopedGetObjectInput): Promise<ObjectData> {
+    return this.objectClient.get({
+      ...this.scope,
+      ...input,
+    } as GetObjectInput);
+  }
+
+  /**
+   * Delete an object from storage using scoped owner and region
+   *
+   * @param input - Delete parameters (key only)
+   *
+   * @example
+   * ```typescript
+   * const scoped = objectClient.scoped({ ownerId: "tea-xxxxx", region: "oregon" });
+   * await scoped.delete({ key: "file.png" });
+   * ```
+   */
+  async delete(input: ScopedDeleteObjectInput): Promise<void> {
+    return this.objectClient.delete({
+      ...this.scope,
+      ...input,
+    } as DeleteObjectInput);
+  }
+}

package/src/experimental/object/index.ts

@@ -0,0 +1,22 @@
+// Object storage client exports
+export { ObjectApi } from "./api.js";
+export { ObjectClient, ScopedObjectClient } from "./client.js";
+// Type exports
+export type {
+  DeleteObjectInput,
+  GetObjectInput,
+  ObjectData,
+  ObjectIdentifier,
+  ObjectScope,
+  PresignedDownloadUrl,
+  PresignedUploadUrl,
+  PutObjectInput,
+  PutObjectInputBuffer,
+  PutObjectInputStream,
+  PutObjectResult,
+  ScopedDeleteObjectInput,
+  ScopedGetObjectInput,
+  ScopedPutObjectInput,
+} from "./types.js";
+// Re-export the Region enum (both type and value)
+export { Region } from "./types.js";

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

@@ -0,0 +1,87 @@
+import type { Readable } from "node:stream";
+import type {
+  DeleteObjectInput,
+  GetObjectInput,
+  ObjectIdentifier,
+  ObjectScope,
+  PutObjectInput,
+  PutObjectInputBuffer,
+  PutObjectInputStream,
+  ScopedDeleteObjectInput,
+  ScopedGetObjectInput,
+  ScopedPutObjectInput,
+} from "./types.js";
+
+describe("PutObjectInput discriminated union", () => {
+  it("accepts buffer variant", () => {
+    const input: PutObjectInput = {
+      ownerId: "tea-123",
+      region: "frankfurt",
+      key: "test.txt",
+      data: Buffer.from("hello"),
+    };
+    expectTypeOf(input).toMatchTypeOf<PutObjectInput>();
+  });
+
+  it("accepts stream variant with required size", () => {
+    const input: PutObjectInput = {
+      ownerId: "tea-123",
+      region: "frankfurt",
+      key: "test.txt",
+      data: {} as Readable,
+      size: 100,
+    };
+    expectTypeOf(input).toMatchTypeOf<PutObjectInput>();
+  });
+
+  it("union includes both variants", () => {
+    expectTypeOf<PutObjectInput>().toMatchTypeOf<PutObjectInputBuffer | PutObjectInputStream>();
+  });
+});
+
+describe("ObjectIdentifier type", () => {
+  it("requires tea- prefix on ownerId", () => {
+    expectTypeOf<ObjectIdentifier["ownerId"]>().toEqualTypeOf<`tea-${string}`>();
+  });
+
+  it("has required key property", () => {
+    expectTypeOf<ObjectIdentifier>().toHaveProperty("key");
+    expectTypeOf<ObjectIdentifier["key"]>().toEqualTypeOf<string>();
+  });
+});
+
+describe("Scoped types omit ObjectScope fields", () => {
+  it("ScopedPutObjectInput omits ownerId and region", () => {
+    expectTypeOf<ScopedPutObjectInput>().not.toHaveProperty("ownerId");
+    expectTypeOf<ScopedPutObjectInput>().not.toHaveProperty("region");
+    expectTypeOf<ScopedPutObjectInput>().toHaveProperty("key");
+    expectTypeOf<ScopedPutObjectInput>().toHaveProperty("data");
+  });
+
+  it("ScopedGetObjectInput omits ownerId and region", () => {
+    expectTypeOf<ScopedGetObjectInput>().not.toHaveProperty("ownerId");
+    expectTypeOf<ScopedGetObjectInput>().not.toHaveProperty("region");
+    expectTypeOf<ScopedGetObjectInput>().toHaveProperty("key");
+  });
+
+  it("ScopedDeleteObjectInput omits ownerId and region", () => {
+    expectTypeOf<ScopedDeleteObjectInput>().not.toHaveProperty("ownerId");
+    expectTypeOf<ScopedDeleteObjectInput>().not.toHaveProperty("region");
+    expectTypeOf<ScopedDeleteObjectInput>().toHaveProperty("key");
+  });
+
+  it("ObjectScope has ownerId and region", () => {
+    expectTypeOf<ObjectScope>().toHaveProperty("ownerId");
+    expectTypeOf<ObjectScope>().toHaveProperty("region");
+  });
+});
+
+describe("GetObjectInput and DeleteObjectInput extend ObjectIdentifier", () => {
+  it("GetObjectInput matches ObjectIdentifier", () => {
+    expectTypeOf<GetObjectInput>().toMatchTypeOf<ObjectIdentifier>();
+  });
+
+  it("DeleteObjectInput matches ObjectIdentifier", () => {
+    expectTypeOf<DeleteObjectInput>().toMatchTypeOf<ObjectIdentifier>();
+  });
+});

package/src/experimental/object/types.ts

@@ -0,0 +1,131 @@
+import type { Readable } from "node:stream";
+
+/**
+ * Supported regions for object storage
+ */
+export type Region = "frankfurt" | "oregon" | "ohio" | "singapore" | "virginia";
+
+/**
+ * Base identifier for a storage object
+ */
+export interface ObjectIdentifier {
+  /** Owner ID (workspace team ID) in format tea-xxxxx */
+  ownerId: `tea-${string}`;
+  /** Region where the object is stored */
+  region: Region | string;
+  /** Object key (path) for the object */
+  key: string;
+}
+
+/**
+ * Base options for putting an object
+ */
+interface PutObjectInputBase extends ObjectIdentifier {
+  /** MIME type of the content (optional, will be auto-detected if not provided) */
+  contentType?: string;
+}
+
+/**
+ * Put object input for Buffer, Uint8Array, or string data
+ * Size is optional and will be auto-calculated
+ */
+export interface PutObjectInputBuffer extends PutObjectInputBase {
+  /** Binary data as Buffer, Uint8Array, or string */
+  data: Buffer | Uint8Array | string;
+  /** Size in bytes (optional, auto-calculated for Buffer/Uint8Array) */
+  size?: number;
+}
+
+/**
+ * Put object input for readable streams
+ * Size is required for streams
+ */
+export interface PutObjectInputStream extends PutObjectInputBase {
+  /** Readable stream */
+  data: Readable;
+  /** Size in bytes (required for streams) */
+  size: number;
+}
+
+/**
+ * Input for uploading an object
+ * Discriminated union: size is optional for Buffer/Uint8Array, required for streams
+ */
+export type PutObjectInput = PutObjectInputBuffer | PutObjectInputStream;
+
+/**
+ * Input for downloading an object
+ */
+export interface GetObjectInput extends ObjectIdentifier {}
+
+/**
+ * Input for deleting an object
+ */
+export interface DeleteObjectInput extends ObjectIdentifier {}
+
+/**
+ * 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 object data
+ */
+export interface ObjectData {
+  /** Binary content */
+  data: Buffer;
+  /** MIME type if available */
+  contentType?: string;
+  /** Size in bytes */
+  size: number;
+}
+
+/**
+ * Result from uploading an object
+ */
+export interface PutObjectResult {
+  /** ETag from storage provider */
+  etag?: string;
+}
+
+/**
+ * Scope configuration for scoped object client
+ */
+export interface ObjectScope {
+  /** Owner ID (workspace team ID) in format tea-xxxxx */
+  ownerId: `tea-${string}`;
+  /** Region where the object is stored */
+  region: Region | string;
+}
+
+/**
+ * Scoped input for uploading an object (without ownerId/region)
+ */
+export type ScopedPutObjectInput = Omit<PutObjectInput, keyof ObjectScope>;
+
+/**
+ * Scoped input for downloading an object (without ownerId/region)
+ */
+export type ScopedGetObjectInput = Omit<GetObjectInput, keyof ObjectScope>;
+
+/**
+ * Scoped input for deleting an object (without ownerId/region)
+ */
+export type ScopedDeleteObjectInput = Omit<DeleteObjectInput, keyof ObjectScope>;