@cosmoola/cosmoola-native 1.0.0

package/README.md

@@ -0,0 +1,119 @@
+# @cosmoola/cosmoola-native
+
+React Native SDK for Cosmoola — payments + currency converter.
+Works with Expo and bare React Native (iOS + Android).
+
+## Install
+
+```bash
+npm install @cosmoola/cosmoola-native @react-native-async-storage/async-storage
+```
+
+If bare RN (not Expo):
+```bash
+cd ios && pod install
+```
+
+---
+
+## Currency Converter
+
+### 1. Wrap your app ONCE in App.js
+
+```jsx
+import { CurrencyProvider } from "@cosmoola/cosmoola-native";
+
+export default function App() {
+  return (
+    <CurrencyProvider apiKey="pk_live_xxx">
+      <NavigationContainer>
+        <RootNavigator />
+      </NavigationContainer>
+    </CurrencyProvider>
+  );
+}
+```
+
+### 2. Use anywhere in any screen
+
+```jsx
+import { useCurrency, CsmPrice } from "@cosmoola/cosmoola-native";
+import { Text, View } from "react-native";
+
+// Hook
+function ProductScreen() {
+  const { convert, currency, setCurrency } = useCurrency();
+  return (
+    <View>
+      <Text>{convert(99.99)}</Text>         // → "£79.23"
+      <Text>{convert(99.99, "USD")}</Text>  // explicit base
+    </View>
+  );
+}
+
+// Drop-in component
+function PriceTag({ amount }) {
+  return <CsmPrice amount={amount} from="USD" style={{ fontSize: 18, fontWeight: "bold" }} />;
+}
+```
+
+---
+
+## Payments
+
+```jsx
+import CosmoolaNative, { useMobilePayment } from "@cosmoola/cosmoola-native";
+
+const cosmoola = new CosmoolaNative("pk_live_xxx");
+
+// Card payment
+const { paymentIntent, error } = await cosmoola.confirmCardPayment(clientSecret, {
+  payment_method: {
+    card: { number: "4242424242424242", exp_month: "12", exp_year: "26", cvc: "123" }
+  }
+});
+
+// Mobile Money hook
+function PayScreen() {
+  const { initiate, status, error } = useMobilePayment("pk_live_xxx");
+
+  const pay = async () => {
+    await initiate({
+      clientSecret: "pi_xxx_secret_xxx",
+      phone:        "+254712345678",
+      country:      "KE",
+      amount:       500,
+      currency:     "KES",
+    });
+  };
+
+  return (
+    <Button title={status === "polling" ? "Waiting..." : "Pay with M-Pesa"} onPress={pay} />
+  );
+}
+```
+
+---
+
+## Folder structure
+
+```
+sdk/
+  cosmoola-js/         ← Web browser SDK
+  cosmoola-node/       ← Node.js server SDK
+  cosmoola-react/      ← React web SDK (hooks + components)
+  cosmoola-native/     ← React Native SDK (this package)
+```
+
+---
+
+## Differences from cosmoola-react
+
+| Feature | cosmoola-react | cosmoola-native |
+|---------|---------------|-----------------|
+| Cache | localStorage | AsyncStorage |
+| Country detect | ipapi.co + navigator.language | ipapi.co |
+| Price component | `<CsmPrice />` (web) | `<CsmPrice />` (RN Text) |
+| Currency switcher | `<CsmSwitcher />` | Build your own with `allCurrencies` |
+| Payment elements | DOM-based CardElement | Use your own RN inputs |
+| No-build | ✓ | ✓ |

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@cosmoola/cosmoola-native",
+  "version": "1.0.0",
+  "description": "Cosmoola React Native SDK — payments + currency converter",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "types": "types/index.d.ts",
+  "files": [
+    "src",
+    "types"
+  ],
+  "keywords": [
+    "cosmoola",
+    "payments",
+    "react-native",
+    "currency",
+    "mobile-money"
+  ],
+  "peerDependencies": {
+    "@react-native-async-storage/async-storage": "^3.0.2",
+    "react": ">=17.0.0",
+    "react-native": ">=0.70.0"
+  },
+  "license": "MIT"
+}

package/src/index.js

@@ -0,0 +1,539 @@
+/*!
+ * @cosmoola/cosmoola-native — React Native SDK  v1.0.0
+ * ==========================================================
+ * Cosmoola SDK for React Native (Expo + bare workflow).
+ *
+ * USAGE:
+ *
+ *   import { CurrencyProvider, useCurrency, CsmPrice } from "@cosmoola/cosmoola-native";
+ *
+ *   // Wrap your app once in App.js
+ *   <CurrencyProvider apiKey="pk_live_xxx">
+ *     <App />
+ *   </CurrencyProvider>
+ *
+ *   // Use anywhere
+ *   const { convert, currency, setCurrency } = useCurrency();
+ *   <Text>{convert(99.99)}</Text>
+ *
+ *   // Drop-in price component
+ *   <CsmPrice amount={99.99} from="USD" />
+ *
+ * Payment methods (same as cosmoola-js):
+ *   const { paymentIntent, error } = await cosmoola.confirmCardPayment(clientSecret, { ... });
+ *   await cosmoola.confirmMobileMoneyPayment(clientSecret, { phone, country });
+ *
+ * No DOM, no localStorage — fully React Native compatible.
+ * ==========================================================
+ */
+
+import React, {
+  createContext,
+  useContext,
+  useEffect,
+  useState,
+  useCallback,
+  useRef,
+} from "react";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { Text } from "react-native";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CONSTANTS
+// ─────────────────────────────────────────────────────────────────────────────
+
+const API_BASE          = "https://cosmoola.com/api";
+const CURRENCY_API_BASE = "https://cosmoola.com/currency";
+const SDK_VERSION       = "1.0.0";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CACHE — AsyncStorage instead of localStorage
+// ─────────────────────────────────────────────────────────────────────────────
+
+const CACHE_KEY    = "csm_rates_v1";
+const CACHE_TS_KEY = "csm_rates_ts";
+const CACHE_TTL    = 24 * 60 * 60 * 1000; // 24 hours
+
+async function _cacheGet() {
+  try {
+    const ts     = parseInt((await AsyncStorage.getItem(CACHE_TS_KEY)) || "0", 10);
+    const cached = await AsyncStorage.getItem(CACHE_KEY);
+    if (cached && Date.now() - ts < CACHE_TTL) return JSON.parse(cached);
+  } catch {}
+  return null;
+}
+
+async function _cacheSet(data) {
+  try {
+    await AsyncStorage.setItem(CACHE_KEY, JSON.stringify(data));
+    await AsyncStorage.setItem(CACHE_TS_KEY, String(Date.now()));
+  } catch {}
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// COUNTRY DETECTION — IP based, no window/navigator needed
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function _detectCountry() {
+  try {
+    const controller = new AbortController();
+    const timeout    = setTimeout(() => controller.abort(), 3000);
+    const res        = await fetch("https://ipapi.co/json/", { signal: controller.signal });
+    clearTimeout(timeout);
+    const d = await res.json();
+    return d.country_code || null;
+  } catch {
+    return null;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// HTTP HELPERS — pure fetch, works in RN
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function _apiCall(method, endpoint, key, body = null, base = API_BASE) {
+  try {
+    const opts = {
+      method,
+      headers: {
+        "Authorization":    `Bearer ${key}`,
+        "Content-Type":     "application/json",
+        "Cosmoola-Version": SDK_VERSION,
+      },
+    };
+    if (body && method !== "GET") opts.body = JSON.stringify(body);
+    const res  = await fetch(`${base}/${endpoint}`, opts);
+    const data = await res.json();
+    if (!res.ok) return { error: data?.error || data };
+    return data;
+  } catch (e) {
+    return { error: { message: e.message, type: "network_error" } };
+  }
+}
+
+const _post = (endpoint, key, body, base = API_BASE) =>
+  _apiCall("POST", endpoint, key, body, base);
+
+const _get = (endpoint, key, params = {}, base = API_BASE) => {
+  const qs = Object.keys(params).length
+    ? "?" + new URLSearchParams(params).toString()
+    : "";
+  return _apiCall("GET", `${endpoint}${qs}`, key, null, base);
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CURRENCY HELPERS
+// ─────────────────────────────────────────────────────────────────────────────
+
+function _convertRaw(amount, from, to, rates) {
+  if (!rates || from === to) return amount;
+  const fromRate = rates[from] || 1;
+  const toRate   = rates[to]   || 1;
+  return (amount / fromRate) * toRate;
+}
+
+function _format(amount, currencyCode, symbols) {
+  const symbol     = symbols?.[currencyCode] || currencyCode;
+  const noDecimals = new Set([
+    "JPY","KRW","IDR","VND","CLP","ISK","PYG","UGX","TZS",
+    "BIF","RWF","GNF","MGA","KMF","XAF","XOF","XPF","DJF",
+  ]);
+  const decimals  = noDecimals.has(currencyCode) ? 0 : 2;
+  const formatted = amount
+    .toFixed(decimals)
+    .replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+  return `${symbol}${formatted}`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MOBILE MONEY COUNTRIES
+// ─────────────────────────────────────────────────────────────────────────────
+
+const MOBILE_MONEY_COUNTRIES = {
+  KE: { provider:"safaricom", method:"mpesa",  label:"M-Pesa",       prefix:"254", currency:"KES" },
+  TZ: { provider:"vodacom",   method:"mpesa",  label:"M-Pesa",       prefix:"255", currency:"TZS" },
+  NG: { provider:"mtn",       method:"momo",   label:"MTN MoMo",     prefix:"234", currency:"NGN" },
+  GH: { provider:"mtn",       method:"momo",   label:"MTN MoMo",     prefix:"233", currency:"GHS" },
+  UG: { provider:"airtel",    method:"airtel", label:"Airtel Money", prefix:"256", currency:"UGX" },
+  RW: { provider:"mtn",       method:"momo",   label:"MTN MoMo",     prefix:"250", currency:"RWF" },
+  ZM: { provider:"airtel",    method:"airtel", label:"Airtel Money", prefix:"260", currency:"ZMW" },
+  MW: { provider:"airtel",    method:"airtel", label:"Airtel Money", prefix:"265", currency:"MWK" },
+  SN: { provider:"orange",    method:"orange", label:"Orange Money", prefix:"221", currency:"XOF" },
+  CI: { provider:"orange",    method:"orange", label:"Orange Money", prefix:"225", currency:"XOF" },
+  CM: { provider:"mtn",       method:"momo",   label:"MTN MoMo",     prefix:"237", currency:"XAF" },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CosmoolaNative — main class (mirrors cosmoola-js CosmooolaInstance)
+// Use this if you want the imperative API without React hooks
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class CosmoolaNative {
+  constructor(publishableKey, options = {}) {
+    if (!publishableKey) throw new Error("[Cosmoola] publishableKey is required.");
+    if (!publishableKey.startsWith("pk_live_") && !publishableKey.startsWith("pk_test_"))
+      throw new Error("[Cosmoola] Invalid key. Must start with pk_live_ or pk_test_");
+
+    this._key      = publishableKey;
+    this._mode     = publishableKey.includes("_test_") ? "test" : "live";
+    this._country  = options.country || null;
+    this.currency  = new NativeCurrency(publishableKey);
+  }
+
+  // ── confirmCardPayment ────────────────────────────────────────────────────
+  async confirmCardPayment(clientSecret, data = {}) {
+    try {
+      const intentId = _extractIntentId(clientSecret);
+      const res = await _post("confirmPaymentIntent", this._key, {
+        id:             intentId,
+        payment_method: data.payment_method,
+        return_url:     data.return_url || "",
+      });
+      if (res.error) return { error: res.error };
+      return { paymentIntent: res };
+    } catch (e) {
+      return { error: { type: "api_error", message: e.message } };
+    }
+  }
+
+  // ── confirmMobileMoneyPayment ─────────────────────────────────────────────
+  async confirmMobileMoneyPayment(clientSecret, data = {}) {
+    try {
+      if (!data.phone)   throw new Error("phone is required");
+      if (!data.country) throw new Error("country is required");
+
+      const country = data.country.toUpperCase();
+      const config  = MOBILE_MONEY_COUNTRIES[country];
+      if (!config) return { error: { message: `Mobile money not supported for: ${country}` } };
+
+      const intentId = _extractIntentId(clientSecret);
+      const endpoint = {
+        mpesa:  "initiateMpesa",
+        momo:   "initiateMtnMomo",
+        airtel: "initiateAirtel",
+        orange: "initiateOrange",
+      }[config.method];
+
+      const res = await _post(endpoint, this._key, {
+        payment_intent_id: intentId,
+        phone:    data.phone,
+        amount:   data.amount,
+        currency: data.currency || config.currency,
+        country,
+      });
+
+      if (res.error) return { error: res.error };
+      return { paymentIntent: { id: intentId, status: "processing" }, mobile_money: res };
+    } catch (e) {
+      return { error: { type: "api_error", message: e.message } };
+    }
+  }
+
+  // ── retrievePaymentIntent ─────────────────────────────────────────────────
+  async retrievePaymentIntent(clientSecret) {
+    try {
+      const intentId = _extractIntentId(clientSecret);
+      const res = await _get("getPaymentStatus", this._key, { id: intentId });
+      if (res.error) return { error: res.error };
+      return { paymentIntent: res };
+    } catch (e) {
+      return { error: { type: "api_error", message: e.message } };
+    }
+  }
+
+  // ── pollPaymentStatus ─────────────────────────────────────────────────────
+  async pollPaymentStatus(clientSecret, options = {}) {
+    const { interval = 3000, maxChecks = 40, onUpdate } = options;
+    const TERMINAL = ["succeeded", "canceled", "failed"];
+    let count = 0;
+
+    return new Promise((resolve) => {
+      const timer = setInterval(async () => {
+        count++;
+        const { paymentIntent, error } = await this.retrievePaymentIntent(clientSecret);
+        if (error) { clearInterval(timer); resolve({ error }); return; }
+        if (onUpdate) onUpdate(paymentIntent);
+        if (TERMINAL.includes(paymentIntent.status)) {
+          clearInterval(timer);
+          resolve({ paymentIntent });
+          return;
+        }
+        if (count >= maxChecks) {
+          clearInterval(timer);
+          resolve({ error: { type: "timeout_error", message: "Payment polling timed out." } });
+        }
+      }, interval);
+    });
+  }
+
+  getPublishableKey() { return this._key; }
+  getMode()           { return this._mode; }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// NativeCurrency — currency methods for React Native
+// Accessed via cosmoola.currency or via useCurrency() hook
+// ─────────────────────────────────────────────────────────────────────────────
+
+class NativeCurrency {
+  constructor(key) {
+    this._key          = key;
+    this._rates        = null;
+    this._symbols      = {};
+    this._names        = {};
+    this._countryMap   = {};
+    this._active       = "USD";
+    this._readyPromise = null;
+  }
+
+  async init(country = null) {
+    if (this._readyPromise) return this._readyPromise;
+    this._readyPromise = (async () => {
+      const cached = await _cacheGet();
+      if (cached) {
+        this._rates      = cached.rates;
+        this._symbols    = cached.symbols    || {};
+        this._names      = cached.names      || {};
+        this._countryMap = cached.countryMap || {};
+        this._active     = cached.detected   || "USD";
+        return;
+      }
+      const detectedCountry = country || await _detectCountry();
+      const params = detectedCountry ? { country: detectedCountry } : {};
+      const data   = await _get("getCurrencyRates", this._key, params, CURRENCY_API_BASE);
+      if (data.error) { console.warn("[Cosmoola] Currency init failed:", data.error.message); return; }
+      this._rates      = data.rates;
+      this._symbols    = data.symbols    || {};
+      this._names      = data.names      || {};
+      this._countryMap = data.countryMap || {};
+      this._active     = data.detected   || "USD";
+      await _cacheSet(data);
+    })();
+    return this._readyPromise;
+  }
+
+  async getRates(country = null) {
+    await this.init(country);
+    return { rates: this._rates, symbols: this._symbols, names: this._names, countryMap: this._countryMap, detected: this._active, base: "USD" };
+  }
+
+  async convert(amount, from = "USD", to = null) {
+    await this.init();
+    const target = to || this._active || "USD";
+    return _format(_convertRaw(amount, from, target, this._rates || {}), target, this._symbols);
+  }
+
+  async convertRaw(amount, from = "USD", to = null) {
+    await this.init();
+    const target = to || this._active || "USD";
+    return _convertRaw(amount, from, target, this._rates || {});
+  }
+
+  setCurrency(code) { this._active = code.toUpperCase(); }
+  getActiveCurrency() { return this._active; }
+  getSymbol(code = null) { return this._symbols[code || this._active] || "$"; }
+  getAllCurrencies() {
+    if (!this._rates) return [];
+    return Object.keys(this._rates).map(code => ({
+      code, symbol: this._symbols[code] || code, name: this._names[code] || code, rate: this._rates[code],
+    }));
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// React Native Context + Provider
+// ─────────────────────────────────────────────────────────────────────────────
+
+const CurrencyContext = createContext(null);
+
+/**
+ * Wrap your entire app ONCE in App.js — works everywhere inside.
+ *
+ * @example
+ * // App.js
+ * import { CurrencyProvider } from "@cosmoola/cosmoola-native";
+ *
+ * export default function App() {
+ *   return (
+ *     <CurrencyProvider apiKey="pk_live_xxx">
+ *       <NavigationContainer>...</NavigationContainer>
+ *     </CurrencyProvider>
+ *   );
+ * }
+ */
+export function CurrencyProvider({ apiKey, defaultCurrency = "USD", country = null, children }) {
+  const [rates,    setRates]    = useState(null);
+  const [symbols,  setSymbols]  = useState({});
+  const [names,    setNames]    = useState({});
+  const [currency, setCurrency] = useState(defaultCurrency);
+  const [loading,  setLoading]  = useState(true);
+  const [error,    setError]    = useState(null);
+
+  useEffect(() => {
+    async function init() {
+      try {
+        // Try AsyncStorage cache first
+        const cached = await _cacheGet();
+        if (cached) {
+          setRates(cached.rates);
+          setSymbols(cached.symbols || {});
+          setNames(cached.names || {});
+          setCurrency(cached.detected || defaultCurrency);
+          setLoading(false);
+          return;
+        }
+
+        // Detect country then fetch
+        const detectedCountry = country || await _detectCountry();
+        const params = detectedCountry ? { country: detectedCountry } : {};
+        const data   = await _get("getCurrencyRates", apiKey, params, CURRENCY_API_BASE);
+
+        if (data.error) throw new Error(data.error.message);
+
+        setRates(data.rates);
+        setSymbols(data.symbols || {});
+        setNames(data.names || {});
+        setCurrency(data.detected || defaultCurrency);
+        await _cacheSet(data);
+      } catch (e) {
+        setError(e.message);
+        console.warn("[Cosmoola Native] Failed to load rates:", e.message);
+      } finally {
+        setLoading(false);
+      }
+    }
+    init();
+  }, [apiKey, country]);
+
+  const convert = useCallback((amount, from = "USD") => {
+    if (!rates) return String(amount);
+    return _format(_convertRaw(amount, from, currency, rates), currency, symbols);
+  }, [rates, symbols, currency]);
+
+  const convertRaw = useCallback((amount, from = "USD") => {
+    if (!rates) return amount;
+    return _convertRaw(amount, from, currency, rates);
+  }, [rates, currency]);
+
+  const allCurrencies = rates
+    ? Object.keys(rates).map(code => ({ code, symbol: symbols[code] || code, name: names[code] || code, rate: rates[code] }))
+    : [];
+
+  return (
+    <CurrencyContext.Provider value={{
+      loading, error, currency, setCurrency,
+      symbol: symbols[currency] || "$",
+      convert, convertRaw,
+      rates, symbols, names, allCurrencies,
+    }}>
+      {children}
+    </CurrencyContext.Provider>
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useCurrency — hook, use anywhere inside <CurrencyProvider>
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * @example
+ * const { convert, currency, setCurrency } = useCurrency();
+ * <Text>{convert(99.99)}</Text>  // → "£79.23"
+ */
+export function useCurrency() {
+  const ctx = useContext(CurrencyContext);
+  if (!ctx) throw new Error("[Cosmoola] useCurrency() must be called inside <CurrencyProvider>");
+  return ctx;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CsmPrice — drop-in React Native price component
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * @example
+ * <CsmPrice amount={99.99} />
+ * <CsmPrice amount={99.99} from="USD" style={{ fontSize: 18, fontWeight: "bold" }} />
+ */
+export function CsmPrice({ amount, from = "USD", style }) {
+  const { convert, loading } = useCurrency();
+  return (
+    <Text style={style}>
+      {loading ? String(amount) : convert(amount, from)}
+    </Text>
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// useMobilePayment — hook for mobile money flows in React Native
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * @example
+ * const { initiate, status, error } = useMobilePayment("pk_live_xxx");
+ *
+ * await initiate({
+ *   clientSecret: "pi_xxx_secret_xxx",
+ *   phone: "+254712345678",
+ *   country: "KE",
+ *   amount: 500,
+ * });
+ */
+export function useMobilePayment(publishableKey) {
+  const cosmoolaRef = useRef(null);
+  if (!cosmoolaRef.current) cosmoolaRef.current = new CosmoolaNative(publishableKey);
+
+  const [status,  setStatus]  = useState("idle");
+  const [error,   setError]   = useState(null);
+  const [receipt, setReceipt] = useState(null);
+
+  const reset = useCallback(() => {
+    setStatus("idle"); setError(null); setReceipt(null);
+  }, []);
+
+  const initiate = useCallback(async ({ clientSecret, phone, country, amount, currency }) => {
+    setStatus("pending"); setError(null);
+    const cosmoola = cosmoolaRef.current;
+
+    const result = await cosmoola.confirmMobileMoneyPayment(clientSecret, {
+      phone, country, amount, currency,
+    });
+
+    if (result.error) { setError(result.error); setStatus("failed"); return; }
+
+    setStatus("polling");
+    setReceipt(result.mobile_money);
+
+    const { paymentIntent, error: pollError } = await cosmoola.pollPaymentStatus(clientSecret, {
+      interval: 3000, maxChecks: 40,
+    });
+
+    if (pollError) { setError(pollError); setStatus("failed"); }
+    else           { setStatus(paymentIntent.status === "succeeded" ? "succeeded" : "failed"); }
+  }, []);
+
+  return { initiate, status, error, receipt, reset };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// UTILITIES
+// ─────────────────────────────────────────────────────────────────────────────
+
+function _extractIntentId(clientSecret) {
+  const parts = (clientSecret || "").split("_secret_");
+  if (parts.length < 2) throw new Error("[Cosmoola] Invalid client_secret format.");
+  return parts[0];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// EXPORTS
+// ─────────────────────────────────────────────────────────────────────────────
+
+export {
+  MOBILE_MONEY_COUNTRIES,
+  API_BASE,
+  CURRENCY_API_BASE,
+  SDK_VERSION,
+};
+
+export default CosmoolaNative;

package/types/index.d.ts

@@ -0,0 +1,156 @@
+// @cosmoola/cosmoola-native — TypeScript definitions v1.0.0
+
+import React, { ReactNode } from "react";
+import { TextStyle } from "react-native";
+
+// ─── Core ────────────────────────────────────────────────────────────────────
+
+export declare const API_BASE:          string;
+export declare const CURRENCY_API_BASE: string;
+export declare const SDK_VERSION:       string;
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface PaymentIntent {
+  id:             string;
+  status:         "requires_payment_method" | "processing" | "succeeded" | "canceled" | "failed" | "requires_action";
+  amount:         number;
+  currency:       string;
+  client_secret?: string;
+}
+
+export interface CosmoolaError {
+  type:     string;
+  code?:    string;
+  message:  string;
+}
+
+export interface MobileMoneyResult {
+  id:      string;
+  status:  string;
+  method:  string;
+  phone?:  string;
+}
+
+export interface CurrencyData {
+  rates:      Record<string, number>;
+  symbols:    Record<string, string>;
+  names:      Record<string, string>;
+  countryMap: Record<string, string>;
+  detected:   string;
+  base:       string;
+}
+
+export interface CurrencyItem {
+  code:   string;
+  symbol: string;
+  name:   string;
+  rate:   number;
+}
+
+// ─── CosmoolaNative ──────────────────────────────────────────────────────────
+
+export declare class CosmoolaNative {
+  constructor(publishableKey: string, options?: { country?: string });
+
+  currency: NativeCurrency;
+
+  confirmCardPayment(
+    clientSecret: string,
+    data: {
+      payment_method: { card: { number: string; exp_month: string; exp_year: string; cvc: string; name?: string } };
+      return_url?: string;
+    }
+  ): Promise<{ paymentIntent?: PaymentIntent; error?: CosmoolaError }>;
+
+  confirmMobileMoneyPayment(
+    clientSecret: string,
+    data: { phone: string; country: string; amount?: number; currency?: string }
+  ): Promise<{ paymentIntent?: PaymentIntent; mobile_money?: MobileMoneyResult; error?: CosmoolaError }>;
+
+  retrievePaymentIntent(
+    clientSecret: string
+  ): Promise<{ paymentIntent?: PaymentIntent; error?: CosmoolaError }>;
+
+  pollPaymentStatus(
+    clientSecret: string,
+    options?: { interval?: number; maxChecks?: number; onUpdate?: (pi: PaymentIntent) => void }
+  ): Promise<{ paymentIntent?: PaymentIntent; error?: CosmoolaError }>;
+
+  getPublishableKey(): string;
+  getMode(): "live" | "test";
+}
+
+// ─── NativeCurrency ──────────────────────────────────────────────────────────
+
+export declare class NativeCurrency {
+  init(country?: string): Promise<void>;
+  getRates(country?: string): Promise<CurrencyData>;
+  convert(amount: number, from?: string, to?: string): Promise<string>;
+  convertRaw(amount: number, from?: string, to?: string): Promise<number>;
+  setCurrency(code: string): void;
+  getActiveCurrency(): string;
+  getSymbol(code?: string): string;
+  getAllCurrencies(): CurrencyItem[];
+}
+
+// ─── CurrencyProvider ────────────────────────────────────────────────────────
+
+export interface CurrencyContextValue {
+  loading:        boolean;
+  error:          string | null;
+  currency:       string;
+  setCurrency:    (code: string) => void;
+  symbol:         string;
+  convert:        (amount: number, from?: string) => string;
+  convertRaw:     (amount: number, from?: string) => number;
+  rates:          Record<string, number> | null;
+  symbols:        Record<string, string>;
+  names:          Record<string, string>;
+  allCurrencies:  CurrencyItem[];
+}
+
+export declare function CurrencyProvider(props: {
+  apiKey:           string;
+  defaultCurrency?: string;
+  country?:         string;
+  children:         ReactNode;
+}): React.ReactElement;
+
+// ─── Hooks ───────────────────────────────────────────────────────────────────
+
+export declare function useCurrency(): CurrencyContextValue;
+
+export declare function useMobilePayment(publishableKey: string): {
+  initiate: (params: {
+    clientSecret: string;
+    phone:        string;
+    country:      string;
+    amount?:      number;
+    currency?:    string;
+  }) => Promise<void>;
+  status:  "idle" | "pending" | "polling" | "succeeded" | "failed";
+  error:   CosmoolaError | null;
+  receipt: MobileMoneyResult | null;
+  reset:   () => void;
+};
+
+// ─── Components ──────────────────────────────────────────────────────────────
+
+export declare function CsmPrice(props: {
+  amount: number;
+  from?:  string;
+  style?: TextStyle;
+}): React.ReactElement;
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+export declare const MOBILE_MONEY_COUNTRIES: Record<string, {
+  provider: string;
+  method:   string;
+  label:    string;
+  prefix:   string;
+  currency: string;
+}>;
+
+export default CosmoolaNative;