@deliverart/sdk-js-company 2.1.49 → 2.1.51

package/README.md

@@ -0,0 +1,516 @@
+# @deliverart/sdk-js-company
+
+Company management package for the DeliverArt JavaScript SDK.
+
+## Installation
+
+```bash
+npm install @deliverart/sdk-js-company @deliverart/sdk-js-core
+# or
+pnpm add @deliverart/sdk-js-company @deliverart/sdk-js-core
+# or
+yarn add @deliverart/sdk-js-company @deliverart/sdk-js-core
+```
+
+## Exported Types
+
+### Models
+
+#### Company
+```typescript
+interface Company {
+  id: string
+  businessName: string
+  vat: string
+  taxCode: string | null
+  operationalAddress: Address
+  createdAt: string
+  updatedAt: string
+}
+```
+Basic company information.
+
+**Properties:**
+- `id: string` - Unique company identifier
+- `businessName: string` - Company business name (required)
+- `vat: string` - VAT number (required)
+- `taxCode: string | null` - Tax code (optional)
+- `operationalAddress: Address` - Operational address (required)
+- `createdAt: string` - Creation timestamp (ISO 8601)
+- `updatedAt: string` - Last update timestamp (ISO 8601)
+
+#### CompanyDetails
+```typescript
+interface CompanyDetails extends Company {
+  billingAddress: Address
+  billingData: BillingData
+  adminBy: string
+}
+```
+Extended company information with billing details.
+
+**Additional Properties:**
+- `billingAddress: Address` - Billing address (required)
+- `billingData: BillingData` - Billing information (required)
+- `adminBy: string` - User IRI who administers the company (required)
+
+#### CompaniesQueryParams
+```typescript
+interface CompaniesQueryParams {
+  businessName?: string
+  vat?: string
+  taxCode?: string
+  'billingAddress.city'?: string
+  'billingAddress.postalCode'?: string
+  'operationalAddress.city'?: string
+  'operationalAddress.postalCode'?: string
+  'order[businessName]'?: 'asc' | 'desc'
+  'order[createdAt]'?: 'asc' | 'desc'
+  'order[updatedAt]'?: 'asc' | 'desc'
+  page?: number
+}
+```
+Query parameters for filtering and sorting companies.
+
+**Filter Parameters:**
+- `businessName?: string` - Filter by business name (partial match)
+- `vat?: string` - Filter by VAT number (exact match)
+- `taxCode?: string` - Filter by tax code (exact match)
+- `billingAddress.city?: string` - Filter by billing city
+- `billingAddress.postalCode?: string` - Filter by billing postal code
+- `operationalAddress.city?: string` - Filter by operational city
+- `operationalAddress.postalCode?: string` - Filter by operational postal code
+
+**Sort Parameters:**
+- `order[businessName]?: 'asc' | 'desc'` - Sort by business name
+- `order[createdAt]?: 'asc' | 'desc'` - Sort by creation date
+- `order[updatedAt]?: 'asc' | 'desc'` - Sort by update date
+
+**Pagination:**
+- `page?: number` - Page number (default: 1)
+
+### IRI Types
+
+#### CompanyIri
+```typescript
+type CompanyIri = string
+```
+Company IRI type (format: `/companies/:id`)
+
+#### CompanyNullableIri
+```typescript
+type CompanyNullableIri = string | null
+```
+Nullable company IRI type
+
+## Available Requests
+
+### CreateCompany
+
+Create a new company.
+
+**Class:** `CreateCompany`
+
+**Input Schema:**
+```typescript
+{
+  businessName: string        // Required, min 1 char
+  vat: string                 // Required
+  taxCode?: string | null     // Optional
+  billingAddress: {           // Required
+    street: string
+    city: string
+    postalCode: string
+    country: string
+    state?: string
+    province?: string
+  }
+  operationalAddress: {       // Required
+    street: string
+    city: string
+    postalCode: string
+    country: string
+    state?: string
+    province?: string
+  }
+  billingData: {              // Required
+    email: string
+    pec?: string
+    sdi?: string
+  }
+  adminBy: string             // Required, User IRI (e.g., '/users/123')
+}
+```
+
+**Response:** `CompanyDetails`
+
+**Example:**
+```typescript
+import { CreateCompany } from '@deliverart/sdk-js-company';
+
+const company = await sdk.call(new CreateCompany({
+  businessName: 'Acme Corporation',
+  vat: 'IT12345678901',
+  taxCode: 'ACME1234567890',
+  billingAddress: {
+    street: 'Via Roma 1',
+    city: 'Milano',
+    postalCode: '20100',
+    country: 'IT'
+  },
+  operationalAddress: {
+    street: 'Via Roma 1',
+    city: 'Milano',
+    postalCode: '20100',
+    country: 'IT'
+  },
+  billingData: {
+    email: 'billing@acme.com',
+    pec: 'acme@pec.it'
+  },
+  adminBy: '/users/123'
+}));
+```
+
+**Validation:**
+- `businessName`: Required, minimum 1 character
+- `vat`: Required
+- `billingAddress`: Required, all address fields validated
+- `operationalAddress`: Required, all address fields validated
+- `billingData`: Required, email must be valid
+- `adminBy`: Required, must be a valid User IRI
+
+---
+
+### GetCompanies
+
+Get a paginated list of companies with optional filters.
+
+**Class:** `GetCompanies`
+
+**Constructor:**
+```typescript
+new GetCompanies(options?: { query?: CompaniesQueryParams })
+```
+
+**Query Parameters:** See `CompaniesQueryParams` above
+
+**Response:** `Paginated<Company>`
+
+**Example:**
+```typescript
+import { GetCompanies } from '@deliverart/sdk-js-company';
+
+// Get all companies
+const companies = await sdk.call(new GetCompanies());
+
+// Get companies with filters
+const filtered = await sdk.call(new GetCompanies({
+  query: {
+    businessName: 'Acme',
+    'operationalAddress.city': 'Milano',
+    'order[createdAt]': 'desc',
+    page: 1
+  }
+}));
+
+// Access pagination info
+console.log(filtered.pagination.totalItems);
+console.log(filtered.pagination.currentPage);
+console.log(filtered.pagination.itemsPerPage);
+
+// Access data
+filtered.data.forEach(company => {
+  console.log(company.businessName);
+});
+```
+
+**Validation:**
+- `page`: Optional, must be a positive number
+- All filter values are optional
+
+---
+
+### GetCompanyDetails
+
+Get detailed information about a specific company.
+
+**Class:** `GetCompanyDetails`
+
+**Constructor:**
+```typescript
+new GetCompanyDetails(companyId: string)
+```
+
+**Parameters:**
+- `companyId: string` - Company ID (required)
+
+**Response:** `CompanyDetails`
+
+**Example:**
+```typescript
+import { GetCompanyDetails } from '@deliverart/sdk-js-company';
+
+const company = await sdk.call(new GetCompanyDetails('company-123'));
+
+console.log(company.businessName);
+console.log(company.billingAddress);
+console.log(company.billingData);
+```
+
+**Validation:**
+- `companyId`: Required, must be a non-empty string
+
+---
+
+### GetUserCompanies
+
+Get companies administered by a specific user.
+
+**Class:** `GetUserCompanies`
+
+**Constructor:**
+```typescript
+new GetUserCompanies(userId: string)
+```
+
+**Parameters:**
+- `userId: string` - User ID (required)
+
+**Response:** `Company[]`
+
+**Example:**
+```typescript
+import { GetUserCompanies } from '@deliverart/sdk-js-company';
+
+const companies = await sdk.call(new GetUserCompanies('user-123'));
+
+companies.forEach(company => {
+  console.log(company.businessName);
+});
+```
+
+**Validation:**
+- `userId`: Required, must be a non-empty string
+
+---
+
+### UpdateCompany
+
+Update an existing company (partial update).
+
+**Class:** `UpdateCompany`
+
+**Constructor:**
+```typescript
+new UpdateCompany(companyId: string, input: Partial<CompanyInput>)
+```
+
+**Parameters:**
+- `companyId: string` - Company ID (required)
+- `input: Partial<CompanyInput>` - Fields to update (all optional)
+
+**Input Schema:**
+```typescript
+{
+  businessName?: string
+  vat?: string
+  taxCode?: string | null
+  billingAddress?: {
+    street: string
+    city: string
+    postalCode: string
+    country: string
+    state?: string
+    province?: string
+  }
+  operationalAddress?: {
+    street: string
+    city: string
+    postalCode: string
+    country: string
+    state?: string
+    province?: string
+  }
+  billingData?: {
+    email: string
+    pec?: string
+    sdi?: string
+  }
+  adminBy?: string  // User IRI
+}
+```
+
+**Response:** `CompanyDetails`
+
+**Example:**
+```typescript
+import { UpdateCompany } from '@deliverart/sdk-js-company';
+
+// Update single field
+const updated = await sdk.call(new UpdateCompany('company-123', {
+  businessName: 'Acme Corp Updated'
+}));
+
+// Update multiple fields
+const updated = await sdk.call(new UpdateCompany('company-123', {
+  businessName: 'New Name',
+  billingAddress: {
+    street: 'Via Nuova 10',
+    city: 'Roma',
+    postalCode: '00100',
+    country: 'IT'
+  }
+}));
+```
+
+**Validation:**
+- `companyId`: Required, must be a non-empty string
+- All input fields are optional but validated when provided
+- Uses `application/merge-patch+json` content type for partial updates
+
+---
+
+### DeleteCompany
+
+Delete a company.
+
+**Class:** `DeleteCompany`
+
+**Constructor:**
+```typescript
+new DeleteCompany(companyId: string)
+```
+
+**Parameters:**
+- `companyId: string` - Company ID (required)
+
+**Response:** `void`
+
+**Example:**
+```typescript
+import { DeleteCompany } from '@deliverart/sdk-js-company';
+
+await sdk.call(new DeleteCompany('company-123'));
+```
+
+**Validation:**
+- `companyId`: Required, must be a non-empty string
+
+---
+
+## Complete Usage Example
+
+```typescript
+import { sdk } from './lib/sdk';
+import {
+  CreateCompany,
+  GetCompanies,
+  GetCompanyDetails,
+  GetUserCompanies,
+  UpdateCompany,
+  DeleteCompany
+} from '@deliverart/sdk-js-company';
+
+async function companyManagement() {
+  // Create a company
+  const newCompany = await sdk.call(new CreateCompany({
+    businessName: 'Tech Startup SRL',
+    vat: 'IT98765432109',
+    taxCode: null,
+    billingAddress: {
+      street: 'Via Innovation 42',
+      city: 'Milano',
+      postalCode: '20100',
+      country: 'IT'
+    },
+    operationalAddress: {
+      street: 'Via Innovation 42',
+      city: 'Milano',
+      postalCode: '20100',
+      country: 'IT'
+    },
+    billingData: {
+      email: 'billing@techstartup.it',
+      pec: 'techstartup@pec.it'
+    },
+    adminBy: '/users/456'
+  }));
+
+  console.log('Created company:', newCompany.id);
+
+  // Get all companies
+  const allCompanies = await sdk.call(new GetCompanies());
+  console.log(`Total companies: ${allCompanies.pagination.totalItems}`);
+
+  // Search companies
+  const milanCompanies = await sdk.call(new GetCompanies({
+    query: {
+      'operationalAddress.city': 'Milano',
+      'order[businessName]': 'asc'
+    }
+  }));
+
+  // Get company details
+  const details = await sdk.call(new GetCompanyDetails(newCompany.id));
+  console.log('Billing email:', details.billingData.email);
+
+  // Get user's companies
+  const userCompanies = await sdk.call(new GetUserCompanies('user-456'));
+  console.log(`User has ${userCompanies.length} companies`);
+
+  // Update company
+  const updated = await sdk.call(new UpdateCompany(newCompany.id, {
+    businessName: 'Tech Startup Updated SRL',
+    billingData: {
+      email: 'new-billing@techstartup.it',
+      pec: 'techstartup@pec.it',
+      sdi: 'ABC1234'
+    }
+  }));
+
+  // Delete company
+  await sdk.call(new DeleteCompany(newCompany.id));
+  console.log('Company deleted');
+}
+```
+
+## Error Handling
+
+```typescript
+import { ApiError } from '@deliverart/sdk-js-error-handler';
+import { CreateCompany } from '@deliverart/sdk-js-company';
+
+try {
+  await sdk.call(new CreateCompany({
+    businessName: '',  // Invalid: too short
+    vat: 'INVALID',
+    // ... other fields
+  }));
+} catch (error) {
+  if (error instanceof ApiError && error.data?.type === 'VALIDATION_ERROR') {
+    error.data.value.violations.forEach(violation => {
+      console.error(`${violation.propertyPath}: ${violation.message}`);
+    });
+  }
+}
+```
+
+## TypeScript Types
+
+All types are fully typed with TypeScript. Import them directly:
+
+```typescript
+import type {
+  Company,
+  CompanyDetails,
+  CompaniesQueryParams,
+  CompanyIri,
+  CompanyNullableIri
+} from '@deliverart/sdk-js-company';
+```
+
+## License
+
+MIT
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deliverart/sdk-js-company",
   "description": "Deliverart JavaScript SDK for Company Management",
-  "version": "2.1.49",
+  "version": "2.1.51",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,9 +18,9 @@
     "dist"
   ],
   "dependencies": {
-    "@deliverart/sdk-js-core": "2.1.49",
-    "@deliverart/sdk-js-global-types": "2.1.49",
-    "@deliverart/sdk-js-user": "2.1.49"
+    "@deliverart/sdk-js-core": "2.1.51",
+    "@deliverart/sdk-js-global-types": "2.1.51",
+    "@deliverart/sdk-js-user": "2.1.51"
   },
   "publishConfig": {
     "access": "public"