cloudx-react-native 2.0.0-beta.1

package/src/specs/CloudXAdViewNativeComponent.ts

@@ -0,0 +1,82 @@
+import type { HostComponent, ViewProps } from 'react-native';
+import type { DirectEventHandler, Int32, Double } from 'react-native/Libraries/Types/CodegenTypes';
+import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
+import codegenNativeCommands from 'react-native/Libraries/Utilities/codegenNativeCommands';
+
+/**
+ * Ad info event payload from native.
+ */
+export type AdInfoEvent = Readonly<{
+    adUnitId: string;
+    adFormat: string;
+    networkName: string;
+    networkPlacement: string;
+    placement: string;
+    revenue: Double;
+}>;
+
+/**
+ * Ad error event payload from native.
+ */
+export type AdErrorEvent = Readonly<{
+    adUnitId: string;
+    code: Int32;
+    message: string;
+}>;
+
+/**
+ * Props for CloudXAdView native component.
+ */
+export interface NativeProps extends ViewProps {
+    /** The ad unit ID. */
+    adUnitId?: string | null;
+
+    /** The ad format: "BANNER" or "MREC". */
+    adFormat?: string | null;
+
+    /** Placement name. */
+    placement?: string | null;
+
+    /** Custom data string. */
+    customData?: string | null;
+
+    /** Whether to automatically refresh the ad. */
+    autoRefresh?: boolean;
+
+    /** Whether to load the ad on mount. */
+    loadOnMount?: boolean;
+
+    /** Position for programmatic window-level placement (e.g. "TOP_CENTER", "BOTTOM_CENTER"). */
+    adPosition?: string | null;
+
+    /** Called when ad is loaded. */
+    onAdLoaded?: DirectEventHandler<AdInfoEvent>;
+
+    /** Called when ad fails to load. */
+    onAdLoadFailed?: DirectEventHandler<AdErrorEvent>;
+
+    /** Called when ad is clicked. */
+    onAdClicked?: DirectEventHandler<AdInfoEvent>;
+
+    /** Called when ad expands. */
+    onAdExpanded?: DirectEventHandler<AdInfoEvent>;
+
+    /** Called when ad collapses. */
+    onAdCollapsed?: DirectEventHandler<AdInfoEvent>;
+
+    /** Called when ad revenue is paid. */
+    onAdRevenuePaid?: DirectEventHandler<AdInfoEvent>;
+}
+
+type NativeComponentType = HostComponent<NativeProps>;
+
+interface NativeCommands {
+    loadAd: (viewRef: React.ElementRef<NativeComponentType>) => void;
+    destroy: (viewRef: React.ElementRef<NativeComponentType>) => void;
+}
+
+export const Commands = codegenNativeCommands<NativeCommands>({
+    supportedCommands: ['loadAd', 'destroy'],
+});
+
+export default codegenNativeComponent<NativeProps>('CloudXAdView') as NativeComponentType;

package/src/specs/NativeCloudXModule.ts

@@ -0,0 +1,162 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+/**
+ * TurboModule spec for the CloudX native module.
+ *
+ * This spec defines every native method exposed to JavaScript.
+ * Codegen uses this to produce type-safe native bindings.
+ *
+ * All methods correspond 1-to-1 with public APIs in the native iOS SDK
+ * (CloudXCore 2.1.0-beta) and the native Android SDK.
+ */
+export interface Spec extends TurboModule {
+    // =========================================================================
+    // Event Emitter (required by NativeEventEmitter)
+    // =========================================================================
+
+    addListener(eventName: string): void;
+    removeListeners(count: number): void;
+
+    // =========================================================================
+    // Initialization
+    // =========================================================================
+
+    initialize(pluginVersion: string, appKey: string): Promise<Object>;
+    isInitialized(): Promise<boolean>;
+    isTablet(): Promise<boolean>;
+    getVersion(): Promise<string>;
+
+    // =========================================================================
+    // Configuration
+    // =========================================================================
+
+    setMinLogLevel(level: string): void;
+    setVisualDebuggingEnabled(enabled: boolean): void;
+
+    // =========================================================================
+    // User Targeting
+    // =========================================================================
+
+    setHashedUserID(hashedUserID: string): void;
+    setUserKeyValue(key: string, value: string): void;
+    setAppKeyValue(key: string, value: string): void;
+    clearAllKeyValues(): void;
+
+    // =========================================================================
+    // Banner (Programmatic)
+    // =========================================================================
+
+    createBanner(adUnitId: string, position: string): void;
+    createBannerWithOffsets(adUnitId: string, position: string, xOffset: number, yOffset: number): void;
+    showBanner(adUnitId: string): void;
+    hideBanner(adUnitId: string): void;
+    destroyBanner(adUnitId: string): void;
+    setBannerPlacement(adUnitId: string, placement: string | null): void;
+    setBannerCustomData(adUnitId: string, customData: string | null): void;
+    startBannerAutoRefresh(adUnitId: string): void;
+    stopBannerAutoRefresh(adUnitId: string): void;
+    updateBannerPosition(adUnitId: string, position: string): void;
+    updateBannerOffsets(adUnitId: string, xOffset: number, yOffset: number): void;
+    setBannerBackgroundColor(adUnitId: string, hexColorString: string): void;
+
+    // =========================================================================
+    // MREC (Programmatic)
+    // =========================================================================
+
+    createMRec(adUnitId: string, position: string): void;
+    createMRecWithOffsets(adUnitId: string, position: string, xOffset: number, yOffset: number): void;
+    showMRec(adUnitId: string): void;
+    hideMRec(adUnitId: string): void;
+    destroyMRec(adUnitId: string): void;
+    setMRecPlacement(adUnitId: string, placement: string | null): void;
+    setMRecCustomData(adUnitId: string, customData: string | null): void;
+    startMRecAutoRefresh(adUnitId: string): void;
+    stopMRecAutoRefresh(adUnitId: string): void;
+    updateMRecPosition(adUnitId: string, position: string): void;
+    updateMRecOffsets(adUnitId: string, xOffset: number, yOffset: number): void;
+    setMRecBackgroundColor(adUnitId: string, hexColorString: string): void;
+
+    // =========================================================================
+    // Interstitial
+    // =========================================================================
+
+    loadInterstitial(adUnitId: string): void;
+    isInterstitialReady(adUnitId: string): Promise<boolean>;
+    showInterstitial(adUnitId: string, placement?: string | null, customData?: string | null): void;
+    destroyInterstitial(adUnitId: string): void;
+
+    // =========================================================================
+    // Rewarded
+    // =========================================================================
+
+    loadRewarded(adUnitId: string): void;
+    isRewardedReady(adUnitId: string): Promise<boolean>;
+    showRewarded(adUnitId: string, placement?: string | null, customData?: string | null): void;
+    destroyRewarded(adUnitId: string): void;
+
+    // =========================================================================
+    // Constants (event names, positions, error codes)
+    // =========================================================================
+
+    getConstants(): {
+        // Banner events
+        ON_BANNER_AD_LOADED_EVENT: string;
+        ON_BANNER_AD_LOAD_FAILED_EVENT: string;
+        ON_BANNER_AD_CLICKED_EVENT: string;
+        ON_BANNER_AD_EXPANDED_EVENT: string;
+        ON_BANNER_AD_COLLAPSED_EVENT: string;
+        ON_BANNER_AD_REVENUE_PAID: string;
+
+        // MREC events
+        ON_MREC_AD_LOADED_EVENT: string;
+        ON_MREC_AD_LOAD_FAILED_EVENT: string;
+        ON_MREC_AD_CLICKED_EVENT: string;
+        ON_MREC_AD_EXPANDED_EVENT: string;
+        ON_MREC_AD_COLLAPSED_EVENT: string;
+        ON_MREC_AD_REVENUE_PAID: string;
+
+        // Interstitial events
+        ON_INTERSTITIAL_LOADED_EVENT: string;
+        ON_INTERSTITIAL_LOAD_FAILED_EVENT: string;
+        ON_INTERSTITIAL_CLICKED_EVENT: string;
+        ON_INTERSTITIAL_DISPLAYED_EVENT: string;
+        ON_INTERSTITIAL_DISPLAY_FAILED_EVENT: string;
+        ON_INTERSTITIAL_HIDDEN_EVENT: string;
+        ON_INTERSTITIAL_AD_REVENUE_PAID: string;
+
+        // Rewarded events
+        ON_REWARDED_AD_LOADED_EVENT: string;
+        ON_REWARDED_AD_LOAD_FAILED_EVENT: string;
+        ON_REWARDED_AD_CLICKED_EVENT: string;
+        ON_REWARDED_AD_DISPLAYED_EVENT: string;
+        ON_REWARDED_AD_DISPLAY_FAILED_EVENT: string;
+        ON_REWARDED_AD_HIDDEN_EVENT: string;
+        ON_REWARDED_AD_RECEIVED_REWARD_EVENT: string;
+        ON_REWARDED_AD_REVENUE_PAID: string;
+
+        // Position constants
+        TOP_LEFT_POSITION: string;
+        TOP_CENTER_POSITION: string;
+        TOP_RIGHT_POSITION: string;
+        CENTER_LEFT_POSITION: string;
+        CENTERED_POSITION: string;
+        CENTER_RIGHT_POSITION: string;
+        BOTTOM_LEFT_POSITION: string;
+        BOTTOM_CENTER_POSITION: string;
+        BOTTOM_RIGHT_POSITION: string;
+
+        // Error code constants
+        ERROR_CODE_INTERNAL_ERROR: number;
+        ERROR_CODE_NETWORK_ERROR: number;
+        ERROR_CODE_NETWORK_TIMEOUT: number;
+        ERROR_CODE_NO_FILL: number;
+        ERROR_CODE_AD_NOT_READY: number;
+        ERROR_CODE_AD_ALREADY_SHOWING: number;
+        ERROR_CODE_INVALID_AD_UNIT: number;
+        ERROR_CODE_NOT_INITIALIZED: number;
+        ERROR_CODE_NO_CONNECTION: number;
+    };
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('CloudXModule');

package/src/types/AdEvent.ts

@@ -0,0 +1,11 @@
+/**
+ * Represents any ad event object emitted by the native module.
+ */
+import type { AdInfo, AdLoadFailedInfo, AdDisplayFailedInfo, AdRewardInfo } from './AdInfo';
+
+export type AdEventObject = AdInfo | AdLoadFailedInfo | AdDisplayFailedInfo | AdRewardInfo;
+
+/**
+ * Generic ad event listener callback type.
+ */
+export type AdEventListener<T extends AdEventObject = AdEventObject> = (event: T) => void;

package/src/types/AdInfo.ts

@@ -0,0 +1,60 @@
+import type { ErrorCode } from '../ErrorCode';
+
+/**
+ * Represents a successfully loaded ad served by CloudX.
+ */
+export type AdInfo = {
+    /** The ad unit ID for this ad. */
+    adUnitId: string;
+
+    /** The format of the ad (e.g., "BANNER", "MREC", "INTERSTITIAL", "REWARDED"). */
+    adFormat: string;
+
+    /** The name of the ad network that served the ad. */
+    networkName: string;
+
+    /** The name of the placement as configured on the ad network side. */
+    networkPlacement?: string | null;
+
+    /** The custom placement name defined in your integration. */
+    placement?: string | null;
+
+    /** The revenue generated from the ad impression, in USD. Defaults to 0. */
+    revenue: number;
+};
+
+/**
+ * Represents a failure when attempting to load an ad.
+ */
+export type AdLoadFailedInfo = {
+    /** The ad unit ID for which the load failed. */
+    adUnitId: string;
+
+    /** CloudX error code. */
+    code: ErrorCode;
+
+    /** Descriptive error message. */
+    message?: string | null;
+};
+
+/**
+ * Represents an error that occurred when displaying an ad.
+ */
+export type AdDisplayFailedInfo = AdInfo & {
+    /** CloudX error code. */
+    code: ErrorCode;
+
+    /** Descriptive error message. */
+    message?: string | null;
+};
+
+/**
+ * Represents a successful reward event from a rewarded ad.
+ */
+export type AdRewardInfo = AdInfo & {
+    /** The label of the reward. */
+    rewardLabel?: string | null;
+
+    /** The reward amount. */
+    rewardAmount: number;
+};

package/src/types/BannerAd.ts

@@ -0,0 +1,59 @@
+import type { AdInfo, AdLoadFailedInfo } from './AdInfo';
+
+/**
+ * Position constants for programmatic banner placement.
+ */
+export type AdViewPositionType =
+    | 'top_left'
+    | 'top_center'
+    | 'top_right'
+    | 'center_left'
+    | 'centered'
+    | 'center_right'
+    | 'bottom_left'
+    | 'bottom_center'
+    | 'bottom_right';
+
+/**
+ * Programmatic banner ad interface.
+ */
+export type BannerAdType = {
+    createAd(adUnitId: string, position: AdViewPositionType): void;
+    createAdWithOffsets(adUnitId: string, position: AdViewPositionType, xOffset: number, yOffset: number): void;
+    destroyAd(adUnitId: string): void;
+    showAd(adUnitId: string): void;
+    hideAd(adUnitId: string): void;
+
+    updatePosition(adUnitId: string, position: AdViewPositionType): void;
+    updateOffsets(adUnitId: string, xOffset: number, yOffset: number): void;
+    setBackgroundColor(adUnitId: string, hexColorString: string): void;
+
+    setPlacement(adUnitId: string, placement: string | null): void;
+    setCustomData(adUnitId: string, customData: string | null): void;
+
+    startAutoRefresh(adUnitId: string): void;
+    stopAutoRefresh(adUnitId: string): void;
+
+    addAdLoadedEventListener(listener: (adInfo: AdInfo) => void): void;
+    removeAdLoadedEventListener(): void;
+
+    addAdLoadFailedEventListener(listener: (errorInfo: AdLoadFailedInfo) => void): void;
+    removeAdLoadFailedEventListener(): void;
+
+    addAdClickedEventListener(listener: (adInfo: AdInfo) => void): void;
+    removeAdClickedEventListener(): void;
+
+    addAdExpandedEventListener(listener: (adInfo: AdInfo) => void): void;
+    removeAdExpandedEventListener(): void;
+
+    addAdCollapsedEventListener(listener: (adInfo: AdInfo) => void): void;
+    removeAdCollapsedEventListener(): void;
+
+    addAdRevenuePaidListener(listener: (adInfo: AdInfo) => void): void;
+    removeAdRevenuePaidListener(): void;
+};
+
+/**
+ * MREC ad type is identical to Banner in terms of API surface.
+ */
+export type MRecAdType = BannerAdType;

package/src/types/CloudX.ts

@@ -0,0 +1,33 @@
+import type { Configuration } from './Configuration';
+
+/**
+ * Main CloudX SDK module interface.
+ */
+export type CloudXType = {
+    /** Initializes the CloudX SDK with the given app key. */
+    initialize(appKey: string): Promise<Configuration>;
+
+    /** Returns whether the SDK has been initialized. */
+    isInitialized(): Promise<boolean>;
+
+    /** Returns the native SDK version string. */
+    getVersion(): Promise<string>;
+
+    /** Sets the minimum log level for CloudX SDK logging. */
+    setMinLogLevel(level: string): void;
+
+    /** Sets a hashed user ID for targeting. */
+    setHashedUserID(hashedUserID: string): void;
+
+    /** Sets a user-level key-value pair for targeting. */
+    setUserKeyValue(key: string, value: string): void;
+
+    /** Sets an app-level key-value pair for targeting. */
+    setAppKeyValue(key: string, value: string): void;
+
+    /** Clears all targeting key-values. */
+    clearAllKeyValues(): void;
+
+    /** Enables or disables visual debugging overlay (iOS only; no-op on Android). */
+    setVisualDebuggingEnabled(enabled: boolean): void;
+};

package/src/types/Configuration.ts

@@ -0,0 +1,10 @@
+/**
+ * SDK configuration returned after successful initialization.
+ */
+export type Configuration = {
+    /** Whether initialization was successful. */
+    success: boolean;
+
+    /** Optional message with additional details. */
+    message?: string | null;
+};

package/src/types/FullscreenAd.ts

@@ -0,0 +1,39 @@
+import type { AdDisplayFailedInfo, AdInfo, AdLoadFailedInfo } from './AdInfo';
+
+/**
+ * Shared interface for fullscreen ad types (Interstitial, Rewarded).
+ */
+export type FullscreenAdType = {
+    /** Returns whether an ad is ready to display. */
+    isAdReady(adUnitId: string): Promise<boolean>;
+
+    /** Loads an ad for the given ad unit. */
+    loadAd(adUnitId: string): void;
+
+    /** Shows a previously loaded ad. */
+    showAd(adUnitId: string, placement?: string | null, customData?: string | null): void;
+
+    /** Destroys the ad instance and frees resources. */
+    destroyAd(adUnitId: string): void;
+
+    addAdLoadedEventListener(listener: (adInfo: AdInfo) => void): void;
+    removeAdLoadedEventListener(): void;
+
+    addAdLoadFailedEventListener(listener: (errorInfo: AdLoadFailedInfo) => void): void;
+    removeAdLoadFailedEventListener(): void;
+
+    addAdClickedEventListener(listener: (adInfo: AdInfo) => void): void;
+    removeAdClickedEventListener(): void;
+
+    addAdDisplayedEventListener(listener: (adInfo: AdInfo) => void): void;
+    removeAdDisplayedEventListener(): void;
+
+    addAdFailedToDisplayEventListener(listener: (errorInfo: AdDisplayFailedInfo) => void): void;
+    removeAdFailedToDisplayEventListener(): void;
+
+    addAdHiddenEventListener(listener: (adInfo: AdInfo) => void): void;
+    removeAdHiddenEventListener(): void;
+
+    addAdRevenuePaidListener(listener: (adInfo: AdInfo) => void): void;
+    removeAdRevenuePaidListener(): void;
+};

package/src/types/RewardedAd.ts

@@ -0,0 +1,10 @@
+import type { AdRewardInfo } from './AdInfo';
+import type { FullscreenAdType } from './FullscreenAd';
+
+/**
+ * Rewarded ad interface, extending fullscreen ad with reward listener.
+ */
+export type RewardedAdType = FullscreenAdType & {
+    addAdReceivedRewardEventListener(listener: (rewardInfo: AdRewardInfo) => void): void;
+    removeAdReceivedRewardEventListener(): void;
+};

package/src/types/index.ts

@@ -0,0 +1,7 @@
+export type { AdInfo, AdLoadFailedInfo, AdDisplayFailedInfo, AdRewardInfo } from './AdInfo';
+export type { Configuration } from './Configuration';
+export type { CloudXType } from './CloudX';
+export type { FullscreenAdType } from './FullscreenAd';
+export type { RewardedAdType } from './RewardedAd';
+export type { BannerAdType, MRecAdType, AdViewPositionType } from './BannerAd';
+export type { AdEventObject, AdEventListener } from './AdEvent';