Skip to main content
Version: next

Node Server Sync

@monoverse/voicebot-node is an npm package that pushes your Node.js catalog and content to VoiceBot so the assistant can answer about your real products, categories and pages.

It is a producer client for the VoiceBot canonical signed-ingest contract: it pairs once, sends a full snapshot to establish a baseline, then streams small incremental deltas as your data changes. Everything runs server-to-server over an HMAC-signed HTTP protocol — no browser, no end-user involvement, no LLM SDK on your side. Voice and retrieval stay on the VoiceBot backend. It is the Node/TypeScript twin of the Laravel and WordPress sync producers.

Data channel — your Node app to VoiceBot ingest
┌──────────────────┐   gzip-NDJSON snapshot       ┌──────────────┐
│  Your Node app   │   + signed /events deltas     │  VoiceBot    │
│  + this package  │ ───────────────────────────▶  │  ingest      │
│  (entity         │   HMAC-SHA256, https only      │  (catalog,   │
│   builders)      │                                │   RAG)       │
└──────────────────┘                                └──────────────┘
You need a catalog before the widget says anything

The widget answers questions using this data. Until a backend sync runs, there is nothing for it to talk about. Get the catalog in first.

The lifecycle at a glance​

Four steps from an empty connection to a self-maintaining feed:

  1. Pair — exchange a one-time VB-XXXX-XXXX code for your tenant id + an encrypted shared secret.
  2. Map — build canonical entities from your data with the typed builders (product, category, …).
  3. Snapshot — client.snapshot(...) streams a complete baseline of every kind you emit.
  4. Schedule — deltas every few minutes via client.sendEvents(...), plus a periodic full to reconcile deletes.

Two channels, two keys​

VoiceBot reads your store over two independent channels. They use different credentials and flow in opposite directions — don't confuse them.

Data channel (this package)Widget channel (browser)
DirectionYour server → VoiceBot (push)End-user browser ↔ VoiceBot (live)
CredentialHMAC shared secret (per-tenant, secret)Publishable key pk_… (public, embeddable)
Obtained viaclient.pair('VB-XXXX-XXXX')Copied from the cabinet, dropped in a <script>
CarriesCatalog + content snapshots and deltasVoice/text conversation traffic
TrustSecret, encrypted at rest, never loggedPublic identifier, safe to ship in markup

The shared secret minted by pairing is stored encrypted at rest (AES-256-GCM, keyed by your encryptionKey) and is never printed, logged, or returned in any output.

When to use it​

Use this package when:

  • Your storefront runs on Node.js (Express, NestJS, Fastify, a headless backend, a custom shop).
  • You want the assistant to answer about live products, prices, stock, categories and pages.
  • You can run a script on a schedule (cron, a worker, a platform scheduler).

You do not need this package if your store runs on WordPress/WooCommerce (use the WordPress sync plugin) or Laravel (use the Laravel package), or if you'd rather not run a producer at all.

Prefer no code?

If you can't run a producer, VoiceBot can ingest your store with no code on your side — a managed crawler reads your public pages, and supported platforms can be pulled read-only. See No-code & read-only alternatives.

What it sends​

The package maps your data to VoiceBot's canonical entity schema via typed builder functions and emits the kinds you have — products, categories, pages and more. Money is integer minor units, categories/tags are slug lists, and page.contentText is plain text; the builders enforce these. See Mapping for how to build entities and Syncing for how to push them.

Requirements​

  • Node.js 18+ (uses built-in node:crypto and global fetch; zero runtime dependencies).
  • A full-entropy 32-byte encryptionKey to encrypt the stored shared secret (openssl rand -hex 32).
  • A reachable VoiceBot ingest endpoint over https (localhost is allowed for local dev).

The five-minute path​

  1. Install & pair — npm install, construct the client, exchange a pair code.
  2. Map your data to canonical entities.
  3. Push a baseline: client.snapshot(catalog()).
  4. Sync deltas + a periodic full.
  5. Operate it — status, unpair, retries, scheduling.

Next steps​