@reevit/core 0.9.0 → 0.9.1

package/README.md

@@ -8,6 +8,25 @@ The foundation for all Reevit payment SDKs. It provides the shared API client, s
 npm install @reevit/core
 ```
 
+## Compatibility
+
+`@reevit/core` is a regular `dependencies` entry of each framework SDK, so it is
+installed for you. Install it directly only when you are building against the
+low-level API.
+
+| `@reevit/core` | Required by |
+|---|---|
+| 0.9.x | `@reevit/react` 0.9.x–0.10.x, `@reevit/vue` 0.9.x–0.10.x, `@reevit/svelte` 0.9.x–0.10.x |
+
+0.9.1 is a patch release on purpose: it carries the idempotency-key and
+zero-decimal-currency fixes, and the framework SDKs pick it up through their
+existing `^0.9.0` range without a coordinated bump.
+
+On a `0.x` package a caret range pins the **minor**, not the major:
+`^0.9.0` resolves to `>=0.9.0 <0.10.0`. A future `@reevit/core` 0.10.0 is
+therefore not picked up automatically — the React, Vue and Svelte manifests
+have to be bumped together in the same release.
+
 ## Features
 
 - **ReevitAPIClient**: A lightweight, promise-based client for interacting with the Reevit backend.
@@ -74,11 +93,30 @@ if (result.error) {
 ```typescript
 import { formatAmount, validatePhone, detectNetwork } from '@reevit/core';
 
-console.log(formatAmount(10000, 'GHS')); // "GH₵ 100.00"
+console.log(formatAmount(10000, 'GHS')); // "GH₵100.00"
 console.log(validatePhone('0241234567')); // true
 console.log(detectNetwork('0241234567')); // "mtn"
 ```
 
+### Amounts and currency exponents
+
+Amounts are always integers in the smallest unit of the currency, and that unit
+is **not** always 1/100. GHS, NGN and USD have two decimals; XOF, XAF, RWF, UGX,
+JPY and KRW have none — 5,000 XOF is 5000, not 500000.
+
+```typescript
+import { currencyExponent, formatAmount, toMinorUnits } from '@reevit/core';
+
+currencyExponent('GHS'); // 2
+currencyExponent('XOF'); // 0
+
+formatAmount(4500, 'GHS'); // "GH₵45.00"
+formatAmount(5000, 'XOF'); // "F CFA 5,000"  (not "XOF 50.00")
+
+toMinorUnits(45, 'GHS');   // 4500
+toMinorUnits(5000, 'XOF'); // 5000
+```
+
 ### Intent Identity & Idempotency
 
 Core exports helpers to stabilize intent creation and dedupe in-flight requests.
@@ -86,7 +124,7 @@ Core exports helpers to stabilize intent creation and dedupe in-flight requests.
 ```typescript
 import { resolveIntentIdentity } from '@reevit/core';
 
-const { idempotencyKey, reference } = resolveIntentIdentity({
+const { idempotencyKey, lookupKey, reference } = resolveIntentIdentity({
   config: {
     amount: 5000,
     currency: 'GHS',
@@ -97,8 +135,34 @@ const { idempotencyKey, reference } = resolveIntentIdentity({
 });
 ```
 
+**Pass your own order-scoped `idempotencyKey` for retry safety across page
+loads.** Without one, the SDK generates a per-tab attempt key: a UUID minted on
+the first request and kept in `sessionStorage`, so a repeated "Continue" click
+in the same tab is deduped by the API, while a reload or a different shopper
+starts a new attempt.
+
+Two keys are in play and they must not be confused:
+
+| | Value | Where it goes |
+|---|---|---|
+| `idempotencyKey` | UUID from `newIdempotencyKey()` / `attemptIdempotencyKey()`, or the one you supplied | the `Idempotency-Key` request header |
+| `lookupKey` | deterministic djb2 hash from `generateIdempotencyKey()` | local in-flight cache only — **never** the wire |
+
+`generateIdempotencyKey()` stays exported for existing callers, but a 32-bit
+hash is not safe as a wire key: two unrelated shoppers can collide and be handed
+each other's `client_secret`. Use `newIdempotencyKey()` if you need to mint one
+yourself, and `clearIdempotencyAttemptKeys()` to start a fresh attempt after a
+completed checkout.
+
 ## Release Notes
 
+### v0.9.1
+
+- The wire `Idempotency-Key` is now a per-attempt UUID instead of a djb2 hash
+- Zero-decimal currencies (XOF, XAF, RWF, UGX, JPY, …) are no longer divided by 100
+- Added `currencyExponent`, `toMinorUnits`, `newIdempotencyKey`, `attemptIdempotencyKey`, `clearIdempotencyAttemptKeys`
+- First test suite for this package; CI runs `npm test`
+
 ### v0.9.0
 
 - Version alignment across all Reevit SDKs

package/dist/index.d.mts

@@ -331,11 +331,43 @@ interface ReevitAPIClientConfig {
 declare function createPaymentError(response: Response, errorData: APIErrorResponse): PaymentError;
 declare function isPaymentError(error: unknown): error is PaymentError;
 /**
- * Generates a deterministic idempotency key based on input parameters
- * Uses a simple hash function suitable for browser environments
- * Exported for use by SDK hooks (e.g., payment link flows)
+ * Generates a deterministic **cache/lookup** key from input parameters.
+ *
+ * NEVER SEND THIS ON THE WIRE. It is a 32-bit djb2 hash bucketed into
+ * 5-minute windows, so two unrelated shoppers can collide and be handed each
+ * other's payment intent (and therefore each other's `client_secret`), and a
+ * shopper legitimately buying the same item twice inside one window would be
+ * charged once. Its only job is to identify "the same checkout attempt" inside
+ * a single browser tab so the in-flight intent cache can dedupe a repeated
+ * "Continue" click.
+ *
+ * The value actually sent as `Idempotency-Key` is produced by
+ * {@link newIdempotencyKey} / {@link attemptIdempotencyKey}.
+ *
+ * Exported for use by SDK hooks (e.g. payment link flows).
  */
 declare function generateIdempotencyKey(params: Record<string, unknown>): string;
+/**
+ * Generates a fresh, globally unique `Idempotency-Key` (RFC 4122 v4 UUID).
+ * This is the only value that should ever be sent on the wire.
+ */
+declare function newIdempotencyKey(): string;
+/**
+ * Resolves the stable per-checkout-attempt wire key for a deterministic
+ * lookup key (see {@link generateIdempotencyKey}).
+ *
+ * The first call for a lookup key mints a UUID and stores it in
+ * `sessionStorage` (falling back to a module-level map when storage is
+ * unavailable); every later call in the same tab returns that same UUID, so a
+ * repeated "Continue" click is still deduped by the backend. A different tab,
+ * a different shopper or a cleared store yields a different UUID.
+ */
+declare function attemptIdempotencyKey(lookupKey: string): string;
+/**
+ * Forgets every stored per-attempt key, so the next checkout attempt gets a
+ * fresh `Idempotency-Key`. Call it after a completed checkout (and in tests).
+ */
+declare function clearIdempotencyAttemptKeys(): void;
 /**
  * Reevit API Client
  */
@@ -418,6 +450,19 @@ declare function createReevitClient(config: ReevitAPIClientConfig): ReevitAPICli
  * Shared utilities for Reevit SDKs
  */
 
+/**
+ * Returns how many decimal places a currency's minor unit uses: 2 for GHS and
+ * NGN, 0 for XOF, XAF, RWF, UGX, JPY and friends.
+ *
+ * Dividing every amount by 100 renders a 5,000 XOF charge as "XOF 50.00" while
+ * the shopper is actually charged 5,000 — which is why this exists.
+ */
+declare function currencyExponent(currency: string): number;
+/**
+ * Converts a major-unit amount (what a shopper types) into the minor units the
+ * API expects: `toMinorUnits(45, 'GHS') === 4500`, `toMinorUnits(5000, 'XOF') === 5000`.
+ */
+declare function toMinorUnits(major: number, currency: string): number;
 /**
  * Formats an amount from smallest currency unit to display format
  */
@@ -453,6 +498,18 @@ declare function detectCountryFromCurrency(currency: string): string;
 
 /**
  * Intent identity + cache helpers
+ *
+ * Two different keys are in play here and mixing them up is a money bug:
+ *
+ * - the **lookup key** is the deterministic djb2 hash of the checkout
+ *   parameters (`generateIdempotencyKey`). It identifies "the same checkout
+ *   attempt" for the in-flight cache and is never sent to the API.
+ * - the **wire key** is the per-attempt UUID (`attemptIdempotencyKey`) that
+ *   goes out as the `Idempotency-Key` header.
+ *
+ * The cache is keyed by the lookup key and remembers the wire key it minted.
+ * The public helpers accept either key so callers that only ever saw the
+ * `idempotencyKey` field keep working unchanged.
  */
 
 interface IntentIdentityOptions {
@@ -467,16 +524,21 @@ interface IntentCacheEntry {
     response?: PaymentIntentResponse;
     expiresAt: number;
     reference?: string;
+    /** The `Idempotency-Key` sent on the wire for this attempt. */
+    idempotencyKey?: string;
 }
 declare function resolveIntentIdentity(options: IntentIdentityOptions): {
+    /** The value to send as `Idempotency-Key`. */
     idempotencyKey: string;
+    /** The local cache key. Never send this on the wire. */
+    lookupKey: string;
     reference: string;
     cacheEntry?: IntentCacheEntry;
 };
-declare function getIntentCacheEntry(idempotencyKey: string): IntentCacheEntry | undefined;
-declare function cacheIntentPromise(idempotencyKey: string, promise: Promise<PaymentIntentResponse>): IntentCacheEntry;
-declare function cacheIntentResponse(idempotencyKey: string, response: PaymentIntentResponse): IntentCacheEntry;
-declare function clearIntentCacheEntry(idempotencyKey: string): void;
+declare function getIntentCacheEntry(key: string): IntentCacheEntry | undefined;
+declare function cacheIntentPromise(key: string, promise: Promise<PaymentIntentResponse>): IntentCacheEntry;
+declare function cacheIntentResponse(key: string, response: PaymentIntentResponse): IntentCacheEntry;
+declare function clearIntentCacheEntry(key: string): void;
 
 /**
  * Reevit State Machine
@@ -523,4 +585,4 @@ declare function createInitialState(): ReevitState;
  */
 declare function reevitReducer(state: ReevitState, action: ReevitAction): ReevitState;
 
-export { type APIErrorResponse, type CardFormData, type CheckoutProviderOption, type CheckoutSessionResponse, type CheckoutState, type ConfirmPaymentRequest, type CreatePaymentIntentRequest, type HubtelSessionResponse, type IntentCacheEntry, type MobileMoneyFormData, type MobileMoneyNetwork, type PSPConfig, type PSPType, type PaymentDetailResponse, type PaymentError, type PaymentIntent, type PaymentIntentResponse, type PaymentMethod, type PaymentResult, type PaymentSource, ReevitAPIClient, type ReevitAPIClientConfig, type ReevitAPIResult, type ReevitAction, type ReevitCheckoutCallbacks, type ReevitCheckoutConfig, type ReevitState, type ReevitTheme, cacheIntentPromise, cacheIntentResponse, clearIntentCacheEntry, cn, createInitialState, createPaymentError, createReevitClient, createThemeVariables, detectCountryFromCurrency, detectNetwork, formatAmount, formatPhone, generateIdempotencyKey, generateReference, getIntentCacheEntry, isPaymentError, reevitReducer, resolveIntentIdentity, validatePhone };
+export { type APIErrorResponse, type CardFormData, type CheckoutProviderOption, type CheckoutSessionResponse, type CheckoutState, type ConfirmPaymentRequest, type CreatePaymentIntentRequest, type HubtelSessionResponse, type IntentCacheEntry, type MobileMoneyFormData, type MobileMoneyNetwork, type PSPConfig, type PSPType, type PaymentDetailResponse, type PaymentError, type PaymentIntent, type PaymentIntentResponse, type PaymentMethod, type PaymentResult, type PaymentSource, ReevitAPIClient, type ReevitAPIClientConfig, type ReevitAPIResult, type ReevitAction, type ReevitCheckoutCallbacks, type ReevitCheckoutConfig, type ReevitState, type ReevitTheme, attemptIdempotencyKey, cacheIntentPromise, cacheIntentResponse, clearIdempotencyAttemptKeys, clearIntentCacheEntry, cn, createInitialState, createPaymentError, createReevitClient, createThemeVariables, currencyExponent, detectCountryFromCurrency, detectNetwork, formatAmount, formatPhone, generateIdempotencyKey, generateReference, getIntentCacheEntry, isPaymentError, newIdempotencyKey, reevitReducer, resolveIntentIdentity, toMinorUnits, validatePhone };

package/dist/index.d.ts

@@ -331,11 +331,43 @@ interface ReevitAPIClientConfig {
 declare function createPaymentError(response: Response, errorData: APIErrorResponse): PaymentError;
 declare function isPaymentError(error: unknown): error is PaymentError;
 /**
- * Generates a deterministic idempotency key based on input parameters
- * Uses a simple hash function suitable for browser environments
- * Exported for use by SDK hooks (e.g., payment link flows)
+ * Generates a deterministic **cache/lookup** key from input parameters.
+ *
+ * NEVER SEND THIS ON THE WIRE. It is a 32-bit djb2 hash bucketed into
+ * 5-minute windows, so two unrelated shoppers can collide and be handed each
+ * other's payment intent (and therefore each other's `client_secret`), and a
+ * shopper legitimately buying the same item twice inside one window would be
+ * charged once. Its only job is to identify "the same checkout attempt" inside
+ * a single browser tab so the in-flight intent cache can dedupe a repeated
+ * "Continue" click.
+ *
+ * The value actually sent as `Idempotency-Key` is produced by
+ * {@link newIdempotencyKey} / {@link attemptIdempotencyKey}.
+ *
+ * Exported for use by SDK hooks (e.g. payment link flows).
  */
 declare function generateIdempotencyKey(params: Record<string, unknown>): string;
+/**
+ * Generates a fresh, globally unique `Idempotency-Key` (RFC 4122 v4 UUID).
+ * This is the only value that should ever be sent on the wire.
+ */
+declare function newIdempotencyKey(): string;
+/**
+ * Resolves the stable per-checkout-attempt wire key for a deterministic
+ * lookup key (see {@link generateIdempotencyKey}).
+ *
+ * The first call for a lookup key mints a UUID and stores it in
+ * `sessionStorage` (falling back to a module-level map when storage is
+ * unavailable); every later call in the same tab returns that same UUID, so a
+ * repeated "Continue" click is still deduped by the backend. A different tab,
+ * a different shopper or a cleared store yields a different UUID.
+ */
+declare function attemptIdempotencyKey(lookupKey: string): string;
+/**
+ * Forgets every stored per-attempt key, so the next checkout attempt gets a
+ * fresh `Idempotency-Key`. Call it after a completed checkout (and in tests).
+ */
+declare function clearIdempotencyAttemptKeys(): void;
 /**
  * Reevit API Client
  */
@@ -418,6 +450,19 @@ declare function createReevitClient(config: ReevitAPIClientConfig): ReevitAPICli
  * Shared utilities for Reevit SDKs
  */
 
+/**
+ * Returns how many decimal places a currency's minor unit uses: 2 for GHS and
+ * NGN, 0 for XOF, XAF, RWF, UGX, JPY and friends.
+ *
+ * Dividing every amount by 100 renders a 5,000 XOF charge as "XOF 50.00" while
+ * the shopper is actually charged 5,000 — which is why this exists.
+ */
+declare function currencyExponent(currency: string): number;
+/**
+ * Converts a major-unit amount (what a shopper types) into the minor units the
+ * API expects: `toMinorUnits(45, 'GHS') === 4500`, `toMinorUnits(5000, 'XOF') === 5000`.
+ */
+declare function toMinorUnits(major: number, currency: string): number;
 /**
  * Formats an amount from smallest currency unit to display format
  */
@@ -453,6 +498,18 @@ declare function detectCountryFromCurrency(currency: string): string;
 
 /**
  * Intent identity + cache helpers
+ *
+ * Two different keys are in play here and mixing them up is a money bug:
+ *
+ * - the **lookup key** is the deterministic djb2 hash of the checkout
+ *   parameters (`generateIdempotencyKey`). It identifies "the same checkout
+ *   attempt" for the in-flight cache and is never sent to the API.
+ * - the **wire key** is the per-attempt UUID (`attemptIdempotencyKey`) that
+ *   goes out as the `Idempotency-Key` header.
+ *
+ * The cache is keyed by the lookup key and remembers the wire key it minted.
+ * The public helpers accept either key so callers that only ever saw the
+ * `idempotencyKey` field keep working unchanged.
  */
 
 interface IntentIdentityOptions {
@@ -467,16 +524,21 @@ interface IntentCacheEntry {
     response?: PaymentIntentResponse;
     expiresAt: number;
     reference?: string;
+    /** The `Idempotency-Key` sent on the wire for this attempt. */
+    idempotencyKey?: string;
 }
 declare function resolveIntentIdentity(options: IntentIdentityOptions): {
+    /** The value to send as `Idempotency-Key`. */
     idempotencyKey: string;
+    /** The local cache key. Never send this on the wire. */
+    lookupKey: string;
     reference: string;
     cacheEntry?: IntentCacheEntry;
 };
-declare function getIntentCacheEntry(idempotencyKey: string): IntentCacheEntry | undefined;
-declare function cacheIntentPromise(idempotencyKey: string, promise: Promise<PaymentIntentResponse>): IntentCacheEntry;
-declare function cacheIntentResponse(idempotencyKey: string, response: PaymentIntentResponse): IntentCacheEntry;
-declare function clearIntentCacheEntry(idempotencyKey: string): void;
+declare function getIntentCacheEntry(key: string): IntentCacheEntry | undefined;
+declare function cacheIntentPromise(key: string, promise: Promise<PaymentIntentResponse>): IntentCacheEntry;
+declare function cacheIntentResponse(key: string, response: PaymentIntentResponse): IntentCacheEntry;
+declare function clearIntentCacheEntry(key: string): void;
 
 /**
  * Reevit State Machine
@@ -523,4 +585,4 @@ declare function createInitialState(): ReevitState;
  */
 declare function reevitReducer(state: ReevitState, action: ReevitAction): ReevitState;
 
-export { type APIErrorResponse, type CardFormData, type CheckoutProviderOption, type CheckoutSessionResponse, type CheckoutState, type ConfirmPaymentRequest, type CreatePaymentIntentRequest, type HubtelSessionResponse, type IntentCacheEntry, type MobileMoneyFormData, type MobileMoneyNetwork, type PSPConfig, type PSPType, type PaymentDetailResponse, type PaymentError, type PaymentIntent, type PaymentIntentResponse, type PaymentMethod, type PaymentResult, type PaymentSource, ReevitAPIClient, type ReevitAPIClientConfig, type ReevitAPIResult, type ReevitAction, type ReevitCheckoutCallbacks, type ReevitCheckoutConfig, type ReevitState, type ReevitTheme, cacheIntentPromise, cacheIntentResponse, clearIntentCacheEntry, cn, createInitialState, createPaymentError, createReevitClient, createThemeVariables, detectCountryFromCurrency, detectNetwork, formatAmount, formatPhone, generateIdempotencyKey, generateReference, getIntentCacheEntry, isPaymentError, reevitReducer, resolveIntentIdentity, validatePhone };
+export { type APIErrorResponse, type CardFormData, type CheckoutProviderOption, type CheckoutSessionResponse, type CheckoutState, type ConfirmPaymentRequest, type CreatePaymentIntentRequest, type HubtelSessionResponse, type IntentCacheEntry, type MobileMoneyFormData, type MobileMoneyNetwork, type PSPConfig, type PSPType, type PaymentDetailResponse, type PaymentError, type PaymentIntent, type PaymentIntentResponse, type PaymentMethod, type PaymentResult, type PaymentSource, ReevitAPIClient, type ReevitAPIClientConfig, type ReevitAPIResult, type ReevitAction, type ReevitCheckoutCallbacks, type ReevitCheckoutConfig, type ReevitState, type ReevitTheme, attemptIdempotencyKey, cacheIntentPromise, cacheIntentResponse, clearIdempotencyAttemptKeys, clearIntentCacheEntry, cn, createInitialState, createPaymentError, createReevitClient, createThemeVariables, currencyExponent, detectCountryFromCurrency, detectNetwork, formatAmount, formatPhone, generateIdempotencyKey, generateReference, getIntentCacheEntry, isPaymentError, newIdempotencyKey, reevitReducer, resolveIntentIdentity, toMinorUnits, validatePhone };