# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is the `@duhanbalci/iyzico-sdk` TypeScript library for integrating with the iyzico payment gateway. It provides a type-safe SDK for payment processing operations including 3DS/Non-3DS payments, card storage, BIN checking, refunds/cancellations, and reporting.

## Commands

```bash
# Install dependencies
npm install

# Build (outputs ESM + CJS to dist/)
npm run build

# Watch mode for development
npm run dev  # or npm run watch

# Run all tests
npm test

# Run unit tests only
npm test:unit

# Run integration tests only (requires .env credentials)
npm test:integration

# Run single test file
npx vitest run tests/unit/auth.test.ts

# Run tests matching a pattern
npx vitest run -t "pattern"

# Watch mode for tests
npm run test:watch

# Coverage report
npm run test:coverage
```

## Architecture

### Core Modules

- `src/client.ts` - `IyzicoClient` main entry point. Instantiates with API credentials and exposes service properties.
- `src/auth.ts` - HMAC SHA256 signature generation for iyzico's `IYZWSv2` auth scheme.
- `src/http.ts` - HTTP layer with retry-on-rate-limit support and error handling.
- `src/errors.ts` - Custom error classes: `IyzicoError`, `IyzicoRequestError`, `IyzicoResponseError`.

### Services (src/services/)

Each service wraps a domain of iyzico API endpoints:
- `payment.ts` - 3DS/Non-3DS payments, payment details
- `bin-check.ts` - BIN number lookup
- `cancel-refund.ts` - Payment cancellations and refunds
- `card-storage.ts` - Card and user management
- `reporting.ts` - Transaction reports
- `installment.ts` - Installment options

### Types (src/types/)

Request/response interfaces organized by domain. All exported from `src/types/index.ts`.

### Test Structure

- `tests/setup.ts` - Creates `IyzicoClient` from env vars, provides test utilities
- `tests/fixtures/` - Reusable test data
- `tests/unit/` - Unit tests (mocked)
- `tests/integration/` - Live API tests against sandbox

## Important Notes

- Uses `tsdown` (Rolldown + Oxc based) for building - not webpack/rollup directly
- Integration tests require `.env` file with `IYZICO_API_KEY` and `IYZICO_API_SECRET`
- Sandbox URL: `https://sandbox-api.iyzipay.com`
- Production URL: `https://api.iyzipay.com`
- Tests run sequentially (`singleFork: true`) to avoid rate limiting
- Track implementation progress in `checklist.md`
- API documentation available in `ai-docs/` (auth scheme, endpoints)