mirror of
https://github.com/duhanbalci/iyzico.git
synced 2026-10-30 01:54:59 +00:00
82 lines
2.5 KiB
Markdown
82 lines
2.5 KiB
Markdown
# 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)
|