For AI agents: the documentation index is at /docs/interbox/llms.txt. A Markdown version of this page is available at /docs/interbox/reference/core.md or by requesting it with the Accept: text/markdown header.
Interbox Docs

/core

import type { ... } from "@health-samurai/interbox/core";

Pure stage contracts shared by the SDK (descriptors, authoring) and the engine (factories, runtime) — types + light pure helpers only, no drizzle/pg, so a workspace's bundle stays lean.

A workspace author rarely imports from /core directly. Everything you use day-to-day — defineMapper, MapperContext, env(), the builtin config types — is exported from the package root or /builtins, and map()'s parameter types are inferred for you. This subpath exists so the engine and the SDK share one set of type definitions and can't drift.

What's in it, by category:

categorytypeswho cares
authoring valuesStr, Num, Resolvedyou, occasionally — see Env & Config
mapper contractsMapperDefinition, MapperContext, MapperSource, MappedCode, ParserOutputMap, ParserTypeyou, via defineMapper — usually inferred, import only to annotate helpers
error taxonomydomainError, ERROR_GROUPS, ErrorGroupyou — re-exported from the root, see Errors
payloadsPayloadItem, PayloadBody, bodyFromBytes, bodyFromStream, concatChunks, PayloadBodyConsumed, ConfiguredPreprocessor, Preprocessor, PreprocessorDefinitionyou, when a source you define runs a preprocess chain or you declare a preprocessor — all but concatChunks and ConfiguredPreprocessor are re-exported from the root, the latter from /builtins; see Preprocessing what a source read and Defining a preprocessor
stage runtime contractsSourceDefinition/SenderDefinition/ParserDefinition + their *Config/*Entry/*Factory/*Instance siblings, Runnerthe engine, except SourceDefinition, which a workspace implements through defineSource — see Sources

One import that does come up: annotating a mapper helper function that takes the context —

import type { MapperContext } from "@health-samurai/interbox/core";

async function resolveObservationCode(ctx: MapperContext, code: string) {
  return ctx.translate("obs-codes", code);
}

For the exact shapes of the mapper contracts, see Mapper authoring. For the engine-side runtime contracts, read src/core/*.ts in the package — they're small, documented files, and if you're implementing one you're working on the engine, not a workspace.

Last updated: