@ovt-sdk/partners

Official TypeScript/JavaScript SDK for Ovation Partner Services API

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

npm install @ovt-sdk/partners

Quick Start

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

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

Companies API

// 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 - Comprehensive guide with detailed examples

Key Topics

• Authentication Flow
• OAuth2 API Reference
• Companies API Reference
• Error Handling
• TypeScript Support
• Best Practices
• Examples

Configuration

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

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:

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

// 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

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

# Run tests
npm test

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

Support

• Issues: GitHub Issues
• Documentation: API Documentation
• Email: [email protected]

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT © Ovation

Related Packages

• @ovt-sdk/app-services - App Services SDK
• @ovt-sdk/core - Core SDK utilities

View Full API Documentation →