@scalebun-release/react-native 2.5.0

package/lib/commonjs/analytics/batching.js

@@ -0,0 +1,64 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.MAX_BATCH_EVENTS = void 0;
+exports.batchIdempotencyKey = batchIdempotencyKey;
+exports.chunkEvents = chunkEvents;
+exports.clampBatchSize = clampBatchSize;
+/**
+ * ScaleBun SDK — batch chunking contract (Phase 3 / Wave 1).
+ *
+ * The backend rejects any `/batch` request whose `events.length` exceeds
+ * MAX_BATCH_EVENTS with HTTP 413 BATCH_TOO_LARGE (accepted:0, rejected:all).
+ * The old backend behaviour silently sliced to the first 500 and 202'd — a
+ * silent data-loss defect. Now that the server rejects, the SDK must NEVER
+ * emit an oversized batch; it splits its queue into chunks of at most this
+ * value, preserving eventIds, ordering, identifiers, and timestamps.
+ *
+ * This constant MUST equal `MAX_BATCH_EVENTS` in the backend
+ * (scalebun-dashboard-backend/src/features/ingestion-v1/constants.ts).
+ * The shared contract test (`__tests__/batchChunking.test.ts`) pins the
+ * value so the two sides cannot drift.
+ */
+const MAX_BATCH_EVENTS = exports.MAX_BATCH_EVENTS = 500;
+
+/**
+ * Split a list into contiguous chunks of at most `size`, preserving order.
+ * A queue of N items yields ceil(N/size) chunks; every chunk is <= size and
+ * only the last may be shorter. No item is dropped, duplicated, or reordered.
+ */
+function chunkEvents(events, size = MAX_BATCH_EVENTS) {
+  const cap = Math.max(1, Math.min(size, MAX_BATCH_EVENTS));
+  if (events.length <= cap) return events.length ? [events.slice()] : [];
+  const out = [];
+  for (let i = 0; i < events.length; i += cap) {
+    out.push(events.slice(i, i + cap));
+  }
+  return out;
+}
+
+/** Clamp a caller-configured batch size into the server-safe range [1, MAX_BATCH_EVENTS]. */
+function clampBatchSize(configured, fallback) {
+  const n = typeof configured === 'number' && configured > 0 ? configured : fallback;
+  return Math.max(1, Math.min(n, MAX_BATCH_EVENTS));
+}
+
+/**
+ * Wave 2 (§2F.2): a STABLE batch idempotency key derived from the batch's event
+ * ids. The same leading events produce the same key across transient retries, so
+ * the server replays the first response instead of re-counting accepts; a changed
+ * batch produces a different key. Non-cryptographic (FNV-1a) — this is a dedup
+ * label, not a security token. The per-event id remains the true dedup anchor.
+ */
+function batchIdempotencyKey(eventIds) {
+  let h = 0x811c9dc5; // FNV-1a 32-bit offset basis
+  const joined = eventIds.join('
');
+  for (let i = 0; i < joined.length; i++) {
+    h ^= joined.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return `sdk-${eventIds.length}-${h.toString(16).padStart(8, '0')}`;
+}
+//# sourceMappingURL=batching.js.map

package/lib/commonjs/analytics/eventLane.js

@@ -0,0 +1,55 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.isSessionLaneEvent = isSessionLaneEvent;
+exports.isUploadedSessionEvent = isUploadedSessionEvent;
+exports.resolveEventLane = resolveEventLane;
+/**
+ * ScaleBun SDK — event lane routing.
+ *
+ * A tracked event goes to exactly one of two lanes:
+ *  - `analytics`: product events (public, non-`$`) → EventTracker → `/batch`
+ *    → raw_events → events. These are the rows a customer queries/visualizes.
+ *  - `session`: SDK-internal signals (`$`-prefixed: `$log`, `$network_request`,
+ *    `$perf_event`, `$internal_event`, …) → session/replay/debug lane only.
+ *    They must NOT enter the analytics `events` table.
+ *
+ * The `$` prefix is the single source of truth for this split. Keeping the
+ * decision in one pure function keeps the facade and any tooling in agreement
+ * and makes the split unit-testable without the native runtime.
+ */
+
+/** True for SDK-internal (`$`-prefixed) signals that ride the session lane only. */
+function isSessionLaneEvent(name) {
+  return name.startsWith('$');
+}
+
+/** Resolve the destination lane for a tracked event name. */
+function resolveEventLane(name) {
+  return isSessionLaneEvent(name) ? 'session' : 'analytics';
+}
+
+/**
+ * Signals that stay IN-PROCESS: they fan out to the engage trigger engine, the perf collectors and
+ * the desktop debug stream, but are NOT uploaded as session events — because each one already has
+ * its own dedicated ingestion lane carrying strictly more data.
+ *
+ * `$network_request` is the founding member: NetworkFeature writes every request to the
+ * `network_requests` table via reportNetworkRequest (method/status/timing/sizes/headers), and ALSO
+ * tracked it — which uploaded a second copy as a USER_ACTION session event that nothing reads. The
+ * dashboard's inspector explicitly filters that echo out as noise, the heatmap route catalog
+ * documents it as pollution, and measured sessions carried ~15% of their event volume in it.
+ * (`$perf_event` was the same pattern, removed at its emit site — d81e0ab.)
+ *
+ * Rule for adding here: the signal must have a dedicated lane that every consumer reads. A signal
+ * whose ONLY record is the session event stream must never be added.
+ */
+const INTERNAL_ONLY_SIGNALS = new Set(['$network_request']);
+
+/** Should this tracked event be uploaded to the session-events lane at all? */
+function isUploadedSessionEvent(name) {
+  return !INTERNAL_ONLY_SIGNALS.has(name);
+}
+//# sourceMappingURL=eventLane.js.map

package/lib/commonjs/analytics/revenue.js

@@ -0,0 +1,125 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.normalizeCurrency = normalizeCurrency;
+exports.normalizeRevenue = normalizeRevenue;
+exports.validBusinessAmount = validBusinessAmount;
+/**
+ * Revenue modelling for the mobile SDK — the twin of `revenue.ts` in the web SDK.
+ *
+ * WHY THIS EXISTS AT ALL. `trackPurchase` used to be three fields and a spread:
+ * `revenue`, `currency`, `transactionId`, everything else passed through
+ * untouched. That was fine while revenue was one number on a dashboard card, and
+ * it is not fine now that the Business section bridges gross to net, splits by
+ * plan, and separates refunds from charges. Three concrete consequences of the
+ * old shape, all silent:
+ *
+ *   1. A REFUND COUNTED AS A SALE. The web SDK stores a refund as a NEGATIVE
+ *      amount; mobile stored whatever sign the caller used. An app sending
+ *      `{ revenue: 30, type: 'refund' }` from iOS added $30 to GROSS revenue and
+ *      to the customer's lifetime value. Same call from the browser subtracted
+ *      it. Nothing reported the disagreement.
+ *   2. NO PLAN ATTRIBUTION. `productId` was not mapped to the `product_id`
+ *      property the rollup groups by, so every mobile sale landed in the
+ *      "Unattributed" bucket of "Top plans by revenue".
+ *   3. ADJUSTMENTS WERE UNVALIDATED. A store commission sent as the string
+ *      "0.30" reached the aggregate, failed its numeric check there, and was
+ *      dropped with no error — so mobile net revenue was quietly overstated by
+ *      the size of the app store's cut.
+ *
+ * The shapes and the property names here are the web SDK's, deliberately: both
+ * write into one `events` table that one rollup reads. A field named differently
+ * on one platform is a field that platform does not have.
+ *
+ * No third-party dependency, browser API or React import — this is pure data
+ * transformation, callable from the tracker and directly testable.
+ */
+
+/**
+ * What KIND of money movement this is.
+ *
+ * `dispute` and `adjustment` exist for the transaction ledger, which has to
+ * separate them: a chargeback is money taken back by the bank and an adjustment
+ * is a correction someone made, and lumping either into `refund` makes a refund
+ * rate that cannot be acted on.
+ *
+ * SIGN CONVENTION, matching the web SDK exactly:
+ *   refund, dispute  ALWAYS stored negative — money left, whatever sign the
+ *                    caller used.
+ *   adjustment       keeps the CALLER's sign; it is the one kind that
+ *                    legitimately goes either way (a credit or a debit).
+ */
+
+/** The adjustment keys, in the order the bridge deducts them. */
+const ADJUSTMENTS = ['tax', 'fee', 'discount'];
+
+/** Upper-case a 3-letter ISO-like code; return an empty string when invalid. */
+function normalizeCurrency(c) {
+  c = c.trim();
+  return /^[a-z]{3}$/i.test(c) ? c.toUpperCase() : '';
+}
+function validBusinessAmount(value) {
+  return typeof value === 'number' && Math.abs(value) < 1e10;
+}
+
+/**
+ * Validate and normalize a revenue event into a top-level amount/currency plus
+ * folded properties. Returns null — a DROP — when a required field is missing or
+ * unusable, because a purchase without an idempotency key cannot be deduplicated,
+ * one without a currency cannot be added to anything, and silently dropping an
+ * invalid explicit fee/tax/discount would overstate net revenue.
+ */
+function normalizeRevenue(input) {
+  input = input || {};
+  const {
+    revenue,
+    currency,
+    transactionId,
+    type,
+    productId,
+    productName,
+    quantity,
+    recurrence,
+    ...rest
+  } = input;
+  const normalizedCurrency = typeof currency === 'string' ? normalizeCurrency(currency) : '';
+  const normalizedTransactionId = typeof transactionId === 'string' ? transactionId.trim() : '';
+  if (!validBusinessAmount(revenue) || !normalizedCurrency || !normalizedTransactionId || normalizedTransactionId.length > 256) return null;
+  const kind = type ?? 'one_time';
+  if (!/^(one_time|subscription|refund|dispute|adjustment)$/.test(kind)) return null;
+
+  // A refund or a dispute is negative whatever sign the caller used, so sums and
+  // LTV are right without every call site having to remember the convention.
+  const outflow = kind === 'refund' || kind === 'dispute';
+  const amount = outflow ? -Math.abs(revenue) : revenue;
+  const props = {
+    ...rest,
+    transaction_id: normalizedTransactionId,
+    revenue_type: kind
+  };
+  const productIdText = typeof productId === 'string' ? productId.trim() : '';
+  const productNameText = typeof productName === 'string' ? productName.trim() : '';
+  if (productIdText && productIdText.length <= 256) props.product_id = productIdText;
+  if (productNameText && productNameText.length <= 512) props.product_name = productNameText;
+  if (quantity != null) props.quantity = quantity;
+  if (recurrence) props.recurrence = recurrence;
+
+  // Adjustments are always positive because the aggregate DEDUCTS them. Reject the
+  // whole purchase when an explicit adjustment is invalid: silently omitting a fee
+  // would overstate net revenue while making the event look complete.
+  for (const k of ADJUSTMENTS) {
+    const v = input[k];
+    if (v !== undefined) {
+      if (!validBusinessAmount(v)) return null;
+      props[k] = Math.abs(v);
+    }
+  }
+  return {
+    revenue: amount,
+    currency: normalizedCurrency,
+    props
+  };
+}
+//# sourceMappingURL=revenue.js.map

package/lib/commonjs/analytics/subscription.js

@@ -0,0 +1,94 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SUBSCRIPTION_SCHEMA_VERSION = void 0;
+exports.normalizeSubscription = normalizeSubscription;
+var _revenue = require("./revenue");
+/**
+ * Subscription lifecycle normalization — the mobile half of the Web SDK contract.
+ *
+ * These events feed the event-sourced subscription ledger used by Business
+ * Overview, MRR, retention and trials. Invalid price-setting events are dropped
+ * instead of manufacturing recurring revenue from incomplete data.
+ */
+
+/** Backend subscription-ledger wire contract. Additive fields require a new version. */
+const SUBSCRIPTION_SCHEMA_VERSION = exports.SUBSCRIPTION_SCHEMA_VERSION = 3;
+const SUBSCRIPTION_KEY = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$/;
+
+/** Stable cancellation taxonomy shared by React Native, Web and the dashboard. */
+
+const CANCELLATION_REASONS = ['too_expensive', 'no_longer_needed', 'competitive_offer', 'missing_features', 'poor_experience', 'payment_issue', 'other'];
+const STATUSES = ['trial_started', 'trial_converted', 'started', 'plan_changed', 'renewed', 'cancel_scheduled', 'resumed', 'canceled', 'expired', 'payment_failed', 'refunded'];
+/** `undefined` means absent; `null` means an explicit but invalid business timestamp. */
+function toIso(value, maxFutureMs) {
+  if (value === undefined) return undefined;
+  if (typeof value === 'string' ? value.length > 64 : !(value instanceof Date)) return null;
+  const date = new Date(value);
+  return +date <= Date.now() + maxFutureMs ? date.toISOString() : null;
+}
+function cleanPlan(plan) {
+  const p = plan || {};
+  const currency = typeof p.currency === 'string' ? (0, _revenue.normalizeCurrency)(p.currency) : '';
+  const intervalCount = p.intervalCount;
+  if (!(0, _revenue.validBusinessAmount)(p.amount) || p.amount < 0 || !currency || !/^(day|week|month|year)$/.test(p.interval) || intervalCount !== undefined && (intervalCount !== (intervalCount | 0) || intervalCount <= 0 || intervalCount > 1_000)) return null;
+  const id = typeof p.id === 'string' ? p.id.trim() : '';
+  const name = typeof p.name === 'string' ? p.name.trim() : '';
+  return {
+    amount: p.amount,
+    currency,
+    interval: p.interval,
+    ...(intervalCount === undefined ? {} : {
+      intervalCount
+    }),
+    ...(id && id.length <= 256 ? {
+      id
+    } : {}),
+    ...(name && name.length <= 512 ? {
+      name
+    } : {})
+  };
+}
+
+/** Validate and build the canonical `$subscription` event properties. */
+function normalizeSubscription(input) {
+  input = input || {};
+  const subscriptionId = typeof input.subscriptionId === 'string' ? input.subscriptionId.trim() : '';
+  const subscriptionEventId = typeof input.subscriptionEventId === 'string' ? input.subscriptionEventId.trim() : input.subscriptionEventId;
+  const status = input.status;
+  const statusIndex = STATUSES.indexOf(status);
+  if (!SUBSCRIPTION_KEY.test(subscriptionId) || subscriptionEventId !== undefined && (typeof subscriptionEventId !== 'string' || !SUBSCRIPTION_KEY.test(subscriptionEventId)) || statusIndex < 0) return null;
+  const cancellationReason = input.cancellationReason;
+  const cancellationComment = typeof input.cancellationComment === 'string' ? input.cancellationComment.trim() : input.cancellationComment;
+  const cancellationStatus = status === 'cancel_scheduled' || status === 'canceled' || status === 'expired';
+  if ((cancellationReason !== undefined || cancellationComment !== undefined) && !cancellationStatus) return null;
+  if (cancellationReason !== undefined && !CANCELLATION_REASONS.includes(cancellationReason)) return null;
+  if (cancellationComment !== undefined && (typeof cancellationComment !== 'string' || !cancellationComment || cancellationComment.length > 500)) return null;
+  const plan = input.plan;
+  const normalizedPlan = plan === undefined ? undefined : cleanPlan(plan);
+  if (!normalizedPlan && (statusIndex < 4 || plan !== undefined)) return null;
+  const trialEndAt = toIso(input.trialEndAt, 316224000000);
+  const effectiveAt = toIso(input.effectiveAt, 86400000);
+  if (trialEndAt === null || effectiveAt === null) return null;
+  return {
+    ...(input.properties ?? {}),
+    schemaVersion: SUBSCRIPTION_SCHEMA_VERSION,
+    subscriptionId,
+    ...(subscriptionEventId === undefined ? {} : {
+      subscriptionEventId
+    }),
+    status,
+    ...(cancellationReason === undefined ? {} : {
+      cancellationReason
+    }),
+    ...(cancellationComment === undefined ? {} : {
+      cancellationComment
+    }),
+    plan: normalizedPlan,
+    trialEndAt,
+    effectiveAt
+  };
+}
+//# sourceMappingURL=subscription.js.map

package/lib/commonjs/bootstrap/FeatureRegistry.js

@@ -0,0 +1,86 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.FeatureRegistry = void 0;
+var _internalLogger = require("../core/logger/internalLogger");
+/**
+ * ScaleBun SDK — Feature Registry
+ *
+ * Central registry for SDK feature modules.
+ * Manages feature registration, initialization order, and lifecycle teardown.
+ *
+ * SOLID: Single Responsibility — only manages feature lifecycle.
+ * SOLID: Dependency Inversion — depends on IFeature abstraction.
+ */
+
+class FeatureRegistry {
+  features = new Map();
+  initialized = false;
+
+  /**
+   * Register a feature. Must be called before `initializeAll()`.
+   * Duplicate registrations are silently ignored (idempotent).
+   */
+  register(feature) {
+    if (this.features.has(feature.name)) {
+      __DEV__ && _internalLogger.logger.debug(`Feature '${feature.name}' already registered, skipping`);
+      return;
+    }
+    this.features.set(feature.name, feature);
+    __DEV__ && _internalLogger.logger.debug(`Feature '${feature.name}' registered`);
+  }
+
+  /**
+   * Initialize all registered features with the provided context.
+   * Features that fail to initialize are logged but don't break others.
+   */
+  async initializeAll(context) {
+    if (this.initialized) return;
+    for (const [name, feature] of this.features) {
+      try {
+        await feature.initialize(context);
+        __DEV__ && _internalLogger.logger.debug(`Feature '${name}' initialized`);
+      } catch (err) {
+        _internalLogger.logger.error(`Feature '${name}' failed to initialize:`, err);
+      }
+    }
+    this.initialized = true;
+  }
+
+  /**
+   * Tear down all features in reverse registration order.
+   * Safe to call even if not initialized.
+   */
+  teardownAll() {
+    const entries = Array.from(this.features.entries()).reverse();
+    for (const [name, feature] of entries) {
+      try {
+        feature.teardown();
+        __DEV__ && _internalLogger.logger.debug(`Feature '${name}' torn down`);
+      } catch (err) {
+        _internalLogger.logger.error(`Feature '${name}' teardown failed:`, err);
+      }
+    }
+    this.features.clear();
+    this.initialized = false;
+  }
+
+  /** Get a feature by name */
+  get(name) {
+    return this.features.get(name);
+  }
+
+  /** Check if a feature is registered and active */
+  isFeatureActive(name) {
+    return this.features.get(name)?.isActive ?? false;
+  }
+
+  /** Get all registered feature names */
+  getRegisteredFeatures() {
+    return Array.from(this.features.keys());
+  }
+}
+exports.FeatureRegistry = FeatureRegistry;
+//# sourceMappingURL=FeatureRegistry.js.map