fix(uploads): serialize objects without files as JSON in multipart forms

Objects without uploadable values are now JSON-serialized per OpenAPI
contentType spec instead of being flattened into bracketed keys.

Special handling for env_vars to maintain backward compatibility - it
continues using flattened format (env_vars[KEY]) as expected by APIs.

- Add hasUploadableValue check to determine serialization strategy
- Add tests for source field (JSON) and env_vars (flattened) behavior
- Fixes 400 errors where source[type] was sent instead of source JSON

Resolves issue reported to Stainless support on Oct 8, 2025

Author: jarugupj

src/internal/uploads.ts

@@ -176,9 +176,28 @@ const addFormValue = async (form: FormData, key: string, value: unknown): Promis
   } else if (Array.isArray(value)) {
     await Promise.all(value.map((entry) => addFormValue(form, key + '[]', entry)));
   } else if (typeof value === 'object') {
-    await Promise.all(
-      Object.entries(value).map(([name, prop]) => addFormValue(form, `${key}[${name}]`, prop)),
-    );
+    // Special case: env_vars should always be flattened for backward compatibility
+    // with APIs that expect env_vars[KEY] format
+    const shouldAlwaysFlatten = key === 'env_vars';
+    
+    // If the object doesn't contain any uploadable values,
+    // serialize it as JSON instead of flattening it into bracketed keys.
+    // This handles fields with contentType: application/json in the OpenAPI spec.
+    if (!shouldAlwaysFlatten && !hasUploadableValue(value)) {
+      // Filter out undefined values to check if object has any actual content
+      const entries = Object.entries(value).filter(([_, v]) => v !== undefined);
+      if (entries.length > 0) {
+        form.append(key, JSON.stringify(value));
+      }
+      // If all properties are undefined, don't add anything to the form
+    } else {
+      // Flatten objects that:
+      // - Contain uploadable values (files/blobs), or
+      // - Are explicitly marked to always flatten (like env_vars)
+      await Promise.all(
+        Object.entries(value).map(([name, prop]) => addFormValue(form, `${key}[${name}]`, prop)),
+      );
+    }
   } else {
     throw new TypeError(
       `Invalid value given to form, expected a string, number, boolean, object, Array, File or Blob but got ${value} instead`,

tests/form.test.ts

@@ -62,7 +62,49 @@ describe('form data validation', () => {
       },
       fetch,
     );
-    expect(Array.from(form2.entries())).toEqual([['bar[foo]', 'string']]);
+    // Objects without uploadable values are now serialized as JSON
+    expect(Array.from(form2.entries())).toEqual([['bar', '{"foo":"string"}']]);
+  });
+
+  test('env_vars are always flattened for backward compatibility', async () => {
+    const form = await createForm(
+      {
+        env_vars: {
+          API_KEY: 'secret',
+          DEBUG: 'true',
+        },
+      },
+      fetch,
+    );
+    // env_vars should be flattened, not JSON-serialized
+    expect(Array.from(form.entries())).toEqual([
+      ['env_vars[API_KEY]', 'secret'],
+      ['env_vars[DEBUG]', 'true'],
+    ]);
+  });
+
+  test('source field is JSON-serialized', async () => {
+    const form = await createForm(
+      {
+        source: {
+          type: 'github',
+          url: 'https://github.com/user/repo',
+          ref: 'main',
+          entrypoint: 'app.py',
+        },
+      },
+      fetch,
+    );
+    // source should be JSON-serialized per OpenAPI spec
+    const entries = Array.from(form.entries());
+    expect(entries.length).toBe(1);
+    expect(entries[0]![0]).toBe('source');
+    expect(JSON.parse(entries[0]![1] as string)).toEqual({
+      type: 'github',
+      url: 'https://github.com/user/repo',
+      ref: 'main',
+      entrypoint: 'app.py',
+    });
   });
 
   test('nested undefined array item is stripped', async () => {