@placeshakr/config 10.30.2-alpha.1 → 10.31.0

package/src/types.ts

@@ -527,7 +527,7 @@ export interface Enterprise extends Resource {
     whatsapp?: boolean;
     marketplace?: boolean;
     multiProfessionals?: boolean;
-    /** Integracion con PennyLane: activa el listado Bills y el sync. */
+    /** PennyLane integration: enables the Bills listing and the sync. */
     pennylane?: boolean;
   };
 
@@ -693,9 +693,9 @@ type Permissions = Record<string, boolean>;
 
 export interface Profile extends Resource {
   /**
-   * Datos de facturacion del tercero. Vive en Profile —y no en Client, Pro y
-   * Seller por separado— porque los tres lo heredan y el SDK escribe contra
-   * este tipo. Ver [[BillingIdentity]] y `config/src/billing`.
+   * The third party's billing data. It lives on Profile — and not on Client,
+   * Pro and Seller separately — because all three inherit from it and the SDK
+   * writes against this type. See [[BillingIdentity]] and `config/src/billing`.
    */
   billing?: BillingIdentity;
 
@@ -2508,30 +2508,31 @@ export type Bill = Resource & {
   // used to save information related with any possible external system
   metadata?: {
     sentToIpaidthat?: boolean;
-    /** @deprecated usar metadata.pennylane. Se mantiene hasta retirar el envio por email. */
+    /** @deprecated use metadata.pennylane. Kept until email delivery is retired. */
     sentToPennyLane?: boolean;
     /** @deprecated usar metadata.pennylane.lastSyncAt */
     sentToPennyLaneDate?: number;
     /**
-     * Estado de sincronizacion con PennyLane. Sustituye a los dos booleanos
-     * de arriba: guarda el id contable, el hash del ultimo payload enviado
-     * (idempotencia) y el error, para poder reintentar sin duplicar.
+     * PennyLane sync state. Replaces the two booleans above: it holds the
+     * accounting id, the hash of the last payload sent (idempotency) and the
+     * error, so a retry never duplicates.
      */
     pennylane?: PennylaneBillSync;
   };
 
   /**
-   * Origen del documento cuando no se ha creado en Articho. Las facturas con
-   * source distinto de undefined no se editan ni se borran desde la app: la
-   * autoridad esta en firestore.rules.
+   * Where the document came from when it was not created in Articho. Bills
+   * whose source is not undefined are neither edited nor deleted from the app:
+   * the authority on that is firestore.rules.
    */
   source?: 'pennylane';
   imported?: boolean;
 
   /**
-   * Datos de facturacion del destinatario, cuando este no tiene ficha propia
-   * (fournisseur de materiaux, de services y personnalise). Para CLIENT, PRO y
-   * PROVIDER viven en la ficha del tercero. Ver `config/src/billing`.
+   * Billing data of the recipient when they have no record of their own
+   * (fournisseur de matériaux, de services and personnalisé). For CLIENT, PRO
+   * and PROVIDER it lives on the third party's record. See
+   * `config/src/billing`.
    */
   billing?: BillingIdentity;
 };
@@ -4612,24 +4613,24 @@ export enum EmailEventsEnum {
 /*                                 PennyLane                                  */
 /* -------------------------------------------------------------------------- */
 
-/** Estado de la sincronizacion de una factura concreta con PennyLane. */
+/** Sync state of one specific bill against PennyLane. */
 export type PennylaneBillSync = {
   status: 'PENDING' | 'SYNCED' | 'FAILED' | 'SKIPPED';
-  /** Id de la factura en PennyLane. */
+  /** Invoice id in PennyLane. */
   invoiceId?: string;
-  /** Id de la factura acreditada en PennyLane (para avoirs). */
+  /** Id of the credited invoice in PennyLane (for credit notes). */
   creditedInvoiceId?: string;
-  /** Id del avoir en PennyLane que cancela esta factura. */
+  /** Id of the PennyLane credit note that cancels this invoice. */
   creditNoteId?: string;
   creditNoteNumber?: string;
   creditNoteStatus?: 'PENDING' | 'SYNCED' | 'FAILED' | 'SKIPPED';
   creditNoteError?: string;
-  /** Documento espejo en enterprises/{id}/importedBills. */
+  /** Mirror document under enterprises/{id}/importedBills. */
   importedBillId?: string;
   fileAttachmentId?: string;
   /**
-   * Hash del payload enviado. PennyLane no ofrece Idempotency-Key, asi que la
-   * deduplicacion es nuestra: mismo hash que el ultimo SYNCED, no se reenvia.
+   * Hash of the payload sent. PennyLane offers no Idempotency-Key, so
+   * deduplication is ours: same hash as the last SYNCED, nothing is resent.
    */
   payloadHash?: string;
   attempts?: number;
@@ -4639,13 +4640,13 @@ export type PennylaneBillSync = {
   error?: { code: string; message: string; status?: number };
 };
 
-/** De que campo de la factura de PennyLane se lee cada referencia. */
+/** Which field of the PennyLane invoice each reference is read from. */
 export type PennylaneReferenceConfig = {
-  /** Campo donde el proveedor escribe la referencia de chantier. */
+  /** Field where the supplier writes the chantier reference. */
   projectField: 'label' | 'invoice_number' | 'lines';
-  /** Campo donde el proveedor escribe la referencia de devis. */
+  /** Field where the supplier writes the devis reference. */
   devisField: 'label' | 'invoice_number' | 'lines';
-  /** Expresion regular con un grupo de captura. */
+  /** Regular expression with a single capture group. */
   projectPattern?: string;
   devisPattern?: string;
 };
@@ -4658,29 +4659,29 @@ export type PennylaneIgnoredSupplier = {
   ignoredBy?: string | null;
 };
 
-/** Configuracion de PennyLane por empresa: enterprises/{id}/configurations/pennylane */
+/** Per-enterprise PennyLane configuration: enterprises/{id}/configurations/pennylane */
 export type PennylaneConfiguration = {
   enabled: boolean;
-  /** Identificador numérico de la empresa en PennyLane (ej. '156553'). */
+  /** Numeric id of the company in PennyLane (e.g. '156553'). */
   companyId?: string;
   push: { issued: boolean; received: boolean };
   pull: { supplierInvoices: boolean };
-  /** false = enviar solo importes agregados + PDF. */
+  /** false = send aggregate amounts + PDF only. */
   sendLineItems: boolean;
-  /** true mientras el mapeo contable no este cerrado con el contable. */
+  /** true while the accounting mapping is not settled with the accountant. */
   importAsIncomplete: boolean;
   references: PennylaneReferenceConfig;
-  /** Estados de PennyLane que no se traen (borradores y ruido inicial). */
+  /** PennyLane states that are not pulled (drafts and initial noise). */
   excludedStates?: string[];
-  /** Dias hacia atras en la carga inicial o el resync completo. */
+  /** Days to look back on the initial load or a full resync. */
   lookbackDays?: number;
   defaultLedgerAccountId?: string;
   ledgerAccountByCategory?: Record<string, string>;
-  /** Analitico por chantier. Ver [[PennylaneCategoryConfig]]. */
+  /** Analytical breakdown per chantier. See [[PennylaneCategoryConfig]]. */
   categories?: PennylaneCategoryConfig;
-  /** Lista de proveedores cuyas facturas se ignoran automáticamente al sincronizar. */
+  /** Suppliers whose invoices are ignored automatically on sync. */
   ignoredSuppliers?: PennylaneIgnoredSupplier[];
-  /** Estado del sync. Solo lo escriben las Cloud Functions. */
+  /** Sync state. Written by the Cloud Functions only. */
   sync?: {
     supplierInvoices?: PennylaneSyncState;
     customerInvoices?: PennylaneSyncState;
@@ -4688,47 +4689,69 @@ export type PennylaneConfiguration = {
 };
 
 /**
- * Analitico por chantier: una categoria de PennyLane por proyecto de Articho,
- * la misma para las facturas emitidas y las recibidas de ese proyecto.
+ * Analytical breakdown per chantier: one PennyLane category per Articho
+ * project, the same one for that project's issued and received invoices.
  *
- * El GRUPO de categorias no se puede crear por API: lo da de alta una persona
- * en PennyLane y su id se pega aqui. Y las categorias, una vez creadas, NO se
- * pueden borrar por API —solo renombrar—, asi que se crean perezosamente: la
- * primera vez que un proyecto recibe o emite una factura, nunca al crear el
- * proyecto. Un proyecto que nunca factura no ensucia el plan analitico.
+ * The category GROUP cannot be created through the API: a person creates it in
+ * PennyLane and its id is pasted here. And categories, once created, can NOT
+ * be deleted through the API — only renamed — so they are created lazily: the
+ * first time a project receives or issues an invoice, never when the project
+ * is created. A project that never invoices does not pollute the chart.
  */
 export type PennylaneCategoryConfig = {
-  /** Interruptor. Sin esto el sync no toca categorias. */
+  /** Master switch. Without it the sync never touches categories. */
   enabled: boolean;
   /**
-   * Id del grupo creado a mano en PennyLane (p. ej. "Chantiers Articho").
-   * Es distinto en cada empresa: son espacios de PennyLane distintos.
+   * Id of the group created by hand in PennyLane (e.g. "Chantiers Articho").
+   * It differs per enterprise: they are separate PennyLane workspaces.
    */
   groupId: number;
-  /** Categorizar tambien las facturas que Articho emite. */
+  /** Also categorise the invoices Articho issues. */
   includeCustomerInvoices?: boolean;
 };
 
 export type PennylaneSyncState = {
   /**
-   * Marca de tiempo del ultimo cambio procesado. El changelog de PennyLane
-   * solo retiene 4 semanas: si esto se queda atras, hay perdida de datos.
+   * Timestamp of the last change processed. PennyLane's changelog only retains
+   * 4 weeks: if this falls behind, data is lost.
    */
   checkpoint: number;
   lastRunAt: number;
   lastError?: string | null;
+  /**
+   * Invoices that failed and must be retried on the next run.
+   *
+   * It exists so the checkpoint can advance even when an invoice fails. The
+   * alternative — holding the checkpoint back whenever there are errors —
+   * looks safer and is not: a single invoice that always fails (a corrupt PDF,
+   * a supplier that never resolves) would freeze the whole enterprise's sync,
+   * reprocessing an ever-growing window until the function times out.
+   */
+  pending?: PennylanePendingInvoice[];
+};
+
+/** An invoice awaiting retry, with its attempt count. */
+export type PennylanePendingInvoice = {
+  /** Invoice id in PennyLane. */
+  id: string;
+  /** Attempts used. On reaching [[PENNYLANE_MAX_RETRIES]] it is abandoned. */
+  attempts: number;
+  /** Last error, so the reason is visible without opening the logs. */
+  lastError: string;
+  /** When it last failed. */
+  lastAttemptAt: number;
 };
 
 export enum ImportedBillStatus {
-  /** Llego de PennyLane y no se ha podido resolver proyecto o devis. */
+  /** Arrived from PennyLane; project or devis could not be resolved. */
   PENDING_ASSIGNMENT = 'PENDING_ASSIGNMENT',
-  /** Proyecto y devis resueltos: falta que un administrador confirme. */
+  /** Project and devis resolved: waiting for an administrator to confirm. */
   READY_TO_ASSIGN = 'READY_TO_ASSIGN',
-  /** Ya tiene una factura creada dentro de un proyecto. */
+  /** Already has a bill created inside a project. */
   ASSIGNED = 'ASSIGNED',
-  /** Descartada a mano. */
+  /** Discarded by hand. */
   IGNORED = 'IGNORED',
-  /** Duplicado de otra factura importada. */
+  /** Duplicate of another imported invoice. */
   DUPLICATE = 'DUPLICATE',
 }
 
@@ -4742,8 +4765,8 @@ export enum PennylaneSyncEventType {
 }
 
 /**
- * Un evento por cada cosa que le pasa a una factura importada. Sin esto, una
- * factura que cambia sola de estado es indistinguible de un bug.
+ * One event per thing that happens to an imported invoice. Without this, an
+ * invoice that changes status on its own is indistinguishable from a bug.
  */
 export type PennylaneSyncEvent = {
   id: string;
@@ -4756,17 +4779,17 @@ export type PennylaneSyncEvent = {
 };
 
 /**
- * Espejo de una factura de PennyLane dentro de Articho.
+ * Mirror of a PennyLane invoice inside Articho.
  *
- * Vive a nivel de empresa y no dentro de un proyecto a proposito: una factura
- * que entra electronicamente no sabe a que proyecto pertenece. Es tambien la
- * fuente del listado "Bills" del menu de administradores.
+ * It deliberately lives at enterprise level and not inside a project: an
+ * invoice arriving electronically does not know which project it belongs to.
+ * It is also the source of the "Bills" listing in the administrator menu.
  */
 export type ImportedBill = {
   id: string;
   source: 'pennylane';
   direction: 'supplier' | 'customer';
-  /** Id en PennyLane. Clave de deduplicacion. */
+  /** Id in PennyLane. The deduplication key. */
   externalId: string;
   enterpriseId: string;
   status: ImportedBillStatus;
@@ -4783,7 +4806,7 @@ export type ImportedBill = {
     isPaid: boolean;
     paidAt?: number | null;
     externalStatus?: string | null;
-    /** Origen de la importacion en PennyLane: Email, API, PA/PDP... */
+    /** How it got into PennyLane: Email, API, PA/PDP… */
     externalSource?: string | null;
     fileUrl?: string | null;
   };
@@ -4794,21 +4817,21 @@ export type ImportedBill = {
     pennylaneId?: string | null;
   };
 
-  /** Referencias tal y como venian en la factura, y de que campo salieron. */
+  /** References exactly as they came on the invoice, and which field they came from. */
   references: {
     projectRef?: string | null;
     devisRef?: string | null;
     sources?: { project?: string; devis?: string };
   };
 
-  /** Resolucion automatica. Nunca crea la factura por si sola. */
+  /** Automatic resolution. It never creates the bill on its own. */
   suggestion?: {
     projectId?: string | null;
     devisId?: string | null;
     reasons: string[];
   };
 
-  /** Asociacion confirmada por un administrador. */
+  /** Association confirmed by an administrator. */
   assignment?: {
     projectId: string;
     devisId: string;
@@ -4825,22 +4848,22 @@ export type ImportedBill = {
 };
 
 /* -------------------------------------------------------------------------- */
-/*                          Identidad de facturacion                          */
+/*                              Billing identity                              */
 /* -------------------------------------------------------------------------- */
 
 /**
- * Direccion postal desglosada.
+ * Postal address, broken down.
  *
- * El campo `address` suelto que ya existe en varias entidades no sirve para
- * facturar: PennyLane —y la facturacion electronica en general— exige calle,
- * codigo postal, ciudad y pais como campos separados. Y `GeoLocation` solo
- * guarda lat/lng, asi que no hay de donde derivarlos.
+ * The loose `address` field several entities already carry is not usable for
+ * invoicing: PennyLane — and e-invoicing in general — requires street, postal
+ * code, city and country as separate fields. And `GeoLocation` only stores
+ * lat/lng, so there is nothing to derive them from.
  */
 export type PostalAddress = {
   address: string;
   postalCode: string;
   city: string;
-  /** Codigo ISO de dos letras: FR, ES, BE... */
+  /** Two-letter ISO code: FR, ES, BE… */
   countryAlpha2: string;
 };
 
@@ -4863,80 +4886,79 @@ export enum BillingLanguage {
 }
 
 /**
- * Datos necesarios para emitir una factura a esta entidad.
+ * Everything needed to issue an invoice to this entity.
  *
- * Es el mismo objeto para las cinco entidades facturables (Client, Pro,
- * Seller, Provider, MaterialsProvider) a proposito: un solo tipo, un solo
- * validador y un solo formulario, en lugar de cinco variantes que divergen.
+ * It is deliberately the same object for the five billable entities (Client,
+ * Pro, Seller, Provider, MaterialsProvider): one type, one validator and one
+ * form, instead of five variants that drift apart.
  *
- * Se rellena de forma incremental: el modal de envio a PennyLane pide lo que
- * falte justo antes de facturar y lo guarda aqui, de modo que solo se completa
- * para las entidades a las que de verdad se les factura.
+ * It is filled in incrementally: the PennyLane sending modal asks for whatever
+ * is missing right before invoicing and saves it here, so it only ever gets
+ * completed for the entities that actually get invoiced.
  */
 /**
- * Persona juridica o persona fisica.
+ * Legal person or natural person.
  *
- * No es un detalle de forma: decide que exige la ley y que endpoint de
- * PennyLane se usa. Una factura a una empresa entra en la facturacion
- * electronica —SIREN obligatorio, transmision por la red—; una a un particular
- * queda fuera del ambito y solo genera e-reporting, sin identificar al cliente.
+ * Not a cosmetic detail: it decides what the law requires and which PennyLane
+ * endpoint is used. An invoice to a company falls under e-invoicing — SIREN
+ * mandatory, transmitted over the network; one to a private individual is out
+ * of scope and only produces e-reporting, with no client identity.
  *
- * Un `undefined` significa "todavia no lo sabemos", que es distinto de las
- * otras dos: el formulario tiene que preguntarlo, no suponerlo.
+ * `undefined` means "we do not know yet", which is different from the other
+ * two: the form has to ask, not assume.
  */
 export type BillingLegalType = 'company' | 'individual';
 
 export type BillingIdentity = {
-  /** Empresa o particular. Ver [[BillingLegalType]]. */
+  /** Company or private individual. See [[BillingLegalType]]. */
   legalType?: BillingLegalType;
 
   /**
-   * Razon social. Obligatoria en empresas.
+   * Legal name. Mandatory for companies.
    *
-   * En un particular no se pide: se compone de nombre y apellidos con
-   * [[billingDisplayName]], para no tener dos sitios donde vive el mismo dato
-   * y que acaben diciendo cosas distintas.
+   * It is not asked of an individual: it is composed from first and last name
+   * by [[billingDisplayName]], so the same fact does not live in two places
+   * and end up saying different things.
    */
   legalName: string;
 
-  /** Nombre. Obligatorio en particulares; PennyLane lo pide separado. */
+  /** First name. Mandatory for individuals; PennyLane wants it separate. */
   firstName?: string;
-  /** Apellidos. Obligatorio en particulares. */
+  /** Last name. Mandatory for individuals. */
   lastName?: string;
-  /** Direccion de facturacion. Obligatoria. */
+  /** Billing address. Mandatory. */
   address: PostalAddress;
-  /** Direccion de entrega, si difiere de la de facturacion. */
+  /** Delivery address, when it differs from the billing one. */
   deliveryAddress?: PostalAddress;
-  /** SIREN (9 digitos) o SIRET (14). */
+  /** SIREN (9 digits) or SIRET (14). */
   registrationNumber?: string;
-  /** Numero de TVA intracomunitario. No confundir con el tipo de IVA. */
+  /** Intra-community VAT number. Not to be confused with the VAT rate. */
   vatNumber?: string;
-  /** Correos a los que enviar la factura. */
+  /** Addresses the invoice is sent to. */
   emails?: string[];
   phone?: string;
-  /** Persona o servicio destinatario dentro de la empresa. */
+  /** Recipient person or department inside the company. */
   recipient?: string;
   paymentConditions?: BillingPaymentConditions;
   language?: BillingLanguage;
-  /** Notas que acompanan a la ficha del tercero. */
+  /** Notes attached to the third party's record. */
   notes?: string;
   /**
-   * Id del tercero en PennyLane, cacheado tras la primera factura. Evita
-   * volver a buscarlo y, sobre todo, evita duplicar la ficha.
+   * The third party's id in PennyLane, cached after the first invoice. It
+   * avoids looking it up again and, above all, avoids duplicating the record.
    */
   pennylaneCustomerId?: string;
 
   /**
-   * Lo que dice el registro publico de la empresa, tal y como se leyo la
-   * ultima vez. No va impreso en la factura: es la procedencia de lo que hay
-   * arriba. Ver [[BillingInseeData]].
+   * What the public register says about the company, exactly as it was last
+   * read. It is not printed on the invoice: it is the provenance of what is
+   * above. See [[BillingInseeData]].
    */
   insee?: BillingInseeData;
 
   /**
-   * Que problemas se encontraron la ultima vez que se intento completar esta
-   * ficha desde los registros publicos. Pensado para pintarse como tooltip.
-   * Ver [[BillingEnrichment]].
+   * What went wrong the last time this record was completed from the public
+   * registers. Meant to be rendered as a tooltip. See [[BillingEnrichment]].
    */
   enrichment?: BillingEnrichment;
 
@@ -4945,57 +4967,58 @@ export type BillingIdentity = {
 };
 
 /**
- * Lo que el registro publico dice de la empresa de un tercero.
+ * What the public register says about a third party's company.
  *
- * Lo escribe `scripts/enrich-billing-from-insee.js`. Cuelga de
- * [[BillingIdentity]] junto al resto de lo que hace falta para facturar, pero
- * en su propio bloque: los campos de arriba son lo que va impreso en la
- * factura y los puede corregir una persona; esto es lo que dice el registro y
- * se reescribe en cada pasada.
+ * Written by `scripts/enrich-billing-from-insee.js`. It hangs off
+ * [[BillingIdentity]] alongside the rest of what invoicing needs, but in its
+ * own block: the fields above are what gets printed on the invoice and a human
+ * may correct them; this is what the register says and it is rewritten on
+ * every pass.
  */
 export interface BillingInseeData {
-  /** SIREN, 9 digitos. */
+  /** SIREN, 9 digits. */
   siren?: string;
-  /** SIRET del establecimiento consultado, 14 digitos. */
+  /** SIRET of the establishment queried, 14 digits. */
   siret?: string;
-  /** Si el establecimiento consultado es el domicilio social. */
+  /** Whether the establishment queried is the registered office. */
   siege?: boolean;
-  /** Categoria juridica (`categorieJuridiqueUniteLegale`). */
+  /** Legal form (`categorieJuridiqueUniteLegale`). */
   legalForm?: string | null;
-  /** Codigo APE/NAF (`activitePrincipaleUniteLegale`). */
+  /** APE/NAF code (`activitePrincipaleUniteLegale`). */
   nafCode?: string | null;
-  /** Estado de la unidad legal: `A` activa, `C` cesada. */
+  /** Legal unit state: `A` active, `C` ceased. */
   state?: string | null;
-  /** Estado del establecimiento: `A` activo, `F` cerrado. */
+  /** Establishment state: `A` open, `F` closed. */
   establishmentState?: string | null;
-  /** Nombre comercial, si difiere de la razon social. */
+  /** Trade name, when it differs from the legal name. */
   tradeName?: string | null;
-  /** Como se resolvio: `siret`, `siege` o `siege-fallback`. */
+  /** How it was resolved: `siret`, `siege` or `siege-fallback`. */
   matchedBy?: string;
   /**
-   * Presente solo si el SIREN no venia en la ficha y se dedujo buscando por
-   * razon social. Sirve para no confundir un dato aportado con uno inferido.
+   * Set only when the SIREN was absent from the record and was deduced by
+   * searching on the legal name. It keeps a supplied fact distinguishable from
+   * an inferred one.
    */
   sirenFoundBy?: string;
-  /** Resultado de validar el numero de TVA contra VIES. */
+  /** Result of checking the VAT number against VIES. */
   vatCheck?: BillingVatCheck;
-  /** Cuando se consulto el registro por ultima vez. */
+  /** When the register was last queried. */
   checkedAt?: number;
 }
 
 /**
- * Validacion del numero de TVA intracomunitario contra el registro VIES.
+ * Validation of the intra-community VAT number against the VIES register.
  *
- * El numero no lo publica el INSEE: se calcula a partir del SIREN, y la
- * formula siempre devuelve algo bien formado, tambien para quien esta en
- * franquicia en base y no tiene numero real. `valid: false` significa que el
- * numero no existe, no que este mal escrito.
+ * INSEE does not publish the number: it is computed from the SIREN, and the
+ * formula always returns something well-formed, including for someone under
+ * franchise en base who has no real number. `valid: false` means the number
+ * does not exist, not that it is malformed.
  */
 export interface BillingVatCheck {
-  /** El numero que se comprobo. */
+  /** The number that was checked. */
   number: string;
   status: 'VALID' | 'INVALID' | 'UNAVAILABLE';
-  /** `null` cuando VIES no contesto: no se sabe, que no es lo mismo que no. */
+  /** `null` when VIES did not answer: unknown, which is not the same as no. */
   valid: boolean | null;
   reason?: string | null;
   source: string;
@@ -5003,64 +5026,64 @@ export interface BillingVatCheck {
 }
 
 /**
- * Gravedad de una incidencia de enriquecimiento.
+ * Severity of an enrichment issue.
  *
- * - `ok`      la ficha se completo sin nada que senalar.
- * - `warning` se completo, pero hay algo que conviene mirar.
- * - `error`   no se pudo completar: falta el identificador, no esta en el
- *             registro, o la consulta fallo.
+ * - `ok`      the record was completed with nothing worth flagging.
+ * - `warning` it was completed, but something is worth a look.
+ * - `error`   it could not be completed: the identifier is missing, it is not
+ *             in the register, or the lookup failed.
  */
 export type BillingEnrichmentLevel = 'ok' | 'warning' | 'error';
 
 /**
- * Codigo de cada incidencia. Existe para poder filtrar y contar sin parsear
- * el texto, que esta escrito para leerse y puede cambiar de redaccion.
+ * Code for each issue. It exists so they can be filtered and counted without
+ * parsing the text, which is written to be read and may be reworded.
  */
 export enum BillingEnrichmentCode {
-  /** La ficha no trae ni SIREN ni SIRET. */
+  /** The record carries neither SIREN nor SIRET. */
   NO_IDENTIFIER = 'NO_IDENTIFIER',
-  /** Hay varias empresas con esa razon social: hace falta elegir a mano. */
+  /** Several companies share that legal name: a human must choose. */
   SIREN_AMBIGUOUS = 'SIREN_AMBIGUOUS',
-  /** El identificador no aparece en el registro. */
+  /** The identifier does not appear in the register. */
   NOT_FOUND = 'NOT_FOUND',
-  /** La unidad legal figura cesada. */
+  /** The legal unit is recorded as ceased. */
   COMPANY_CLOSED = 'COMPANY_CLOSED',
-  /** El establecimiento figura cerrado; la empresa puede seguir viva. */
+  /** The establishment is closed; the company may still be alive. */
   ESTABLISHMENT_CLOSED = 'ESTABLISHMENT_CLOSED',
-  /** El numero de TVA no consta en VIES. Probable franquicia en base. */
+  /** The VAT number is unknown to VIES. Likely franchise en base. */
   VAT_NOT_REGISTERED = 'VAT_NOT_REGISTERED',
-  /** VIES no contesto: el numero se guardo sin verificar. */
+  /** VIES did not answer: the number was stored unverified. */
   VAT_UNVERIFIED = 'VAT_UNVERIFIED',
-  /** VIES devuelve una razon social distinta de la del INSEE. */
+  /** VIES returns a legal name different from INSEE's. */
   VAT_NAME_MISMATCH = 'VAT_NAME_MISMATCH',
-  /** Establecimiento fuera de Francia: falta informar el pais. */
+  /** Establishment outside France: the country must be filled in by hand. */
   FOREIGN_ADDRESS = 'FOREIGN_ADDRESS',
   MISSING_POSTAL_CODE = 'MISSING_POSTAL_CODE',
   MISSING_STREET = 'MISSING_STREET',
-  /** La consulta al registro fallo (red, cuota, credenciales). */
+  /** The register lookup failed (network, quota, credentials). */
   LOOKUP_ERROR = 'LOOKUP_ERROR',
 }
 
 /**
- * Que paso la ultima vez que se intento completar los datos de facturacion de
- * esta ficha desde los registros publicos.
+ * What happened the last time this record's billing data was completed from
+ * the public registers.
  *
- * `text` es el campo que se pinta: texto plano, un mensaje por linea, listo
- * para un `title` o un tooltip. `messages` y `codes` estan para quien prefiera
- * pintarlos sueltos o filtrar por tipo de incidencia.
+ * `text` is the field meant to be displayed: plain text, one message per line,
+ * ready for a `title` or a tooltip. `messages` and `codes` are there for
+ * whoever prefers to render them separately or filter by issue type.
  *
- * El bloque se reescribe entero en cada pasada. Que este ausente significa que
- * la ficha nunca se reviso; que `level` sea `ok` significa que se reviso y no
- * habia nada que senalar.
+ * The whole block is rewritten on every pass. Its absence means the record was
+ * never reviewed; `level` being `ok` means it was reviewed and there was
+ * nothing to flag.
  */
 export interface BillingEnrichment {
-  /** Un mensaje por linea, separados por `\n`. Vacio cuando `level` es `ok`. */
+  /** One message per line, separated by `\n`. Empty when `level` is `ok`. */
   text: string;
-  /** Los mismos mensajes, sin unir. */
+  /** The same messages, unjoined. */
   messages: string[];
   codes: BillingEnrichmentCode[];
   level: BillingEnrichmentLevel;
-  /** Quien lo escribio, p. ej. `insee-script`. */
+  /** Who wrote it, e.g. `insee-script`. */
   source: string;
   checkedAt: number;
 }