@nkmc/gateway 0.1.0

package/src/registry/rpc-compiler.ts

@@ -0,0 +1,142 @@
+// packages/gateway/src/registry/rpc-compiler.ts
+
+import type { RpcManifestDef } from "../onboard/types.js";
+import type { ServiceRecord, EndpointRecord, RpcSourceMeta } from "./types.js";
+
+export interface RpcCompileResult {
+  record: ServiceRecord;
+  skillMd: string;
+}
+
+/**
+ * Compile an RpcManifestDef into a ServiceRecord suitable for the registry.
+ *
+ * Each RPC method becomes an EndpointRecord with method="RPC" and path=rpcMethod.
+ * Resources are inferred from the method prefix (e.g. "eth_getBalance" → "balances")
+ * or from explicit `resource` annotations on each method.
+ */
+export function compileRpcDef(
+  domain: string,
+  rpcDef: RpcManifestDef,
+  options?: { version?: string; isFirstParty?: boolean },
+): RpcCompileResult {
+  const convention = rpcDef.convention ?? "raw";
+
+  // Build endpoints
+  const endpoints: EndpointRecord[] = rpcDef.methods.map((m) => ({
+    method: "RPC",
+    path: m.rpcMethod,
+    description: m.description,
+  }));
+
+  // Group methods by resource for SourceConfig
+  const resourceMap = new Map<string, { name: string; idField?: string; methods: Record<string, string> }>();
+
+  for (const m of rpcDef.methods) {
+    const resName = m.resource ?? inferResource(m.rpcMethod);
+    if (!resourceMap.has(resName)) {
+      resourceMap.set(resName, { name: resName, methods: {} });
+    }
+    const entry = resourceMap.get(resName)!;
+    if (m.fsOp) {
+      entry.methods[m.fsOp] = m.rpcMethod;
+    }
+  }
+
+  const rpcMeta: RpcSourceMeta = {
+    rpcUrl: rpcDef.url,
+    convention,
+    resources: Array.from(resourceMap.values()),
+  };
+
+  // Generate skill.md
+  const skillMd = generateSkillMd(domain, rpcDef, endpoints);
+
+  const now = Date.now();
+  const record: ServiceRecord = {
+    domain,
+    name: domain,
+    description: `JSON-RPC service at ${domain}`,
+    version: options?.version ?? "1.0",
+    roles: ["agent"],
+    skillMd,
+    endpoints,
+    isFirstParty: options?.isFirstParty ?? false,
+    createdAt: now,
+    updatedAt: now,
+    status: "active",
+    isDefault: true,
+    source: {
+      type: "jsonrpc",
+      url: rpcDef.url,
+      rpc: rpcMeta,
+    },
+  };
+
+  return { record, skillMd };
+}
+
+/**
+ * Infer a resource name from an RPC method name.
+ * e.g. "eth_getBlockByNumber" → "blocks"
+ *      "eth_getBalance" → "balances"
+ *      "net_version" → "net"
+ */
+function inferResource(rpcMethod: string): string {
+  // Split by underscore: "eth_getBlockByNumber" → ["eth", "getBlockByNumber"]
+  const underscoreIdx = rpcMethod.indexOf("_");
+  if (underscoreIdx < 0) return rpcMethod;
+
+  const action = rpcMethod.slice(underscoreIdx + 1);
+
+  // Strip common verb prefixes
+  const verbPrefixes = ["get", "send", "subscribe", "unsubscribe", "new", "call"];
+  let noun = action;
+  for (const prefix of verbPrefixes) {
+    if (action.startsWith(prefix) && action.length > prefix.length) {
+      noun = action.slice(prefix.length);
+      break;
+    }
+  }
+
+  // Split camelCase on first capital to get the noun: "BlockByNumber" → "Block"
+  const camelMatch = noun.match(/^([A-Z][a-z]+)/);
+  if (camelMatch) {
+    noun = camelMatch[1];
+  }
+
+  // Pluralize naive: add 's' if not already ending in 's'
+  const lower = noun.toLowerCase();
+  return lower.endsWith("s") ? lower : lower + "s";
+}
+
+function generateSkillMd(
+  domain: string,
+  rpcDef: RpcManifestDef,
+  endpoints: EndpointRecord[],
+): string {
+  const lines: string[] = [
+    "---",
+    `name: "${domain}"`,
+    `version: "1.0"`,
+    `roles: [agent]`,
+    "---",
+    "",
+    `# ${domain}`,
+    "",
+    `JSON-RPC service at ${rpcDef.url}`,
+    "",
+    `Convention: ${rpcDef.convention ?? "raw"}`,
+    "",
+    "## RPC Methods",
+    "",
+    "| method | description |",
+    "|--------|-------------|",
+  ];
+
+  for (const ep of endpoints) {
+    lines.push(`| ${ep.path} | ${ep.description} |`);
+  }
+
+  return lines.join("\n");
+}

package/src/registry/skill-parser.ts

@@ -0,0 +1,119 @@
+// packages/gateway/src/registry/skill-parser.ts
+import { parse as parseYaml } from "yaml";
+import type { ServiceRecord, EndpointRecord, EndpointPricing } from "./types.js";
+
+export interface ParseOptions {
+  isFirstParty?: boolean;
+}
+
+export function parseSkillMd(
+  domain: string,
+  raw: string,
+  options?: ParseOptions,
+): ServiceRecord {
+  const { frontmatter, body } = extractFrontmatter(raw);
+  const parsed = (parseYaml(frontmatter) as {
+    name?: string;
+    version?: string;
+    roles?: string[];
+  }) ?? {};
+
+  const description = extractDescription(body);
+  const endpoints = extractEndpoints(body);
+  const now = Date.now();
+
+  return {
+    domain,
+    name: parsed.name ?? domain,
+    description,
+    version: parsed.version ?? "0.0",
+    roles: parsed.roles ?? ["agent"],
+    skillMd: raw,
+    endpoints,
+    isFirstParty: options?.isFirstParty ?? false,
+    createdAt: now,
+    updatedAt: now,
+    status: "active",
+    isDefault: true,
+  };
+}
+
+export function parsePricingAnnotation(text: string): EndpointPricing | undefined {
+  // Matches patterns like "0.05 USDC / call", "0.1 USDC / byte"
+  const match = text.match(
+    /(\d+(?:\.\d+)?)\s+(\w+)\s*\/\s*(call|byte|minute|次)/i,
+  );
+  if (!match) return undefined;
+  return {
+    cost: parseFloat(match[1]),
+    currency: match[2].toUpperCase(),
+    per: match[3] === "次" ? "call" : (match[3].toLowerCase() as "call" | "byte" | "minute"),
+  };
+}
+
+function extractFrontmatter(raw: string): { frontmatter: string; body: string } {
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) return { frontmatter: "", body: raw };
+  return { frontmatter: match[1], body: match[2] };
+}
+
+function extractDescription(body: string): string {
+  const lines = body.split("\n");
+  let foundTitle = false;
+  const descLines: string[] = [];
+
+  for (const line of lines) {
+    if (!foundTitle) {
+      if (line.startsWith("# ")) foundTitle = true;
+      continue;
+    }
+    if (line.startsWith("## ")) break;
+    const trimmed = line.trim();
+    if (trimmed === "" && descLines.length > 0) break;
+    if (trimmed !== "") descLines.push(trimmed);
+  }
+
+  return descLines.join(" ");
+}
+
+function extractEndpoints(body: string): EndpointRecord[] {
+  const endpoints: EndpointRecord[] = [];
+  const lines = body.split("\n");
+
+  let inApiSection = false;
+  let currentHeading: string | null = null;
+
+  for (const line of lines) {
+    if (line.startsWith("## API")) {
+      inApiSection = true;
+      continue;
+    }
+    if (inApiSection && line.startsWith("## ") && !line.startsWith("## API")) {
+      break;
+    }
+    if (!inApiSection) continue;
+
+    if (line.startsWith("### ")) {
+      currentHeading = line.slice(4).trim();
+      continue;
+    }
+
+    const endpointMatch = line.match(/^`(GET|POST|PUT|PATCH|DELETE)\s+(\S+)`/);
+    if (endpointMatch && currentHeading) {
+      const afterBacktick = line.slice(line.indexOf("`", 1) + 1).trim();
+      const pricing = afterBacktick.startsWith("—")
+        ? parsePricingAnnotation(afterBacktick.slice(1).trim())
+        : undefined;
+
+      endpoints.push({
+        method: endpointMatch[1],
+        path: endpointMatch[2],
+        description: currentHeading,
+        ...(pricing ? { pricing } : {}),
+      });
+      currentHeading = null;
+    }
+  }
+
+  return endpoints;
+}

package/src/registry/skill-to-config.ts

@@ -0,0 +1,239 @@
+// packages/gateway/src/registry/skill-to-config.ts
+import type { HttpBackendConfig, HttpResource, HttpEndpoint, RpcResource, RpcMethod, RpcCallContext } from "@nkmc/agent-fs";
+import type { ServiceRecord, RpcSourceMeta } from "./types.js";
+
+export function skillToHttpConfig(record: ServiceRecord): HttpBackendConfig {
+  let baseUrl = `https://${record.domain}`;
+  if (record.source?.basePath) {
+    baseUrl += record.source.basePath;
+  }
+  const resources = extractResources(record.skillMd);
+  const endpoints = extractHttpEndpoints(record.skillMd);
+
+  return {
+    baseUrl,
+    resources,
+    endpoints,
+  };
+}
+
+function extractResources(skillMd: string): HttpResource[] {
+  const resources: HttpResource[] = [];
+  const lines = skillMd.split("\n");
+
+  let inSchema = false;
+  let current: {
+    name: string;
+    fields: { name: string; type: string; description: string }[];
+  } | null = null;
+
+  for (const line of lines) {
+    if (line.startsWith("## Schema")) {
+      inSchema = true;
+      continue;
+    }
+    if (inSchema && line.startsWith("## ") && !line.startsWith("## Schema")) {
+      break;
+    }
+    if (!inSchema) continue;
+
+    const tableMatch = line.match(/^### (\w+)\s/);
+    if (tableMatch) {
+      if (current) resources.push(toHttpResource(current));
+      current = { name: tableMatch[1], fields: [] };
+      continue;
+    }
+
+    if (current && line.startsWith("|") && !line.startsWith("|--") && !line.startsWith("| field")) {
+      const cells = line.split("|").map((c) => c.trim()).filter(Boolean);
+      if (cells.length >= 3) {
+        current.fields.push({
+          name: cells[0],
+          type: cells[1],
+          description: cells[2],
+        });
+      }
+    }
+  }
+
+  if (current) resources.push(toHttpResource(current));
+  return resources;
+}
+
+function toHttpResource(parsed: {
+  name: string;
+  fields: { name: string; type: string; description: string }[];
+}): HttpResource {
+  return {
+    name: parsed.name,
+    apiPath: `/${parsed.name}`,
+    fields: parsed.fields,
+  };
+}
+
+function extractHttpEndpoints(skillMd: string): HttpEndpoint[] {
+  const endpoints: HttpEndpoint[] = [];
+  const lines = skillMd.split("\n");
+
+  let inApi = false;
+  let currentHeading: string | null = null;
+
+  for (const line of lines) {
+    if (line.startsWith("## API")) {
+      inApi = true;
+      continue;
+    }
+    if (inApi && line.startsWith("## ") && !line.startsWith("## API")) {
+      break;
+    }
+    if (!inApi) continue;
+
+    if (line.startsWith("### ")) {
+      currentHeading = line.slice(4).trim();
+      continue;
+    }
+
+    const match = line.match(/^`(GET|POST|PUT|PATCH|DELETE)\s+(\S+)`/);
+    if (match && currentHeading) {
+      const slug = currentHeading.toLowerCase().replace(/\s+/g, "-");
+      endpoints.push({
+        name: slug,
+        method: match[1] as HttpEndpoint["method"],
+        apiPath: match[2],
+        description: currentHeading,
+      });
+      currentHeading = null;
+    }
+  }
+
+  return endpoints;
+}
+
+// --- RPC config factory ---
+
+export interface RpcConfigResult {
+  resources: RpcResource[];
+}
+
+/**
+ * Rebuild RpcResource[] from the serializable RpcSourceMeta stored in the DB.
+ * The `params` callbacks are recreated based on the convention mode.
+ */
+export function skillToRpcConfig(meta: RpcSourceMeta): RpcConfigResult {
+  const resources: RpcResource[] = meta.resources.map((r) => {
+    const methods: RpcResource["methods"] = {};
+    const builder = getParamsBuilder(meta.convention);
+
+    for (const [fsOp, rpcMethod] of Object.entries(r.methods)) {
+      const key = fsOp as keyof RpcResource["methods"];
+      methods[key] = {
+        method: rpcMethod,
+        params: builder(key),
+      };
+    }
+
+    const resource: RpcResource = {
+      name: r.name,
+      ...(r.idField ? { idField: r.idField } : {}),
+      methods,
+    };
+
+    // Add transforms for evm convention
+    if (meta.convention === "evm") {
+      resource.transform = buildEvmTransforms(r.name);
+    }
+
+    return resource;
+  });
+
+  return { resources };
+}
+
+type ParamsBuilder = (fsOp: keyof RpcResource["methods"]) => RpcMethod["params"];
+
+function getParamsBuilder(convention: RpcSourceMeta["convention"]): ParamsBuilder {
+  switch (convention) {
+    case "crud":
+      return crudParamsBuilder;
+    case "evm":
+      return evmParamsBuilder;
+    case "raw":
+    default:
+      return rawParamsBuilder;
+  }
+}
+
+/** Raw convention: pass-through — no params transformation */
+function rawParamsBuilder(_fsOp: keyof RpcResource["methods"]): RpcMethod["params"] {
+  return (ctx: RpcCallContext) => {
+    if (ctx.data !== undefined) return [ctx.data];
+    if (ctx.id !== undefined) return [ctx.id];
+    return [];
+  };
+}
+
+/** CRUD convention: standard CRUD parameter mapping */
+function crudParamsBuilder(fsOp: keyof RpcResource["methods"]): RpcMethod["params"] {
+  switch (fsOp) {
+    case "list":
+      return () => [];
+    case "read":
+      return (ctx: RpcCallContext) => [ctx.id!];
+    case "write":
+      return (ctx: RpcCallContext) => [ctx.id!, ctx.data];
+    case "create":
+      return (ctx: RpcCallContext) => [ctx.data];
+    case "remove":
+      return (ctx: RpcCallContext) => [ctx.id!];
+    case "search":
+      return (ctx: RpcCallContext) => [ctx.pattern!];
+    default:
+      return () => [];
+  }
+}
+
+/** EVM convention: hex encoding and EVM-specific parameter patterns */
+function evmParamsBuilder(fsOp: keyof RpcResource["methods"]): RpcMethod["params"] {
+  switch (fsOp) {
+    case "list":
+      return () => [];
+    case "read":
+      return (ctx: RpcCallContext) => {
+        const id = ctx.id!;
+        // If it looks like a number, convert to hex
+        const hexId = /^\d+$/.test(id) ? "0x" + Number(id).toString(16) : id;
+        // Second param: "latest" for address-based methods (balance, nonce, code),
+        // false for block/tx methods. "latest" is safe for both — providers that
+        // expect a boolean will coerce the truthy string, and address-based
+        // methods use it as a block tag.
+        return [hexId, "latest"];
+      };
+    default:
+      return rawParamsBuilder(fsOp);
+  }
+}
+
+function buildEvmTransforms(resourceName: string): RpcResource["transform"] {
+  const transform: RpcResource["transform"] = {};
+
+  if (resourceName === "blocks") {
+    // eth_blockNumber returns a hex string like "0x1234abc"
+    // Convert to a list of recent block numbers as .json files
+    transform.list = (data: unknown) => {
+      const hex = String(data);
+      const latest = parseInt(hex, 16);
+      if (isNaN(latest)) return [];
+      return Array.from({ length: 10 }, (_, i) => `${latest - i}.json`);
+    };
+  }
+
+  if (resourceName === "balances") {
+    transform.read = (data: unknown) => {
+      // Convert wei hex to a readable object
+      const hex = String(data);
+      return { wei: hex, raw: hex };
+    };
+  }
+
+  return Object.keys(transform).length > 0 ? transform : undefined;
+}

package/src/registry/source-refresher.ts

@@ -0,0 +1,83 @@
+import type { RegistryStore, ServiceRecord } from "./types.js";
+import { fetchAndCompile } from "./openapi-compiler.js";
+
+export class SourceRefresher {
+  constructor(
+    private store: RegistryStore,
+    private fetchFn: typeof globalThis.fetch = globalThis.fetch.bind(globalThis),
+  ) {}
+
+  async shouldRefresh(record: ServiceRecord): Promise<boolean> {
+    if (!record.source?.refreshInterval) return false;
+    const lastRefresh = record.source.lastRefresh ?? record.updatedAt;
+    return Date.now() - lastRefresh > record.source.refreshInterval * 1000;
+  }
+
+  async refresh(record: ServiceRecord): Promise<ServiceRecord | null> {
+    if (!record.source) return null;
+
+    if (record.source.type === "openapi" && record.source.url) {
+      const result = await fetchAndCompile(
+        record.source.url,
+        { domain: record.domain, version: record.version, isFirstParty: record.isFirstParty },
+        this.fetchFn,
+      );
+      const updated: ServiceRecord = {
+        ...result.record,
+        createdAt: record.createdAt,
+        isDefault: record.isDefault,
+        source: { ...record.source, lastRefresh: Date.now() },
+      };
+      await this.store.put(record.domain, updated);
+      return updated;
+    }
+
+    if (record.source.type === "wellknown" && record.source.url) {
+      const resp = await this.fetchFn(record.source.url);
+      if (!resp.ok) return null;
+      const skillMd = await resp.text();
+      // Re-parse using dynamic import to avoid circular dep
+      const { parseSkillMd } = await import("./skill-parser.js");
+      const updated = parseSkillMd(record.domain, skillMd, { isFirstParty: record.isFirstParty });
+      updated.createdAt = record.createdAt;
+      updated.isDefault = record.isDefault;
+      updated.version = record.version;
+      updated.source = { ...record.source, lastRefresh: Date.now() };
+      await this.store.put(record.domain, updated);
+      return updated;
+    }
+
+    // JSON-RPC: method lists are static, just update timestamp
+    if (record.source.type === "jsonrpc") {
+      const updated: ServiceRecord = {
+        ...record,
+        source: { ...record.source, lastRefresh: Date.now() },
+      };
+      await this.store.put(record.domain, updated);
+      return updated;
+    }
+
+    return null;
+  }
+
+  async refreshAll(): Promise<{ refreshed: string[]; errors: string[] }> {
+    const services = await this.store.list();
+    const refreshed: string[] = [];
+    const errors: string[] = [];
+
+    for (const summary of services) {
+      const record = await this.store.get(summary.domain);
+      if (!record) continue;
+      if (!(await this.shouldRefresh(record))) continue;
+
+      try {
+        const updated = await this.refresh(record);
+        if (updated) refreshed.push(record.domain);
+      } catch {
+        errors.push(record.domain);
+      }
+    }
+
+    return { refreshed, errors };
+  }
+}

package/src/registry/types.ts

@@ -0,0 +1,129 @@
+// packages/gateway/src/registry/types.ts
+
+export type ServiceStatus = "active" | "deprecated" | "sunset";
+
+export interface EndpointPricing {
+  cost: number;
+  currency: string;
+  per: "call" | "byte" | "minute";
+}
+
+export interface EndpointAnnotations {
+  rateLimit?: number;
+  cacheTtl?: number;
+  tags?: string[];
+}
+
+export interface EndpointParam {
+  name: string;
+  in: "path" | "query" | "header";
+  required: boolean;
+  type: string;
+  description?: string;
+}
+
+export interface SchemaProperty {
+  name: string;
+  type: string;
+  required: boolean;
+  description?: string;
+}
+
+export interface EndpointRecord {
+  method: string;
+  path: string;
+  description: string;
+  price?: string;
+  pricing?: EndpointPricing;
+  annotations?: EndpointAnnotations;
+  parameters?: EndpointParam[];
+  requestBody?: {
+    contentType: string;
+    required: boolean;
+    properties: SchemaProperty[];
+  };
+  responses?: {
+    status: number;
+    description: string;
+    properties?: SchemaProperty[];
+  }[];
+}
+
+/** @deprecated Use EndpointRecord instead */
+export type EndpointSummary = EndpointRecord;
+
+export interface RpcSourceMeta {
+  rpcUrl: string;
+  convention: "crud" | "evm" | "raw";
+  resources: Array<{
+    name: string;
+    idField?: string;
+    methods: Record<string, string>; // fsOp → rpcMethod
+  }>;
+}
+
+export interface SourceConfig {
+  type: "skillmd" | "openapi" | "wellknown" | "jsonrpc";
+  url?: string;
+  basePath?: string;
+  refreshInterval?: number;
+  lastRefresh?: number;
+  rpc?: RpcSourceMeta;
+}
+
+export interface ServiceRecord {
+  domain: string;
+  name: string;
+  description: string;
+  version: string;
+  roles: string[];
+  skillMd: string;
+  endpoints: EndpointRecord[];
+  isFirstParty: boolean;
+  createdAt: number;
+  updatedAt: number;
+  status: ServiceStatus;
+  isDefault: boolean;
+  sunsetDate?: number;
+  source?: SourceConfig;
+  authMode?: "nkmc-jwt";
+}
+
+export interface ServiceSummary {
+  domain: string;
+  name: string;
+  description: string;
+  isFirstParty: boolean;
+}
+
+export interface SearchResult {
+  domain: string;
+  name: string;
+  description: string;
+  isFirstParty: boolean;
+  matchedEndpoints: Pick<EndpointRecord, "method" | "path" | "description">[];
+}
+
+export interface VersionSummary {
+  version: string;
+  status: ServiceStatus;
+  isDefault: boolean;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface RegistryStats {
+  serviceCount: number;
+  endpointCount: number;
+}
+
+export interface RegistryStore {
+  get(domain: string): Promise<ServiceRecord | null>;
+  getVersion(domain: string, version: string): Promise<ServiceRecord | null>;
+  listVersions(domain: string): Promise<VersionSummary[]>;
+  put(domain: string, record: ServiceRecord): Promise<void>;
+  delete(domain: string): Promise<void>;
+  list(): Promise<ServiceSummary[]>;
+  search(query: string): Promise<SearchResult[]>;
+  stats?(): Promise<RegistryStats>;
+}