@renderinc/sdk 0.2.0 → 0.2.1

package/src/generated/schema.ts

@@ -27,6 +27,28 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/blueprints/validate": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Validate Blueprint
+         * @description Validate a `render.yaml` Blueprint file without creating or modifying any resources. This endpoint checks the syntax and structure of the Blueprint, validates that all required fields are present, and returns a plan indicating the resources that would be created.
+         *
+         *     Requests to this endpoint use `Content-Type: multipart/form-data`. The provided Blueprint file cannot exceed 10MB in size.
+         */
+        post: operations["validate-blueprint"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/owners/{ownerId}/members/{userId}": {
         parameters: {
             query?: never;
@@ -512,7 +534,7 @@ export interface paths {
         put?: never;
         /**
          * Create service
-         * @description Create a service.
+         * @description Creates a new Render service in the specified workspace with the specified configuration.
          */
         post: operations["create-service"];
         delete?: never;
@@ -3262,6 +3284,31 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/blobs/{ownerId}/{region}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description The ID of the workspace to return resources for */
+                ownerId: components["parameters"]["ownerIdPathParam"];
+                /** @description The region to return resources for */
+                region: components["parameters"]["regionPathParam"];
+            };
+            cookie?: never;
+        };
+        /**
+         * List blobs
+         * @description List blobs in the specified region for a workspace.
+         */
+        get: operations["list-blobs"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/blobs/{ownerId}/{region}/{key}": {
         parameters: {
             query?: never;
@@ -3603,23 +3650,25 @@ export interface components {
         };
         servicePOST: {
             type: components["schemas"]["serviceType"];
+            /** @description The service's name. Must be unique within the workspace. */
             name: string;
+            /** @description The ID of the workspace the service belongs to. Obtain your workspace's ID from its Settings page in the Render Dashboard. */
             ownerId: string;
             /**
-             * @description Do not include the branch in the repo string. You can instead supply a 'branch' parameter.
+             * @description The service's repository URL. Do not specify a branch in this string (use the `branch` parameter instead).
              * @example https://github.com/render-examples/flask-hello-world
              */
             repo?: string;
             autoDeploy?: components["schemas"]["autoDeploy"];
             autoDeployTrigger?: components["schemas"]["autoDeployTrigger"];
-            /** @description If left empty, this will fall back to the default branch of the repository */
+            /** @description The repo branch to pull, build, and deploy. If omitted, uses the repository's default branch. */
             branch?: string;
             image?: components["schemas"]["image"];
             buildFilter?: components["schemas"]["buildFilter"];
             rootDir?: string;
             envVars?: components["schemas"]["envVarInputArray"];
             secretFiles?: components["schemas"]["secretFileInput"][];
-            /** @description The ID of the environment the service is associated with */
+            /** @description The ID of the environment the service belongs to, if any. Obtain an environment's ID from its Settings page in the Render Dashboard. */
             environmentId?: string;
             serviceDetails?: components["schemas"]["staticSiteDetailsPOST"] | components["schemas"]["webServiceDetailsPOST"] | components["schemas"]["privateServiceDetailsPOST"] | components["schemas"]["backgroundWorkerDetailsPOST"] | components["schemas"]["cronJobDetailsPOST"];
         };
@@ -3656,7 +3705,11 @@ export interface components {
             maintenanceMode?: components["schemas"]["maintenanceMode"];
             /** @description Defaults to 1 */
             numInstances?: number;
-            plan?: components["schemas"]["paidPlan"];
+            /**
+             * @description The instance type to use. If omitted, defaults to `starter` when creating a new service.
+             * @default starter
+             */
+            plan: components["schemas"]["plan"];
             preDeployCommand?: string;
             pullRequestPreviewsEnabled?: components["schemas"]["pullRequestPreviewsEnabled"];
             previews?: components["schemas"]["previews"];
@@ -3742,7 +3795,7 @@ export interface components {
             envSpecificDetails?: components["schemas"]["envSpecificDetailsPATCH"];
             healthCheckPath?: string;
             maintenanceMode?: components["schemas"]["maintenanceMode"];
-            plan?: components["schemas"]["paidPlan"];
+            plan?: components["schemas"]["plan"];
             preDeployCommand?: string;
             pullRequestPreviewsEnabled?: components["schemas"]["pullRequestPreviewsEnabled"];
             previews?: components["schemas"]["previews"];
@@ -3807,7 +3860,7 @@ export interface components {
             plan?: components["schemas"]["plan"];
         };
         /**
-         * @description The instance type to use for the preview instance. Note that base services with any paid instance type can't create preview instances with the `free` instance type.
+         * @description The instance type to use. Note that base services on any paid instance type can't create preview instances with the `free` instance type.
          * @example starter
          * @enum {string}
          */
@@ -4250,6 +4303,18 @@ export interface components {
         redisPlan: "free" | "starter" | "standard" | "pro" | "pro_plus" | "custom";
         /** @enum {string} */
         databaseStatus: "creating" | "available" | "unavailable" | "config_restart" | "suspended" | "maintenance_scheduled" | "maintenance_in_progress" | "recovery_failed" | "recovery_in_progress" | "unknown" | "updating_instance";
+        /**
+         * @description Controls deployment behavior when triggering a deploy.
+         *
+         *     - `deploy_only`: Deploy the last successful build without rebuilding (minimizes downtime)
+         *     - `build_and_deploy`: Build new code and deploy it (default behavior when not specified)
+         *
+         *     **Note:** `deploy_only` cannot be combined with `commitId`, `imageUrl` or `clearCache` parameters,
+         *     as those are build related fields.
+         * @default build_and_deploy
+         * @enum {string}
+         */
+        DeployMode: "deploy_only" | "build_and_deploy";
         projectWithCursor: {
             project: components["schemas"]["project"];
             cursor: components["schemas"]["cursor"];
@@ -4526,7 +4591,7 @@ export interface components {
         /** @enum {string} */
         databaseRole: "primary" | "replica";
         /**
-         * @description Defaults to "starter"
+         * @description Defaults to `starter` when creating a new database.
          * @default starter
          * @enum {string}
          */
@@ -4603,6 +4668,48 @@ export interface components {
             /** Format: date-time */
             lastSync?: string;
         };
+        validateBlueprintRequest: {
+            /**
+             * @description The ID of the workspace to validate against. Obtain your workspace ID from its Settings page in the Render Dashboard.
+             * @example tea-cjnxpkdhshc73d12t9i0
+             */
+            ownerId: string;
+            /**
+             * Format: binary
+             * @description The render.yaml file to validate, as a binary file.
+             */
+            file: string;
+        };
+        validationError: {
+            /** @description The path to the field with the error (e.g., `services[0].plan`) */
+            path?: string;
+            /** @description The error message */
+            error: string;
+            /** @description The line number in the YAML file (1-indexed) */
+            line?: number;
+            /** @description The column number in the YAML file (1-indexed) */
+            column?: number;
+        };
+        validationPlanSummary: {
+            /** @description The names of services that would be created as part of the Blueprint. */
+            services?: string[];
+            /** @description The names of Render Postgres databases that would be created as part of the Blueprint. */
+            databases?: string[];
+            /** @description The names of Render Key Value instances that would be created as part of the Blueprint. */
+            keyValue?: string[];
+            /** @description The names of environment groups that would be created as part of the Blueprint. */
+            envGroups?: string[];
+            /** @description The total number of actions that would be performed by the Blueprint. In addition to created resources, this includes modifications to individual configuration fields. */
+            totalActions?: number;
+        };
+        validateBlueprintResponse: {
+            /** @description If `true`, the Blueprint validated successfully. If `false`, at least one validation error occurred. */
+            valid: boolean;
+            /** @description A list of validation errors. Only present if `valid` is `false`. */
+            errors?: components["schemas"]["validationError"][];
+            /** @description A summary of the resources that would be created as part of the Blueprint. Only present if `valid` is `true`. */
+            plan?: components["schemas"]["validationPlanSummary"];
+        };
         resourceRef: {
             id: string;
             name: string;
@@ -5182,7 +5289,7 @@ export interface components {
          * @description Provider to send metrics to
          * @enum {string}
          */
-        otelProviderType: "BETTER_STACK" | "GRAFANA" | "DATADOG" | "NEW_RELIC" | "HONEYCOMB" | "SIGNOZ" | "CUSTOM";
+        otelProviderType: "BETTER_STACK" | "GRAFANA" | "DATADOG" | "NEW_RELIC" | "HONEYCOMB" | "SIGNOZ" | "GROUNDSOURCE" | "CUSTOM";
         metricsStream: {
             /** @description The ID of the owner */
             ownerId: string;
@@ -5493,6 +5600,34 @@ export interface components {
             retries: number;
             attempts: components["schemas"]["TaskAttemptDetails"][];
         };
+        blobMetadata: {
+            /**
+             * @description The blob's object key
+             * @example workflow-data/task-output.json
+             */
+            key: string;
+            /**
+             * Format: int64
+             * @description Size of the blob in bytes
+             * @example 1048576
+             */
+            sizeBytes: number;
+            /**
+             * Format: date-time
+             * @description When the blob was last modified (ISO 8601)
+             * @example 2026-01-15T12:30:00Z
+             */
+            lastModified: string;
+            /**
+             * @description MIME type of the blob
+             * @example application/json
+             */
+            contentType: string;
+        };
+        blobWithCursor: {
+            cursor: string;
+            blob: components["schemas"]["blobMetadata"];
+        };
         getBlobOutput: {
             /**
              * Format: uri
@@ -5984,6 +6119,35 @@ export interface operations {
             503: components["responses"]["503ServiceUnavailable"];
         };
     };
+    "validate-blueprint": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "multipart/form-data": components["schemas"]["validateBlueprintRequest"];
+            };
+        };
+        responses: {
+            /** @description Validation complete */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["validateBlueprintResponse"];
+                };
+            };
+            400: components["responses"]["400BadRequest"];
+            401: components["responses"]["401Unauthorized"];
+            403: components["responses"]["403Forbidden"];
+            429: components["responses"]["429RateLimit"];
+            500: components["responses"]["500InternalServerError"];
+        };
+    };
     "remove-workspace-member": {
         parameters: {
             query?: never;
@@ -7357,6 +7521,14 @@ export interface operations {
                      *     The host, repository, and image name all must match the currently configured image for the service.
                      */
                     imageUrl?: string;
+                    /**
+                     * @description Deployment mode controlling build and deploy behavior.
+                     *
+                     *     Defaults to `build_and_deploy` when not specified.
+                     *
+                     *     **Validation:** `deploy_mode` cannot be combined with `commitId` or `imageUrl` or `clearCache`.
+                     */
+                    deployMode?: components["schemas"]["DeployMode"];
                 };
             };
         };
@@ -12619,6 +12791,42 @@ export interface operations {
             503: components["responses"]["503ServiceUnavailable"];
         };
     };
+    "list-blobs": {
+        parameters: {
+            query?: {
+                /** @description The position in the result list to start from when fetching paginated results. For details, see [Pagination](https://api-docs.render.com/reference/pagination). */
+                cursor?: components["parameters"]["cursorParam"];
+                /** @description The maximum number of items to return. For details, see [Pagination](https://api-docs.render.com/reference/pagination). */
+                limit?: components["parameters"]["limitParam"];
+            };
+            header?: never;
+            path: {
+                /** @description The ID of the workspace to return resources for */
+                ownerId: components["parameters"]["ownerIdPathParam"];
+                /** @description The region to return resources for */
+                region: components["parameters"]["regionPathParam"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["blobWithCursor"][];
+                };
+            };
+            401: components["responses"]["401Unauthorized"];
+            403: components["responses"]["403Forbidden"];
+            404: components["responses"]["404NotFound"];
+            429: components["responses"]["429RateLimit"];
+            500: components["responses"]["500InternalServerError"];
+            503: components["responses"]["503ServiceUnavailable"];
+        };
+    };
     "get-blob": {
         parameters: {
             query?: never;

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

@@ -0,0 +1,58 @@
+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/workflows/client/client.test.ts

@@ -0,0 +1,68 @@
+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/types.test.ts

@@ -0,0 +1,52 @@
+import type { TaskContext, TaskFunction, TaskResult } from "./types.js";
+
+describe("TaskFunction type", () => {
+  it("accepts typed args and returns typed result", () => {
+    expectTypeOf<TaskFunction<[string, number], boolean>>().toExtend<
+      (a: string, b: number) => boolean | Promise<boolean>
+    >();
+  });
+
+  it("defaults to any[] args and any result", () => {
+    expectTypeOf<TaskFunction>().toExtend<(...args: any[]) => any>();
+  });
+
+  it("allows async return type", () => {
+    const asyncFn: TaskFunction<[string], number> = async (s) => s.length;
+    expectTypeOf(asyncFn).returns.toExtend<number | Promise<number>>();
+  });
+
+  it("allows sync return type", () => {
+    const syncFn: TaskFunction<[string], number> = (s) => s.length;
+    expectTypeOf(syncFn).returns.toExtend<number | Promise<number>>();
+  });
+});
+
+describe("TaskResult type", () => {
+  it("get() returns Promise<T>", () => {
+    expectTypeOf<TaskResult<string>>().toHaveProperty("get");
+    expectTypeOf<TaskResult<string>["get"]>().returns.toEqualTypeOf<Promise<string>>();
+  });
+
+  it("preserves generic parameter", () => {
+    type NumberResult = TaskResult<number>;
+    type StringResult = TaskResult<string>;
+    expectTypeOf<NumberResult["get"]>().returns.toEqualTypeOf<Promise<number>>();
+    expectTypeOf<StringResult["get"]>().returns.toEqualTypeOf<Promise<string>>();
+  });
+});
+
+describe("TaskContext type", () => {
+  it("has executeTask method", () => {
+    expectTypeOf<TaskContext>().toHaveProperty("executeTask");
+  });
+
+  it("executeTask is callable", () => {
+    type ExecuteTask = TaskContext["executeTask"];
+    expectTypeOf<ExecuteTask>().toBeCallableWith(
+      {} as TaskFunction<[string], number>,
+      "taskName",
+      "arg",
+    );
+  });
+});

package/src/workflows/uds.ts

@@ -1,8 +1,6 @@
-import { createConnection } from "node:net";
+import http from "node:http";
 import { getUserAgent } from "../version.js";
 
-const CONTENT_LENGTH_REGEX = /Content-Length:\s*(\d+)/i;
-
 import type {
   CallbackRequest,
   GetInputResponse,
@@ -97,83 +95,45 @@ export class UDSClient {
    */
   private async request<T>(path: string, method: string, body?: any): Promise<T> {
     return new Promise((resolve, reject) => {
-      const client = createConnection({ path: this.socketPath }, () => {
-        const bodyStr = body ? JSON.stringify(body) : "";
-        const userAgent = getUserAgent();
-        const request = `${method} ${path} HTTP/1.1\r\nHost: unix\r\nContent-Length: ${bodyStr.length}\r\nContent-Type: application/json\r\nUser-Agent: ${userAgent}\r\n\r\n${bodyStr}`;
-        client.write(request);
-      });
-
-      let data = "";
-      let contentLength: number | null = null;
-      let headersParsed = false;
-      let bodyStartIndex = -1;
-
-      client.on("data", (chunk) => {
-        data += chunk.toString();
-
-        // Check if we have received the full response
-        if (!headersParsed) {
-          const headerEndIndex = data.indexOf("\r\n\r\n");
-          if (headerEndIndex !== -1) {
-            headersParsed = true;
-            bodyStartIndex = headerEndIndex + 4;
-
-            // Parse Content-Length header
-            const headers = data.substring(0, headerEndIndex);
-            const contentLengthMatch = headers.match(CONTENT_LENGTH_REGEX);
-            if (contentLengthMatch) {
-              contentLength = Number.parseInt(contentLengthMatch[1], 10);
-            }
-          }
-        }
-
-        // Check if we have received the complete body
-        if (headersParsed && contentLength !== null) {
-          const bodyReceived = data.length - bodyStartIndex;
-          if (bodyReceived >= contentLength) {
-            // We have the complete response, close the connection
-            client.end();
-          }
-        }
-      });
-
-      client.on("end", () => {
-        try {
-          // Parse HTTP response
-          const lines = data.split("\r\n");
-          const statusLine = lines[0];
-          const statusCode = Number.parseInt(statusLine.split(" ")[1], 10);
+      const req = http.request(
+        {
+          socketPath: this.socketPath,
+          path: path,
+          method: method,
+          headers: {
+            "Content-Length": body ? JSON.stringify(body).length : 0,
+            "Content-Type": "application/json",
+            "User-Agent": getUserAgent(),
+          },
+        },
+        async (res) => {
+          const chunks: Buffer[] = [];
+          for await (const chunk of res) chunks.push(chunk);
+          const responseBody = Buffer.concat(chunks).toString();
 
-          if (statusCode >= 400) {
-            reject(new Error(`HTTP ${statusCode}: ${data}`));
+          if (res.statusCode && res.statusCode >= 400) {
+            reject(new Error(`HTTP ${res.statusCode}: ${responseBody}`));
             return;
           }
 
-          // Find empty line (separates headers from body)
-          const emptyLineIndex = lines.indexOf("");
-          if (emptyLineIndex === -1) {
+          if (responseBody.length === 0) {
             resolve(undefined as T);
             return;
           }
 
-          const bodyLines = lines.slice(emptyLineIndex + 1);
-          const responseBody = bodyLines.join("\r\n").trim();
-
-          if (!responseBody) {
-            resolve(undefined as T);
-            return;
+          try {
+            resolve(JSON.parse(responseBody));
+          } catch (error) {
+            reject(error);
           }
-
-          resolve(JSON.parse(responseBody));
-        } catch (error) {
-          reject(error);
-        }
-      });
-
-      client.on("error", (error) => {
+        },
+      );
+      req.on("error", (error) => {
         reject(error);
       });
+
+      // Write the body to the request
+      req.end(body ? JSON.stringify(body) : "");
     });
   }
 }

package/tsconfig.json

@@ -16,7 +16,7 @@
     "resolveJsonModule": true,
     "experimentalDecorators": true,
     "emitDecoratorMetadata": true,
-    "types": ["vitest/globals"]
+    "types": ["node", "vitest/globals"]
   },
   "include": ["src/**/*"],
   "exclude": ["node_modules", "dist"]

package/{vite.config.ts → vitest.config.ts}

@@ -2,6 +2,7 @@ import { defineConfig } from "vitest/config";
 
 export default defineConfig({
   test: {
+    include: ["src/**/*.test.ts"],
     globals: true,
   },
 });