{"_id":"@011bq/payments-sdk","name":"@011bq/payments-sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@011bq/payments-sdk","version":"0.1.0","description":"Node/Next.js SDK for Bytequests payments API (Phase 1: one-time payments)","license":"ISC","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","clean":"rm -rf dist"},"engines":{"node":">=18"},"devDependencies":{"@types/node":"^26.1.2","tsup":"^8.5.0","typescript":"^5.8.3"},"publishConfig":{"access":"public"},"_id":"@011bq/payments-sdk@0.1.0","gitHead":"589e0bd4476099095de685e6438364fe07e74da2","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-UU38O+rcKhRRPGo2bCkeUX+gbujA5rrEyVkLBs5Q7GobM1I44AJfCxr5mOPhr5mq+eGNgnIE0QcouXJKH46CxQ==","shasum":"f03adb79d8e8e92c1e038dfa05124b6abfa872ca","tarball":"https://registry.npmjs.org/@011bq/payments-sdk/-/payments-sdk-0.1.0.tgz","fileCount":8,"unpackedSize":42944,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC41CxhV/Rgh8o6GZKI3qMACFUXANw34NgOMz45PquzSAIhAPMJX6GdnYu1Dq26d2Lt4nj3+GfqXBLLJPXBOyhZXhbR"}]},"_npmUser":{"name":"piyushkothari","email":"piyush@011bq.com"},"directories":{},"maintainers":[{"name":"piyushkothari","email":"piyush@011bq.com"},{"name":"webrication","email":"shashank@bytequests.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/payments-sdk_0.1.0_1785757843482_0.4306369874605309"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-03T11:50:43.247Z","0.1.0":"2026-08-03T11:50:43.630Z","modified":"2026-08-03T11:50:43.866Z"},"maintainers":[{"name":"piyushkothari","email":"piyush@011bq.com"},{"name":"webrication","email":"shashank@bytequests.com"}],"description":"Node/Next.js SDK for Bytequests payments API (Phase 1: one-time payments)","license":"ISC","readme":"# @011bq/payments-sdk\n\nTypeScript SDK for the Bytequests payments API. **Phase 1** covers one-time payments only (create order, draft invoice, status check).\n\nUse this from **Node.js** or **Next.js server** code (Route Handlers / Server Actions). It is not intended for browser / client components — payment create calls send a `cred-id` header that should stay on the server.\n\n## Install\n\nFrom the monorepo (local path), or after publish:\n\n```bash\n# Local workspace (from an app in this repo)\nnpm install ../packages/sdk\n\n# Or after npm publish\nnpm install @011bq/payments-sdk\n```\n\nRequires **Node.js 18+** (native `fetch`).\n\n## Quick start\n\n```ts\nimport { PaymentsClient, PaymentsApiError } from \"@011bq/payments-sdk\";\n\nconst client = new PaymentsClient({\n  credId: process.env.PAYMENTS_CRED_ID!,  // merchant credential UUID\n});\n// Defaults to https://billing.011bq.app (override with `baseUrl` if needed)\n\nconst { orderID, paymentLink } = await client.payments.createOrder({\n  amount: 29.99,\n  currency: \"USD\",\n  successURL: \"https://app.example.com/success\",\n  failureURL: \"https://app.example.com/cancel\",\n  toolName: \"my-app\",\n  payerEmail: \"buyer@example.com\",\n});\n\n// Redirect the user to paymentLink\n```\n\n## Client options\n\n| Option | Required | Description |\n|--------|----------|-------------|\n| `baseUrl` | no | API origin without trailing slash. Defaults to `PAYMENTS_API_URL` (`https://billing.011bq.app`) |\n| `credId` | no* | Default `cred-id` header for create calls |\n| `fetch` | no | Custom `fetch` (tests / agents) |\n\n\\* `credId` is required on `createOrder` / `createDraftInvoice` either as the client default or via per-call `options.credId`.\n\n## Methods (Phase 1)\n\n### `payments.createOrder(body, options?)`\n\n`POST /api/v1/payment/create-order`\n\n```ts\nconst result = await client.payments.createOrder({\n  amount: 10,\n  currency: \"USD\",\n  successURL: \"https://app.example.com/ok\",\n  failureURL: \"https://app.example.com/fail\",\n  toolName: \"checkout\",\n  description: \"Pro plan\",\n  payerEmail: \"a@b.com\",\n  payerName: \"Ada\",\n});\n// { orderID, paymentGatewayID, paymentLink }\n```\n\nOverride credential per call:\n\n```ts\nawait client.payments.createOrder(body, { credId: \"other-cred-uuid\" });\n```\n\n### `payments.createDraftInvoice(body, options?)`\n\n`POST /api/v1/payment/create-draft-invoice`\n\n```ts\nconst result = await client.payments.createDraftInvoice({\n  itemName: \"Consulting\",\n  description: \"April invoice\",\n  amount: 100,\n  currency: \"USD\",\n  payerEmail: \"client@example.com\",\n  firstName: \"Ada\",\n  lastName: \"Lovelace\",\n  successURL: \"https://app.example.com/ok\",\n  failureURL: \"https://app.example.com/fail\",\n});\n```\n\n### `payments.check(orderId)`\n\n`GET /api/v1/payment/check/:orderId`\n\n```ts\nconst { status, message } = await client.payments.check(orderID);\n// status: unpaid | paid | failed | refunded | …\n```\n\n## Next.js Route Handler example\n\n```ts\n// app/api/checkout/route.ts\nimport { NextResponse } from \"next/server\";\nimport { PaymentsClient, PaymentsApiError } from \"@011bq/payments-sdk\";\n\nconst client = new PaymentsClient({\n  credId: process.env.PAYMENTS_CRED_ID!,\n});\n\nexport async function POST(request: Request) {\n  const body = await request.json();\n\n  try {\n    const { paymentLink, orderID } = await client.payments.createOrder({\n      amount: body.amount,\n      currency: body.currency ?? \"USD\",\n      successURL: body.successURL,\n      failureURL: body.failureURL,\n      toolName: \"next-storefront\",\n      payerEmail: body.email,\n    });\n\n    return NextResponse.json({ orderID, paymentLink });\n  } catch (err) {\n    if (err instanceof PaymentsApiError) {\n      return NextResponse.json(\n        { error: err.message, code: err.code },\n        { status: err.statusCode }\n      );\n    }\n    throw err;\n  }\n}\n```\n\n## Errors\n\nNon-2xx API responses throw `PaymentsApiError`:\n\n| Property | Meaning |\n|----------|---------|\n| `message` | Human-readable message from the API |\n| `statusCode` | HTTP / envelope status |\n| `code` | API error code when present |\n| `details` | Raw `error` field or response body |\n\nBoth standard (`status_code`) and validation (`statusCode`) envelopes are mapped.\n\n## Build (contributors)\n\n```bash\ncd packages/sdk\nnpm install\nnpm run build\n```\n\n## Roadmap\n\n- **Phase 1 (this package):** create order, draft invoice, payment check\n- **Later:** subscriptions, public orders, invoices, dashboard APIs\n","readmeFilename":"README.md","_rev":"1-f8a3cf7534e05c3c2875eacae7f21a3e"}