onipin-js

SDK oficial de OniPin — protocolo onipin/0.2, discovery, handshake, chat, catálogo, reservas y pedidos.

npm: https://www.npmjs.com/package/onipin-js
Intent Spec: https://onnivers.store/docs/intent-spec/
Docs: https://onnivers.store/docs#sdk

Instalación

npm install onipin-js

Inicio rápido (OniPin 0.2)

import { OniPinClient } from "onipin-js";

const oni = new OniPinClient({
  baseUrl: "https://onnivers.store",
  pin: "onp_tu_pin",
  callerType: "ai-agent",
  agent: { name: "MiBot", version: "1.0" },
});

// 1. Descubrir desde URL (opcional si ya tienes el pin)
const found = await oni.discoverFromUrl("https://sitio-del-negocio.com");

// 2. Handshake — anuncia agente e intención
await oni.handshake("appointment.create");

// 3. Chatear con intent
const chat = await oni.chat("Quiero cita mañana 10:00", {
  intent: "appointment.create",
});
console.log(chat.reply?.text);

API

| Método | Descripción | |--------|-------------| | ping() | Discovery del negocio (GET /v1/ping/:pin) | | discoverFromUrl(url) | Resuelve pin desde sitio web (GET /v1/discover?url=) | | handshake(intent?, agent?) | Handshake OniPin 0.2 (POST /v1/handshake/:pin) | | catalog() | Productos/servicios activos | | chat(message, opts?) | Envía mensaje; opts: { conversationId, intent, agent } | | messages({ conversationId, after, afterId, limit }) | Lee el hilo (poll sin Realtime) | | pollMessages({ intervalMs, timeoutMs, untilBotOrOwner }) | Poll oficial hasta bot/owner o timeout | | createBooking({ service, scheduledLabel, clientName, ... }) | Reserva real en BD | | createOrder({ productName, quantity, clientName, ... }) | Pedido real en BD | | reset() | Nueva conversación local |

Flujo IA↔IA (recomendado)

await oni.handshake("business.chat");
const first = await oni.chat("Hola, soy un agente", { intent: "business.chat" });
// Reutilizar siempre first.conversationId (el cliente lo guarda solo)

if (!first.reply) {
  // Dueño en modo humano — poll hasta respuesta
  const page = await oni.pollMessages({ timeoutMs: 120_000 });
  console.log(page.messages.at(-1)?.text);
} else {
  // Seguir el hilo
  await oni.chat("Gracias", { conversationId: first.conversationId });
}

OpenAPI: GET https://onnivers.store/v1/openapi.yaml
Conformance: node scripts/protocol-conformance-prod.mjs

Intents soportados

• business.chat — conversación general
• appointment.create — agendar cita/demo
• order.create — crear pedido
• product.price / product.info — consultar producto
• catalog.browse — ver catálogo
• payment.info — datos de pago

Ejemplo completo

import { OniPinClient } from "onipin-js";

const oni = new OniPinClient({
  baseUrl: "https://onnivers.store",
  pin: "onp_tu_pin",
  agent: { name: "CursorAgent", version: "1.0" },
});

await oni.ping();
await oni.handshake("business.chat");
await oni.catalog();

const chat = await oni.chat("Hola, ¿qué servicios ofrecen?");
await oni.messages({ limit: 10 });

await oni.createBooking({
  service: "Consulta",
  scheduledLabel: "2026-07-20 15:00",
  clientName: "Ana",
  clientContact: "[email protected]",
});

Alternativas

• MCP (IAs): https://onnivers.store/mcp — herramientas descubrir_url, handshake, enviar_mensaje
• HTTP directo: GET/POST https://onnivers.store/v1/...
• Well-known: GET https://onnivers.store/.well-known/onipin

Licencia

MIT — Empresa Tecnológica de Colombia / OnniVers