@blueprint-ts/core 4.1.0-beta.1 → 4.1.0-beta.2

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 4.1.0-beta.2 - 2026-03-25 (beta)
+
+# [4.1.0-beta.2](/compare/4.1.0-beta.1...4.1.0-beta.2) (2026-03-25)
+
+
+### Bug Fixes
+
+* Tighten response header typing f767572
+
+
+### Features
+
+* Support Blob and ArrayBuffer bodies a265df3
 ## 4.1.0-beta.1 - 2026-03-21 (beta)
 
 # [4.1.0-beta.1](/compare/v4.0.0...v4.1.0-beta.1) (2026-03-21)

package/docs/services/requests/file-uploads.md

@@ -1,7 +1,15 @@
 # File Uploads
 
-Use `FormDataFactory` to build multipart payloads, and use `XMLHttpRequestDriver` when the consuming application needs
-upload progress for a progress bar.
+Use `FormDataFactory` for multipart uploads with fields, and use `BinaryBodyFactory` when the endpoint expects a raw
+binary body such as a chunk `PUT`. Use `XMLHttpRequestDriver` when the consuming application needs upload progress for a
+progress bar.
+
+Choose the body factory based on the wire format your endpoint expects:
+
+- Use `FormDataFactory` when the request includes normal fields plus one or more files.
+- Use `BinaryBodyFactory` when the request body itself is the file or chunk.
+- Use `FetchDriver` if you just need to send the upload.
+- Use `XMLHttpRequestDriver` if you also need upload progress events.
 
 ## Request Definition
 
@@ -92,10 +100,65 @@ await request.setBody({
 }).send()
 ```
 
+## Raw Chunk Uploads
+
+```typescript
+import {
+    BaseRequest,
+    BinaryBodyFactory,
+    JsonResponse,
+    RequestMethodEnum,
+    XMLHttpRequestDriver
+} from '@blueprint-ts/core/requests'
+
+interface UploadPartResponse {
+    etag: string
+}
+
+class UploadPartRequest extends BaseRequest<
+        boolean,
+        { message: string },
+        UploadPartResponse,
+        JsonResponse<UploadPartResponse>,
+        Uint8Array
+> {
+    public method(): RequestMethodEnum {
+        return RequestMethodEnum.PUT
+    }
+
+    public url(): string {
+        return '/api/v1/uploads/part'
+    }
+
+    public getResponse(): JsonResponse<UploadPartResponse> {
+        return new JsonResponse<UploadPartResponse>()
+    }
+
+    public override getRequestBodyFactory() {
+        return new BinaryBodyFactory<Uint8Array>('application/octet-stream')
+    }
+
+    public override requestHeaders() {
+        return {
+            'X-Part-Number': '1'
+        }
+    }
+
+    protected override getRequestDriver() {
+        return new XMLHttpRequestDriver()
+    }
+}
+```
+
+In this example, `setBody(...)` can receive a `Blob`, `ArrayBuffer`, `Uint8Array`, or another typed-array/data-view
+payload supported by `BinaryBodyFactory`.
+
 ## Notes
 
 - Upload progress requires `XMLHttpRequestDriver`. The default `FetchDriver` does not emit upload progress events.
 - Define `XMLHttpRequestDriver` inside the upload request class when that request should always support progress.
+- `BinaryBodyFactory` only sets `Content-Type` automatically when the body is a `Blob` with a non-empty `type`.
+  For `ArrayBuffer` and typed-array uploads, pass the expected content type explicitly.
 - `XMLHttpRequestDriver` supports the same `corsWithCredentials` and `headers` options as `FetchDriver`, including
   header callbacks.
 - Request-defined drivers do not automatically inherit config from the globally registered driver.

package/docs/services/requests/request-bodies.md

@@ -56,6 +56,34 @@ public override getRequestBodyFactory() {
 
 If you want to show upload progress for multipart file uploads, see [File Uploads](/services/requests/file-uploads).
 
+## Raw Binary Bodies
+
+Use `BinaryBodyFactory` when the request body should be sent as raw binary instead of multipart form data. This is a
+better fit for chunk uploads, binary artifact pushes, and endpoints that expect the request body as-is:
+
+```typescript
+import { BinaryBodyFactory } from '@blueprint-ts/core/requests'
+
+public override getRequestBodyFactory() {
+    return new BinaryBodyFactory<ArrayBuffer>('application/octet-stream')
+}
+```
+
+`BinaryBodyFactory` supports:
+
+- `Blob`
+- `ArrayBuffer`
+- typed-array and view values such as `Uint8Array` or `DataView`
+
+`Content-Type` resolution works like this:
+
+- If you pass a content type to `BinaryBodyFactory`, Blueprint sends that `Content-Type` header.
+- Otherwise, if the body is a `Blob` with a non-empty `type`, Blueprint uses `Blob.type`.
+- Otherwise, Blueprint does not add a `Content-Type` header for you.
+
+`BinaryBodyFactory` works with both `FetchDriver` and `XMLHttpRequestDriver`. Choose `XMLHttpRequestDriver` only when
+the consuming application needs upload progress events.
+
 ## Custom Body Factories
 
 You can implement your own body factory by returning a `BodyContract` with custom headers and serialization logic.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueprint-ts/core",
-  "version": "4.1.0-beta.1",
+  "version": "4.1.0-beta.2",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/src/requests/bodies/BinaryBody.ts

@@ -0,0 +1,31 @@
+import { type BodyContent, type BodyContract } from '../contracts/BodyContract'
+import { type HeadersContract } from '../contracts/HeadersContract'
+
+export class BinaryBody<RequestBody extends Exclude<BodyContent, string | FormData>> implements BodyContract {
+  public constructor(
+    protected data: RequestBody,
+    protected contentType?: string
+  ) {}
+
+  public getHeaders(): HeadersContract {
+    const contentType = this.resolveContentType()
+
+    return contentType === undefined ? {} : { 'Content-Type': contentType }
+  }
+
+  public getContent(): RequestBody {
+    return this.data
+  }
+
+  protected resolveContentType(): string | undefined {
+    if (this.contentType !== undefined) {
+      return this.contentType
+    }
+
+    if (typeof Blob !== 'undefined' && this.data instanceof Blob && this.data.type !== '') {
+      return this.data.type
+    }
+
+    return undefined
+  }
+}

package/src/requests/contracts/BodyContract.ts

@@ -1,7 +1,9 @@
 import { type HeadersContract } from './HeadersContract'
 
+export type BodyContent = string | FormData | Blob | ArrayBuffer | ArrayBufferView<ArrayBuffer>
+
 export interface BodyContract {
-  getContent(): string | FormData
+  getContent(): BodyContent
 
   getHeaders(): HeadersContract
 }

package/src/requests/contracts/HeadersContract.ts

@@ -3,3 +3,7 @@ export type HeaderValue = string | (() => string)
 export interface HeadersContract {
   [key: string]: HeaderValue
 }
+
+export interface ResolvedHeadersContract {
+  [key: string]: string
+}

package/src/requests/drivers/contracts/ResponseHandlerContract.ts

@@ -1,8 +1,8 @@
-import { type HeadersContract } from '../../contracts/HeadersContract'
+import { type ResolvedHeadersContract } from '../../contracts/HeadersContract'
 
 export interface ResponseHandlerContract {
   getStatusCode(): number | undefined
-  getHeaders(): HeadersContract
+  getHeaders(): ResolvedHeadersContract
   getRawResponse(): Response
   json<ResponseBodyInterface>(): Promise<ResponseBodyInterface>
   text(): Promise<string>

package/src/requests/drivers/fetch/FetchDriver.ts

@@ -2,7 +2,7 @@ import { ResponseException } from '../../exceptions/ResponseException'
 import { FetchResponse } from './FetchResponse'
 import { RequestMethodEnum } from '../../RequestMethod.enum'
 import { type HeadersContract, type HeaderValue } from '../../contracts/HeadersContract'
-import { type BodyContract } from '../../contracts/BodyContract'
+import { type BodyContent, type BodyContract } from '../../contracts/BodyContract'
 import { type RequestDriverContract } from '../../contracts/RequestDriverContract'
 import { type DriverConfigContract } from '../../contracts/DriverConfigContract'
 import { type ResponseHandlerContract } from '../contracts/ResponseHandlerContract'
@@ -17,7 +17,7 @@ interface FetchDriverConfig {
   headers: HeadersContract
   credentials?: FetchDriverCredentialConfigEnum | undefined
   signal?: AbortSignal | undefined
-  body?: string | FormData | Blob | ArrayBuffer | ArrayBufferView | URLSearchParams | undefined
+  body?: BodyContent | URLSearchParams | undefined
 }
 
 export class FetchDriver implements RequestDriverContract {

package/src/requests/drivers/fetch/FetchResponse.ts

@@ -1,4 +1,4 @@
-import { type HeadersContract } from '../../contracts/HeadersContract'
+import { type ResolvedHeadersContract } from '../../contracts/HeadersContract'
 import { type ResponseHandlerContract } from '../contracts/ResponseHandlerContract'
 
 export class FetchResponse implements ResponseHandlerContract {
@@ -8,7 +8,7 @@ export class FetchResponse implements ResponseHandlerContract {
     return this.response.status
   }
 
-  public getHeaders(): HeadersContract {
+  public getHeaders(): ResolvedHeadersContract {
     return Object.fromEntries(this.response.headers)
   }
 

package/src/requests/drivers/xhr/XMLHttpRequestResponse.ts

@@ -1,9 +1,9 @@
-import { type HeadersContract } from '../../contracts/HeadersContract'
+import { type ResolvedHeadersContract } from '../../contracts/HeadersContract'
 import { type ResponseHandlerContract } from '../contracts/ResponseHandlerContract'
 
 export class XMLHttpRequestResponse implements ResponseHandlerContract {
   protected response: Response
-  protected headers: HeadersContract
+  protected headers: ResolvedHeadersContract
 
   public constructor(protected request: XMLHttpRequest) {
     this.headers = this.parseHeaders(request.getAllResponseHeaders())
@@ -18,7 +18,7 @@ export class XMLHttpRequestResponse implements ResponseHandlerContract {
     return this.request.status
   }
 
-  public getHeaders(): HeadersContract {
+  public getHeaders(): ResolvedHeadersContract {
     return this.headers
   }
 
@@ -65,8 +65,8 @@ export class XMLHttpRequestResponse implements ResponseHandlerContract {
     )
   }
 
-  protected parseHeaders(rawHeaders: string): HeadersContract {
-    const headers: HeadersContract = {}
+  protected parseHeaders(rawHeaders: string): ResolvedHeadersContract {
+    const headers: ResolvedHeadersContract = {}
     const lines = rawHeaders.trim()
 
     if (lines.length === 0) {

package/src/requests/factories/BinaryBodyFactory.ts

@@ -0,0 +1,13 @@
+import { BinaryBody } from '../bodies/BinaryBody'
+import { type BodyFactoryContract } from '../contracts/BodyFactoryContract'
+import { type BodyContent, type BodyContract } from '../contracts/BodyContract'
+
+export type BinaryBodyContent = Exclude<BodyContent, string | FormData>
+
+export class BinaryBodyFactory<RequestBodyInterface extends BinaryBodyContent> implements BodyFactoryContract<RequestBodyInterface> {
+  public constructor(protected contentType?: string) {}
+
+  public make(body: RequestBodyInterface): BodyContract {
+    return new BinaryBody<RequestBodyInterface>(body, this.contentType)
+  }
+}

package/src/requests/index.ts

@@ -9,9 +9,11 @@ import { RequestErrorRouter } from './RequestErrorRouter'
 import { RequestEvents } from './RequestEvents.enum'
 import { RequestMethodEnum } from './RequestMethod.enum'
 import { RequestConcurrencyMode } from './RequestConcurrencyMode.enum'
+import { BinaryBody } from './bodies/BinaryBody'
 import { JsonBodyFactory } from './factories/JsonBodyFactory'
+import { BinaryBodyFactory, type BinaryBodyContent } from './factories/BinaryBodyFactory'
 import { FormDataFactory } from './factories/FormDataFactory'
-import { type BodyContract } from './contracts/BodyContract'
+import { type BodyContent, type BodyContract } from './contracts/BodyContract'
 import { type RequestLoaderContract } from './contracts/RequestLoaderContract'
 import { type RequestDriverContract } from './contracts/RequestDriverContract'
 import { type RequestLoaderFactoryContract } from './contracts/RequestLoaderFactoryContract'
@@ -21,7 +23,7 @@ import { type ResponseHandlerContract } from './drivers/contracts/ResponseHandle
 import { type BaseRequestContract } from './contracts/BaseRequestContract'
 import { ResponseException } from './exceptions/ResponseException'
 import { StaleResponseException } from './exceptions/StaleResponseException'
-import { type HeaderValue, type HeadersContract } from './contracts/HeadersContract'
+import { type HeaderValue, type HeadersContract, type ResolvedHeadersContract } from './contracts/HeadersContract'
 import { type RequestConcurrencyOptions } from './types/RequestConcurrencyOptions'
 import { type RequestUploadProgress } from './types/RequestUploadProgress'
 import { XMLHttpRequestDriver } from './drivers/xhr/XMLHttpRequestDriver'
@@ -40,12 +42,16 @@ export {
   RequestConcurrencyMode,
   ResponseException,
   StaleResponseException,
+  BinaryBody,
   JsonBodyFactory,
+  BinaryBodyFactory,
   FormDataFactory,
   XMLHttpRequestDriver
 }
 
 export type {
+  BodyContent,
+  BinaryBodyContent,
   RequestDriverContract,
   RequestLoaderContract,
   BodyContract,
@@ -56,6 +62,7 @@ export type {
   BaseRequestContract,
   HeaderValue,
   HeadersContract,
+  ResolvedHeadersContract,
   RequestConcurrencyOptions,
   RequestUploadProgress
 }

package/src/requests/responses/BaseResponse.ts

@@ -1,5 +1,5 @@
 import { type ResponseHandlerContract } from '../drivers/contracts/ResponseHandlerContract'
-import { type HeadersContract } from '../contracts/HeadersContract'
+import { type ResolvedHeadersContract } from '../contracts/HeadersContract'
 import { type ResponseContract } from '../contracts/ResponseContract'
 
 export abstract class BaseResponse<ResponseInterface> implements ResponseContract<ResponseInterface> {
@@ -27,7 +27,7 @@ export abstract class BaseResponse<ResponseInterface> implements ResponseContrac
     return this.response?.getStatusCode()
   }
 
-  public getHeaders(): HeadersContract | undefined {
+  public getHeaders(): ResolvedHeadersContract | undefined {
     return this.response?.getHeaders()
   }
 

package/tests/service/requests/BodiesAndFactories.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, it } from 'vitest'
+import { BinaryBody } from '../../../src/requests/bodies/BinaryBody'
 import { JsonBody } from '../../../src/requests/bodies/JsonBody'
+import { BinaryBodyFactory } from '../../../src/requests/factories/BinaryBodyFactory'
 import { JsonBodyFactory } from '../../../src/requests/factories/JsonBodyFactory'
 import { FormDataFactory } from '../../../src/requests/factories/FormDataFactory'
 import { FormDataBody } from '../../../src/requests/bodies/FormDataBody'
@@ -19,6 +21,28 @@ describe('Request bodies and factories', () => {
     expect(body).toBeInstanceOf(JsonBody)
   })
 
+  it('BinaryBody returns explicit content type and binary content', () => {
+    const body = new BinaryBody(new Uint8Array([1, 2, 3]), 'application/octet-stream')
+
+    expect(body.getHeaders()).toEqual({ 'Content-Type': 'application/octet-stream' })
+    expect(body.getContent()).toEqual(new Uint8Array([1, 2, 3]))
+  })
+
+  it('BinaryBody uses Blob mime type when no explicit content type is given', () => {
+    const blob = new Blob(['hello'], { type: 'application/custom-binary' })
+    const body = new BinaryBody(blob)
+
+    expect(body.getHeaders()).toEqual({ 'Content-Type': 'application/custom-binary' })
+    expect(body.getContent()).toBe(blob)
+  })
+
+  it('BinaryBodyFactory returns BinaryBody', () => {
+    const factory = new BinaryBodyFactory<Uint8Array>('application/octet-stream')
+    const body = factory.make(new Uint8Array([4, 5, 6]))
+
+    expect(body).toBeInstanceOf(BinaryBody)
+  })
+
   it('FormDataFactory returns FormDataBody', () => {
     const factory = new FormDataFactory<{ name: string }>()
     const body = factory.make({ name: 'alice' })

package/tests/service/requests/fetch/FetchDriver.test.ts

@@ -3,10 +3,10 @@ import { FetchDriver } from '../../../../src/requests/drivers/fetch/FetchDriver'
 import { FetchResponse } from '../../../../src/requests/drivers/fetch/FetchResponse'
 import { RequestMethodEnum } from '../../../../src/requests/RequestMethod.enum'
 import { ResponseException } from '../../../../src/requests/exceptions/ResponseException'
-import type { BodyContract } from '../../../../src/requests/contracts/BodyContract'
+import type { BodyContent, BodyContract } from '../../../../src/requests/contracts/BodyContract'
 
-const createBody = (content: string): BodyContract => ({
-  getHeaders: () => ({ 'Content-Type': 'application/json' }),
+const createBody = (content: BodyContent, headers: Record<string, string> = { 'Content-Type': 'application/json' }): BodyContract => ({
+  getHeaders: () => headers,
   getContent: () => content,
 })
 
@@ -65,6 +65,24 @@ describe('FetchDriver', () => {
     expect(config.body).toBeUndefined()
   })
 
+  it('passes Blob bodies through to fetch unchanged', async () => {
+    const response = new Response('ok', { status: 200 })
+    ;(global.fetch as unknown as ReturnType<typeof vi.fn>).mockResolvedValue(response)
+
+    const blob = new Blob(['chunk'], { type: 'application/octet-stream' })
+    const driver = new FetchDriver()
+
+    await driver.send(
+      'https://example.com',
+      RequestMethodEnum.PUT,
+      {},
+      createBody(blob, { 'Content-Type': 'application/octet-stream' })
+    )
+
+    const [, config] = (global.fetch as unknown as ReturnType<typeof vi.fn>).mock.calls[0]
+    expect(config.body).toBe(blob)
+  })
+
   it('throws ResponseException when response is not ok', async () => {
     const response = new Response('fail', { status: 500 })
     ;(global.fetch as unknown as ReturnType<typeof vi.fn>).mockResolvedValue(response)

package/tests/service/requests/xhr/XMLHttpRequestDriver.test.ts

@@ -3,10 +3,10 @@ import { XMLHttpRequestDriver } from '../../../../src/requests/drivers/xhr/XMLHt
 import { XMLHttpRequestResponse } from '../../../../src/requests/drivers/xhr/XMLHttpRequestResponse'
 import { RequestMethodEnum } from '../../../../src/requests/RequestMethod.enum'
 import { ResponseException } from '../../../../src/requests/exceptions/ResponseException'
-import type { BodyContract } from '../../../../src/requests/contracts/BodyContract'
+import type { BodyContent, BodyContract } from '../../../../src/requests/contracts/BodyContract'
 
-const createBody = (content: string): BodyContract => ({
-  getHeaders: () => ({ 'Content-Type': 'application/json' }),
+const createBody = (content: BodyContent, headers: Record<string, string> = { 'Content-Type': 'application/json' }): BodyContract => ({
+  getHeaders: () => headers,
   getContent: () => content,
 })
 
@@ -148,6 +148,25 @@ describe('XMLHttpRequestDriver', () => {
     expect(request.sentBody).toBeUndefined()
   })
 
+  it('passes typed array bodies through to xhr unchanged', async () => {
+    const driver = new XMLHttpRequestDriver()
+    const chunk = new Uint8Array([1, 2, 3, 4])
+
+    const promise = driver.send(
+      'https://example.com',
+      RequestMethodEnum.PUT,
+      {},
+      createBody(chunk, { 'Content-Type': 'application/octet-stream' })
+    )
+
+    const request = MockXMLHttpRequest.instances[0]
+    request.triggerLoad()
+
+    await promise
+
+    expect(request.sentBody).toBe(chunk)
+  })
+
   it('throws ResponseException when the response status is not ok', async () => {
     const driver = new XMLHttpRequestDriver()