Skip to content

Commit 4578b3b

Browse files
francescobiancofrancescobianco
authored
Merge pull request #11 from openapi/claude/add-comments-and-todos-011CUxXLiw5Gf5bQ7CTwTxX2
Add code comments and improve error messages
2 parents 6b8635e + 9b12f48 commit 4578b3b

17 files changed

+770
-85
lines changed

‎src/Services/Comuni.ts‎

Lines changed: 46 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,9 @@ interface Dettagliocomuni {
1717
codice_istat: string;
1818
}
1919

20+
/**
21+
* Service for querying Italian municipalities, provinces, and regions data
22+
*/
2023
export class Comuni implements Service {
2124
client: AxiosInstance;
2225
readonly service = 'comuni';
@@ -28,49 +31,87 @@ export class Comuni implements Service {
2831
this.environment = environment;
2932
}
3033

34+
/**
35+
* Retrieves cities by postal code (CAP)
36+
* @param cap - Italian postal code
37+
*/
3138
async getCitiesByCap(cap: string): Promise<Provincia[]> {
39+
// TODO: Add validation for CAP format and provide graceful error message for invalid/not found CAP
3240
return await (await this.client.get(this.url + '/cap/' + cap)).data.data;
3341
}
3442

43+
/**
44+
* Gets municipality information by cadastral code
45+
* @param codiceCatastale - The cadastral code
46+
*/
3547
async getComuneByCatasto(codiceCatastale: string) {
48+
// TODO: Validate cadastral code format and handle not found cases with user-friendly messages
3649
return await (await this.client.get(this.url + '/catastale/' + codiceCatastale)).data.data;
3750
}
3851

39-
//Regioni
52+
// Region-related methods
4053

54+
/**
55+
* Lists all Italian regions (sorted alphabetically)
56+
*/
4157
async getRegioni() {
58+
// TODO: Add error handling for API failures
4259
const regioni: Array<string> = await (await this.client.get(this.url + '/regioni')).data.data;
4360
return regioni.sort();
4461
}
4562

63+
/**
64+
* Gets all provinces within a specific region
65+
* @param regione - The region name
66+
*/
4667
async getRegione(regione: string): Promise<Provincia[]> {
68+
// TODO: Validate region name and provide helpful error message if region not found
4769
return await (await this.client.get(this.url + '/regioni/' + regione)).data.data;
4870
}
4971

50-
// Provincie
72+
// Province-related methods
5173

5274
/**
53-
* @return Ritorna un oggetto chiave-valore delle province,
54-
* definito come { codice_privicia: nome_provincia }
75+
* Lists all Italian provinces
76+
* @returns Key-value object of provinces { province_code: province_name }
5577
*/
5678
async listProvince() {
79+
// TODO: Add error handling for API failures
5780
return await (await this.client.get(this.url + '/province')).data.data;
5881
}
5982

83+
/**
84+
* Gets detailed information about a specific province
85+
* @param provincia - The province code or name
86+
*/
6087
async getProvincia(provincia?: string): Promise<Provincia> {
88+
// TODO: Add validation for empty provincia parameter and graceful error message
6189
return await (await this.client.get(this.url + '/province/' + provincia)).data.data[0];
6290
}
6391

64-
// Comuni
92+
// Municipality-related methods
6593

94+
/**
95+
* Lists all municipalities within a province
96+
* @param provincia - The province code or name
97+
*/
6698
async listComuni(provincia: string) {
99+
// TODO: Add error handling if provincia is not found or API fails
67100
return (await this.getProvincia(provincia)).dettaglio_comuni;
68101
}
69102

103+
/**
104+
* Gets municipality data by ISTAT code
105+
* @param code - The ISTAT statistical code
106+
*/
70107
async getFromIstatCode(code: string): Promise<any[]> {
108+
// TODO: Validate ISTAT code format and handle not found cases with clear error messages
71109
return await (await this.client.get(this.url + '/istat/' + code)).data.data;
72110
}
73111

112+
/**
113+
* Gets the full service URL based on environment
114+
*/
74115
get url() {
75116
return getBaseUrl(this.environment, this.baseUrl)
76117
}

‎src/Services/Domains.ts‎

Lines changed: 71 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,9 @@ interface Contact {
6464
timestamp: number;
6565
}
6666

67+
/**
68+
* Service for managing domain name registrations
69+
*/
6770
export class Domains implements Service {
6871
client: AxiosInstance;
6972
readonly service = 'domains';
@@ -75,55 +78,121 @@ export class Domains implements Service {
7578
this.environment = environment;
7679
}
7780

81+
/**
82+
* Checks if a domain name is available for registration
83+
* @param domain - The domain name to check
84+
*/
7885
async checkAvailability(domain: string) {
86+
// TODO: Validate domain format and add graceful error messages
7987
return await (await this.client.get(this.url + '/check/' + domain)).data;
8088
}
8189

90+
/**
91+
* Lists all registered domains
92+
*/
8293
async listDomains(): Promise<string[]> {
94+
// TODO: Add error handling for API failures
8395
return await (await this.client.get(this.url + '/domain')).data.data;
8496
}
8597

98+
/**
99+
* Registers a new domain
100+
* @param data - Domain registration details (domain, contacts, DNS)
101+
*/
86102
async registerDomain(data: DomainRegistration) {
103+
// TODO: Validate registration data and provide clear error messages for missing required fields
104+
// TODO: Handle API errors (domain already registered, invalid contacts, etc.)
87105
return await (await this.client.post(this.url + '/domain', JSON.stringify(data))).data;
88106
}
89107

108+
/**
109+
* Gets details of a registered domain
110+
* @param domain - The domain name
111+
*/
90112
async getDomain(domain: string): Promise<Domain> {
113+
// TODO: Validate domain and add error handling for not found cases
91114
return await (await this.client.get(this.url + '/domain/' + domain)).data.data;
92115
}
93116

117+
/**
118+
* Updates domain configuration
119+
* @param domain - The domain name
120+
* @param data - Updated domain data
121+
*/
94122
async updateDomain(domain: string, data: DomainRegistration): Promise<Domain> {
123+
// TODO: Validate parameters and handle errors for unauthorized updates or invalid data
95124
return await (await this.client.put(this.url + '/domain/' + domain, JSON.stringify(data))).data.data;
96125
}
97126

127+
/**
128+
* Deletes/cancels a domain registration
129+
* @param domain - The domain name to delete
130+
*/
98131
async deleteDomain(domain: string): Promise<Domain> {
132+
// TODO: Add confirmation validation and graceful error messages
99133
return await (await this.client.delete(this.url + '/domain/' + domain)).data.data;
100134
}
101135

136+
/**
137+
* Removes a technical contact from a domain
138+
* @param domain - The domain name
139+
* @param techId - The technical contact ID to remove
140+
*/
102141
async deleteTech(domain: string, techId: string): Promise<Domain> {
142+
// TODO: Validate parameters and handle errors for invalid contact ID
103143
return await (await this.client.delete(this.url + '/domain/' + domain + '/tech/' + techId)).data.data;
104144
}
105145

106-
// Contacts
146+
// Contact management methods
147+
148+
/**
149+
* Lists all registered contacts
150+
*/
107151
async listContacts(): Promise<string[]> {
152+
// TODO: Add error handling for API failures
108153
return await (await this.client.get(this.url + '/contact')).data.data;
109154
}
155+
156+
/**
157+
* Creates a new contact for domain registration
158+
* @param data - Contact information
159+
*/
110160
async createContact(data: ContactRequest) {
161+
// TODO: Validate contact data and provide clear error messages for missing required fields
111162
return await (await this.client.post(this.url + '/contact', JSON.stringify(data))).data;
112163
}
113164

165+
/**
166+
* Gets details of a specific contact
167+
* @param id - The contact ID
168+
*/
114169
async getContact(id: string): Promise<Contact> {
170+
// TODO: Validate ID and add error handling for not found cases
115171
return await (await this.client.get(this.url + '/contact/' + id)).data.data;
116172
}
117173

174+
/**
175+
* Updates contact information
176+
* @param id - The contact ID
177+
* @param data - Updated contact data
178+
*/
118179
async updateContact(id: string, data: ContactRequest) {
180+
// TODO: Validate parameters and handle errors for invalid data
119181
return await (await this.client.put(this.url + '/contact/' + id, JSON.stringify(data))).data;
120182
}
121183

184+
/**
185+
* Deletes a contact
186+
* @param id - The contact ID to delete
187+
*/
122188
async deleteContact(id: string) {
189+
// TODO: Add validation to prevent deleting contacts still in use by domains
123190
return await (await this.client.delete(this.url + '/contact/' + id)).data.data;
124191
}
125192

126-
193+
/**
194+
* Gets the full service URL based on environment
195+
*/
127196
get url() {
128197
return getBaseUrl(this.environment, this.baseUrl)
129198
}

‎src/Services/EuropeanVat.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,9 @@ export interface Company {
1111
company_address?: string;
1212
}
1313

14+
/**
15+
* Service for validating European VAT numbers (VIES)
16+
*/
1417
export class EuropeanVat implements Service {
1518
client: AxiosInstance;
1619
readonly service = 'europeanvat';
@@ -22,10 +25,21 @@ export class EuropeanVat implements Service {
2225
this.environment = environment;
2326
}
2427

28+
/**
29+
* Validates and retrieves company information by European VAT number
30+
* @param country - Two-letter country code (e.g., 'IT', 'DE', 'FR')
31+
* @param vat - The VAT number to validate
32+
* @returns Company information including validation status
33+
*/
2534
async getInformation(country: string, vat?: string): Promise<Company> {
35+
// TODO: Validate country code format and VAT parameter
36+
// TODO: Add graceful error messages for invalid VAT numbers or country codes
2637
return await (await this.client.get(this.url + '/companies/' + country + '/' + vat)).data.data;
2738
}
2839

40+
/**
41+
* Gets the full service URL based on environment
42+
*/
2943
get url() {
3044
return getBaseUrl(this.environment, this.baseUrl)
3145
}

‎src/Services/FirmaDigitale.ts‎

Lines changed: 55 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,9 @@ interface Sign {
8181
position: string;
8282
}
8383

84+
/**
85+
* Service for managing digital signatures and electronic signature requests
86+
*/
8487
export class FirmaDigitale implements Service {
8588
client: AxiosInstance;
8689
readonly service = 'firmaDigitale';
@@ -92,47 +95,85 @@ export class FirmaDigitale implements Service {
9295
this.environment = environment;
9396
}
9497

98+
/**
99+
* Retrieves the list of available digital signature products
100+
*/
95101
async getProducts(): Promise<Array<Prodotto>> {
102+
// TODO: Add error handling for failed API requests with user-friendly messages
96103
return await (await this.client.get(this.url + '/prodotti')).data.data
97104
}
98105

106+
/**
107+
* Gets details of a specific digital signature request
108+
* @param id - The request ID
109+
*/
99110
async getRequest(id: string) {
111+
// TODO: Add validation for empty/invalid ID and graceful error message
100112
return await (await this.client.get(this.url + '/richiesta/' + id)).data.data
101113
}
102114

115+
/**
116+
* Lists all digital signature requests
117+
*/
103118
async listRequests(): Promise<Array<any>> {
119+
// TODO: Add error handling for API failures
104120
return await (await this.client.get(this.url + '/richiesta/')).data.data
105121
}
106122

123+
/**
124+
* Downloads the request module/form for a specific request
125+
* @param id - The request ID
126+
*/
107127
async getRequestModule(id: string): Promise<Buffer> {
128+
// TODO: Add validation and error handling for invalid ID or missing module
108129
return await this.client.get(this.url + '/richiesta/' + id + '/modulo');
109130
}
110131

111132
/**
112-
*
113-
* @param codProdotto il codice del prodotto da richiedere: https://developers.openapi.it/services/firmadigitale
114-
* @param data dati aggiuntivi richiesti dallo specifico prodotto richiesto
133+
* Requests a digital signature product
134+
* @param codProdotto - Product code to request (see https://developers.openapi.it/services/firmadigitale)
135+
* @param data - Additional data required by the specific product
136+
* @param assistenza - Whether to request assistance
137+
* @param callback - Optional callback configuration
115138
*/
116139
async requestProduct(codProdotto: string, data: any, assistenza?: boolean, callback?: Callback) {
140+
// TODO: Add validation for codProdotto and data parameters with clear error messages
117141
const body = { ...data };
118142
if (assistenza) body.assistenza = assistenza;
119143
if (callback) body.callback = callback;
120144

145+
// TODO: Handle API errors with descriptive messages (invalid product code, missing required fields, etc.)
121146
return await (await this.client.post(this.url + '/richiesta/' + codProdotto, JSON.stringify(body))).data.data
122147
}
123148

124149
/**
125-
* Firma digitale
150+
* Gets details of a specific electronic signature request
151+
* @param id - The electronic signature ID
126152
*/
127153
async getFirmaElettronica(id: string): Promise<FirmaElettronica> {
154+
// TODO: Add error handling for invalid ID or not found cases
128155
return await (await this.client.get(this.url + '/firma_elettronica/' + id )).data.data;
129156
}
130157

158+
/**
159+
* Lists all electronic signature requests
160+
*/
131161
async listFirmaElettronica(): Promise<FirmaElettronica[]> {
162+
// TODO: Add error handling for API failures
132163
return await (await this.client.get(this.url + '/firma_elettronica/')).data.data;
133164
}
134165

166+
/**
167+
* Creates a new electronic signature request
168+
* @param filename - Name of the file to be signed
169+
* @param content - Base64 encoded file content
170+
* @param members - Array of signers with their details and signature positions
171+
* @param callback - Optional callback configuration for status updates
172+
* @param title - Optional title for the signature request
173+
* @param description - Optional description
174+
*/
135175
async createFirmaElettronica(filename: string, content: string, members: FesMember[], callback?: FesCallback, title?: string, description?: string): Promise<FirmaElettronica> {
176+
// TODO: Validate required fields (filename, content, members) and provide clear error messages
136177
let body: any = {
137178
filename,
138179
content,
@@ -143,13 +184,23 @@ export class FirmaDigitale implements Service {
143184
if (title) body.title = title;
144185
if (description) body.description = description;
145186

187+
// TODO: Handle API errors (invalid file format, missing member info, etc.) with user-friendly messages
146188
return await (await this.client.post(this.url + '/firma_elettronica/base', JSON.stringify(body))).data.data;
147189
}
148190

191+
/**
192+
* Downloads the signed document
193+
* @param id - The electronic signature ID
194+
* @returns Base64 encoded signed document
195+
*/
149196
async downloadFirmaElettronica(id: string): Promise<string> {
197+
// TODO: Add error handling for invalid ID or document not ready cases
150198
return await (await this.client.get(this.url + '/firma_elettronica/' + id + '/download')).data.content;
151199
}
152200

201+
/**
202+
* Gets the full service URL based on environment
203+
*/
153204
get url() {
154205
return getBaseUrl(this.environment, this.baseUrl)
155206
}

0 commit comments

Comments
 (0)