@prodobit/sdk

The official TypeScript SDK for Prodobit API - A comprehensive client library for interacting with Prodobit's manufacturing and ERP platform.

Features

• 🔒 Type-safe - Full TypeScript support with comprehensive type definitions
• 🏗️ Framework Integration - Built-in support for React Query, SWR, and other data-fetching libraries
• 🔄 Automatic Token Management - Handles authentication and token refresh automatically
• ✅ Runtime Validation - Optional request/response validation with detailed error messages
• 🚀 Interceptors - Powerful middleware system for requests, responses, and errors
• 📦 Tree-shakable - Optimized bundle size with modular exports
• 🧪 Cache Management - Smart caching strategies for different resource types

Installation

npm install @prodobit/sdk
# or
pnpm add @prodobit/sdk
# or
yarn add @prodobit/sdk

Quick Start

Basic Usage

import { ProdobitClient } from '@prodobit/sdk';

const client = new ProdobitClient({
  baseUrl: 'https://api.prodobit.com',
  apiKey: 'your-api-key', // optional
  timeout: 30000, // optional, default 30s
});

// Authenticate with OTP
await client.requestOTP({ email: '[email protected]' });
const response = await client.verifyOTP({ 
  email: '[email protected]', 
  code: '123456' 
});

// Use the API
const tenants = await client.getTenants();
const items = await client.getItems({ itemType: 'product' });

Framework Integration

React Query

import { createFrameworkAPI, queryKeys } from '@prodobit/sdk/framework';
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

const api = createFrameworkAPI(client);
const queryClient = useQueryClient();

// Query Hook
function useItems(filters?: ItemFilters) {
  return useQuery({
    queryKey: queryKeys.items.list(filters),
    queryFn: () => api.items.list(filters),
    staleTime: 5 * 60 * 1000, // 5 minutes
  });
}

// Mutation Hook
function useCreateItem() {
  return useMutation({
    mutationFn: api.items.create,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: queryKeys.items.lists() });
    },
  });
}

SWR

import { queryKeys, toSWRKey } from '@prodobit/sdk/framework';
import useSWR from 'swr';

function useItems(filters?: ItemFilters) {
  return useSWR(
    toSWRKey(queryKeys.items.list(filters)),
    () => api.items.list(filters)
  );
}

API Reference

Authentication

// Request OTP
await client.requestOTP({ email: '[email protected]', tenantId: 'optional' });

// Verify OTP and login
await client.verifyOTP({ email: '[email protected]', code: '123456' });

// Refresh token
await client.refreshToken();

// Logout
await client.logout({ allDevices: false });

// Get current user
const user = await client.getCurrentUser();

Tenants

// List tenants
const tenants = await client.getTenants({ page: 1, limit: 20 });

// Get specific tenant
const tenant = await client.getTenant('tenant-id');

// Create tenant
const newTenant = await client.createTenant({
  name: 'My Company',
  subscriptionPlan: 'pro'
});

// Update tenant
await client.updateTenant('tenant-id', { name: 'Updated Name' });

// Delete tenant
await client.deleteTenant('tenant-id');

Parties (Customers, Suppliers, Employees)

// Create person
const person = await client.createPerson({
  firstName: 'John',
  lastName: 'Doe',
  roles: ['customer'],
  addresses: [{
    addressType: 'billing',
    line1: '123 Main St',
    country: 'US',
    isPrimary: true
  }]
});

// Create organization
const org = await client.createOrganization({
  name: 'Acme Corp',
  roles: ['supplier'],
  contacts: [{
    contactType: 'email',
    contactValue: '[email protected]',
    isPrimary: true
  }]
});

// Get parties
const customers = await client.getCustomers();
const suppliers = await client.getSuppliers();
const employees = await client.getEmployeeParties();

Items

// List items
const items = await client.getItems({
  itemType: 'product',
  status: 'active',
  page: 1,
  limit: 50
});

// Get specific item
const item = await client.getItem('item-id');

// Create item
const newItem = await client.createItem({
  name: 'Widget Pro',
  itemType: 'product',
  code: 'WP-001'
});

// Search items
const searchResults = await client.searchItems('widget', {
  itemType: 'product'
});

Advanced Usage

With Validation

import { InterceptorManager, validationSchemas } from '@prodobit/sdk/validation';

const interceptorManager = new InterceptorManager({
  enabled: true,
  validateRequests: true,
  validateResponses: false,
  failOnValidationError: true
});

// Register validation schemas
interceptorManager.getValidationMiddleware()
  .registerRequestValidator('/api/v1/tenants', validationSchemas.tenant.create);

// Add to client (custom integration required)

With Custom Interceptors

import { builtInInterceptors } from '@prodobit/sdk/validation';

const interceptorManager = new InterceptorManager();

// Add logging
interceptorManager.addRequestInterceptor(
  builtInInterceptors.requestLogger({ logLevel: 'info' })
);

// Add retry logic
interceptorManager.addErrorInterceptor(
  builtInInterceptors.retryInterceptor({ maxRetries: 3 })
);

// Add auth headers
interceptorManager.addRequestInterceptor(
  builtInInterceptors.authHeaderInjector(() => client.getTokenInfo()?.accessToken || null)
);

Authentication State Management

import { AuthStateManager } from '@prodobit/sdk/framework';

const authManager = new AuthStateManager(client);

// Subscribe to auth state changes
const unsubscribe = authManager.subscribe((state) => {
  console.log('Auth state:', state);
  if (state.isAuthenticated) {
    console.log('User:', state.user);
  }
});

// Initialize from stored token
await authManager.initialize();

// Login with OTP
const result = await authManager.loginWithOTP('[email protected]');
if (result.success) {
  await authManager.verifyOTP('[email protected]', '123456');
}

// Cleanup
authManager.destroy();
unsubscribe();

Cache Management

The SDK provides intelligent caching strategies for different resource types:

import { cacheStrategies, resourceCacheStrategies } from '@prodobit/sdk/framework';

// Static data (locations, tenants) - 30 minutes
// Dynamic data (stocks, sales orders) - 30 seconds  
// Standard data (items, parties) - 5 minutes
// Real-time data - always fresh

const itemCacheSettings = cacheStrategies[resourceCacheStrategies.items]; // 'standard'
// Returns: { staleTime: 5 * 60 * 1000, cacheTime: 10 * 60 * 1000, ... }

Error Handling

import { ProdobitError } from '@prodobit/sdk';

try {
  await client.createTenant(invalidData);
} catch (error) {
  if (error instanceof ProdobitError) {
    console.log('Status:', error.status); // HTTP status code
    console.log('Code:', error.code); // Error code (e.g., 'VALIDATION_ERROR')
    console.log('Message:', error.message); // Human-readable message
    console.log('Details:', error.details); // Additional error details
    
    // Check error types
    if (error.isValidationError()) {
      console.log('Validation failed');
    } else if (error.isAuthError()) {
      console.log('Authentication required');
    } else if (error.isNetworkError()) {
      console.log('Network issue');
    }
  }
}

TypeScript Support

The SDK is built with TypeScript and provides comprehensive type definitions:

import type { 
  Tenant, 
  CreateTenantRequest, 
  Party, 
  ItemBase, 
  Response, 
  PaginatedResponse 
} from '@prodobit/sdk';

// All API responses are typed
const response: Response<Tenant[]> = await client.getTenants();
const tenant: Tenant = response.data[0];

// Request payloads are validated
const createRequest: CreateTenantRequest = {
  name: 'My Company', // ✓ Required
  subscriptionPlan: 'pro', // ✓ Valid enum value  
  // status: 'invalid' // ✗ TypeScript error
};

Contributing

See the main Prodobit repository for contributing guidelines.

License

MIT