docs(tem): revamp (#549)

Author: scaleway-bot

packages/clients/src/api/tem/v1alpha1/api.gen.ts

@@ -46,16 +46,19 @@ const jsonContentHeaders = {
 }
 
 /**
- * Transactional Email API.
+ * Transactional Email API documentation.
  *
- * Tem. Transactional Email API.
+ * Tem. Transactional Email API documentation.
  */
 export class API extends ParentAPI {
   /** Lists the available regions of the API. */
   public static readonly LOCALITIES: Region[] = ['fr-par']
 
   /**
-   * Send an email.
+   * Send an email. You must specify the `region`, the sender and the
+   * recipient's information and the `project_id` to send an email from a
+   * checked domain. The subject of the email must contain at least 6
+   * characters.
    *
    * @param request - The request {@link CreateEmailRequest}
    * @returns A Promise of CreateEmailResponse
@@ -77,7 +80,8 @@ export class API extends ParentAPI {
     )
 
   /**
-   * Get information about an email.
+   * Get an email. Retrieve information about a specific email using the
+   * `email_id` and `region` parameters.
    *
    * @param request - The request {@link GetEmailRequest}
    * @returns A Promise of Email
@@ -143,8 +147,8 @@ export class API extends ParentAPI {
     )
 
   /**
-   * List emails sent from a domain and/or for a project and/or for an
-   * organization.
+   * List emails. Retrieve the list of emails sent from a specific domain or for
+   * a specific Project or Organization. You must specify the `region`.
    *
    * @param request - The request {@link ListEmailsRequest}
    * @returns A Promise of ListEmailsResponse
@@ -153,7 +157,7 @@ export class API extends ParentAPI {
     enrichForPagination('emails', this.pageOfListEmails, request)
 
   /**
-   * Get statistics on the email statuses.
+   * Email statuses. Get information on your emails' statuses.
    *
    * @param request - The request {@link GetStatisticsRequest}
    * @returns A Promise of Statistics
@@ -178,7 +182,9 @@ export class API extends ParentAPI {
     )
 
   /**
-   * Try to cancel an email if it has not yet been sent.
+   * Cancel an email. You can cancel the sending of an email if it has not been
+   * sent yet. You must specify the `region` and the `email_id` of the email you
+   * want to cancel.
    *
    * @param request - The request {@link CancelEmailRequest}
    * @returns A Promise of Email
@@ -198,7 +204,8 @@ export class API extends ParentAPI {
     )
 
   /**
-   * Register a domain in a project.
+   * Register a domain in a project. You must specify the `region`, `project_id`
+   * and `domain_name` to register a domain in a specific Project.
    *
    * @param request - The request {@link CreateDomainRequest}
    * @returns A Promise of Domain
@@ -220,7 +227,8 @@ export class API extends ParentAPI {
     )
 
   /**
-   * Get information about a domain.
+   * Get information about a domain. Retrieve information about a specific
+   * domain using the `region` and `domain_id` parameters.
    *
    * @param request - The request {@link GetDomainRequest}
    * @returns A Promise of Domain
@@ -281,7 +289,8 @@ export class API extends ParentAPI {
     )
 
   /**
-   * List domains in a project and/or in an organization.
+   * List domains. Retrieve domains in a specific project or in a specific
+   * Organization using the `region` parameter.
    *
    * @param request - The request {@link ListDomainsRequest}
    * @returns A Promise of ListDomainsResponse
@@ -290,7 +299,9 @@ export class API extends ParentAPI {
     enrichForPagination('domains', this.pageOfListDomains, request)
 
   /**
-   * Revoke a domain.
+   * Delete a domain. You must specify the domain you want to delete by the
+   * `region` and `domain_id`. Deleting a domain is permanent and cannot be
+   * undone.
    *
    * @param request - The request {@link RevokeDomainRequest}
    * @returns A Promise of Domain
@@ -310,7 +321,8 @@ export class API extends ParentAPI {
     )
 
   /**
-   * Ask for an immediate check of a domain (DNS check).
+   * Domain DNS check. Perform an immediate DNS check of a domain using the
+   * `region` and `domain_id` parameters.
    *
    * @param request - The request {@link CheckDomainRequest}
    * @returns A Promise of Domain

packages/clients/src/api/tem/v1alpha1/types.gen.ts

@@ -25,20 +25,17 @@ export type EmailStatus =
 export interface CreateEmailRequestAddress {
   /** Email address. */
   email: string
-  /** Optional display name. */
+  /** (Optional) Name displayed. */
   name?: string
 }
 
 /** Create email request. attachment. */
 export interface CreateEmailRequestAttachment {
   /** Filename of the attachment. */
   name: string
-  /**
-   * MIME type of the attachment (Currently only allow, text files, pdf and html
-   * files).
-   */
+  /** MIME type of the attachment. */
   type: string
-  /** Content of the attachment, encoded in base64. */
+  /** Content of the attachment encoded in base64. */
   content: string
 }
 
@@ -52,27 +49,27 @@ export interface CreateEmailResponse {
 export interface Domain {
   /** ID of the domain. */
   id: string
-  /** ID of the organization to which the domain belongs. */
+  /** ID of the domain's Organization. */
   organizationId: string
-  /** ID of the project. */
+  /** ID of the domain's Project. */
   projectId: string
   /** Domain name (example.com). */
   name: string
   /** Status of the domain. */
   status: DomainStatus
-  /** Date and time of domain's creation. */
+  /** Date and time of domain creation. */
   createdAt?: Date
   /** Date and time of the next scheduled check. */
   nextCheckAt?: Date
-  /** Date and time the domain was last found to be valid. */
+  /** Date and time the domain was last valid. */
   lastValidAt?: Date
-  /** Date and time of the revocation of the domain. */
+  /** Date and time of the domain's deletion. */
   revokedAt?: Date
-  /** Error message if the last check failed. */
+  /** Error message returned if the last check failed. */
   lastError?: string
-  /** Snippet of the SPF record that should be registered in the DNS zone. */
+  /** Snippet of the SPF record to register in the DNS zone. */
   spfConfig: string
-  /** DKIM public key, as should be recorded in the DNS zone. */
+  /** DKIM public key to record in the DNS zone. */
   dkimConfig: string
   /** Domain's statistics. */
   statistics?: DomainStatistics
@@ -90,53 +87,53 @@ export interface DomainStatistics {
 export interface Email {
   /** Technical ID of the email. */
   id: string
-  /** MessageID of the email. */
+  /** Message ID of the email. */
   messageId: string
-  /** ID of the project to which the email belongs. */
+  /** ID of the Project to which the email belongs. */
   projectId: string
   /** Email address of the sender. */
   mailFrom: string
   /** Email address of the recipient. */
   rcptTo: string
-  /** Type of the recipient. */
+  /** Type of recipient. */
   rcptType: EmailRcptType
   /** Subject of the email. */
   subject: string
   /** Creation date of the email object. */
   createdAt?: Date
-  /** Last update time of the email object. */
+  /** Last update of the email object. */
   updatedAt?: Date
   /** Status of the email. */
   status: EmailStatus
-  /** Additional information on the status. */
+  /** Additional status information. */
   statusDetails?: string
-  /** Total number of attempts to send the email. */
+  /** Number of attempts to send the email. */
   tryCount: number
-  /** Informations about the latest three attempts to send the email. */
+  /** Information about the last three attempts to send the email. */
   lastTries: EmailTry[]
 }
 
 /** Email. try. */
 export interface EmailTry {
   /** Rank number of this attempt to send the email. */
   rank: number
-  /** Date of the attempt. */
+  /** Date of the attempt to send the email. */
   triedAt?: Date
   /**
    * The SMTP status code received after the attempt. 0 if the attempt did not
    * reach an SMTP server.
    */
   code: number
   /**
-   * The SMTP message received, if any. If the attempt did not reach an SMTP
-   * server, the message says why.
+   * The SMTP message received. If the attempt did not reach an SMTP server, the
+   * message returned explains what happened.
    */
   message: string
 }
 
 /** List domains response. */
 export interface ListDomainsResponse {
-  /** Total number of domains matching the request (without pagination). */
+  /** Number of domains that match the request (without pagination). */
   totalCount: number
   domains: Domain[]
 }
@@ -151,31 +148,31 @@ export interface ListEmailsResponse {
 
 /** Statistics. */
 export interface Statistics {
-  /** Total number of emails matching the request criteria. */
+  /** Total number of emails matching the requested criteria. */
   totalCount: number
   /**
-   * Number of emails still in the `new` transient state (received from the API,
-   * not yet processed).
+   * Number of emails still in the `new` transient state. This means emails
+   * received from the API but not yet processed.
    */
   newCount: number
   /**
-   * Number of emails still in the `sending` transient state (received from the
-   * API, not yet in their final status).
+   * Number of emails still in the `sending` transient state. This means emails
+   * received from the API but not yet in their final status.
    */
   sendingCount: number
   /**
-   * Number of emails in the final `sent` state (have been delivered to the
-   * target mail system).
+   * Number of emails in the final `sent` state. This means emails that have
+   * been delivered to the target mail system.
    */
   sentCount: number
   /**
-   * Number of emails in the final `failed` state (refused by the target mail
-   * system with a final error status).
+   * Number of emails in the final `failed` state. This means emails that have
+   * been refused by the target mail system with a final error status.
    */
   failedCount: number
   /**
-   * Number of emails in the final `canceled` state (canceled by customer's
-   * request).
+   * Number of emails in the final `canceled` state. This meanns emails that
+   * have been canceled upon request.
    */
   canceledCount: number
 }
@@ -186,25 +183,25 @@ export type CreateEmailRequest = {
    * config.
    */
   region?: Region
-  /** Sender information (must be from a checked domain declared in the project). */
+  /** Sender information. Must be from a checked domain declared in the Project. */
   from?: CreateEmailRequestAddress
   /** Array of recipient information (limited to 1 recipient). */
   to?: CreateEmailRequestAddress[]
   /** Array of recipient information (unimplemented). */
   cc?: CreateEmailRequestAddress[]
   /** Array of recipient information (unimplemented). */
   bcc?: CreateEmailRequestAddress[]
-  /** Message subject. */
+  /** Subject of the email. */
   subject: string
   /** Text content. */
   text: string
   /** HTML content. */
   html: string
-  /** ID of the project in which to create the email. */
+  /** ID of the Project in which to create the email. */
   projectId?: string
   /** Array of attachments. */
   attachments?: CreateEmailRequestAttachment[]
-  /** Maximum date to deliver mail. */
+  /** Maximum date to deliver the email. */
   sendBefore?: Date
 }
 
@@ -226,24 +223,24 @@ export type ListEmailsRequest = {
   region?: Region
   page?: number
   pageSize?: number
-  /** Optional ID of the project in which to list the emails. */
+  /** ID of the Project in which to list the emails (optional). */
   projectId?: string
-  /** Optional ID of the domain for which to list the emails. */
+  /** ID of the domain for which to list the emails (optional). */
   domainId?: string
-  /** Optional ID of the message for which to list the emails. */
+  /** ID of the message for which to list the emails (optional). */
   messageId?: string
-  /** Optional, list emails created after this date. */
+  /** Subject of the email. */
+  subject?: string
+  /** List emails created after this date (optional). */
   since?: Date
-  /** Optional, list emails created before this date. */
+  /** List emails created before this date (optional). */
   until?: Date
-  /** Optional, list emails sent with this `mail_from` sender's address. */
+  /** List emails sent with this `mail_from` sender's address (optional). */
   mailFrom?: string
-  /** Optional, list emails sent with this `mail_to` recipient's address. */
+  /** List emails sent with this `mail_to` recipient's address (optional). */
   mailTo?: string
-  /** Optional, list emails having any of this status. */
+  /** List emails having any of this status (optional). */
   statuses?: EmailStatus[]
-  /** Optional, list emails having this subject. */
-  subject?: string
 }
 
 export type GetStatisticsRequest = {
@@ -252,18 +249,18 @@ export type GetStatisticsRequest = {
    * config.
    */
   region?: Region
-  /** Optional, count emails for this project. */
+  /** Number of emails for this Project (optional). */
   projectId?: string
   /**
-   * Optional, count emails send from this domain (must be coherent with the
-   * `project_id` and the `organization_id`).
+   * Number of emails sent from this domain (must be coherent with the
+   * `project_id` and the `organization_id`) (optional).
    */
   domainId?: string
-  /** Optional, count emails created after this date. */
+  /** Number of emails created after this date (optional). */
   since?: Date
-  /** Optional, count emails created before this date. */
+  /** Number of emails created before this date (optional). */
   until?: Date
-  /** Optional, count emails sent with this `mail_from` sender's address. */
+  /** Number of emails sent with this `mail_from` sender's address (optional). */
   mailFrom?: string
 }
 
@@ -287,7 +284,7 @@ export type CreateDomainRequest = {
   projectId?: string
   /** Fully qualified domain dame. */
   domainName: string
-  /** Accept the Scaleway Terms of Service. */
+  /** Accept Scaleway's Terms of Service. */
   acceptTos: boolean
 }
 
@@ -307,7 +304,7 @@ export type ListDomainsRequest = {
    * config.
    */
   region?: Region
-  /** Page number (1 for the first page). */
+  /** Requested page number. Value must be greater or equal to 1. */
   page?: number
   /** Page size. */
   pageSize?: number
@@ -323,7 +320,7 @@ export type RevokeDomainRequest = {
    * config.
    */
   region?: Region
-  /** ID of the domain to revoke. */
+  /** ID of the domain to delete. */
   domainId: string
 }