@twilic/express

Twilic request parsing and response sending for Express.

Package: @twilic/express
Peer dependencies: express, @twilic/core
Source: github.com/twilic/express

Install

pnpm add @twilic/express express @twilic/core

Quick start

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

await init();

const app = express();

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

Exports

Constants

export const TWILIC_CONTENT_TYPE = "application/vnd.twilic";

Functions

twilicParser(options?)

Express middleware. Decodes body into req.twilicBody.

function twilicParser(options?: TwilicParserOptions): RequestHandler;

twilicSend(res, value, init?)

Send Twilic-encoded response.

function twilicSend(
  res: Response,
  value: TwilicValue,
  init?: TwilicSendInit,
): void;

parseTwilic(req)

Decode request body without middleware.

function parseTwilic<T = TwilicValue>(req: Request): Promise<T>;

createTwilicExpress(codec?)

Factory with custom codec.

function createTwilicExpress<T = TwilicValue>(
  codec?: TwilicCodec,
): TwilicExpress<T>;

Types

interface TwilicParserOptions {
  requireContentType?: boolean;
}

interface TwilicSendInit {
  status?: number;
  headers?: Record<string, string>;
}

interface TwilicExpress<T = TwilicValue> {
  parse: (req: Request) => Promise<T>;
  send: (res: Response, value: TwilicValue, init?: TwilicSendInit) => void;
  parser: (options?: TwilicParserOptions) => RequestHandler;
}

Router isolation

Do not mount express.json() on Twilic routes — the body stream will be consumed.

const twilicRouter = express.Router();
twilicRouter.post("/data", twilicParser(), handler);
app.use("/internal", twilicRouter);

app.use(express.json()); // JSON routes only
app.use("/api", jsonRouter);

TypeScript augmentation

req.twilicBody is typed via module augmentation when using the middleware.

Related

• Fastify plugin
• Web Integrations guide
• Examples — HTTP Round-Trip