@twilic/express

Express middleware and helpers for Twilic binary request and response bodies.

Install

pnpm add @twilic/express express @twilic/core

Usage

import express from "express";
import { twilicParser, twilicSend } from "@twilic/express";

const app = express();

app.post("/users", twilicParser(), (req, res) => {
  twilicSend(res, { ok: true, received: req.twilicBody });
});

Do not mount express.json() before Twilic routes on the same path, or the request body stream will already be consumed. Use a dedicated router or place twilicParser() on routes that do not use JSON body parsing.

API

• TWILIC_CONTENT_TYPE
• parseTwilic(req, options?)
• twilicSend(res, value, init?)
• twilicParser(options?)
• createTwilicExpress(codec?)

Request body limits

twilicParser() and parseTwilic() limit the body to 1,048,576 bytes (1 MiB) by default. The same options apply to factory-created parser() and parse() helpers. Set limit to a non-negative safe integer in bytes:

twilicParser({ limit: 256 * 1024 });
await parseTwilic(req, { limit: 256 * 1024 });

The reader counts received chunks, including requests without Content-Length, and stops before decoding an oversized body. Middleware responds with HTTP 413. A direct parse() call rejects with an error carrying status: 413. limit: 0 permits an empty body only. Previously accepted larger requests now require an explicit higher limit; decoded collection limits still apply separately.

Mount the parser before other middleware consumes the request stream. Also configure request timeouts and authentication for the route.

Runnable example

Clone twilic/examples and run the HTTP round-trip demo:

pnpm example:http-roundtrip          # Express server
pnpm example:http-roundtrip:client   # @twilic/fetch client

See http-roundtrip/.

Changelog

See docs/CHANGELOG.md.

Publish to npm

The package ships build artifacts from dist/.

Local dry run:

pnpm build
pnpm pack

GitHub Actions publish uses npm trusted publishing (OIDC)—no long-lived NPM_TOKEN secret.

One-time setup on npmjs.com: open the package → Settings → Trusted Publisher → GitHub Actions, then set Organization or user twilic, Repository express, and Workflow filename publish-npm.yml (exact name, including .yml). See also GitHub Actions OIDC.

Release steps:

1. Update docs/CHANGELOG.md and bump version in package.json.
2. Create and push matching tag v<version>.

Example:

git tag v0.1.0
git push origin v0.1.0

The workflow .github/workflows/publish-npm.yml verifies tag/version match, runs tests, and then runs npm publish (OIDC authentication via id-token: write).

Contributing

See docs/CONTRIBUTING.md.

License

This project is licensed under the MIT License - see the LICENSE file for details.