@neocoode/sdk-orion

SDK em JavaScript/TypeScript para integração com a API Orion (chat e autenticação).

Requisitos

• Node.js >= 18
• Credenciais Orion: Base URL da API, Client API Key e Agent API Key (fornecidos pelo seu projeto Orion)
• Opcional: Login – se o backend exigir autenticação, use os métodos de auth após connect

Instalação

npm install @neocoode/sdk-orion

ou

yarn add @neocoode/sdk-orion

Uso básico

import { connect, createChatId } from '@neocoode/sdk-orion';

const orn = connect({
  baseUrl: 'https://sua-api.orion.com',
  clientApiKey: 'SUA_CLIENT_API_KEY',
  agentApiKey: 'SUA_AGENT_API_KEY',
});

const chatId = orn.chat.createChatId();
const res = await orn.chat.sendMessage({ chatId, content: 'Olá' });

Conexão por argumentos

const orn = connect(
  'https://sua-api.orion.com',
  'SUA_CLIENT_API_KEY',
  'SUA_AGENT_API_KEY'
);

Configuração (OrionSdkConfig)

| Campo | Tipo | Obrigatório | Descrição | |--------------------|----------|-------------|-----------| | baseUrl | string | Sim | URL base da API Orion (sem barra final) | | clientApiKey | string | Sim | Chave do projeto (Client API Key) | | agentApiKey | string | Sim | Chave do agente (Agent API Key) | | agentId | string | Não | ID do agente, se necessário | | requireLogin | boolean | Não | Se exige login; padrão true | | getGeoJson | () => string | Não | Função que retorna GeoJSON do cliente (localização) | | getIdentifyCli | () => string | Não | Função que retorna identificador do cliente |

API

Após connect(config) você recebe um objeto com:

• orn.chat – API de chat (mensagens, conversas, feedback)
• orn.auth – API de autenticação (login, registro, sessão)
• orn.requireLogin – indica se o backend exige login

Chat (orn.chat)

createChatId(): string

Gera um ID único para nova conversa (uso local, antes de criar o chat no servidor).

const chatId = orn.chat.createChatId();

sendMessage(payload): Promise<SdkMessageSendResponse>

Envia uma mensagem sem streaming.

Payload (SdkMessageSendRequest):

| Campo | Tipo | Obrigatório | Descrição | |-------------------------|----------|-------------|-----------| | chatId | string | Sim | ID da conversa | | content | string | Sim | Texto da mensagem | | projectId | string | Não | ID do projeto | | sender | string | Não | Identificador do remetente | | language | string | Não | Ex.: pt-BR | | useStream | boolean | Não | Se deve usar streaming | | recordTraining | boolean | Não | Gravar para treinamento | | disableFallback | boolean | Não | Desabilitar fallback | | timezoneOffsetMinutes | number | Não | Offset de fuso em minutos | | inputFilters | string[] | Não | Filtros de entrada (ex.: busca na internet) |

Retorno: { success: boolean; data?: SdkMessageSendResponseData; error?: string }

sendMessageStream(payload, callbacks): Promise<SdkMessageSendResponseData | null>

Envia mensagem em streaming. O mesmo payload de sendMessage, sem useStream. Os eventos são entregues via callbacks.

Callbacks (SdkStreamCallbacks):

| Callback | Assinatura | Descrição | |------------|------------|-----------| | onChunk | (content: string, source?: string) => void | Fragmento de texto da resposta | | onItem | (item: { contentType: string; data: string }) => void | Item estruturado (ex.: bloco de código) | | onStatus| (status: string) => void | Mensagem de status do fluxo | | onDone | (data?: SdkMessageSendResponseData) => void | Resposta final (IDs, tokens, etc.) | | onError | (error: string) => void | Erro durante o stream |

await orn.chat.sendMessageStream(
  { chatId, content: 'Explique X' },
  {
    onChunk: (content) => console.log(content),
    onDone: (data) => console.log('Concluído', data),
    onError: (err) => console.error(err),
  }
);

getMessages(chatId, params?): Promise<SdkListMessagesResponse>

Lista mensagens de uma conversa.

Params: { page?: number; limit?: number }

Retorno: { success: boolean; data?: { messages: unknown[]; total: number }; error?: string }

getChats(params?): Promise<SdkListChatsResponse>

Lista conversas do usuário.

Params: { page?: number; limit?: number }

Retorno: { success: boolean; data?: { chats: unknown[]; total: number }; error?: string }

getDetails(): Promise<SdkDetailsResponse>

Retorna detalhes do projeto/agente (nome do projeto, agente, quantidade de chats abertos, etc.).

Retorno: { success: boolean; data?: { projectName; agentName; openChatsCount }; error?: string }

createChat(): Promise<SdkCreateChatResponse>

Cria uma nova conversa no servidor.

Retorno: { success: boolean; data?: { id: string; title?: string }; error?: string }

clearChat(chatId): Promise<SdkClearChatResponse>

Limpa as mensagens de uma conversa.

deleteChat(chatId): Promise<SdkDeleteChatResponse>

Exclui uma conversa.

renameChat(chatId, title): Promise<SdkRenameChatResponse>

Renomeia uma conversa.

like(messageId): Promise<boolean>

Envia feedback positivo (like) para uma mensagem do agente.

dislike(messageId, reason?): Promise<boolean>

Envia feedback negativo (dislike), com reason opcional.

Auth (orn.auth)

Usado quando o backend Orion exige login. Após login bem-sucedido, o token é guardado na instância e enviado nas requisições seguintes.

loginEmail(email, password): Promise<SdkAuthLoginResponse>

Login com e-mail e senha.

Retorno: { success: boolean; data?: { token: string; user: SdkAuthUser }; error?: string }

loginWithGoogle(idToken): Promise<SdkAuthLoginResponse>

Login com Google (idToken do OAuth).

register(email, password, name?): Promise<SdkAuthLoginResponse>

Registro de novo usuário. Opcionalmente name.

logout(): Promise<{ success: boolean; error?: string }>

Encerra a sessão e limpa o token na instância.

getMe(): Promise<SdkAuthMeResponse>

Retorna o usuário logado.

Retorno: { success: boolean; data?: SdkAuthUser; error?: string }

getSessionToken(): string | null

Retorna o token da sessão atual (ou null).

setSessionToken(token: string | null): void

Define o token manualmente (útil para restaurar sessão, ex.: a partir de cookie ou storage).

const orn = connect(config);
const loginRes = await orn.auth.loginEmail('[email protected]', 'senha');
if (loginRes.success && loginRes.data?.token) {
  orn.auth.setSessionToken(loginRes.data.token);
}
const me = await orn.auth.getMe();

Utilitário

createChatId(): string (export direto)

Gera um ID único para chat (usa crypto.getRandomValues no browser/Node 18+).

import { createChatId } from '@neocoode/sdk-orion';
const id = createChatId();

Tipos exportados

O pacote exporta os tipos TypeScript necessários para payloads e respostas, entre outros:

• Config e instância: OrionSdkConfig, OrionInstance, OrionChatApi, OrionAuthApi
• Mensagens e chat: SdkMessage, SdkMessageSender, SdkMessageFeedback, SdkChat, SdkMessageSendRequest, SdkMessageSendResponse, SdkMessageSendResponseData, UserMessageResponse, AgentMessageResponse
• Listagens: SdkListMessagesParams, SdkListMessagesResponse, SdkListChatsParams, SdkListChatsResponse
• Respostas de chat: SdkDetailsResponse, SdkCreateChatResponse, SdkClearChatResponse, SdkDeleteChatResponse, SdkRenameChatResponse
• Feedback: SdkFeedbackRequest, SdkFeedbackResponse
• Streaming: SdkStreamEvent, SdkStreamEventChunk, SdkStreamEventItem, SdkStreamEventStatus, SdkStreamEventDone, SdkStreamEventError, SdkStreamCallbacks
• Auth: SdkAuthUser, SdkAuthLoginResponse, SdkAuthMeResponse
• Cliente: OrionSdkClient (classe, para uso avançado)

Exemplo completo (envio com streaming)

import { connect, createChatId } from '@neocoode/sdk-orion';

const orn = connect({
  baseUrl: process.env.ORION_BASE_URL!,
  clientApiKey: process.env.ORION_CLIENT_API_KEY!,
  agentApiKey: process.env.ORION_AGENT_API_KEY!,
});

const chatId = createChatId();
const created = await orn.chat.createChat();
if (!created.success || !created.data?.id) {
  console.error(created.error);
  return;
}
const conversationId = created.data.id;

await orn.chat.sendMessageStream(
  { chatId: conversationId, content: 'O que é TypeScript?' },
  {
    onChunk: (content) => process.stdout.write(content),
    onStatus: (s) => console.log('[status]', s),
    onDone: (data) => console.log('\nDone', data),
    onError: (e) => console.error(e),
  }
);

const list = await orn.chat.getMessages(conversationId, { limit: 20 });
console.log(list.data?.messages);

Exemplo no repositório (Next.js)

O projeto sdk-console-nextjs é um exemplo de interface de chat (sidebar, lista de conversas, envio em streaming, detalhes) usando este SDK. Na raiz do monorepo:

cd sdk-console-nextjs
yarn install
yarn dev

Abra http://localhost:3002 e configure Base URL e chaves no modal. O SDK é usado nas API Routes do Next.js; o front chama essas rotas e não importa o SDK diretamente no browser.

Build e publicação

yarn install
yarn build

Para publicar no npm (pacote com escopo @neocoode):

1. Crie a organização "neocoode" no npm (se ainda não existir): https://www.npmjs.com/org/create — sem isso o npm retorna 404 para @neocoode/sdk-orion.

2. Use o token na mesma linha do comando (o .npmrc do projeto usa a variável NPM_TOKEN; se não estiver definida, o npm usa a config global, que pode estar expirada):

NPM_TOKEN=seu_token_npm npm publish --access public

Substitua seu_token_npm pelo token que você criou em https://www.npmjs.com/ → Access Tokens. O build roda automaticamente via prepublishOnly. O package.json define files: ["dist", "README.md"], então apenas o build e o README são publicados.