@flink-app/stripe-plugin 0.12.1-alpha.4 → 0.12.1-alpha.44

package/.flink/generatedHandlers.ts

@@ -1,4 +1,4 @@
-// Generated Thu Mar 20 2025 15:57:52 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 23 2025 14:20:59 GMT+0100 (Central European Standard Time)
 import { autoRegisteredHandlers, HttpMethod } from "@flink-app/flink";
 import * as HandlebarsTemplateHandler_0 from "../src/handlers/HandlebarsTemplateHandler";
 

package/.flink/generatedJobs.ts

@@ -1,4 +1,4 @@
-// Generated Thu Mar 20 2025 15:57:52 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 23 2025 14:20:59 GMT+0100 (Central European Standard Time)
 import { autoRegisteredJobs } from "@flink-app/flink";
 export const jobs = [];
 autoRegisteredJobs.push(...jobs);

package/.flink/generatedRepos.ts

@@ -1,4 +1,4 @@
-// Generated Thu Mar 20 2025 15:57:52 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 23 2025 14:20:59 GMT+0100 (Central European Standard Time)
   import { autoRegisteredRepos } from "@flink-app/flink";
   export const repos = [];
   autoRegisteredRepos.push(...repos);

package/.flink/schemas/schemas.ts

@@ -1 +1 @@
-// Generated Thu Mar 20 2025 15:57:52 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 23 2025 14:20:59 GMT+0100 (Central European Standard Time)

package/.flink/start.ts

@@ -1,5 +1,6 @@
-// Generated Thu Mar 20 2025 15:57:52 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 23 2025 14:20:59 GMT+0100 (Central European Standard Time)
 import "./generatedHandlers";
 import "./generatedRepos";
 import "./generatedJobs";
 import "../src/index";
+export default {}; // Export an empty object to make it a module

package/dist/.flink/generatedHandlers.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handlers = void 0;
-// Generated Thu Mar 20 2025 15:57:52 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 23 2025 14:20:59 GMT+0100 (Central European Standard Time)
 var flink_1 = require("@flink-app/flink");
 exports.handlers = [];
 flink_1.autoRegisteredHandlers.push.apply(flink_1.autoRegisteredHandlers, exports.handlers);

package/dist/.flink/generatedJobs.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.jobs = void 0;
-// Generated Thu Mar 20 2025 15:57:52 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 23 2025 14:20:59 GMT+0100 (Central European Standard Time)
 var flink_1 = require("@flink-app/flink");
 exports.jobs = [];
 flink_1.autoRegisteredJobs.push.apply(flink_1.autoRegisteredJobs, exports.jobs);

package/dist/.flink/generatedRepos.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.repos = void 0;
-// Generated Thu Mar 20 2025 15:57:52 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 23 2025 14:20:59 GMT+0100 (Central European Standard Time)
 var flink_1 = require("@flink-app/flink");
 exports.repos = [];
 flink_1.autoRegisteredRepos.push.apply(flink_1.autoRegisteredRepos, exports.repos);

package/dist/.flink/schemas/schemas.js

@@ -1,2 +1,2 @@
 "use strict";
-// Generated Thu Mar 20 2025 15:57:52 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 23 2025 14:20:59 GMT+0100 (Central European Standard Time)

package/dist/.flink/start.d.ts

@@ -2,3 +2,5 @@ import "./generatedHandlers";
 import "./generatedRepos";
 import "./generatedJobs";
 import "../src/index";
+declare const _default: {};
+export default _default;

package/dist/.flink/start.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-// Generated Thu Mar 20 2025 15:57:52 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 23 2025 14:20:59 GMT+0100 (Central European Standard Time)
 require("./generatedHandlers");
 require("./generatedRepos");
 require("./generatedJobs");
 require("../src/index");
+exports.default = {}; // Export an empty object to make it a module

package/package.json

@@ -1,11 +1,11 @@
 {
     "name": "@flink-app/stripe-plugin",
-    "version": "0.12.1-alpha.4",
+    "version": "0.12.1-alpha.44",
     "description": "Flink plugin to work with stripe payments",
     "scripts": {
         "test": "echo \"Error: no test specified\"",
         "build": "flink build",
-        "prepublish": "npm run build",
+        "prepare": "npm run build",
         "watch": "nodemon --exec \"flink build\""
     },
     "author": "johan@frost.se",
@@ -24,7 +24,7 @@
         "stripe": "^8.186.1"
     },
     "devDependencies": {
-        "@flink-app/flink": "^0.12.1-alpha.4",
+        "@flink-app/flink": "^0.12.1-alpha.44",
         "@types/bcrypt": "^5.0.0",
         "@types/express": "4.17.11",
         "@types/express-fileupload": "^1.1.7",
@@ -33,5 +33,5 @@
         "ts-node": "^9.1.1",
         "typescript": "5.4.5"
     },
-    "gitHead": "8f06a4ab98e7179322d36546756d4305fd196f5a"
+    "gitHead": "4243e3b3cd6d4e1ca001a61baa8436bf2bbe4113"
 }

package/readme.md

@@ -1,51 +1,390 @@
-# Flink API Docs
+# @flink-app/stripe-plugin
 
-**WORK IN PROGRESS 👷‍♀️👷🏻‍♂️**
+A comprehensive Flink plugin for integrating Stripe payment processing, including customer management, payment intents, card setup, and Stripe Connect functionality. The plugin provides both API methods and hosted UI pages for payment flows.
 
-A FLINK plugin that lets you expose management api:s for other plugins.
+## Features
 
-Other plugins must be able to generate a ManagementApiModule that can be registered with this plugin to expose management apis.
+- Customer creation and management
+- Payment intent creation and confirmation
+- Card setup with hosted UI
+- Payment capture for authorized payments
+- Stripe Connect integration
+- Pre-built, customizable payment UI templates
+- JWT-based secure token system
+- MongoDB-backed session management
+- Webhook callback support
+- Full TypeScript support
 
-## Usage
-
-Install plugin to your flink app project:
+## Installation
 
-```
-npm i -S @flink-app/management-api-plugin
+```bash
+npm install @flink-app/stripe-plugin
 ```
 
-Add and configure plugin in your app startup (probable the `index.ts` in root project):
+## Usage
 
-```
-import { managementApiPlugin } from "@flink-app/management-api-plugin";
+### Basic Setup
 
+```typescript
+import { FlinkApp } from "@flink-app/flink";
+import { stripePlugin } from "@flink-app/stripe-plugin";
 
 function start() {
   new FlinkApp<AppContext>({
     name: "My app",
     plugins: [
-        // Register plugin
-        managementApiPlugin({
-          token : "SECRET_TOKEN_USED_TO_COMMUNICATE_WITH_THE_API",
-          jwtSecret : "JWT_SECRET_USED_TO_GENERATE_LOGGED_IN_TOKENS",
-          modules : []
-        })
+      stripePlugin({
+        stripeSecreteKey: process.env.STRIPE_SECRET_KEY!,
+        stripePublishableKey: process.env.STRIPE_PUBLISHABLE_KEY!,
+        JTW_TOKEN: process.env.JWT_SECRET!,
+        baseUrl: "/stripe", // optional, defaults to /stripe
+        redirectUrl: "https://yourapp.com/success", // Where to redirect after successful operations
+        logo: "https://yourapp.com/logo.png", // Optional logo for payment pages
+        stripeConnectClientID: process.env.STRIPE_CONNECT_CLIENT_ID, // For Stripe Connect
+        paymentCallback: (paymentIntentId, status) => {
+          // Handle successful payments
+          console.log(`Payment ${paymentIntentId} status: ${status}`);
+        },
+        stripeConnectCallback: (userId, stripeAccountId) => {
+          // Handle Stripe Connect account linking
+          console.log(`User ${userId} connected to Stripe account ${stripeAccountId}`);
+        },
+        phrases: {
+          setupDescription: "Add your payment card",
+          setupButtonText: "Save Card",
+          setupDoneMessage: "Your card has been saved successfully",
+          paymentSelectCardPayButtonText: "Pay",
+          paymentSelectCardChangeCardButtonText: "Change Card",
+          paymentEnterCardPayButtonText: "Pay",
+          connectDoneMessage: "Your account has been connected to Stripe",
+        },
+      }),
     ],
   }).start();
 }
 ```
 
-## Communicating with the management api
+### Add Plugin Context to Your Application
+
+```typescript
+import { stripePluginContext } from "@flink-app/stripe-plugin";
+
+export interface AppContext extends FlinkContext<stripePluginContext> {
+  repos: {
+    // your repos
+  };
+}
+```
+
+## Configuration Options
+
+- `stripeSecreteKey` (required): Your Stripe secret API key
+- `stripePublishableKey` (required): Your Stripe publishable API key
+- `JTW_TOKEN` (required): Secret for JWT token generation
+- `baseUrl` (optional): Base URL for plugin routes (defaults to `/stripe`)
+- `redirectUrl` (optional): URL to redirect users after successful operations
+- `logo` (optional): Logo URL to display on payment pages
+- `stripeConnectClientID` (optional): Client ID for Stripe Connect integration
+- `paymentCallback` (optional): Function called when payment succeeds
+- `stripeConnectCallback` (optional): Function called when Stripe Connect linking succeeds
+- `phrases` (optional): Customize UI text for different languages
+- `templates` (optional): Override default Handlebars templates for payment pages
+
+## API Usage
+
+### Customer Management
+
+#### Create Customer
+
+```typescript
+const customerId = await ctx.plugins.stripePlugin.stripeAPI.customer.create({
+  email: "customer@example.com",
+  name: "John Doe",
+  metadata: {
+    userId: "user123",
+  },
+});
+```
+
+#### Check if Customer Has Payment Method
+
+```typescript
+const hasCard = await ctx.plugins.stripePlugin.stripeAPI.customer.hasPaymentMethod({
+  stripeCustomerId: "cus_xxxxx",
+});
+```
+
+#### Setup Card Registration
+
+```typescript
+const { token, redirectUrl } = await ctx.plugins.stripePlugin.stripeAPI.customer.setupCard({
+  stripeCustomerId: "cus_xxxxx",
+});
+
+// Redirect user to redirectUrl to complete card setup
+// Example: https://yourapp.com/stripe/customer/setup-card/JWT_TOKEN
+```
+
+#### Connect to Stripe Connect
+
+```typescript
+const connectUrl = await ctx.plugins.stripePlugin.stripeAPI.customer.connectToStripeConnect({
+  userId: "user123",
+});
+
+// Redirect user to connectUrl to link their Stripe Connect account
+```
+
+### Payment Processing
+
+#### Create Payment Intent
+
+```typescript
+const payment = await ctx.plugins.stripePlugin.stripeAPI.payment.create({
+  amount: 5000, // Amount in cents ($50.00)
+  currency: "usd",
+  customer: "cus_xxxxx",
+  description: "Order #12345",
+  capture_method: "automatic", // or "manual" for authorization only
+  metadata: {
+    orderId: "order_12345",
+  },
+});
+
+// payment.token - JWT token for payment confirmation
+// payment.paymentUrl - URL to redirect user for payment
+// payment.paymentIntentId - Stripe payment intent ID
+```
+
+#### Confirm Payment
+
+```typescript
+const result = await ctx.plugins.stripePlugin.stripeAPI.payment.confirm({
+  paymentIntentId: "pi_xxxxx",
+});
+
+// result.confirmed - true if payment was confirmed
+// result.captured - true if payment was captured (only for automatic capture)
+// result.token - JWT token if additional action needed
+// result.redirectUrl - URL to redirect user if additional action needed
+```
+
+#### Create and Confirm Payment (Combined)
+
+```typescript
+const result = await ctx.plugins.stripePlugin.stripeAPI.payment.createAndConfirm({
+  amount: 5000,
+  currency: "usd",
+  customer: "cus_xxxxx",
+  description: "Order #12345",
+});
+```
+
+#### Capture Authorized Payment
+
+For payments created with `capture_method: "manual"`:
+
+```typescript
+const captured = await ctx.plugins.stripePlugin.stripeAPI.payment.capture({
+  paymentIntentId: "pi_xxxxx",
+  amount: 5000, // Optional: partial capture amount
+});
+```
+
+## Hosted Payment Flow
+
+The plugin provides pre-built, secure payment pages:
+
+### Card Setup Flow
+
+1. Generate setup URL:
+```typescript
+const { redirectUrl } = await ctx.plugins.stripePlugin.stripeAPI.customer.setupCard({
+  stripeCustomerId: "cus_xxxxx",
+});
+```
+
+2. Redirect user to `redirectUrl`
+3. User enters card details on hosted page
+4. User is redirected to your `redirectUrl` upon completion
+
+### Payment Flow
+
+1. Create payment intent:
+```typescript
+const { paymentUrl } = await ctx.plugins.stripePlugin.stripeAPI.payment.create({
+  amount: 5000,
+  currency: "usd",
+  customer: "cus_xxxxx",
+});
+```
+
+2. Redirect user to `paymentUrl`
+3. Plugin automatically detects if customer has saved cards
+4. Shows appropriate UI (select saved card or enter new card)
+5. Processes payment and redirects to your `redirectUrl`
+
+## API Routes
+
+The plugin automatically registers these routes:
+
+- `GET /stripe/customer/setup-card/:token` - Card setup page
+- `GET /stripe/customer/setup-card-done` - Success page after card setup
+- `GET /stripe/payment/confirm/:token` - Payment confirmation flow entry
+- `GET /stripe/payment/select-card/:token` - Select from saved cards
+- `GET /stripe/payment/enter-card/:token` - Enter new card details
+- `GET /stripe/error` - Error page
+- `POST /stripe/callback/:event` - Webhook for payment status updates
+- `GET /stripe/connect` - Stripe Connect OAuth callback
+
+## Webhooks
+
+Configure Stripe webhooks to point to:
+```
+POST https://yourapp.com/stripe/callback/charge.succeeded
+```
+
+The `paymentCallback` function will be invoked when payments succeed:
+
+```typescript
+paymentCallback: async (paymentIntentId, status) => {
+  // Update order status in database
+  await ctx.repos.orderRepo.updateByPaymentId(paymentIntentId, {
+    status: status === "succeeded" ? "paid" : "authorized",
+  });
+}
+```
+
+## Stripe Connect Integration
+
+Enable users to receive payments through Stripe Connect:
+
+1. Configure `stripeConnectClientID` in plugin options
+2. Generate connect URL:
+```typescript
+const url = await ctx.plugins.stripePlugin.stripeAPI.customer.connectToStripeConnect({
+  userId: "user123",
+});
+```
+3. Redirect user to `url`
+4. User completes Stripe Connect onboarding
+5. `stripeConnectCallback` is invoked with their Stripe account ID
+
+## Customization
+
+### Custom Templates
+
+Override default payment page templates:
+
+```typescript
+stripePlugin({
+  // ... other options
+  templates: {
+    master: customMasterTemplate,
+    style: customStyleTemplate,
+    setupCard: customSetupCardTemplate,
+    setupDone: customSetupDoneTemplate,
+    error: customErrorTemplate,
+    paySelectCard: customPaySelectCardTemplate,
+    payEnterCard: customPayEnterCardTemplate,
+    connectDone: customConnectDoneTemplate,
+  },
+});
+```
+
+Templates use Handlebars syntax.
+
+### Custom Phrases
+
+Customize text for different languages or branding:
+
+```typescript
+phrases: {
+  setupDescription: "Lägg till ditt kort",
+  setupButtonText: "Spara",
+  setupDoneMessage: "Kortet har sparats",
+  paymentSelectCardPayButtonText: "Betala",
+  paymentSelectCardChangeCardButtonText: "Byt kort",
+  paymentEnterCardPayButtonText: "Betala",
+  connectDoneMessage: "Kontot har kopplats",
+}
+```
+
+## Database Requirements
+
+This plugin requires MongoDB to be configured for Stripe Connect session management. The plugin automatically creates a `ConnectSessionRepo` repository.
+
+## Security Notes
+
+- Never expose your `stripeSecreteKey` in client-side code
+- Store all secrets in environment variables
+- Use the JWT token system for secure payment URLs
+- Validate webhook signatures in production (enhance `paymentCallback` with signature verification)
+- Use HTTPS in production for all payment flows
+
+## Testing
 
-To work with the management api you must in the http header `management-token` send either the `token` specified when register the plugin or a user login token.
+Use Stripe test mode credentials during development:
+- Test secret key: `sk_test_...`
+- Test publishable key: `pk_test_...`
+- Use Stripe's test card numbers
 
-The management API have it's own users system, where you might add, edit or remove management users.
+## Error Handling
 
-To create a first user to your management api make a POST request to /managementapi/managementapiuser with http-header management-token set to the specified token.
+All API methods throw errors that should be caught and handled:
 
+```typescript
+try {
+  const payment = await ctx.plugins.stripePlugin.stripeAPI.payment.create({
+    amount: 5000,
+    currency: "usd",
+    customer: "cus_xxxxx",
+  });
+} catch (error) {
+  console.error("Payment creation failed:", error);
+  // Handle error appropriately
+}
 ```
-curl 'https://URL-TO-YOUR-API/managementapi/managementapiuser' \
-    -H 'management-token: SECRET_TOKEN_USED_TO_COMMUNICATE_WITH_THE_API' \
-  -H 'Content-Type: application/json;charset=UTF-8' \
-  --data-raw '{"username":"test","password":"test"}'
+
+## TypeScript Support
+
+The plugin includes comprehensive TypeScript definitions for all options, methods, and responses.
+
+## Complete Example
+
+```typescript
+// Create customer
+const customerId = await ctx.plugins.stripePlugin.stripeAPI.customer.create({
+  email: user.email,
+  name: user.name,
+});
+
+// Setup their card
+const { redirectUrl: setupUrl } = await ctx.plugins.stripePlugin.stripeAPI.customer.setupCard({
+  stripeCustomerId: customerId,
+});
+// Redirect user to setupUrl
+
+// Later, create a payment
+const hasCard = await ctx.plugins.stripePlugin.stripeAPI.customer.hasPaymentMethod({
+  stripeCustomerId: customerId,
+});
+
+if (hasCard) {
+  const result = await ctx.plugins.stripePlugin.stripeAPI.payment.createAndConfirm({
+    amount: 5000,
+    currency: "usd",
+    customer: customerId,
+    description: "Premium subscription",
+  });
+
+  if (result.confirmed && result.captured) {
+    // Payment successful
+    await activatePremiumSubscription(user.id);
+  }
+}
 ```
+
+## License
+
+MIT