zata-vsdc-sdk 1.1.0 → 1.1.2

package/README.md

@@ -1,108 +1,303 @@
 # 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/)
 
-TypeScript SDK for the Zata API, aligned with the latest OpenAPI documentation.
+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.
 
-## Installation
+## Why use this SDK
+
+- 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
+
+## Install
 
 ```bash
 npm install zata-vsdc-sdk
 ```
 
-## Initialize Client
+Or with yarn:
+
+```bash
+yarn add zata-vsdc-sdk
+```
+
+Or with pnpm:
+
+```bash
+pnpm add zata-vsdc-sdk
+```
+
+## Quick start
 
 ```ts
 import { ZataClient } from "zata-vsdc-sdk";
 
 const client = new ZataClient({
+  // token is preferred. apiKey is also supported as an alias.
   token: process.env.ZATA_TOKEN,
   companyId: 1,
   branchId: 1,
-  baseUrl: "https://api.zata.rw",
+  baseUrl: "https://api.zata.rw", // default (direct)
+  // baseUrl: "https://proxy.zata.rw", // optional gateway/proxy base
+  timeout: 30000,                 // default
 });
+
+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 };
+}
 ```
 
-`apiKey` is still accepted as an alias for `token`.
+## JavaScript (CommonJS)
 
-## Quick Start
+```js
+const { ZataClient } = require("zata-vsdc-sdk");
 
-```ts
-// 1) Login (if you do not have a token yet)
-const auth = await client.login({
-  email: "user@example.com",
-  password: "your-password",
+const client = new ZataClient({
+  token: process.env.ZATA_TOKEN,
+  companyId: 1,
+  branchId: 1,
 });
 
-// 2) Reference data
-const paymentModes = await client.getPaymentModes();
-const productTaxes = await client.getProductTaxes();
-
-// 3) Create parties/products
-await client.createCustomer({
-  name: "John Doe",
-  phone: "0780000000",
-  email: "john@example.com",
-  tin: "123456789",
-  address: "Kigali",
-  hasInsurance: "no",
-});
+client
+  .listTransactions({ page: 1, perPage: 20 })
+  .then((res) => console.log(res))
+  .catch((err) => console.error(err.message));
+```
+
+## Authentication and context
+
+Most business endpoints need:
+
+- `Authorization: Bearer <token>`
+- `companyId`
+- `branchId`
+
+You can define these once at client creation, then update later when needed:
+
+```ts
+client.setContext({ companyId: 2, branchId: 7 });
+client.setToken("new-token-value");
+```
+
+## End-to-end implementation flow
+
+Recommended sequence for most integrators:
+
+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
+
+This mirrors the practical order required by dependent IDs across endpoints.
+
+## API reference (SDK methods)
+
+### Auth and utility
 
-await client.createProduct({
-  name: "Service Item",
-  packagingUnitID: 1,
-  quantityUnitID: 1,
-  countryID: 1,
-  taxID: 1,
-  branchProductCategoryID: 1,
-  hasStock: "yes",
+- `login(data)`
+- `createAccount(data)`
+- `getTestStatus()`
+
+### Company and branches
+
+- `listCompanies(params?)`
+- `getCompany(companyId)`
+- `createCompany(data)`
+- `updateCompany(data)`
+- `listCompanyBranches(params?)`
+- `createCompanyBranch(data)`
+- `updateCompanyBranch(data)`
+- `getCompanyFinance()`
+- `getCompanyTaxInfo()`
+
+### Reference data
+
+- `getPaymentModes()`
+- `getProductCategories()`
+- `getProductClasses()`
+- `getProductCountryOrigins()`
+- `getProductPackagingUnits()`
+- `getProductQuantityUnits()`
+- `getProductTaxes()`
+- `getProductTypes()`
+
+### Parties
+
+- `listParties(params?)`
+- `createCustomer(data)`
+- `createSupplier(data)`
+
+### Products
+
+- `createProduct(data)`
+- `listBranchProducts(params?)`
+- `getProduct(productId)`
+- `updateProduct(productId, data)`
+- `increaseProductQuantity(productId, data)`
+- `reduceProductQuantity(productId, data)`
+
+### Expenses
+
+- `listExpenses(params?)`
+- `createExpense(data)`
+- `getExpenseCategories()`
+
+### Insurance
+
+- `listInsurances()`
+- `createPresetInsurance(data)`
+- `createCustomInsurance(data)`
+- `updateCustomInsurance(insuranceId, data)`
+- `updateBranchInsurance(companyInsuranceId, data)`
+
+### Patients
+
+- `listPatients(params?)`
+- `createPatient(data)`
+- `getPatient(patientId)`
+- `updatePatient(patientId, data)`
+- `getPatientByParty(partyId)`
+
+### Transactions
+
+- `listTransactions(params?)`
+- `calculateTransaction(data)`
+- `createSaleTransaction(data)`
+- `createPurchaseTransaction(data)`
+- `createProformaTransaction(data)`
+- `createRefundTransaction(transactionId, data)`
+- `getTransaction(transactionId, params?)`
+- `getTransactionDownloadSignature(transactionId, params?)`
+- `downloadTransaction(params)`
+
+## Transaction examples
+
+### Calculate before create
+
+```bash
+const calc = await client.calculateTransaction({
+  items: [
+    { productID: 1, units: 2, unitPrice: 1000, discountRate: 5, batchNumber: "B-001" }
+  ]
 });
+```
 
-// 4) Create sale transaction
-await client.createSaleTransaction({
+### Create sale
+
+```ts
+const sale = await client.createSaleTransaction({
   paymentMethodID: 1,
-  transactionDate: "2026-01-01",
-  items: [{ productID: 1, units: 1, unitPrice: 1000, discountRate: 0 }],
+  customerID: 1,
+  transactionDate: "2026-04-01",
+  note: "Sale from SDK",
+  items: [{ productID: 1, units: 2, unitPrice: 1000, discountRate: 0 }],
 });
 ```
 
-## API Coverage
+### Download invoice PDF
 
-The SDK exposes methods for all paths in the current OpenAPI spec, including:
-
-- 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`
+```ts
+const signature = await client.getTransactionDownloadSignature(123, { downloadSize: "A4" });
 
-## Context and Headers
+const pdf = await client.downloadTransaction({
+  expires: signature.expires,
+  id: signature.id,
+  signature: signature.signature,
+});
+```
 
-The client automatically attaches:
+## Error handling
 
-- `Authorization: Bearer <token>` (when token/apiKey provided)
-- `companyId` header (when set)
-- `branchId` header (when set)
+The client throws normalized errors in this format:
 
-You can update context at runtime:
+- `Zata API Error <status>: <response-json>`
+- `Network/Request Error: <message>`
 
 ```ts
-client.setContext({ companyId: 2, branchId: 3 });
-client.setToken("new-token-value");
+try {
+  await client.getTransaction(999999);
+} catch (error) {
+  console.error(error.message);
+}
 ```
 
-## Scripts
+## 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
+
+## Development
 
 ```bash
+npm install
 npm run build
 npm test
 ```
 
-## Resources
+## API docs & base URLs
+
+- Taxes docs: [https://docs.zata.rw](https://docs.zata.rw)
+- Unified gateway docs: [https://proxy.zata.rw/api/v1/docs](https://proxy.zata.rw/api/v1/docs)
+- Direct taxes base URL: `https://api.zata.rw`
+- Gateway base URL (taxes under `/api/v1/*`): `https://proxy.zata.rw`
+
+## 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)
+
+## Support
+
+- Email: `hirwa@hiq.africa`
+- Issues: [https://github.com/HiQ-Africa/zata-npm/issues](https://github.com/HiQ-Africa/zata-npm/issues)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zata-vsdc-sdk",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "TypeScript SDK for Zata API – E-Invoicing & Tax Compliance (Rwanda)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",