@swimmesberger/elarion-jsonrpc-client-generator 0.2.3-preview.61.1 → 0.2.3-preview.62.1

package/dist/cli.js

@@ -42,6 +42,11 @@ function parseArgs(argv) {
             index += 1;
             continue;
         }
+        if (arg === '--session-client') {
+            options.sessionClientFileName = next;
+            index += 1;
+            continue;
+        }
         if (arg === '--source-label') {
             options.sourceLabel = next;
             index += 1;
@@ -60,6 +65,8 @@ Options:
   --types <file>        TypeScript types filename (default: rpc-types.ts)
   --schemas <file>      Zod schemas filename (default: rpc-schemas.ts)
   --client <file>       Fetch client filename (default: rpc-client.ts)
+  --session-client <file> Client-capability snapshot client + OpenFeature provider (default: session-client.ts;
+                          emitted only when the schema exposes the elarion.session operation)
   --source-label <text> Source label written into generated file headers
 `);
 }
@@ -74,11 +81,17 @@ function main() {
         typesFileName: options.typesFileName,
         schemasFileName: options.schemasFileName,
         clientFileName: options.clientFileName,
+        sessionClientFileName: options.sessionClientFileName,
     });
     mkdirSync(outDir, { recursive: true });
     writeFileSync(resolve(outDir, generated.typesFileName), generated.typesSource, 'utf-8');
     writeFileSync(resolve(outDir, generated.schemasFileName), generated.schemasSource, 'utf-8');
     writeFileSync(resolve(outDir, generated.clientFileName), generated.clientSource, 'utf-8');
-    console.log(`[jsonrpc-client-generator] Generated ${generated.methodCount} RPC method types and schemas -> ${outDir}`);
+    let sessionNote = '';
+    if (generated.sessionClientFileName !== undefined && generated.sessionClientSource !== undefined) {
+        writeFileSync(resolve(outDir, generated.sessionClientFileName), generated.sessionClientSource, 'utf-8');
+        sessionNote = ` (+ ${generated.sessionClientFileName})`;
+    }
+    console.log(`[jsonrpc-client-generator] Generated ${generated.methodCount} RPC method types and schemas${sessionNote} -> ${outDir}`);
 }
 main();

package/dist/generate.js

@@ -2,11 +2,14 @@ import { jsonSchemaToTypeScript } from './json-schema-to-ts.js';
 import { jsonSchemaToZod } from './json-schema-to-zod.js';
 import { stripNullable } from './json-schema.js';
 import { generateRpcClientSource } from './rpc-client-source.js';
+import { generateSessionClientSource } from './session-client-source.js';
 const DEFAULT_GENERATED_BY = 'elarion-jsonrpc-client-generator';
 const DEFAULT_SOURCE_LABEL = 'rpc-schema.json';
 const DEFAULT_TYPES_FILE = 'rpc-types.ts';
 const DEFAULT_SCHEMAS_FILE = 'rpc-schemas.ts';
 const DEFAULT_CLIENT_FILE = 'rpc-client.ts';
+const DEFAULT_SESSION_CLIENT_FILE = 'session-client.ts';
+const DEFAULT_SESSION_OPERATION = 'elarion.session';
 export { UnsupportedJsonSchemaError } from './json-schema.js';
 export function generateRpcClientFiles(schema, options = {}) {
     const generatedBy = options.generatedBy ?? DEFAULT_GENERATED_BY;
@@ -68,6 +71,20 @@ export function generateRpcClientFiles(schema, options = {}) {
         methods,
         idempotentMethods,
     });
+    // The client-capability snapshot client + OpenFeature provider (ADR-0030) is emitted only when the host exposes
+    // the session operation, so a schema without it produces byte-identical output. The schema's optional
+    // `capabilities` vocabulary (ADR-0032) turns the emitted module/flag/permission/role names into typed constants.
+    const sessionOperationName = options.sessionOperationName ?? DEFAULT_SESSION_OPERATION;
+    const sessionClientFileName = options.sessionClientFileName ?? DEFAULT_SESSION_CLIENT_FILE;
+    const hasSession = Object.prototype.hasOwnProperty.call(schema.methods, sessionOperationName);
+    const sessionClientSource = hasSession
+        ? generateSessionClientSource({
+            generatedBy,
+            sourceLabel,
+            operationName: sessionOperationName,
+            capabilities: schema.capabilities,
+        })
+        : undefined;
     return {
         methodCount: methods.length,
         typesFileName,
@@ -76,6 +93,8 @@ export function generateRpcClientFiles(schema, options = {}) {
         typesSource: typesLines.join('\n'),
         schemasSource: schemasLines.join('\n'),
         clientSource,
+        sessionClientFileName: sessionClientSource === undefined ? undefined : sessionClientFileName,
+        sessionClientSource,
     };
 }
 function createContext(root, path) {

package/dist/schema.d.ts

@@ -25,8 +25,27 @@ export interface RpcMethodSchema {
     result: JsonSchema;
     idempotent?: boolean;
 }
+/** One structured permission from the schema's capability vocabulary ({resource}.{verb} plus its parts). */
+export interface RpcCapabilityPermission {
+    permission: string;
+    resource: string;
+    verb: string;
+}
+/**
+ * The capability vocabulary block emitted by the server exporter (ADR-0032): module names with the
+ * `[ClientFeatures]` each exposes, the structured permission catalog, and role names. All optional — older
+ * schemas (or hosts without the session/authorization registrations) simply omit it.
+ */
+export interface RpcSchemaCapabilities {
+    modules?: Record<string, {
+        features?: string[];
+    }>;
+    permissions?: RpcCapabilityPermission[];
+    roles?: string[];
+}
 export interface RpcSchema {
     methods: Record<string, RpcMethodSchema>;
+    capabilities?: RpcSchemaCapabilities;
 }
 export interface GenerateRpcClientOptions {
     generatedBy?: string;
@@ -34,6 +53,10 @@ export interface GenerateRpcClientOptions {
     typesFileName?: string;
     schemasFileName?: string;
     clientFileName?: string;
+    /** Output filename for the client-capability snapshot client + OpenFeature provider (default `session-client.ts`). */
+    sessionClientFileName?: string;
+    /** The operation name the client-capability snapshot is served under (default `elarion.session`). */
+    sessionOperationName?: string;
 }
 export interface GeneratedRpcClientFiles {
     methodCount: number;
@@ -43,4 +66,10 @@ export interface GeneratedRpcClientFiles {
     typesSource: string;
     schemasSource: string;
     clientSource: string;
+    /**
+     * The client-capability snapshot client + OpenFeature provider (ADR-0020). Present only when the schema exposes
+     * the session operation (default `elarion.session`); otherwise both fields are `undefined`.
+     */
+    sessionClientFileName?: string;
+    sessionClientSource?: string;
 }

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

@@ -0,0 +1,22 @@
+import type { RpcSchemaCapabilities } from './schema.js';
+export interface GenerateSessionClientSourceOptions {
+    generatedBy: string;
+    sourceLabel: string;
+    /** The bus/REST operation name the session snapshot is served under (default `elarion.session`). */
+    operationName: string;
+    /** The schema's capability vocabulary (ADR-0032); absent on older schemas — types then fall back to `string`. */
+    capabilities?: RpcSchemaCapabilities;
+}
+/**
+ * Emits a self-contained client for the Elarion client-capability snapshot (ADR-0030): a typed `ClientSnapshot`,
+ * synchronous capability accessors, and an `@openfeature/web-sdk`-shaped provider that answers every key from the
+ * cached snapshot via the reserved `module.` / `permission.` / `role.` namespaces (a bare key is a flag/variant).
+ * When the schema carries the ADR-0032 capability vocabulary, the module/flag/permission/role names become typed
+ * constants and literal unions, so a typo in a capability check is a compile error; accessor parameters keep an
+ * escape hatch (`| (string & {})`) for names outside the exported vocabulary.
+ *
+ * The module has **no imports** — it neither depends on the RPC schema's generated dictionary typing nor pins
+ * `@openfeature/web-sdk`, so it type-checks and runs in any browser or Node target. The consumer fetches the
+ * snapshot through the generated RPC client (`rpc.{operation}(...)`) and hands it to the factory.
+ */
+export declare function generateSessionClientSource(options: GenerateSessionClientSourceOptions): string;

package/dist/session-client-source.js

@@ -0,0 +1,232 @@
+const q = (value) => JSON.stringify(value);
+/**
+ * Emits the typed vocabulary section: `Modules`/`Flags`/`Permissions`/`Roles` const objects (only those with
+ * entries) plus the `ModuleName`/`FlagName`/`PermissionName`/`RoleName` aliases the accessors reference. With no
+ * vocabulary every alias is `string`, so the emitted accessors keep their pre-vocabulary signatures.
+ */
+function vocabularySection(capabilities) {
+    const moduleNames = Object.keys(capabilities?.modules ?? {}).sort();
+    const flagNames = [
+        ...new Set(Object.values(capabilities?.modules ?? {}).flatMap((m) => m.features ?? [])),
+    ].sort();
+    const permissions = [...(capabilities?.permissions ?? [])].sort((a, b) => a.permission < b.permission ? -1 : a.permission > b.permission ? 1 : 0);
+    const roles = [...(capabilities?.roles ?? [])].sort();
+    const lines = [];
+    if (moduleNames.length > 0) {
+        lines.push('/** Module names declared by the backend (enabled at schema-export time). */');
+        lines.push('export const Modules = {');
+        for (const name of moduleNames)
+            lines.push(`  ${q(name)}: ${q(name)},`);
+        lines.push('} as const');
+        lines.push('export type ModuleName = (typeof Modules)[keyof typeof Modules]');
+    }
+    else {
+        lines.push('/** No module vocabulary in the schema — any string is accepted. */');
+        lines.push('export type ModuleName = string');
+    }
+    lines.push('');
+    if (flagNames.length > 0) {
+        lines.push('/** Flag/variant names the backend exposes to the client (the union of every [ClientFeatures] list). */');
+        lines.push('export const Flags = {');
+        for (const name of flagNames)
+            lines.push(`  ${q(name)}: ${q(name)},`);
+        lines.push('} as const');
+        lines.push('export type FlagName = (typeof Flags)[keyof typeof Flags]');
+    }
+    else {
+        lines.push('/** No flag vocabulary in the schema — any string is accepted. */');
+        lines.push('export type FlagName = string');
+    }
+    lines.push('');
+    if (permissions.length > 0) {
+        const byResource = new Map();
+        for (const entry of permissions) {
+            const list = byResource.get(entry.resource) ?? [];
+            list.push({ verb: entry.verb, permission: entry.permission });
+            byResource.set(entry.resource, list);
+        }
+        lines.push('/** The declared permission catalog, nested by resource → verb (values are the composed claim strings). */');
+        lines.push('export const Permissions = {');
+        for (const [resource, entries] of [...byResource.entries()].sort(([a], [b]) => (a < b ? -1 : 1))) {
+            lines.push(`  ${q(resource)}: {`);
+            for (const { verb, permission } of entries)
+                lines.push(`    ${q(verb)}: ${q(permission)},`);
+            lines.push('  },');
+        }
+        lines.push('} as const');
+        lines.push(`export type PermissionName = ${permissions.map((p) => q(p.permission)).join(' | ')}`);
+    }
+    else {
+        lines.push('/** No permission vocabulary in the schema — any string is accepted. */');
+        lines.push('export type PermissionName = string');
+    }
+    lines.push('');
+    if (roles.length > 0) {
+        lines.push('/** Role names declared by the backend ([RequireRole] across enabled modules). */');
+        lines.push('export const Roles = {');
+        for (const name of roles)
+            lines.push(`  ${q(name)}: ${q(name)},`);
+        lines.push('} as const');
+        lines.push('export type RoleName = (typeof Roles)[keyof typeof Roles]');
+    }
+    else {
+        lines.push('/** No role vocabulary in the schema — any string is accepted. */');
+        lines.push('export type RoleName = string');
+    }
+    return lines.join('\n');
+}
+/**
+ * Emits a self-contained client for the Elarion client-capability snapshot (ADR-0030): a typed `ClientSnapshot`,
+ * synchronous capability accessors, and an `@openfeature/web-sdk`-shaped provider that answers every key from the
+ * cached snapshot via the reserved `module.` / `permission.` / `role.` namespaces (a bare key is a flag/variant).
+ * When the schema carries the ADR-0032 capability vocabulary, the module/flag/permission/role names become typed
+ * constants and literal unions, so a typo in a capability check is a compile error; accessor parameters keep an
+ * escape hatch (`| (string & {})`) for names outside the exported vocabulary.
+ *
+ * The module has **no imports** — it neither depends on the RPC schema's generated dictionary typing nor pins
+ * `@openfeature/web-sdk`, so it type-checks and runs in any browser or Node target. The consumer fetches the
+ * snapshot through the generated RPC client (`rpc.{operation}(...)`) and hands it to the factory.
+ */
+export function generateSessionClientSource(options) {
+    const { generatedBy, sourceLabel, operationName, capabilities } = options;
+    return `// Auto-generated by ${generatedBy} — DO NOT EDIT
+// Source: ${sourceLabel}
+//
+// Client-capability snapshot (operation: ${JSON.stringify(operationName)}). Fetch it with the generated RPC client
+// and pass it to createSessionCapabilities / createElarionOpenFeatureProvider.
+
+/** The current user's identity and raw grants, as projected into the snapshot. */
+export interface ClientSnapshotUser {
+  readonly id: string
+  readonly email?: string | null
+  readonly isAuthenticated: boolean
+  readonly roles: readonly string[]
+  readonly permissions: readonly string[]
+}
+
+/** The client-capability snapshot returned by the ${JSON.stringify(operationName)} operation. */
+export interface ClientSnapshot {
+  readonly user: ClientSnapshotUser
+  readonly modules: Readonly<Record<string, boolean>>
+  readonly flags: Readonly<Record<string, boolean>>
+  readonly variants: Readonly<Record<string, string>>
+}
+
+${vocabularySection(capabilities)}
+
+/** The reserved OpenFeature key namespaces and their typed builders. */
+export const Keys = {
+  module: (name: ModuleName | (string & {})): string => \`module.\${name}\`,
+  permission: (permission: PermissionName | (string & {})): string => \`permission.\${permission}\`,
+  role: (role: RoleName | (string & {})): string => \`role.\${role}\`,
+} as const
+
+/** Synchronous, typed accessors over a cached snapshot. */
+export class SessionCapabilities {
+  // An explicit field, not a constructor parameter property — the emitted code must stay valid under
+  // 'erasableSyntaxOnly' (parameter properties are non-erasable TypeScript).
+  private readonly snapshot: ClientSnapshot
+
+  constructor(snapshot: ClientSnapshot) {
+    this.snapshot = snapshot
+  }
+
+  get user(): ClientSnapshotUser {
+    return this.snapshot.user
+  }
+
+  isModuleEnabled(name: ModuleName | (string & {})): boolean {
+    return this.snapshot.modules[name] ?? false
+  }
+
+  hasRole(role: RoleName | (string & {})): boolean {
+    return this.snapshot.user.roles.includes(role)
+  }
+
+  hasPermission(permission: PermissionName | (string & {})): boolean {
+    return this.snapshot.user.permissions.includes(permission)
+  }
+
+  isFlagEnabled(name: FlagName | (string & {})): boolean {
+    return this.snapshot.flags[name] ?? false
+  }
+
+  getVariant(name: FlagName | (string & {})): string | undefined {
+    return this.snapshot.variants[name]
+  }
+
+  /** Resolves a reserved-namespace boolean key (the OpenFeature boolean read). */
+  resolveBoolean(key: string): boolean {
+    if (key.startsWith('module.')) return this.isModuleEnabled(key.slice('module.'.length))
+    if (key.startsWith('permission.')) return this.hasPermission(key.slice('permission.'.length))
+    if (key.startsWith('role.')) return this.hasRole(key.slice('role.'.length))
+    return this.isFlagEnabled(key)
+  }
+}
+
+export function createSessionCapabilities(snapshot: ClientSnapshot): SessionCapabilities {
+  return new SessionCapabilities(snapshot)
+}
+
+/** A single flag resolution result (structurally compatible with OpenFeature's ResolutionDetails). */
+export interface ResolutionDetails<T> {
+  readonly value: T
+  readonly variant?: string
+  readonly reason: string
+}
+
+/**
+ * The subset of the \`@openfeature/web-sdk\` Provider surface this snapshot provider implements. Register it with
+ * \`OpenFeature.setProvider(provider as unknown as Provider)\` — the static-context (web) paradigm reads
+ * synchronously, so module enablement (deployment-scoped, context-invariant) rides the same snapshot.
+ */
+export interface ElarionWebProvider {
+  readonly metadata: { readonly name: string }
+  readonly runsOn: 'client'
+  resolveBooleanEvaluation(flagKey: string, defaultValue: boolean): ResolutionDetails<boolean>
+  resolveStringEvaluation(flagKey: string, defaultValue: string): ResolutionDetails<string>
+  resolveNumberEvaluation(flagKey: string, defaultValue: number): ResolutionDetails<number>
+  resolveObjectEvaluation<T>(flagKey: string, defaultValue: T): ResolutionDetails<T>
+}
+
+const STATIC = 'STATIC'
+const DEFAULT = 'DEFAULT'
+
+/**
+ * Builds an OpenFeature web-SDK provider hydrated from one session snapshot. Every key resolves from the cache:
+ * \`module.{name}\` / \`permission.{p}\` / \`role.{r}\` are booleans, a bare key is a flag (boolean) or a variant
+ * (string), and anything else falls back to the default. No network calls — refresh by building a new provider
+ * from a freshly fetched snapshot (e.g. on \`onContextChange\`).
+ */
+export function createElarionOpenFeatureProvider(snapshot: ClientSnapshot): ElarionWebProvider {
+  const capabilities = new SessionCapabilities(snapshot)
+  return {
+    metadata: { name: 'elarion-session' },
+    runsOn: 'client',
+    resolveBooleanEvaluation(flagKey, defaultValue) {
+      if (
+        flagKey.startsWith('module.') ||
+        flagKey.startsWith('permission.') ||
+        flagKey.startsWith('role.')
+      ) {
+        return { value: capabilities.resolveBoolean(flagKey), reason: STATIC }
+      }
+      const flag = snapshot.flags[flagKey]
+      return flag === undefined ? { value: defaultValue, reason: DEFAULT } : { value: flag, reason: STATIC }
+    },
+    resolveStringEvaluation(flagKey, defaultValue) {
+      const variant = capabilities.getVariant(flagKey)
+      return variant === undefined
+        ? { value: defaultValue, reason: DEFAULT }
+        : { value: variant, variant, reason: STATIC }
+    },
+    resolveNumberEvaluation(_flagKey, defaultValue) {
+      return { value: defaultValue, reason: DEFAULT }
+    },
+    resolveObjectEvaluation(_flagKey, defaultValue) {
+      return { value: defaultValue, reason: DEFAULT }
+    },
+  }
+}
+`;
+}

package/package.json

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