@captigo/core - npm Package Compare versions

Comparing version 0.1.0 to 0.2.0

README.md

+# @captigo/core
+
+> Core types and adapter contracts for [Captigo](https://github.com/moritzmyrz/captigo) — a provider-agnostic CAPTCHA integration layer.
+
+This package defines the shared types and the `CaptchaAdapter` / `CaptchaWidget`
+interfaces that every captigo provider implements. You usually install it
+alongside a provider package (Turnstile, hCaptcha, reCAPTCHA); it is also pulled
+in automatically as a dependency of those adapters.
+
+Use `@captigo/core` directly when you want to depend only on types, write helper
+code against `CaptchaAdapter`, or share configuration between client and server
+without importing a specific provider.
+
+---
+
+## Installation
+
+```bash
+npm install @captigo/core
+```
+
+Most apps install an adapter as well; `@captigo/core` is also installed automatically as a dependency of `@captigo/turnstile`, `@captigo/hcaptcha`, `@captigo/recaptcha`, `@captigo/react`, `@captigo/vue`, and `@captigo/nextjs`.
+
+```bash
+npm install @captigo/core @captigo/turnstile
+```
+
+---
+
+## What this package exports
+
+- **Types:** `CaptchaToken`, `VerifyResult`, `VerifyOptions`, `AdapterMeta`,
+  `CaptchaMode`, `ProviderId`, and related configuration types.
+- **Contracts:** `CaptchaAdapter`, `CaptchaWidget`, `RenderOptions`,
+  `WidgetCallbacks`, `AdapterFactory`.
+- **Errors:** `CaptchaError` and `CaptchaErrorCode`.
+
+See the TypeScript definitions in `dist/index.d.ts` after build for the full API.
+
+---
+
+## Typical usage
+
+Provider factories return a `CaptchaAdapter`. Your app passes that adapter to
+framework integrations (`@captigo/react`, `@captigo/vue`) or calls
+`adapter.render` / `adapter.verify` yourself:
+
+```ts
+import type { CaptchaAdapter } from "@captigo/core";
+import { turnstile } from "@captigo/turnstile";
+
+const adapter: CaptchaAdapter = turnstile({ siteKey: "..." });
+```
+
+---
+
+## Caveats
+
+- **This package has no widget UI.** Use a provider adapter plus `@captigo/react`, `@captigo/vue`, or your own `adapter.render()` integration.
+- **Secrets never belong in client bundles.** Use each adapter’s server-side `verify` / `verifyToken` from your backend only.
+
+---
+
+## Documentation
+
+- [Getting started](https://github.com/moritzmyrz/captigo/blob/main/docs/getting-started.md)
+- [Server-side verification](https://github.com/moritzmyrz/captigo/blob/main/docs/server-verification.md)
+- [Supported providers](https://github.com/moritzmyrz/captigo/blob/main/docs/providers.md)
+- [Compatibility](https://github.com/moritzmyrz/captigo/blob/main/docs/compatibility.md)
+
+[Monorepo overview](https://github.com/moritzmyrz/captigo#readme) · [Source](https://github.com/moritzmyrz/captigo/tree/main/packages/core) · [Issues](https://github.com/moritzmyrz/captigo/issues)

dist/index.js

@@ -11,4 +11,5 @@ // src/errors.ts
     this.provider = provider;
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, _CaptchaError);
+    const Err = Error;
+    if (typeof Err.captureStackTrace === "function") {
+      Err.captureStackTrace(this, _CaptchaError);
     }
@@ -15,0 +16,0 @@ }

dist/index.js.map

@@ -1,1 +0,1 @@
-{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["/**\n * All errors thrown by captigo and its provider packages are instances\n * of CaptchaError. Check `error.code` to branch on specific failure cases\n * without string-matching the message.\n */\nexport type CaptchaErrorCode =\n  | \"script-load-failed\" // provider script could not be loaded or timed out\n  | \"render-failed\" // widget failed to mount into the container\n  | \"execute-failed\" // challenge could not be triggered (e.g. called before ready)\n  | \"verify-failed\" // server-side HTTP request to the provider API failed\n  | \"token-expired\" // a token was present but the provider reported it as expired\n  | \"provider-error\" // provider returned success:false with error codes\n  | \"not-implemented\"; // adapter method has not been implemented yet\n\nexport class CaptchaError extends Error {\n  readonly code: CaptchaErrorCode;\n  /** The provider that raised this error, if known (e.g. \"turnstile\"). */\n  readonly provider: string | undefined;\n\n  constructor(code: CaptchaErrorCode, message: string, provider?: string) {\n    super(message);\n    this.name = \"CaptchaError\";\n    this.code = code;\n    this.provider = provider;\n\n    // Preserves a clean stack trace in V8 (Node.js / Chrome).\n    if (Error.captureStackTrace) {\n      Error.captureStackTrace(this, CaptchaError);\n    }\n  }\n}\n"],"mappings":";AAcO,IAAM,eAAN,MAAM,sBAAqB,MAAM;AAAA,EAC7B;AAAA;AAAA,EAEA;AAAA,EAET,YAAY,MAAwB,SAAiB,UAAmB;AACtE,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,OAAO;AACZ,SAAK,WAAW;AAGhB,QAAI,MAAM,mBAAmB;AAC3B,YAAM,kBAAkB,MAAM,aAAY;AAAA,IAC5C;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["/**\n * All errors thrown by captigo and its provider packages are instances\n * of CaptchaError. Check `error.code` to branch on specific failure cases\n * without string-matching the message.\n */\nexport type CaptchaErrorCode =\n  | \"script-load-failed\" // provider script could not be loaded or timed out\n  | \"render-failed\" // widget failed to mount into the container\n  | \"execute-failed\" // challenge could not be triggered (e.g. called before ready)\n  | \"verify-failed\" // server-side HTTP request to the provider API failed\n  | \"token-expired\" // a token was present but the provider reported it as expired\n  | \"provider-error\" // provider returned success:false with error codes\n  | \"not-implemented\"; // adapter method has not been implemented yet\n\n/** V8-only (Node.js / Chrome). Not on `ErrorConstructor` in DOM/ES libs. */\ntype ErrorConstructorWithCapture = ErrorConstructor & {\n  captureStackTrace?: (\n    target: object,\n    constructorOpt?: new (...args: unknown[]) => unknown,\n  ) => void;\n};\n\nexport class CaptchaError extends Error {\n  readonly code: CaptchaErrorCode;\n  /** The provider that raised this error, if known (e.g. \"turnstile\"). */\n  readonly provider: string | undefined;\n\n  constructor(code: CaptchaErrorCode, message: string, provider?: string) {\n    super(message);\n    this.name = \"CaptchaError\";\n    this.code = code;\n    this.provider = provider;\n\n    // Preserves a clean stack trace in V8 (Node.js / Chrome).\n    const Err = Error as ErrorConstructorWithCapture;\n    if (typeof Err.captureStackTrace === \"function\") {\n      // V8 accepts any constructor; `CaptchaError`'s ctor params are stricter than `unknown[]`.\n      Err.captureStackTrace(this, CaptchaError as unknown as new (...args: unknown[]) => unknown);\n    }\n  }\n}\n"],"mappings":";AAsBO,IAAM,eAAN,MAAM,sBAAqB,MAAM;AAAA,EAC7B;AAAA;AAAA,EAEA;AAAA,EAET,YAAY,MAAwB,SAAiB,UAAmB;AACtE,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,OAAO;AACZ,SAAK,WAAW;AAGhB,UAAM,MAAM;AACZ,QAAI,OAAO,IAAI,sBAAsB,YAAY;AAE/C,UAAI,kBAAkB,MAAM,aAA8D;AAAA,IAC5F;AAAA,EACF;AACF;","names":[]}

package.json

 {
   "name": "@captigo/core",
-  "version": "0.1.0",
-  "description": "Provider-agnostic CAPTCHA integration for the modern web",
+  "version": "0.2.0",
+  "description": "Core types and CaptchaAdapter contracts for Captigo — provider-agnostic CAPTCHA integration",
   "type": "module",
@@ -27,11 +27,13 @@ "exports": {
   "keywords": [
+    "adapter",
+    "bot-protection",
     "captigo",
     "captcha",
+    "cloudflare",
     "hcaptcha",
+    "provider-agnostic",
     "recaptcha",
+    "security",
     "turnstile",
-    "cloudflare",
-    "security",
-    "typescript",
-    "provider-agnostic"
+    "typescript"
   ],
@@ -38,0 +40,0 @@ "license": "MIT",

src/errors.ts

@@ -15,2 +15,10 @@ /**
 
+/** V8-only (Node.js / Chrome). Not on `ErrorConstructor` in DOM/ES libs. */
+type ErrorConstructorWithCapture = ErrorConstructor & {
+  captureStackTrace?: (
+    target: object,
+    constructorOpt?: new (...args: unknown[]) => unknown,
+  ) => void;
+};
+
 export class CaptchaError extends Error {
@@ -28,6 +36,8 @@ readonly code: CaptchaErrorCode;
     // Preserves a clean stack trace in V8 (Node.js / Chrome).
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, CaptchaError);
+    const Err = Error as ErrorConstructorWithCapture;
+    if (typeof Err.captureStackTrace === "function") {
+      // V8 accepts any constructor; `CaptchaError`'s ctor params are stricter than `unknown[]`.
+      Err.captureStackTrace(this, CaptchaError as unknown as new (...args: unknown[]) => unknown);
     }
   }
 }

Fixed alerts

No README

Quality

Package does not have a README. This may indicate a failed publish or a low quality package.

Improved metrics

Total package byte prevSize

27311

16.13%

Number of package files

10

11.11%

Lines of code

468

2.18%

Number of medium quality alerts

0

-100%

Number of lines in readme file

72

Infinity%

No dependency changes