@nokinc-flur/sdk 0.1.6 → 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,1593 @@
+import { z } from 'zod';
+
+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;
+    timeoutMs?: number;
+    getExtraHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+};
+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;
+    checkUrl?: string;
+    expiresInSec: number;
+    fallback: OnboardingFallback;
+};
+type OnboardingRiskReason = "SIM_SWAP_RECENT" | "ROAMING" | "CARRIER_CHANGED";
+type OnboardingCompleteInput = {
+    requestId: string;
+    code: string;
+    appInstanceId: string;
+    fingerprintHash?: string;
+};
+type OnboardingCompleteResponse = {
+    sessionToken: string;
+    userId: string;
+    restricted: boolean;
+    risk_reasons: OnboardingRiskReason[];
+    stepUpRequired?: boolean;
+    riskStatus?: "ok" | "unavailable";
+};
+type RegisterDeviceInput = {
+    userId: string;
+    appInstanceId: string;
+    platform: string;
+    model?: string;
+    networkSignals: {
+        ip: string;
+        asn?: number;
+        country?: string;
+        carrier?: string;
+    };
+};
+type DeviceTrustState = "TRUSTED_PRIMARY" | "TRUSTED_SECONDARY" | "UNVERIFIED";
+type RegisterDeviceResponse = {
+    deviceId: string;
+    fingerprintHash: string;
+    driftScore: number;
+    trustState: DeviceTrustState;
+    stepUpRequired: boolean;
+};
+type AuthRefreshInput = {
+    userId: string;
+    refreshToken: string;
+    appInstanceId: string;
+    fingerprintHash: string;
+};
+type AuthRefreshResponse = {
+    refreshToken: string;
+    stepUpRequired: boolean;
+};
+type AuthLogoutInput = {
+    userId: string;
+    refreshToken: string;
+};
+type PinSetInput = {
+    userId: string;
+    pin: string;
+};
+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 CreatePayLinkResponse = {
+    token: string;
+};
+type ResolvePayLinkResponse = {
+    recipientUserId: string;
+    displayName: string;
+    normalizedIdentifier: string;
+    isActive: boolean;
+};
+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;
+    private readonly timeoutMs;
+    private readonly getExtraHeaders?;
+    constructor(opts: FlurClientOptions);
+    health(): Promise<{
+        ok: boolean;
+    }>;
+    welcome(): Promise<{
+        message: string;
+    }>;
+    onboardingStart(input: OnboardingStartInput): Promise<OnboardingStartResponse>;
+    onboardingComplete(input: OnboardingCompleteInput): Promise<OnboardingCompleteResponse>;
+    registerDevice(input: RegisterDeviceInput, options: AuthorizedOptions): Promise<RegisterDeviceResponse>;
+    authRefresh(input: AuthRefreshInput): Promise<AuthRefreshResponse>;
+    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;
+    }>;
+    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;
+    }>;
+    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;
+    }>;
+    createPayLink(options: AuthorizedOptions): Promise<CreatePayLinkResponse>;
+    resolvePayLink(token: string, options: AuthorizedOptions): Promise<ResolvePayLinkResponse>;
+    private requestJson;
+}
+
+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;
+    readonly details?: unknown;
+    readonly reqId?: string | null;
+    constructor(message: string, code: FlurErrorCode, opts?: {
+        status?: number;
+        details?: unknown;
+        reqId?: string | null;
+    });
+}
+/**
+ * Generic API error thrown by HTTP clients in `flur.passes` / `flur.receipts`
+ * for non-2xx responses. Lives at the SDK root so bounded-context modules
+ * (passes, receipts) never cross-import each other.
+ */
+declare class FlurApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly raw?: unknown;
+    constructor(status: number, code: string, message: string, raw?: unknown);
+}
+/** Thrown by `buildRedemption` when the pass is past its `validUntilMs`. */
+declare class FlurExpiredError extends Error {
+    readonly code: "PASS_EXPIRED";
+    constructor(message?: string);
+}
+/** Thrown by `buildRedemption` when `counter` is not strictly greater than the
+ *  caller-supplied `lastSeenCounter` (replay / out-of-order redemption attempt). */
+declare class FlurReplayError extends Error {
+    readonly code: "PASS_REPLAY";
+    constructor(message?: string);
+}
+/** Thrown by `buildRedemption` when this redemption would breach the pass's
+ *  `cumulativeCapKobo` given the caller-supplied `cumulativeUsedKobo`. */
+declare class FlurCapExceededError extends Error {
+    readonly code: "PASS_CAP_EXCEEDED";
+    constructor(message?: string);
+}
+
+/**
+ * EMV / NQR Merchant-Presented top-level field IDs.
+ * See EMVCo MPM v1.1 §4 and NIBSS NQR specification.
+ */
+declare const FIELD: {
+    readonly PAYLOAD_FORMAT_INDICATOR: "00";
+    readonly POINT_OF_INITIATION: "01";
+    readonly MERCHANT_CATEGORY_CODE: "52";
+    readonly TRANSACTION_CURRENCY: "53";
+    readonly TRANSACTION_AMOUNT: "54";
+    readonly TIP_OR_CONVENIENCE_INDICATOR: "55";
+    readonly VALUE_CONVENIENCE_FEE_FIXED: "56";
+    readonly VALUE_CONVENIENCE_FEE_PERCENT: "57";
+    readonly COUNTRY_CODE: "58";
+    readonly MERCHANT_NAME: "59";
+    readonly MERCHANT_CITY: "60";
+    readonly POSTAL_CODE: "61";
+    readonly ADDITIONAL_DATA_FIELD: "62";
+    readonly CRC: "63";
+    readonly MERCHANT_INFO_LANGUAGE: "64";
+};
+declare const ADDITIONAL_DATA_SUBFIELD: {
+    readonly BILL_NUMBER: "01";
+    readonly MOBILE_NUMBER: "02";
+    readonly STORE_LABEL: "03";
+    readonly LOYALTY_NUMBER: "04";
+    readonly REFERENCE_LABEL: "05";
+    readonly CUSTOMER_LABEL: "06";
+    readonly TERMINAL_LABEL: "07";
+    readonly PURPOSE_OF_TRANSACTION: "08";
+};
+declare const POINT_OF_INITIATION: {
+    readonly STATIC: "11";
+    readonly DYNAMIC: "12";
+};
+declare const PAYLOAD_FORMAT_INDICATOR_VALUE = "01";
+declare const NGN_CURRENCY_CODE = "566";
+declare const NG_COUNTRY_CODE = "NG";
+
+/**
+ * CRC-16/CCITT-FALSE — polynomial 0x1021, initial 0xFFFF, no reflection,
+ * no XOR-out. Specified by EMVCo MPM for tag 63 (CRC).
+ */
+declare function crc16ccitt(bytes: Uint8Array): number;
+declare function crc16ccittHex(bytes: Uint8Array): string;
+
+/**
+ * EMV TLV (Tag-Length-Value) primitives.
+ * - Tag is 2 ASCII digits.
+ * - Length is 2 ASCII digits (00..99).
+ * - Value is up to 99 ASCII characters.
+ */
+type TLVField = {
+    tag: string;
+    value: string;
+};
+declare function writeTLV(tag: string, value: string): string;
+declare function readTLV(buf: string): TLVField[];
+
+/**
+ * High-level EMV/NQR payload types.
+ *
+ * Merchant Account Information (tags 02..51) is issuer-specific. NQR uses
+ * one of these templates with a globally unique identifier (GUID) and a
+ * merchant identifier issued by the sponsor bank or NIBSS.
+ */
+type MerchantAccountInfo = {
+    /** Tag in 02..51 (typically "26" for NQR). */
+    tag: string;
+    children: Array<{
+        tag: string;
+        value: string;
+    }>;
+};
+type AdditionalData = {
+    billNumber?: string;
+    mobileNumber?: string;
+    storeLabel?: string;
+    loyaltyNumber?: string;
+    referenceLabel?: string;
+    customerLabel?: string;
+    terminalLabel?: string;
+    purposeOfTransaction?: string;
+};
+type NQRPayloadInput = {
+    /** "static" → POI 11, "dynamic" → POI 12. Dynamic typically has amount. */
+    pointOfInitiation: 'static' | 'dynamic';
+    merchantAccountInfo: MerchantAccountInfo;
+    /** ISO 18245 Merchant Category Code. 4 digits. */
+    merchantCategoryCode: string;
+    /** Up to 25 chars per EMV spec. */
+    merchantName: string;
+    /** Up to 15 chars per EMV spec. */
+    merchantCity: string;
+    /** Decimal string (e.g. "100.00"). Required when dynamic. */
+    transactionAmount?: string;
+    postalCode?: string;
+    additionalData?: AdditionalData;
+};
+type ParsedNQR = {
+    payloadFormatIndicator: string;
+    pointOfInitiation: 'static' | 'dynamic' | 'unknown';
+    merchantAccountInfo: MerchantAccountInfo[];
+    merchantCategoryCode: string;
+    transactionCurrency: string;
+    transactionAmount?: string;
+    countryCode: string;
+    merchantName: string;
+    merchantCity: string;
+    postalCode?: string;
+    additionalData?: AdditionalData;
+    /** Convenience: extracted referenceLabel (ADF tag 05). */
+    flurReference?: string;
+    raw: string;
+};
+
+declare function encodeNQR(input: NQRPayloadInput): string;
+
+declare class NQRParseError extends Error {
+    readonly path: string;
+    constructor(message: string, path?: string);
+}
+declare function parseNQR(payload: string): ParsedNQR;
+
+type RoutingHint = 'flur-onus' | 'nibss' | 'unknown';
+/**
+ * Decide whether a parsed NQR payload should be routed on-us through Flur
+ * (because it carries a Flur reference label) or sent through standard NIBSS.
+ */
+declare function routingHint(parsed: ParsedNQR): RoutingHint;
+
+/**
+ * Deterministic JSON serialization for cryptographic signing.
+ *
+ * Rules:
+ * - Object keys sorted lexicographically (recursively).
+ * - Arrays preserve order.
+ * - undefined / NaN / Infinity / bigint / function / symbol are rejected.
+ *   Signatures must be unambiguous; ambiguous values are bugs.
+ */
+declare function canonicalJSONStringify(value: unknown): string;
+declare function canonicalJSONBytes(value: unknown): Uint8Array;
+
+/**
+ * Constant-time equality for byte arrays. Returns false fast on length
+ * mismatch (length is not secret); compares byte-wise without short-circuit
+ * for equal-length inputs.
+ */
+declare function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean;
+
+type Ed25519KeyPair = {
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+};
+declare function generateKeyPair(): Ed25519KeyPair;
+declare function publicKeyFromPrivate(privateKey: Uint8Array): Uint8Array;
+declare function sign(message: Uint8Array, privateKey: Uint8Array): Uint8Array;
+declare function verify(message: Uint8Array, signature: Uint8Array, publicKey: Uint8Array): boolean;
+/**
+ * Sign a value by canonicalizing it to JSON bytes first.
+ * Use this for any object payload that must round-trip across devices.
+ */
+declare function signCanonical(value: unknown, privateKey: Uint8Array): Uint8Array;
+declare function verifyCanonical(value: unknown, signature: Uint8Array, publicKey: Uint8Array): boolean;
+
+declare const OAC_DEFAULT_PER_TX_KOBO = 500000;
+declare const OAC_DEFAULT_CUMULATIVE_KOBO = 2000000;
+declare const OAC_DEFAULT_VALIDITY_MS: number;
+declare const OACSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
+    userId: z.ZodString;
+    deviceId: z.ZodString;
+    devicePublicKey: z.ZodString;
+    perTxCapKobo: z.ZodNumber;
+    cumulativeCapKobo: z.ZodNumber;
+    validFromMs: z.ZodNumber;
+    validUntilMs: z.ZodNumber;
+    counterSeed: z.ZodNumber;
+    nonce: z.ZodString;
+    issuerSig: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    userId: string;
+    deviceId: string;
+    nonce: string;
+    devicePublicKey: string;
+    perTxCapKobo: number;
+    cumulativeCapKobo: number;
+    validFromMs: number;
+    validUntilMs: number;
+    counterSeed: number;
+    issuerSig: string;
+}, {
+    userId: string;
+    deviceId: string;
+    nonce: string;
+    devicePublicKey: string;
+    perTxCapKobo: number;
+    cumulativeCapKobo: number;
+    validFromMs: number;
+    validUntilMs: number;
+    counterSeed: number;
+    issuerSig: string;
+}>, {
+    userId: string;
+    deviceId: string;
+    nonce: string;
+    devicePublicKey: string;
+    perTxCapKobo: number;
+    cumulativeCapKobo: number;
+    validFromMs: number;
+    validUntilMs: number;
+    counterSeed: number;
+    issuerSig: string;
+}, {
+    userId: string;
+    deviceId: string;
+    nonce: string;
+    devicePublicKey: string;
+    perTxCapKobo: number;
+    cumulativeCapKobo: number;
+    validFromMs: number;
+    validUntilMs: number;
+    counterSeed: number;
+    issuerSig: string;
+}>, {
+    userId: string;
+    deviceId: string;
+    nonce: string;
+    devicePublicKey: string;
+    perTxCapKobo: number;
+    cumulativeCapKobo: number;
+    validFromMs: number;
+    validUntilMs: number;
+    counterSeed: number;
+    issuerSig: string;
+}, {
+    userId: string;
+    deviceId: string;
+    nonce: string;
+    devicePublicKey: string;
+    perTxCapKobo: number;
+    cumulativeCapKobo: number;
+    validFromMs: number;
+    validUntilMs: number;
+    counterSeed: number;
+    issuerSig: string;
+}>;
+type OAC = z.infer<typeof OACSchema>;
+type UnsignedOAC = Omit<OAC, 'issuerSig'>;
+declare function buildOAC(input: {
+    userId: string;
+    deviceId: string;
+    devicePublicKey: Uint8Array | string;
+    perTxCapKobo?: number;
+    cumulativeCapKobo?: number;
+    validFromMs: number;
+    validUntilMs: number;
+    counterSeed?: number;
+    nonce: string;
+}): UnsignedOAC;
+declare function signOAC(unsigned: UnsignedOAC, issuerPrivateKey: Uint8Array): OAC;
+declare function verifyOAC(oac: OAC, issuerPublicKey: Uint8Array): boolean;
+
+declare function encodeBase45(bytes: Uint8Array): string;
+declare function decodeBase45(s: string): Uint8Array;
+
+declare const OfflinePaymentRequestSchema: z.ZodObject<{
+    reference: z.ZodString;
+    amountKobo: z.ZodNumber;
+    merchantOAC: z.ZodEffects<z.ZodEffects<z.ZodObject<{
+        userId: z.ZodString;
+        deviceId: z.ZodString;
+        devicePublicKey: z.ZodString;
+        perTxCapKobo: z.ZodNumber;
+        cumulativeCapKobo: z.ZodNumber;
+        validFromMs: z.ZodNumber;
+        validUntilMs: z.ZodNumber;
+        counterSeed: z.ZodNumber;
+        nonce: z.ZodString;
+        issuerSig: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        userId: string;
+        deviceId: string;
+        nonce: string;
+        devicePublicKey: string;
+        perTxCapKobo: number;
+        cumulativeCapKobo: number;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+    }, {
+        userId: string;
+        deviceId: string;
+        nonce: string;
+        devicePublicKey: string;
+        perTxCapKobo: number;
+        cumulativeCapKobo: number;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+    }>, {
+        userId: string;
+        deviceId: string;
+        nonce: string;
+        devicePublicKey: string;
+        perTxCapKobo: number;
+        cumulativeCapKobo: number;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+    }, {
+        userId: string;
+        deviceId: string;
+        nonce: string;
+        devicePublicKey: string;
+        perTxCapKobo: number;
+        cumulativeCapKobo: number;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+    }>, {
+        userId: string;
+        deviceId: string;
+        nonce: string;
+        devicePublicKey: string;
+        perTxCapKobo: number;
+        cumulativeCapKobo: number;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+    }, {
+        userId: string;
+        deviceId: string;
+        nonce: string;
+        devicePublicKey: string;
+        perTxCapKobo: number;
+        cumulativeCapKobo: number;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+    }>;
+    expiresAtMs: z.ZodNumber;
+    merchantSig: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reference: string;
+    amountKobo: number;
+    merchantOAC: {
+        userId: string;
+        deviceId: string;
+        nonce: string;
+        devicePublicKey: string;
+        perTxCapKobo: number;
+        cumulativeCapKobo: number;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+    };
+    expiresAtMs: number;
+    merchantSig: string;
+}, {
+    reference: string;
+    amountKobo: number;
+    merchantOAC: {
+        userId: string;
+        deviceId: string;
+        nonce: string;
+        devicePublicKey: string;
+        perTxCapKobo: number;
+        cumulativeCapKobo: number;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+    };
+    expiresAtMs: number;
+    merchantSig: string;
+}>;
+type OfflinePaymentRequest = z.infer<typeof OfflinePaymentRequestSchema>;
+type UnsignedOfflinePaymentRequest = Omit<OfflinePaymentRequest, 'merchantSig'>;
+declare const OfflinePaymentAuthorizationSchema: z.ZodObject<{
+    request: z.ZodObject<{
+        reference: z.ZodString;
+        amountKobo: z.ZodNumber;
+        merchantOAC: z.ZodEffects<z.ZodEffects<z.ZodObject<{
+            userId: z.ZodString;
+            deviceId: z.ZodString;
+            devicePublicKey: z.ZodString;
+            perTxCapKobo: z.ZodNumber;
+            cumulativeCapKobo: z.ZodNumber;
+            validFromMs: z.ZodNumber;
+            validUntilMs: z.ZodNumber;
+            counterSeed: z.ZodNumber;
+            nonce: z.ZodString;
+            issuerSig: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            userId: string;
+            deviceId: string;
+            nonce: string;
+            devicePublicKey: string;
+            perTxCapKobo: number;
+            cumulativeCapKobo: number;
+            validFromMs: number;
+            validUntilMs: number;
+            counterSeed: number;
+            issuerSig: string;
+        }, {
+            userId: string;
+            deviceId: string;
+            nonce: string;
+            devicePublicKey: string;
+            perTxCapKobo: number;
+            cumulativeCapKobo: number;
+            validFromMs: number;
+            validUntilMs: number;
+            counterSeed: number;
+            issuerSig: string;
+        }>, {
+            userId: string;
+            deviceId: string;
+            nonce: string;
+            devicePublicKey: string;
+            perTxCapKobo: number;
+            cumulativeCapKobo: number;
+            validFromMs: number;
+            validUntilMs: number;
+            counterSeed: number;
+            issuerSig: string;
+        }, {
+            userId: string;
+            deviceId: string;
+            nonce: string;
+            devicePublicKey: string;
+            perTxCapKobo: number;
+            cumulativeCapKobo: number;
+            validFromMs: number;
+            validUntilMs: number;
+            counterSeed: number;
+            issuerSig: string;
+        }>, {
+            userId: string;
+            deviceId: string;
+            nonce: string;
+            devicePublicKey: string;
+            perTxCapKobo: number;
+            cumulativeCapKobo: number;
+            validFromMs: number;
+            validUntilMs: number;
+            counterSeed: number;
+            issuerSig: string;
+        }, {
+            userId: string;
+            deviceId: string;
+            nonce: string;
+            devicePublicKey: string;
+            perTxCapKobo: number;
+            cumulativeCapKobo: number;
+            validFromMs: number;
+            validUntilMs: number;
+            counterSeed: number;
+            issuerSig: string;
+        }>;
+        expiresAtMs: z.ZodNumber;
+        merchantSig: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        reference: string;
+        amountKobo: number;
+        merchantOAC: {
+            userId: string;
+            deviceId: string;
+            nonce: string;
+            devicePublicKey: string;
+            perTxCapKobo: number;
+            cumulativeCapKobo: number;
+            validFromMs: number;
+            validUntilMs: number;
+            counterSeed: number;
+            issuerSig: string;
+        };
+        expiresAtMs: number;
+        merchantSig: string;
+    }, {
+        reference: string;
+        amountKobo: number;
+        merchantOAC: {
+            userId: string;
+            deviceId: string;
+            nonce: string;
+            devicePublicKey: string;
+            perTxCapKobo: number;
+            cumulativeCapKobo: number;
+            validFromMs: number;
+            validUntilMs: number;
+            counterSeed: number;
+            issuerSig: string;
+        };
+        expiresAtMs: number;
+        merchantSig: string;
+    }>;
+    payerOAC: z.ZodEffects<z.ZodEffects<z.ZodObject<{
+        userId: z.ZodString;
+        deviceId: z.ZodString;
+        devicePublicKey: z.ZodString;
+        perTxCapKobo: z.ZodNumber;
+        cumulativeCapKobo: z.ZodNumber;
+        validFromMs: z.ZodNumber;
+        validUntilMs: z.ZodNumber;
+        counterSeed: z.ZodNumber;
+        nonce: z.ZodString;
+        issuerSig: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        userId: string;
+        deviceId: string;
+        nonce: string;
+        devicePublicKey: string;
+        perTxCapKobo: number;
+        cumulativeCapKobo: number;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+    }, {
+        userId: string;
+        deviceId: string;
+        nonce: string;
+        devicePublicKey: string;
+        perTxCapKobo: number;
+        cumulativeCapKobo: number;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+    }>, {
+        userId: string;
+        deviceId: string;
+        nonce: string;
+        devicePublicKey: string;
+        perTxCapKobo: number;
+        cumulativeCapKobo: number;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+    }, {
+        userId: string;
+        deviceId: string;
+        nonce: string;
+        devicePublicKey: string;
+        perTxCapKobo: number;
+        cumulativeCapKobo: number;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+    }>, {
+        userId: string;
+        deviceId: string;
+        nonce: string;
+        devicePublicKey: string;
+        perTxCapKobo: number;
+        cumulativeCapKobo: number;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+    }, {
+        userId: string;
+        deviceId: string;
+        nonce: string;
+        devicePublicKey: string;
+        perTxCapKobo: number;
+        cumulativeCapKobo: number;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+    }>;
+    payerCounter: z.ZodNumber;
+    payerSig: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    request: {
+        reference: string;
+        amountKobo: number;
+        merchantOAC: {
+            userId: string;
+            deviceId: string;
+            nonce: string;
+            devicePublicKey: string;
+            perTxCapKobo: number;
+            cumulativeCapKobo: number;
+            validFromMs: number;
+            validUntilMs: number;
+            counterSeed: number;
+            issuerSig: string;
+        };
+        expiresAtMs: number;
+        merchantSig: string;
+    };
+    payerOAC: {
+        userId: string;
+        deviceId: string;
+        nonce: string;
+        devicePublicKey: string;
+        perTxCapKobo: number;
+        cumulativeCapKobo: number;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+    };
+    payerCounter: number;
+    payerSig: string;
+}, {
+    request: {
+        reference: string;
+        amountKobo: number;
+        merchantOAC: {
+            userId: string;
+            deviceId: string;
+            nonce: string;
+            devicePublicKey: string;
+            perTxCapKobo: number;
+            cumulativeCapKobo: number;
+            validFromMs: number;
+            validUntilMs: number;
+            counterSeed: number;
+            issuerSig: string;
+        };
+        expiresAtMs: number;
+        merchantSig: string;
+    };
+    payerOAC: {
+        userId: string;
+        deviceId: string;
+        nonce: string;
+        devicePublicKey: string;
+        perTxCapKobo: number;
+        cumulativeCapKobo: number;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+    };
+    payerCounter: number;
+    payerSig: string;
+}>;
+type OfflinePaymentAuthorization = z.infer<typeof OfflinePaymentAuthorizationSchema>;
+type UnsignedOfflinePaymentAuthorization = Omit<OfflinePaymentAuthorization, 'payerSig'>;
+declare function buildPaymentRequest(input: {
+    reference: string;
+    amountKobo: number;
+    merchantOAC: OAC;
+    expiresAtMs: number;
+}): UnsignedOfflinePaymentRequest;
+declare function signPaymentRequest(unsigned: UnsignedOfflinePaymentRequest, merchantDevicePrivateKey: Uint8Array): OfflinePaymentRequest;
+declare function verifyPaymentRequest(req: OfflinePaymentRequest, issuerPublicKey: Uint8Array): boolean;
+declare function buildAuthorization(input: {
+    request: OfflinePaymentRequest;
+    payerOAC: OAC;
+    payerCounter: number;
+}): UnsignedOfflinePaymentAuthorization;
+declare function signAuthorization(unsigned: UnsignedOfflinePaymentAuthorization, payerDevicePrivateKey: Uint8Array): OfflinePaymentAuthorization;
+declare function verifyAuthorization(auth: OfflinePaymentAuthorization, issuerPublicKey: Uint8Array): boolean;
+declare function encodePaymentRequestQR(req: OfflinePaymentRequest): string;
+declare function decodePaymentRequestQR(s: string): OfflinePaymentRequest;
+declare function encodeAuthorizationQR(auth: OfflinePaymentAuthorization): string;
+declare function decodeAuthorizationQR(s: string): OfflinePaymentAuthorization;
+
+declare function bodySha256Hex(body: string): string;
+declare function canonicalRequestString(input: {
+    method: string;
+    path: string;
+    timestamp: string;
+    nonce: string;
+    body: string;
+}): string;
+declare function signRequestHMAC(input: {
+    method: string;
+    path: string;
+    timestamp: string;
+    nonce: string;
+    body: string;
+    apiSecret: string;
+}): string;
+declare function verifyRequestHMAC(input: {
+    method: string;
+    path: string;
+    timestamp: string;
+    nonce: string;
+    body: string;
+    apiSecret: string;
+    signature: string;
+}): boolean;
+
+declare const REPLAY_WINDOW_MS: number;
+type HmacFetchOptions = {
+    apiKey: string;
+    apiSecret: string;
+    fetchImpl?: typeof fetch;
+    nowMs?: () => number;
+    nonceFn?: () => string;
+    /** Optional scope claim forwarded as `X-Flur-Scope` (comma-joined). Backend remains authoritative. */
+    scope?: readonly string[];
+};
+declare function createHmacFetch(opts: HmacFetchOptions): typeof fetch;
+
+declare const PASS_KINDS: readonly ["ride-ticket", "transit-pass", "event-ticket", "voucher", "loyalty", "receipt-link"];
+type PassKind = (typeof PASS_KINDS)[number];
+declare const PASS_STATES: readonly ["issued", "active", "redeemed", "expired", "revoked"];
+type PassState = (typeof PASS_STATES)[number];
+/** JSON-serialisable metadata payload — bounded to keep QR/offline encodings tractable. */
+declare const PassMetadataSchema: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+type PassMetadata = z.infer<typeof PassMetadataSchema>;
+declare const PassSchema: z.ZodEffects<z.ZodObject<{
+    passId: z.ZodString;
+    /** Optional client/template grouping id (server may omit). */
+    templateId: z.ZodOptional<z.ZodString>;
+    /** Optional human-facing holder identity (server may omit). The cryptographic binding
+     *  is `holderDevicePubkey` below. */
+    holderUserId: z.ZodOptional<z.ZodString>;
+    kind: z.ZodEnum<["ride-ticket", "transit-pass", "event-ticket", "voucher", "loyalty", "receipt-link"]>;
+    issuerId: z.ZodString;
+    issuedAtMs: z.ZodNumber;
+    validFromMs: z.ZodNumber;
+    validUntilMs: z.ZodNumber;
+    state: z.ZodEnum<["issued", "active", "redeemed", "expired", "revoked"]>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    nonce: z.ZodString;
+    /** Device id this pass is bound to (FK to backend `device_keys`). */
+    holderDeviceId: z.ZodString;
+    /** 32-byte hex Ed25519 public key of the bound device. The redemption signature
+     *  is verified against this key — it is the security-critical binding. */
+    holderDevicePubkey: z.ZodString;
+    /** Optional fixed amount for monetary passes (vouchers, gift cards) in kobo. */
+    amountKobo: z.ZodOptional<z.ZodNumber>;
+    /** ISO-4217-ish currency code; required on the wire. SDK builders default to NGN. */
+    currency: z.ZodString;
+    /** Monotonic redemption counter floor. Redemption.counter MUST be > counterSeed. */
+    counterSeed: z.ZodNumber;
+    /** Optional cumulative spend cap in kobo across all redemptions of this pass. */
+    cumulativeCapKobo: z.ZodOptional<z.ZodNumber>;
+    issuerSig: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    nonce: string;
+    currency: string;
+    validFromMs: number;
+    validUntilMs: number;
+    counterSeed: number;
+    issuerSig: string;
+    passId: string;
+    kind: "ride-ticket" | "transit-pass" | "event-ticket" | "voucher" | "loyalty" | "receipt-link";
+    issuerId: string;
+    issuedAtMs: number;
+    state: "issued" | "active" | "redeemed" | "expired" | "revoked";
+    metadata: Record<string, string | number | boolean | null>;
+    holderDeviceId: string;
+    holderDevicePubkey: string;
+    cumulativeCapKobo?: number | undefined;
+    amountKobo?: number | undefined;
+    templateId?: string | undefined;
+    holderUserId?: string | undefined;
+}, {
+    nonce: string;
+    currency: string;
+    validFromMs: number;
+    validUntilMs: number;
+    counterSeed: number;
+    issuerSig: string;
+    passId: string;
+    kind: "ride-ticket" | "transit-pass" | "event-ticket" | "voucher" | "loyalty" | "receipt-link";
+    issuerId: string;
+    issuedAtMs: number;
+    state: "issued" | "active" | "redeemed" | "expired" | "revoked";
+    metadata: Record<string, string | number | boolean | null>;
+    holderDeviceId: string;
+    holderDevicePubkey: string;
+    cumulativeCapKobo?: number | undefined;
+    amountKobo?: number | undefined;
+    templateId?: string | undefined;
+    holderUserId?: string | undefined;
+}>, {
+    nonce: string;
+    currency: string;
+    validFromMs: number;
+    validUntilMs: number;
+    counterSeed: number;
+    issuerSig: string;
+    passId: string;
+    kind: "ride-ticket" | "transit-pass" | "event-ticket" | "voucher" | "loyalty" | "receipt-link";
+    issuerId: string;
+    issuedAtMs: number;
+    state: "issued" | "active" | "redeemed" | "expired" | "revoked";
+    metadata: Record<string, string | number | boolean | null>;
+    holderDeviceId: string;
+    holderDevicePubkey: string;
+    cumulativeCapKobo?: number | undefined;
+    amountKobo?: number | undefined;
+    templateId?: string | undefined;
+    holderUserId?: string | undefined;
+}, {
+    nonce: string;
+    currency: string;
+    validFromMs: number;
+    validUntilMs: number;
+    counterSeed: number;
+    issuerSig: string;
+    passId: string;
+    kind: "ride-ticket" | "transit-pass" | "event-ticket" | "voucher" | "loyalty" | "receipt-link";
+    issuerId: string;
+    issuedAtMs: number;
+    state: "issued" | "active" | "redeemed" | "expired" | "revoked";
+    metadata: Record<string, string | number | boolean | null>;
+    holderDeviceId: string;
+    holderDevicePubkey: string;
+    cumulativeCapKobo?: number | undefined;
+    amountKobo?: number | undefined;
+    templateId?: string | undefined;
+    holderUserId?: string | undefined;
+}>;
+type Pass = z.infer<typeof PassSchema>;
+type UnsignedPass = Omit<Pass, 'issuerSig'>;
+type BuildPassInput = {
+    passId: string;
+    templateId?: string;
+    holderUserId?: string;
+    kind: PassKind;
+    issuerId: string;
+    issuedAtMs: number;
+    validFromMs: number;
+    validUntilMs: number;
+    state: PassState;
+    metadata: PassMetadata;
+    nonce: string;
+    holderDeviceId: string;
+    holderDevicePubkey: string;
+    amountKobo?: number;
+    currency?: string;
+    counterSeed: number;
+    cumulativeCapKobo?: number;
+};
+declare function buildPass(input: BuildPassInput): UnsignedPass;
+declare function signPass(unsigned: UnsignedPass, issuerPrivateKey: Uint8Array): Pass;
+declare function verifyPass(pass: Pass, issuerPublicKey: Uint8Array): boolean;
+/**
+ * Validity window check is done separately from signature verification so callers can
+ * decide their clock-skew tolerance.
+ */
+declare function isPassWithinValidity(pass: Pass, nowMs: number): boolean;
+
+declare const RedemptionSchema: z.ZodObject<{
+    pass: z.ZodEffects<z.ZodObject<{
+        passId: z.ZodString;
+        templateId: z.ZodOptional<z.ZodString>;
+        holderUserId: z.ZodOptional<z.ZodString>;
+        kind: z.ZodEnum<["ride-ticket", "transit-pass", "event-ticket", "voucher", "loyalty", "receipt-link"]>;
+        issuerId: z.ZodString;
+        issuedAtMs: z.ZodNumber;
+        validFromMs: z.ZodNumber;
+        validUntilMs: z.ZodNumber;
+        state: z.ZodEnum<["issued", "active", "redeemed", "expired", "revoked"]>;
+        metadata: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+        nonce: z.ZodString;
+        holderDeviceId: z.ZodString;
+        holderDevicePubkey: z.ZodString;
+        amountKobo: z.ZodOptional<z.ZodNumber>;
+        currency: z.ZodString;
+        counterSeed: z.ZodNumber;
+        cumulativeCapKobo: z.ZodOptional<z.ZodNumber>;
+        issuerSig: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        nonce: string;
+        currency: string;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+        passId: string;
+        kind: "ride-ticket" | "transit-pass" | "event-ticket" | "voucher" | "loyalty" | "receipt-link";
+        issuerId: string;
+        issuedAtMs: number;
+        state: "issued" | "active" | "redeemed" | "expired" | "revoked";
+        metadata: Record<string, string | number | boolean | null>;
+        holderDeviceId: string;
+        holderDevicePubkey: string;
+        cumulativeCapKobo?: number | undefined;
+        amountKobo?: number | undefined;
+        templateId?: string | undefined;
+        holderUserId?: string | undefined;
+    }, {
+        nonce: string;
+        currency: string;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+        passId: string;
+        kind: "ride-ticket" | "transit-pass" | "event-ticket" | "voucher" | "loyalty" | "receipt-link";
+        issuerId: string;
+        issuedAtMs: number;
+        state: "issued" | "active" | "redeemed" | "expired" | "revoked";
+        metadata: Record<string, string | number | boolean | null>;
+        holderDeviceId: string;
+        holderDevicePubkey: string;
+        cumulativeCapKobo?: number | undefined;
+        amountKobo?: number | undefined;
+        templateId?: string | undefined;
+        holderUserId?: string | undefined;
+    }>, {
+        nonce: string;
+        currency: string;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+        passId: string;
+        kind: "ride-ticket" | "transit-pass" | "event-ticket" | "voucher" | "loyalty" | "receipt-link";
+        issuerId: string;
+        issuedAtMs: number;
+        state: "issued" | "active" | "redeemed" | "expired" | "revoked";
+        metadata: Record<string, string | number | boolean | null>;
+        holderDeviceId: string;
+        holderDevicePubkey: string;
+        cumulativeCapKobo?: number | undefined;
+        amountKobo?: number | undefined;
+        templateId?: string | undefined;
+        holderUserId?: string | undefined;
+    }, {
+        nonce: string;
+        currency: string;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+        passId: string;
+        kind: "ride-ticket" | "transit-pass" | "event-ticket" | "voucher" | "loyalty" | "receipt-link";
+        issuerId: string;
+        issuedAtMs: number;
+        state: "issued" | "active" | "redeemed" | "expired" | "revoked";
+        metadata: Record<string, string | number | boolean | null>;
+        holderDeviceId: string;
+        holderDevicePubkey: string;
+        cumulativeCapKobo?: number | undefined;
+        amountKobo?: number | undefined;
+        templateId?: string | undefined;
+        holderUserId?: string | undefined;
+    }>;
+    redeemerId: z.ZodString;
+    redeemedAtMs: z.ZodNumber;
+    /** Strictly monotonic counter scoped to a single pass. Must be > pass.counterSeed
+     *  and > the redeemer's lastSeenCounter for this pass. */
+    counter: z.ZodNumber;
+    /** Amount being redeemed in kobo (0 for non-monetary passes like ride tickets). */
+    amountKobo: z.ZodNumber;
+    nonce: z.ZodString;
+    holderSig: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    nonce: string;
+    amountKobo: number;
+    pass: {
+        nonce: string;
+        currency: string;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+        passId: string;
+        kind: "ride-ticket" | "transit-pass" | "event-ticket" | "voucher" | "loyalty" | "receipt-link";
+        issuerId: string;
+        issuedAtMs: number;
+        state: "issued" | "active" | "redeemed" | "expired" | "revoked";
+        metadata: Record<string, string | number | boolean | null>;
+        holderDeviceId: string;
+        holderDevicePubkey: string;
+        cumulativeCapKobo?: number | undefined;
+        amountKobo?: number | undefined;
+        templateId?: string | undefined;
+        holderUserId?: string | undefined;
+    };
+    redeemerId: string;
+    redeemedAtMs: number;
+    counter: number;
+    holderSig: string;
+}, {
+    nonce: string;
+    amountKobo: number;
+    pass: {
+        nonce: string;
+        currency: string;
+        validFromMs: number;
+        validUntilMs: number;
+        counterSeed: number;
+        issuerSig: string;
+        passId: string;
+        kind: "ride-ticket" | "transit-pass" | "event-ticket" | "voucher" | "loyalty" | "receipt-link";
+        issuerId: string;
+        issuedAtMs: number;
+        state: "issued" | "active" | "redeemed" | "expired" | "revoked";
+        metadata: Record<string, string | number | boolean | null>;
+        holderDeviceId: string;
+        holderDevicePubkey: string;
+        cumulativeCapKobo?: number | undefined;
+        amountKobo?: number | undefined;
+        templateId?: string | undefined;
+        holderUserId?: string | undefined;
+    };
+    redeemerId: string;
+    redeemedAtMs: number;
+    counter: number;
+    holderSig: string;
+}>;
+type Redemption = z.infer<typeof RedemptionSchema>;
+type UnsignedRedemption = Omit<Redemption, 'holderSig'>;
+type BuildRedemptionInput = {
+    pass: Pass;
+    redeemerId: string;
+    redeemedAtMs: number;
+    counter: number;
+    amountKobo?: number;
+    nonce: string;
+    /** Optional local clock — if supplied, fail-fast against pass.validUntilMs. */
+    nowMs?: number;
+    /** Last counter the holder has seen for this pass (default: pass.counterSeed). */
+    lastSeenCounter?: number;
+    /** Total kobo already redeemed against this pass (default: 0). Used with pass.cumulativeCapKobo. */
+    cumulativeUsedKobo?: number;
+};
+declare function buildRedemption(input: BuildRedemptionInput): UnsignedRedemption;
+declare function signRedemption(unsigned: UnsignedRedemption, holderDevicePrivateKey: Uint8Array): Redemption;
+/**
+ * Verifies, in order:
+ *  1. The pass itself is signed by the issuer.
+ *  2. The pass binds a `holderDevicePubkey` (top-level, security-critical).
+ *  3. The redemption is signed by that bound device key.
+ *  4. The redemption counter is strictly greater than pass.counterSeed.
+ */
+declare function verifyRedemption(r: Redemption, issuerPublicKey: Uint8Array): boolean;
+
+type PassesClientOptions = {
+    baseUrl: string;
+    /** Pre-configured fetch (typically `createHmacFetch(...)`). Falls back to global fetch. */
+    fetchImpl?: typeof fetch;
+};
+type IssuePassInput = {
+    /** Device this pass is bound to. Required (BE-19). */
+    holderDeviceId: string;
+    /** 32-byte hex Ed25519 public key of the bound device. Required (BE-19). */
+    holderDevicePubkey: string;
+    /** Pass kind (server may default for templated flows). */
+    kind: PassKind;
+    /** Optional fixed amount for monetary passes (kobo). */
+    amountKobo?: number;
+    /** Optional cumulative spend cap in kobo across all redemptions. */
+    cumulativeCapKobo?: number;
+    validFromMs: number;
+    validUntilMs: number;
+    metadata?: PassMetadata;
+    /** Optional template grouping id (server may emit one if omitted). */
+    templateId?: string;
+    /** Optional human-facing holder identity. */
+    holderUserId?: string;
+    /** Optional client-supplied id for idempotency / retries. */
+    passId?: string;
+};
+type ListPassesInput = {
+    holderDeviceId?: string;
+    holderUserId?: string;
+    state?: PassState;
+    kind?: PassKind;
+    templateId?: string;
+    limit?: number;
+    cursor?: string;
+};
+type ListPassesResponse = {
+    items: Pass[];
+    nextCursor: string | null;
+};
+type RevokePassInput = {
+    reason: string;
+};
+type PassesClient = {
+    issuePass: (input: IssuePassInput) => Promise<Pass>;
+    listPasses: (input: ListPassesInput) => Promise<ListPassesResponse>;
+    getPass: (passId: string) => Promise<Pass>;
+    redeemPass: (passId: string, redemption: Redemption) => Promise<Pass>;
+    revokePass: (passId: string, input: RevokePassInput) => Promise<Pass>;
+    /** Local Ed25519 verification of a pass envelope under the supplied issuer public key. */
+    verifyPass: (pass: Pass, issuerPublicKey: Uint8Array) => boolean;
+};
+declare function createPassesClient(opts: PassesClientOptions): PassesClient;
+
+declare const RECEIPT_CHANNELS: readonly ["cash", "pass"];
+type ReceiptChannel = (typeof RECEIPT_CHANNELS)[number];
+/** @deprecated use {@link RECEIPT_CHANNELS}. Will be removed before 1.0. */
+declare const RECEIPT_KINDS: readonly ["cash", "pass"];
+/** @deprecated use {@link ReceiptChannel}. */
+type ReceiptKind = ReceiptChannel;
+/** Free-form payload reserved for channel-specific extras (e.g. memo, intent metadata).
+ *  Top-level fields below are the security-relevant facts and must not be duplicated here. */
+declare const ReceiptPayloadSchema: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+type ReceiptPayload = z.infer<typeof ReceiptPayloadSchema>;
+/** BE-20 wire schema: channel + exactly one of `intentId` (cash) or `passRedemptionId` (pass). */
+declare const ReceiptSchema: z.ZodEffects<z.ZodObject<{
+    receiptId: z.ZodString;
+    channel: z.ZodEnum<["cash", "pass"]>;
+    /** Cash-channel: send_intents.id. Required when channel === 'cash'. */
+    intentId: z.ZodOptional<z.ZodString>;
+    /** Pass-channel: pass_redemptions.id. Required when channel === 'pass'. */
+    passRedemptionId: z.ZodOptional<z.ZodString>;
+    payerUserId: z.ZodString;
+    payeeUserId: z.ZodString;
+    amountKobo: z.ZodNumber;
+    currency: z.ZodString;
+    issuedAtMs: z.ZodNumber;
+    issuerId: z.ZodString;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    issuerSig: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    currency: string;
+    issuerSig: string;
+    amountKobo: number;
+    issuerId: string;
+    issuedAtMs: number;
+    receiptId: string;
+    channel: "pass" | "cash";
+    payerUserId: string;
+    payeeUserId: string;
+    payload: Record<string, string | number | boolean | null>;
+    intentId?: string | undefined;
+    passRedemptionId?: string | undefined;
+}, {
+    currency: string;
+    issuerSig: string;
+    amountKobo: number;
+    issuerId: string;
+    issuedAtMs: number;
+    receiptId: string;
+    channel: "pass" | "cash";
+    payerUserId: string;
+    payeeUserId: string;
+    payload: Record<string, string | number | boolean | null>;
+    intentId?: string | undefined;
+    passRedemptionId?: string | undefined;
+}>, {
+    currency: string;
+    issuerSig: string;
+    amountKobo: number;
+    issuerId: string;
+    issuedAtMs: number;
+    receiptId: string;
+    channel: "pass" | "cash";
+    payerUserId: string;
+    payeeUserId: string;
+    payload: Record<string, string | number | boolean | null>;
+    intentId?: string | undefined;
+    passRedemptionId?: string | undefined;
+}, {
+    currency: string;
+    issuerSig: string;
+    amountKobo: number;
+    issuerId: string;
+    issuedAtMs: number;
+    receiptId: string;
+    channel: "pass" | "cash";
+    payerUserId: string;
+    payeeUserId: string;
+    payload: Record<string, string | number | boolean | null>;
+    intentId?: string | undefined;
+    passRedemptionId?: string | undefined;
+}>;
+type Receipt = z.infer<typeof ReceiptSchema>;
+type UnsignedReceipt = Omit<Receipt, 'issuerSig'>;
+type BuildReceiptInput = {
+    receiptId: string;
+    channel: ReceiptChannel;
+    intentId?: string;
+    passRedemptionId?: string;
+    payerUserId: string;
+    payeeUserId: string;
+    amountKobo: number;
+    currency: string;
+    issuedAtMs: number;
+    issuerId: string;
+    payload?: ReceiptPayload;
+};
+declare function buildReceipt(input: BuildReceiptInput): UnsignedReceipt;
+declare function signReceipt(unsigned: UnsignedReceipt, issuerPrivateKey: Uint8Array): Receipt;
+declare function verifyReceipt(r: Receipt, issuerPublicKey: Uint8Array): boolean;
+
+type ReceiptsClientOptions = {
+    baseUrl: string;
+    fetchImpl?: typeof fetch;
+};
+type IssueReceiptInput = {
+    channel: ReceiptChannel;
+    /** Required for cash channel; FK to send_intents.id. */
+    intentId?: string;
+    /** Required for pass channel; FK to pass_redemptions.id. */
+    passRedemptionId?: string;
+    payerUserId: string;
+    payeeUserId: string;
+    amountKobo: number;
+    currency: string;
+    payload?: ReceiptPayload;
+    /** Optional client-supplied id for idempotency / retries. */
+    receiptId?: string;
+};
+type ListReceiptsInput = {
+    /** Filter by either side of the receipt. Server scopes by caller identity. */
+    payerUserId?: string;
+    payeeUserId?: string;
+    channel?: ReceiptChannel;
+    limit?: number;
+    cursor?: string;
+};
+type ListReceiptsResponse = {
+    items: Receipt[];
+    nextCursor: string | null;
+};
+type ReceiptsClient = {
+    issueReceipt: (input: IssueReceiptInput) => Promise<Receipt>;
+    /** Alias of `getById`, matches addendum surface. */
+    getReceipt: (receiptId: string) => Promise<Receipt>;
+    getById: (receiptId: string) => Promise<Receipt>;
+    /** Look up a cash-channel receipt by its originating intentId. */
+    getByIntentId: (intentId: string) => Promise<Receipt>;
+    /** Look up a pass-channel receipt by its originating passRedemptionId. */
+    getByPassRedemptionId: (passRedemptionId: string) => Promise<Receipt>;
+    listForUser: (input: ListReceiptsInput) => Promise<ListReceiptsResponse>;
+    /** Local Ed25519 verification of a receipt envelope under the supplied issuer key. */
+    verifyReceipt: (receipt: Receipt, issuerPublicKey: Uint8Array) => boolean;
+};
+declare function createReceiptsClient(opts: ReceiptsClientOptions): ReceiptsClient;
+
+type FlurInitOptions = {
+    apiKey: string;
+    apiSecret: string;
+    baseUrl: string;
+    fetchImpl?: typeof fetch;
+    /** When true, all QR generation is performed locally without any network call. */
+    offlineMode?: boolean;
+    /** Optional scope claim forwarded as `X-Flur-Scope`. Backend remains authoritative. */
+    scope?: readonly string[];
+};
+type FlurPaymentEvent = {
+    type: string;
+    reference?: string;
+    [k: string]: unknown;
+};
+type SubscribeOptions = {
+    reference: string;
+    onEvent: (event: FlurPaymentEvent) => void;
+    onError?: (err: unknown) => void;
+};
+declare function generateStaticQR(input: Omit<NQRPayloadInput, 'pointOfInitiation'>): string;
+declare function generateDynamicQR(input: Omit<NQRPayloadInput, 'pointOfInitiation'>): string;
+declare function parseQR(payload: string): ParsedNQR;
+type CashNamespace = {
+    generateStaticQR: typeof generateStaticQR;
+    generateDynamicQR: typeof generateDynamicQR;
+    parseQR: typeof parseQR;
+    subscribeToPayments: (opts: SubscribeOptions) => () => void;
+};
+type FlurHandle = CashNamespace & {
+    /** Cash / money: NQR generation, payment subscriptions, transfers (future). */
+    cash: CashNamespace;
+    /** Passes: tickets, vouchers, loyalty, transit. */
+    passes: PassesClient;
+    /** Receipts: signed, immutable views over cash + pass events. */
+    receipts: ReceiptsClient;
+};
+declare function init(opts: FlurInitOptions): FlurHandle;
+
+export { ADDITIONAL_DATA_SUBFIELD, type AccountActivityItem, type AccountSummaryResponse, type AdditionalData, type AuthLogoutInput, type AuthRefreshInput, type AuthRefreshResponse, type AuthorizeSendWithBiometricInput, type AuthorizedOptions, type BiometricSigner, type BuildPassInput, type BuildReceiptInput, type BuildRedemptionInput, type CashNamespace, type CreatePayLinkResponse, type CreateTransferOptions, type DeviceTrustState, type Ed25519KeyPair, FIELD, FlurApiError, FlurCapExceededError, FlurClient, type FlurClientOptions, FlurError, type FlurErrorCode, FlurExpiredError, type FlurHandle, type FlurInitOptions, type FlurPaymentEvent, FlurReplayError, type HmacFetchOptions, type IssuePassInput, type IssueReceiptInput, type ListPassesInput, type ListPassesResponse, type ListReceiptsInput, type ListReceiptsResponse, type ListTransactionsOptions, type MerchantAccountInfo, type Money, NGN_CURRENCY_CODE, NG_COUNTRY_CODE, NQRParseError, type NQRPayloadInput, type OAC, OACSchema, OAC_DEFAULT_CUMULATIVE_KOBO, OAC_DEFAULT_PER_TX_KOBO, OAC_DEFAULT_VALIDITY_MS, type OfflinePaymentAuthorization, OfflinePaymentAuthorizationSchema, type OfflinePaymentRequest, OfflinePaymentRequestSchema, type OnboardingCompleteInput, type OnboardingCompleteResponse, type OnboardingFallback, type OnboardingRiskReason, type OnboardingStartInput, type OnboardingStartResponse, PASS_KINDS, PASS_STATES, PAYLOAD_FORMAT_INDICATOR_VALUE, POINT_OF_INITIATION, type ParsedNQR, type Pass, type PassKind, type PassMetadata, PassMetadataSchema, PassSchema, type PassState, type PassesClient, type PassesClientOptions, type PinSetInput, type PinVerifyInput, type PushPlatform, type PushRegisterInput, RECEIPT_CHANNELS, RECEIPT_KINDS, REPLAY_WINDOW_MS, type Receipt, type ReceiptChannel, type ReceiptKind, type ReceiptPayload, ReceiptPayloadSchema, ReceiptSchema, type ReceiptsClient, type ReceiptsClientOptions, type RecipientResolveInput, type RecipientResolveResponse, type Redemption, RedemptionSchema, type RegisterDeviceInput, type RegisterDeviceResponse, type RegisterSendDeviceKeyInput, type ResolvePayLinkResponse, type RevokePassInput, type RoutingHint, type SendChallengeInput, type SendChallengeResponse, type SendMoneyInput, type SendMoneyOptions, type SendVerifyInput, type SendVerifyResponse, type SubscribeOptions, type TLVField, type TransactionDetailResponse, type TransactionDirection, type TransactionsListResponse, type TransferInput, type TransferResponse, type TransferStatus, type UnsignedOAC, type UnsignedOfflinePaymentAuthorization, type UnsignedOfflinePaymentRequest, type UnsignedPass, type UnsignedReceipt, type UnsignedRedemption, bodySha256Hex, buildAuthorization, buildOAC, buildPass, buildPaymentRequest, buildReceipt, buildRedemption, canonicalJSONBytes, canonicalJSONStringify, canonicalRequestString, constantTimeEqual, crc16ccitt, crc16ccittHex, createHmacFetch, createPassesClient, createReceiptsClient, decodeAuthorizationQR, decodeBase45, decodePaymentRequestQR, encodeAuthorizationQR, encodeBase45, encodeNQR, encodePaymentRequestQR, formatAmount, generateDynamicQR, generateKeyPair, generateStaticQR, init, isPassWithinValidity, moneyMinorToNumber, normalizeE164, parseAmountInput, parseNQR, parseQR, publicKeyFromPrivate, readTLV, routingHint, sign, signAuthorization, signCanonical, signOAC, signPass, signPaymentRequest, signReceipt, signRedemption, signRequestHMAC, verify, verifyAuthorization, verifyCanonical, verifyOAC, verifyPass, verifyPaymentRequest, verifyReceipt, verifyRedemption, verifyRequestHMAC, writeTLV };