ncc-06-js 0.2.2 → 0.2.3

package/DOCS.md

@@ -57,6 +57,12 @@ Utilities for locator payload construction and evaluation.
 ### `buildSidecarConfig(options)`
 - Mirrors the example sidecar setup and derives `ncc02ExpectedKey`, `publishRelays`, and `torControl` from operator intent so you do not need to duplicate those scripts.
 
+### `getRelayMode(config)`
+- Returns the normalized `"public"` or `"private"` mode that drives whether the sidecar publishes NCC-05 locators.
+
+### `setRelayMode(config, mode)`
+- Normalizes and writes `"public"` or `"private"` back into the config object so you can persistively toggle the relay’s exposure level.
+
 ### `buildClientConfig(options)`
 - Rehydrates the minimal client config that the example resolver expects; dedupes publication relays, enforces `serviceIdentityUri`, and carries the `expectedK` for NCC-02 pinning.
 

package/README.md

@@ -13,6 +13,7 @@ Reusable helpers extracted from the NCC-06 example relay, sidecar, and client im
 - **Lightweight protocol helpers** (`parseNostrMessage`, `serializeNostrMessage`, `createReqMessage`) for downstream code that wants to reuse the same framing logic as the example client.
 - **Sidecar config helpers** (`buildSidecarConfig`, `buildClientConfig`) so you can reuse the same config generation logic the example sidecar/client rely on without copying the scripts.
 - **TypeScript definitions** (`index.d.ts`) that describe every exported helper, making it easier to import from TypeScript consumers.
+- **Relay mode helpers** (`getRelayMode`, `setRelayMode`) so you can portrait whether your relay is *public* (publishes NCC-05 locators) or *private* (only maintains an NCC-02 record without advertising endpoints).
 
 ## Usage
 

package/index.d.ts

@@ -214,6 +214,7 @@ declare module 'ncc-06-js' {
     externalEndpoints?: Record<string, unknown>;
     k?: KConfig;
     baseDir?: string;
+    relayMode?: 'public' | 'private';
     ncc02ExpectedKeySource?: string;
   }
   export interface SidecarConfig {
@@ -232,8 +233,11 @@ declare module 'ncc-06-js' {
     externalEndpoints: Record<string, unknown>;
     torControl: Record<string, unknown>;
     k: KConfig;
+    relayMode: 'public' | 'private';
   }
   export function buildSidecarConfig(options: SidecarConfigOptions): SidecarConfig;
+  export function getRelayMode(config?: { relayMode?: string }): 'public' | 'private';
+  export function setRelayMode(config?: Record<string, unknown>, mode: 'public' | 'private'): Record<string, unknown>;
 
   export interface ClientConfigOptions {
     relayUrl: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ncc-06-js",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Reusable NCC-06 discovery helpers extracted from the example relay, sidecar, and client.",
   "type": "module",
   "main": "src/index.js",

package/src/sidecar-config.js

@@ -11,6 +11,20 @@ const DEFAULT_TOR_CONTROL = {
   timeout: 5000
 };
 
+const RELAY_MODE_PUBLIC = 'public';
+const RELAY_MODE_PRIVATE = 'private';
+
+function normalizeRelayMode(mode) {
+  if (!mode) {
+    return RELAY_MODE_PUBLIC;
+  }
+  const value = String(mode).toLowerCase();
+  if (value !== RELAY_MODE_PUBLIC && value !== RELAY_MODE_PRIVATE) {
+    throw new Error(`relayMode must be "${RELAY_MODE_PUBLIC}" or "${RELAY_MODE_PRIVATE}"`);
+  }
+  return value;
+}
+
 function uniqueList(items) {
   const seen = new Set();
   return items.filter(item => {
@@ -24,6 +38,15 @@ function uniqueList(items) {
   });
 }
 
+export function getRelayMode(config = {}) {
+  return normalizeRelayMode(config.relayMode);
+}
+
+export function setRelayMode(config = {}, mode) {
+  const normalized = normalizeRelayMode(mode);
+  return { ...config, relayMode: normalized };
+}
+
 /**
  * Build a deployable sidecar config object that mirrors the example's defaults.
  */
@@ -42,6 +65,7 @@ export function buildSidecarConfig({
   externalEndpoints = {},
   k = {},
   baseDir = process.cwd(),
+  relayMode,
   ncc02ExpectedKeySource
 } = {}) {
   if (!serviceSk || !servicePk || !serviceNpub) {
@@ -58,6 +82,7 @@ export function buildSidecarConfig({
     ...(publishRelays ?? normalizedPublicationRelays)
   ]);
   const keySource = ncc02ExpectedKeySource ?? k.mode ?? 'auto';
+  const normalizedRelayMode = normalizeRelayMode(relayMode);
 
   return {
     serviceSk,
@@ -74,7 +99,8 @@ export function buildSidecarConfig({
     ncc02ExpectedKeySource: keySource,
     externalEndpoints,
     torControl,
-    k
+    k,
+    relayMode: normalizedRelayMode
   };
 }
 

package/test/sidecar-config.test.js

@@ -1,6 +1,11 @@
 import { test } from 'node:test';
 import { strict as assert } from 'assert';
-import { buildSidecarConfig, buildClientConfig } from '../src/sidecar-config.js';
+import {
+  buildSidecarConfig,
+  buildClientConfig,
+  getRelayMode,
+  setRelayMode
+} from '../src/sidecar-config.js';
 
 test('buildSidecarConfig constructs expected fields based on inputs', () => {
   const cfg = buildSidecarConfig({
@@ -34,3 +39,11 @@ test('buildClientConfig enforces identity URI and relays', () => {
   assert.equal(client.publicationRelays.length, 2);
   assert.equal(client.ncc02ExpectedKey, 'TESTKEY:abc');
 });
+
+test('getRelayMode default and setter', () => {
+  assert.equal(getRelayMode({}), 'public');
+  assert.equal(getRelayMode({ relayMode: 'private' }), 'private');
+  const config = setRelayMode({}, 'private');
+  assert.equal(config.relayMode, 'private');
+  assert.throws(() => setRelayMode({}, 'unknown'));
+});