@kody/stripe
Read and manage Stripe customers, payments, invoices, subscriptions, and refunds with dry-run mutations.
Files
@kody/stripe — agent notes
Human setup and intent live in README.md. This file is for
agents: imports, smoke/dryRun execute snippets, and edge cases. Secrets by
name only — never paste key values. Do not disable live webhooks or jobs.
Secrets
| Name | Purpose |
|---|---|
stripeApiKey | Default API key (user scope); hosts api.stripe.com, files.stripe.com |
stripeWebhookSecret | Optional HMAC signing secret (whsec_…) |
stripeApiKey-<label> | Extra account via account: "<label>" or secretName |
Placeholder shape: {{secret:stripeApiKey|scope=user}}.
Import paths
| Export | Import |
|---|---|
root dispatcher (default smoke-test) | kody:@kody/stripe |
| account / balance / payouts / events | kody:@kody/stripe/account |
| customers | kody:@kody/stripe/customers |
| payments | kody:@kody/stripe/payments |
| invoices | kody:@kody/stripe/invoices |
| subscriptions | kody:@kody/stripe/subscriptions |
| products / prices / payment links | kody:@kody/stripe/products |
| webhooks | kody:@kody/stripe/webhooks |
| smoke-test | kody:@kody/stripe/smoke-test |
Prefer static kody:@kody/stripe/... imports from execute. Do not lead with
packages.invoke. Root also re-exports helpers and low-level stripeRequest,
stripeList, stripeSearch, stripeParams, stripeUploadFile,
StripeApiError.
Smoke test (read-only)
import smokeTest from 'kody:@kody/stripe/smoke-test'
export default async function main() {
return await smokeTest()
// Without stripeApiKey: { ok: true, live: false, setupUrl, ... }
// With key: live account/balance/customer sample — no writes
}Equivalent via root dispatcher:
import stripe from 'kody:@kody/stripe'
export default async function main() {
return await stripe({ action: 'smoke-test' })
}Read-only search:
import stripe from 'kody:@kody/stripe'
export default async function main() {
return await stripe({
action: 'search-charges',
searchQuery: "billing_details.email:'ada@example.com'",
maxItems: 10,
})
}dryRun / confirm
Pass dryRun: true on any mutation to return
{ dryRun: true, method, path, body } without contacting Stripe.
These also throw unless confirm: true:
createRefund,createSubscription,cancelSubscriptionfinalizeInvoice,sendInvoice,voidInvoice,deleteDraftInvoicedeleteCustomer,archiveProduct,deactivatePaymentLink
import { createRefund } from 'kody:@kody/stripe/payments'
export default async function main() {
return await createRefund({
chargeId: 'ch_123',
amount: 500,
dryRun: true,
})
}Webhooks
import { verifyWebhookSignature, loadVerifiedEvent } from 'kody:@kody/stripe/webhooks'
export default async function main() {
// HMAC when the handler already has whsec_… (never paste in chat)
await verifyWebhookSignature({
payload: rawBody,
signatureHeader: stripeSignatureHeader,
webhookSecret: 'whsec_…',
})
// Prefer re-fetch when you do not want to hold the signing secret:
return await loadVerifiedEvent({ eventId: 'evt_123' })
}Edge cases / fork notes
- Amounts are Stripe integer amounts in the smallest currency unit (cents for
USD); summaries include a
displaystring. - Namespace defaults:
./customers→ list-customers,./payments→ list-charges,./invoices→ list-invoices,./subscriptions→ list-subscriptions,./products→ list-products. - POST helpers accept optional
idempotencyKeyand only retry automatically when one is provided. - Never run money-moving actions in smoke tests.
- Fork/adapt: save your own
stripeApiKey(and optionalstripeWebhookSecret); do not point at a shared platform store. KeepdryRun/confirmguards.