npm package: @ovt-sdk/partners
Description: Official TypeScript/JavaScript SDK for Ovation Partner Services API
Author: Ovation
Latest version: 0.2.0

# @ovt-sdk/partners

> Official TypeScript/JavaScript SDK for Ovation Partner Services API

[![npm version](https://badge.fury.io/js/%40ovt-sdk%2Fpartners.svg)](https://www.npmjs.com/package/@ovt-sdk/partners)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- 🔐 **OAuth2 Authentication** - Secure token-based authentication
- 🏢 **Companies API** - Full CRUD operations for company management
- ✅ **Built-in Validation** - Request/response validation using Zod
- 🔄 **Auto Retry** - Automatic retry logic with exponential backoff
- 📝 **TypeScript First** - Full type definitions included
- 🚀 **ESM & CommonJS** - Support for both module systems

## Installation

```bash
npm install @ovt-sdk/partners
```

## Quick Start

```typescript
import Partners from '@ovt-sdk/partners'

// 1. Configure the SDK
Partners.configure({
  environment: 'sandbox',
  auth: {
    token: 'your-token',
    ovationId: 'your-partner-name'
  }
})

// 2. Get an access token
const tokenResponse = await Partners.OAuth2Api.getAccessTokenAsync({
  grant_type: 'client_credentials',
  scopes: ['admin']
})

// 3. Use the API
const companies = await Partners.CompanyApi.listAsync()
console.log(companies.data.companies)
```

## Available APIs

### OAuth2 API

```typescript
// Get access token
const token = await Partners.OAuth2Api.getAccessTokenAsync({
  grant_type: 'client_credentials',
  scopes: ['admin'],
  company: '507f1f77bcf86cd799439011' // optional
})
```

### Companies API

```typescript
// Get company by ID
const company = await Partners.CompanyApi.getByIdAsync('507f1f77bcf86cd799439011')

// List companies
const companies = await Partners.CompanyApi.listAsync(
  { company_ids: ['507f1f77bcf86cd799439011'] },
  { limit: 50, skip: 0 }
)

// Create company
const newCompany = await Partners.CompanyApi.createAsync({
  name: 'Acme Restaurant',
  industry: 'restaurant',
  url: 'https://acme.com',
  logo: 'https://acme.com/logo.png',
  address_1: '123 Main St',
  city: 'New York',
  state: 'NY',
  zip: '10001',
  country: 'US',
  user: '507f1f77bcf86cd799439012'
})

// Update company
const updated = await Partners.CompanyApi.updateAsync(
  '507f1f77bcf86cd799439011',
  {
    set: {
      name: 'Acme Restaurant & Bar',
      disabled: false
    }
  }
)

// Retry phone verification
await Partners.CompanyApi.retryPhoneVerificationAsync('507f1f77bcf86cd799439011')
```

## Documentation

📚 **[Complete API Documentation](./API.md)** - Comprehensive guide with detailed examples

### Key Topics

- [Authentication Flow](./API.md#authentication)
- [OAuth2 API Reference](./API.md#oauth2-api)
- [Companies API Reference](./API.md#companies-api)
- [Error Handling](./API.md#error-handling)
- [TypeScript Support](./API.md#typescript-support)
- [Best Practices](./API.md#best-practices)
- [Examples](./API.md#examples)

## Configuration

```typescript
Partners.configure({
  environment: 'production' | 'sandbox',
  auth: {
    token: string,        // Required: Bearer token or client credentials
    ovationId: string,    // Required: Your partner name (sets X-Ovation-Id header)
    apiKey?: string       // Optional: API Gateway key
  },
  headers?: {             // Optional: Custom headers
    [key: string]: string
  }
})
```

## Environment URLs

| Environment | URL |
|------------|-----|
| **Sandbox** | `https://partner-test.ovationup.com/partner-services/v2` |
| **Production** | `https://partner.ovationup.com/partner-services/v2` |

## Error Handling

```typescript
import { ValidationError, AuthenticationError, NotFoundError } from '@ovt-sdk/partners'

try {
  const company = await Partners.CompanyApi.getByIdAsync('invalid-id')
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message)
  } else if (error instanceof AuthenticationError) {
    console.error('Authentication failed - refresh token')
  } else if (error instanceof NotFoundError) {
    console.error('Company not found')
  }
}
```

## TypeScript

Full TypeScript support with comprehensive type definitions:

```typescript
import type { 
  Company, 
  CompanyCreateData,
  CompanyUpdatePayload,
  OAuth2TokenRequest,
  OAuth2TokenResponse
} from '@ovt-sdk/partners'

const createData: CompanyCreateData = {
  name: 'My Company',
  industry: 'restaurant',
  // ... TypeScript will validate all fields
}
```

## Examples

### Complete Authentication Flow

```typescript
// Get access token
const tokenResponse = await Partners.OAuth2Api.getAccessTokenAsync({
  grant_type: 'client_credentials',
  scopes: ['admin']
})

// Reconfigure with new token
Partners.configure({
  environment: 'production',
  auth: {
    token: tokenResponse.data.access_token,
    apiKey: tokenResponse.data.api_key,
    ovationId: 'your-partner-name'
  }
})

// Now use any API
const companies = await Partners.CompanyApi.listAsync()
```

### Pagination

```typescript
const allCompanies = []
let skip = 0
const limit = 100

while (true) {
  const response = await Partners.CompanyApi.listAsync({}, { limit, skip })
  allCompanies.push(...response.data.companies)
  
  if (response.data.companies.length < limit) break
  skip += limit
}
```

## Requirements

- Node.js >= 18.0.0
- TypeScript >= 4.9.0 (for TypeScript projects)

## Testing

```bash
# Run tests
npm test

# Run tests with coverage
npm test -- --coverage
```

## Support

- **Issues**: [GitHub Issues](https://github.com/your-org/ovt-sdk/issues)
- **Documentation**: [API Documentation](./API.md)
- **Email**: support@ovationup.com

## Contributing

We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for details.

## License

MIT © Ovation

## Related Packages

- [`@ovt-sdk/app-services`](../app-services) - App Services SDK
- [`@ovt-sdk/core`](../core) - Core SDK utilities

---

**[View Full API Documentation →](./API.md)**