@ripwords/myinvois-client 0.0.10 → 0.1.2

package/src/utils/validation.ts

@@ -0,0 +1,268 @@
+import type { InvoiceV1_1 } from '../types/documents/index.js'
+
+/**
+ * MyInvois Invoice Validation Utilities
+ *
+ * Provides comprehensive validation for invoice data before document generation
+ * and submission to ensure compliance with MyInvois business rules and format requirements.
+ */
+
+export interface ValidationResult {
+  isValid: boolean
+  errors: ValidationError[]
+  warnings: ValidationWarning[]
+}
+
+export interface ValidationError {
+  field: string
+  code: string
+  message: string
+  severity: 'error' | 'warning'
+}
+
+export interface ValidationWarning extends ValidationError {
+  severity: 'warning'
+}
+
+/**
+ * Validates TIN format based on registration type
+ */
+export const validateTIN = (
+  tin: string,
+  registrationType?: string,
+): ValidationError[] => {
+  const errors: ValidationError[] = []
+
+  if (!tin) {
+    errors.push({
+      field: 'tin',
+      code: 'TIN_REQUIRED',
+      message: 'TIN is required',
+      severity: 'error',
+    })
+    return errors
+  }
+
+  // TIN format validation based on type
+  if (registrationType === 'BRN' && !tin.startsWith('C')) {
+    errors.push({
+      field: 'tin',
+      code: 'TIN_FORMAT_INVALID',
+      message: 'Company TIN should start with "C" for BRN registration',
+      severity: 'warning',
+    })
+  }
+
+  if (registrationType === 'NRIC' && !tin.startsWith('IG')) {
+    errors.push({
+      field: 'tin',
+      code: 'TIN_FORMAT_INVALID',
+      message: 'Individual TIN should start with "IG" for NRIC registration',
+      severity: 'warning',
+    })
+  }
+
+  // Length validation
+  if (tin.length > 14) {
+    errors.push({
+      field: 'tin',
+      code: 'TIN_LENGTH_INVALID',
+      message: 'TIN cannot exceed 14 characters',
+      severity: 'error',
+    })
+  }
+
+  return errors
+}
+
+/**
+ * Validates contact number format (E.164 standard)
+ */
+export const validateContactNumber = (
+  contactNumber: string,
+): ValidationError[] => {
+  const errors: ValidationError[] = []
+
+  if (!contactNumber || contactNumber === 'NA') {
+    return errors // Allow NA for consolidated e-invoices
+  }
+
+  // E.164 format validation
+  const e164Regex = /^\+[1-9]\d{1,14}$/
+  if (!e164Regex.test(contactNumber)) {
+    errors.push({
+      field: 'contactNumber',
+      code: 'CONTACT_FORMAT_INVALID',
+      message: 'Contact number must be in E.164 format (e.g., +60123456789)',
+      severity: 'error',
+    })
+  }
+
+  if (contactNumber.length < 8) {
+    errors.push({
+      field: 'contactNumber',
+      code: 'CONTACT_LENGTH_INVALID',
+      message: 'Contact number must be at least 8 characters',
+      severity: 'error',
+    })
+  }
+
+  return errors
+}
+
+/**
+ * Validates monetary amounts
+ */
+export const validateMonetaryAmount = (
+  amount: number,
+  fieldName: string,
+  maxDigits = 18,
+  maxDecimals = 2,
+): ValidationError[] => {
+  const errors: ValidationError[] = []
+
+  if (amount < 0) {
+    errors.push({
+      field: fieldName,
+      code: 'AMOUNT_NEGATIVE',
+      message: `${fieldName} cannot be negative`,
+      severity: 'error',
+    })
+  }
+
+  // Check total digits
+  const amountStr = amount.toString()
+  const [integerPart, decimalPart] = amountStr.split('.')
+
+  if (integerPart && integerPart.length > maxDigits - maxDecimals) {
+    errors.push({
+      field: fieldName,
+      code: 'AMOUNT_DIGITS_EXCEEDED',
+      message: `${fieldName} exceeds maximum ${maxDigits} digits`,
+      severity: 'error',
+    })
+  }
+
+  if (decimalPart && decimalPart.length > maxDecimals) {
+    errors.push({
+      field: fieldName,
+      code: 'AMOUNT_DECIMALS_EXCEEDED',
+      message: `${fieldName} exceeds maximum ${maxDecimals} decimal places`,
+      severity: 'error',
+    })
+  }
+
+  return errors
+}
+
+/**
+ * Validates tax calculation consistency
+ */
+export const validateTaxCalculations = (
+  invoice: InvoiceV1_1,
+): ValidationError[] => {
+  const errors: ValidationError[] = []
+
+  // Calculate expected totals from line items
+  const expectedTaxExclusive = invoice.invoiceLineItems.reduce(
+    (sum, item) => sum + item.totalTaxableAmountPerLine,
+    0,
+  )
+  const expectedTaxAmount = invoice.invoiceLineItems.reduce(
+    (sum, item) => sum + item.taxAmount,
+    0,
+  )
+
+  // Allow small rounding differences (0.01)
+  const tolerance = 0.01
+
+  if (
+    Math.abs(
+      invoice.legalMonetaryTotal.taxExclusiveAmount - expectedTaxExclusive,
+    ) > tolerance
+  ) {
+    errors.push({
+      field: 'legalMonetaryTotal.taxExclusiveAmount',
+      code: 'TAX_EXCLUSIVE_MISMATCH',
+      message: `Tax exclusive amount (${invoice.legalMonetaryTotal.taxExclusiveAmount}) doesn't match sum of line items (${expectedTaxExclusive})`,
+      severity: 'error',
+    })
+  }
+
+  if (Math.abs(invoice.taxTotal.taxAmount - expectedTaxAmount) > tolerance) {
+    errors.push({
+      field: 'taxTotal.taxAmount',
+      code: 'TAX_AMOUNT_MISMATCH',
+      message: `Tax amount (${invoice.taxTotal.taxAmount}) doesn't match sum of line item taxes (${expectedTaxAmount})`,
+      severity: 'error',
+    })
+  }
+
+  return errors
+}
+
+/**
+ * Main validation function for complete invoice
+ */
+export const validateInvoice = (invoice: InvoiceV1_1): ValidationResult => {
+  const allErrors: ValidationError[] = []
+
+  // Core field validations
+  allErrors.push(
+    ...validateTIN(invoice.supplier.tin, invoice.supplier.registrationType),
+  )
+  allErrors.push(
+    ...validateTIN(invoice.buyer.tin, invoice.buyer.registrationType),
+  )
+
+  allErrors.push(...validateContactNumber(invoice.supplier.contactNumber))
+  allErrors.push(...validateContactNumber(invoice.buyer.contactNumber))
+
+  // Monetary validations
+  allErrors.push(
+    ...validateMonetaryAmount(
+      invoice.legalMonetaryTotal.taxExclusiveAmount,
+      'taxExclusiveAmount',
+    ),
+  )
+  allErrors.push(
+    ...validateMonetaryAmount(
+      invoice.legalMonetaryTotal.payableAmount,
+      'payableAmount',
+    ),
+  )
+  allErrors.push(
+    ...validateMonetaryAmount(invoice.taxTotal.taxAmount, 'taxAmount'),
+  )
+
+  // Line item validations
+  invoice.invoiceLineItems.forEach((item, index) => {
+    allErrors.push(
+      ...validateMonetaryAmount(item.unitPrice, `lineItem[${index}].unitPrice`),
+    )
+    allErrors.push(
+      ...validateMonetaryAmount(item.taxAmount, `lineItem[${index}].taxAmount`),
+    )
+    allErrors.push(
+      ...validateMonetaryAmount(
+        item.totalTaxableAmountPerLine,
+        `lineItem[${index}].totalTaxableAmountPerLine`,
+      ),
+    )
+  })
+
+  // Business rule validations
+  allErrors.push(...validateTaxCalculations(invoice))
+
+  // Separate errors and warnings
+  const errors = allErrors.filter(e => e.severity === 'error')
+  const warnings = allErrors.filter(
+    e => e.severity === 'warning',
+  ) as ValidationWarning[]
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+    warnings,
+  }
+}

package/test/MyInvoiClientWithRealData.test.ts

@@ -1,5 +1,11 @@
 import { describe, it, expect } from 'vitest'
-import { MyInvoisClient } from '../src/utils/MyInvoisClient'
+import { MyInvoisClient } from '../src'
+
+/**
+ * ⚠️ SECURITY NOTICE: This file uses environment variables for sensitive data.
+ * Never hardcode actual TIN, NRIC, certificates, or API credentials in test files.
+ * Use .env file for your actual values (already gitignored).
+ */
 
 describe('MyInvoisClientWithRealData', () => {
   it('should verify TIN with real data', async () => {
@@ -19,11 +25,14 @@ describe('MyInvoisClientWithRealData', () => {
       process.env.CLIENT_ID!,
       process.env.CLIENT_SECRET!,
       'sandbox',
+      process.env.CERTIFICATE!,
+      process.env.PRIVATE_KEY!,
     )
-    // @ts-ignore
+    // @ts-ignore - refreshToken is a private method
     await client.refreshToken()
     const result = await client.verifyTin(
       process.env.TIN_VALUE!,
+      'NRIC',
       process.env.NRIC_VALUE!,
     )
     expect(result).toBe(true)

package/test/MyInvoisClient.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest'
-import { MyInvoisClient } from '../src/utils/MyInvoisClient'
+import { MyInvoisClient } from '../src'
 
 // Mock global fetch
 const mockFetch = vi.fn()
@@ -12,7 +12,15 @@ describe('MyInvoisClient', () => {
 
   beforeEach(() => {
     vi.clearAllMocks()
-    client = new MyInvoisClient('test-id', 'test-secret', 'sandbox', false)
+    client = new MyInvoisClient(
+      'test-id',
+      'test-secret',
+      'sandbox',
+      process.env.TEST_CERTIFICATE!,
+      process.env.TEST_PRIVATE_KEY!,
+      undefined,
+      true,
+    )
   })
 
   describe('constructor', () => {
@@ -21,6 +29,9 @@ describe('MyInvoisClient', () => {
         'test-id',
         'test-secret',
         'sandbox',
+        process.env.TEST_CERTIFICATE!,
+        process.env.TEST_PRIVATE_KEY!,
+        undefined,
         true,
       )
       expect((sandboxClient as any).baseUrl).toBe(
@@ -33,6 +44,9 @@ describe('MyInvoisClient', () => {
         'test-id',
         'test-secret',
         'production',
+        process.env.TEST_CERTIFICATE!,
+        process.env.TEST_PRIVATE_KEY!,
+        undefined,
         true,
       )
       expect((prodClient as any).baseUrl).toBe(
@@ -53,7 +67,7 @@ describe('MyInvoisClient', () => {
         json: () => Promise.resolve(mockToken),
       } as Response)
 
-      await client.verifyTin('123', '456')
+      await client.verifyTin('123', 'NRIC', '456')
 
       expect(mockFetch).toHaveBeenCalledWith(
         'https://preprod-api.myinvois.hasil.gov.my/connect/token',
@@ -77,7 +91,7 @@ describe('MyInvoisClient', () => {
           json: () => Promise.resolve(undefined),
         } as Response)
 
-      await client.verifyTin('123', '456')
+      await client.verifyTin('123', 'NRIC', '456')
 
       // Check first call (token request)
       expect(mockFetch).toHaveBeenNthCalledWith(
@@ -122,12 +136,12 @@ describe('MyInvoisClient', () => {
       } as Response)
 
       // First call to get token
-      await client.verifyTin('123', '456')
+      await client.verifyTin('123', 'NRIC', '456')
 
       vi.setSystemTime(new Date(Date.now() + 1000))
 
       // Second call should reuse token
-      await client.verifyTin('123', '456')
+      await client.verifyTin('123', 'NRIC', '456')
 
       // Token endpoint should only be called once
       expect(mockFetch).toHaveBeenCalledWith(
@@ -154,9 +168,9 @@ describe('MyInvoisClient', () => {
           json: () => Promise.resolve(undefined),
         } as Response)
 
-      await client.verifyTin('123', '456')
+      await client.verifyTin('123', 'NRIC', '456')
       vi.setSystemTime(new Date(Date.now() + 1000 * 8000))
-      await client.verifyTin('123', '456')
+      await client.verifyTin('123', 'NRIC', '456')
 
       expect(mockFetch).toHaveBeenCalledWith(
         `https://preprod-api.myinvois.hasil.gov.my/api/v1.0/taxpayer/validate/123?idType=NRIC&idValue=456`,
@@ -182,7 +196,7 @@ describe('MyInvoisClient', () => {
         } as Response)
         .mockRejectedValueOnce(new Error('Invalid TIN'))
 
-      const result = await client.verifyTin('123', '456')
+      const result = await client.verifyTin('123', 'NRIC', '456')
 
       expect(result).toBe(false)
     })

package/test/base64.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest'
+import { encodeToBase64 } from '../src/utils/base64' // Adjust path if necessary
+
+describe('encodeToBase64', () => {
+  it('should correctly encode a simple JSON string', () => {
+    const jsonString = '{"key": "value"}'
+    const expectedBase64 = 'eyJrZXkiOiAidmFsdWUifQ==' // Buffer.from(jsonString).toString('base64')
+    expect(encodeToBase64(jsonString)).toBe(expectedBase64)
+  })
+
+  it('should correctly encode a simple XML string', () => {
+    const xmlString = '<root><element>value</element></root>'
+    const expectedBase64 =
+      'PHJvb3Q+PGVsZW1lbnQ+dmFsdWU8L2VsZW1lbnQ+PC9yb290Pg==' // Buffer.from(xmlString).toString('base64')
+    expect(encodeToBase64(xmlString)).toBe(expectedBase64)
+  })
+
+  it('should correctly encode an empty string', () => {
+    const emptyString = ''
+    const expectedBase64 = '' // Buffer.from(emptyString).toString('base64')
+    expect(encodeToBase64(emptyString)).toBe(expectedBase64)
+  })
+
+  it('should correctly encode a string with special characters', () => {
+    const specialString = '!@#$%^&*()_+=-`~[]{}\\|;\'",./<>?'
+    const expectedBase64 = 'IUAjJCVeJiooKV8rPS1gfltde31cfDsnIiwuLzw+Pw==' // Corrected value
+    expect(encodeToBase64(specialString)).toBe(expectedBase64)
+  })
+
+  it('should correctly encode a string with Unicode characters', () => {
+    const unicodeString = '你好世界🌍'
+    const expectedBase64 = '5L2g5aW95LiW55WM8J+MjQ==' // Corrected value
+    expect(encodeToBase64(unicodeString)).toBe(expectedBase64)
+  })
+
+  it('should correctly encode a longer string', () => {
+    const longString =
+      'This is a longer string that needs to be encoded to Base64 to ensure it handles more than just a few characters correctly.'
+    const expectedBase64 =
+      'VGhpcyBpcyBhIGxvbmdlciBzdHJpbmcgdGhhdCBuZWVkcyB0byBiZSBlbmNvZGVkIHRvIEJhc2U2NCB0byBlbnN1cmUgaXQgaGFuZGxlcyBtb3JlIHRoYW4ganVzdCBhIGZldyBjaGFyYWN0ZXJzIGNvcnJlY3RseS4=' // Buffer.from(longString).toString('base64')
+    expect(encodeToBase64(longString)).toBe(expectedBase64)
+  })
+})