@kentcdodds/stripe

@kentcdodds/stripe — agent notes

Human setup and intent live in README.md. This file is for agents: imports, smoke checks, confirm guards, and edge cases. Secrets by name only — never paste key values. Do not disable live webhooks or jobs.

Secret

• Name: stripeSecretKey (user scope)
• Hosts: api.stripe.com, files.stripe.com
• Placeholder in package: {{secret:stripeSecretKey|scope=user}}

Import paths

Prefer named / subpath imports. Root also re-exports helpers and exposes low-level stripeRequest, stripeList, stripeSearch, stripeParams, stripeUploadFile, StripeApiError, formatStripeAmount, stripeDate.

Smoke test (read-only)

import smokeTest from 'kody:@kentcdodds/stripe/smoke-test'

export default async function main() {
	return await smokeTest()
	// => { ok: true, account, balance, customerSample, chargeSample }
}

Equivalent via root dispatcher:

import stripe from 'kody:@kentcdodds/stripe'

export default async function main() {
	return await stripe({ action: 'smoke-test' })
}

Read-only search example:

import stripe from 'kody:@kentcdodds/stripe'

export default async function main() {
	return await stripe({
		action: 'search-charges',
		searchQuery: "billing_details.email:'ada@example.com'",
		maxItems: 10,
	})
}

confirm-guarded mutations

These throw unless confirm: true:

• createRefund, createSubscription, cancelSubscription
• finalizeInvoice, sendInvoice, voidInvoice, deleteDraftInvoice
• deleteCustomer, archiveProduct, deactivatePaymentLink

Reads and searches never require confirmation. POST helpers accept optional idempotencyKey and only retry automatically when one is provided.

Edge cases

• Amounts are Stripe integer amounts in the smallest currency unit (cents for USD); summaries include a human-readable display string.
• Namespace defaults: ./customers → list-customers, ./payments → list-charges, ./invoices → list-invoices, ./subscriptions → list-subscriptions, ./products → list-products.
• Use stripeRequest({ path, method, query, body, idempotencyKey }) for endpoints without a typed helper; path stays under https://api.stripe.com/v1.
• Never run money-moving actions in smoke tests.