{"_id":"@alguna/sdk","_rev":"3-d1d2a4a301b235f7554f61b8b028dac1","name":"@alguna/sdk","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@alguna/sdk","version":"0.1.0","keywords":["alguna","billing","subscriptions","invoicing","payments"],"author":{"name":"Alguna"},"license":"UNLICENSED","_id":"@alguna/sdk@0.1.0","maintainers":[{"name":"joluna","email":"joe-r@live.co.uk"},{"name":"reecepm","email":"reecemartin1425@gmail.com"}],"homepage":"https://docs.alguna.io","bugs":{"url":"https://github.com/alguna-io/monorepo/issues"},"dist":{"shasum":"0733d673e8caa0c3dad01880c7e42ba9778dc0d6","tarball":"https://registry.npmjs.org/@alguna/sdk/-/sdk-0.1.0.tgz","fileCount":8,"integrity":"sha512-M5MLZveqIR32A933kIV7Cfm2iHOnQQ4jUood/1PClgaYp0KaWAdfM672HtuZ2Ir2pqyq2Y5j0PMvVni/pDdpkg==","signatures":[{"sig":"MEUCIA0Y3Yz/ypV3M0p0Ijs7DSf7j+z0cHfZSAH1thGrya2uAiEAm6lFnxeU3lIpiDvwb4hSy9nB5fipeft+bJ6e1bfisPc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1306858},"main":"./dist/index.js","_from":"file:alguna-sdk-0.1.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"lint":"biome check .","test":"vitest run","build":"tsup","clean":"rm -rf .turbo node_modules dist","generate":"tsx scripts/generate.ts","lint:fix":"biome check --fix .","test:watch":"vitest","type-check":"tsc --noEmit"},"_npmUser":{"name":"joluna","email":"joe-r@live.co.uk"},"_resolved":"/tmp/29a68ba138773efb2c537ce3462e2ea7/alguna-sdk-0.1.0.tgz","_integrity":"sha512-M5MLZveqIR32A933kIV7Cfm2iHOnQQ4jUood/1PClgaYp0KaWAdfM672HtuZ2Ir2pqyq2Y5j0PMvVni/pDdpkg==","repository":{"url":"git+https://github.com/alguna-io/monorepo.git","type":"git","directory":"typescript/packages/sdk"},"_npmVersion":"10.9.8","description":"Official TypeScript SDK for the Alguna Public API","directories":{},"sideEffects":false,"_nodeVersion":"22.23.1","dependencies":{"axios":"^1.7.9"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","tsup":"^8.3.5","vitest":"^4.0.18","typescript":"^7.0.2","@hey-api/openapi-ts":"^0.95.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1786437647025_0.9775534316877248","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@alguna/sdk","version":"0.2.0","keywords":["alguna","billing","subscriptions","invoicing","payments"],"author":{"name":"Alguna"},"license":"UNLICENSED","_id":"@alguna/sdk@0.2.0","maintainers":[{"name":"joluna","email":"joe-r@live.co.uk"},{"name":"reecepm","email":"reecemartin1425@gmail.com"}],"homepage":"https://docs.alguna.io","bugs":{"url":"https://github.com/alguna-io/monorepo/issues"},"dist":{"shasum":"0e26ea109a2f9cca042fe14f73617369b2bcd574","tarball":"https://registry.npmjs.org/@alguna/sdk/-/sdk-0.2.0.tgz","fileCount":8,"integrity":"sha512-mCIxFavFSO4CM6zJnGFHQcYlW8K0H6YSKEbWRbNjwSjRY7WGIfaDtGlzS6cfp3U8Yf/clf6vWgZS48xjRlU0Bw==","signatures":[{"sig":"MEUCIEFv96+DINb1TeHfPq1/mWz1mF8gi6cqrhUcSxFc+pzuAiEAyjE/C/jYA8xeOiM3/89oxPob3hhCjLnEjtnoyGyM1o0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1478356},"main":"./dist/index.js","_from":"file:alguna-sdk-0.2.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"lint":"biome check .","test":"vitest run","build":"tsup","clean":"rm -rf .turbo node_modules dist","generate":"tsx scripts/generate.ts","lint:fix":"biome check --fix .","test:watch":"vitest","type-check":"tsc --noEmit"},"_npmUser":{"name":"joluna","email":"joe-r@live.co.uk"},"_resolved":"/tmp/6f3ab752a2ac0daac34b5da593f88f49/alguna-sdk-0.2.0.tgz","_integrity":"sha512-mCIxFavFSO4CM6zJnGFHQcYlW8K0H6YSKEbWRbNjwSjRY7WGIfaDtGlzS6cfp3U8Yf/clf6vWgZS48xjRlU0Bw==","repository":{"url":"git+https://github.com/alguna-io/monorepo.git","type":"git","directory":"typescript/packages/sdk"},"_npmVersion":"10.9.8","description":"Official TypeScript SDK for the Alguna Public API","directories":{},"sideEffects":false,"_nodeVersion":"22.23.2","dependencies":{"axios":"^1.7.9"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","tsup":"^8.3.5","vitest":"^4.0.18","typescript":"^7.0.2","@hey-api/openapi-ts":"^0.95.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.2.0_1788273261786_0.8849640952568041","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"_id":"@alguna/sdk@0.3.0","bugs":{"email":"support@alguna.io"},"dist":{"shasum":"cc0a862ca08ef3ad11ed5ddb09ea8cc24f982a0a","tarball":"https://registry.npmjs.org/@alguna/sdk/-/sdk-0.3.0.tgz","fileCount":8,"integrity":"sha512-S+ygNtLC8bVqhDUbF+Dyv8bRtrwueVdQCSzeS8MuBg8MPsNs3VVItOXISMC3JDdIMkPU6cjxCA5KbZlTJRF+cg==","signatures":[{"sig":"MEUCIQCyIcV13mEg9vDc8H9bCXnFsa/IFehW5S+VH7j0L78WDwIgFz29ZRpPNHkeuBET4p5lvukxI2Xcs5dJ4ExEgh79xqQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDg+ewpgbukbADM2zqeLaaV6pr49ZtbePxYXBk06vW24QIgZTrkg2W6CowIB/JAUPWYdbFj/tDzka4az8xRrMMrfdU="}],"unpackedSize":1506069},"main":"./dist/index.js","name":"@alguna/sdk","_from":"file:alguna-sdk-0.3.0.tgz","types":"./dist/index.d.ts","author":{"name":"Alguna"},"module":"./dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"license":"UNLICENSED","scripts":{"lint":"biome check .","test":"vitest run","build":"tsup","clean":"rm -rf .turbo node_modules dist","generate":"tsx scripts/generate.ts","lint:fix":"biome check --fix .","test:watch":"vitest","type-check":"tsc --noEmit"},"version":"0.3.0","_npmUser":{"name":"joluna","email":"joe-r@live.co.uk"},"homepage":"https://alguna.com/docs","keywords":["alguna","billing","subscriptions","invoicing","payments"],"_resolved":"/tmp/b44eea969ee9d161f6a7c47ec9048652/alguna-sdk-0.3.0.tgz","_integrity":"sha512-S+ygNtLC8bVqhDUbF+Dyv8bRtrwueVdQCSzeS8MuBg8MPsNs3VVItOXISMC3JDdIMkPU6cjxCA5KbZlTJRF+cg==","_npmVersion":"10.9.8","description":"Official TypeScript SDK for the Alguna Public API","directories":{},"maintainers":[{"name":"joluna","email":"joe-r@live.co.uk"},{"name":"reecepm","email":"reecemartin1425@gmail.com"}],"sideEffects":false,"_nodeVersion":"22.23.2","dependencies":{"axios":"^1.7.9"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","tsup":"^8.3.5","vitest":"^4.0.18","typescript":"^7.0.2","@hey-api/openapi-ts":"^0.95.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.3.0_1789488083355_0.318948439613417"}}},"time":{"created":"2026-08-11T08:40:46.827Z","modified":"2026-09-15T16:01:23.621Z","0.1.0":"2026-08-11T08:40:47.188Z","0.2.0":"2026-09-01T14:34:21.986Z","0.3.0":"2026-09-15T16:01:23.456Z"},"bugs":{"email":"support@alguna.io"},"author":{"name":"Alguna"},"license":"UNLICENSED","homepage":"https://alguna.com/docs","keywords":["alguna","billing","subscriptions","invoicing","payments"],"description":"Official TypeScript SDK for the Alguna Public API","maintainers":[{"name":"joluna","email":"joe-r@live.co.uk"},{"name":"reecepm","email":"reecemartin1425@gmail.com"}],"readme":"# @alguna/sdk\n\nOfficial TypeScript SDK for the [Alguna Public API](https://alguna.com/docs) —\nusage-based billing, subscriptions, invoicing, and payment links.\n\nThe client is generated from the platform's versioned OpenAPI spec\n(`platform/services/api/specs/<version>.json`), with thin hand-written resource\nwrappers on top for ergonomics.\n\n## Requirements\n\n- Node.js 18 or later\n- An Alguna API key, created in the dashboard under **Settings → API Keys**\n\nAPI keys are secret. Use the SDK server-side only — never in browser code.\n\n## Installation\n\n```bash\nnpm install @alguna/sdk\n# or\npnpm add @alguna/sdk\n```\n\n## Quick start\n\n```typescript\nimport { Alguna } from \"@alguna/sdk\";\n\nconst alguna = new Alguna({\n  apiKey: process.env.ALGUNA_API_KEY,\n  apiVersion: \"2026-04-01\", // required — pin the version you integrate against\n});\n\n// 1. Create a customer\nconst customer = await alguna.customers.create({\n  name: \"Acme Corp\",\n  currency: \"USD\",\n  contacts: [{ email: \"billing@acme.com\", is_primary: true }],\n});\n\n// 2. Start a subscription\nconst product = await alguna.products.create({\n  name: \"Platform Fee\",\n  fee_type: \"fixed\",\n  billing_frequency: \"recurring\",\n  payment_terms: \"advance\",\n});\nconst subscription = await alguna.subscriptions.create({\n  customer_id: customer.id,\n  currency: \"USD\",\n  items: [\n    {\n      product_id: product.id,\n      price: {\n        type: \"fixed\",\n        fee_type: \"fixed\",\n        billing_direction: \"advance\",\n        billing_frequency: \"recurring\",\n        billing_interval: \"monthly\",\n        fixed_pricing_model: { price_per_unit: \"99.00\", units: 1 },\n      },\n    },\n  ],\n  contract: { period_type: \"fixed\", duration_months: 12, start_date: \"2026-07-01\" },\n  auto_activate: true,\n});\n\n// 3. Issue an invoice\nconst invoice = await alguna.invoices.create({\n  customer_id: customer.id,\n  currency: \"USD\",\n  line_items: [{ description: \"Onboarding\", unit_price: \"500.00\", quantity: \"1\" }],\n});\n\n// 4. Generate a payment link (hosted customer portal session)\nconst session = await alguna.portal.createSession({ customer_id: customer.id });\nconsole.log(session.url); // share with the customer; expires after 1 hour\n```\n\n## Resources\n\nThe SDK covers **every** public API operation — one field per resource\n(`alguna.customers`, `alguna.subscriptions`, `alguna.invoices`,\n`alguna.portal`, `alguna.wallets`, `alguna.insights`, …). The resource layer\nis generated: `resources.config.ts` maps each SDK method to a spec\n`operationId`, and `pnpm generate` emits `src/resources/*.gen.ts` from it,\nderiving signatures (path params, body, query) from the spec. Generation\nfails if the map misses an operation, so the SDK cannot fall out of parity\nwith the API.\n\nRequest/response types are generated from the spec and exported from the\npackage root (e.g. `CreateCustomerRequest`, `InvoiceResponse`).\n\nList endpoints accept `limit`, `offset`, `sort`, and resource-specific filters,\nand return the page plus pagination metadata:\n\n```typescript\nconst { data, pagination } = await alguna.customers.list({ limit: 50, offset: 0 });\n// data: CustomerResponse[]\n// pagination: { per_page, total_pages }\n```\n\n## Idempotency\n\nMutating methods accept an optional trailing `options` argument. Pass\n`idempotencyKey` to make retries safe — the API returns the original result\ninstead of repeating the action:\n\n```typescript\nawait alguna.subscriptions.create(\n  { customer_id: customer.id, plan_id: \"plan_abc123\", auto_activate: true },\n  { idempotencyKey: \"order_1234\" },\n);\n```\n\n## Configuration\n\n```typescript\nconst alguna = new Alguna({\n  apiKey: \"key_id.key_secret\",           // required — created in the dashboard\n  apiVersion: \"2026-04-01\",              // required — the Alguna-Version header\n  baseUrl: \"http://localhost:4000/beta\", // optional — defaults to https://api.alguna.io/beta\n  timeout: 30_000,                       // optional — ms\n});\n```\n\nEvery request carries the required `Alguna-Version` header. `apiVersion` is a\nrequired input: pin the version your integration is written against, so\nupgrading the SDK package never silently moves you to a different API\nversion.\n\n## Error handling\n\nFailed requests throw typed errors, all extending `AlgunaError`:\n\n```typescript\nimport { NotFoundError, RateLimitError, ValidationError } from \"@alguna/sdk\";\n\ntry {\n  await alguna.customers.get(\"nope\");\n} catch (error) {\n  if (error instanceof NotFoundError) {\n    // error.message, error.statusCode, error.requestId\n  } else if (error instanceof RateLimitError) {\n    // error.retryAfter — seconds to wait before retrying\n  } else if (error instanceof ValidationError) {\n    // error.fields — per-field validation messages\n  }\n}\n```\n\n| Error                 | Status | Extra fields              |\n| --------------------- | ------ | ------------------------- |\n| `ValidationError`     | 400    | `fields`                  |\n| `AuthenticationError` | 401    |                           |\n| `NotFoundError`       | 404    | `resource`                |\n| `RateLimitError`      | 429    | `retryAfter`              |\n| `ApiError`            | other  |                           |\n\nAll errors expose `statusCode`, `code`, and `requestId` — include the\n`requestId` when contacting support about a failed call.\n\n## Regenerating the client\n\nWhen the public API changes:\n\n```bash\n# 1. In the platform: regenerate the versioned spec\ntask api:specs\n\n# 2. Here: sync the spec and regenerate src/client/\npnpm generate            # latest version, or: pnpm generate 2026-04-01\npnpm build && pnpm test\n```\n\n`scripts/generate.ts` copies the spec into `openapi/`, strips the\nper-operation `Alguna-Version` header parameter (the SDK sends it globally),\nruns `@hey-api/openapi-ts`, and emits the resource layer from\n`resources.config.ts`. Everything under `src/client/` and every\n`src/resources/*.gen.ts` file is generated — don't edit them by hand. If the\nAPI gained endpoints, generation fails with the list of unmapped operations;\nname them in `resources.config.ts` and re-run.\n\n## Development\n\n```bash\npnpm build        # bundle to dist/ (tsup: cjs + esm + d.ts)\npnpm test         # vitest\npnpm lint         # biome\npnpm type-check\n```\n\n## Support\n\n- Documentation: [alguna.com/docs](https://alguna.com/docs)\n- Issues: contact support@alguna.io with the failing `requestId`\n","readmeFilename":"README.md"}