order3000 Node.js SDK

A TypeScript-first Node.js SDK for integrating with the order3000 restaurant management platform. This SDK provides a simple, type-safe interface for managing orders, reservations, and other restaurant operations through the order3000 API.

Overview

order3000 is a comprehensive restaurant management platform that handles orders, reservations, customer management, and more. This SDK allows external applications and websites to integrate seamlessly with order3000 through a clean, promise-based API.

Key Features

• 🔐 OAuth2 Authentication - Secure client credentials flow with automatic token management
• 🏢 Multi-Tenant Support - Built for multi-restaurant/tenant operations
• 📝 TypeScript Support - Full TypeScript support with auto-generated types from OpenAPI spec
• 🔄 Auto Token Refresh - Automatic token renewal with 5-minute buffer before expiration
• 🎯 Type-Safe API - OpenAPI-generated types ensure type safety across all operations
• ⚡ Modern Architecture - Built with ES modules and CommonJS dual support

Installation

npm install order3000
# or
yarn add order3000
# or
pnpm add order3000

Quick Start

import { Order3000Client } from 'order3000'

// Initialize the client
const client = new Order3000Client({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  tenantId: 'your-tenant-id', // Optional - will use default from token if not provided
  baseUrl: 'https://api.order3000.com', // Optional - defaults to production
})

// Place an order
const order = await client.orders.place({
  tenantId: 'restaurant-123',
  basketId: 'basket-456',
  status: 'PENDING',
  paymentMethod: 'CARD',
  taxAmount: '2.50',
  totalAmount: '25.00',
  currency: 'USD',
  orderedBy: '[email protected]',
})

console.log('Order placed:', order.id)

Architecture

Authentication Flow

The SDK uses OAuth2 client credentials flow for authentication:

1. Initial Authentication: On first use, the SDK requests an access token using your client credentials
2. Token Storage: The access token is stored in memory with its expiration time
3. Automatic Refresh: Tokens are automatically refreshed 5 minutes before expiration
4. Tenant Resolution: If no tenant ID is provided, the SDK extracts the default tenant from the JWT token

Project Structure

order3000-nodejs/
├── src/
│   ├── client.ts           # Main client class and initialization
│   ├── token-manager.ts    # OAuth2 token management and refresh logic
│   ├── resources/
│   │   ├── index.ts        # Base resource class for API calls
│   │   └── orders.ts       # Orders resource implementation
│   └── types/
│       ├── index.ts        # Type exports
│       └── generated.d.ts  # Auto-generated types from OpenAPI spec
├── scripts/
│   ├── dev.sh             # Development script with Vault integration
│   └── vaultcar.sh        # HashiCorp Vault integration for secrets
└── package.json

Configuration

Client Options

interface Order3000ClientConfig {
  clientId: string // OAuth2 client ID (required)
  clientSecret: string // OAuth2 client secret (required)
  tenantId?: string // Specific tenant ID (optional)
  baseUrl?: string // Base URL for API requests (default: https://order3000.com/api)
  tokenUrl?: string // OAuth2 token endpoint (default: ${baseUrl}/auth/token)
}

Environment Variables

For development, you can use environment variables:

ORDER3000_CLIENT_ID=your-client-id
ORDER3000_CLIENT_SECRET=your-client-secret
ORDER3000_BASE_URL=https://api.order3000.com

API Documentation

For complete API documentation including all available endpoints, request/response schemas, and interactive examples, visit:

• Development: http://localhost:3000/developers/reference
• Staging: https://order3000.kolaveri.co/developers/reference
• Production: https://order3000.com/developers/reference

The API documentation is powered by Scalar and provides a comprehensive view of all available endpoints, schemas, and integration examples.

SDK Development Workflow

Adding New API Endpoints

When new endpoints are added or modified in the order3000 platform, follow this workflow to update the SDK:

1. Define API Contracts: Create or update TypeScript contracts that define the API structure

   • Add/modify contracts in /apps/order3000/src/app/api/openapi/contracts/
   • Use @ts-rest/core to define type-safe contracts
   • Export contracts from /apps/order3000/src/app/api/openapi/contract.ts
   • Generate OpenAPI spec to preview changes: npx nx run order3000:generate-openapi
   • View updated docs at http://localhost:3000/developers/reference

2. Implement API Endpoints: Create the actual endpoint logic in the order3000 application

   • Implement handlers in /apps/order3000/src/app/api/ following the contract definitions
   • Ensure endpoints match the contracts exactly

3. Update SDK Resources: Integrate the new endpoints into the SDK

   • Create or update resource classes in /apps/order3000-nodejs/src/resources/
   • Follow the existing pattern extending from BaseResource
   • Export new resources from the main Order3000Client class
   • Note: Type generation (npm run build:types) is handled automatically by CI/CD

4. Create Changeset: Document the changes

   pnpm changeset

   • Select order3000 package
   • Choose version bump type (patch/minor/major)
   • Describe the new endpoints or changes added

5. CI/CD Pipeline: The automated pipeline handles the rest

   • Generates types from OpenAPI spec automatically
   • Builds the SDK package with pkgroll
   • Runs tests and type checking
   • Publishes to npm registry as order3000 package
   • Updates version numbers based on changeset

Local Development

# Generate types from OpenAPI spec
npm run build:types

# Build the package locally
npm run build

# Test SDK in development mode
npm run dev

Development with Vault

The SDK includes HashiCorp Vault integration for secure credential management:

# Run with Vault integration
npm run dev

Credentials are fetched from:

• secret/kolaveri/thamarai/ORDER3000_CLIENT_ID
• secret/kolaveri/thamarai/ORDER3000_CLIENT_SECRET
• secret/kolaveri/thamarai/ORDER3000_BASE_URL

Security Considerations

1. Never commit credentials - Always use environment variables or secret management systems
2. Token Security - Access tokens are stored in memory only, never persisted to disk
3. HTTPS Only - All API calls are made over HTTPS
4. Automatic Token Rotation - Tokens are refreshed automatically before expiration

Error Handling

try {
  const order = await client.orders.place({
    // ... order details
  })
} catch (error) {
  if (error.response?.statusCode === 401) {
    console.error('Authentication failed - check credentials')
  } else if (error.response?.statusCode === 400) {
    console.error('Invalid order data:', error.response.body)
  } else {
    console.error('Unexpected error:', error)
  }
}

Platform Integration

Multi-Tenant Architecture

order3000 supports multi-tenant operations where each restaurant or location is a separate tenant:

• Automatic Tenant Resolution: If no tenant ID is provided, the SDK uses the default tenant from the authentication token
• Explicit Tenant Selection: You can specify a tenant ID in the client configuration or per-request
• Tenant Isolation: All operations are scoped to the specified tenant

Related Components

The order3000 platform includes:

• Reservations System: Complete table reservation management with flexible contact preferences
• Customer Management: Customer profiles with order history and preferences
• Order Management: Full order lifecycle from placement to fulfillment
• Payment Integration: Support for multiple payment methods

Roadmap

Planned features for future releases:

• [ ] Reservations API support
• [ ] Customer management endpoints
• [ ] Webhook support for real-time updates
• [ ] Batch operations
• [ ] Analytics and reporting APIs
• [ ] Menu management
• [ ] Table management

Contributing

This SDK is part of the Kolaveri monorepo. Development follows the monorepo conventions:

1. Use CVA for styling in library packages
2. Follow TypeScript strict mode
3. Run linting before commits: npx nx lint order3000-nodejs
4. Generate types from OpenAPI spec when API changes

License

Part of the Kolaveri platform - see root repository for license information.

Support

For issues, questions, or feature requests related to this SDK, please contact the order3000 development team or open an issue in the main repository.