@dynamic-labs-sdk/react-native-captcha 0.0.0 → 1.27.1

package/README.md

@@ -0,0 +1,92 @@
+# @dynamic-labs-sdk/react-native-captcha
+
+Captcha challenge widgets for React Native apps using Dynamic.
+
+Provides self-contained `HCaptchaChallenge` and `TurnstileChallenge` components that render their provider's widget in a `react-native-webview` and return the captcha token over a postMessage bridge. Pass the token to `@dynamic-labs-sdk/client`'s `setCaptchaToken` before sign-in methods that require captcha.
+
+## Installation
+
+```bash
+pnpm add @dynamic-labs-sdk/react-native-captcha
+```
+
+Requires `@dynamic-labs-sdk/client` and `react-native-webview`.
+
+## Usage
+
+Read the active provider and site key from `getCaptchaSettings`, then render the matching challenge component.
+
+```tsx
+import { useState } from 'react';
+import { View, Button } from 'react-native';
+import { CaptchaProviderEnum, getCaptchaSettings, setCaptchaToken } from '@dynamic-labs-sdk/client';
+import { HCaptchaChallenge, TurnstileChallenge } from '@dynamic-labs-sdk/react-native-captcha';
+
+function SignInScreen() {
+  const [captchaReady, setCaptchaReady] = useState(false);
+  const settings = getCaptchaSettings();
+  const siteKey = settings?.siteKey;
+
+  const handleSignIn = async () => {
+    // sendEmailOTP, auth.wallet.connect, etc.
+  };
+
+  if (!settings || !siteKey) {
+    return <Button title="Sign in" onPress={handleSignIn} />;
+  }
+
+  const handleToken = (token: string) => {
+    setCaptchaToken({ captchaToken: token });
+    setCaptchaReady(true);
+  };
+
+  const Challenge =
+    settings.provider === CaptchaProviderEnum.Hcaptcha
+      ? HCaptchaChallenge
+      : TurnstileChallenge;
+
+  return (
+    <View>
+      <Challenge
+        baseUrl="https://your-whitelisted-origin.com"
+        siteKey={siteKey}
+        onToken={handleToken}
+        onError={(error) => console.error(error.message)}
+      />
+      <Button title="Sign in" disabled={!captchaReady} onPress={handleSignIn} />
+    </View>
+  );
+}
+```
+
+The `baseUrl` prop is the origin the widget document is served under. hCaptcha and Turnstile site keys only render on whitelisted hostnames, so set it to a domain you have added to your provider's site configuration.
+
+## Components
+
+| Component | Provider |
+| --------- | -------- |
+| `HCaptchaChallenge` | hCaptcha |
+| `TurnstileChallenge` | Cloudflare Turnstile |
+
+Both components accept `baseUrl`, `siteKey`, `onToken`, `onError`, and an optional `style` prop. `onToken` fires once when the user solves the challenge; `onError` fires once on challenge error, token expiry, or WebView load failure. The returned errors are typed (`HCaptchaError` / `TurnstileError`) so you can branch on `error instanceof HCaptchaError` or inspect `error.message`.
+
+Use the `style` prop to override the default height, border radius, or other container styles to match your app's design.
+
+## Retrying a challenge
+
+`onToken` and `onError` each fire at most once per mounted widget. If you need to let the user retry after a challenge error or token expiry, unmount and remount the component, for example by incrementing a React `key`:
+
+```tsx
+const [attemptKey, setAttemptKey] = useState(0);
+
+<Challenge
+  key={attemptKey}
+  baseUrl="https://your-whitelisted-origin.com"
+  siteKey={siteKey}
+  onToken={handleToken}
+  onError={(error) => {
+    console.error(error.message);
+    setAttemptKey((k) => k + 1);
+  }}
+/>
+```

package/dist/components/HCaptchaChallenge/HCaptchaChallenge.d.ts

@@ -0,0 +1,86 @@
+import type { FC } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import { type LogLevel } from '@dynamic-labs-sdk/client/core';
+import { HCaptchaError } from '../../errors/HCaptchaError';
+/**
+ * `testID` e2e drivers use to locate the hCaptcha widget on screen.
+ *
+ * @example
+ * ```tsx
+ * <View testID={HCAPTCHA_CHALLENGE_TEST_ID} />
+ * ```
+ * @see HCaptchaChallenge
+ * @see HCaptchaChallengeProps
+ */
+export declare const HCAPTCHA_CHALLENGE_TEST_ID = "hcaptcha-challenge";
+/**
+ * Props for the {@link HCaptchaChallenge} component.
+ *
+ * @example
+ * ```tsx
+ * const props: HCaptchaChallengeProps = {
+ *   baseUrl: 'https://your-whitelisted-origin.com',
+ *   onError: console.error,
+ *   onToken: setToken,
+ *   siteKey: '10000000-ffff-ffff-ffff-000000000001',
+ *   logLevel: 'warn',
+ * };
+ * ```
+ * @see HCaptchaChallenge
+ * @see HCaptchaError
+ */
+export type HCaptchaChallengeProps = {
+    /**
+     * Origin the widget document is served under. hCaptcha refuses to render on
+     * origin-less documents, and real (non-test) site keys only render on hosts
+     * whitelisted for the key — pass an origin your site key accepts.
+     */
+    baseUrl: string;
+    /**
+     * Optional minimum log level for the component's internal logger. Defaults
+     * to `'warn'` when omitted.
+     */
+    logLevel?: LogLevel;
+    /**
+     * Called when the widget cannot produce a token: the WebView fails to load,
+     * hCaptcha reports a challenge error, or the token expires unclaimed —
+     * so callers awaiting `onToken` fail immediately instead of hanging until
+     * their own timeout.
+     */
+    onError: (error: HCaptchaError) => void;
+    /** Called with the token hCaptcha issues when the widget is solved. */
+    onToken: (token: string) => void;
+    /**
+     * The environment's hCaptcha site key, from the SDK's `getCaptchaSettings`.
+     */
+    siteKey: string;
+    /**
+     * Optional style for the outer container. Use this to set width/height,
+     * margins, border radius, or background color to match your app's UI.
+     */
+    style?: StyleProp<ViewStyle>;
+};
+/**
+ * Renders the hCaptcha checkbox widget in an inline WebView and reports the
+ * resulting captcha token over the postMessage bridge. The caller hands the
+ * token to the SDK's `setCaptchaToken`. Exactly one of `onToken`/`onError`
+ * fires, exactly once — the first terminal event (token, challenge error,
+ * expiry, or WebView load failure) wins.
+ *
+ * @example
+ * ```tsx
+ * <HCaptchaChallenge
+ *   baseUrl="https://your-whitelisted-origin.com"
+ *   siteKey="10000000-ffff-ffff-ffff-000000000001"
+ *   onToken={(token) => setCaptchaToken({ captchaToken: token })}
+ *   onError={(error) => console.error(error.message)}
+ *   style={{ height: 260 }}
+ *   logLevel="warn"
+ * />
+ * ```
+ * @returns A React Native view that hosts the captcha WebView.
+ * @see HCaptchaChallengeProps
+ * @see HCaptchaError
+ */
+export declare const HCaptchaChallenge: FC<HCaptchaChallengeProps>;
+//# sourceMappingURL=HCaptchaChallenge.d.ts.map

package/dist/components/HCaptchaChallenge/HCaptchaChallenge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HCaptchaChallenge.d.ts","sourceRoot":"","sources":["../../../src/components/HCaptchaChallenge/HCaptchaChallenge.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC;AAEhC,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAIzD,OAAO,EAAE,KAAK,QAAQ,EAAgB,MAAM,+BAA+B,CAAC;AAG5E,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE3D;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,uBAAuB,CAAC;AAmB/D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;;;;OAKG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IACxC,uEAAuE;IACvE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;CAC9B,CAAC;AAkDF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,iBAAiB,EAAE,EAAE,CAAC,sBAAsB,CAyFxD,CAAC"}

package/dist/components/TurnstileChallenge/TurnstileChallenge.d.ts

@@ -0,0 +1,86 @@
+import type { FC } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import { type LogLevel } from '@dynamic-labs-sdk/client/core';
+import { TurnstileError } from '../../errors/TurnstileError';
+/**
+ * `testID` e2e drivers use to locate the Turnstile widget on screen.
+ *
+ * @example
+ * ```tsx
+ * <View testID={TURNSTILE_CHALLENGE_TEST_ID} />
+ * ```
+ * @see TurnstileChallenge
+ * @see TurnstileChallengeProps
+ */
+export declare const TURNSTILE_CHALLENGE_TEST_ID = "turnstile-challenge";
+/**
+ * Props for the {@link TurnstileChallenge} component.
+ *
+ * @example
+ * ```tsx
+ * const props: TurnstileChallengeProps = {
+ *   baseUrl: 'https://your-whitelisted-origin.com',
+ *   onError: console.error,
+ *   onToken: setToken,
+ *   siteKey: '1x00000000000000000000AA',
+ *   logLevel: 'warn',
+ * };
+ * ```
+ * @see TurnstileChallenge
+ * @see TurnstileError
+ */
+export type TurnstileChallengeProps = {
+    /**
+     * Origin the widget document is served under. Turnstile refuses to render on
+     * origin-less documents, and real (non-test) site keys only render on hosts
+     * whitelisted for the key — pass an origin your site key accepts.
+     */
+    baseUrl: string;
+    /**
+     * Optional minimum log level for the component's internal logger. Defaults
+     * to `'warn'` when omitted.
+     */
+    logLevel?: LogLevel;
+    /**
+     * Called when the widget cannot produce a token: the WebView fails to load,
+     * Turnstile reports a challenge error, or the token expires unclaimed —
+     * so callers awaiting `onToken` fail immediately instead of hanging until
+     * their own timeout.
+     */
+    onError: (error: TurnstileError) => void;
+    /** Called with the token Turnstile issues when the widget is solved. */
+    onToken: (token: string) => void;
+    /**
+     * The environment's Turnstile site key, from the SDK's `getCaptchaSettings`.
+     */
+    siteKey: string;
+    /**
+     * Optional style for the outer container. Use this to set width/height,
+     * margins, border radius, or background color to match your app's UI.
+     */
+    style?: StyleProp<ViewStyle>;
+};
+/**
+ * Renders the Cloudflare Turnstile widget in an inline WebView and reports the
+ * resulting captcha token over the postMessage bridge. The caller hands the
+ * token to the SDK's `setCaptchaToken`. Exactly one of `onToken`/`onError`
+ * fires, exactly once — the first terminal event (token, challenge error,
+ * expiry, or WebView load failure) wins.
+ *
+ * @example
+ * ```tsx
+ * <TurnstileChallenge
+ *   baseUrl="https://your-whitelisted-origin.com"
+ *   siteKey="1x00000000000000000000AA"
+ *   onToken={(token) => setCaptchaToken({ captchaToken: token })}
+ *   onError={(error) => console.error(error.message)}
+ *   style={{ height: 120 }}
+ *   logLevel="warn"
+ * />
+ * ```
+ * @returns A React Native view that hosts the captcha WebView.
+ * @see TurnstileChallengeProps
+ * @see TurnstileError
+ */
+export declare const TurnstileChallenge: FC<TurnstileChallengeProps>;
+//# sourceMappingURL=TurnstileChallenge.d.ts.map

package/dist/components/TurnstileChallenge/TurnstileChallenge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TurnstileChallenge.d.ts","sourceRoot":"","sources":["../../../src/components/TurnstileChallenge/TurnstileChallenge.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC;AAEhC,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAIzD,OAAO,EAAE,KAAK,QAAQ,EAAgB,MAAM,+BAA+B,CAAC;AAG5E,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,wBAAwB,CAAC;AAmBjE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;;;;OAKG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IACzC,wEAAwE;IACxE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;CAC9B,CAAC;AAkDF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,kBAAkB,EAAE,EAAE,CAAC,uBAAuB,CA2F1D,CAAC"}

package/dist/errors/HCaptchaError.d.ts

@@ -0,0 +1,30 @@
+import { BaseError } from '@dynamic-labs-sdk/client';
+/**
+ * Thrown when the embedded hCaptcha challenge fails to resolve — for example
+ * the widget reports an error, the token expires, or the user closes the
+ * challenge without completing it.
+ *
+ * The {@link HCaptchaChallenge} component surfaces this typed error through its
+ * `onError` callback so consumers can distinguish a failed captcha from other
+ * failures and prompt the user to retry rather than treating it as a fatal
+ * error.
+ *
+ * @example
+ * ```tsx
+ * <HCaptchaChallenge
+ *   onError={(error) => {
+ *     if (error instanceof HCaptchaError) {
+ *       promptRetry(error.message);
+ *     }
+ *   }}
+ * />
+ * ```
+ * @see HCaptchaChallenge
+ * @see HCaptchaChallengeProps
+ */
+export declare class HCaptchaError extends BaseError {
+    constructor({ description }: {
+        description: string | undefined;
+    });
+}
+//# sourceMappingURL=HCaptchaError.d.ts.map

package/dist/errors/HCaptchaError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HCaptchaError.d.ts","sourceRoot":"","sources":["../../src/errors/HCaptchaError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,aAAc,SAAQ,SAAS;gBAC9B,EAAE,WAAW,EAAE,EAAE;QAAE,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE;CASjE"}

package/dist/errors/TurnstileError.d.ts

@@ -0,0 +1,30 @@
+import { BaseError } from '@dynamic-labs-sdk/client';
+/**
+ * Thrown when the embedded Cloudflare Turnstile challenge fails to resolve —
+ * for example the widget reports an error, the token expires, or the user
+ * closes the challenge without completing it.
+ *
+ * The {@link TurnstileChallenge} component surfaces this typed error through
+ * its `onError` callback so consumers can distinguish a failed captcha from
+ * other failures and prompt the user to retry rather than treating it as a
+ * fatal error.
+ *
+ * @example
+ * ```tsx
+ * <TurnstileChallenge
+ *   onError={(error) => {
+ *     if (error instanceof TurnstileError) {
+ *       promptRetry(error.message);
+ *     }
+ *   }}
+ * />
+ * ```
+ * @see TurnstileChallenge
+ * @see TurnstileChallengeProps
+ */
+export declare class TurnstileError extends BaseError {
+    constructor({ description }: {
+        description: string | undefined;
+    });
+}
+//# sourceMappingURL=TurnstileError.d.ts.map

package/dist/errors/TurnstileError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TurnstileError.d.ts","sourceRoot":"","sources":["../../src/errors/TurnstileError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,cAAe,SAAQ,SAAS;gBAC/B,EAAE,WAAW,EAAE,EAAE;QAAE,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE;CASjE"}

package/dist/exports/index.d.ts

@@ -0,0 +1,7 @@
+export { HCAPTCHA_CHALLENGE_TEST_ID, HCaptchaChallenge, } from '../components/HCaptchaChallenge/HCaptchaChallenge';
+export type { HCaptchaChallengeProps } from '../components/HCaptchaChallenge/HCaptchaChallenge';
+export { HCaptchaError } from '../errors/HCaptchaError';
+export { TURNSTILE_CHALLENGE_TEST_ID, TurnstileChallenge, } from '../components/TurnstileChallenge/TurnstileChallenge';
+export type { TurnstileChallengeProps } from '../components/TurnstileChallenge/TurnstileChallenge';
+export { TurnstileError } from '../errors/TurnstileError';
+//# sourceMappingURL=index.d.ts.map

package/dist/exports/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/exports/index.ts"],"names":[],"mappings":"AASA,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,GAClB,MAAM,mDAAmD,CAAC;AAC3D,YAAY,EAAE,sBAAsB,EAAE,MAAM,mDAAmD,CAAC;AAChG,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAExD,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,GACnB,MAAM,qDAAqD,CAAC;AAC7D,YAAY,EAAE,uBAAuB,EAAE,MAAM,qDAAqD,CAAC;AACnG,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC"}