Merge pull request #11 from openapi/claude/add-comments-and-todos-011CUxXLiw5Gf5bQ7CTwTxX2

Add code comments and improve error messages

Author: francescobianco

src/Services/Comuni.ts

@@ -17,6 +17,9 @@ interface Dettagliocomuni {
   codice_istat: string;
 }
 
+/**
+ * Service for querying Italian municipalities, provinces, and regions data
+ */
 export class Comuni implements Service {
     client: AxiosInstance;
     readonly service = 'comuni';
@@ -28,49 +31,87 @@ export class Comuni implements Service {
         this.environment = environment;
     }
 
+    /**
+     * Retrieves cities by postal code (CAP)
+     * @param cap - Italian postal code
+     */
     async getCitiesByCap(cap: string): Promise<Provincia[]> {
+        // TODO: Add validation for CAP format and provide graceful error message for invalid/not found CAP
         return await (await this.client.get(this.url + '/cap/' + cap)).data.data;
     }
 
+    /**
+     * Gets municipality information by cadastral code
+     * @param codiceCatastale - The cadastral code
+     */
     async getComuneByCatasto(codiceCatastale: string) {
+        // TODO: Validate cadastral code format and handle not found cases with user-friendly messages
         return await (await this.client.get(this.url + '/catastale/' + codiceCatastale)).data.data;
     }
 
-    //Regioni
+    // Region-related methods
 
+    /**
+     * Lists all Italian regions (sorted alphabetically)
+     */
     async getRegioni() {
+        // TODO: Add error handling for API failures
         const regioni: Array<string> = await (await this.client.get(this.url + '/regioni')).data.data;
         return regioni.sort();
     }
 
+    /**
+     * Gets all provinces within a specific region
+     * @param regione - The region name
+     */
     async getRegione(regione: string): Promise<Provincia[]> {
+        // TODO: Validate region name and provide helpful error message if region not found
         return await (await this.client.get(this.url + '/regioni/' + regione)).data.data;
     }
 
-    // Provincie
+    // Province-related methods
 
     /**
-     * @return Ritorna un oggetto chiave-valore delle province,
-     * definito come { codice_privicia: nome_provincia }
+     * Lists all Italian provinces
+     * @returns Key-value object of provinces { province_code: province_name }
      */
     async listProvince() {
+        // TODO: Add error handling for API failures
         return await (await this.client.get(this.url + '/province')).data.data;
     }
 
+    /**
+     * Gets detailed information about a specific province
+     * @param provincia - The province code or name
+     */
     async getProvincia(provincia?: string): Promise<Provincia> {
+        // TODO: Add validation for empty provincia parameter and graceful error message
         return await (await this.client.get(this.url + '/province/' + provincia)).data.data[0];
     }
 
-    // Comuni
+    // Municipality-related methods
 
+    /**
+     * Lists all municipalities within a province
+     * @param provincia - The province code or name
+     */
     async listComuni(provincia: string) {
+        // TODO: Add error handling if provincia is not found or API fails
        return (await this.getProvincia(provincia)).dettaglio_comuni;
     }
 
+    /**
+     * Gets municipality data by ISTAT code
+     * @param code - The ISTAT statistical code
+     */
     async getFromIstatCode(code: string): Promise<any[]> {
+        // TODO: Validate ISTAT code format and handle not found cases with clear error messages
         return await (await this.client.get(this.url + '/istat/' + code)).data.data;
     }
 
+    /**
+     * Gets the full service URL based on environment
+     */
     get url() {
         return getBaseUrl(this.environment, this.baseUrl)
     }

src/Services/Domains.ts

@@ -64,6 +64,9 @@ interface Contact {
   timestamp: number;
 }
 
+/**
+ * Service for managing domain name registrations
+ */
 export class Domains implements Service {
     client: AxiosInstance;
     readonly service = 'domains';
@@ -75,55 +78,121 @@ export class Domains implements Service {
         this.environment = environment;
     }
 
+    /**
+     * Checks if a domain name is available for registration
+     * @param domain - The domain name to check
+     */
     async checkAvailability(domain: string) {
+        // TODO: Validate domain format and add graceful error messages
         return await (await this.client.get(this.url + '/check/' + domain)).data;
     }
 
+    /**
+     * Lists all registered domains
+     */
     async listDomains(): Promise<string[]> {
+        // TODO: Add error handling for API failures
         return await (await this.client.get(this.url + '/domain')).data.data;
     }
 
+    /**
+     * Registers a new domain
+     * @param data - Domain registration details (domain, contacts, DNS)
+     */
     async registerDomain(data: DomainRegistration) {
+        // TODO: Validate registration data and provide clear error messages for missing required fields
+        // TODO: Handle API errors (domain already registered, invalid contacts, etc.)
         return await (await this.client.post(this.url + '/domain', JSON.stringify(data))).data;
     }
 
+    /**
+     * Gets details of a registered domain
+     * @param domain - The domain name
+     */
     async getDomain(domain: string): Promise<Domain> {
+        // TODO: Validate domain and add error handling for not found cases
         return await (await this.client.get(this.url + '/domain/' + domain)).data.data;
     }
 
+    /**
+     * Updates domain configuration
+     * @param domain - The domain name
+     * @param data - Updated domain data
+     */
     async updateDomain(domain: string, data: DomainRegistration): Promise<Domain> {
+        // TODO: Validate parameters and handle errors for unauthorized updates or invalid data
         return await (await this.client.put(this.url + '/domain/' + domain, JSON.stringify(data))).data.data;
     }
 
+    /**
+     * Deletes/cancels a domain registration
+     * @param domain - The domain name to delete
+     */
     async deleteDomain(domain: string): Promise<Domain> {
+        // TODO: Add confirmation validation and graceful error messages
         return await (await this.client.delete(this.url + '/domain/' + domain)).data.data;
     }
 
+    /**
+     * Removes a technical contact from a domain
+     * @param domain - The domain name
+     * @param techId - The technical contact ID to remove
+     */
     async deleteTech(domain: string, techId: string): Promise<Domain> {
+        // TODO: Validate parameters and handle errors for invalid contact ID
         return await (await this.client.delete(this.url + '/domain/' + domain + '/tech/' + techId)).data.data;
     }
 
-    // Contacts
+    // Contact management methods
+
+    /**
+     * Lists all registered contacts
+     */
     async listContacts(): Promise<string[]> {
+        // TODO: Add error handling for API failures
         return await (await this.client.get(this.url + '/contact')).data.data;
     }
+
+    /**
+     * Creates a new contact for domain registration
+     * @param data - Contact information
+     */
     async createContact(data: ContactRequest) {
+        // TODO: Validate contact data and provide clear error messages for missing required fields
         return await (await this.client.post(this.url + '/contact', JSON.stringify(data))).data;
     }
 
+    /**
+     * Gets details of a specific contact
+     * @param id - The contact ID
+     */
     async getContact(id: string): Promise<Contact> {
+        // TODO: Validate ID and add error handling for not found cases
         return await (await this.client.get(this.url + '/contact/' + id)).data.data;
     }
 
+    /**
+     * Updates contact information
+     * @param id - The contact ID
+     * @param data - Updated contact data
+     */
     async updateContact(id: string, data: ContactRequest) {
+        // TODO: Validate parameters and handle errors for invalid data
         return await (await this.client.put(this.url + '/contact/' + id, JSON.stringify(data))).data;
     }
 
+    /**
+     * Deletes a contact
+     * @param id - The contact ID to delete
+     */
     async deleteContact(id: string) {
+        // TODO: Add validation to prevent deleting contacts still in use by domains
         return await (await this.client.delete(this.url + '/contact/' + id)).data.data;
     }
 
-
+    /**
+     * Gets the full service URL based on environment
+     */
     get url() {
         return getBaseUrl(this.environment, this.baseUrl)
     }

src/Services/EuropeanVat.ts

@@ -11,6 +11,9 @@ export interface Company {
   company_address?: string;
 }
 
+/**
+ * Service for validating European VAT numbers (VIES)
+ */
 export class EuropeanVat implements Service {
     client: AxiosInstance;
     readonly service = 'europeanvat';
@@ -22,10 +25,21 @@ export class EuropeanVat implements Service {
         this.environment = environment;
     }
 
+    /**
+     * Validates and retrieves company information by European VAT number
+     * @param country - Two-letter country code (e.g., 'IT', 'DE', 'FR')
+     * @param vat - The VAT number to validate
+     * @returns Company information including validation status
+     */
     async getInformation(country: string, vat?: string): Promise<Company> {
+        // TODO: Validate country code format and VAT parameter
+        // TODO: Add graceful error messages for invalid VAT numbers or country codes
         return await (await this.client.get(this.url + '/companies/' + country + '/' + vat)).data.data;
     }
 
+    /**
+     * Gets the full service URL based on environment
+     */
     get url() {
         return getBaseUrl(this.environment, this.baseUrl)
     }

src/Services/FirmaDigitale.ts

@@ -81,6 +81,9 @@ interface Sign {
   position: string;
 }
 
+/**
+ * Service for managing digital signatures and electronic signature requests
+ */
 export class FirmaDigitale implements Service {
     client: AxiosInstance;
     readonly service = 'firmaDigitale';
@@ -92,47 +95,85 @@ export class FirmaDigitale implements Service {
         this.environment = environment;
     }
 
+    /**
+     * Retrieves the list of available digital signature products
+     */
     async getProducts(): Promise<Array<Prodotto>> {
+        // TODO: Add error handling for failed API requests with user-friendly messages
         return await (await this.client.get(this.url + '/prodotti')).data.data
     }
 
+    /**
+     * Gets details of a specific digital signature request
+     * @param id - The request ID
+     */
     async getRequest(id: string) {
+        // TODO: Add validation for empty/invalid ID and graceful error message
         return await (await this.client.get(this.url + '/richiesta/' + id)).data.data
     }
 
+    /**
+     * Lists all digital signature requests
+     */
     async listRequests(): Promise<Array<any>> {
+        // TODO: Add error handling for API failures
         return await (await this.client.get(this.url + '/richiesta/')).data.data
     }
 
+    /**
+     * Downloads the request module/form for a specific request
+     * @param id - The request ID
+     */
     async getRequestModule(id: string): Promise<Buffer> {
+        // TODO: Add validation and error handling for invalid ID or missing module
         return await this.client.get(this.url + '/richiesta/' + id + '/modulo');
     }
 
     /**
-     * 
-     * @param codProdotto il codice del prodotto da richiedere: https://developers.openapi.it/services/firmadigitale
-     * @param data dati aggiuntivi richiesti dallo specifico prodotto richiesto
+     * Requests a digital signature product
+     * @param codProdotto - Product code to request (see https://developers.openapi.it/services/firmadigitale)
+     * @param data - Additional data required by the specific product
+     * @param assistenza - Whether to request assistance
+     * @param callback - Optional callback configuration
      */
     async requestProduct(codProdotto: string, data: any, assistenza?: boolean, callback?: Callback) {
+        // TODO: Add validation for codProdotto and data parameters with clear error messages
         const body = { ...data };
         if (assistenza) body.assistenza = assistenza;
         if (callback) body.callback = callback;
 
+        // TODO: Handle API errors with descriptive messages (invalid product code, missing required fields, etc.)
         return await (await this.client.post(this.url + '/richiesta/' + codProdotto, JSON.stringify(body))).data.data
     }
 
     /**
-     * Firma digitale
+     * Gets details of a specific electronic signature request
+     * @param id - The electronic signature ID
      */
     async getFirmaElettronica(id: string): Promise<FirmaElettronica> {
+        // TODO: Add error handling for invalid ID or not found cases
         return await (await this.client.get(this.url + '/firma_elettronica/' + id )).data.data;
     }
 
+    /**
+     * Lists all electronic signature requests
+     */
     async listFirmaElettronica(): Promise<FirmaElettronica[]> {
+        // TODO: Add error handling for API failures
         return await (await this.client.get(this.url + '/firma_elettronica/')).data.data;
     }
 
+    /**
+     * Creates a new electronic signature request
+     * @param filename - Name of the file to be signed
+     * @param content - Base64 encoded file content
+     * @param members - Array of signers with their details and signature positions
+     * @param callback - Optional callback configuration for status updates
+     * @param title - Optional title for the signature request
+     * @param description - Optional description
+     */
     async createFirmaElettronica(filename: string, content: string, members: FesMember[], callback?: FesCallback, title?: string, description?: string): Promise<FirmaElettronica> {
+        // TODO: Validate required fields (filename, content, members) and provide clear error messages
         let body: any = {
             filename,
             content,
@@ -143,13 +184,23 @@ export class FirmaDigitale implements Service {
         if (title) body.title = title;
         if (description) body.description = description;
 
+        // TODO: Handle API errors (invalid file format, missing member info, etc.) with user-friendly messages
         return await (await this.client.post(this.url + '/firma_elettronica/base', JSON.stringify(body))).data.data;
     }
 
+    /**
+     * Downloads the signed document
+     * @param id - The electronic signature ID
+     * @returns Base64 encoded signed document
+     */
     async downloadFirmaElettronica(id: string): Promise<string> {
+        // TODO: Add error handling for invalid ID or document not ready cases
         return await (await this.client.get(this.url + '/firma_elettronica/' + id + '/download')).data.content;
     }
 
+    /**
+     * Gets the full service URL based on environment
+     */
     get url() {
         return getBaseUrl(this.environment, this.baseUrl)
     }