@nokinc-flur/sdk 0.1.2 → 0.1.4

package/README.md

@@ -23,6 +23,31 @@ npm run gen
 FLUR_BASE_URL=http://localhost:8080 RUN_E2E=1 npm test
 ```
 
+Contract-focused E2E only:
+```bash
+FLUR_BASE_URL=https://your-oci-gateway.example.com RUN_E2E=1 npm run test:contract
+```
+
+Optional envs for full send-money E2E coverage:
+- `FLUR_E2E_SESSION_TOKEN` (required for account/transactions/recipient)
+- `FLUR_E2E_RECIPIENT_IDENTIFIER` (required for recipient resolve / transfer)
+- `FLUR_E2E_SEND_AUTH_TOKEN` (required for transfer create)
+- `FLUR_E2E_DEVICE_ID` (required for transfer create)
+- `FLUR_E2E_AMOUNT_MINOR` (optional, default `100`)
+- `FLUR_E2E_CURRENCY` (optional, default `NGN`)
+
+Generate real E2E auth inputs against deployed backend:
+```bash
+# Step 1: start onboarding and get requestId
+npm run e2e:bootstrap -- --base-url https://your-oci-gateway --phone +23480xxxxxxx
+
+# Step 2: rerun with OTP/silent-auth code (and optional recipient)
+npm run e2e:bootstrap -- --base-url https://your-oci-gateway --phone +23480xxxxxxx --code 123456 --recipient +23481xxxxxxx
+
+# Script prints PowerShell env exports, then run:
+npm run test:contract
+```
+
 ## Onboarding flow methods
 
 ```ts
@@ -30,12 +55,17 @@ import { FlurClient } from "@nokinc-flur/sdk";
 
 const client = new FlurClient({ baseUrl: "https://api.example.com" });
 
-const started = await client.onboardingStart({ phoneE164: "+14155550123" });
+const started = await client.onboardingStart({
+	phoneE164: "+14155550123",
+	appInstanceId: "app-instance-1",
+	platform: "ios",
+});
 // started: { requestId, checkUrl?, expiresInSec, fallback }
 
 const completed = await client.onboardingComplete({
 	requestId: started.requestId,
 	code: "123456",
+	appInstanceId: "app-instance-1",
 });
 // completed: { sessionToken, userId, restricted, risk_reasons }
 ```
@@ -48,7 +78,7 @@ const registered = await client.registerDevice({
 	appInstanceId: "app-instance-1",
 	platform: "ios",
 	networkSignals: { ip: "1.2.3.4" },
-});
+}, { accessToken: completed.sessionToken });
 // { deviceId, fingerprintHash, driftScore, trustState, stepUpRequired }
 
 const refreshed = await client.authRefresh({
@@ -59,9 +89,60 @@ const refreshed = await client.authRefresh({
 });
 // { refreshToken, stepUpRequired }
 
-await client.pinSet({ userId: completed.userId, pin: "123456" });
-await client.pinVerify({ userId: completed.userId, pin: "123456" });
-await client.authLogout({ userId: completed.userId, refreshToken: refreshed.refreshToken });
+await client.pinSet({ userId: completed.userId, pin: "123456" }, { accessToken: completed.sessionToken });
+await client.pinVerify({ userId: completed.userId, pin: "123456" }, { accessToken: completed.sessionToken });
+await client.authLogout(
+	{ userId: completed.userId, refreshToken: refreshed.refreshToken },
+	{ accessToken: refreshed.refreshToken }
+);
+```
+
+## Send-money methods
+
+```ts
+// Register per-device signing key for send authorization
+await client.registerSendDeviceKey({
+	userId: completed.userId,
+	deviceId: registered.deviceId,
+	publicKey: "-----BEGIN PUBLIC KEY-----...",
+}, { accessToken: completed.sessionToken });
+
+// Obtain challenge and verify signature to get short-lived send token
+const challenge = await client.createSendChallenge({
+	userId: completed.userId,
+	deviceId: registered.deviceId,
+}, { accessToken: completed.sessionToken });
+
+const send = await client.verifySendChallenge({
+	userId: completed.userId,
+	deviceId: registered.deviceId,
+	challengeId: challenge.challengeId,
+	signature: "base64-signature",
+}, { accessToken: completed.sessionToken });
+
+// Resolve recipient and create transfer
+const recipient = await client.resolveRecipient(
+	{ identifier: "+14155550123" },
+	{ accessToken: completed.sessionToken }
+);
+
+await client.createTransfer(
+	{
+		recipientIdentifier: recipient.normalizedIdentifier,
+		amountMinor: 5000,
+		currency: "NGN",
+		sendAuthToken: send.sendAuthToken,
+	},
+	{
+		accessToken: completed.sessionToken,
+		deviceId: registered.deviceId,
+		idempotencyKey: crypto.randomUUID(),
+	}
+);
+
+// Account + transaction endpoints
+await client.accountSummary({ accessToken: completed.sessionToken });
+await client.listTransactions({ accessToken: completed.sessionToken, limit: 20 });
 ```
 
 ## Error code mapping

package/dist/index.d.ts

@@ -1,3 +1,12 @@
+type Money = {
+    amountMinor: bigint;
+    currency: string;
+};
+declare function parseAmountInput(value: string, currency: string): Money;
+declare function formatAmount(amountMinor: bigint, currency: string): string;
+declare function normalizeE164(input: string, defaultCountry?: string): string;
+declare function moneyMinorToNumber(amountMinor: bigint): number;
+
 type FlurClientOptions = {
     baseUrl: string;
     fetchImpl?: typeof fetch;
@@ -6,6 +15,15 @@ type FlurClientOptions = {
 type OnboardingFallback = "SILENT_AUTH" | "OTP";
 type OnboardingStartInput = {
     phoneE164: string;
+    appInstanceId: string;
+    platform: "android" | "ios" | "web";
+    turnstileToken?: string;
+    appAttestation?: {
+        provider: "android" | "ios" | "web";
+        token: string;
+    };
+    firstName?: string;
+    lastName?: string;
 };
 type OnboardingStartResponse = {
     requestId: string;
@@ -17,7 +35,7 @@ type OnboardingRiskReason = "SIM_SWAP_RECENT" | "ROAMING" | "CARRIER_CHANGED";
 type OnboardingCompleteInput = {
     requestId: string;
     code: string;
-    appInstanceId?: string;
+    appInstanceId: string;
     fingerprintHash?: string;
 };
 type OnboardingCompleteResponse = {
@@ -70,6 +88,125 @@ type PinVerifyInput = {
     userId: string;
     pin: string;
 };
+type RegisterSendDeviceKeyInput = {
+    userId: string;
+    deviceId: string;
+    publicKey: string;
+};
+type SendChallengeInput = {
+    userId: string;
+    deviceId: string;
+};
+type SendChallengeResponse = {
+    challengeId: string;
+    nonce: string;
+    expiresAt: string;
+};
+type SendVerifyInput = {
+    userId: string;
+    deviceId: string;
+    challengeId: string;
+    signature: string;
+};
+type SendVerifyResponse = {
+    sendAuthToken: string;
+};
+type RecipientResolveInput = {
+    identifier: string;
+};
+type RecipientResolveResponse = {
+    recipientUserId: string;
+    displayName: string;
+    normalizedIdentifier: string;
+    isActive: boolean;
+};
+type TransferInput = {
+    recipientIdentifier: string;
+    amountMinor: number;
+    currency: string;
+    sendAuthToken: string;
+};
+type TransferStatus = "SETTLED" | "PENDING_REVIEW" | "DECLINED";
+type TransferResponse = {
+    transactionId: string;
+    status: TransferStatus;
+    userStatus: TransferStatus;
+    recipientName: string;
+    timestamp: string;
+};
+type TransactionDirection = "OUTGOING" | "INCOMING";
+type AccountActivityItem = {
+    id: string;
+    type: string;
+    direction: TransactionDirection;
+    name: string;
+    identifier: string;
+    amountMinor: number;
+    currency: string;
+    status: string;
+    timestamp: string;
+};
+type AccountSummaryResponse = {
+    balance: number;
+    currency: string;
+    dailySendLimit: number;
+    dailySendRemaining: number;
+    kycTier: string;
+    kycStatus: string;
+    recentActivity: AccountActivityItem[];
+};
+type TransactionsListResponse = {
+    items: AccountActivityItem[];
+    nextCursor: string | null;
+};
+type TransactionDetailResponse = {
+    transactionId: string;
+    type: string;
+    direction: TransactionDirection;
+    counterpartyName: string;
+    counterpartyIdentifier: string;
+    amountMinor: number;
+    currency: string;
+    status: string;
+    timestamp: string;
+};
+type PushPlatform = "ios" | "android" | "web";
+type PushRegisterInput = {
+    deviceId: string;
+    platform: PushPlatform;
+    token: string;
+};
+type AuthorizedOptions = {
+    accessToken: string;
+};
+type CreateTransferOptions = AuthorizedOptions & {
+    deviceId: string;
+    idempotencyKey: string;
+};
+type ListTransactionsOptions = AuthorizedOptions & {
+    cursor?: string;
+    limit?: number;
+};
+type BiometricSigner = {
+    getOrCreateKeyPair(deviceId: string): Promise<string>;
+    sign(payload: string): Promise<string>;
+};
+type SendMoneyInput = {
+    recipientIdentifier: string;
+    money: Money;
+    sendAuthToken: string;
+    idempotencyKey?: string;
+    defaultCountry?: string;
+};
+type SendMoneyOptions = AuthorizedOptions & {
+    deviceId: string;
+};
+type AuthorizeSendWithBiometricInput = {
+    userId: string;
+    deviceId: string;
+    accessToken: string;
+    signer: BiometricSigner;
+};
 declare class FlurClient {
     private readonly baseUrl;
     private readonly fetchImpl;
@@ -83,21 +220,44 @@ declare class FlurClient {
     }>;
     onboardingStart(input: OnboardingStartInput): Promise<OnboardingStartResponse>;
     onboardingComplete(input: OnboardingCompleteInput): Promise<OnboardingCompleteResponse>;
-    registerDevice(input: RegisterDeviceInput): Promise<RegisterDeviceResponse>;
+    registerDevice(input: RegisterDeviceInput, options: AuthorizedOptions): Promise<RegisterDeviceResponse>;
     authRefresh(input: AuthRefreshInput): Promise<AuthRefreshResponse>;
-    authLogout(input: AuthLogoutInput): Promise<{
+    authLogout(input: AuthLogoutInput, options: AuthorizedOptions): Promise<{
+        ok: boolean;
+    }>;
+    pinSet(input: PinSetInput, options: AuthorizedOptions): Promise<{
+        ok: boolean;
+    }>;
+    pinVerify(input: PinVerifyInput, options: AuthorizedOptions): Promise<{
+        ok: boolean;
+    }>;
+    registerSendDeviceKey(input: RegisterSendDeviceKeyInput, options: AuthorizedOptions): Promise<{
         ok: boolean;
     }>;
-    pinSet(input: PinSetInput): Promise<{
+    createSendChallenge(input: SendChallengeInput, options: AuthorizedOptions): Promise<SendChallengeResponse>;
+    verifySendChallenge(input: SendVerifyInput, options: AuthorizedOptions): Promise<SendVerifyResponse>;
+    registerBiometricDeviceKey(input: {
+        userId: string;
+        deviceId: string;
+        accessToken: string;
+        signer: BiometricSigner;
+    }): Promise<{
         ok: boolean;
     }>;
-    pinVerify(input: PinVerifyInput): Promise<{
+    authorizeSendWithBiometric(input: AuthorizeSendWithBiometricInput): Promise<SendVerifyResponse>;
+    resolveRecipient(input: RecipientResolveInput, options: AuthorizedOptions): Promise<RecipientResolveResponse>;
+    createTransfer(input: TransferInput, options: CreateTransferOptions): Promise<TransferResponse>;
+    sendMoney(input: SendMoneyInput, options: SendMoneyOptions): Promise<TransferResponse>;
+    accountSummary(options: AuthorizedOptions): Promise<AccountSummaryResponse>;
+    listTransactions(options: ListTransactionsOptions): Promise<TransactionsListResponse>;
+    transactionDetail(transactionId: string, options: AuthorizedOptions): Promise<TransactionDetailResponse>;
+    registerPushToken(input: PushRegisterInput, options: AuthorizedOptions): Promise<{
         ok: boolean;
     }>;
     private requestJson;
 }
 
-type FlurErrorCode = "NETWORK_ERROR" | "HTTP_ERROR" | "TIMEOUT" | "UNKNOWN" | "TOKEN_REPLAYED" | "SESSION_MISMATCH" | "PIN_INVALID" | "PIN_LOCKED" | "PIN_NOT_SET" | "STEP_UP_REQUIRED";
+type FlurErrorCode = "NETWORK_ERROR" | "HTTP_ERROR" | "TIMEOUT" | "UNKNOWN" | "UNAUTHORIZED" | "INVALID_REQUEST" | "RATE_LIMITED" | "NOT_FOUND" | "USER_NOT_FOUND" | "TOKEN_REPLAYED" | "SESSION_MISMATCH" | "PIN_INVALID" | "PIN_LOCKED" | "PIN_NOT_SET" | "STEP_UP_REQUIRED" | "DEVICE_KEY_NOT_REGISTERED" | "CHALLENGE_INVALID" | "CHALLENGE_EXPIRED" | "DEVICE_KEY_REVOKED" | "SIGNATURE_INVALID" | "INVALID_RECIPIENT" | "SEND_AUTH_INVALID" | "IDEMPOTENCY_KEY_CONFLICT" | "IDEMPOTENCY_IN_PROGRESS" | "CANNOT_SEND_TO_SELF" | "INSUFFICIENT_FUNDS";
 declare class FlurError extends Error {
     readonly code: FlurErrorCode;
     readonly status?: number;
@@ -108,4 +268,4 @@ declare class FlurError extends Error {
     });
 }
 
-export { type AuthLogoutInput, type AuthRefreshInput, type AuthRefreshResponse, type DeviceTrustState, FlurClient, type FlurClientOptions, FlurError, type OnboardingCompleteInput, type OnboardingCompleteResponse, type OnboardingFallback, type OnboardingRiskReason, type OnboardingStartInput, type OnboardingStartResponse, type PinSetInput, type PinVerifyInput, type RegisterDeviceInput, type RegisterDeviceResponse };
+export { type AccountActivityItem, type AccountSummaryResponse, type AuthLogoutInput, type AuthRefreshInput, type AuthRefreshResponse, type AuthorizeSendWithBiometricInput, type AuthorizedOptions, type BiometricSigner, type CreateTransferOptions, type DeviceTrustState, FlurClient, type FlurClientOptions, FlurError, type ListTransactionsOptions, type Money, type OnboardingCompleteInput, type OnboardingCompleteResponse, type OnboardingFallback, type OnboardingRiskReason, type OnboardingStartInput, type OnboardingStartResponse, type PinSetInput, type PinVerifyInput, type PushPlatform, type PushRegisterInput, type RecipientResolveInput, type RecipientResolveResponse, type RegisterDeviceInput, type RegisterDeviceResponse, type RegisterSendDeviceKeyInput, type SendChallengeInput, type SendChallengeResponse, type SendMoneyInput, type SendMoneyOptions, type SendVerifyInput, type SendVerifyResponse, type TransactionDetailResponse, type TransactionDirection, type TransactionsListResponse, type TransferInput, type TransferResponse, type TransferStatus, formatAmount, moneyMinorToNumber, normalizeE164, parseAmountInput };

package/dist/index.js

@@ -1,11 +1,206 @@
+// src/client.ts
+import { z as z3 } from "zod";
+
+// src/contracts.ts
+import { z } from "zod";
+var E164Regex = /^\+[1-9]\d{7,14}$/;
+var UuidSchema = z.string().uuid();
+var IsoDateSchema = z.string().datetime({ offset: true });
+var CurrencySchema = z.string().trim().length(3).transform((value) => value.toUpperCase());
+var HealthResponseSchema = z.object({
+  ok: z.boolean()
+});
+var WelcomeResponseSchema = z.object({
+  message: z.string()
+});
+var OnboardingStartRequestSchema = z.object({
+  phoneE164: z.string().regex(E164Regex),
+  appInstanceId: z.string().min(3),
+  platform: z.enum(["android", "ios", "web"]),
+  turnstileToken: z.string().min(20).optional(),
+  appAttestation: z.object({
+    provider: z.enum(["android", "ios", "web"]),
+    token: z.string().min(24)
+  }).optional(),
+  firstName: z.string().trim().min(1).max(80).optional(),
+  lastName: z.string().trim().min(1).max(80).optional()
+});
+var OnboardingStartResponseSchema = z.object({
+  requestId: z.string().min(1),
+  checkUrl: z.string().url().optional(),
+  expiresInSec: z.number().int().positive(),
+  fallback: z.enum(["SILENT_AUTH", "OTP"])
+});
+var OnboardingCompleteRequestSchema = z.object({
+  requestId: z.string().min(1),
+  code: z.string().min(1).max(32),
+  appInstanceId: z.string().min(3),
+  fingerprintHash: z.string().min(3).optional()
+});
+var OnboardingCompleteResponseSchema = z.object({
+  sessionToken: z.string().min(1),
+  userId: UuidSchema,
+  restricted: z.boolean(),
+  risk_reasons: z.array(z.enum(["SIM_SWAP_RECENT", "ROAMING", "CARRIER_CHANGED"])),
+  stepUpRequired: z.boolean().optional(),
+  riskStatus: z.enum(["ok", "unavailable"]).optional()
+});
+var RegisterDeviceRequestSchema = z.object({
+  userId: UuidSchema,
+  appInstanceId: z.string().min(3),
+  platform: z.string().min(2),
+  model: z.string().optional(),
+  networkSignals: z.object({
+    ip: z.string().min(3),
+    asn: z.number().int().optional(),
+    country: z.string().min(2).optional(),
+    carrier: z.string().optional()
+  })
+});
+var RegisterDeviceResponseSchema = z.object({
+  deviceId: z.string().min(1),
+  fingerprintHash: z.string().min(1),
+  driftScore: z.number(),
+  trustState: z.enum(["TRUSTED_PRIMARY", "TRUSTED_SECONDARY", "UNVERIFIED"]),
+  stepUpRequired: z.boolean()
+});
+var AuthRefreshRequestSchema = z.object({
+  userId: UuidSchema,
+  refreshToken: z.string().min(8),
+  appInstanceId: z.string().min(3),
+  fingerprintHash: z.string().min(3)
+});
+var AuthRefreshResponseSchema = z.object({
+  refreshToken: z.string().min(8),
+  stepUpRequired: z.boolean()
+});
+var AuthLogoutRequestSchema = z.object({
+  userId: UuidSchema,
+  refreshToken: z.string().min(8)
+});
+var PinSetRequestSchema = z.object({
+  userId: UuidSchema,
+  pin: z.string().regex(/^\d{6}$/)
+});
+var PinVerifyRequestSchema = z.object({
+  userId: UuidSchema,
+  pin: z.string().regex(/^\d{6}$/)
+});
+var OkResponseSchema = z.object({
+  ok: z.boolean()
+});
+var RegisterSendDeviceKeyRequestSchema = z.object({
+  userId: UuidSchema,
+  deviceId: z.string().min(3),
+  publicKey: z.string().min(32)
+});
+var SendChallengeRequestSchema = z.object({
+  userId: UuidSchema,
+  deviceId: z.string().min(3)
+});
+var SendChallengeResponseSchema = z.object({
+  challengeId: UuidSchema,
+  nonce: z.string().min(1),
+  expiresAt: IsoDateSchema
+});
+var SendVerifyRequestSchema = z.object({
+  userId: UuidSchema,
+  deviceId: z.string().min(3),
+  challengeId: UuidSchema,
+  signature: z.string().min(16)
+});
+var SendVerifyResponseSchema = z.object({
+  sendAuthToken: z.string().min(16)
+});
+var ResolveRecipientRequestSchema = z.object({
+  identifier: z.string().min(3)
+});
+var ResolveRecipientResponseSchema = z.object({
+  recipientUserId: UuidSchema,
+  displayName: z.string().min(1),
+  normalizedIdentifier: z.string().regex(E164Regex),
+  isActive: z.boolean()
+});
+var CreateTransferRequestSchema = z.object({
+  recipientIdentifier: z.string().min(3),
+  amountMinor: z.number().int().positive(),
+  currency: CurrencySchema,
+  sendAuthToken: z.string().min(16)
+});
+var TransferStatusSchema = z.enum(["SETTLED", "PENDING_REVIEW", "DECLINED"]);
+var TransferResponseSchema = z.object({
+  transactionId: z.string().min(1),
+  status: TransferStatusSchema,
+  userStatus: TransferStatusSchema,
+  recipientName: z.string().min(1),
+  timestamp: IsoDateSchema
+});
+var DirectionSchema = z.enum(["OUTGOING", "INCOMING"]);
+var AccountActivityItemSchema = z.object({
+  id: z.string().min(1),
+  type: z.string().min(1),
+  direction: DirectionSchema,
+  name: z.string().min(1),
+  identifier: z.string().min(1),
+  amountMinor: z.number().int(),
+  currency: CurrencySchema,
+  status: z.string().min(1),
+  timestamp: IsoDateSchema
+});
+var AccountSummaryResponseSchema = z.object({
+  balance: z.number().int(),
+  currency: CurrencySchema,
+  dailySendLimit: z.number().int().nonnegative(),
+  dailySendRemaining: z.number().int().nonnegative(),
+  kycTier: z.string().min(1),
+  kycStatus: z.string().min(1),
+  recentActivity: z.array(AccountActivityItemSchema)
+});
+var TransactionsListResponseSchema = z.object({
+  items: z.array(AccountActivityItemSchema),
+  nextCursor: z.string().nullable()
+});
+var TransactionDetailResponseSchema = z.object({
+  transactionId: z.string().min(1),
+  type: z.string().min(1),
+  direction: DirectionSchema,
+  counterpartyName: z.string().min(1),
+  counterpartyIdentifier: z.string().min(1),
+  amountMinor: z.number().int(),
+  currency: CurrencySchema,
+  status: z.string().min(1),
+  timestamp: IsoDateSchema
+});
+var PushRegisterRequestSchema = z.object({
+  deviceId: z.string().min(3),
+  platform: z.enum(["ios", "android", "web"]),
+  token: z.string().min(16)
+});
+
 // src/errors.ts
 var backendErrorCodeSet = /* @__PURE__ */ new Set([
+  "UNAUTHORIZED",
+  "INVALID_REQUEST",
+  "RATE_LIMITED",
+  "NOT_FOUND",
+  "USER_NOT_FOUND",
   "TOKEN_REPLAYED",
   "SESSION_MISMATCH",
   "PIN_INVALID",
   "PIN_LOCKED",
   "PIN_NOT_SET",
-  "STEP_UP_REQUIRED"
+  "STEP_UP_REQUIRED",
+  "DEVICE_KEY_NOT_REGISTERED",
+  "CHALLENGE_INVALID",
+  "CHALLENGE_EXPIRED",
+  "DEVICE_KEY_REVOKED",
+  "SIGNATURE_INVALID",
+  "INVALID_RECIPIENT",
+  "SEND_AUTH_INVALID",
+  "IDEMPOTENCY_KEY_CONFLICT",
+  "IDEMPOTENCY_IN_PROGRESS",
+  "CANNOT_SEND_TO_SELF",
+  "INSUFFICIENT_FUNDS"
 ]);
 var FlurError = class extends Error {
   code;
@@ -44,6 +239,101 @@ async function mapToFlurError(res) {
   return new FlurError(mappedMessage, mappedCode, { status: res.status, details });
 }
 
+// src/primitives.ts
+import { z as z2 } from "zod";
+var CurrencyCodeSchema = z2.string().trim().length(3).transform((value) => value.toUpperCase());
+var currencyFractionDigits = {
+  NGN: 2,
+  USD: 2,
+  EUR: 2,
+  GBP: 2,
+  CAD: 2,
+  JPY: 0
+};
+function getFractionDigits(currency) {
+  return currencyFractionDigits[currency] ?? 2;
+}
+function parseAmountInput(value, currency) {
+  const normalizedCurrency = CurrencyCodeSchema.parse(currency);
+  const raw = value.trim();
+  if (!/^\d+(\.\d+)?$/.test(raw)) {
+    throw new FlurError("Invalid amount format", "INVALID_REQUEST");
+  }
+  const [whole, fraction = ""] = raw.split(".");
+  const fractionDigits = getFractionDigits(normalizedCurrency);
+  if (fraction.length > fractionDigits) {
+    throw new FlurError("Too many decimal places for currency", "INVALID_REQUEST");
+  }
+  const paddedFraction = fraction.padEnd(fractionDigits, "0");
+  const minorAsString = `${whole}${paddedFraction}`.replace(/^0+(\d)/, "$1") || "0";
+  const amountMinor = BigInt(minorAsString);
+  if (amountMinor < 0n) {
+    throw new FlurError("Amount cannot be negative", "INVALID_REQUEST");
+  }
+  return {
+    amountMinor,
+    currency: normalizedCurrency
+  };
+}
+function formatAmount(amountMinor, currency) {
+  const normalizedCurrency = CurrencyCodeSchema.parse(currency);
+  if (amountMinor < 0n) {
+    throw new FlurError("Amount cannot be negative", "INVALID_REQUEST");
+  }
+  const fractionDigits = getFractionDigits(normalizedCurrency);
+  if (fractionDigits === 0) {
+    return amountMinor.toString();
+  }
+  const divisor = 10n ** BigInt(fractionDigits);
+  const whole = amountMinor / divisor;
+  const fraction = (amountMinor % divisor).toString().padStart(fractionDigits, "0");
+  return `${whole.toString()}.${fraction}`;
+}
+var defaultCountryDialingCode = {
+  NG: "234",
+  US: "1",
+  CA: "1",
+  GB: "44"
+};
+function normalizeE164(input, defaultCountry) {
+  const trimmed = input.trim();
+  if (trimmed.startsWith("+")) {
+    if (!E164Regex.test(trimmed)) {
+      throw new FlurError("Invalid phone number", "INVALID_REQUEST");
+    }
+    return trimmed;
+  }
+  const digits = trimmed.replace(/\D/g, "");
+  if (digits.length === 0) {
+    throw new FlurError("Invalid phone number", "INVALID_REQUEST");
+  }
+  if (digits.startsWith("00")) {
+    const candidate2 = `+${digits.slice(2)}`;
+    if (!E164Regex.test(candidate2)) {
+      throw new FlurError("Invalid phone number", "INVALID_REQUEST");
+    }
+    return candidate2;
+  }
+  const normalizedCountry = defaultCountry?.trim().toUpperCase();
+  const countryCode = normalizedCountry ? defaultCountryDialingCode[normalizedCountry] : void 0;
+  if (!countryCode) {
+    throw new FlurError("Invalid phone number", "INVALID_REQUEST");
+  }
+  const localDigits = digits.startsWith("0") ? digits.slice(1) : digits;
+  const candidate = `+${countryCode}${localDigits}`;
+  if (!E164Regex.test(candidate)) {
+    throw new FlurError("Invalid phone number", "INVALID_REQUEST");
+  }
+  return candidate;
+}
+function moneyMinorToNumber(amountMinor) {
+  const asNumber = Number(amountMinor);
+  if (!Number.isSafeInteger(asNumber)) {
+    throw new FlurError("Amount exceeds safe integer range", "INVALID_REQUEST");
+  }
+  return asNumber;
+}
+
 // src/client.ts
 var FlurClient = class {
   baseUrl;
@@ -55,68 +345,315 @@ var FlurClient = class {
     this.timeoutMs = opts.timeoutMs ?? 1e4;
   }
   async health() {
-    return this.requestJson("/health", { method: "GET" });
+    return this.requestJson("/health", { method: "GET" }, void 0, HealthResponseSchema);
   }
   async welcome() {
-    return this.requestJson("/welcome", { method: "GET" });
+    return this.requestJson("/welcome", { method: "GET" }, void 0, WelcomeResponseSchema);
   }
   async onboardingStart(input) {
-    return this.requestJson("/v1/onboarding/start", {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(input)
-    });
+    return this.requestJson(
+      "/v1/onboarding/start",
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" }
+      },
+      OnboardingStartRequestSchema,
+      OnboardingStartResponseSchema,
+      input
+    );
   }
   async onboardingComplete(input) {
-    return this.requestJson("/v1/onboarding/complete", {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(input)
-    });
-  }
-  async registerDevice(input) {
-    return this.requestJson("/v1/devices/register", {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(input)
-    });
+    return this.requestJson(
+      "/v1/onboarding/complete",
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" }
+      },
+      OnboardingCompleteRequestSchema,
+      OnboardingCompleteResponseSchema,
+      input
+    );
+  }
+  async registerDevice(input, options) {
+    return this.requestJson(
+      "/v1/devices/register",
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${options.accessToken}`
+        }
+      },
+      RegisterDeviceRequestSchema,
+      RegisterDeviceResponseSchema,
+      input
+    );
   }
   async authRefresh(input) {
-    return this.requestJson("/v1/auth/refresh", {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(input)
-    });
-  }
-  async authLogout(input) {
-    return this.requestJson("/v1/auth/logout", {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(input)
-    });
-  }
-  async pinSet(input) {
-    return this.requestJson("/v1/auth/pin/set", {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(input)
-    });
-  }
-  async pinVerify(input) {
-    return this.requestJson("/v1/auth/pin/verify", {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(input)
-    });
-  }
-  async requestJson(path, init) {
+    return this.requestJson(
+      "/v1/auth/refresh",
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" }
+      },
+      AuthRefreshRequestSchema,
+      AuthRefreshResponseSchema,
+      input
+    );
+  }
+  async authLogout(input, options) {
+    return this.requestJson(
+      "/v1/auth/logout",
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${options.accessToken}`
+        }
+      },
+      AuthLogoutRequestSchema,
+      OkResponseSchema,
+      input
+    );
+  }
+  async pinSet(input, options) {
+    return this.requestJson(
+      "/v1/auth/pin/set",
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${options.accessToken}`
+        }
+      },
+      PinSetRequestSchema,
+      OkResponseSchema,
+      input
+    );
+  }
+  async pinVerify(input, options) {
+    return this.requestJson(
+      "/v1/auth/pin/verify",
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${options.accessToken}`
+        }
+      },
+      PinVerifyRequestSchema,
+      OkResponseSchema,
+      input
+    );
+  }
+  async registerSendDeviceKey(input, options) {
+    return this.requestJson(
+      "/api/v1/auth/send/device-key",
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${options.accessToken}`
+        }
+      },
+      RegisterSendDeviceKeyRequestSchema,
+      OkResponseSchema,
+      input
+    );
+  }
+  async createSendChallenge(input, options) {
+    return this.requestJson(
+      "/api/v1/auth/send/challenge",
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${options.accessToken}`
+        }
+      },
+      SendChallengeRequestSchema,
+      SendChallengeResponseSchema,
+      input
+    );
+  }
+  async verifySendChallenge(input, options) {
+    return this.requestJson(
+      "/api/v1/auth/send/verify",
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${options.accessToken}`
+        }
+      },
+      SendVerifyRequestSchema,
+      SendVerifyResponseSchema,
+      input
+    );
+  }
+  async registerBiometricDeviceKey(input) {
+    const publicKey = await input.signer.getOrCreateKeyPair(input.deviceId);
+    return this.registerSendDeviceKey({
+      userId: input.userId,
+      deviceId: input.deviceId,
+      publicKey
+    }, { accessToken: input.accessToken });
+  }
+  async authorizeSendWithBiometric(input) {
+    const challenge = await this.createSendChallenge({
+      userId: input.userId,
+      deviceId: input.deviceId
+    }, { accessToken: input.accessToken });
+    const signature = await input.signer.sign(challenge.nonce);
+    return this.verifySendChallenge({
+      userId: input.userId,
+      deviceId: input.deviceId,
+      challengeId: challenge.challengeId,
+      signature
+    }, { accessToken: input.accessToken });
+  }
+  async resolveRecipient(input, options) {
+    return this.requestJson(
+      "/api/v1/recipients/resolve",
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${options.accessToken}`
+        }
+      },
+      ResolveRecipientRequestSchema,
+      ResolveRecipientResponseSchema,
+      input
+    );
+  }
+  async createTransfer(input, options) {
+    return this.requestJson(
+      "/api/v1/transfers",
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${options.accessToken}`,
+          "x-device-id": options.deviceId,
+          "x-idempotency-key": options.idempotencyKey
+        }
+      },
+      CreateTransferRequestSchema,
+      TransferResponseSchema,
+      input
+    );
+  }
+  async sendMoney(input, options) {
+    const normalizedRecipient = E164Regex.test(input.recipientIdentifier) ? input.recipientIdentifier : normalizeE164(input.recipientIdentifier, input.defaultCountry);
+    const idempotencyKey = input.idempotencyKey ?? getSecureRandomUuid();
+    return this.createTransfer(
+      {
+        recipientIdentifier: normalizedRecipient,
+        amountMinor: moneyMinorToNumber(input.money.amountMinor),
+        currency: input.money.currency,
+        sendAuthToken: input.sendAuthToken
+      },
+      {
+        accessToken: options.accessToken,
+        deviceId: options.deviceId,
+        idempotencyKey
+      }
+    );
+  }
+  async accountSummary(options) {
+    return this.requestJson(
+      "/api/v1/account/summary",
+      {
+        method: "GET",
+        headers: {
+          authorization: `Bearer ${options.accessToken}`
+        }
+      },
+      void 0,
+      AccountSummaryResponseSchema
+    );
+  }
+  async listTransactions(options) {
+    const query = new URLSearchParams();
+    if (typeof options.cursor === "string" && options.cursor.trim().length > 0) {
+      query.set("cursor", options.cursor);
+    }
+    if (typeof options.limit === "number") {
+      query.set("limit", String(options.limit));
+    }
+    const path = query.size > 0 ? `/api/v1/transactions?${query.toString()}` : "/api/v1/transactions";
+    return this.requestJson(
+      path,
+      {
+        method: "GET",
+        headers: {
+          authorization: `Bearer ${options.accessToken}`
+        }
+      },
+      void 0,
+      TransactionsListResponseSchema
+    );
+  }
+  async transactionDetail(transactionId, options) {
+    const encodedId = encodeURIComponent(transactionId);
+    return this.requestJson(
+      `/api/v1/transactions/${encodedId}`,
+      {
+        method: "GET",
+        headers: {
+          authorization: `Bearer ${options.accessToken}`
+        }
+      },
+      void 0,
+      TransactionDetailResponseSchema
+    );
+  }
+  async registerPushToken(input, options) {
+    return this.requestJson(
+      "/api/v1/push/register",
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${options.accessToken}`
+        }
+      },
+      PushRegisterRequestSchema,
+      OkResponseSchema,
+      input
+    );
+  }
+  async requestJson(path, init, requestSchema, responseSchema, input) {
     const url = `${this.baseUrl}${path}`;
     const controller = new AbortController();
     const t = setTimeout(() => controller.abort(), this.timeoutMs);
+    let body = init.body;
+    try {
+      body = requestSchema ? JSON.stringify(requestSchema.parse(input)) : init.body;
+    } catch (err) {
+      if (err instanceof z3.ZodError) {
+        throw new FlurError("Invalid request payload", "INVALID_REQUEST", {
+          details: err.flatten()
+        });
+      }
+      throw err;
+    }
     try {
-      const res = await this.fetchImpl(url, { ...init, signal: controller.signal });
+      const res = await this.fetchImpl(url, { ...init, body, signal: controller.signal });
       if (!res.ok) throw await mapToFlurError(res);
-      return await res.json();
+      const payload = await res.json();
+      if (!responseSchema) return payload;
+      try {
+        return responseSchema.parse(payload);
+      } catch (err) {
+        if (err instanceof z3.ZodError) {
+          throw new FlurError("SDK contract validation failed", "INVALID_REQUEST", {
+            details: err.flatten()
+          });
+        }
+        throw err;
+      }
     } catch (err) {
       if (err instanceof Error && err.name === "AbortError") {
         throw new FlurError("Request timed out", "TIMEOUT");
@@ -128,7 +665,17 @@ var FlurClient = class {
     }
   }
 };
+function getSecureRandomUuid() {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  throw new FlurError("Secure UUID generator unavailable; provide idempotencyKey", "INVALID_REQUEST");
+}
 export {
   FlurClient,
-  FlurError
+  FlurError,
+  formatAmount,
+  moneyMinorToNumber,
+  normalizeE164,
+  parseAmountInput
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nokinc-flur/sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Flur Wallet SDK (sprint 1 scaffold)",
   "license": "MIT",
   "type": "module",
@@ -22,8 +22,12 @@
     "lint": "eslint .",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
+    "test:contract": "vitest run test/e2e.health.test.ts test/e2e.send-money.test.ts",
+    "e2e:bootstrap": "node scripts/bootstrap-e2e-sendmoney.mjs",
     "build": "tsup src/index.ts --format esm --dts",
     "gen": "openapi-typescript openapi/flur.openapi.json -o src/gen/openapi-types.ts",
+    "prod:release": "pwsh -NoProfile -ExecutionPolicy Bypass -File ./scripts/prod-build-publish-npm.ps1",
+    "prod:release:publish": "pwsh -NoProfile -ExecutionPolicy Bypass -File ./scripts/prod-build-publish-npm.ps1 -Publish",
     "release:patch": "pwsh -NoProfile -ExecutionPolicy Bypass -File ./scripts/release.ps1 -Bump patch",
     "release:minor": "pwsh -NoProfile -ExecutionPolicy Bypass -File ./scripts/release.ps1 -Bump minor",
     "release:major": "pwsh -NoProfile -ExecutionPolicy Bypass -File ./scripts/release.ps1 -Bump major"