{"_id":"@accalia.io/kora-client","name":"@accalia.io/kora-client","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@accalia.io/kora-client","version":"0.1.0","private":false,"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","scripts":{"build":"tsc -p tsconfig.json","typecheck":"tsc --noEmit -p tsconfig.json"},"devDependencies":{"@types/node":"^22.9.0","typescript":"^5.6.3"},"_id":"@accalia.io/kora-client@0.1.0","gitHead":"9e45ccab19459691e0041d023c353395c1f72165","description":"SDK Node.js oficial da API do Kora — plataforma de billing-as-a-service multitenant (Kadi, Qiazap e futuros produtos).","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-DYrk6q9FnXd/0Q8AshH/hO+0D7gXCGU8oI66EyOnWEVgEi3q5kuLCF/FU4fOHao7CUS2qHSVQBMgmcWhlGxNYw==","shasum":"0cd87d0943ea9a159c6771e8fc8d7d4a98a4df80","tarball":"https://registry.npmjs.org/@accalia.io/kora-client/-/kora-client-0.1.0.tgz","fileCount":11,"unpackedSize":19118,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFWOcOos2zvf5GuFte/xH+zO4oW1y4CfYsCQeopcx9m5AiEAl1TFB5Wa5HL1ZH8FMTX49F2QuBrZl9NOnIumeLZmmcA="}]},"_npmUser":{"name":"ruandersonvieira","email":"ruanderson.vieira@gmail.com"},"directories":{},"maintainers":[{"name":"ruandersonvieira","email":"ruanderson.vieira@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/kora-client_0.1.0_1786236560353_0.015259041418622887"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-09T00:49:20.232Z","0.1.0":"2026-08-09T00:49:20.500Z","modified":"2026-08-09T00:49:20.688Z"},"maintainers":[{"name":"ruandersonvieira","email":"ruanderson.vieira@gmail.com"}],"description":"SDK Node.js oficial da API do Kora — plataforma de billing-as-a-service multitenant (Kadi, Qiazap e futuros produtos).","readme":"# @accalia.io/kora-client\n\nSDK Node.js oficial da API do Kora — plataforma de billing-as-a-service multitenant (Kadi, Qiazap e futuros produtos).\n\nParte da plataforma Kora, dividida em 3 repositórios:\n\n- [`kora-api`](../kora-api) — Fastify + Prisma + PostgreSQL, API + OpenAPI docs + worker de webhooks.\n- [`kora-web`](../kora-web) — React + Vite + Twind, painel administrativo.\n- **kora-node** (este repo) — SDK Node.js (`@accalia.io/kora-client`) para integrações externas.\n\nZero dependências de runtime. Wrapper fino sobre 3 recursos protegidos por API token: `plans`, `subscriptions`, `customers` — CRUD completo em cada um.\n\n## Instalação\n\n```bash\nnpm install @accalia.io/kora-client\n```\n\n## Como conectar\n\n1. **Tenant existente** — todo API token pertence a um tenant (criado por um master-admin via painel `/master` ou `POST /v1/master/tenants`). Se você já tem acesso ao painel do seu tenant, pule para o passo 2.\n2. Logue no painel Kora (`kora-web`, ex. `https://app.kora.example.com`) e vá em **`/app/api-tokens`** → **Novo token**. Dê um nome (ex. `\"Integração Node - produção\"`) e confirme.\n3. O valor completo do token (`kora_...`) só aparece **uma vez**, na resposta da criação — copie e guarde num secret manager ou `.env`, nunca em código versionado.\n\n```bash\n# .env do seu app\nKORA_API_TOKEN=kora_xxxxxxxxxxxxxxxxxxxx\nKORA_BASE_URL=https://api.kora.example.com   # http://localhost:3334 em dev\n```\n\n4. Instancie o client uma vez e reuse-o (ele não guarda estado de conexão, é só um wrapper fino sobre `fetch`):\n\n```ts\n// kora.ts\nimport { KoraClient } from '@accalia.io/kora-client';\n\nexport const kora = new KoraClient({\n  apiToken: process.env.KORA_API_TOKEN!,\n  baseUrl: process.env.KORA_BASE_URL, // opcional — default http://localhost:3334\n});\n```\n\n```ts\n// em qualquer outro arquivo\nimport { kora } from './kora.js';\n\nconst { items: plans } = await kora.plans.list({ status: 'ACTIVE' });\n```\n\nUm `403`/`401` (`KoraApiError`) nessa chamada normalmente indica token errado, revogado (status `INACTIVE`) ou `baseUrl` apontando pro ambiente errado (sandbox vs. produção usam tenants/tokens diferentes).\n\n## Uso\n\n```ts\nimport { KoraClient } from '@accalia.io/kora-client';\n\nconst kora = new KoraClient({\n  apiToken: 'kora_...',\n  baseUrl: 'https://api.kora.example.com', // sem /v1 — o SDK já prefixa\n});\n\nconst customer = await kora.customers.create({ name: 'Ana Silva', email: 'ana@example.com' });\n\nconst plan = await kora.plans.create({\n  name: 'Pro',\n  prices: [{ interval: 'MONTH', amount: 49.9 }],\n});\n\nconst subscription = await kora.subscriptions.create({\n  customerId: customer.id,\n  planId: plan.id,\n  items: [{ type: 'PLAN', planId: plan.id, planPriceId: plan.prices![0].id, interval: 'MONTH' }],\n});\n\nawait kora.subscriptions.pause(subscription.id);\nawait kora.subscriptions.resume(subscription.id);\nawait kora.subscriptions.cancel(subscription.id);\n```\n\nListagens retornam `{ items, total, page, pageSize }`:\n\n```ts\nconst { items } = await kora.subscriptions.list({ customerId: customer.id });\n```\n\nUm token é criado pelo painel do Kora (`/app/api-tokens`) ou via `POST /v1/api-tokens` na API — o valor completo só aparece na resposta da criação. Todo token é tenant-scoped (sem escopos ou restrição por categoria): dá acesso total aos recursos deste SDK dentro do tenant que o gerou.\n\n## Erros\n\nToda resposta de erro da API é lançada como `KoraApiError`:\n\n```ts\nimport { KoraApiError } from '@accalia.io/kora-client';\n\ntry {\n  await kora.customers.get('id-invalido');\n} catch (err) {\n  if (err instanceof KoraApiError) {\n    console.error(err.status, err.message);\n  }\n}\n```\n\n## Desenvolvimento\n\n```bash\nnpm install\nnpm run build       # compila para dist/\nnpm run typecheck   # apenas checagem de tipos\n```\n\n## Histórico\n\nEste repo nasceu de um split do monorepo original do Kora (`git filter-repo`, histórico de commits preservado apenas para os arquivos deste app).\n","readmeFilename":"README.md","_rev":"1-b940c61920a071f7e82b5c576d40be61"}