@swimmesberger/elarion-jsonrpc-client-generator 0.2.21 → 0.2.22-preview.190.1

package/dist/generate.js

@@ -126,6 +126,24 @@ export function generateRpcClientFiles(schema, options = {}) {
         }
     }
     const idempotentMethods = methods.filter((method) => schema.methods[method].idempotent === true);
+    // Every method's client-visible facts, normalized so a consumer never has to tell "absent" from "false".
+    const methodInfo = {};
+    for (const method of methods) {
+        const definition = schema.methods[method];
+        const requires = definition.requires ?? {};
+        methodInfo[method] = {
+            readOnly: definition.readOnly === true,
+            idempotent: definition.idempotent === true,
+            requires: {
+                anonymous: requires.anonymous === true,
+                authenticated: requires.authenticated === true,
+                permissions: [...(requires.permissions ?? [])].sort(),
+                roles: [...(requires.roles ?? [])].sort(),
+                serverChecks: requires.serverChecks === true,
+            },
+            tags: Object.fromEntries(Object.entries(definition.tags ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
+        };
+    }
     // Where each method carries file payloads (x-elarion-file nodes), so the client can convert between
     // native File values and the base64 wire envelope. Methods without files are omitted entirely.
     const paramsFilePaths = {};
@@ -148,6 +166,7 @@ export function generateRpcClientFiles(schema, options = {}) {
         schemasFileName,
         methods,
         idempotentMethods,
+        methodInfo,
         errorCodesByMethod,
         paramsFilePaths,
         resultFilePaths,

package/dist/rpc-client-source.d.ts

@@ -1,3 +1,16 @@
+/** The normalized client-visible facts of one method, emitted verbatim into `rpcMethodInfo`. */
+export interface RpcMethodInfoLiteral {
+    readOnly: boolean;
+    idempotent: boolean;
+    requires: {
+        anonymous: boolean;
+        authenticated: boolean;
+        permissions: string[];
+        roles: string[];
+        serverChecks: boolean;
+    };
+    tags: Record<string, string>;
+}
 interface GenerateRpcClientSourceOptions {
     generatedBy: string;
     sourceLabel: string;
@@ -5,6 +18,8 @@ interface GenerateRpcClientSourceOptions {
     schemasFileName: string;
     methods: readonly string[];
     idempotentMethods: readonly string[];
+    /** Every method's normalized requirements, read-only flag and tags. */
+    methodInfo: Readonly<Record<string, RpcMethodInfoLiteral>>;
     /** The declared error codes per method (ADR-0080); methods without declared errors are omitted. */
     errorCodesByMethod: Readonly<Record<string, readonly string[]>>;
     /** Property paths of file payloads per method ('*' = array items, [] = the value itself); omitted methods carry none. */

package/dist/rpc-client-source.js

@@ -120,6 +120,39 @@ export function generateRpcClientSource(options) {
         ...generateMethodNameLines(options.methods),
         `const rpcIdempotentMethods: ReadonlySet<RpcMethod> = new Set(${JSON.stringify(options.idempotentMethods)})`,
         '',
+        '/**',
+        ' * What a caller needs, as far as a client can tell: `anonymous` (any caller), or `authenticated` with every',
+        ' * permission and role listed. `serverChecks` marks requirements only the server evaluates (a policy, claim or',
+        ' * resource check), so an allowed-looking call may still be refused.',
+        ' */',
+        'export interface RpcMethodRequirements {',
+        '  readonly anonymous: boolean',
+        '  readonly authenticated: boolean',
+        '  readonly permissions: readonly string[]',
+        '  readonly roles: readonly string[]',
+        '  readonly serverChecks: boolean',
+        '}',
+        '',
+        '/** What the schema says about a method before it is called. */',
+        'export interface RpcMethodInfo {',
+        '  /** The request is a query: the operation only reads. */',
+        '  readonly readOnly: boolean',
+        '  /** The operation is [Idempotent]: the client attaches an idempotency key by default. */',
+        '  readonly idempotent: boolean',
+        '  readonly requires: RpcMethodRequirements',
+        '  /** The handler\'s [ClientTag] hints (for example a timeout) by key. */',
+        '  readonly tags: Readonly<Record<string, string>>',
+        '}',
+        '',
+        '/**',
+        ' * Every method\'s requirements, read-only flag and tags, from the server\'s handler declarations — the input of',
+        ' * UI gating (for example canCall from @swimmesberger/elarion-contributions). A UX projection, never security:',
+        ' * the server authorizes every call.',
+        ' */',
+        'export const rpcMethodInfo: { readonly [M in RpcMethod]: RpcMethodInfo } = {',
+        ...options.methods.map((method) => `  ${JSON.stringify(method)}: ${JSON.stringify(options.methodInfo[method])},`),
+        '}',
+        '',
         `const rpcErrorCodes: Partial<Record<RpcMethod, readonly string[]>> = ${JSON.stringify(options.errorCodesByMethod)}`,
         '',
         '/** True when `error` is an RpcError carrying one of the error codes `method` declares. */',
@@ -180,6 +213,11 @@ export function generateRpcClientSource(options) {
         '  readonly data: TData',
         '  /** The numeric JSON-RPC error code (the coarse error kind, see ElarionErrorCodes). */',
         '  readonly rpcCode: number',
+        '  /**',
+        '   * The support reference of an unexpected server error (code "internal"): show it next to the message so a',
+        '   * user can quote it. Undefined for every other error.',
+        '   */',
+        '  readonly reference: string | undefined',
         '',
         '  constructor(rpcCode: number, message: string, wireData?: unknown) {',
         '    super(message)',
@@ -188,6 +226,7 @@ export function generateRpcClientSource(options) {
         '    const envelope = readErrorData(wireData)',
         '    this.code = (envelope?.code ?? defaultErrorCode(rpcCode)) as TCode',
         '    this.data = envelope?.data as TData',
+        '    this.reference = envelope?.reference',
         '  }',
         '',
         '  get isParseError() {',
@@ -677,10 +716,11 @@ export function generateRpcClientSource(options) {
         '  return rpcError',
         '}',
         '',
-        '// The wire shape of error.data is always { code, data? } (ADR-0080).',
-        'function readErrorData(value: unknown): { code: string; data?: unknown } | undefined {',
+        '// The wire shape of error.data is always { code, data?, reference? } (ADR-0080).',
+        'function readErrorData(value: unknown): { code: string; data?: unknown; reference?: string | undefined } | undefined {',
         '  if (!isRecord(value) || typeof value.code !== ' + "'string'" + ') return undefined',
-        '  return { code: value.code, data: value.data }',
+        "  const reference = typeof value.reference === 'string' ? value.reference : undefined",
+        '  return { code: value.code, data: value.data, reference }',
         '}',
         '',
         '// Fallback for a server that sends no error.data: the default code of the numeric kind.',

package/dist/schema.d.ts

@@ -47,6 +47,24 @@ export interface RpcMethodSchema {
     /** The declared error contract, keyed by stable error code; omitted when the method declares none. */
     errors?: Record<string, RpcErrorSchema>;
     idempotent?: boolean;
+    /** What a caller needs, as far as a client can tell; omitted when the handler declares nothing. */
+    requires?: RpcMethodRequirementsSchema;
+    /** Set when the request is an IQuery: the operation only reads. */
+    readOnly?: boolean;
+    /** The handler's [ClientTag] hints by key; omitted when it declares none. */
+    tags?: Record<string, string>;
+}
+/**
+ * The per-method `requires` block of the server exporter: `anonymous` alone, or the requirements a client can
+ * evaluate against its session (`authenticated`, `permissions`, `roles`, all of them) plus `serverChecks` for
+ * requirements only the server can evaluate (a policy, claim or resource check).
+ */
+export interface RpcMethodRequirementsSchema {
+    anonymous?: boolean;
+    authenticated?: boolean;
+    permissions?: string[];
+    roles?: string[];
+    serverChecks?: boolean;
 }
 /** One structured permission from the schema's capability vocabulary ({resource}.{verb} plus its parts). */
 export interface RpcCapabilityPermission {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swimmesberger/elarion-jsonrpc-client-generator",
-  "version": "0.2.21",
+  "version": "0.2.22-preview.190.1",
   "description": "Generate TypeScript RPC contracts, Zod schemas, and a fetch client from Elarion JSON-RPC schema exports.",
   "license": "Apache-2.0",
   "type": "module",