@miniduckco/stash 0.1.1

package/dist/src/providers/ozow.js

@@ -0,0 +1,258 @@
+import { sha512Hex } from "../internal/hash.js";
+import { formatAmount, requireValue, toStringValue } from "../internal/guards.js";
+import { parseFormEncoded, pairsToRecord } from "../internal/form.js";
+const OZOW_ORDER = [
+    "SiteCode",
+    "CountryCode",
+    "CurrencyCode",
+    "Amount",
+    "TransactionReference",
+    "BankReference",
+    "Optional1",
+    "Optional2",
+    "Optional3",
+    "Optional4",
+    "Optional5",
+    "Customer",
+    "CancelUrl",
+    "ErrorUrl",
+    "SuccessUrl",
+    "NotifyUrl",
+    "IsTest",
+    "SelectedBankId",
+    "BankAccountNumber",
+    "BankAccountBranchCode",
+    "BankAccountName",
+    "BankName",
+    "ExpiryDateUtc",
+    "AllowVariableAmount",
+    "VariableAmountMin",
+    "VariableAmountMax",
+    "CustomerIdentityNumber",
+    "CustomerCellphoneNumber",
+    "HashCheck",
+    "Token",
+    "GenerateShortUrl",
+];
+const OZOW_RESPONSE_ORDER = [
+    "SiteCode",
+    "TransactionId",
+    "TransactionReference",
+    "Amount",
+    "Status",
+    "Optional1",
+    "Optional2",
+    "Optional3",
+    "Optional4",
+    "Optional5",
+    "CurrencyCode",
+    "IsTest",
+    "StatusMessage",
+];
+const OZOW_ALLOWED_FIELDS = new Set(OZOW_ORDER);
+const OZOW_PROVIDER_OPTION_FIELDS = {
+    selectedBankId: "SelectedBankId",
+    customerIdentityNumber: "CustomerIdentityNumber",
+    allowVariableAmount: "AllowVariableAmount",
+    variableAmountMin: "VariableAmountMin",
+    variableAmountMax: "VariableAmountMax",
+};
+const OZOW_ENDPOINTS = {
+    live: "https://api.ozow.com/PostPaymentRequest",
+    sandbox: "https://stagingapi.ozow.com/PostPaymentRequest",
+};
+function buildOzowPayload(input) {
+    const siteCode = requireValue(input.secrets.siteCode, "secrets.siteCode");
+    const currency = (input.currency ?? "ZAR").toUpperCase();
+    const country = "ZA";
+    if (currency !== "ZAR") {
+        throw new Error("Ozow only supports ZAR amounts");
+    }
+    const payload = {
+        SiteCode: siteCode,
+        CountryCode: country,
+        CurrencyCode: currency,
+        Amount: formatAmount(input.amount),
+        TransactionReference: input.reference,
+    };
+    const bankReference = input.providerData?.BankReference ?? input.description ?? input.reference;
+    payload.BankReference = toStringValue(bankReference);
+    const providerOptions = input.providerOptions;
+    applyOzowProviderOptions(payload, providerOptions, input.providerData);
+    if (input.metadata) {
+        const entries = Object.entries(input.metadata).slice(0, 5);
+        entries.forEach(([, value], index) => {
+            payload[`Optional${index + 1}`] = value;
+        });
+    }
+    if (input.customer) {
+        const fullName = [input.customer.firstName, input.customer.lastName]
+            .filter(Boolean)
+            .join(" ");
+        if (fullName) {
+            payload.Customer = fullName;
+        }
+        if (input.customer.phone) {
+            payload.CustomerCellphoneNumber = input.customer.phone;
+        }
+    }
+    if (input.urls?.cancelUrl)
+        payload.CancelUrl = input.urls.cancelUrl;
+    if (input.urls?.errorUrl)
+        payload.ErrorUrl = input.urls.errorUrl;
+    if (input.urls?.returnUrl)
+        payload.SuccessUrl = input.urls.returnUrl;
+    if (input.urls?.notifyUrl)
+        payload.NotifyUrl = input.urls.notifyUrl;
+    payload.IsTest = input.testMode ? "true" : "false";
+    if (input.providerData) {
+        for (const [key, value] of Object.entries(input.providerData)) {
+            if (!OZOW_ALLOWED_FIELDS.has(key)) {
+                throw new Error(`Unsupported Ozow field: ${key}`);
+            }
+            if (value === undefined || value === null)
+                continue;
+            if (key === "HashCheck")
+                continue;
+            if (providerOptions && isOzowProviderOptionField(key)) {
+                throw new Error(`providerData overlaps providerOptions: ${key}`);
+            }
+            payload[key] = toStringValue(value);
+        }
+    }
+    return payload;
+}
+function applyOzowProviderOptions(payload, options, providerData) {
+    if (!options)
+        return;
+    for (const fieldKey of Object.values(OZOW_PROVIDER_OPTION_FIELDS)) {
+        if (providerData && fieldKey in providerData) {
+            throw new Error(`providerData overlaps providerOptions: ${fieldKey}`);
+        }
+    }
+    if (options.selectedBankId) {
+        payload.SelectedBankId = options.selectedBankId;
+    }
+    if (options.customerIdentityNumber) {
+        payload.CustomerIdentityNumber = options.customerIdentityNumber;
+    }
+    if (options.allowVariableAmount !== undefined) {
+        payload.AllowVariableAmount = options.allowVariableAmount ? "true" : "false";
+    }
+    if (options.allowVariableAmount) {
+        if (options.variableAmountMin === undefined) {
+            throw new Error("variableAmountMin is required when allowVariableAmount is true");
+        }
+        if (options.variableAmountMax === undefined) {
+            throw new Error("variableAmountMax is required when allowVariableAmount is true");
+        }
+        payload.VariableAmountMin = String(options.variableAmountMin);
+        payload.VariableAmountMax = String(options.variableAmountMax);
+    }
+}
+function isOzowProviderOptionField(fieldKey) {
+    const optionFields = Object.values(OZOW_PROVIDER_OPTION_FIELDS);
+    return optionFields.includes(fieldKey);
+}
+export function buildOzowHashCheck(payload, privateKey) {
+    const parts = [];
+    for (const key of OZOW_ORDER) {
+        if (key === "HashCheck" || key === "Token")
+            continue;
+        if (key === "CustomerCellphoneNumber")
+            continue;
+        if (key === "GenerateShortUrl")
+            continue;
+        const value = payload[key];
+        if (value === undefined || value === null || value === "")
+            continue;
+        if (key === "AllowVariableAmount" &&
+            typeof value === "string" &&
+            value.toLowerCase() === "false") {
+            continue;
+        }
+        parts.push(toStringValue(value));
+    }
+    const concatenated = `${parts.join("")}${privateKey}`.toLowerCase();
+    return sha512Hex(concatenated);
+}
+export async function makeOzowPayment(input) {
+    const apiKey = requireValue(input.secrets.apiKey, "secrets.apiKey");
+    const privateKey = requireValue(input.secrets.privateKey, "secrets.privateKey");
+    const payload = buildOzowPayload(input);
+    payload.HashCheck = buildOzowHashCheck(payload, privateKey);
+    const endpoint = input.testMode ? OZOW_ENDPOINTS.sandbox : OZOW_ENDPOINTS.live;
+    const response = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+            ApiKey: apiKey,
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        },
+        body: JSON.stringify(payload),
+    });
+    const body = await response.json().catch(() => null);
+    if (!response.ok) {
+        const errorMessage = body?.ErrorMessage || body?.errorMessage || response.statusText;
+        throw new Error(`Ozow payment request failed: ${errorMessage}`);
+    }
+    const paymentUrl = body?.PaymentUrl ?? body?.paymentUrl;
+    if (!paymentUrl) {
+        throw new Error("Ozow payment response missing PaymentUrl");
+    }
+    return {
+        provider: "ozow",
+        redirectUrl: paymentUrl,
+        method: "GET",
+        paymentRequestId: body?.PaymentRequestId ?? body?.paymentRequestId,
+        raw: body,
+    };
+}
+export function verifyOzowWebhook(input) {
+    const privateKey = input.secrets.privateKey;
+    if (!privateKey) {
+        return {
+            provider: "ozow",
+            isValid: false,
+            reason: "missingPrivateKey",
+        };
+    }
+    const raw = input.rawBody
+        ? Buffer.isBuffer(input.rawBody)
+            ? input.rawBody.toString("utf8")
+            : input.rawBody
+        : null;
+    const payload = raw
+        ? pairsToRecord(parseFormEncoded(raw))
+        : input.payload
+            ? Object.entries(input.payload).reduce((acc, [key, value]) => {
+                if (value === undefined || value === null)
+                    return acc;
+                acc[key] = toStringValue(value);
+                return acc;
+            }, {})
+            : null;
+    if (!payload) {
+        return {
+            provider: "ozow",
+            isValid: false,
+            reason: "missingPayload",
+        };
+    }
+    const received = payload.HashCheck || payload.hashCheck;
+    if (!received) {
+        return {
+            provider: "ozow",
+            isValid: false,
+            reason: "missingHashCheck",
+        };
+    }
+    const parts = OZOW_RESPONSE_ORDER.map((key) => payload[key] ?? "");
+    const concatenated = `${parts.join("")}${privateKey}`.toLowerCase();
+    const computed = sha512Hex(concatenated);
+    const normalize = (value) => value.replace(/^0+/, "").toLowerCase();
+    return {
+        provider: "ozow",
+        isValid: normalize(received) === normalize(computed),
+    };
+}

package/dist/src/providers/payfast.d.ts

@@ -0,0 +1,4 @@
+import type { PaymentRequest, PaymentResponse, WebhookVerifyInput, WebhookVerifyResult } from "../types.js";
+export declare function buildPayfastSignature(fields: Record<string, string>, passphrase?: string): string;
+export declare function makePayfastPayment(input: PaymentRequest): PaymentResponse;
+export declare function verifyPayfastWebhook(input: WebhookVerifyInput): WebhookVerifyResult;

package/dist/src/providers/payfast.js

@@ -0,0 +1,213 @@
+import { encodePayfastValue } from "../internal/encoding.js";
+import { md5Hex } from "../internal/hash.js";
+import { formatAmount, requireValue, toStringValue } from "../internal/guards.js";
+import { parseFormEncoded, pairsToRecord } from "../internal/form.js";
+const PAYFAST_ORDER = [
+    "merchant_id",
+    "merchant_key",
+    "return_url",
+    "cancel_url",
+    "notify_url",
+    "fica_id_number",
+    "name_first",
+    "name_last",
+    "email_address",
+    "cell_number",
+    "m_payment_id",
+    "amount",
+    "item_name",
+    "item_description",
+    "custom_int1",
+    "custom_int2",
+    "custom_int3",
+    "custom_int4",
+    "custom_int5",
+    "custom_str1",
+    "custom_str2",
+    "custom_str3",
+    "custom_str4",
+    "custom_str5",
+    "email_confirmation",
+    "confirmation_address",
+    "payment_method",
+    "subscription_type",
+    "billing_date",
+    "recurring_amount",
+    "frequency",
+    "cycles",
+    "subscription_notify_email",
+    "subscription_notify_webhook",
+    "subscription_notify_buyer",
+    "setup",
+    "token",
+    "return",
+];
+const PAYFAST_ALLOWED_FIELDS = new Set([...PAYFAST_ORDER, "signature"]);
+const PAYFAST_SIGNATURE_EXCLUSIONS = new Set(["signature", "setup"]);
+const PAYFAST_PROVIDER_OPTION_FIELDS = {
+    paymentMethod: "payment_method",
+    emailConfirmation: "email_confirmation",
+    confirmationAddress: "confirmation_address",
+    mPaymentId: "m_payment_id",
+    itemName: "item_name",
+    itemDescription: "item_description",
+};
+const PAYFAST_ENDPOINTS = {
+    live: "https://www.payfast.co.za/eng/process",
+    sandbox: "https://sandbox.payfast.co.za/eng/process",
+};
+function normalizePayfastFields(input) {
+    const merchantId = requireValue(input.secrets.merchantId, "secrets.merchantId");
+    const merchantKey = requireValue(input.secrets.merchantKey, "secrets.merchantKey");
+    const currency = (input.currency ?? "ZAR").toUpperCase();
+    if (currency !== "ZAR") {
+        throw new Error("Payfast only supports ZAR amounts");
+    }
+    const fields = {
+        merchant_id: merchantId,
+        merchant_key: merchantKey,
+    };
+    if (input.urls?.returnUrl)
+        fields.return_url = input.urls.returnUrl;
+    if (input.urls?.cancelUrl)
+        fields.cancel_url = input.urls.cancelUrl;
+    if (input.urls?.notifyUrl)
+        fields.notify_url = input.urls.notifyUrl;
+    if (input.customer?.firstName)
+        fields.name_first = input.customer.firstName;
+    if (input.customer?.lastName)
+        fields.name_last = input.customer.lastName;
+    if (input.customer?.email)
+        fields.email_address = input.customer.email;
+    if (input.customer?.phone)
+        fields.cell_number = input.customer.phone;
+    fields.amount = formatAmount(input.amount);
+    const providerOptions = input.providerOptions;
+    applyPayfastProviderOptions(fields, providerOptions, input.providerData);
+    if (!fields.m_payment_id) {
+        fields.m_payment_id = input.reference;
+    }
+    if (!fields.item_name) {
+        fields.item_name = input.description ?? input.reference;
+    }
+    if (input.metadata) {
+        const entries = Object.entries(input.metadata).slice(0, 5);
+        entries.forEach(([, value], index) => {
+            fields[`custom_str${index + 1}`] = value;
+        });
+    }
+    if (input.providerData) {
+        for (const [key, value] of Object.entries(input.providerData)) {
+            if (!PAYFAST_ALLOWED_FIELDS.has(key)) {
+                throw new Error(`Unsupported Payfast field: ${key}`);
+            }
+            if (value === undefined || value === null)
+                continue;
+            if (key === "signature")
+                continue;
+            if (providerOptions && isPayfastProviderOptionField(key)) {
+                throw new Error(`providerData overlaps providerOptions: ${key}`);
+            }
+            fields[key] = toStringValue(value);
+        }
+    }
+    return fields;
+}
+function applyPayfastProviderOptions(fields, options, providerData) {
+    if (!options)
+        return;
+    for (const fieldKey of Object.values(PAYFAST_PROVIDER_OPTION_FIELDS)) {
+        if (providerData && fieldKey in providerData) {
+            throw new Error(`providerData overlaps providerOptions: ${fieldKey}`);
+        }
+    }
+    if (options.paymentMethod) {
+        fields.payment_method = options.paymentMethod;
+    }
+    if (options.emailConfirmation !== undefined) {
+        fields.email_confirmation = options.emailConfirmation ? "1" : "0";
+    }
+    if (options.confirmationAddress) {
+        fields.confirmation_address = options.confirmationAddress;
+    }
+    if (options.mPaymentId) {
+        fields.m_payment_id = options.mPaymentId;
+    }
+    if (options.itemName) {
+        fields.item_name = options.itemName;
+    }
+    if (options.itemDescription) {
+        fields.item_description = options.itemDescription;
+    }
+}
+function isPayfastProviderOptionField(fieldKey) {
+    const optionFields = Object.values(PAYFAST_PROVIDER_OPTION_FIELDS);
+    return optionFields.includes(fieldKey);
+}
+export function buildPayfastSignature(fields, passphrase) {
+    const pairs = [];
+    for (const key of PAYFAST_ORDER) {
+        if (PAYFAST_SIGNATURE_EXCLUSIONS.has(key))
+            continue;
+        const value = fields[key];
+        if (value === undefined || value === null || value === "")
+            continue;
+        pairs.push(`${key}=${encodePayfastValue(String(value).trim())}`);
+    }
+    let paramString = pairs.join("&");
+    if (passphrase) {
+        paramString += `&passphrase=${encodePayfastValue(passphrase.trim())}`;
+    }
+    return md5Hex(paramString);
+}
+export function makePayfastPayment(input) {
+    const fields = normalizePayfastFields(input);
+    const signature = buildPayfastSignature(fields, input.secrets.passphrase);
+    fields.signature = signature;
+    return {
+        provider: "payfast",
+        redirectUrl: input.testMode ? PAYFAST_ENDPOINTS.sandbox : PAYFAST_ENDPOINTS.live,
+        method: "POST",
+        formFields: fields,
+    };
+}
+export function verifyPayfastWebhook(input) {
+    const raw = input.rawBody
+        ? Buffer.isBuffer(input.rawBody)
+            ? input.rawBody.toString("utf8")
+            : input.rawBody
+        : null;
+    if (!raw) {
+        return {
+            provider: "payfast",
+            isValid: false,
+            reason: "rawBodyRequired",
+        };
+    }
+    const pairs = parseFormEncoded(raw);
+    const payload = pairsToRecord(pairs);
+    const signature = payload.signature;
+    if (!signature) {
+        return {
+            provider: "payfast",
+            isValid: false,
+            reason: "missingSignature",
+        };
+    }
+    const params = [];
+    for (const [key, value] of pairs) {
+        if (key === "signature") {
+            break;
+        }
+        params.push(`${key}=${encodePayfastValue(value)}`);
+    }
+    let paramString = params.join("&");
+    if (input.secrets.passphrase) {
+        paramString += `&passphrase=${encodePayfastValue(input.secrets.passphrase)}`;
+    }
+    const computed = md5Hex(paramString);
+    return {
+        provider: "payfast",
+        isValid: signature.toLowerCase() === computed.toLowerCase(),
+    };
+}

package/dist/src/providers/paystack.d.ts

@@ -0,0 +1,4 @@
+import type { PaymentRequest, PaymentResponse, VerificationResult } from "../types.js";
+export declare function makePaystackPayment(input: PaymentRequest): Promise<PaymentResponse>;
+export declare function verifyPaystackWebhook(rawBody: string | Buffer, signatureHeader: string | undefined, secretKey: string): boolean;
+export declare function verifyPaystackPayment(reference: string, secretKey: string): Promise<VerificationResult>;

package/dist/src/providers/paystack.js

@@ -0,0 +1,116 @@
+import { createHmac } from "node:crypto";
+import { requireValue } from "../internal/guards.js";
+const PAYSTACK_BASE_URL = "https://api.paystack.co";
+function parseMinorAmount(amount) {
+    const raw = typeof amount === "string" ? amount : String(amount);
+    if (raw.includes(".")) {
+        throw new Error("Paystack amount must be in minor units (integer)");
+    }
+    const value = Number(raw);
+    if (!Number.isInteger(value)) {
+        throw new Error("Paystack amount must be an integer in minor units");
+    }
+    return value;
+}
+function resolvePaystackOptions(input) {
+    return input.providerOptions;
+}
+export async function makePaystackPayment(input) {
+    const secretKey = requireValue(input.secrets.paystackSecretKey, "secrets.paystackSecretKey");
+    const email = input.customer?.email;
+    if (!email) {
+        throw new Error("Paystack requires customer email");
+    }
+    const amount = parseMinorAmount(input.amount);
+    const currency = input.currency ?? "ZAR";
+    const options = resolvePaystackOptions(input);
+    const payload = {
+        email,
+        amount,
+        currency,
+        reference: input.reference,
+    };
+    if (input.urls?.returnUrl) {
+        payload.callback_url = input.urls.returnUrl;
+    }
+    if (options?.channels) {
+        payload.channels = options.channels;
+    }
+    if (input.metadata) {
+        payload.metadata = input.metadata;
+    }
+    if (input.providerData) {
+        if (options?.channels && "channels" in input.providerData) {
+            throw new Error("providerData overlaps providerOptions: channels");
+        }
+        for (const [key, value] of Object.entries(input.providerData)) {
+            if (value === undefined || value === null)
+                continue;
+            if (key in payload) {
+                throw new Error(`providerData overlaps core fields: ${key}`);
+            }
+            payload[key] = value;
+        }
+    }
+    const response = await fetch(`${PAYSTACK_BASE_URL}/transaction/initialize`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${secretKey}`,
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        },
+        body: JSON.stringify(payload),
+    });
+    const body = await response.json().catch(() => null);
+    if (!response.ok || !body?.status) {
+        const message = body?.message || response.statusText;
+        throw new Error(`Paystack initialize failed: ${message}`);
+    }
+    const authUrl = body?.data?.authorization_url;
+    const reference = body?.data?.reference;
+    if (!authUrl || !reference) {
+        throw new Error("Paystack response missing authorization_url or reference");
+    }
+    return {
+        provider: "paystack",
+        redirectUrl: authUrl,
+        method: "GET",
+        paymentRequestId: reference,
+        raw: body,
+    };
+}
+export function verifyPaystackWebhook(rawBody, signatureHeader, secretKey) {
+    if (!signatureHeader) {
+        return false;
+    }
+    const payload = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody);
+    const hash = createHmac("sha512", secretKey).update(payload).digest("hex");
+    return hash === signatureHeader;
+}
+export async function verifyPaystackPayment(reference, secretKey) {
+    const response = await fetch(`${PAYSTACK_BASE_URL}/transaction/verify/${encodeURIComponent(reference)}`, {
+        headers: {
+            Authorization: `Bearer ${secretKey}`,
+            Accept: "application/json",
+        },
+    });
+    const body = await response.json().catch(() => null);
+    if (!response.ok || !body?.status) {
+        const message = body?.message || response.statusText;
+        throw new Error(`Paystack verify failed: ${message}`);
+    }
+    const status = String(body?.data?.status ?? "").toLowerCase();
+    const normalized = status === "success"
+        ? "paid"
+        : status === "failed"
+            ? "failed"
+            : status === "abandoned"
+                ? "pending"
+                : "unknown";
+    return {
+        provider: "paystack",
+        status: normalized,
+        providerRef: body?.data?.id ? String(body.data.id) : undefined,
+        raw: body,
+    };
+}

package/dist/src/providers/provider-adapter.d.ts

@@ -0,0 +1,22 @@
+import type { PaymentRequest, PaymentResponse, VerificationResult, WebhookEvent } from "../types.js";
+export type ProviderWebhookInput = {
+    rawBody: string | Buffer;
+    headers?: Record<string, string | string[] | undefined>;
+    secrets: PaymentRequest["secrets"];
+};
+export type ProviderWebhookResult = {
+    isValid: boolean;
+    event: WebhookEvent;
+    raw: Record<string, unknown>;
+};
+export type ProviderVerifyInput = {
+    reference: string;
+    secrets: PaymentRequest["secrets"];
+    testMode?: boolean;
+};
+export interface ProviderAdapter {
+    id: PaymentRequest["provider"];
+    createPayment(input: PaymentRequest): Promise<PaymentResponse>;
+    parseWebhook(input: ProviderWebhookInput): ProviderWebhookResult;
+    verifyPayment?: (input: ProviderVerifyInput) => Promise<VerificationResult>;
+}

package/dist/src/providers/provider-adapter.js

@@ -0,0 +1 @@
+export {};