@mercurjs/payout-stripe-connect 2.0.0-canary.94

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@mercurjs/payout-stripe-connect",
+  "version": "2.0.0-canary.94",
+  "description": "Stripe Connect payment provider for Mercur",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mercurjs/mercur",
+    "directory": "packages/providers/payment-stripe-connect"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "author": "Medusa",
+  "license": "MIT",
+  "peerDependencies": {
+    "@medusajs/framework": "2.13.4"
+  },
+  "devDependencies": {
+    "@medusajs/framework": "2.13.4",
+    "@mercurjs/types": "2.0.0-canary.94"
+  },
+  "dependencies": {
+    "stripe": "^15.5.0"
+  },
+  "keywords": [
+    "medusa-plugin",
+    "medusa-plugin-payment",
+    "stripe-connect"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+import { ModuleProvider, Modules } from "@medusajs/framework/utils"
+
+export default ModuleProvider(Modules.PAYMENT, {
+    services: [],
+})

package/src/services/stripe-connect.ts

@@ -0,0 +1,267 @@
+import { isPresent, MedusaError } from "@medusajs/framework/utils"
+import {
+    CreateOnboardingInput,
+    CreateOnboardingResponse,
+    CreatePayoutAccountInput,
+    CreatePayoutAccountResponse,
+    CreatePayoutInput,
+    CreatePayoutResponse,
+    IPayoutProvider,
+    PayoutAccountStatus,
+    PayoutStatus,
+    PayoutWebhookActionInput,
+    PayoutWebhookResult,
+} from "@mercurjs/types"
+import { StripeConnectOptions } from "@types"
+import { getSmallestUnit } from "@utils"
+import Stripe from "stripe"
+
+const DEFAULT_ACCOUNT_VALIDATION = {
+    detailsSubmitted: true,
+    chargesEnabled: true,
+    payoutsEnabled: true,
+    noOutstandingRequirements: true,
+    requiredCapabilities: [],
+}
+
+class StripeConnectProviderService implements IPayoutProvider {
+    static identifier = "stripe-connect"
+    protected stripe_: Stripe
+    protected config_: StripeConnectOptions
+
+    protected constructor(
+        options: StripeConnectOptions
+    ) {
+        this.config_ = options
+        this.stripe_ = new Stripe(options.apiKey)
+    }
+
+    protected normalizePayoutParameters(
+        extra: Record<string, unknown>
+    ): Partial<Stripe.TransferCreateParams> & { destination: string } {
+        const res = {
+        } as Partial<Stripe.TransferCreateParams>
+
+        res.destination = extra!.id as string
+        res.source_transaction = extra?.source_transaction as string | undefined
+        res.transfer_group = extra?.order_id as string | undefined
+        res.description = extra?.description as string | undefined
+        res.metadata = extra?.metadata as Stripe.MetadataParam | undefined
+
+
+        return res as Partial<Stripe.TransferCreateParams> & { destination: string }
+    }
+
+    private getWebhookResultFromAccount_(
+        account: Stripe.Account
+    ): PayoutWebhookResult {
+        const validation = {
+            ...DEFAULT_ACCOUNT_VALIDATION,
+            ...this.config_.accountValidation,
+        }
+        const requirements = account.requirements
+        const disabledReason = requirements?.disabled_reason
+        const hasOutstandingRequirements = Boolean(
+            requirements?.currently_due?.length ||
+            requirements?.past_due?.length ||
+            requirements?.pending_verification?.length
+        )
+        const requiredCapabilities = validation.requiredCapabilities ?? []
+        const hasInactiveCapabilities = requiredCapabilities.some((capability) => {
+            return account.capabilities?.[capability as keyof Stripe.Account.Capabilities] !== "active"
+        })
+
+        if (disabledReason?.startsWith("rejected.")) {
+            return {
+                action: "account.rejected",
+                data: {
+                    id: account.id,
+                },
+            }
+        }
+
+        if (
+            (!validation.detailsSubmitted || account.details_submitted) &&
+            (!validation.chargesEnabled || account.charges_enabled) &&
+            (!validation.payoutsEnabled || account.payouts_enabled) &&
+            (!validation.noOutstandingRequirements || !hasOutstandingRequirements) &&
+            !hasInactiveCapabilities
+        ) {
+            return {
+                action: "account.activated",
+                data: {
+                    id: account.id,
+                },
+            }
+        }
+
+        if (disabledReason) {
+            return {
+                action: "account.restricted",
+                data: {
+                    id: account.id,
+                },
+            }
+        }
+
+        return {
+            action: "account.restricted",
+            data: {
+                id: account.id,
+            },
+        }
+    }
+
+    private getWebhookResultFromPayout_(
+        payout: Stripe.Payout
+    ): PayoutWebhookResult {
+        const payoutId = payout.metadata?.payout_id || payout.id
+
+        switch (payout.status) {
+            case "pending":
+            case "in_transit":
+                return {
+                    action: "payout.processing",
+                    data: {
+                        id: payoutId,
+                    },
+                }
+            case "paid":
+                return {
+                    action: "payout.paid",
+                    data: {
+                        id: payoutId,
+                    },
+                }
+            case "failed":
+                return {
+                    action: "payout.failed",
+                    data: {
+                        id: payoutId,
+                    },
+                }
+            case "canceled":
+                return {
+                    action: "payout.canceled",
+                    data: {
+                        id: payoutId,
+                    },
+                }
+            default:
+                return {
+                    action: "not_supported",
+                }
+        }
+    }
+
+    async createPayoutAccount(
+        input: CreatePayoutAccountInput
+    ): Promise<CreatePayoutAccountResponse> {
+        const { data } = input;
+        const country = data?.country as string
+
+        if (!isPresent(country)) {
+            throw new MedusaError(
+                MedusaError.Types.INVALID_DATA,
+                `"country" is required`
+            );
+        }
+
+        const response = await this.stripe_.accounts.create({
+            type: 'express',
+            country,
+        }, {
+            idempotencyKey: input.context?.idempotency_key
+        })
+
+        return {
+            id: response.id,
+            status: PayoutAccountStatus.PENDING,
+            data: response as unknown as Record<string, unknown>
+        }
+    }
+
+    async createPayout(input: CreatePayoutInput): Promise<CreatePayoutResponse> {
+        const normalizedInput = this.normalizePayoutParameters(input.data!)
+        const transfer = await this.stripe_.transfers.create(
+            {
+                currency: input.currency_code,
+                amount: getSmallestUnit(input.amount, input.currency_code),
+                ...normalizedInput,
+            },
+            { idempotencyKey: input.context?.idempotency_key }
+        );
+
+
+        return {
+            data: transfer as unknown as Record<string, unknown>,
+            status: PayoutStatus.PENDING
+        }
+    }
+
+    async createOnboarding(
+        input: CreateOnboardingInput
+    ): Promise<CreateOnboardingResponse> {
+        const id = input?.data?.id as string
+        if (!isPresent(id)) {
+            throw new MedusaError(
+                MedusaError.Types.INVALID_DATA,
+                `'id' is required`
+            );
+        }
+
+        if (!isPresent(input.data?.refresh_url)) {
+            throw new MedusaError(
+                MedusaError.Types.INVALID_DATA,
+                `'refresh_url' is required`
+            );
+        }
+
+        if (!isPresent(input.data?.return_url)) {
+            throw new MedusaError(
+                MedusaError.Types.INVALID_DATA,
+                `'return_url' is required`
+            );
+        }
+
+        const accountLink = await this.stripe_.accountLinks.create({
+            account: id,
+            refresh_url: input.data?.refresh_url as string,
+            return_url: input.data?.return_url as string,
+            type: "account_onboarding",
+        }, {
+            idempotencyKey: input.context?.idempotency_key
+        });
+
+        return {
+            data: accountLink as unknown as Record<string, unknown>,
+        };
+    }
+
+    async getWebhookActionAndData(
+        payload: PayoutWebhookActionInput
+    ): Promise<PayoutWebhookResult> {
+        const signature = payload.headers["stripe-signature"] as string
+
+        const event = this.stripe_.webhooks.constructEvent(
+            payload.rawData as string | Buffer,
+            signature,
+            this.config_.webhookSecret
+        )
+
+        switch (event.type) {
+            case "account.updated":
+                return this.getWebhookResultFromAccount_(event.data.object as Stripe.Account)
+            case "payout.created":
+            case "payout.updated":
+            case "payout.paid":
+            case "payout.failed":
+            case "payout.canceled":
+                return this.getWebhookResultFromPayout_(event.data.object as Stripe.Payout)
+            default:
+                return { action: "not_supported" }
+        }
+    }
+}
+
+export default StripeConnectProviderService

package/src/types/index.ts

@@ -0,0 +1,37 @@
+export interface StripeConnectAccountValidationOptions {
+    /**
+     * Require Stripe to mark onboarding details as submitted
+     */
+    detailsSubmitted?: boolean
+    /**
+     * Require the account to be enabled for charges
+     */
+    chargesEnabled?: boolean
+    /**
+     * Require the account to be enabled for payouts
+     */
+    payoutsEnabled?: boolean
+    /**
+     * Treat pending Stripe requirements as a restricted account
+     */
+    noOutstandingRequirements?: boolean
+    /**
+     * Require specific Stripe capabilities to be active
+     */
+    requiredCapabilities?: string[]
+}
+
+export interface StripeConnectOptions {
+    /**
+     * The API key for the Stripe Connect account
+     */
+    apiKey: string
+    /**
+     * The webhook secret used to verify webhooks
+     */
+    webhookSecret: string
+    /**
+     * Controls how connected accounts are validated from Stripe webhook data
+     */
+    accountValidation?: StripeConnectAccountValidationOptions
+}

package/src/utils/index.ts

@@ -0,0 +1,79 @@
+import { BigNumberInput } from '@medusajs/framework/types'
+import { BigNumber, MathBN } from '@medusajs/framework/utils'
+
+function getCurrencyMultiplier(currency) {
+    const currencyMultipliers = {
+        0: [
+            'BIF',
+            'CLP',
+            'DJF',
+            'GNF',
+            'JPY',
+            'KMF',
+            'KRW',
+            'MGA',
+            'PYG',
+            'RWF',
+            'UGX',
+            'VND',
+            'VUV',
+            'XAF',
+            'XOF',
+            'XPF'
+        ],
+        3: ['BHD', 'IQD', 'JOD', 'KWD', 'OMR', 'TND']
+    }
+
+    currency = currency.toUpperCase()
+    let power = 2
+    for (const [key, value] of Object.entries(currencyMultipliers)) {
+        if (value.includes(currency)) {
+            power = parseInt(key, 10)
+            break
+        }
+    }
+    return Math.pow(10, power)
+}
+
+/**
+ * Converts an amount to the format required by Stripe based on currency.
+ * https://docs.stripe.com/currencies
+ * @param {BigNumberInput} amount - The amount to be converted.
+ * @param {string} currency - The currency code (e.g., 'USD', 'JOD').
+ * @returns {number} - The converted amount in the smallest currency unit.
+ */
+export function getSmallestUnit(
+    amount: BigNumberInput,
+    currency: string
+): number {
+    const multiplier = getCurrencyMultiplier(currency)
+
+    const amount_ =
+        Math.round(new BigNumber(MathBN.mult(amount, multiplier)).numeric) /
+        multiplier
+
+    const smallestAmount = new BigNumber(MathBN.mult(amount_, multiplier))
+
+    let numeric = smallestAmount.numeric
+    // Check if the currency requires rounding to the nearest ten
+    if (multiplier === 1e3) {
+        numeric = Math.ceil(numeric / 10) * 10
+    }
+
+    return parseInt(numeric.toString().split('.').shift()!, 10)
+}
+
+/**
+ * Converts an amount from the smallest currency unit to the standard unit based on currency.
+ * @param {BigNumberInput} amount - The amount in the smallest currency unit.
+ * @param {string} currency - The currency code (e.g., 'USD', 'JOD').
+ * @returns {number} - The converted amount in the standard currency unit.
+ */
+export function getAmountFromSmallestUnit(
+    amount: BigNumberInput,
+    currency: string
+): number {
+    const multiplier = getCurrencyMultiplier(currency)
+    const standardAmount = new BigNumber(MathBN.div(amount, multiplier))
+    return standardAmount.numeric
+}

package/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "lib": ["ES2021"],
+    "target": "ES2021",
+    "outDir": "./dist",
+    "esModuleInterop": true,
+    "declaration": true,
+    "declarationMap": true,
+    "noUnusedLocals": true,
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "sourceMap": true,
+    "noImplicitReturns": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "noImplicitThis": true,
+    "allowJs": true,
+    "skipLibCheck": true,
+    "incremental": false,
+    "paths": {
+      "@models": ["./src/models"],
+      "@services": ["./src/services"],
+      "@repositories": ["./src/repositories"],
+      "@types": ["./src/types"],
+      "@utils": ["./src/utils"]
+    }
+  },
+  "include": ["./src"],
+  "exclude": ["./dist", "./node_modules"]
+}