didox 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -0,0 +1,128 @@
+# Changelog
+
+All notable changes to the Didox SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.3] - 2026-01-16
+
+### Added
+- **Product Classes (ИКПУ) Management**
+  - `getProductClassCodes()` - Get attached product class codes for current profile
+  - `searchProductClasses()` - Search available product classes with pagination
+  - `addProductClass()` - Add product class code to profile
+  - `removeProductClass()` - Remove product class code from profile
+  - `checkProductClassCode()` - Check product class code packages by TIN
+- **VAT & Taxpayer Information**
+  - `getVatRegStatus()` - Get VAT registration status by TIN or PINFL
+  - `getTaxpayerType()` - Get taxpayer type information
+  - Support for historical data queries with date parameters
+- **Warehouses Management**
+  - `getWarehouses()` - Get warehouses by TIN or PINFL
+- **Company Users & Permissions**
+  - `updateCompanyUsersPermissions()` - Update company users permissions with signed tokens
+  - Support for GNK (tax committee) and Didox internal roles
+- **Enhanced Profile Module**
+  - Modular architecture with sub-APIs for better organization
+  - Convenience methods for direct access to extended features
+- **Comprehensive Type Definitions**
+  - Full TypeScript support for all new APIs
+  - Enums for VAT status codes and role codes
+  - Detailed interface definitions for all request/response objects
+
+### Technical Improvements
+- Extended validation for TIN/PINFL formats
+- Enhanced error handling for new endpoint types
+- Maintained backward compatibility with existing APIs
+
+## [1.0.2] - 2026-01-16
+
+### Added
+
+- **Profile module** - Complete company profile management API
+- **Get current profile** - Retrieve detailed company information (`didox.profile.getProfile()`)
+- **Update profile** - Update company profile with comprehensive validation (`didox.profile.updateProfile()`)
+- **Profile operators** - Get operators associated with the profile (`didox.profile.getOperators()`)
+- **Utilities module** - Helper functions for company data operations
+- **Get branches by TIN** - Retrieve company branches by Tax ID (`didox.utilities.getBranchesByTin()`)
+
+### Technical Features
+
+- **Enhanced validation** - Support for TIN (9 digits), PINFL (14 digits), VAT rates, regions
+- **Comprehensive typing** - Full TypeScript support for all profile fields
+- **Operator management** - Access to integrated platform operators (Didox, Faktura, etc.)
+- **Branch queries** - Geographic and organizational branch information
+- **Field filtering** - Only expose documented API fields in public types
+
+### Validation Rules
+
+- **TIN validation** - Exactly 9 digits for company/director identification
+- **PINFL validation** - Exactly 14 digits for personal identification
+- **Notifications** - Only 0 (disabled) or 1 (enabled)
+- **Region ID** - Numeric regional identifiers
+- **VAT settings** - Number validation for VAT rates and excise flags
+
+### API Methods
+
+- `didox.profile.getProfile()` - Get comprehensive company profile
+- `didox.profile.updateProfile()` - Update company information
+- `didox.profile.getOperators()` - List profile operators
+- `didox.utilities.getBranchesByTin()` - Query branches by company TIN
+
+## [1.0.1] - 2026-01-16
+
+### Added
+
+- **Account module** - Complete account/profile management API
+- **Get current profile** - Retrieve authenticated user profile information (`didox.account.getProfile()`)
+- **Update profile** - Update user profile with validation (`didox.account.updateProfile()`)
+- **Input validation for profile update** - Strict validation for mobile, email, password, notifications
+- **Enhanced authorization headers** - Automatic Partner-Authorization header management
+- **TypeScript support for Account** - Full type definitions for profile operations
+
+### Technical Features
+
+- **Mobile validation** - Format 998XXXXXXXXX (12 digits)
+- **Email validation** - Standard email format validation
+- **Password validation** - Optional field, minimum 8 characters when provided
+- **Notifications validation** - Accepts only 0 (disabled) or 1 (enabled)
+- **Dual authentication** - Supports both user-key and Partner-Authorization headers
+
+### API Methods
+
+- `didox.account.getProfile()` - Get current user profile
+- `didox.account.updateProfile()` - Update user profile information
+
+## [1.0.0] - 2026-01-16
+
+### Added
+
+- **DidoxClient initialization** - Main SDK client with configuration management
+- **Auth module** - Complete authentication API implementation
+- **Legal entity login** - Authenticate legal entities with Tax ID and password
+- **Individual to company login** - Switch context to company using individual token
+- **Input validation** - Strict validation for all API parameters before requests
+- **Typed errors** - Custom error classes for different failure scenarios:
+  - `DidoxValidationError` - Input validation failures
+  - `DidoxAuthError` - Authentication failures (422 status)
+  - `DidoxApiError` - API error responses (4xx, 5xx)
+  - `DidoxNetworkError` - Network and timeout errors
+- **TypeScript support** - Full TypeScript definitions with strict typing
+- **Environment configuration** - Support for development and production environments
+- **Partner token authentication** - Secure API authorization using partner tokens
+- **Token management** - Automatic token handling for authenticated requests
+- **JSDoc documentation** - Complete IDE hints for all public methods
+- **ESM + CJS builds** - Universal module support for modern and legacy Node.js
+
+### Technical Features
+
+- **Node.js ≥ 18 support** - Modern Node.js runtime requirement
+- **Zero external dependencies** - Uses native fetch API for HTTP requests
+- **Modular architecture** - Clean separation of concerns across modules
+- **Production-ready code** - Enterprise-grade error handling and validation
+
+### API Methods
+
+- `didox.auth.loginLegalEntity()` - Legal entity authentication
+- `didox.auth.loginCompanyAsIndividual()` - Company context switching

package/README.md

@@ -292,6 +292,174 @@ try {
 }
 ```
 
+## Product Classes (ИКПУ)
+
+Manage product classification codes for your company profile.
+
+### Get Attached Product Classes
+
+Retrieve product classes currently attached to your profile:
+
+```typescript
+try {
+  const result = await didox.profile.getProductClassCodes();
+  
+  console.log('Total attached classes:', result.data.length);
+  
+  result.data.forEach(productClass => {
+    console.log(`Code: ${productClass.classCode}`);
+    console.log(`Name: ${productClass.className}`);
+    console.log(`Packages: ${productClass.packages.length} available`);
+    console.log('---');
+  });
+} catch (error) {
+  console.error('Failed to get product classes:', error.message);
+}
+```
+
+### Search Available Product Classes
+
+Search for product classes you can attach to your profile:
+
+```typescript
+try {
+  const result = await didox.profile.searchProductClasses({
+    search: 'фото',
+    lang: 'ru',
+    page: 1
+  });
+  
+  console.log(`Found ${result.total} classes (page ${result.current_page})`);
+  
+  result.data.forEach(productClass => {
+    console.log(`Code: ${productClass.classCode}`);
+    console.log(`Name: ${productClass.className_ru}`);
+    console.log(`Origin: ${productClass.origin.name}`);
+  });
+} catch (error) {
+  console.error('Failed to search product classes:', error.message);
+}
+```
+
+### Add/Remove Product Classes
+
+```typescript
+try {
+  // Add a product class
+  await didox.profile.addProductClass('08418001001013043');
+  console.log('Product class added successfully');
+  
+  // Remove a product class
+  await didox.profile.removeProductClass('08418001001013043');
+  console.log('Product class removed successfully');
+} catch (error) {
+  console.error('Failed to manage product class:', error.message);
+}
+```
+
+## VAT & Taxpayer Information
+
+Get VAT registration and taxpayer type information.
+
+### VAT Registration Status
+
+Check VAT registration status by TIN or PINFL:
+
+```typescript
+try {
+  const vatStatus = await didox.profile.getVatRegStatus('123456789');
+  
+  console.log(`VAT Registration Code: ${vatStatus.vatRegCode}`);
+  console.log(`VAT Status: ${vatStatus.vatRegStatus}`);
+  
+  // Status codes:
+  // 10 - Плательщик НДС
+  // 20 - Плательщик НДС+ (сертификат активный)
+  // 21 - Плательщик НДС+ (сертификат неактивный)
+  // 30 - Плательщик налога с оборота
+  // 50 - Индивидуальный предприниматель
+  // 60 - Физическое лицо
+} catch (error) {
+  console.error('Failed to get VAT status:', error.message);
+}
+```
+
+### Taxpayer Type
+
+Get taxpayer type information:
+
+```typescript
+try {
+  const taxpayerType = await didox.profile.getTaxpayerType(
+    '123456789', // TIN
+    'ru',        // Language
+    '17.01.2022' // Optional date
+  );
+  
+  console.log(`Code: ${taxpayerType.code}`);
+  console.log(`Name: ${taxpayerType.name}`);
+} catch (error) {
+  console.error('Failed to get taxpayer type:', error.message);
+}
+```
+
+## Warehouses
+
+Get warehouse information by TIN or PINFL.
+
+```typescript
+try {
+  const warehouses = await didox.profile.getWarehouses('123456789');
+  
+  console.log(`Found ${warehouses.length} warehouses`);
+  
+  warehouses.forEach(warehouse => {
+    console.log(`Warehouse #${warehouse.warehouseNumber}`);
+    console.log(`Name: ${warehouse.warehouseName}`);
+    console.log(`Address: ${warehouse.warehouseAddress}`);
+    console.log('---');
+  });
+} catch (error) {
+  console.error('Failed to get warehouses:', error.message);
+}
+```
+
+## Company Users & Permissions
+
+Manage company user permissions with signed tokens.
+
+```typescript
+try {
+  await didox.profile.updateCompanyUsersPermissions({
+    gnkpermissions: 'base64-signed-gnk-roles-token',
+    internalpermissions: 'base64-signed-didox-roles-token',
+    is_director: 1
+  });
+  
+  console.log('User permissions updated successfully');
+} catch (error) {
+  console.error('Failed to update permissions:', error.message);
+}
+```
+
+**Note**: This API requires externally signed tokens. The SDK does not generate signatures - you must prepare and sign the role JSONs externally before calling this method.
+
+### Role Codes Reference
+
+**GNK (Tax Committee) Roles:**
+- 11 - Отправка / отмена ЭСФ
+- 12 - Подтверждение / отклонение ЭСФ
+- 21 - Отправка / отмена доверенностей
+- 22 - Подтверждение / отклонение доверенностей
+- And more...
+
+**Didox Internal Roles:**
+- 191 - Отправка / отмена заказов
+- 192 - Подтверждение / отклонение заказов
+- 59 - Создание договоров
+- 199 - Создание заказов
+- And more...
+
 ## Error Handling
 
 The SDK provides specific error classes for different failure scenarios: