# @smithers-orchestrator/openapi — src

Turns an OpenAPI 3.x spec into AI SDK (`ai`) tools. The pipeline:

1. **Load** — `loadSpecEffect.js` (URL / file / raw text / object, Effect-based)
   or `loadSpecSync.js` (no URLs), both parsing via `_specHelpers.js`
   `parseSpecText`.
2. **Extract** — `extractOperations.js` walks `paths` × `HTTP_METHODS`
   (`types.js`), derefs `$ref`s via `ref-resolver.js`, merges path/operation
   parameters, and generates missing operationIds (`_specHelpers.js`).
3. **Schema** — `buildOperationSchema.js` + `jsonSchemaToZod.js` build the Zod
   input schema; `getRequestBodyArgName.js` picks a body key that cannot
   collide with a parameter name.
4. **Tools** — `tool-factory/` assembles the tools and executes HTTP calls.

File map: camelCase `.js` files are the current one-export-per-file modules;
the kebab-case files (`spec-parser.js`, `schema-converter.js`,
`tool-factory.js`) are thin legacy re-export barrels. The package export map
has a `./*` → `./src/*.js` wildcard and tests import many files directly, so
every file here is public surface — do not move, rename, or drop exports.

Type sidecars: every PascalCase `.ts` file (`OpenApiSpec.ts`,
`ParsedOperation.ts`, …) is type-only and consumed from JSDoc. Blocks between
`@smithers-type-exports-begin/end` (`index.js`, `types.js`) are tool-managed —
never hand-edit them. `index.d.ts` is generated by `tsup --dts-only`.

Gotchas: `SPEC_SOURCE_URL` (`specSourceUrl.js`) is a registered symbol stamped
on fetched specs so a relative `servers[].url` can be resolved against the
document URL. `metrics.js` re-exports the tool-call counters/histogram from
`@smithers-orchestrator/observability` and backs the `./metrics` export.
