fix(pos-app): rename partner API key to customer API key

[ignaciosantise]

Summary

• Renames partner API key terminology to customer across settings UI, hooks, store API, payment services, web URL params, env defaults, docs, and tests.
• Bumps persisted settings schema to v13 with state migration from isPartnerApiKeySet to isCustomerApiKeySet and secure-storage key migration from legacy keys to customer_api_key.
• Hardened fresh-install cleanup by deleting legacy secure-storage keys (merchant_api_key, partner_api_key) so stale credentials cannot be re-imported during migration.
• Adds postMessage as the primary credential injection method on web, keeping URL query params as fallback.
• Increments Android versionCode in dapps/pos-app/app.json from 17 to 18.

postMessage Protocol

Parent/opener sends credentials to the POS app window via plain text (no base64 needed):

posWindow.postMessage({
  type: "pos-credentials",
  merchantId: "merchant-123",        // optional
  customerApiKey: "api-key-456"      // optional
}, "*");

• URL params still work as fallback (?merchantId=<base64>&customerApiKey=<base64>)
• Both methods overwrite previously stored credentials

Flow

flowchart TD
  A[App Rehydrate] --> B[clearStaleSecureStorage]
  B --> C[Delete customer_api_key + legacy keys]
  A --> D[migrateCustomerApiKey]
  D --> E{customer_api_key exists?}
  E -- No --> F[Copy first legacy key to customer_api_key]
  E -- Yes --> G[Keep existing customer_api_key]
  F --> H[Delete legacy keys]
  G --> H

Loading

Validation

• npm test -- --runInBand __tests__/hooks/use-url-credentials.test.ts __tests__/services/payment.test.ts __tests__/store/useSettingsStore.test.ts __tests__/utils/secure-storage.test.ts
• npx tsc --noEmit

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
react-native-examples	Ready	Preview, Comment	Feb 27, 2026 5:07pm

[claude]

Claude finished @ignaciosantise's task in 3m 1s —— View job

---

Code Review

• Read CLAUDE.md and gather context
• Read changed files
• Run breaking changes subagent
• Run data classification subagent
• Compile and post review

---

Found 5 issue(s)

Issue 1: URL query parameter renamed without fallback

ID: brk-use-url-credentials-url-param-rename-b7c4
File: dapps/pos-app/hooks/use-url-credentials.ts:32
Severity: HIGH
Category: breaking_change

Context:

• Pattern: params.get("customerApiKey") with no fallback to the old partnerApiKey param name
• Risk: Any external URL, script, or automated onboarding flow using ?partnerApiKey=<base64> silently stops working — the hook finds nothing, no API key is applied, user hits settings without pre-populated credentials
• Impact: The feature was introduced in 63c00c8, any consumers already using it break without notice
• Trigger: Web app loaded with a URL containing ?partnerApiKey=

Recommendation: Add temporary fallback during transition:

const rawCustomerApiKey = params.get("customerApiKey") ?? params.get("partnerApiKey");

---

Issue 2: Env variable renamed without backward compat

ID: brk-env-example-partner-to-customer-env-var-a3f2
File: dapps/pos-app/.env.example:7
Severity: HIGH
Category: breaking_change

Context:

• Pattern: EXPO_PUBLIC_DEFAULT_PARTNER_API_KEY → EXPO_PUBLIC_DEFAULT_CUSTOMER_API_KEY with no runtime fallback
• Risk: Any CI pipeline, hosting environment, or dev machine with the old env var set will silently lose the default API key — app behaves as if no key is configured without any error
• Impact: Build deployments that have not updated their environment variables (.env, CI secrets, hosting platform vars)
• Trigger: Every build in an environment with the old var name still set

Recommendation: Add a dev-mode guard in merchant-config.ts to warn when the old var is set but the new one is not, and document this as a required manual migration in the PR.

---

Issue 3: Hardcoded key string instead of constant in migration

ID: secure-storage-hardcoded-key-constant-f3a1
File: dapps/pos-app/utils/secure-storage.ts:41
Severity: MEDIUM
Category: code_quality

Context:

• Pattern: const NEW_KEY = "customer_api_key" is a hardcoded string literal; the rest of the file uses KEYS.CUSTOMER_API_KEY for the same value
• Risk: If the key value ever changes, this migration function would be silently left behind pointing at the old key name while reads/writes use the new constant
• Impact: Silent data loss: migrated key written to wrong location, getCustomerApiKey() returns null, user's API key disappears
• Trigger: Any future refactor of the KEYS.CUSTOMER_API_KEY value

Recommendation:

const NEW_KEY = KEYS.CUSTOMER_API_KEY; // was hardcoded "customer_api_key"

---

Issue 4: API key transmitted via URL query parameter

ID: dcl-use-url-credentials-apikey-url-exposure-c2d9
File: dapps/pos-app/hooks/use-url-credentials.ts:31-51
Severity: HIGH
Category: security

Context:

• Pattern: customerApiKey is accepted as a base64-encoded (not encrypted) URL query parameter
• Risk: URL query parameters are logged by browsers (history), proxies, CDNs, reverse proxies, and web server access logs. Base64 is trivially decoded. This exposes a credential-tier secret via a low-security channel
• Impact: Any environment where URL access logs are retained or shared (analytics, CDN logs, Vercel deployment logs) leaks the API key in plaintext
• Trigger: Any web deployment that uses URL-based credential injection for onboarding

Recommendation: Use a short-lived signed token or server-side session handoff instead of embedding the raw key in the URL. If URL delivery is required, use a one-time code that is exchanged server-side for the actual key.

---

Issue 5: Error message text change breaks monitoring rules

ID: brk-payment-error-message-text-rename-d1e8
File: dapps/pos-app/services/payment.ts, dapps/pos-app/services/payment.web.ts
Severity: LOW
Category: breaking_change

Context:

• Pattern: Error message changed from "Partner API key is not configured" to "Customer API key is not configured"
• Risk: Sentry alert rules, error grouping, or monitoring dashboards that match the exact old string will stop firing
• Impact: Silent monitoring gap for the "API key missing" failure path until alert rules are updated
• Trigger: Payment attempted without a configured API key after deploying this change

Recommendation: Update any Sentry/monitoring alert rules that reference the old message text before or immediately after deploying.

[ignaciosantise]

Review Response — All 5 issues discarded

Issue 1 (URL param no fallback): Discarded — user explicitly chose a clean break during planning. No backward compatibility for the old partnerApiKey param.

Issue 2 (Env var no fallback): Discarded — fallback not needed in this case. Environments using the old var name will update as part of this rename.

Issue 3 (Hardcoded key in migration): Discarded — intentional pattern. Migration functions should use hardcoded strings to remain stable regardless of future constant changes. If KEYS.CUSTOMER_API_KEY is ever renamed, the migration must still reference the original value it was written for.

Issue 4 (API key in URL): Discarded — pre-existing design introduced in commit 63c00c8, out of scope for this rename PR.

Issue 5 (Error message monitoring): Discarded — standard consequence of the rename with low risk. No monitoring rules reference the old message text.