@miniduckco/stash 0.1.1 → 0.1.2

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 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 type { OzowProviderOptions, ParsedWebhook, LogEvent, Logger, 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): {

package/dist/src/index.js

@@ -10,11 +10,36 @@ export { buildFormEncoded, parseFormBody, parseFormEncoded, pairsToRecord } from
 export function createStash(config) {
     const provider = config.provider;
     const testMode = config.testMode ?? false;
+    const logger = config.logger;
+    const emit = (event) => {
+        if (!logger)
+            return;
+        logger.log({
+            timestamp: new Date().toISOString(),
+            ...event,
+        });
+    };
     return {
         payments: {
             create: async (input) => {
+                const correlationId = randomUUID();
+                const startedAt = Date.now();
                 const currency = input.currency ?? config.defaults?.currency ?? "ZAR";
                 const amountNumber = Number(formatAmount(input.amount));
+                emit({
+                    event: "payments.create.request",
+                    provider,
+                    action: "create",
+                    stage: "request",
+                    correlation_id: correlationId,
+                    status: "success",
+                    metadata: {
+                        amount: input.amount,
+                        currency,
+                        reference: input.reference,
+                        testMode,
+                    },
+                });
                 const paymentRequest = {
                     provider,
                     amount: input.amount,
@@ -30,38 +55,183 @@ export function createStash(config) {
                     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,
-                };
+                try {
+                    const response = await adapter.createPayment(paymentRequest);
+                    const payment = {
+                        id: randomUUID(),
+                        status: "pending",
+                        amount: amountNumber,
+                        currency,
+                        redirectUrl: response.redirectUrl,
+                        provider,
+                        providerRef: response.paymentRequestId,
+                        correlationId,
+                        raw: response.raw ?? response,
+                    };
+                    emit({
+                        event: "payments.create.response",
+                        provider,
+                        action: "create",
+                        stage: "response",
+                        correlation_id: correlationId,
+                        status: "success",
+                        duration_ms: Date.now() - startedAt,
+                        metadata: {
+                            amount: amountNumber,
+                            currency,
+                            reference: input.reference,
+                            provider_ref: response.paymentRequestId,
+                            testMode,
+                        },
+                    });
+                    return payment;
+                }
+                catch (error) {
+                    emit({
+                        event: "payments.create.error",
+                        provider,
+                        action: "create",
+                        stage: "error",
+                        correlation_id: correlationId,
+                        status: "failure",
+                        duration_ms: Date.now() - startedAt,
+                        metadata: {
+                            amount: input.amount,
+                            currency,
+                            reference: input.reference,
+                            testMode,
+                        },
+                        error: {
+                            code: error instanceof StashError ? error.code : "unknown",
+                            message: error instanceof Error ? error.message : "Unknown error",
+                        },
+                    });
+                    throw error;
+                }
             },
             verify: async (input) => {
+                const correlationId = randomUUID();
+                const startedAt = Date.now();
+                emit({
+                    event: "payments.verify.request",
+                    provider,
+                    action: "verify",
+                    stage: "request",
+                    correlation_id: correlationId,
+                    status: "success",
+                    metadata: {
+                        reference: input.reference,
+                        testMode,
+                    },
+                });
                 const adapter = providerAdapters[provider];
                 if (!adapter?.verifyPayment) {
-                    throw new StashError("unsupported_capability", `payments.verify is not supported for ${provider}`);
+                    const error = new StashError("unsupported_capability", `payments.verify is not supported for ${provider}`);
+                    emit({
+                        event: "payments.verify.error",
+                        provider,
+                        action: "verify",
+                        stage: "error",
+                        correlation_id: correlationId,
+                        status: "failure",
+                        duration_ms: Date.now() - startedAt,
+                        metadata: {
+                            reference: input.reference,
+                            testMode,
+                        },
+                        error: {
+                            code: error.code,
+                            message: error.message,
+                        },
+                    });
+                    throw error;
+                }
+                try {
+                    const result = await adapter.verifyPayment({
+                        reference: input.reference,
+                        secrets: buildSecrets(provider, config.credentials),
+                        testMode,
+                    });
+                    const enriched = {
+                        ...result,
+                        correlationId,
+                    };
+                    emit({
+                        event: "payments.verify.response",
+                        provider,
+                        action: "verify",
+                        stage: "response",
+                        correlation_id: correlationId,
+                        status: "success",
+                        duration_ms: Date.now() - startedAt,
+                        metadata: {
+                            reference: input.reference,
+                            provider_ref: result.providerRef,
+                            testMode,
+                        },
+                    });
+                    return enriched;
+                }
+                catch (error) {
+                    emit({
+                        event: "payments.verify.error",
+                        provider,
+                        action: "verify",
+                        stage: "error",
+                        correlation_id: correlationId,
+                        status: "failure",
+                        duration_ms: Date.now() - startedAt,
+                        metadata: {
+                            reference: input.reference,
+                            testMode,
+                        },
+                        error: {
+                            code: error instanceof StashError ? error.code : "unknown",
+                            message: error instanceof Error ? error.message : "Unknown error",
+                        },
+                    });
+                    throw error;
                 }
-                return adapter.verifyPayment({
-                    reference: input.reference,
-                    secrets: buildSecrets(provider, config.credentials),
-                    testMode,
-                });
             },
         },
         webhooks: {
             parse: (input) => {
+                const correlationId = randomUUID();
+                const startedAt = Date.now();
                 const resolvedProvider = input.provider ?? provider;
                 const secrets = buildSecrets(resolvedProvider, config.credentials);
                 const rawBody = input.rawBody;
+                emit({
+                    event: "webhooks.parse.request",
+                    provider: resolvedProvider,
+                    action: "parse",
+                    stage: "request",
+                    correlation_id: correlationId,
+                    status: "success",
+                    metadata: {
+                        testMode,
+                    },
+                });
                 const adapter = providerAdapters[resolvedProvider];
                 if (!adapter) {
-                    throw new Error(`Unsupported provider: ${resolvedProvider}`);
+                    const error = new Error(`Unsupported provider: ${resolvedProvider}`);
+                    emit({
+                        event: "webhooks.parse.error",
+                        provider: resolvedProvider,
+                        action: "parse",
+                        stage: "error",
+                        correlation_id: correlationId,
+                        status: "failure",
+                        duration_ms: Date.now() - startedAt,
+                        metadata: {
+                            testMode,
+                        },
+                        error: {
+                            code: "unsupported_provider",
+                            message: error.message,
+                        },
+                    });
+                    throw error;
                 }
                 const parsed = adapter.parseWebhook({
                     rawBody,
@@ -69,13 +239,48 @@ export function createStash(config) {
                     secrets,
                 });
                 if (!parsed.isValid) {
-                    throw new StashError("invalid_signature", `Invalid ${resolvedProvider} signature`);
+                    const error = new StashError("invalid_signature", `Invalid ${resolvedProvider} signature`);
+                    emit({
+                        event: "webhooks.parse.error",
+                        provider: resolvedProvider,
+                        action: "parse",
+                        stage: "error",
+                        correlation_id: correlationId,
+                        status: "failure",
+                        duration_ms: Date.now() - startedAt,
+                        metadata: {
+                            testMode,
+                        },
+                        error: {
+                            code: error.code,
+                            message: error.message,
+                        },
+                    });
+                    throw error;
                 }
-                return {
+                const response = {
                     event: parsed.event,
                     provider: resolvedProvider,
+                    correlationId,
                     raw: parsed.raw,
                 };
+                emit({
+                    event: "webhooks.parse.response",
+                    provider: resolvedProvider,
+                    action: "parse",
+                    stage: "response",
+                    correlation_id: correlationId,
+                    status: "success",
+                    duration_ms: Date.now() - startedAt,
+                    metadata: {
+                        amount: parsed.event.data.amount,
+                        currency: parsed.event.data.currency,
+                        reference: parsed.event.data.reference,
+                        provider_ref: parsed.event.data.providerRef,
+                        testMode,
+                    },
+                });
+                return response;
             },
         },
     };

package/dist/src/types.d.ts

@@ -38,6 +38,31 @@ export type StashConfig = {
     defaults?: {
         currency?: string;
     };
+    logger?: Logger;
+};
+export type LogEvent = {
+    event: string;
+    timestamp: string;
+    provider: PaymentProvider;
+    action: "create" | "verify" | "parse";
+    stage: "request" | "response" | "error";
+    correlation_id: string;
+    status: "success" | "failure";
+    duration_ms?: number;
+    metadata?: {
+        amount?: number | string;
+        currency?: string;
+        reference?: string;
+        provider_ref?: string;
+        testMode?: boolean;
+    };
+    error?: {
+        code: string;
+        message: string;
+    };
+};
+export type Logger = {
+    log: (event: LogEvent) => void;
 };
 export type PaymentCreateInput = {
     amount: string | number;
@@ -68,6 +93,7 @@ export type Payment = {
     redirectUrl?: string;
     provider: PaymentProvider;
     providerRef?: string;
+    correlationId?: string;
     raw?: unknown;
 };
 export type PaymentVerifyInput = {
@@ -77,6 +103,7 @@ export type VerificationResult = {
     provider: PaymentProvider;
     status: "pending" | "paid" | "failed" | "unknown";
     providerRef?: string;
+    correlationId?: string;
     raw?: unknown;
 };
 export type WebhookEvent = {
@@ -99,6 +126,7 @@ export type WebhookParseInput = {
 export type ParsedWebhook = {
     event: WebhookEvent;
     provider: PaymentProvider;
+    correlationId?: string;
     raw: Record<string, unknown>;
 };
 export type PaymentRequest = {

package/dist/test/stash.test.js

@@ -22,6 +22,34 @@ test("createStash payments.create returns canonical payment", async () => {
     assert.equal(payment.provider, "payfast");
     assert.match(payment.id, /^[0-9a-f-]{36}$/i);
     assert.ok(payment.redirectUrl);
+    assert.match(payment.correlationId ?? "", /^[0-9a-f-]{36}$/i);
+});
+test("createStash emits canonical logs for payments.create", async () => {
+    const events = [];
+    const stash = createStash({
+        provider: "payfast",
+        credentials: {
+            merchantId: "merchant",
+            merchantKey: "key",
+        },
+        testMode: true,
+        logger: {
+            log: (event) => events.push(event),
+        },
+    });
+    const payment = await stash.payments.create({
+        amount: "100.00",
+        currency: "ZAR",
+        reference: "ORDER-1",
+    });
+    assert.equal(events.length, 2);
+    assert.equal(events[0].event, "payments.create.request");
+    assert.equal(events[1].event, "payments.create.response");
+    assert.equal(events[0].provider, "payfast");
+    assert.equal(events[1].provider, "payfast");
+    assert.equal(events[0].correlation_id, payment.correlationId);
+    assert.equal(events[1].correlation_id, payment.correlationId);
+    assert.equal(events[1].metadata.testMode, true);
 });
 test("createStash payments.create maps ozow response", async () => {
     const originalFetch = globalThis.fetch;
@@ -127,6 +155,7 @@ test("webhooks.parse returns canonical event for payfast", () => {
     assert.equal(parsed.event.type, "payment.completed");
     assert.equal(parsed.event.data.reference, "ORDER-100");
     assert.equal(parsed.provider, "payfast");
+    assert.match(parsed.correlationId ?? "", /^[0-9a-f-]{36}$/i);
 });
 test("webhooks.parse throws invalid_signature for payfast", () => {
     const stash = createStash({
@@ -172,6 +201,7 @@ test("webhooks.parse returns canonical event for paystack", () => {
     assert.equal(parsed.provider, "paystack");
     assert.equal(parsed.event.type, "payment.completed");
     assert.equal(parsed.event.data.reference, "REF-3");
+    assert.match(parsed.correlationId ?? "", /^[0-9a-f-]{36}$/i);
 });
 test("payments.verify throws unsupported_capability for payfast", async () => {
     const stash = createStash({
@@ -205,5 +235,6 @@ test("payments.verify returns paid for paystack", async () => {
     });
     const result = await stash.payments.verify({ reference: "REF-1" });
     assert.equal(result.status, "paid");
+    assert.match(result.correlationId ?? "", /^[0-9a-f-]{36}$/i);
     globalThis.fetch = originalFetch;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miniduckco/stash",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "integrate payments. switch once.",
   "license": "MIT",
   "type": "module",