{"_id":"@adaflow/sdk","_rev":"7-f3329a98b39bb585911b9c2333b14523","name":"@adaflow/sdk","dist-tags":{"latest":"0.3.2"},"versions":{"0.1.0":{"name":"@adaflow/sdk","version":"0.1.0","license":"MIT","_id":"@adaflow/sdk@0.1.0","maintainers":[{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"}],"homepage":"https://github.com/Adalink-ai/adalink-integration-kit#readme","bugs":{"url":"https://github.com/Adalink-ai/adalink-integration-kit/issues"},"dist":{"shasum":"11894677270d9e9cf8e31169a380a07029d34142","tarball":"https://registry.npmjs.org/@adaflow/sdk/-/sdk-0.1.0.tgz","fileCount":9,"integrity":"sha512-QtUCcBa9oUBkg+12eJIkHFpOWhg3Pe33nOwAcBlrv3q88koSRHeQLh2T8u72iw01jgrJELUDF9UmVsjbwlJEwg==","signatures":[{"sig":"MEUCIQCnGshOnb5Z7D8b/VoG5OLnOelioqh3H8aaeHQC6rIamQIgfTJjRh1jA39oefdUHkGor3eHnj5apFS95XEvLHCU3uA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":121977},"main":"./dist/index.cjs","type":"module","_from":"file:adaflow-sdk-0.1.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.17"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"test":"vitest run","build":"tsup src/index.ts --format esm,cjs --dts --sourcemap --clean","typecheck":"tsc --noEmit"},"_npmUser":{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"},"_resolved":"/private/var/folders/_p/x5r0k47566516wwcmsy47k6c0000gn/T/be8369dc4e365260561e28f5f5035d8f/adaflow-sdk-0.1.0.tgz","_integrity":"sha512-QtUCcBa9oUBkg+12eJIkHFpOWhg3Pe33nOwAcBlrv3q88koSRHeQLh2T8u72iw01jgrJELUDF9UmVsjbwlJEwg==","repository":{"url":"git+https://github.com/Adalink-ai/adalink-integration-kit.git","type":"git","directory":"packages/sdk"},"_npmVersion":"11.13.0","description":"SDK Node/TypeScript oficial para integração com a plataforma Adaflow","directories":{},"_nodeVersion":"24.16.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","vitest":"^3.1.0","typescript":"^5.9.0","@types/node":"^22.15.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1784565365173_0.7476370955321754","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@adaflow/sdk","version":"0.2.0","license":"MIT","_id":"@adaflow/sdk@0.2.0","maintainers":[{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"}],"homepage":"https://github.com/Adalink-ai/adalink-integration-kit#readme","bugs":{"url":"https://github.com/Adalink-ai/adalink-integration-kit/issues"},"dist":{"shasum":"9e3dbb89b005522e1aac6094514e0c737604b821","tarball":"https://registry.npmjs.org/@adaflow/sdk/-/sdk-0.2.0.tgz","fileCount":9,"integrity":"sha512-SLQM5ZtadAf4lO6/lqPZ8AyOiHm1iUM9vdOr8h2rTlfvWILZJbwBOjqUFU5g0VHLQmE4k7Uf5pQdD+rVLboyuw==","signatures":[{"sig":"MEUCIGo5Wu2TQk/ZNcTxJmaggXEdaXKbNvCIyi/qfW8/sK/MAiEAsjgekEt5k+jdFm8/JQ9zaDOpKO9uyGGP35SWtXM012o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":234563},"main":"./dist/index.cjs","type":"module","_from":"file:adaflow-sdk-0.2.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.17"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"test":"vitest run","build":"tsup src/index.ts --format esm,cjs --dts --sourcemap --clean","typecheck":"tsc --noEmit"},"_npmUser":{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"},"_resolved":"/private/var/folders/_p/x5r0k47566516wwcmsy47k6c0000gn/T/813e83b922352b3ff12bb6a0a9529bbf/adaflow-sdk-0.2.0.tgz","_integrity":"sha512-SLQM5ZtadAf4lO6/lqPZ8AyOiHm1iUM9vdOr8h2rTlfvWILZJbwBOjqUFU5g0VHLQmE4k7Uf5pQdD+rVLboyuw==","repository":{"url":"git+https://github.com/Adalink-ai/adalink-integration-kit.git","type":"git","directory":"packages/sdk"},"_npmVersion":"11.13.0","description":"SDK Node/TypeScript oficial para integração com a plataforma Adaflow","directories":{},"_nodeVersion":"24.16.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","vitest":"^3.1.0","typescript":"^5.9.0","@types/node":"^22.15.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.2.0_1784582655777_0.07919828154752673","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@adaflow/sdk","version":"0.3.0","license":"MIT","_id":"@adaflow/sdk@0.3.0","maintainers":[{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"}],"homepage":"https://github.com/Adalink-ai/adalink-integration-kit#readme","bugs":{"url":"https://github.com/Adalink-ai/adalink-integration-kit/issues"},"dist":{"shasum":"729f7c4250944114d2cbe99656e7049a5ff3b26f","tarball":"https://registry.npmjs.org/@adaflow/sdk/-/sdk-0.3.0.tgz","fileCount":9,"integrity":"sha512-P4R6qyNL5UXVkTpwNLWu7b7Otj5z9hTZl0L72nQbZquf0uoXHORZ81NZjLf4Op1B/Jv2Fx9aKIdYWORnqtbbng==","signatures":[{"sig":"MEQCIFeaNtJmbIWR9YrILN2KJ0Y4VuyprvtrtrHFLiympnpTAiATo6ynrsRLIRkXDNSxcmdMjEnt7x8Zuv89FA4OQrY6bw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":239640},"main":"./dist/index.cjs","type":"module","_from":"file:adaflow-sdk-0.3.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.17"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"test":"vitest run","build":"tsup src/index.ts --format esm,cjs --dts --sourcemap --clean","typecheck":"tsc --noEmit"},"_npmUser":{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"},"_resolved":"/private/var/folders/_p/x5r0k47566516wwcmsy47k6c0000gn/T/7b24340c0a72af1296a3f67ee8851b51/adaflow-sdk-0.3.0.tgz","_integrity":"sha512-P4R6qyNL5UXVkTpwNLWu7b7Otj5z9hTZl0L72nQbZquf0uoXHORZ81NZjLf4Op1B/Jv2Fx9aKIdYWORnqtbbng==","repository":{"url":"git+https://github.com/Adalink-ai/adalink-integration-kit.git","type":"git","directory":"packages/sdk"},"_npmVersion":"11.13.0","description":"SDK Node/TypeScript oficial para integração com a plataforma Adaflow","directories":{},"_nodeVersion":"24.16.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","vitest":"^3.1.0","typescript":"^5.9.0","@types/node":"^22.15.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.3.0_1784641539767_0.4995509932760578","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"@adaflow/sdk","version":"0.3.1","license":"MIT","_id":"@adaflow/sdk@0.3.1","maintainers":[{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"}],"homepage":"https://github.com/Adalink-ai/adalink-integration-kit#readme","bugs":{"url":"https://github.com/Adalink-ai/adalink-integration-kit/issues"},"dist":{"shasum":"0b4fa83274135d5dcc1a79a467d166b4dee858b2","tarball":"https://registry.npmjs.org/@adaflow/sdk/-/sdk-0.3.1.tgz","fileCount":9,"integrity":"sha512-ZzSO/Rvl+eZF8z9wdyw6VXCwLeEbRmTeC209/NT29Sfi02tK3BpOelQAK0r7Gaaq053a7yOr0m1rNyKhjqWgOA==","signatures":[{"sig":"MEQCIHcPmGQ1kURxora83lguRzqSECw9QVEQAyIJ5Cg5UdD3AiBzhUK9pruk2rv6fjI78JKL2SH3knpIEFrDAnov7W9TIQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":240346},"main":"./dist/index.cjs","type":"module","_from":"file:adaflow-sdk-0.3.1.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.17"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"test":"vitest run","build":"tsup src/index.ts --format esm,cjs --dts --sourcemap --clean","typecheck":"tsc --noEmit"},"_npmUser":{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"},"_resolved":"/private/var/folders/_p/x5r0k47566516wwcmsy47k6c0000gn/T/8fe7e717b168ffc4d6ea018ec42aa30f/adaflow-sdk-0.3.1.tgz","_integrity":"sha512-ZzSO/Rvl+eZF8z9wdyw6VXCwLeEbRmTeC209/NT29Sfi02tK3BpOelQAK0r7Gaaq053a7yOr0m1rNyKhjqWgOA==","repository":{"url":"git+https://github.com/Adalink-ai/adalink-integration-kit.git","type":"git","directory":"packages/sdk"},"_npmVersion":"11.13.0","description":"SDK Node/TypeScript oficial para integração com a plataforma Adaflow","directories":{},"_nodeVersion":"24.16.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","vitest":"^3.1.0","typescript":"^5.9.0","@types/node":"^22.15.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.3.1_1784646811500_0.7343061779251236","host":"s3://npm-registry-packages-npm-production"}},"0.3.2":{"name":"@adaflow/sdk","version":"0.3.2","description":"SDK Node/TypeScript oficial para integração com a plataforma Adaflow","repository":{"type":"git","url":"git+https://github.com/Adalink-ai/adalink-integration-kit.git","directory":"packages/sdk"},"license":"MIT","publishConfig":{"access":"public"},"type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","engines":{"node":">=18.17"},"devDependencies":{"@types/node":"^22.15.0","tsup":"^8.4.0","typescript":"^5.9.0","vitest":"^3.1.0"},"scripts":{"build":"tsup src/index.ts --format esm,cjs --dts --sourcemap --clean","test":"vitest run","typecheck":"tsc --noEmit"},"_id":"@adaflow/sdk@0.3.2","bugs":{"url":"https://github.com/Adalink-ai/adalink-integration-kit/issues"},"homepage":"https://github.com/Adalink-ai/adalink-integration-kit#readme","_integrity":"sha512-/xbVl4OulNB5xn/Rna/mUKTWNUTz8pwXw0BYfkcHhuYRie982sO3AbVDVuBLoG6H0BGOVlnU3aoi7I3dlrPbPw==","_resolved":"/private/var/folders/_p/x5r0k47566516wwcmsy47k6c0000gn/T/9df13836df058500cd5ab591cd0aa7c4/adaflow-sdk-0.3.2.tgz","_from":"file:adaflow-sdk-0.3.2.tgz","_nodeVersion":"24.16.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-/xbVl4OulNB5xn/Rna/mUKTWNUTz8pwXw0BYfkcHhuYRie982sO3AbVDVuBLoG6H0BGOVlnU3aoi7I3dlrPbPw==","shasum":"3252b25bbcc6717744cfb5bcd5e6ba9ef79c757e","tarball":"https://registry.npmjs.org/@adaflow/sdk/-/sdk-0.3.2.tgz","fileCount":9,"unpackedSize":243842,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDVedjO33ZsDgdoBvzZuRyPLRdpmoySQlgLipE0q+g5XwIhAJGARgRoFTKceIs9p8L6sAmP02xrMAPuw6Nwyge8rPQE"}]},"_npmUser":{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"},"directories":{},"maintainers":[{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.3.2_1784651647322_0.7266951587690029"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-20T16:36:04.964Z","modified":"2026-07-21T16:34:07.661Z","0.1.0":"2026-07-20T16:36:05.304Z","0.2.0":"2026-07-20T21:24:15.959Z","0.3.0":"2026-07-21T13:45:39.904Z","0.3.1":"2026-07-21T15:13:31.648Z","0.3.2":"2026-07-21T16:34:07.502Z"},"bugs":{"url":"https://github.com/Adalink-ai/adalink-integration-kit/issues"},"license":"MIT","homepage":"https://github.com/Adalink-ai/adalink-integration-kit#readme","repository":{"type":"git","url":"git+https://github.com/Adalink-ai/adalink-integration-kit.git","directory":"packages/sdk"},"description":"SDK Node/TypeScript oficial para integração com a plataforma Adaflow","maintainers":[{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"}],"readme":"# @adaflow/sdk\n\nSDK Node/TypeScript oficial para integração com a plataforma Adaflow.\nClient tipado sobre o API Gateway: chat OpenAI-compatible (genérico e\nespecialista), agentes autônomos, repositórios de conhecimento, SSO handoff e\nbilling. Zero dependências de runtime — usa `fetch` nativo (Node ≥ 18.17 ou\nbrowser).\n\n> Contexto completo das superfícies: [guia de apps integrados](../../docs/INTEGRATED-APPS-GUIDE.md)\n> e [contrato OpenAI-compatible](../../docs/OPENAI-COMPAT.md).\n\n## Instalação\n\n```bash\npnpm add @adaflow/sdk\n```\n\n## Credenciais\n\nRegra da plataforma: **JWT do usuário logado sempre que há usuário no fluxo**\n(a ação fica auditada no usuário real); app token (`x-ada-token`) só para\nserver-to-server.\n\n```ts\nimport { AdaflowClient } from '@adaflow/sdk';\n\n// Usuário logado (preferido) — JWT obtido via SSO handoff.\n// Aceita função (sincrona/assíncrona) para renovação a cada request.\nconst client = new AdaflowClient({\n  jwt: () => sessionStorage.getItem('adaflow:jwt')!,\n});\n\n// Server-to-server — app token, NUNCA exposto no browser.\nconst s2s = new AdaflowClient({ appToken: process.env.ADAFLOW_APP_TOKEN! });\n```\n\n`baseUrl` resolve nesta ordem: valor explícito → env **`ADAFLOW_BASE_URL`** →\ndefault de produção (`https://adalink-api-gateway.onrender.com`). Clientes\nprivate label com API própria só setam a env — zero mudança de código. O app\ntoken também pode vir do ambiente (**`ADAFLOW_APP_TOKEN`**, alias `ADA_TOKEN`),\npermitindo `new AdaflowClient()` sem argumentos em integrações server-to-server:\n\n```ts\n// ADAFLOW_BASE_URL=https://api.cliente.com  ADAFLOW_APP_TOKEN=ada_...\nconst client = new AdaflowClient(); // pronto — private label, sem usuário logado\n```\n\n## SSO handoff (browser)\n\nO Adaflow é o Identity Provider. O app redireciona para o handoff e recebe o\nJWT no fragment `#sso_token=` (não vai ao servidor nem vaza por Referer):\n\n```ts\nimport { buildHandoffUrl, consumeSsoToken } from '@adaflow/sdk';\n\n// 1. Redireciona para o Adaflow\nlocation.href = buildHandoffUrl('https://app.adalink.ai', 'https://meuapp.com/sso/callback');\n\n// 2. Na página de callback: extrai o token e limpa a URL\nconst jwt = consumeSsoToken();\nif (jwt) sessionStorage.setItem('adaflow:jwt', jwt);\n```\n\nQuando o JWT expira, `AdaflowApiError.isAuthError` fica `true` — refaça o\nhandoff (com sessão ativa no Adaflow o redirect volta imediatamente).\n\n## Chat (genérico e especialista)\n\n```ts\n// Genérico: <gatewayId> do catálogo\nconst { content } = await client.chat.create({\n  model: 'anthropic/claude-haiku-4.5',\n  messages: [{ role: 'user', content: 'Classifique: \"adorei o produto\"' }],\n});\n\n// Especialista: assistant:<uuid> — RAG, skills, conectores e governança valem\nconst result = await client.chat.create({\n  model: 'assistant:0198c9a1-...',\n  messages: [{ role: 'user', content: 'Resuma o contrato X.' }],\n});\n\n// Histórico server-side: persista o chatId e envie só a mensagem nova\nconst followUp = await client.chat.create({\n  model: 'assistant:0198c9a1-...',\n  chatId: result.chatId,\n  messages: [{ role: 'user', content: 'E os riscos?' }],\n});\n\n// Streaming\nconst stream = await client.chat.stream({ model: 'anthropic/claude-haiku-4.5', messages });\nfor await (const chunk of stream) {\n  process.stdout.write(chunk.choices[0]?.delta.content ?? '');\n}\n\n// Catálogo de modelos\nconst models = await client.chat.models();\n```\n\n## Agentes autônomos\n\n```ts\nconst { data } = await client.agents.list({ search: 'relatório' });\n\n// Síncrono\nconst exec = await client.agents.execute(agentId, {\n  input: 'Gere o relatório semanal',\n  threadId: 'meu-app:user-42', // reenvie para manter contexto\n});\n\n// Streaming SSE\nfor await (const event of client.agents.stream(agentId, { input: '...' })) {\n  console.log(event);\n}\n```\n\n## Repositórios de conhecimento\n\n```ts\nconst repo = await client.repositories.create({ name: 'Contratos 2026' });\n\n// Upload orquestrado: presign → PUT no storage → confirm (os 3 passos em um)\nconst { fileId } = await client.repositories.uploadDocument(repo.id, {\n  fileName: 'contrato.pdf',\n  contentType: 'application/pdf',\n  data: await readFile('./contrato.pdf'),\n});\n\n// Vincula ao especialista — arquivos passam a compor o RAG\nawait client.specialists.linkRepository(specialistId, repo.id);\n```\n\nO processamento (OCR/embedding) é assíncrono após o `confirm`; acompanhe via\n`client.repositories.listFiles(repo.id)`.\n\n## Governança / Trilha de Auditoria\n\nRegistre os passos do usuário logado — eles aparecem no módulo Governança do\nAdaflow identificados como `App: <nome>`:\n\n```ts\n// Browser: tracker buffered (fail-soft, flush automático + keepalive no unload)\nconst tracker = client.governance.tracker({ app: 'meu-app' });\ntracker.track({\n  action: 'app.contrato.aprovado',   // namespace obrigatório: app.<dominio>.<verbo>\n  resource: 'Contrato',\n  actionLabel: 'Contrato aprovado',  // label pt-BR exibido na Governança\n});\n\n// Server-side / evento crítico: imediato e awaitável (idempotente por eventId)\nawait client.governance.track(\n  { action: 'app.proposta.enviada', resource: 'Proposta', eventId: proposta.id },\n  { app: 'meu-app' },\n);\n\n// Sessão automática (browser): heartbeat 60s + session-end no fechamento\nimport { startSessionTracking } from '@adaflow/sdk';\nconst handle = startSessionTracking(client);\nhandle.pageView('/contratos');   // no route-change do SPA\nawait handle.stop();             // no logout/cleanup\n\n// Leitura (exige permissão platform.audit.read — 403 → err.isPermissionError)\nconst page = await client.governance.listLogs({ sourceService: 'app:meu-app' });\n```\n\nNunca coloque PII/segredos em `metadata` (cap 4KB). No browser, aponte o\n`baseUrl` para um proxy do seu app (ver template NextJS) — sem CORS.\n\n## Tratamento de erros\n\nToda resposta não-2xx vira `AdaflowApiError`, normalizando os dois envelopes\nde erro da plataforma (OpenAI e gateway):\n\n```ts\nimport { AdaflowApiError } from '@adaflow/sdk';\n\ntry {\n  await client.chat.create(params);\n} catch (err) {\n  if (err instanceof AdaflowApiError) {\n    if (err.isAuthError) refazerHandoff();          // 401 — JWT expirado\n    else if (err.isInsufficientQuota) avisarSaldo(); // condição do tenant, não é bug\n    else if (err.isRateLimit) retryComBackoff();     // 429\n    else reportar(err.status, err.code, err.message);\n  }\n}\n```\n\n## Desenvolvimento\n\n```bash\npnpm typecheck   # tsc --noEmit\npnpm test        # vitest\npnpm build       # tsup — ESM + CJS + d.ts\n```\n","readmeFilename":"README.md"}