@amplytools/react-native-amply-sdk 0.13.0 → 0.15.0

package/ios/Sources/AmplyReactNative/AmplyReactNative/AmplyReactNative-generated.mm

@@ -80,6 +80,10 @@ namespace facebook::react {
       return static_cast<ObjCTurboModule&>(turboModule).invokeObjCMethod(rt, PromiseKind, "getRecentEvents", @selector(getRecentEvents:resolve:reject:), args, count);
     }
 
+    static facebook::jsi::Value __hostFunction_NativeAmplyModuleSpecJSI_getLastCampaignTouch(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {
+      return static_cast<ObjCTurboModule&>(turboModule).invokeObjCMethod(rt, PromiseKind, "getLastCampaignTouch", @selector(getLastCampaignTouch:resolve:reject:), args, count);
+    }
+
     static facebook::jsi::Value __hostFunction_NativeAmplyModuleSpecJSI_getDataSetSnapshot(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {
       return static_cast<ObjCTurboModule&>(turboModule).invokeObjCMethod(rt, PromiseKind, "getDataSetSnapshot", @selector(getDataSetSnapshot:resolve:reject:), args, count);
     }
@@ -92,6 +96,14 @@ namespace facebook::react {
       return static_cast<ObjCTurboModule&>(turboModule).invokeObjCMethod(rt, VoidKind, "setUserId", @selector(setUserId:), args, count);
     }
 
+    static facebook::jsi::Value __hostFunction_NativeAmplyModuleSpecJSI_setAppLanguage(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {
+      return static_cast<ObjCTurboModule&>(turboModule).invokeObjCMethod(rt, VoidKind, "setAppLanguage", @selector(setAppLanguage:), args, count);
+    }
+
+    static facebook::jsi::Value __hostFunction_NativeAmplyModuleSpecJSI_handleUrl(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {
+      return static_cast<ObjCTurboModule&>(turboModule).invokeObjCMethod(rt, BooleanKind, "handleUrl", @selector(handleUrl:), args, count);
+    }
+
     static facebook::jsi::Value __hostFunction_NativeAmplyModuleSpecJSI_setLogLevel(facebook::jsi::Runtime& rt, TurboModule &turboModule, const facebook::jsi::Value* args, size_t count) {
       return static_cast<ObjCTurboModule&>(turboModule).invokeObjCMethod(rt, VoidKind, "setLogLevel", @selector(setLogLevel:), args, count);
     }
@@ -151,6 +163,9 @@ namespace facebook::react {
         methodMap_["getRecentEvents"] = MethodMetadata {1, __hostFunction_NativeAmplyModuleSpecJSI_getRecentEvents};
         
         
+        methodMap_["getLastCampaignTouch"] = MethodMetadata {1, __hostFunction_NativeAmplyModuleSpecJSI_getLastCampaignTouch};
+        
+        
         methodMap_["getDataSetSnapshot"] = MethodMetadata {1, __hostFunction_NativeAmplyModuleSpecJSI_getDataSetSnapshot};
         
         
@@ -160,6 +175,12 @@ namespace facebook::react {
         methodMap_["setUserId"] = MethodMetadata {1, __hostFunction_NativeAmplyModuleSpecJSI_setUserId};
         
         
+        methodMap_["setAppLanguage"] = MethodMetadata {1, __hostFunction_NativeAmplyModuleSpecJSI_setAppLanguage};
+        
+        
+        methodMap_["handleUrl"] = MethodMetadata {1, __hostFunction_NativeAmplyModuleSpecJSI_handleUrl};
+        
+        
         methodMap_["setLogLevel"] = MethodMetadata {1, __hostFunction_NativeAmplyModuleSpecJSI_setLogLevel};
         
         

package/ios/Sources/AmplyReactNative/AmplyReactNative/AmplyReactNative.h

@@ -44,6 +44,7 @@ namespace JS {
       NSString *defaultConfig() const;
       std::optional<bool> debug() const;
       NSString *logLevel() const;
+      NSString *appLanguage() const;
 
       AmplyInitializationConfig(NSDictionary *const v) : _v(v) {}
     private:
@@ -93,11 +94,16 @@ namespace JS {
 - (void)getRecentEvents:(double)limit
                 resolve:(RCTPromiseResolveBlock)resolve
                  reject:(RCTPromiseRejectBlock)reject;
+- (void)getLastCampaignTouch:(double)withinMs
+                     resolve:(RCTPromiseResolveBlock)resolve
+                      reject:(RCTPromiseRejectBlock)reject;
 - (void)getDataSetSnapshot:(NSDictionary *)type
                    resolve:(RCTPromiseResolveBlock)resolve
                     reject:(RCTPromiseRejectBlock)reject;
 - (void)registerDeepLinkListener;
 - (void)setUserId:(NSString * _Nullable)userId;
+- (void)setAppLanguage:(NSString * _Nullable)tag;
+- (NSNumber *)handleUrl:(NSString *)url;
 - (void)setLogLevel:(NSString *)level;
 - (NSString *)getLogLevel;
 - (void)setCustomProperties:(NSDictionary *)properties;
@@ -176,6 +182,11 @@ inline NSString *JS::NativeAmplyModule::AmplyInitializationConfig::logLevel() co
   id const p = _v[@"logLevel"];
   return RCTBridgingToOptionalString(p);
 }
+inline NSString *JS::NativeAmplyModule::AmplyInitializationConfig::appLanguage() const
+{
+  id const p = _v[@"appLanguage"];
+  return RCTBridgingToOptionalString(p);
+}
 inline NSString *JS::NativeAmplyModule::TrackEventPayload::name() const
 {
   id const p = _v[@"name"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amplytools/react-native-amply-sdk",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "React Native SDK for Amply: Mobile SDK to orchestrate in-app experiences and campaigns remotely, without app releases",
   "license": "MIT",
   "repository": {

package/src/__tests__/appLanguage.test.ts

@@ -0,0 +1,298 @@
+/**
+ * `setAppLanguage` and the `appLanguage` initialization option.
+ *
+ * The SDK treats both as one setting with "last write wins": `appLanguage` in the config is the
+ * same as calling `setAppLanguage` at initialization. The native bridges cannot honour that order
+ * on their own for a call made BEFORE `initialize` — they buffer it and replay it after the SDK is
+ * built, which would let an earlier call overwrite the later config value. So the JS layer parks a
+ * pre-init call itself and folds it into the config it hands to native.
+ *
+ * Each test loads a fresh copy of the module: the parked value is module state, and leaking it
+ * from one test into the next would make every ordering assertion here meaningless.
+ */
+type AmplyModule = typeof import('../index');
+
+function createNativeModule() {
+  let initialized = false;
+  return {
+    initialize: jest.fn(async () => {
+      initialized = true;
+    }),
+    isInitialized: jest.fn(() => initialized),
+    setAppLanguage: jest.fn(),
+    setUserId: jest.fn(),
+    addListener: jest.fn(),
+    removeListeners: jest.fn(),
+    onSystemEvent: jest.fn(() => ({remove: jest.fn()})),
+    onDeepLink: jest.fn(() => ({remove: jest.fn()})),
+    onCampaignPresent: jest.fn(() => ({remove: jest.fn()})),
+    /** Test-only: pretend the SDK is (or is not) up without going through initialize. */
+    setInitialized(value: boolean) {
+      initialized = value;
+    },
+  };
+}
+
+type NativeModuleMock = ReturnType<typeof createNativeModule>;
+
+const KEYS = {appId: 'id', apiKeyPublic: 'public', apiKeySecret: 'secret'};
+
+function load(): {Amply: AmplyModule; native: NativeModuleMock} {
+  let Amply!: AmplyModule;
+  const native = createNativeModule();
+  jest.isolateModules(() => {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    require('../nativeModule').__setNativeModule(native as never);
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    Amply = require('../index');
+  });
+  return {Amply, native};
+}
+
+describe('setAppLanguage after initialization', () => {
+  it.each(['pt_BR', 'zh-TW', 'FR', 'Français'])(
+    'forwards %p to the native SDK verbatim — parsing and the warning for junk are the SDK’s job',
+    tag => {
+      const {Amply, native} = load();
+      native.setInitialized(true);
+
+      Amply.setAppLanguage(tag);
+
+      expect(native.setAppLanguage).toHaveBeenCalledTimes(1);
+      expect(native.setAppLanguage).toHaveBeenCalledWith(tag);
+    },
+  );
+
+  it('forwards null, which returns the SDK to automatic detection', () => {
+    const {Amply, native} = load();
+    native.setInitialized(true);
+
+    Amply.setAppLanguage(null);
+
+    expect(native.setAppLanguage).toHaveBeenCalledWith(null);
+  });
+
+  it('is on the default export as well', () => {
+    const {Amply, native} = load();
+    native.setInitialized(true);
+
+    Amply.default.setAppLanguage('de');
+
+    expect(native.setAppLanguage).toHaveBeenCalledWith('de');
+  });
+});
+
+describe('appLanguage in the initialization config', () => {
+  it('is passed through to the native initialize', async () => {
+    const {Amply, native} = load();
+
+    await Amply.initialize({...KEYS, appLanguage: 'pt_BR'});
+
+    expect(native.initialize).toHaveBeenCalledWith(expect.objectContaining({appLanguage: 'pt_BR'}));
+    expect(native.setAppLanguage).not.toHaveBeenCalled();
+  });
+
+  it('is left out of the native config when the caller did not give one', async () => {
+    const {Amply, native} = load();
+
+    await Amply.initialize(KEYS);
+
+    const [config] = native.initialize.mock.calls[0] as unknown as [Record<string, unknown>];
+    expect(config).not.toHaveProperty('appLanguage');
+  });
+});
+
+describe('setAppLanguage before initialization', () => {
+  it('is not sent to a native SDK that is not up yet', () => {
+    const {Amply, native} = load();
+
+    Amply.setAppLanguage('fr');
+
+    expect(native.setAppLanguage).not.toHaveBeenCalled();
+  });
+
+  it('reaches the SDK as the config appLanguage when initialize names none', async () => {
+    const {Amply, native} = load();
+    Amply.setAppLanguage('fr');
+
+    await Amply.initialize(KEYS);
+
+    expect(native.initialize).toHaveBeenCalledWith(expect.objectContaining({appLanguage: 'fr'}));
+    expect(native.setAppLanguage).not.toHaveBeenCalled();
+  });
+
+  it('keeps only the last of several calls', async () => {
+    const {Amply, native} = load();
+    Amply.setAppLanguage('fr');
+    Amply.setAppLanguage('de');
+
+    await Amply.initialize(KEYS);
+
+    expect(native.initialize).toHaveBeenCalledWith(expect.objectContaining({appLanguage: 'de'}));
+  });
+
+  it('loses to an appLanguage given to the later initialize call', async () => {
+    const {Amply, native} = load();
+    Amply.setAppLanguage('fr');
+
+    await Amply.initialize({...KEYS, appLanguage: 'de'});
+
+    expect(native.initialize).toHaveBeenCalledWith(expect.objectContaining({appLanguage: 'de'}));
+    expect(native.setAppLanguage).not.toHaveBeenCalled();
+  });
+
+  it('wins over a blank appLanguage in the config, which names no language', async () => {
+    const {Amply, native} = load();
+    Amply.setAppLanguage('fr');
+
+    await Amply.initialize({...KEYS, appLanguage: '  '});
+
+    expect(native.initialize).toHaveBeenCalledWith(expect.objectContaining({appLanguage: 'fr'}));
+  });
+
+  // null cannot travel in the config — there it means "leave the setting alone" — so a parked
+  // clear is applied as a call once the SDK is up.
+  it('applies a parked null right after initialization', async () => {
+    const {Amply, native} = load();
+    Amply.setAppLanguage(null);
+
+    await Amply.initialize(KEYS);
+
+    const [config] = native.initialize.mock.calls[0] as unknown as [Record<string, unknown>];
+    expect(config).not.toHaveProperty('appLanguage');
+    expect(native.setAppLanguage).toHaveBeenCalledTimes(1);
+    expect(native.setAppLanguage).toHaveBeenCalledWith(null);
+  });
+
+  it('drops a parked null when the later initialize names a language', async () => {
+    const {Amply, native} = load();
+    Amply.setAppLanguage(null);
+
+    await Amply.initialize({...KEYS, appLanguage: 'de'});
+
+    expect(native.initialize).toHaveBeenCalledWith(expect.objectContaining({appLanguage: 'de'}));
+    expect(native.setAppLanguage).not.toHaveBeenCalled();
+  });
+
+  it('survives an initialize that fails, and is used by the retry', async () => {
+    const {Amply, native} = load();
+    Amply.setAppLanguage('fr');
+    native.initialize.mockImplementationOnce(async () => {
+      throw new Error('AMP_INIT_FAILED');
+    });
+
+    await expect(Amply.initialize(KEYS)).rejects.toThrow('AMP_INIT_FAILED');
+    await Amply.initialize(KEYS);
+
+    expect(native.initialize).toHaveBeenLastCalledWith(expect.objectContaining({appLanguage: 'fr'}));
+  });
+
+  it('survives an initialize rejected for a missing key', async () => {
+    const {Amply, native} = load();
+    const error = jest.spyOn(console, 'error').mockImplementation(() => {});
+    Amply.setAppLanguage('fr');
+
+    await expect(Amply.initialize({...KEYS, apiKeySecret: ''})).rejects.toMatchObject({
+      code: 'AMP_INVALID_CONFIG',
+    });
+    await Amply.initialize(KEYS);
+
+    expect(native.initialize).toHaveBeenCalledTimes(1);
+    expect(native.initialize).toHaveBeenCalledWith(expect.objectContaining({appLanguage: 'fr'}));
+    error.mockRestore();
+  });
+});
+
+describe('setAppLanguage while initialize is in flight', () => {
+  it('is applied after initialization, so it wins over the config value it came after', async () => {
+    const {Amply, native} = load();
+    let finishInit!: () => void;
+    native.initialize.mockImplementationOnce(
+      () =>
+        new Promise<void>(resolve => {
+          finishInit = () => {
+            native.setInitialized(true);
+            resolve();
+          };
+        }),
+    );
+
+    const init = Amply.initialize({...KEYS, appLanguage: 'de'});
+    Amply.setAppLanguage('fr');
+    expect(native.setAppLanguage).not.toHaveBeenCalled();
+    finishInit();
+    await init;
+
+    expect(native.initialize).toHaveBeenCalledWith(expect.objectContaining({appLanguage: 'de'}));
+    expect(native.setAppLanguage).toHaveBeenCalledTimes(1);
+    expect(native.setAppLanguage).toHaveBeenCalledWith('fr');
+  });
+
+  // The native SDK reports itself up before the initialize promise settles, so a call made in
+  // that window goes straight through. A value held from before initialize is older than it and
+  // must not be replayed over it when the promise finally resolves.
+  function hangInitialize(native: NativeModuleMock): {
+    comeUp: () => void;
+    resolve: () => void;
+    reject: (error: Error) => void;
+  } {
+    const control = {comeUp: () => {}, resolve: () => {}, reject: (_error: Error) => {}};
+    native.initialize.mockImplementationOnce(
+      () =>
+        new Promise<void>((resolve, reject) => {
+          control.comeUp = () => native.setInitialized(true);
+          control.resolve = resolve;
+          control.reject = reject;
+        }),
+    );
+    return control;
+  }
+
+  it('does not replay an older held null over a call the SDK already received', async () => {
+    const {Amply, native} = load();
+    Amply.setAppLanguage(null);
+    const init = hangInitialize(native);
+
+    const pending = Amply.initialize(KEYS);
+    init.comeUp();
+    Amply.setAppLanguage('fr');
+    init.resolve();
+    await pending;
+
+    expect(native.setAppLanguage.mock.calls).toEqual([['fr']]);
+  });
+
+  it('does not replay an older held tag over a call the SDK already received', async () => {
+    const {Amply, native} = load();
+    const init = hangInitialize(native);
+
+    const pending = Amply.initialize(KEYS);
+    Amply.setAppLanguage('de');
+    init.comeUp();
+    Amply.setAppLanguage('fr');
+    init.resolve();
+    await pending;
+
+    expect(native.setAppLanguage.mock.calls).toEqual([['fr']]);
+  });
+
+  it('does not hand a superseded held tag to the retry of a failed initialize', async () => {
+    const {Amply, native} = load();
+    Amply.setAppLanguage('de');
+    const init = hangInitialize(native);
+
+    const pending = Amply.initialize(KEYS);
+    init.comeUp();
+    Amply.setAppLanguage('fr');
+    init.reject(new Error('AMP_INIT_FAILED'));
+    await expect(pending).rejects.toThrow('AMP_INIT_FAILED');
+    native.setInitialized(false);
+    await Amply.initialize(KEYS);
+
+    const [retryConfig] = native.initialize.mock.calls[1] as unknown as [Record<string, unknown>];
+    expect(retryConfig).not.toHaveProperty('appLanguage');
+    expect(native.setAppLanguage.mock.calls).toEqual([['fr']]);
+  });
+});
+
+export {};

package/src/__tests__/handleUrl.test.ts

@@ -0,0 +1,155 @@
+/**
+ * `handleUrl` hands an incoming link to the native SDK and reports whether the SDK recognised it.
+ * It is synchronous, and it never throws: an older native build without the method answers false.
+ */
+type SdkModule = typeof import('../index');
+
+function loadWith(native: Record<string, unknown>): SdkModule {
+  // Absent isInitialized means "SDK up" for the plain pass-through tests below.
+  const withState = {isInitialized: () => true, ...native};
+  let Amply!: SdkModule;
+  jest.isolateModules(() => {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    require('../nativeModule').__setNativeModule(withState as never);
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    Amply = require('../index');
+  });
+  return Amply;
+}
+
+const DEBUG_URL = 'myapp://amply-debug/campaign?t=abc';
+
+describe('handleUrl', () => {
+  it('passes the DEBUG_URL to the native module and returns its answer', () => {
+    const handleUrl = jest.fn(() => true);
+    const Amply = loadWith({handleUrl});
+
+    expect(Amply.handleUrl(DEBUG_URL)).toBe(true);
+    expect(handleUrl).toHaveBeenCalledWith(DEBUG_URL);
+  });
+
+  it('returns false when the native module does not recognise the DEBUG_URL', () => {
+    const Amply = loadWith({handleUrl: jest.fn(() => false)});
+
+    expect(Amply.handleUrl('myapp://settings')).toBe(false);
+  });
+
+  it('returns false without throwing when the native module has no handleUrl', () => {
+    const Amply = loadWith({});
+
+    expect(Amply.handleUrl(DEBUG_URL)).toBe(false);
+  });
+
+  it('returns false without throwing when the native call throws', () => {
+    const Amply = loadWith({
+      handleUrl: jest.fn(() => {
+        throw new Error('boom');
+      }),
+    });
+
+    expect(Amply.handleUrl(DEBUG_URL)).toBe(false);
+  });
+
+  it('returns false for a non-string DEBUG_URL', () => {
+    const handleUrl = jest.fn(() => true);
+    const Amply = loadWith({handleUrl});
+
+    expect(Amply.handleUrl(null as never)).toBe(false);
+    expect(handleUrl).not.toHaveBeenCalled();
+  });
+
+  it('is on the default export', () => {
+    const Amply = loadWith({handleUrl: jest.fn(() => true)});
+
+    expect(Amply.default.handleUrl(DEBUG_URL)).toBe(true);
+  });
+});
+
+describe('handleUrl before initialize', () => {
+  function loadUninitialised(initialize?: () => Promise<void>) {
+    let up = false;
+    const handleUrl = jest.fn(() => true);
+    const native = {
+      handleUrl,
+      isInitialized: jest.fn(() => up),
+      initialize: jest.fn(
+        initialize ??
+          (async () => {
+            up = true;
+          }),
+      ),
+      addListener: jest.fn(),
+      removeListeners: jest.fn(),
+    };
+    return {Amply: loadWith(native), handleUrl};
+  }
+  const KEYS = {appId: 'id', apiKeyPublic: 'public', apiKeySecret: 'secret'};
+
+  it('parks a debug link, returns true and does not call native', () => {
+    const {Amply, handleUrl} = loadUninitialised();
+
+    expect(Amply.handleUrl(DEBUG_URL)).toBe(true);
+    expect(handleUrl).not.toHaveBeenCalled();
+  });
+
+  it('replays the parked link to native once after initialize', async () => {
+    const {Amply, handleUrl} = loadUninitialised();
+    Amply.handleUrl(DEBUG_URL);
+
+    await Amply.initialize(KEYS);
+
+    expect(handleUrl).toHaveBeenCalledTimes(1);
+    expect(handleUrl).toHaveBeenCalledWith(DEBUG_URL);
+  });
+
+  it('replays only the newer of two parked links', async () => {
+    const {Amply, handleUrl} = loadUninitialised();
+    Amply.handleUrl('myapp://amply-debug/campaign?t=old');
+    Amply.handleUrl('myapp://amply-debug/campaign?t=new');
+
+    await Amply.initialize(KEYS);
+
+    expect(handleUrl).toHaveBeenCalledTimes(1);
+    expect(handleUrl).toHaveBeenCalledWith('myapp://amply-debug/campaign?t=new');
+  });
+
+  it('does not park a non-debug link', async () => {
+    const {Amply, handleUrl} = loadUninitialised();
+
+    expect(Amply.handleUrl('myapp://settings')).toBe(false);
+    await Amply.initialize(KEYS);
+
+    expect(handleUrl).not.toHaveBeenCalled();
+  });
+
+  it('drops the parked link when initialize fails', async () => {
+    const {Amply, handleUrl} = loadUninitialised(async () => {
+      throw new Error('init failed');
+    });
+    Amply.handleUrl(DEBUG_URL);
+
+    await expect(Amply.initialize(KEYS)).rejects.toThrow('init failed');
+
+    expect(handleUrl).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    '',
+    'not a url',
+    'myapp://amply-debug/campaign',
+    'myapp://amply-debug/campaign?t=',
+    'myapp://amply-debug/other?t=abc',
+    'myapp://other/campaign?t=abc',
+    'amply-debug/campaign?t=abc',
+    '://amply-debug/campaign?t=abc',
+  ])('returns false without throwing for %p', async url => {
+    const {Amply, handleUrl} = loadUninitialised();
+
+    expect(Amply.handleUrl(url)).toBe(false);
+    await Amply.initialize(KEYS);
+
+    expect(handleUrl).not.toHaveBeenCalled();
+  });
+});
+
+export {};

package/src/__tests__/lastCampaignTouch.test.ts

@@ -0,0 +1,151 @@
+import * as Amply from '../index';
+import {__setNativeModule} from '../nativeModule';
+
+const mockNativeModule = {
+  isInitialized: jest.fn(() => true),
+  getLastCampaignTouch: jest.fn(),
+};
+
+const ONE_HOUR_MS = 60 * 60 * 1000;
+
+describe('getLastCampaignTouch', () => {
+  let warn: jest.SpyInstance;
+
+  beforeEach(() => {
+    __setNativeModule(mockNativeModule as never);
+    warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warn.mockRestore();
+    jest.clearAllMocks();
+    __setNativeModule(null);
+  });
+
+  it('passes withinMs through to the native module and returns the touch', async () => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce({
+      campaignId: 'cmp_1',
+      campaignName: 'Spring offer',
+      kind: 'shown',
+      atMs: 1_760_000_000_000,
+    });
+
+    const touch = await Amply.getLastCampaignTouch(ONE_HOUR_MS);
+
+    expect(mockNativeModule.getLastCampaignTouch).toHaveBeenCalledWith(ONE_HOUR_MS);
+    expect(touch).toEqual({
+      campaignId: 'cmp_1',
+      campaignName: 'Spring offer',
+      kind: 'shown',
+      atMs: 1_760_000_000_000,
+    });
+  });
+
+  it('is exposed on the default export too', async () => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce(null);
+
+    await expect(Amply.default.getLastCampaignTouch(0)).resolves.toBeNull();
+  });
+
+  it('resolves null when the native side has no touch', async () => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce(null);
+
+    await expect(Amply.getLastCampaignTouch(ONE_HOUR_MS)).resolves.toBeNull();
+  });
+
+  it('resolves null when the native side resolves undefined', async () => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce(undefined);
+
+    await expect(Amply.getLastCampaignTouch(ONE_HOUR_MS)).resolves.toBeNull();
+  });
+
+  it.each([
+    ['shown', 'shown'],
+    ['engaged', 'engaged'],
+    ['SHOWN', 'shown'],
+    ['ENGAGED', 'engaged'],
+  ])('maps native kind %s to %s', async (nativeKind, expected) => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce({
+      campaignId: 'cmp_1',
+      campaignName: 'Spring offer',
+      kind: nativeKind,
+      atMs: 1,
+    });
+
+    const touch = await Amply.getLastCampaignTouch(ONE_HOUR_MS);
+
+    expect(touch?.kind).toBe(expected);
+  });
+
+  it('resolves null and warns for a kind this bridge does not know', async () => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce({
+      campaignId: 'cmp_1',
+      campaignName: 'Spring offer',
+      kind: 'clicked',
+      atMs: 1,
+    });
+
+    await expect(Amply.getLastCampaignTouch(ONE_HOUR_MS)).resolves.toBeNull();
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('getLastCampaignTouch'), expect.anything());
+  });
+
+  it.each([
+    ['a missing campaignId', {campaignName: 'x', kind: 'shown', atMs: 1}],
+    ['a non-numeric atMs', {campaignId: 'c', campaignName: 'x', kind: 'shown', atMs: '1'}],
+  ])('resolves null for a payload with %s', async (_label, payload) => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce(payload);
+
+    await expect(Amply.getLastCampaignTouch(ONE_HOUR_MS)).resolves.toBeNull();
+  });
+
+  it('keeps an empty campaign name rather than dropping the touch', async () => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce({
+      campaignId: 'cmp_1',
+      campaignName: '',
+      kind: 'engaged',
+      atMs: 5,
+    });
+
+    await expect(Amply.getLastCampaignTouch(ONE_HOUR_MS)).resolves.toEqual({
+      campaignId: 'cmp_1',
+      campaignName: '',
+      kind: 'engaged',
+      atMs: 5,
+    });
+  });
+
+  it('resolves null instead of rejecting when the native call fails', async () => {
+    mockNativeModule.getLastCampaignTouch.mockRejectedValueOnce(new Error('bridge gone'));
+
+    await expect(Amply.getLastCampaignTouch(ONE_HOUR_MS)).resolves.toBeNull();
+    expect(warn).toHaveBeenCalled();
+  });
+
+  it('accepts zero', async () => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce(null);
+
+    await Amply.getLastCampaignTouch(0);
+
+    expect(mockNativeModule.getLastCampaignTouch).toHaveBeenCalledWith(0);
+  });
+
+  it('leaves a large window to the native clamp', async () => {
+    mockNativeModule.getLastCampaignTouch.mockResolvedValueOnce(null);
+    const ninetyDaysMs = 90 * 24 * ONE_HOUR_MS;
+
+    await Amply.getLastCampaignTouch(ninetyDaysMs);
+
+    expect(mockNativeModule.getLastCampaignTouch).toHaveBeenCalledWith(ninetyDaysMs);
+  });
+
+  it.each([
+    ['negative', -1],
+    ['NaN', Number.NaN],
+    ['Infinity', Number.POSITIVE_INFINITY],
+    ['a string', '3600000'],
+    ['undefined', undefined],
+  ])('rejects with a RangeError for %s and never calls native', async (_label, value) => {
+    await expect(Amply.getLastCampaignTouch(value as never)).rejects.toBeInstanceOf(RangeError);
+    expect(mockNativeModule.getLastCampaignTouch).not.toHaveBeenCalled();
+  });
+});