@porulle/adapter-stripe 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# @porulle/adapter-stripe
+
+`PaymentAdapter` for [Stripe](https://stripe.com). The reference implementation of the payment-adapter contract.
+
+## Usage
+
+```ts
+import { defineConfig } from "@porulle/core";
+import { stripePayment } from "@porulle/adapter-stripe";
+
+export default defineConfig({
+  payments: [
+    stripePayment({
+      secretKey: process.env.STRIPE_SECRET_KEY!,
+      webhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
+      apiVersion: "2025-08-27.basil",  // optional override
+    }),
+  ],
+  // …
+});
+```
+
+## What it implements
+
+| Adapter method | Stripe call |
+|---|---|
+| `createPaymentIntent({ amount, currency })` | `stripe.paymentIntents.create()` |
+| `capturePayment(intentId, amount?)` | `stripe.paymentIntents.capture()` — returns `amountCaptured` (the framework reads this and stores it on the order; refunds are then capped at this value) |
+| `refundPayment(paymentId, amount, reason?)` | `stripe.refunds.create()` |
+| `cancelPaymentIntent(intentId)` | `stripe.paymentIntents.cancel()` |
+| `verifyWebhook(payload, signature)` | `stripe.webhooks.constructEvent()` (timing-safe HMAC compare under the hood) |
+
+## Why this is the reference
+
+It's the canonical example of the [Payment Adapter Contract](https://github.com/asyncdotengineering/porulle/blob/main/apps/docs/src/content/docs/extending/payment-adapter-contract.mdx):
+
+- Returns accurate `amountCaptured` (so refund cap works)
+- Idempotency keys propagate through Stripe's `Idempotency-Key` header
+- Webhook signature verification is timing-safe (Stripe SDK handles)
+- Errors return `Result<T>` — never throws across module boundaries
+- Vendor SDK (`stripe`) is isolated to this package; never leaks into core
+
+If you build a new payment adapter, mirror this file's shape.
+
+## See also
+
+- [Payment Adapter Contract](https://github.com/asyncdotengineering/porulle/blob/main/apps/docs/src/content/docs/extending/payment-adapter-contract.mdx) — the contract this implements
+- [Stripe API reference](https://stripe.com/docs/api)

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import Stripe from "stripe";
+import { type PaymentAdapter } from "@porulle/core";
+export interface StripeAdapterOptions {
+    secretKey: string;
+    webhookSecret?: string;
+    apiVersion?: Stripe.LatestApiVersion;
+}
+export declare function stripePayment(options: StripeAdapterOptions): PaymentAdapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAGL,KAAK,cAAc,EAMpB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC,gBAAgB,CAAC;CACtC;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,cAAc,CA4H3E"}

package/dist/index.js

@@ -0,0 +1,121 @@
+import Stripe from "stripe";
+import { Err, Ok, } from "@porulle/core";
+export function stripePayment(options) {
+    const stripe = new Stripe(options.secretKey, {
+        apiVersion: options.apiVersion ?? "2025-08-27.basil",
+    });
+    return {
+        providerId: "stripe",
+        async createPaymentIntent(params) {
+            try {
+                const intent = await stripe.paymentIntents.create({
+                    amount: params.amount,
+                    currency: params.currency.toLowerCase(),
+                    metadata: {
+                        orderId: params.orderId,
+                        customerId: params.customerId ?? "",
+                        ...params.metadata,
+                    },
+                    automatic_payment_methods: {
+                        enabled: true,
+                    },
+                });
+                return Ok({
+                    id: intent.id,
+                    status: intent.status,
+                    amount: intent.amount,
+                    currency: intent.currency,
+                    clientSecret: intent.client_secret,
+                });
+            }
+            catch (error) {
+                return Err({
+                    code: "PAYMENT_INTENT_CREATE_FAILED",
+                    message: error instanceof Error ? error.message : "Stripe payment intent creation failed.",
+                });
+            }
+        },
+        async capturePayment(paymentIntentId, amount) {
+            try {
+                const captured = await stripe.paymentIntents.capture(paymentIntentId, amount ? { amount_to_capture: amount } : undefined);
+                return Ok({
+                    id: captured.id,
+                    status: captured.status,
+                    amountCaptured: captured.amount_received,
+                });
+            }
+            catch (error) {
+                return Err({
+                    code: "PAYMENT_CAPTURE_FAILED",
+                    message: error instanceof Error ? error.message : "Stripe capture failed.",
+                });
+            }
+        },
+        async refundPayment(paymentId, amount, reason) {
+            try {
+                const params = {
+                    payment_intent: paymentId,
+                    amount,
+                };
+                if (reason != null) {
+                    // Single-cast: `string` to Stripe's `Reason` enum — structurally compatible
+                    params.reason = reason;
+                }
+                const refund = await stripe.refunds.create(params);
+                return Ok({
+                    id: refund.id,
+                    status: refund.status ?? "pending",
+                    amountRefunded: refund.amount,
+                });
+            }
+            catch (error) {
+                return Err({
+                    code: "PAYMENT_REFUND_FAILED",
+                    message: error instanceof Error ? error.message : "Stripe refund failed.",
+                });
+            }
+        },
+        async cancelPaymentIntent(paymentIntentId) {
+            try {
+                await stripe.paymentIntents.cancel(paymentIntentId);
+                return Ok(undefined);
+            }
+            catch (error) {
+                return Err({
+                    code: "PAYMENT_CANCEL_FAILED",
+                    message: error instanceof Error ? error.message : "Stripe cancellation failed.",
+                });
+            }
+        },
+        async verifyWebhook(request) {
+            try {
+                if (!options.webhookSecret) {
+                    return Err({
+                        code: "WEBHOOK_SECRET_MISSING",
+                        message: "Stripe webhook secret is not configured.",
+                    });
+                }
+                const signature = request.headers.get("stripe-signature");
+                if (!signature) {
+                    return Err({
+                        code: "WEBHOOK_SIGNATURE_MISSING",
+                        message: "Missing stripe-signature header.",
+                    });
+                }
+                const body = await request.text();
+                const event = stripe.webhooks.constructEvent(body, signature, options.webhookSecret);
+                return Ok({
+                    id: event.id,
+                    type: event.type,
+                    data: event.data.object,
+                });
+            }
+            catch (error) {
+                return Err({
+                    code: "WEBHOOK_VERIFICATION_FAILED",
+                    message: error instanceof Error ? error.message : "Stripe webhook verification failed.",
+                });
+            }
+        },
+    };
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@porulle/adapter-stripe",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 1000",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@porulle/core": "workspace:*",
+    "stripe": "^18.5.0"
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "*",
+    "@repo/typescript-config": "*",
+    "@types/node": "^24.5.2",
+    "eslint": "^9.39.1",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "description": "PaymentAdapter for Stripe. The reference implementation of the payment-adapter contract.",
+  "homepage": "https://porulle-docs.vercel.app",
+  "bugs": {
+    "url": "https://github.com/asyncdotengineering/porulle/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asyncdotengineering/porulle.git",
+    "directory": "packages/adapters/adapter-stripe"
+  },
+  "author": "Porulle contributors"
+}

package/src/index.ts

@@ -0,0 +1,143 @@
+import Stripe from "stripe";
+import {
+  Err,
+  Ok,
+  type PaymentAdapter,
+  type PaymentCapture,
+  type PaymentIntent,
+  type PaymentRefund,
+  type PaymentWebhookEvent,
+  type Result,
+} from "@porulle/core";
+
+export interface StripeAdapterOptions {
+  secretKey: string;
+  webhookSecret?: string;
+  apiVersion?: Stripe.LatestApiVersion;
+}
+
+export function stripePayment(options: StripeAdapterOptions): PaymentAdapter {
+  const stripe = new Stripe(options.secretKey, {
+    apiVersion: options.apiVersion ?? "2025-08-27.basil",
+  });
+
+  return {
+    providerId: "stripe",
+
+    async createPaymentIntent(params): Promise<Result<PaymentIntent>> {
+      try {
+        const intent = await stripe.paymentIntents.create({
+          amount: params.amount,
+          currency: params.currency.toLowerCase(),
+          metadata: {
+            orderId: params.orderId,
+            customerId: params.customerId ?? "",
+            ...params.metadata,
+          },
+          automatic_payment_methods: {
+            enabled: true,
+          },
+        });
+
+        return Ok({
+          id: intent.id,
+          status: intent.status,
+          amount: intent.amount,
+          currency: intent.currency,
+          clientSecret: intent.client_secret,
+        });
+      } catch (error) {
+        return Err({
+          code: "PAYMENT_INTENT_CREATE_FAILED",
+          message: error instanceof Error ? error.message : "Stripe payment intent creation failed.",
+        });
+      }
+    },
+
+    async capturePayment(paymentIntentId: string, amount?: number): Promise<Result<PaymentCapture>> {
+      try {
+        const captured = await stripe.paymentIntents.capture(paymentIntentId, amount ? { amount_to_capture: amount } : undefined);
+        return Ok({
+          id: captured.id,
+          status: captured.status,
+          amountCaptured: captured.amount_received,
+        });
+      } catch (error) {
+        return Err({
+          code: "PAYMENT_CAPTURE_FAILED",
+          message: error instanceof Error ? error.message : "Stripe capture failed.",
+        });
+      }
+    },
+
+    async refundPayment(paymentId: string, amount: number, reason?: string): Promise<Result<PaymentRefund>> {
+      try {
+        const params: Stripe.RefundCreateParams = {
+          payment_intent: paymentId,
+          amount,
+        };
+        if (reason != null) {
+          // Single-cast: `string` to Stripe's `Reason` enum — structurally compatible
+          (params as Record<string, unknown>).reason = reason;
+        }
+        const refund = await stripe.refunds.create(params);
+
+        return Ok({
+          id: refund.id,
+          status: refund.status ?? "pending",
+          amountRefunded: refund.amount,
+        });
+      } catch (error) {
+        return Err({
+          code: "PAYMENT_REFUND_FAILED",
+          message: error instanceof Error ? error.message : "Stripe refund failed.",
+        });
+      }
+    },
+
+    async cancelPaymentIntent(paymentIntentId: string): Promise<Result<void>> {
+      try {
+        await stripe.paymentIntents.cancel(paymentIntentId);
+        return Ok(undefined);
+      } catch (error) {
+        return Err({
+          code: "PAYMENT_CANCEL_FAILED",
+          message: error instanceof Error ? error.message : "Stripe cancellation failed.",
+        });
+      }
+    },
+
+    async verifyWebhook(request: Request): Promise<Result<PaymentWebhookEvent>> {
+      try {
+        if (!options.webhookSecret) {
+          return Err({
+            code: "WEBHOOK_SECRET_MISSING",
+            message: "Stripe webhook secret is not configured.",
+          });
+        }
+
+        const signature = request.headers.get("stripe-signature");
+        if (!signature) {
+          return Err({
+            code: "WEBHOOK_SIGNATURE_MISSING",
+            message: "Missing stripe-signature header.",
+          });
+        }
+
+        const body = await request.text();
+        const event = stripe.webhooks.constructEvent(body, signature, options.webhookSecret);
+
+        return Ok({
+          id: event.id,
+          type: event.type,
+          data: event.data.object,
+        });
+      } catch (error) {
+        return Err({
+          code: "WEBHOOK_VERIFICATION_FAILED",
+          message: error instanceof Error ? error.message : "Stripe webhook verification failed.",
+        });
+      }
+    },
+  };
+}