{"_id":"@atoapayments/pay-host","name":"@atoapayments/pay-host","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@atoapayments/pay-host","version":"0.0.1","private":false,"type":"module","description":"Host Atoa checkout inside your own UI — a chat thread, a support widget, a nested iframe. Detects the frame environment it landed in, picks the tier that can actually complete a payment there, and tells you exactly why. A payment is always completable, an","keywords":["atoa","payments","embed","iframe","chat","checkout","integration","sdk","browser"],"homepage":"https://github.com/ATOAPaymentsLimited/AtoaAgenticFramework/tree/main/packages/pay-host#readme","repository":{"type":"git","url":"git+https://github.com/ATOAPaymentsLimited/AtoaAgenticFramework.git","directory":"packages/pay-host"},"bugs":{"url":"https://github.com/ATOAPaymentsLimited/AtoaAgenticFramework/issues"},"author":{"name":"Atoa and contributors"},"license":"MIT","sideEffects":false,"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","unpkg":"./dist/index.global.js","bin":{"atoa-pay-host":"bin/conformance.mjs"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./package.json":"./package.json"},"publishConfig":{"access":"public"},"scripts":{"prebuild":"node scripts/assert-embed-dist-fresh.mjs","build":"tsup","pretest":"node scripts/assert-embed-dist-fresh.mjs","test":"node --test test/*.test.ts","typecheck":"tsc --noEmit","conformance":"node bin/conformance.mjs","rig":"node examples/nested-host/serve.mjs","proof:rig":"node scripts/rig-proof.mjs"},"dependencies":{"@atoapayments/pay-embed":"*"},"devDependencies":{"@types/node":"^22.0.0","linkedom":"^0.18.13","puppeteer-core":"^25.4.0","tsup":"^8.0.0","typescript":"^5.5.0"},"gitHead":"7b2d5d12976b92eea65eb45932badc2729ed5936","_id":"@atoapayments/pay-host@0.0.1","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-0MXEEAcckTiZHliyxdaCSSXz8FjLWSKqmIhAsFwdcG+nnt4Bv+CVGLddCutOUJmrgcv/faQ4y9J6NrXQ8F9KQQ==","shasum":"15dd109e43d316f63637698817e2e9939787565f","tarball":"https://registry.npmjs.org/@atoapayments/pay-host/-/pay-host-0.0.1.tgz","fileCount":12,"unpackedSize":145268,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDQrztmJUP5wvjqw5NzIFkfIbtuq8604+rHiq2GzTanRQIgISdVb8FbEvtRR59YZUHJc9hL/lbnOGWCrfYR4hdlg04="}]},"_npmUser":{"name":"atoalicence","email":"licence@paywithatoa.co.uk"},"directories":{},"maintainers":[{"name":"shariqueatoa","email":"sharique@paywithatoa.co.uk"},{"name":"rvkrish","email":"vamsi@paywithatoa.co.uk"},{"name":"tushargupta224","email":"tushar@paywithatoa.co.uk"},{"name":"atoalicence","email":"licence@paywithatoa.co.uk"},{"name":"anandtanu","email":"tanushree@paywithatoa.co.uk"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pay-host_0.0.1_1787654008018_0.09926407639887813"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-25T10:33:27.876Z","0.0.1":"2026-08-25T10:33:28.159Z","modified":"2026-08-25T10:33:28.350Z"},"maintainers":[{"name":"shariqueatoa","email":"sharique@paywithatoa.co.uk"},{"name":"rvkrish","email":"vamsi@paywithatoa.co.uk"},{"name":"tushargupta224","email":"tushar@paywithatoa.co.uk"},{"name":"atoalicence","email":"licence@paywithatoa.co.uk"},{"name":"anandtanu","email":"tanushree@paywithatoa.co.uk"}],"description":"Host Atoa checkout inside your own UI — a chat thread, a support widget, a nested iframe. Detects the frame environment it landed in, picks the tier that can actually complete a payment there, and tells you exactly why. A payment is always completable, an","homepage":"https://github.com/ATOAPaymentsLimited/AtoaAgenticFramework/tree/main/packages/pay-host#readme","keywords":["atoa","payments","embed","iframe","chat","checkout","integration","sdk","browser"],"repository":{"type":"git","url":"git+https://github.com/ATOAPaymentsLimited/AtoaAgenticFramework.git","directory":"packages/pay-host"},"author":{"name":"Atoa and contributors"},"bugs":{"url":"https://github.com/ATOAPaymentsLimited/AtoaAgenticFramework/issues"},"license":"MIT","readme":"# `@atoapayments/pay-host`\n\nHost Atoa checkout inside your own UI — a chat thread, a support widget, a nested iframe.\n\n`@atoapayments/pay-embed` mounts a checkout. This package answers the question that comes first: **given the\nframe I actually landed in, what can work here?** It detects the environment, picks the tier that can\ncomplete a payment, degrades automatically when it must, and tells you exactly why.\n\n```bash\nnpm i @atoapayments/pay-host\n```\n\nOr with no install — a script tag. `@atoapayments/pay-embed` is bundled into this file, so one tag is\nthe whole integration. `@0` floats within the 0.x line; **in production pin an exact version**.\n\n```html\n<script src=\"https://unpkg.com/@atoapayments/pay-host@0/dist/index.global.js\"></script>\n<script>\n  const { AtoaHost } = window.AtoaHost; // the tag exposes the package's exports as `window.AtoaHost`\n  // AtoaHost.mount(result, { … }) exactly as below\n</script>\n```\n\n```js\nimport { AtoaHost } from '@atoapayments/pay-host';\n\nconst handle = AtoaHost.mount(result, {\n  container: document.querySelector('#checkout'),\n  environment: 'sandbox',\n  preset: 'bubble',                 // chat-width defaults\n  hosted: {                         // the bottom rung, so a payment is always completable\n    url: result.paymentUrl,\n    qrUrl: result.qrCodeUrl,\n    amountDisplay: '£12.50',\n    payee: 'Liberty London',\n  },\n  // Outcomes are resource.event domain events (see @atoapayments/pay-embed). UX signals only —\n  // confirm by polling (`payment.get` / `awaitSettled`) before fulfilling.\n  onPaymentCompleted: (e) => confirmOrder(e.data),\n  onEvent: (e) => log(e.type),      // every domain event, including future types\n});\n\nhandle.decision.tier;   // 'embed' | 'embed-relay' | 'embed-copy' | 'hosted-link'\nhandle.decision.reason; // why, in a sentence you can put in a log\n```\n\n## Detect · degrade · diagnose\n\n**Detect.** Before mounting, the SDK reads its situation: the real (possibly opaque) origin, sandbox\nflags, delegated permissions, storage, popup capability, nesting depth.\n\n**Degrade.** One decision picks the tier. Nothing here is the integrator's homework:\n\n| Tier | When | What the customer sees |\n|---|---|---|\n| `embed` | A normal embedding context | The full checkout |\n| `embed-relay` | Nested inside another frame | The full checkout; height relayed to the page above |\n| `embed-copy` | A sandbox above blocks popups | The checkout, with the hop as a copyable link + QR — because a bank link would fail *silently* here |\n| `hosted-link` | Opaque origin (sandbox without `allow-same-origin`) | A payment card with the hosted link, instead of a frame that cannot work |\n\n**Diagnose.** `AtoaHost.diagnose()` returns a machine-readable report — sandbox flags, allow-chain\nresults, ancestor origins, storage state, the chosen tier and why, plus warnings that each name the\nattribute to change. `?atoaDebug=1` renders the same thing as an overlay. It carries no payment data,\nso it is safe to paste into a ticket.\n\n## The integrator contract\n\n[`INTEGRATORS.md`](./INTEGRATORS.md) is the whole thing: the exact `allow` string, the sandbox flags\nand what breaks without each, the relay snippet, and the hop adapter. There is no origin to\nregister — framing is open by design, and the security boundary is the server-minted payment\nplus the customer's SCA on Atoa's origin, not who framed the page.\n\n## Conformance\n\n```bash\nnpx @atoapayments/pay-host conformance https://your-page.example\n```\n\nLoads your page headlessly and checks everything in the contract: frame present, real origin, sandbox\nflags sufficient, permissions delegated, no payment data posted to `'*'`, height applied rather than\nfixed, relay wired when nested. Exit 0 means you are done. `--json` for CI.\n\n## The reference rig\n\n```bash\nnpm run rig          # A (merchant) → B (chatbot) → C (checkout), three real origins\nnpm run proof:rig    # the same chain driven headlessly across the sandbox permutations\n```\n\n`examples/nested-host/` is a runnable two-level chain you can copy from, and the harness that proves\nthe nested-frame behaviour rather than asserting it. Flags let you reproduce each hostile case:\n`--sandbox \"…\"`, `--no-webauthn`, `--no-referrer`.\n\nIt is also how we found that `location.origin` **lies** inside an opaque-origin sandbox (it reports\nthe URL's tuple origin) while `window.origin` tells the truth. The detector probes the latter.\n\n## What this package does not do\n\nIt does not create payments, define new message types, or weaken any origin rule — the postMessage\nbridge stays pinned to the exact Atoa origin that answered the handshake. pay-embed keeps exactly\ntwo seams for this package to use (`onHop`, `relay`) and nothing else moved into it.\n\n## Gates\n\n```bash\nnpm test        # 45 tests\nnpm run typecheck\nnpm run build\nnpm run proof:rig    # 28 checks in a real browser across five frame configurations\n```\n","readmeFilename":"README.md","_rev":"1-616358de32cc6821977f3b2bc1e433fc"}