@bielu/scalar-signalr 0.1.0

package/src/discovery.ts

@@ -0,0 +1,21 @@
+import { resolveDocuments as resolveDocumentsCore } from '@bielu/scalar-core'
+import type { SignalRDocumentRef } from './types'
+
+/** How the SignalR bundle discovers its AsyncAPI documents (see `resolveDocuments` in @bielu/scalar-core). */
+export const SIGNALR_DISCOVERY = {
+  configKey: 'signalr',
+  globalName: '__BIELU_SCALAR_SIGNALR__',
+} as const
+
+/**
+ * Resolves the documents to scan, in decreasing priority: an explicit override (`documents` prop);
+ * a `SignalRPluginConfig` embedded inline on the Scalar config as `config.signalr`; a
+ * `window.__BIELU_SCALAR_SIGNALR__` global; otherwise auto-discovery from the Scalar configuration
+ * passed as `options`.
+ */
+export function resolveDocuments(
+  options: Record<string, any> | undefined,
+  override?: SignalRDocumentRef[],
+): SignalRDocumentRef[] {
+  return resolveDocumentsCore(options, SIGNALR_DISCOVERY, override)
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+import { bootstrapConsole } from '@bielu/scalar-core'
+import SignalRConsole from './components/SignalRConsole.vue'
+import { SIGNALR_DISCOVERY } from './discovery'
+import { SIGNALR_PLUGIN_SPEC } from './plugin'
+
+export { createSignalRPlugin } from './plugin'
+export { loadSignalRHubs, parseSignalRHubs } from './signalr-bindings'
+export type {
+  SignalRDirection,
+  SignalRDocumentRef,
+  SignalRHubModel,
+  SignalROperationModel,
+  SignalRPluginConfig,
+} from './types'
+
+// Register the console Web Component and hook `window.Scalar.createApiReference` so every Scalar
+// API Reference on the page picks up the SignalR plugin (see @bielu/scalar-core's bootstrap).
+bootstrapConsole(
+  {
+    ...SIGNALR_PLUGIN_SPEC,
+    discovery: SIGNALR_DISCOVERY,
+    stylesId: 'bielu-signalr-styles',
+    wrappedFlag: '__bieluSignalRWrapped',
+  },
+  SignalRConsole,
+)

package/src/plugin.ts

@@ -0,0 +1,39 @@
+import { createConsolePlugin } from '@bielu/scalar-core'
+import type { SignalRDocumentRef } from './types'
+
+/** The custom element tag the console is rendered as (registered in `index.ts`). */
+export const SIGNALR_CONSOLE_TAG = 'bielu-signalr-console'
+
+/** The Scalar plugin's identifier, used to detect (and de-duplicate) an existing registration. */
+export const SIGNALR_PLUGIN_NAME = 'bielu-signalr'
+
+/** How the SignalR console registers with Scalar (plugin name, element tag, sidebar label). */
+export const SIGNALR_PLUGIN_SPEC = {
+  pluginName: SIGNALR_PLUGIN_NAME,
+  elementTag: SIGNALR_CONSOLE_TAG,
+  sidebarLabel: 'SignalR',
+} as const
+
+/**
+ * The structural shape of a Scalar API Reference plugin. Declared locally (a structural copy of
+ * @bielu/scalar-core's type) so the published declaration files never reference the private core
+ * package; Scalar validates it at runtime.
+ */
+export type ApiReferencePlugin = () => {
+  name: string
+  extensions: unknown[]
+  views?: Record<string, unknown[]>
+  hooks?: Record<string, unknown>
+  apiClientPlugins?: unknown[]
+}
+
+/**
+ * Creates the SignalR console plugin for the Scalar API Reference.
+ *
+ * The view's `component` is the custom element tag name (a string), so Scalar's own Vue renders a
+ * plain element — our Web Component (with its own Vue + styles) takes over from there. The AsyncAPI
+ * documents (discovered from the Scalar configuration at registration time) are passed to the
+ * element as the `documents` prop, so the console does not depend on Scalar binding its config.
+ */
+export const createSignalRPlugin = (documents?: SignalRDocumentRef[]): ApiReferencePlugin =>
+  createConsolePlugin(SIGNALR_PLUGIN_SPEC, documents)

package/src/signalr-bindings.ts

@@ -0,0 +1,114 @@
+import {
+  deref,
+  exampleFromSchema,
+  extractSecuritySchemes,
+  firstServerHost,
+  loadAsyncApiDocuments,
+  refName,
+  resolveServerBaseUrl,
+} from '@bielu/scalar-core'
+import type {
+  SignalRDirection,
+  SignalRDocumentRef,
+  SignalRHubModel,
+  SignalRMessageModel,
+  SignalROperationModel,
+} from './types'
+
+const SIGNALR = 'signalr'
+
+type AnyRecord = Record<string, any>
+
+/** Resolve the message(s) an operation carries and generate an example payload for each. */
+function buildMessages(doc: AnyRecord, op: AnyRecord): SignalRMessageModel[] {
+  const refs = (Array.isArray(op.messages) ? op.messages : [])
+    .map((m: AnyRecord) => m?.$ref)
+    .filter((ref: unknown): ref is string => typeof ref === 'string')
+
+  const messages: SignalRMessageModel[] = []
+  for (const ref of refs) {
+    const message = deref(doc, { $ref: ref })
+    const name = message?.name ?? refName(ref) ?? 'message'
+    const payloadExample = exampleFromSchema(doc, message?.payload)
+    // SignalR hub methods take positional arguments; the payload is the (first) argument.
+    const args = payloadExample === null ? [] : [payloadExample]
+    messages.push({ name, title: message?.title, example: JSON.stringify(args, null, 2) })
+  }
+  return messages
+}
+
+function directionFor(op: AnyRecord, binding: AnyRecord | undefined): SignalRDirection {
+  const fromBinding = binding?.direction
+  if (fromBinding === 'clientToServer' || fromBinding === 'serverToClient') {
+    return fromBinding
+  }
+  // AsyncAPI 3 `action`: `send` = application -> channel, `receive` = channel -> application.
+  return op.action === 'receive' ? 'serverToClient' : 'clientToServer'
+}
+
+/** Extract every SignalR hub (channel + its operations) from a parsed AsyncAPI document. */
+export function parseSignalRHubs(documentName: string, doc: AnyRecord): SignalRHubModel[] {
+  if (!doc || typeof doc !== 'object') {
+    return []
+  }
+
+  const baseUrl = resolveServerBaseUrl(firstServerHost(doc, SIGNALR))
+
+  // Extract security schemes from the document so the console can read them at connect time
+  // without re-fetching the document. Only a minimal subset is needed for auth resolution.
+  const securitySchemes = extractSecuritySchemes(doc)
+  const docSecuritySchemes = Object.keys(securitySchemes).length > 0 ? securitySchemes : undefined
+
+  const channels: AnyRecord = doc.channels ?? {}
+  const hubs = new Map<string, SignalRHubModel>()
+
+  for (const channelName of Object.keys(channels)) {
+    const channel: AnyRecord = channels[channelName] ?? {}
+    const binding: AnyRecord | undefined = channel.bindings?.[SIGNALR]
+    if (!binding) {
+      continue
+    }
+    hubs.set(channelName, {
+      documentName,
+      channelName,
+      hubPath: binding.hub ?? channel.address ?? `/${channelName}`,
+      baseUrl,
+      transports: binding.transports ?? [],
+      protocols: binding.protocols ?? [],
+      operations: [],
+      securitySchemes: docSecuritySchemes,
+    })
+  }
+
+  const operations: AnyRecord = doc.operations ?? {}
+  for (const opName of Object.keys(operations)) {
+    const op: AnyRecord = operations[opName] ?? {}
+    const channelName = refName(op.channel?.$ref)
+    const hub = channelName ? hubs.get(channelName) : undefined
+    if (!hub) {
+      continue
+    }
+    const binding: AnyRecord | undefined = op.bindings?.[SIGNALR]
+    const model: SignalROperationModel = {
+      id: opName,
+      target: binding?.target ?? opName,
+      direction: directionFor(op, binding),
+      callType: binding?.callType,
+      summary: op.summary ?? op.description,
+      messages: buildMessages(doc, op),
+    }
+    hub.operations.push(model)
+  }
+
+  return [...hubs.values()]
+}
+
+/**
+ * Resolve the configured documents (inline object or URL) and aggregate the SignalR hubs they
+ * declare. Only documents that are actually AsyncAPI are considered, so OpenAPI sources in the
+ * same Scalar configuration are ignored.
+ */
+export async function loadSignalRHubs(documents: SignalRDocumentRef[]): Promise<SignalRHubModel[]> {
+  const loaded = await loadAsyncApiDocuments(documents)
+  return loaded.flatMap(({ name, doc }) => parseSignalRHubs(name, doc))
+}

package/src/types.ts

@@ -0,0 +1,75 @@
+/** Direction of a SignalR hub operation relative to the server. */
+export type SignalRDirection = 'clientToServer' | 'serverToClient'
+
+/** A reference to an AsyncAPI document — either by URL or as an already-parsed object. */
+export type SignalRDocumentRef = {
+  /** Logical document name (matches the AsyncAPI/source title). */
+  name: string
+  /** URL the AsyncAPI JSON document is served from. */
+  url?: string
+  /** An inline, already-parsed document object (from a Scalar source's `content`). */
+  doc?: Record<string, any>
+}
+
+/** Configuration consumed by the SignalR console plugin. */
+export type SignalRPluginConfig = {
+  /**
+   * AsyncAPI documents to scan for SignalR bindings. Normally derived automatically from the
+   * Scalar configuration's `sources`; only set explicitly to override that discovery.
+   */
+  documents: SignalRDocumentRef[]
+}
+
+/** A message an operation can carry, with a generated example payload. */
+export type SignalRMessageModel = {
+  /** Message name/key (e.g. `chatMessage`). */
+  name: string
+  /** Human-friendly title, when the document provides one. */
+  title?: string
+  /**
+   * A ready-to-send example of the hub method arguments, as a pretty-printed JSON array string
+   * (e.g. `[{ "user": "string", … }]`), generated from the message payload schema.
+   */
+  example: string
+}
+
+/** A single hub operation (client-to-server method or server-to-client event). */
+export type SignalROperationModel = {
+  /** AsyncAPI operation id. */
+  id: string
+  /** The hub method / event name actually used on the wire. */
+  target: string
+  direction: SignalRDirection
+  /** `invocation`, `streamInvocation` or `send`. */
+  callType?: string
+  summary?: string
+  /** Messages this operation carries, each with an example payload to prefill the editor. */
+  messages: SignalRMessageModel[]
+}
+
+/** A minimal representation of an AsyncAPI security scheme, extracted at document-parse time. */
+export type SecuritySchemeModel = {
+  /** e.g. `'apiKey'`, `'http'`, `'oauth2'`, `'openIdConnect'`. */
+  type: string
+  /** For `apiKey`: `'query'`, `'header'`, or `'cookie'`. */
+  in?: string
+  /** For `apiKey`: the query-param or header field name. */
+  name?: string
+  /** For `http`: `'bearer'`, `'basic'`, etc. */
+  scheme?: string
+}
+
+/** A SignalR hub discovered from an AsyncAPI channel with a `signalr` binding. */
+export type SignalRHubModel = {
+  documentName: string
+  channelName: string
+  /** Hub path, e.g. `/chatHub`. */
+  hubPath: string
+  /** Best-effort absolute base URL (scheme://host) resolved from the AsyncAPI servers. */
+  baseUrl: string
+  transports: string[]
+  protocols: string[]
+  operations: SignalROperationModel[]
+  /** Security schemes declared in this hub's AsyncAPI document, keyed by scheme name. */
+  securitySchemes?: Record<string, SecuritySchemeModel>
+}