zata-vsdc-sdk 1.0.2 → 1.1.0

package/README.md

@@ -1,17 +1,108 @@
 # zata-vsdc-sdk
 
-TypeScript SDK for Zata API – E-Invoicing & Tax Compliance (Rwanda)
+[![npm version](https://img.shields.io/npm/v/zata-vsdc-sdk.svg)](https://www.npmjs.com/package/zata-vsdc-sdk)
 
-**Installation Guide:** [https://zata.lovable.app](https://zata.lovable.app)
+TypeScript SDK for the Zata API, aligned with the latest OpenAPI documentation.
 
-**Official Website:** [https://zata.rw](https://zata.rw)
-**API Documentation:** [https://docs.zata.rw](https://docs.zata.rw)
-**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
 
-Zata provides a developer-friendly REST API for Rwanda Revenue Authority (RRA) compliant e-invoicing, EBM/VSDC integration, real-time transaction validation, signed PDFs, and more. This SDK simplifies integration with full TypeScript support.
+```bash
+npm install zata-vsdc-sdk
+```
 
-## Installation
+## Initialize Client
+
+```ts
+import { ZataClient } from "zata-vsdc-sdk";
+
+const client = new ZataClient({
+  token: process.env.ZATA_TOKEN,
+  companyId: 1,
+  branchId: 1,
+  baseUrl: "https://api.zata.rw",
+});
+```
+
+`apiKey` is still accepted as an alias for `token`.
+
+## Quick Start
+
+```ts
+// 1) Login (if you do not have a token yet)
+const auth = await client.login({
+  email: "user@example.com",
+  password: "your-password",
+});
+
+// 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",
+});
+
+await client.createProduct({
+  name: "Service Item",
+  packagingUnitID: 1,
+  quantityUnitID: 1,
+  countryID: 1,
+  taxID: 1,
+  branchProductCategoryID: 1,
+  hasStock: "yes",
+});
+
+// 4) Create sale transaction
+await client.createSaleTransaction({
+  paymentMethodID: 1,
+  transactionDate: "2026-01-01",
+  items: [{ productID: 1, units: 1, unitPrice: 1000, discountRate: 0 }],
+});
+```
+
+## API Coverage
+
+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`
+
+## Context and Headers
+
+The client automatically attaches:
+
+- `Authorization: Bearer <token>` (when token/apiKey provided)
+- `companyId` header (when set)
+- `branchId` header (when set)
+
+You can update context at runtime:
+
+```ts
+client.setContext({ companyId: 2, branchId: 3 });
+client.setToken("new-token-value");
+```
+
+## Scripts
 
 ```bash
-npm install zata-vsdc-sdk
+npm run build
+npm test
+```
+
+## Resources
+
+- 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.2",
+  "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"
-}
+}