@sms/plugin-http

Classes

HttpError

Defined in: packages/plugins/http/src/contract.ts:85

Throw from a route handler to answer with a specific status/kind instead of a 500.

Constructors

Constructor

new HttpError(
   status, 
   message, 
   kind?
): HttpError;

Defined in: packages/plugins/http/src/contract.ts:88

Parameters

Parameter	Type
`status`	`number`
`message`	`string`
`kind`	`string`

Overrides

Error.constructor

Properties

cause?

optional cause?: unknown;

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26

Inherited from

Error.cause

kind

readonly kind: string;

Defined in: packages/plugins/http/src/contract.ts:87

message

message: string;

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from

Error.message

name

name: string;

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

Error.name

stack?

optional stack?: string;

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from

Error.stack

status

readonly status: number;

Defined in: packages/plugins/http/src/contract.ts:86

stackTraceLimit

static stackTraceLimit: number;

Defined in: node_modules/.pnpm/@types+node@22.20.1/node_modules/@types/node/globals.d.ts:68

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from

Error.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.pnpm/@types+node@22.20.1/node_modules/@types/node/globals.d.ts:52

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Inherited from

Error.captureStackTrace

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/.pnpm/@types+node@22.20.1/node_modules/@types/node/globals.d.ts:56

Parameters

Parameter	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

Error.prepareStackTrace

Interfaces

ErrorBody

Defined in: packages/plugins/http/src/contract.ts:68

The one error shape every baseline route speaks: { error: { message, kind } }. kind is a short machine-readable tag a client can switch on (auth, not_found, validation, internal, …).

Properties

error

error: {
  kind: string;
  message: string;
  plugin?: string;
};

Defined in: packages/plugins/http/src/contract.ts:69

kind

kind: string;

message

message: string;

plugin?

optional plugin?: string;

HttpService

Defined in: packages/plugins/http/src/contract.ts:131

Methods

Parameter	Type
`request`	`Request`

routes()

routes(): {
  description?: string;
  method: string;
  owner: string;
  path: string;
}[];

Defined in: packages/plugins/http/src/contract.ts:133

Returns

{ description?: string; method: string; owner: string; path: string; }[]

Route

Defined in: packages/plugins/http/src/contract.ts:124

Properties

description?

optional description?: string;

Defined in: packages/plugins/http/src/contract.ts:127

method

method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "*";

Defined in: packages/plugins/http/src/contract.ts:125

path

path: string;

Defined in: packages/plugins/http/src/contract.ts:126

RouteRequest

Defined in: packages/plugins/http/src/contract.ts:14

JSON-safe request view, so agent plugins (across the executor boundary) can handle routes too.

Properties

body

body: unknown;

Defined in: packages/plugins/http/src/contract.ts:20

headers

headers: Record<string, string>;

Defined in: packages/plugins/http/src/contract.ts:19

method

method: string;

Defined in: packages/plugins/http/src/contract.ts:15

params

params: Record<string, string>;

Defined in: packages/plugins/http/src/contract.ts:17

path

path: string;

Defined in: packages/plugins/http/src/contract.ts:16

query

query: Record<string, string>;

Defined in: packages/plugins/http/src/contract.ts:18

Type Aliases

RouteResult

type RouteResult = Response | unknown;

Defined in: packages/plugins/http/src/contract.ts:27

A handler returns a Response (use the json() / html() / text() helpers) or any JSON value, which is sent as 200 application/json. Handlers running in an executor can only return JSON values.

Variables

HTTP_KEY

const HTTP_KEY: "http" = 'http';

Defined in: packages/plugins/http/src/contract.ts:9

Key under which the http plugin provides HttpService.

httpPlugin

const httpPlugin: SystemPlugin;

Defined in: packages/plugins/http/src/index.ts:43

ROUTE_POINT

const ROUTE_POINT: "route" = 'route';

Defined in: packages/plugins/http/src/contract.ts:11

Extension point for { method, path, handler(req) } items.

Functions

bodyOf()

function bodyOf(req): Record<string, unknown>;

Defined in: packages/plugins/http/src/contract.ts:119

The JSON object body of a request, or {} — for handlers that take { ...fields }.

Parameters

Parameter	Type
`req`	`RouteRequest`

Returns

Record<string, unknown>

cookieValue()

function cookieValue(req, name): string | undefined;

Defined in: packages/plugins/http/src/contract.ts:97

Value of one cookie on a request view (cookie header), or undefined.

Parameters

Parameter	Type
`req`	`RouteRequest`
`name`	`string`

Returns

string | undefined

errorJson()

function errorJson(
   message, 
   status?, 
   kind?
): Response;

Defined in: packages/plugins/http/src/contract.ts:72

Parameters

Parameter	Type	Default value
`message`	`string`	`undefined`
`status`	`number`	`500`
`kind`	`string`	`...`

Returns

Response

html()

function html(body, status?): Response;

Defined in: packages/plugins/http/src/contract.ts:32

Parameters

Parameter	Type	Default value
`body`	`string`	`undefined`
`status`	`number`	`200`

Returns

Response

json()

function json(
   body, 
   status?, 
   headers?
): Response;

Defined in: packages/plugins/http/src/contract.ts:30

Parameters

Parameter	Type	Default value
`body`	`unknown`	`undefined`
`status`	`number`	`200`
`headers`	`Record`<`string`, `string`>	`{}`

Returns

Response

matchPath()

function matchPath(pattern, path): Record<string, string> | null;

Defined in: packages/plugins/http/src/contract.ts:151

Parameters

Parameter	Type
`pattern`	`string`
`path`	`string`

Returns

Record<string, string> | null

serializeCookie()

function serializeCookie(
   name, 
   value, 
   opts?
): string;

Defined in: packages/plugins/http/src/contract.ts:106

A set-cookie header value. Defaults: HttpOnly, SameSite=Lax, Path=/. maxAge 0 deletes.

Parameters

Parameter	Type
`name`	`string`
`value`	`string`
`opts`	{ `maxAge?`: `number`; `path?`: `string`; `sameSite?`: `"Lax"` \| `"Strict"` \| `"None"`; `secure?`: `boolean`; }
`opts.maxAge?`	`number`
`opts.path?`	`string`
`opts.sameSite?`	`"Lax"` \| `"Strict"` \| `"None"`
`opts.secure?`	`boolean`

Returns

string

sse()

function sse(events, status?): Response;

Defined in: packages/plugins/http/src/contract.ts:47

Server-sent events: each item is one data: <json> frame, written as soon as it is produced. If the iterable throws, the stream ends with { type: 'error', message } so a client always sees a terminal frame. The producer is not cancelled when the client goes away — the loop keeps it running on purpose.