{"_id":"@axobot/mppx","name":"@axobot/mppx","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@axobot/mppx","version":"1.0.0","description":"Lightning-native Machine Payments Protocol SDK with pluggable payment adapters","license":"MIT","repository":{"type":"git","url":"git+https://github.com/zbdpay/axobot-mppx.git"},"bugs":{"url":"https://github.com/zbdpay/axobot-mppx/issues"},"homepage":"https://github.com/zbdpay/axobot-mppx#readme","keywords":["axo","axobot","mpp","mppx","lightning"],"type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"publishConfig":{"access":"public","provenance":true},"engines":{"node":">=22"},"scripts":{"build":"tsc -p tsconfig.json","lint":"npm run typecheck","release":"semantic-release","release:dry-run":"SEMANTIC_RELEASE_DRY_RUN=true semantic-release --dry-run --no-ci","test":"npm run build && node --test test/**/*.test.js","typecheck":"tsc --noEmit"},"devDependencies":{"@semantic-release/changelog":"^6.0.3","@semantic-release/commit-analyzer":"^13.0.1","@semantic-release/git":"^10.0.1","@semantic-release/github":"^11.0.6","@semantic-release/npm":"^13.1.4","@semantic-release/release-notes-generator":"^14.1.0","@types/node":"^24.3.0","conventional-changelog-conventionalcommits":"^8.0.0","semantic-release":"^25.0.3","typescript":"^5.9.2"},"gitHead":"c120052353f5bb3b71ee059f67e2f93427691c89","_id":"@axobot/mppx@1.0.0","_nodeVersion":"22.22.1","_npmVersion":"11.12.0","dist":{"integrity":"sha512-3RyGBhaHHAsIfaeO2p9j/on2Guj1NKE3O3mcAsXQJ3oL+EM3VG19J1zfM5BKih10dNBDeHSj8RIUh8KzdX1ngQ==","shasum":"6823b5b4f1aea08187d4e0038737b80ac3bcf1b3","tarball":"https://registry.npmjs.org/@axobot/mppx/-/mppx-1.0.0.tgz","fileCount":20,"unpackedSize":36697,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@axobot%2fmppx@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDE+qA6uwIVX0m9eM80INxG+vRz8QV9vgZdeg4jpgNFogIgBBoE1da0sz9C2qxkLE4sb8EsmNGlbhNE6T0UP5TZ5EU="}]},"_npmUser":{"name":"andrerfneves","email":"andrerfneves@protonmail.com"},"directories":{},"maintainers":[{"name":"andrerfneves","email":"andrerfneves@protonmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mppx_1.0.0_1774200282455_0.1191163073953605"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-22T17:24:42.319Z","1.0.0":"2026-03-22T17:24:42.606Z","modified":"2026-03-22T17:24:43.107Z"},"maintainers":[{"name":"andrerfneves","email":"andrerfneves@protonmail.com"}],"description":"Lightning-native Machine Payments Protocol SDK with pluggable payment adapters","homepage":"https://github.com/zbdpay/axobot-mppx#readme","keywords":["axo","axobot","mpp","mppx","lightning"],"repository":{"type":"git","url":"git+https://github.com/zbdpay/axobot-mppx.git"},"bugs":{"url":"https://github.com/zbdpay/axobot-mppx/issues"},"license":"MIT","readme":"# `@axobot/mppx`\n\nLightning-native Machine Payments Protocol SDK.\n\n`@axobot/mppx` is an Axo-maintained implementation of MPP that keeps the\nprotocol public and portable while treating Lightning as a first-class\npayment method.\n\nIt is intended to:\n\n- follow the MPP and HTTP Payment Authentication specifications\n- model Lightning `charge` and `session` flows directly\n- stay provider-agnostic at the adapter boundary\n- ship a ZBD-backed adapter first\n- remain useful outside Axo instead of becoming an Axo-only protocol fork\n\n## Why This Package Exists\n\nMost public MPP implementation gravity is currently around Tempo/Spark.\nAxo wants a Lightning-native implementation where:\n\n- BOLT11 invoices and preimages are first-class primitives\n- session deposits, top-ups, and refunds work on Lightning\n- the payment adapter can be swapped later for `lnd`, `cln`, or others\n- Axo can use the package without owning a proprietary wire protocol\n\n## Protocol Compatibility\n\nThe official Lightning MPP drafts already define:\n\n- `charge` via BOLT11 invoice + preimage proof\n- `session` via deposit invoice + preimage bearer token + top-up invoices + refund on close\n\nPrimary references:\n\n- [mpp.dev](https://mpp.dev/)\n- [wevm/mppx](https://github.com/wevm/mppx)\n- [tempoxyz/mpp-specs](https://github.com/tempoxyz/mpp-specs)\n- [`draft-lightning-charge-00`](https://raw.githubusercontent.com/tempoxyz/mpp-specs/main/specs/methods/lightning/draft-lightning-charge-00.md)\n- [`draft-lightning-session-00`](https://raw.githubusercontent.com/tempoxyz/mpp-specs/main/specs/methods/lightning/draft-lightning-session-00.md)\n\n## Current Package Surface\n\nCurrent implementation includes:\n\n- Payment-auth challenge parsing\n- canonical request and credential encoding helpers\n- Lightning `charge` credential builders\n- Lightning `session` open / bearer / topUp / close credential builders\n- high-level helpers for paying charge challenges and opening/top-up/closing sessions\n- BOLT11 payment hash extraction\n- first ZBD Lightning adapter\n- Axo extension support for `returnLightningAddress`\n- refund helper that prefers `returnInvoice` and falls back to `returnLightningAddress`\n\n## Package Shape\n\nThe package is currently organized into:\n\n1. `core`\n   - Payment-auth parsing and canonical encoding\n   - protocol-safe challenge and credential types\n2. `lightning`\n   - Lightning charge/session helpers\n   - invoice/preimage session primitives\n3. `adapters`\n   - ZBD adapter first\n   - future `lnd` / `cln` adapters later\n\n## Axo Extension: `returnLightningAddress`\n\nThe current Lightning session draft uses `returnInvoice` as the native refund\nfield. `@axobot/mppx` also supports `returnLightningAddress` as an Axo\nextension:\n\n- if both are present, `returnInvoice` wins\n- if only `returnLightningAddress` is present, refund falls back to the adapter\n- this keeps the package ergonomic without throwing away spec-native behavior\n\n## Example\n\n```ts\nimport {\n  createZbdLightningAdapter,\n  openLightningSession,\n  createLightningSessionBearerAuthorization,\n} from \"@axobot/mppx\";\n\nconst adapter = createZbdLightningAdapter({\n  apiKey: process.env.ZBD_API_KEY!,\n});\n\nconst session = await openLightningSession({\n  challenge,\n  adapter,\n  returnLightningAddress: \"agent@axo.bot\",\n});\n\nconst authorization = createLightningSessionBearerAuthorization({\n  challenge: bearerChallenge,\n  session,\n});\n```\n\n## Scripts\n\n```bash\nnpm run build\nnpm test\nnpm run typecheck\n```\n\n## Status\n\nImplemented:\n\n- protocol primitives\n- Lightning charge/session credential helpers\n- first ZBD adapter\n- initial high-level client helpers\n\nStill pending:\n\n- richer session manager state model\n- fetch/client integration\n- server middleware integration\n- live validation of zero-amount invoice behavior against ZBD\n- non-ZBD Lightning adapters\n","readmeFilename":"README.md","_rev":"1-7d73c77ec2915199a3cc8ea6b7711c0d"}