@deliverart/sdk-js-company

Company management package for the DeliverArt JavaScript SDK.

Installation

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

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

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

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

type CompanyIri = string

Company IRI type (format: /companies/:id)

CompanyNullableIri

type CompanyNullableIri = string | null

Nullable company IRI type

Available Requests

CreateCompany

Create a new company.

Class: CreateCompany

Input Schema:

{
  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:

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: '[email protected]',
    pec: '[email protected]'
  },
  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:

new GetCompanies(options?: { query?: CompaniesQueryParams })

Query Parameters: See CompaniesQueryParams above

Response: Paginated<Company>

Example:

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:

new GetCompanyDetails(companyId: string)

Parameters:

• companyId: string - Company ID (required)

Response: CompanyDetails

Example:

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:

new GetUserCompanies(userId: string)

Parameters:

• userId: string - User ID (required)

Response: Company[]

Example:

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:

new UpdateCompany(companyId: string, input: Partial<CompanyInput>)

Parameters:

• companyId: string - Company ID (required)
• input: Partial<CompanyInput> - Fields to update (all optional)

Input Schema:

{
  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:

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:

new DeleteCompany(companyId: string)

Parameters:

• companyId: string - Company ID (required)

Response: void

Example:

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

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: '[email protected]',
      pec: '[email protected]'
    },
    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: '[email protected]',
      pec: '[email protected]',
      sdi: 'ABC1234'
    }
  }));

  // Delete company
  await sdk.call(new DeleteCompany(newCompany.id));
  console.log('Company deleted');
}

Error Handling

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:

import type {
  Company,
  CompanyDetails,
  CompaniesQueryParams,
  CompanyIri,
  CompanyNullableIri
} from '@deliverart/sdk-js-company';

License

MIT

Administrative creation

CreateCompany links the existing user referenced by adminBy; it does not create an account, send an invitation, or grant manager roles. Admin interfaces should select an existing active manager. Lead initialization is a separate API workflow that can create a manager.

For VAT numbers starting with IT, provide billingData with both sdi and pec keys and at least one non-empty value. Other countries can use { sdi: null, pec: null }. Company response validation does not impose Italian invoicing rules on foreign companies. PATCH defers conditional VAT requirements to the API, which can validate the complete persisted company.