@paykit-sdk/medusajs 1.0.0

package/README.md

@@ -0,0 +1,66 @@
+# @paykit-sdk/medusajs
+
+Universal payment provider adapter for Medusa v2+ using PayKit. Compatible with any PayKit provider.
+
+## Installation
+
+```bash
+npm install @paykit-sdk/medusajs @paykit-sdk/core
+```
+
+## Install your provider
+
+```bash
+npm install @paykit-sdk/stripe
+```
+
+## Usage
+
+Configure in `medusa-config.ts`:
+
+```typescript
+import { defineConfig } from '@medusajs/framework/utils';
+import { createStripe } from '@paykit-sdk/stripe';
+
+export default defineConfig({
+  modules: [
+    {
+      resolve: '@paykit-sdk/medusa-adapter',
+      options: {
+        provider: createStripe({ apiKey: process.env.STRIPE_API_KEY }),
+        webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+        debug: process.env.NODE_ENV === 'development',
+      },
+    },
+  ],
+});
+```
+
+## Environment Variables
+
+```env
+STRIPE_API_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+```
+
+## Webhook Setup
+
+Configure your payment provider to send webhooks to:
+
+```
+https://your-store.com/hooks/payment/pp_paykit
+```
+
+Select payment-related events based on the PayKit provider documentation.
+
+## Configuration Options
+
+| Option        | Type           | Required | Description                  |
+| ------------- | -------------- | -------- | ---------------------------- |
+| provider      | PayKitProvider | Yes      | PayKit provider instance     |
+| webhookSecret | string         | Yes      | Webhook secret from provider |
+| debug         | boolean        | No       | Enable debug logging         |
+
+## License
+
+ISC

package/dist/index.d.mts

@@ -0,0 +1,10 @@
+import * as _medusajs_types from '@medusajs/types';
+export { PaykitMedusaJSAdapter, PaykitMedusaJSAdapterOptions } from './providers/paykit-provider.mjs';
+import '@medusajs/framework/types';
+import '@medusajs/framework/utils';
+import '@paykit-sdk/core';
+import 'zod';
+
+declare const _default: _medusajs_types.ModuleProviderExports;
+
+export { _default as default };

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import * as _medusajs_types from '@medusajs/types';
+export { PaykitMedusaJSAdapter, PaykitMedusaJSAdapterOptions } from './providers/paykit-provider.js';
+import '@medusajs/framework/types';
+import '@medusajs/framework/utils';
+import '@paykit-sdk/core';
+import 'zod';
+
+declare const _default: _medusajs_types.ModuleProviderExports;
+
+export { _default as default };

package/dist/index.js

@@ -0,0 +1,311 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils = require('@medusajs/framework/utils');
+var core = require('@paykit-sdk/core');
+var zod = require('zod');
+
+// src/index.ts
+var medusaStatus$InboundSchema = (status) => {
+  switch (status) {
+    case "pending":
+    case "processing":
+      return utils.PaymentSessionStatus.PENDING;
+    case "requires_action":
+      return utils.PaymentSessionStatus.REQUIRES_MORE;
+    case "requires_capture":
+      return utils.PaymentSessionStatus.AUTHORIZED;
+    case "succeeded":
+      return utils.PaymentSessionStatus.CAPTURED;
+    case "canceled":
+      return utils.PaymentSessionStatus.CANCELED;
+    case "failed":
+      return utils.PaymentSessionStatus.ERROR;
+    default:
+      return utils.PaymentSessionStatus.PENDING;
+  }
+};
+
+// src/providers/paykit-provider.ts
+var optionsSchema = zod.z.object({
+  /**
+   * The underlying PayKit provider instance (Stripe, PayPal, etc.)
+   * This is required and must be a valid PayKit provider instance
+   */
+  provider: core.providerSchema,
+  /**
+   * The webhook secret for the provider
+   * This is required and must be a valid webhook secret
+   */
+  webhookSecret: zod.z.string(),
+  /**
+   * Whether to enable debug mode
+   * If enabled, the adapter will log debug information to the console
+   */
+  debug: zod.z.boolean().optional()
+});
+var PaykitMedusaJSAdapter = class extends utils.AbstractPaymentProvider {
+  /**
+   * The unique identifier for this payment provider
+   * Will be stored as `pp_paykit_{id}` in Medusa
+   */
+  static identifier = "paykit";
+  paykit;
+  provider;
+  options;
+  static validateOptions(options) {
+    const { error } = optionsSchema.safeParse(options);
+    if (error) {
+      throw new utils.MedusaError(utils.MedusaError.Types.INVALID_DATA, error.message);
+    }
+    return;
+  }
+  /**
+   * Constructor receives Medusa's container and provider options
+   *
+   * @param cradle - Medusa's dependency injection container
+   * @param options - PayKit provider configuration
+   */
+  constructor(cradle, options) {
+    super(cradle, options);
+    this.options = options;
+    this.provider = options.provider;
+    this.paykit = new core.PayKit(this.provider);
+    if (this.options.debug) {
+      console.info(`[PayKit] Initialized with provider: ${this.provider.providerName}`);
+    }
+  }
+  initiatePayment = async ({
+    context,
+    amount,
+    currency_code,
+    data
+  }) => {
+    if (this.options.debug) {
+      console.info("[PayKit] Initiating payment", { context, amount, currency_code, data });
+    }
+    const intent = {
+      status: "pending",
+      amount: Number(amount),
+      currency: currency_code,
+      metadata: { ...data?.metadata ?? {}, session_id: data?.session_id ?? "" },
+      provider_metadata: data?.provider_metadata ?? void 0
+    };
+    let customer;
+    if (context?.account_holder?.data?.id) {
+      customer = context.account_holder.data.id;
+    } else if (data?.email) {
+      customer = { email: data.email };
+    }
+    if (!customer) {
+      throw new utils.MedusaError(utils.MedusaError.Types.INVALID_DATA, "Required: customer ID (account_holder) or email (data)");
+    }
+    if (typeof customer === "object" && "email" in customer) {
+      await core.tryCatchAsync(
+        this.paykit.customers.create({
+          email: customer.email,
+          phone: data?.phone ?? "",
+          name: data?.name ? data.name : customer.email.split("@")[0],
+          metadata: { PAYKIT_METADATA_KEY: JSON.stringify({ source: "medusa" }) }
+        })
+      );
+    } else {
+      customer = customer;
+    }
+    intent.customer = customer;
+    const [paymentIntentResult, paymentIntentError] = await core.tryCatchAsync(
+      this.paykit.payments.create(intent)
+    );
+    if (paymentIntentError)
+      throw new utils.MedusaError(utils.MedusaError.Types.PAYMENT_AUTHORIZATION_ERROR, paymentIntentError.message);
+    return { id: paymentIntentResult.id, status: medusaStatus$InboundSchema(paymentIntentResult.status) };
+  };
+  capturePayment = async (input) => {
+    if (this.options.debug) {
+      console.info("[PayKit] Capturing payment", input);
+    }
+    const { id, amount } = core.validateRequiredKeys(
+      ["id", "amount"],
+      input?.data ?? {},
+      "Missing required payment ID"
+    );
+    if (!id) throw new utils.MedusaError(utils.MedusaError.Types.INVALID_DATA, "Missing required payment ID");
+    if (!amount) throw new utils.MedusaError(utils.MedusaError.Types.INVALID_DATA, "Missing required payment amount");
+    const [paymentIntentResult, paymentIntentError] = await core.tryCatchAsync(
+      this.paykit.payments.capture(id, { amount: Number(amount) })
+    );
+    if (paymentIntentError)
+      throw new utils.MedusaError(utils.MedusaError.Types.PAYMENT_AUTHORIZATION_ERROR, paymentIntentError.message);
+    return { data: paymentIntentResult };
+  };
+  authorizePayment = async (input) => {
+    if (this.options.debug) {
+      console.info("[PayKit] Authorizing payment", input);
+    }
+    return this.getPaymentStatus(input);
+  };
+  cancelPayment = async (input) => {
+    if (this.options.debug) {
+      console.info("[PayKit] Canceling payment", input);
+    }
+    const { id } = core.validateRequiredKeys(
+      ["id"],
+      input?.data ?? {},
+      "Missing required payment ID"
+    );
+    if (!id) throw new utils.MedusaError(utils.MedusaError.Types.INVALID_DATA, "Missing required payment ID");
+    const [paymentIntentResult, paymentIntentError] = await core.tryCatchAsync(this.paykit.payments.cancel(id));
+    if (paymentIntentError)
+      throw new utils.MedusaError(utils.MedusaError.Types.PAYMENT_AUTHORIZATION_ERROR, paymentIntentError.message);
+    return { data: paymentIntentResult };
+  };
+  deletePayment = async (input) => {
+    return this.cancelPayment(input);
+  };
+  getPaymentStatus = async (input) => {
+    const { id } = core.validateRequiredKeys(
+      ["id"],
+      input?.data ?? {},
+      "Missing required payment ID"
+    );
+    if (!id) throw new utils.MedusaError(utils.MedusaError.Types.INVALID_DATA, "Missing required payment ID");
+    const [paymentIntentResult, paymentIntentError] = await core.tryCatchAsync(this.paykit.payments.retrieve(id));
+    if (paymentIntentError)
+      throw new utils.MedusaError(utils.MedusaError.Types.PAYMENT_AUTHORIZATION_ERROR, paymentIntentError.message);
+    if (!paymentIntentResult) throw new utils.MedusaError(utils.MedusaError.Types.PAYMENT_AUTHORIZATION_ERROR, "Payment not found");
+    return {
+      status: medusaStatus$InboundSchema(paymentIntentResult.status),
+      data: paymentIntentResult
+    };
+  };
+  refundPayment = async (input) => {
+    if (this.options.debug) {
+      console.info("[PayKit] Refunding payment", input);
+    }
+    const { id: paymentId } = core.validateRequiredKeys(
+      ["id"],
+      input?.data ?? {},
+      "Missing required payment ID"
+    );
+    if (!paymentId) throw new utils.MedusaError(utils.MedusaError.Types.INVALID_DATA, "Missing required payment ID");
+    const [refundResult, refundError] = await core.tryCatchAsync(
+      this.paykit.refunds.create({
+        payment_id: paymentId,
+        amount: Number(input.amount),
+        reason: null,
+        metadata: input.data?.metadata ? input.data.metadata : null,
+        provider_metadata: input.data?.provider_metadata ? input.data.provider_metadata : void 0
+      })
+    );
+    if (refundError) throw new utils.MedusaError(utils.MedusaError.Types.PAYMENT_AUTHORIZATION_ERROR, refundError.message);
+    return { data: refundResult };
+  };
+  retrievePayment = async (input) => {
+    if (this.options.debug) {
+      console.info("[PayKit] Retrieving payment", input);
+    }
+    const { id } = core.validateRequiredKeys(
+      ["id"],
+      input?.data ?? {},
+      "Missing required payment ID"
+    );
+    if (!id) throw new utils.MedusaError(utils.MedusaError.Types.INVALID_DATA, "Missing required payment ID");
+    const [paymentIntentResult, paymentIntentError] = await core.tryCatchAsync(this.paykit.payments.retrieve(id));
+    if (paymentIntentError)
+      throw new utils.MedusaError(utils.MedusaError.Types.PAYMENT_AUTHORIZATION_ERROR, paymentIntentError.message);
+    return { data: paymentIntentResult };
+  };
+  updatePayment = async (input) => {
+    if (this.options.debug) {
+      console.info("[PayKit] Updating payment", input);
+    }
+    const { amount, currency_code } = core.validateRequiredKeys(
+      ["amount", "currency_code"],
+      input,
+      "Missing required payment ID"
+    );
+    if (!amount || !currency_code)
+      throw new utils.MedusaError(utils.MedusaError.Types.INVALID_DATA, "Missing required amount or currency code");
+    const { id: paymentId } = core.validateRequiredKeys(
+      ["id"],
+      input.data,
+      "Missing required payment ID"
+    );
+    if (!paymentId) throw new utils.MedusaError(utils.MedusaError.Types.INVALID_DATA, "Missing required payment ID");
+    const [paymentIntentResult, paymentIntentError] = await core.tryCatchAsync(
+      this.paykit.payments.update(paymentId, {
+        amount: Number(amount),
+        currency: currency_code,
+        metadata: input.data?.metadata ? input.data.metadata : {},
+        provider_metadata: input.data?.provider_metadata ? input.data.provider_metadata : void 0
+      })
+    );
+    if (paymentIntentError)
+      throw new utils.MedusaError(utils.MedusaError.Types.PAYMENT_AUTHORIZATION_ERROR, paymentIntentError.message);
+    return { data: paymentIntentResult };
+  };
+  getWebhookActionAndData = async (payload) => {
+    if (this.options.debug) {
+      console.info("[PayKit] Getting webhook action and data", payload);
+    }
+    const { rawData, headers } = payload;
+    const fullUrl = (() => {
+      if (headers["origin"]) {
+        return headers["origin"];
+      }
+      if (headers["x-forwarded-host"]) {
+        const protocol = headers["x-forwarded-proto"] || "https";
+        const host = headers["x-forwarded-host"];
+        const path = headers["x-forwarded-path"] || "";
+        return `${protocol}://${host}${path}`;
+      }
+      if (headers["host"]) {
+        const protocol = headers["x-forwarded-proto"] || (String(headers["host"]).includes("localhost") ? "http" : "https");
+        const host = headers["host"];
+        const path = headers["x-original-url"] || headers["x-forwarded-path"] || "";
+        return `${protocol}://${host}${path}`;
+      }
+      return "";
+    })();
+    const webhook = this.paykit.webhooks.setup({ webhookSecret: this.options.webhookSecret }).on("payment.created", async (event) => {
+      return {
+        action: utils.PaymentActions.PENDING,
+        data: { session_id: event.data?.metadata?.session_id, amount: event.data?.amount }
+      };
+    }).on("payment.updated", async (event) => {
+      const statusActionMap = {
+        pending: utils.PaymentActions.PENDING,
+        processing: utils.PaymentActions.PENDING,
+        requires_action: utils.PaymentActions.REQUIRES_MORE,
+        requires_capture: utils.PaymentActions.AUTHORIZED,
+        succeeded: utils.PaymentActions.SUCCESSFUL,
+        failed: utils.PaymentActions.FAILED,
+        canceled: utils.PaymentActions.CANCELED
+      };
+      return {
+        action: event.data?.status ? statusActionMap[event.data.status] : utils.PaymentActions.PENDING,
+        data: { session_id: event.data?.metadata?.session_id, amount: event.data?.amount }
+      };
+    }).on("payment.canceled", async (event) => {
+      return {
+        action: utils.PaymentActions.CANCELED,
+        data: { session_id: event.data?.metadata?.session_id, amount: event.data?.amount }
+      };
+    });
+    const webhookEvents = await webhook.handle({
+      body: rawData,
+      headers,
+      fullUrl
+    });
+    return webhookEvents;
+  };
+};
+
+// src/index.ts
+var index_default = utils.ModuleProvider(utils.Modules.PAYMENT, {
+  services: [PaykitMedusaJSAdapter]
+});
+
+exports.PaykitMedusaJSAdapter = PaykitMedusaJSAdapter;
+exports.default = index_default;