@allstak/react-native 0.1.3 → 0.3.1

package/build-hooks/allstak-sourcemaps.gradle

@@ -0,0 +1,132 @@
+// AllStak source-map upload — Gradle helper.
+//
+// Drop this file into your Android project at:
+//   allstak-react-native/build-hooks/allstak-sourcemaps.gradle
+// (or any path you like — just point apply-from at it)
+//
+// Then add ONE line to android/app/build.gradle, after the
+// react-native-gradle-plugin apply at the top:
+//
+//   apply from: file('../node_modules/@allstak/react-native/build-hooks/allstak-sourcemaps.gradle')
+//
+// Set these in ~/.gradle/gradle.properties or as `-PallstakRelease=…`
+// on the command line:
+//
+//   allstakRelease=mobile@1.2.3+5
+//   allstakUploadToken=aspk_...        # only required for actual upload
+//   allstakHost=https://api.allstak.sa # optional override
+//
+// What it does:
+//   • Hooks every variant whose name ends with "Release" (e.g.
+//     bundleRelease, assembleRelease) and runs the AllStak uploader
+//     on the Metro bundle + sourcemap that variant produced.
+//   • Falls back to inject-only mode when no upload token is set.
+//   • Never fails the build over a sourcemap glitch — logs and moves on.
+//
+// Output path conventions (Metro/Hermes default):
+//   build/generated/assets/createBundleReleaseJsAndAssets/index.android.bundle
+//   build/generated/sourcemaps/react/release/index.android.bundle.map
+
+import org.gradle.api.tasks.Exec
+import java.nio.file.Files
+import java.nio.file.Paths
+
+afterEvaluate {
+    android.applicationVariants.all { variant ->
+        def variantName = variant.name
+        if (!variantName.toLowerCase().endsWith('release')) return
+
+        def capitalized = variantName.capitalize()
+        // The bundle/sourcemap-emitting tasks are created by the React
+        // Native gradle plugin during configuration. Hook them by name
+        // so we run *after* the bundle is on disk.
+        def bundleTaskName = "createBundle${capitalized}JsAndAssets"
+        def parent = tasks.findByName(bundleTaskName)
+        if (parent == null) {
+            project.logger.lifecycle("[allstak] no ${bundleTaskName} task found — skipping sourcemap upload for ${variantName}")
+            return
+        }
+
+        def uploadTask = tasks.create("allstakUpload${capitalized}Sourcemaps", Exec) {
+            group = 'AllStak'
+            description = "Inject debug-id and (optionally) upload Hermes/Metro sourcemap for the ${variantName} variant."
+
+            // Metro+Hermes paths the React Native gradle plugin uses by default.
+            // We accept the conventional defaults; users can override via project props.
+            def jsBundleDir = project.findProperty('allstakBundleDir') ?:
+                file("${buildDir}/generated/assets/${bundleTaskName}").absolutePath
+            def mapDir = project.findProperty('allstakMapDir') ?:
+                file("${buildDir}/generated/sourcemaps/react/${variantName}").absolutePath
+
+            // Pick the right pair (Hermes emits .bundle + .bundle.map after compose).
+            doFirst {
+                def bundleCandidates = [
+                    Paths.get(jsBundleDir.toString(), 'index.android.bundle'),
+                    Paths.get(jsBundleDir.toString(), 'index.android.jsbundle'),
+                ]
+                def mapCandidates = [
+                    Paths.get(mapDir.toString(), 'index.android.bundle.map'),
+                    Paths.get(mapDir.toString(), 'index.android.bundle.composed.map'),
+                ]
+                def bundle = bundleCandidates.find { Files.exists(it) }
+                def mapFile = mapCandidates.find { Files.exists(it) }
+
+                if (bundle == null || mapFile == null) {
+                    project.logger.warn("[allstak] no bundle/sourcemap pair found for ${variantName}: " +
+                            "tried ${bundleCandidates}, ${mapCandidates}")
+                    enabled = false
+                    return
+                }
+
+                def releaseProp = project.findProperty('allstakRelease') ?:
+                    System.getenv('ALLSTAK_RELEASE')
+                def tokenProp = project.findProperty('allstakUploadToken') ?:
+                    System.getenv('ALLSTAK_UPLOAD_TOKEN')
+                def hostProp = project.findProperty('allstakHost') ?:
+                    System.getenv('ALLSTAK_HOST')
+                def distProp = project.findProperty('allstakDist') ?:
+                    System.getenv('ALLSTAK_DIST_OVERRIDE') ?:
+                    'android-hermes'
+
+                if (releaseProp == null) {
+                    project.logger.warn("[allstak] no allstakRelease / ALLSTAK_RELEASE set — skipping sourcemap step")
+                    enabled = false
+                    return
+                }
+
+                // Resolve the helper script that ships inside the SDK package.
+                def hookScript = project.findProperty('allstakHookScript') ?:
+                    project.rootDir.toPath()
+                        .resolve('../node_modules/@allstak/react-native/build-hooks/upload-sourcemaps.js')
+                        .normalize()
+                        .toString()
+
+                if (!Files.exists(Paths.get(hookScript))) {
+                    project.logger.warn("[allstak] hook script not found at ${hookScript} — is @allstak/react-native installed?")
+                    enabled = false
+                    return
+                }
+
+                environment 'ALLSTAK_RELEASE', releaseProp
+                if (tokenProp) environment 'ALLSTAK_UPLOAD_TOKEN', tokenProp
+                if (hostProp)  environment 'ALLSTAK_HOST', hostProp
+
+                commandLine 'node', hookScript,
+                    '--bundle', bundle.toString(),
+                    '--sourcemap', mapFile.toString(),
+                    '--platform', 'android',
+                    '--dist', distProp
+
+                project.logger.lifecycle("[allstak] uploading sourcemap for ${variantName}: ${bundle} (release=${releaseProp})")
+            }
+
+            // Don't fail the build — log and continue.
+            ignoreExitValue = true
+        }
+
+        // Run AFTER the bundle exists. We hook the bundle task's
+        // doLast so the artifact is on disk; finalizedBy ensures we
+        // run even if the user invoked just :app:bundleRelease.
+        parent.finalizedBy(uploadTask)
+    }
+}

package/build-hooks/eas-post-bundle.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * AllStak source-map upload — Expo / EAS Build hook.
+ *
+ * EAS Build calls per-build hooks defined in `eas.json` under
+ * `build.<profile>.hooks` (e.g. `eas-build-on-success`) or via package.json
+ * scripts (`eas-build-pre-install`, `eas-build-on-success`, …).
+ *
+ * Drop-in setup:
+ *   1. Add a script in package.json:
+ *
+ *        "scripts": {
+ *          "eas-build-on-success":
+ *            "node node_modules/@allstak/react-native/build-hooks/eas-post-bundle.js"
+ *        }
+ *
+ *   2. Set these in eas.json secrets (or as EAS env vars):
+ *
+ *        ALLSTAK_RELEASE        — required (e.g. "mobile@1.2.3+5")
+ *        ALLSTAK_UPLOAD_TOKEN   — required for actual upload
+ *        ALLSTAK_HOST           — optional override
+ *
+ * What this hook does:
+ *   • Probes EAS's standard output paths for both iOS and Android Hermes
+ *     bundles + composed source maps.
+ *   • Calls the SDK's uploader for each platform that produced artifacts.
+ *   • Falls back to inject-only mode when no token is set.
+ *   • Always exits 0 — never fails an EAS build over a sourcemap glitch.
+ *
+ * If you build outside of EAS (bare RN, custom CI), use
+ * `upload-sourcemaps.js` directly instead.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const RELEASE = process.env.ALLSTAK_RELEASE;
+const TOKEN = process.env.ALLSTAK_UPLOAD_TOKEN;
+
+if (!RELEASE) {
+  console.warn('[allstak] ALLSTAK_RELEASE not set — skipping sourcemap upload');
+  process.exit(0);
+}
+
+if (!TOKEN) {
+  console.warn('[allstak] ALLSTAK_UPLOAD_TOKEN not set — running in inject-only mode');
+}
+
+// EAS sets EAS_BUILD_WORKINGDIR to the per-build working directory.
+// Outside of EAS it falls back to cwd.
+const root = process.env.EAS_BUILD_WORKINGDIR || process.cwd();
+
+// Probe locations for each platform. EAS runs the standard
+// `npx react-native bundle` in a temp dir under android/ios — these
+// are the conventional output names.
+const probes = [
+  // iOS
+  { platform: 'ios', dist: 'ios-hermes',
+    bundle: path.join(root, 'ios', 'main.jsbundle'),
+    sourcemap: path.join(root, 'ios', 'main.jsbundle.map') },
+  { platform: 'ios', dist: 'ios-hermes',
+    bundle: path.join(root, 'ios.bundle'),
+    sourcemap: path.join(root, 'ios.bundle.map') },
+  // Android
+  { platform: 'android', dist: 'android-hermes',
+    bundle: path.join(root, 'android', 'app', 'build', 'generated', 'assets',
+                      'createBundleReleaseJsAndAssets', 'index.android.bundle'),
+    sourcemap: path.join(root, 'android', 'app', 'build', 'generated', 'sourcemaps',
+                         'react', 'release', 'index.android.bundle.map') },
+  { platform: 'android', dist: 'android-hermes',
+    bundle: path.join(root, 'android.bundle'),
+    sourcemap: path.join(root, 'android.bundle.map') },
+];
+
+const targets = [];
+const seen = new Set();
+for (const p of probes) {
+  if (fs.existsSync(p.bundle) && fs.existsSync(p.sourcemap)) {
+    const key = p.platform;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    targets.push(p);
+  }
+}
+
+if (targets.length === 0) {
+  console.warn('[allstak] no bundle+sourcemap pairs found under', root);
+  console.warn('         Searched standard EAS / RN paths for both iOS and Android.');
+  console.warn('         If your build writes to a different location, run');
+  console.warn('         `node node_modules/@allstak/react-native/build-hooks/upload-sourcemaps.js`');
+  console.warn('         with explicit --bundle and --sourcemap flags.');
+  process.exit(0);  // not a failure
+}
+
+const hookScript = path.join(__dirname, 'upload-sourcemaps.js');
+
+(async () => {
+  for (const t of targets) {
+    console.log(`[allstak] EAS hook: ${t.platform} bundle ${t.bundle}`);
+    await new Promise((resolve) => {
+      const child = spawn('node', [
+        hookScript,
+        '--bundle', t.bundle,
+        '--sourcemap', t.sourcemap,
+        '--platform', t.platform,
+        '--dist', t.dist,
+      ], {
+        stdio: 'inherit',
+        env: process.env,
+      });
+      child.on('close', (code) => {
+        if (code !== 0) {
+          console.warn(`[allstak] EAS hook: ${t.platform} returned exit ${code} — continuing`);
+        }
+        resolve();
+      });
+      child.on('error', (e) => {
+        console.warn(`[allstak] EAS hook: ${t.platform} error — ${e.message}`);
+        resolve();
+      });
+    });
+  }
+  process.exit(0);
+})();

package/build-hooks/upload-sourcemaps.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * One-line source-map upload hook for React Native (Metro / Hermes).
+ *
+ * Drop this file into your repo at `scripts/upload-sourcemaps.js` (or
+ * any path you like). It auto-detects the bundle + map written by
+ * `npx react-native bundle` for both platforms, calls the SDK's
+ * uploader, and exits non-zero if any platform's upload fails.
+ *
+ * Usage in CI / Xcode build phase / Gradle task:
+ *
+ *   ALLSTAK_RELEASE='mobile@1.2.3+5' \
+ *   ALLSTAK_UPLOAD_TOKEN='aspk_…' \
+ *     node scripts/upload-sourcemaps.js [path/to/build-output-dir]
+ *
+ * Env vars consulted:
+ *   ALLSTAK_RELEASE       — required, your release identifier
+ *   ALLSTAK_UPLOAD_TOKEN  — required, project-scoped upload token
+ *   ALLSTAK_HOST          — optional, defaults to https://api.allstak.sa
+ *   ALLSTAK_DIST_OVERRIDE — optional, override auto-detected dist
+ *
+ * Bundle/map paths it looks for, in order:
+ *   1. CLI arg: explicit `--bundle` / `--sourcemap` / `--platform` / `--dist`
+ *   2. Build dir from CLI positional arg (default: cwd)
+ *   3. Conventional names: <platform>.bundle / <platform>.bundle.map
+ *
+ * Exits:
+ *   0  — at least one platform uploaded OK (or injectOnly with no token)
+ *   1  — required env missing or all platforms failed
+ *
+ * No deps beyond Node 18+ and the SDK itself.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const args = parseArgs(process.argv.slice(2));
+
+const RELEASE = process.env.ALLSTAK_RELEASE;
+const TOKEN = process.env.ALLSTAK_UPLOAD_TOKEN;
+const HOST = process.env.ALLSTAK_HOST;
+const DIST_OVERRIDE = process.env.ALLSTAK_DIST_OVERRIDE;
+const INJECT_ONLY = !TOKEN;  // gracefully fall back to inject-only if no token
+
+if (!RELEASE) {
+  console.error('[allstak] ALLSTAK_RELEASE env var is required (e.g. "mobile@1.2.3+5")');
+  process.exit(1);
+}
+
+if (INJECT_ONLY && !args.injectOnly) {
+  console.warn('[allstak] no ALLSTAK_UPLOAD_TOKEN — running in inject-only mode (debug-ids written, no upload)');
+}
+
+(async () => {
+  let uploader;
+  try {
+    uploader = require('@allstak/react-native/sourcemaps').uploadReactNativeSourcemap;
+  } catch (e) {
+    console.error('[allstak] could not require @allstak/react-native/sourcemaps — is the package installed?');
+    console.error(e?.message ?? e);
+    process.exit(1);
+  }
+
+  const baseDir = path.resolve(args.dir || process.cwd());
+
+  // Targets to try. If --bundle/--sourcemap are supplied, treat that as
+  // a single explicit target; otherwise probe both ios + android in the
+  // build dir.
+  const targets = [];
+  if (args.bundle && args.sourcemap) {
+    targets.push({
+      platform: args.platform || guessPlatform(args.bundle),
+      bundle: path.resolve(args.bundle),
+      sourcemap: path.resolve(args.sourcemap),
+      dist: args.dist || guessDist(args.platform || guessPlatform(args.bundle)),
+    });
+  } else {
+    for (const platform of ['ios', 'android']) {
+      const probe = pickBundle(baseDir, platform);
+      if (probe) targets.push({
+        platform,
+        bundle: probe.bundle,
+        sourcemap: probe.sourcemap,
+        dist: args.dist || (DIST_OVERRIDE || guessDist(platform)),
+      });
+    }
+  }
+
+  if (targets.length === 0) {
+    console.error(`[allstak] no bundle+sourcemap pair found under ${baseDir}.`);
+    console.error('         Expected: <platform>.bundle + <platform>.bundle.map');
+    console.error('         Or pass --bundle <path> --sourcemap <path>.');
+    process.exit(1);
+  }
+
+  let okCount = 0;
+  for (const t of targets) {
+    try {
+      console.log(`[allstak] ${t.platform}: ${path.relative(baseDir, t.bundle)} + .map  (dist=${t.dist})`);
+      const result = await uploader({
+        bundle: t.bundle,
+        sourcemap: t.sourcemap,
+        release: RELEASE,
+        dist: t.dist,
+        token: TOKEN,
+        host: HOST,
+        injectOnly: INJECT_ONLY || args.injectOnly,
+        stripSources: args.stripSources,
+        uploadBundle: args.uploadBundle,
+      });
+      if (INJECT_ONLY || args.injectOnly) {
+        console.log(`[allstak] ${t.platform}: debug-id ${result.debugId} ${result.reused ? '(reused)' : '(new)'} — inject-only`);
+        okCount += 1;
+      } else if (result.uploaded) {
+        console.log(`[allstak] ${t.platform}: uploaded debug-id ${result.debugId}`);
+        okCount += 1;
+      } else {
+        const last = result.steps?.[result.steps.length - 1];
+        console.error(`[allstak] ${t.platform}: FAIL status=${last?.status ?? '?'} body=${(last?.body ?? '').slice(0, 200)}`);
+      }
+    } catch (e) {
+      console.error(`[allstak] ${t.platform}: error — ${e?.message ?? e}`);
+    }
+  }
+
+  process.exit(okCount > 0 ? 0 : 1);
+})();
+
+// ────────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--bundle')        out.bundle = argv[++i];
+    else if (a === '--sourcemap') out.sourcemap = argv[++i];
+    else if (a === '--platform')  out.platform = argv[++i];
+    else if (a === '--dist')      out.dist = argv[++i];
+    else if (a === '--inject-only') out.injectOnly = true;
+    else if (a === '--strip-sources') out.stripSources = true;
+    else if (a === '--upload-bundle') out.uploadBundle = true;
+    else if (a.startsWith('--')) console.warn(`[allstak] unknown flag: ${a}`);
+    else out._.push(a);
+  }
+  if (out._.length > 0 && !out.dir) out.dir = out._[0];
+  return out;
+}
+
+function pickBundle(dir, platform) {
+  const candidates = [
+    [path.join(dir, `${platform}.bundle`), path.join(dir, `${platform}.bundle.map`)],
+    [path.join(dir, `main.jsbundle`), path.join(dir, `main.jsbundle.map`)],     // iOS Xcode default
+    [path.join(dir, `index.${platform}.bundle`), path.join(dir, `index.${platform}.bundle.map`)],
+  ];
+  for (const [b, m] of candidates) {
+    if (fs.existsSync(b) && fs.existsSync(m)) return { bundle: b, sourcemap: m };
+  }
+  return null;
+}
+
+function guessPlatform(bundlePath) {
+  const f = path.basename(bundlePath).toLowerCase();
+  if (f.includes('ios')) return 'ios';
+  if (f.includes('android')) return 'android';
+  return 'unknown';
+}
+
+function guessDist(platform) {
+  // Match the SDK's runtime dist auto-detection (`<os>-<engine>`).
+  if (platform === 'ios') return 'ios-hermes';
+  if (platform === 'android') return 'android-hermes';
+  return platform;
+}

package/build-hooks/xcode-build-phase.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# AllStak source-map upload — iOS Xcode build phase.
+#
+# Add a new "Run Script" build phase to your iOS app target in Xcode,
+# AFTER the React Native "Bundle React Native code and images" phase,
+# with this exact body:
+#
+#   "$SRCROOT/../node_modules/@allstak/react-native/build-hooks/xcode-build-phase.sh"
+#
+# Then set the env vars in the same Run Script panel (or via .xcconfig
+# / your CI shell):
+#
+#   ALLSTAK_RELEASE        = mobile@1.2.3+5
+#   ALLSTAK_UPLOAD_TOKEN   = aspk_…              # only required for upload
+#   ALLSTAK_HOST           = https://api.allstak.sa  (optional)
+#   ALLSTAK_DIST_OVERRIDE  = ios-hermes              (optional override)
+#
+# This script auto-detects the bundle + sourcemap that the React Native
+# Xcode build phase wrote and runs the SDK's uploader on them. It only
+# runs in Release builds — Debug builds are no-ops.
+#
+# Exits 0 even on upload failure so a flaky CI step doesn't fail your
+# archive. The hook script logs everything to the build log.
+
+set -e
+
+if [[ "${CONFIGURATION}" != "Release" ]]; then
+  echo "[allstak] CONFIGURATION=${CONFIGURATION} — skipping sourcemap upload (Release-only)"
+  exit 0
+fi
+
+if [[ -z "${ALLSTAK_RELEASE}" ]]; then
+  echo "[allstak] ALLSTAK_RELEASE not set — skipping sourcemap upload"
+  exit 0
+fi
+
+# Locate the bundle + map relative to standard React Native output paths.
+# The RN Xcode build phase writes:
+#   ${CONFIGURATION_BUILD_DIR}/${UNLOCALIZED_RESOURCES_FOLDER_PATH}/main.jsbundle
+#   ${CONFIGURATION_BUILD_DIR}/main.jsbundle.map
+BUNDLE="${CONFIGURATION_BUILD_DIR}/${UNLOCALIZED_RESOURCES_FOLDER_PATH}/main.jsbundle"
+MAP="${CONFIGURATION_BUILD_DIR}/main.jsbundle.map"
+
+if [[ ! -f "${BUNDLE}" ]]; then
+  echo "[allstak] bundle not found at ${BUNDLE} — skipping"
+  exit 0
+fi
+if [[ ! -f "${MAP}" ]]; then
+  echo "[allstak] sourcemap not found at ${MAP} — skipping (set SOURCEMAP_FILE in your bundle build phase)"
+  exit 0
+fi
+
+# Resolve the hook script. Default location: node_modules in the JS root
+# above the iOS project. Override via ALLSTAK_HOOK_SCRIPT.
+HOOK_SCRIPT="${ALLSTAK_HOOK_SCRIPT:-${SRCROOT}/../node_modules/@allstak/react-native/build-hooks/upload-sourcemaps.js}"
+if [[ ! -f "${HOOK_SCRIPT}" ]]; then
+  echo "[allstak] hook script not found at ${HOOK_SCRIPT} — is @allstak/react-native installed?"
+  exit 0
+fi
+
+# Find a usable Node binary. Xcode build phases don't inherit the user's
+# PATH, so check the common locations.
+if [[ -z "${NODE_BINARY}" ]]; then
+  for candidate in \
+    "$(command -v node 2>/dev/null)" \
+    "/usr/local/bin/node" \
+    "/opt/homebrew/bin/node" \
+    "/usr/bin/node" ; do
+    if [[ -x "${candidate}" ]]; then
+      NODE_BINARY="${candidate}"
+      break
+    fi
+  done
+fi
+if [[ -z "${NODE_BINARY}" || ! -x "${NODE_BINARY}" ]]; then
+  echo "[allstak] could not locate a Node binary — set NODE_BINARY in your build phase"
+  exit 0
+fi
+
+DIST="${ALLSTAK_DIST_OVERRIDE:-ios-hermes}"
+
+echo "[allstak] uploading sourcemap for ${BUNDLE} (release=${ALLSTAK_RELEASE} dist=${DIST})"
+
+# Don't fail the archive if the upload errors. Log and continue.
+"${NODE_BINARY}" "${HOOK_SCRIPT}" \
+  --bundle "${BUNDLE}" \
+  --sourcemap "${MAP}" \
+  --platform ios \
+  --dist "${DIST}" \
+  || echo "[allstak] sourcemap upload reported non-zero — see log above"

package/dist/build/sourcemaps.d.mts

@@ -0,0 +1,94 @@
+/**
+ * Source-map upload pipeline for React Native (Metro / Hermes). Build-time only.
+ *
+ * Metro emits one bundle + one source map per build, so the React Native
+ * flow is simpler than the React-web flow (no `dist/` walk needed). The
+ * developer hands us the bundle + map paths produced by:
+ *
+ *   npx react-native bundle \
+ *     --platform ios --dev false --entry-file index.js \
+ *     --bundle-output ios.bundle \
+ *     --sourcemap-output ios.bundle.map
+ *
+ * If Hermes is enabled, the resulting `.hbc` bytecode replaces the JS
+ * bundle on the device, and the user must compose the Metro map with the
+ * Hermes map BEFORE uploading. We accept whatever map the user gives us
+ * and inject a debug-id into both the map and the bundle.
+ *
+ * Usage from a build script (`scripts/upload-sourcemaps.js`):
+ *
+ *   const { uploadReactNativeSourcemap } = require('@allstak/react-native/sourcemaps');
+ *
+ *   await uploadReactNativeSourcemap({
+ *     bundle: 'ios.bundle',
+ *     sourcemap: 'ios.bundle.map',
+ *     release: 'mobile@1.2.3',
+ *     dist: 'ios-hermes',
+ *     token: process.env.ALLSTAK_UPLOAD_TOKEN,
+ *   });
+ *
+ * Or `injectOnly: true` to add the debug-id without uploading (useful in
+ * CI dry-runs or when you don't have an upload token yet).
+ */
+declare const DEFAULT_HOST = "https://api.allstak.sa";
+interface UploadReactNativeSourcemapOptions {
+    /** Path to the JS/Hermes-bytecode bundle (Metro's `--bundle-output`). */
+    bundle: string;
+    /** Path to the matching `.map` (Metro's `--sourcemap-output`). */
+    sourcemap: string;
+    /** Release identifier (e.g. `mobile@1.2.3` — match `release` in AllStak.init). */
+    release: string;
+    /**
+     * Distribution tag — recommended values: `ios-hermes`, `android-hermes`,
+     * `ios-jsc`, `android-jsc`. Match the `dist` the SDK auto-detects at
+     * runtime (see `src/install.ts`). Required for the symbolicator to
+     * pick the right map per platform.
+     */
+    dist?: string;
+    /** Project upload token (`aspk_…`). Defaults to `ALLSTAK_UPLOAD_TOKEN`. */
+    token?: string;
+    /** Override ingest host. Defaults to `ALLSTAK_HOST` or production. */
+    host?: string;
+    /** Drop `sourcesContent` from the map before upload (smaller payload). */
+    stripSources?: boolean;
+    /** Also upload the JS/HBC bundle alongside the map. Off by default. */
+    uploadBundle?: boolean;
+    /** Inject debug-id but skip the upload (CI dry-run). */
+    injectOnly?: boolean;
+    /** Pre-existing debug-id to use instead of generating one. Optional. */
+    debugId?: string;
+    /** Suppress per-step console output. Default false. */
+    silent?: boolean;
+}
+interface UploadReactNativeSourcemapResult {
+    /** The debug-id injected into the bundle + map. */
+    debugId: string;
+    /** True if the bundle already had a debug-id; we reused it. */
+    reused: boolean;
+    /** True when upload(s) succeeded — undefined when `injectOnly: true`. */
+    uploaded?: boolean;
+    /** Per-artifact responses, in the order we sent them. */
+    steps?: Array<{
+        type: 'sourcemap' | 'bundle';
+        status: number;
+        sha8: string;
+        body?: string;
+    }>;
+}
+/**
+ * Inject a debug-id into the bundle + map (idempotent — reuses an
+ * existing id if present).
+ */
+declare function injectReactNativeSourcemap(opts: Pick<UploadReactNativeSourcemapOptions, 'bundle' | 'sourcemap' | 'debugId'>): {
+    debugId: string;
+    reused: boolean;
+};
+/**
+ * Inject debug-id into the bundle + map and (optionally) upload.
+ *
+ * Returns the debug-id (so the caller can stash it for symbolicator
+ * lookups), whether it was reused, and per-step upload statuses.
+ */
+declare function uploadReactNativeSourcemap(opts: UploadReactNativeSourcemapOptions): Promise<UploadReactNativeSourcemapResult>;
+
+export { DEFAULT_HOST, type UploadReactNativeSourcemapOptions, type UploadReactNativeSourcemapResult, injectReactNativeSourcemap, uploadReactNativeSourcemap };