feat: Update SDK to match OpenAPI v1.9.0 spec

- Rename `language` to `runtime` with new SandboxRuntime type
- Add `base64Encoded` optional field to files with camelCase-to-snake_case transform
- Flatten error response structure (remove nested `error` wrapper)
- Add new error codes (INVALID_REQUEST_BODY, EXECUTION_TIMEOUT, etc.)
- Change exitCode from nullable to non-nullable
- Update SandboxStageStatus values (SUCCESS→OK, remove RUNTIME_ERROR/ERROR_LIMIT_EXCEEDED)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: koki-develop

typescript/CLAUDE.md

@@ -47,8 +47,8 @@ bun test   # run all tests via vitest
 
 Three source files:
 
-- **`src/client.ts`** — `CodizeClient` class. Takes `{ apiKey, fetchFn? }`. Makes `POST https://codize.dev/api/v1/sandbox/execute` with Bearer auth. Returns `SandboxExecuteResponse` containing `data.compile` (nullable) and `data.run` (nullable) stage results plus `headers`.
-- **`src/error.ts`** — `CodizeApiError` class. Thrown on non-2xx responses. Parses error body using valibot's `apiErrorResponseSchema`. Exposes `.code`, `.status`, `.headers`, `.errors`.
+- **`src/client.ts`** — `CodizeClient` class. Takes `{ apiKey, fetchFn? }`. Makes `POST https://codize.dev/api/v1/sandbox/execute` with Bearer auth. Transforms request (camelCase `base64Encoded` → snake_case `base64_encoded`). Returns `SandboxExecuteResponse` containing `data.compile` (nullable) and `data.run` (nullable) stage results plus `headers`.
+- **`src/error.ts`** — `CodizeApiError` class. Thrown on non-2xx responses with a flat `{ code, message, errors? }` JSON body. Parses error body using valibot's `apiErrorResponseSchema`. Exposes `.code`, `.status`, `.headers`, `.errors`.
 - **`src/index.ts`** — Barrel file re-exporting all public types and classes from `client.ts` and `error.ts`.
 
 ## Key Dependencies

typescript/src/client.spec.ts

@@ -20,16 +20,16 @@ const makeTextResponse = (body: string, status: number): Response =>
   new Response(body, { status });
 
 const sampleRunResult = {
-  stdout: "Hello\n",
+  stdout: "SGVsbG8K",
   stderr: "",
-  output: "Hello\n",
+  output: "SGVsbG8K",
   exit_code: 0,
   signal: null,
-  status: "SUCCESS",
+  status: "OK",
 };
 
 const sampleRequest = {
-  language: "python" as const,
+  runtime: "python" as const,
   files: [{ name: "main.py", content: 'print("Hello")' }],
 };
 
@@ -108,7 +108,48 @@ describe("CodizeClient", () => {
         await client.sandbox.execute(sampleRequest);
 
         const init = fetchFn.mock.calls[0]![1] as RequestInit;
-        expect(JSON.parse(init.body as string)).toEqual(sampleRequest);
+        expect(JSON.parse(init.body as string)).toEqual({
+          runtime: "python",
+          files: [{ name: "main.py", content: 'print("Hello")', base64_encoded: false }],
+        });
+      });
+
+      it("sends base64_encoded flag when specified", async () => {
+        const fetchFn = vi.fn().mockResolvedValue(
+          makeJsonResponse({ compile: null, run: sampleRunResult }),
+        );
+        const client = new CodizeClient({ apiKey: "key", fetchFn });
+        await client.sandbox.execute({
+          runtime: "python",
+          files: [{ name: "data.bin", content: "aGVsbG8=", base64Encoded: true }],
+        });
+
+        const init = fetchFn.mock.calls[0]![1] as RequestInit;
+        const body = JSON.parse(init.body as string);
+        expect(body.files[0].base64_encoded).toBe(true);
+      });
+
+      it("handles mixed base64Encoded values across multiple files", async () => {
+        const fetchFn = vi.fn().mockResolvedValue(
+          makeJsonResponse({ compile: null, run: sampleRunResult }),
+        );
+        const client = new CodizeClient({ apiKey: "key", fetchFn });
+        await client.sandbox.execute({
+          runtime: "python",
+          files: [
+            { name: "main.py", content: 'print("Hello")' },
+            { name: "data.bin", content: "aGVsbG8=", base64Encoded: true },
+            { name: "config.json", content: '{}', base64Encoded: false },
+          ],
+        });
+
+        const init = fetchFn.mock.calls[0]![1] as RequestInit;
+        const body = JSON.parse(init.body as string);
+        expect(body.files).toEqual([
+          { name: "main.py", content: 'print("Hello")', base64_encoded: false },
+          { name: "data.bin", content: "aGVsbG8=", base64_encoded: true },
+          { name: "config.json", content: '{}', base64_encoded: false },
+        ]);
       });
     });
 
@@ -123,9 +164,9 @@ describe("CodizeClient", () => {
             output: "",
             exit_code: 0,
             signal: null,
-            status: "SUCCESS",
+            status: "OK",
           },
-          run: { stdout: "ok\n", stderr: "", output: "ok\n", exit_code: 0, signal: null, status: "SUCCESS" },
+          run: { stdout: "b2sK", stderr: "", output: "b2sK", exit_code: 0, signal: null, status: "OK" },
         };
         const fetchFn = vi.fn().mockResolvedValue(makeJsonResponse(body));
         const client = new CodizeClient({ apiKey: "key", fetchFn });
@@ -137,22 +178,22 @@ describe("CodizeClient", () => {
           output: "",
           exitCode: 0,
           signal: null,
-          status: "SUCCESS",
+          status: "OK",
         });
         expect(result.data.run).toEqual({
-          stdout: "ok\n",
+          stdout: "b2sK",
           stderr: "",
-          output: "ok\n",
+          output: "b2sK",
           exitCode: 0,
           signal: null,
-          status: "SUCCESS",
+          status: "OK",
         });
       });
 
       it("returns compile as null when the API returns null", async () => {
         const body = {
           compile: null,
-          run: { stdout: "", stderr: "", output: "", exit_code: 0, signal: null, status: "SUCCESS" },
+          run: { stdout: "", stderr: "", output: "", exit_code: 0, signal: null, status: "OK" },
         };
         const fetchFn = vi.fn().mockResolvedValue(makeJsonResponse(body));
         const client = new CodizeClient({ apiKey: "key", fetchFn });
@@ -193,7 +234,8 @@ describe("CodizeClient", () => {
     describe("structured API error", () => {
       it("throws CodizeApiError for a structured error response", async () => {
         const errorBody = {
-          error: { code: "UNAUTHORIZED", message: "Invalid API key" },
+          code: "UNAUTHORIZED",
+          message: "Invalid API key",
         };
         const fetchFn = vi.fn().mockResolvedValue(
           makeJsonResponse(errorBody, 401),
@@ -207,7 +249,8 @@ describe("CodizeClient", () => {
 
       it("sets the correct status on CodizeApiError", async () => {
         const errorBody = {
-          error: { code: "RATE_LIMITED", message: "Too many requests" },
+          code: "RATE_LIMITED",
+          message: "Too many requests",
         };
         const fetchFn = vi.fn().mockResolvedValue(
           makeJsonResponse(errorBody, 429),
@@ -223,7 +266,8 @@ describe("CodizeClient", () => {
 
       it("sets the correct code on CodizeApiError", async () => {
         const errorBody = {
-          error: { code: "RATE_LIMITED", message: "Too many requests" },
+          code: "RATE_LIMITED",
+          message: "Too many requests",
         };
         const fetchFn = vi.fn().mockResolvedValue(
           makeJsonResponse(errorBody, 429),
@@ -238,7 +282,8 @@ describe("CodizeClient", () => {
 
       it("sets the correct message on CodizeApiError", async () => {
         const errorBody = {
-          error: { code: "UNAUTHORIZED", message: "Invalid API key" },
+          code: "UNAUTHORIZED",
+          message: "Invalid API key",
         };
         const fetchFn = vi.fn().mockResolvedValue(
           makeJsonResponse(errorBody, 401),
@@ -253,13 +298,11 @@ describe("CodizeClient", () => {
 
       it("includes validation errors array when present", async () => {
         const errorBody = {
-          error: {
-            code: "VALIDATION_ERROR",
-            message: "Validation failed",
-            errors: [
-              { message: "'files' is required", path: ["files"] },
-            ],
-          },
+          code: "VALIDATION_ERROR",
+          message: "Validation failed",
+          errors: [
+            { message: "'files' is required", path: ["files"] },
+          ],
         };
         const fetchFn = vi.fn().mockResolvedValue(
           makeJsonResponse(errorBody, 422),
@@ -270,13 +313,14 @@ describe("CodizeClient", () => {
           .catch((e: unknown) => e);
 
         expect((error as CodizeApiError).errors).toEqual(
-          errorBody.error.errors,
+          errorBody.errors,
         );
       });
 
       it("attaches response headers to CodizeApiError", async () => {
         const errorBody = {
-          error: { code: "UNAUTHORIZED", message: "Invalid API key" },
+          code: "UNAUTHORIZED",
+          message: "Invalid API key",
         };
         const fetchFn = vi.fn().mockResolvedValue(
           makeJsonResponse(errorBody, 401, {

typescript/src/client.ts

@@ -26,20 +26,23 @@ export type CodizeClientOptions = {
 };
 
 /**
- * Request payload for `sandbox.execute`.
+ * Runtime identifier for sandbox execution.
  */
+export type SandboxRuntime =
+  | "bash"
+  | "go"
+  | "node"
+  | "node-typescript"
+  | "python"
+  | "ruby"
+  | "rust"
+  | (string & {});
+
 export type SandboxExecuteRequest = {
   /**
-   * Language name used for execution.
+   * Runtime used for execution.
    */
-  language:
-    | "go"
-    | "javascript"
-    | "python"
-    | "ruby"
-    | "rust"
-    | "typescript"
-    | (string & {});
+  runtime: SandboxRuntime;
   /**
    * Source files to execute, with their content.
    */
@@ -49,9 +52,13 @@ export type SandboxExecuteRequest = {
      */
     name: string;
     /**
-     * Full text content of the file.
+     * File content. Plain text by default, or Base64-encoded data when `base64Encoded` is `true`.
      */
     content: string;
+    /**
+     * Whether the content is Base64 encoded.
+     */
+    base64Encoded?: boolean;
   }[];
 };
 
@@ -79,12 +86,10 @@ export type SandboxExecuteResponse = {
  * Execution status of a sandbox stage.
  */
 export type SandboxStageStatus =
-  | "SUCCESS"
-  | "RUNTIME_ERROR"
+  | "OK"
   | "SIGNAL"
   | "TIMEOUT"
   | "OUTPUT_LIMIT_EXCEEDED"
-  | "ERROR_LIMIT_EXCEEDED"
   | (string & {});
 
 /**
@@ -106,7 +111,7 @@ export type SandboxStageResult = {
   /**
    * Process exit code.
    */
-  exitCode: number | null;
+  exitCode: number;
   /**
    * Signal name that terminated the process, or null if not terminated by a signal.
    */
@@ -124,7 +129,7 @@ type RawStageResult = {
   stdout: string;
   stderr: string;
   output: string;
-  exit_code: number | null;
+  exit_code: number;
   signal: string | null;
   status: SandboxStageStatus;
 };
@@ -188,6 +193,15 @@ export class CodizeClient {
   private async _sandboxExecute(
     request: SandboxExecuteRequest,
   ): Promise<SandboxExecuteResponse> {
+    const body = {
+      runtime: request.runtime,
+      files: request.files.map((f) => ({
+        name: f.name,
+        content: f.content,
+        base64_encoded: f.base64Encoded ?? false,
+      })),
+    };
+
     const response = await this._fetchFn(
       new URL("/api/v1/sandbox/execute", this._baseUrl),
       {
@@ -196,7 +210,7 @@ export class CodizeClient {
           "Content-Type": "application/json",
           Authorization: `Bearer ${this._apiKey}`,
         },
-        body: JSON.stringify(request),
+        body: JSON.stringify(body),
       },
     );
 

typescript/src/error.spec.ts

@@ -7,36 +7,41 @@ describe("CodizeApiError", () => {
 
   it("sets name to 'CodizeApiError'", () => {
     const error = new CodizeApiError(401, makeHeaders(), {
-      error: { code: "UNAUTHORIZED", message: "Unauthorized" },
+      code: "UNAUTHORIZED",
+      message: "Unauthorized",
     });
     expect(error.name).toBe("CodizeApiError");
   });
 
-  it("sets message from response.error.message", () => {
+  it("sets message from response.message", () => {
     const error = new CodizeApiError(401, makeHeaders(), {
-      error: { code: "UNAUTHORIZED", message: "Invalid API key" },
+      code: "UNAUTHORIZED",
+      message: "Invalid API key",
     });
     expect(error.message).toBe("Invalid API key");
   });
 
-  it("sets code from response.error.code", () => {
+  it("sets code from response.code", () => {
     const error = new CodizeApiError(401, makeHeaders(), {
-      error: { code: "UNAUTHORIZED", message: "Unauthorized" },
+      code: "UNAUTHORIZED",
+      message: "Unauthorized",
     });
     expect(error.code).toBe("UNAUTHORIZED");
   });
 
   it("sets status from the first argument", () => {
     const error = new CodizeApiError(429, makeHeaders(), {
-      error: { code: "RATE_LIMITED", message: "Too many requests" },
+      code: "RATE_LIMITED",
+      message: "Too many requests",
     });
     expect(error.status).toBe(429);
   });
 
   it("sets headers from the second argument", () => {
     const headers = makeHeaders({ "x-request-id": "abc123" });
     const error = new CodizeApiError(500, headers, {
-      error: { code: "INTERNAL_ERROR", message: "Server error" },
+      code: "INTERNAL_ERROR",
+      message: "Server error",
     });
     expect(error.headers).toBe(headers);
     expect(error.headers.get("x-request-id")).toBe("abc123");
@@ -45,25 +50,25 @@ describe("CodizeApiError", () => {
   it("sets errors when provided", () => {
     const errors = [{ message: "field required", path: ["files", 0] }];
     const error = new CodizeApiError(422, makeHeaders(), {
-      error: {
-        code: "VALIDATION_ERROR",
-        message: "Validation failed",
-        errors,
-      },
+      code: "VALIDATION_ERROR",
+      message: "Validation failed",
+      errors,
     });
     expect(error.errors).toEqual(errors);
   });
 
   it("leaves errors undefined when not provided", () => {
     const error = new CodizeApiError(401, makeHeaders(), {
-      error: { code: "UNAUTHORIZED", message: "Unauthorized" },
+      code: "UNAUTHORIZED",
+      message: "Unauthorized",
     });
     expect(error.errors).toBeUndefined();
   });
 
   it("is an instance of Error", () => {
     const error = new CodizeApiError(500, makeHeaders(), {
-      error: { code: "INTERNAL_ERROR", message: "Oops" },
+      code: "INTERNAL_ERROR",
+      message: "Oops",
     });
     expect(error).toBeInstanceOf(Error);
   });