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

# 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)

2.5 KiB Raw Blame History