onipin-js 0.2.0 → 0.2.1

package/README.md

@@ -1,6 +1,10 @@
 # onipin-js
 
-SDK oficial de [OniPin](https://onnivers.store) — protocolo `/v1`, chat, catálogo, reservas y pedidos.
+SDK oficial de [OniPin](https://onnivers.store) — 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
 
@@ -8,7 +12,7 @@ SDK oficial de [OniPin](https://onnivers.store) — protocolo `/v1`, chat, catá
 npm install onipin-js
 ```
 
-## Uso rápido
+## Inicio rápido (OniPin 0.2)
 
 ```javascript
 import { OniPinClient } from "onipin-js";
@@ -17,40 +21,76 @@ const oni = new OniPinClient({
   baseUrl: "https://onnivers.store",
   pin: "onp_tu_pin",
   callerType: "ai-agent",
-  callerName: "MiBot",
+  agent: { name: "MiBot", version: "1.0" },
 });
 
-const info = await oni.ping();
-console.log(info.name, info.capabilities);
+// 1. Descubrir desde URL (opcional si ya tienes el pin)
+const found = await oni.discoverFromUrl("https://sitio-del-negocio.com");
 
-const chat = await oni.chat("Hola, ¿qué servicios ofrecen?");
+// 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, limit })` | Lee el hilo |
+| `createBooking({ service, scheduledLabel, clientName, ... })` | Reserva real en BD |
+| `createOrder({ productName, quantity, clientName, ... })` | Pedido real en BD |
+| `reset()` | Nueva conversación local |
+
+## 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
+
+```javascript
+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 });
 
-const booking = await oni.createBooking({
+await oni.createBooking({
   service: "Consulta",
   scheduledLabel: "2026-07-20 15:00",
   clientName: "Ana",
   clientContact: "ana@email.com",
 });
-
-const order = await oni.createOrder({
-  productName: "Plan Pro",
-  quantity: 1,
-  clientName: "Ana",
-});
 ```
 
-## API
+## Alternativas
 
-| Método | Descripción |
-|--------|-------------|
-| `ping()` | Discovery del negocio |
-| `catalog()` | Productos/servicios activos |
-| `chat(message)` | Envía mensaje y mantiene `conversationId` |
-| `messages({ after, limit })` | Lee el hilo |
-| `createBooking(...)` | Reserva real en BD |
-| `createOrder(...)` | Pedido real en BD |
-| `reset()` | Nueva conversación |
+- **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
 

package/dist/index.d.ts

@@ -15,9 +15,23 @@ export type OniPinClientOptions = {
     callerType?: "human" | "ai-agent";
     /** Nombre visible del llamador */
     callerName?: string;
+    /** Agente externo (handshake OniPin 0.2) */
+    agent?: {
+        name: string;
+        version?: string;
+    };
     /** fetch personalizado (p. ej. undici, timeout wrappers) */
     fetch?: typeof globalThis.fetch;
 };
+export type OniIntent = "business.chat" | "appointment.create" | "appointment.status" | "order.create" | "product.price" | "product.info" | "catalog.browse" | "payment.info" | string;
+export type ChatOptions = {
+    conversationId?: string | null;
+    intent?: OniIntent;
+    agent?: {
+        name: string;
+        version?: string;
+    };
+};
 export type PingResult = {
     ok: true;
     protocol: string;
@@ -25,8 +39,31 @@ export type PingResult = {
     name: string;
     description?: string;
     language?: string;
-    capabilities: string[];
+    capabilities?: string[];
+    supports?: string[];
     mcp?: string;
+    handshake_endpoint?: string;
+};
+export type DiscoverResult = {
+    ok: boolean;
+    found: boolean;
+    pin?: string;
+    source?: string;
+    url?: string;
+    discovery?: Record<string, unknown>;
+    handshake_url?: string;
+};
+export type HandshakeResult = {
+    ok: true;
+    protocol: string;
+    handshake: string;
+    agent?: {
+        name: string;
+        version?: string | null;
+    } | null;
+    intent?: string | null;
+    supports?: string[];
+    endpoint?: string;
 };
 export type CatalogItem = {
     id: string;
@@ -47,6 +84,11 @@ export type ChatResult = {
     ok: true;
     protocol: string;
     conversationId: string;
+    handshake?: {
+        accepted: boolean;
+        agent?: unknown;
+        intent?: string | null;
+    };
     reply: {
         id?: string;
         text: string;
@@ -65,12 +107,23 @@ export declare class OniPinClient {
     readonly pin: string;
     readonly callerType: "human" | "ai-agent";
     readonly callerName?: string;
+    readonly agent?: {
+        name: string;
+        version?: string;
+    };
     conversationId: string | null;
     private readonly _fetch;
     constructor(opts: OniPinClientOptions);
     private request;
     /** Discovery del negocio (GET /v1/ping/:pin). */
     ping(): Promise<PingResult>;
+    /** Descubrir pin desde URL de un sitio (GET /v1/discover?url=). */
+    discoverFromUrl(url: string): Promise<DiscoverResult>;
+    /** Handshake OniPin 0.2 — anuncia agente e intención. */
+    handshake(intent?: OniIntent, agent?: {
+        name: string;
+        version?: string;
+    }): Promise<HandshakeResult>;
     /** Catálogo público de productos/servicios. */
     catalog(): Promise<{
         ok: true;
@@ -78,7 +131,7 @@ export declare class OniPinClient {
         business?: string;
     }>;
     /** Envía un mensaje y mantiene conversationId entre llamadas. */
-    chat(message: string, conversationId?: string | null): Promise<ChatResult>;
+    chat(message: string, opts?: ChatOptions): Promise<ChatResult>;
     /** Lee mensajes del hilo (con cursor `after` y `limit` opcionales). */
     messages(opts?: {
         conversationId?: string;

package/dist/index.js

@@ -21,6 +21,7 @@ export class OniPinClient {
     pin;
     callerType;
     callerName;
+    agent;
     conversationId = null;
     _fetch;
     constructor(opts) {
@@ -30,6 +31,7 @@ export class OniPinClient {
         this.pin = opts.pin;
         this.callerType = opts.callerType || "ai-agent";
         this.callerName = opts.callerName;
+        this.agent = opts.agent || (opts.callerName ? { name: opts.callerName } : undefined);
         this._fetch = opts.fetch || globalThis.fetch.bind(globalThis);
     }
     async request(path, init) {
@@ -50,19 +52,39 @@ export class OniPinClient {
     ping() {
         return this.request(`/v1/ping/${encodeURIComponent(this.pin)}`);
     }
+    /** Descubrir pin desde URL de un sitio (GET /v1/discover?url=). */
+    discoverFromUrl(url) {
+        return this.request(`/v1/discover?url=${encodeURIComponent(url)}`);
+    }
+    /** Handshake OniPin 0.2 — anuncia agente e intención. */
+    handshake(intent, agent) {
+        const a = agent || this.agent;
+        return this.request(`/v1/handshake/${encodeURIComponent(this.pin)}`, {
+            method: "POST",
+            headers: { "X-Caller-Type": this.callerType },
+            body: JSON.stringify({ agent: a, intent: intent || "business.chat" }),
+        });
+    }
     /** Catálogo público de productos/servicios. */
     async catalog() {
         return this.request(`/v1/catalog/${encodeURIComponent(this.pin)}`);
     }
     /** Envía un mensaje y mantiene conversationId entre llamadas. */
-    async chat(message, conversationId) {
+    async chat(message, opts = {}) {
+        const agent = opts.agent || this.agent;
         const result = await this.request(`/v1/chat/${encodeURIComponent(this.pin)}`, {
             method: "POST",
-            headers: { "X-Caller-Type": this.callerType },
+            headers: {
+                "X-Caller-Type": this.callerType,
+                ...(opts.intent ? { "X-Oni-Intent": String(opts.intent) } : {}),
+                ...(agent?.name ? { "X-Oni-Agent": agent.name } : {}),
+            },
             body: JSON.stringify({
                 message,
-                conversationId: conversationId ?? this.conversationId,
-                callerName: this.callerName,
+                conversationId: opts.conversationId ?? this.conversationId,
+                callerName: agent?.name || this.callerName,
+                agent,
+                intent: opts.intent,
             }),
         });
         this.conversationId = result.conversationId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onipin-js",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "SDK oficial de OniPin — protocolo /v1, chat, catálogo, reservas y pedidos",
   "type": "module",
   "main": "./dist/index.js",