TypeScript v4 SDKs now handle files end to end. Binary request bodies, multipart/form-data forms whose parts are files, typed JSON documents or text fields, and binary success and error responses all generate with typed signatures.
Details
A file is passed as a FileInput: a Blob, a Uint8Array, an ArrayBuffer, a web ReadableStream, or a Node stream such as createReadStream(path). Wrap any of them as { data, fileName, contentType } to name the file or override its media type. A path on its own is not a file, so open it first. A multipart form takes each part as its own request field, and a field declared as an array of files sends one part per file.
A binary success response resolves to BinaryContent, a handle whose stream is the unread response body together with its contentType and fileName. Read the stream once or cancel it. A binary error response arrives as BinaryErrorContent on the thrown error's payload, with its bytes already read, so the body is never lost.
Usage Example
Upload a multipart form from a file on disk, then download a file and save it:
import { openAsBlob } from "node:fs";
import { writeFile } from "node:fs/promises";
import { PaymentsClient } from "payments";
const client = new PaymentsClient();
const uploaded = await client.files.uploadForm({
file: { data: await openAsBlob("report.pdf"), fileName: "report.pdf" },
metadata: { title: "Q3 report" },
label: "finance",
});
const download = await client.files.download({ fileId: uploaded.id });
const bytes = new Uint8Array(await new Response(download.stream).arrayBuffer());
await writeFile("report-copy.pdf", bytes);
The server's fileName on a download is untrusted input, so name the file you write yourself.
This feature is available in the TypeScript v4 SDK (beta). Generate it from the APIMatic CLI:
apimatic sdk generate --language=typescript --codegen-version=v4 --stability=beta
For the full set of flags and options, see the APIMatic CLI documentation.