@ripwords/myinvois-client 0.1.0 → 0.1.3

package/dist/documents-CJ8hqIGH.d.ts

@@ -0,0 +1,858 @@
+import { ClassificationCode } from "./classification-codes-BKxV-rO9.js";
+import { CurrencyCode } from "./currencies-BYJK-m6v.js";
+import { EInvoiceTypeCode } from "./e-invoice-CmbLQkHw.js";
+import { MSICCode } from "./msic-codes-C8PJVOaA.js";
+import { IssuerDigitalSignature } from "./signatures-W-_brwdb.js";
+import { TaxTypeCode } from "./tax-types-CsQ76JMf.js";
+import { Suggested } from "./utils.js";
+
+//#region src/types/documents.d.ts
+type RegistrationType = 'BRN' | 'NRIC' | 'PASSPORT';
+
+// Based on https://sdk.myinvois.hasil.gov.my/documents/invoice-v1-1/
+
+/**
+ * Represents a physical address.
+ * Based on the Address section of the documentation.
+ */
+interface Address {
+  /** Main address line. Max 150 chars.
+   * @example Lot 66
+   */
+  addressLine0: string;
+  /** City name. Max 50 chars. */
+  cityName: string;
+  /** State code. Refer to /codes/state-codes/. Max 50 chars. */
+  state: string;
+  /** Country code (ISO 3166-1). Refer to /codes/countries/. Max 3 chars. */
+  country: string; // MYS
+}
+
+/**
+ * Represents the supplier information.
+ * Based on the Supplier section of the documentation.
+ */
+interface Supplier {
+  /** Supplier's name. Max 300 chars.
+   * @example Test Supplier Sdn Bhd
+   */
+  name: string;
+  /** Supplier's Tax Identification Number (TIN). Max 14 chars.
+   * @example 1234567890
+   */
+  tin: string;
+  /**
+   * Supplier's Registration Type. NRIC, BRN, PASSPORT
+   * @example NRIC
+   */
+  registrationType: RegistrationType;
+  /**
+   * Supplier's Registration / Identification Number / Passport Number.
+   * Format depends on schemeID: NRIC (12), BRN (20), PASSPORT (12), ARMY (12).
+   * @example BRN: 202001234567
+   */
+  registrationNumber: string;
+  /** Supplier's address. */
+  address: Address;
+  /** Supplier's contact number (E.164 standard). Max 20 chars.
+   * @example +60123456789
+   */
+  contactNumber: string;
+  /**
+   * Supplier's industry classification code. Max 10 chars.
+   * @example 41001
+   */
+  industryClassificationCode: MSICCode['code'];
+  /**
+   * Supplier's industry classification description. Max 300 chars.
+   * @example Other retail sale in non-specialised stores
+   */
+  industryClassificationDescription: Suggested<MSICCode['description']>;
+}
+
+/**
+ * Represents the buyer information.
+ * Based on the Buyer section of the documentation.
+ */
+interface Buyer {
+  /** Buyer's name. Max 300 chars.
+   * @example Hebat Group
+   */
+  name: string;
+  /** Buyer's Tax Identification Number (TIN). Max 14 chars.
+   * @example C12345678901
+   */
+  tin: string;
+  /**
+   * Buyer's Registration Type. NRIC, BRN, PASSPORT, ARMY
+   * @example BRN
+   */
+  registrationType: RegistrationType;
+  /**
+   * Buyer's Registration / Identification Number / Passport Number.
+   * Format depends on schemeID: NRIC (12), BRN (20), PASSPORT (12), ARMY (12).
+   * @example BRN: 202001234567
+   */
+  registrationNumber: string;
+  /**
+   * Buyer's SST registration number. Max 35 chars.
+   * Mandatory for SST-registrants.
+   * Allows up to two numbers separated by ';'.
+   * @example W10-1909-32000060
+   */
+  sstRegistrationNumber: string;
+  /** Buyer's address. */
+  address: Address;
+  /** Buyer's contact number (E.164 standard). Max 20 chars.
+   * @example +60123456789
+   */
+  contactNumber: string;
+}
+
+/**
+ * Represents a single line item in an invoice.
+ * Based on the Invoice Line Item section of the documentation.
+ * https://sdk.myinvois.hasil.gov.my/documents/invoice-v1-1/#invoice-line-item
+ */
+interface InvoiceLineItem {
+  /**
+   * Item classification code. Refer to /codes/item-classifications/. Max 50 chars.
+   * @example 001
+   */
+  itemClassificationCode: ClassificationCode;
+  /**
+   * Item description. Max 300 chars.
+   * @example Laptop
+   */
+  itemDescription: string;
+  /**
+   * Unit price before tax. Max 18 digits, 6 decimal places.
+   * @example 1500.00
+   */
+  unitPrice: number;
+  /**
+   * Tax type code. Refer to /codes/tax-types/. Max 2 chars.
+   * @example 01
+   */
+  taxType: TaxTypeCode;
+  /**
+   * Tax rate. Max 18 digits, 2 decimal places.
+   * @example 6.00
+   */
+  taxRate: number;
+  /**
+   * Tax amount. Max 18 digits, 2 decimal places.
+   * @example 90.00
+   */
+  taxAmount: number;
+  /**
+   * Tax exemption reason code. Refer to /codes/tax-exemption-reasons/. Max 2 chars.
+   * Mandatory if tax rate is 0%.
+   * @example 02
+   */
+  taxExemptionReasonCode?: string;
+  /**
+   * Tax exemption reason amount. Max 18 digits, 2 decimal places.
+   * Mandatory if tax rate is 0%.
+   * @example 1500.00
+   */
+  taxExemptionReasonAmount?: number;
+  /**
+   * Total taxable amount per line (Quantity * Unit Price - Discount Amount). Max 18 digits, 2 decimal places.
+   * @example 1500.00
+   */
+  totalTaxableAmountPerLine: number;
+  /**
+   * Total amount per line including tax (Total Taxable Amount Per Line + Tax Amount). Max 18 digits, 2 decimal places.
+   * @example 1590.00
+   */
+  totalAmountPerLine: number;
+}
+
+/** Represents monetary totals for the invoice. Based on UBL cac:LegalMonetaryTotal. */
+interface LegalMonetaryTotal {
+  /** Total amount exclusive of taxes. Max 18 digits, 2 decimal places. */
+  taxExclusiveAmount: number;
+  /** Total amount inclusive of taxes. Max 18 digits, 2 decimal places. */
+  taxInclusiveAmount: number;
+  /** The final payable amount. Max 18 digits, 2 decimal places. */
+  payableAmount: number;
+}
+
+/** Represents tax category information. Based on UBL cac:TaxCategory. */
+interface TaxCategory {
+  /** Tax type code. Refer to /codes/tax-types/. Max 2 chars. */
+  taxTypeCode: TaxTypeCode;
+  /** Tax rate percentage. Max 18 digits, 2 decimal places. */
+  taxRate: number;
+}
+
+/** Represents a subtotal for a specific tax category. Based on UBL cac:TaxSubtotal. */
+interface TaxSubtotal {
+  /** Taxable amount for this category. Max 18 digits, 2 decimal places. */
+  taxableAmount: number;
+  /** Tax amount for this category. Max 18 digits, 2 decimal places. */
+  taxAmount: number;
+  /** Tax category details. */
+  taxCategory: TaxCategory;
+}
+
+/** Represents the total tax amount for the invoice. Based on UBL cac:TaxTotal. */
+interface TaxTotal {
+  /** Total tax amount for the entire invoice. Max 18 digits, 2 decimal places. */
+  taxAmount: number;
+}
+
+/**
+ * Represents the core Invoice v1.1 document structure.
+ * Based on the Core section of the documentation.
+ */
+interface InvoiceV1_1 {
+  /** Supplier information. */
+  supplier: Supplier;
+  /** Buyer information. */
+  buyer: Buyer;
+  /** e-Invoice version. Fixed value '1.1'. */
+  eInvoiceVersion: '1.1';
+  /** e-Invoice type code. Refer to /codes/e-invoice-types/. Max 2 chars. */
+  eInvoiceTypeCode: EInvoiceTypeCode; // e.g., '01'
+  /** Document reference number used by Supplier. Max 50 chars. */
+  eInvoiceCodeOrNumber: string; // e.g., 'INV12345'
+  /** Date of issuance (YYYY-MM-DD) in UTC. Max 10 chars. */
+  eInvoiceDate: string; // e.g., '2017-11-26'
+  /** Time of issuance (HH:mm:ssZ) in UTC. Max 9 chars. */
+  eInvoiceTime: string; // e.g., '15:30:00Z'
+  /** Issuer's digital signature. Refer to /signature/ documentation. */
+  issuerDigitalSignature: IssuerDigitalSignature;
+  /** Invoice currency code. Refer to /codes/currencies/. Max 3 chars. */
+  invoiceCurrencyCode: CurrencyCode; // e.g., 'MYR'
+  /** Invoice line items. */
+  invoiceLineItems: InvoiceLineItem[];
+  /**
+   * Currency exchange rate to MYR. Max 15 decimal places.
+   * Mandatory if InvoiceCurrencyCode is not MYR.
+   */
+  currencyExchangeRate?: number; // e.g., 1.0 or 4.75
+
+  /** Overall monetary totals for the invoice. */
+  legalMonetaryTotal: LegalMonetaryTotal;
+  /** Total tax amounts and subtotals. */
+  taxTotal: TaxTotal;
+}
+type SubmissionStatus = 'InProgress' | 'Valid' | 'PartiallyValid' | 'Invalid';
+type DocumentStatus = 'Valid' | 'Invalid' | 'Cancelled' | 'Submitted';
+type StandardError = {
+  code: string;
+  message: string;
+  target: string;
+  details: {
+    code: string;
+    message: string;
+    target: string;
+  }[];
+};
+type DocumentValidationResult = 'Valid' | 'Invalid' | 'Pending';
+interface DocumentValidationStepResult {
+  name: string;
+  status: DocumentValidationResult;
+  error?: StandardError;
+}
+interface DocumentSummary {
+  uuid: string;
+  submissionUid: string;
+  longId: string;
+  internalId: string;
+  typeName: string;
+  typeVersionName: string;
+  issuerTin: string;
+  issuerName: string;
+  receiverId: string;
+  receiverName: string;
+  dateTimeIssued: string;
+  dateTimeReceived: string;
+  dateTimeValidated: string;
+  totalPayableAmount: number;
+  totalExcludingTax: number;
+  totalDiscount: number;
+  totalNetAmount: number;
+  status: DocumentStatus;
+  cancelDateTime: string | null;
+  rejectRequestDateTime: string | null;
+  documentStatusReason: string | null;
+  createdByUserId: string;
+}
+interface GetSubmissionResponse {
+  submissionUid?: string;
+  documentCount?: number;
+  dateTimeReceived?: string;
+  overallStatus?: SubmissionStatus;
+  documentSummary?: DocumentSummary[];
+  error?: StandardError;
+}
+interface ResponseDocument {
+  invoiceCodeNumber: string;
+  error?: StandardError;
+}
+interface SubmissionResponse {
+  submissionUid: string;
+  acceptedDocuments: ResponseDocument[];
+  rejectedDocuments: ResponseDocument[];
+}
+interface SigningCredentials {
+  /** Private key in PEM format for signing */
+  privateKeyPem: string;
+  /** Certificate in PEM format */
+  certificatePem: string;
+  /** Certificate issuer name (e.g., "CN=Trial LHDNM Sub CA V1, OU=Terms of use at https://www.posdigicert.com.my, O=LHDNM, C=MY") */
+  issuerName: string;
+  /** Certificate serial number as string */
+  serialNumber: string;
+}
+interface FinalDocumentData {
+  signatureValue: string; // Base64 encoded RSA signature (Sig from Step 4)
+  propsDigest: string; // Base64 encoded hash of SignedProperties (PropsDigest from Step 7)
+  docDigest: string; // Base64 encoded hash of Canonicalized Document (DocDigest from Step 3)
+  certificatePem: string; // Signing certificate in PEM format
+}
+interface SignedPropertiesData {
+  certDigest: string; // Base64 encoded SHA-256 hash of certificate (Step 5)
+  signingTime: string; // ISO 8601 UTC timestamp string (e.g., 2023-10-26T10:30:00Z)
+  issuerName: string; // Certificate Issuer Name
+  serialNumber: string; // Certificate Serial Number
+}
+interface InvoiceSubmission {
+  /** Invoice ID */
+  ID: {
+    _: string;
+  }[];
+
+  /** Issue date in YYYY-MM-DD format */
+  IssueDate: {
+    _: string;
+  }[];
+
+  /** Issue time in HH:mm:ssZ format */
+  IssueTime: {
+    _: string;
+  }[];
+
+  /** Invoice type code with version */
+  InvoiceTypeCode: {
+    _: string;
+    listVersionID: string;
+  }[];
+
+  /** Document currency code */
+  DocumentCurrencyCode: {
+    _: string;
+  }[];
+
+  /** Supplier party information */
+  AccountingSupplierParty: {
+    Party: {
+      IndustryClassificationCode: {
+        _: string;
+        name: string;
+      }[];
+      PartyIdentification: {
+        ID: {
+          _: string;
+          schemeID: string;
+        }[];
+      }[];
+      PostalAddress: {
+        CityName: {
+          _: string;
+        }[];
+        CountrySubentityCode: {
+          _: string;
+        }[];
+        AddressLine: {
+          Line: {
+            _: string;
+          }[];
+        }[];
+        Country: {
+          IdentificationCode: {
+            _: string;
+            listID: string;
+            listAgencyID: string;
+          }[];
+        }[];
+      }[];
+      PartyLegalEntity: {
+        RegistrationName: {
+          _: string;
+        }[];
+      }[];
+      Contact: {
+        Telephone: {
+          _: string;
+        }[];
+      }[];
+    }[];
+  }[];
+
+  /** Customer party information */
+  AccountingCustomerParty: {
+    Party: {
+      PartyIdentification: {
+        ID: {
+          _: string;
+          schemeID: string;
+        }[];
+      }[];
+      PostalAddress: {
+        CityName: {
+          _: string;
+        }[];
+        CountrySubentityCode: {
+          _: string;
+        }[];
+        AddressLine: {
+          Line: {
+            _: string;
+          }[];
+        }[];
+        Country: {
+          IdentificationCode: {
+            _: string;
+            listID: string;
+            listAgencyID: string;
+          }[];
+        }[];
+      }[];
+      PartyLegalEntity: {
+        RegistrationName: {
+          _: string;
+        }[];
+      }[];
+      Contact: {
+        Telephone: {
+          _: string;
+        }[];
+      }[];
+    }[];
+  }[];
+
+  /** Tax total */
+  TaxTotal: {
+    TaxAmount: {
+      _: number;
+      currencyID: string;
+    }[];
+    TaxSubtotal: {
+      TaxableAmount: {
+        _: number;
+        currencyID: string;
+      }[];
+      TaxAmount: {
+        _: number;
+        currencyID: string;
+      }[];
+      TaxCategory: {
+        ID: {
+          _: string;
+        }[];
+        TaxScheme: {
+          ID: {
+            _: string;
+            schemeAgencyID: string;
+            schemeID: string;
+          }[];
+        }[];
+      }[];
+    }[];
+  }[];
+
+  /** Legal monetary total */
+  LegalMonetaryTotal: {
+    LineExtensionAmount: {
+      _: number;
+      currencyID: string;
+    }[];
+    TaxExclusiveAmount: {
+      _: number;
+      currencyID: string;
+    }[];
+    TaxInclusiveAmount: {
+      _: number;
+      currencyID: string;
+    }[];
+    PayableAmount: {
+      _: number;
+      currencyID: string;
+    }[];
+  }[];
+
+  /** Invoice line items */
+  InvoiceLine: {
+    ID: {
+      _: string;
+    }[];
+    Item: {
+      CommodityClassification: {
+        ItemClassificationCode: {
+          _: string;
+          listID: string;
+        }[];
+      }[];
+      Description: {
+        _: string;
+      }[];
+    }[];
+    ItemPriceExtension: {
+      Amount: {
+        _: number;
+        currencyID: string;
+      }[];
+    }[];
+    LineExtensionAmount: {
+      _: number;
+      currencyID: string;
+    }[];
+    Price: {
+      PriceAmount: {
+        _: number;
+        currencyID: string;
+      }[];
+    }[];
+    TaxTotal: {
+      TaxAmount: {
+        _: number;
+        currencyID: string;
+      }[];
+      TaxSubtotal: {
+        TaxableAmount: {
+          _: number;
+          currencyID: string;
+        }[];
+        TaxAmount: {
+          _: number;
+          currencyID: string;
+        }[];
+        TaxCategory: {
+          ID: {
+            _: string;
+          }[];
+          TaxScheme: {
+            ID: {
+              _: string;
+              schemeAgencyID: string;
+              schemeID: string;
+            }[];
+          }[];
+        }[];
+      }[];
+    }[];
+  }[];
+
+  /** Tax exchange rate - Mandatory where applicable */
+  TaxExchangeRate?: {
+    SourceCurrencyCode: {
+      _: string;
+    }[];
+    TargetCurrencyCode: {
+      _: string;
+    }[];
+    CalculationRate: {
+      _: number;
+    }[];
+  }[];
+
+  /** UBL Extensions for signatures (optional - only present in signed documents) */
+  UBLExtensions?: {
+    UBLExtension: {
+      ExtensionURI: {
+        _: string;
+      }[];
+      ExtensionContent: {
+        UBLDocumentSignatures: {
+          SignatureInformation: {
+            ID: {
+              _: string;
+            }[];
+            ReferencedSignatureID: {
+              _: string;
+            }[];
+            Signature: {
+              Id: string;
+              Object: {
+                QualifyingProperties: {
+                  Target: string;
+                  SignedProperties: {
+                    Id: string;
+                    SignedSignatureProperties: {
+                      SigningTime: {
+                        _: string;
+                      }[];
+                      SigningCertificate: {
+                        Cert: {
+                          CertDigest: {
+                            DigestMethod: {
+                              Algorithm: string;
+                            }[];
+                            DigestValue: {
+                              _: string;
+                            }[];
+                          }[];
+                          IssuerSerial: {
+                            X509IssuerName: {
+                              _: string;
+                            }[];
+                            X509SerialNumber: {
+                              _: string;
+                            }[];
+                          }[];
+                        }[];
+                      }[];
+                    }[];
+                  }[];
+                }[];
+              }[];
+              KeyInfo: {
+                X509Data: {
+                  X509Certificate: {
+                    _: string;
+                  }[];
+                  X509SubjectName: {
+                    _: string;
+                  }[];
+                  X509IssuerSerial: {
+                    X509IssuerName: {
+                      _: string;
+                    }[];
+                    X509SerialNumber: {
+                      _: string;
+                    }[];
+                  }[];
+                }[];
+              }[];
+              SignatureValue: {
+                _: string;
+              }[];
+              SignedInfo: {
+                CanonicalizationMethod: {
+                  _: string;
+                  Algorithm: string;
+                }[];
+                SignatureMethod: {
+                  _: string;
+                  Algorithm: string;
+                }[];
+                Reference: {
+                  Id: string;
+                  Type: string;
+                  URI: string;
+                  DigestMethod: {
+                    _: string;
+                    Algorithm: string;
+                  }[];
+                  DigestValue: {
+                    _: string;
+                  }[];
+                }[];
+              }[];
+            }[];
+          }[];
+        }[];
+      }[];
+    }[];
+  }[];
+
+  /** Signature reference (optional - only present in signed documents) */
+  Signature?: {
+    ID: {
+      _: string;
+    }[];
+    SignatureMethod: {
+      _: string;
+    }[];
+  }[];
+}
+
+/** Represents the complete UBL document structure with namespace declarations */
+interface UBLDocument {
+  /** UBL Invoice namespace */
+  _D: string;
+  /** UBL CommonAggregateComponents namespace */
+  _A: string;
+  /** UBL CommonBasicComponents namespace */
+  _B: string;
+  /** Array of invoice submissions */
+  Invoice: InvoiceSubmission[];
+}
+
+/** Represents the signed properties structure for digital signatures */
+interface SignedPropertiesObject {
+  SignedProperties: {
+    /** Unique identifier for the signed properties */
+    Id: string;
+    /** Signed signature properties containing signing details */
+    SignedSignatureProperties: {
+      /** Signing timestamp */
+      SigningTime: {
+        _: string;
+      }[];
+      /** Signing certificate information */
+      SigningCertificate: {
+        /** Certificate details */
+        Cert: {
+          /** Certificate digest information */
+          CertDigest: {
+            /** Digest method algorithm */
+            DigestMethod: {
+              Algorithm: string;
+            }[];
+            /** Base64 encoded digest value */
+            DigestValue: {
+              _: string;
+            }[];
+          }[];
+          /** Certificate issuer and serial information */
+          IssuerSerial: {
+            /** X.509 issuer distinguished name */
+            X509IssuerName: {
+              _: string;
+            }[];
+            /** X.509 certificate serial number */
+            X509SerialNumber: {
+              _: string;
+            }[];
+          }[];
+        }[];
+      }[];
+    }[];
+  }[];
+}
+
+/** Represents the signed info structure for digital signatures */
+interface SignedInfoObject {
+  /** Canonicalization method */
+  CanonicalizationMethod: {
+    _: string;
+    Algorithm: string;
+  }[];
+  /** Signature method */
+  SignatureMethod: {
+    _: string;
+    Algorithm: string;
+  }[];
+  /** References being signed */
+  Reference: {
+    Id: string;
+    Type: string;
+    URI: string;
+    DigestMethod: {
+      _: string;
+      Algorithm: string;
+    }[];
+    DigestValue: {
+      _: string;
+    }[];
+  }[];
+}
+
+/** Represents a complete signed invoice with all signature elements */
+interface SignedInvoiceSubmission extends InvoiceSubmission {
+  /** UBL Extensions for signatures - required for signed documents */
+  UBLExtensions: {
+    UBLExtension: {
+      ExtensionURI: {
+        _: string;
+      }[];
+      ExtensionContent: {
+        UBLDocumentSignatures: {
+          SignatureInformation: {
+            ID: {
+              _: string;
+            }[];
+            ReferencedSignatureID: {
+              _: string;
+            }[];
+            Signature: {
+              Id: string;
+              Object: {
+                QualifyingProperties: {
+                  Target: string;
+                  SignedProperties: {
+                    Id: string;
+                    SignedSignatureProperties: {
+                      SigningTime: {
+                        _: string;
+                      }[];
+                      SigningCertificate: {
+                        Cert: {
+                          CertDigest: {
+                            DigestMethod: {
+                              Algorithm: string;
+                            }[];
+                            DigestValue: {
+                              _: string;
+                            }[];
+                          }[];
+                          IssuerSerial: {
+                            X509IssuerName: {
+                              _: string;
+                            }[];
+                            X509SerialNumber: {
+                              _: string;
+                            }[];
+                          }[];
+                        }[];
+                      }[];
+                    }[];
+                  }[];
+                }[];
+              }[];
+              KeyInfo: {
+                X509Data: {
+                  X509Certificate: {
+                    _: string;
+                  }[];
+                  X509SubjectName: {
+                    _: string;
+                  }[];
+                  X509IssuerSerial: {
+                    X509IssuerName: {
+                      _: string;
+                    }[];
+                    X509SerialNumber: {
+                      _: string;
+                    }[];
+                  }[];
+                }[];
+              }[];
+              SignatureValue: {
+                _: string;
+              }[];
+              SignedInfo: SignedInfoObject[];
+            }[];
+          }[];
+        }[];
+      }[];
+    }[];
+  }[];
+
+  /** Signature reference - required for signed documents */
+  Signature: {
+    ID: {
+      _: string;
+    }[];
+    SignatureMethod: {
+      _: string;
+    }[];
+  }[];
+}
+interface CompleteInvoice {
+  /** UBL Invoice namespace */
+  _D: string;
+  /** UBL CommonAggregateComponents namespace */
+  _A: string;
+  /** UBL CommonBasicComponents namespace */
+  _B: string;
+  /** Array of signed invoice submissions */
+  Invoice: SignedInvoiceSubmission[];
+}
+//#endregion
+export { Address, Buyer, CompleteInvoice, DocumentStatus, DocumentSummary, DocumentValidationResult, DocumentValidationStepResult, FinalDocumentData, GetSubmissionResponse, InvoiceLineItem, InvoiceSubmission, InvoiceV1_1, LegalMonetaryTotal, RegistrationType, ResponseDocument, SignedInfoObject, SignedInvoiceSubmission, SignedPropertiesData, SignedPropertiesObject, SigningCredentials, StandardError, SubmissionResponse, SubmissionStatus, Supplier, TaxCategory, TaxSubtotal, TaxTotal, UBLDocument };