Error: {error.message}
;\n return ;\n}\n```\n\nReact is declared as an **optional** peer dependency — you only need it installed if you import from `@allsign/embedded/react`.\n\n## TypeScript\n\nFull type declarations are shipped with the package:\n\n```ts\nimport type {\n AllSignInitOptions,\n AllSignSession,\n SigningResult,\n ExitMetadata,\n SigningEvent,\n ThemeOptions,\n Locale,\n} from '@allsign/embedded';\n\nimport type {\n UseAllSignLinkOptions,\n UseAllSignLinkReturn,\n} from '@allsign/embedded/react';\n```\n\n## Error handling\n\nAll errors thrown by the SDK are instances of `AllSignError` with a stable `code` you can branch on:\n\n```js\nimport { AllSign, AllSignError, AllSignErrorCode } from '@allsign/embedded';\n\ntry {\n const session = AllSign.init({ clientSecret });\n} catch (e) {\n if (e instanceof AllSignError) {\n switch (e.code) {\n case AllSignErrorCode.MISSING_CLIENT_SECRET:\n case AllSignErrorCode.INVALID_CLIENT_SECRET_FORMAT:\n // Your backend didn't return a valid client_secret\n break;\n case AllSignErrorCode.SECRET_KEY_PASSED_AS_CLIENT_SECRET:\n // You passed a secret key to the frontend — SECURITY BUG, fix it\n break;\n case AllSignErrorCode.SESSION_EXPIRED:\n // Create a new signing session server-side and retry\n break;\n // ... see src/core/errors.ts for the full catalog\n }\n }\n throw e;\n}\n```\n\nRuntime errors from the signing flow (the iframe) do NOT throw — they arrive in your `onExit`\ncallback as `metadata.error.code`. The SDK passes those codes through **verbatim** (no\nnormalization), and the full catalog — what each code means, who emits it, and what to do — is\ndocumented per-code in [`src/core/errors.ts`](./src/core/errors.ts) and in the docs:\n[developers.allsign.io/embedded/errors](https://developers.allsign.io/embedded/errors).\n\n### Terminal vs retryable — recovery pattern\n\nUse `isRetryableError(code)` / `isTerminalError(code)` to decide how to recover:\n\n- **Retryable (transient)** — `NETWORK_ERROR`, `BACKEND_UNREACHABLE`, `INVALID_BACKEND_RESPONSE`,\n `INTERNAL_ERROR`, `INIT_TIMEOUT`, and any `HTTP_5xx` fallback. The failure is\n infrastructure-side: the **same** `client_secret` remains exchangeable for its full 15-minute\n TTL, so re-invoke `AllSign.init` with it (add a short backoff).\n- **Terminal (everything else, including unknown codes)** — the session itself is unusable\n (expired, completed, cancelled, invalid, misconfigured…). Retrying with the same secret cannot\n succeed. Recovery, Plaid-style: your **server** creates a NEW signing session\n (`POST /v2/signing-sessions`) and your frontend re-invokes `AllSign.init` with the fresh\n `client_secret`.\n\n```js\nimport { AllSign, isRetryableError } from '@allsign/embedded';\n\nfunction mount(clientSecret) {\n const session = AllSign.init({\n clientSecret,\n onSuccess: (result) => console.log('Firmado:', result.signatureId),\n onExit: async (metadata) => {\n const code = metadata.error?.code;\n if (!code) return; // clean exit (completed / cancelled by the signer)\n\n if (isRetryableError(code)) {\n // Transient — same client_secret is still valid (15-min TTL)\n setTimeout(() => mount(clientSecret), 2000);\n } else {\n // Terminal — create a NEW session server-side and re-init\n const res = await fetch('/my-api/signing-sessions', { method: 'POST' });\n const { client_secret: fresh } = await res.json();\n mount(fresh);\n }\n },\n });\n session.modal();\n}\n```\n\n## Development\n\n```bash\n# Install deps\nnpm install\n\n# Run tests (unit, jsdom)\nnpm test\n\n# Typecheck\nnpm run typecheck\n\n# Build (ESM + CJS + UMD + d.ts per entry)\nnpm run build\n```\n\n## Release pipeline\n\nPublishing is automated via GitHub Actions ([`.github/workflows/release.yml`](.github/workflows/release.yml)):\npushing a `v*` tag typechecks, tests, builds, and `npm publish`es with provenance.\n\n```bash\n# 1. bump \"version\" in package.json + add a CHANGELOG.md entry, merge to main\n# 2. tag and push:\ngit tag v0.2.0 && git push origin v0.2.0\n```\n\nOne-time setup: add an npm **automation token** as the `NPM_TOKEN` repo secret.\n\nTo publish manually instead (the `prepublishOnly` hook rebuilds `dist/` first, so it can never ship stale output):\n\n```bash\nnpm login # if your local token is expired\nnpm publish # publishConfig.access is already \"public\"\n```\n\n- Semver: loader API stable at `v1.x`, additive events are minors, type breaks are majors\n- Size budgets: loader <3KB gzip, core <50KB gzip\n\n## Links\n\n- **Docs**: [developers.allsign.io/embedded](https://developers.allsign.io/embedded)\n- **Backend API**: [developers.allsign.io](https://developers.allsign.io)\n- **Dashboard (iframe host)**: [allsign.io](https://allsign.io)\n- **Issues**: [github.com/binaryme/allsign-embedded-sdk/issues](https://github.com/binaryme/allsign-embedded-sdk/issues)\n\n## License\n\nMIT\n","readmeFilename":"README.md"}