@flightdev/payments 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Flight Contributors
+
+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,323 @@
+# @flight-framework/payments
+
+Payment processing for Flight Framework. Unified API for Stripe, Paddle, and LemonSqueezy.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Adapters](#adapters)
+- [Checkout Sessions](#checkout-sessions)
+- [Subscriptions](#subscriptions)
+- [Webhooks](#webhooks)
+- [Customer Portal](#customer-portal)
+- [API Reference](#api-reference)
+- [License](#license)
+
+---
+
+## Features
+
+- Single API for multiple payment providers
+- Checkout session management
+- Subscription lifecycle handling
+- Webhook verification and parsing
+- Customer portal links
+- Type-safe event handling
+- Idempotency key support
+
+---
+
+## Installation
+
+```bash
+npm install @flight-framework/payments
+
+# Install your provider's SDK
+npm install stripe           # For Stripe
+npm install @paddle/paddle-node-sdk  # For Paddle
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { createPayments } from '@flight-framework/payments';
+import { stripe } from '@flight-framework/payments/stripe';
+
+const payments = createPayments(stripe({
+    secretKey: process.env.STRIPE_SECRET_KEY,
+    webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+}));
+
+// Create a checkout session
+const session = await payments.createCheckout({
+    items: [
+        { name: 'Pro Plan', price: 2999, quantity: 1 },
+    ],
+    successUrl: 'https://example.com/success',
+    cancelUrl: 'https://example.com/cancel',
+});
+
+// Redirect user to session.url
+```
+
+---
+
+## Adapters
+
+### Stripe
+
+Full-featured payment processing.
+
+```typescript
+import { stripe } from '@flight-framework/payments/stripe';
+
+const adapter = stripe({
+    secretKey: process.env.STRIPE_SECRET_KEY,
+    webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+    apiVersion: '2024-12-18.acacia',
+});
+```
+
+### Paddle
+
+Merchant of record for global sales.
+
+```typescript
+import { paddle } from '@flight-framework/payments/paddle';
+
+const adapter = paddle({
+    apiKey: process.env.PADDLE_API_KEY,
+    environment: 'sandbox',  // or 'production'
+    webhookSecret: process.env.PADDLE_WEBHOOK_SECRET,
+});
+```
+
+### LemonSqueezy
+
+Digital products and subscriptions.
+
+```typescript
+import { lemonsqueezy } from '@flight-framework/payments/lemonsqueezy';
+
+const adapter = lemonsqueezy({
+    apiKey: process.env.LEMON_SQUEEZY_API_KEY,
+    storeId: process.env.LEMON_SQUEEZY_STORE_ID,
+    webhookSecret: process.env.LEMON_SQUEEZY_WEBHOOK_SECRET,
+});
+```
+
+---
+
+## Checkout Sessions
+
+### One-Time Payment
+
+```typescript
+const session = await payments.createCheckout({
+    mode: 'payment',
+    items: [
+        { 
+            name: 'Flight Framework License',
+            price: 9900,  // $99.00 in cents
+            quantity: 1,
+        },
+    ],
+    successUrl: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
+    cancelUrl: 'https://example.com/cancel',
+    customerEmail: 'user@example.com',
+    metadata: {
+        userId: 'user_123',
+    },
+});
+```
+
+### Subscription Checkout
+
+```typescript
+const session = await payments.createCheckout({
+    mode: 'subscription',
+    items: [
+        { priceId: 'price_monthly_pro' },  // Use existing price ID
+    ],
+    successUrl: 'https://example.com/success',
+    cancelUrl: 'https://example.com/cancel',
+    trialDays: 14,
+});
+```
+
+### Custom Line Items
+
+```typescript
+const session = await payments.createCheckout({
+    items: [
+        { name: 'Consulting Hour', price: 15000, quantity: 2 },
+        { name: 'Setup Fee', price: 5000, quantity: 1 },
+    ],
+    allowPromoCodes: true,
+    collectBillingAddress: true,
+    collectShippingAddress: false,
+});
+```
+
+---
+
+## Subscriptions
+
+### Retrieve Subscription
+
+```typescript
+const subscription = await payments.getSubscription('sub_123');
+
+console.log(subscription.status);       // 'active'
+console.log(subscription.currentPeriodEnd);  // Date
+console.log(subscription.cancelAtPeriodEnd); // boolean
+```
+
+### Cancel Subscription
+
+```typescript
+// Cancel at period end
+await payments.cancelSubscription('sub_123', { 
+    immediately: false 
+});
+
+// Cancel immediately
+await payments.cancelSubscription('sub_123', { 
+    immediately: true 
+});
+```
+
+### Update Subscription
+
+```typescript
+await payments.updateSubscription('sub_123', {
+    priceId: 'price_yearly_pro',  // Upgrade/downgrade
+    prorationBehavior: 'create_prorations',
+});
+```
+
+---
+
+## Webhooks
+
+### Webhook Handler
+
+```typescript
+// src/routes/api/webhooks/payments.post.ts
+import { payments } from '~/lib/payments';
+
+export async function POST(request: Request) {
+    const payload = await request.text();
+    const signature = request.headers.get('stripe-signature');
+    
+    if (!signature) {
+        return new Response('Missing signature', { status: 400 });
+    }
+    
+    try {
+        const event = payments.verifyWebhook(payload, signature);
+        
+        switch (event.type) {
+            case 'checkout.session.completed':
+                await handleCheckoutComplete(event.data);
+                break;
+                
+            case 'customer.subscription.created':
+                await handleSubscriptionCreated(event.data);
+                break;
+                
+            case 'customer.subscription.updated':
+                await handleSubscriptionUpdated(event.data);
+                break;
+                
+            case 'customer.subscription.deleted':
+                await handleSubscriptionCanceled(event.data);
+                break;
+                
+            case 'invoice.payment_failed':
+                await handlePaymentFailed(event.data);
+                break;
+        }
+        
+        return new Response('OK', { status: 200 });
+    } catch (error) {
+        console.error('Webhook error:', error);
+        return new Response('Webhook error', { status: 400 });
+    }
+}
+```
+
+### Event Types
+
+| Event | Description |
+|-------|-------------|
+| `checkout.session.completed` | Checkout was successful |
+| `customer.subscription.created` | New subscription created |
+| `customer.subscription.updated` | Subscription changed |
+| `customer.subscription.deleted` | Subscription canceled |
+| `invoice.payment_failed` | Payment failed |
+| `invoice.paid` | Invoice was paid |
+
+---
+
+## Customer Portal
+
+Generate a link for customers to manage their subscriptions:
+
+```typescript
+const portalUrl = await payments.createPortalSession({
+    customerId: 'cus_123',
+    returnUrl: 'https://example.com/account',
+});
+
+// Redirect user to portalUrl
+```
+
+---
+
+## API Reference
+
+### createCheckout Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `mode` | `'payment' \| 'subscription'` | Checkout mode |
+| `items` | `LineItem[]` | Items to purchase |
+| `successUrl` | `string` | Redirect after success |
+| `cancelUrl` | `string` | Redirect on cancel |
+| `customerEmail` | `string` | Pre-fill email |
+| `customerId` | `string` | Existing customer ID |
+| `trialDays` | `number` | Subscription trial days |
+| `allowPromoCodes` | `boolean` | Enable promo codes |
+| `metadata` | `object` | Custom metadata |
+
+### LineItem
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | Item name (for one-time) |
+| `price` | `number` | Price in cents |
+| `priceId` | `string` | Existing price ID |
+| `quantity` | `number` | Quantity |
+
+### Subscription
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `string` | Subscription ID |
+| `status` | `string` | active, past_due, canceled |
+| `customerId` | `string` | Customer ID |
+| `priceId` | `string` | Price ID |
+| `currentPeriodStart` | `Date` | Period start |
+| `currentPeriodEnd` | `Date` | Period end |
+| `cancelAtPeriodEnd` | `boolean` | Will cancel at end |
+
+---
+
+## License
+
+MIT

package/dist/adapters/stripe.d.ts

@@ -0,0 +1,13 @@
+import { PaymentsAdapterFactory } from '../index.js';
+
+/**
+ * Stripe Adapter for @flightdev/payments
+ */
+
+interface StripeConfig {
+    secretKey: string;
+    webhookSecret?: string;
+}
+declare const stripe: PaymentsAdapterFactory<StripeConfig>;
+
+export { type StripeConfig, stripe as default, stripe };

package/dist/adapters/stripe.js

@@ -0,0 +1,97 @@
+// src/adapters/stripe.ts
+var stripe = (config) => {
+  let stripeClient = null;
+  async function getStripe() {
+    if (!stripeClient) {
+      try {
+        const Stripe = (await import("stripe")).default;
+        stripeClient = new Stripe(config.secretKey);
+      } catch {
+        throw new Error("@flightdev/payments: stripe not installed. Run: npm install stripe");
+      }
+    }
+    return stripeClient;
+  }
+  const adapter = {
+    name: "stripe",
+    async createCheckout(options) {
+      const stripe2 = await getStripe();
+      const session = await stripe2.checkout.sessions.create({
+        mode: options.mode ?? "payment",
+        line_items: options.items.map((item) => ({
+          price_data: {
+            currency: "usd",
+            unit_amount: item.price,
+            product_data: { name: item.name, description: item.description }
+          },
+          quantity: item.quantity
+        })),
+        success_url: options.successUrl,
+        cancel_url: options.cancelUrl,
+        customer_email: options.customerEmail,
+        customer: options.customerId,
+        metadata: options.metadata
+      });
+      return {
+        id: session.id,
+        url: session.url ?? "",
+        status: session.status === "complete" ? "complete" : "pending"
+      };
+    },
+    async getSession(sessionId) {
+      const stripe2 = await getStripe();
+      try {
+        const session = await stripe2.checkout.sessions.retrieve(sessionId);
+        return {
+          id: session.id,
+          url: session.url ?? "",
+          status: session.status === "complete" ? "complete" : "pending"
+        };
+      } catch {
+        return null;
+      }
+    },
+    async createCustomer(email, metadata) {
+      const stripe2 = await getStripe();
+      const customer = await stripe2.customers.create({ email, metadata });
+      return { id: customer.id, email: customer.email, name: customer.name ?? void 0, metadata: customer.metadata };
+    },
+    async getCustomer(customerId) {
+      const stripe2 = await getStripe();
+      try {
+        const customer = await stripe2.customers.retrieve(customerId);
+        return { id: customer.id, email: customer.email, name: customer.name ?? void 0, metadata: customer.metadata };
+      } catch {
+        return null;
+      }
+    },
+    async createSubscription(customerId, priceId) {
+      const stripe2 = await getStripe();
+      const sub = await stripe2.subscriptions.create({ customer: customerId, items: [{ price: priceId }] });
+      return {
+        id: sub.id,
+        customerId: sub.customer,
+        status: sub.status,
+        currentPeriodEnd: new Date(sub.current_period_end * 1e3),
+        priceId: sub.items.data[0]?.price.id ?? ""
+      };
+    },
+    async cancelSubscription(subscriptionId) {
+      const stripe2 = await getStripe();
+      await stripe2.subscriptions.cancel(subscriptionId);
+    },
+    verifyWebhook(payload, _signature) {
+      if (!config.webhookSecret) {
+        throw new Error("Webhook secret not configured");
+      }
+      const event = JSON.parse(payload);
+      return { id: event.id, type: event.type, data: event.data.object };
+    }
+  };
+  return adapter;
+};
+var stripe_default = stripe;
+export {
+  stripe_default as default,
+  stripe
+};

package/dist/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @flightdev/payments - Agnostic Payments Layer
+ *
+ * @example
+ * ```typescript
+ * import { createPayments } from '@flightdev/payments';
+ * import { stripe } from '@flightdev/payments/stripe';
+ *
+ * const payments = createPayments(stripe({
+ *   secretKey: process.env.STRIPE_SECRET_KEY,
+ * }));
+ *
+ * const session = await payments.createCheckout({
+ *   items: [{ name: 'Pro Plan', price: 2999, quantity: 1 }],
+ *   successUrl: '/success',
+ *   cancelUrl: '/cancel',
+ * });
+ * ```
+ */
+interface LineItem {
+    name: string;
+    price: number;
+    quantity: number;
+    description?: string;
+    image?: string;
+}
+interface CheckoutOptions {
+    items: LineItem[];
+    successUrl: string;
+    cancelUrl: string;
+    customerEmail?: string;
+    customerId?: string;
+    metadata?: Record<string, string>;
+    mode?: 'payment' | 'subscription';
+}
+interface CheckoutSession {
+    id: string;
+    url: string;
+    status: 'pending' | 'complete' | 'expired';
+}
+interface Customer {
+    id: string;
+    email: string;
+    name?: string;
+    metadata?: Record<string, string>;
+}
+interface Subscription {
+    id: string;
+    customerId: string;
+    status: 'active' | 'canceled' | 'past_due' | 'trialing';
+    currentPeriodEnd: Date;
+    priceId: string;
+}
+interface WebhookEvent {
+    id: string;
+    type: string;
+    data: unknown;
+}
+interface PaymentsAdapter {
+    readonly name: string;
+    createCheckout(options: CheckoutOptions): Promise<CheckoutSession>;
+    getSession(sessionId: string): Promise<CheckoutSession | null>;
+    createCustomer(email: string, metadata?: Record<string, string>): Promise<Customer>;
+    getCustomer(customerId: string): Promise<Customer | null>;
+    createSubscription(customerId: string, priceId: string): Promise<Subscription>;
+    cancelSubscription(subscriptionId: string): Promise<void>;
+    verifyWebhook(payload: string, signature: string): WebhookEvent;
+}
+type PaymentsAdapterFactory<TConfig = unknown> = (config: TConfig) => PaymentsAdapter;
+interface PaymentsService {
+    readonly adapter: PaymentsAdapter;
+    createCheckout(options: CheckoutOptions): Promise<CheckoutSession>;
+    getSession(sessionId: string): Promise<CheckoutSession | null>;
+    createCustomer(email: string, metadata?: Record<string, string>): Promise<Customer>;
+    getCustomer(customerId: string): Promise<Customer | null>;
+    createSubscription(customerId: string, priceId: string): Promise<Subscription>;
+    cancelSubscription(subscriptionId: string): Promise<void>;
+    handleWebhook(payload: string, signature: string): WebhookEvent;
+}
+declare function createPayments(adapter: PaymentsAdapter): PaymentsService;
+declare function formatCurrency(amount: number, currency: string, locale?: string): string;
+
+export { type CheckoutOptions, type CheckoutSession, type Customer, type LineItem, type PaymentsAdapter, type PaymentsAdapterFactory, type PaymentsService, type Subscription, type WebhookEvent, createPayments, formatCurrency };

package/dist/index.js

@@ -0,0 +1,23 @@
+// src/index.ts
+function createPayments(adapter) {
+  return {
+    adapter,
+    createCheckout: (options) => adapter.createCheckout(options),
+    getSession: (id) => adapter.getSession(id),
+    createCustomer: (email, meta) => adapter.createCustomer(email, meta),
+    getCustomer: (id) => adapter.getCustomer(id),
+    createSubscription: (customerId, priceId) => adapter.createSubscription(customerId, priceId),
+    cancelSubscription: (id) => adapter.cancelSubscription(id),
+    handleWebhook: (payload, signature) => adapter.verifyWebhook(payload, signature)
+  };
+}
+function formatCurrency(amount, currency, locale = "en-US") {
+  return new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency: currency.toUpperCase()
+  }).format(amount / 100);
+}
+export {
+  createPayments,
+  formatCurrency
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flightdev/payments",
+  "version": "0.0.2",
+  "description": "Agnostic payments layer for Flight Framework. Choose your processor: Stripe, Paddle, MercadoPago.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./stripe": {
+      "types": "./dist/adapters/stripe.d.ts",
+      "import": "./dist/adapters/stripe.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "stripe": ">=14.0.0"
+  },
+  "peerDependenciesMeta": {
+    "stripe": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.0.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}