@ripwords/myinvois-client 0.0.10 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+
+## v0.1.2
+
+[compare changes](https://github.com/Ripwords/MyInvoisClient/compare/v0.1.1...v0.1.2)
+
+### 🚀 Enhancements
+
+- Introduce RegistrationType type and update registrationType fields in Supplier and Buyer interfaces for improved type safety ([28bcd5b](https://github.com/Ripwords/MyInvoisClient/commit/28bcd5b))
+- Consolidate and expand invoice type definitions by merging index.ts into index.d.ts, enhancing type safety and clarity across various invoice-related interfaces ([e8ba3f9](https://github.com/Ripwords/MyInvoisClient/commit/e8ba3f9))
+
+### 💅 Refactors
+
+- Update type exports by removing the deprecated index.d.ts file and directly exporting from documents.d.ts to streamline type definitions and improve clarity ([b5fcd79](https://github.com/Ripwords/MyInvoisClient/commit/b5fcd79))
+- Streamline invoice type definitions by removing unused fields and enhancing clarity in the documents.d.ts and document.ts files, while updating tests to reflect these changes ([834bb63](https://github.com/Ripwords/MyInvoisClient/commit/834bb63))
+
+### 🏡 Chore
+
+- Enhance release script to run linting before building and publishing ([230e15c](https://github.com/Ripwords/MyInvoisClient/commit/230e15c))
+
+### ❤️ Contributors
+
+- JJ <teohjjteoh@gmail.com>
+
+## v0.1.1
+
+
+### 🚀 Enhancements
+
+- First commit ([c03ee2c](https://github.com/Ripwords/MyInvoisClient/commit/c03ee2c))
+- Add docs ([cb80529](https://github.com/Ripwords/MyInvoisClient/commit/cb80529))
+- Add base64 encoding utility ([51cbad8](https://github.com/Ripwords/MyInvoisClient/commit/51cbad8))
+- Add XML-related dependencies and update rolldown config for external modules ([5237aad](https://github.com/Ripwords/MyInvoisClient/commit/5237aad))
+- Add support for new XML processing features and enhance rolldown configuration for better module handling ([a492bb8](https://github.com/Ripwords/MyInvoisClient/commit/a492bb8))
+- Populate signed properties (step 6) ([87397b1](https://github.com/Ripwords/MyInvoisClient/commit/87397b1))
+- Implement new XML processing enhancements and refine rolldown configuration for improved module management ([d1b4455](https://github.com/Ripwords/MyInvoisClient/commit/d1b4455))
+- Document signature implementation ([b42604c](https://github.com/Ripwords/MyInvoisClient/commit/b42604c))
+- Add debugDocumentHash and testSubmissionHashMethods functions for validating document hash calculations ([b0921ac](https://github.com/Ripwords/MyInvoisClient/commit/b0921ac))
+- Expand invoice type definitions with InvoiceSubmission and SignedInvoiceSubmission interfaces, enhance document generation utilities to support new structures, and improve type safety in signature handling ([eae4ed7](https://github.com/Ripwords/MyInvoisClient/commit/eae4ed7))
+
+### 🩹 Fixes
+
+- Update release script in package.json to use bun run for building ([d41b5d3](https://github.com/Ripwords/MyInvoisClient/commit/d41b5d3))
+- Update release script in package.json to include public access for npm publish ([36c4e14](https://github.com/Ripwords/MyInvoisClient/commit/36c4e14))
+
+### 💅 Refactors
+
+- Update rolldown.config.ts to support multiple output formats and entry file naming ([eacd967](https://github.com/Ripwords/MyInvoisClient/commit/eacd967))
+- Update MyInvoisClient to use taxpayerLogin for token management and remove redundant TokenResponse interface; delete obsolete test file ([4844b2c](https://github.com/Ripwords/MyInvoisClient/commit/4844b2c))
+- Simplify UnitTypeCode definition by replacing hardcoded values with imports from unit-specific modules ([62484e3](https://github.com/Ripwords/MyInvoisClient/commit/62484e3))
+- Update unit type imports to include .d.ts extensions for better type resolution ([db2ea18](https://github.com/Ripwords/MyInvoisClient/commit/db2ea18))
+- Remove taxpayerLogin function and update MyInvoisClient to use platformLogin; add optional onBehalfOf parameter to ClientCredentials ([790ea53](https://github.com/Ripwords/MyInvoisClient/commit/790ea53))
+- Enhance PEM certificate handling by adding validation for Base64 content and improving error messages ([9d9d8ae](https://github.com/Ripwords/MyInvoisClient/commit/9d9d8ae))
+- Remove unused imports related to Document and Node types from xmldom-ts in signature utility files ([15ae5bb](https://github.com/Ripwords/MyInvoisClient/commit/15ae5bb))
+- Remove debug logging from populateFinalDocument function in signature utility ([980b322](https://github.com/Ripwords/MyInvoisClient/commit/980b322))
+- Update verifyTin method to support multiple ID types and improve parameter naming for clarity ([3d09585](https://github.com/Ripwords/MyInvoisClient/commit/3d09585))
+- Initialize tokenExpiration to undefined and enhance token validation logic in MyInvoisClient ([a7edd3e](https://github.com/Ripwords/MyInvoisClient/commit/a7edd3e))
+- Remove unnecessary ts-ignore for private method call in MyInvoisClientWithBRN test ([c04ea76](https://github.com/Ripwords/MyInvoisClient/commit/c04ea76))
+- Update MSIC code types and integrate into invoice supplier interface ([f28fa71](https://github.com/Ripwords/MyInvoisClient/commit/f28fa71))
+- Enhance hashSignedProperties function to support optional canonicalization algorithm and add fallback for C14N 1.1 ([b7d693b](https://github.com/Ripwords/MyInvoisClient/commit/b7d693b))
+- Add registrationType field to Supplier interface in invoice-1_1.d.ts ([225ffeb](https://github.com/Ripwords/MyInvoisClient/commit/225ffeb))
+- Enhance canonicalization process in canonicalizeAndHashDocument function with optional algorithm support and fallback for C14N 1.1 ([41a5570](https://github.com/Ripwords/MyInvoisClient/commit/41a5570))
+- Restructure invoice1-1.ts for improved readability and maintainability; add XML minification and error handling in document hash generation ([9df51cb](https://github.com/Ripwords/MyInvoisClient/commit/9df51cb))
+- Update canonicalization algorithm URIs in signature utilities to use C14N 1.1 and ensure proper fallback handling ([20e375a](https://github.com/Ripwords/MyInvoisClient/commit/20e375a))
+- Remove unused MyInvoisClient and invoice1-1 utility files, update tsconfig.json to improve type declaration settings, and enhance invoice-1_1 type definitions with additional fields for better clarity ([2bbe651](https://github.com/Ripwords/MyInvoisClient/commit/2bbe651))
+
+### 🏡 Chore
+
+- Update package.json with new name, version, description, and main entry point ([b952d5a](https://github.com/Ripwords/MyInvoisClient/commit/b952d5a))
+- Update package.json to add rolldown and rolldown-plugin-dts as devDependencies ([1322bac](https://github.com/Ripwords/MyInvoisClient/commit/1322bac))
+- Add release script to package.json ([7ab378d](https://github.com/Ripwords/MyInvoisClient/commit/7ab378d))
+- Bump version to 0.0.2 in package.json ([863187a](https://github.com/Ripwords/MyInvoisClient/commit/863187a))
+- Bump version to 0.0.4 in package.json and add dotenv as a devDependency; update rolldown output directory and enable sourcemaps ([a53bc25](https://github.com/Ripwords/MyInvoisClient/commit/a53bc25))
+- Bump version to 0.0.5 in package.json; update ofetch import path in MyInvoisClient and tests ([c5ef1d3](https://github.com/Ripwords/MyInvoisClient/commit/c5ef1d3))
+- Bump version to 0.0.6 in package.json; remove ofetch dependency and update MyInvoisClient to use fetch; add dotenv setup in vitest.config.ts ([4b73f11](https://github.com/Ripwords/MyInvoisClient/commit/4b73f11))
+- Bump version to 0.0.7 in package.json; add exports field and update rolldown output directory; enhance MyInvoisClient with debug option ([7bfa137](https://github.com/Ripwords/MyInvoisClient/commit/7bfa137))
+- Organise package.json fields ([94afac0](https://github.com/Ripwords/MyInvoisClient/commit/94afac0))
+- Bump version to 0.0.8 in package.json; update rolldown-plugin-dts and typescript dependencies; remove git push from release script ([04fc74c](https://github.com/Ripwords/MyInvoisClient/commit/04fc74c))
+- Bump version to 0.0.9 in package.json; add clean script using rimraf; update rolldown config for isolated declaration; fix import path in MyInvoisClient ([f820113](https://github.com/Ripwords/MyInvoisClient/commit/f820113))
+- Bump version to 0.0.10 in package.json ([0baa610](https://github.com/Ripwords/MyInvoisClient/commit/0baa610))
+- Add @vitest/coverage-v8 dependency to package.json and bun.lock for improved test coverage reporting ([02c11da](https://github.com/Ripwords/MyInvoisClient/commit/02c11da))
+- Add *.pem to .gitignore to exclude PEM files from version control ([f86ad14](https://github.com/Ripwords/MyInvoisClient/commit/f86ad14))
+- Update dependencies in package.json and bun.lock to include xml-crypto and related packages ([48539ea](https://github.com/Ripwords/MyInvoisClient/commit/48539ea))
+- Update package version to 0.0.11, add crypto dependency, and adjust type imports for improved clarity ([1b78281](https://github.com/Ripwords/MyInvoisClient/commit/1b78281))
+- Remove rolldown and related dependencies, update build script to use tsdown, and enhance type definitions for better clarity and maintainability ([6c06af9](https://github.com/Ripwords/MyInvoisClient/commit/6c06af9))
+- Bump package version to 0.1.0 for release readiness ([8b75664](https://github.com/Ripwords/MyInvoisClient/commit/8b75664))
+- Update .gitignore to exclude *.conf files, enhance release script to include changelog generation, and expand README with detailed installation and testing instructions for MyInvois client ([ca968bc](https://github.com/Ripwords/MyInvoisClient/commit/ca968bc))
+- Add changelogen dependency for automated changelog generation ([3c6592e](https://github.com/Ripwords/MyInvoisClient/commit/3c6592e))
+
+### ✅ Tests
+
+- Skip MyInvoisClient tests if required environment variables are missing; use hardcoded values for TIN and NRIC in tests ([3200a8e](https://github.com/Ripwords/MyInvoisClient/commit/3200a8e))
+- Improve handling of potential canonicalization failures in canonicalizeAndHashDocument test ([16d3f58](https://github.com/Ripwords/MyInvoisClient/commit/16d3f58))
+
+### ❤️ Contributors
+
+- JJ <teohjjteoh@gmail.com>
+

package/README.md

@@ -1,15 +1,139 @@
-# e-invoice-client
+# MyInvois Client
 
-To install dependencies:
+A comprehensive Node.js client for Malaysia's MyInvois e-invoicing system with full digital signature support.
+
+## Installation
 
 ```bash
 bun install
 ```
 
-To run:
+## Environment Variables
+
+Create a `.env` file in the project root with your MyInvois credentials:
+
+```bash
+# MyInvois API Credentials (from MyInvois portal)
+CLIENT_ID=your_client_id_here
+CLIENT_SECRET=your_client_secret_here
+
+# Your Certificate and Private Key (PEM format)
+TEST_CERTIFICATE="-----BEGIN CERTIFICATE-----
+your_certificate_content_here
+-----END CERTIFICATE-----"
+
+TEST_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
+your_private_key_content_here
+-----END PRIVATE KEY-----"
+
+# Your MyInvois TIN (Tax Identification Number)
+TIN_VALUE=IG12345678901
+
+# Your NRIC/Business Registration Number
+NRIC_VALUE=123456789012
+
+# Additional test TINs for comprehensive testing
+TEST_TIN_1=C12345678901
+TEST_TIN_2=C98765432109
+TEST_TIN_3=IG98765432109
+
+# Test buyer information
+BUYER_TIN_VALUE=IG00000000000
+BUYER_NRIC_VALUE=000000000000
+```
+
+⚠️ **Important**: Never commit your actual TIN, NRIC, certificates, or API credentials to version control.
+
+## Testing
 
 ```bash
-bun run index.ts
+bun test
+```
+
+## Generating Test Certificates for Development
+
+For testing purposes, you can generate self-signed certificates with MyInvois-required fields:
+
+### 1. Create Certificate Configuration
+
+Create `myinvois-cert.conf`:
+
+```ini
+[req]
+distinguished_name = req_distinguished_name
+req_extensions = v3_req
+prompt = no
+
+[req_distinguished_name]
+C = MY
+ST = YOUR_STATE
+L = YOUR_CITY
+O = YOUR_COMPANY_NAME
+CN = YOUR_COMPANY_NAME
+emailAddress = YOUR_EMAIL
+serialNumber = YOUR_BUSINESS_REGISTRATION_NUMBER
+
+[v3_req]
+keyUsage = keyEncipherment, dataEncipherment, digitalSignature, nonRepudiation
+extendedKeyUsage = clientAuth, emailProtection
+subjectAltName = @alt_names
+
+[alt_names]
+email.1 = YOUR_EMAIL
+DNS.1 = YOUR_DOMAIN
 ```
 
+### 2. Generate Private Key
+
+```bash
+openssl genrsa -out myinvois-test-key.pem 2048
+```
+
+### 3. Generate Certificate with Required MyInvois Fields
+
+```bash
+# Basic certificate with SERIALNUMBER
+openssl req -new -x509 -key myinvois-test-key.pem -out myinvois-test-cert.pem -days 365 -config myinvois-cert.conf
+
+# Enhanced certificate with organizationIdentifier (OI) field for TIN
+openssl req -new -x509 -key myinvois-test-key.pem -out myinvois-enhanced-cert.pem -days 365 \
+  -subj "/C=MY/ST=YOUR_STATE/L=YOUR_CITY/O=YOUR_COMPANY_NAME/CN=YOUR_COMPANY_NAME/serialNumber=YOUR_BUSINESS_REG/2.5.4.97=YOUR_TIN/emailAddress=YOUR_EMAIL"
+```
+
+### 4. Verify Certificate Fields
+
+```bash
+# Check certificate details
+openssl x509 -in myinvois-enhanced-cert.pem -text -noout | grep -A 2 -B 2 "Subject:"
+
+# Should show both:
+# serialNumber=YOUR_BUSINESS_REG
+# organizationIdentifier=YOUR_TIN
+```
+
+## Example Values
+
+Replace the placeholders with your actual values:
+
+- `YOUR_STATE`: `Kuala Lumpur`
+- `YOUR_CITY`: `Kuala Lumpur` 
+- `YOUR_COMPANY_NAME`: `My Company Sdn Bhd`
+- `YOUR_EMAIL`: `admin@mycompany.com`
+- `YOUR_BUSINESS_REG`: `202301234567` (SSM registration)
+- `YOUR_TIN`: `IG12345678901` (MyInvois TIN)
+- `YOUR_DOMAIN`: `mycompany.com`
+
+## Production Certificates
+
+⚠️ **For production use, obtain official business certificates from MyInvois-approved Certificate Authorities:**
+
+- **MSC Trustgate**: https://www.msctrustgate.com/
+- **Digicert Sdn Bhd**
+- **Cybersign Asia**
+
+The certificate must include:
+- `organizationIdentifier` field with your TIN
+- `SERIALNUMBER` field with your business registration number
+- Issued by a MyInvois-trusted CA
+
 This project was created using `bun init` in bun v1.2.10. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.