onipin-js 0.2.0

package/README.md

@@ -0,0 +1,57 @@
+# onipin-js
+
+SDK oficial de [OniPin](https://onnivers.store) — protocolo `/v1`, chat, catálogo, reservas y pedidos.
+
+## Instalación
+
+```bash
+npm install onipin-js
+```
+
+## Uso rápido
+
+```javascript
+import { OniPinClient } from "onipin-js";
+
+const oni = new OniPinClient({
+  baseUrl: "https://onnivers.store",
+  pin: "onp_tu_pin",
+  callerType: "ai-agent",
+  callerName: "MiBot",
+});
+
+const info = await oni.ping();
+console.log(info.name, info.capabilities);
+
+const chat = await oni.chat("Hola, ¿qué servicios ofrecen?");
+console.log(chat.reply?.text);
+
+const booking = 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
+
+| 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 |
+
+## Licencia
+
+MIT — Empresa Tecnológica de Colombia / OnniVers

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+/**
+ * onipin-js — SDK oficial del protocolo OniPin (/v1).
+ *
+ * Uso:
+ *   import { OniPinClient } from "onipin-js";
+ *   const oni = new OniPinClient({ baseUrl: "https://onnivers.store", pin: "onp_..." });
+ *   const reply = await oni.chat("Hola");
+ */
+export type OniPinClientOptions = {
+    /** Origen del servidor OniPin (sin slash final). Default: https://onnivers.store */
+    baseUrl?: string;
+    /** Pin del negocio (onp_…) */
+    pin: string;
+    /** Tipo de llamador para el protocolo. Default: ai-agent */
+    callerType?: "human" | "ai-agent";
+    /** Nombre visible del llamador */
+    callerName?: string;
+    /** fetch personalizado (p. ej. undici, timeout wrappers) */
+    fetch?: typeof globalThis.fetch;
+};
+export type PingResult = {
+    ok: true;
+    protocol: string;
+    pin: string;
+    name: string;
+    description?: string;
+    language?: string;
+    capabilities: string[];
+    mcp?: string;
+};
+export type CatalogItem = {
+    id: string;
+    name: string;
+    description?: string;
+    price?: string;
+    kind?: string;
+    imageUrl?: string | null;
+};
+export type ChatMessage = {
+    id: string;
+    role: "visitor" | "bot" | "owner" | string;
+    author?: string;
+    text: string;
+    createdAt: string;
+};
+export type ChatResult = {
+    ok: true;
+    protocol: string;
+    conversationId: string;
+    reply: {
+        id?: string;
+        text: string;
+        engine?: string;
+        createdAt?: string;
+    } | null;
+    data: Record<string, unknown>;
+};
+export declare class OniPinError extends Error {
+    status: number;
+    body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+export declare class OniPinClient {
+    readonly baseUrl: string;
+    readonly pin: string;
+    readonly callerType: "human" | "ai-agent";
+    readonly callerName?: string;
+    conversationId: string | null;
+    private readonly _fetch;
+    constructor(opts: OniPinClientOptions);
+    private request;
+    /** Discovery del negocio (GET /v1/ping/:pin). */
+    ping(): Promise<PingResult>;
+    /** Catálogo público de productos/servicios. */
+    catalog(): Promise<{
+        ok: true;
+        items: CatalogItem[];
+        business?: string;
+    }>;
+    /** Envía un mensaje y mantiene conversationId entre llamadas. */
+    chat(message: string, conversationId?: string | null): Promise<ChatResult>;
+    /** Lee mensajes del hilo (con cursor `after` y `limit` opcionales). */
+    messages(opts?: {
+        conversationId?: string;
+        after?: string;
+        limit?: number;
+    }): Promise<{
+        ok: true;
+        conversationId: string;
+        mode: string;
+        messages: ChatMessage[];
+    }>;
+    /** Crea una reserva real (tabla bookings). */
+    createBooking(input: {
+        service: string;
+        scheduledLabel?: string;
+        scheduledAt?: string;
+        clientName: string;
+        clientContact?: string;
+        notes?: string;
+        conversationId?: string;
+    }): Promise<{
+        ok: true;
+        booking: Record<string, unknown>;
+    }>;
+    /** Crea un pedido real (tabla orders). */
+    createOrder(input: {
+        productName: string;
+        quantity?: number;
+        productId?: string;
+        unitPrice?: string;
+        clientName: string;
+        clientContact?: string;
+        notes?: string;
+        conversationId?: string;
+    }): Promise<{
+        ok: true;
+        order: Record<string, unknown>;
+    }>;
+    /** Resetea el hilo local (la próxima chat() abre conversación nueva). */
+    reset(): void;
+}
+export default OniPinClient;

package/dist/index.js

@@ -0,0 +1,97 @@
+/**
+ * onipin-js — SDK oficial del protocolo OniPin (/v1).
+ *
+ * Uso:
+ *   import { OniPinClient } from "onipin-js";
+ *   const oni = new OniPinClient({ baseUrl: "https://onnivers.store", pin: "onp_..." });
+ *   const reply = await oni.chat("Hola");
+ */
+export class OniPinError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = "OniPinError";
+        this.status = status;
+        this.body = body;
+    }
+}
+export class OniPinClient {
+    baseUrl;
+    pin;
+    callerType;
+    callerName;
+    conversationId = null;
+    _fetch;
+    constructor(opts) {
+        if (!opts.pin)
+            throw new Error("pin es obligatorio");
+        this.baseUrl = (opts.baseUrl || "https://onnivers.store").replace(/\/$/, "");
+        this.pin = opts.pin;
+        this.callerType = opts.callerType || "ai-agent";
+        this.callerName = opts.callerName;
+        this._fetch = opts.fetch || globalThis.fetch.bind(globalThis);
+    }
+    async request(path, init) {
+        const res = await this._fetch(`${this.baseUrl}${path}`, {
+            ...init,
+            headers: {
+                "Content-Type": "application/json",
+                ...(init?.headers || {}),
+            },
+        });
+        const body = await res.json().catch(() => ({}));
+        if (!res.ok || body.ok === false) {
+            throw new OniPinError(body.error || `OniPin HTTP ${res.status}`, res.status, body);
+        }
+        return body;
+    }
+    /** Discovery del negocio (GET /v1/ping/:pin). */
+    ping() {
+        return this.request(`/v1/ping/${encodeURIComponent(this.pin)}`);
+    }
+    /** 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) {
+        const result = await this.request(`/v1/chat/${encodeURIComponent(this.pin)}`, {
+            method: "POST",
+            headers: { "X-Caller-Type": this.callerType },
+            body: JSON.stringify({
+                message,
+                conversationId: conversationId ?? this.conversationId,
+                callerName: this.callerName,
+            }),
+        });
+        this.conversationId = result.conversationId;
+        return result;
+    }
+    /** Lee mensajes del hilo (con cursor `after` y `limit` opcionales). */
+    messages(opts = {}) {
+        const id = opts.conversationId || this.conversationId;
+        if (!id)
+            throw new Error("conversationId requerido — llama chat() primero");
+        const q = new URLSearchParams();
+        if (opts.after)
+            q.set("after", opts.after);
+        if (opts.limit)
+            q.set("limit", String(opts.limit));
+        const qs = q.toString() ? `?${q}` : "";
+        return this.request(`/v1/chat/${encodeURIComponent(this.pin)}/${id}/messages${qs}`);
+    }
+    /** Crea una reserva real (tabla bookings). */
+    createBooking(input) {
+        return this.request(`/v1/bookings/${encodeURIComponent(this.pin)}`, { method: "POST", body: JSON.stringify({ ...input, conversationId: input.conversationId ?? this.conversationId }) });
+    }
+    /** Crea un pedido real (tabla orders). */
+    createOrder(input) {
+        return this.request(`/v1/orders/${encodeURIComponent(this.pin)}`, { method: "POST", body: JSON.stringify({ ...input, conversationId: input.conversationId ?? this.conversationId }) });
+    }
+    /** Resetea el hilo local (la próxima chat() abre conversación nueva). */
+    reset() {
+        this.conversationId = null;
+    }
+}
+export default OniPinClient;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "onipin-js",
+  "version": "0.2.0",
+  "description": "SDK oficial de OniPin — protocolo /v1, chat, catálogo, reservas y pedidos",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "keywords": ["onipin", "mcp", "ai", "chat", "sdk", "onnivers"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deivys1224-ctrl/oniping.git",
+    "directory": "packages/onipin-js"
+  },
+  "homepage": "https://onnivers.store/docs#sdk",
+  "bugs": {
+    "url": "https://github.com/deivys1224-ctrl/oniping/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}