@placeshakr/config 10.28.1 → 10.30.2-alpha.1

package/src/types.ts

@@ -527,6 +527,8 @@ export interface Enterprise extends Resource {
     whatsapp?: boolean;
     marketplace?: boolean;
     multiProfessionals?: boolean;
+    /** Integracion con PennyLane: activa el listado Bills y el sync. */
+    pennylane?: boolean;
   };
 
   /**
@@ -690,6 +692,13 @@ export interface User extends Resource {
 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`.
+   */
+  billing?: BillingIdentity;
+
   /**
    *
    */
@@ -1009,7 +1018,12 @@ export interface Seller extends Profile {
   /**
    * the provider related
    */
-  provider: string;
+  provider?: string;
+
+  /**
+   * the providers related
+   */
+  providers?: string[];
 
   /**
    * indicates if is a team leader
@@ -1100,6 +1114,12 @@ export interface Commissions {
  * Represents an provider
  */
 export interface Provider extends Resource {
+  /**
+   * Datos de facturacion. Se completa de forma incremental al facturar.
+   * Ver [[BillingIdentity]] y `config/src/billing`.
+   */
+  billing?: BillingIdentity;
+
   /**
    * The provider name
    */
@@ -2488,9 +2508,32 @@ 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. */
     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?: 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.
+   */
+  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?: BillingIdentity;
 };
 
 export type BillReceived = Bill & {
@@ -2651,6 +2694,12 @@ export type Price = {
  * Represents a materials provider
  */
 export interface MaterialsProvider extends Resource {
+  /**
+   * Datos de facturacion. Se completa de forma incremental al facturar.
+   * Ver [[BillingIdentity]] y `config/src/billing`.
+   */
+  billing?: BillingIdentity;
+
   /**
    * The material provider name
    */
@@ -3404,6 +3453,11 @@ export interface Invitation {
    */
   provider?: Provider;
 
+  /**
+   * Invited user's providers list
+   */
+  providers?: Provider[] | string[];
+
   /**
    * Invited user's district where he/she works
    */
@@ -4553,3 +4607,460 @@ export enum EmailEventsEnum {
   RESET_USER_PASSWORD = 'RESET_USER_PASSWORD',
   DOCUMENTS_ISSUES = 'DOCUMENTS_ISSUES',
 }
+
+/* -------------------------------------------------------------------------- */
+/*                                 PennyLane                                  */
+/* -------------------------------------------------------------------------- */
+
+/** Estado de la sincronizacion de una factura concreta con PennyLane. */
+export type PennylaneBillSync = {
+  status: 'PENDING' | 'SYNCED' | 'FAILED' | 'SKIPPED';
+  /** Id de la factura en PennyLane. */
+  invoiceId?: string;
+  /** Id de la factura acreditada en PennyLane (para avoirs). */
+  creditedInvoiceId?: string;
+  /** Id del avoir en PennyLane que cancela esta factura. */
+  creditNoteId?: string;
+  creditNoteNumber?: string;
+  creditNoteStatus?: 'PENDING' | 'SYNCED' | 'FAILED' | 'SKIPPED';
+  creditNoteError?: string;
+  /** Documento espejo en 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.
+   */
+  payloadHash?: string;
+  attempts?: number;
+  lastAttemptAt?: number;
+  lastSyncAt?: number;
+  syncedAt?: number;
+  error?: { code: string; message: string; status?: number };
+};
+
+/** De que campo de la factura de PennyLane se lee cada referencia. */
+export type PennylaneReferenceConfig = {
+  /** Campo donde el proveedor escribe la referencia de chantier. */
+  projectField: 'label' | 'invoice_number' | 'lines';
+  /** Campo donde el proveedor escribe la referencia de devis. */
+  devisField: 'label' | 'invoice_number' | 'lines';
+  /** Expresion regular con un grupo de captura. */
+  projectPattern?: string;
+  devisPattern?: string;
+};
+
+export type PennylaneIgnoredSupplier = {
+  name: string;
+  regNo?: string | null;
+  pennylaneId?: string | null;
+  ignoredAt: number;
+  ignoredBy?: string | null;
+};
+
+/** Configuracion de PennyLane por empresa: enterprises/{id}/configurations/pennylane */
+export type PennylaneConfiguration = {
+  enabled: boolean;
+  /** Identificador numérico de la empresa en PennyLane (ej. '156553'). */
+  companyId?: string;
+  push: { issued: boolean; received: boolean };
+  pull: { supplierInvoices: boolean };
+  /** false = enviar solo importes agregados + PDF. */
+  sendLineItems: boolean;
+  /** true mientras el mapeo contable no este cerrado con el contable. */
+  importAsIncomplete: boolean;
+  references: PennylaneReferenceConfig;
+  /** Estados de PennyLane que no se traen (borradores y ruido inicial). */
+  excludedStates?: string[];
+  /** Dias hacia atras en la carga inicial o el resync completo. */
+  lookbackDays?: number;
+  defaultLedgerAccountId?: string;
+  ledgerAccountByCategory?: Record<string, string>;
+  /** Analitico por chantier. Ver [[PennylaneCategoryConfig]]. */
+  categories?: PennylaneCategoryConfig;
+  /** Lista de proveedores cuyas facturas se ignoran automáticamente al sincronizar. */
+  ignoredSuppliers?: PennylaneIgnoredSupplier[];
+  /** Estado del sync. Solo lo escriben las Cloud Functions. */
+  sync?: {
+    supplierInvoices?: PennylaneSyncState;
+    customerInvoices?: PennylaneSyncState;
+  };
+};
+
+/**
+ * Analitico por chantier: una categoria de PennyLane por proyecto de Articho,
+ * la misma para las facturas emitidas y las recibidas de ese proyecto.
+ *
+ * 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.
+ */
+export type PennylaneCategoryConfig = {
+  /** Interruptor. Sin esto el sync no toca categorias. */
+  enabled: boolean;
+  /**
+   * Id del grupo creado a mano en PennyLane (p. ej. "Chantiers Articho").
+   * Es distinto en cada empresa: son espacios de PennyLane distintos.
+   */
+  groupId: number;
+  /** Categorizar tambien las facturas que Articho emite. */
+  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.
+   */
+  checkpoint: number;
+  lastRunAt: number;
+  lastError?: string | null;
+};
+
+export enum ImportedBillStatus {
+  /** Llego de PennyLane y no se ha podido resolver proyecto o devis. */
+  PENDING_ASSIGNMENT = 'PENDING_ASSIGNMENT',
+  /** Proyecto y devis resueltos: falta que un administrador confirme. */
+  READY_TO_ASSIGN = 'READY_TO_ASSIGN',
+  /** Ya tiene una factura creada dentro de un proyecto. */
+  ASSIGNED = 'ASSIGNED',
+  /** Descartada a mano. */
+  IGNORED = 'IGNORED',
+  /** Duplicado de otra factura importada. */
+  DUPLICATE = 'DUPLICATE',
+}
+
+export enum PennylaneSyncEventType {
+  IMPORTED = 'IMPORTED',
+  EXTERNAL_STATUS_CHANGE = 'EXTERNAL_STATUS_CHANGE',
+  BILL_STATUS_UPDATED = 'BILL_STATUS_UPDATED',
+  ASSIGNED = 'ASSIGNED',
+  IGNORED = 'IGNORED',
+  ERROR = 'ERROR',
+}
+
+/**
+ * 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.
+ */
+export type PennylaneSyncEvent = {
+  id: string;
+  date: number;
+  type: PennylaneSyncEventType;
+  message: string;
+  before?: Record<string, unknown>;
+  after?: Record<string, unknown>;
+  payload?: Record<string, unknown>;
+};
+
+/**
+ * Espejo de una factura de PennyLane dentro de 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.
+ */
+export type ImportedBill = {
+  id: string;
+  source: 'pennylane';
+  direction: 'supplier' | 'customer';
+  /** Id en PennyLane. Clave de deduplicacion. */
+  externalId: string;
+  enterpriseId: string;
+  status: ImportedBillStatus;
+
+  invoice: {
+    reference: string;
+    label?: string;
+    date: number;
+    dueDate?: number | null;
+    currency: string;
+    amountHT: number;
+    amountTVA: number;
+    amountTTC: number;
+    isPaid: boolean;
+    paidAt?: number | null;
+    externalStatus?: string | null;
+    /** Origen de la importacion en PennyLane: Email, API, PA/PDP... */
+    externalSource?: string | null;
+    fileUrl?: string | null;
+  };
+
+  counterparty: {
+    name: string;
+    regNo?: string | null;
+    pennylaneId?: string | null;
+  };
+
+  /** Referencias tal y como venian en la factura, y de que campo salieron. */
+  references: {
+    projectRef?: string | null;
+    devisRef?: string | null;
+    sources?: { project?: string; devis?: string };
+  };
+
+  /** Resolucion automatica. Nunca crea la factura por si sola. */
+  suggestion?: {
+    projectId?: string | null;
+    devisId?: string | null;
+    reasons: string[];
+  };
+
+  /** Asociacion confirmada por un administrador. */
+  assignment?: {
+    projectId: string;
+    devisId: string;
+    billId: string;
+    projectName?: string | null;
+    projectReference?: string | null;
+    devisName?: string | null;
+    assignedBy: string;
+    assignedAt: number;
+  } | null;
+
+  lastSyncAt: number;
+  createdAt: number;
+};
+
+/* -------------------------------------------------------------------------- */
+/*                          Identidad de facturacion                          */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Direccion postal desglosada.
+ *
+ * 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.
+ */
+export type PostalAddress = {
+  address: string;
+  postalCode: string;
+  city: string;
+  /** Codigo ISO de dos letras: FR, ES, BE... */
+  countryAlpha2: string;
+};
+
+export enum BillingPaymentConditions {
+  UPON_RECEIPT = 'upon_receipt',
+  DAYS_7 = '7_days',
+  DAYS_15 = '15_days',
+  DAYS_30 = '30_days',
+  DAYS_30_EOM = '30_days_end_of_month',
+  DAYS_45 = '45_days',
+  DAYS_45_EOM = '45_days_end_of_month',
+  DAYS_60 = '60_days',
+}
+
+export enum BillingLanguage {
+  FR = 'fr_FR',
+  EN = 'en_GB',
+  DE = 'de_DE',
+  ES = 'es_ES',
+}
+
+/**
+ * Datos necesarios para emitir una factura a esta entidad.
+ *
+ * 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.
+ *
+ * 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.
+ */
+/**
+ * Persona juridica o persona fisica.
+ *
+ * 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.
+ *
+ * Un `undefined` significa "todavia no lo sabemos", que es distinto de las
+ * otras dos: el formulario tiene que preguntarlo, no suponerlo.
+ */
+export type BillingLegalType = 'company' | 'individual';
+
+export type BillingIdentity = {
+  /** Empresa o particular. Ver [[BillingLegalType]]. */
+  legalType?: BillingLegalType;
+
+  /**
+   * Razon social. Obligatoria en empresas.
+   *
+   * 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.
+   */
+  legalName: string;
+
+  /** Nombre. Obligatorio en particulares; PennyLane lo pide separado. */
+  firstName?: string;
+  /** Apellidos. Obligatorio en particulares. */
+  lastName?: string;
+  /** Direccion de facturacion. Obligatoria. */
+  address: PostalAddress;
+  /** Direccion de entrega, si difiere de la de facturacion. */
+  deliveryAddress?: PostalAddress;
+  /** SIREN (9 digitos) o SIRET (14). */
+  registrationNumber?: string;
+  /** Numero de TVA intracomunitario. No confundir con el tipo de IVA. */
+  vatNumber?: string;
+  /** Correos a los que enviar la factura. */
+  emails?: string[];
+  phone?: string;
+  /** Persona o servicio destinatario dentro de la empresa. */
+  recipient?: string;
+  paymentConditions?: BillingPaymentConditions;
+  language?: BillingLanguage;
+  /** Notas que acompanan a la ficha del tercero. */
+  notes?: string;
+  /**
+   * Id del tercero en PennyLane, cacheado tras la primera factura. Evita
+   * volver a buscarlo y, sobre todo, evita duplicar la ficha.
+   */
+  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]].
+   */
+  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]].
+   */
+  enrichment?: BillingEnrichment;
+
+  updatedAt?: number;
+  updatedBy?: string;
+};
+
+/**
+ * Lo que el registro publico dice de la empresa de un tercero.
+ *
+ * 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.
+ */
+export interface BillingInseeData {
+  /** SIREN, 9 digitos. */
+  siren?: string;
+  /** SIRET del establecimiento consultado, 14 digitos. */
+  siret?: string;
+  /** Si el establecimiento consultado es el domicilio social. */
+  siege?: boolean;
+  /** Categoria juridica (`categorieJuridiqueUniteLegale`). */
+  legalForm?: string | null;
+  /** Codigo APE/NAF (`activitePrincipaleUniteLegale`). */
+  nafCode?: string | null;
+  /** Estado de la unidad legal: `A` activa, `C` cesada. */
+  state?: string | null;
+  /** Estado del establecimiento: `A` activo, `F` cerrado. */
+  establishmentState?: string | null;
+  /** Nombre comercial, si difiere de la razon social. */
+  tradeName?: string | null;
+  /** Como se resolvio: `siret`, `siege` o `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.
+   */
+  sirenFoundBy?: string;
+  /** Resultado de validar el numero de TVA contra VIES. */
+  vatCheck?: BillingVatCheck;
+  /** Cuando se consulto el registro por ultima vez. */
+  checkedAt?: number;
+}
+
+/**
+ * Validacion del numero de TVA intracomunitario contra el registro VIES.
+ *
+ * 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.
+ */
+export interface BillingVatCheck {
+  /** El numero que se comprobo. */
+  number: string;
+  status: 'VALID' | 'INVALID' | 'UNAVAILABLE';
+  /** `null` cuando VIES no contesto: no se sabe, que no es lo mismo que no. */
+  valid: boolean | null;
+  reason?: string | null;
+  source: string;
+  checkedAt: number;
+}
+
+/**
+ * Gravedad de una incidencia de enriquecimiento.
+ *
+ * - `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.
+ */
+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.
+ */
+export enum BillingEnrichmentCode {
+  /** La ficha no trae ni SIREN ni SIRET. */
+  NO_IDENTIFIER = 'NO_IDENTIFIER',
+  /** Hay varias empresas con esa razon social: hace falta elegir a mano. */
+  SIREN_AMBIGUOUS = 'SIREN_AMBIGUOUS',
+  /** El identificador no aparece en el registro. */
+  NOT_FOUND = 'NOT_FOUND',
+  /** La unidad legal figura cesada. */
+  COMPANY_CLOSED = 'COMPANY_CLOSED',
+  /** El establecimiento figura cerrado; la empresa puede seguir viva. */
+  ESTABLISHMENT_CLOSED = 'ESTABLISHMENT_CLOSED',
+  /** El numero de TVA no consta en VIES. Probable franquicia en base. */
+  VAT_NOT_REGISTERED = 'VAT_NOT_REGISTERED',
+  /** VIES no contesto: el numero se guardo sin verificar. */
+  VAT_UNVERIFIED = 'VAT_UNVERIFIED',
+  /** VIES devuelve una razon social distinta de la del INSEE. */
+  VAT_NAME_MISMATCH = 'VAT_NAME_MISMATCH',
+  /** Establecimiento fuera de Francia: falta informar el pais. */
+  FOREIGN_ADDRESS = 'FOREIGN_ADDRESS',
+  MISSING_POSTAL_CODE = 'MISSING_POSTAL_CODE',
+  MISSING_STREET = 'MISSING_STREET',
+  /** La consulta al registro fallo (red, cuota, credenciales). */
+  LOOKUP_ERROR = 'LOOKUP_ERROR',
+}
+
+/**
+ * Que paso la ultima vez que se intento completar los datos de facturacion de
+ * esta ficha desde los registros publicos.
+ *
+ * `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.
+ *
+ * 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.
+ */
+export interface BillingEnrichment {
+  /** Un mensaje por linea, separados por `\n`. Vacio cuando `level` es `ok`. */
+  text: string;
+  /** Los mismos mensajes, sin unir. */
+  messages: string[];
+  codes: BillingEnrichmentCode[];
+  level: BillingEnrichmentLevel;
+  /** Quien lo escribio, p. ej. `insee-script`. */
+  source: string;
+  checkedAt: number;
+}