@miniduckco/stash 0.1.1

package/dist/src/types.d.ts

@@ -0,0 +1,159 @@
+export type PaymentProvider = "ozow" | "payfast" | "paystack";
+export type PayfastProviderOptions = {
+    paymentMethod?: string;
+    emailConfirmation?: boolean;
+    confirmationAddress?: string;
+    mPaymentId?: string;
+    itemName?: string;
+    itemDescription?: string;
+};
+export type PaystackProviderOptions = {
+    channels?: string[];
+};
+export type OzowProviderOptions = {
+    selectedBankId?: string;
+    customerIdentityNumber?: string;
+    allowVariableAmount?: boolean;
+    variableAmountMin?: number;
+    variableAmountMax?: number;
+};
+export type ProviderOptions = PayfastProviderOptions | OzowProviderOptions | PaystackProviderOptions;
+export type OzowCredentials = {
+    siteCode: string;
+    apiKey: string;
+    privateKey: string;
+};
+export type PayfastCredentials = {
+    merchantId: string;
+    merchantKey: string;
+    passphrase?: string;
+};
+export type PaystackCredentials = {
+    secretKey: string;
+};
+export type StashConfig = {
+    provider: PaymentProvider;
+    credentials: OzowCredentials | PayfastCredentials | PaystackCredentials;
+    testMode?: boolean;
+    defaults?: {
+        currency?: string;
+    };
+};
+export type PaymentCreateInput = {
+    amount: string | number;
+    currency?: "ZAR" | string;
+    reference: string;
+    description?: string;
+    customer?: {
+        firstName?: string;
+        lastName?: string;
+        email?: string;
+        phone?: string;
+    };
+    urls?: {
+        returnUrl?: string;
+        cancelUrl?: string;
+        notifyUrl?: string;
+        errorUrl?: string;
+    };
+    metadata?: Record<string, string>;
+    providerOptions?: ProviderOptions;
+    providerData?: Record<string, string | number | boolean | null | undefined>;
+};
+export type Payment = {
+    id: string;
+    status: "pending" | "paid" | "failed";
+    amount: number;
+    currency: string;
+    redirectUrl?: string;
+    provider: PaymentProvider;
+    providerRef?: string;
+    raw?: unknown;
+};
+export type PaymentVerifyInput = {
+    reference: string;
+};
+export type VerificationResult = {
+    provider: PaymentProvider;
+    status: "pending" | "paid" | "failed" | "unknown";
+    providerRef?: string;
+    raw?: unknown;
+};
+export type WebhookEvent = {
+    type: "payment.completed" | "payment.failed" | "payment.cancelled";
+    data: {
+        id?: string;
+        providerRef?: string;
+        reference: string;
+        amount?: number;
+        currency?: string;
+        provider: PaymentProvider;
+        raw: unknown;
+    };
+};
+export type WebhookParseInput = {
+    provider?: PaymentProvider;
+    rawBody: string | Buffer;
+    headers?: Record<string, string | string[] | undefined>;
+};
+export type ParsedWebhook = {
+    event: WebhookEvent;
+    provider: PaymentProvider;
+    raw: Record<string, unknown>;
+};
+export type PaymentRequest = {
+    provider: PaymentProvider;
+    amount: string | number;
+    currency?: "ZAR" | string;
+    reference: string;
+    description?: string;
+    customer?: {
+        firstName?: string;
+        lastName?: string;
+        email?: string;
+        phone?: string;
+    };
+    urls?: {
+        returnUrl?: string;
+        cancelUrl?: string;
+        notifyUrl?: string;
+        errorUrl?: string;
+    };
+    metadata?: Record<string, string>;
+    secrets: {
+        siteCode?: string;
+        apiKey?: string;
+        privateKey?: string;
+        merchantId?: string;
+        merchantKey?: string;
+        passphrase?: string;
+        paystackSecretKey?: string;
+    };
+    providerOptions?: ProviderOptions;
+    testMode?: boolean;
+    providerData?: Record<string, string | number | boolean | null | undefined>;
+};
+export type PaymentResponse = {
+    provider: PaymentProvider;
+    redirectUrl: string;
+    method: "GET" | "POST";
+    formFields?: Record<string, string>;
+    paymentRequestId?: string;
+    raw?: unknown;
+};
+export type WebhookVerifyInput = {
+    provider: PaymentProvider;
+    rawBody?: string | Buffer;
+    payload?: Record<string, string | number | boolean | null | undefined>;
+    headers?: Record<string, string | string[] | undefined>;
+    secrets: {
+        privateKey?: string;
+        passphrase?: string;
+        paystackSecretKey?: string;
+    };
+};
+export type WebhookVerifyResult = {
+    provider: PaymentProvider;
+    isValid: boolean;
+    reason?: string;
+};

package/dist/src/types.js

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

package/dist/test/ozow.test.d.ts

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

package/dist/test/ozow.test.js

@@ -0,0 +1,112 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { test } from "node:test";
+import { buildOzowHashCheck, makeOzowPayment, verifyOzowWebhook, } from "../src/providers/ozow.js";
+test("buildOzowHashCheck excludes cellphone and allowVariableAmount false", () => {
+    const payload = {
+        SiteCode: "TSTSTE0001",
+        CountryCode: "ZA",
+        CurrencyCode: "ZAR",
+        Amount: "25.00",
+        TransactionReference: "123",
+        BankReference: "ABC123",
+        CancelUrl: "http://demo.ozow.com/cancel.aspx",
+        ErrorUrl: "http://demo.ozow.com/error.aspx",
+        SuccessUrl: "http://demo.ozow.com/success.aspx",
+        NotifyUrl: "http://demo.ozow.com/notify.aspx",
+        IsTest: "false",
+        AllowVariableAmount: "false",
+        CustomerCellphoneNumber: "0821234567",
+    };
+    const privateKey = "private-key";
+    const expectedString = "TSTSTE0001" +
+        "ZA" +
+        "ZAR" +
+        "25.00" +
+        "123" +
+        "ABC123" +
+        "http://demo.ozow.com/cancel.aspx" +
+        "http://demo.ozow.com/error.aspx" +
+        "http://demo.ozow.com/success.aspx" +
+        "http://demo.ozow.com/notify.aspx" +
+        "false" +
+        privateKey;
+    const expectedHash = createHash("sha512")
+        .update(expectedString.toLowerCase())
+        .digest("hex");
+    assert.equal(buildOzowHashCheck(payload, privateKey), expectedHash);
+});
+test("verifyOzowWebhook validates response hash", () => {
+    const privateKey = "private-key";
+    const payload = {
+        SiteCode: "TSTSTE0001",
+        TransactionId: "33857766-f29a-4a3a-a37e-66db3c42e439",
+        TransactionReference: "ORDER-1",
+        Amount: "25.00",
+        Status: "Complete",
+        Optional1: "",
+        Optional2: "",
+        Optional3: "",
+        Optional4: "",
+        Optional5: "",
+        CurrencyCode: "ZAR",
+        IsTest: "true",
+        StatusMessage: "Payment successful",
+    };
+    const concatenated = payload.SiteCode +
+        payload.TransactionId +
+        payload.TransactionReference +
+        payload.Amount +
+        payload.Status +
+        payload.Optional1 +
+        payload.Optional2 +
+        payload.Optional3 +
+        payload.Optional4 +
+        payload.Optional5 +
+        payload.CurrencyCode +
+        payload.IsTest +
+        payload.StatusMessage +
+        privateKey;
+    const hash = createHash("sha512")
+        .update(concatenated.toLowerCase())
+        .digest("hex");
+    const result = verifyOzowWebhook({
+        provider: "ozow",
+        payload: { ...payload, HashCheck: hash },
+        secrets: { privateKey },
+    });
+    assert.equal(result.isValid, true);
+});
+test("makeOzowPayment requires variable amount bounds", async () => {
+    await assert.rejects(() => makeOzowPayment({
+        provider: "ozow",
+        amount: "10.00",
+        reference: "ORDER-1",
+        secrets: {
+            siteCode: "SITE",
+            apiKey: "API",
+            privateKey: "PRIVATE",
+        },
+        providerOptions: {
+            allowVariableAmount: true,
+        },
+    }), /variableAmountMin is required/);
+});
+test("makeOzowPayment rejects providerData overlap", async () => {
+    await assert.rejects(() => makeOzowPayment({
+        provider: "ozow",
+        amount: "10.00",
+        reference: "ORDER-2",
+        secrets: {
+            siteCode: "SITE",
+            apiKey: "API",
+            privateKey: "PRIVATE",
+        },
+        providerOptions: {
+            selectedBankId: "BANK",
+        },
+        providerData: {
+            SelectedBankId: "OTHER",
+        },
+    }), /providerData overlaps providerOptions/);
+});

package/dist/test/payfast.test.d.ts

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

package/dist/test/payfast.test.js

@@ -0,0 +1,80 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { test } from "node:test";
+import { encodePayfastValue } from "../src/internal/encoding.js";
+import { makePayfastPayment, verifyPayfastWebhook } from "../src/providers/payfast.js";
+test("encodePayfastValue uses uppercase hex and plus for spaces", () => {
+    const value = "http://example.com/a b";
+    assert.equal(encodePayfastValue(value), "http%3A%2F%2Fexample.com%2Fa+b");
+});
+test("verifyPayfastWebhook validates ITN signature", () => {
+    const pairs = [
+        ["m_payment_id", "ORDER-100"],
+        ["pf_payment_id", "1089250"],
+        ["payment_status", "COMPLETE"],
+        ["item_name", "Test product"],
+        ["amount_gross", "200.00"],
+        ["merchant_id", "10000100"],
+    ];
+    const paramString = pairs
+        .map(([key, value]) => `${key}=${encodePayfastValue(value)}`)
+        .join("&");
+    const passphrase = "test-pass";
+    const signature = createHash("md5")
+        .update(`${paramString}&passphrase=${encodePayfastValue(passphrase)}`)
+        .digest("hex");
+    const rawBody = `${pairs
+        .map(([key, value]) => `${key}=${encodePayfastValue(value)}`)
+        .join("&")}&signature=${signature}`;
+    const result = verifyPayfastWebhook({
+        provider: "payfast",
+        rawBody,
+        secrets: { passphrase },
+    });
+    assert.equal(result.isValid, true);
+});
+test("makePayfastPayment maps providerOptions", () => {
+    const payment = makePayfastPayment({
+        provider: "payfast",
+        amount: "100.00",
+        reference: "ORDER-1",
+        description: "Order #1",
+        secrets: {
+            merchantId: "merchant",
+            merchantKey: "key",
+        },
+        providerOptions: {
+            paymentMethod: "cc",
+            emailConfirmation: true,
+            confirmationAddress: "ops@example.com",
+            mPaymentId: "MP-1",
+            itemName: "Custom Item",
+            itemDescription: "Custom Desc",
+        },
+    });
+    assert.equal(payment.formFields?.payment_method, "cc");
+    assert.equal(payment.formFields?.email_confirmation, "1");
+    assert.equal(payment.formFields?.confirmation_address, "ops@example.com");
+    assert.equal(payment.formFields?.m_payment_id, "MP-1");
+    assert.equal(payment.formFields?.item_name, "Custom Item");
+    assert.equal(payment.formFields?.item_description, "Custom Desc");
+});
+test("makePayfastPayment rejects providerData overlap", () => {
+    assert.throws(() => {
+        makePayfastPayment({
+            provider: "payfast",
+            amount: "100.00",
+            reference: "ORDER-2",
+            secrets: {
+                merchantId: "merchant",
+                merchantKey: "key",
+            },
+            providerOptions: {
+                paymentMethod: "cc",
+            },
+            providerData: {
+                payment_method: "dc",
+            },
+        });
+    }, /providerData overlaps providerOptions/);
+});

package/dist/test/stash.test.d.ts

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

package/dist/test/stash.test.js

@@ -0,0 +1,209 @@
+import assert from "node:assert/strict";
+import { createHash, createHmac } from "node:crypto";
+import { test } from "node:test";
+import { createStash } from "../src/index.js";
+import { encodePayfastValue } from "../src/internal/encoding.js";
+test("createStash payments.create returns canonical payment", async () => {
+    const stash = createStash({
+        provider: "payfast",
+        credentials: {
+            merchantId: "merchant",
+            merchantKey: "key",
+        },
+        testMode: true,
+    });
+    const payment = await stash.payments.create({
+        amount: "100.00",
+        currency: "ZAR",
+        reference: "ORDER-1",
+    });
+    assert.equal(payment.status, "pending");
+    assert.equal(payment.currency, "ZAR");
+    assert.equal(payment.provider, "payfast");
+    assert.match(payment.id, /^[0-9a-f-]{36}$/i);
+    assert.ok(payment.redirectUrl);
+});
+test("createStash payments.create maps ozow response", async () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = (async () => {
+        return {
+            ok: true,
+            json: async () => ({
+                PaymentUrl: "https://pay.ozow.com/123",
+                PaymentRequestId: "REQ-1",
+            }),
+        };
+    });
+    const stash = createStash({
+        provider: "ozow",
+        credentials: {
+            siteCode: "SITE",
+            apiKey: "API",
+            privateKey: "PRIVATE",
+        },
+    });
+    const payment = await stash.payments.create({
+        amount: "10.00",
+        reference: "ORDER-2",
+    });
+    assert.equal(payment.provider, "ozow");
+    assert.equal(payment.providerRef, "REQ-1");
+    assert.equal(payment.redirectUrl, "https://pay.ozow.com/123");
+    globalThis.fetch = originalFetch;
+});
+test("createStash payments.create maps paystack response", async () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = (async () => {
+        return {
+            ok: true,
+            json: async () => ({
+                status: true,
+                data: {
+                    authorization_url: "https://checkout.paystack.com/abc",
+                    reference: "REF-1",
+                },
+            }),
+        };
+    });
+    const stash = createStash({
+        provider: "paystack",
+        credentials: {
+            secretKey: "sk_test",
+        },
+    });
+    const payment = await stash.payments.create({
+        amount: 2500,
+        reference: "REF-1",
+        customer: {
+            email: "buyer@example.com",
+        },
+    });
+    assert.equal(payment.provider, "paystack");
+    assert.equal(payment.providerRef, "REF-1");
+    assert.equal(payment.redirectUrl, "https://checkout.paystack.com/abc");
+    globalThis.fetch = originalFetch;
+});
+test("createStash payments.create rejects paystack major units", async () => {
+    const stash = createStash({
+        provider: "paystack",
+        credentials: {
+            secretKey: "sk_test",
+        },
+    });
+    await assert.rejects(() => stash.payments.create({
+        amount: "10.00",
+        reference: "REF-2",
+        customer: {
+            email: "buyer@example.com",
+        },
+    }), /minor units/);
+});
+test("webhooks.parse returns canonical event for payfast", () => {
+    const stash = createStash({
+        provider: "payfast",
+        credentials: {
+            merchantId: "merchant",
+            merchantKey: "key",
+            passphrase: "test-pass",
+        },
+    });
+    const pairs = [
+        ["m_payment_id", "ORDER-100"],
+        ["pf_payment_id", "1089250"],
+        ["payment_status", "COMPLETE"],
+        ["amount_gross", "200.00"],
+        ["merchant_id", "10000100"],
+    ];
+    const paramString = pairs
+        .map(([key, value]) => `${key}=${encodePayfastValue(value)}`)
+        .join("&");
+    const signature = createHash("md5")
+        .update(`${paramString}&passphrase=${encodePayfastValue("test-pass")}`)
+        .digest("hex");
+    const rawBody = `${pairs
+        .map(([key, value]) => `${key}=${encodePayfastValue(value)}`)
+        .join("&")}&signature=${signature}`;
+    const parsed = stash.webhooks.parse({ rawBody });
+    assert.equal(parsed.event.type, "payment.completed");
+    assert.equal(parsed.event.data.reference, "ORDER-100");
+    assert.equal(parsed.provider, "payfast");
+});
+test("webhooks.parse throws invalid_signature for payfast", () => {
+    const stash = createStash({
+        provider: "payfast",
+        credentials: {
+            merchantId: "merchant",
+            merchantKey: "key",
+            passphrase: "test-pass",
+        },
+    });
+    const rawBody = "payment_status=COMPLETE";
+    assert.throws(() => stash.webhooks.parse({ rawBody }), (error) => {
+        const stashError = error;
+        return stashError.code === "invalid_signature";
+    });
+});
+test("webhooks.parse returns canonical event for paystack", () => {
+    const stash = createStash({
+        provider: "paystack",
+        credentials: {
+            secretKey: "sk_test",
+        },
+    });
+    const payload = {
+        event: "charge.success",
+        data: {
+            reference: "REF-3",
+            id: 555,
+            amount: 2500,
+            currency: "ZAR",
+        },
+    };
+    const rawBody = JSON.stringify(payload);
+    const signature = createHmac("sha512", "sk_test")
+        .update(rawBody, "utf8")
+        .digest("hex");
+    const parsed = stash.webhooks.parse({
+        rawBody,
+        headers: {
+            "x-paystack-signature": signature,
+        },
+    });
+    assert.equal(parsed.provider, "paystack");
+    assert.equal(parsed.event.type, "payment.completed");
+    assert.equal(parsed.event.data.reference, "REF-3");
+});
+test("payments.verify throws unsupported_capability for payfast", async () => {
+    const stash = createStash({
+        provider: "payfast",
+        credentials: {
+            merchantId: "merchant",
+            merchantKey: "key",
+        },
+    });
+    await assert.rejects(() => stash.payments.verify({ reference: "ORDER-1" }), (error) => error.code === "unsupported_capability");
+});
+test("payments.verify returns paid for paystack", async () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = (async () => {
+        return {
+            ok: true,
+            json: async () => ({
+                status: true,
+                data: {
+                    status: "success",
+                    id: 123,
+                },
+            }),
+        };
+    });
+    const stash = createStash({
+        provider: "paystack",
+        credentials: {
+            secretKey: "sk_test",
+        },
+    });
+    const result = await stash.payments.verify({ reference: "REF-1" });
+    assert.equal(result.status, "paid");
+    globalThis.fetch = originalFetch;
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@miniduckco/stash",
+  "version": "0.1.1",
+  "description": "integrate payments. switch once.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.4.5"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\" && npm run build && node --test dist/test/*.test.js",
+    "site:dev": "npm run dev --prefix site -- --host 0.0.0.0 --port 5173",
+    "site:build": "npm run build --prefix site",
+    "site:preview": "npm run preview --prefix site"
+  }
+}