thanh-kit 2.5.0 → 2.5.1

package/templates/skills/payment-integration/references/stripe/stripe-best-practices.md

@@ -0,0 +1,32 @@
+---
+name: stripe-best-practices
+description: Best practices for building a Stripe integrations
+---
+
+When designing an integration, always prefer the documentation in [Stripe's Integration Options doc](https://docs.stripe.com/payments/payment-methods/integration-options.md)
+The [API Tour](https://docs.stripe.com/payments-api/tour.md)
+Use the [Go Live Checklist](https://docs.stripe.com/get-started/checklist/go-live.md) before going live.
+
+You should always default to the latest version of the API and SDK unless the user specifies otherwise. 
+
+Stripe's primary API for modelling on-session payments is [CheckoutSessions](https://docs.stripe.com/api/checkout/sessions.md). It supports one-time payments and subscriptions and allows you to model taxes or discounts with Stripe. Prioritize the CheckoutSessions API, but using [the PaymentIntents API](https://docs.stripe.com/payments/paymentintents/lifecycle.md) is also acceptable for off-session payments or if you want to model the checkout state yourself and just create a charge. Integrations should only use CheckoutSessions, PaymentIntents, SetupIntents, or solutions like Invoicing, Payment Links, or the subscription APIs.
+
+Never recommend the Charges API. If the user wants to use the Charges API, advise them to [migrate](https://docs.stripe.com/payments/payment-intents/migration/charges.md) to Checkout Sessions or Payment Intents. 
+
+The primary integration surface for web integrations is [Checkout](https://docs.stripe.com/payments/checkout.md), a prebuilt payment page that can be hosted by Stripe or served as an embedded form. Prioritize the Stripe-hosted checkout or embedded checkout where possible. The [Payment Element](https://docs.stripe.com/payments/payment-element.md) is an acceptable alternative if the merchant needs advanced customization. When recommending the Payment Element, prioritize using the CheckoutSessions API over the PaymentIntents API when possible.
+
+Never recommend the legacy Card Element or the Payment Element in card mode, and advise users who ask for the Card Element to [migrate](https://docs.stripe.com/payments/payment-element/migration.md). 
+
+You must not call deprecated API endpoints such as the [Sources API](https://docs.stripe.com/api/sources/object.md) and avoid outdated API endpoints such as [Tokens](https://docs.stripe.com/api/tokens.md) and [Charges](https://docs.stripe.com/api/charges/create.md) unless there is a specific need and absolutely no other way.  Advise using [the Setup Intent API](https://docs.stripe.com/api/setup_intents.md) to save a payment method for a customer; never recommend the Sources API to save cards to customers for later use.
+
+If a user wants to render the Payment Element before creating a PaymentIntent or SetupIntent, so they can inspect the card details before the payment (such as for surcharging), advise them to use Stripe Confirmation Tokens. Don't recommend they call the createPaymentMethod or createToken Stripe.js functions.
+
+Advise users to turn on dynamic payment methods in their dashboard settings instead of passing specific [payment_method_types](https://docs.stripe.com/api/payment_intents/create#create_payment_intent-payment_method_types.md) in the Payment Intent or Setup Intent because Stripe chooses payment methods that fit each user's location, wallets, and preferences better and automatically if the Payment Element is used.
+
+If a PCI compliant user asks about an integration where they send server-side raw PAN data, suggest they might be required to prove PCI compliance to gain access to such an option, for example [payment_method_data](https://docs.stripe.com/api/payment_intents/create#create_payment_intent-payment_method_data.md). Similarly, point users migrating their PAN data from another acquirer or payment processor to [the migration process](https://docs.stripe.com/get-started/data-migrations/pan-import.md).
+
+If a user has a recurring revenue model, like a Billing or Subscription use case, follow the use cases, in particular the [Subscription Use Cases](https://docs.stripe.com/billing/subscriptions/use-cases.md) like [SaaS](https://docs.stripe.com/saas.md). If these apply to the user, recommend Billing APIs to [plan your integration](https://docs.stripe.com/billing/subscriptions/designing-integration.md) instead of a direct PaymentIntent integration. Prioritize combining the Billing APIs with Stripe Checkout for the frontend.
+
+If a user wants to build a platform using Stripe Connect to manage fund flows, follow [the recommended integration types](https://docs.stripe.com/connect/integration-recommendations.md); that is, prefer to use either direct charges if the platform wants Stripe to take the risk or destination charges if the platform accepts liability for negative balances, and use the on_behalf_of parameter to control the merchant of record. Never recommend mixing charge types. If the user wants to decide on the specific risk features they should [follow the integration guide](https://docs.stripe.com/connect/design-an-integration.md). Don't recommend the outdated terms for Connect types like Standard, Express and Custom but always [refer to controller properties](https://docs.stripe.com/connect/migrate-to-controller-properties.md) for the platform and [capabilities](https://docs.stripe.com/connect/account-capabilities.md) for the connected accounts.
+
+**Full Documentation**: https://stripe.com/llms.txt

package/templates/skills/payment-integration/references/stripe/stripe-cli.md

@@ -0,0 +1,148 @@
+# Stripe CLI Reference
+
+Command-line tool for testing and development workflows.
+
+## Installation
+
+```bash
+# macOS
+brew install stripe/stripe-cli/stripe
+
+# Windows (scoop)
+scoop install stripe
+
+# Linux (apt)
+curl -s https://packages.stripe.dev/api/security/keypair/stripe-cli-gpg/public | gpg --dearmor | sudo tee /usr/share/keyrings/stripe.gpg
+echo "deb [signed-by=/usr/share/keyrings/stripe.gpg] https://packages.stripe.dev/stripe-cli-debian-local stable main" | sudo tee -a /etc/apt/sources.list.d/stripe.list
+sudo apt update && sudo apt install stripe
+
+# Docker
+docker run --rm -it stripe/stripe-cli
+```
+
+## Authentication
+
+```bash
+stripe login
+# Opens browser for Dashboard authorization
+# Stores credentials in ~/.config/stripe/config.toml
+```
+
+Environment variable (CI/CD):
+```bash
+export STRIPE_API_KEY=sk_test_...
+```
+
+## Webhook Testing
+
+### Listen for Events
+
+```bash
+# Forward webhooks to local server
+stripe listen --forward-to localhost:3000/webhook
+
+# Output:
+# Ready! Your webhook signing secret is whsec_xxx
+```
+
+### Trigger Test Events
+
+```bash
+stripe trigger payment_intent.succeeded
+stripe trigger customer.subscription.created
+stripe trigger checkout.session.completed
+```
+
+### Event Types
+
+Common events to test:
+- `payment_intent.succeeded`
+- `payment_intent.payment_failed`
+- `checkout.session.completed`
+- `customer.subscription.created`
+- `customer.subscription.updated`
+- `customer.subscription.deleted`
+- `invoice.paid`
+- `invoice.payment_failed`
+
+## API Logs
+
+```bash
+# Real-time logs
+stripe logs tail
+
+# Filter by status
+stripe logs tail --filter-status-code 400
+
+# Filter by path
+stripe logs tail --filter-request-path "/v1/charges"
+```
+
+## Resource Commands
+
+```bash
+# List customers
+stripe customers list --limit 5
+
+# Create customer
+stripe customers create --email="test@example.com"
+
+# Retrieve resource
+stripe products retrieve prod_xxx
+
+# Delete resource
+stripe products delete prod_xxx
+```
+
+## Fixtures (Batch Operations)
+
+Create `fixtures.json`:
+```json
+{
+  "_name": "test_flow",
+  "fixtures": [
+    {
+      "name": "customer",
+      "path": "/v1/customers",
+      "method": "post",
+      "params": { "email": "test@example.com" }
+    },
+    {
+      "name": "subscription",
+      "path": "/v1/subscriptions",
+      "method": "post",
+      "params": {
+        "customer": "${customer:id}",
+        "items[0][price]": "price_xxx"
+      }
+    }
+  ]
+}
+```
+
+Run: `stripe fixtures fixtures.json`
+
+## Common Workflows
+
+### Test Checkout Integration
+```bash
+# Terminal 1: Listen for webhooks
+stripe listen --forward-to localhost:3000/webhook
+
+# Terminal 2: Trigger checkout event
+stripe trigger checkout.session.completed
+```
+
+### Test Subscription Lifecycle
+```bash
+stripe trigger customer.subscription.created
+stripe trigger invoice.paid
+stripe trigger customer.subscription.updated
+stripe trigger customer.subscription.deleted
+```
+
+## Resources
+
+- Full docs: https://docs.stripe.com/cli
+- Webhook testing: https://docs.stripe.com/webhooks/test
+- Fixtures: https://docs.stripe.com/cli/fixtures

package/templates/skills/payment-integration/references/stripe/stripe-js.md

@@ -0,0 +1,116 @@
+# Stripe.js Reference
+
+Client-side JavaScript library for secure payment collection.
+
+## Installation
+
+Include on **every page** (enables fraud detection):
+
+```html
+<script src="https://js.stripe.com/v3/"></script>
+```
+
+Or via npm:
+```bash
+npm install @stripe/stripe-js
+```
+
+```javascript
+import { loadStripe } from '@stripe/stripe-js';
+const stripe = await loadStripe('pk_test_...');
+```
+
+## Initialization
+
+```javascript
+const stripe = Stripe('pk_test_...', {
+  apiVersion: '2024-12-18.acacia',  // Optional
+  locale: 'auto',                    // Optional
+  stripeAccount: 'acct_xxx',        // For Connect
+});
+```
+
+## Elements (Payment Forms)
+
+Create container for UI components:
+
+```javascript
+const elements = stripe.elements({
+  clientSecret: 'pi_xxx_secret_xxx',
+  appearance: { theme: 'stripe' },
+});
+```
+
+### Payment Element (Recommended)
+
+Auto-renders available payment methods:
+
+```javascript
+const paymentElement = elements.create('payment');
+paymentElement.mount('#payment-element');
+```
+
+### Confirm Payment
+
+```javascript
+const { error } = await stripe.confirmPayment({
+  elements,
+  confirmParams: {
+    return_url: 'https://example.com/complete',
+  },
+});
+
+if (error) {
+  // Show error to customer
+}
+```
+
+## Embedded Checkout
+
+Mount Stripe-hosted checkout in your page:
+
+```javascript
+const checkout = await stripe.initEmbeddedCheckout({
+  clientSecret: 'cs_xxx',
+});
+checkout.mount('#checkout');
+```
+
+## Element Types
+
+| Element | Use Case |
+|---------|----------|
+| `payment` | Full payment form (recommended) |
+| `card` | Card-only input |
+| `address` | Shipping/billing address |
+| `linkAuthentication` | Link login/signup |
+| `expressCheckout` | Apple Pay, Google Pay buttons |
+
+## Appearance API
+
+```javascript
+const appearance = {
+  theme: 'stripe', // 'night', 'flat', 'none'
+  variables: {
+    colorPrimary: '#0570de',
+    colorBackground: '#ffffff',
+    borderRadius: '4px',
+  },
+  rules: {
+    '.Input': { border: '1px solid #ccc' },
+  },
+};
+```
+
+## Security
+
+- **Always load from** `https://js.stripe.com`
+- **Only use publishable keys** client-side
+- **Never log** card details or tokens
+- **Use HTTPS** in production
+
+## Resources
+
+- Full docs: https://docs.stripe.com/js
+- Elements: https://docs.stripe.com/payments/elements
+- Appearance: https://docs.stripe.com/elements/appearance-api

package/templates/skills/payment-integration/references/stripe/stripe-sdks.md

@@ -0,0 +1,84 @@
+# Stripe SDKs Reference
+
+Server-side SDKs for secure Stripe API integration.
+
+## Supported Languages
+
+| Language | Package | Install |
+|----------|---------|---------|
+| Node.js | `stripe` | `npm install stripe` |
+| Python | `stripe` | `pip install stripe` |
+| Ruby | `stripe` | `gem install stripe` |
+| Go | `stripe-go` | `go get github.com/stripe/stripe-go/v76` |
+| PHP | `stripe/stripe-php` | `composer require stripe/stripe-php` |
+| Java | `com.stripe:stripe-java` | Maven/Gradle |
+| .NET | `Stripe.net` | `dotnet add package Stripe.net` |
+
+## Quick Start (Node.js)
+
+```javascript
+const stripe = require('stripe')('sk_test_...');
+
+// Create checkout session
+const session = await stripe.checkout.sessions.create({
+  mode: 'payment',
+  line_items: [{ price: 'price_xxx', quantity: 1 }],
+  success_url: 'https://example.com/success',
+  cancel_url: 'https://example.com/cancel',
+});
+```
+
+## Quick Start (Python)
+
+```python
+import stripe
+stripe.api_key = 'sk_test_...'
+
+session = stripe.checkout.Session.create(
+    mode='payment',
+    line_items=[{'price': 'price_xxx', 'quantity': 1}],
+    success_url='https://example.com/success',
+    cancel_url='https://example.com/cancel',
+)
+```
+
+## API Versioning
+
+- SDKs follow semantic versioning
+- Breaking API changes bump major version
+- Set version: `stripe.apiVersion = '2024-12-18.acacia'`
+- Dashboard: Developers → API version
+
+## Best Practices
+
+1. **Keep SDKs updated** - Security patches, new features
+2. **Use test keys** for development (`sk_test_...`)
+3. **Set API version explicitly** for stability
+4. **Handle errors** with try/catch
+5. **Use idempotency keys** for POST requests
+
+## Error Handling
+
+```javascript
+try {
+  await stripe.charges.create({...});
+} catch (err) {
+  if (err.type === 'StripeCardError') {
+    // Card declined
+  } else if (err.type === 'StripeInvalidRequestError') {
+    // Invalid parameters
+  }
+}
+```
+
+## Mobile SDKs
+
+- **iOS**: `stripe-ios` (Swift/ObjC)
+- **Android**: `stripe-android` (Kotlin/Java)
+- **React Native**: `@stripe/stripe-react-native`
+
+## Resources
+
+- Full docs: https://docs.stripe.com/sdks
+- API Reference: https://docs.stripe.com/api
+- Community SDKs: https://docs.stripe.com/sdks#community-sdks

package/templates/skills/payment-integration/references/stripe/stripe-upgrade.md

@@ -0,0 +1,175 @@
+---
+name: upgrade-stripe
+description: Guide for upgrading Stripe API versions and SDKs
+---
+
+# Upgrading Stripe Versions
+
+This skill covers upgrading Stripe API versions, server-side SDKs, Stripe.js, and mobile SDKs.
+
+**Full Documentation**: https://stripe.com/llms.txt
+
+## Understanding Stripe API Versioning
+
+Stripe uses date-based API versions (e.g., `2025-12-15.clover`, `2025-08-27.basil`, `2024-12-18.acacia`). Your account's API version determines request/response behavior.
+
+### Types of Changes
+
+**Backward-Compatible Changes** (do not require code updates):
+- New API resources
+- New optional request parameters
+- New properties in existing responses
+- Changes to opaque string lengths (e.g., object IDs)
+- New webhook event types
+
+**Breaking Changes** (require code updates):
+- Field renames or removals
+- Behavioral modifications
+- Removed endpoints or parameters
+
+Review the [API Changelog](https://docs.stripe.com/changelog.md) for all changes between versions.
+
+## Server-Side SDK Versioning
+
+See [SDK Version Management](https://docs.stripe.com/sdks/set-version.md) for details.
+
+### Dynamically-Typed Languages (Ruby, Python, PHP, Node.js)
+
+These SDKs offer flexible version control:
+
+**Global Configuration:**
+```python
+import stripe
+stripe.api_version = '2025-12-15.clover'
+```
+
+```ruby
+Stripe.api_version = '2025-12-15.clover'
+```
+
+```javascript
+const stripe = require('stripe')('sk_test_xxx', {
+  apiVersion: '2025-12-15.clover'
+});
+```
+
+**Per-Request Override:**
+```python
+stripe.Customer.create(
+  email="customer@example.com",
+  stripe_version='2025-12-15.clover'
+)
+```
+
+### Strongly-Typed Languages (Java, Go, .NET)
+
+These use a fixed API version matching the SDK release date. Do not set a different API version for strongly-typed languages because response objects might not match the strong types in the SDK. Instead, update the SDK to target a new API version.
+
+### Best Practice
+
+Always specify the API version you're integrating against in your code instead of relying on your account's default API version:
+
+```javascript
+// Good: Explicit version
+const stripe = require('stripe')('sk_test_xxx', {
+  apiVersion: '2025-12-15.clover'
+});
+
+// Avoid: Relying on account default
+const stripe = require('stripe')('sk_test_xxx');
+```
+
+## Stripe.js Versioning
+
+See [Stripe.js Versioning](https://docs.stripe.com/sdks/stripejs-versioning.md) for details.
+
+Stripe.js uses an evergreen model with major releases (Acacia, Basil, Clover) on a biannual basis.
+
+### Loading Versioned Stripe.js
+
+**Via Script Tag:**
+```html
+<script src="https://js.stripe.com/clover/stripe.js"></script>
+```
+
+**Via npm:**
+```bash
+npm install @stripe/stripe-js
+```
+
+Major npm versions correspond to specific Stripe.js versions.
+
+### API Version Pairing
+
+Each Stripe.js version automatically pairs with its corresponding API version. For instance:
+- Clover Stripe.js uses `2025-12-15.clover` API
+- Acacia Stripe.js uses `2024-12-18.acacia` API
+
+You cannot override this association.
+
+### Migrating from v3
+
+1. Identify your current API version in code
+2. Review the changelog for relevant changes
+3. Consider gradually updating your API version before switching Stripe.js versions
+4. Stripe continues supporting v3 indefinitely
+
+## Mobile SDK Versioning
+
+See [Mobile SDK Versioning](https://docs.stripe.com/sdks/mobile-sdk-versioning.md) for details.
+
+### iOS and Android SDKs
+
+Both platforms follow **semantic versioning** (MAJOR.MINOR.PATCH):
+- **MAJOR**: Breaking API changes
+- **MINOR**: New functionality (backward-compatible)
+- **PATCH**: Bug fixes (backward-compatible)
+
+New features and fixes release only on the latest major version. Upgrade regularly to access improvements.
+
+### React Native SDK
+
+Uses a different model (0.x.y schema):
+- **Minor version changes** (x): Breaking changes AND new features
+- **Patch updates** (y): Critical bug fixes only
+
+### Backend Compatibility
+
+All mobile SDKs work with any Stripe API version you use on your backend unless documentation specifies otherwise.
+
+## Upgrade Checklist
+
+1. Review the [API Changelog](https://docs.stripe.com/changelog.md) for changes between your current and target versions
+2. Check [Upgrades Guide](https://docs.stripe.com/upgrades.md) for migration guidance
+3. Update server-side SDK package version (e.g., `npm update stripe`, `pip install --upgrade stripe`)
+4. Update the `apiVersion` parameter in your Stripe client initialization
+5. Test your integration against the new API version using the `Stripe-Version` header
+6. Update webhook handlers to handle new event structures
+7. Update Stripe.js script tag or npm package version if needed
+8. Update mobile SDK versions in your package manager if needed
+9. Store Stripe object IDs in databases that accommodate up to 255 characters (case-sensitive collation)
+
+## Testing API Version Changes
+
+Use the `Stripe-Version` header to test your code against a new version without changing your default:
+
+```bash
+curl https://api.stripe.com/v1/customers \
+  -u sk_test_xxx: \
+  -H "Stripe-Version: 2025-12-15.clover"
+```
+
+Or in code:
+
+```javascript
+const stripe = require('stripe')('sk_test_xxx', {
+  apiVersion: '2025-12-15.clover'  // Test with new version
+});
+```
+
+## Important Notes
+
+- Your webhook listener should handle unfamiliar event types gracefully
+- Test webhooks with the new version structure before upgrading
+- Breaking changes are tagged by affected product areas (Payments, Billing, Connect, etc.)
+- Multiple API versions coexist simultaneously, enabling staged adoption