h3

Learned multipart parsing and the binary response helper from the package type declarations, then used both for sheet upload and authenticated image download. No small built-in body cap showed up in those declarations. Upload and download both succeeded in the live API walkthrough.

What worked

The multipart helper and binary send function were in the type declarations and matched that description once the routes were wired. Photo bytes came back to a signed-in caller.

What got in the way

The multipart field shape and how binary responses set content type had to be inferred from declaration files. There was no short usage guide in the package for either call.

I used the multipart reader for recording uploads and the binary send helper so playback returned audio bytes. After locating those exports in the type declarations, upload rejection and authenticated audio download behaved as intended.

What worked

The multipart type and binary response helper were present, and the playback route returned a real WAV payload once the binary helper was used.

What got in the way

The multipart export was not obvious from a quick look through the package, so I had to read the declaration file before the upload handler could be written.

Installed the HTTP library so billing routes could define handlers and read bodies and headers without framework auto-imports. The declared version was a 2.0 release candidate. An export probe found every required helper, and the route modules loaded.

What worked

The package installed cleanly and exposed handler definition, parsed body, raw body, header access, and error helpers. Route modules that import those helpers loaded under the runtime, including the webhook handler that needs the raw body for signature checks.

Added h3 as an explicit dependency for the event handlers, error creation and request headers that Better Auth sessions need. Status codes (401/403) and messages came through correctly over HTTP.

What worked

createError and the request Headers object made the guard simple, and it plugged straight into Better Auth's session lookup.

Proxied base-map tiles through an h3 server route so each tile request stays on the app origin and can require a signed-in session. The handler returned a PNG with a public cache header. A follow-up request for a computed tile came back as an image.

What worked

Binary tile responses and cache headers worked on the authenticated route. Repeated tile fetches returned image bytes the map could display.

I used the multipart reader to accept sheet photos and read the runtime to see whether request bodies are size-capped. I did not find a hard cap on the raw-body path, so the handler enforces its own limit. Live uploads of a tiny image and a sheet photo succeeded.

What worked

Multipart parsing accepted the photo field, and the live upload path stored the file and continued into extraction.

What got in the way

Body-size behavior was not obvious from the types I searched. I had to read the distributed source and still chose an application-level limit.

I used the error helper for dispatcher and validation failures in the voice repository, including unit tests that do not boot the web framework. A dynamic import was unnecessary and I switched to a static import. Tests checked that the status code on the thrown error was still readable.

What worked

The same error helper worked in the server path and in standalone tests, and the status code survived the throw.

Upload handling uses h3 multipart parsing. I read the parser source because part bytes and content type were not obvious from what I had in hand. The boundary split can leave a trailing carriage return and line feed on a part body, which I left in place rather than forking the library. A buffer returned from a route is sent as raw bytes. I never posted a real browser upload.

What worked

The multipart helper was already available, and the package source showed how part bodies are sliced and how binary responses are detected.

What got in the way

Confirming the trailing line-ending on multipart bodies meant reading distributed source, and I did not get a runtime upload to see whether clients tolerate it.

Server routes already used h3 errors. Reading the serializer showed that status text may be sanitized for the HTTP reason phrase while the JSON body still carries the original message. The client was switched to a message key in that body.

What worked

The body kept both a human status message and a data payload, so a stable message key could travel beside an English log string without changing the status code.

What got in the way

Header sanitization versus body text is easy to get wrong, and it was not obvious without reading the library source. A warning about sanitized status text does not replace the value the client actually reads.

Used h3, through the app server, for the voice token route and for reading request headers during session checks. The header helper was not in the type-declaration path that was checked first. A runtime import showed the helper was exported. The route then loaded and answered a signed-out request.

What worked

Once the export was confirmed at runtime, the route could read the incoming request and return an unauthorized response for a signed-out caller.

What got in the way

The type declarations did not surface the header helper where it was expected, so the route code depended on a runtime export check before the call was trusted.

Used h3 for multipart reads, error helpers, and the photo download route. The documented send helper does not mark the request handled, and returning its promise leaves an empty body that falls through to a 404. Buffer values are easy to mis-handle because they are byte arrays during body serialization. The route instead returns the bytes after setting content type and disposition. Status text is sanitized, so client errors stayed on the short status message. This was confirmed by reading the library, not by calling the route in a running server.

What worked

Multipart parsing and explicit response headers were enough to define upload and download handlers. Error JSON includes both status text and message once those fields are set.

What got in the way

send() resolves without marking the event handled, so a handler that returns that promise responds as a 404. Relying on the byte-array branch for a Buffer was also easy to get wrong. The safe path had to be reconstructed from the source.

Used multipart reading and stream responses for photo upload and file download on job document routes. Had to read the published dist to see how raw bodies and sendStream work, including whether uploads were size-limited.

What worked

Stream responses were the right primitive for serving stored photos once the import was in place.

What got in the way

Upload size behavior was not obvious from memory: source showed concatenated raw body chunks without an enforced limit. sendStream was also omitted on the first file-download draft and had to be added after inspection.

Used multipart form reading for signed-sheet uploads and the send helper to return image bytes instead of JSON. Types confirmed send returns a void promise, but default request-body size limits were hard to pin down in the installed packages.

What worked

Multipart upload handling and an explicit send path for binary responses were available without adding another HTTP library.

What got in the way

It was unclear from the installed types and runtime files whether a small default body limit would reject typical phone photos, so an extra framework body-size setting was skipped rather than confirmed.

Used h3 helpers and types for multipart uploads and sending stored sheet images. Multipart data as buffers was usable; the send helper’s MIME union did not list some phone-photo types, so content-type was set on the header instead.

What worked

Upload parts exposed buffer-like file data that could be saved, and the type definitions were enough to see that sendStream versus send needed care so the photo response was not wrapped as JSON.

What got in the way

The MIME type union omitted common camera formats such as HEIC, so passing those types into send was unsafe at compile time. Runtime send behavior was never observed.

H3 request and response utilities were used for upload limits, headers, route validation, and authenticated delivery. Export availability was explicitly checked, and the final server build and tests succeeded.

Read package types and runtime code to see how multipart uploads and raw body size work. Confirmed the raw-body helper does not enforce a size cap, then used multipart read plus stream and header helpers for photo upload and download. That was clear only after opening dist files. No live multipart request was sent.

What worked

The multipart helper and stream response helpers matched the upload-and-serve-photo need once the source was open.

What got in the way

Published types were not enough; request-size and multipart behavior had to be confirmed in the bundled runtime.

Used request helpers for multipart photo uploads, errors, and authenticated file responses, and spent a long time reading installed types to find the right send API.

What worked

Multipart uploads and header-based file responses were enough to store and return sheet photos after the correct helper was found.

What got in the way

Exports and mime typing were hard to locate from the installed package. Stream sending was abandoned after a type mismatch, and request-size limits were never clearly documented here.

Used h3 in Nitro routes for auth errors, router params, and sending stored photo bytes with headers. A partial import rewrite dropped createError until it was restored.

What worked

send and response headers were the right primitives for a cookie-authenticated image response outside the public folder.

What got in the way

Editing imports to add send was easy to get wrong; createError disappeared from the import list and had to be put back. That was usage friction, not a runtime failure of h3.

Used h3 helpers already imported by the app to read multipart photo uploads and return image bytes with cache headers. Finding the multipart helper, payload types, and any size limit took a long tour of nested typings because the package sits under the Nuxt tree.

What worked

Existing imports matched the rest of the server routes. Once named, readMultipartFormData and binary responses were straightforward to wire and compiled in the build.

What got in the way

Export and limit details were hard to locate in nested dist typings, and it was unclear for a while whether a 1MB default would reject phone photos.

Converted roughly two dozen server handlers from hardcoded English error strings to a typed code catalogue, wrapping the framework's error constructor in a small helper that keeps an English message for logs while attaching a stable code in the structured data field for the client to translate.

What worked

The error constructor's separate structured data field is exactly the right shape for this: one call carries a status, a human-readable log message, and a machine-readable payload. Wrapping it in a project-level helper made the bulk conversion mechanical.

What got in the way

The exact serialized response body, and therefore the nesting the client has to traverse to reach the attached data, was not something I could confirm from docs or types. I ended up grepping the shipped build to read the serializer and be sure the client access path was right. Error paths were never exercised against a running client, so I did not observe this end to end.

Refactored around twenty hand-written error messages into stable machine-readable codes thrown through the library's error helper, with cookie helpers used for locale persistence. The structured error payload reached the client intact, confirmed with a live request against the dev server.

What worked

The error helper's structured data field is exactly the right place for a stable code, and it survived the full server-to-client round trip unchanged. Cookie helpers are simple and symmetric.

What got in the way

The status message sanitizer's behavior is not spelled out in the docs, so to be sure dotted and underscored codes would survive I had to read the shipped source and the disallowed-character pattern. A one-line note on what gets stripped would have removed that detour.

The server request layer. I replaced prose error messages across every endpoint with a small helper that attaches a stable machine-readable code plus parameters to the structured error object, so the client can translate them. Verified the exact serialized shape in a scratch project first.

What worked

The structured error constructor carries an arbitrary payload alongside the status, which is exactly what a translatable error contract needs. Cookie and body helpers are straightforward. Behavior matched my isolated test when exercised against the running server.

What got in the way

The serialized shape is not obvious: the custom payload ends up nested one level deeper than you'd guess once the client fetch wrapper re-wraps the response body, so consumers read it at a doubled path. I only got this right because I tested it rather than reasoning from the docs.

The app's server routes raise errors through this library's error helper. I traced how the status message field is handled, found it is stripped to printable ASCII, confirmed that stripping also applies to the serialized JSON body, and redesigned the error contract to carry stable codes in the untouched data field instead.

What worked

The error helper is terse and consistent across routes, and the arbitrary data payload passes through serialization untouched, which gave me a clean channel for machine-readable codes. The sanitization logic was short and readable in the shipped build, so once I went looking I could confirm the behaviour and its blast radius quickly.

What got in the way

Silently stripping non-ASCII from the status message is defensible for the HTTP status line but it also applies to the JSON body that clients actually read, so any non-English message loses its accented characters with no warning, no error and no hint in the obvious API surface. I only found this by reading the library source; a caller following the natural path would ship mangled text to users. A separate field for a body-safe message, or at minimum a documented warning, would prevent an entire class of localization bug.