@verevoir/stripe 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 verevoir
+
+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,86 @@
+# @verevoir/stripe
+
+Stripe payment adapter — checkout sessions, subscription management, webhook handling, and billing portal.
+
+Part of [Verevoir](https://verevoir.io) — a database-agnostic application platform.
+
+## Install
+
+```bash
+npm install @verevoir/stripe stripe
+```
+
+Requires `stripe` as a peer dependency (^17.0.0 || ^18.0.0).
+
+## Quick Start
+
+```typescript
+import Stripe from 'stripe';
+import { createStripeAdapter } from '@verevoir/stripe';
+
+const stripe = new Stripe('sk_test_...');
+const adapter = createStripeAdapter({
+  client: stripe,
+  webhookSecret: 'whsec_...',
+});
+
+// Create a checkout session
+const session = await adapter.createCheckoutSession({
+  priceId: 'price_pro_monthly',
+  customerEmail: 'alice@example.com',
+  successUrl: 'https://app.com/success',
+  cancelUrl: 'https://app.com/cancel',
+});
+// Redirect to session.url
+
+// Handle webhooks
+const event = adapter.parseWebhookEvent(body, signature);
+if (event.type === 'customer.subscription.updated') {
+  // Sync subscription state
+}
+```
+
+## API
+
+### Adapter
+
+| Method                                  | Description                                       |
+| --------------------------------------- | ------------------------------------------------- |
+| `createCheckoutSession(options)`        | Create a Stripe Checkout session for subscription |
+| `createPortalSession(options)`          | Create a Stripe Billing Portal session            |
+| `createCustomer(email, metadata?)`      | Create a Stripe customer                          |
+| `cancelSubscription(subscriptionId)`    | Cancel a subscription                             |
+| `parseWebhookEvent(payload, signature)` | Parse and verify a webhook event                  |
+
+### Webhook Events
+
+| Event Type                      | Fields                                                                                               |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `checkout.session.completed`    | `customerId`, `subscriptionId`, `metadata`                                                           |
+| `customer.subscription.updated` | `subscriptionId`, `status`, `currentPeriodStart`, `currentPeriodEnd`, `priceId`, `cancelAtPeriodEnd` |
+| `customer.subscription.deleted` | `subscriptionId`                                                                                     |
+| `invoice.payment_failed`        | `subscriptionId`, `customerId`                                                                       |
+| `unknown`                       | `rawType`                                                                                            |
+
+## Design
+
+- Consumer owns the Stripe client — adapter does not manage API keys
+- Stripe is source of truth for subscription state
+- Focused on subscription billing (not one-off payments)
+
+## Documentation
+
+- [Verevoir Packages](https://verevoir.io/packages)
+- [Commerce Guide](https://verevoir.io/docs/commerce)
+
+## Development
+
+```bash
+make build   # Compile TypeScript
+make test    # Run test suite
+make lint    # Lint and check formatting
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,123 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createStripeAdapter: () => createStripeAdapter
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/adapter.ts
+function createStripeAdapter(options) {
+  const { client, webhookSecret } = options;
+  return {
+    async createCheckoutSession(opts) {
+      const params = {
+        mode: "subscription",
+        line_items: [{ price: opts.priceId, quantity: 1 }],
+        success_url: opts.successUrl,
+        cancel_url: opts.cancelUrl
+      };
+      if (opts.customerId) {
+        params.customer = opts.customerId;
+      } else if (opts.customerEmail) {
+        params.customer_email = opts.customerEmail;
+      }
+      if (opts.metadata) {
+        params.metadata = opts.metadata;
+      }
+      const session = await client.checkout.sessions.create(params);
+      return {
+        sessionId: session.id,
+        url: session.url
+      };
+    },
+    async createPortalSession(opts) {
+      const session = await client.billingPortal.sessions.create({
+        customer: opts.customerId,
+        return_url: opts.returnUrl
+      });
+      return { url: session.url };
+    },
+    async createCustomer(email, metadata) {
+      const customer = await client.customers.create({
+        email,
+        ...metadata && { metadata }
+      });
+      return customer.id;
+    },
+    async cancelSubscription(subscriptionId) {
+      await client.subscriptions.cancel(subscriptionId);
+    },
+    parseWebhookEvent(payload, signature) {
+      const event = client.webhooks.constructEvent(
+        payload,
+        signature,
+        webhookSecret
+      );
+      switch (event.type) {
+        case "checkout.session.completed": {
+          const session = event.data.object;
+          return {
+            type: "checkout.session.completed",
+            customerId: session.customer,
+            subscriptionId: session.subscription,
+            metadata: session.metadata ?? {}
+          };
+        }
+        case "customer.subscription.updated": {
+          const sub = event.data.object;
+          const item = sub.items.data[0];
+          return {
+            type: "customer.subscription.updated",
+            subscriptionId: sub.id,
+            status: sub.status,
+            currentPeriodStart: item?.current_period_start ?? 0,
+            currentPeriodEnd: item?.current_period_end ?? 0,
+            priceId: item?.price?.id ?? "",
+            cancelAtPeriodEnd: sub.cancel_at_period_end
+          };
+        }
+        case "customer.subscription.deleted": {
+          const sub = event.data.object;
+          return {
+            type: "customer.subscription.deleted",
+            subscriptionId: sub.id
+          };
+        }
+        case "invoice.payment_failed": {
+          const invoice = event.data.object;
+          const subDetails = invoice.parent?.subscription_details;
+          return {
+            type: "invoice.payment_failed",
+            subscriptionId: subDetails?.subscription ? typeof subDetails.subscription === "string" ? subDetails.subscription : subDetails.subscription.id : "",
+            customerId: typeof invoice.customer === "string" ? invoice.customer : invoice.customer?.id ?? ""
+          };
+        }
+        default:
+          return { type: "unknown", rawType: event.type };
+      }
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createStripeAdapter
+});

package/dist/index.d.cts

@@ -0,0 +1,91 @@
+import Stripe from 'stripe';
+
+/** Structural Money type — compatible with @verevoir/commerce Money. */
+interface Money {
+    readonly amount: number;
+    readonly currency: string;
+}
+/** A plan that maps to a Stripe Price. */
+interface PlanMapping {
+    readonly planId: string;
+    readonly stripePriceId: string;
+}
+/** Checkout session configuration. */
+interface CheckoutOptions {
+    /** Stripe customer ID. Created automatically if not provided. */
+    readonly customerId?: string;
+    /** Customer email — used if creating a new Stripe customer. */
+    readonly customerEmail?: string;
+    /** Stripe Price ID to subscribe to. */
+    readonly priceId: string;
+    /** URL to redirect on success. */
+    readonly successUrl: string;
+    /** URL to redirect on cancel. */
+    readonly cancelUrl: string;
+    /** Optional metadata to attach to the Stripe session. */
+    readonly metadata?: Record<string, string>;
+}
+/** Result of creating a checkout session. */
+interface CheckoutSession {
+    readonly sessionId: string;
+    readonly url: string;
+}
+/** Billing portal configuration. */
+interface PortalOptions {
+    readonly customerId: string;
+    readonly returnUrl: string;
+}
+/** Result of creating a billing portal session. */
+interface PortalSession {
+    readonly url: string;
+}
+/** Parsed webhook event — the subset of Stripe events we handle. */
+type WebhookEvent = {
+    type: 'checkout.session.completed';
+    customerId: string;
+    subscriptionId: string;
+    metadata: Record<string, string>;
+} | {
+    type: 'customer.subscription.updated';
+    subscriptionId: string;
+    status: string;
+    currentPeriodStart: number;
+    currentPeriodEnd: number;
+    priceId: string;
+    cancelAtPeriodEnd: boolean;
+} | {
+    type: 'customer.subscription.deleted';
+    subscriptionId: string;
+} | {
+    type: 'invoice.payment_failed';
+    subscriptionId: string;
+    customerId: string;
+} | {
+    type: 'unknown';
+    rawType: string;
+};
+/** The adapter interface — everything a consumer needs from Stripe. */
+interface StripeAdapter {
+    createCheckoutSession(options: CheckoutOptions): Promise<CheckoutSession>;
+    createPortalSession(options: PortalOptions): Promise<PortalSession>;
+    createCustomer(email: string, metadata?: Record<string, string>): Promise<string>;
+    cancelSubscription(subscriptionId: string): Promise<void>;
+    parseWebhookEvent(payload: string | Buffer, signature: string): WebhookEvent;
+}
+
+interface CreateStripeAdapterOptions {
+    /** Configured Stripe SDK instance. Consumer creates this with their API key. */
+    client: Stripe;
+    /** Webhook endpoint secret for signature verification. */
+    webhookSecret: string;
+}
+/**
+ * Create a Stripe adapter wrapping the Stripe SDK.
+ *
+ * The consumer provides a configured Stripe client — this adapter does not
+ * manage API keys. It provides the operations needed for subscription billing:
+ * checkout, portal, customer management, and webhook parsing.
+ */
+declare function createStripeAdapter(options: CreateStripeAdapterOptions): StripeAdapter;
+
+export { type CheckoutOptions, type CheckoutSession, type CreateStripeAdapterOptions, type Money, type PlanMapping, type PortalOptions, type PortalSession, type StripeAdapter, type WebhookEvent, createStripeAdapter };

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+import Stripe from 'stripe';
+
+/** Structural Money type — compatible with @verevoir/commerce Money. */
+interface Money {
+    readonly amount: number;
+    readonly currency: string;
+}
+/** A plan that maps to a Stripe Price. */
+interface PlanMapping {
+    readonly planId: string;
+    readonly stripePriceId: string;
+}
+/** Checkout session configuration. */
+interface CheckoutOptions {
+    /** Stripe customer ID. Created automatically if not provided. */
+    readonly customerId?: string;
+    /** Customer email — used if creating a new Stripe customer. */
+    readonly customerEmail?: string;
+    /** Stripe Price ID to subscribe to. */
+    readonly priceId: string;
+    /** URL to redirect on success. */
+    readonly successUrl: string;
+    /** URL to redirect on cancel. */
+    readonly cancelUrl: string;
+    /** Optional metadata to attach to the Stripe session. */
+    readonly metadata?: Record<string, string>;
+}
+/** Result of creating a checkout session. */
+interface CheckoutSession {
+    readonly sessionId: string;
+    readonly url: string;
+}
+/** Billing portal configuration. */
+interface PortalOptions {
+    readonly customerId: string;
+    readonly returnUrl: string;
+}
+/** Result of creating a billing portal session. */
+interface PortalSession {
+    readonly url: string;
+}
+/** Parsed webhook event — the subset of Stripe events we handle. */
+type WebhookEvent = {
+    type: 'checkout.session.completed';
+    customerId: string;
+    subscriptionId: string;
+    metadata: Record<string, string>;
+} | {
+    type: 'customer.subscription.updated';
+    subscriptionId: string;
+    status: string;
+    currentPeriodStart: number;
+    currentPeriodEnd: number;
+    priceId: string;
+    cancelAtPeriodEnd: boolean;
+} | {
+    type: 'customer.subscription.deleted';
+    subscriptionId: string;
+} | {
+    type: 'invoice.payment_failed';
+    subscriptionId: string;
+    customerId: string;
+} | {
+    type: 'unknown';
+    rawType: string;
+};
+/** The adapter interface — everything a consumer needs from Stripe. */
+interface StripeAdapter {
+    createCheckoutSession(options: CheckoutOptions): Promise<CheckoutSession>;
+    createPortalSession(options: PortalOptions): Promise<PortalSession>;
+    createCustomer(email: string, metadata?: Record<string, string>): Promise<string>;
+    cancelSubscription(subscriptionId: string): Promise<void>;
+    parseWebhookEvent(payload: string | Buffer, signature: string): WebhookEvent;
+}
+
+interface CreateStripeAdapterOptions {
+    /** Configured Stripe SDK instance. Consumer creates this with their API key. */
+    client: Stripe;
+    /** Webhook endpoint secret for signature verification. */
+    webhookSecret: string;
+}
+/**
+ * Create a Stripe adapter wrapping the Stripe SDK.
+ *
+ * The consumer provides a configured Stripe client — this adapter does not
+ * manage API keys. It provides the operations needed for subscription billing:
+ * checkout, portal, customer management, and webhook parsing.
+ */
+declare function createStripeAdapter(options: CreateStripeAdapterOptions): StripeAdapter;
+
+export { type CheckoutOptions, type CheckoutSession, type CreateStripeAdapterOptions, type Money, type PlanMapping, type PortalOptions, type PortalSession, type StripeAdapter, type WebhookEvent, createStripeAdapter };

package/dist/index.js

@@ -0,0 +1,96 @@
+// src/adapter.ts
+function createStripeAdapter(options) {
+  const { client, webhookSecret } = options;
+  return {
+    async createCheckoutSession(opts) {
+      const params = {
+        mode: "subscription",
+        line_items: [{ price: opts.priceId, quantity: 1 }],
+        success_url: opts.successUrl,
+        cancel_url: opts.cancelUrl
+      };
+      if (opts.customerId) {
+        params.customer = opts.customerId;
+      } else if (opts.customerEmail) {
+        params.customer_email = opts.customerEmail;
+      }
+      if (opts.metadata) {
+        params.metadata = opts.metadata;
+      }
+      const session = await client.checkout.sessions.create(params);
+      return {
+        sessionId: session.id,
+        url: session.url
+      };
+    },
+    async createPortalSession(opts) {
+      const session = await client.billingPortal.sessions.create({
+        customer: opts.customerId,
+        return_url: opts.returnUrl
+      });
+      return { url: session.url };
+    },
+    async createCustomer(email, metadata) {
+      const customer = await client.customers.create({
+        email,
+        ...metadata && { metadata }
+      });
+      return customer.id;
+    },
+    async cancelSubscription(subscriptionId) {
+      await client.subscriptions.cancel(subscriptionId);
+    },
+    parseWebhookEvent(payload, signature) {
+      const event = client.webhooks.constructEvent(
+        payload,
+        signature,
+        webhookSecret
+      );
+      switch (event.type) {
+        case "checkout.session.completed": {
+          const session = event.data.object;
+          return {
+            type: "checkout.session.completed",
+            customerId: session.customer,
+            subscriptionId: session.subscription,
+            metadata: session.metadata ?? {}
+          };
+        }
+        case "customer.subscription.updated": {
+          const sub = event.data.object;
+          const item = sub.items.data[0];
+          return {
+            type: "customer.subscription.updated",
+            subscriptionId: sub.id,
+            status: sub.status,
+            currentPeriodStart: item?.current_period_start ?? 0,
+            currentPeriodEnd: item?.current_period_end ?? 0,
+            priceId: item?.price?.id ?? "",
+            cancelAtPeriodEnd: sub.cancel_at_period_end
+          };
+        }
+        case "customer.subscription.deleted": {
+          const sub = event.data.object;
+          return {
+            type: "customer.subscription.deleted",
+            subscriptionId: sub.id
+          };
+        }
+        case "invoice.payment_failed": {
+          const invoice = event.data.object;
+          const subDetails = invoice.parent?.subscription_details;
+          return {
+            type: "invoice.payment_failed",
+            subscriptionId: subDetails?.subscription ? typeof subDetails.subscription === "string" ? subDetails.subscription : subDetails.subscription.id : "",
+            customerId: typeof invoice.customer === "string" ? invoice.customer : invoice.customer?.id ?? ""
+          };
+        }
+        default:
+          return { type: "unknown", rawType: event.type };
+      }
+    }
+  };
+}
+export {
+  createStripeAdapter
+};

package/llms.txt

@@ -0,0 +1,89 @@
+# @verevoir/stripe
+
+> Stripe payment adapter — checkout sessions, subscription management, webhook handling, and billing portal. Wraps the Stripe SDK with a focused interface for subscription billing.
+
+## Install
+
+```bash
+npm install @verevoir/stripe stripe
+```
+
+## Core Exports
+
+### Stripe Adapter
+
+```typescript
+import Stripe from 'stripe';
+import { createStripeAdapter } from '@verevoir/stripe';
+
+const stripe = new Stripe('sk_test_...');
+const adapter = createStripeAdapter({
+  client: stripe,
+  webhookSecret: 'whsec_...',
+});
+
+// Create checkout session for subscription
+const session = await adapter.createCheckoutSession({
+  priceId: 'price_pro_monthly',
+  customerEmail: 'alice@example.com',
+  successUrl: 'https://app.com/success',
+  cancelUrl: 'https://app.com/cancel',
+  metadata: { accountId: 'acc_123' },
+});
+// Redirect to session.url
+
+// Create billing portal session
+const portal = await adapter.createPortalSession({
+  customerId: 'cus_123',
+  returnUrl: 'https://app.com/settings',
+});
+
+// Create customer
+const customerId = await adapter.createCustomer('alice@example.com', { accountId: 'acc_1' });
+
+// Cancel subscription
+await adapter.cancelSubscription('sub_123');
+```
+
+### Webhook Handling
+
+```typescript
+// In your webhook endpoint
+const event = adapter.parseWebhookEvent(requestBody, stripeSignature);
+
+switch (event.type) {
+  case 'checkout.session.completed':
+    // event.customerId, event.subscriptionId, event.metadata
+    break;
+  case 'customer.subscription.updated':
+    // event.subscriptionId, event.status, event.currentPeriodStart, event.currentPeriodEnd, event.priceId
+    break;
+  case 'customer.subscription.deleted':
+    // event.subscriptionId
+    break;
+  case 'invoice.payment_failed':
+    // event.subscriptionId, event.customerId
+    break;
+  case 'unknown':
+    // event.rawType — unhandled Stripe event
+    break;
+}
+```
+
+## Types
+
+```typescript
+interface StripeAdapter {
+  createCheckoutSession(options: CheckoutOptions): Promise<CheckoutSession>;
+  createPortalSession(options: PortalOptions): Promise<PortalSession>;
+  createCustomer(email: string, metadata?: Record<string, string>): Promise<string>;
+  cancelSubscription(subscriptionId: string): Promise<void>;
+  parseWebhookEvent(payload: string | Buffer, signature: string): WebhookEvent;
+}
+```
+
+## Constraints
+
+- Peer dependency: `stripe` (^17.0.0 || ^18.0.0)
+- Consumer provides configured Stripe SDK instance
+- Stripe is source of truth for subscription state

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@verevoir/stripe",
+  "version": "0.1.0-alpha.1",
+  "description": "Stripe payment adapter — checkout, subscriptions, webhooks, and billing portal",
+  "homepage": "https://verevoir.io",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "llms.txt"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com:verevoir/stripe.git"
+  },
+  "funding": "https://buymeacoffee.com/verevoir",
+  "scripts": {
+    "build": "tsup",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write ."
+  },
+  "peerDependencies": {
+    "stripe": "^17.0.0 || ^18.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.1",
+    "@types/node": "^22.0.0",
+    "stripe": "^18.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.1",
+    "vitest": "^3.2.4"
+  }
+}