zata-vsdc-sdk 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +245 -58
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,108 +1,295 @@
1
1
  # zata-vsdc-sdk
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/zata-vsdc-sdk.svg)](https://www.npmjs.com/package/zata-vsdc-sdk)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
+ [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
4
6
 
5
- TypeScript SDK for the Zata API, aligned with the latest OpenAPI documentation.
7
+ A production-friendly TypeScript/JavaScript SDK for the Zata API.
8
+ Built for Rwanda e-invoicing and tax-compliance workflows: companies, branches, parties, products, expenses, transactions, insurance, patient flows, and signed invoice downloads.
6
9
 
7
- ## Installation
10
+ ## Why use this SDK
11
+
12
+ - Fast onboarding to the Zata API with a single client
13
+ - Automatic `Authorization`, `companyId`, and `branchId` header handling
14
+ - Clean method names that map directly to documented API actions
15
+ - Works in both TypeScript and JavaScript projects
16
+ - Built-in request error formatting for faster debugging
17
+
18
+ ## Install
8
19
 
9
20
  ```bash
10
21
  npm install zata-vsdc-sdk
11
22
  ```
12
23
 
13
- ## Initialize Client
24
+ Or with yarn:
25
+
26
+ ```bash
27
+ yarn add zata-vsdc-sdk
28
+ ```
29
+
30
+ Or with pnpm:
31
+
32
+ ```bash
33
+ pnpm add zata-vsdc-sdk
34
+ ```
35
+
36
+ ## Quick start
14
37
 
15
38
  ```ts
16
39
  import { ZataClient } from "zata-vsdc-sdk";
17
40
 
18
41
  const client = new ZataClient({
42
+ // token is preferred. apiKey is also supported as an alias.
19
43
  token: process.env.ZATA_TOKEN,
20
44
  companyId: 1,
21
45
  branchId: 1,
22
- baseUrl: "https://api.zata.rw",
46
+ baseUrl: "https://api.zata.rw", // default
47
+ timeout: 30000, // default
23
48
  });
49
+
50
+ async function run() {
51
+ // 1) Pull reference data
52
+ const paymentModes = await client.getPaymentModes();
53
+ const taxes = await client.getProductTaxes();
54
+
55
+ // 2) Create a customer
56
+ await client.createCustomer({
57
+ name: "John Doe",
58
+ address: "Kigali",
59
+ phone: "0780000000",
60
+ email: "john@example.com",
61
+ tin: "123456789",
62
+ hasInsurance: "no",
63
+ });
64
+
65
+ // 3) Create a product
66
+ await client.createProduct({
67
+ name: "Service Item",
68
+ packagingUnitID: 1,
69
+ quantityUnitID: 1,
70
+ countryID: 1,
71
+ taxID: 1,
72
+ branchProductCategoryID: 1,
73
+ hasStock: "yes",
74
+ });
75
+
76
+ // 4) Create a sale transaction
77
+ const sale = await client.createSaleTransaction({
78
+ paymentMethodID: 1,
79
+ transactionDate: "2026-01-01",
80
+ items: [{ productID: 1, units: 1, unitPrice: 1000, discountRate: 0 }],
81
+ });
82
+
83
+ return { paymentModes, taxes, sale };
84
+ }
24
85
  ```
25
86
 
26
- `apiKey` is still accepted as an alias for `token`.
87
+ ## JavaScript (CommonJS)
27
88
 
28
- ## Quick Start
89
+ ```js
90
+ const { ZataClient } = require("zata-vsdc-sdk");
29
91
 
30
- ```ts
31
- // 1) Login (if you do not have a token yet)
32
- const auth = await client.login({
33
- email: "user@example.com",
34
- password: "your-password",
92
+ const client = new ZataClient({
93
+ token: process.env.ZATA_TOKEN,
94
+ companyId: 1,
95
+ branchId: 1,
35
96
  });
36
97
 
37
- // 2) Reference data
38
- const paymentModes = await client.getPaymentModes();
39
- const productTaxes = await client.getProductTaxes();
40
-
41
- // 3) Create parties/products
42
- await client.createCustomer({
43
- name: "John Doe",
44
- phone: "0780000000",
45
- email: "john@example.com",
46
- tin: "123456789",
47
- address: "Kigali",
48
- hasInsurance: "no",
49
- });
98
+ client
99
+ .listTransactions({ page: 1, perPage: 20 })
100
+ .then((res) => console.log(res))
101
+ .catch((err) => console.error(err.message));
102
+ ```
103
+
104
+ ## Authentication and context
105
+
106
+ Most business endpoints need:
107
+
108
+ - `Authorization: Bearer <token>`
109
+ - `companyId`
110
+ - `branchId`
111
+
112
+ You can define these once at client creation, then update later when needed:
113
+
114
+ ```ts
115
+ client.setContext({ companyId: 2, branchId: 7 });
116
+ client.setToken("new-token-value");
117
+ ```
118
+
119
+ ## End-to-end implementation flow
120
+
121
+ Recommended sequence for most integrators:
122
+
123
+ 1. Authenticate (`login`) and set token
124
+ 2. Validate company and branch (`getCompany`, `listCompanyBranches`)
125
+ 3. Fetch reference data (`getPaymentModes`, product tax/unit/category lookups)
126
+ 4. Create parties (`createCustomer`, `createSupplier`)
127
+ 5. Create products (`createProduct`)
128
+ 6. Create expense and transactions
129
+ 7. Retrieve transaction PDF signature and download invoice
130
+
131
+ This mirrors the practical order required by dependent IDs across endpoints.
132
+
133
+ ## API reference (SDK methods)
50
134
 
51
- await client.createProduct({
52
- name: "Service Item",
53
- packagingUnitID: 1,
54
- quantityUnitID: 1,
55
- countryID: 1,
56
- taxID: 1,
57
- branchProductCategoryID: 1,
58
- hasStock: "yes",
135
+ ### Auth and utility
136
+
137
+ - `login(data)`
138
+ - `createAccount(data)`
139
+ - `getTestStatus()`
140
+
141
+ ### Company and branches
142
+
143
+ - `listCompanies(params?)`
144
+ - `getCompany(companyId)`
145
+ - `createCompany(data)`
146
+ - `updateCompany(data)`
147
+ - `listCompanyBranches(params?)`
148
+ - `createCompanyBranch(data)`
149
+ - `updateCompanyBranch(data)`
150
+ - `getCompanyFinance()`
151
+ - `getCompanyTaxInfo()`
152
+
153
+ ### Reference data
154
+
155
+ - `getPaymentModes()`
156
+ - `getProductCategories()`
157
+ - `getProductClasses()`
158
+ - `getProductCountryOrigins()`
159
+ - `getProductPackagingUnits()`
160
+ - `getProductQuantityUnits()`
161
+ - `getProductTaxes()`
162
+ - `getProductTypes()`
163
+
164
+ ### Parties
165
+
166
+ - `listParties(params?)`
167
+ - `createCustomer(data)`
168
+ - `createSupplier(data)`
169
+
170
+ ### Products
171
+
172
+ - `createProduct(data)`
173
+ - `listBranchProducts(params?)`
174
+ - `getProduct(productId)`
175
+ - `updateProduct(productId, data)`
176
+ - `increaseProductQuantity(productId, data)`
177
+ - `reduceProductQuantity(productId, data)`
178
+
179
+ ### Expenses
180
+
181
+ - `listExpenses(params?)`
182
+ - `createExpense(data)`
183
+ - `getExpenseCategories()`
184
+
185
+ ### Insurance
186
+
187
+ - `listInsurances()`
188
+ - `createPresetInsurance(data)`
189
+ - `createCustomInsurance(data)`
190
+ - `updateCustomInsurance(insuranceId, data)`
191
+ - `updateBranchInsurance(companyInsuranceId, data)`
192
+
193
+ ### Patients
194
+
195
+ - `listPatients(params?)`
196
+ - `createPatient(data)`
197
+ - `getPatient(patientId)`
198
+ - `updatePatient(patientId, data)`
199
+ - `getPatientByParty(partyId)`
200
+
201
+ ### Transactions
202
+
203
+ - `listTransactions(params?)`
204
+ - `calculateTransaction(data)`
205
+ - `createSaleTransaction(data)`
206
+ - `createPurchaseTransaction(data)`
207
+ - `createProformaTransaction(data)`
208
+ - `createRefundTransaction(transactionId, data)`
209
+ - `getTransaction(transactionId, params?)`
210
+ - `getTransactionDownloadSignature(transactionId, params?)`
211
+ - `downloadTransaction(params)`
212
+
213
+ ## Transaction examples
214
+
215
+ ### Calculate before create
216
+
217
+ ```bash
218
+ const calc = await client.calculateTransaction({
219
+ items: [
220
+ { productID: 1, units: 2, unitPrice: 1000, discountRate: 5, batchNumber: "B-001" }
221
+ ]
59
222
  });
223
+ ```
224
+
225
+ ### Create sale
60
226
 
61
- // 4) Create sale transaction
62
- await client.createSaleTransaction({
227
+ ```ts
228
+ const sale = await client.createSaleTransaction({
63
229
  paymentMethodID: 1,
64
- transactionDate: "2026-01-01",
65
- items: [{ productID: 1, units: 1, unitPrice: 1000, discountRate: 0 }],
230
+ customerID: 1,
231
+ transactionDate: "2026-04-01",
232
+ note: "Sale from SDK",
233
+ items: [{ productID: 1, units: 2, unitPrice: 1000, discountRate: 0 }],
66
234
  });
67
235
  ```
68
236
 
69
- ## API Coverage
70
-
71
- The SDK exposes methods for all paths in the current OpenAPI spec, including:
237
+ ### Download invoice PDF
72
238
 
73
- - Auth and account: `login`, `createAccount`
74
- - Company and branches: `listCompanies`, `getCompany`, `createCompany`, `updateCompany`, `listCompanyBranches`, `createCompanyBranch`, `updateCompanyBranch`, `getCompanyFinance`, `getCompanyTaxInfo`
75
- - Reference data: `getPaymentModes`, `getProductCategories`, `getProductClasses`, `getProductCountryOrigins`, `getProductPackagingUnits`, `getProductQuantityUnits`, `getProductTaxes`, `getProductTypes`
76
- - Parties: `listParties`, `createCustomer`, `createSupplier`
77
- - Product: `createProduct`, `listBranchProducts`, `getProduct`, `updateProduct`, `increaseProductQuantity`, `reduceProductQuantity`
78
- - Expense: `listExpenses`, `createExpense`, `getExpenseCategories`
79
- - Insurance: `listInsurances`, `createPresetInsurance`, `createCustomInsurance`, `updateCustomInsurance`, `updateBranchInsurance`
80
- - Patient: `listPatients`, `createPatient`, `getPatient`, `updatePatient`, `getPatientByParty`
81
- - Transactions: `listTransactions`, `calculateTransaction`, `createSaleTransaction`, `createPurchaseTransaction`, `createProformaTransaction`, `createRefundTransaction`, `getTransaction`, `getTransactionDownloadSignature`, `downloadTransaction`
239
+ ```ts
240
+ const signature = await client.getTransactionDownloadSignature(123, { downloadSize: "A4" });
82
241
 
83
- ## Context and Headers
242
+ const pdf = await client.downloadTransaction({
243
+ expires: signature.expires,
244
+ id: signature.id,
245
+ signature: signature.signature,
246
+ });
247
+ ```
84
248
 
85
- The client automatically attaches:
249
+ ## Error handling
86
250
 
87
- - `Authorization: Bearer <token>` (when token/apiKey provided)
88
- - `companyId` header (when set)
89
- - `branchId` header (when set)
251
+ The client throws normalized errors in this format:
90
252
 
91
- You can update context at runtime:
253
+ - `Zata API Error <status>: <response-json>`
254
+ - `Network/Request Error: <message>`
92
255
 
93
256
  ```ts
94
- client.setContext({ companyId: 2, branchId: 3 });
95
- client.setToken("new-token-value");
257
+ try {
258
+ await client.getTransaction(999999);
259
+ } catch (error) {
260
+ console.error(error.message);
261
+ }
96
262
  ```
97
263
 
98
- ## Scripts
264
+ ## Best practices
265
+
266
+ - Cache lookup/reference data (payment modes, taxes, units)
267
+ - Validate IDs and required fields before calling write endpoints
268
+ - Use `calculateTransaction` before creating high-value invoices
269
+ - Store entity IDs you create (party, product, transaction)
270
+ - Use retries/backoff for transient network or 5xx failures
271
+
272
+ ## Development
99
273
 
100
274
  ```bash
275
+ npm install
101
276
  npm run build
102
277
  npm test
103
278
  ```
104
279
 
105
- ## Resources
280
+ ## Links
106
281
 
107
282
  - API docs: [https://docs.zata.rw](https://docs.zata.rw)
108
283
  - Website: [https://zata.rw](https://zata.rw)
284
+ - npm: [https://www.npmjs.com/package/zata-vsdc-sdk](https://www.npmjs.com/package/zata-vsdc-sdk)
285
+ - GitHub: [https://github.com/HiQ-Africa/zata-npm](https://github.com/HiQ-Africa/zata-npm)
286
+ - Integration guide: [./guide.md](./guide.md)
287
+
288
+ ## Support
289
+
290
+ - Email: `hirwa@hiq.africa`
291
+ - Issues: [https://github.com/HiQ-Africa/zata-npm/issues](https://github.com/HiQ-Africa/zata-npm/issues)
292
+
293
+ ## License
294
+
295
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "zata-vsdc-sdk",
3
- "version": "1.1.0",
3
+ "version": "1.1.1",
4
4
  "description": "TypeScript SDK for Zata API – E-Invoicing & Tax Compliance (Rwanda)",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",