# 📚 Repzo TypeScript SDK

[![npm version](https://badge.fury.io/js/repzo.svg)](https://badge.fury.io/js/repzo)
[![Documentation](https://img.shields.io/badge/docs-📖_available-blue.svg)](./docs/)
[![TypeScript](https://img.shields.io/badge/TypeScript-💪_ready-blue.svg)](https://www.typescriptlang.org/)
[![OpenAPI](https://img.shields.io/badge/OpenAPI-3.0-green.svg)](https://swagger.io/specification/)

A comprehensive TypeScript SDK for the Repzo API platform with **automatically generated documentation** from OpenAPI specifications.

## 🚀 Features

- **Full TypeScript Support**: Complete type definitions for all APIs
- **Comprehensive Documentation**: Auto-generated from 86+ OpenAPI specifications
- **Interactive Docs**: Beautiful HTML documentation with ReDoc
- **Multiple Formats**: Markdown and HTML documentation
- **Type Safety**: IntelliSense support and compile-time checking
- **Always Up-to-Date**: Documentation automatically syncs with API changes

## 📦 Installation

```bash
npm install repzo
```

## 🔧 Quick Start

```typescript
import Repzo from "repzo";

// Basic initialization
const repzo = new Repzo("my-repzo-api-key");

// With options (staging environment, custom timeout, retry logic)
const repzoWithOptions = new Repzo("my-repzo-api-key", {
  env: "staging", // 'production', 'staging', or 'local'
  timeout: 60000, // Request timeout in milliseconds
  retryAttempts: 3, // Number of retry attempts (default: 3)
  headers: {
    "Custom-Header": "value",
  },
});

// Find clients
let clients = repzo.client.find({ search: "Mecca" });

// Example usage with type safety
const params: Service.Client.Find.Params = {
  page: 1,
  per_page: 25,
  active: true,
};

// Your API implementation here
```

### Retry Logic

The SDK includes automatic retry logic for failed requests:

- **Default Behavior**: Automatically retries failed requests up to 3 times
- **Exponential Backoff**: Uses exponential backoff strategy (2^attempt seconds)
- **401 Protection**: Never retries on 401 (Unauthorized) errors
- **Configurable**: Set custom retry attempts via `retryAttempts` option

```typescript
// Default: 3 retry attempts
const repzo = new Repzo("api-key");

// Custom: 5 retry attempts
const repzoCustom = new Repzo("api-key", { retryAttempts: 5 });

// Disable retries: 1 attempt only
const repzoNoRetry = new Repzo("api-key", { retryAttempts: 1 });
```

## 📖 Documentation

This SDK provides **three levels of documentation**:

### 1. 🏠 **Documentation Hub**

**[Open Interactive Documentation](./docs/generated/index.html)**

A beautiful web interface showcasing all 86+ APIs with:

- Interactive API explorer
- Search functionality
- Try-it-out capabilities
- Mobile-responsive design

### 2. 📚 **Complete API Reference**

**[View Complete API Documentation](./docs/generated/repzo-api-complete.html)**

Single comprehensive document containing:

- All endpoints in one place
- Complete request/response schemas
- Authentication details
- Error handling information

### 3. 📝 **Individual API Docs**

Each API has dedicated documentation:

- **[API Reference](./docs/api/)** - Detailed Markdown documentation
- **[TypeScript Examples](./docs/api/)** - Practical code examples

### Available APIs (86+ endpoints)

| Category          | APIs                             | Description            |
| ----------------- | -------------------------------- | ---------------------- |
| **Core Business** | Client, Product, Brand, Category | Core business entities |
| **Inventory**     | Inventory, Warehouse, Transfer   | Inventory management   |
| **Sales**         | Invoice, Sales Order, Payments   | Sales operations       |
| **Assets**        | Asset, Asset Parts, Workorders   | Asset management       |
| **Feedback**      | Activity Feedback V1/V2, Forms   | Customer feedback      |
| **Media**         | Media, Media Storage             | File management        |
| **Admin**         | Teams, Reps, Settings            | Administration         |
| **Integration**   | Webhooks, Logs, Commands         | System integration     |

**[👀 View All APIs](./docs/api/index.md)**

## 🛠️ Development

### Generate Documentation

```bash
# Generate all documentation (Markdown + HTML)
npm run docs:build

# Generate only Markdown docs
npm run docs:python

# Generate only HTML docs
npm run docs:generate

# Serve documentation locally
npm run docs:serve
# Then open http://localhost:8080
```

### Documentation Scripts

| Script          | Description                     |
| --------------- | ------------------------------- |
| `docs:build`    | Generate complete documentation |
| `docs:clean`    | Remove generated documentation  |
| `docs:rebuild`  | Clean and rebuild all docs      |
| `docs:serve`    | Serve docs locally on port 8080 |
| `docs:validate` | Validate documentation files    |

## 📂 Documentation Structure

```
docs/
├── README.md                          # Main documentation
├── api/                              # Markdown documentation
│   ├── index.md                      # API index
│   ├── {api-name}.md                # API reference
│   └── {api-name}-examples.md       # TypeScript examples
└── generated/                        # Interactive HTML docs
    ├── index.html                    # Documentation hub
    ├── {api-name}.html              # Individual API docs
    └── repzo-api-complete.html      # Complete API reference
```

## 💡 Key Benefits for NPM Users

### 🎯 **For Developers**

- **IntelliSense Support**: Full autocomplete in your IDE
- **Type Safety**: Catch errors at compile time
- **Practical Examples**: Ready-to-use TypeScript code
- **Interactive Testing**: Try APIs directly in documentation

### 📚 **For Teams**

- **Always Current**: Docs auto-update with API changes
- **Multiple Formats**: Choose Markdown or interactive HTML
- **Comprehensive Coverage**: 86+ APIs fully documented
- **Search & Navigation**: Find what you need quickly

### 🚀 **For Projects**

- **Faster Integration**: Clear examples and schemas
- **Better Reliability**: Type checking prevents runtime errors
- **Professional Docs**: Beautiful, searchable documentation
- **Offline Access**: Documentation included in NPM package

## 🔍 Example Usage

### Type-Safe API Calls

```typescript
import { Service } from "repzo";

// Full type safety for parameters
const clientParams: Service.Client.Find.Params = {
  page: 1,
  per_page: 25,
  search: "coffee shop",
  active: true,
  tags: ["retail", "food-service"],
};

// Type-safe response handling
const handleResponse = (result: Service.Client.Find.Result) => {
  console.log(`Found ${result.paging.total} clients`);
  result.data.forEach((client) => {
    console.log(`${client.name} - ${client.formatted_address}`);
  });
};
```

### Error Handling with Types

```typescript
try {
  const result = await apiCall();
  if (result.success) {
    // TypeScript knows the exact shape of result.data
    console.log("Data:", result.data);
  }
} catch (error) {
  // Handle API errors appropriately
  console.error("API Error:", error);
}
```

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Update OpenAPI specs in `src/oas/` if needed
4. Generate documentation: `npm run docs:build`
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

## 📜 License

This project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- **GitHub Issues**: [Report bugs or request features](https://github.com/Repzo/repzo-ts/issues)
- **Documentation**: [Browse complete API docs](./docs/)
- **Examples**: [View TypeScript examples](./docs/api/)

## 📊 Stats

- **86+ API Endpoints**: Comprehensive coverage
- **100% TypeScript**: Full type safety
- **Auto-Generated**: Always up-to-date documentation
- **Multiple Formats**: Markdown + Interactive HTML
- **Zero Config**: Documentation included in NPM package

---

**Made with ❤️ by the Repzo Team**

_Comprehensive documentation automatically generated from OpenAPI 3.0 specifications_