{"_id":"@aipp/satsgate-client-sdk","name":"@aipp/satsgate-client-sdk","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@aipp/satsgate-client-sdk","version":"0.2.0","description":"TypeScript SDK for satsgate — L402 paywall + prepaid payment verifications","type":"module","main":"dist/src/index.js","types":"dist/src/index.d.ts","exports":{".":{"types":"./dist/src/index.d.ts","import":"./dist/src/index.js"}},"scripts":{"build":"tsc","test":"node --test dist/tests/test_client.js","prepublishOnly":"npm run build"},"keywords":["satsgate","l402","lightning","paywall","bitcoin","sdk"],"license":"MIT","engines":{"node":">=18"},"devDependencies":{"typescript":"^5.4.0","@types/node":"^20.0.0"},"repository":{"type":"git","url":"git+https://github.com/aippdev/satsgate.git"},"_id":"@aipp/satsgate-client-sdk@0.2.0","gitHead":"31222addf3639c355a351c4709b02822078342b6","bugs":{"url":"https://github.com/aippdev/satsgate/issues"},"homepage":"https://github.com/aippdev/satsgate#readme","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-iccsVPNrj59tazTGrDUJivFxdyeIaPY4LZEd/tPB5IHg10hWEBv7ZBXLV+ianXcmucpNvLxTxEe9Tjn5OxtC+w==","shasum":"fb0e115c6276e5d6b79f2fb143985a2718ef44bd","tarball":"https://registry.npmjs.org/@aipp/satsgate-client-sdk/-/satsgate-client-sdk-0.2.0.tgz","fileCount":26,"unpackedSize":49366,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC5xBEO2YTTgG/L8w2pY5mNzSTUO35qvJjktl7WQwoh7AIgFZYcwFLuv7DdmCDkwyaj7CyUpO5cFCZtvLG9J2z1nRE="}]},"_npmUser":{"name":"aipp","email":"farukucal@gmail.com"},"directories":{},"maintainers":[{"name":"aipp","email":"farukucal@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/satsgate-client-sdk_0.2.0_1781978870189_0.7071348598306368"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-20T18:07:50.024Z","0.2.0":"2026-06-20T18:07:50.360Z","modified":"2026-06-20T18:07:50.570Z"},"maintainers":[{"name":"aipp","email":"farukucal@gmail.com"}],"description":"TypeScript SDK for satsgate — L402 paywall + prepaid payment verifications","homepage":"https://github.com/aippdev/satsgate#readme","keywords":["satsgate","l402","lightning","paywall","bitcoin","sdk"],"repository":{"type":"git","url":"git+https://github.com/aippdev/satsgate.git"},"bugs":{"url":"https://github.com/aippdev/satsgate/issues"},"license":"MIT","readme":"# @satsgate/sdk\n\nTypeScript/Node.js SDK for **satsgate** — L402 Lightning paywall + prepaid payment verifications.\n\n## Install\n\n```bash\nnpm install @satsgate/sdk\n```\n\n## Quick Start\n\n```typescript\nimport { SatsgateClient } from '@satsgate/sdk';\n\nconst sg = new SatsgateClient({ apiKey: 'sg_...' });\n\n// 1. Set your payee Lightning Address (once)\nawait sg.setPayee('yourname@yourdomain.com');\n\n// 2. Create a paywall challenge\nconst challenge = await sg.paywallChallenge({\n  resource: 'api/premium',\n  amountSats: 10,\n  memo: 'Premium access',\n});\n\n// Return HTTP 402 with challenge.invoice and challenge.macaroon to your end user.\n\n// 3. Verify payment when user retries with Authorization: L402 ...\nconst result = await sg.paywallVerify({\n  authorizationHeader: 'L402 <macaroon>:<preimage>',\n  expectedResource: 'api/premium',\n});\n\nconsole.log(result.chargedCredits); // 1 on first call, 0 on cache hits\nconsole.log(result.newBalance);    // remaining credits\n```\n\n## Configuration\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `baseUrl` | `https://api.aipp.dev` | Satsgate API base URL |\n| `apiKey` | *(required)* | Your satsgate API key (`sg_...`) |\n| `timeoutMs` | `10000` | Request timeout in milliseconds |\n\n## Cache\n\n`paywallVerify` caches verified `payment_hash` entries (LRU, max 1000) until their `valid_until` timestamp expires. Set `useCache: false` to always call the server.\n\n## Idempotency\n\nEvery `paywallVerify` call automatically sends an `Idempotency-Key` header derived from the `payment_hash`. Retries of the same payment are charged only once.\n\n## API Methods\n\n| Method | Description |\n|--------|-------------|\n| `listPlans()` | List available credit purchase plans |\n| `balance()` | Get current credit balance |\n| `getClient()` | Get client profile |\n| `setPayee(address)` | Set payee Lightning Address |\n| `paywallChallenge(opts)` | Create L402 challenge (invoice + macaroon) |\n| `paywallVerify(opts)` | Verify L402 payment and spend credits |\n| `spend(opts)` | Manual credit spend with idempotency key |\n| `ledger(opts?)` | Paginated ledger entries |\n| `usageSummary(opts?)` | Aggregated usage summary |\n| `usageDaily(opts?)` | Daily usage time series |\n| `usageForecast(opts?)` | Forecast + purchase recommendation |\n\n## Helpers\n\n```typescript\nimport { parseL402Authorization, decodeMacaroonPayload } from '@satsgate/sdk';\n\nconst [macaroon, preimage] = parseL402Authorization('L402 ...');\nconst payload = decodeMacaroonPayload(macaroon);\n```\n\n## Types\n\n```typescript\nimport type { Challenge, VerifyResult, Plan, BalanceResponse, ClientInfo,\n  LedgerResponse, UsageSummary, UsageDaily, UsageForecast } from '@satsgate/sdk';\n```\n\n## Requirements\n\n- Node.js >= 18\n- No runtime dependencies (uses native `fetch`)\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-bfb4b7a955242400b982eaf69a016d3d"}