@oaspect/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oaspect contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,14 @@
+# @oaspect/core
+
+Framework-free OpenAPI processing behind [oaspect](https://github.com/oaspect/oaspect):
+
+- `loadSpecText()`, `parseSpec()`, `normalizeSpec()`: JSON or YAML, Swagger 2.0 → OpenAPI 3.0
+- `buildModel()`: tags → operations with resolved parameters, bodies and responses
+- `resolveSchema()`, `childrenOf()`, `typeLabel()`: `$ref`/`allOf` resolution for schema trees
+- `exampleFromSchema()`, `mediaExample()`: example values
+- `buildRequest()`, `defaultValues()`, `defaultBody()`: concrete HTTP requests
+- `SNIPPET_LANGUAGES`, `resolveSnippet()`: code samples for 30 clients
+- `parseMarkdown()`, `selectLocale()`, `localize()`: Markdown with `:::lang` blocks and `x-i18n`
+- `tokenize()`: syntax highlighting tokens
+
+Written in TypeScript; ships ESM with type definitions. MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,358 @@
+/** Any OpenAPI object (schema, parameter, response…), vendor extensions included. */
+type OpenAPIObject = Record<string, any>;
+interface OpenAPIDocument extends OpenAPIObject {
+    openapi?: string;
+    swagger?: string;
+    info?: OpenAPIObject;
+    servers?: ServerObject[];
+    tags?: OpenAPIObject[];
+    paths?: Record<string, OpenAPIObject>;
+    components?: OpenAPIObject;
+}
+interface ServerObject extends OpenAPIObject {
+    url: string;
+    description?: string;
+    variables?: Record<string, {
+        default?: string;
+        enum?: string[];
+        description?: string;
+    }>;
+}
+type HttpMethod = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";
+interface ResolvedSchema {
+    schema: OpenAPIObject;
+    /** Component name when the schema came from a $ref. */
+    name?: string;
+}
+type SchemaChildren = {
+    kind: "properties";
+} | ({
+    kind: "items" | "map";
+} & ResolvedSchema) | {
+    kind: "oneOf" | "anyOf";
+    variants: ResolvedSchema[];
+} | null;
+interface LinkInfo {
+    name: string;
+    operationId?: string;
+    operationRef?: string;
+    /** Target parameter name → runtime expression or value. */
+    parameters: Record<string, unknown>;
+    requestBody?: unknown;
+    description: string;
+}
+interface ResponseInfo {
+    status: string;
+    description: string;
+    "x-i18n"?: OpenAPIObject;
+    content: Record<string, OpenAPIObject>;
+    headers: Record<string, OpenAPIObject>;
+    links: LinkInfo[];
+}
+interface CallbackInfo {
+    name: string;
+    /** Operations keyed by runtime expression ("{$request.body#/callbackUrl}") in `path`. */
+    operations: Operation[];
+}
+interface Operation {
+    /** Stable id for links: "operation/<operationId>" or "operation/<method>-<path>". */
+    anchor: string;
+    /** "webhook": sent by the API (3.1 webhooks); "callback": nested under an operation. */
+    kind: "operation" | "webhook" | "callback";
+    method: HttpMethod;
+    path: string;
+    summary: string;
+    description: string;
+    "x-i18n"?: OpenAPIObject;
+    operationId?: string;
+    deprecated: boolean;
+    tags: string[];
+    parameters: OpenAPIObject[];
+    requestBody: OpenAPIObject | null;
+    responses: ResponseInfo[];
+    callbacks: CallbackInfo[];
+    security: OpenAPIObject[];
+    servers: ServerObject[];
+}
+interface TagGroup {
+    name: string;
+    anchor: string;
+    description: string;
+    "x-i18n"?: OpenAPIObject;
+    operations: Operation[];
+}
+interface SchemaEntry {
+    name: string;
+    anchor: string;
+    schema: OpenAPIObject;
+}
+interface ApiModel {
+    openapi: string;
+    info: OpenAPIObject;
+    servers: ServerObject[];
+    securitySchemes: Record<string, OpenAPIObject>;
+    tags: TagGroup[];
+    operations: Operation[];
+    /** OpenAPI 3.1 webhooks; `path` holds the webhook name. */
+    webhooks: Operation[];
+    schemas: SchemaEntry[];
+}
+/** Values entered for an operation's parameters, by location. */
+interface ParameterValues {
+    path: Record<string, string>;
+    query: Record<string, string>;
+    header: Record<string, string>;
+    cookie: Record<string, string>;
+}
+/** One part of a multipart/form-data body: a text value or a file. */
+interface FormField {
+    name: string;
+    /** Text value (ignored for files). */
+    value?: string;
+    /** Present for file parts; `name` is the file name shown in samples. */
+    file?: {
+        name: string;
+        type?: string;
+    };
+}
+/** A concrete HTTP request, as produced by buildRequest(). */
+interface HttpRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    /** Text body (JSON, form-urlencoded…). */
+    body?: string;
+    /**
+     * multipart/form-data parts. Set instead of `body`; there is no
+     * Content-Type header because clients add it with the boundary.
+     */
+    form?: FormField[];
+}
+interface SnippetClient {
+    key: string;
+    label: string;
+    build: (request: HttpRequest) => string;
+}
+interface SnippetLanguage {
+    key: string;
+    label: string;
+    /** Tokenizer language for tokenize(). */
+    highlight: string;
+    clients: SnippetClient[];
+}
+interface Token {
+    /** Token class ("string", "keyword"…), or null for plain text. */
+    type: string | null;
+    text: string;
+}
+type InlineNode = {
+    type: "text";
+    value: string;
+} | {
+    type: "br";
+} | {
+    type: "code";
+    value: string;
+} | {
+    type: "strong" | "em" | "del";
+    children: InlineNode[];
+} | {
+    type: "link";
+    href: string;
+    title?: string;
+    children: InlineNode[];
+} | {
+    type: "image";
+    src: string;
+    alt: string;
+    title?: string;
+};
+interface ListItem {
+    checked: boolean | null;
+    children: MarkdownBlock[];
+}
+type MarkdownBlock = {
+    type: "paragraph";
+    children: InlineNode[];
+} | {
+    type: "heading";
+    level: number;
+    children: InlineNode[];
+} | {
+    type: "code";
+    language: string;
+    text: string;
+} | {
+    type: "blockquote";
+    children: MarkdownBlock[];
+} | {
+    type: "hr";
+} | {
+    type: "list";
+    ordered: boolean;
+    start: number | null;
+    loose: boolean;
+    items: ListItem[];
+} | {
+    type: "table";
+    align: ("left" | "right" | "center" | null)[];
+    header: InlineNode[][];
+    rows: InlineNode[][][];
+} | {
+    type: "lang";
+    locales: string[];
+    children: MarkdownBlock[];
+} | {
+    type: "lang-selected";
+    locale: string;
+    children: MarkdownBlock[];
+};
+
+declare function resolvePointer(spec: OpenAPIObject, ref: unknown): any;
+declare function refName(ref: string): string;
+declare function deref(spec: OpenAPIObject, node: any): {
+    node: OpenAPIObject;
+    ref?: string;
+};
+
+declare function resolveSchema(spec: OpenAPIObject, input: unknown): ResolvedSchema;
+declare function inferType(schema: OpenAPIObject): string;
+declare function typeLabel(spec: OpenAPIObject, schema: OpenAPIObject, name?: string): string;
+declare function constraintsOf(schema: OpenAPIObject): string[];
+declare function childrenOf(spec: OpenAPIObject, schema: OpenAPIObject): SchemaChildren;
+
+declare function exampleFromSchema(spec: OpenAPIObject, input: unknown, seen?: Set<string>, depth?: number): any;
+declare function mediaExample(spec: OpenAPIObject, media: OpenAPIObject | undefined): any;
+declare function mediaExamples(spec: OpenAPIObject, media: OpenAPIObject | undefined): {
+    key: string;
+    summary: string;
+    value: unknown;
+}[];
+
+declare const HTTP_METHODS: HttpMethod[];
+declare function slugify(value: unknown): string;
+declare const tagAnchor: (name: string) => string;
+declare const modelAnchor: (name: string) => string;
+declare function buildModel(spec: OpenAPIDocument): ApiModel;
+declare function serverUrl(server: ServerObject, values?: Record<string, string>): string;
+/** Finds the operation a link points to (operationId, or a local operationRef). */
+declare function linkTarget(model: ApiModel, link: LinkInfo): Operation | undefined;
+
+declare function jsonMediaType(content?: Record<string, unknown>): string | undefined;
+declare function parameterExample(spec: OpenAPIObject, param: OpenAPIObject): any;
+declare function defaultValues(spec: OpenAPIObject, operation: Operation): ParameterValues;
+interface DefaultBody {
+    contentType: string | null;
+    /** Text body for JSON and other text media types. */
+    body: string;
+    /** Parts for multipart/form-data. */
+    form?: FormField[];
+}
+declare const isMultipart: (contentType?: string | null) => boolean;
+/**
+ * Parts for a multipart/form-data body from its schema: binary properties
+ * become file parts, everything else a text part with an example value.
+ */
+declare function defaultForm(spec: OpenAPIObject, media: OpenAPIObject | undefined): FormField[];
+declare function defaultBody(spec: OpenAPIObject, operation: Operation): DefaultBody;
+declare function formEncode(value: unknown): string;
+interface BuildRequestOptions {
+    server?: ServerObject;
+    values: Partial<ParameterValues>;
+    body?: string;
+    /** multipart/form-data parts; used instead of `body` when given. */
+    form?: FormField[];
+    contentType?: string | null;
+    headers?: Record<string, string>;
+}
+declare function buildRequest(operation: Pick<Operation, "method" | "path">, { server, values, body, form, contentType, headers }: BuildRequestOptions): HttpRequest;
+
+declare const SNIPPET_LANGUAGES: SnippetLanguage[];
+declare function resolveSnippet(selection: unknown): {
+    language: SnippetLanguage;
+    client: SnippetLanguage["clients"][number];
+    selection: string;
+};
+
+declare function localize(node: OpenAPIObject | null | undefined, field: string, locale?: string): any;
+
+declare function parseBlocks(lines: string[]): MarkdownBlock[];
+declare function parseInline(text: string, { links }?: {
+    links?: boolean;
+}): InlineNode[];
+declare function selectLocale(blocks: MarkdownBlock[], locale: string, fallbacks?: string[]): MarkdownBlock[];
+declare function parseMarkdown(source: unknown): MarkdownBlock[];
+declare function safeUrl(url: unknown, { image }?: {
+    image?: boolean;
+}): string | null;
+
+declare function tokenize(code: string, language: string): Token[];
+
+interface Credential {
+    /** Bearer / http token, API key or OAuth2 / OpenID Connect access token. */
+    token?: string;
+    username?: string;
+    password?: string;
+    clientId?: string;
+    clientSecret?: string;
+    /** Space-separated OAuth2 scopes for token requests. */
+    scopes?: string;
+}
+type Credentials = Record<string, Credential>;
+interface AuthParts {
+    headers: Record<string, string>;
+    query: Record<string, string>;
+    cookies: Record<string, string>;
+}
+interface SecurityRequirement {
+    /** Scheme names that must all be present. Empty: auth optional. */
+    schemes: string[];
+    scopes: Record<string, string[]>;
+}
+/** The operation's requirements (alternatives), from its own or the global `security`. */
+declare function securityRequirements(operation: Pick<Operation, "security">): SecurityRequirement[];
+declare function hasCredential(scheme: OpenAPIObject | undefined, credential: Credential | undefined): boolean;
+/**
+ * Headers, query parameters and cookies for an operation: the first
+ * requirement whose schemes all have credentials wins. Nothing is applied
+ * when no requirement can be met.
+ */
+declare function applySecurity(schemes: Record<string, OpenAPIObject>, requirements: SecurityRequirement[], credentials: Credentials): AuthParts;
+/** Short description of a scheme for labels: "Bearer", "API key (header: X-Key)"… */
+declare function describeScheme(scheme: OpenAPIObject): string;
+/** OAuth2 flows a viewer can complete itself (no browser redirect). */
+declare const TOKEN_FLOWS: readonly ["clientCredentials", "password"];
+/** Token request (RFC 6749 §4.3 / §4.4) for a clientCredentials or password flow. */
+declare function buildTokenRequest(flowName: (typeof TOKEN_FLOWS)[number], flow: OpenAPIObject, credential: Credential): HttpRequest;
+
+declare function convertSchema(schema: any): any;
+/** Converts a Swagger 2.0 document to OpenAPI 3.0.3. */
+declare function convertSwagger2(doc: OpenAPIObject): OpenAPIDocument;
+
+declare const EXTERNAL_KEY = "x-oaspect-external";
+interface ExternalRefOptions {
+    /** URL of the document itself; relative refs resolve against it. */
+    baseUrl: string;
+    /** Loads a referenced document's text (fetch, fs…). */
+    read: (url: string) => Promise<string>;
+    /** Upper bound on loaded documents. Default 100. */
+    maxDocuments?: number;
+}
+/** True when the document contains a $ref to another file or URL. */
+declare function hasExternalRefs(node: unknown): boolean;
+declare function resolveExternalRefs(doc: OpenAPIDocument, { baseUrl, read, maxDocuments }: ExternalRefOptions): Promise<OpenAPIDocument>;
+
+/** Parses JSON, falling back to YAML. Throws with a readable message. */
+declare function parseSpec(text: string): unknown;
+declare function isOpenApiDocument(value: unknown): value is OpenAPIDocument;
+/** OpenAPI 3.x documents pass through; Swagger 2.0 documents are converted. */
+declare function normalizeSpec(doc: OpenAPIDocument): OpenAPIDocument;
+/** parseSpec + validation + normalizeSpec. */
+declare function loadSpecText(text: string): OpenAPIDocument;
+/**
+ * loadSpecText + external $ref resolution. Without `read`, external refs are
+ * left as they are (the viewer shows them as unresolved).
+ */
+declare function loadSpec(text: string, options?: Partial<ExternalRefOptions>): Promise<OpenAPIDocument>;
+
+export { type ApiModel, type AuthParts, type BuildRequestOptions, type CallbackInfo, type Credential, type Credentials, type DefaultBody, EXTERNAL_KEY, type ExternalRefOptions, type FormField, HTTP_METHODS, type HttpMethod, type HttpRequest, type InlineNode, type LinkInfo, type ListItem, type MarkdownBlock, type OpenAPIDocument, type OpenAPIObject, type Operation, type ParameterValues, type ResolvedSchema, type ResponseInfo, SNIPPET_LANGUAGES, type SchemaChildren, type SchemaEntry, type SecurityRequirement, type ServerObject, type SnippetClient, type SnippetLanguage, TOKEN_FLOWS, type TagGroup, type Token, applySecurity, buildModel, buildRequest, buildTokenRequest, childrenOf, constraintsOf, convertSchema, convertSwagger2, defaultBody, defaultForm, defaultValues, deref, describeScheme, exampleFromSchema, formEncode, hasCredential, hasExternalRefs, inferType, isMultipart, isOpenApiDocument, jsonMediaType, linkTarget, loadSpec, loadSpecText, localize, mediaExample, mediaExamples, modelAnchor, normalizeSpec, parameterExample, parseBlocks, parseInline, parseMarkdown, parseSpec, refName, resolveExternalRefs, resolvePointer, resolveSchema, resolveSnippet, safeUrl, securityRequirements, selectLocale, serverUrl, slugify, tagAnchor, tokenize, typeLabel };