@miniduckco/stash 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miniduck Co
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# @miniduck/stash
+
+Integrate payments in under 15 minutes.
+
+## Install
+
+```bash
+npm install @miniduck/stash
+```
+
+## Getting started
+
+Start with the quickstart tutorial: `docs/tutorials/quickstart.md`.
+
+## Docs (Diataxis)
+
+- Tutorials: `docs/tutorials/quickstart.md`
+- How-to guides: `docs/how-to/README.md`
+- Reference: `docs/reference/api.md`
+- Explanation: `docs/explanation/architecture.md`
+- Skills quick reference: `doc/skill.md`
+
+## Examples
+
+Runnable examples live in `examples/`:
+
+- Index: `examples/README.md`
+
+## Site (SvelteKit)
+
+The landing page + docs site lives in `site/` and renders markdown directly from `docs/`.
+
+Local dev:
+
+```bash
+npm install --prefix site
+npm run dev --prefix site -- --host 0.0.0.0 --port 5173
+```
+
+Docker preview:
+
+```bash
+docker build -t stash-site .
+docker run --rm -p 5173:5173 stash-site
+```
+
+## Providers and operations
+
+Providers
+- [x] Ozow
+- [x] Payfast
+- [x] Paystack
+- [ ] Paygate
+- [ ] Peach
+
+Supported operations
+- [x] payments.create
+- [x] payments.verify (Ozow, Paystack; Payfast unsupported)
+- [x] webhooks.parse
+
+Notes:
+- Ozow hash excludes `CustomerCellphoneNumber`, `Token`, and `GenerateShortUrl`.
+- Ozow `AllowVariableAmount=false` is excluded from the hash.
+- Payfast signature excludes `setup` and requires uppercase URL encoding.

package/dist/src/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class StashError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}

package/dist/src/errors.js

@@ -0,0 +1,7 @@
+export class StashError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "StashError";
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,21 @@
+import type { ParsedWebhook, Payment, PaymentCreateInput, PaymentVerifyInput, PaymentRequest, PaymentResponse, StashConfig, VerificationResult, WebhookParseInput, WebhookVerifyInput, WebhookVerifyResult } from "./types.js";
+export type { OzowProviderOptions, ParsedWebhook, Payment, PaymentCreateInput, PaymentProvider, PaymentVerifyInput, PaymentRequest, PaymentResponse, PaystackProviderOptions, PayfastProviderOptions, ProviderOptions, StashConfig, VerificationResult, WebhookEvent, WebhookParseInput, WebhookVerifyInput, WebhookVerifyResult, } from "./types.js";
+export { StashError } from "./errors.js";
+export { buildFormEncoded, parseFormBody, parseFormEncoded, pairsToRecord } from "./internal/form.js";
+export declare function createStash(config: StashConfig): {
+    payments: {
+        create: (input: PaymentCreateInput) => Promise<Payment>;
+        verify: (input: PaymentVerifyInput) => Promise<VerificationResult>;
+    };
+    webhooks: {
+        parse: (input: WebhookParseInput) => ParsedWebhook;
+    };
+};
+/**
+ * @deprecated Use createStash({ provider, credentials }).payments.create instead.
+ */
+export declare function makePayment(input: PaymentRequest): Promise<PaymentResponse>;
+/**
+ * @deprecated Use createStash({ provider, credentials }).webhooks.parse instead.
+ */
+export declare function verifyWebhookSignature(input: WebhookVerifyInput): WebhookVerifyResult;

package/dist/src/index.js

@@ -0,0 +1,160 @@
+import { randomUUID } from "node:crypto";
+import { formatAmount } from "./internal/guards.js";
+import { StashError } from "./errors.js";
+import { providerAdapters } from "./providers/adapters.js";
+import { makeOzowPayment, verifyOzowWebhook } from "./providers/ozow.js";
+import { makePayfastPayment, verifyPayfastWebhook } from "./providers/payfast.js";
+import { makePaystackPayment, verifyPaystackWebhook } from "./providers/paystack.js";
+export { StashError } from "./errors.js";
+export { buildFormEncoded, parseFormBody, parseFormEncoded, pairsToRecord } from "./internal/form.js";
+export function createStash(config) {
+    const provider = config.provider;
+    const testMode = config.testMode ?? false;
+    return {
+        payments: {
+            create: async (input) => {
+                const currency = input.currency ?? config.defaults?.currency ?? "ZAR";
+                const amountNumber = Number(formatAmount(input.amount));
+                const paymentRequest = {
+                    provider,
+                    amount: input.amount,
+                    currency,
+                    reference: input.reference,
+                    description: input.description,
+                    customer: input.customer,
+                    urls: input.urls,
+                    metadata: input.metadata,
+                    providerOptions: input.providerOptions,
+                    providerData: input.providerData,
+                    testMode,
+                    secrets: buildSecrets(provider, config.credentials),
+                };
+                const adapter = providerAdapters[provider];
+                const response = await adapter.createPayment(paymentRequest);
+                return {
+                    id: randomUUID(),
+                    status: "pending",
+                    amount: amountNumber,
+                    currency,
+                    redirectUrl: response.redirectUrl,
+                    provider,
+                    providerRef: response.paymentRequestId,
+                    raw: response.raw ?? response,
+                };
+            },
+            verify: async (input) => {
+                const adapter = providerAdapters[provider];
+                if (!adapter?.verifyPayment) {
+                    throw new StashError("unsupported_capability", `payments.verify is not supported for ${provider}`);
+                }
+                return adapter.verifyPayment({
+                    reference: input.reference,
+                    secrets: buildSecrets(provider, config.credentials),
+                    testMode,
+                });
+            },
+        },
+        webhooks: {
+            parse: (input) => {
+                const resolvedProvider = input.provider ?? provider;
+                const secrets = buildSecrets(resolvedProvider, config.credentials);
+                const rawBody = input.rawBody;
+                const adapter = providerAdapters[resolvedProvider];
+                if (!adapter) {
+                    throw new Error(`Unsupported provider: ${resolvedProvider}`);
+                }
+                const parsed = adapter.parseWebhook({
+                    rawBody,
+                    headers: input.headers,
+                    secrets,
+                });
+                if (!parsed.isValid) {
+                    throw new StashError("invalid_signature", `Invalid ${resolvedProvider} signature`);
+                }
+                return {
+                    event: parsed.event,
+                    provider: resolvedProvider,
+                    raw: parsed.raw,
+                };
+            },
+        },
+    };
+}
+function buildSecrets(provider, credentials) {
+    if (provider === "ozow") {
+        const ozow = credentials;
+        return {
+            siteCode: ozow.siteCode,
+            apiKey: ozow.apiKey,
+            privateKey: ozow.privateKey,
+        };
+    }
+    const payfast = credentials;
+    if (provider === "payfast") {
+        return {
+            merchantId: payfast.merchantId,
+            merchantKey: payfast.merchantKey,
+            passphrase: payfast.passphrase,
+        };
+    }
+    const paystack = credentials;
+    return {
+        paystackSecretKey: paystack.secretKey,
+    };
+}
+/**
+ * @deprecated Use createStash({ provider, credentials }).payments.create instead.
+ */
+export async function makePayment(input) {
+    switch (input.provider) {
+        case "ozow":
+            return makeOzowPayment(input);
+        case "payfast":
+            return makePayfastPayment(input);
+        case "paystack":
+            return makePaystackPayment(input);
+        default:
+            throw new Error(`Unsupported provider: ${input.provider}`);
+    }
+}
+/**
+ * @deprecated Use createStash({ provider, credentials }).webhooks.parse instead.
+ */
+export function verifyWebhookSignature(input) {
+    switch (input.provider) {
+        case "ozow":
+            return verifyOzowWebhook(input);
+        case "payfast":
+            return verifyPayfastWebhook(input);
+        case "paystack": {
+            const signature = resolveHeader(input.headers, "x-paystack-signature");
+            const secretKey = input.secrets.paystackSecretKey;
+            if (!input.rawBody || !secretKey) {
+                return {
+                    provider: "paystack",
+                    isValid: false,
+                    reason: "missingPayload",
+                };
+            }
+            return {
+                provider: "paystack",
+                isValid: verifyPaystackWebhook(input.rawBody, signature, secretKey),
+            };
+        }
+        default:
+            throw new Error(`Unsupported provider: ${input.provider}`);
+    }
+}
+function resolveHeader(headers, key) {
+    if (!headers)
+        return undefined;
+    const lowerKey = key.toLowerCase();
+    for (const [headerKey, value] of Object.entries(headers)) {
+        if (headerKey.toLowerCase() !== lowerKey)
+            continue;
+        if (Array.isArray(value))
+            return value[0];
+        return value;
+    }
+    return undefined;
+}

package/dist/src/internal/encoding.d.ts

@@ -0,0 +1,2 @@
+export declare function encodePayfastValue(value: string): string;
+export declare function decodeFormComponent(value: string): string;

package/dist/src/internal/encoding.js

@@ -0,0 +1,10 @@
+export function encodePayfastValue(value) {
+    const encoded = encodeURIComponent(value)
+        .replace(/%[0-9a-f]{2}/gi, (match) => match.toUpperCase())
+        .replace(/%20/g, "+");
+    return encoded;
+}
+export function decodeFormComponent(value) {
+    const replaced = value.replace(/\+/g, " ");
+    return decodeURIComponent(replaced);
+}

package/dist/src/internal/form.d.ts

@@ -0,0 +1,5 @@
+export type FormPair = [string, string];
+export declare function parseFormEncoded(raw: string): FormPair[];
+export declare function pairsToRecord(pairs: FormPair[]): Record<string, string>;
+export declare function parseFormBody(rawBody: string | Buffer): FormPair[];
+export declare function buildFormEncoded(payload: Record<string, string | number | boolean | null | undefined>): string;

package/dist/src/internal/form.js

@@ -0,0 +1,40 @@
+import { decodeFormComponent } from "./encoding.js";
+function encodeFormComponent(value) {
+    return encodeURIComponent(value).replace(/%20/g, "+");
+}
+export function parseFormEncoded(raw) {
+    if (!raw) {
+        return [];
+    }
+    return raw
+        .split("&")
+        .filter((pair) => pair.length > 0)
+        .map((pair) => {
+        const index = pair.indexOf("=");
+        if (index === -1) {
+            return [decodeFormComponent(pair), ""];
+        }
+        const key = pair.slice(0, index);
+        const value = pair.slice(index + 1);
+        return [decodeFormComponent(key), decodeFormComponent(value)];
+    });
+}
+export function pairsToRecord(pairs) {
+    return pairs.reduce((acc, [key, value]) => {
+        acc[key] = value;
+        return acc;
+    }, {});
+}
+export function parseFormBody(rawBody) {
+    const text = Buffer.isBuffer(rawBody) ? rawBody.toString("utf8") : rawBody;
+    return parseFormEncoded(text);
+}
+export function buildFormEncoded(payload) {
+    const pairs = [];
+    for (const [key, value] of Object.entries(payload)) {
+        if (value === undefined || value === null)
+            continue;
+        pairs.push(`${encodeFormComponent(key)}=${encodeFormComponent(String(value))}`);
+    }
+    return pairs.join("&");
+}

package/dist/src/internal/guards.d.ts

@@ -0,0 +1,3 @@
+export declare function requireValue<T>(value: T | undefined | null, name: string): T;
+export declare function formatAmount(value: string | number): string;
+export declare function toStringValue(value: string | number | boolean): string;

package/dist/src/internal/guards.js

@@ -0,0 +1,19 @@
+export function requireValue(value, name) {
+    if (value === undefined || value === null || value === "") {
+        throw new Error(`Missing required value: ${name}`);
+    }
+    return value;
+}
+export function formatAmount(value) {
+    const numeric = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(numeric)) {
+        throw new Error("Amount must be a valid number");
+    }
+    return numeric.toFixed(2);
+}
+export function toStringValue(value) {
+    if (typeof value === "boolean") {
+        return value ? "true" : "false";
+    }
+    return String(value);
+}

package/dist/src/internal/hash.d.ts

@@ -0,0 +1,2 @@
+export declare function sha512Hex(input: string): string;
+export declare function md5Hex(input: string): string;

package/dist/src/internal/hash.js

@@ -0,0 +1,7 @@
+import { createHash } from "node:crypto";
+export function sha512Hex(input) {
+    return createHash("sha512").update(input).digest("hex");
+}
+export function md5Hex(input) {
+    return createHash("md5").update(input).digest("hex");
+}

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

@@ -0,0 +1,6 @@
+import type { PaymentRequest } from "../types.js";
+import type { ProviderAdapter } from "./provider-adapter.js";
+export declare const ozowAdapter: ProviderAdapter;
+export declare const payfastAdapter: ProviderAdapter;
+export declare const paystackAdapter: ProviderAdapter;
+export declare const providerAdapters: Record<PaymentRequest["provider"], ProviderAdapter>;

package/dist/src/providers/adapters.js

@@ -0,0 +1,198 @@
+import { pairsToRecord, parseFormEncoded } from "../internal/form.js";
+import { makeOzowPayment, verifyOzowWebhook } from "./ozow.js";
+import { makePayfastPayment, verifyPayfastWebhook } from "./payfast.js";
+import { makePaystackPayment, verifyPaystackPayment, verifyPaystackWebhook } from "./paystack.js";
+function parseWebhookPayload(rawBody) {
+    const raw = Buffer.isBuffer(rawBody) ? rawBody.toString("utf8") : rawBody;
+    return pairsToRecord(parseFormEncoded(raw));
+}
+function mapPayfastEvent(payload) {
+    const status = (payload.payment_status ?? "").toUpperCase();
+    const type = status === "COMPLETE"
+        ? "payment.completed"
+        : status === "CANCELLED"
+            ? "payment.cancelled"
+            : "payment.failed";
+    return {
+        type,
+        data: {
+            provider: "payfast",
+            reference: payload.m_payment_id ?? "",
+            providerRef: payload.pf_payment_id,
+            amount: payload.amount_gross ? Number(payload.amount_gross) : undefined,
+            currency: payload.amount_gross ? "ZAR" : undefined,
+            raw: payload,
+        },
+    };
+}
+function mapOzowEvent(payload) {
+    const status = (payload.Status ?? "").toLowerCase();
+    const type = status === "complete"
+        ? "payment.completed"
+        : status === "cancelled"
+            ? "payment.cancelled"
+            : "payment.failed";
+    return {
+        type,
+        data: {
+            provider: "ozow",
+            reference: payload.TransactionReference ?? "",
+            providerRef: payload.TransactionId,
+            amount: payload.Amount ? Number(payload.Amount) : undefined,
+            currency: payload.CurrencyCode,
+            raw: payload,
+        },
+    };
+}
+function parsePayfastWebhook(input) {
+    const verified = verifyPayfastWebhook({
+        provider: "payfast",
+        rawBody: input.rawBody,
+        headers: input.headers,
+        secrets: {
+            passphrase: input.secrets.passphrase,
+        },
+    });
+    const payload = parseWebhookPayload(input.rawBody);
+    return {
+        isValid: verified.isValid,
+        event: mapPayfastEvent(payload),
+        raw: payload,
+    };
+}
+function parseOzowWebhook(input) {
+    const verified = verifyOzowWebhook({
+        provider: "ozow",
+        rawBody: input.rawBody,
+        headers: input.headers,
+        secrets: {
+            privateKey: input.secrets.privateKey,
+        },
+    });
+    const payload = parseWebhookPayload(input.rawBody);
+    return {
+        isValid: verified.isValid,
+        event: mapOzowEvent(payload),
+        raw: payload,
+    };
+}
+function parsePaystackWebhook(input) {
+    const signature = resolveHeader(input.headers, "x-paystack-signature");
+    const secretKey = input.secrets.paystackSecretKey ?? "";
+    const isValid = verifyPaystackWebhook(input.rawBody, signature, secretKey);
+    const rawText = Buffer.isBuffer(input.rawBody)
+        ? input.rawBody.toString("utf8")
+        : input.rawBody;
+    const payload = JSON.parse(rawText);
+    const event = mapPaystackEvent(payload);
+    return {
+        isValid,
+        event,
+        raw: payload,
+    };
+}
+function mapPaystackEvent(payload) {
+    const eventType = String(payload.event ?? "").toLowerCase();
+    const type = eventType === "charge.success" ? "payment.completed" : "payment.failed";
+    const data = payload.data ?? {};
+    return {
+        type,
+        data: {
+            provider: "paystack",
+            reference: String(data.reference ?? ""),
+            providerRef: data.id
+                ? String(data.id)
+                : undefined,
+            amount: data.amount
+                ? Number(data.amount)
+                : undefined,
+            currency: data.currency
+                ? String(data.currency)
+                : undefined,
+            raw: payload,
+        },
+    };
+}
+function resolveHeader(headers, key) {
+    if (!headers)
+        return undefined;
+    const lowerKey = key.toLowerCase();
+    for (const [headerKey, value] of Object.entries(headers)) {
+        if (headerKey.toLowerCase() !== lowerKey)
+            continue;
+        if (Array.isArray(value))
+            return value[0];
+        return value;
+    }
+    return undefined;
+}
+async function verifyOzowPaymentByReference(input) {
+    const siteCode = input.secrets.siteCode;
+    const apiKey = input.secrets.apiKey;
+    if (!siteCode || !apiKey) {
+        throw new Error("Ozow credentials missing for verification");
+    }
+    const baseUrl = input.testMode
+        ? "https://stagingapi.ozow.com"
+        : "https://api.ozow.com";
+    const url = new URL(`${baseUrl}/GetTransactionByReference`);
+    url.searchParams.set("siteCode", siteCode);
+    url.searchParams.set("transactionReference", input.reference);
+    if (input.testMode) {
+        url.searchParams.set("isTest", "true");
+    }
+    const response = await fetch(url.toString(), {
+        headers: {
+            ApiKey: apiKey,
+            Accept: "application/json",
+        },
+    });
+    const body = await response.json().catch(() => null);
+    if (!response.ok) {
+        throw new Error(`Ozow verify failed: ${response.statusText}`);
+    }
+    const transaction = Array.isArray(body) ? body[0] : null;
+    const statusRaw = String(transaction?.Status ?? "").toLowerCase();
+    const status = statusRaw === "complete"
+        ? "paid"
+        : statusRaw === "cancelled" || statusRaw === "error"
+            ? "failed"
+            : statusRaw
+                ? "pending"
+                : "unknown";
+    return {
+        provider: "ozow",
+        status,
+        providerRef: transaction?.TransactionId,
+        raw: body,
+    };
+}
+async function verifyPaystackPaymentByReference(input) {
+    const secretKey = input.secrets.paystackSecretKey;
+    if (!secretKey) {
+        throw new Error("Paystack secret key missing for verification");
+    }
+    return verifyPaystackPayment(input.reference, secretKey);
+}
+export const ozowAdapter = {
+    id: "ozow",
+    createPayment: async (input) => makeOzowPayment(input),
+    parseWebhook: (input) => parseOzowWebhook(input),
+    verifyPayment: (input) => verifyOzowPaymentByReference(input),
+};
+export const payfastAdapter = {
+    id: "payfast",
+    createPayment: async (input) => makePayfastPayment(input),
+    parseWebhook: (input) => parsePayfastWebhook(input),
+};
+export const paystackAdapter = {
+    id: "paystack",
+    createPayment: async (input) => makePaystackPayment(input),
+    parseWebhook: (input) => parsePaystackWebhook(input),
+    verifyPayment: (input) => verifyPaystackPaymentByReference(input),
+};
+export const providerAdapters = {
+    ozow: ozowAdapter,
+    payfast: payfastAdapter,
+    paystack: paystackAdapter,
+};

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

@@ -0,0 +1,4 @@
+import type { PaymentRequest, PaymentResponse, WebhookVerifyInput, WebhookVerifyResult } from "../types.js";
+export declare function buildOzowHashCheck(payload: Record<string, string>, privateKey: string): string;
+export declare function makeOzowPayment(input: PaymentRequest): Promise<PaymentResponse>;
+export declare function verifyOzowWebhook(input: WebhookVerifyInput): WebhookVerifyResult;