# CLAUDE.md

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

## Repository Overview

This is the Nami React Native SDK (`react-native-nami-sdk`), a TypeScript bridge layer that exposes native Android and iOS SDK functionality to React Native applications via TurboModules. The SDK is a thin bridge — all business logic lives in the native Android and Apple SDKs.

## Development Setup

### Prerequisites
- Node.js 20+
- npm
- For iOS bridge work: Xcode + CocoaPods
- For Android bridge work: Android Studio with JDK 17

### Install dependencies
```bash
cd sdk/react-native && npm install
```

## Build Commands

```bash
# From monorepo root
make build-react-native   # Install npm dependencies
make test-react-native    # Run Jest unit tests
make lint-react-native    # Run pre-commit + ktlint checks
```

```bash
# Directly
cd sdk/react-native
npm test                  # Run Jest unit tests
npm run lint              # ESLint
```

## Project Structure

- `src/` — TypeScript bridge layer (managers, types, transformers)
- `specs/` — TurboModule native interface specs (Codegen)
- `android/` — Kotlin native bridge modules
- `ios/` — Swift + Objective-C native bridge
- `dist/` — Built `.d.ts` type declarations (`emitDeclarationOnly`)
- `examples/Basic/` — Full-featured sample app with Detox e2e tests
- `examples/TestNamiTV/` — tvOS sample app
- `build-utils/` — Version management scripts

## Architecture

The SDK is a **thin bridge** — no business logic lives here. TypeScript managers wrap TurboModules; TurboModules call into the native Android/Apple SDKs.

```
JavaScript (React Native)
    ↓
TypeScript Managers (src/)
    ↓
TurboModule Specs (specs/)
    ↓
Native Bridge Modules (android/ + ios/)
    ↓
Native SDKs (com.namiml:sdk-android / Nami CocoaPod)
```

### Adding or changing bridge methods

1. Update the TurboModule spec in `specs/` (TypeScript interface)
2. Update the TypeScript manager in `src/`
3. Update the Kotlin bridge module in `android/`
4. Update the Swift bridge module in `ios/`
5. Run `npm run lint` and `make test-react-native` before committing

## Testing

### Unit Tests (Jest + ts-jest)
Tests cover the pure data transformation layer in `src/transformers.ts` and live in `src/__tests__/`.

```bash
make test-react-native
# or: cd sdk/react-native && npm test
```

### E2E Tests (Detox)
Located in `examples/Basic/e2e/`. Run via CI. See `ARCHITECTURE.md` for local native SDK resolution setup required before running e2e locally.

## Code Quality

- **ESLint** (`@react-native` config) + **Prettier** for TypeScript
- **ktlint** for Kotlin bridge code — run `ktlint -F` on changed `.kt` files before committing
- Pre-commit hooks via `.pre-commit-config.yaml`

## Key Files

- `src/index.ts` — Main exports
- `src/types.ts` — All public TypeScript types
- `src/transformers.ts` — Data transformation between native and JS types (unit-tested)
- `specs/` — TurboModule specs (source of truth for the native bridge contract)