stripe — CLAUDE.md

# Stripe Node.js SDK — CLAUDE.md

## Overview

This is the official Stripe Node.js library. It provides convenient access to the Stripe REST API from Node.js and browser environments.

## Development Setup

```bash
npm install
npm run build
npm test
```

## Code Style

- TypeScript strict mode is enabled.
- All public APIs must be typed; avoid `any`.
- Use `readonly` for properties that shouldn't change after construction.
- Prefer `interface` over `type` for object shapes.

## Testing

- Tests live in `test/` and mirror the `src/` structure.
- Run the full suite: `npm test`
- Use `nock` for HTTP mocking — never make real API calls in tests.
- Every new feature needs a corresponding test.

## Versioning & Releases

- Follow semantic versioning strictly.
- Breaking changes require a major version bump.
- All changes must be documented in `CHANGELOG.md`.

## API Design Principles

- Match the Stripe REST API structure as closely as possible.
- Resource methods should mirror API endpoints: `stripe.customers.create()`, `stripe.charges.retrieve()`.
- Always return typed responses.
- Handle pagination consistently across list endpoints.

## Error Handling

- Throw `StripeError` subclasses for API errors.
- Always include the HTTP status, error code, and error message.
- Don't swallow errors silently.

## Commit Convention

- Use conventional commits: `feat:`, `fix:`, `docs:`, `chore:`.
- Reference issue numbers when applicable.