Stripe Skill

A library-first, read-only Stripe analysis toolkit for AI agents and humans. It provides a small, stable interface for reading Stripe balance transactions, producing finance summaries, exporting raw transaction JSON, and building daily sales summaries from successful PaymentIntents.

This is not a Stripe Dashboard replacement, a payment executor, or a generic Stripe API proxy. The project deliberately keeps the public contract narrow: read data, normalize it, summarize it, and write local artifacts only when explicitly requested.

This repository is designed to be publishable with only fake examples. Real API keys, local data, generated charts, and private business-specific analysis overlays must stay outside the public repo.

Capabilities

• Load Stripe configuration from .env or already-injected environment variables.
• Select test or live keys with STRIPE_ENV, with STRIPE_SECRET_KEY as an explicit override.
• Read Stripe balance transactions through a constrained client.
• Summarize gross, net, fees, transaction counts, and transaction types by day.
• Read successful PaymentIntents and normalize sales to USD settled amount through latest_charge.balance_transaction.
• Export raw balance transaction JSON.
• Generate daily sales PNG charts as local artifacts.
• Keep the legacy sync_stripe.py entry point as a thin compatibility wrapper.

Install

git clone <this-repo> stripe_skill
cd stripe_skill
cp .env.example .env
uv venv .venv
uv pip install --python .venv/bin/python -e '.[dev]'

Edit .env and replace the placeholder values with your own Stripe keys. Keep .env private. If your local workflow stores secret-manager references in .env, resolve them outside the library and inject real environment variables before running live commands.

For AI Agents

When a user asks for Stripe finance or sales analysis through this repo, start from the repository root and read skills/stripe_skill.md. That skill file defines the command contract, safety boundaries, output locations, and acceptance criteria.

Useful entry points:

scripts/stripe doctor config
scripts/stripe finance summary --days 30 --format text
scripts/stripe finance summary --full --format json
scripts/stripe sales summary --days 30 --format text
scripts/stripe sales chart --days 120 --output docs/assets/daily_sales_usd_120d.png
scripts/stripe transactions export --days 30 --output data/transactions_raw.json
scripts/sync_stripe --days 30

For module-style invocation:

.venv/bin/python -m stripe_skill.cli doctor config
.venv/bin/python -m stripe_skill.cli finance summary --days 30 --format text
.venv/bin/python -m stripe_skill.cli sales summary --days 30 --format text
.venv/bin/python -m stripe_skill.cli transactions export --days 30 --output data/transactions_raw.json

The CLI parses arguments, loads configuration, calls the library, and prints JSON or text. Business logic belongs in src/stripe_skill/, not in shell wrappers or ad hoc scripts.

Safety And Privacy

The library never performs write operations against Stripe. It does not create payments, refunds, customers, invoices, transfers, subscriptions, or arbitrary API calls. It also does not invoke a secret manager directly. If a secret-manager reference is present in .env, resolve it in the surrounding shell before calling the CLI.

Local outputs are private by default. data/ may contain raw transaction JSON and summary artifacts. docs/assets/*.png may contain generated charts. Both are ignored by git and should not be committed unless they are synthetic fixtures created for documentation.

Live integration tests are opt-in. They only run when STRIPE_ENABLE_LIVE_TESTS=1 is set and valid credentials are already injected.

Project Structure

stripe_skill/
├── AGENTS.md
├── README.md
├── docs/
├── scripts/
├── skills/
├── src/stripe_skill/
├── tests/
└── sync_stripe.py

src/stripe_skill/ contains configuration, the constrained Stripe client, normalized models, finance summary logic, sales summary logic, services, CLI, and compatibility code. growth/ is reserved for future read-only analysis modules; it is not a generic API passthrough boundary.

For Developers

Run the offline test suite first:

.venv/bin/python -m pytest -v

Run live tests only when you intentionally want to hit Stripe:

STRIPE_ENABLE_LIVE_TESTS=1 .venv/bin/python -m pytest -v -m live_integration

Recommended smoke checks after changing configuration or CLI behavior:

.venv/bin/python -m stripe_skill.cli doctor config
.venv/bin/python -m stripe_skill.cli finance summary --days 30 --format text

Do not run live data export or chart commands as part of routine verification unless the task explicitly requires live Stripe access.

Non-Goals

• Stripe write operations.
• Arbitrary Stripe SDK passthrough.
• Dashboard UI.
• Database storage.
• Background sync service.
• Secret-manager integration inside the core library.
• Private product attribution or workspace-specific growth analysis workflows.