@ripwords/myinvois-client 0.1.6 → 0.2.0

package/dist/index.d.ts

@@ -1,60 +1,63 @@
-import { Classification, ClassificationCode, ClassificationCodeEnum } from "./classification-codes-BKxV-rO9.js";
-import { Country, CountryCode, CountryCodeEnum, CountryNameEnum } from "./country-code-CQuaiQm2.js";
-import { Currency, CurrencyCode, CurrencyCodeEnum } from "./currencies-BYJK-m6v.js";
-import { EInvoiceType, EInvoiceTypeCode, EInvoiceTypeCodeEnum } from "./e-invoice-CmbLQkHw.js";
-import "./0X-CTIq3y3a.js";
-import "./1X-Bu4oiv8D.js";
-import "./2X-DnG3FY1f.js";
-import "./3X-CLdmoel1.js";
-import "./4X-BTG6o1Gn.js";
-import "./5X-CjSz1zxJ.js";
-import "./6X-B9KP_vEn.js";
-import "./7X-DtkQutx2.js";
-import "./8X-5n9seY3z.js";
-import "./9X-Cpb6V4JC.js";
-import { MSICCode } from "./msic-codes-C8PJVOaA.js";
-import { CanonicalizationMethod, Cert, CertDigest, DigestMethod, IssuerDigitalSignature, IssuerSerial, KeyInfo, QualifyingProperties, Reference, SignatureMethod, SignedInfo, SignedProperties, SignedSignatureProperties, SigningCertificate, Transform, X509Data } from "./signatures-W-_brwdb.js";
-import { TaxType, TaxTypeCode, TaxTypeCodeEnum } from "./tax-types-CsQ76JMf.js";
-import { 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 } from "./documents-i5EV868Y.js";
-import { PaymentMode, PaymentModeCode, PaymentModeCodeEnum } from "./payment-modes-BOTSRC_X.js";
-import "./1X-BywXCqtn.js";
-import "./2X-3fSEGIuE.js";
-import "./3X-Ynjfgoll.js";
-import "./4X-B5ePdMky.js";
-import "./5X-dhP6fyou.js";
-import "./6X-BHaY0TCf.js";
-import "./7X-C4eX_tAk.js";
-import "./8X-D6HTLShY.js";
-import "./9X-CHZKsIdD.js";
-import "./AX-C0w_r3PA.js";
-import "./BX-RadlZ-6m.js";
-import "./CX-CT1Zzb9D.js";
-import "./DX-CtUeTKMM.js";
-import "./EX-084Yu7Wt.js";
-import "./FX-BrbQM0CW.js";
-import "./GX-gKj8iAAh.js";
-import "./HX-9D-ZXTy5.js";
-import "./IX-DR4Fc92A.js";
-import "./JX-DIKa9ma-.js";
-import "./KX-DpsJ_unT.js";
-import "./LX-DeXPPWUX.js";
-import "./MX-CKMjg_zK.js";
-import "./NX-oYdb4NDo.js";
-import "./OX-Bid9es3D.js";
-import "./PX-D7jy9CFk.js";
-import "./QX-BFWOR4g3.js";
-import "./RX-XHgCyMV1.js";
-import "./SX-Cl8RN8oH.js";
-import "./TX-ZymoIbtr.js";
-import "./UX-D-Ndd1ov.js";
-import "./VX-B-1b34r7.js";
-import "./WX-0GuMjPNZ.js";
-import "./YX-B51BbNSg.js";
-import "./ZX-BMJS1iAv.js";
-import "./XX-CF2NANsy.js";
-import { UnitType, UnitTypeCode } from "./unit-types-B41YFOLT.js";
-import { State, StateCode, StateCodeEnum } from "./state-codes-oeFKlwXZ.js";
-import { ClientCredentials, TokenResponse } from "./index-0-EvC6Nv.js";
+import { Classification, ClassificationCode, ClassificationCodeEnum } from "./classification-codes-B1D5xbq5.js";
+import { Country, CountryCode, CountryCodeEnum, CountryNameEnum } from "./country-code-D42kAyNH.js";
+import { Currency, CurrencyCode, CurrencyCodeEnum } from "./currencies-CDveO_yz.js";
+import { EInvoiceType, EInvoiceTypeCode, EInvoiceTypeCodeEnum } from "./e-invoice-BxNC6V_j.js";
+import "./0X-DZnB0al0.js";
+import "./1X-Dg5J6Bfg.js";
+import "./2X-D_qwTeDT.js";
+import "./3X-BJHYxgxa.js";
+import "./4X-BbZgoRHO.js";
+import "./5X-oQRBnO0f.js";
+import "./6X-B9I2XJa4.js";
+import "./7X-Ckv9bbzG.js";
+import "./8X-C37BJTl6.js";
+import "./9X-_XRgT2-_.js";
+import { MSICCode } from "./msic-codes-CiPeemFK.js";
+import { CanonicalizationMethod, Cert, CertDigest, DigestMethod, IssuerDigitalSignature, IssuerSerial, KeyInfo, QualifyingProperties, Reference, SignatureMethod, SignedInfo, SignedProperties, SignedSignatureProperties, SigningCertificate, Transform, X509Data } from "./signatures-DOKNMiZI.js";
+import { TaxType, TaxTypeCode, TaxTypeCodeEnum } from "./tax-types-ieqw5Ze7.js";
+import { Address, Buyer, CompleteInvoice, DocumentStatus, DocumentSummary, DocumentTypeResponse, DocumentTypeVersion, DocumentTypeVersionResponse, DocumentTypesResponse, DocumentValidationResult, DocumentValidationStepResult, FinalDocumentData, GetSubmissionResponse, InvoiceLineItem, InvoiceSubmission, InvoiceV1_1, LegalMonetaryTotal, RegistrationType, ResponseDocument, SignedInfoObject, SignedInvoiceSubmission, SignedPropertiesData, SignedPropertiesObject, SigningCredentials, StandardError, SubmissionResponse, SubmissionStatus, Supplier, TaxCategory, TaxSubtotal, TaxTotal, UBLDocument, WorkflowParameter } from "./documents-BgXt86Qp.js";
+import { PaymentMode, PaymentModeCode, PaymentModeCodeEnum } from "./payment-modes-NpE3OcCV.js";
+import "./1X-C72Wa4pk.js";
+import "./2X-CH89y3Af.js";
+import "./3X-DryrwYRf.js";
+import "./4X-BPMLRoDv.js";
+import "./5X-Bv7M6KyG.js";
+import "./6X-ZeZ8OB57.js";
+import "./7X-Dvw2Z2VN.js";
+import "./8X-BkgoX8dg.js";
+import "./9X-Du0e44cq.js";
+import "./AX-BSPLpkVT.js";
+import "./BX-u4yMaIkz.js";
+import "./CX-BKZG0pVE.js";
+import "./DX-CwA9WJAf.js";
+import "./EX-BRNu1Ooi.js";
+import "./FX-DBxjq6xY.js";
+import "./GX-B3CvWNrP.js";
+import "./HX-D7FABgTv.js";
+import "./IX-D3ZknsAB.js";
+import "./JX-BRaZM3Gc.js";
+import "./KX-B1K0OWoi.js";
+import "./LX-CKRefinL.js";
+import "./MX-DKmaeO9r.js";
+import "./NX-CJL2Gn1U.js";
+import "./OX-Do2ap5v_.js";
+import "./PX-_DOr_rm9.js";
+import "./QX-HlXLkIki.js";
+import "./RX-DVPGOVES.js";
+import "./SX-OGT3qwlS.js";
+import "./TX-cPDINmZ5.js";
+import "./UX-Be3sqvPV.js";
+import "./VX-CoEuBNDK.js";
+import "./WX-DMvw__jH.js";
+import "./YX-F34sJ7Ik.js";
+import "./ZX-CDQOfsHh.js";
+import "./XX-DOA-10JW.js";
+import { UnitType, UnitTypeCode } from "./unit-types-VgYXIwTT.js";
+import { State, StateCode, StateCodeEnum } from "./state-codes-VOFWhHA0.js";
+import { Notification, NotificationDeliveryAttempt, NotificationMetadata, NotificationResponse, NotificationSearchParams, NotificationStatus, NotificationStatusEnum, NotificationType, NotificationTypeEnum } from "./notifications-B4l_qRj7.js";
+import { TaxpayerQRCodeResponse } from "./taxpayer-D67d2zAC.js";
+import { Fetch } from "./utils-B3mo51Zp.js";
+import { ClientCredentials, TokenResponse } from "./index-FTgB2nM6.js";
 
 //#region src/index.d.ts
 declare class MyInvoisClient {
@@ -73,10 +76,30 @@ declare class MyInvoisClient {
   /**
   * Validates a TIN against a NRIC/ARMY/PASSPORT/BRN (Business Registration Number)
   *
+  * This method verifies if a given Tax Identification Number (TIN) is valid by checking it against
+  * the provided identification type and value through the MyInvois platform's validation service.
+  *
   * @param tin - The TIN to validate
-  * @param idType - The type of ID to validate against
+  * @param idType - The type of ID to validate against ('NRIC', 'ARMY', 'PASSPORT', or 'BRN')
   * @param idValue - The value of the ID to validate against
-  * @returns true if the TIN is valid, false otherwise
+  * @returns Promise resolving to true if the TIN is valid, false otherwise
+  *
+  * @example
+  * ```typescript
+  * // Validate TIN against NRIC
+  * const isValid = await client.verifyTin('C12345678901234', 'NRIC', '123456789012');
+  * if (isValid) {
+  *   console.log('TIN is valid');
+  * }
+  *
+  * // Validate TIN against Business Registration Number
+  * const isValidBusiness = await client.verifyTin('C98765432109876', 'BRN', '123456-K');
+  * ```
+  *
+  * @remarks
+  * - Returns false if validation fails due to network errors or invalid credentials
+  * - Debug mode provides error logging for troubleshooting validation failures
+  * - This is a non-blocking validation that won't throw exceptions on failure
   */
   verifyTin(tin: string, idType: RegistrationType, idValue: string): Promise<boolean>;
   /**
@@ -116,6 +139,41 @@ declare class MyInvoisClient {
     data: SubmissionResponse;
     status: number;
   }>;
+  /**
+  * Polls the MyInvois platform to get the current status of a document submission.
+  *
+  * This method continuously checks the submission status until it receives a final result
+  * (Valid or Invalid) or reaches the maximum retry limit. It's designed to handle the
+  * asynchronous nature of document processing on the MyInvois platform.
+  *
+  * @param submissionUid - The unique identifier of the submission to check
+  * @param pollInterval - Time in milliseconds between status checks (default: 1000ms)
+  * @param maxRetries - Maximum number of retry attempts (default: 10)
+  * @returns Promise resolving to submission status object with document summary and any errors
+  *
+  * @example
+  * ```typescript
+  * // Check submission status with default polling
+  * const result = await client.getSubmissionStatus('submission-uid-123');
+  * if (result.status === 'Valid') {
+  *   console.log('All documents processed successfully');
+  *   console.log('Document summaries:', result.documentSummary);
+  * }
+  *
+  * // Custom polling interval and retry count
+  * const result = await client.getSubmissionStatus(
+  *   'submission-uid-123',
+  *   2000, // Poll every 2 seconds
+  *   20    // Try up to 20 times
+  * );
+  * ```
+  *
+  * @remarks
+  * - Automatically retries on network errors until maxRetries is reached
+  * - Returns 'Invalid' status with timeout error if submission processing takes too long
+  * - Debug mode provides detailed logging of polling attempts and responses
+  * - Use reasonable poll intervals to avoid overwhelming the API
+  */
   getSubmissionStatus(submissionUid: string, pollInterval?: number, maxRetries?: number): Promise<{
     status: SubmissionStatus;
     documentSummary?: DocumentSummary[];
@@ -228,6 +286,138 @@ declare class MyInvoisClient {
     documentType?: EInvoiceTypeCode;
     searchQuery?: string;
   }): Promise<DocumentSummary[]>;
+  /**
+  * Retrieves notifications from the MyInvois platform based on specified search criteria.
+  *
+  * This method allows you to search for system notifications, alerts, and messages
+  * sent by the MyInvois platform regarding document processing, system updates,
+  * or account-related information.
+  *
+  * @param params - Search parameters object for filtering notifications
+  * @param params.dateFrom - Optional start date for notification date range (ISO date string)
+  * @param params.dateTo - Optional end date for notification date range (ISO date string)
+  * @param params.type - Optional notification type filter
+  * @param params.language - Optional language preference for notifications
+  * @param params.status - Optional notification status filter
+  * @param params.pageNo - Optional page number for pagination (0-based)
+  * @param params.pageSize - Optional number of results per page
+  * @returns Promise resolving to notification response object or standard error
+  *
+  * @example
+  * ```typescript
+  * // Get all notifications from the last 7 days
+  * const notifications = await client.getNotifications({
+  *   dateFrom: '2024-01-01',
+  *   dateTo: '2024-01-07',
+  *   pageSize: 20
+  * });
+  *
+  * // Get unread notifications only
+  * const unreadNotifications = await client.getNotifications({
+  *   status: 0, // Assuming 0 = unread
+  *   language: 'en'
+  * });
+  *
+  * // Paginated notification retrieval
+  * const firstPage = await client.getNotifications({
+  *   dateFrom: '2024-01-01',
+  *   pageNo: 0,
+  *   pageSize: 10
+  * });
+  * ```
+  *
+  * @remarks
+  * - All parameters are optional, allowing flexible filtering
+  * - Returns paginated results when pageNo and pageSize are specified
+  * - Date parameters should be in ISO format (YYYY-MM-DD)
+  * - May return StandardError object if the request fails
+  */
+  getNotifications({
+    dateFrom,
+    dateTo,
+    type,
+    language,
+    status,
+    pageNo,
+    pageSize
+  }: NotificationSearchParams): Promise<NotificationResponse | StandardError>;
+  getDocumentTypes(): Promise<DocumentTypesResponse | StandardError>;
+  /**
+  * Retrieves detailed information about a specific document type from the MyInvois platform.
+  *
+  * This method fetches metadata and configuration details for a specific document type,
+  * including supported versions, validation rules, and structural requirements.
+  * Useful for understanding document format requirements before submission.
+  *
+  * @param id - The unique identifier of the document type to retrieve
+  * @returns Promise resolving to document type response object or standard error
+  *
+  * @example
+  * ```typescript
+  * // Get details for e-invoice document type
+  * const invoiceType = await client.getDocumentType(1);
+  * if ('id' in invoiceType) {
+  *   console.log('Document type name:', invoiceType.name);
+  *   console.log('Available versions:', invoiceType.versionNumber);
+  *   console.log('Description:', invoiceType.description);
+  * }
+  *
+  * // Handle potential errors
+  * const documentType = await client.getDocumentType(999);
+  * if ('error' in documentType) {
+  *   console.error('Failed to retrieve document type:', documentType.error.message);
+  * }
+  * ```
+  *
+  * @remarks
+  * - Returns StandardError object if the document type ID doesn't exist
+  * - Document type information includes validation schemas and business rules
+  * - Use this method to discover supported document formats and versions
+  * - Essential for understanding submission requirements for different document types
+  */
+  getDocumentType(id: number): Promise<DocumentTypeResponse | StandardError>;
+  /**
+  * Retrieves detailed information about a specific version of a document type.
+  *
+  * This method fetches version-specific metadata, schema definitions, and validation rules
+  * for a particular document type version. Essential for understanding the exact format
+  * and requirements for document submission in a specific version.
+  *
+  * @param id - The unique identifier of the document type
+  * @param versionId - The unique identifier of the specific version to retrieve
+  * @returns Promise resolving to document type version response object or standard error
+  *
+  * @example
+  * ```typescript
+  * // Get specific version details for e-invoice
+  * const invoiceV1_1 = await client.getDocumentTypeVersion(1, 1);
+  * if ('id' in invoiceV1_1) {
+  *   console.log('Version number:', invoiceV1_1.versionNumber);
+  *   console.log('Schema:', invoiceV1_1.jsonSchema);
+  *   console.log('Status:', invoiceV1_1.status);
+  * }
+  *
+  * // Compare different versions
+  * const [v1_0, v1_1] = await Promise.all([
+  *   client.getDocumentTypeVersion(1, 0),
+  *   client.getDocumentTypeVersion(1, 1)
+  * ]);
+  *
+  * // Handle version not found
+  * const result = await client.getDocumentTypeVersion(1, 999);
+  * if ('error' in result) {
+  *   console.error('Version not found:', result.error.message);
+  * }
+  * ```
+  *
+  * @remarks
+  * - Returns StandardError object if document type ID or version ID doesn't exist
+  * - Version information includes JSON schema for validation
+  * - Different versions may have different validation rules and field requirements
+  * - Use this to ensure your documents conform to the specific version requirements
+  * - Version status indicates if the version is active, deprecated, or under development
+  */
+  getDocumentTypeVersion(id: number, versionId: number): Promise<DocumentTypeVersionResponse | StandardError>;
 }
 //#endregion
-export { Address, Buyer, CanonicalizationMethod, Cert, CertDigest, Classification, ClassificationCode, ClassificationCodeEnum, ClientCredentials, CompleteInvoice, Country, CountryCode, CountryCodeEnum, CountryNameEnum, Currency, CurrencyCode, CurrencyCodeEnum, DigestMethod, DocumentStatus, DocumentSummary, DocumentValidationResult, DocumentValidationStepResult, EInvoiceType, EInvoiceTypeCode, EInvoiceTypeCodeEnum, FinalDocumentData, GetSubmissionResponse, InvoiceLineItem, InvoiceSubmission, InvoiceV1_1, IssuerDigitalSignature, IssuerSerial, KeyInfo, LegalMonetaryTotal, MSICCode, MyInvoisClient, PaymentMode, PaymentModeCode, PaymentModeCodeEnum, QualifyingProperties, Reference, RegistrationType, ResponseDocument, SignatureMethod, SignedInfo, SignedInfoObject, SignedInvoiceSubmission, SignedProperties, SignedPropertiesData, SignedPropertiesObject, SignedSignatureProperties, SigningCertificate, SigningCredentials, StandardError, State, StateCode, StateCodeEnum, SubmissionResponse, SubmissionStatus, Supplier, TaxCategory, TaxSubtotal, TaxTotal, TaxType, TaxTypeCode, TaxTypeCodeEnum, TokenResponse, Transform, UBLDocument, UnitType, UnitTypeCode, X509Data };
+export { Address, Buyer, CanonicalizationMethod, Cert, CertDigest, Classification, ClassificationCode, ClassificationCodeEnum, ClientCredentials, CompleteInvoice, Country, CountryCode, CountryCodeEnum, CountryNameEnum, Currency, CurrencyCode, CurrencyCodeEnum, DigestMethod, DocumentStatus, DocumentSummary, DocumentTypeResponse, DocumentTypeVersion, DocumentTypeVersionResponse, DocumentTypesResponse, DocumentValidationResult, DocumentValidationStepResult, EInvoiceType, EInvoiceTypeCode, EInvoiceTypeCodeEnum, Fetch, FinalDocumentData, GetSubmissionResponse, InvoiceLineItem, InvoiceSubmission, InvoiceV1_1, IssuerDigitalSignature, IssuerSerial, KeyInfo, LegalMonetaryTotal, MSICCode, MyInvoisClient, Notification, NotificationDeliveryAttempt, NotificationMetadata, NotificationResponse, NotificationSearchParams, NotificationStatus, NotificationStatusEnum, NotificationType, NotificationTypeEnum, PaymentMode, PaymentModeCode, PaymentModeCodeEnum, QualifyingProperties, Reference, RegistrationType, ResponseDocument, SignatureMethod, SignedInfo, SignedInfoObject, SignedInvoiceSubmission, SignedProperties, SignedPropertiesData, SignedPropertiesObject, SignedSignatureProperties, SigningCertificate, SigningCredentials, StandardError, State, StateCode, StateCodeEnum, SubmissionResponse, SubmissionStatus, Supplier, TaxCategory, TaxSubtotal, TaxTotal, TaxType, TaxTypeCode, TaxTypeCodeEnum, TaxpayerQRCodeResponse, TokenResponse, Transform, UBLDocument, UnitType, UnitTypeCode, WorkflowParameter, X509Data };