zata-vsdc-sdk 1.0.3 → 1.1.0

package/README.md

@@ -1,859 +1,108 @@
 # zata-vsdc-sdk
 
 [![npm version](https://img.shields.io/npm/v/zata-vsdc-sdk.svg)](https://www.npmjs.com/package/zata-vsdc-sdk)
-[![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.
+TypeScript SDK for the Zata API, aligned with the latest OpenAPI documentation.
 
-## 🌟 Features
-
-- ✅ **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
-
-## 📚 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
+## Installation
 
 ```bash
 npm install zata-vsdc-sdk
 ```
 
-Or with yarn:
-
-```bash
-yarn add zata-vsdc-sdk
-```
-
-Or with pnpm:
-
-```bash
-pnpm add zata-vsdc-sdk
-```
-
-## 🚀 Quick Start
-
-### TypeScript/ES Modules
-
-```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
-});
-
-// Example: Get all companies
-async function example() {
-  try {
-    const companies = await client.getCompanies();
-    console.log('Companies:', companies);
-  } catch (error) {
-    console.error('Error:', error.message);
-  }
-}
-```
-
-### JavaScript/CommonJS
+## Initialize Client
 
-```javascript
-const { ZataClient } = require('zata-vsdc-sdk');
+```ts
+import { ZataClient } from "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);
+  token: process.env.ZATA_TOKEN,
+  companyId: 1,
+  branchId: 1,
+  baseUrl: "https://api.zata.rw",
 });
 ```
 
-## 📖 API Reference
-
-### Initialization
-
-#### `new ZataClient(options: ZataClientOptions)`
-
-Creates a new Zata API client instance.
-
-**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`)
-
-**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'
-});
-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'
-});
-```
-
-#### `deleteCompany(id: string): Promise<{ success: boolean; message?: string }>`
-
-Deletes a company by ID.
-
-**Parameters:**
-- `id` (string) – Company ID
-
-**Returns:** Promise resolving to a deletion confirmation object.
-
-**Example:**
-```typescript
-const result = await client.deleteCompany('comp-123');
-if (result.success) {
-  console.log('Company deleted successfully');
-}
-```
-
----
-
-### Branches
-
-Manage branch locations for your company.
+`apiKey` is still accepted as an alias for `token`.
 
-#### `getBranches(): Promise<Branch[]>`
+## Quick Start
 
-Retrieves a list of all branches.
-
-**Returns:** Promise resolving to an array of `Branch` objects.
-
-**Example:**
-```typescript
-const branches = await client.getBranches();
-branches.forEach(branch => {
-  console.log(`${branch.name} (${branch.id})`);
+```ts
+// 1) Login (if you do not have a token yet)
+const auth = await client.login({
+  email: "user@example.com",
+  password: "your-password",
 });
-```
-
-#### `getBranch(id: string): Promise<Branch>`
-
-Retrieves a specific branch by ID.
-
-**Parameters:**
-- `id` (string) – Branch ID
-
-**Returns:** Promise resolving to a `Branch` object.
-
-**Example:**
-```typescript
-const branch = await client.getBranch('branch-123');
-```
 
-#### `createBranch(data: Partial<Branch>): Promise<Branch>`
+// 2) Reference data
+const paymentModes = await client.getPaymentModes();
+const productTaxes = await client.getProductTaxes();
 
-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'
+// 3) Create parties/products
+await client.createCustomer({
+  name: "John Doe",
+  phone: "0780000000",
+  email: "john@example.com",
+  tin: "123456789",
+  address: "Kigali",
+  hasInsurance: "no",
 });
-```
-
-#### `updateBranch(id: string, data: Partial<Branch>): Promise<Branch>`
-
-Updates an existing branch.
-
-**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.
-
----
-
-### 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'
+await client.createProduct({
+  name: "Service Item",
+  packagingUnitID: 1,
+  quantityUnitID: 1,
+  countryID: 1,
+  taxID: 1,
+  branchProductCategoryID: 1,
+  hasStock: "yes",
 });
-```
-
-#### `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
+// 4) Create sale transaction
+await client.createSaleTransaction({
+  paymentMethodID: 1,
+  transactionDate: "2026-01-01",
+  items: [{ productID: 1, units: 1, unitPrice: 1000, discountRate: 0 }],
 });
 ```
 
-#### `deleteProduct(id: string): Promise<{ success: boolean }>`
-
-Deletes a product by ID.
-
-**Parameters:**
-- `id` (string) – Product ID
-
-**Returns:** Promise resolving to a deletion confirmation object.
+## API Coverage
 
----
+The SDK exposes methods for all paths in the current OpenAPI spec, including:
 
-### Parties (Customers & Suppliers)
+- Auth and account: `login`, `createAccount`
+- Company and branches: `listCompanies`, `getCompany`, `createCompany`, `updateCompany`, `listCompanyBranches`, `createCompanyBranch`, `updateCompanyBranch`, `getCompanyFinance`, `getCompanyTaxInfo`
+- Reference data: `getPaymentModes`, `getProductCategories`, `getProductClasses`, `getProductCountryOrigins`, `getProductPackagingUnits`, `getProductQuantityUnits`, `getProductTaxes`, `getProductTypes`
+- Parties: `listParties`, `createCustomer`, `createSupplier`
+- Product: `createProduct`, `listBranchProducts`, `getProduct`, `updateProduct`, `increaseProductQuantity`, `reduceProductQuantity`
+- Expense: `listExpenses`, `createExpense`, `getExpenseCategories`
+- Insurance: `listInsurances`, `createPresetInsurance`, `createCustomInsurance`, `updateCustomInsurance`, `updateBranchInsurance`
+- Patient: `listPatients`, `createPatient`, `getPatient`, `updatePatient`, `getPatientByParty`
+- Transactions: `listTransactions`, `calculateTransaction`, `createSaleTransaction`, `createPurchaseTransaction`, `createProformaTransaction`, `createRefundTransaction`, `getTransaction`, `getTransactionDownloadSignature`, `downloadTransaction`
 
-Manage customers and suppliers.
+## Context and Headers
 
-#### `getParties(): Promise<Party[]>`
+The client automatically attaches:
 
-Retrieves a list of all parties (customers and suppliers).
+- `Authorization: Bearer <token>` (when token/apiKey provided)
+- `companyId` header (when set)
+- `branchId` header (when set)
 
-**Returns:** Promise resolving to an array of `Party` objects.
+You can update context at runtime:
 
-**Example:**
-```typescript
-const parties = await client.getParties();
-const customers = parties.filter(p => p.type === 'customer');
+```ts
+client.setContext({ companyId: 2, branchId: 3 });
+client.setToken("new-token-value");
 ```
 
-#### `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.
-
----
-
-### 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.
-
-**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 }>`
-
-Deletes an expense by ID.
-
-**Parameters:**
-- `id` (string) – Expense ID
-
-**Returns:** Promise resolving to a deletion confirmation object.
-
----
-
-### 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');
-```
-
-#### `getTransaction(id: string): Promise<Transaction>`
-
-Retrieves a specific transaction by ID.
-
-**Parameters:**
-- `id` (string) – Transaction ID
-
-**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',
-  items: [
-    {
-      productId: 'prod-123',
-      quantity: 2,
-      unitPrice: 5000
-    }
-  ]
-});
-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.
-
-**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!
-});
-
-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 };
-    }
-  }
-}
-```
-
----
-
-## 🔧 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';
-```
-
-### Available Types
-
-- `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
-
----
-
-## ⚠️ Error Handling
-
-The SDK includes built-in error handling that provides detailed error messages:
-
-```typescript
-try {
-  await client.getCompany('invalid-id');
-} catch (error: any) {
-  // Error format: "Zata API Error 404: {...}"
-  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)
-
----
-
-## 🌍 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
+## Scripts
 
 ```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)
-
----
-
-## 🔗 Related Resources
-
-- [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
-
----
+## Resources
 
-**Made with ❤️ for the Rwanda developer community**
+- API docs: [https://docs.zata.rw](https://docs.zata.rw)
+- Website: [https://zata.rw](https://zata.rw)

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+export type Primitive = string | number | boolean;
+export type QueryParams = Record<string, Primitive | undefined>;
+export type ApiRecord = Record<string, unknown>;
+export interface ZataClientOptions {
+    /**
+     * Bearer token for Zata API. `apiKey` remains as an alias
+     * for backwards compatibility with previous SDK versions.
+     */
+    token?: string;
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+    companyId?: string | number;
+    branchId?: string | number;
+    defaultHeaders?: Record<string, string>;
+}
+export interface ZataClientContext {
+    companyId?: string | number;
+    branchId?: string | number;
+}
+export declare class ZataClient {
+    private readonly axios;
+    private readonly baseHeaders;
+    private context;
+    constructor(options?: ZataClientOptions);
+    setToken(token: string): void;
+    setContext(context: ZataClientContext): void;
+    private buildHeaders;
+    private request;
+    login(data: ApiRecord): Promise<ApiRecord>;
+    createAccount(data: ApiRecord): Promise<ApiRecord>;
+    getTestStatus(): Promise<ApiRecord>;
+    listCompanies(params?: {
+        perPage?: number;
+        page?: number;
+    }): Promise<ApiRecord>;
+    createCompany(data: ApiRecord): Promise<ApiRecord>;
+    updateCompany(data: ApiRecord): Promise<ApiRecord>;
+    getCompany(companyId: string | number): Promise<ApiRecord>;
+    listCompanyBranches(params?: {
+        perPage?: number;
+        page?: number;
+    }): Promise<ApiRecord>;
+    createCompanyBranch(data: ApiRecord): Promise<ApiRecord>;
+    updateCompanyBranch(data: ApiRecord): Promise<ApiRecord>;
+    getCompanyFinance(): Promise<ApiRecord>;
+    getCompanyTaxInfo(): Promise<ApiRecord>;
+    getPaymentModes(): Promise<ApiRecord>;
+    getProductCategories(): Promise<ApiRecord>;
+    getProductClasses(): Promise<ApiRecord>;
+    getProductCountryOrigins(): Promise<ApiRecord>;
+    getProductPackagingUnits(): Promise<ApiRecord>;
+    getProductQuantityUnits(): Promise<ApiRecord>;
+    getProductTaxes(): Promise<ApiRecord>;
+    getProductTypes(): Promise<ApiRecord>;
+    listParties(params?: {
+        partyType?: string;
+        perPage?: number;
+        page?: number;
+    }): Promise<ApiRecord>;
+    createCustomer(data: ApiRecord): Promise<ApiRecord>;
+    createSupplier(data: ApiRecord): Promise<ApiRecord>;
+    listExpenses(params?: {
+        perPage?: number;
+        page?: number;
+        searchQuery?: string;
+    }): Promise<ApiRecord>;
+    createExpense(data: ApiRecord): Promise<ApiRecord>;
+    getExpenseCategories(): Promise<ApiRecord>;
+    listInsurances(): Promise<ApiRecord>;
+    createPresetInsurance(data: ApiRecord): Promise<ApiRecord>;
+    createCustomInsurance(data: ApiRecord): Promise<ApiRecord>;
+    updateCustomInsurance(insuranceId: string | number, data: ApiRecord): Promise<ApiRecord>;
+    updateBranchInsurance(companyInsuranceId: string | number, data: ApiRecord): Promise<ApiRecord>;
+    listPatients(params?: {
+        perPage?: number;
+        page?: number;
+        searchQuery?: string;
+    }): Promise<ApiRecord>;
+    createPatient(data: ApiRecord): Promise<ApiRecord>;
+    getPatient(patientId: string | number): Promise<ApiRecord>;
+    updatePatient(patientId: string | number, data: ApiRecord): Promise<ApiRecord>;
+    getPatientByParty(partyId: string | number): Promise<ApiRecord>;
+    createProduct(data: ApiRecord): Promise<ApiRecord>;
+    listBranchProducts(params?: {
+        perPage?: number;
+        page?: number;
+        searchQuery?: string;
+    }): Promise<ApiRecord>;
+    getProduct(productId: string | number): Promise<ApiRecord>;
+    updateProduct(productId: string | number, data: ApiRecord): Promise<ApiRecord>;
+    increaseProductQuantity(productId: string | number, data: ApiRecord): Promise<ApiRecord>;
+    reduceProductQuantity(productId: string | number, data: ApiRecord): Promise<ApiRecord>;
+    listTransactions(params?: {
+        perPage?: number;
+        page?: number;
+        fromDate?: string;
+        toDate?: string;
+        invoiceType?: string;
+    }): Promise<ApiRecord>;
+    calculateTransaction(data: ApiRecord): Promise<ApiRecord>;
+    createSaleTransaction(data: ApiRecord): Promise<ApiRecord>;
+    createPurchaseTransaction(data: ApiRecord): Promise<ApiRecord>;
+    createProformaTransaction(data: ApiRecord): Promise<ApiRecord>;
+    createRefundTransaction(transactionId: string | number, data: ApiRecord): Promise<ApiRecord>;
+    getTransaction(transactionId: string | number, params?: {
+        withSignature?: boolean;
+    }): Promise<ApiRecord>;
+    getTransactionDownloadSignature(transactionId: string | number, params?: {
+        downloadSize?: 'A4' | 'm80' | 'm58';
+    }): Promise<ApiRecord>;
+    downloadTransaction(params: {
+        expires: string | number;
+        id: string | number;
+        signature: string;
+    }): Promise<ApiRecord>;
+}
+export default ZataClient;

package/dist/index.js

@@ -0,0 +1,240 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZataClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+class ZataClient {
+    constructor(options = {}) {
+        const { token, apiKey, baseUrl = 'https://api.zata.rw', timeout = 30000, companyId, branchId, defaultHeaders = {}, } = options;
+        const authToken = token ?? apiKey;
+        this.baseHeaders = {
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+            ...defaultHeaders,
+        };
+        if (authToken) {
+            this.baseHeaders.Authorization = authToken.startsWith('Bearer ')
+                ? authToken
+                : `Bearer ${authToken}`;
+        }
+        this.context = { companyId, branchId };
+        this.axios = axios_1.default.create({
+            baseURL: baseUrl,
+            timeout,
+            headers: this.baseHeaders,
+        });
+        this.axios.interceptors.response.use((response) => response, (error) => {
+            if (error.response) {
+                const { status, data } = error.response;
+                throw new Error(`Zata API Error ${status}: ${JSON.stringify(data)}`);
+            }
+            throw new Error(`Network/Request Error: ${error.message}`);
+        });
+    }
+    setToken(token) {
+        this.baseHeaders.Authorization = token.startsWith('Bearer ')
+            ? token
+            : `Bearer ${token}`;
+    }
+    setContext(context) {
+        this.context = {
+            ...this.context,
+            ...context,
+        };
+    }
+    buildHeaders(extraHeaders) {
+        const headers = {
+            ...this.baseHeaders,
+            ...extraHeaders,
+        };
+        if (this.context.companyId !== undefined) {
+            headers.companyId = String(this.context.companyId);
+        }
+        if (this.context.branchId !== undefined) {
+            headers.branchId = String(this.context.branchId);
+        }
+        return headers;
+    }
+    async request(method, path, options = {}) {
+        const { data, params, headers, config } = options;
+        const response = await this.axios.request({
+            method,
+            url: path,
+            data,
+            params,
+            headers: this.buildHeaders(headers),
+            ...config,
+        });
+        return response.data;
+    }
+    // Auth and utilities
+    login(data) {
+        return this.request('POST', '/api/v1/login', { data });
+    }
+    createAccount(data) {
+        return this.request('POST', '/api/v1/create-account', { data });
+    }
+    getTestStatus() {
+        return this.request('GET', '/api/v1/test');
+    }
+    // Company
+    listCompanies(params) {
+        return this.request('GET', '/api/v1/company', { params });
+    }
+    createCompany(data) {
+        return this.request('POST', '/api/v1/company', { data });
+    }
+    updateCompany(data) {
+        return this.request('PUT', '/api/v1/company', { data });
+    }
+    getCompany(companyId) {
+        return this.request('GET', `/api/v1/company/${companyId}`);
+    }
+    listCompanyBranches(params) {
+        return this.request('GET', '/api/v1/company/branch', { params });
+    }
+    createCompanyBranch(data) {
+        return this.request('POST', '/api/v1/company/branch', { data });
+    }
+    updateCompanyBranch(data) {
+        return this.request('PUT', '/api/v1/company/branch', { data });
+    }
+    getCompanyFinance() {
+        return this.request('GET', '/api/v1/company/finance');
+    }
+    getCompanyTaxInfo() {
+        return this.request('GET', '/api/v1/company/tax-info');
+    }
+    // Data/Reference
+    getPaymentModes() {
+        return this.request('GET', '/api/v1/data/payment-mode');
+    }
+    getProductCategories() {
+        return this.request('GET', '/api/v1/data/product-category');
+    }
+    getProductClasses() {
+        return this.request('GET', '/api/v1/data/product-class');
+    }
+    getProductCountryOrigins() {
+        return this.request('GET', '/api/v1/data/product-country-origin');
+    }
+    getProductPackagingUnits() {
+        return this.request('GET', '/api/v1/data/product-packaging-unit');
+    }
+    getProductQuantityUnits() {
+        return this.request('GET', '/api/v1/data/product-quantity-unit');
+    }
+    getProductTaxes() {
+        return this.request('GET', '/api/v1/data/product-tax');
+    }
+    getProductTypes() {
+        return this.request('GET', '/api/v1/data/product-type');
+    }
+    // Party
+    listParties(params) {
+        return this.request('GET', '/api/v1/party', { params });
+    }
+    createCustomer(data) {
+        return this.request('POST', '/api/v1/party/new-customer', { data });
+    }
+    createSupplier(data) {
+        return this.request('POST', '/api/v1/party/new-supplier', { data });
+    }
+    // Expense
+    listExpenses(params) {
+        return this.request('GET', '/api/v1/expense', { params });
+    }
+    createExpense(data) {
+        return this.request('POST', '/api/v1/expense', { data });
+    }
+    getExpenseCategories() {
+        return this.request('GET', '/api/v1/expense/categories');
+    }
+    // Insurance
+    listInsurances() {
+        return this.request('GET', '/api/v1/insurance');
+    }
+    createPresetInsurance(data) {
+        return this.request('POST', '/api/v1/insurance/preset', { data });
+    }
+    createCustomInsurance(data) {
+        return this.request('POST', '/api/v1/insurance/custom', { data });
+    }
+    updateCustomInsurance(insuranceId, data) {
+        return this.request('PUT', `/api/v1/insurance/custom/${insuranceId}`, { data });
+    }
+    updateBranchInsurance(companyInsuranceId, data) {
+        return this.request('PUT', `/api/v1/insurance/branch/${companyInsuranceId}`, {
+            data,
+        });
+    }
+    // Patient
+    listPatients(params) {
+        return this.request('GET', '/api/v1/patient', { params });
+    }
+    createPatient(data) {
+        return this.request('POST', '/api/v1/patient', { data });
+    }
+    getPatient(patientId) {
+        return this.request('GET', `/api/v1/patient/${patientId}`);
+    }
+    updatePatient(patientId, data) {
+        return this.request('PUT', `/api/v1/patient/${patientId}`, { data });
+    }
+    getPatientByParty(partyId) {
+        return this.request('GET', `/api/v1/patient/party/${partyId}`);
+    }
+    // Product
+    createProduct(data) {
+        return this.request('POST', '/api/v1/product', { data });
+    }
+    listBranchProducts(params) {
+        return this.request('GET', '/api/v1/product/branch', { params });
+    }
+    getProduct(productId) {
+        return this.request('GET', `/api/v1/product/${productId}`);
+    }
+    updateProduct(productId, data) {
+        return this.request('PUT', `/api/v1/product/${productId}`, { data });
+    }
+    increaseProductQuantity(productId, data) {
+        return this.request('PUT', `/api/v1/product/increase-quantity/${productId}`, { data });
+    }
+    reduceProductQuantity(productId, data) {
+        return this.request('PUT', `/api/v1/product/reduce-quantity/${productId}`, { data });
+    }
+    // Transaction
+    listTransactions(params) {
+        return this.request('GET', '/api/v1/transaction', { params });
+    }
+    calculateTransaction(data) {
+        return this.request('POST', '/api/v1/transaction/calculate', { data });
+    }
+    createSaleTransaction(data) {
+        return this.request('POST', '/api/v1/transaction/sale', { data });
+    }
+    createPurchaseTransaction(data) {
+        return this.request('POST', '/api/v1/transaction/purchase', { data });
+    }
+    createProformaTransaction(data) {
+        return this.request('POST', '/api/v1/transaction/proforma', { data });
+    }
+    createRefundTransaction(transactionId, data) {
+        return this.request('POST', `/api/v1/transaction/refund/${transactionId}`, { data });
+    }
+    getTransaction(transactionId, params) {
+        return this.request('GET', `/api/v1/transaction/${transactionId}`, { params });
+    }
+    getTransactionDownloadSignature(transactionId, params) {
+        return this.request('GET', `/api/v1/transaction/download-signature/${transactionId}`, {
+            params,
+        });
+    }
+    downloadTransaction(params) {
+        return this.request('GET', '/api/v1/transaction/download', { params });
+    }
+}
+exports.ZataClient = ZataClient;
+exports.default = ZataClient;

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "zata-vsdc-sdk",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "TypeScript SDK for Zata API – E-Invoicing & Tax Compliance (Rwanda)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "homepage": "https://zata.rw",
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "npm run build"
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "npm run build && npm test"
   },
   "keywords": [
     "zata",
@@ -38,4 +39,4 @@
     "access": "public"
   },
   "readme": "README.md"
-}
+}