@amritk/asyncapi 0.1.0 → 0.3.0

package/AI.md

@@ -1,8 +1,9 @@
 # @amritk/asyncapi — notes for AI coding agents
 
 Extract every message payload/headers schema from an AsyncAPI 2.x/3.0 document
-as self-contained JSON Schema 2020-12, ready for the mjst generators. Full
-reference is [README.md](./README.md).
+as self-contained JSON Schema 2020-12 for the mjst generators, and project each
+channel onto an `@amritk/api` `defineMessages` contract. Full reference is
+[README.md](./README.md).
 
 > Pre-alpha: APIs change in **minor** versions.
 
@@ -16,6 +17,20 @@ const schemas = listMessageSchemas(model)
 // → [{ subDir: 'channels/lighting-measured/light-measured', rootTypeName: 'LightMeasured', schema }, ...]
 ```
 
+## Channel contracts
+
+```ts
+import { buildChannelContract } from '@amritk/asyncapi'
+
+const contract = buildChannelContract(model.channels[0], { discriminator: 'event' })
+// → { exportName: 'lobbyMessages', discriminator: 'event',
+//     clientToServer: { say: schema }, serverToClient: { said: schema }, issues: [] }
+// Keys are the wire tags the payloads pin, not the AsyncAPI message names.
+```
+
+Hand the two direction maps straight to `defineMessages` — that is what
+`mjst --input asyncapi --message-contracts` writes out.
+
 ## Gotchas — where agents fail
 
 1. **It takes an already-parsed document.** No filesystem, no YAML, no network —
@@ -23,8 +38,10 @@ const schemas = listMessageSchemas(model)
    `@amritk/resolve-refs` *before* calling. External `$ref`s still present are
    reported as issues, not fetched.
 2. **Problems are collected, not thrown.** Read `model.issues`; only "this is
-   not an AsyncAPI document" throws. An Avro/Protobuf `schemaFormat` skips that
-   one schema with an issue.
+   not an AsyncAPI document" throws. An Avro `schemaFormat` is *converted* via
+   `@amritk/adapters` (pass `{ avroEncoding: 'avro-json' }` for the wire shape
+   instead of the decoded one); a Protobuf one, or an Avro schema the converter
+   rejects, skips that one schema with an issue.
 3. **Directions are application-relative.** 2.x `publish` → `receive`,
    `subscribe` → `send` (the app is the server). Absent when no operation names
    the message.
@@ -33,3 +50,20 @@ const schemas = listMessageSchemas(model)
    message's schema never affects another.
 5. **Root type names come from message identity**, not schema `title` — two
    messages titled "Event" stay distinct.
+6. **A contract's map key is the wire tag, not the message name.** `receive` →
+   `clientToServer`, `send` → `serverToClient`, and the discriminator property is
+   *stripped* from each payload: `@amritk/api` reads the tag off the frame to
+   pick the message, then removes it before validating, and refuses a schema
+   that still declares it. The key comes from the value the payload pins the tag
+   to (`type: { const: 'bot_added' }` → key `bot_added`), and falls back to the
+   message name only when the payload pins nothing. Two messages pinning the
+   same tag in one direction collide: first wins, second reported.
+7. **The discriminator has a priority order**: `x-mjst: { discriminator }` on
+   the channel, then the caller's argument, then `'type'`. The document wins
+   over the argument on purpose — one override covers a whole run, and a run
+   may span channels that disagree.
+8. **Contracts carry payloads only, never headers.** `listMessageSchemas` gives
+   a message's `headers` its own `<message>-headers/` tree, but
+   `buildChannelContract` ignores headers: an `@amritk/api` contract describes
+   WebSocket frames, which have none. For a Kafka/MQTT document the headers
+   types are generated and yours to apply at the broker boundary.

package/README.md

@@ -2,7 +2,7 @@
 
 # @amritk/asyncapi
 
-**Extract JSON Schemas from AsyncAPI 2.x/3.0 documents for the mjst generators.**
+**Extract JSON Schemas — and `@amritk/api` channel contracts — from AsyncAPI 2.x/3.0 documents.**
 
 ![status](https://img.shields.io/badge/status-pre--alpha-ef4444?style=flat-square) 
 ![version](https://img.shields.io/npm/v/@amritk/asyncapi?style=flat-square&logo=npm&logoColor=white&label=version&color=6366f1) 
@@ -21,7 +21,9 @@
 
 What "self-contained" buys: the AsyncAPI default schema dialect (a draft-07 superset) is upgraded to 2020-12 conventions, OpenAPI-format payloads get `nullable` folded into their `type`, and every `$ref` into the document's `#/components/schemas/...` is rebased into a local `$defs` with the referenced components copied in transitively — so each extracted schema stands alone as a generator input.
 
-Both majors normalize into one 3.0-shaped model. Directions are named from the application's point of view (2.x `publish` → `receive`, `subscribe` → `send`), matching [`@amritk/api`](../api)'s message contracts. Non-JSON-Schema payloads (`schemaFormat`: Avro, Protobuf, …) are skipped per message with a recorded issue — one Avro payload never costs the document's other messages.
+It also projects each channel onto a [`@amritk/api`](../api) **messages contract**: the two directions AsyncAPI declares become `clientToServer`/`serverToClient`, each message's name becomes its wire discriminator value, and the discriminator property is stripped out of the payload — which is exactly the shape `defineMessages` takes. That projection is what `mjst --input asyncapi --message-contracts` writes to disk.
+
+Both majors normalize into one 3.0-shaped model. Directions are named from the application's point of view (2.x `publish` → `receive`, `subscribe` → `send`), matching [`@amritk/api`](../api)'s message contracts. An Avro `schemaFormat` is **converted**, not skipped — [`@amritk/adapters`](../adapters) already reads Avro, so those payloads reach the generators like any other. A payload in a language nothing here reads (Protobuf, RAML) is skipped per message with a recorded issue, and so is an Avro schema the converter rejects — one bad payload never costs the document's other messages.
 
 ---
 
@@ -64,16 +66,48 @@ for (const channel of model.channels) {
 const schemas = listMessageSchemas(model)
 ```
 
+### Channel contracts
+
+```ts
+import { buildChannelContract } from '@amritk/asyncapi'
+import { defineMessages } from '@amritk/api'
+
+for (const channel of model.channels) {
+  const contract = buildChannelContract(channel)
+  for (const issue of contract.issues) console.warn(`${issue.path}: ${issue.message}`)
+
+  // The two maps are keyed by the value a frame carries on the wire, payloads
+  // already stripped of the tag — hand them straight to defineMessages.
+  const messages = defineMessages({
+    discriminator: contract.discriminator,
+    clientToServer: contract.clientToServer,
+    serverToClient: contract.serverToClient,
+  })
+}
+```
+
+The discriminator is resolved in priority order: `x-mjst: { discriminator }` on the channel, then the `discriminator` option, then `'type'` (matching `@amritk/api`'s default). The document wins over the option deliberately — one option covers a whole run, and a run may span channels that disagree.
+
+**The key is the tag, not the name.** A payload usually states its own tag — `type: { const: 'bot_added' }` is how a channel of alternatives says which message is which — and that value becomes the contract key, because it is what actually arrives on the wire. The AsyncAPI message *name* is only the fallback for a payload that pins nothing; it is a document-authoring handle, and 2.x messages inside a `oneOf` frequently have none at all. Slack's RTM document names a message `botAdded` and tags it `bot_added`; keying on the name would emit a contract listening for a frame that never comes.
+
+Two messages that pin the *same* tag in the *same* direction are one frame shape with two descriptions, so the first wins and the second is reported (Slack declares two messages for its single `bot_added` event). A payload that constrains the tag without pinning it to one string — `type: { type: 'string' }`, a multi-member `enum`, a non-string `const` — names no message the runtime could select, and is skipped with an issue.
+
+**Headers are not part of a contract.** `listMessageSchemas` emits a message's `headers` schema as its own generatable tree, but `buildChannelContract` projects payloads only: `@amritk/api` message contracts describe WebSocket frames, which carry no headers of their own. For a Kafka or MQTT document the headers types are still generated (under `<message>-headers/`) — they are simply yours to apply at the broker boundary, not something the socket runtime validates.
+
 Cross-file and remote `$ref`s are the loader's job: resolve them first (for example with [`@amritk/resolve-refs`](../resolve-refs)); a still-unresolved external reference is reported as an issue, never fetched.
 
 ---
 
 ## API
 
-- **`extractAsyncApi(document)`** → `AsyncApiModel` — the normalized document: `version`, `major`, `title?`, `channels` (each with `key`, `address?`, `messages`), and collected `issues`. Throws only when the input is not an AsyncAPI document at all.
+- **`extractAsyncApi(document, options?)`** → `AsyncApiModel` — the normalized document: `version`, `major`, `title?`, `channels` (each with `key`, `address?`, `messages`), and collected `issues`. Throws only when the input is not an AsyncAPI document at all. `options.avroEncoding` picks which JSON shape an Avro payload describes: `'json'` (default) is the decoded object an application works with, `'avro-json'` is the spec's JSON encoding as it travels on the wire.
 - **`listMessageSchemas(model, issues?)`** → `ExtractedSchema[]` — one `{ subDir, rootTypeName, schema }` per generatable payload/headers, with deterministic collision-suffixed directory tokens; collision issues are appended to `model.issues` (or to the `issues` array you pass).
+- **`buildChannelContract(channel, options?)`** → `ChannelContract` — one channel as `{ exportName, discriminator, clientToServer, serverToClient, issues }`, ready for `defineMessages`.
+- **`resolveDiscriminator(channel, override?)`** / **`DEFAULT_DISCRIMINATOR`** — the priority order above, and the `'type'` fallback.
+- **`stripDiscriminator(payload, discriminator)`** → `{ schema, tag? }` or `{ issue }` — the payload with its tag removed plus the value it pinned the tag to, or why neither could be read.
+- **`sanitizeToken(value, fallback)`** — the filesystem- and import-safe token both output layouts name a channel or message with.
 - **`detectAsyncApiVersion(document)`** — the `asyncapi` version and its major, or `undefined`.
-- **`classifySchemaFormat(schemaFormat)`** — which JSON Schema dialect a `schemaFormat` names (`'asyncapi' | 'draft-07' | '2020-12' | 'openapi'`), or `'unsupported'`.
+- **`classifySchemaFormat(schemaFormat)`** — which schema language a `schemaFormat` names (`'asyncapi' | 'draft-07' | '2020-12' | 'openapi' | 'avro'`), or `'unsupported'`.
 - **`mergeTraits(target, traits, precedence)`** — trait application as an RFC 7386 JSON Merge Patch (recursive, so nested contributions from both sides survive); `precedence` is `'trait'` for 2.x (traits override the target) or `'target'` for 3.0 (the target wins). Applied before `schemaFormat` is read.
 
 ---

package/dist/build-channel-contract.d.ts

@@ -0,0 +1,53 @@
+import type { ExtractionIssue, NormalizedChannel } from './types.js';
+/** One direction's message map: wire name → payload schema, ready for `defineMessages`. */
+export type ContractDirection = {
+    readonly [name: string]: Record<string, unknown>;
+};
+/**
+ * One channel projected onto an `@amritk/api` messages contract.
+ *
+ * The map keys *are* the wire discriminator values — that is what
+ * `defineMessages` means by a message name — taken from the value the payload
+ * pins the discriminator to, and falling back to the AsyncAPI message name only
+ * when the payload pins nothing. A message that cannot be given a legal key or a
+ * legal payload is left out and its reason recorded in
+ * {@link ChannelContract.issues} rather than emitted broken.
+ */
+export type ChannelContract = {
+    /** The `export const <name> = defineMessages(...)` identifier for this channel. */
+    readonly exportName: string;
+    readonly discriminator: string;
+    /** What the client may send — AsyncAPI's `receive`, from the application's side. */
+    readonly clientToServer: ContractDirection;
+    /** What the server may send — AsyncAPI's `send`. */
+    readonly serverToClient: ContractDirection;
+    readonly issues: readonly ExtractionIssue[];
+};
+export type BuildChannelContractOptions = {
+    /** Fallback discriminator when the channel does not name one (the CLI's `--discriminator`). */
+    readonly discriminator?: string;
+};
+/**
+ * Projects one normalized channel onto a `defineMessages`-shaped contract.
+ *
+ * The two models nearly line up already — AsyncAPI 3.0 and `@amritk/api` name
+ * directions from the same end — so the work is in the two places they do not:
+ *
+ * - **Direction.** `receive` (the application receives it) is what a client
+ *   sends, hence `clientToServer`; `send` is `serverToClient`. A message no
+ *   operation names has no direction at all, and a contract cannot guess one:
+ *   putting it in the wrong half would validate frames flowing the wrong way
+ *   and reject the ones that arrive.
+ * - **The tag.** The key is the value a frame carries on the wire, which the
+ *   payload usually states itself as `type: { const: 'bot_added' }`; that
+ *   value is taken as the key and stripped out of the payload (see
+ *   {@link stripDiscriminator}), because the runtime removes it from the frame
+ *   before validating. Only a payload that pins nothing falls back to the
+ *   message's name.
+ *
+ * Everything skipped comes back as an issue naming the message and the reason,
+ * so the caller can warn per message instead of failing the channel. A channel
+ * that ends up with no messages at all is still returned: an empty contract is
+ * a truthful one, and the issues say why it is empty.
+ */
+export declare const buildChannelContract: (channel: NormalizedChannel, options?: BuildChannelContractOptions) => ChannelContract;

package/dist/build-channel-contract.js

@@ -0,0 +1,60 @@
+import { resolveDiscriminator } from "./resolve-discriminator.js";
+import { sanitizeToken } from "./sanitize-token.js";
+import { stripDiscriminator } from "./strip-discriminator.js";
+const toExportName = (token) => {
+  const camel = token.replace(/[^A-Za-z0-9]+(.)?/g, (_, next) => next === void 0 ? "" : next.toUpperCase());
+  return `${/^[A-Za-z_$]/.test(camel) ? camel : `_${camel}`}Messages`;
+};
+const buildChannelContract = (channel, options = {}) => {
+  const discriminator = resolveDiscriminator(channel, options.discriminator);
+  const issues = [];
+  const clientToServer = /* @__PURE__ */ new Map();
+  const serverToClient = /* @__PURE__ */ new Map();
+  for (const message of channel.messages) {
+    const path = `#/channels/${channel.key}/messages/${message.name}`;
+    const skip = (reason) => void issues.push({ path, message: reason });
+    if (message.direction === void 0) {
+      skip("message has no direction (no operation names it), so it belongs to neither half of the contract");
+      continue;
+    }
+    if (message.payload === void 0 && message.schemaFormat !== void 0) {
+      skip(`payload was not extracted as JSON Schema (schemaFormat "${message.schemaFormat}")`);
+      continue;
+    }
+    const target = message.direction === "receive" ? clientToServer : serverToClient;
+    const half = message.direction === "receive" ? "clientToServer" : "serverToClient";
+    const place = (key, schema) => {
+      if (key === "__proto__") {
+        skip('the wire tag "__proto__" cannot be written as an object key in the generated contract');
+        return;
+      }
+      if (target.has(key)) {
+        skip(`two ${half} messages carry the wire tag "${key}"; keeping the first`);
+        return;
+      }
+      target.set(key, schema);
+    };
+    if (message.payload === void 0) {
+      place(message.name, { type: "object" });
+      continue;
+    }
+    const projected = stripDiscriminator(message.payload, discriminator);
+    if (projected.issue !== void 0) {
+      skip(projected.issue);
+      continue;
+    }
+    place(projected.tag ?? message.name, projected.schema);
+  }
+  return {
+    exportName: toExportName(sanitizeToken(channel.key, "channel")),
+    discriminator,
+    // `Object.fromEntries` defines own properties rather than assigning them,
+    // so even a hostile name lands as data on the object it belongs to.
+    clientToServer: Object.fromEntries(clientToServer),
+    serverToClient: Object.fromEntries(serverToClient),
+    issues
+  };
+};
+export {
+  buildChannelContract
+};

package/dist/extract-async-api.d.ts

@@ -1,13 +1,19 @@
+import type { NormalizeMessageOptions } from './normalize-message.js';
 import type { AsyncApiModel } from './types.js';
+/** Options for {@link extractAsyncApi}. */
+export type ExtractAsyncApiOptions = NormalizeMessageOptions;
 /**
  * Extracts an already-parsed AsyncAPI document (2.x or 3.x) into the
  * normalized model: channels, their messages, and each message's payload and
  * headers as self-contained JSON Schema 2020-12 documents.
  *
- * Per-message problems — an Avro payload, a dangling `$ref`, a malformed
+ * Per-message problems — a Protobuf payload, a dangling `$ref`, a malformed
  * trait — are collected on `issues` so one bad message never costs the rest of
  * the document. Only a document that is not AsyncAPI at all throws: there is
  * nothing to extract, and a silent empty model would read as "no channels"
  * rather than "wrong file".
+ *
+ * `options` tunes the one conversion that has more than one right answer: which
+ * JSON shape an Avro payload describes. See {@link ExtractAsyncApiOptions}.
  */
-export declare const extractAsyncApi: (document: unknown) => AsyncApiModel;
+export declare const extractAsyncApi: (document: unknown, options?: ExtractAsyncApiOptions) => AsyncApiModel;

package/dist/extract-async-api.js

@@ -2,14 +2,14 @@ import { readKey } from "@amritk/helpers/read-key";
 import { detectAsyncApiVersion } from "./detect-version.js";
 import { extractChannelsV2 } from "./extract-channels-v2.js";
 import { extractChannelsV3 } from "./extract-channels-v3.js";
-const extractAsyncApi = (document) => {
+const extractAsyncApi = (document, options = {}) => {
   const detected = detectAsyncApiVersion(document);
   if (!detected) {
     throw new Error("Not an AsyncAPI document: expected a top-level `asyncapi` field declaring version 2.x or 3.x.");
   }
   const record = document;
   const issues = [];
-  const channels = detected.major === 2 ? extractChannelsV2(record, issues) : extractChannelsV3(record, issues);
+  const channels = detected.major === 2 ? extractChannelsV2(record, issues, options) : extractChannelsV3(record, issues, options);
   const info = readKey(record, "info");
   const title = typeof info === "object" && info !== null ? readKey(info, "title") : void 0;
   return {

package/dist/extract-channels-v2.d.ts

@@ -1,3 +1,4 @@
+import { type NormalizeMessageOptions } from './normalize-message.js';
 import type { ExtractionIssue, NormalizedChannel } from './types.js';
 /**
  * Walks an AsyncAPI 2.x document's channels into the normalized model.
@@ -13,4 +14,4 @@ import type { ExtractionIssue, NormalizedChannel } from './types.js';
  * `n` counting across both operations of the channel so a `oneOf` list and a
  * publish/subscribe pair cannot collide.
  */
-export declare const extractChannelsV2: (document: Record<string, unknown>, issues: ExtractionIssue[]) => NormalizedChannel[];
+export declare const extractChannelsV2: (document: Record<string, unknown>, issues: ExtractionIssue[], options?: NormalizeMessageOptions) => NormalizedChannel[];

package/dist/extract-channels-v2.js

@@ -1,3 +1,4 @@
+import { getMjstDiscriminator } from "@amritk/helpers/mjst-extension";
 import { readKey } from "@amritk/helpers/read-key";
 import { mergeTraits } from "./merge-traits.js";
 import { normalizeMessage } from "./normalize-message.js";
@@ -13,7 +14,7 @@ const resolveTraits = (document, traits, issues, path) => {
   }
   return resolved;
 };
-const extractChannelsV2 = (document, issues) => {
+const extractChannelsV2 = (document, issues, options = {}) => {
   const channelsMap = readKey(document, "channels");
   if (typeof channelsMap !== "object" || channelsMap === null)
     return [];
@@ -59,10 +60,16 @@ const extractChannelsV2 = (document, issues) => {
           payloadSchemaFormat: readKey(merged, "schemaFormat"),
           payload: readKey(merged, "payload"),
           headers: readKey(merged, "headers")
-        }, document, issues, itemPath));
+        }, document, issues, itemPath, options));
       }
     }
-    channels.push({ key: channelKey, address: channelKey, messages });
+    const discriminator = getMjstDiscriminator(channel);
+    channels.push({
+      key: channelKey,
+      address: channelKey,
+      ...discriminator !== void 0 ? { discriminator } : {},
+      messages
+    });
   }
   return channels;
 };

package/dist/extract-channels-v3.d.ts

@@ -1,3 +1,4 @@
+import { type NormalizeMessageOptions } from './normalize-message.js';
 import type { ExtractionIssue, NormalizedChannel } from './types.js';
 /**
  * Walks an AsyncAPI 3.0 document's channels into the normalized model.
@@ -7,4 +8,4 @@ import type { ExtractionIssue, NormalizedChannel } from './types.js';
  * format travels with the schema it labels. Message names are the channel's
  * `messages` map keys, which 3.0 makes mandatory and unique per channel.
  */
-export declare const extractChannelsV3: (document: Record<string, unknown>, issues: ExtractionIssue[]) => NormalizedChannel[];
+export declare const extractChannelsV3: (document: Record<string, unknown>, issues: ExtractionIssue[], options?: NormalizeMessageOptions) => NormalizedChannel[];

package/dist/extract-channels-v3.js

@@ -1,3 +1,4 @@
+import { getMjstDiscriminator } from "@amritk/helpers/mjst-extension";
 import { readKey } from "@amritk/helpers/read-key";
 import { mergeTraits } from "./merge-traits.js";
 import { normalizeMessage } from "./normalize-message.js";
@@ -157,7 +158,7 @@ const collectDirections = (document, channelsMap, issues) => {
   }
   return directions;
 };
-const extractChannelsV3 = (document, issues) => {
+const extractChannelsV3 = (document, issues, options = {}) => {
   const channelsMap = readKey(document, "channels");
   if (typeof channelsMap !== "object" || channelsMap === null)
     return [];
@@ -192,12 +193,14 @@ const extractChannelsV3 = (document, issues) => {
           payload: payload.schema,
           headersSchemaFormat: headers.schemaFormat,
           headers: headers.schema
-        }, document, issues, messagePath));
+        }, document, issues, messagePath, options));
       }
     }
+    const discriminator = getMjstDiscriminator(channel);
     channels.push({
       key: channelKey,
       ...typeof address === "string" && address !== "" ? { address } : {},
+      ...discriminator !== void 0 ? { discriminator } : {},
       messages
     });
   }

package/dist/index.d.ts

@@ -1,6 +1,10 @@
+export { type BuildChannelContractOptions, buildChannelContract, type ChannelContract, type ContractDirection, } from './build-channel-contract.js';
 export { type DetectedVersion, detectAsyncApiVersion } from './detect-version.js';
-export { extractAsyncApi } from './extract-async-api.js';
+export { type ExtractAsyncApiOptions, extractAsyncApi } from './extract-async-api.js';
 export { mergeTraits } from './merge-traits.js';
 export { listMessageSchemas } from './message-schemas.js';
+export { DEFAULT_DISCRIMINATOR, resolveDiscriminator } from './resolve-discriminator.js';
+export { sanitizeToken } from './sanitize-token.js';
 export { classifySchemaFormat, type SchemaFormatFamily } from './schema-format.js';
+export { type StripDiscriminatorResult, stripDiscriminator } from './strip-discriminator.js';
 export type { AsyncApiModel, ExtractedSchema, ExtractionIssue, MessageDirection, NormalizedChannel, NormalizedMessage, } from './types.js';

package/dist/index.js

@@ -1,12 +1,21 @@
+import { buildChannelContract } from "./build-channel-contract.js";
 import { detectAsyncApiVersion } from "./detect-version.js";
 import { extractAsyncApi } from "./extract-async-api.js";
 import { mergeTraits } from "./merge-traits.js";
 import { listMessageSchemas } from "./message-schemas.js";
+import { DEFAULT_DISCRIMINATOR, resolveDiscriminator } from "./resolve-discriminator.js";
+import { sanitizeToken } from "./sanitize-token.js";
 import { classifySchemaFormat } from "./schema-format.js";
+import { stripDiscriminator } from "./strip-discriminator.js";
 export {
+  DEFAULT_DISCRIMINATOR,
+  buildChannelContract,
   classifySchemaFormat,
   detectAsyncApiVersion,
   extractAsyncApi,
   listMessageSchemas,
-  mergeTraits
+  mergeTraits,
+  resolveDiscriminator,
+  sanitizeToken,
+  stripDiscriminator
 };

package/dist/message-schemas.js

@@ -1,9 +1,5 @@
-import { toKebabCase } from "@amritk/helpers/ref-to-filename";
 import { refToName } from "@amritk/helpers/ref-to-name";
-const sanitizeToken = (value, fallback) => {
-  const token = toKebabCase(value).replace(/[^\p{ID_Continue}.]+/gu, "-").replace(/-{2,}/g, "-").replace(/^[-.]+|[-.]+$/g, "");
-  return token === "" ? fallback : token;
-};
+import { sanitizeToken } from "./sanitize-token.js";
 const claimToken = (base, taken, issues, path) => {
   let token = base;
   for (let n = 2; taken.has(token); n++) {

package/dist/normalize-message.d.ts

@@ -1,4 +1,17 @@
+import { type AvroEncoding } from '@amritk/adapters/avro-to-json-schema';
 import type { ExtractionIssue, MessageDirection, NormalizedMessage } from './types.js';
+/** Knobs the version walkers pass straight through from `extractAsyncApi`. */
+export type NormalizeMessageOptions = {
+    /**
+     * Which JSON shape an Avro payload is converted into. `'json'` (the default)
+     * describes the decoded object an application works with, which is what the
+     * generators exist to produce; `'avro-json'` describes the spec's JSON
+     * encoding — the bytes that actually travel under
+     * `application/vnd.apache.avro+json`, with unions wrapped in their branch
+     * name. Pick the wire shape only if you are validating raw frames.
+     */
+    readonly avroEncoding?: AvroEncoding;
+};
 export type RawMessage = {
     readonly name: string;
     readonly channelKey: string;
@@ -20,10 +33,17 @@ export type RawMessage = {
  * walkers) into a {@link NormalizedMessage}, normalizing its payload and
  * headers into self-contained 2020-12 schemas.
  *
- * A schema whose format is not a JSON Schema dialect — Avro, Protobuf, a
+ * An Avro `schemaFormat` is converted rather than refused: Avro is a schema
+ * language `@amritk/adapters` already reads, and the whole point of the
+ * extraction layer is to hand the generators JSON Schema whatever the document
+ * wrote. A conversion that fails — an illegal Avro name, a construct with no
+ * JSON Schema reading — becomes an issue rather than an exception, so one bad
+ * record schema costs only its own message.
+ *
+ * A schema whose format is neither a JSON Schema dialect nor Avro — Protobuf, a
  * malformed value — is skipped with an issue naming the format, keeping the
  * message itself in the model so a consumer can still see it exists. A
  * non-object schema (AsyncAPI allows boolean schemas; the generators need an
  * object root) is skipped the same way.
  */
-export declare const normalizeMessage: (raw: RawMessage, document: unknown, issues: ExtractionIssue[], path: string) => NormalizedMessage;
+export declare const normalizeMessage: (raw: RawMessage, document: unknown, issues: ExtractionIssue[], path: string, options?: NormalizeMessageOptions) => NormalizedMessage;

package/dist/normalize-message.js

@@ -1,7 +1,8 @@
+import { avroToJsonSchema } from "@amritk/adapters/avro-to-json-schema";
 import { normalizeSchema } from "./normalize-schema.js";
 import { rebaseComponentRefs } from "./rebase-component-refs.js";
 import { classifySchemaFormat } from "./schema-format.js";
-const normalizeMessage = (raw, document, issues, path) => {
+const normalizeMessage = (raw, document, issues, path, options = {}) => {
   const normalizeOne = (value, schemaFormat, label) => {
     if (value === void 0)
       return void 0;
@@ -13,6 +14,17 @@ const normalizeMessage = (raw, document, issues, path) => {
       });
       return void 0;
     }
+    if (family === "avro") {
+      try {
+        return avroToJsonSchema(value, { encoding: options.avroEncoding ?? "json" });
+      } catch (error) {
+        issues.push({
+          path: `${path}/${label}`,
+          message: `skipped: Avro ${label} could not be converted (${error instanceof Error ? error.message : String(error)})`
+        });
+        return void 0;
+      }
+    }
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
       issues.push({ path: `${path}/${label}`, message: `skipped: ${label} is not an object schema` });
       return void 0;

package/dist/normalize-schema.d.ts

@@ -13,6 +13,10 @@ import type { SchemaFormatFamily } from './schema-format.js';
  *   the generators would otherwise read as "never null".
  * - `'2020-12'` — pass through.
  *
+ * Avro never reaches here: it is a different schema language rather than a
+ * dialect of this one, so `normalize-message` hands it to `@amritk/adapters`
+ * and receives 2020-12 back already converted.
+ *
  * Keywords the AsyncAPI dialect adds beyond draft-07 (and draft-07 spellings
  * the upgrade does not rewrite, like array-form `items`) pass through
  * unchanged: `@amritk/runtime-validators` implements them directly, and an
@@ -21,4 +25,4 @@ import type { SchemaFormatFamily } from './schema-format.js';
  * An empty `$defs` left behind by the upgrade is dropped so a schema with no
  * definitions round-trips without growing keys.
  */
-export declare const normalizeSchema: (schema: Record<string, unknown>, family: Exclude<SchemaFormatFamily, 'unsupported'>) => Record<string, unknown>;
+export declare const normalizeSchema: (schema: Record<string, unknown>, family: Exclude<SchemaFormatFamily, 'unsupported' | 'avro'>) => Record<string, unknown>;

package/dist/rebase-component-refs.d.ts

@@ -37,4 +37,4 @@ import type { ExtractionIssue } from './types.js';
  * (`{}`, match-anything) definition plus an issue — one dangling pointer
  * should cost precision on one branch, not the whole message.
  */
-export declare const rebaseComponentRefs: (root: Record<string, unknown>, document: unknown, family: Exclude<SchemaFormatFamily, 'unsupported'>, issues: ExtractionIssue[], path: string) => Record<string, unknown>;
+export declare const rebaseComponentRefs: (root: Record<string, unknown>, document: unknown, family: Exclude<SchemaFormatFamily, 'unsupported' | 'avro'>, issues: ExtractionIssue[], path: string) => Record<string, unknown>;

package/dist/rebase-component-refs.js

@@ -5,6 +5,7 @@ import { readKey } from "@amritk/helpers/read-key";
 import { normalizeSchema } from "./normalize-schema.js";
 import { classifySchemaFormat } from "./schema-format.js";
 import { unwrapMultiFormat } from "./unwrap-multi-format.js";
+const isCopyableFamily = (family) => family !== "unsupported" && family !== "avro";
 const COMPONENT_SCHEMA_REF = /^#\/components\/schemas\/([^/]+)(\/.*)?$/;
 const TAIL_THROUGH_DEFS = /^\/(definitions|\$defs)\/([^/]+)(\/.*)?$/;
 const LOCAL_DEFS_REF = /^#\/(\$defs|definitions)\/([^/]+)(\/.*)?$/;
@@ -116,7 +117,7 @@ const rebaseComponentRefs = (root, document, family, issues, path) => {
       return void 0;
     const { schemaFormat, schema } = unwrapMultiFormat(raw);
     const componentFamily = schemaFormat === void 0 ? family : classifySchemaFormat(schemaFormat);
-    if (componentFamily === "unsupported" || typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+    if (!isCopyableFamily(componentFamily) || typeof schema !== "object" || schema === null || Array.isArray(schema)) {
       return void 0;
     }
     const names = { definitions: /* @__PURE__ */ new Set(), $defs: /* @__PURE__ */ new Set() };
@@ -258,10 +259,10 @@ const rebaseComponentRefs = (root, document, family, issues, path) => {
     }
     const { schemaFormat, schema } = unwrapMultiFormat(raw);
     const componentFamily = schemaFormat === void 0 ? family : classifySchemaFormat(schemaFormat);
-    if (componentFamily === "unsupported" || typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+    if (!isCopyableFamily(componentFamily) || typeof schema !== "object" || schema === null || Array.isArray(schema)) {
       issues.push({
         path,
-        message: componentFamily === "unsupported" ? `component "${name}" uses unsupported schemaFormat ${JSON.stringify(schemaFormat)}; treated as an unconstrained schema` : `component "${name}" is not an object schema; treated as an unconstrained schema`
+        message: isCopyableFamily(componentFamily) ? `component "${name}" is not an object schema; treated as an unconstrained schema` : `component "${name}" uses unsupported schemaFormat ${JSON.stringify(schemaFormat)}; treated as an unconstrained schema`
       });
       assignKey(copiedDefs, defsKey, {});
       return;

package/dist/resolve-discriminator.d.ts

@@ -0,0 +1,29 @@
+import type { NormalizedChannel } from './types.js';
+/**
+ * The property a message contract falls back to when nothing names one.
+ *
+ * Kept as a literal rather than imported from `@amritk/api`: this package's
+ * only dependency is `@amritk/helpers`, and the runtime it feeds must stay a
+ * *peer* of the generated code, not a dependency of the extractor. The value
+ * mirrors `DEFAULT_DISCRIMINATOR` there, and the contract tests hold the two
+ * together.
+ */
+export declare const DEFAULT_DISCRIMINATOR = "type";
+/**
+ * Decides which property tags a channel's messages, in the order the answer
+ * gets more specific:
+ *
+ * 1. `x-mjst: { discriminator }` on the channel itself. The document is the one
+ *    place that knows the wire, and it travels with the document — a consumer
+ *    regenerating from it does not have to be told again.
+ * 2. The caller's override (the CLI's `--discriminator`), for a document you do
+ *    not control and cannot annotate.
+ * 3. `'type'`, matching `@amritk/api`'s default, so the common case needs no
+ *    declaration at all.
+ *
+ * The document wins over the flag deliberately: one `--discriminator` covers a
+ * whole run, and a run may span channels that disagree. A channel that has
+ * written its answer down should not have it overwritten by a blanket default
+ * meant for the channels that have not.
+ */
+export declare const resolveDiscriminator: (channel: NormalizedChannel, override?: string) => string;

package/dist/resolve-discriminator.js

@@ -0,0 +1,6 @@
+const DEFAULT_DISCRIMINATOR = "type";
+const resolveDiscriminator = (channel, override) => channel.discriminator ?? override ?? DEFAULT_DISCRIMINATOR;
+export {
+  DEFAULT_DISCRIMINATOR,
+  resolveDiscriminator
+};

package/dist/sanitize-token.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Folds an arbitrary channel key or message name into a filesystem- and
+ * import-safe kebab token: camelCase splits, and everything a filename cannot
+ * carry — a topic's `/` separators, `{param}` braces, spaces — becomes a
+ * dash. `fallback` covers the value that normalizes away entirely.
+ *
+ * Shared by the schema layout (`channels/<channel>/<message>/`) and the channel
+ * contracts (`contracts/<channel>.ts`) so the two name the same channel the
+ * same way — a reader moving between the trees should not have to translate.
+ */
+export declare const sanitizeToken: (value: string, fallback: string) => string;

package/dist/sanitize-token.js

@@ -0,0 +1,8 @@
+import { toKebabCase } from "@amritk/helpers/ref-to-filename";
+const sanitizeToken = (value, fallback) => {
+  const token = toKebabCase(value).replace(/[^\p{ID_Continue}.]+/gu, "-").replace(/-{2,}/g, "-").replace(/^[-.]+|[-.]+$/g, "");
+  return token === "" ? fallback : token;
+};
+export {
+  sanitizeToken
+};

package/dist/schema-format.d.ts

@@ -1,12 +1,12 @@
 /**
- * The JSON Schema dialect a `schemaFormat` names, or `'unsupported'` for
- * everything the pipeline cannot turn into JSON Schema (Avro, Protobuf, RAML,
- * unrecognized media types). The four supported families each get their own
- * normalization: the AsyncAPI default dialect and declared draft-07 go through
- * the draft-07 upgrade, OpenAPI schema objects get `nullable` folded, and
- * 2020-12 passes through.
+ * The schema language a `schemaFormat` names, or `'unsupported'` for everything
+ * the pipeline cannot turn into JSON Schema (Protobuf, RAML, unrecognized media
+ * types). Each supported family gets its own normalization: the AsyncAPI default
+ * dialect and declared draft-07 go through the draft-07 upgrade, OpenAPI schema
+ * objects get `nullable` folded, 2020-12 passes through, and Avro is converted
+ * by `@amritk/adapters`.
  */
-export type SchemaFormatFamily = 'asyncapi' | 'draft-07' | '2020-12' | 'openapi' | 'unsupported';
+export type SchemaFormatFamily = 'asyncapi' | 'draft-07' | '2020-12' | 'openapi' | 'avro' | 'unsupported';
 /**
  * Classifies a message's effective `schemaFormat`. An absent format means the
  * AsyncAPI default dialect — the spec's own rule — so `undefined` is

package/dist/schema-format.js

@@ -1,5 +1,6 @@
 const ASYNCAPI_DIALECT = /^application\/vnd\.aai\.asyncapi([+;]|$)/;
 const OPENAPI_DIALECT = /^application\/vnd\.oai\.openapi([+;]|$)/;
+const AVRO_DIALECT = /^application\/vnd\.apache\.avro([+;]|$)/;
 const JSON_SCHEMA_DIALECT = /^application\/schema\+(?:json|yaml);\s*version=(draft-07|draft-2020-12)\s*$/;
 const classifySchemaFormat = (schemaFormat) => {
   if (schemaFormat === void 0)
@@ -10,6 +11,8 @@ const classifySchemaFormat = (schemaFormat) => {
     return "asyncapi";
   if (OPENAPI_DIALECT.test(schemaFormat))
     return "openapi";
+  if (AVRO_DIALECT.test(schemaFormat))
+    return "avro";
   const jsonSchema = JSON_SCHEMA_DIALECT.exec(schemaFormat);
   if (jsonSchema)
     return jsonSchema[1] === "draft-07" ? "draft-07" : "2020-12";

package/dist/strip-discriminator.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Either a payload schema fit to stand as a message schema — with the wire tag
+ * it declared, when it declared one — or the reason it is not. Never both: a
+ * message whose payload cannot be made contract-legal is skipped with the
+ * issue, rather than emitted as something that would throw at
+ * `prepareMessages` time or reject every frame at runtime.
+ */
+export type StripDiscriminatorResult = {
+    readonly schema: Record<string, unknown>;
+    /**
+     * The value the payload pinned the discriminator to, which *is* the
+     * frame's tag on the wire. Absent when the payload never mentions the
+     * discriminator, leaving the caller to fall back to the message name.
+     */
+    readonly tag?: string;
+    readonly issue?: undefined;
+} | {
+    readonly schema?: undefined;
+    readonly tag?: undefined;
+    readonly issue: string;
+};
+/**
+ * Removes the discriminator property from a message payload, so what is left
+ * describes the payload alone, and reports the tag value the payload pinned it
+ * to.
+ *
+ * `@amritk/api` reads the tag off the frame to *select* the message, then
+ * removes it before validating — so a schema that still declares the tag is
+ * refused at setup time by `assertMessageSchema`, and would be unsatisfiable
+ * even if it were not. AsyncAPI documents, meanwhile, almost always declare it:
+ * a channel carrying a `oneOf` of messages has nothing *but* the tag to tell
+ * them apart, so `type: { const: 'hello' }` is how the document says "this is
+ * the hello message". The two conventions are the same fact written twice, and
+ * this reconciles them by taking the document's word for what goes on the wire
+ * and dropping the copy.
+ *
+ * The pinned value is returned rather than checked against the message name,
+ * because the two answer different questions. A message's *name* is a
+ * document-authoring handle — 2.x messages inside a `oneOf` often have none at
+ * all, and get a positional `message-3` — while `const` is a statement about
+ * the bytes. Slack's RTM API names a message `botAdded` and tags it
+ * `bot_added`; keying on the name would emit a contract listening for a frame
+ * that never arrives, so the tag wins and the name is only the fallback for a
+ * payload that pins nothing.
+ *
+ * What is still refused, because no tag can be recovered from it:
+ *
+ * - `type: { type: 'string' }` constrains the tag without naming a value.
+ * - A multi-member `enum` names several, which identifies no single message.
+ * - `type: { const: 7 }` names a non-string, and the runtime selects a message
+ *   by a string tag — a numeric one matches no key it could be given.
+ * - A payload that is not an object schema has nowhere for a tag to live, which
+ *   `assertMessageSchema` refuses too.
+ *
+ * The input is never mutated: the model's schemas are shared with the parser
+ * generators, which must keep seeing the payload as the document wrote it.
+ */
+export declare const stripDiscriminator: (payload: unknown, discriminator: string) => StripDiscriminatorResult;

package/dist/strip-discriminator.js

@@ -0,0 +1,56 @@
+import { readKey } from "@amritk/helpers/read-key";
+const pinnedValue = (branch) => {
+  if (Object.hasOwn(branch, "const"))
+    return { value: readKey(branch, "const") };
+  const enumValue = readKey(branch, "enum");
+  if (Array.isArray(enumValue) && enumValue.length === 1)
+    return { value: enumValue[0] };
+  return void 0;
+};
+const stripDiscriminator = (payload, discriminator) => {
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload))
+    return { issue: "payload is not an object schema, so it cannot describe a message" };
+  const schema = payload;
+  const type = readKey(schema, "type");
+  if (type !== void 0 && type !== "object")
+    return { issue: `payload declares type ${JSON.stringify(type)}; a message schema must be type 'object'` };
+  const properties = readKey(schema, "properties");
+  const declaredProperties = typeof properties === "object" && properties !== null ? properties : void 0;
+  const declaration = declaredProperties === void 0 ? void 0 : readKey(declaredProperties, discriminator);
+  const required = readKey(schema, "required");
+  const requiresDiscriminator = Array.isArray(required) && required.includes(discriminator);
+  if (declaration === void 0 && !requiresDiscriminator)
+    return { schema };
+  if (declaration === void 0)
+    return {
+      issue: `payload requires "${discriminator}" without declaring it, so the tag it carries cannot be read`
+    };
+  if (typeof declaration !== "object" || declaration === null)
+    return { issue: `payload declares "${discriminator}" as ${JSON.stringify(declaration)}, not a schema` };
+  const pinned = pinnedValue(declaration);
+  if (pinned === void 0)
+    return {
+      issue: `payload constrains "${discriminator}" without pinning it to one value, so the message it tags cannot be identified`
+    };
+  if (typeof pinned.value !== "string")
+    return {
+      issue: `payload pins "${discriminator}" to ${JSON.stringify(pinned.value)}, which is not a string; a frame is routed by a string tag, so this one could never select a message`
+    };
+  const stripped = { ...schema };
+  const remaining = Object.fromEntries(Object.entries(declaredProperties).filter(([key]) => key !== discriminator));
+  if (Object.keys(remaining).length === 0)
+    delete stripped["properties"];
+  else
+    stripped["properties"] = remaining;
+  if (requiresDiscriminator) {
+    const rest = required.filter((entry) => entry !== discriminator);
+    if (rest.length === 0)
+      delete stripped["required"];
+    else
+      stripped["required"] = rest;
+  }
+  return { schema: stripped, tag: pinned.value };
+};
+export {
+  stripDiscriminator
+};

package/dist/types.d.ts

@@ -47,8 +47,10 @@ export type NormalizedMessage = {
     /**
      * The payload as a self-contained JSON Schema 2020-12 document: the dialect
      * normalized, and every `#/components/schemas/...` reference rebased into a
-     * local `$defs`. Absent when the message declares none, or when its
-     * `schemaFormat` is not a JSON Schema dialect (an issue records which).
+     * local `$defs`. An Avro `schemaFormat` arrives here converted, not skipped.
+     * Absent when the message declares no payload, when its `schemaFormat` names
+     * a language this cannot read (Protobuf, say), or when an Avro conversion
+     * failed — an issue records which.
      */
     readonly payload?: Record<string, unknown>;
     /** The headers schema, normalized the same way as {@link payload}. */
@@ -59,6 +61,14 @@ export type NormalizedChannel = {
     readonly key: string;
     /** The 3.0 `address`; for 2.x the channel key, which *is* the topic/path. */
     readonly address?: string;
+    /**
+     * The property naming which message a frame is, when the channel declares one
+     * via `x-mjst: { discriminator }`. AsyncAPI itself has no way to say this —
+     * it lists a channel's messages and stops — but a message contract has to
+     * pick one property, so a document whose frames are tagged `event` rather
+     * than `type` can say so where the messages are.
+     */
+    readonly discriminator?: string;
     readonly messages: readonly NormalizedMessage[];
 };
 export type AsyncApiModel = {

package/dist/unwrap-multi-format.d.ts

@@ -7,8 +7,17 @@ export type UnwrappedSchema = {
  * Unwraps an AsyncAPI 3.0 Multi Format Schema Object (`{ schemaFormat,
  * schema }`) into its parts, passing a bare Schema Object through untouched.
  *
- * The wrapper is recognized only when *both* keys are present: `schemaFormat`
- * is required on the wrapper, and demanding `schema` too keeps a plain schema
- * that merely declares a property named `schemaFormat` from losing its body.
+ * An own `schema` key alone makes it a wrapper, which is exactly how the 3.0
+ * meta-schema decides (`anySchema.json`: `if: { required: ['schema'] }` → the
+ * Multi Format Schema Object, else a plain Schema Object). `schemaFormat` is
+ * *optional* on the wrapper and defaults to the AsyncAPI dialect, so requiring
+ * it here read `{ schema: … }` as a schema whose only keyword is one no dialect
+ * defines — the payload vanished and the message generated an empty type.
+ *
+ * Note what this still does not claim: `{ schemaFormat: 'x', type: 'object' }`
+ * has no `schema` key, so it stays a bare Schema Object that happens to carry
+ * an unknown keyword, rather than a wrapper with nothing inside it. That is the
+ * meta-schema's reading too, and it is why the check is on `schema` rather than
+ * on either key being present.
  */
 export declare const unwrapMultiFormat: (node: unknown) => UnwrappedSchema;

package/dist/unwrap-multi-format.js

@@ -1,11 +1,8 @@
 import { readKey } from "@amritk/helpers/read-key";
 const unwrapMultiFormat = (node) => {
-  if (typeof node === "object" && node !== null && !Array.isArray(node)) {
+  if (typeof node === "object" && node !== null && !Array.isArray(node) && Object.hasOwn(node, "schema")) {
     const record = node;
-    const schemaFormat = readKey(record, "schemaFormat");
-    if (schemaFormat !== void 0 && Object.hasOwn(record, "schema")) {
-      return { schemaFormat, schema: readKey(record, "schema") };
-    }
+    return { schemaFormat: readKey(record, "schemaFormat"), schema: readKey(record, "schema") };
   }
   return { schema: node };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/asyncapi",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Extract JSON Schemas from AsyncAPI 2.x/3.0 documents for the mjst generators.",
   "type": "module",
   "sideEffects": false,
@@ -39,7 +39,8 @@
     "test": "NODE_ENV=production vitest run --root ../.. packages/asyncapi"
   },
   "dependencies": {
-    "@amritk/helpers": "^0.19.0"
+    "@amritk/adapters": "^0.6.2",
+    "@amritk/helpers": "^0.21.0"
   },
   "exports": {
     "./package.json": "./package.json",