codebyplan 1.13.46 → 1.13.49
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cli.js +33 -13
- package/package.json +1 -1
- package/templates/agents/cbp-cc-executor.md +0 -1
- package/templates/agents/cbp-database-agent.md +0 -1
- package/templates/agents/cbp-e2e-maestro.md +0 -1
- package/templates/agents/cbp-e2e-playwright.md +0 -1
- package/templates/agents/cbp-e2e-tauri.md +0 -1
- package/templates/agents/cbp-e2e-vscode.md +0 -1
- package/templates/agents/cbp-e2e-xcuitest.md +0 -1
- package/templates/agents/cbp-improve-claude.md +0 -1
- package/templates/agents/cbp-improve-round.md +0 -1
- package/templates/agents/cbp-map-architecture.md +0 -1
- package/templates/agents/cbp-mechanical-edits.md +0 -1
- package/templates/agents/cbp-research.md +0 -1
- package/templates/agents/cbp-round-executor.md +7 -1
- package/templates/agents/cbp-security-agent.md +0 -1
- package/templates/agents/cbp-stripe-agent.md +173 -0
- package/templates/agents/cbp-task-check.md +0 -1
- package/templates/agents/cbp-task-planner.md +0 -1
- package/templates/agents/cbp-testing-qa-agent.md +0 -1
- package/templates/hooks/cbp-auto-test-hooks.sh +0 -1
- package/templates/hooks/cbp-canonical-templates-nudge.sh +0 -1
- package/templates/hooks/cbp-context-window-notify.sh +0 -1
- package/templates/hooks/cbp-e2e-spec-patterns.sh +0 -1
- package/templates/hooks/cbp-lint-format-on-edit.sh +0 -1
- package/templates/hooks/cbp-maestro-yaml-validate.sh +0 -1
- package/templates/hooks/cbp-mcp-caller-worktree-inject.sh +0 -1
- package/templates/hooks/cbp-mcp-migration-guard.sh +0 -1
- package/templates/hooks/cbp-mcp-round-sync.sh +0 -1
- package/templates/hooks/cbp-plugin-dispatch.sh +0 -1
- package/templates/hooks/cbp-pre-commit-quality-gate.sh +0 -1
- package/templates/hooks/cbp-session-start-hook.sh +0 -1
- package/templates/hooks/cbp-statusline.mjs +0 -1
- package/templates/hooks/cbp-statusline.py +0 -1
- package/templates/hooks/cbp-statusline.sh +0 -1
- package/templates/hooks/cbp-subagent-statusline.mjs +0 -1
- package/templates/hooks/cbp-subagent-statusline.py +0 -1
- package/templates/hooks/cbp-subagent-statusline.sh +0 -1
- package/templates/hooks/cbp-test-coverage-gate.sh +0 -1
- package/templates/hooks/cbp-test-hooks.sh +0 -1
- package/templates/hooks/validate-context-usage.sh +0 -1
- package/templates/hooks/validate-git-commit.sh +57 -9
- package/templates/hooks/validate-git-stash-deny.sh +0 -1
- package/templates/hooks/validate-structure-lengths.sh +0 -1
- package/templates/hooks/validate-structure-lib.sh +17 -1
- package/templates/hooks/validate-structure-patterns.sh +0 -1
- package/templates/hooks/validate-structure-scope.sh +43 -11
- package/templates/hooks/validate-structure-smoke.sh +0 -1
- package/templates/hooks/validate-structure-templates.sh +0 -1
- package/templates/hooks/validate-structure.sh +0 -1
- package/templates/hooks/verify-parity.sh +0 -1
- package/templates/rules/agent-claim-verification.md +0 -1
- package/templates/rules/architecture-map.md +0 -4
- package/templates/rules/cbp-operating-gotchas.md +0 -4
- package/templates/rules/context-file-loading.md +0 -1
- package/templates/rules/e2e-mandatory.md +0 -4
- package/templates/rules/parallel-waves.md +0 -1
- package/templates/rules/scope-vocabulary.md +14 -10
- package/templates/rules/supabase-branch-lifecycle.md +0 -1
- package/templates/rules/todo-backend.md +0 -1
- package/templates/settings.project.base.json +13 -0
- package/templates/skills/cbp-build-cc-agent/SKILL.md +2 -3
- package/templates/skills/cbp-build-cc-agent/reference/cbp-quality.md +6 -8
- package/templates/skills/cbp-build-cc-agent/scripts/validate-agent.sh +10 -1
- package/templates/skills/cbp-build-cc-claude-file/SKILL.md +0 -1
- package/templates/skills/cbp-build-cc-claude-file/scripts/validate-claude-file.sh +0 -1
- package/templates/skills/cbp-build-cc-mode/SKILL.md +0 -1
- package/templates/skills/cbp-build-cc-rule/SKILL.md +18 -8
- package/templates/skills/cbp-build-cc-rule/scripts/validate-rule.sh +4 -5
- package/templates/skills/cbp-build-cc-settings/SKILL.md +0 -1
- package/templates/skills/cbp-build-cc-settings/reference/cbp-conventions.md +0 -4
- package/templates/skills/cbp-build-cc-settings/scripts/validate-settings.sh +0 -1
- package/templates/skills/cbp-build-cc-skill/SKILL.md +0 -1
- package/templates/skills/cbp-build-cc-skill/reference/cbp-quality.md +6 -8
- package/templates/skills/cbp-build-cc-skill/scripts/validate-skill.sh +10 -2
- package/templates/skills/cbp-checkpoint-check/SKILL.md +0 -1
- package/templates/skills/cbp-checkpoint-complete/SKILL.md +0 -1
- package/templates/skills/cbp-checkpoint-create/SKILL.md +10 -11
- package/templates/skills/cbp-checkpoint-end/SKILL.md +0 -1
- package/templates/skills/cbp-checkpoint-plan/SKILL.md +0 -1
- package/templates/skills/cbp-checkpoint-plan/reference/alternative-comparison-template.md +0 -4
- package/templates/skills/cbp-checkpoint-plan/reference/dep-decision-rubric.md +0 -4
- package/templates/skills/cbp-checkpoint-plan/reference/e2e-discovery-probe.md +0 -4
- package/templates/skills/cbp-checkpoint-plan/reference/gap-analysis-playbook.md +0 -4
- package/templates/skills/cbp-checkpoint-start/SKILL.md +0 -1
- package/templates/skills/cbp-checkpoint-update/SKILL.md +0 -1
- package/templates/skills/cbp-frontend-a11y/SKILL.md +0 -1
- package/templates/skills/cbp-frontend-design/SKILL.md +0 -1
- package/templates/skills/cbp-frontend-ui/SKILL.md +0 -1
- package/templates/skills/cbp-frontend-ux/SKILL.md +0 -1
- package/templates/skills/cbp-git-branch-feat-create/SKILL.md +0 -1
- package/templates/skills/cbp-git-commit/SKILL.md +0 -1
- package/templates/skills/cbp-git-worktree-create/SKILL.md +0 -1
- package/templates/skills/cbp-git-worktree-remove/SKILL.md +0 -1
- package/templates/skills/cbp-map-architecture/SKILL.md +0 -1
- package/templates/skills/cbp-merge-main/SKILL.md +0 -1
- package/templates/skills/cbp-refresh-arch-map/SKILL.md +0 -1
- package/templates/skills/cbp-round-check/SKILL.md +0 -1
- package/templates/skills/cbp-round-complete/SKILL.md +0 -1
- package/templates/skills/cbp-round-end/SKILL.md +0 -1
- package/templates/skills/cbp-round-execute/SKILL.md +9 -2
- package/templates/skills/cbp-round-execute/reference/inline-fallback.md +0 -4
- package/templates/skills/cbp-round-input/SKILL.md +0 -1
- package/templates/skills/cbp-round-start/SKILL.md +0 -1
- package/templates/skills/cbp-round-update/SKILL.md +0 -1
- package/templates/skills/cbp-session-end/SKILL.md +0 -1
- package/templates/skills/cbp-session-start/SKILL.md +0 -1
- package/templates/skills/cbp-session-start/qa-regression.md +0 -1
- package/templates/skills/cbp-setup-e2e/SKILL.md +0 -1
- package/templates/skills/cbp-setup-eslint/SKILL.md +0 -1
- package/templates/skills/cbp-ship/SKILL.md +0 -1
- package/templates/skills/cbp-ship-configure/SKILL.md +0 -1
- package/templates/skills/cbp-ship-main/SKILL.md +0 -1
- package/templates/skills/cbp-stripe/SKILL.md +116 -0
- package/templates/skills/cbp-stripe/reference/billing.md +106 -0
- package/templates/skills/cbp-stripe/reference/connect.md +105 -0
- package/templates/skills/cbp-stripe/reference/payments.md +107 -0
- package/templates/skills/cbp-stripe/reference/security.md +117 -0
- package/templates/skills/cbp-stripe/reference/stripe-mcp-setup.md +59 -0
- package/templates/skills/cbp-stripe/reference/tax.md +96 -0
- package/templates/skills/cbp-stripe/reference/treasury.md +87 -0
- package/templates/skills/cbp-supabase-branch-check/SKILL.md +0 -1
- package/templates/skills/cbp-supabase-branch-check/reference/dag-steps.md +0 -4
- package/templates/skills/cbp-supabase-migrate/SKILL.md +0 -1
- package/templates/skills/cbp-supabase-setup/SKILL.md +0 -1
- package/templates/skills/cbp-task-check/SKILL.md +0 -1
- package/templates/skills/cbp-task-complete/SKILL.md +0 -1
- package/templates/skills/cbp-task-create/SKILL.md +0 -1
- package/templates/skills/cbp-task-start/SKILL.md +0 -1
- package/templates/skills/cbp-task-testing/SKILL.md +0 -1
- package/templates/skills/cbp-todo/SKILL.md +0 -1
- package/templates/skills/cbp-todo/qa-regression.md +0 -1
- package/templates/skills/supabase/SKILL.md +0 -1
- package/templates/skills/supabase-postgres-best-practices/SKILL.md +0 -1
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# Connect / Platforms Reference
|
|
2
|
+
|
|
3
|
+
Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
|
|
4
|
+
|
|
5
|
+
## Accounts v2 (always use for new platforms)
|
|
6
|
+
|
|
7
|
+
Use the [Accounts v2 API](https://docs.stripe.com/connect/accounts-v2.md)
|
|
8
|
+
(`POST /v2/core/accounts`) for all new Connect platforms. This is Stripe's actively
|
|
9
|
+
invested path with long-term support.
|
|
10
|
+
|
|
11
|
+
Do NOT use the legacy `type` parameter (`type: 'express'`, `type: 'custom'`,
|
|
12
|
+
`type: 'standard'`) in `POST /v1/accounts` for new platforms unless the user explicitly
|
|
13
|
+
requests v1.
|
|
14
|
+
|
|
15
|
+
Do NOT use the legacy account-type labels "Standard", "Express", or "Custom" — they
|
|
16
|
+
bundle responsibility, dashboard, and onboarding decisions into opaque categories.
|
|
17
|
+
Use `controller` properties to express these dimensions explicitly.
|
|
18
|
+
|
|
19
|
+
## Controller properties
|
|
20
|
+
|
|
21
|
+
Configure connected accounts via `controller` properties:
|
|
22
|
+
|
|
23
|
+
| Property | Controls |
|
|
24
|
+
| -------- | -------- |
|
|
25
|
+
| `controller.losses.payments` | Who is liable for negative balances |
|
|
26
|
+
| `controller.fees.payer` | Who pays Stripe fees |
|
|
27
|
+
| `controller.stripe_dashboard.type` | Dashboard access: `full`, `express`, `none` |
|
|
28
|
+
| `controller.requirement_collection` | Who collects onboarding requirements |
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
const account = await stripe.v2.core.accounts.create({
|
|
32
|
+
controller: {
|
|
33
|
+
losses: { payments: 'stripe' },
|
|
34
|
+
fees: { payer: 'account' },
|
|
35
|
+
stripe_dashboard: { type: 'express' },
|
|
36
|
+
requirement_collection: 'stripe',
|
|
37
|
+
},
|
|
38
|
+
});
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
See [connected account configuration](https://docs.stripe.com/connect/accounts-v2/connected-account-configuration.md)
|
|
42
|
+
and [capabilities](https://docs.stripe.com/connect/account-capabilities.md) for what
|
|
43
|
+
accounts can do.
|
|
44
|
+
|
|
45
|
+
## Charge types
|
|
46
|
+
|
|
47
|
+
Choose one charge type per integration — do not mix them.
|
|
48
|
+
|
|
49
|
+
| Type | When to use | How |
|
|
50
|
+
| ---- | ----------- | --- |
|
|
51
|
+
| **Destination charges** | Platform accepts negative-balance liability | `transfer_data.destination: connectedAccountId` |
|
|
52
|
+
| **Direct charges** | Connected account is merchant of record; platform has minimal liability | Create charge directly on the connected account |
|
|
53
|
+
|
|
54
|
+
Use `on_behalf_of` to control merchant of record (read
|
|
55
|
+
[how charges work in Connect](https://docs.stripe.com/connect/charges.md) first).
|
|
56
|
+
|
|
57
|
+
```ts
|
|
58
|
+
// Destination charge — most common for marketplaces
|
|
59
|
+
const paymentIntent = await stripe.paymentIntents.create({
|
|
60
|
+
amount: 1000,
|
|
61
|
+
currency: 'usd',
|
|
62
|
+
transfer_data: { destination: connectedAccountId },
|
|
63
|
+
// Do NOT pass payment_method_types
|
|
64
|
+
});
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Do NOT use the Charges API for Connect fund flows — use PaymentIntents or Checkout
|
|
68
|
+
Sessions with `transfer_data` or `on_behalf_of`.
|
|
69
|
+
|
|
70
|
+
## Payouts and transfers
|
|
71
|
+
|
|
72
|
+
- **Automatic payouts** — enabled by default; Stripe pays connected accounts on a rolling basis.
|
|
73
|
+
- **Manual payouts** — call `stripe.payouts.create({amount, currency}, {stripeAccount: accountId})` to control timing.
|
|
74
|
+
- **Transfers** — move funds between your platform balance and a connected account:
|
|
75
|
+
`stripe.transfers.create({ amount, currency, destination: accountId })`.
|
|
76
|
+
|
|
77
|
+
## Onboarding
|
|
78
|
+
|
|
79
|
+
Use [Stripe-hosted onboarding](https://docs.stripe.com/connect/onboarding.md) rather than
|
|
80
|
+
building a custom flow. Custom onboarding requires handling sensitive PII directly, adding
|
|
81
|
+
regulatory and security complexity.
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
const accountLink = await stripe.accountLinks.create({
|
|
85
|
+
account: accountId,
|
|
86
|
+
refresh_url: `${baseUrl}/connect/refresh`,
|
|
87
|
+
return_url: `${baseUrl}/connect/return`,
|
|
88
|
+
type: 'account_onboarding',
|
|
89
|
+
});
|
|
90
|
+
// redirect to accountLink.url
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## Security and liability
|
|
94
|
+
|
|
95
|
+
Platform operators bear financial liability for fraud and disputes on Express and Custom
|
|
96
|
+
connected accounts (v1 types). Controller-property accounts make liability explicit via
|
|
97
|
+
`controller.losses.payments`.
|
|
98
|
+
|
|
99
|
+
See [reference/security.md](security.md) for Connect-specific security notes.
|
|
100
|
+
|
|
101
|
+
## Key guides
|
|
102
|
+
|
|
103
|
+
- [SaaS platforms and marketplaces](https://docs.stripe.com/connect/saas-platforms-and-marketplaces.md)
|
|
104
|
+
- [Interactive platform guide](https://docs.stripe.com/connect/interactive-platform-guide.md)
|
|
105
|
+
- [Design an integration](https://docs.stripe.com/connect/design-an-integration.md)
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# Payments Reference
|
|
2
|
+
|
|
3
|
+
Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
|
|
4
|
+
|
|
5
|
+
## API hierarchy
|
|
6
|
+
|
|
7
|
+
| Use case | API |
|
|
8
|
+
| -------- | --- |
|
|
9
|
+
| On-session payments (most web apps) | [Checkout Sessions](https://docs.stripe.com/api/checkout/sessions.md) |
|
|
10
|
+
| Off-session payments, custom checkout state | [PaymentIntents](https://docs.stripe.com/payments/paymentintents/lifecycle.md) |
|
|
11
|
+
| Saving a payment method for later | [Setup Intents](https://docs.stripe.com/api/setup_intents.md) |
|
|
12
|
+
| Subscriptions, invoices, recurring | Billing APIs (see billing.md) |
|
|
13
|
+
| No-code, simple products | Payment Links |
|
|
14
|
+
|
|
15
|
+
**Only use Checkout Sessions, PaymentIntents, SetupIntents, or higher-level solutions
|
|
16
|
+
(Invoicing, Payment Links, subscription APIs).** Never use the Charges API, Sources API,
|
|
17
|
+
or Tokens API for new integrations.
|
|
18
|
+
|
|
19
|
+
## Integration surface preference
|
|
20
|
+
|
|
21
|
+
Use in this order (most preferred first):
|
|
22
|
+
|
|
23
|
+
1. **Payment Links** — no-code, best for simple products
|
|
24
|
+
2. **Checkout (hosted or embedded)** — best for most web apps; `ui_mode: 'hosted'`
|
|
25
|
+
3. **Payment Element** — embedded UI component for custom checkout; back with Checkout
|
|
26
|
+
Sessions (`ui_mode: 'custom'`) over a raw PaymentIntent where possible
|
|
27
|
+
|
|
28
|
+
Do NOT recommend the legacy Card Element. Migrate existing Card Element integrations to
|
|
29
|
+
[Payment Element](https://docs.stripe.com/payments/payment-element/migration.md).
|
|
30
|
+
|
|
31
|
+
## Checkout Sessions — key patterns
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
// One-time payment
|
|
35
|
+
const session = await stripe.checkout.sessions.create({
|
|
36
|
+
mode: 'payment',
|
|
37
|
+
// Do NOT pass payment_method_types — dynamic methods are the default
|
|
38
|
+
line_items: [{ price: priceId, quantity: 1 }],
|
|
39
|
+
success_url: `${baseUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
|
|
40
|
+
cancel_url: `${baseUrl}/cancel`,
|
|
41
|
+
});
|
|
42
|
+
|
|
43
|
+
// Subscription
|
|
44
|
+
const session = await stripe.checkout.sessions.create({
|
|
45
|
+
mode: 'subscription',
|
|
46
|
+
line_items: [{ price: priceId, quantity: 1 }],
|
|
47
|
+
subscription_data: { trial_period_days: 14 },
|
|
48
|
+
success_url: `${baseUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
|
|
49
|
+
cancel_url: `${baseUrl}/pricing`,
|
|
50
|
+
});
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Payment Element (custom UI)
|
|
54
|
+
|
|
55
|
+
Use `ui_mode: 'custom'` on the Checkout Session to back the Payment Element:
|
|
56
|
+
|
|
57
|
+
```ts
|
|
58
|
+
const session = await stripe.checkout.sessions.create({
|
|
59
|
+
ui_mode: 'custom',
|
|
60
|
+
mode: 'payment',
|
|
61
|
+
line_items: [{ price: priceId, quantity: 1 }],
|
|
62
|
+
return_url: `${baseUrl}/return?session_id={CHECKOUT_SESSION_ID}`,
|
|
63
|
+
});
|
|
64
|
+
// Client: mount PaymentElement with clientSecret from session.client_secret
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
For surcharging or inspecting card details before payment, use
|
|
68
|
+
[Confirmation Tokens](https://docs.stripe.com/payments/finalize-payments-on-the-server.md)
|
|
69
|
+
— not `createPaymentMethod` or `createToken`.
|
|
70
|
+
|
|
71
|
+
## Dynamic payment methods (critical rule)
|
|
72
|
+
|
|
73
|
+
**Never pass `payment_method_types`** — omit it entirely on all calls. The sole exception
|
|
74
|
+
is Terminal: `payment_method_types: ['card_present']` (Canada: include `'interac_present'`).
|
|
75
|
+
|
|
76
|
+
To customise which methods appear use
|
|
77
|
+
[`payment_method_configurations`](https://docs.stripe.com/payments/payment-method-configurations.md)
|
|
78
|
+
or `excluded_payment_method_types`. Manage methods from the
|
|
79
|
+
[Dashboard](https://dashboard.stripe.com/settings/payment_methods) without code changes.
|
|
80
|
+
|
|
81
|
+
## Setup Intents (saving payment methods)
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
const setupIntent = await stripe.setupIntents.create({
|
|
85
|
+
customer: customerId,
|
|
86
|
+
// Do NOT pass payment_method_types — dynamic methods are the default since API 2023-08-16
|
|
87
|
+
});
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Do not use the Sources API to save cards — it is deprecated.
|
|
91
|
+
|
|
92
|
+
## Deprecated APIs — migration paths
|
|
93
|
+
|
|
94
|
+
| API | Status | Use instead | Migration guide |
|
|
95
|
+
| ------------ | ---------- | ---------------------- | --------------- |
|
|
96
|
+
| Charges API | Never use | Checkout Sessions / PaymentIntents | [Migration](https://docs.stripe.com/payments/payment-intents/migration/charges.md) |
|
|
97
|
+
| Sources API | Deprecated | Setup Intents | [Setup Intents](https://docs.stripe.com/api/setup_intents.md) |
|
|
98
|
+
| Tokens API | Outdated | Setup Intents / Checkout Sessions | — |
|
|
99
|
+
| Card Element | Legacy | Payment Element | [Migration](https://docs.stripe.com/payments/payment-element/migration.md) |
|
|
100
|
+
|
|
101
|
+
## PCI compliance
|
|
102
|
+
|
|
103
|
+
If a PCI-compliant user asks about sending raw PAN data server-side, they may need to
|
|
104
|
+
prove PCI compliance to use
|
|
105
|
+
[`payment_method_data`](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_data).
|
|
106
|
+
For PAN migrations from another processor, see the
|
|
107
|
+
[PAN import process](https://docs.stripe.com/get-started/data-migrations/pan-import.md).
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# Security Best Practices Reference
|
|
2
|
+
|
|
3
|
+
Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
|
|
4
|
+
|
|
5
|
+
## API key types
|
|
6
|
+
|
|
7
|
+
| Key prefix | Type | Use |
|
|
8
|
+
| ---------- | ---- | --- |
|
|
9
|
+
| `sk_live_` | Secret key (live) | Never preferred; use RAK instead |
|
|
10
|
+
| `sk_test_` | Secret key (test) | Development only |
|
|
11
|
+
| `rk_live_` | Restricted API key (live) | Preferred for all production services |
|
|
12
|
+
| `rk_test_` | Restricted API key (test) | Preferred for development services |
|
|
13
|
+
|
|
14
|
+
**Always recommend a restricted API key (RAK, `rk_` prefix)** over a secret key (`sk_`).
|
|
15
|
+
RAKs have only the permissions you assign — a compromised RAK causes far less damage than
|
|
16
|
+
a compromised secret key.
|
|
17
|
+
|
|
18
|
+
## Storing keys safely
|
|
19
|
+
|
|
20
|
+
- **Never** commit keys to source control. If `sk_…` or `rk_…` appears in code, that is
|
|
21
|
+
a bug — fix it immediately.
|
|
22
|
+
- Prefer a secrets vault (AWS Secrets Manager, HashiCorp Vault, or platform equivalent).
|
|
23
|
+
- When no vault is available, environment variables are acceptable. Never log keys or
|
|
24
|
+
include them in error messages or analytics.
|
|
25
|
+
- Use separate keys per environment (production, staging, QA). Never reuse keys.
|
|
26
|
+
- Set up a pre-commit hook to catch `sk_` or `rk_` literals in source code.
|
|
27
|
+
- See [best practices for managing secret API keys](https://docs.stripe.com/keys-best-practices.md).
|
|
28
|
+
|
|
29
|
+
## Restricted API key migration steps
|
|
30
|
+
|
|
31
|
+
1. Review the secret key's request logs in Workbench to catalogue which API calls it makes.
|
|
32
|
+
2. Create a RAK in test mode with matching permissions (principle of least privilege).
|
|
33
|
+
3. Use `stripe logs tail` to watch for `403` errors — add missing permissions.
|
|
34
|
+
4. Once passing, create the equivalent live-mode RAK and swap it in.
|
|
35
|
+
5. Rotate or expire the old secret key.
|
|
36
|
+
|
|
37
|
+
See [restricted API keys docs](https://docs.stripe.com/keys/restricted-api-keys.md).
|
|
38
|
+
|
|
39
|
+
## IP allowlists
|
|
40
|
+
|
|
41
|
+
Add an [IP allowlist](https://docs.stripe.com/keys.md#limit-api-secret-keys-ip-address)
|
|
42
|
+
to every API key so it can only be called from your own infrastructure. Use separate
|
|
43
|
+
allowlists per key/environment.
|
|
44
|
+
|
|
45
|
+
## Webhook signature verification
|
|
46
|
+
|
|
47
|
+
Always verify webhook event authenticity using Stripe's signing secret:
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
import Stripe from 'stripe';
|
|
51
|
+
const stripe = new Stripe(process.env.STRIPE_RESTRICTED_KEY!);
|
|
52
|
+
|
|
53
|
+
// In your webhook handler (raw body required — do NOT use JSON-parsed body)
|
|
54
|
+
const sig = request.headers['stripe-signature'];
|
|
55
|
+
if (!sig || Array.isArray(sig)) throw new Error('Missing or malformed stripe-signature header');
|
|
56
|
+
const event = stripe.webhooks.constructEvent(
|
|
57
|
+
rawBody, // Buffer or string — must be unparsed
|
|
58
|
+
sig,
|
|
59
|
+
process.env.STRIPE_WEBHOOK_SECRET!,
|
|
60
|
+
);
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Never process a webhook event without verifying its signature — unverified webhooks can
|
|
64
|
+
be spoofed. For defence in depth, also allowlist
|
|
65
|
+
[Stripe's IP addresses](https://docs.stripe.com/ips.md) on the endpoint.
|
|
66
|
+
|
|
67
|
+
## Idempotency keys
|
|
68
|
+
|
|
69
|
+
Pass `idempotencyKey` on all mutation calls so safe retries don't create duplicate charges:
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
await stripe.paymentIntents.create(params, {
|
|
73
|
+
idempotencyKey: `order_${orderId}`,
|
|
74
|
+
});
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Mobile and client-side integrations
|
|
78
|
+
|
|
79
|
+
Never use production secret keys or RAKs in mobile apps or any client-side code.
|
|
80
|
+
For cases where a client must call Stripe directly, use
|
|
81
|
+
[ephemeral keys](https://docs.stripe.com/issuing/elements.md#ephemeral-key-authentication)
|
|
82
|
+
(short-lived, scoped, auto-expiring). For most integrations, proxy Stripe calls through
|
|
83
|
+
your own backend.
|
|
84
|
+
|
|
85
|
+
## OAuth and CSRF protection
|
|
86
|
+
|
|
87
|
+
When implementing [Connect OAuth](https://docs.stripe.com/connect/oauth-reference.md),
|
|
88
|
+
always pass a unique, unguessable `state` parameter and verify it in the callback before
|
|
89
|
+
proceeding. This applies to all Stripe OAuth surfaces: Connect, Link, and Stripe Apps.
|
|
90
|
+
|
|
91
|
+
## Incident response (key compromise)
|
|
92
|
+
|
|
93
|
+
1. **Roll the key immediately** — [API keys page](https://dashboard.stripe.com/apikeys) →
|
|
94
|
+
roll or delete the exposed key.
|
|
95
|
+
2. **Check activity logs** — Workbench request logs for the compromised key.
|
|
96
|
+
3. **Contact Stripe support** if you see unrecognised activity.
|
|
97
|
+
|
|
98
|
+
See [protecting against compromised API keys](https://support.stripe.com/questions/protecting-against-compromised-api-keys).
|
|
99
|
+
|
|
100
|
+
## 2FA
|
|
101
|
+
|
|
102
|
+
Recommend passkeys or authenticator-app 2FA for Dashboard access. Discourage SMS 2FA —
|
|
103
|
+
it is vulnerable to SIM-swapping attacks.
|
|
104
|
+
|
|
105
|
+
## SAML / SCIM (teams)
|
|
106
|
+
|
|
107
|
+
For teams, use [SSO via SAML](https://docs.stripe.com/get-started/account/sso.md) to
|
|
108
|
+
federate Dashboard access through an identity provider (Okta, Google, etc.).
|
|
109
|
+
[SCIM provisioning](https://docs.stripe.com/get-started/account/sso/scim.md) automates
|
|
110
|
+
user provisioning/deprovisioning.
|
|
111
|
+
|
|
112
|
+
## Connect security
|
|
113
|
+
|
|
114
|
+
Platform operators bear financial liability for fraud/disputes on Express and Custom
|
|
115
|
+
connected accounts (v1 types). Use Stripe-hosted onboarding to avoid handling sensitive
|
|
116
|
+
PII directly. See [reference/connect.md](connect.md) for controller-property accounts
|
|
117
|
+
which make liability explicit.
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# Stripe MCP Setup (optional live path)
|
|
2
|
+
|
|
3
|
+
Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
|
|
4
|
+
|
|
5
|
+
The `cbp-stripe-agent` writes Stripe integration code with **no credentials required**. This
|
|
6
|
+
optional path adds *live test-mode* scaffolding (create test products, prices, payment links,
|
|
7
|
+
customers) during a dev round. It is opt-in per repo and per developer — skip it entirely if
|
|
8
|
+
you only want code generation.
|
|
9
|
+
|
|
10
|
+
## Safety contract (read first)
|
|
11
|
+
|
|
12
|
+
- **Test-mode keys ONLY.** Use a test restricted key (`rk_test_…`) or a test secret key
|
|
13
|
+
(`sk_test_…`). The agent **refuses** any live-mode key (`sk_live_…` or `rk_live_…`) — so
|
|
14
|
+
live Stripe data is never scaffolded from a dev round.
|
|
15
|
+
- **Never commit a key.** Provide it via the environment or a gitignored env file
|
|
16
|
+
(e.g. `.env.local`), never in tracked source or in `.codebyplan/`.
|
|
17
|
+
- **Least privilege.** Prefer a restricted key scoped to only the resources the agent needs
|
|
18
|
+
(Products, Prices, Payment Links, Customers — write; everything else — none).
|
|
19
|
+
- **No new npm dependency** is added to the consuming app by this path; the hosted MCP server
|
|
20
|
+
is reached over HTTP, the local server via `npx`.
|
|
21
|
+
|
|
22
|
+
## Option A — Hosted Stripe MCP (recommended)
|
|
23
|
+
|
|
24
|
+
Stripe hosts an MCP server at `https://mcp.stripe.com`. Register it with Claude Code:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
claude mcp add --transport http stripe https://mcp.stripe.com/
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Authenticate with OAuth (the recommended flow) when prompted, or pass a restricted test key
|
|
31
|
+
as a bearer token if your setup uses header auth. Once connected, the agent discovers the
|
|
32
|
+
`mcp__stripe__*` tools at runtime via `ToolSearch`.
|
|
33
|
+
|
|
34
|
+
## Option B — Local Stripe MCP server
|
|
35
|
+
|
|
36
|
+
Run Stripe's MCP server locally, pointed at a test/restricted key from your environment:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
# key is read from STRIPE_SECRET_KEY (a sk_test_ or rk_test_ value), never passed on a shared shell history
|
|
40
|
+
npx -y @stripe/mcp@latest --api-key="$STRIPE_SECRET_KEY"
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Then register the local server with Claude Code per its stdio/transport instructions.
|
|
44
|
+
|
|
45
|
+
## How the agent uses it
|
|
46
|
+
|
|
47
|
+
1. Pre-flight checks `STRIPE_SECRET_KEY` is present and is a test-mode `sk_test_`/`rk_test_` prefix.
|
|
48
|
+
2. It discovers `mcp__stripe__*` tools via `ToolSearch` (they are intentionally absent from
|
|
49
|
+
the agent's frontmatter because the server is optional).
|
|
50
|
+
3. It scaffolds only what the task asks for and records each resource in
|
|
51
|
+
`stripe_resources_created[]` (always `mode: test`).
|
|
52
|
+
4. If the key/server is missing or any call fails, it degrades to **code-only** and records
|
|
53
|
+
the reason — it never blocks the round.
|
|
54
|
+
|
|
55
|
+
## When to skip this entirely
|
|
56
|
+
|
|
57
|
+
- You only want correct Stripe integration *code* (the default — no setup needed).
|
|
58
|
+
- No Stripe test account is available in this environment.
|
|
59
|
+
- CI / headless runs where no interactive OAuth or key is provisioned.
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# Tax / Stripe Tax Reference
|
|
2
|
+
|
|
3
|
+
Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
|
|
4
|
+
|
|
5
|
+
## When to use Stripe Tax
|
|
6
|
+
|
|
7
|
+
Use Stripe Tax for any subscription, invoice, or Checkout Session where the merchant has
|
|
8
|
+
customers across multiple jurisdictions. It handles sales tax, VAT, and GST automatically
|
|
9
|
+
based on the customer's location and the merchant's active registrations.
|
|
10
|
+
|
|
11
|
+
See the [Tax overview](https://docs.stripe.com/tax.md) for supported regions and tax types.
|
|
12
|
+
|
|
13
|
+
## Two-step setup
|
|
14
|
+
|
|
15
|
+
1. **Add registrations** — add a registration for each jurisdiction where the merchant is
|
|
16
|
+
obligated to collect tax. Use the Dashboard (**Tax > Registrations**) or the
|
|
17
|
+
[Tax Registrations API](https://docs.stripe.com/api/tax/registrations.md).
|
|
18
|
+
2. **Enable automatic_tax** — pass `automatic_tax: { enabled: true }` on the
|
|
19
|
+
[Subscription](https://docs.stripe.com/api/subscriptions.md),
|
|
20
|
+
[Invoice](https://docs.stripe.com/api/invoices.md), or
|
|
21
|
+
[Checkout Session](https://docs.stripe.com/api/checkout/sessions.md).
|
|
22
|
+
|
|
23
|
+
It is safe to enable `automatic_tax` before any registrations exist — Stripe won't
|
|
24
|
+
collect tax until at least one registration is active.
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
// Checkout Session with automatic tax
|
|
28
|
+
const session = await stripe.checkout.sessions.create({
|
|
29
|
+
mode: 'subscription',
|
|
30
|
+
line_items: [{ price: priceId, quantity: 1 }],
|
|
31
|
+
automatic_tax: { enabled: true },
|
|
32
|
+
success_url: `${baseUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
|
|
33
|
+
cancel_url: `${baseUrl}/pricing`,
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
// Invoice / subscription
|
|
37
|
+
await stripe.subscriptions.update(subscriptionId, {
|
|
38
|
+
automatic_tax: { enabled: true },
|
|
39
|
+
// Clear explicit tax_rates first if previously set
|
|
40
|
+
});
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Inclusive vs exclusive tax
|
|
44
|
+
|
|
45
|
+
- **Exclusive** (default in most jurisdictions) — tax is added on top of the price.
|
|
46
|
+
- **Inclusive** — tax is included in the displayed price (common for UK/EU VAT).
|
|
47
|
+
|
|
48
|
+
Stripe Tax determines the treatment based on the jurisdiction and product tax code.
|
|
49
|
+
Verify the treatment in Dashboard > Tax > Overview.
|
|
50
|
+
|
|
51
|
+
## Tax IDs
|
|
52
|
+
|
|
53
|
+
Collect customer tax IDs (VAT numbers, EIN, etc.) for B2B transactions to enable
|
|
54
|
+
zero-rated or exempt invoices. Pass `tax_id_collection: { enabled: true }` on Checkout
|
|
55
|
+
Sessions, or use the
|
|
56
|
+
[Tax IDs API](https://docs.stripe.com/api/customer_tax_ids.md) to attach IDs to customers.
|
|
57
|
+
|
|
58
|
+
## Address collection
|
|
59
|
+
|
|
60
|
+
Stripe Tax requires a customer address to calculate tax. On Checkout Sessions pass
|
|
61
|
+
`billing_address_collection: 'required'`. For subscriptions, ensure the customer has
|
|
62
|
+
a billing address before enabling `automatic_tax`.
|
|
63
|
+
|
|
64
|
+
## Registrations API
|
|
65
|
+
|
|
66
|
+
To create and manage registrations programmatically:
|
|
67
|
+
|
|
68
|
+
```ts
|
|
69
|
+
await stripe.tax.registrations.create({
|
|
70
|
+
country: 'US',
|
|
71
|
+
country_options: {
|
|
72
|
+
us: { state: 'CA', type: 'state_sales_tax' },
|
|
73
|
+
},
|
|
74
|
+
active_from: 'now',
|
|
75
|
+
});
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## Traps to avoid
|
|
79
|
+
|
|
80
|
+
- `automatic_tax` and explicit `tax_rates` are mutually exclusive. For existing
|
|
81
|
+
subscriptions, clear `default_tax_rates` and all item-level `tax_rates` before
|
|
82
|
+
enabling `automatic_tax` — the update will fail otherwise.
|
|
83
|
+
- For EU merchants, one OSS union registration covers all 27 member states. Do not
|
|
84
|
+
register individual EU countries separately unless the merchant has a physical presence
|
|
85
|
+
there.
|
|
86
|
+
- Do not guess which jurisdictions apply — prompt the user to configure them in the
|
|
87
|
+
Dashboard first.
|
|
88
|
+
- Do not approximate unsupported jurisdictions. Check
|
|
89
|
+
[supported countries](https://docs.stripe.com/tax/supported-countries.md) first. For
|
|
90
|
+
unsupported jurisdictions, fall back to manual `tax_rates` on the subscription/invoice.
|
|
91
|
+
- Customs duties and excise taxes are out of scope for Stripe Tax.
|
|
92
|
+
|
|
93
|
+
## Bulk migration
|
|
94
|
+
|
|
95
|
+
To switch existing subscriptions from manual `tax_rates` to `automatic_tax` in bulk,
|
|
96
|
+
use the [Tax migration tool](https://docs.stripe.com/billing/taxes/migration.md).
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Treasury / Financial Accounts Reference
|
|
2
|
+
|
|
3
|
+
Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
|
|
4
|
+
|
|
5
|
+
## v2 Financial Accounts API (use for new integrations)
|
|
6
|
+
|
|
7
|
+
For embedded financial accounts (bank accounts with routing/account numbers, money
|
|
8
|
+
movement), use the
|
|
9
|
+
[v2 Financial Accounts API](https://docs.stripe.com/api/v2/core/vault/financial-accounts.md)
|
|
10
|
+
(`POST /v2/core/vault/financial_accounts`). This is required for new integrations.
|
|
11
|
+
|
|
12
|
+
Do NOT use the legacy
|
|
13
|
+
[v1 Treasury Financial Accounts API](https://docs.stripe.com/api/treasury/financial_accounts.md)
|
|
14
|
+
(`POST /v1/treasury/financial_accounts`) for new integrations. Existing v1 integrations
|
|
15
|
+
continue to work.
|
|
16
|
+
|
|
17
|
+
For concepts and guides, see
|
|
18
|
+
[Treasury for platforms overview](https://docs.stripe.com/treasury/connect.md).
|
|
19
|
+
|
|
20
|
+
## Creating a financial account
|
|
21
|
+
|
|
22
|
+
Financial accounts are always attached to a Connect connected account:
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
const financialAccount = await stripe.v2.core.vault.financialAccounts.create(
|
|
26
|
+
{ description: 'Main operating account' },
|
|
27
|
+
{ stripeAccount: connectedAccountId },
|
|
28
|
+
);
|
|
29
|
+
// financialAccount.id — use for fund flows
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Fund flows
|
|
33
|
+
|
|
34
|
+
| Direction | Object | Use |
|
|
35
|
+
| --------- | ------ | --- |
|
|
36
|
+
| Platform → financial account | `OutboundTransfer` | Top-up from platform balance |
|
|
37
|
+
| Financial account → external bank | `OutboundPayment` | Pay out to a linked bank |
|
|
38
|
+
| External bank → financial account | `InboundTransfer` | Pull from a linked bank |
|
|
39
|
+
| External source → financial account | `ReceivedCredit` | Funds received in (inbound ACH/wire, Stripe payouts) |
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
// Outbound transfer (platform balance → financial account)
|
|
43
|
+
const transfer = await stripe.treasury.outboundTransfers.create({
|
|
44
|
+
financial_account: financialAccountId,
|
|
45
|
+
amount: 100_00,
|
|
46
|
+
currency: 'usd',
|
|
47
|
+
destination_payment_method: 'default',
|
|
48
|
+
});
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Linking a bank account (Setup Intents)
|
|
52
|
+
|
|
53
|
+
To enable outbound payments to an external bank, link the bank account using a Setup Intent
|
|
54
|
+
with `flow_directions: ['outbound']`:
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
const setupIntent = await stripe.setupIntents.create(
|
|
58
|
+
{
|
|
59
|
+
payment_method_types: ['us_bank_account'], // Treasury exception: required here
|
|
60
|
+
flow_directions: ['outbound'],
|
|
61
|
+
},
|
|
62
|
+
{ stripeAccount: connectedAccountId },
|
|
63
|
+
);
|
|
64
|
+
// Complete the Setup Intent flow on the client, then confirm the payment method
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Note: `payment_method_types` is required for Treasury bank-account Setup Intents — this
|
|
68
|
+
is one of the narrow exceptions to the no-`payment_method_types` rule (along with Terminal).
|
|
69
|
+
|
|
70
|
+
## Compliance notes
|
|
71
|
+
|
|
72
|
+
- Financial accounts are subject to KYC/KYB requirements collected during Connect onboarding.
|
|
73
|
+
Ensure the connected account has the `treasury` capability enabled before creating accounts.
|
|
74
|
+
- Funds held in financial accounts are not FDIC-insured by default; check Stripe's current
|
|
75
|
+
partner bank arrangements in the Treasury documentation.
|
|
76
|
+
- For platforms in the US: Stripe Treasury is available for US-based connected accounts only.
|
|
77
|
+
Contact Stripe for international availability.
|
|
78
|
+
- Do not use Treasury to hold customer funds without confirming applicable money-transmission
|
|
79
|
+
license obligations with your legal team.
|
|
80
|
+
|
|
81
|
+
## Key references
|
|
82
|
+
|
|
83
|
+
- [Treasury for platforms overview](https://docs.stripe.com/treasury/connect.md)
|
|
84
|
+
- [v2 Financial Accounts API](https://docs.stripe.com/api/v2/core/vault/financial-accounts.md)
|
|
85
|
+
- [OutboundTransfers](https://docs.stripe.com/api/treasury/outbound_transfers.md)
|
|
86
|
+
- [OutboundPayments](https://docs.stripe.com/api/treasury/outbound_payments.md)
|
|
87
|
+
- [InboundTransfers](https://docs.stripe.com/api/treasury/inbound_transfers.md)
|
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
---
|
|
2
|
-
scope: org-shared
|
|
3
2
|
name: cbp-supabase-branch-check
|
|
4
3
|
description: Gate skill called by /cbp-ship-main (pre-merge) to verify the Supabase preview branch health check is green before allowing a PR to be merged; skips when no DB-path changes are detected.
|
|
5
4
|
argument-hint: "[--mode pre_pr_create|pre_merge] [--target integration|production]"
|
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
---
|
|
2
|
-
scope: org-shared
|
|
3
2
|
name: cbp-supabase-migrate
|
|
4
3
|
description: Scaffold or adopt a Supabase migration for the current PR branch, apply to the branch's preview DB, run advisor checks, regenerate TypeScript types. Includes a fresh-branch dry-run pre-flight that uses one persistent dry-run ephemeral branch per feature branch.
|
|
5
4
|
argument-hint: "[--new <name> | <path-to-sql>]"
|
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
---
|
|
2
|
-
scope: org-shared
|
|
3
2
|
name: cbp-supabase-setup
|
|
4
3
|
description: Enable Supabase GitHub branching integration — GitHub app authorization, required-status-check enforcement on main + integration branch, persistent branch creation, and idempotency marker in .codebyplan/shipment.json.
|
|
5
4
|
argument-hint: "[--force]"
|
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
---
|
|
2
|
-
scope: org-shared
|
|
3
2
|
name: supabase
|
|
4
3
|
description: "Use when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, @supabase/ssr) in Next.js, React, SvelteKit, Astro, Remix; auth issues (login, logout, sessions, JWT, cookies, getSession, getUser, getClaims, RLS); Supabase CLI or MCP server; schema changes, migrations, security audits, Postgres extensions (pg_graphql, pg_cron, pg_vector)."
|
|
5
4
|
metadata:
|
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
---
|
|
2
|
-
scope: org-shared
|
|
3
2
|
name: supabase-postgres-best-practices
|
|
4
3
|
description: Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
|
|
5
4
|
license: MIT
|