Skip to content
← Public packages

@kody/stripe

Read and manage Stripe customers, payments, invoices, subscriptions, and refunds with dry-run mutations.

FollowFork

Files

AGENTS.md

123 lines · 3.7 KB · Markdown

@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

NamePurpose
stripeApiKeyDefault API key (user scope); hosts api.stripe.com, files.stripe.com
stripeWebhookSecretOptional HMAC signing secret (whsec_…)
stripeApiKey-<label>Extra account via account: "<label>" or secretName

Placeholder shape: {{secret:stripeApiKey|scope=user}}.

Import paths

ExportImport
root dispatcher (default smoke-test)kody:@kody/stripe
account / balance / payouts / eventskody:@kody/stripe/account
customerskody:@kody/stripe/customers
paymentskody:@kody/stripe/payments
invoiceskody:@kody/stripe/invoices
subscriptionskody:@kody/stripe/subscriptions
products / prices / payment linkskody:@kody/stripe/products
webhookskody:@kody/stripe/webhooks
smoke-testkody:@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, cancelSubscription
  • finalizeInvoice, sendInvoice, voidInvoice, deleteDraftInvoice
  • deleteCustomer, 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 display string.
  • Namespace defaults: ./customers → list-customers, ./payments → list-charges, ./invoices → list-invoices, ./subscriptions → list-subscriptions, ./products → list-products.
  • POST helpers accept optional idempotencyKey and only retry automatically when one is provided.
  • Never run money-moving actions in smoke tests.
  • Fork/adapt: save your own stripeApiKey (and optional stripeWebhookSecret); do not point at a shared platform store. Keep dryRun / confirm guards.