feat: add native SDK debug mode switch

[DeepakSingh80]

ClickUp: https://app.clickup.com/t/603234/86d4bpgpd

Requirement

We need to build this package against the native SDKs in release and debug mode separately, so debug builds of the Gateway/Loans SDKs (logs, WebView inspection) can be used for internal debugging without affecting production.

Suggested approaches

1. Use GitHub branches directly as the dependency version. A branch pins the -debug native SDKs and consumers install github:smallcase/react-native-smallcase-gateway#<branch>.
2. Publish debug builds to GitHub Packages. CI swaps in the -debug pins and publishes a separate debug version of the package.

Current implementation

Neither of the above. This PR keeps one package and one npm release, and adds a mode switch:

• Native SDK versions live in native-sdk.json, with a release block (the default) and a debug block.
• The host app opts in to debug with SmallcaseGateway_sdkMode=debug (Android gradle.properties) or SMALLCASE_SDK_MODE=debug pod install (iOS).
• Without the flag, nothing changes, so external customers are unaffected and no extra branch or registry needs maintaining.

Summary

Lets host apps switch the RN wrapper to debug builds of the native Gateway/Loans SDKs (WebView inspection, debug logging) without a separate branch or npm release.

Background

This package is a bridge between a React Native app's JavaScript and the native Gateway and Loans SDKs, which exist separately for Android and iOS. The package doesn't bundle those SDKs. It declares them as dependencies, which Gradle (Android) and CocoaPods (iOS) download when the host app builds.

Host app JS  →  react-native-smallcase-gateway (bridge)  →  native Gateway / Loans SDK

Until now the dependency list was hardcoded to the release SDKs. Debugging an issue inside a native SDK meant hand-editing the pins on a separate branch (the "INTERNAL TEST PIN" commits).

	Release SDK build	Debug SDK build
Audience	Production users	smallcase developers / QA
Logging	Minimal	Detailed debug logs
WebView inspection	Off	On (Chrome / Safari dev tools)
Published to	Public registries	smallcase internal registries only

Changes

• Native SDK pins move to native-sdk.json, with release (default) and debug entries. The release block carries the pins development already uses (incognito-mode Gateway and dark-theme Loans internal builds), so resolved SDK versions don't change.
• Android: android/build.gradle reads the pins. Opt in with SmallcaseGateway_sdkMode=debug in the host's gradle.properties.
• iOS: the podspec reads the pins. Opt in with SMALLCASE_SDK_MODE=debug pod install, with cocoapodspec-internal added as a Podfile source.
• An unknown mode, or debug mode with a missing pin, fails the build with an explicit error.
• native-sdk.json is added to files so it ships in the npm package.
• README section documenting debug mode.

How release and debug work separately

There is one npm package and one codebase. Release and debug differ only in which native SDK versions get downloaded, and the host app picks one at build / install time:

                       native-sdk.json
                   ┌───────────┴───────────┐
                "release"               "debug"
            (public SDK pins)     (internal debug SDK pins)
                   │                       │
   no flag set (default) ──┘               └── flag set by host app
                                               Android: SmallcaseGateway_sdkMode=debug
                                               iOS:     SMALLCASE_SDK_MODE=debug pod install

1. When the host app builds, Gradle evaluates android/build.gradle and CocoaPods evaluates the podspec on pod install.
2. Each one reads native-sdk.json and looks for the mode flag. If the flag is missing, the mode is release.
3. It takes the pins for that mode and platform and declares them as dependencies:
   • Release: the public SDKs from the public Artifactory repo / CocoaPods trunk. External customers are on this path and need no change.
   • Debug: the debug SDKs from SCGateway-internal (Android) or cocoapodspec-internal (iOS). This path is only taken when someone opts in, so the published package never makes customers resolve internal artifacts.
4. If the mode is unknown, or a debug pin is null, the build stops with an explicit error instead of silently falling back.

The mode is set per project / per pod install, not per Debug/Release build variant of the host app. That keeps Android and iOS behaving the same.

How to use debug mode

Requires internal access: Artifactory SCGateway-internal for Android, and SSH access to smallcase/cocoapodspec-internal for iOS.

Android

1. In the host app's android/gradle.properties, add:

   SmallcaseGateway_sdkMode=debug

2. Sync / rebuild (for example npx react-native run-android). Gradle now resolves the debug SDKs.
3. To switch back, remove the line and rebuild.

iOS

1. At the top of the host app's ios/Podfile, add:

   source 'git@github.com:smallcase/cocoapodspec-internal.git'
   source 'https://cdn.cocoapods.org/'

2. From the ios folder, run:

   SMALLCASE_SDK_MODE=debug pod install

3. Build the app. It now links the debug SDKs.
4. To switch back, run a plain pod install.

Things to know before relying on it

• Not usable end to end yet. Every debug pin in native-sdk.json is still null, so turning on debug mode fails with the "no SDK pinned" error until real debug versions are filled in.
• iOS is blocked on the native side. gw-mob-ios BuildScripts/phases/create-xc-framework.sh archives without -configuration, so it always builds Release. A real debug xcframework needs -configuration Debug there plus a CI run.
• Don't ship debug SDKs to production. The mode is per project, not per build type. If sdkMode=debug is left in gradle.properties, release APKs also get the debug SDK. On iOS, the mode from the last pod install stays in effect. Switch back before building for the Play Store / App Store.
• Internal access is required for debug mode (see above). External customers stay on release and are unaffected.

Follow-ups

• Fill in the debug pins with published internal debug versions.
• iOS: add -configuration Debug to the xcframework build in gw-mob-ios and publish a debug pod.
• Consider using debugImplementation <debug pin> / releaseImplementation <release pin> on Android in debug mode, so a release build can never pick up the debug SDK.
• Consider documenting ENV['SMALLCASE_SDK_MODE'] = 'debug' at the top of the Podfile, so teammates and CI don't depend on remembering the env var.

Test plan

• pod ipc spec on development: release mode resolves to the same pods as before (SCGateway-feat-incognito-mode-2d15c7b 7.2.0-28-release, SCLoans-sourav-native-dark-theme-37c97d9 7.1.2-45-release); debug mode with no pins errors out.
• Gradle sync in a host app, in release mode and in debug mode (not run locally).

🤖 Generated with Claude Code