gkt-node 3.3.0

package/assets/.agent/skills/stripe-automation/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: stripe-automation
+description: "Automate Stripe tasks via Rube MCP (Composio): customers, charges, subscriptions, invoices, products, refunds. Always search tools first for current schemas."
+requires:
+  mcp: [rube]
+---
+
+# Stripe Automation via Rube MCP
+
+Automate Stripe payment operations through Composio's Stripe toolkit via Rube MCP.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active Stripe connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `stripe`
+- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
+
+## Setup
+
+**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
+
+
+1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
+2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `stripe`
+3. If connection is not ACTIVE, follow the returned auth link to complete Stripe connection
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. Manage Customers
+
+**When to use**: User wants to create, update, search, or list Stripe customers
+
+**Tool sequence**:
+1. `STRIPE_SEARCH_CUSTOMERS` - Search customers by email/name [Optional]
+2. `STRIPE_LIST_CUSTOMERS` - List all customers [Optional]
+3. `STRIPE_CREATE_CUSTOMER` - Create a new customer [Optional]
+4. `STRIPE_POST_CUSTOMERS_CUSTOMER` - Update a customer [Optional]
+
+**Key parameters**:
+- `email`: Customer email
+- `name`: Customer name
+- `description`: Customer description
+- `metadata`: Key-value metadata pairs
+- `customer`: Customer ID for updates (e.g., 'cus_xxx')
+
+**Pitfalls**:
+- Stripe allows duplicate customers with the same email; search first to avoid duplicates
+- Customer IDs start with 'cus_'
+
+### 2. Manage Charges and Payments
+
+**When to use**: User wants to create charges, payment intents, or view charge history
+
+**Tool sequence**:
+1. `STRIPE_LIST_CHARGES` - List charges with filters [Optional]
+2. `STRIPE_CREATE_PAYMENT_INTENT` - Create a payment intent [Optional]
+3. `STRIPE_CONFIRM_PAYMENT_INTENT` - Confirm a payment intent [Optional]
+4. `STRIPE_POST_CHARGES` - Create a direct charge [Optional]
+5. `STRIPE_CAPTURE_CHARGE` - Capture an authorized charge [Optional]
+
+**Key parameters**:
+- `amount`: Amount in smallest currency unit (e.g., cents for USD)
+- `currency`: Three-letter ISO currency code (e.g., 'usd')
+- `customer`: Customer ID
+- `payment_method`: Payment method ID
+- `description`: Charge description
+
+**Pitfalls**:
+- Amounts are in smallest currency unit (100 = $1.00 for USD)
+- Currency codes must be lowercase (e.g., 'usd' not 'USD')
+- Payment intents are the recommended flow over direct charges
+
+### 3. Manage Subscriptions
+
+**When to use**: User wants to create, list, update, or cancel subscriptions
+
+**Tool sequence**:
+1. `STRIPE_LIST_SUBSCRIPTIONS` - List subscriptions [Optional]
+2. `STRIPE_POST_CUSTOMERS_CUSTOMER_SUBSCRIPTIONS` - Create subscription [Optional]
+3. `STRIPE_RETRIEVE_SUBSCRIPTION` - Get subscription details [Optional]
+4. `STRIPE_UPDATE_SUBSCRIPTION` - Modify subscription [Optional]
+
+**Key parameters**:
+- `customer`: Customer ID
+- `items`: Array of price items (price_id and quantity)
+- `subscription`: Subscription ID for retrieval/update (e.g., 'sub_xxx')
+
+**Pitfalls**:
+- Subscriptions require a valid customer with a payment method
+- Price IDs (not product IDs) are used for subscription items
+- Cancellation can be immediate or at period end
+
+### 4. Manage Invoices
+
+**When to use**: User wants to create, list, or search invoices
+
+**Tool sequence**:
+1. `STRIPE_LIST_INVOICES` - List invoices [Optional]
+2. `STRIPE_SEARCH_INVOICES` - Search invoices [Optional]
+3. `STRIPE_CREATE_INVOICE` - Create an invoice [Optional]
+
+**Key parameters**:
+- `customer`: Customer ID for invoice
+- `collection_method`: 'charge_automatically' or 'send_invoice'
+- `days_until_due`: Days until invoice is due
+
+**Pitfalls**:
+- Invoices auto-finalize by default; use `auto_advance: false` for draft invoices
+
+### 5. Manage Products and Prices
+
+**When to use**: User wants to list or search products and their pricing
+
+**Tool sequence**:
+1. `STRIPE_LIST_PRODUCTS` - List products [Optional]
+2. `STRIPE_SEARCH_PRODUCTS` - Search products [Optional]
+3. `STRIPE_LIST_PRICES` - List prices [Optional]
+4. `STRIPE_GET_PRICES_SEARCH` - Search prices [Optional]
+
+**Key parameters**:
+- `active`: Filter by active/inactive status
+- `query`: Search query for search endpoints
+
+**Pitfalls**:
+- Products and prices are separate objects; a product can have multiple prices
+- Price IDs (e.g., 'price_xxx') are used for subscriptions and checkout
+
+### 6. Handle Refunds
+
+**When to use**: User wants to issue refunds on charges
+
+**Tool sequence**:
+1. `STRIPE_LIST_REFUNDS` - List refunds [Optional]
+2. `STRIPE_POST_CHARGES_CHARGE_REFUNDS` - Create a refund [Optional]
+3. `STRIPE_CREATE_REFUND` - Create refund via payment intent [Optional]
+
+**Key parameters**:
+- `charge`: Charge ID for refund
+- `amount`: Partial refund amount (omit for full refund)
+- `reason`: Refund reason ('duplicate', 'fraudulent', 'requested_by_customer')
+
+**Pitfalls**:
+- Refunds can take 5-10 business days to appear on customer statements
+- Amount is in smallest currency unit
+
+## Common Patterns
+
+### Amount Formatting
+
+Stripe uses smallest currency unit:
+- USD: $10.50 = 1050 cents
+- EUR: 10.50 = 1050 cents
+- JPY: 1000 = 1000 (no decimals)
+
+### Pagination
+
+- Use `limit` parameter (max 100)
+- Check `has_more` in response
+- Pass `starting_after` with last object ID for next page
+- Continue until `has_more` is false
+
+## Known Pitfalls
+
+**Amount Units**:
+- Always use smallest currency unit (cents for USD/EUR)
+- Zero-decimal currencies (JPY, KRW) use the amount directly
+
+**ID Prefixes**:
+- Customers: `cus_`, Charges: `ch_`, Subscriptions: `sub_`
+- Invoices: `in_`, Products: `prod_`, Prices: `price_`
+- Payment Intents: `pi_`, Refunds: `re_`
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| Create customer | STRIPE_CREATE_CUSTOMER | email, name |
+| Search customers | STRIPE_SEARCH_CUSTOMERS | query |
+| Update customer | STRIPE_POST_CUSTOMERS_CUSTOMER | customer, fields |
+| List charges | STRIPE_LIST_CHARGES | customer, limit |
+| Create payment intent | STRIPE_CREATE_PAYMENT_INTENT | amount, currency |
+| Confirm payment | STRIPE_CONFIRM_PAYMENT_INTENT | payment_intent |
+| List subscriptions | STRIPE_LIST_SUBSCRIPTIONS | customer |
+| Create subscription | STRIPE_POST_CUSTOMERS_CUSTOMER_SUBSCRIPTIONS | customer, items |
+| Update subscription | STRIPE_UPDATE_SUBSCRIPTION | subscription, fields |
+| List invoices | STRIPE_LIST_INVOICES | customer |
+| Create invoice | STRIPE_CREATE_INVOICE | customer |
+| Search invoices | STRIPE_SEARCH_INVOICES | query |
+| List products | STRIPE_LIST_PRODUCTS | active |
+| Search products | STRIPE_SEARCH_PRODUCTS | query |
+| List prices | STRIPE_LIST_PRICES | product |
+| Search prices | STRIPE_GET_PRICES_SEARCH | query |
+| List refunds | STRIPE_LIST_REFUNDS | charge |
+| Create refund | STRIPE_CREATE_REFUND | charge, amount |
+| Payment methods | STRIPE_LIST_CUSTOMER_PAYMENT_METHODS | customer |
+| Checkout session | STRIPE_CREATE_CHECKOUT_SESSION | line_items |
+| List payment intents | STRIPE_LIST_PAYMENT_INTENTS | customer |

package/assets/.agent/skills/stripe-integration/SKILL.md

@@ -0,0 +1,454 @@
+---
+name: stripe-integration
+description: Implement Stripe payment processing for robust, PCI-compliant payment flows including checkout, subscriptions, and webhooks. Use when integrating Stripe payments, building subscription systems, or implementing secure checkout flows.
+---
+
+# Stripe Integration
+
+Master Stripe payment processing integration for robust, PCI-compliant payment flows including checkout, subscriptions, webhooks, and refunds.
+
+## Do not use this skill when
+
+- The task is unrelated to stripe integration
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Use this skill when
+
+- Implementing payment processing in web/mobile applications
+- Setting up subscription billing systems
+- Handling one-time payments and recurring charges
+- Processing refunds and disputes
+- Managing customer payment methods
+- Implementing SCA (Strong Customer Authentication) for European payments
+- Building marketplace payment flows with Stripe Connect
+
+## Core Concepts
+
+### 1. Payment Flows
+**Checkout Session (Hosted)**
+- Stripe-hosted payment page
+- Minimal PCI compliance burden
+- Fastest implementation
+- Supports one-time and recurring payments
+
+**Payment Intents (Custom UI)**
+- Full control over payment UI
+- Requires Stripe.js for PCI compliance
+- More complex implementation
+- Better customization options
+
+**Setup Intents (Save Payment Methods)**
+- Collect payment method without charging
+- Used for subscriptions and future payments
+- Requires customer confirmation
+
+### 2. Webhooks
+**Critical Events:**
+- `payment_intent.succeeded`: Payment completed
+- `payment_intent.payment_failed`: Payment failed
+- `customer.subscription.updated`: Subscription changed
+- `customer.subscription.deleted`: Subscription canceled
+- `charge.refunded`: Refund processed
+- `invoice.payment_succeeded`: Subscription payment successful
+
+### 3. Subscriptions
+**Components:**
+- **Product**: What you're selling
+- **Price**: How much and how often
+- **Subscription**: Customer's recurring payment
+- **Invoice**: Generated for each billing cycle
+
+### 4. Customer Management
+- Create and manage customer records
+- Store multiple payment methods
+- Track customer metadata
+- Manage billing details
+
+## Quick Start
+
+```python
+import stripe
+
+stripe.api_key = "sk_test_..."
+
+# Create a checkout session
+session = stripe.checkout.Session.create(
+    payment_method_types=['card'],
+    line_items=[{
+        'price_data': {
+            'currency': 'usd',
+            'product_data': {
+                'name': 'Premium Subscription',
+            },
+            'unit_amount': 2000,  # $20.00
+            'recurring': {
+                'interval': 'month',
+            },
+        },
+        'quantity': 1,
+    }],
+    mode='subscription',
+    success_url='https://yourdomain.com/success?session_id={CHECKOUT_SESSION_ID}',
+    cancel_url='https://yourdomain.com/cancel',
+)
+
+# Redirect user to session.url
+print(session.url)
+```
+
+## Payment Implementation Patterns
+
+### Pattern 1: One-Time Payment (Hosted Checkout)
+```python
+def create_checkout_session(amount, currency='usd'):
+    """Create a one-time payment checkout session."""
+    try:
+        session = stripe.checkout.Session.create(
+            payment_method_types=['card'],
+            line_items=[{
+                'price_data': {
+                    'currency': currency,
+                    'product_data': {
+                        'name': 'Purchase',
+                        'images': ['https://example.com/product.jpg'],
+                    },
+                    'unit_amount': amount,  # Amount in cents
+                },
+                'quantity': 1,
+            }],
+            mode='payment',
+            success_url='https://yourdomain.com/success?session_id={CHECKOUT_SESSION_ID}',
+            cancel_url='https://yourdomain.com/cancel',
+            metadata={
+                'order_id': 'order_123',
+                'user_id': 'user_456'
+            }
+        )
+        return session
+    except stripe.error.StripeError as e:
+        # Handle error
+        print(f"Stripe error: {e.user_message}")
+        raise
+```
+
+### Pattern 2: Custom Payment Intent Flow
+```python
+def create_payment_intent(amount, currency='usd', customer_id=None):
+    """Create a payment intent for custom checkout UI."""
+    intent = stripe.PaymentIntent.create(
+        amount=amount,
+        currency=currency,
+        customer=customer_id,
+        automatic_payment_methods={
+            'enabled': True,
+        },
+        metadata={
+            'integration_check': 'accept_a_payment'
+        }
+    )
+    return intent.client_secret  # Send to frontend
+
+# Frontend (JavaScript)
+"""
+const stripe = Stripe('pk_test_...');
+const elements = stripe.elements();
+const cardElement = elements.create('card');
+cardElement.mount('#card-element');
+
+const {error, paymentIntent} = await stripe.confirmCardPayment(
+    clientSecret,
+    {
+        payment_method: {
+            card: cardElement,
+            billing_details: {
+                name: 'Customer Name'
+            }
+        }
+    }
+);
+
+if (error) {
+    // Handle error
+} else if (paymentIntent.status === 'succeeded') {
+    // Payment successful
+}
+"""
+```
+
+### Pattern 3: Subscription Creation
+```python
+def create_subscription(customer_id, price_id):
+    """Create a subscription for a customer."""
+    try:
+        subscription = stripe.Subscription.create(
+            customer=customer_id,
+            items=[{'price': price_id}],
+            payment_behavior='default_incomplete',
+            payment_settings={'save_default_payment_method': 'on_subscription'},
+            expand=['latest_invoice.payment_intent'],
+        )
+
+        return {
+            'subscription_id': subscription.id,
+            'client_secret': subscription.latest_invoice.payment_intent.client_secret
+        }
+    except stripe.error.StripeError as e:
+        print(f"Subscription creation failed: {e}")
+        raise
+```
+
+### Pattern 4: Customer Portal
+```python
+def create_customer_portal_session(customer_id):
+    """Create a portal session for customers to manage subscriptions."""
+    session = stripe.billing_portal.Session.create(
+        customer=customer_id,
+        return_url='https://yourdomain.com/account',
+    )
+    return session.url  # Redirect customer here
+```
+
+## Webhook Handling
+
+### Secure Webhook Endpoint
+```python
+from flask import Flask, request
+import stripe
+
+app = Flask(__name__)
+
+endpoint_secret = 'whsec_...'
+
+@app.route('/webhook', methods=['POST'])
+def webhook():
+    payload = request.data
+    sig_header = request.headers.get('Stripe-Signature')
+
+    try:
+        event = stripe.Webhook.construct_event(
+            payload, sig_header, endpoint_secret
+        )
+    except ValueError:
+        # Invalid payload
+        return 'Invalid payload', 400
+    except stripe.error.SignatureVerificationError:
+        # Invalid signature
+        return 'Invalid signature', 400
+
+    # Handle the event
+    if event['type'] == 'payment_intent.succeeded':
+        payment_intent = event['data']['object']
+        handle_successful_payment(payment_intent)
+    elif event['type'] == 'payment_intent.payment_failed':
+        payment_intent = event['data']['object']
+        handle_failed_payment(payment_intent)
+    elif event['type'] == 'customer.subscription.deleted':
+        subscription = event['data']['object']
+        handle_subscription_canceled(subscription)
+
+    return 'Success', 200
+
+def handle_successful_payment(payment_intent):
+    """Process successful payment."""
+    customer_id = payment_intent.get('customer')
+    amount = payment_intent['amount']
+    metadata = payment_intent.get('metadata', {})
+
+    # Update your database
+    # Send confirmation email
+    # Fulfill order
+    print(f"Payment succeeded: {payment_intent['id']}")
+
+def handle_failed_payment(payment_intent):
+    """Handle failed payment."""
+    error = payment_intent.get('last_payment_error', {})
+    print(f"Payment failed: {error.get('message')}")
+    # Notify customer
+    # Update order status
+
+def handle_subscription_canceled(subscription):
+    """Handle subscription cancellation."""
+    customer_id = subscription['customer']
+    # Update user access
+    # Send cancellation email
+    print(f"Subscription canceled: {subscription['id']}")
+```
+
+### Webhook Best Practices
+```python
+import hashlib
+import hmac
+
+def verify_webhook_signature(payload, signature, secret):
+    """Manually verify webhook signature."""
+    expected_sig = hmac.new(
+        secret.encode('utf-8'),
+        payload,
+        hashlib.sha256
+    ).hexdigest()
+
+    return hmac.compare_digest(signature, expected_sig)
+
+def handle_webhook_idempotently(event_id, handler):
+    """Ensure webhook is processed exactly once."""
+    # Check if event already processed
+    if is_event_processed(event_id):
+        return
+
+    # Process event
+    try:
+        handler()
+        mark_event_processed(event_id)
+    except Exception as e:
+        log_error(e)
+        # Stripe will retry failed webhooks
+        raise
+```
+
+## Customer Management
+
+```python
+def create_customer(email, name, payment_method_id=None):
+    """Create a Stripe customer."""
+    customer = stripe.Customer.create(
+        email=email,
+        name=name,
+        payment_method=payment_method_id,
+        invoice_settings={
+            'default_payment_method': payment_method_id
+        } if payment_method_id else None,
+        metadata={
+            'user_id': '12345'
+        }
+    )
+    return customer
+
+def attach_payment_method(customer_id, payment_method_id):
+    """Attach a payment method to a customer."""
+    stripe.PaymentMethod.attach(
+        payment_method_id,
+        customer=customer_id
+    )
+
+    # Set as default
+    stripe.Customer.modify(
+        customer_id,
+        invoice_settings={
+            'default_payment_method': payment_method_id
+        }
+    )
+
+def list_customer_payment_methods(customer_id):
+    """List all payment methods for a customer."""
+    payment_methods = stripe.PaymentMethod.list(
+        customer=customer_id,
+        type='card'
+    )
+    return payment_methods.data
+```
+
+## Refund Handling
+
+```python
+def create_refund(payment_intent_id, amount=None, reason=None):
+    """Create a refund."""
+    refund_params = {
+        'payment_intent': payment_intent_id
+    }
+
+    if amount:
+        refund_params['amount'] = amount  # Partial refund
+
+    if reason:
+        refund_params['reason'] = reason  # 'duplicate', 'fraudulent', 'requested_by_customer'
+
+    refund = stripe.Refund.create(**refund_params)
+    return refund
+
+def handle_dispute(charge_id, evidence):
+    """Update dispute with evidence."""
+    stripe.Dispute.modify(
+        charge_id,
+        evidence={
+            'customer_name': evidence.get('customer_name'),
+            'customer_email_address': evidence.get('customer_email'),
+            'shipping_documentation': evidence.get('shipping_proof'),
+            'customer_communication': evidence.get('communication'),
+        }
+    )
+```
+
+## Testing
+
+```python
+# Use test mode keys
+stripe.api_key = "sk_test_..."
+
+# Test card numbers
+TEST_CARDS = {
+    'success': '4242424242424242',
+    'declined': '4000000000000002',
+    '3d_secure': '4000002500003155',
+    'insufficient_funds': '4000000000009995'
+}
+
+def test_payment_flow():
+    """Test complete payment flow."""
+    # Create test customer
+    customer = stripe.Customer.create(
+        email="test@example.com"
+    )
+
+    # Create payment intent
+    intent = stripe.PaymentIntent.create(
+        amount=1000,
+        currency='usd',
+        customer=customer.id,
+        payment_method_types=['card']
+    )
+
+    # Confirm with test card
+    confirmed = stripe.PaymentIntent.confirm(
+        intent.id,
+        payment_method='pm_card_visa'  # Test payment method
+    )
+
+    assert confirmed.status == 'succeeded'
+```
+
+## Resources
+
+- **references/checkout-flows.md**: Detailed checkout implementation
+- **references/webhook-handling.md**: Webhook security and processing
+- **references/subscription-management.md**: Subscription lifecycle
+- **references/customer-management.md**: Customer and payment method handling
+- **references/invoice-generation.md**: Invoicing and billing
+- **assets/stripe-client.py**: Production-ready Stripe client wrapper
+- **assets/webhook-handler.py**: Complete webhook processor
+- **assets/checkout-config.json**: Checkout configuration templates
+
+## Best Practices
+
+1. **Always Use Webhooks**: Don't rely solely on client-side confirmation
+2. **Idempotency**: Handle webhook events idempotently
+3. **Error Handling**: Gracefully handle all Stripe errors
+4. **Test Mode**: Thoroughly test with test keys before production
+5. **Metadata**: Use metadata to link Stripe objects to your database
+6. **Monitoring**: Track payment success rates and errors
+7. **PCI Compliance**: Never handle raw card data on your server
+8. **SCA Ready**: Implement 3D Secure for European payments
+
+## Common Pitfalls
+
+- **Not Verifying Webhooks**: Always verify webhook signatures
+- **Missing Webhook Events**: Handle all relevant webhook events
+- **Hardcoded Amounts**: Use cents/smallest currency unit
+- **No Retry Logic**: Implement retries for API calls
+- **Ignoring Test Mode**: Test all edge cases with test cards