feat(pos-app): unify merchant API base URL, keep separate auth

Consolidate to single base URL (EXPO_PUBLIC_API_URL) for both Payment and
Merchant APIs, removing EXPO_PUBLIC_MERCHANT_API_URL. Delete redundant
merchant-client.ts and reuse apiClient. Extract getApiHeaders() to shared
client module for payment endpoints.

Merchant endpoints retain separate auth via EXPO_PUBLIC_MERCHANT_PORTAL_API_KEY
since the Merchants API has its own auth layer. Added TODOs for when APIs
unify auth. Fix incomplete test mock after module export migration.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ignaciosantise

dapps/pos-app/.env.example

@@ -5,5 +5,4 @@ EXPO_PUBLIC_API_URL=""
 EXPO_PUBLIC_GATEWAY_URL=""
 EXPO_PUBLIC_DEFAULT_MERCHANT_ID=""
 EXPO_PUBLIC_DEFAULT_PARTNER_API_KEY=""
-EXPO_PUBLIC_MERCHANT_API_URL=""
-EXPO_PUBLIC_MERCHANT_PORTAL_API_KEY=""
+EXPO_PUBLIC_MERCHANT_PORTAL_API_KEY=""

dapps/pos-app/AGENTS.md

@@ -129,7 +129,7 @@ Uses **Expo Router** with file-based routing:
    - Filter tabs: All, Failed, Pending, Completed
    - Transaction detail modal on tap
    - Empty state when no transactions
-   - Uses Merchant Portal API for data fetching
+   - Uses unified API for data fetching
 
 ### 2. Receipt Printing
 
@@ -174,9 +174,10 @@ Uses **Expo Router** with file-based routing:
 
 ## Payment API Integration
 
-### Payment API Client (`services/client.ts`)
+### API Client (`services/client.ts`)
 
 - Base URL from `EXPO_PUBLIC_API_URL` environment variable
+- Shared `getApiHeaders()` helper for authenticated requests
 - Request/response interceptors
 - Error handling
 
@@ -204,33 +205,24 @@ All Payment API requests include:
 - `Sdk-Version`: "1.0.0"
 - `Sdk-Platform`: "react-native"
 
-## Merchant Portal API Integration
-
-The Merchant Portal API is a separate backend used for fetching transaction history (Activity screen).
-
-### Merchant API Client (`services/merchant-client.ts`)
-
-- Base URL from `EXPO_PUBLIC_MERCHANT_API_URL` environment variable
-- Generic HTTP client (no credentials baked in)
-- API key passed per-request via headers
-- Used by native apps (iOS/Android) for direct API calls
-
-### Server-Side Proxy (`api/transactions.ts`)
-
-- Vercel serverless function that proxies requests to the Merchant Portal API (web only)
-- API key read from server-side env (`EXPO_PUBLIC_MERCHANT_PORTAL_API_KEY`)
-- Client only sends `x-merchant-id` header
-- Avoids CORS issues by making requests server-side
-
 ### Transactions Service (`services/transactions.ts`)
 
+> **Note:** The Merchants API currently has its own auth layer separate from the Payment API. Both share the same base URL (`EXPO_PUBLIC_API_URL`), but merchant endpoints authenticate via `EXPO_PUBLIC_MERCHANT_PORTAL_API_KEY` (sent as `x-api-key` header) rather than the partner API key used by payment endpoints. This will be unified in the future.
+
 **`getTransactions(options)`**
 
 - Fetches merchant transaction history
 - Endpoint: `GET /merchants/{merchant_id}/payments`
+- Uses the shared base URL (`EXPO_PUBLIC_API_URL`) but authenticates with `EXPO_PUBLIC_MERCHANT_PORTAL_API_KEY`
 - Supports filtering by status, date range, pagination
 - Returns array of `PaymentRecord` objects
 
+### Server-Side Proxy (`api/transactions.ts`)
+
+- Vercel serverless function that proxies transaction requests (web only)
+- Client only sends `x-merchant-id` header; API key is handled server-side via `EXPO_PUBLIC_MERCHANT_PORTAL_API_KEY`
+- Avoids CORS issues by making requests server-side
+
 ### useTransactions Hook (`services/hooks.ts`)
 
 ```typescript
@@ -259,7 +251,6 @@ EXPO_PUBLIC_API_URL=""                 # Payment API base URL
 EXPO_PUBLIC_GATEWAY_URL=""             # WalletConnect gateway URL
 EXPO_PUBLIC_DEFAULT_MERCHANT_ID=""     # Default merchant ID (optional)
 EXPO_PUBLIC_DEFAULT_PARTNER_API_KEY="" # Default partner API key (optional)
-EXPO_PUBLIC_MERCHANT_API_URL=""        # Merchant Portal API base URL
 EXPO_PUBLIC_MERCHANT_PORTAL_API_KEY="" # Merchant Portal API key (for Activity screen)
 ```
 
@@ -330,8 +321,7 @@ This project uses **npm** (not pnpm or yarn). Always use `npm` commands for inst
 
 ### Services & API
 
-- **`services/client.ts`**: Payment API client configuration
-- **`services/merchant-client.ts`**: Merchant Portal API client (native)
+- **`services/client.ts`**: API client and shared auth headers (`getApiHeaders`)
 - **`services/payment.ts`**: Payment API functions
 - **`services/transactions.ts`**: Transaction fetching (native: direct API)
 - **`services/transactions.web.ts`**: Transaction fetching (web: server-side proxy)
@@ -713,10 +703,13 @@ const apiKey = await secureStorage.getItem(SECURE_STORAGE_KEYS.PARTNER_API_KEY);
 npm run lint          # Check and fix ESLint errors
 npx prettier --write . # Format code with Prettier
 npx tsc --noEmit      # Check for TypeScript errors
+npm test              # Run Jest tests
 ```
 
 Fix any errors found. Pre-existing TypeScript errors in unrelated files can be ignored.
 
+**When moving exports between modules**, update any `jest.mock()` calls in tests that mock the source or destination module. Mocks that use a manual factory (e.g., `jest.mock("@/services/client", () => ({ ... }))`) replace the entire module — any export not included in the factory becomes `undefined` at runtime, which silently breaks tests.
+
 ### Code Style
 
 - Follow TypeScript best practices

dapps/pos-app/__tests__/services/payment.test.ts

@@ -17,8 +17,9 @@ import { apiClient } from "@/services/client";
 // Get the mocked secure store
 const SecureStore = require("expo-secure-store");
 
-// Mock the API client
+// Mock only apiClient, keep real getApiHeaders so header logic is tested
 jest.mock("@/services/client", () => ({
+  ...jest.requireActual("@/services/client"),
   apiClient: {
     get: jest.fn(),
     post: jest.fn(),

dapps/pos-app/api/transactions.ts

@@ -1,6 +1,7 @@
 import type { VercelRequest, VercelResponse } from "@vercel/node";
 
-const MERCHANT_API_BASE_URL = process.env.EXPO_PUBLIC_MERCHANT_API_URL;
+const API_BASE_URL = process.env.EXPO_PUBLIC_API_URL;
+// TODO: Once Merchants API unifies auth with Payment API, forward client credentials instead
 const MERCHANT_PORTAL_API_KEY = process.env.EXPO_PUBLIC_MERCHANT_PORTAL_API_KEY;
 
 /**
@@ -25,9 +26,9 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
       });
     }
 
-    if (!MERCHANT_API_BASE_URL) {
+    if (!API_BASE_URL) {
       return res.status(500).json({
-        message: "MERCHANT_API_BASE_URL is not configured",
+        message: "API_BASE_URL is not configured",
       });
     }
 
@@ -63,7 +64,7 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
     }
 
     const queryString = params.toString();
-    const normalizedBaseUrl = MERCHANT_API_BASE_URL.replace(/\/+$/, "");
+    const normalizedBaseUrl = API_BASE_URL.replace(/\/+$/, "");
     const endpoint = `/merchants/${encodeURIComponent(merchantId)}/payments${queryString ? `?${queryString}` : ""}`;
 
     const response = await fetch(`${normalizedBaseUrl}${endpoint}`, {

dapps/pos-app/services/client.ts

@@ -1,4 +1,5 @@
 import { useLogsStore } from "@/store/useLogsStore";
+import { useSettingsStore } from "@/store/useSettingsStore";
 import { ApiError } from "@/utils/types";
 
 const API_BASE_URL = process.env.EXPO_PUBLIC_API_URL;
@@ -156,3 +157,29 @@ class ApiClient {
 }
 
 export const apiClient = new ApiClient(API_BASE_URL);
+
+/**
+ * Get API headers for authenticated requests
+ * @returns Headers object with Api-Key, Merchant-Id, and SDK headers
+ * @throws Error if partner API key or merchant ID is missing
+ */
+export async function getApiHeaders(): Promise<Record<string, string>> {
+  const merchantId = useSettingsStore.getState().merchantId;
+  const partnerApiKey = await useSettingsStore.getState().getPartnerApiKey();
+
+  if (!merchantId || merchantId.trim().length === 0) {
+    throw new Error("Merchant ID is not configured");
+  }
+
+  if (!partnerApiKey || partnerApiKey.trim().length === 0) {
+    throw new Error("Partner API key is not configured");
+  }
+
+  return {
+    "Api-Key": partnerApiKey,
+    "Merchant-Id": merchantId,
+    "Sdk-Name": "pos-device",
+    "Sdk-Version": "1.0.0",
+    "Sdk-Platform": "react-native",
+  };
+}

dapps/pos-app/services/merchant-client.ts

@@ -1,36 +1,9 @@
-import { useSettingsStore } from "@/store/useSettingsStore";
 import {
   PaymentStatusResponse,
   StartPaymentRequest,
   StartPaymentResponse,
 } from "@/utils/types";
-import { apiClient } from "./client";
-
-/**
- * Get API headers for authenticated requests
- * @returns Headers object with Api-Key, Merchant-Id, and SDK headers
- * @throws Error if partner API key or merchant ID is missing
- */
-async function getApiHeaders(): Promise<Record<string, string>> {
-  const merchantId = useSettingsStore.getState().merchantId;
-  const partnerApiKey = await useSettingsStore.getState().getPartnerApiKey();
-
-  if (!merchantId || merchantId.trim().length === 0) {
-    throw new Error("Merchant ID is not configured");
-  }
-
-  if (!partnerApiKey || partnerApiKey.trim().length === 0) {
-    throw new Error("Partner API key is not configured");
-  }
-
-  return {
-    "Api-Key": partnerApiKey,
-    "Merchant-Id": merchantId,
-    "Sdk-Name": "pos-device",
-    "Sdk-Version": "1.0.0",
-    "Sdk-Platform": "react-native",
-  };
-}
+import { apiClient, getApiHeaders } from "./client";
 
 /**
  * Start a new payment

dapps/pos-app/services/payment.ts

@@ -1,6 +1,9 @@
 import { useSettingsStore } from "@/store/useSettingsStore";
 import { TransactionsResponse } from "@/utils/types";
-import { merchantApiClient } from "./merchant-client";
+// TODO: Once Merchants API unifies auth with Payment API, switch to getApiHeaders()
+import { apiClient } from "./client";
+
+const MERCHANT_PORTAL_API_KEY = process.env.EXPO_PUBLIC_MERCHANT_PORTAL_API_KEY;
 
 export interface GetTransactionsOptions {
   status?: string | string[];
@@ -10,10 +13,8 @@ export interface GetTransactionsOptions {
   cursor?: string;
 }
 
-const MERCHANT_PORTAL_API_KEY = process.env.EXPO_PUBLIC_MERCHANT_PORTAL_API_KEY;
-
 /**
- * Fetch merchant transactions from the Merchant Portal API (native version)
+ * Fetch merchant transactions from the API (native version)
  * @param options - Optional query parameters for filtering and pagination
  * @returns TransactionsResponse with list of payments and stats
  */
@@ -60,7 +61,7 @@ export async function getTransactions(
   const queryString = params.toString();
   const endpoint = `/merchants/${merchantId}/payments${queryString ? `?${queryString}` : ""}`;
 
-  return merchantApiClient.get<TransactionsResponse>(endpoint, {
+  return apiClient.get<TransactionsResponse>(endpoint, {
     headers: {
       "x-api-key": MERCHANT_PORTAL_API_KEY,
     },