tempest-express-sdk 0.31.0 → 0.32.0

package/dist/index.cjs

@@ -16086,6 +16086,239 @@ function makeMetricsRouter(options = {}) {
   });
   return router;
 }
+var PERSPECTIVE_EXTENSION = "x-tempest-perspective";
+var ASYNCAPI_VERSION = "3.0.0";
+function actionFor(direction) {
+  return direction === "clientToServer" ? "receive" : "send";
+}
+var AsyncApiRegistry = class {
+  /** Channels by `name`. */
+  channels = /* @__PURE__ */ new Map();
+  /** Messages by `name`. */
+  messages = /* @__PURE__ */ new Map();
+  /** Operations, in registration order. */
+  operations = [];
+  /**
+   * Register the connection a socket is served on.
+   *
+   * @param channel - The channel definition.
+   * @returns This registry, for chaining.
+   * @throws Error When `name` is already registered.
+   */
+  registerChannel(channel) {
+    if (this.channels.has(channel.name)) {
+      throw new Error(`AsyncAPI channel "${channel.name}" is already registered.`);
+    }
+    this.channels.set(channel.name, channel);
+    return this;
+  }
+  /**
+   * Register one frame the socket carries.
+   *
+   * @param message - The message definition.
+   * @returns This registry, for chaining.
+   * @throws Error When `name` is already registered.
+   */
+  registerMessage(message) {
+    if (this.messages.has(message.name)) {
+      throw new Error(`AsyncAPI message "${message.name}" is already registered.`);
+    }
+    this.messages.set(message.name, message);
+    return this;
+  }
+  /**
+   * Register a set of messages travelling one way on one channel.
+   *
+   * @param operation - The operation definition.
+   * @returns This registry, for chaining.
+   * @throws Error When `name` is already registered.
+   */
+  registerOperation(operation) {
+    if (this.operations.some((existing) => existing.name === operation.name)) {
+      throw new Error(`AsyncAPI operation "${operation.name}" is already registered.`);
+    }
+    this.operations.push(operation);
+    return this;
+  }
+  /**
+   * Render the AsyncAPI document.
+   *
+   * @param options - The `info` block, optional servers and default content
+   *   type.
+   * @returns The document, JSON-serializable.
+   * @throws Error When an operation names a channel or a message that was
+   *   never registered. A dangling `$ref` produces a document that validates
+   *   structurally and generates a client missing the frame, so it fails
+   *   here instead.
+   */
+  generate(options) {
+    this.assertReferencesResolve();
+    const schemas = this.renderPayloads();
+    const messages = this.renderMessages();
+    const channels = this.renderChannels(schemas);
+    const operations = this.renderOperations();
+    return {
+      asyncapi: ASYNCAPI_VERSION,
+      [PERSPECTIVE_EXTENSION]: "server",
+      info: {
+        title: options.info.title,
+        version: options.info.version,
+        ...options.info.description !== void 0 ? { description: options.info.description } : {}
+      },
+      ...options.servers !== void 0 ? { servers: options.servers } : {},
+      defaultContentType: options.defaultContentType ?? "application/json",
+      channels,
+      operations,
+      components: { messages, schemas }
+    };
+  }
+  /**
+   * Fail when an operation points at something that was never registered.
+   *
+   * @throws Error Naming the operation and what it could not resolve.
+   */
+  assertReferencesResolve() {
+    for (const operation of this.operations) {
+      if (!this.channels.has(operation.channel)) {
+        throw new Error(
+          `AsyncAPI operation "${operation.name}" refers to channel "${operation.channel}", which is not registered.`
+        );
+      }
+      for (const message of operation.messages) {
+        if (!this.messages.has(message)) {
+          throw new Error(
+            `AsyncAPI operation "${operation.name}" refers to message "${message}", which is not registered.`
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Render every payload schema through the OpenAPI generator.
+   *
+   * @returns Component schemas keyed by message name, plus any handshake
+   *   schema a channel declared.
+   *
+   * AsyncAPI 3 payloads are JSON Schema, and `generateComponents` emits
+   * exactly that from the Zod objects already validating at runtime. Reusing
+   * it is what keeps the document from describing a shape the server would
+   * reject.
+   */
+  renderPayloads() {
+    const registry = createOpenApiRegistry();
+    for (const message of this.messages.values()) {
+      registry.register(message.name, message.schema);
+    }
+    for (const channel of this.channels.values()) {
+      if (channel.handshakeHeaders !== void 0) {
+        registry.register(`${channel.name}Headers`, channel.handshakeHeaders);
+      }
+      if (channel.handshakeQuery !== void 0) {
+        registry.register(`${channel.name}Query`, channel.handshakeQuery);
+      }
+    }
+    const components = new zodToOpenapi.OpenApiGeneratorV31(registry.definitions).generateComponents();
+    const schemas = components.components?.schemas ?? {};
+    return schemas;
+  }
+  /**
+   * Render `components.messages`.
+   *
+   * @returns Message objects keyed by name, each pointing at its payload.
+   */
+  renderMessages() {
+    const rendered = {};
+    for (const [name, message] of this.messages) {
+      rendered[name] = {
+        name,
+        contentType: message.contentType ?? "application/json",
+        ...message.summary !== void 0 ? { summary: message.summary } : {},
+        ...message.description !== void 0 ? { description: message.description } : {},
+        payload: { $ref: `#/components/schemas/${name}` }
+      };
+    }
+    return rendered;
+  }
+  /**
+   * Render `channels`, each listing every message it can carry.
+   *
+   * @param schemas - The rendered component schemas, to inline the
+   *   handshake ones into the binding.
+   * @returns Channel objects keyed by name.
+   *
+   * The handshake schemas are **inlined** rather than `$ref`-ed. The
+   * specification types the binding's `headers` and `query` as
+   * `oneOf: [Schema, Reference]`, and a bare `{"$ref": ...}` object
+   * satisfies both branches — so `oneOf` sees two matches and the document
+   * fails validation against AsyncAPI's own JSON Schema. Measured: the same
+   * binding with the schema inlined validates clean.
+   *
+   * A channel lists every registered message rather than only those its own
+   * operations use: the specification requires an operation's `messages` to
+   * be a subset of its channel's, and with one connection per document the
+   * distinction buys nothing.
+   */
+  renderChannels(schemas) {
+    const everyMessage = {};
+    for (const name of this.messages.keys()) {
+      everyMessage[name] = { $ref: `#/components/messages/${name}` };
+    }
+    const rendered = {};
+    for (const [name, channel] of this.channels) {
+      const bindings = {
+        bindingVersion: "0.1.0",
+        method: "GET"
+      };
+      if (channel.handshakeHeaders !== void 0) {
+        bindings.headers = schemas[`${name}Headers`];
+      }
+      if (channel.handshakeQuery !== void 0) {
+        bindings.query = schemas[`${name}Query`];
+      }
+      rendered[name] = {
+        address: channel.address,
+        ...channel.title !== void 0 ? { title: channel.title } : {},
+        ...channel.description !== void 0 ? { description: channel.description } : {},
+        messages: everyMessage,
+        bindings: { ws: bindings }
+      };
+    }
+    return rendered;
+  }
+  /**
+   * Render `operations`, translating each direction into an `action`.
+   *
+   * @returns Operation objects keyed by name.
+   */
+  renderOperations() {
+    const rendered = {};
+    for (const operation of this.operations) {
+      rendered[operation.name] = {
+        action: actionFor(operation.direction),
+        channel: { $ref: `#/channels/${operation.channel}` },
+        ...operation.summary !== void 0 ? { summary: operation.summary } : {},
+        ...operation.description !== void 0 ? { description: operation.description } : {},
+        messages: operation.messages.map((message) => ({
+          $ref: `#/channels/${operation.channel}/messages/${message}`
+        }))
+      };
+    }
+    return rendered;
+  }
+};
+function createAsyncApiRegistry() {
+  return new AsyncApiRegistry();
+}
+function generateAsyncApiDocument(registry, options) {
+  return registry.generate(options);
+}
+
+// src/asyncapi/mount.ts
+function mountAsyncApiJson(app, path, document) {
+  app.get(path, (_req, res) => {
+    res.json(document);
+  });
+}
 var logger4 = new JSONLogger("tempest_express_sdk.api.server");
 function corsMiddleware(origins) {
   const allowAll = origins === "*";
@@ -16134,6 +16367,14 @@ async function createApp(options = {}) {
       mountRedoc(app, redocPath ?? "/redoc", specPath, redoc ?? {});
     }
   }
+  if (options.asyncapi) {
+    const { registry, jsonPath, ...genOptions } = options.asyncapi;
+    mountAsyncApiJson(
+      app,
+      jsonPath ?? "/asyncapi.json",
+      generateAsyncApiDocument(registry, genOptions)
+    );
+  }
   registerExceptionHandlers(app, {
     ...options.errorHandling,
     ...options.catalog !== void 0 ? { catalog: options.catalog } : {}
@@ -17026,7 +17267,7 @@ async function withTestDatabase(models, fn) {
 }
 
 // src/version.ts
-var VERSION = "0.31.0";
+var VERSION = "0.32.0";
 
 Object.defineProperty(exports, "OpenAPIRegistry", {
   enumerable: true,
@@ -17185,6 +17426,7 @@ Object.defineProperty(exports, "update", {
   get: function () { return tempestDbJs.update; }
 });
 exports.ADMIN_CSS = ADMIN_CSS;
+exports.ASYNCAPI_VERSION = ASYNCAPI_VERSION;
 exports.ActivationService = ActivationService;
 exports.AdminJsonSite = AdminJsonSite;
 exports.AdminModel = AdminModel;
@@ -17192,6 +17434,7 @@ exports.AdminPermission = AdminPermission;
 exports.AdminSessionStore = AdminSessionStore;
 exports.AdminSite = AdminSite;
 exports.AppException = AppException;
+exports.AsyncApiRegistry = AsyncApiRegistry;
 exports.AttemptThrottle = AttemptThrottle;
 exports.AuditAction = AuditAction;
 exports.BaseAuditLogModel = BaseAuditLogModel;
@@ -17253,6 +17496,7 @@ exports.OAuthError = OAuthError;
 exports.OIDCProvider = OIDCProvider;
 exports.OutboxRelay = OutboxRelay;
 exports.OutboxStatus = OutboxStatus;
+exports.PERSPECTIVE_EXTENSION = PERSPECTIVE_EXTENSION;
 exports.PHONE_BR_PATTERN = PHONE_BR_PATTERN;
 exports.PasswordResetService = PasswordResetService;
 exports.PasswordUtils = PasswordUtils;
@@ -17324,6 +17568,7 @@ exports.corsSettingsShape = corsSettingsShape;
 exports.cpfField = cpfField;
 exports.cpfOrCnpjField = cpfOrCnpjField;
 exports.createApp = createApp;
+exports.createAsyncApiRegistry = createAsyncApiRegistry;
 exports.createOpenApiRegistry = createOpenApiRegistry;
 exports.createTestDatabase = createTestDatabase;
 exports.createdByColumn = createdByColumn;
@@ -17349,6 +17594,7 @@ exports.foreignKeyLabel = foreignKeyLabel;
 exports.foreignKeyTable = foreignKeyTable;
 exports.formatCellValue = formatCellValue;
 exports.formatFieldValue = formatFieldValue;
+exports.generateAsyncApiDocument = generateAsyncApiDocument;
 exports.generateCsrfToken = generateCsrfToken;
 exports.generateOAuthState = generateOAuthState;
 exports.generateOpaqueToken = generateOpaqueToken;
@@ -17409,6 +17655,7 @@ exports.mfaCodeSchema = mfaCodeSchema;
 exports.mfaEnrollResponseSchema = mfaEnrollResponseSchema;
 exports.minioSettingsShape = minioSettingsShape;
 exports.modifyDict = modifyDict;
+exports.mountAsyncApiJson = mountAsyncApiJson;
 exports.mountOpenApiJson = mountOpenApiJson;
 exports.mountRedoc = mountRedoc;
 exports.mountSwaggerUi = mountSwaggerUi;