react-native-buzzvil-ad 0.1.0

package/lib/typescript/src/buzzvil.native.d.ts

@@ -0,0 +1,25 @@
+import type { BuzzvilUser, BenefitHubOptions } from './types.js';
+/**
+ * Native (iOS/Android) implementation of the public Buzzvil API. Maps the
+ * friendly types in `./types` onto the primitive-only native spec, applying
+ * the sentinel contract documented in `./NativeBuzzvil`.
+ */
+/** Initialize the BuzzBenefit SDK. Call once, before any other method. */
+export declare function initialize(appId: string): void;
+/**
+ * Dev-only sanity checks for `userId`. Buzzvil requires a non-PII, stable,
+ * ASCII identifier (≤255 chars) — not an email or login id. Returns a list of
+ * human-readable warnings (empty when the id looks fine). Pure: `login` logs
+ * these via `console.warn` only under `__DEV__`; it never alters behavior or
+ * blocks the call (the SDK is the source of truth on acceptance).
+ */
+export declare function userIdWarnings(userId: string): string[];
+/** Log a user in. Resolves on success, rejects on SDK failure. */
+export declare function login(user: BuzzvilUser): Promise<void>;
+/** Log the current user out. */
+export declare function logout(): void;
+/** Whether a user is currently logged in. */
+export declare function isLoggedIn(): Promise<boolean>;
+/** Present the BenefitHub (offerwall) over the current screen. */
+export declare function showBenefitHub(options?: BenefitHubOptions): void;
+//# sourceMappingURL=buzzvil.native.d.ts.map

package/lib/typescript/src/buzzvil.native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buzzvil.native.d.ts","sourceRoot":"","sources":["../../../src/buzzvil.native.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAS,CAAC;AAE9D;;;;GAIG;AAEH,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBvD;AAED,kEAAkE;AAClE,wBAAgB,KAAK,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAOtD;AAED,gCAAgC;AAChC,wBAAgB,MAAM,IAAI,IAAI,CAE7B;AAED,6CAA6C;AAC7C,wBAAgB,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC,CAE7C;AAED,kEAAkE;AAClE,wBAAgB,cAAc,CAAC,OAAO,GAAE,iBAAsB,GAAG,IAAI,CAEpE"}

package/lib/typescript/src/index.d.ts

@@ -0,0 +1,5 @@
+export { initialize, login, logout, isLoggedIn, showBenefitHub, } from './buzzvil';
+export type { BuzzvilUser, BuzzvilGender, BenefitHubOptions } from './types.js';
+export { BuzzvilNativeAdView } from './BuzzvilNativeAdView';
+export type { BuzzvilNativeAdLayout, BuzzvilNativeAdViewProps } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,KAAK,EACL,MAAM,EACN,UAAU,EACV,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAS,CAAC;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,YAAY,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,YAAS,CAAC"}

package/lib/typescript/src/layout.d.ts

@@ -0,0 +1,6 @@
+/** Resolve the default size for a layout; unknown/undefined → `300x250`. */
+export declare function sizeForLayout(layout?: string): {
+    width: number;
+    height: number;
+} | undefined;
+//# sourceMappingURL=layout.d.ts.map

package/lib/typescript/src/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/layout.ts"],"names":[],"mappings":"AAiBA,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM;WATF,MAAM;YAAU,MAAM;cAWhE"}

package/lib/typescript/src/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Public, friendly types for the Buzzvil wrapper. These are the types
+ * consumers see; the native spec (`./NativeBuzzvil`) uses primitives only and
+ * the wrapper (`./buzzvil.native.tsx`) maps between the two.
+ */
+/** Optional demographic hint used by Buzzvil for ad targeting. */
+export type BuzzvilGender = 'MALE' | 'FEMALE';
+/** A Buzzvil user. Only `userId` is required; the rest improve targeting. */
+export interface BuzzvilUser {
+    /** Non-identifiable, persistent user id. ASCII, max 255 chars. */
+    userId: string;
+    gender?: BuzzvilGender;
+    /** 4-digit birth year, e.g. `1990`. */
+    birthYear?: number;
+}
+/** Options for presenting the BenefitHub (offerwall). */
+export interface BenefitHubOptions {
+    /** BenefitHub page number from the Buzzvil admin (advanced routing). */
+    routePath?: string;
+    /** Open directly on the history/earnings page instead of the default hub. */
+    showHistory?: boolean;
+}
+/** Supported Native-ad layout sizes (width x height in dp). */
+export type BuzzvilNativeAdLayout = '320x50' | '320x100' | '320x130' | '300x250' | '320x480';
+/** Friendly props for the `BuzzvilNativeAdView` Fabric component. */
+export interface BuzzvilNativeAdViewProps {
+    unitId: string;
+    layout?: BuzzvilNativeAdLayout;
+    style?: import('react-native').StyleProp<import('react-native').ViewStyle>;
+    onAdLoaded?: (e: {
+        width: number;
+        height: number;
+    }) => void;
+    onAdFailed?: (e: {
+        code: string;
+        message: string;
+    }) => void;
+    onAdClicked?: () => void;
+    onImpressed?: () => void;
+    onRewarded?: (e: {
+        success: boolean;
+    }) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,kEAAkE;AAClE,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE9C,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,+DAA+D;AAC/D,MAAM,MAAM,qBAAqB,GAC7B,QAAQ,GACR,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,CAAC;AAEd,qEAAqE;AACrE,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,KAAK,CAAC,EAAE,OAAO,cAAc,EAAE,SAAS,CAAC,OAAO,cAAc,EAAE,SAAS,CAAC,CAAC;IAC3E,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC5D,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC5D,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;CAChD"}

package/package.json

@@ -0,0 +1,159 @@
+{
+  "name": "react-native-buzzvil-ad",
+  "version": "0.1.0",
+  "description": "Unofficial, community-maintained React Native wrapper for the Buzzvil BuzzBenefit SDK (Android & iOS). Not affiliated with, endorsed by, or supported by Buzzvil.",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.tsx",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "cpp",
+    "*.podspec",
+    "react-native.config.js",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "example": "yarn workspace react-native-buzzvil-example",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
+    "prepare": "bob build",
+    "typecheck": "tsc",
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "test": "jest",
+    "web": "vite",
+    "build:web": "vite build"
+  },
+  "keywords": [
+    "react-native",
+    "ios",
+    "android"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AndrewDongminYoo/react-native-buzzvil.git"
+  },
+  "author": "Dongmin, Yu <ydm2790@gmail.com> (https://github.com/AndrewDongminYoo)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/AndrewDongminYoo/react-native-buzzvil/issues"
+  },
+  "homepage": "https://github.com/AndrewDongminYoo/react-native-buzzvil#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^2.1.0",
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "^10.0.1",
+    "@jest/globals": "^30.0.0",
+    "@react-native/babel-preset": "0.85.0",
+    "@react-native/eslint-config": "0.85.0",
+    "@react-native/jest-preset": "0.85.0",
+    "@types/react": "^19.2.0",
+    "del-cli": "^7.0.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-ft-flow": "^3.0.11",
+    "eslint-plugin-prettier": "^5.5.6",
+    "jest": "^30.3.0",
+    "prettier": "^3.8.3",
+    "react": "19.2.3",
+    "react-native": "0.85.0",
+    "react-native-builder-bob": "^0.42.1",
+    "react-native-web": "~0.21.2",
+    "turbo": "^2.9.16",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  },
+  "resolutions": {
+    "jest": "30.4.1",
+    "jest-cli": "30.4.1",
+    "@jest/core": "30.4.1",
+    "jest-runtime": "30.4.1",
+    "jest-mock": "30.4.1",
+    "jest-environment-node": "30.4.1"
+  },
+  "workspaces": [
+    "example"
+  ],
+  "packageManager": "yarn@4.11.0",
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "codegenConfig": {
+    "name": "BuzzvilSpec",
+    "type": "all",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "com.buzzvil"
+    },
+    "ios": {
+      "components": {
+        "BuzzvilNativeAdView": {
+          "className": "BuzzvilNativeAdView"
+        }
+      }
+    }
+  },
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "jest": {
+    "preset": "@react-native/jest-preset",
+    "modulePathIgnorePatterns": [
+      "<rootDir>/example/node_modules",
+      "<rootDir>/lib/"
+    ]
+  },
+  "create-react-native-library": {
+    "type": "fabric-view",
+    "languages": "kotlin-objc",
+    "tools": [
+      "eslint",
+      "jest",
+      "vite"
+    ],
+    "version": "0.62.2"
+  }
+}

package/src/BuzzvilNativeAdView.native.tsx

@@ -0,0 +1,48 @@
+import NativeComponent from './BuzzvilNativeAdViewNativeComponent';
+import { sizeForLayout } from './layout';
+import type { BuzzvilNativeAdViewProps } from './types';
+
+export { sizeForLayout };
+
+const DEFAULT_LAYOUT = '300x250';
+
+export function toNativeProps(props: BuzzvilNativeAdViewProps) {
+  const {
+    layout,
+    onAdLoaded,
+    onAdFailed,
+    onAdClicked,
+    onImpressed,
+    onRewarded,
+    ...rest
+  } = props;
+  return {
+    ...rest,
+    layout: layout ?? DEFAULT_LAYOUT,
+    onAdLoaded: onAdLoaded
+      ? (e: { nativeEvent: { width: number; height: number } }) =>
+          onAdLoaded(e.nativeEvent)
+      : undefined,
+    onAdFailed: onAdFailed
+      ? (e: { nativeEvent: { code: string; message: string } }) =>
+          onAdFailed(e.nativeEvent)
+      : undefined,
+    // No payload — pass the friendly handler straight through (it ignores the
+    // native event arg). Avoids an empty wrapper that could mislead a future
+    // contributor copying the pattern for a payload-carrying event.
+    onAdClicked,
+    onImpressed,
+    onRewarded: onRewarded
+      ? (e: { nativeEvent: { success: boolean } }) => onRewarded(e.nativeEvent)
+      : undefined,
+  };
+}
+
+export function BuzzvilNativeAdView(props: BuzzvilNativeAdViewProps) {
+  const native = toNativeProps(props);
+  const size = sizeForLayout(props.layout);
+  // Apply the inventory size as a DEFAULT style; the consumer's `style` is
+  // last in the array, so it overrides. `style` is set once here (the explicit
+  // prop wins over the one carried in `native`'s spread).
+  return <NativeComponent {...(native as any)} style={[size, props.style]} />;
+}

package/src/BuzzvilNativeAdView.tsx

@@ -0,0 +1,12 @@
+import { View } from 'react-native';
+import { sizeForLayout } from './layout';
+import type { BuzzvilNativeAdViewProps } from './types';
+
+export function BuzzvilNativeAdView({
+  layout,
+  style,
+}: BuzzvilNativeAdViewProps) {
+  // Buzzvil native ads are not available on web; render nothing visible, but
+  // reserve the same box as native (consumer `style` overrides the default).
+  return <View style={[sizeForLayout(layout), style]} />;
+}

package/src/BuzzvilNativeAdViewNativeComponent.ts

@@ -0,0 +1,22 @@
+import { codegenNativeComponent, type ViewProps } from 'react-native';
+import type { CodegenTypes } from 'react-native';
+
+// Flat primitive payloads — codegen events cannot carry nested objects/enums.
+type AdLoadedEvent = Readonly<{
+  width: CodegenTypes.Double;
+  height: CodegenTypes.Double;
+}>;
+type AdFailedEvent = Readonly<{ code: string; message: string }>;
+type RewardedEvent = Readonly<{ success: boolean }>;
+
+export interface NativeProps extends ViewProps {
+  unitId: string;
+  layout?: string; // friendly union + default live in the JS wrapper; codegen sees a plain string
+  onAdLoaded?: CodegenTypes.DirectEventHandler<AdLoadedEvent>;
+  onAdFailed?: CodegenTypes.DirectEventHandler<AdFailedEvent>;
+  onAdClicked?: CodegenTypes.DirectEventHandler<Readonly<{}>>;
+  onImpressed?: CodegenTypes.DirectEventHandler<Readonly<{}>>;
+  onRewarded?: CodegenTypes.DirectEventHandler<RewardedEvent>;
+}
+
+export default codegenNativeComponent<NativeProps>('BuzzvilNativeAdView');

package/src/NativeBuzzvil.ts

@@ -0,0 +1,76 @@
+import { TurboModuleRegistry, type TurboModule } from 'react-native';
+
+/**
+ * TurboModule spec for the native `Buzzvil` module — a thin bridge over
+ * Buzzvil's BuzzBenefit v6 SDKs (Android / iOS).
+ *
+ * This file is the **source of truth**: codegen generates the native
+ * interfaces from it. The codegen type system is restricted, so the spec
+ * intentionally uses **primitives only** — no optional fields, no object
+ * params, no enums/unions. Friendly types (optional fields, the `'MALE' |
+ * 'FEMALE'` gender union) live in `./types` and are applied in the JS
+ * wrapper (`./buzzvil.native.tsx`).
+ *
+ * ## Sentinel contract (MUST be interpreted identically by both native impls)
+ *
+ * Because the spec has no optionals, the JS wrapper encodes "not provided"
+ * as sentinel values. `BuzzvilModule.kt` and `Buzzvil.mm` must treat them
+ * the same way or the platforms will silently diverge:
+ *
+ * - `gender`: `'MALE'` or `'FEMALE'`. **Empty string `''` → do not set gender**
+ *   (pass `null` to the native user builder).
+ * - `birthYear`: a 4-digit year. **`0` → do not set birth year** (pass `null`).
+ * - `routePath`: a BenefitHub page number from the Buzzvil admin. **`''` → no
+ *   route path** (open the default hub page).
+ * - `showHistory`: `true` → open the BenefitHub history/earnings page
+ *   (Android `BuzzBenefitHubPage.HISTORY` / iOS `.history` query params).
+ */
+export interface Spec extends TurboModule {
+  /**
+   * Initialize the BuzzBenefit SDK with the app's Buzzvil app id.
+   *
+   * - iOS: `BuzzBenefit.shared.initialize(with: BuzzBenefitConfig.Builder(appId:).build())`.
+   * - Android: `BuzzvilSdk.initialize(application, BuzzBenefitConfig.Builder(appId).build())`.
+   *
+   * NOTE (verify at native-impl time): the Android SDK initializes with the
+   * `Application` instance and the docs recommend `Application.onCreate()`
+   * timing. JS-driven init must pass `reactContext.applicationContext as
+   * Application` and run before any `login`/`showBenefitHub` call. If the
+   * Android SDK turns out to require manifest/Application-level setup (as the
+   * AdPopcorn wrapper's `setAppKey` does), this becomes iOS-effective with an
+   * Android no-op — confirm against the running SDK before shipping.
+   */
+  initialize(appId: string): void;
+
+  /**
+   * Log a user into the SDK. Resolves on success, rejects on failure.
+   *
+   * See the sentinel contract above for `gender` / `birthYear`.
+   *
+   * - iOS: `BuzzBenefit.shared.login(with:onSuccess:onFailure:)`.
+   * - Android: `BuzzvilSdk.login(BuzzvilSdkUser(...), BuzzvilSdkLoginListener)`.
+   *
+   * @param userId Non-identifiable, persistent user id. ASCII, max 255 chars.
+   * @param gender `'MALE'` | `'FEMALE'` | `''` (unset).
+   * @param birthYear 4-digit year, or `0` (unset).
+   */
+  login(userId: string, gender: string, birthYear: number): Promise<void>;
+
+  /** Log the current user out. iOS/Android: `logout()`. */
+  logout(): void;
+
+  /** Whether a user is currently logged in. iOS `isLoggedIn()` / Android `isLoggedIn`. */
+  isLoggedIn(): Promise<boolean>;
+
+  /**
+   * Present the BenefitHub (offerwall) over the current screen.
+   *
+   * - iOS: `BuzzBenefitHub().show(on: currentViewController)`.
+   * - Android: `BuzzBenefitHub.show(currentActivity, config)`.
+   *
+   * See the sentinel contract above for `routePath` / `showHistory`.
+   */
+  showBenefitHub(routePath: string, showHistory: boolean): void;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('Buzzvil');

package/src/buzzvil.native.tsx

@@ -0,0 +1,65 @@
+import Buzzvil from './NativeBuzzvil';
+import type { BuzzvilUser, BenefitHubOptions } from './types';
+
+/**
+ * Native (iOS/Android) implementation of the public Buzzvil API. Maps the
+ * friendly types in `./types` onto the primitive-only native spec, applying
+ * the sentinel contract documented in `./NativeBuzzvil`.
+ */
+
+/** Initialize the BuzzBenefit SDK. Call once, before any other method. */
+export function initialize(appId: string): void {
+  Buzzvil.initialize(appId);
+}
+
+/**
+ * Dev-only sanity checks for `userId`. Buzzvil requires a non-PII, stable,
+ * ASCII identifier (≤255 chars) — not an email or login id. Returns a list of
+ * human-readable warnings (empty when the id looks fine). Pure: `login` logs
+ * these via `console.warn` only under `__DEV__`; it never alters behavior or
+ * blocks the call (the SDK is the source of truth on acceptance).
+ */
+export function userIdWarnings(userId: string): string[] {
+  const warnings: string[] = [];
+  if (!userId) {
+    warnings.push('userId is empty.');
+    return warnings;
+  }
+  if (userId.includes('@')) {
+    warnings.push(
+      'userId looks like an email — Buzzvil requires a non-PII, stable identifier (not an email/login id); ads may be rejected.'
+    );
+  }
+  if (userId.length > 255) {
+    warnings.push('userId exceeds 255 characters.');
+  }
+  if ([...userId].some((ch) => ch.charCodeAt(0) > 127)) {
+    warnings.push('userId should be ASCII.');
+  }
+  return warnings;
+}
+
+/** Log a user in. Resolves on success, rejects on SDK failure. */
+export function login(user: BuzzvilUser): Promise<void> {
+  if (__DEV__) {
+    for (const message of userIdWarnings(user.userId)) {
+      console.warn(`[buzzvil] login: ${message}`);
+    }
+  }
+  return Buzzvil.login(user.userId, user.gender ?? '', user.birthYear ?? 0);
+}
+
+/** Log the current user out. */
+export function logout(): void {
+  Buzzvil.logout();
+}
+
+/** Whether a user is currently logged in. */
+export function isLoggedIn(): Promise<boolean> {
+  return Buzzvil.isLoggedIn();
+}
+
+/** Present the BenefitHub (offerwall) over the current screen. */
+export function showBenefitHub(options: BenefitHubOptions = {}): void {
+  Buzzvil.showBenefitHub(options.routePath ?? '', options.showHistory ?? false);
+}

package/src/buzzvil.tsx

@@ -0,0 +1,29 @@
+import type { BuzzvilUser, BenefitHubOptions } from './types';
+
+/**
+ * Web fallback. Buzzvil's BuzzBenefit SDKs are mobile-only, so every method
+ * throws **at call time** (never at import time — importing must not break the
+ * web bundle). The `.native.tsx` counterpart is used on iOS/Android.
+ */
+
+const UNSUPPORTED = 'react-native-buzzvil is not supported on web.';
+
+export function initialize(_appId: string): void {
+  throw new Error(UNSUPPORTED);
+}
+
+export function login(_user: BuzzvilUser): Promise<void> {
+  return Promise.reject(new Error(UNSUPPORTED));
+}
+
+export function logout(): void {
+  throw new Error(UNSUPPORTED);
+}
+
+export function isLoggedIn(): Promise<boolean> {
+  return Promise.reject(new Error(UNSUPPORTED));
+}
+
+export function showBenefitHub(_options: BenefitHubOptions = {}): void {
+  throw new Error(UNSUPPORTED);
+}

package/src/index.tsx

@@ -0,0 +1,10 @@
+export {
+  initialize,
+  login,
+  logout,
+  isLoggedIn,
+  showBenefitHub,
+} from './buzzvil';
+export type { BuzzvilUser, BuzzvilGender, BenefitHubOptions } from './types';
+export { BuzzvilNativeAdView } from './BuzzvilNativeAdView';
+export type { BuzzvilNativeAdLayout, BuzzvilNativeAdViewProps } from './types';

package/src/layout.ts

@@ -0,0 +1,21 @@
+/**
+ * Default inventory sizes for the Native-ad layout variants, shared by the
+ * native and web `BuzzvilNativeAdView` so the box matches on every platform.
+ *
+ * Under Fabric the component's frame comes from the JS shadow node (the
+ * `style`), so the native side's per-size height is only a hint — without a
+ * JS-side height iOS bounds stay 0 and `onAdLoaded` never fires. The wrapper
+ * therefore applies one of these as a DEFAULT style; a consumer `style` wins.
+ */
+const LAYOUT_SIZE: Record<string, { width: number; height: number }> = {
+  '320x50': { width: 320, height: 50 },
+  '320x100': { width: 320, height: 100 },
+  '320x130': { width: 320, height: 130 },
+  '300x250': { width: 300, height: 250 },
+  '320x480': { width: 320, height: 480 },
+};
+
+/** Resolve the default size for a layout; unknown/undefined → `300x250`. */
+export function sizeForLayout(layout?: string) {
+  return LAYOUT_SIZE[layout ?? '300x250'] ?? LAYOUT_SIZE['300x250'];
+}

package/src/types.ts

@@ -0,0 +1,45 @@
+/**
+ * Public, friendly types for the Buzzvil wrapper. These are the types
+ * consumers see; the native spec (`./NativeBuzzvil`) uses primitives only and
+ * the wrapper (`./buzzvil.native.tsx`) maps between the two.
+ */
+
+/** Optional demographic hint used by Buzzvil for ad targeting. */
+export type BuzzvilGender = 'MALE' | 'FEMALE';
+
+/** A Buzzvil user. Only `userId` is required; the rest improve targeting. */
+export interface BuzzvilUser {
+  /** Non-identifiable, persistent user id. ASCII, max 255 chars. */
+  userId: string;
+  gender?: BuzzvilGender;
+  /** 4-digit birth year, e.g. `1990`. */
+  birthYear?: number;
+}
+
+/** Options for presenting the BenefitHub (offerwall). */
+export interface BenefitHubOptions {
+  /** BenefitHub page number from the Buzzvil admin (advanced routing). */
+  routePath?: string;
+  /** Open directly on the history/earnings page instead of the default hub. */
+  showHistory?: boolean;
+}
+
+/** Supported Native-ad layout sizes (width x height in dp). */
+export type BuzzvilNativeAdLayout =
+  | '320x50'
+  | '320x100'
+  | '320x130'
+  | '300x250'
+  | '320x480';
+
+/** Friendly props for the `BuzzvilNativeAdView` Fabric component. */
+export interface BuzzvilNativeAdViewProps {
+  unitId: string;
+  layout?: BuzzvilNativeAdLayout;
+  style?: import('react-native').StyleProp<import('react-native').ViewStyle>;
+  onAdLoaded?: (e: { width: number; height: number }) => void;
+  onAdFailed?: (e: { code: string; message: string }) => void;
+  onAdClicked?: () => void;
+  onImpressed?: () => void;
+  onRewarded?: (e: { success: boolean }) => void;
+}