plugin-paperclip-personal-openia-adapter 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# OpenAI‑compatible Adapter for Paperclip
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+![npm](https://img.shields.io/npm/v/plugin-paperclip-personal-openia-adapter)
+![npm downloads](https://img.shields.io/npm/dt/plugin-paperclip-personal-openia-adapter)
+
+---
+
+<details open>
+<summary>🇺🇸 English</summary>
+
+## Installation
+
+```bash
+npm i plugin-paperclip-personal-openia-adapter
+```
+
+## Configuration (Paperclip UI)
+
+| Field   | Label                              | Default value                | Description                                            |
+|---------|------------------------------------|------------------------------|--------------------------------------------------------|
+| `baseUrl` | Base URL of the OpenAI gateway   | `https://api.openai.com/v1`  | Base endpoint address (e.g., https://example.com/v1) |
+| `apiKey`  | API Key                          | –                            | Access key for the gateway (secret field) |
+| `model`   | Model name                       | `gpt-4o`                     | Identifier of the model to be used |
+
+## How it works
+
+1. Paperclip calls the `handleChat` function with the user's messages.
+2. The adapter constructs a **POST** request to `${baseUrl}/chat/completions`.
+3. The request includes the header `Authorization: Bearer <apiKey>`.
+4. The response returns the content of `choices[0].message.content`.
+5. In case of error, friendly messages are generated without mentioning specific providers.
+
+---
+</details>
+
+<details>
+<summary>🇧🇷 Português</summary>
+
+## Instalação
+
+```bash
+npm i plugin-paperclip-personal-openia-adapter
+```
+
+## Configuração (UI exibida no Paperclip)
+
+| Campo      | Rótulo               | Valor padrão                | Descrição                                            |
+|------------|----------------------|-----------------------------|------------------------------------------------------|
+| `baseUrl`  | Base URL do gateway OpenAI | `https://api.openai.com/v1` | Endereço base do endpoint (ex.: https://example.com/v1) |
+| `apiKey`   | API Key              | –                           | Chave de acesso ao gateway (campo secreto)          |
+| `model`    | Nome do Modelo       | `gpt-4o`                    | Identificador do modelo a ser usado                 |
+
+## Como funciona
+
+1. O Paperclip chama a função `handleChat` passando as mensagens do usuário.
+2. O adapter monta a requisição **POST** para `${baseUrl}/chat/completions`.
+3. A requisição inclui o cabeçalho `Authorization: Bearer <apiKey>`.
+4. A resposta é retornada como o conteúdo de `choices[0].message.content`.
+5. Em caso de erro, mensagens amigáveis são geradas sem citar provedores específicos.
+
+---
+</details>
+
+MIT © 2026 Glebson Santos

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * External Adapter – OpenAI compatible (e.g., 9route)
+ *
+ * Implements the Paperclip SDK contract.  The adapter is generic for any
+ * OpenAI‑compatible endpoint, therefore error messages refer only to the
+ * generic gateway and not to a specific provider such as "9route".
+ */
+import { Adapter, ConfigField } from '@paperclip/sdk';
+/** ------------------------------------------------------------
+ * 1️⃣ CONFIGURATION SCHEMA (UI displayed in Paperclip)
+ * ------------------------------------------------------------ */
+export declare const configSchema: ConfigField[];
+/** ------------------------------------------------------------
+ * 3️⃣ EXPORT ADAPTER OBJECT
+ * ------------------------------------------------------------ */
+export declare const adapter: Adapter;
+export default adapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,OAAO,EAIP,WAAW,EACZ,MAAM,gBAAgB,CAAC;AAExB;;kEAEkE;AAClE,eAAO,MAAM,YAAY,EAAE,WAAW,EAyBrC,CAAC;AAyDF;;kEAEkE;AAClE,eAAO,MAAM,OAAO,EAAE,OAIrB,CAAC;AAEF,eAAe,OAAO,CAAC"}

package/dist/index.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * External Adapter – OpenAI compatible (e.g., 9route)
+ *
+ * Implements the Paperclip SDK contract.  The adapter is generic for any
+ * OpenAI‑compatible endpoint, therefore error messages refer only to the
+ * generic gateway and not to a specific provider such as "9route".
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.adapter = exports.configSchema = void 0;
+const axios_1 = __importDefault(require("axios"));
+/** ------------------------------------------------------------
+ * 1️⃣ CONFIGURATION SCHEMA (UI displayed in Paperclip)
+ * ------------------------------------------------------------ */
+exports.configSchema = [
+    {
+        key: 'baseUrl',
+        type: 'string',
+        label: 'Base URL do gateway OpenAI',
+        default: 'https://api.openai.com/v1',
+        placeholder: 'https://example.com/v1',
+        description: 'Endereço base do gateway compatível com a API da OpenAI.',
+    },
+    {
+        key: 'apiKey',
+        type: 'string',
+        label: 'API Key',
+        secret: true,
+        placeholder: 'sk-*****',
+        description: 'Chave de acesso ao gateway.',
+    },
+    {
+        key: 'model',
+        type: 'string',
+        label: 'Nome do Modelo',
+        default: 'gpt-4o',
+        placeholder: 'gpt-4o',
+        description: 'Identificador do modelo a ser usado.',
+    },
+];
+/** ------------------------------------------------------------
+ * 2️⃣ CHAT REQUEST HANDLER
+ * ------------------------------------------------------------ */
+async function handleChat(config, request) {
+    // Ensure the base URL does not end with a slash before appending the path
+    const url = `${config.baseUrl?.replace(/\/+$/, '')}/chat/completions`;
+    const payload = {
+        model: config.model ?? 'gpt-4o',
+        messages: request.messages,
+        temperature: request.options?.temperature ?? 0.7,
+        top_p: request.options?.top_p ?? 1,
+    };
+    try {
+        const resp = await axios_1.default.post(url, payload, {
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${config.apiKey}`,
+            },
+            timeout: 30_000,
+        });
+        const choice = resp.data?.choices?.[0];
+        if (!choice?.message?.content) {
+            throw new Error('Resposta inesperada da API OpenAI‑compatible.');
+        }
+        return { content: choice.message.content };
+    }
+    catch (err) {
+        // -------- Friendly generic error handling --------
+        if (axios_1.default.isAxiosError(err)) {
+            const axiosErr = err;
+            const status = axiosErr.response?.status;
+            const data = axiosErr.response?.data;
+            let friendlyMsg = 'Erro ao comunicar com o gateway OpenAI‑compatible.';
+            if (status === 401)
+                friendlyMsg = 'Credenciais inválidas (401).';
+            else if (status === 404)
+                friendlyMsg = 'Endpoint não encontrado (404).';
+            else if (status && status >= 500)
+                friendlyMsg = 'Erro interno do servidor (5xx).';
+            else if (data && typeof data === 'object' && 'error' in data) {
+                // OpenAI‑style error payload
+                friendlyMsg = `Gateway error: ${data.error?.message ?? friendlyMsg}`;
+            }
+            throw new Error(friendlyMsg);
+        }
+        // Non‑HTTP errors
+        throw err;
+    }
+}
+/** ------------------------------------------------------------
+ * 3️⃣ EXPORT ADAPTER OBJECT
+ * ------------------------------------------------------------ */
+exports.adapter = {
+    name: 'OpenAI‑compatible Adapter (personal)',
+    configSchema: exports.configSchema,
+    handleChat,
+};
+exports.default = exports.adapter;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "plugin-paperclip-personal-openia-adapter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "External adapter for Paperclip AI that connects to an OpenAI‑compatible gateway (e.g., 9route).",
+  "author": "Glebson Santos <glebsonsantos@outlook.pt>",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc",
+    "prepare": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "axios": "^1.7.2"
+  },
+  "peerDependencies": {
+    "@paperclip/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@paperclip/sdk": "file:./sdk",
+    "typescript": "^5.5.4",
+    "rimraf": "^5.0.5"
+  }
+}

package/src/index.ts

@@ -0,0 +1,112 @@
+/**
+ * External Adapter – OpenAI compatible (e.g., 9route)
+ *
+ * Implements the Paperclip SDK contract.  The adapter is generic for any
+ * OpenAI‑compatible endpoint, therefore error messages refer only to the
+ * generic gateway and not to a specific provider such as "9route".
+ */
+
+import axios, { AxiosError } from 'axios';
+import {
+  Adapter,
+  AdapterConfig,
+  ChatRequest,
+  ChatResponse,
+  ConfigField,
+} from '@paperclip/sdk';
+
+/** ------------------------------------------------------------
+ * 1️⃣ CONFIGURATION SCHEMA (UI displayed in Paperclip)
+ * ------------------------------------------------------------ */
+export const configSchema: ConfigField[] = [
+  {
+    key: 'baseUrl',
+    type: 'string',
+    label: 'Base URL do gateway OpenAI',
+    default: 'https://api.openai.com/v1',
+    placeholder: 'https://example.com/v1',
+    description: 'Endereço base do gateway compatível com a API da OpenAI.',
+  },
+  {
+    key: 'apiKey',
+    type: 'string',
+    label: 'API Key',
+    secret: true,
+    placeholder: 'sk-*****',
+    description: 'Chave de acesso ao gateway.',
+  },
+  {
+    key: 'model',
+    type: 'string',
+    label: 'Nome do Modelo',
+    default: 'gpt-4o',
+    placeholder: 'gpt-4o',
+    description: 'Identificador do modelo a ser usado.',
+  },
+];
+
+/** ------------------------------------------------------------
+ * 2️⃣ CHAT REQUEST HANDLER
+ * ------------------------------------------------------------ */
+async function handleChat(
+  config: AdapterConfig,
+  request: ChatRequest
+): Promise<ChatResponse> {
+  // Ensure the base URL does not end with a slash before appending the path
+  const url = `${config.baseUrl?.replace(/\/+$/, '')}/chat/completions`;
+
+  const payload = {
+    model: config.model ?? 'gpt-4o',
+    messages: request.messages,
+    temperature: request.options?.temperature ?? 0.7,
+    top_p: request.options?.top_p ?? 1,
+  };
+
+  try {
+    const resp = await axios.post(url, payload, {
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${config.apiKey}`,
+      },
+      timeout: 30_000,
+    });
+
+    const choice = resp.data?.choices?.[0];
+    if (!choice?.message?.content) {
+      throw new Error('Resposta inesperada da API OpenAI‑compatible.');
+    }
+
+    return { content: choice.message.content } as ChatResponse;
+  } catch (err) {
+    // -------- Friendly generic error handling --------
+    if (axios.isAxiosError(err)) {
+      const axiosErr = err as AxiosError;
+      const status = axiosErr.response?.status;
+      const data = axiosErr.response?.data;
+
+      let friendlyMsg = 'Erro ao comunicar com o gateway OpenAI‑compatible.';
+      if (status === 401) friendlyMsg = 'Credenciais inválidas (401).';
+      else if (status === 404) friendlyMsg = 'Endpoint não encontrado (404).';
+      else if (status && status >= 500) friendlyMsg = 'Erro interno do servidor (5xx).';
+      else if (data && typeof data === 'object' && 'error' in data) {
+        // OpenAI‑style error payload
+        friendlyMsg = `Gateway error: ${(data as any).error?.message ?? friendlyMsg}`;
+      }
+
+      throw new Error(friendlyMsg);
+    }
+    // Non‑HTTP errors
+    throw err;
+  }
+}
+
+/** ------------------------------------------------------------
+ * 3️⃣ EXPORT ADAPTER OBJECT
+ * ------------------------------------------------------------ */
+export const adapter: Adapter = {
+  name: 'OpenAI‑compatible Adapter (personal)',
+  configSchema,
+  handleChat,
+};
+
+export default adapter;