From 045f828c62b6879e11ef7628255e80c4ae7d2a8a Mon Sep 17 00:00:00 2001
From: Duhan BALCI <duhanbalci@msn.com>
Date: Fri, 16 Oct 2026 11:14:13 +0300
Subject: [PATCH] docs: add CLAUDE.md

---
 CLAUDE.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..91b10df
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,81 @@
+# 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)