zata-vsdc-sdk 1.0.3 → 1.1.1

package/README.md

@@ -4,27 +4,18 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
-A lightweight, fully-typed TypeScript SDK for the **Zata API** – Rwanda's leading E-Invoicing & Tax Compliance platform. This SDK simplifies integration with the Rwanda Revenue Authority (RRA) compliant e-invoicing system, EBM/VSDC integration, real-time transaction validation, signed PDFs, and more.
+A production-friendly TypeScript/JavaScript SDK for the Zata API.  
+Built for Rwanda e-invoicing and tax-compliance workflows: companies, branches, parties, products, expenses, transactions, insurance, patient flows, and signed invoice downloads.
 
-## 🌟 Features
+## Why use this SDK
 
-- ✅ **Full TypeScript Support** – Complete type definitions for all API resources
-- ✅ **Lightweight & Fast** – Minimal dependencies, optimized for performance
-- ✅ **Comprehensive Coverage** – Support for all Zata API endpoints
-- ✅ **Error Handling** – Built-in error interceptors with detailed error messages
-- ✅ **Promise-Based** – Modern async/await API
-- ✅ **Well Documented** – Extensive JSDoc comments and examples
-- ✅ **Open Source** – Community-driven development
+- Fast onboarding to the Zata API with a single client
+- Automatic `Authorization`, `companyId`, and `branchId` header handling
+- Clean method names that map directly to documented API actions
+- Works in both TypeScript and JavaScript projects
+- Built-in request error formatting for faster debugging
 
-## 📚 Resources
-
-- **Official Website**: [https://zata.rw](https://zata.rw)
-- **API Documentation**: [https://docs.zata.rw](https://docs.zata.rw)
-- **Installation Guide**: [https://zata.lovable.app](https://zata.lovable.app)
-- **npm Package**: [zata-vsdc-sdk on npm](https://www.npmjs.com/package/zata-vsdc-sdk)
-- **GitHub Repository**: [HiQ-Africa/zata-npm](https://github.com/HiQ-Africa/zata-npm)
-
-## 📦 Installation
+## Install
 
 ```bash
 npm install zata-vsdc-sdk
@@ -42,818 +33,263 @@ Or with pnpm:
 pnpm add zata-vsdc-sdk
 ```
 
-## 🚀 Quick Start
+## Quick start
 
-### TypeScript/ES Modules
+```ts
+import { ZataClient } from "zata-vsdc-sdk";
 
-```typescript
-import { ZataClient } from 'zata-vsdc-sdk';
-
-// Initialize the client
 const client = new ZataClient({
-  apiKey: 'your-api-key-here',
-  baseUrl: 'https://api.zata.rw/v1', // Optional, defaults to production
-  timeout: 30000 // Optional, defaults to 30000ms
+  // token is preferred. apiKey is also supported as an alias.
+  token: process.env.ZATA_TOKEN,
+  companyId: 1,
+  branchId: 1,
+  baseUrl: "https://api.zata.rw", // default
+  timeout: 30000,                 // default
 });
 
-// Example: Get all companies
-async function example() {
-  try {
-    const companies = await client.getCompanies();
-    console.log('Companies:', companies);
-  } catch (error) {
-    console.error('Error:', error.message);
-  }
+async function run() {
+  // 1) Pull reference data
+  const paymentModes = await client.getPaymentModes();
+  const taxes = await client.getProductTaxes();
+
+  // 2) Create a customer
+  await client.createCustomer({
+    name: "John Doe",
+    address: "Kigali",
+    phone: "0780000000",
+    email: "john@example.com",
+    tin: "123456789",
+    hasInsurance: "no",
+  });
+
+  // 3) Create a product
+  await client.createProduct({
+    name: "Service Item",
+    packagingUnitID: 1,
+    quantityUnitID: 1,
+    countryID: 1,
+    taxID: 1,
+    branchProductCategoryID: 1,
+    hasStock: "yes",
+  });
+
+  // 4) Create a sale transaction
+  const sale = await client.createSaleTransaction({
+    paymentMethodID: 1,
+    transactionDate: "2026-01-01",
+    items: [{ productID: 1, units: 1, unitPrice: 1000, discountRate: 0 }],
+  });
+
+  return { paymentModes, taxes, sale };
 }
 ```
 
-### JavaScript/CommonJS
-
-```javascript
-const { ZataClient } = require('zata-vsdc-sdk');
-
-const client = new ZataClient({
-  apiKey: 'your-api-key-here'
-});
-
-// Use the client...
-client.getCompanies().then(companies => {
-  console.log('Companies:', companies);
-}).catch(error => {
-  console.error('Error:', error.message);
-});
-```
-
-## 📖 API Reference
-
-### Initialization
-
-#### `new ZataClient(options: ZataClientOptions)`
-
-Creates a new Zata API client instance.
+## JavaScript (CommonJS)
 
-**Parameters:**
-- `options.apiKey` (string, required) – Your Zata API key
-- `options.baseUrl` (string, optional) – API base URL (default: `'https://api.zata.rw/v1'`)
-- `options.timeout` (number, optional) – Request timeout in milliseconds (default: `30000`)
+```js
+const { ZataClient } = require("zata-vsdc-sdk");
 
-**Example:**
-```typescript
 const client = new ZataClient({
-  apiKey: process.env.ZATA_API_KEY!,
-  baseUrl: 'https://api.zata.rw/v1',
-  timeout: 30000
-});
-```
-
----
-
-### Companies
-
-Manage company information and settings.
-
-#### `getCompanies(): Promise<Company[]>`
-
-Retrieves a list of all companies.
-
-**Returns:** Promise resolving to an array of `Company` objects.
-
-**Example:**
-```typescript
-const companies = await client.getCompanies();
-console.log(`Found ${companies.length} companies`);
-```
-
-#### `getCompany(id: string): Promise<Company>`
-
-Retrieves a specific company by ID.
-
-**Parameters:**
-- `id` (string) – Company ID
-
-**Returns:** Promise resolving to a `Company` object.
-
-**Example:**
-```typescript
-const company = await client.getCompany('comp-123');
-console.log('Company:', company.name);
-```
-
-#### `createCompany(data: Partial<Company>): Promise<Company>`
-
-Creates a new company.
-
-**Parameters:**
-- `data` (Partial<Company>) – Company data including:
-  - `name` (string, required) – Company name
-  - `tin` (string, required) – Tax Identification Number (9 digits)
-  - `address` (string, optional) – Company address
-
-**Returns:** Promise resolving to the created `Company` object.
-
-**Example:**
-```typescript
-const newCompany = await client.createCompany({
-  name: 'Acme Corporation',
-  tin: '123456789',
-  address: 'Kigali, Rwanda'
+  token: process.env.ZATA_TOKEN,
+  companyId: 1,
+  branchId: 1,
 });
-console.log('Created company:', newCompany.id);
-```
-
-#### `updateCompany(id: string, data: Partial<Company>): Promise<Company>`
-
-Updates an existing company.
 
-**Parameters:**
-- `id` (string) – Company ID
-- `data` (Partial<Company>) – Updated company data
-
-**Returns:** Promise resolving to the updated `Company` object.
-
-**Example:**
-```typescript
-const updated = await client.updateCompany('comp-123', {
-  address: 'New Address, Kigali'
-});
+client
+  .listTransactions({ page: 1, perPage: 20 })
+  .then((res) => console.log(res))
+  .catch((err) => console.error(err.message));
 ```
 
-#### `deleteCompany(id: string): Promise<{ success: boolean; message?: string }>`
+## Authentication and context
 
-Deletes a company by ID.
+Most business endpoints need:
 
-**Parameters:**
-- `id` (string) – Company ID
+- `Authorization: Bearer <token>`
+- `companyId`
+- `branchId`
 
-**Returns:** Promise resolving to a deletion confirmation object.
+You can define these once at client creation, then update later when needed:
 
-**Example:**
-```typescript
-const result = await client.deleteCompany('comp-123');
-if (result.success) {
-  console.log('Company deleted successfully');
-}
+```ts
+client.setContext({ companyId: 2, branchId: 7 });
+client.setToken("new-token-value");
 ```
 
----
-
-### Branches
+## End-to-end implementation flow
 
-Manage branch locations for your company.
+Recommended sequence for most integrators:
 
-#### `getBranches(): Promise<Branch[]>`
+1. Authenticate (`login`) and set token
+2. Validate company and branch (`getCompany`, `listCompanyBranches`)
+3. Fetch reference data (`getPaymentModes`, product tax/unit/category lookups)
+4. Create parties (`createCustomer`, `createSupplier`)
+5. Create products (`createProduct`)
+6. Create expense and transactions
+7. Retrieve transaction PDF signature and download invoice
 
-Retrieves a list of all branches.
+This mirrors the practical order required by dependent IDs across endpoints.
 
-**Returns:** Promise resolving to an array of `Branch` objects.
+## API reference (SDK methods)
 
-**Example:**
-```typescript
-const branches = await client.getBranches();
-branches.forEach(branch => {
-  console.log(`${branch.name} (${branch.id})`);
-});
-```
+### Auth and utility
 
-#### `getBranch(id: string): Promise<Branch>`
+- `login(data)`
+- `createAccount(data)`
+- `getTestStatus()`
 
-Retrieves a specific branch by ID.
+### Company and branches
 
-**Parameters:**
-- `id` (string) – Branch ID
-
-**Returns:** Promise resolving to a `Branch` object.
-
-**Example:**
-```typescript
-const branch = await client.getBranch('branch-123');
-```
+- `listCompanies(params?)`
+- `getCompany(companyId)`
+- `createCompany(data)`
+- `updateCompany(data)`
+- `listCompanyBranches(params?)`
+- `createCompanyBranch(data)`
+- `updateCompanyBranch(data)`
+- `getCompanyFinance()`
+- `getCompanyTaxInfo()`
 
-#### `createBranch(data: Partial<Branch>): Promise<Branch>`
-
-Creates a new branch.
-
-**Parameters:**
-- `data` (Partial<Branch>) – Branch data including:
-  - `name` (string, required) – Branch name
-  - `companyId` (string, required) – Parent company ID
-
-**Returns:** Promise resolving to the created `Branch` object.
-
-**Example:**
-```typescript
-const newBranch = await client.createBranch({
-  name: 'Kicukiro Branch',
-  companyId: 'comp-123'
-});
-```
+### Reference data
 
-#### `updateBranch(id: string, data: Partial<Branch>): Promise<Branch>`
+- `getPaymentModes()`
+- `getProductCategories()`
+- `getProductClasses()`
+- `getProductCountryOrigins()`
+- `getProductPackagingUnits()`
+- `getProductQuantityUnits()`
+- `getProductTaxes()`
+- `getProductTypes()`
 
-Updates an existing branch.
+### Parties
 
-**Parameters:**
-- `id` (string) – Branch ID
-- `data` (Partial<Branch>) – Updated branch data
-
-**Returns:** Promise resolving to the updated `Branch` object.
-
-#### `deleteBranch(id: string): Promise<{ success: boolean }>`
-
-Deletes a branch by ID.
-
-**Parameters:**
-- `id` (string) – Branch ID
-
-**Returns:** Promise resolving to a deletion confirmation object.
-
----
+- `listParties(params?)`
+- `createCustomer(data)`
+- `createSupplier(data)`
 
 ### Products
 
-Manage your product catalog.
-
-#### `getProducts(): Promise<Product[]>`
-
-Retrieves a list of all products.
-
-**Returns:** Promise resolving to an array of `Product` objects.
-
-**Example:**
-```typescript
-const products = await client.getProducts();
-console.log(`Total products: ${products.length}`);
-```
-
-#### `getProduct(id: string): Promise<Product>`
-
-Retrieves a specific product by ID.
-
-**Parameters:**
-- `id` (string) – Product ID
-
-**Returns:** Promise resolving to a `Product` object.
-
-**Example:**
-```typescript
-const product = await client.getProduct('prod-123');
-console.log(`${product.name} - ${product.price} RWF`);
-```
-
-#### `createProduct(data: Partial<Product>): Promise<Product>`
-
-Creates a new product.
-
-**Parameters:**
-- `data` (Partial<Product>) – Product data including:
-  - `name` (string, required) – Product name
-  - `code` (string, optional) – Product code/SKU
-  - `price` (number, optional) – Product price
-  - `unit` (string, optional) – Unit of measurement
-
-**Returns:** Promise resolving to the created `Product` object.
-
-**Example:**
-```typescript
-const newProduct = await client.createProduct({
-  name: 'Premium Coffee',
-  code: 'COFFEE-001',
-  price: 5000,
-  unit: 'kg'
-});
-```
-
-#### `updateProduct(id: string, data: Partial<Product>): Promise<Product>`
-
-Updates an existing product.
-
-**Parameters:**
-- `id` (string) – Product ID
-- `data` (Partial<Product>) – Updated product data
-
-**Returns:** Promise resolving to the updated `Product` object.
-
-**Example:**
-```typescript
-await client.updateProduct('prod-123', {
-  price: 5500 // Update price
-});
-```
-
-#### `deleteProduct(id: string): Promise<{ success: boolean }>`
-
-Deletes a product by ID.
-
-**Parameters:**
-- `id` (string) – Product ID
-
-**Returns:** Promise resolving to a deletion confirmation object.
-
----
-
-### Parties (Customers & Suppliers)
-
-Manage customers and suppliers.
-
-#### `getParties(): Promise<Party[]>`
-
-Retrieves a list of all parties (customers and suppliers).
-
-**Returns:** Promise resolving to an array of `Party` objects.
-
-**Example:**
-```typescript
-const parties = await client.getParties();
-const customers = parties.filter(p => p.type === 'customer');
-```
-
-#### `getParty(id: string): Promise<Party>`
-
-Retrieves a specific party by ID.
-
-**Parameters:**
-- `id` (string) – Party ID
-
-**Returns:** Promise resolving to a `Party` object.
-
-**Example:**
-```typescript
-const customer = await client.getParty('party-123');
-console.log(`Customer: ${customer.name} (TIN: ${customer.tin})`);
-```
-
-#### `createParty(data: Partial<Party>): Promise<Party>`
-
-Creates a new party (customer or supplier).
-
-**Parameters:**
-- `data` (Partial<Party>) – Party data including:
-  - `name` (string, required) – Party name
-  - `tin` (string, optional) – Tax Identification Number (9 digits)
-  - `type` (string, optional) – Party type: `'customer'` or `'supplier'`
-
-**Returns:** Promise resolving to the created `Party` object.
-
-**Example:**
-```typescript
-const newCustomer = await client.createParty({
-  name: 'John Doe',
-  tin: '123456789',
-  type: 'customer'
-});
-```
-
-#### `updateParty(id: string, data: Partial<Party>): Promise<Party>`
-
-Updates an existing party.
-
-**Parameters:**
-- `id` (string) – Party ID
-- `data` (Partial<Party>) – Updated party data
-
-**Returns:** Promise resolving to the updated `Party` object.
-
-#### `deleteParty(id: string): Promise<{ success: boolean }>`
-
-Deletes a party by ID.
-
-**Parameters:**
-- `id` (string) – Party ID
-
-**Returns:** Promise resolving to a deletion confirmation object.
-
----
+- `createProduct(data)`
+- `listBranchProducts(params?)`
+- `getProduct(productId)`
+- `updateProduct(productId, data)`
+- `increaseProductQuantity(productId, data)`
+- `reduceProductQuantity(productId, data)`
 
 ### Expenses
 
-Track business expenses.
-
-#### `getExpenses(): Promise<Expense[]>`
-
-Retrieves a list of all expenses.
-
-**Returns:** Promise resolving to an array of `Expense` objects.
-
-**Example:**
-```typescript
-const expenses = await client.getExpenses();
-const total = expenses.reduce((sum, e) => sum + e.amount, 0);
-console.log(`Total expenses: ${total} RWF`);
-```
-
-#### `getExpense(id: string): Promise<Expense>`
-
-Retrieves a specific expense by ID.
-
-**Parameters:**
-- `id` (string) – Expense ID
-
-**Returns:** Promise resolving to an `Expense` object.
-
-**Example:**
-```typescript
-const expense = await client.getExpense('exp-123');
-console.log(`${expense.description}: ${expense.amount} RWF`);
-```
-
-#### `createExpense(data: Partial<Expense>): Promise<Expense>`
-
-Creates a new expense record.
-
-**Parameters:**
-- `data` (Partial<Expense>) – Expense data including:
-  - `amount` (number, required) – Expense amount
-  - `description` (string, required) – Expense description
-  - `date` (string, optional) – Expense date (YYYY-MM-DD format)
-
-**Returns:** Promise resolving to the created `Expense` object.
+- `listExpenses(params?)`
+- `createExpense(data)`
+- `getExpenseCategories()`
 
-**Example:**
-```typescript
-const newExpense = await client.createExpense({
-  amount: 50000,
-  description: 'Office Supplies',
-  date: '2024-01-15'
-});
-```
-
-#### `updateExpense(id: string, data: Partial<Expense>): Promise<Expense>`
-
-Updates an existing expense.
-
-**Parameters:**
-- `id` (string) – Expense ID
-- `data` (Partial<Expense>) – Updated expense data
-
-**Returns:** Promise resolving to the updated `Expense` object.
-
-#### `deleteExpense(id: string): Promise<{ success: boolean }>`
+### Insurance
 
-Deletes an expense by ID.
+- `listInsurances()`
+- `createPresetInsurance(data)`
+- `createCustomInsurance(data)`
+- `updateCustomInsurance(insuranceId, data)`
+- `updateBranchInsurance(companyInsuranceId, data)`
 
-**Parameters:**
-- `id` (string) – Expense ID
+### Patients
 
-**Returns:** Promise resolving to a deletion confirmation object.
+- `listPatients(params?)`
+- `createPatient(data)`
+- `getPatient(patientId)`
+- `updatePatient(patientId, data)`
+- `getPatientByParty(partyId)`
 
----
-
-### Transactions (Invoices, Receipts, etc.)
-
-Create and manage transactions including invoices, receipts, credit notes, and more.
-
-#### `getTransactions(): Promise<Transaction[]>`
-
-Retrieves a list of all transactions.
-
-**Returns:** Promise resolving to an array of `Transaction` objects.
-
-**Example:**
-```typescript
-const transactions = await client.getTransactions();
-const invoices = transactions.filter(t => t.type === 'invoice');
-```
+### Transactions
 
-#### `getTransaction(id: string): Promise<Transaction>`
+- `listTransactions(params?)`
+- `calculateTransaction(data)`
+- `createSaleTransaction(data)`
+- `createPurchaseTransaction(data)`
+- `createProformaTransaction(data)`
+- `createRefundTransaction(transactionId, data)`
+- `getTransaction(transactionId, params?)`
+- `getTransactionDownloadSignature(transactionId, params?)`
+- `downloadTransaction(params)`
 
-Retrieves a specific transaction by ID.
+## Transaction examples
 
-**Parameters:**
-- `id` (string) – Transaction ID
+### Calculate before create
 
-**Returns:** Promise resolving to a `Transaction` object.
-
-**Example:**
-```typescript
-const transaction = await client.getTransaction('txn-123');
-console.log(`Invoice #${transaction.id}: ${transaction.totalAmount} RWF`);
-```
-
-#### `createTransaction(data: Partial<Transaction>): Promise<Transaction>`
-
-Creates a new transaction (invoice, receipt, credit note, etc.).
-
-**Parameters:**
-- `data` (Partial<Transaction>) – Transaction data including:
-  - `type` (string, optional) – Transaction type: `'invoice'`, `'receipt'`, `'credit_note'`, etc.
-  - `partyId` (string, optional) – Customer/Supplier party ID
-  - `items` (array, optional) – Transaction line items:
-    - `productId` (string, optional) – Product ID
-    - `quantity` (number, required) – Item quantity
-    - `unitPrice` (number, required) – Unit price
-  - `totalAmount` (number, optional) – Total transaction amount
-
-**Returns:** Promise resolving to the created `Transaction` object.
-
-**Example:**
-```typescript
-const invoice = await client.createTransaction({
-  type: 'invoice',
-  partyId: 'party-123',
+```bash
+const calc = await client.calculateTransaction({
   items: [
-    {
-      productId: 'prod-123',
-      quantity: 2,
-      unitPrice: 5000
-    }
+    { productID: 1, units: 2, unitPrice: 1000, discountRate: 5, batchNumber: "B-001" }
   ]
 });
-console.log(`Created invoice: ${invoice.id}`);
 ```
 
-#### `updateTransaction(id: string, data: Partial<Transaction>): Promise<Transaction>`
-
-Updates an existing transaction.
-
-**Parameters:**
-- `id` (string) – Transaction ID
-- `data` (Partial<Transaction>) – Updated transaction data
-
-**Returns:** Promise resolving to the updated `Transaction` object.
-
-#### `deleteTransaction(id: string): Promise<{ success: boolean }>`
-
-Deletes a transaction by ID.
+### Create sale
 
-**Parameters:**
-- `id` (string) – Transaction ID
-
-**Returns:** Promise resolving to a deletion confirmation object.
-
-#### `getSignedPdf(id: string): Promise<SignedPdfResponse>`
-
-Retrieves a signed PDF document for a transaction.
-
-**Parameters:**
-- `id` (string) – Transaction ID
-
-**Returns:** Promise resolving to a `SignedPdfResponse` object containing:
-- `url` (string, optional) – URL to download the PDF
-- `base64` (string, optional) – Base64-encoded PDF content
-
-**Example:**
-```typescript
-const pdf = await client.getSignedPdf('txn-123');
-if (pdf.url) {
-  console.log('PDF URL:', pdf.url);
-  // Download the PDF from the URL
-} else if (pdf.base64) {
-  // Decode and save the base64 PDF
-  const buffer = Buffer.from(pdf.base64, 'base64');
-  fs.writeFileSync('invoice.pdf', buffer);
-}
-```
-
----
-
-## 💡 Common Use Cases
-
-### Creating a Complete Invoice Flow
-
-```typescript
-import { ZataClient } from 'zata-vsdc-sdk';
-
-const client = new ZataClient({
-  apiKey: process.env.ZATA_API_KEY!
+```ts
+const sale = await client.createSaleTransaction({
+  paymentMethodID: 1,
+  customerID: 1,
+  transactionDate: "2026-04-01",
+  note: "Sale from SDK",
+  items: [{ productID: 1, units: 2, unitPrice: 1000, discountRate: 0 }],
 });
-
-async function createInvoice() {
-  try {
-    // 1. Create or get a customer
-    const customer = await client.createParty({
-      name: 'Acme Customer Ltd',
-      tin: '123456789',
-      type: 'customer'
-    });
-
-    // 2. Create or get products
-    const product = await client.createProduct({
-      name: 'Premium Service',
-      price: 10000,
-      unit: 'hour'
-    });
-
-    // 3. Create the invoice
-    const invoice = await client.createTransaction({
-      type: 'invoice',
-      partyId: customer.id,
-      items: [
-        {
-          productId: product.id,
-          quantity: 5,
-          unitPrice: 10000
-        }
-      ]
-    });
-
-    console.log(`Invoice created: ${invoice.id}`);
-
-    // 4. Get the signed PDF
-    const pdf = await client.getSignedPdf(invoice.id);
-    console.log('PDF available at:', pdf.url);
-
-    return invoice;
-  } catch (error) {
-    console.error('Error creating invoice:', error);
-    throw error;
-  }
-}
 ```
 
-### Batch Processing
-
-```typescript
-async function createMultipleInvoices(invoices: Array<{ customerId: string; items: any[] }>) {
-  const results = await Promise.allSettled(
-    invoices.map(data =>
-      client.createTransaction({
-        type: 'invoice',
-        partyId: data.customerId,
-        items: data.items
-      })
-    )
-  );
-
-  const successful = results
-    .filter((r): r is PromiseFulfilledResult<any> => r.status === 'fulfilled')
-    .map(r => r.value);
-
-  const failed = results
-    .filter((r): r is PromiseRejectedResult => r.status === 'rejected')
-    .map(r => r.reason);
-
-  console.log(`Created ${successful.length} invoices, ${failed.length} failed`);
-  return { successful, failed };
-}
-```
-
-### Error Handling
-
-```typescript
-async function safeCreateProduct(productData: Partial<Product>) {
-  try {
-    const product = await client.createProduct(productData);
-    return { success: true, data: product };
-  } catch (error: any) {
-    // Parse error message
-    if (error.message.includes('400')) {
-      return { success: false, error: 'Validation error', details: error.message };
-    } else if (error.message.includes('401')) {
-      return { success: false, error: 'Authentication failed' };
-    } else if (error.message.includes('404')) {
-      return { success: false, error: 'Resource not found' };
-    } else {
-      return { success: false, error: 'Unknown error', details: error.message };
-    }
-  }
-}
-```
+### Download invoice PDF
 
----
+```ts
+const signature = await client.getTransactionDownloadSignature(123, { downloadSize: "A4" });
 
-## 🔧 TypeScript Types
-
-The SDK exports TypeScript interfaces for all resources:
-
-```typescript
-import {
-  ZataClient,
-  Company,
-  Branch,
-  Product,
-  Party,
-  Expense,
-  Transaction,
-  SignedPdfResponse,
-  ZataClientOptions
-} from 'zata-vsdc-sdk';
+const pdf = await client.downloadTransaction({
+  expires: signature.expires,
+  id: signature.id,
+  signature: signature.signature,
+});
 ```
 
-### Available Types
+## Error handling
 
-- `Company` – Company resource
-- `Branch` – Branch resource
-- `Product` – Product resource
-- `Party` – Customer/Supplier resource
-- `Expense` – Expense resource
-- `Transaction` – Invoice/Receipt/Credit Note resource
-- `SignedPdfResponse` – PDF response with URL or base64
-- `ZataClientOptions` – Client initialization options
-- `ZataResourceMeta` – Base metadata fields for resources
+The client throws normalized errors in this format:
 
----
+- `Zata API Error <status>: <response-json>`
+- `Network/Request Error: <message>`
 
-## ⚠️ Error Handling
-
-The SDK includes built-in error handling that provides detailed error messages:
-
-```typescript
+```ts
 try {
-  await client.getCompany('invalid-id');
-} catch (error: any) {
-  // Error format: "Zata API Error 404: {...}"
+  await client.getTransaction(999999);
+} catch (error) {
   console.error(error.message);
 }
 ```
 
-Common error scenarios:
-
-- **400 Bad Request** – Validation errors (check request data)
-- **401 Unauthorized** – Invalid or missing API key
-- **404 Not Found** – Resource doesn't exist
-- **500 Server Error** – Internal server error (retry with backoff)
-- **Network Errors** – Connection issues (check network/API URL)
+## Best practices
 
----
+- Cache lookup/reference data (payment modes, taxes, units)
+- Validate IDs and required fields before calling write endpoints
+- Use `calculateTransaction` before creating high-value invoices
+- Store entity IDs you create (party, product, transaction)
+- Use retries/backoff for transient network or 5xx failures
 
-## 🌍 Environment Configuration
-
-For different environments, you can configure the base URL:
-
-```typescript
-// Production (default)
-const prodClient = new ZataClient({
-  apiKey: process.env.ZATA_API_KEY!
-});
-
-// Staging/Development
-const devClient = new ZataClient({
-  apiKey: process.env.ZATA_API_KEY!,
-  baseUrl: 'https://staging-api.zata.rw/v1'
-});
-
-// Custom timeout for slow connections
-const slowClient = new ZataClient({
-  apiKey: process.env.ZATA_API_KEY!,
-  timeout: 60000 // 60 seconds
-});
-```
-
----
-
-## 🤝 Contributing
-
-This is an open-source project, and we welcome contributions from the community! Here's how you can help:
-
-1. **Report Issues** – Found a bug? [Open an issue](https://github.com/HiQ-Africa/zata-npm/issues)
-2. **Suggest Features** – Have an idea? [Share it with us](https://github.com/HiQ-Africa/zata-npm/issues)
-3. **Submit Pull Requests** – Fixed a bug or added a feature? [Submit a PR](https://github.com/HiQ-Africa/zata-npm/pulls)
-4. **Improve Documentation** – Help make the docs better for everyone
-
-### Development Setup
+## Development
 
 ```bash
-# Clone the repository
-git clone https://github.com/HiQ-Africa/zata-npm.git
-cd zata-npm
-
-# Install dependencies
 npm install
-
-# Build the project
 npm run build
-
-# Run tests (if available)
 npm test
 ```
 
-### Code Style
-
-- Use TypeScript for all new code
-- Follow existing code style and patterns
-- Add JSDoc comments for public methods
-- Include examples in documentation
-
----
-
-## 📝 License
-
-This project is licensed under the MIT License – see the [LICENSE](LICENSE) file for details.
-
----
-
-## 🙏 Acknowledgments
-
-- Built for the Rwanda business community
-- Powered by [Zata](https://zata.rw) – Rwanda's leading tax compliance platform
-- Developed by [HiQ Africa](https://hiq.africa)
-
----
-
-## 📞 Support
-
-- **Documentation**: [https://docs.zata.rw](https://docs.zata.rw)
-- **Support Email**: hirwa@hiq.africa
-- **GitHub Issues**: [https://github.com/HiQ-Africa/zata-npm/issues](https://github.com/HiQ-Africa/zata-npm/issues)
+## Links
 
----
+- API docs: [https://docs.zata.rw](https://docs.zata.rw)
+- Website: [https://zata.rw](https://zata.rw)
+- npm: [https://www.npmjs.com/package/zata-vsdc-sdk](https://www.npmjs.com/package/zata-vsdc-sdk)
+- GitHub: [https://github.com/HiQ-Africa/zata-npm](https://github.com/HiQ-Africa/zata-npm)
+- Integration guide: [./guide.md](./guide.md)
 
-## 🔗 Related Resources
+## Support
 
-- [Zata Official Website](https://zata.rw)
-- [Zata API Documentation](https://docs.zata.rw)
-- [Implementation Guide](./guide.md) – Detailed step-by-step guide for implementing the Zata API
+- Email: `hirwa@hiq.africa`
+- Issues: [https://github.com/HiQ-Africa/zata-npm/issues](https://github.com/HiQ-Africa/zata-npm/issues)
 
----
+## License
 
-**Made with ❤️ for the Rwanda developer community**
+MIT