{"_id":"@angx/ngx-easy-captcha","_rev":"24-eab6fe6c2421d596e51e04fb28c2b176","name":"@angx/ngx-easy-captcha","dist-tags":{"latest":"3.0.1"},"versions":{"0.0.1":{"name":"@angx/ngx-easy-captcha","version":"0.0.1","keywords":["ngx easy captcha","angular captcha","angular 18 captcha","ngx google recaptcha","ngx cloudflare turnstile","google recaptcha","cloudflare turnstile","angular 18 google recaptcha","angular 18 cloudflare turnstile"],"_id":"@angx/ngx-easy-captcha@0.0.1","maintainers":[{"name":"onlyabhishek","email":"singh.abhishek0601@gmail.com"}],"homepage":"https://github.com/angx-libs/ngx-easy-captcha#readme","bugs":{"url":"https://github.com/angx-libs/ngx-easy-captcha/issues"},"dist":{"shasum":"e0a2380081dd8e9ead03a9655c5073ee09124e43","tarball":"https://registry.npmjs.org/@angx/ngx-easy-captcha/-/ngx-easy-captcha-0.0.1.tgz","fileCount":28,"integrity":"sha512-zCUmvRiuWvdTXTlijocH56IeqMtRaaQ3/TeCaooqIV1MLxTvzJTh1z7+PwO42gCxfrixkQ8yK9b5Wtp0QU1AqA==","signatures":[{"sig":"MEUCIQCV736mDrqshLvqmJvQ5i+m4D0TQaMxe0XwvKeQWG5OMAIgBmSLPYfeLoE37uNu9yz1Bpjs0QbE854y3yhbptlR3U8=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":90577},"module":"fesm2022/angx-ngx-easy-captcha.mjs","exports":{".":{"esm":"./esm2022/angx-ngx-easy-captcha.mjs","types":"./index.d.ts","default":"./fesm2022/angx-ngx-easy-captcha.mjs","esm2022":"./esm2022/angx-ngx-easy-captcha.mjs"},"./package.json":{"default":"./package.json"}},"gitHead":"701a0014c612e69b15ccfae87eed13306e2b66c3","typings":"index.d.ts","_npmUser":{"name":"onlyabhishek","email":"singh.abhishek0601@gmail.com"},"donations":"https://buymeacoffee.com/er.abhishek","repository":{"url":"git+https://github.com/angx-libs/ngx-easy-captcha.git","type":"git"},"_npmVersion":"10.2.4","description":"\"Ngx \"Ngx \"Ngx \"Ngx \"Ngx \r\n This site is protected by reCAPTCHA and the Google\r\n Privacy Policy and\r\n Terms of Service apply.\r\n\r\n```\r\n\r\n`ngx-easy-captcha` removes the badge for you when the last consumer is destroyed.\r\n\r\n## Features\r\n\r\n- One API for two providers — swap with a single enum value\r\n- Provider scripts are injected on demand, not bundled\r\n- Reference-counted script loading: several protected forms share one script tag safely\r\n- Cleans up after itself when the injector is destroyed — script tag, widgets, reCAPTCHA badge and globals\r\n- Tokens and errors on separate streams, so a failed challenge never kills the token stream\r\n- Turnstile tokens are refreshed automatically on expiry\r\n- SSR safe: resolves instead of hanging when there is no document\r\n\r\n## Requirements\r\n\r\nAngular 21 or 22.\r\n\r\n## Install\r\n\r\n```bash\r\nnpm i @angx/ngx-easy-captcha\r\n```\r\n\r\n## Usage\r\n\r\nProvide the service where you need it — usually on the component that owns the protected form, so it is torn down with that component.\r\n\r\n### Cloudflare Turnstile\r\n\r\n`initializer` is the **id prefix** of the element(s) the widget renders into. Every element whose id starts with that prefix gets its own widget, which is how one page can protect several forms.\r\n\r\n```html\r\n
\r\n
\r\n```\r\n\r\n```ts\r\nimport { Component, inject, signal } from '@angular/core';\r\nimport { takeUntilDestroyed } from '@angular/core/rxjs-interop';\r\nimport {\r\n CaptchaProvider,\r\n NgxEasyCaptchaService,\r\n provideNgxEasyCaptcha,\r\n} from '@angx/ngx-easy-captcha';\r\n\r\n@Component({\r\n selector: 'app-signin',\r\n providers: [\r\n provideNgxEasyCaptcha({\r\n provider: CaptchaProvider.CloudFlare,\r\n siteKey: '0x4AAAAAAA...',\r\n initializer: 'cloudflare-captcha',\r\n }),\r\n ],\r\n templateUrl: './signin.component.html',\r\n})\r\nexport class SignInComponent {\r\n private readonly captcha = inject(NgxEasyCaptchaService);\r\n\r\n readonly token = signal('');\r\n readonly error = signal('');\r\n\r\n constructor() {\r\n this.captcha.$.pipe(takeUntilDestroyed()).subscribe((token) => this.token.set(token));\r\n this.captcha.errors$.pipe(takeUntilDestroyed()).subscribe((e) => this.error.set(e.message));\r\n }\r\n\r\n submit() {\r\n if (this.token()) {\r\n // Send this.token() to your backend and verify it there.\r\n }\r\n }\r\n}\r\n```\r\n\r\n### Google reCAPTCHA v3\r\n\r\nreCAPTCHA v3 is invisible, so there is no container element. Here `initializer` is the **action** name (`login`, `register`, ...).\r\n\r\n```ts\r\nproviders: [\r\n provideNgxEasyCaptcha({\r\n provider: CaptchaProvider.Google,\r\n siteKey: '6Lc...',\r\n initializer: 'login',\r\n }),\r\n],\r\n```\r\n\r\nEverything else is identical — the same `$` and `errors$` streams.\r\n\r\n### Manual providers\r\n\r\n`provideNgxEasyCaptcha` is a convenience wrapper. The individual tokens still work:\r\n\r\n```ts\r\nproviders: [\r\n NgxEasyCaptchaService,\r\n { provide: CAPTCHA_PROVIDER, useValue: CaptchaProvider.CloudFlare },\r\n { provide: CAPTCHA_SITE_KEY, useValue: '0x4AAAAAAA...' },\r\n { provide: STRING_INITIALIZER, useValue: 'cloudflare-captcha' },\r\n],\r\n```\r\n\r\n## API\r\n\r\n| Member | Type | Description |\r\n|---|---|---|\r\n| `$` | `Observable` | Emits each issued token. Never errors. |\r\n| `errors$` | `Observable` | Non-fatal provider problems: `{ code, message }`. |\r\n| `refresh()` | `void` | reCAPTCHA: request a new token. Turnstile: reset the widgets. |\r\n\r\nCleanup runs automatically via `ngOnDestroy` when the providing injector is destroyed. You still want `takeUntilDestroyed()` (or an `unsubscribe`) on your own subscriptions.\r\n\r\n> **Verify tokens on your server.** A captcha token proves nothing until your backend posts it to the provider's `siteverify` endpoint with your **secret** key. Never put the secret key in frontend code.\r\n\r\n## Testing locally\r\n\r\nCloudflare publishes dummy site keys that work on any domain, including `localhost`:\r\n\r\n| Key | Behaviour |\r\n|---|---|\r\n| `1x00000000000000000000AA` | Always passes, visible |\r\n| `2x00000000000000000000AB` | Always blocks, visible |\r\n| `3x00000000000000000000FF` | Forces an interactive challenge |\r\n\r\nreCAPTCHA v3 has no universal test key — register `localhost` under your own site key.\r\n\r\n## Migrating from 2.x\r\n\r\n- **Angular 21+ is required**, and the workspace targets Angular 22.\r\n- **`CaptchaProvider` is now a string enum** (`'google'` / `'cloudflare'` rather than `0` / `1`). Use the enum members and nothing changes; only code comparing against raw numbers breaks.\r\n- **`$` no longer errors.** Subscribe to `errors$` instead of an `error` callback. This is what stops one failed challenge from disabling the service for the rest of the session.\r\n- `$` no longer emits an initial empty string, so you can drop `if (token)` guards.\r\n- `removeScriptAndTraces()` is replaced by the reference-counted `release()`.\r\n- Misconfiguration now throws with an actionable message instead of logging to the console and silently returning an observable that never emits.\r\n- New: `provideNgxEasyCaptcha()`, `refresh()`, `errors$`.\r\n\r\n### Fixed in 3.0.0\r\n\r\n- **Turnstile widgets never rendered.** `turnstile.render()` was wrapped in `turnstile.ready()`, which is only for code running *before* `api.js` loads; called afterwards it logs a warning and never invokes the callback.\r\n- **Tearing down one form removed the shared script for every other form** on the page. Script loading is now reference counted.\r\n- **`async` and `defer` were assigned to each other** (`script.async` was set from `defer` and vice versa).\r\n- **The script store was mutated in place** while substituting the site key, so a second consumer with a different key silently reused the first one.\r\n- **The promise never settled during server-side rendering**, leaving callers awaiting forever.\r\n- **The two misconfiguration messages were swapped** — the reCAPTCHA branch printed the Turnstile advice and vice versa.\r\n- A failed script load resolved with `status: 'Loaded'`.\r\n- Removing badges iterated a live `HTMLCollection` forward while deleting from it, leaving roughly half behind.\r\n- Concurrent callers each injected their own copy of the same script tag.\r\n- A hand-written `index.d.ts` re-exported classes and injection tokens with `export type`.\r\n- Cleanup depended on the consumer unsubscribing, via a `finalize()` that never ran if they forgot.\r\n\r\n## Development\r\n\r\n```bash\r\nnpm install\r\nnpm run build:lib # build the package into dist/angx/ngx-easy-captcha\r\nnpm start # build the lib, then serve the demo app\r\nnpm test # run the library unit tests\r\n```\r\n\r\nThe demo app is deployed to GitHub Pages from `master` by `.github/workflows/deploy-demo.yml`.\r\n\r\nThe Turnstile page (`/cloudflare-turnstile`) works out of the box using Cloudflare's public test key. The reCAPTCHA page (`/google-recaptcha`) needs your own site key with `localhost` registered — paste it into the component's `providers`.\r\n\r\n## Support\r\n\r\nIf you like my work and feel like buying me a coffee, please feel free to do so:\r\n\r\n[Buy Me A Coffee](https://buymeacoffee.com/er.abhishek)\r\n\r\n## License\r\n\r\nMIT © Abhishek Singh\r\n\r\n[GitHub](https://github.com/asingh0601) · [Twitter](https://twitter.com/only_abhishek)\r\n","readmeFilename":"README.md"}