ocpi-types

v2.0.1

Published

8 months ago

TypeScript DTOs and enums for OCPI 2.2.1 specification.

0High
0Medium
0Low

niklam

ocpi ocpi-2.2.1 typescript dto enum

OCPI Types

TypeScript DTOs (Data Transfer Objects) and enums for the OCPI 2.2.1 (Open Charge Point Interface) specification. Perfect for building EV charging applications with type safety and validation.

✨ Features

🎯 Complete OCPI 2.2.1 coverage - All DTOs and enums from the specification
🛡️ Type-safe - Full TypeScript support with strict typing
✅ Validation ready - Built with class-validator decorators
🔄 Consistent serialization - Explicit @Expose() decorators on all fields
🏗️ Enhanced response system - Class-based response types for better instantiation
🏗️ NestJS compatible - Works seamlessly with NestJS applications
📚 Well documented - Comprehensive JSDoc comments
🧪 Thoroughly tested - Extensive test coverage
🚀 Tree-shakeable - Import only what you need

📦 Installation

npm install ocpi-types

Peer dependencies:

npm install class-validator class-transformer reflect-metadata

🚀 Quick Start

Important: Import reflect-metadata first!

import 'reflect-metadata';
import { validate } from 'class-validator';
import { plainToInstance } from 'class-transformer';
import { LocationDto, ConnectorType, Status } from 'ocpi-types/locations';

// Create and validate a location
const locationData = {
  country_code: 'DE',
  party_id: 'GEF',
  id: 'LOC001',
  publish: true,
  name: 'Charging Station Downtown',
  address: 'Main Street 1',
  city: 'Berlin',
  postal_code: '10115',
  country: 'DEU',
  time_zone: 'Europe/Berlin',
  coordinates: {
    latitude: '52.520008',
    longitude: '13.404954'
  },
  last_updated: '2023-12-07T10:30:00Z'
};

const location = plainToInstance(LocationDto, locationData);
const errors = await validate(location);

if (errors.length === 0) {
  console.log('✅ Valid OCPI location!');
} else {
  console.log('❌ Validation errors:', errors);
}

📋 Available Modules

🏢 Locations

import {
  LocationDto,
  EVSEDto,
  ConnectorDto,
  GeoLocationDto,
  BusinessDetailsDto,
  EnergyMixDto,
  EnergySourceDto,
  EnvironmentalImpactDto,
  AdditionalGeoLocationDto,
  StatusScheduleDto,
  RegularHoursDto,
  ImageDto,
  PublishTokenTypeDto,
  HoursDto,
  ExceptionalPeriodDto,
  ConnectorType,
  ConnectorFormat,
  Status,
  Capability,
  PowerType,
  EnergySourceCategory,
  Facility,
  EnvironmentalImpactCategory,
  ParkingType,
  ImageCategory,
  ParkingRestriction
} from 'ocpi-types/locations';

💰 Tariffs

import { 
  TariffDto, 
  TariffElementDto,
  PriceComponentDto,
  TariffRestrictionsDto,
  TariffType,
  TariffDimensionType,
  DayOfWeekEnum,
  ReservationRestrictionTypeEnum
} from 'ocpi-types/tariffs';

📊 Sessions & CDRs

// Sessions
import { 
  SessionDto,
  ChargingPreferencesDto,
  SessionStatus,
  ProfileType,
  ChargingPreferencesResponse
} from 'ocpi-types/sessions';

// CDRs
import { 
  CdrDto,
  ChargingPeriodDto,
  SignedValueDto,
  CdrLocationDto,
  SignedDataDto,
  CdrDimensionDto,
  CdrTokenDto,
  AuthMethod,
  CdrDimensionType
} from 'ocpi-types/cdrs';

🎫 Tokens

import { 
  TokenDto,
  AuthorizationInfoDto,
  LocationReferencesDto,
  EnergyContractDto,
  TokenType,
  AllowedType,
  WhitelistType
} from 'ocpi-types/tokens';

⚡ Commands

import { 
  StartSessionDto,
  StopSessionDto,
  ReserveNowDto,
  UnlockConnectorDto,
  CancelReservationDto,
  CommandResultDto,
  CommandResponseDto,
  CommandType,
  CommandResultType,
  CommandResponseType
} from 'ocpi-types/commands';

🔧 Charging Profiles

import { 
  ChargingProfileDto,
  ChargingProfilePeriodDto,
  ActiveChargingProfileDto,
  ActiveChargingProfileResultDto,
  ChargingProfileResponseDto,
  ChargingProfileResultDto,
  ClearProfileResultDto,
  SetChargingProfileDto,
  ChargingRateUnit,
  ChargingProfileResponseType,
  ChargingProfileResultType
} from 'ocpi-types/charging-profiles';

🌐 Versions & Hub Client Info

// Versions
import {
  EndpointDto,
  VersionNumber,
  ModuleId,
  InterfaceRole
} from 'ocpi-types/versions';

// Hub Client Info
import {
  ClientInfoDto,
  ConnectionStatus
} from 'ocpi-types/hubclientinfo';

🔑 Credentials

import {
  CredentialsDto,
  CredentialsRoleDto
} from 'ocpi-types/credentials';

🛠️ Common DTOs & Enums

// Common DTOs
import {
  DisplayTextDto,
  PriceDto
} from 'ocpi-types';

// Common Enums
import {
  Role
} from 'ocpi-types';

📤 OCPI Response System

// Response classes (v2.0.0+)
import {
  OcpiResponse,
  OcpiSingleResponse,
  OcpiListResponse,
  OcpiEmptyResponse,
  OcpiErrorResponse,
  OcpiResponseBuilder
} from 'ocpi-types';

// Create responses using the builder (recommended)
const successResponse = OcpiResponseBuilder.success(data, 'Operation successful');
const emptyResponse = OcpiResponseBuilder.successEmpty('No content');
const errorResponse = OcpiResponseBuilder.error(2001, 'Invalid parameters');

// Or instantiate classes directly
const customResponse = new OcpiResponse<LocationDto>();
customResponse.data = locationData;
customResponse.statusCode = 1000;
customResponse.timestamp = new Date().toISOString();

🎨 Custom Decorators

import {
  IsOcpiDateTime,
  IsOcpiCiString,
  IsTime
} from 'ocpi-types/decorators';

🎯 Usage Examples

NestJS Controller with OCPI Responses

import { Controller, Post, Body, Get, Param } from '@nestjs/common';
import { LocationDto } from 'ocpi-types/locations';
import { OcpiResponseBuilder, OcpiSingleResponse, OcpiListResponse } from 'ocpi-types';

@Controller('ocpi/2.2.1/locations')
export class LocationsController {
  @Post()
  async createLocation(@Body() locationDto: LocationDto): Promise<OcpiSingleResponse<LocationDto>> {
    try {
      const location = await this.locationsService.create(locationDto);
      return OcpiResponseBuilder.success(location, 'Location created successfully');
    } catch (error) {
      return OcpiResponseBuilder.error(2001, 'Failed to create location');
    }
  }

  @Get()
  async getLocations(): Promise<OcpiListResponse<LocationDto>> {
    const locations = await this.locationsService.findAll();
    return OcpiResponseBuilder.success(locations, 'Locations retrieved successfully');
  }
}

Manual Validation

import { validate } from 'class-validator';
import { plainToInstance } from 'class-transformer';
import { ConnectorDto, ConnectorType, ConnectorFormat, PowerType } from 'ocpi-types/locations';

const connectorData = {
  id: 'CONN001',
  standard: ConnectorType.IEC_62196_T2,
  format: ConnectorFormat.SOCKET,
  power_type: PowerType.AC_3_PHASE,
  max_voltage: 400,
  max_amperage: 32,
  last_updated: '2023-12-07T10:30:00Z'
};

const connector = plainToInstance(ConnectorDto, connectorData);
const errors = await validate(connector);

if (errors.length === 0) {
  console.log('Valid connector:', connector);
}

Working with Enums

import { Status, ConnectorType } from 'ocpi-types/locations';
import { TariffType } from 'ocpi-types/tariff';

// Type-safe enum usage
const connectorType: ConnectorType = ConnectorType.IEC_62196_T2;
const status: Status = Status.AVAILABLE;
const tariffType: TariffType = TariffType.REGULAR;

// Get all available values
console.log('Available connector types:', Object.values(ConnectorType));

🏗️ Custom Decorators

This library includes custom validation decorators for OCPI-specific formats:

@IsOcpiDateTime()

Validates OCPI datetime format (ISO 8601 with timezone).

import { IsOcpiDateTime } from 'ocpi-types/decorators';

class MyDto {
  @IsOcpiDateTime()
  lastUpdated: string; // Must be: 2023-12-07T10:30:00Z
}

@IsOcpiCiString()

Validates OCPI case-insensitive string format.

import { IsOcpiCiString } from 'ocpi-types/decorators';

class MyDto {
  @IsOcpiCiString()
  id: string; // Alphanumeric, no spaces or special chars
}

@IsTime()

Validates 24-hour time format (HH:MM).

import { IsTime } from 'ocpi-types/decorators';

class MyDto {
  @IsTime()
  startTime: string; // Must be: 09:30, 23:59, etc.
}

Consistent Serialization (v2.0.0+)

import { plainToInstance, instanceToPlain } from 'class-transformer';
import { LocationDto } from 'ocpi-types/locations';

// All DTOs now have explicit @Expose() decorators
// Serialization is consistent regardless of configuration
const locationData = {
  country_code: 'DE',
  party_id: 'GEF',
  id: 'LOC001',
  // ... other fields
};

const location = plainToInstance(LocationDto, locationData);
const serialized = instanceToPlain(location);

// Always produces consistent snake_case output:
// {
//   "country_code": "DE",
//   "party_id": "GEF",
//   "id": "LOC001",
//   ...
// }

🔄 Migration from v1.x to v2.0.0

Breaking Changes

OcpiResponse is now a class (was interface):

// ❌ v1.x - Interface usage
const response: OcpiResponse<Data> = {
  data: myData,
  status_code: 1000,
  timestamp: new Date().toISOString()
};

// ✅ v2.0.0 - Class usage (recommended)
const response = OcpiResponseBuilder.success(myData);

// ✅ v2.0.0 - Direct instantiation
const response = new OcpiResponse<Data>();
response.data = myData;
response.statusCode = 1000;
response.timestamp = new Date().toISOString();

Response types are now classes (were type aliases):

// ❌ v1.x - Plain object
const errorResponse: OcpiErrorResponse = {
  status_code: 2001,
  status_message: 'Invalid data',
  timestamp: new Date().toISOString()
};

// ✅ v2.0.0 - Class instantiation
const errorResponse = new OcpiErrorResponse();
// OR (recommended)
const errorResponse = OcpiResponseBuilder.error(2001, 'Invalid data');

No Action Required For:

✅ DTO usage - All DTOs work exactly the same
✅ Validation - All validation decorators unchanged
✅ Serialization - Output format is identical (now more consistent)
✅ Imports - All import paths remain the same

🔧 Configuration

Jest Testing Setup

Add to your jest.config.js or package.json:

{
  "jest": {
    "setupFiles": ["reflect-metadata/Reflect"]
  }
}

TypeScript Configuration

Ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "nodenext",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

📖 OCPI Specification

This library implements the OCPI 2.2.1 specification. For detailed information about the protocol, visit:

📄 Official OCPI Documentation
🔗 OCPI 2.2.1 Specification

Supported OCPI Modules

| Module | Status | Description | |--------|--------|-------------| | ✅ Locations | Complete | Charge point locations and their details | | ✅ Sessions | Complete | Charging session information | | ✅ CDRs | Complete | Charge detail records | | ✅ Tariffs | Complete | Pricing information | | ✅ Tokens | Complete | Authentication tokens | | ✅ Commands | Complete | Remote commands (start/stop/reserve) | | ✅ Charging Profiles | Complete | Smart charging profiles | | ✅ Hub Client Info | Complete | Hub connection information | | ✅ Credentials | Complete | Platform credentials | | ✅ Versions | Complete | Supported OCPI versions |

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/niklam/ocpi-types.git
cd ocpi-types

# Install dependencies
npm install

# Run tests
npm test

# Build the library
npm run build

# Run linting
npm run lint

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

🆘 Support

📖 Documentation
🐛 Report Issues

📜 License

This project is licensed under the MIT License — see the LICENSE file for details.

🙏 Acknowledgments

OCPI Forum for the excellent specification
class-validator for validation framework
class-transformer for transformation utilities

Made with ❤️ for the EV charging community

If this library helps your project, please consider giving it a ⭐ on GitHub!