Skip to content

Add code comments and improve error messages #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 9, 2025
Merged

Add code comments and improve error messages #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 46 additions & 5 deletions src/Services/Comuni.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -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)
}
Expand Down
73 changes: 71 additions & 2 deletions src/Services/Domains.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,9 @@ interface Contact {
timestamp: number;
}

/**
* Service for managing domain name registrations
*/
export class Domains implements Service {
client: AxiosInstance;
readonly service = 'domains';
Expand All @@ -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)
}
Expand Down
14 changes: 14 additions & 0 deletions src/Services/EuropeanVat.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -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)
}
Expand Down
59 changes: 55 additions & 4 deletions src/Services/FirmaDigitale.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -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,
Expand All @@ -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)
}
Expand Down
Loading
Loading