@bielu/scalar-signalr 0.1.0

package/dist/types/types.d.ts

@@ -0,0 +1,69 @@
+/** 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>;
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@bielu/scalar-signalr",
+  "version": "0.1.0",
+  "description": "Interactive SignalR console plugin for the Scalar API Reference. Reads SignalR AsyncAPI bindings and lets you connect to hubs, invoke methods and subscribe to server events.",
+  "license": "MIT",
+  "author": "Arkadiusz Biel",
+  "type": "module",
+  "main": "./dist/plugin.js",
+  "module": "./dist/plugin.js",
+  "types": "./dist/types/index.d.ts",
+  "files": [
+    "dist/plugin.js",
+    "dist/types",
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/plugin.js"
+    }
+  },
+  "keywords": [
+    "scalar",
+    "signalr",
+    "asyncapi",
+    "api-reference",
+    "plugin",
+    "websocket"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bielu/Bielu.AspNetCore.AsyncApi"
+  },
+  "scripts": {
+    "build:core": "cd ../../Bielu.AspNetCore.AsyncApi.Scalar/assets && npm install && npm run build",
+    "prebuild": "npm run build:core",
+    "build": "vite build && npm run build:standalone && vue-tsc -p tsconfig.json",
+    "build:standalone": "node ../../Bielu.AspNetCore.AsyncApi.Scalar/assets/scripts/build-standalone.mjs",
+    "pretypecheck": "npm run build:core",
+    "typecheck": "vue-tsc --noEmit",
+    "dev": "vite build --watch"
+  },
+  "dependencies": {
+    "@microsoft/signalr": "^8.0.7",
+    "vue": "^3.5.13"
+  },
+  "devDependencies": {
+    "@bielu/scalar-core": "file:../../Bielu.AspNetCore.AsyncApi.Scalar/assets",
+    "@scalar/api-reference": "1.62.9",
+    "@vitejs/plugin-vue": "^5.2.1",
+    "typescript": "^5.6.0",
+    "vite": "^6.4.3",
+    "vue-tsc": "^2.1.10"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,94 @@
+import {
+  getAuthState as coreGetAuthState,
+  resolveSelectedSchemes,
+  setAuthState as coreSetAuthState,
+} from '@bielu/scalar-core'
+import type { SecuritySchemeModel } from './types'
+
+// Thin wrappers around @bielu/scalar-core's auth-state store. Typed as `unknown` so the published
+// declaration files never reference the private core package (see the core README).
+
+/** Store Scalar's PluginAuthState (no-op on older Scalar versions that predate the API). */
+export function setAuthState(auth: unknown): void {
+  coreSetAuthState(auth)
+}
+
+/** The captured PluginAuthState, as an opaque handle for `resolveSignalRAuth`. */
+export function getAuthState(): unknown {
+  return coreGetAuthState()
+}
+
+export type ResolvedAuth = {
+  /** Bearer token to supply via `accessTokenFactory` (http bearer, oauth2, openIdConnect). */
+  accessToken?: string
+  /** Key-value pairs to append as query parameters to the hub URL. */
+  queryParams: Record<string, string>
+  /** Non-fatal warnings about scheme constraints (e.g. header-only schemes that WS cannot send). */
+  warnings: string[]
+}
+
+/**
+ * Resolve Scalar's selected auth for the given document and map the secrets to SignalR connection
+ * options. Browser WebSocket/SSE cannot send arbitrary headers, so API keys are mapped onto query
+ * parameters (with a warning when the scheme declared a header) and only bearer-shaped schemes can
+ * supply an access token. Returns an empty result when auth state is absent (stock Scalar or no
+ * scheme selected), so callers need no guard.
+ */
+export function resolveSignalRAuth(
+  documentName: string,
+  securitySchemes: Record<string, SecuritySchemeModel> | undefined,
+  auth: unknown,
+): ResolvedAuth {
+  const result: ResolvedAuth = { queryParams: {}, warnings: [] }
+
+  for (const { schemeName, type, scheme: schemeDef, secrets } of resolveSelectedSchemes(
+    documentName,
+    securitySchemes,
+    auth,
+  )) {
+    const token = secrets['x-scalar-secret-token']
+
+    switch (type) {
+      case 'apiKey':
+      case 'httpApiKey': {
+        const location = (schemeDef.in ?? 'query').toLowerCase()
+        const paramName = schemeDef.name ?? 'api_key'
+        if (location === 'cookie') {
+          result.warnings.push(
+            `API key scheme "${schemeName}" targets cookie "${paramName}", which the browser ` +
+              `attaches automatically — not appending it to the URL. Ensure the cookie is set ` +
+              `for this origin.`,
+          )
+          break
+        }
+        if (location === 'header') {
+          result.warnings.push(
+            `API key scheme "${schemeName}" targets header "${paramName}", but browser WebSocket/SSE ` +
+              `cannot set arbitrary headers — appending as a query param instead. ` +
+              `Ensure the server also accepts "${paramName}" as a query parameter.`,
+          )
+        }
+        if (token) result.queryParams[paramName] = token
+        break
+      }
+      case 'http': {
+        const scheme = schemeDef?.scheme?.toLowerCase() ?? ''
+        if (scheme === 'bearer' || scheme === '') {
+          if (token) result.accessToken = token
+        } else if (scheme === 'basic') {
+          result.warnings.push(
+            `HTTP Basic scheme "${schemeName}" cannot be sent over browser WebSocket/SSE — ` +
+              `connect will proceed without credentials.`,
+          )
+        }
+        break
+      }
+      case 'oauth2':
+      case 'openIdConnect':
+        if (token) result.accessToken = token
+        break
+    }
+  }
+
+  return result
+}