clawskills-mcp 0.2.3 → 0.3.0

package/dist/index.test.js

@@ -185,7 +185,7 @@ const REQUIRED_SECTIONS = [
 const KNOWN_SKILLS = [
     "asana", "dynamics365", "figma", "github", "hubspot",
     "jira", "monday", "salesforce", "servicenow", "zendesk",
-    "slack",
+    "slack", "stripe",
 ];
 describe("real skills", () => {
     let skills;

package/package.json

@@ -1,7 +1,29 @@
 {
   "name": "clawskills-mcp",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "MCP server exposing ClawSkills API integration skill docs to AI agents",
+  "license": "MIT",
+  "author": "ClawSkills Contributors",
+  "homepage": "https://github.com/Shanksg/clawskills#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Shanksg/clawskills.git"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "ai",
+    "integration",
+    "api",
+    "skill",
+    "salesforce",
+    "hubspot",
+    "jira",
+    "zendesk",
+    "slack",
+    "crm",
+    "saas"
+  ],
   "type": "module",
   "bin": {
     "clawskills-mcp": "dist/index.js"

package/skills/INDEX.md

@@ -21,6 +21,7 @@ A curated library of integration skill documents for the most common SaaS platfo
 | GitHub | [github/skill.md](./github/skill.md) | Engineering, DevOps | Source control, PRs, CI/CD automation via REST + GraphQL |
 | Figma | [figma/skill.md](./figma/skill.md) | Design, Product, DevOps | Design file inspection, asset export, webhooks, design-to-dev handoff |
 | Slack | [slack/skill.md](./slack/skill.md) | All teams | Real-time messaging, notifications, event-driven automation via Web API |
+| Stripe | [stripe/skill.md](./stripe/skill.md) | Engineering, Finance, RevOps | Payments, subscriptions, refunds, webhooks, and Connect for platforms |
 
 ---
 
@@ -180,6 +181,20 @@ A curated library of integration skill documents for the most common SaaS platfo
 
 ---
 
+### Stripe → [skill.md](./stripe/skill.md)
+1. Create a PaymentIntent for a one-time charge and confirm with Stripe.js
+2. Save a card for future off-session charges (SetupIntent → attach PaymentMethod)
+3. Create a recurring subscription (Customer + Price + Subscription)
+4. Launch a hosted Checkout Session and fulfil on `checkout.session.completed`
+5. Issue a full or partial refund
+6. Handle a failed subscription payment: notify customer, update payment method, retry invoice
+7. Receive and verify webhooks (Stripe-Signature HMAC-SHA256 verification)
+8. Stripe Connect: create a connected account, generate onboarding link, destination charge
+9. List all charges for a customer with cursor pagination
+10. Cancel a subscription at period end
+
+---
+
 ## Common Cross-Tool Patterns
 
 These scenarios span multiple skill docs — reference both tools:
@@ -197,6 +212,9 @@ These scenarios span multiple skill docs — reference both tools:
 | Bug report → GitHub issue + PR | Zendesk / ServiceNow | GitHub | Auto-create issue, label, assign; link ticket ID in body |
 | Design ready → engineering task | Figma | Jira / Asana / GitHub | `DEV_MODE_STATUS_UPDATE` webhook → create/update issue with frame link |
 | Asset pipeline | Figma | S3 / CDN | `FILE_VERSION_UPDATE` webhook → export frames as PNG, upload to storage |
+| Payment succeeded → CRM deal closed | Stripe | Salesforce / HubSpot | `payment_intent.succeeded` webhook → update deal stage to Closed Won |
+| Subscription cancelled → support ticket | Stripe | Zendesk / Jira | `customer.subscription.deleted` → create ticket for churn review |
+| Invoice paid → project provisioned | Stripe | Asana / Monday.com | `invoice.paid` webhook → create onboarding project or board item |
 
 ---
 
@@ -215,6 +233,7 @@ These scenarios span multiple skill docs — reference both tools:
 | GitHub | Fine-grained PAT or GitHub App installation token | Bearer token | Per-resource permissions (contents, issues, pull_requests, etc.) |
 | Figma | Personal Access Token (PAT) or OAuth 2.0 | `X-Figma-Token` (PAT) / `Authorization: Bearer` (OAuth) | Granular scopes: `file_content:read`, `webhooks:write`, etc. |
 | Slack | Bot token (OAuth 2.0 app install) | `xoxb-...` Bearer token | Per-method scopes: `chat:write`, `channels:read`, `users:read`, etc. |
+| Stripe | Secret API key or Restricted key | `Authorization: Bearer sk_live_...` | Per-resource scopes on restricted keys (None / Read / Write) |
 
 ---
 
@@ -233,10 +252,11 @@ These scenarios span multiple skill docs — reference both tools:
 | GitHub | PAT: 5,000/hr · GitHub App: 5k–12.5k/hr · Enterprise Cloud: 15,000/hr · Secondary: 900 pts/min, 80 create/min | 1 hour (primary) + sliding (secondary) | `x-ratelimit-remaining` / `x-ratelimit-reset`; 403 or 429 |
 | Figma | Starter: 10/min (T1), 25/min (T2) · Professional: 15/min (T1), 50/min (T2) · Org: 20/min (T1), 100/min (T2) | Per minute (leaky bucket) | `Retry-After` / `X-Figma-Rate-Limit-Type` / `X-Figma-Plan-Tier` |
 | Slack | Tier 1: 1/min · Tier 2: 20/min · Tier 3: 50/min · Tier 4: 100/min · `chat.postMessage`: 1/sec/channel sub-limit | Per method per workspace | HTTP 429 + `Retry-After` header (seconds) |
+| Stripe | Live: **100 req/sec** · Sandbox: **25 req/sec** · Search: 20/sec | Per account | HTTP 429 + `Stripe-Rate-Limited-Reason` header |
 
 ---
 
-*Last updated: 2026-02-26 (Slack skill added) | See [ROADMAP.md](./ROADMAP.md) for versioning and governance details.*
+*Last updated: 2026-03-01 (Stripe skill added) | See [ROADMAP.md](./ROADMAP.md) for versioning and governance details.*
 
 ### API version reference (as of 2026-02-22)
 
@@ -253,3 +273,4 @@ These scenarios span multiple skill docs — reference both tools:
 | GitHub | REST API + GraphQL v4 | Pin `X-GitHub-Api-Version: 2022-11-28`; fine-grained PATs recommended |
 | Figma | REST API v1 / Webhooks V2 | Path-based versioning (`/v1/`, `/v2/`); `files:read` scope deprecated — use granular scopes |
 | Slack | Web API (no versioned path) | Always check `ok` field (HTTP 200 even on errors); `files.upload` deprecated — use `files.getUploadURLExternal` |
+| Stripe | `2026-02-25.clover` | Pin with `Stripe-Version` header; amounts in smallest currency unit (cents); never log raw card data |

package/skills/ROADMAP.md

@@ -12,229 +12,152 @@ This skill set enables end-to-end automation and integration across the most com
 
 ---
 
-## Prioritization Framework
+## Current state (as of 2026-03-01)
 
-Each skill/recipe is scored on five dimensions (1–5 each):
+### What's shipped
 
-| Dimension | Description |
-|-----------|-------------|
-| **Impact** | Business value if automated (revenue, hours saved, error reduction) |
-| **Frequency** | How often the workflow runs daily/weekly |
-| **Complexity** | Inverse score — simpler = higher priority for Phase 1 |
-| **Risk** | Inverse score — lower risk of data loss/compliance issue = higher priority |
-| **Dependencies** | Whether other workflows or skills depend on this one being stable first |
+| Layer | Status |
+|-------|--------|
+| **11 skill docs** — Monday.com, Salesforce, Jira, Dynamics 365, HubSpot, ServiceNow, Zendesk, Asana, GitHub, Figma, Slack | ✅ Live |
+| **MCP server** — `clawskills-mcp` v0.2.3 on npm; `list_skills`, `get_skill`, `search_skills` | ✅ Live |
+| **CI pipeline** — build + test on every push/PR via `ci.yml` | ✅ Live |
+| **Release automation** — `release.yml` workflow_dispatch → bump, tag, npm publish via OIDC | ✅ Live |
+| **Test suite** — Vitest unit tests + real-skills validation (required sections, ≥5 KB, all 11 tools) | ✅ Live |
+| **Public repo readiness** — MIT license, `.gitignore`, full `package.json` metadata | ✅ Ready |
 
-**Priority score = (Impact × 2) + (Frequency × 1.5) + Complexity + Risk + Dependencies**
+### Content coverage by original phase
 
-Phases are ordered by descending average priority score within a theme.
+| Phase | Theme | Status |
+|-------|-------|--------|
+| Phase 1 — Foundation (Auth + Core CRUD) | Auth flows, basic CRUD, retry patterns | ✅ Complete — all 11 tools |
+| Phase 2 — High-Frequency Workflows | 6–12 recipes per tool | ✅ Complete — all 11 tools |
+| Phase 3 — Event-Driven & Real-Time | Webhook setup, signature verification, event handling | ✅ Complete — all 11 tools |
+| Phase 4 — Bulk & Advanced Operations | Batch APIs, large-volume patterns | ⚠️ Partial — documented for most tools; not all have >500-record examples |
+| Phase 5 — Cross-Tool Orchestration | Multi-system recipes spanning 2+ tools | ❌ Not started — patterns listed in INDEX.md but no dedicated recipes |
 
 ---
 
-## Phased Plan
-
-### Phase 1 — Foundation: Auth + Core CRUD (Weeks 1–4)
+## Next development phase
 
-**Theme:** Get the basics right. Every subsequent skill depends on reliable authentication and basic object manipulation.
+### Priority 1 — Content expansion: 3 new skills
 
-**Deliverables:**
-- All 8 `skill.md` files: Authentication & Permissions section fully validated against live environments
-- Core CRUD recipes for each tool (Create, Read by ID, Update, List/Search)
-- Error handling playbook (auth errors, 429s, 5xx retries)
-- Shared retry/backoff library or pattern documented
+Each new skill follows the 11-section template, lives on a `skill/<name>` branch, and is validated by CI before merge.
 
-**Cross-tool dependencies:**
-- OAuth 2.0 / token management pattern established first (applies to Salesforce JWT, Dynamics Azure AD, HubSpot Private Apps, Jira API Token, Asana PAT/OAuth, Zendesk API Token, ServiceNow OAuth, Monday token)
-- Secret storage convention agreed (env vars, vault reference) before any recipe is productionized
+| Skill | Why | Key areas to cover |
+|-------|-----|--------------------|
+| **Stripe** | Most common payments API; revenue-critical workflows missing from current library | Webhooks (event types + signature), Checkout Sessions, subscriptions, refunds, idempotency keys, Connect (multi-account) |
+| **Notion** | Knowledge base + lightweight PM; high demand for doc/wiki automation | Pages API, Databases + filters + sorts, Blocks API (rich text), Search, cursor pagination |
+| **Linear** | Fast-growing engineering tool, increasingly replacing Jira at startups | Issues, Projects, Teams, Cycles, GraphQL API, webhooks, OAuth + PAT auth |
 
-**Acceptance criteria:**
-- [ ] Each tool: auth flow documented end-to-end with working curl example
-- [ ] Each tool: create + read + update recipe tested against sandbox/dev environment
-- [ ] 429 rate-limit retry returns success within 3 attempts for all tools
-- [ ] No credentials stored in code or logs
+**Order:** Stripe → Notion → Linear (payments coverage is the biggest gap).
 
-**Definition of done:** A developer unfamiliar with any given tool can authenticate and perform a basic CRUD operation in under 30 minutes using only the skill doc.
+**Acceptance criteria for each:**
+- [ ] All 11 required sections present (CI enforces)
+- [ ] `Last validated:` date in header
+- [ ] Auth section has working `curl` example tested against sandbox/dev environment
+- [ ] At least 8 recipes with request/response examples
+- [ ] Rate limits verified against official docs
+- [ ] INDEX.md and README.md updated
 
 ---
 
-### Phase 2 — High-Frequency Workflows (Weeks 5–10)
+### Priority 2 — Freshness CI pipeline (the moat)
 
-**Theme:** The top 5 daily workflows per tool, covering the scenarios that save the most manual effort.
+A weekly automated check that skill docs aren't stale and that key API patterns still work.
 
-**Deliverables:**
-- Monday.com: Intake form → item creation, status sync, approval tracking
-- Salesforce: Lead capture & dedup, opportunity stage update, activity logging (Task/Event)
-- Jira: Ticket creation from external event, JQL search + triage, workflow transition with required fields
-- Dynamics 365: Contact/Account upsert, opportunity pipeline update, activity logging
-- HubSpot: Contact/Company sync, Deal stage update, Engagement logging (call/email/note)
-- ServiceNow: Incident create from alert, state transition + work notes, assignment group routing
-- Zendesk: Ticket creation, status/priority update, internal note vs public reply
-- Asana: Task creation in project/section, status update, comment/story append
+**Phase A — Staleness detection (low-effort, high-value):**
+- Parse `Last validated:` date from each `skill.md` header
+- Flag any doc older than 90 days in CI output
+- Open a GitHub issue automatically when a doc exceeds the threshold
+- Deliverable: `.github/workflows/freshness.yml` (weekly cron, `0 9 * * 1`) + `scripts/check-freshness.ts`
 
-**Cross-tool dependencies:**
-- Phase 1 auth foundation must be stable
-- Dedup/idempotency patterns (Phase 1) applied to all create recipes
+**Phase B — Live smoke tests (medium-effort, highest-value — the real moat):**
+- For each tool, maintain a minimal test that hits: auth endpoint + one read
+- Run weekly against sandbox environments using stored credentials (GitHub Secrets)
+- Failure creates a doc-review issue with the tool name and failing assertion
+- Candidates to start with: Jira (`/rest/api/3/myself`), GitHub (`/user`), HubSpot (`/crm/v3/objects/contacts?limit=1`)
 
 **Acceptance criteria:**
-- [ ] Each recipe has a validated request/response example
-- [ ] Pagination tested to >1 page of results
-- [ ] Incremental sync (updated_since / cursor) demonstrated for at least one search per tool
-- [ ] Dedup logic documented and tested (same input twice = no duplicate record)
-
-**Definition of done:** Each recipe can be executed end-to-end by an automation builder without consulting external docs.
+- [ ] Weekly cron runs without manual intervention
+- [ ] A PR that backdates a `Last validated:` date beyond 90 days fails the staleness check
+- [ ] Smoke test failure creates an issue and does not block `main` CI (it's a separate workflow)
 
 ---
 
-### Phase 3 — Event-Driven & Real-Time (Weeks 11–15)
+### Priority 3 — Distribution
 
-**Theme:** Replace polling with push. Webhooks and event triggers for real-time automation.
-
-**Deliverables:**
-- Monday.com: Webhook setup, column-change events, item-status triggers
-- Salesforce: Platform Events / Change Data Capture (CDC) basics; Outbound Messaging for simpler cases
-- Jira: Webhook registration (UI + API), issue-updated event structure, filtering by project/type
-- Dynamics 365: Webhooks via Plugin Registration Tool / Azure Service Bus; OData notifications
-- HubSpot: Webhook subscriptions, event types (contact.creation, deal.propertyChange), signature verification
-- ServiceNow: Outbound REST + Business Rules as webhook equivalent; Flow Designer basics
-- Zendesk: Webhook + Trigger setup, event payload structure, signature validation (X-Zendesk-Webhook-Signature)
-- Asana: Webhook registration, X-Hook-Secret handshake, event filtering
-
-**Cross-tool dependencies:**
-- Phase 2 update recipes required (webhooks trigger updates cross-system)
-- Shared webhook receiver pattern: signature verification, deduplication by event ID, idempotent handler
-
-**Acceptance criteria:**
-- [ ] Each tool: webhook registered, test event fired, handler receives and validates payload
-- [ ] Signature verification implemented and tested (reject tampered payload)
-- [ ] Idempotent event handler: same event delivered twice = processed once
-- [ ] Retry/dead-letter behavior documented per tool
-
-**Definition of done:** End-to-end event flow demonstrated: source system change → webhook delivery → target system update, with no polling.
+| Channel | Status | Next action |
+|---------|--------|-------------|
+| GitHub (public) | Ready to flip | Make repo public |
+| npm (`clawskills-mcp`) | ✅ Live — v0.2.3 | Maintain via `release.yml` |
+| MCP registry listings | Not submitted | Submit to glama.ai, mcp.so, smithery.ai after public launch |
+| Docs website | Planned | Mintlify — fastest path to SEO-friendly browsable docs |
+| Lane A vs B | TBD | Revisit after first traction signals from public launch |
 
 ---
 
-### Phase 4 — Bulk & Advanced Operations (Weeks 16–20)
-
-**Theme:** Scale up. Handle large datasets, bulk operations, and complex cross-tool orchestration.
+### Priority 4 — Complete Phase 4 & 5 gaps
 
-**Deliverables:**
-- Salesforce: Bulk API v2 (CSV ingest), SOQL aggregate queries, Composite API for multi-step
-- HubSpot: Batch create/update/read (up to 100 per batch), Import API for CSV
-- Jira: Bulk label/component updates, sprint management, custom field batch updates
-- ServiceNow: Import Sets with transform maps, batch table API calls
-- Zendesk: Bulk ticket update (update_many), Incremental Export API for full sync
-- Monday.com: Multiple mutations in single request, board duplication, subitems
-- Dynamics 365: $batch endpoint, FetchXML for complex aggregations
-- Asana: Parallel task creation patterns (respecting rate limits), Portfolio batch reads
+These are lower priority than new skills but worth finishing:
 
-**Cross-tool dependencies:**
-- All Phase 2 & 3 recipes stable
-- Rate limit / backoff patterns from Phase 1 must handle burst scenarios
+**Phase 4 gaps (Bulk operations):**
+- Salesforce Bulk API v2: end-to-end CSV ingest tested at ≥500 rows with error-row reporting
+- HubSpot batch create/update: tested at max batch size (100 records), partial-success handling
+- Zendesk Incremental Export API: full-sync recipe with cursor continuation
 
-**Acceptance criteria:**
-- [ ] Bulk create tested with ≥500 records per supported tool
-- [ ] Bulk job status polling recipe documented (for async APIs: Salesforce Bulk, ServiceNow Import Set)
-- [ ] Memory/time complexity noted for large payloads
-- [ ] Error partial-success handling documented (some rows fail, some succeed)
+**Phase 5 (Cross-tool orchestration) — first 3 recipes:**
+- Zendesk Ticket → Jira Bug (bidirectional status sync)
+- HubSpot Deal Won → Asana project creation (onboarding trigger)
+- Salesforce Lead → HubSpot Contact sync (dedup on email)
 
-**Definition of done:** An integration can process a 10,000-row export from one system and upsert into another using bulk APIs, with error reporting per failed row.
+Each recipe lives as a `## Cross-tool recipe` appendix section in the relevant primary skill doc (e.g., the Zendesk→Jira recipe goes in both `zendesk/skill.md` and `jira/skill.md`).
 
 ---
 
-### Phase 5 — Cross-Tool Orchestration & AI-Ready Patterns (Weeks 21–28)
-
-**Theme:** Connect the systems. Build the integration recipes that span multiple tools, and prepare data flows for AI enrichment.
+## Prioritization framework
 
-**Deliverables:**
-- Cross-tool recipes (documented separately or as appendices in relevant skill.md files):
-  - Salesforce Lead → HubSpot Contact sync
-  - Zendesk Ticket → Jira Bug creation (bidirectional status)
-  - ServiceNow Incident → Monday.com item (ops escalation board)
-  - HubSpot Deal Won → Asana project creation (onboarding workflow)
-  - Dynamics 365 Opportunity → Jira Epic (delivery handoff)
-- Enrichment patterns: append AI-generated summaries to ticket/task descriptions
-- Reporting aggregation: pull data from multiple tools into unified payload
-
-**Cross-tool dependencies:**
-- All Phase 1–4 skills stable
-- Canonical data model (shared field mapping table) agreed across tools
-
-**Acceptance criteria:**
-- [ ] Each cross-tool recipe: end-to-end tested in staging environments
-- [ ] Canonical IDs (external_id / reference fields) used to link records across systems
-- [ ] No data loss on failure (dead-letter queue or retry log)
-- [ ] Latency < 30s for real-time cross-tool sync
-
-**Definition of done:** A single external event (e.g., new support ticket) can automatically create linked records in 2+ systems with correct field mapping, documented in a runbook.
+Each skill/recipe is scored on five dimensions (1–5 each):
 
----
+| Dimension | Description |
+|-----------|-------------|
+| **Impact** | Business value if automated (revenue, hours saved, error reduction) |
+| **Frequency** | How often the workflow runs daily/weekly |
+| **Complexity** | Inverse score — simpler = higher priority |
+| **Risk** | Inverse score — lower risk of data loss = higher priority |
+| **Dependencies** | Whether other workflows depend on this one being stable |
 
-## Deliverables by Tool
-
-| Tool | Phase | Deliverable | Notes | Dependencies |
-|------|-------|-------------|-------|--------------|
-| All tools | 1 | Auth + Core CRUD skill sections | Sandbox environments required | None |
-| Monday.com | 1 | Auth (token + OAuth), Board/Item CRUD | GraphQL API — different pattern from REST tools | None |
-| Monday.com | 2 | Intake workflow, status sync, approval tracking | Column value JSON shapes per type | Phase 1 |
-| Monday.com | 3 | Webhook setup + column-change events | Webhooks require HTTPS endpoint | Phase 1 |
-| Monday.com | 4 | Multi-mutation requests, subitems | Complexity points budget management | Phase 2 |
-| Salesforce | 1 | Connected App, OAuth JWT, REST CRUD | Sandbox org required | None |
-| Salesforce | 2 | Lead capture, Opportunity update, Task logging | Validation rules awareness | Phase 1 |
-| Salesforce | 3 | Platform Events / CDC / Outbound Messaging | Streaming API is separate product | Phase 2 |
-| Salesforce | 4 | Bulk API v2, Composite API, SOQL aggregates | Bulk API best for >1000 rows | Phase 2 |
-| Salesforce | 5 | Lead → HubSpot sync, Opp → Jira Epic | Canonical field mapping required | Phase 4 |
-| Jira | 1 | API Token auth, Issue CRUD | Cloud vs Server distinction | None |
-| Jira | 2 | JQL search, workflow transitions, triage | ADF for rich text comments | Phase 1 |
-| Jira | 3 | Webhook registration + issue-updated events | Webhook URL must be publicly reachable | Phase 2 |
-| Jira | 4 | Bulk label/component updates, sprint ops | No native bulk create — workarounds needed | Phase 2 |
-| Jira | 5 | Zendesk Ticket → Jira Bug (bidirectional) | Status mapping table required | Phase 4 |
-| Dynamics 365 | 1 | Azure AD app registration, Web API CRUD | Azure tenant required; security roles | None |
-| Dynamics 365 | 2 | Account/Contact upsert, Opportunity update, Activity log | Solution prefix awareness | Phase 1 |
-| Dynamics 365 | 3 | Plugin/webhook setup, OData change notifications | Plugin Registration Tool needed | Phase 2 |
-| Dynamics 365 | 4 | $batch endpoint, FetchXML complex queries | FetchXML for anything OData can't express | Phase 2 |
-| Dynamics 365 | 5 | Opportunity → Jira Epic handoff | Canonical ID linking | Phase 4 |
-| HubSpot | 1 | Private App token, OAuth, CRM Object CRUD | Scopes per object type | None |
-| HubSpot | 2 | Contact/Company sync, Deal updates, Engagement logging | Properties API for custom fields | Phase 1 |
-| HubSpot | 3 | Webhook subscriptions + event handling | App registration required for webhooks | Phase 2 |
-| HubSpot | 4 | Batch APIs, Import API for CSV | 100-record batch limit | Phase 2 |
-| HubSpot | 5 | Salesforce Lead → HubSpot Contact sync | Dedup on email field | Phase 4 |
-| ServiceNow | 1 | Basic auth + OAuth, Table API CRUD | Dev instance recommended | None |
-| ServiceNow | 2 | Incident create/update, work notes, assignment | State values are integers — verify per instance | Phase 1 |
-| ServiceNow | 3 | Outbound REST + Business Rule webhooks | Flow Designer alternative | Phase 2 |
-| ServiceNow | 4 | Import Sets + transform maps, batch GETs | Transform map must be configured in UI | Phase 2 |
-| ServiceNow | 5 | Incident → Monday.com escalation board | State-to-status mapping required | Phase 4 |
-| Zendesk | 1 | API Token, OAuth, Ticket CRUD | Subdomain required for all calls | None |
-| Zendesk | 2 | Ticket create/update, note vs reply, bulk update | Status machine strictly enforced | Phase 1 |
-| Zendesk | 3 | Webhook + Trigger setup, signature verification | New webhook API vs deprecated HTTP targets | Phase 2 |
-| Zendesk | 4 | Bulk update_many, Incremental Export API | Incremental API requires Enterprise or above | Phase 2 |
-| Zendesk | 5 | Zendesk Ticket → Jira Bug (bidirectional) | Requires external_id / tag mapping | Phase 4 |
-| Asana | 1 | PAT + OAuth, Task/Project CRUD | opt_fields required for all reads | None |
-| Asana | 2 | Task creation in section, status update, story/comment | Memberships array for project placement | Phase 1 |
-| Asana | 3 | Webhook registration + X-Hook-Secret handshake | Webhook events are coarse-grained | Phase 2 |
-| Asana | 4 | Parallel task creation, Portfolio reads | No native bulk — rate limit math required | Phase 2 |
-| Asana | 5 | HubSpot Deal Won → Asana project (onboarding) | Template project duplication | Phase 4 |
+**Priority score = (Impact × 2) + (Frequency × 1.5) + Complexity + Risk + Dependencies**
 
 ---
 
-## Quality Bar & Governance
+## Quality bar & governance
 
 ### Keeping docs accurate
 
-- **Version pinning:** Each skill.md must note the API version it was validated against (e.g., Salesforce API v62.0, Jira REST API v3, Dynamics 365 v9.2). Update the version header when re-validating.
-- **Quarterly review cycle:** Each skill.md has a `Last validated:` date in its header. Docs older than 90 days are flagged for re-review.
-- **Changelog section:** Major API changes (new auth flows, deprecated endpoints, rate limit changes) are logged in a `## Changelog` section at the bottom of each skill.md.
+- **Version pinning:** Each skill.md notes the API version it was validated against. Update the version header when re-validating.
+- **Quarterly review cycle:** Docs older than 90 days are flagged by the freshness pipeline for re-review.
+- **Changelog notes:** Major API changes (new auth flows, deprecated endpoints, rate limit changes) noted inline with `> ⚠️ Changed [date]:` callouts.
 
 ### Validation approach
 
-- **Automated smoke tests:** For each tool, maintain a minimal test script (curl or SDK) that hits auth, a read, and a write. Run weekly in CI against sandbox environments. Failure triggers a doc-review issue.
-- **Breaking change monitoring:** Subscribe to each vendor's developer changelog / API release notes. Sources:
+- **CI test suite:** Real-skills tests in `mcp-server/src/index.test.ts` verify all skills load, have required sections, and are ≥5 KB.
+- **Freshness pipeline:** Weekly cron checks `Last validated:` dates (see Priority 2 above).
+- **Live smoke tests:** Optional phase B — weekly auth + read tests against sandboxes.
+- **Breaking change monitoring:** Subscribe to each vendor's developer changelog:
   - Monday: https://developer.monday.com/changelog
   - Salesforce: https://help.salesforce.com/s/articleView?id=release-notes.salesforce_release_notes.htm
   - Jira: https://developer.atlassian.com/cloud/jira/platform/changelog/
   - Dynamics 365: https://learn.microsoft.com/en-us/dynamics365/release-plans/
   - HubSpot: https://developers.hubspot.com/changelog
-  - ServiceNow: https://developer.servicenow.com/dev.do (release notes per version)
+  - ServiceNow: https://developer.servicenow.com/dev.do
   - Zendesk: https://developer.zendesk.com/api-reference/ticketing/introduction/#api-changelog
   - Asana: https://developers.asana.com/docs/changelog
+  - GitHub: https://github.blog/changelog/
+  - Figma: https://www.figma.com/developers/api#changelog
+  - Slack: https://api.slack.com/changelog
+  - Stripe: https://stripe.com/docs/changelog
+  - Notion: https://developers.notion.com/page/changelog
+  - Linear: https://linear.app/changelog
 
 ### Handling deprecations
 
@@ -245,29 +168,31 @@ Phases are ordered by descending average priority score within a theme.
 
 ### Contribution process
 
-- PRs to skill.md files require: (a) reference to official doc, (b) tested curl/pseudocode example, (c) updated `Last validated:` date.
-- All changes reviewed by at least one person who has tested against the live API.
+- PRs to `skill.md` files require: (a) reference to official doc, (b) tested curl/pseudocode example, (c) updated `Last validated:` date.
+- Branch convention: `skill/<toolname>` → PR → merge to main.
+- CI runs `npm test` on every PR — validates skill loads and has all required sections.
+- Releases: merge to main, then GitHub Actions → **Release** → Run workflow → pick `patch / minor / major`.
 
 ---
 
-## Backlog (Nice-to-Have)
-
-These items are out of scope for Phases 1–5 but worth tracking for future investment:
+## Backlog (tracked, not yet scheduled)
 
 | Item | Tool(s) | Value | Complexity |
 |------|---------|-------|------------|
-| AI-powered ticket summarization (append GPT summary to description) | Zendesk, Jira, ServiceNow | High | Medium |
+| AI-powered ticket summarization (append LLM summary to description) | Zendesk, Jira, ServiceNow | High | Medium |
 | Automated lead scoring sync | Salesforce, HubSpot | High | Medium |
 | Revenue analytics aggregation (pull pipeline across CRMs) | Salesforce, HubSpot, Dynamics 365 | High | High |
-| Admin automation: user provisioning / deprovisioning | All tools | Medium | Medium |
+| Token rotation automation (refresh before expiry) | All OAuth tools | High | Low |
+| Twilio skill (SMS/voice notifications) | Twilio | High | Medium |
+| Intercom skill (in-app messaging, user segments) | Intercom | Medium | Medium |
+| Okta/Auth0 skill (identity + SSO) | Okta | Medium | Medium |
+| PagerDuty skill (on-call, incident escalation) | PagerDuty | Medium | Low |
+| Docs website (Mintlify/Docusaurus) | — | High | Medium |
+| VS Code extension (inject skill doc into editor context) | — | Medium | High |
+| REST API / hosted endpoint for skill doc retrieval | — | Medium | High |
+| Admin automation: user provisioning/deprovisioning | All tools | Medium | Medium |
 | Compliance export (GDPR data subject requests) | Zendesk, Salesforce, HubSpot | Medium | High |
-| Monday → Asana project migration utility | Monday, Asana | Low | Medium |
-| Jira custom field schema introspection | Jira | Medium | Low |
-| Dynamics 365 Power Automate connector alternatives | Dynamics 365 | Medium | Low |
-| ServiceNow CMDB auto-discovery integration | ServiceNow | High | High |
 | Zendesk → Salesforce Case sync (bidirectional) | Zendesk, Salesforce | High | High |
-| HubSpot Sequences → Outreach/Salesloft parity | HubSpot | Medium | Medium |
-| Monday dashboards → BI tool (Looker/Tableau) export | Monday | Medium | Medium |
+| ServiceNow CMDB auto-discovery integration | ServiceNow | High | High |
 | Multi-workspace / multi-org management recipes | All tools | Medium | High |
-| Token rotation automation (refresh before expiry) | All OAuth tools | High | Low |
 | Audit log export to SIEM | Salesforce, Zendesk, ServiceNow | Medium | Medium |

package/skills/stripe/skill.md

@@ -0,0 +1,823 @@
+# Stripe Skill
+
+> **Last validated:** 2026-03-01 | **API version:** `2026-02-25.clover` (latest stable)
+> **REST base URL:** `https://api.stripe.com/v1/`
+> **Assumed product:** Stripe Payments + Billing. Stripe Connect (multi-account platform) is covered in the Auth and Recipes sections.
+
+---
+
+## What this skill enables
+
+- Collect one-time payments and save cards for future use without handling raw card data (PCI-compliant via Stripe.js / Payment Element).
+- Create and manage recurring subscriptions with automatic billing, dunning, and trial periods.
+- Issue full or partial refunds and query payment history programmatically.
+- Build hosted checkout flows (Checkout Sessions) that Stripe renders — no front-end payment UI required.
+- Handle post-payment events reliably via webhooks: fulfil orders, provision access, update CRM records.
+- Operate as a platform (Stripe Connect): onboard connected accounts, route payments, split revenue.
+- Test the full payment lifecycle with Stripe's sandbox — no real money, no bank involvement.
+
+---
+
+## Best-fit use cases
+
+| Use case | Why it matters | Primary objects | Typical trigger | Success criteria |
+|----------|---------------|-----------------|-----------------|-----------------|
+| One-time purchase | Charge a customer once for a product or service | PaymentIntent, PaymentMethod, Customer | User submits payment form | `payment_intent.succeeded` webhook received; order fulfilled |
+| Save card for future billing | Charge a returning customer without re-entering card | PaymentMethod, Customer | User checks "save card" | PaymentMethod attached to Customer; future charges succeed |
+| Recurring subscription | Monthly/annual SaaS or membership billing | Subscription, Price, Invoice, Customer | User selects plan | Subscription `active`; first invoice `paid` |
+| Hosted checkout page | Delegate payment UI to Stripe | Checkout Session | User clicks "Buy now" | `checkout.session.completed` webhook; `payment_status: paid` |
+| Issue a refund | Reverse a charge (full or partial) | Refund, Charge | Support request or automated policy | Refund `succeeded`; `charge.refunded` webhook received |
+| Failed payment recovery | Retry a failed subscription invoice | Invoice, PaymentIntent | `invoice.payment_failed` webhook | Payment retried; subscription back to `active` |
+| Multi-vendor marketplace | Route payments between platform and sellers | Connect Account, Transfer, Charge | Order placed on platform | Connected account receives funds; platform fee collected |
+| Payout reporting | Pull all payouts and match to bank statement | Payout, BalanceTransaction | Finance reconciliation run | Every payout has matching BalanceTransactions totalling net amount |
+| Metered billing | Charge based on usage at end of billing period | SubscriptionItem, UsageRecord, Invoice | Usage event from product | Invoice includes correct usage line items |
+| Payment link (no-code) | Generate a shareable URL for one-time or recurring payment | PaymentLink | Sales or support request | Customer completes payment via link; webhook confirms |
+
+---
+
+## Key concepts & data model
+
+### Core objects
+
+| Object | Description | ID prefix |
+|--------|-------------|-----------|
+| **Customer** | A person or business entity; stores payment methods and billing info | `cus_` |
+| **PaymentIntent** | The authoritative record of a payment attempt; tracks state through to success/failure | `pi_` |
+| **PaymentMethod** | A reusable token representing a card, bank account, or wallet | `pm_` |
+| **Charge** | A legacy object created when a PaymentIntent succeeds; most APIs now return the PaymentIntent directly | `ch_` |
+| **Invoice** | A bill sent to a Customer; created automatically for subscriptions | `in_` |
+| **Subscription** | A recurring billing agreement linking a Customer to one or more Prices | `sub_` |
+| **Price** | Defines the billing amount, currency, and interval for a Product | `price_` |
+| **Product** | A good or service offered; Prices are attached to Products | `prod_` |
+| **Refund** | A reversal of a Charge, full or partial | `re_` |
+| **Checkout Session** | A hosted payment page managed by Stripe | `cs_` |
+| **PaymentLink** | A shareable URL backed by a Checkout Session template | `plink_` |
+| **Transfer** | Funds moved from platform balance to a connected account | `tr_` |
+| **Payout** | Funds sent from Stripe balance to a bank account | `po_` |
+| **BalanceTransaction** | Every money movement in Stripe (fee, charge, refund, payout) | `txn_` |
+| **Event** | A webhook payload describing a state change | `evt_` |
+| **Connected Account** | An account on your platform (Stripe Connect) | `acct_` |
+
+### PaymentIntent lifecycle
+
+```
+requires_payment_method → requires_confirmation → requires_action → processing → succeeded
+                                                                               ↘ canceled
+```
+
+| Status | Meaning |
+|--------|---------|
+| `requires_payment_method` | No valid payment method attached yet |
+| `requires_confirmation` | Payment method attached; awaiting explicit confirm call |
+| `requires_action` | 3D Secure or redirect authentication needed from the customer |
+| `processing` | Bank processing in progress (instant cards transition through this quickly) |
+| `succeeded` | Payment captured; funds reserved or settled |
+| `canceled` | Cancelled; a new PaymentIntent must be created |
+
+### Subscription lifecycle
+
+| Status | Meaning |
+|--------|---------|
+| `trialing` | In free trial; no payment yet |
+| `active` | In good standing; latest invoice paid |
+| `incomplete` | First payment not yet made; customer has 23 hours |
+| `incomplete_expired` | Initial 23-hour window expired without payment |
+| `past_due` | Latest renewal invoice failed; automatic retries in progress |
+| `unpaid` | Retries exhausted; subscription remains but no more attempts |
+| `paused` | Trial ended without a default payment method |
+| `canceled` | Terminal; cannot be reactivated |
+
+### Amounts and currencies
+
+All monetary amounts are in the **smallest currency unit** — cents for USD, pence for GBP, yen for JPY (which has no subunit, so `100` = ¥100). Always store and pass amounts as integers.
+
+### Expandable fields
+
+Any field that returns an ID (e.g., `"customer": "cus_xxx"`) can be expanded to the full object by passing `expand[]=customer` in the request. Nest with dots: `expand[]=latest_invoice.payment_intent`.
+
+### Metadata
+
+Every Stripe object has a `metadata` dictionary for storing arbitrary key/value pairs (e.g., your internal IDs). Limits: 50 keys per object, key ≤ 40 chars, value ≤ 500 chars.
+
+---
+
+## Authentication & permissions
+
+### API key types
+
+| Key type | Prefix | Use | Never in |
+|----------|--------|-----|----------|
+| Secret (live) | `sk_live_` | Server-side; full API access | Client-side code, logs, version control |
+| Secret (sandbox) | `sk_test_` | Server-side; test mode only | Production environments |
+| Publishable (live) | `pk_live_` | Browser/mobile; only creates tokens | Server-side requests |
+| Publishable (sandbox) | `pk_test_` | Browser/mobile; test mode | Production environments |
+| Restricted | `rk_live_` / `rk_test_` | Server-side; limited to specific resources | When full access is needed |
+
+Create restricted keys in **Dashboard → Developers → API keys → Create restricted key**. Assign **None / Read / Write** per resource (Customers, PaymentIntents, Subscriptions, etc.).
+
+### Authentication header
+
+Stripe uses HTTP Basic auth with the secret key as the username and an empty password. All major HTTP clients also accept `Authorization: Bearer sk_...`:
+
+```bash
+# Basic auth (canonical Stripe style)
+curl https://api.stripe.com/v1/customers \
+  -u "sk_test_51Abc123...:
+
+# Bearer token (equivalent)
+curl https://api.stripe.com/v1/customers \
+  -H "Authorization: Bearer sk_test_51Abc123..."
+```
+
+### API version pinning
+
+Always pin the API version explicitly to avoid unexpected behaviour when Stripe releases a new default:
+
+```bash
+curl https://api.stripe.com/v1/payment_intents \
+  -u "sk_test_...:" \
+  -H "Stripe-Version: 2026-02-25.clover" \
+  -d amount=2000 \
+  -d currency=usd
+```
+
+Set a default version for your account in **Dashboard → Developers → API version**. The SDK reads your account default unless you override per-request.
+
+### Stripe Connect — acting on behalf of a connected account
+
+Pass `Stripe-Account: acct_xxx` to perform an API call in the context of a connected account using your platform key:
+
+```bash
+curl https://api.stripe.com/v1/customers \
+  -u "sk_live_platform...:" \
+  -H "Stripe-Account: acct_1ABCxyzConnected"
+```
+
+### Idempotency keys
+
+Use `Idempotency-Key` on every `POST` request to safely retry without double-charging:
+
+```bash
+curl https://api.stripe.com/v1/payment_intents \
+  -u "sk_test_...:" \
+  -H "Idempotency-Key: $(uuidgen)" \
+  -d amount=2000 \
+  -d currency=usd
+```
+
+- Keys are strings up to 255 characters; UUIDs v4 are recommended.
+- Results are cached for **24 hours**. Reusing a key after expiry generates a new request.
+- Reusing a key with **different parameters** returns a `409 Conflict` `idempotency_error`.
+- Only use on `POST` — `GET` and `DELETE` are inherently idempotent.
+
+---
+
+## Common workflows (recipes)
+
+### 1. Create a one-time payment (PaymentIntent flow)
+
+**Server-side — create PaymentIntent:**
+
+```bash
+curl https://api.stripe.com/v1/payment_intents \
+  -u "sk_test_...:" \
+  -H "Idempotency-Key: order-42-$(date +%s)" \
+  -d amount=4999 \
+  -d currency=usd \
+  -d "automatic_payment_methods[enabled]=true" \
+  -d "metadata[order_id]=order_42"
+```
+
+**Response (key fields):**
+
+```json
+{
+  "id": "pi_3OxAbc2eZvKYlo2C1hb8mT9k",
+  "object": "payment_intent",
+  "amount": 4999,
+  "currency": "usd",
+  "status": "requires_payment_method",
+  "client_secret": "pi_3OxAbc...hb8mT9k_secret_Xyz",
+  "metadata": { "order_id": "order_42" }
+}
+```
+
+**Client-side — confirm with Stripe.js:**
+
+```javascript
+const { error } = await stripe.confirmPayment({
+  elements,                      // Stripe Elements instance
+  clientSecret: pi.client_secret,
+  confirmParams: {
+    return_url: "https://example.com/order/complete"
+  }
+});
+```
+
+**Fulfil on webhook `payment_intent.succeeded`** — see Recipes #7.
+
+---
+
+### 2. Save a card for future use
+
+```bash
+# Step 1 — create or retrieve the Customer
+curl https://api.stripe.com/v1/customers \
+  -u "sk_test_...:" \
+  -d email="alice@example.com" \
+  -d "metadata[user_id]=usr_99"
+
+# Step 2 — create a SetupIntent (confirm later via Stripe.js)
+curl https://api.stripe.com/v1/setup_intents \
+  -u "sk_test_...:" \
+  -d customer=cus_PAbcXyz \
+  -d "automatic_payment_methods[enabled]=true"
+```
+
+After the client confirms the SetupIntent, the PaymentMethod is attached to the Customer. To charge it later:
+
+```bash
+curl https://api.stripe.com/v1/payment_intents \
+  -u "sk_test_...:" \
+  -d amount=2000 \
+  -d currency=usd \
+  -d customer=cus_PAbcXyz \
+  -d payment_method=pm_1ABCdefGhIjKlMnO \
+  -d confirm=true \
+  -d off_session=true
+```
+
+`off_session=true` signals that the customer is not present — Stripe will attempt to complete without 3DS if allowed by the card issuer.
+
+---
+
+### 3. Create a subscription
+
+```bash
+# Step 1 — ensure Customer has a default PaymentMethod
+curl https://api.stripe.com/v1/customers/cus_PAbcXyz \
+  -u "sk_test_...:" \
+  -X POST \
+  -d invoice_settings[default_payment_method]=pm_1ABCdefGhIjKlMnO
+
+# Step 2 — create the Subscription
+curl https://api.stripe.com/v1/subscriptions \
+  -u "sk_test_...:" \
+  -d customer=cus_PAbcXyz \
+  -d "items[0][price]=price_1ABCdefGhIjKlMnO" \
+  -d payment_behavior=default_incomplete \
+  -d "expand[]=latest_invoice.payment_intent"
+```
+
+`payment_behavior=default_incomplete` starts the subscription in `incomplete` status — confirm payment client-side using the `latest_invoice.payment_intent.client_secret` before it expires (23 hours).
+
+**Response (key fields):**
+
+```json
+{
+  "id": "sub_1ABCdef...",
+  "status": "incomplete",
+  "current_period_end": 1740000000,
+  "latest_invoice": {
+    "id": "in_1ABCdef...",
+    "payment_intent": {
+      "id": "pi_1ABCdef...",
+      "client_secret": "pi_...secret_..."
+    }
+  }
+}
+```
+
+---
+
+### 4. Create a hosted Checkout Session
+
+No front-end payment form — Stripe hosts and renders it:
+
+```bash
+curl https://api.stripe.com/v1/checkout/sessions \
+  -u "sk_test_...:" \
+  -d mode=payment \
+  -d "line_items[0][price]=price_1ABCdefGhIjKlMnO" \
+  -d "line_items[0][quantity]=1" \
+  -d success_url="https://example.com/success?session_id={CHECKOUT_SESSION_ID}" \
+  -d cancel_url="https://example.com/cancel" \
+  -d customer_email="alice@example.com"
+```
+
+Redirect the browser to `session.url`. Stripe handles the payment UI and redirects to `success_url` on completion. Confirm fulfilment via `checkout.session.completed` webhook — do not trust the redirect URL alone.
+
+For a subscription Checkout Session, change `mode=subscription` and pass a recurring Price.
+
+---
+
+### 5. Issue a full refund
+
+```bash
+curl https://api.stripe.com/v1/refunds \
+  -u "sk_test_...:" \
+  -H "Idempotency-Key: refund-ch_1ABC-$(date +%s)" \
+  -d charge=ch_1ABCdefGhIjKlMnO
+```
+
+**Partial refund** — add `amount` in cents:
+
+```bash
+curl https://api.stripe.com/v1/refunds \
+  -u "sk_test_...:" \
+  -d charge=ch_1ABCdefGhIjKlMnO \
+  -d amount=500
+```
+
+**Response (key fields):**
+
+```json
+{
+  "id": "re_1ABCdef...",
+  "object": "refund",
+  "amount": 500,
+  "status": "succeeded",
+  "charge": "ch_1ABCdef..."
+}
+```
+
+Watch for `charge.refunded` webhook for async confirmation.
+
+---
+
+### 6. Handle a failed subscription payment
+
+```python
+import stripe
+
+stripe.api_key = "sk_live_..."
+
+# Called from your webhook handler when invoice.payment_failed fires
+def handle_payment_failed(invoice_id: str) -> None:
+    invoice = stripe.Invoice.retrieve(invoice_id, expand=["subscription"])
+    sub = invoice.subscription
+
+    if sub.status == "past_due":
+        # Notify the customer to update their payment method
+        send_dunning_email(sub.customer, invoice.hosted_invoice_url)
+
+    # Stripe will automatically retry according to your retry schedule
+    # (Dashboard → Settings → Billing → Retry schedule)
+    # To trigger an immediate retry:
+    # stripe.Invoice.pay(invoice_id)
+```
+
+When the customer updates their payment method:
+
+```bash
+# Attach the new PaymentMethod to the Customer
+curl https://api.stripe.com/v1/payment_methods/pm_NEW.../attach \
+  -u "sk_live_...:" \
+  -d customer=cus_PAbcXyz
+
+# Attempt to pay the open invoice immediately
+curl https://api.stripe.com/v1/invoices/in_OPEN.../pay \
+  -u "sk_live_...:" \
+  -X POST
+```
+
+---
+
+### 7. Webhook receiver — verify and dispatch
+
+```python
+import stripe
+from flask import Flask, request, jsonify
+
+app = Flask(__name__)
+stripe.api_key = "sk_live_..."
+WEBHOOK_SECRET = "whsec_..."
+
+@app.post("/stripe/webhook")
+def webhook():
+    sig = request.headers.get("Stripe-Signature")
+    try:
+        event = stripe.Webhook.construct_event(
+            payload=request.data,      # raw bytes — do NOT parse JSON first
+            sig_header=sig,
+            secret=WEBHOOK_SECRET,
+        )
+    except stripe.error.SignatureVerificationError:
+        return jsonify(error="invalid signature"), 400
+
+    match event["type"]:
+        case "payment_intent.succeeded":
+            handle_payment_succeeded(event["data"]["object"])
+        case "invoice.paid":
+            handle_invoice_paid(event["data"]["object"])
+        case "customer.subscription.deleted":
+            handle_subscription_cancelled(event["data"]["object"])
+        case "checkout.session.completed":
+            handle_checkout_complete(event["data"]["object"])
+
+    # Must return 2xx within ~30 seconds or Stripe retries
+    return jsonify(ok=True), 200
+```
+
+**Critical rules:**
+- Always verify the `Stripe-Signature` header before processing.
+- Read raw request body — any JSON parsing before `construct_event` may corrupt the signature.
+- Return `200` before triggering long-running work (enqueue a job instead).
+- Make handlers **idempotent** — Stripe may deliver the same event more than once. Use `event.id` to deduplicate.
+
+---
+
+### 8. Stripe Connect — charge on a connected account (destination charge)
+
+```bash
+# Create a PaymentIntent where funds go to the connected account
+# Platform retains application_fee_amount
+curl https://api.stripe.com/v1/payment_intents \
+  -u "sk_live_platform...:" \
+  -d amount=5000 \
+  -d currency=usd \
+  -d "automatic_payment_methods[enabled]=true" \
+  -d transfer_data[destination]=acct_1ConnectedAcct \
+  -d application_fee_amount=500
+```
+
+**Direct charge** (create on the connected account itself):
+
+```bash
+curl https://api.stripe.com/v1/payment_intents \
+  -u "sk_live_platform...:" \
+  -H "Stripe-Account: acct_1ConnectedAcct" \
+  -d amount=5000 \
+  -d currency=usd \
+  -d "automatic_payment_methods[enabled]=true"
+```
+
+**Create a connected account (Express onboarding):**
+
+```bash
+# Step 1 — create the account
+curl https://api.stripe.com/v1/accounts \
+  -u "sk_live_platform...:" \
+  -d type=express \
+  -d country=US \
+  -d email="seller@example.com"
+# → { "id": "acct_1ABCdef...", ... }
+
+# Step 2 — generate onboarding link
+curl https://api.stripe.com/v1/account_links \
+  -u "sk_live_platform...:" \
+  -d account=acct_1ABCdef \
+  -d "refresh_url=https://example.com/reauth" \
+  -d "return_url=https://example.com/onboarded" \
+  -d type=account_onboarding
+# → { "url": "https://connect.stripe.com/setup/e/..." }
+```
+
+---
+
+### 9. Retrieve customer payment history (list charges)
+
+```python
+import stripe
+
+stripe.api_key = "sk_live_..."
+
+def get_customer_charges(customer_id: str, limit: int = 100) -> list:
+    charges = []
+    params = {
+        "customer": customer_id,
+        "limit": 100,
+    }
+    while True:
+        page = stripe.Charge.list(**params)
+        charges.extend(page.data)
+        if not page.has_more:
+            break
+        params["starting_after"] = page.data[-1].id
+    return charges
+```
+
+---
+
+### 10. Cancel a subscription (at period end)
+
+```bash
+# Cancel at the end of the current billing period (no proration)
+curl https://api.stripe.com/v1/subscriptions/sub_1ABCdef... \
+  -u "sk_live_...:" \
+  -X POST \
+  -d cancel_at_period_end=true
+
+# Cancel immediately
+curl https://api.stripe.com/v1/subscriptions/sub_1ABCdef... \
+  -u "sk_live_...:" \
+  -X DELETE
+```
+
+Listen for `customer.subscription.deleted` webhook to revoke access.
+
+---
+
+## Query patterns & filtering
+
+### Cursor-based pagination
+
+All list endpoints return a consistent envelope:
+
+```json
+{
+  "object": "list",
+  "data": [ ... ],
+  "has_more": true,
+  "url": "/v1/charges"
+}
+```
+
+Parameters:
+
+| Parameter | Type | Default | Max | Description |
+|-----------|------|---------|-----|-------------|
+| `limit` | integer | 10 | 100 | Items per page |
+| `starting_after` | string | — | — | ID of last item on previous page (forward pagination) |
+| `ending_before` | string | — | — | ID of first item on next page (backward pagination) |
+
+`starting_after` and `ending_before` are mutually exclusive.
+
+### Date range filters
+
+All list endpoints support `created[gte]` / `created[lte]` (Unix timestamps):
+
+```bash
+# All charges from the last 7 days
+curl "https://api.stripe.com/v1/charges?limit=100&created[gte]=$(date -v-7d +%s)" \
+  -u "sk_live_...:"
+```
+
+Other common filter parameters:
+
+| Endpoint | Filter | Example |
+|----------|--------|---------|
+| `/v1/charges` | `customer`, `payment_intent`, `created[gte/lte]` | `customer=cus_xxx` |
+| `/v1/subscriptions` | `customer`, `status`, `price`, `current_period_end[gte]` | `status=past_due` |
+| `/v1/invoices` | `customer`, `subscription`, `status`, `due_date[gte]` | `status=open` |
+| `/v1/payment_intents` | `customer`, `created[gte/lte]` | `customer=cus_xxx` |
+| `/v1/refunds` | `charge`, `payment_intent`, `created[gte/lte]` | `charge=ch_xxx` |
+
+### Auto-pagination (Python SDK)
+
+```python
+# Iterates all pages automatically
+for charge in stripe.Charge.list(customer="cus_xxx", limit=100).auto_paging_iter():
+    process(charge)
+```
+
+### Search API
+
+Stripe has a structured Search API for Customers, PaymentIntents, Charges, Subscriptions, and Invoices:
+
+```bash
+curl "https://api.stripe.com/v1/customers/search?query=email:'alice@example.com'" \
+  -u "sk_live_...:"
+```
+
+Search is rate-limited to **20 read operations per second** (stricter than list endpoints).
+
+---
+
+## Reliability: rate limits, retries, idempotency
+
+### Rate limits
+
+| Mode | Global limit | Notes |
+|------|-------------|-------|
+| Live | **100 req/sec** | Per account; some endpoints are stricter (see below) |
+| Sandbox | **25 req/sec** | Intentionally lower to surface rate-limit bugs early |
+
+**Endpoint-specific limits (stricter):**
+
+| Endpoint | Limit |
+|----------|-------|
+| Search API | 20 read ops/sec |
+| Files API | 20 reads/sec, 20 writes/sec |
+| Meter Events (`/v1/billing/meter_events`) | 1,000/sec live |
+| PaymentIntent updates | 1,000 updates/PaymentIntent/hr |
+| Create Payout | 15/sec, 30 concurrent |
+| Connect — create account | 5/sec sandbox, 30/sec live |
+
+### Rate limit response
+
+HTTP `429` with header:
+
+```
+Stripe-Rate-Limited-Reason: global-rate
+```
+
+Possible values: `global-concurrency`, `global-rate`, `endpoint-concurrency`, `endpoint-rate`, `resource-specific`.
+
+### Retry with exponential backoff + jitter
+
+```python
+import time, random, stripe
+
+def stripe_call_with_retry(fn, *args, max_retries=5, **kwargs):
+    for attempt in range(max_retries):
+        try:
+            return fn(*args, **kwargs)
+        except stripe.error.RateLimitError:
+            if attempt == max_retries - 1:
+                raise
+            wait = (2 ** attempt) + random.uniform(0, 1)
+            time.sleep(wait)
+        except stripe.error.APIConnectionError:
+            if attempt == max_retries - 1:
+                raise
+            time.sleep(2 ** attempt)
+```
+
+**Python SDK auto-retry:** `stripe.max_network_retries = 3` enables built-in retry for network errors and `429`s.
+
+### Idempotency
+
+- Include `Idempotency-Key` on every `POST` (charge, refund, subscription creation).
+- Use a stable key derived from your internal operation ID, e.g., `f"order-{order_id}-payment"`.
+- Results cached **24 hours**; same key = same response (including `5xx` errors).
+- Different params + same key = `409 idempotency_error`.
+
+```python
+stripe.PaymentIntent.create(
+    amount=4999,
+    currency="usd",
+    idempotency_key=f"order-{order_id}-payment-intent",
+)
+```
+
+---
+
+## Error handling & troubleshooting
+
+### Error object
+
+```json
+{
+  "error": {
+    "type": "card_error",
+    "code": "card_declined",
+    "decline_code": "insufficient_funds",
+    "message": "Your card has insufficient funds.",
+    "param": null,
+    "charge": "ch_1ABCdef...",
+    "doc_url": "https://stripe.com/docs/error-codes/card-declined"
+  }
+}
+```
+
+### HTTP status → action
+
+| Status | Type | Action |
+|--------|------|--------|
+| `400` | `invalid_request_error` | Fix the request — missing or malformed parameter. Check `error.param`. |
+| `401` | `api_error` | Invalid API key. Verify `sk_live_`/`sk_test_` prefix matches environment. |
+| `402` | `card_error` | Card declined or transaction failed. Show `error.message` to the user. |
+| `403` | `api_error` | Insufficient permissions — use a secret key or check restricted key scopes. |
+| `404` | `invalid_request_error` | Object not found. Verify the ID prefix matches the endpoint. |
+| `409` | `idempotency_error` | Same idempotency key reused with different params. Generate a new key. |
+| `429` | — | Rate limited. Retry with exponential backoff; see `Stripe-Rate-Limited-Reason`. |
+| `5xx` | `api_error` | Stripe infrastructure issue. Retry with backoff; check https://status.stripe.com. |
+
+### Error type → handler
+
+| `error.type` | Meaning | What to do |
+|--------------|---------|------------|
+| `card_error` | Card issue (decline, insufficient funds, expired) | Show `error.message` to the end user; do not retry without user action |
+| `invalid_request_error` | Bad API request | Fix the code; do not retry unchanged |
+| `api_error` | Stripe-side problem | Retry with exponential backoff |
+| `idempotency_error` | Key reused with different params | Generate a new idempotency key |
+
+### Common `decline_code` values
+
+| `decline_code` | Meaning | User-facing message |
+|----------------|---------|---------------------|
+| `card_declined` | Generic decline from issuer | "Your card was declined. Please try a different card." |
+| `insufficient_funds` | Not enough balance | "Your card has insufficient funds." |
+| `expired_card` | Card expired | "Your card is expired. Please update your payment method." |
+| `incorrect_cvc` | Wrong CVC | "Incorrect security code. Please check and try again." |
+| `stolen_card` / `lost_card` | Flagged by issuer | "Your card was declined. Please contact your bank." |
+| `do_not_honor` | Issuer catch-all decline | "Your card was declined. Please try a different card or contact your bank." |
+| `fraudulent` | Stripe Radar blocked | Log internally; do not tell user it was flagged as fraud |
+
+### Troubleshooting checklist
+
+| Symptom | Likely cause | Fix |
+|---------|-------------|-----|
+| `401 Unauthorized` | Wrong key or test key in prod | Confirm key prefix: `sk_live_` for production |
+| `404` on a valid-looking ID | Wrong mode (test ID in live mode) | `pi_test_...` IDs only work with `sk_test_...` |
+| Webhook `400` signature failure | Raw body was parsed/modified | Use `request.data` (raw bytes) before passing to `construct_event` |
+| `409 idempotency_error` | Same key, different params | Generate a fresh UUID for the new request |
+| Subscription stuck `incomplete` | Customer never confirmed payment | Send them the `latest_invoice.hosted_invoice_url`; confirm within 23 hours |
+| `402` on off-session charge | 3DS required | Handle `requires_action` — send `payment_intent.client_secret` to customer |
+| Webhook events arriving twice | Stripe retry after timeout | Make handlers idempotent; deduplicate on `event.id` |
+
+---
+
+## Security & compliance
+
+### PCI compliance
+
+Stripe handles PCI scope when you use Stripe.js / Stripe Elements / Payment Element or Checkout Sessions — you never touch raw card numbers. Maintain **SAQ A** compliance:
+
+- Never log, store, or transmit raw card numbers (`number`, `cvc`, full `exp_month`/`exp_year` combination).
+- Never accept card data in your own API endpoint — only accept PaymentMethod IDs (`pm_...`) or tokens.
+- Serve your payment page over HTTPS.
+- If you find card data in logs, rotate the API keys immediately and notify Stripe.
+
+### API key security
+
+- Store keys in environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault), never in source code.
+- Use **restricted keys** for operations that don't need full access (e.g., a reporting service needs only `Read` on `Charges` and `Invoices`).
+- Rotate keys immediately on suspected exposure: Dashboard → API keys → Roll key.
+- Use `sk_test_` in all non-production environments — a test key can never trigger live charges.
+
+### Webhook security
+
+- Always verify `Stripe-Signature` before processing any webhook payload.
+- Use a **separate webhook signing secret** (`whsec_...`) per endpoint — do not reuse across environments.
+- Store the signing secret in environment variables.
+- Reject webhooks with a timestamp more than **5 minutes** old to prevent replay attacks (the SDK does this by default with a 300-second tolerance).
+
+### Stripe Connect — platform responsibilities
+
+- Use the minimum Connect account type needed (Express > Standard > Custom — lower customisation = lower compliance burden).
+- Platforms are responsible for complying with KYC/AML requirements for their connected accounts.
+- Never display the connected account's full bank account or SSN to end users.
+
+### Audit trail
+
+Every API action is logged in **Dashboard → Developers → Logs** (7-day retention for all accounts; extended with Sigma). Use `metadata` to attach your internal IDs for easier cross-referencing.
+
+---
+
+## Testing checklist
+
+Use sandbox keys (`sk_test_`, `pk_test_`) and the test card numbers below. No real money moves.
+
+### Test card numbers
+
+| Scenario | Card number | Expiry | CVC |
+|----------|-------------|--------|-----|
+| Payment succeeds | `4242 4242 4242 4242` | Any future | Any 3 digits |
+| Payment declined (generic) | `4000 0000 0000 0002` | Any future | Any 3 digits |
+| Insufficient funds | `4000 0000 0000 9995` | Any future | Any 3 digits |
+| 3D Secure required | `4000 0025 0000 3155` | Any future | Any 3 digits |
+| 3D Secure 2 — frictionless pass | `4000 0000 0000 3220` | Any future | Any 3 digits |
+| Card expired | `4000 0000 0000 0069` | Any future | Any 3 digits |
+| Incorrect CVC | `4000 0000 0000 0101` | Any future | Any 3 digits |
+| Mastercard success | `5555 5555 5555 4444` | Any future | Any 3 digits |
+
+### Trigger test webhook events (Stripe CLI)
+
+```bash
+# Install: brew install stripe/stripe-cli/stripe
+stripe login
+stripe listen --forward-to localhost:8000/stripe/webhook
+
+# In a separate terminal:
+stripe trigger payment_intent.succeeded
+stripe trigger invoice.payment_failed
+stripe trigger customer.subscription.deleted
+stripe trigger checkout.session.completed
+```
+
+### QA checklist
+
+- [ ] PaymentIntent created in sandbox; `client_secret` returned
+- [ ] Test card `4242...` → PaymentIntent reaches `succeeded`
+- [ ] Decline card `4000...0002` → `402` with `card_error`, `decline_code: card_declined`
+- [ ] 3DS card `4000...3155` → PaymentIntent reaches `requires_action`; completes after challenge
+- [ ] Refund issued on succeeded Charge; `re_...` returned with `status: succeeded`
+- [ ] Subscription created with `payment_behavior=default_incomplete`; first invoice payment confirmed
+- [ ] `invoice.payment_failed` webhook received and processed without error
+- [ ] `cancel_at_period_end=true` sets flag; `customer.subscription.deleted` fires at period end
+- [ ] Webhook signature verification passes for valid payload; returns `400` for tampered payload
+- [ ] Idempotency key: same request sent twice → identical response, no duplicate charge
+- [ ] Pagination loop retrieves all pages (`has_more=false` terminates loop)
+- [ ] Rate limit hit in sandbox (25 req/sec); `429` handled with backoff, eventual success
+
+---
+
+## Sources
+
+- [Stripe API Reference](https://docs.stripe.com/api)
+- [Authentication & API Keys](https://docs.stripe.com/keys)
+- [API Versioning & Changelog](https://docs.stripe.com/changelog)
+- [Payment Intents](https://docs.stripe.com/payments/payment-intents)
+- [Subscriptions Overview](https://docs.stripe.com/billing/subscriptions/overview)
+- [Checkout Sessions](https://docs.stripe.com/payments/checkout)
+- [Refunds](https://docs.stripe.com/refunds)
+- [Webhook Integration](https://docs.stripe.com/webhooks)
+- [Idempotent Requests](https://docs.stripe.com/idempotency)
+- [Rate Limits](https://docs.stripe.com/rate-limits)
+- [Error Codes](https://docs.stripe.com/error-codes)
+- [Stripe Connect](https://docs.stripe.com/connect)
+- [Testing](https://docs.stripe.com/testing)
+- [Security Best Practices](https://docs.stripe.com/security)
+- [API Status](https://status.stripe.com)