@continuonai/rcan-ts 0.2.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # rcan-ts
 
-Official TypeScript SDK for the **RCAN v1.2** Robot Communication and Accountability Network protocol.
+Official TypeScript SDK for the **RCAN v1.5** Robot Communication and Addressing Network protocol.
 
 [![npm version](https://badge.fury.io/js/%40continuonai%2Frcan-ts.svg)](https://www.npmjs.com/package/@continuonai/rcan-ts)
 [![CI](https://github.com/continuonai/rcan-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/continuonai/rcan-ts/actions)
@@ -9,6 +9,8 @@ Official TypeScript SDK for the **RCAN v1.2** Robot Communication and Accountabi
 npm install @continuonai/rcan-ts
 ```
 
+> **v0.2.0** — RCAN v1.2 spec compliance including §17 Distributed Registry Node Protocol
+
 ### CDN / Browser (no build step)
 
 ```html
@@ -139,6 +141,89 @@ result.warnings.forEach((w) => console.warn("⚠️", w));
 | `validateURI` | Validate a Robot URI string |
 | `validateMessage` | Validate a RCAN message object |
 | `validateConfig` | L1/L2/L3 conformance check for a robot RCAN config |
+| `NodeClient` | Resolve RRNs from federated registry nodes (§17) |
+| `fetchCanonicalSchema` | Fetch the canonical JSON schema from rcan.dev |
+| `validateConfigAgainstSchema` | Validate a config object against the live JSON schema |
+| `validateNodeAgainstSchema` | Validate a node manifest against the node schema |
+
+---
+
+## Distributed Registry Nodes (§17)
+
+RCAN v1.2 §17 introduces a federated registry network. `NodeClient` resolves RRNs from any node — root or delegated authoritative.
+
+```typescript
+import { NodeClient } from '@continuonai/rcan-ts';
+
+const client = new NodeClient();
+
+// Resolve an RRN across the federation
+const result = await client.resolve('RRN-BD-000000000001');
+console.log(`Resolved by: ${result.resolved_by}`);
+console.log(`Robot: ${result.record.name}`);
+
+// Discover the authoritative node for a namespace
+const node = await client.discover('RRN-BD-000000000001');
+console.log(`Authoritative: ${node.operator} at ${node.api_base}`);
+
+// List all known registry nodes
+const nodes = await client.listNodes();
+nodes.forEach(n => console.log(`${n.operator}: ${n.namespace_prefix}`));
+
+// Verify a node manifest
+const manifest = await client.getNodeManifest('https://registry.example.com');
+const isValid = client.verifyNode(manifest);
+
+// Error handling
+import { RCANNodeNotFoundError, RCANNodeTrustError } from '@continuonai/rcan-ts';
+try {
+  const result = await client.resolve('RRN-UNKNOWN-000000000001');
+} catch (e) {
+  if (e instanceof RCANNodeNotFoundError) {
+    console.log(`Not found: ${e.rrn}`);
+  } else if (e instanceof RCANNodeTrustError) {
+    console.log(`Trust failure: ${e.reason}`);
+  }
+}
+```
+
+### RRN Format
+
+```
+Root namespace:    RRN-000000000001    (12-digit recommended, 8-digit still valid)
+Delegated:        RRN-BD-000000000001  (prefix 2-8 alphanumeric chars)
+Legacy (valid):   RRN-00000001         (8-digit, backward compatible)
+```
+
+## Schema Validation
+
+Validate configs against the canonical JSON schema published at rcan.dev:
+
+```typescript
+import { validateConfigAgainstSchema, validateNodeAgainstSchema } from '@continuonai/rcan-ts';
+
+// Validate a RCAN config against the canonical schema from rcan.dev
+const result = await validateConfigAgainstSchema(myConfig);
+if (!result.valid) {
+  console.error('Config invalid:', result.errors);
+} else if (result.skipped) {
+  console.warn('Schema validation skipped (rcan.dev unreachable)');
+}
+
+// Validate a node manifest
+const nodeResult = await validateNodeAgainstSchema(manifest);
+```
+
+### CDN / Browser Usage
+
+```html
+<script src="https://unpkg.com/@continuonai/rcan-ts/dist/rcan.iife.js"></script>
+<script>
+  const { validateConfig, NodeClient } = window.RCAN;
+  const client = new NodeClient();
+  client.resolve('RRN-000000000001').then(r => console.log(r));
+</script>
+```
 
 ---
 
@@ -155,10 +240,12 @@ The Python and TypeScript SDKs share an identical API surface — `RobotURI`, `R
 ## Links
 
 - ⚡ [Quickstart](https://rcan.dev/quickstart) — from zero to first message in 5 min
-- 📖 [RCAN Spec](https://rcan.dev/spec) — full protocol specification
+- 📖 [RCAN Spec v1.5](https://rcan.dev/spec) — full protocol specification
 - 🌐 [rcan.dev](https://rcan.dev) — robot registry and documentation
 - 🐍 [rcan-py](https://github.com/continuonai/rcan-py) — Python SDK
-- 🤖 [OpenCastor](https://github.com/craigm26/OpenCastor) — robot runtime with RCAN built in
+- 🤖 [OpenCastor](https://github.com/craigm26/OpenCastor) — Python robot runtime (RCAN reference implementation)
+- 🖥️ [OpenCastor Fleet UI](https://app.opencastor.com) — Flutter web app for remote fleet management (uses rcan-ts for message construction)
+- 🏛️ [Robot Registry Foundation](https://robotregistryfoundation.org) — global robot identity registry
 
 ---
 

package/bin/rcan-validate.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { NodeClient, validateConfig, VERSION, SPEC_VERSION } from '../dist/index.js';
+import { readFileSync } from 'fs';
+import { parseArgs } from 'util';
+
+const { values, positionals } = parseArgs({
+  args: process.argv.slice(2),
+  options: {
+    version: { type: 'boolean', short: 'v' },
+    file: { type: 'string', short: 'f' },
+  },
+  allowPositionals: true,
+});
+
+if (values.version) {
+  console.log(`rcan-validate (ts) ${VERSION} (RCAN spec ${SPEC_VERSION})`);
+  process.exit(0);
+}
+
+const [subcommand, target] = positionals;
+
+if (subcommand === 'node') {
+  if (!target) {
+    console.error('Usage: rcan-validate node <url>');
+    process.exit(1);
+  }
+
+  const client = new NodeClient();
+  console.log(`Validating node manifest: ${target}`);
+
+  try {
+    const manifest = await client.getNodeManifest(target);
+    const valid = client.verifyNode(manifest);
+
+    const checks = [
+      ['node_type', manifest.node_type, ['root','authoritative','resolver','cache'].includes(manifest.node_type)],
+      ['operator', manifest.operator, !!manifest.operator],
+      ['namespace_prefix', manifest.namespace_prefix, !!manifest.namespace_prefix],
+      ['public_key', manifest.public_key?.substring(0, 20) + '...', manifest.public_key?.startsWith('ed25519:')],
+      ['api_base', manifest.api_base, manifest.api_base?.startsWith('https://')],
+    ];
+
+    for (const [name, value, pass] of checks) {
+      console.log(`  ${pass ? '✓' : '✗'} ${name}: ${value}`);
+    }
+
+    const passed = checks.filter(([,,p]) => p).length;
+    console.log(`\n${valid ? 'PASS' : 'FAIL'} (${passed}/${checks.length} checks)`);
+    process.exit(valid ? 0 : 1);
+  } catch (e) {
+    console.error(`❌ Error: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+if (subcommand === 'config') {
+  const filePath = target || values.file;
+  if (!filePath) {
+    console.error('Usage: rcan-validate config <file>');
+    process.exit(1);
+  }
+
+  try {
+    const raw = readFileSync(filePath, 'utf-8');
+    const config = JSON.parse(raw);
+    const result = validateConfig(config);
+    if (result.ok) {
+      console.log('✓ Config valid');
+      if (result.warnings?.length) {
+        result.warnings.forEach(w => console.warn(`  ⚠️  ${w}`));
+      }
+      process.exit(0);
+    } else {
+      console.error('✗ Config invalid:');
+      result.issues?.forEach(i => console.error(`  ❌ ${i}`));
+      process.exit(1);
+    }
+  } catch (e) {
+    console.error(`❌ Error: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+console.error(`Unknown subcommand: ${subcommand}`);
+console.error('Usage: rcan-validate node <url> | rcan-validate config <file> | rcan-validate --version');
+process.exit(1);