@bielu/scalar-grpc 0.1.0

package/dist/types/auth.d.ts

@@ -0,0 +1,19 @@
+import type { SecuritySchemeModel } from './types';
+/** Store Scalar's PluginAuthState (no-op on older Scalar versions that predate the API). */
+export declare function setAuthState(auth: unknown): void;
+/** The captured PluginAuthState, as an opaque handle for `resolveGrpcAuth`. */
+export declare function getAuthState(): unknown;
+export type ResolvedAuth = {
+    /** Metadata (HTTP headers) to send with each gRPC-Web call. */
+    headers: Record<string, string>;
+    /** Non-fatal warnings about scheme constraints (e.g. query-based keys gRPC-Web cannot send). */
+    warnings: string[];
+};
+/**
+ * Resolve Scalar's selected auth for the given document and map the secrets to gRPC-Web call
+ * metadata. gRPC-Web metadata is plain HTTP headers, so header API keys, bearer tokens and HTTP
+ * Basic all map directly; query-based API keys have no place on a gRPC-Web request and only
+ * produce a warning. Returns an empty result when auth state is absent (stock Scalar or no scheme
+ * selected), so callers need no guard.
+ */
+export declare function resolveGrpcAuth(documentName: string, securitySchemes: Record<string, SecuritySchemeModel> | undefined, auth: unknown): ResolvedAuth;

package/dist/types/components/GrpcConsole.vue.d.ts

@@ -0,0 +1,7 @@
+import type { GrpcDocumentRef } from '../types';
+type __VLS_Props = {
+    options?: Record<string, any>;
+    documents?: GrpcDocumentRef[];
+};
+declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/types/discovery.d.ts

@@ -0,0 +1,13 @@
+import type { GrpcDocumentRef } from './types';
+/** How the gRPC bundle discovers its AsyncAPI documents (see `resolveDocuments` in @bielu/scalar-core). */
+export declare const GRPC_DISCOVERY: {
+    readonly configKey: "grpc";
+    readonly globalName: "__BIELU_SCALAR_GRPC__";
+};
+/**
+ * Resolves the documents to scan, in decreasing priority: an explicit override (`documents` prop);
+ * a `GrpcPluginConfig` embedded inline on the Scalar config as `config.grpc`; a
+ * `window.__BIELU_SCALAR_GRPC__` global; otherwise auto-discovery from the Scalar configuration
+ * passed as `options`.
+ */
+export declare function resolveDocuments(options: Record<string, any> | undefined, override?: GrpcDocumentRef[]): GrpcDocumentRef[];

package/dist/types/grpc-bindings.d.ts

@@ -0,0 +1,11 @@
+import type { GrpcDocumentRef, GrpcServiceModel } from './types';
+type AnyRecord = Record<string, any>;
+/** Extract every gRPC service (channel + its operations) from a parsed AsyncAPI document. */
+export declare function parseGrpcServices(documentName: string, doc: AnyRecord): GrpcServiceModel[];
+/**
+ * Resolve the configured documents (inline object or URL) and aggregate the gRPC services they
+ * declare. Only documents that are actually AsyncAPI are considered, so OpenAPI sources in the
+ * same Scalar configuration are ignored.
+ */
+export declare function loadGrpcServices(documents: GrpcDocumentRef[]): Promise<GrpcServiceModel[]>;
+export {};

package/dist/types/grpc-client.d.ts

@@ -0,0 +1,39 @@
+import type { DescMethod, DescService, FileRegistry, JsonValue } from '@bufbuild/protobuf';
+/** The default base path `MapScalarGrpcAssets()` serves the bundle and descriptors from. */
+export declare const DEFAULT_ASSETS_PATH = "/bielu/scalar/grpc";
+/**
+ * Capture the bundle's own script URL. Must be called at module-evaluation time, while
+ * `document.currentScript` still points at the executing `<script>` tag.
+ */
+export declare function captureBundleScriptSrc(): void;
+/**
+ * The URL of the protobuf descriptor endpoint for a target base URL.
+ *
+ * When the bundle was served by `MapScalarGrpcAssets()` from the same origin as the target, the
+ * descriptors live next to plugin.js (whatever custom path it was mapped under). When the bundle
+ * came from elsewhere (e.g. a CDN in the Aspire setup), fall back to the default assets path on
+ * the target origin.
+ */
+export declare function descriptorsUrlFor(baseUrl: string): string;
+/** Load (and cache) the protobuf descriptor registry served by the .NET package. */
+export declare function loadDescriptorRegistry(url: string): Promise<FileRegistry>;
+/** Resolve a service and RPC method from the descriptor registry, with actionable errors. */
+export declare function resolveMethod(registry: FileRegistry, serviceName: string, methodName: string): {
+    service: DescService;
+    method: DescMethod;
+};
+export type GrpcCallOptions = {
+    /** The target origin (scheme://host) the gRPC-Web calls are sent to. */
+    baseUrl: string;
+    /** Call metadata — gRPC-Web metadata is plain HTTP headers. */
+    headers?: Record<string, string>;
+    /** Call deadline in milliseconds. */
+    timeoutMs?: number;
+};
+/** Invoke a unary RPC with a proto3-JSON request; returns the response as proto3 JSON. */
+export declare function invokeUnary(registry: FileRegistry, serviceName: string, methodName: string, requestJson: JsonValue, options: GrpcCallOptions): Promise<JsonValue>;
+/**
+ * Invoke a server-streaming RPC with a proto3-JSON request. Each response message is passed to
+ * `onMessage` as proto3 JSON; resolves with the total message count once the stream completes.
+ */
+export declare function invokeServerStreaming(registry: FileRegistry, serviceName: string, methodName: string, requestJson: JsonValue, options: GrpcCallOptions, onMessage: (message: JsonValue) => void): Promise<number>;

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export { createGrpcPlugin } from './plugin';
+export { loadGrpcServices, parseGrpcServices } from './grpc-bindings';
+export { descriptorsUrlFor, loadDescriptorRegistry } from './grpc-client';
+export type { GrpcDocumentRef, GrpcMethodModel, GrpcMethodTypeName, GrpcPluginConfig, GrpcServiceModel, } from './types';

package/dist/types/plugin.d.ts

@@ -0,0 +1,32 @@
+import type { GrpcDocumentRef } from './types';
+/** The custom element tag the console is rendered as (registered in `index.ts`). */
+export declare const GRPC_CONSOLE_TAG = "bielu-grpc-console";
+/** The Scalar plugin's identifier, used to detect (and de-duplicate) an existing registration. */
+export declare const GRPC_PLUGIN_NAME = "bielu-grpc";
+/** How the gRPC console registers with Scalar (plugin name, element tag, sidebar label). */
+export declare const GRPC_PLUGIN_SPEC: {
+    readonly pluginName: "bielu-grpc";
+    readonly elementTag: "bielu-grpc-console";
+    readonly sidebarLabel: "gRPC";
+};
+/**
+ * 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 gRPC 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 declare const createGrpcPlugin: (documents?: GrpcDocumentRef[]) => ApiReferencePlugin;

package/dist/types/types.d.ts

@@ -0,0 +1,78 @@
+/** The four kinds of RPC a gRPC method can be (camelCase wire tokens from the `grpc` binding). */
+export type GrpcMethodTypeName = 'unary' | 'serverStreaming' | 'clientStreaming' | 'bidirectionalStreaming';
+/** A reference to an AsyncAPI document — either by URL or as an already-parsed object. */
+export type GrpcDocumentRef = {
+    /** 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 gRPC console plugin. */
+export type GrpcPluginConfig = {
+    /**
+     * AsyncAPI documents to scan for gRPC bindings. Normally derived automatically from the
+     * Scalar configuration's `sources`; only set explicitly to override that discovery.
+     */
+    documents: GrpcDocumentRef[];
+};
+/** A message an RPC method can carry, with a generated example payload. */
+export type GrpcMessageModel = {
+    /** Message name/key (e.g. `helloRequest`). */
+    name: string;
+    /** Human-friendly title, when the document provides one. */
+    title?: string;
+    /**
+     * A ready-to-send example of the request message, as a pretty-printed JSON object string
+     * (proto3 JSON mapping), generated from the message payload schema.
+     */
+    example: string;
+};
+/** A single RPC method discovered from an AsyncAPI operation with a `grpc` binding. */
+export type GrpcMethodModel = {
+    /** AsyncAPI operation id. */
+    id: string;
+    /** The RPC method name actually used on the wire, e.g. `SayHello`. */
+    method: string;
+    /** The kind of RPC. Missing method types are treated as unary. */
+    methodType?: GrpcMethodTypeName;
+    /** The fully-qualified protobuf type of the request message, e.g. `greet.HelloRequest`. */
+    requestType?: string;
+    /** The fully-qualified protobuf type of the response message, e.g. `greet.HelloReply`. */
+    responseType?: string;
+    /** The declared idempotency level (e.g. `noSideEffects`). */
+    idempotencyLevel?: string;
+    /** The call deadline in seconds, when the operation declares one. */
+    deadlineSeconds?: number;
+    summary?: string;
+    /** Messages this operation carries, each with an example payload to prefill the editor. */
+    messages: GrpcMessageModel[];
+};
+/** 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 gRPC service discovered from an AsyncAPI channel with a `grpc` binding. */
+export type GrpcServiceModel = {
+    documentName: string;
+    channelName: string;
+    /** The fully-qualified service name, e.g. `greet.Greeter`. */
+    service: string;
+    /** The protobuf package the service belongs to, e.g. `greet`. */
+    package?: string;
+    /** Path or URL to the `.proto` file that defines the service. */
+    protoFile?: string;
+    /** Best-effort absolute base URL (scheme://host) resolved from the AsyncAPI servers. */
+    baseUrl: string;
+    methods: GrpcMethodModel[];
+    /** Security schemes declared in this service's AsyncAPI document, keyed by scheme name. */
+    securitySchemes?: Record<string, SecuritySchemeModel>;
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@bielu/scalar-grpc",
+  "version": "0.1.0",
+  "description": "Interactive gRPC console plugin for the Scalar API Reference. Reads gRPC AsyncAPI bindings and lets you invoke unary and server-streaming methods over gRPC-Web.",
+  "license": "MIT",
+  "author": "Arkadiusz Biel",
+  "type": "module",
+  "main": "./dist/plugin.js",
+  "module": "./dist/plugin.js",
+  "types": "./dist/types/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/plugin.js"
+    }
+  },
+  "keywords": [
+    "scalar",
+    "grpc",
+    "grpc-web",
+    "asyncapi",
+    "api-reference",
+    "plugin"
+  ],
+  "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": {
+    "@bufbuild/protobuf": "^2.2.0",
+    "@connectrpc/connect": "^2.0.0",
+    "@connectrpc/connect-web": "^2.0.0",
+    "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,93 @@
+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 `resolveGrpcAuth`. */
+export function getAuthState(): unknown {
+  return coreGetAuthState()
+}
+
+export type ResolvedAuth = {
+  /** Metadata (HTTP headers) to send with each gRPC-Web call. */
+  headers: Record<string, string>
+  /** Non-fatal warnings about scheme constraints (e.g. query-based keys gRPC-Web cannot send). */
+  warnings: string[]
+}
+
+/**
+ * Resolve Scalar's selected auth for the given document and map the secrets to gRPC-Web call
+ * metadata. gRPC-Web metadata is plain HTTP headers, so header API keys, bearer tokens and HTTP
+ * Basic all map directly; query-based API keys have no place on a gRPC-Web request and only
+ * produce a warning. Returns an empty result when auth state is absent (stock Scalar or no scheme
+ * selected), so callers need no guard.
+ */
+export function resolveGrpcAuth(
+  documentName: string,
+  securitySchemes: Record<string, SecuritySchemeModel> | undefined,
+  auth: unknown,
+): ResolvedAuth {
+  const result: ResolvedAuth = { headers: {}, 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 ?? 'header').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 adding a header. Ensure the cookie is set for the ` +
+              `target origin.`,
+          )
+          break
+        }
+        if (location === 'query') {
+          result.warnings.push(
+            `API key scheme "${schemeName}" targets query parameter "${paramName}", but gRPC-Web ` +
+              `requests carry no query string — sending it as a "${paramName}" header instead. ` +
+              `Ensure the server also accepts "${paramName}" as a header.`,
+          )
+        }
+        if (token) result.headers[paramName] = token
+        break
+      }
+      case 'http': {
+        const scheme = schemeDef?.scheme?.toLowerCase() ?? ''
+        if (scheme === 'bearer' || scheme === '') {
+          if (token) result.headers['Authorization'] = `Bearer ${token}`
+        } else if (scheme === 'basic') {
+          const username = secrets['x-scalar-secret-username'] ?? ''
+          const password = secrets['x-scalar-secret-password'] ?? ''
+          if (username || password) {
+            result.headers['Authorization'] = `Basic ${btoa(`${username}:${password}`)}`
+          }
+        }
+        break
+      }
+      case 'oauth2':
+      case 'openIdConnect':
+        if (token) result.headers['Authorization'] = `Bearer ${token}`
+        break
+    }
+  }
+
+  return result
+}