didox 0.0.6 → 1.0.2

package/README.md

@@ -1,70 +1,407 @@
-# didox
+# Didox SDK for Node.js
 
 [![npm version](https://badge.fury.io/js/didox.svg)](https://badge.fury.io/js/didox)
-[![The Beta Company](https://img.shields.io/badge/powered%20by-The%20Beta%20Company-blue)](https://thebetacompany.uz/projects/didox-npm-module)
----
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org)
 
-**didox** is a Node.js module developed to streamline the integration process for developers and their applications with the Electronic Document Management System (EDM) on the [www.didox.uz](https://didox.uz) platform. With this module, you can simplify interactions with Didox, send and receive electronic documents, manage your account, and more.
+A TypeScript SDK for integrating with **Didox**, an electronic document management (EDO) platform in Uzbekistan that enables legally significant exchange of electronic documents between companies.
 
-## Installation
+## What is Didox?
+
+Didox is an electronic document management platform in the Republic of Uzbekistan that facilitates legally significant electronic document exchange between companies. It provides:
 
-To install the **didox** module, use the following npm command:
+- Secure electronic document signing
+- Legal compliance with Uzbekistan EDO regulations
+- Company-to-company document workflows
+- Digital signature verification
+
+## Installation
 
-### NPM
 ```bash
 npm install didox
 ```
 
-### Yarn
 ```bash
 yarn add didox
 ```
 
-## Environment Variables
+```bash
+pnpm add didox
+```
 
-Before using the didox module, make sure to set the following environment variables in your project's .env file:
+## Quick Start
 
-`TBC_DIDOX_LOGIN`: Your didox login or username. 
+### 1. Initialize the Client
 
-`TBC_DIDOX_PASSWORD`: Your didox password or API key secret.
+```typescript
+import { DidoxClient } from 'didox';
 
-`TBC_DIDOX_PARTNER_TOKEN`: Your didox partner token ( given by didox.uz ).
+const didox = new DidoxClient({
+  partnerToken: 'your-partner-token',
+  environment: 'development', // or 'production'
+  timeout: 10000 // optional, defaults to 10 seconds
+});
+```
 
-These environment variables are required for authentication when using the module. Be sure to keep them secure and do not expose them in your code.
+### 2. Legal Entity Authentication
 
-## Usage
+```typescript
+try {
+  const result = await didox.auth.loginLegalEntity({
+    taxId: '123456789',     // exactly 9 digits
+    password: 'yourPassword', // minimum 8 characters
+    locale: 'ru'            // 'ru' or 'uz', defaults to 'ru'
+  });
+  
+  console.log('Access token:', result.token);
+  console.log('Related companies:', result.related_companies);
+  
+  // Token is automatically stored in the client for subsequent requests
+} catch (error) {
+  console.error('Login failed:', error.message);
+}
+```
 
-```javascript
-const { Account } = require('didox');
+### 3. Individual to Company Login
 
-async function getAccountInfo ( ) {
-    const accountInfo = await Account.getInfo();
-    // Here is your code...
+```typescript
+try {
+  const result = await didox.auth.loginCompanyAsIndividual({
+    companyTaxId: '987654321',
+    userToken: 'individual-user-token', // from previous login
+    locale: 'uz'
+  });
+  
+  console.log('Company access token:', result.token);
+  console.log('User permissions:', result.permissions);
+} catch (error) {
+  console.error('Company login failed:', error.message);
 }
-// Here is your code...
 ```
 
-## Documentation
-For detailed usage instructions and API documentation, please refer to the [documentation](https://docs.thebetacompany.uz/tbc-didox-npm).
+## Configuration
+
+### Partner Token
+
+The Partner Token is required to authorize API requests. To obtain a Partner Token:
+
+1. Contact a Didox representative
+2. Provide your company information and use case
+3. Receive your unique Partner Token for API access
+
+### Environment URLs
+
+- **Development**: `https://stage.goodsign.biz/`
+- **Production**: `https://api-partners.didox.uz/`
+
+### Client Options
+
+```typescript
+interface DidoxConfig {
+  partnerToken: string;                    // Required: Your Partner Token
+  environment: 'development' | 'production'; // Required: Environment
+  timeout?: number;                        // Optional: Request timeout in ms (default: 10000)
+}
+```
+
+## Authentication
+
+### Legal Entity Login
+
+Authenticate a legal entity using Tax ID and password:
+
+```typescript
+const result = await didox.auth.loginLegalEntity({
+  taxId: '123456789',      // exactly 9 digits
+  password: 'securePass123', // minimum 8 characters  
+  locale: 'ru'             // optional: 'ru' | 'uz'
+});
+
+// Access token (UUID, valid for 360 minutes)
+console.log(result.token);
+
+// Related companies (if any)
+if (result.related_companies) {
+  result.related_companies.forEach(company => {
+    console.log(`${company.name} (${company.tin})`);
+    console.log('Permissions:', company.permissions);
+  });
+}
+```
+
+### Individual to Company Login
+
+Switch context to a specific company using an individual's token:
+
+```typescript
+const result = await didox.auth.loginCompanyAsIndividual({
+  companyTaxId: '987654321',
+  userToken: 'user-access-token', 
+  locale: 'uz'
+});
+
+console.log('Company token:', result.token);
+console.log('User roles in company:', result.permissions.roles);
+```
+
+## Account / Profile
+
+### Get Current Profile
+
+Retrieve the profile information for the currently authenticated user:
+
+```typescript
+try {
+  const profile = await didox.account.getProfile();
+  
+  console.log('Mobile:', profile.mobile);           // 998XXXXXXXXX
+  console.log('Email:', profile.email);             // user@example.com
+  console.log('Notifications:', profile.notifications); // 0 or 1
+  console.log('Messengers:', profile.messengers);   // ['telegram', 'viber']
+} catch (error) {
+  if (error instanceof DidoxAuthError) {
+    console.error('Authentication required:', error.message);
+  }
+}
+```
+
+### Update Profile
+
+Update the current user's profile information:
+
+```typescript
+try {
+  const updatedProfile = await didox.account.updateProfile({
+    mobile: '998901234567',        // format: 998XXXXXXXXX
+    email: 'newemail@example.com', // valid email
+    password: 'newPassword123',    // optional, min 8 chars
+    notifications: 1               // 1 = enabled, 0 = disabled
+  });
+  
+  console.log('Profile updated successfully');
+  console.log('New mobile:', updatedProfile.mobile);
+  console.log('New email:', updatedProfile.email);
+  console.log('Notifications:', updatedProfile.notifications);
+} catch (error) {
+  if (error instanceof DidoxValidationError) {
+    console.error('Validation error:', error.message);
+    console.error('Field:', error.field);
+  }
+}
+```
+
+## Profile
+
+The Profile module provides access to detailed company profile information and management capabilities.
 
+### Get Current Profile
 
-# Releases
-### v0.0.5
-- ***Updated*** [Documents](https://api-docs.didox.uz/ru/integrators-documents) controller
-    - Create document now can get AuthData - Login and Password
+Retrieve comprehensive company profile data:
 
-### v0.0.2
-- ***Updated*** [Documents](https://api-docs.didox.uz/ru/integrators-documents) controller
-    - Get documents count
-    - Get document information by ID
-    - Get document privileges ( Льготы ) by ID
-    - Create document
+```typescript
+try {
+  const profile = await didox.profile.getProfile();
+  
+  console.log('Company:', profile.fullName);        // Full company name
+  console.log('TIN:', profile.tin);                 // Tax ID
+  console.log('Balance:', profile.balance);         // Account balance
+  console.log('Director:', profile.director);       // Director name
+  console.log('Address:', profile.address);         // Company address
+  console.log('VAT Status:', profile.VATRegStatus); // VAT registration status
+  console.log('Messengers:', profile.messengers);   // Connected messengers
+} catch (error) {
+  if (error instanceof DidoxAuthError) {
+    console.error('Authentication required:', error.message);
+  }
+}
+```
+
+### Update Profile
+
+Update company profile information with validation:
+
+```typescript
+try {
+  const updatedProfile = await didox.profile.updateProfile({
+    phone: '998901234567',
+    email: 'company@example.com',
+    notifications: 1,              // Enable notifications
+    regionId: 26,                  // Tashkent region
+    directorTin: '123456789',      // Director's TIN (9 digits)
+    address: 'New company address',
+    vatRate: 15                    // VAT rate percentage
+  });
+  
+  console.log('Profile updated successfully');
+  console.log('Updated company:', updatedProfile.name);
+} catch (error) {
+  if (error instanceof DidoxValidationError) {
+    console.error('Validation error:', error.message);
+    console.error('Field:', error.field);
+  }
+}
+```
+
+### Get Profile Operators
+
+Retrieve operators associated with the company:
+
+```typescript
+try {
+  const operators = await didox.profile.getOperators();
+  
+  Object.entries(operators).forEach(([id, name]) => {
+    console.log(`Operator ${id}: ${name}`);
+  });
+  
+  // Example output:
+  // Operator 202530465: soliqservis.uz
+  // Operator 302563857: Faktura.uz
+  // Operator 302936161: Didox.uz
+} catch (error) {
+  console.error('Failed to get operators:', error.message);
+}
+```
+
+## Utilities
+
+The Utilities module provides helper functions for working with company data and branches.
+
+### Get Branches by TIN
+
+Retrieve branch information for a specific company:
+
+```typescript
+try {
+  const branches = await didox.utilities.getBranchesByTin({
+    tin: '123456789'  // Company TIN (9 digits)
+  });
+  
+  branches.forEach(branch => {
+    console.log(`Branch: ${branch.branchName}`);
+    console.log(`Location: ${branch.address}`);
+    console.log(`Director: ${branch.directorName}`);
+    console.log(`Status: ${branch.isDeleted ? 'Deleted' : 'Active'}`);
+    console.log(`Coordinates: ${branch.latitude}, ${branch.longitude}`);
+    console.log('---');
+  });
+} catch (error) {
+  if (error instanceof DidoxValidationError) {
+    console.error('Invalid TIN format:', error.message);
+  }
+}
+```
+
+## Error Handling
+
+The SDK provides specific error classes for different failure scenarios:
+
+```typescript
+import {
+  DidoxValidationError,
+  DidoxAuthError, 
+  DidoxApiError,
+  DidoxNetworkError
+} from 'didox';
+
+try {
+  const result = await didox.auth.loginLegalEntity({
+    taxId: '123456789',
+    password: 'mypassword'
+  });
+} catch (error) {
+  if (error instanceof DidoxValidationError) {
+    // Input validation failed
+    console.error('Validation error:', error.message);
+    console.error('Field:', error.field);
+    
+  } else if (error instanceof DidoxAuthError) {
+    // Authentication failed (wrong credentials, etc.)
+    console.error('Auth error:', error.message);
+    console.error('Status code:', error.statusCode);
+    
+  } else if (error instanceof DidoxApiError) {
+    // API returned an error response
+    console.error('API error:', error.message);
+    console.error('Status:', error.statusCode);
+    console.error('Response:', error.response);
+    
+  } else if (error instanceof DidoxNetworkError) {
+    // Network/connectivity issues
+    console.error('Network error:', error.message);
+    console.error('Cause:', error.cause);
+  }
+}
+```
+
+### Error Types
+
+| Error Class | When It Occurs | Properties |
+|-------------|----------------|------------|
+| `DidoxValidationError` | Invalid input parameters | `field`, `message` |
+| `DidoxAuthError` | Authentication failures (422) | `statusCode`, `message` |
+| `DidoxApiError` | API errors (4xx, 5xx) | `statusCode`, `response`, `message` |
+| `DidoxNetworkError` | Network/timeout issues | `cause`, `message` |
+
+## TypeScript Support
+
+The SDK is built with TypeScript and provides full type definitions:
+
+```typescript
+import type {
+  DidoxConfig,
+  LegalEntityLoginRequest,
+  LegalEntityLoginResponse,
+  CompanyLoginRequest,
+  CompanyLoginResponse,
+  RelatedCompany,
+  UserPermissions,
+  DidoxLocale,
+  AccountProfile,
+  UpdateProfileRequest,
+  UpdateProfileResponse,
+  CompanyProfile,
+  ProfileUpdateRequest,
+  ProfileUpdateResponse,
+  ProfileOperators,
+  CompanyBranch,
+  GetBranchesByTinRequest
+} from 'didox';
+
+// Fully typed request
+const request: LegalEntityLoginRequest = {
+  taxId: '123456789',
+  password: 'securePassword',
+  locale: 'ru'
+};
+
+// Fully typed response
+const response: LegalEntityLoginResponse = await didox.auth.loginLegalEntity(request);
+```
+
+## Requirements
+
+- **Node.js**: ≥ 18.0.0
+- **TypeScript**: ≥ 5.0 (for development)
+
+## Versioning
+
+This package follows [Semantic Versioning](https://semver.org/):
+
+- **1.x.0**: New features, backward compatible
+- **1.x.y**: Bug fixes and patches
+- **No breaking changes** in 1.x releases
+
+## License
+
+MIT
+
+## Support
+
+For API documentation and support:
+- [Official Didox API Documentation](https://api-docs.didox.uz/ru/home)
+- [GitHub Issues](https://github.com/mirzaevoff/didox/issues)
+
+---
 
-### v0.0.1
-- ***Added*** support for [Account](https://api-docs.didox.uz/ru/integrators-account) controller
-    - Get account information
-    - Get account status ( own or by TIN )
-- ***Added*** support for [Profile](https://api-docs.didox.uz/ru/integrators-profile) controller
-    - Get profile information
-- ***Added*** support for [Documents](https://api-docs.didox.uz/ru/integrators-documents) controller
-    - Get documents list
+**Note**: This is an unofficial SDK. For official support, contact Didox directly.