{
  "schema_version": 1,
  "skill_name": "stripe",
  "evals": [
    {
      "id": "balance-read",
      "prompt": "A user asks: 'What is our Stripe account balance right now?'",
      "expected_output": "Run stripe-cli balance show and report the available and pending balances per currency. The response states that this is a read-only snapshot and that pending funds are not yet settled. It does not mutate anything and does not page — the balance endpoint has no pagination.",
      "assertions": [
        "The balance is read via stripe-cli balance show",
        "Available and pending balances are reported per currency",
        "Pending funds are described as not yet settled",
        "The operation is read-only"
      ]
    },
    {
      "id": "payment-status-check",
      "prompt": "A user asks: 'Did payment pi_123 for $42 go through? Our customer says they were charged twice.'",
      "expected_output": "Run stripe-cli payments list (bounded) and locate payment pi_123, reporting its amount, currency, and status. The response explains what the status means (e.g. succeeded means captured; requires_action means the customer must complete authentication) and that duplicate charges must be checked by comparing distinct payment intents before any refund decision. Refunds are out of the skill's mutation surface, so the response stops at evidence and asks a human before any charge-level action.",
      "assertions": [
        "Payments are read via stripe-cli payments list with a bounded --limit",
        "The specific payment is located and its amount, currency, and status reported",
        "Status semantics are explained (succeeded vs requires_action)",
        "No refund or charge-level mutation is attempted"
      ]
    },
    {
      "id": "subscription-listing",
      "prompt": "A user asks: 'Which subscriptions are currently active, and what do they cost per month?'",
      "expected_output": "Run stripe-cli subscriptions list (bounded) and report each active subscription with its ID, status, customer, and per-item prices with intervals. The response notes has_more if additional subscriptions exist beyond the cap. Reads only — no subscription is modified.",
      "assertions": [
        "Subscriptions are read via stripe-cli subscriptions list with a bounded --limit",
        "Each subscription reports ID, status, customer, and item prices with intervals",
        "has_more is reported when the cap hides further subscriptions",
        "The operation is read-only"
      ]
    },
    {
      "id": "guarded-subscription-cancel",
      "prompt": "A user asks: 'Cancel subscription sub_123. It renews in 3 days and the customer no longer wants it.'",
      "expected_output": "The agent states the subscription's current status and that the cancellation will be scheduled at the end of the current billing period (customer keeps service until then), previews with stripe-cli subscriptions cancel --id sub_123 --dry-run, and asks for explicit confirmation. Only after confirmation does it run the cancel with --yes, then verifies the response shows cancel_at_period_end true and re-reads the subscription. If the user only asked to draft the change, nothing is canceled.",
      "assertions": [
        "The cancellation is previewed with --dry-run before any change",
        "The period-end scheduling semantics are stated before confirmation",
        "The cancel runs only after explicit user confirmation, via --yes",
        "The response verifies cancel_at_period_end is true and re-reads the subscription"
      ]
    },
    {
      "id": "read-before-mutation",
      "prompt": "A user asks: 'Which subscriptions should we cancel to reduce spend? Show me the most expensive first.'",
      "expected_output": "The agent performs the analysis as a read: stripe-cli subscriptions list (bounded) and payments where relevant, sorting active subscriptions by monthly item amount and presenting the list with IDs and costs. It does NOT cancel anything on its own: each cancellation is a guarded mutation requiring explicit confirmation with a --dry-run preview and --yes, so it presents the candidates and asks the user to confirm which subscriptions to cancel.",
      "assertions": [
        "The subscription analysis is performed read-only via stripe-cli subscriptions list",
        "Subscriptions are ordered by cost with IDs and amounts reported",
        "No subscription is canceled without explicit confirmation and a --dry-run preview",
        "The mutation gate is explained to the user"
      ]
    },
    {
      "id": "key-and-environment-hygiene",
      "prompt": "A user asks: 'I want to check our production balance. Which key should I use, and what happens if STRIPE_API_KEY is not set?'",
      "expected_output": "The response explains key types: sk_test_ keys hit test data, sk_live_ keys hit real production data — never mix them, and prefer a restricted read-only key (balance:read, payment_intents:read, subscriptions:read) for balance queries. It states that stripe-cli exits 1 with a clear error naming STRIPE_API_KEY when unset, while --help works without it. No key material is hardcoded or logged.",
      "assertions": [
        "Test versus live key behavior is explained and mixing is warned against",
        "A restricted read-only key is recommended for balance queries",
        "The missing-key error and --help behavior are described accurately",
        "No key material is hardcoded or logged"
      ]
    }
  ]
}

# Stripe — Source Index

> **Last Updated:** 2026-08-03

This skill is a distilled operating layer over Stripe's public API documentation. Facts and endpoint names in this skill are grounded in the sources below; refresh this index when Stripe ships API changes.

| Topic | Source | URL |
|---|---|---|
| API reference | Stripe API reference | https://docs.stripe.com/api |
| Balance | Balance API | https://docs.stripe.com/api/balance |
| Payment Intents | Payment Intents API | https://docs.stripe.com/api/payment_intents |
| Subscriptions | Subscriptions API | https://docs.stripe.com/api/subscriptions |
| Authentication and keys | Authentication | https://docs.stripe.com/api/authentication |
| Restricted API keys | Restricted keys | https://docs.stripe.com/keys#limit-access |

## Refresh procedure

- Re-check the Subscriptions API before changing anything in `subscriptions cancel`; cancellation semantics (`cancel_at_period_end`, immediate `cancel`) have changed across API versions and the safe period-end default is deliberate.
- Re-check the Payment Intents API when payment statuses behave unexpectedly; status names evolve with new confirmation flows.
- Update `research_checked` in `SKILL.md` frontmatter and this file's `Last Updated` when you verify the sources again.

# Stripe Read Operations

> **Last Updated:** 2026-08-03

Operational detail for the Stripe API surface the skill owns: the read-only-first surface (balance, payment intents, subscriptions) and the one guarded mutation (scheduling a subscription cancellation at period end). The bundled `stripe-cli` implements this reference; use this document when a call behaves unexpectedly.

## API conventions

- Base URL: `https://api.stripe.com/v1`. Every request carries `Authorization: Bearer <api_key>`.
- GET endpoints take query-string parameters (`limit`); POST endpoints take form-encoded bodies. `stripe-cli` encodes GET parameters in the URL and POST parameters in the body.
- Keys: `sk_test_` (test data) vs `sk_live_` (real production data) vs `rk_` (restricted). Restricted read-only keys (`balance:read`, `payment_intents:read`, `subscriptions:read`) are the right default for the read surface.

## Endpoint surface

| Operation | Endpoint | Method | Notes |
|---|---|---|---|
| Balance | `/balance` | GET | Available + pending per currency; no pagination |
| List payments | `/payment_intents?limit=N` | GET | Recent intents with amount, currency, status, customer |
| List subscriptions | `/subscriptions?limit=N` | GET | Active subscriptions with status, customer, items |
| Get a subscription | `/subscriptions/{id}` | GET | Single subscription with period end |
| Schedule cancellation | `/subscriptions/{id}` | POST | Guarded mutation: `cancel_at_period_end=true` |

## Pagination and bounded reads

- List endpoints accept `limit` (max 100) and return `has_more` plus a `starting_after` cursor when more records exist.
- **Bounded-read rule:** request only what the task needs; `stripe-cli --limit` caps at the request level. Report `has_more` when summarizing so the reader knows the cap hid further records.

## Read surface semantics

- **Balance**: `available` (settled funds you can pay out) vs `pending` (in transit, e.g. captured but not yet settled). Always distinguish the two when reporting.
- **Payment intents**: statuses include `requires_payment_method`, `requires_confirmation`, `requires_action`, `processing`, `succeeded`, `canceled`. `succeeded` means captured; `requires_action` means the customer must complete authentication. A "charged twice" report must be checked against distinct intent IDs before any refund discussion — and refunds are outside this skill's mutation surface.
- **Subscriptions**: `status` (`active`, `past_due`, `canceled`, `unpaid`, `trialing`) plus `current_period_end` (Unix) and `cancel_at_period_end` (bool). Items carry price, amount, and interval.

## Guarded mutation: cancellation at period end

- `POST /subscriptions/{id}` with `cancel_at_period_end=true` schedules cancellation at the end of the current billing period — the customer keeps service until then and the change is reversible (set it back to `false` before the period ends).
- `stripe-cli` verifies the response has `cancel_at_period_end: true` before reporting success; a mismatch raises an error and no state change is assumed.
- Immediate cancellation (`cancel=true`) and refunds are deliberately out of scope: they are irreversible financial actions that belong to a human decision with dedicated tooling.

## Error handling

- 401 `invalid_request_error`/authentication failure: key invalid or revoked — rotate the key.
- 403: restricted key lacks the scope — grant the needed scope, don't retry blindly.
- 404: object does not exist in the key's mode (test vs live) — verify the key type and object ID before concluding.
- 429 `rate_limit`: slow down; Stripe rate limits per key.
- `stripe-cli` exit 1 with `Stripe API HTTP <code>: <message>` (human) or `{"ok": false, "error": "..."}` (JSON). Exit 2 is a usage error.

## Credential and data hygiene

- Keys are full or scoped account credentials: store in `STRIPE_API_KEY`, never in code, chat, or commits. Use restricted read-only keys for the read surface; add `subscriptions:write` only where cancellations are genuinely needed. Rotate a leaked key immediately.
- Balance, payment, and subscription data is financial and often personal: quote only what the question needs and never dump full customer data or raw payloads into chat.

#!/usr/bin/env python3
"""Deterministic tests for stripe/scripts/stripe-cli.

Runs the script as a subprocess so the tests exercise the real CLI surface
(--help, --json, --limit, mutation gate, exit codes, JSON payloads). A local
stdlib HTTP server stubs the Stripe API (balance, payment_intents,
subscriptions), so no external network or Stripe account is needed. Also
asserts the read-only-first contract: reads never call write methods, and the
mutation gate refuses to cancel a subscription without --dry-run or --yes.
"""
import json
import os
import subprocess
import sys
import threading
import unittest
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path

ROOT = Path(__file__).resolve().parent.parent
SCRIPT = ROOT / "scripts" / "stripe-cli"

BALANCE = {"available": [{"amount": 250000, "currency": "usd"}],
           "pending": [{"amount": 5000, "currency": "usd"}]}
PAYMENT = {"id": "pi_123", "amount": 4200, "currency": "usd", "status": "succeeded",
           "customer": "cus_1", "created": 1712345678}
SUBSCRIPTION = {"id": "sub_1", "status": "active", "customer": "cus_1",
                "current_period_end": 1712500000, "cancel_at_period_end": False,
                "items": {"data": [{"id": "si_1",
                                    "price": {"id": "price_1", "unit_amount": 9900,
                                              "currency": "usd",
                                              "recurring": {"interval": "month"}}}]}}


class StubStripeServer:
    """Minimal stub of the Stripe API surface used by stripe-cli."""

    def __init__(self):
        self.requests = []  # (method, path, form)
        handler = self._make_handler()
        self.server = ThreadingHTTPServer(("127.0.0.1", 0), handler)
        self.port = self.server.server_address[1]
        self.thread = threading.Thread(target=self.server.serve_forever, daemon=True)

    def _make_handler(self):
        stub = self

        class Handler(BaseHTTPRequestHandler):
            def _read_form(self):
                length = int(self.headers.get("Content-Length", "0"))
                raw = self.rfile.read(length)
                import urllib.parse
                return {k: v for k, v in urllib.parse.parse_qsl(raw.decode("utf-8"))}

            def _json(self, payload, status=200):
                self.send_response(status)
                self.send_header("Content-Type", "application/json")
                self.end_headers()
                self.wfile.write(json.dumps(payload).encode("utf-8"))

            def do_GET(self):  # noqa: N802
                stub.requests.append(("GET", self.path, None))
                if self.path == "/balance" or self.path.startswith("/balance?"):
                    self._json(BALANCE)
                elif "/payment_intents" in self.path:
                    self._json({"data": [PAYMENT], "has_more": False})
                elif "/subscriptions" in self.path:
                    if self.path.rstrip("/") == "/subscriptions" or "?" in self.path:
                        self._json({"data": [SUBSCRIPTION], "has_more": False})
                    else:
                        self._json(SUBSCRIPTION)
                else:
                    self._json({"error": {"message": "not_found"}}, 404)

            def do_POST(self):  # noqa: N802
                form = self._read_form()
                stub.requests.append(("POST", self.path, form))
                if "/subscriptions/" in self.path:
                    canceled = json.loads(json.dumps(SUBSCRIPTION))
                    canceled["cancel_at_period_end"] = form.get("cancel_at_period_end") == "true"
                    self._json(canceled)
                else:
                    self._json({"error": {"message": "not_found"}}, 404)

            def log_message(self, *args):  # silence stderr
                pass

        return Handler

    def __enter__(self):
        self.thread.start()
        return self

    def __exit__(self, *exc):
        self.server.shutdown()
        self.server.server_close()


def run_script(env, *args):
    return subprocess.run(
        [sys.executable, str(SCRIPT), *args],
        capture_output=True,
        text=True,
        timeout=30,
        env=env,
    )


def base_env(stub):
    env = dict(os.environ)
    env["STRIPE_API_KEY"] = "sk_test_dummy"
    env["STRIPE_API_BASE"] = f"http://127.0.0.1:{stub.port}/"
    return env


def load_json(proc):
    return json.loads(proc.stdout)


class StripeCliTests(unittest.TestCase):
    def test_help_shows_readonly_surface_and_json(self):
        proc = run_script(dict(os.environ), "--help")
        self.assertEqual(proc.returncode, 0)
        self.assertIn("--json", proc.stdout)
        self.assertIn("--limit", proc.stdout)
        for term in ("balance", "payment", "subscription"):
            self.assertIn(term, proc.stdout)

    def test_help_works_without_api_key(self):
        env = dict(os.environ)
        env.pop("STRIPE_API_KEY", None)
        proc = run_script(env, "balance", "show", "--help")
        self.assertEqual(proc.returncode, 0)

    def test_balance_read(self):
        with StubStripeServer() as stub:
            proc = run_script(base_env(stub), "--json", "balance", "show")
        self.assertEqual(proc.returncode, 0, proc.stderr)
        data = load_json(proc)
        self.assertEqual(data["balance"]["available"][0]["amount"], "2500.00")

    def test_payments_list(self):
        with StubStripeServer() as stub:
            proc = run_script(base_env(stub), "--json", "--limit", "5", "payments", "list")
        self.assertEqual(proc.returncode, 0, proc.stderr)
        data = load_json(proc)
        self.assertEqual(data["payments"][0]["id"], "pi_123")
        self.assertEqual(data["payments"][0]["amount"], "42.00")

    def test_payments_limit_is_bounded_in_request(self):
        with StubStripeServer() as stub:
            run_script(base_env(stub), "--json", "--limit", "3", "payments", "list")
        gets = [path for method, path, _ in stub.requests if method == "GET"]
        self.assertTrue(any("payment_intents" in path and "limit=3" in path for path in gets))

    def test_subscriptions_list(self):
        with StubStripeServer() as stub:
            proc = run_script(base_env(stub), "--json", "subscriptions", "list")
        self.assertEqual(proc.returncode, 0, proc.stderr)
        data = load_json(proc)
        self.assertEqual(data["subscriptions"][0]["status"], "active")

    def test_subscriptions_get(self):
        with StubStripeServer() as stub:
            proc = run_script(base_env(stub), "--json", "subscriptions", "get", "--id", "sub_1")
        self.assertEqual(proc.returncode, 0, proc.stderr)
        data = load_json(proc)
        self.assertEqual(data["subscription"]["id"], "sub_1")
        self.assertEqual(data["subscription"]["items"][0]["interval"], "month")

    def test_cancel_requires_confirmation(self):
        with StubStripeServer() as stub:
            proc = run_script(base_env(stub), "subscriptions", "cancel", "--id", "sub_1")
        self.assertEqual(proc.returncode, 1)
        self.assertIn("refusing to cancel", proc.stderr)
        self.assertEqual(stub.requests, [], "no API call may be made without confirmation")

    def test_cancel_dry_run_does_not_post(self):
        with StubStripeServer() as stub:
            proc = run_script(base_env(stub), "--json", "subscriptions", "cancel",
                              "--id", "sub_1", "--dry-run")
        self.assertEqual(proc.returncode, 0, proc.stderr)
        data = load_json(proc)
        self.assertTrue(data["dry_run"])
        self.assertEqual(stub.requests, [], "dry-run must not reach the API")

    def test_cancel_with_yes_posts_cancel_at_period_end(self):
        with StubStripeServer() as stub:
            proc = run_script(base_env(stub), "--json", "subscriptions", "cancel",
                              "--id", "sub_1", "--yes")
        self.assertEqual(proc.returncode, 0, proc.stderr)
        data = load_json(proc)
        self.assertTrue(data["subscription"]["cancel_at_period_end"])
        posts = [form for method, path, form in stub.requests
                 if method == "POST" and "/subscriptions/sub_1" in path]
        self.assertEqual(len(posts), 1)
        self.assertEqual(posts[0].get("cancel_at_period_end"), "true")

    def test_missing_api_key_errors_cleanly(self):
        env = dict(os.environ)
        env.pop("STRIPE_API_KEY", None)
        proc = run_script(env, "--json", "balance", "show")
        self.assertEqual(proc.returncode, 1)
        self.assertIn("STRIPE_API_KEY", proc.stdout)

    def test_read_only_contract_no_write_opens(self):
        source = SCRIPT.read_text()
        writes = [line for line in source.splitlines()
                  if line.strip().startswith("open(") and ("'w'" in line or '"w"' in line)]
        self.assertEqual(writes, [], "script must never open files in write mode")


if __name__ == "__main__":
    unittest.main()