@placeshakr/config 10.29.4 → 10.31.0-alpha.2

package/src/billing/pennylane.ts

@@ -0,0 +1,530 @@
+import * as articho from '../types';
+import { billingDisplayName } from './validate';
+
+/**
+ * Contrato de entrada del callable `pennylaneV2-createCustomerInvoice`.
+ * Se declara aquí, en el paquete compartido, para que la app y las Cloud
+ * Functions hablen exactamente del mismo objeto.
+ */
+export type PennylaneAddressPayload = {
+  address: string;
+  postalCode: string;
+  city: string;
+  countryAlpha2: string;
+};
+
+export type PennylaneInvoicePayload = {
+  customerId?: number | null;
+  customer?: {
+    name: string;
+    /** Empresa o particular. Decide el endpoint que usa la Cloud Function. */
+    legalType?: articho.BillingLegalType;
+    /** Solo en particulares: PennyLane pide el nombre partido. */
+    firstName?: string;
+    lastName?: string;
+    billingAddress: PennylaneAddressPayload;
+    deliveryAddress?: PennylaneAddressPayload;
+    regNo?: string;
+    vatNumber?: string;
+    emails?: string[];
+    phone?: string;
+    recipient?: string;
+    notes?: string;
+    paymentConditions?: string;
+    billingLanguage?: string;
+    externalReference?: string;
+    archiId?: string;
+  };
+  date: string;
+  deadline: string;
+  lines: Array<{
+    label: string;
+    quantity: number;
+    unit: string;
+    unitPrice: number;
+    vatRate: string;
+    description?: string;
+    discount?: { type: 'absolute' | 'relative'; value: number };
+  }>;
+  draft?: boolean;
+  currency?: string;
+  language?: string;
+  label?: string;
+  externalReference?: string;
+  pdfInvoiceSubject?: string;
+  specialMention?: string;
+  discount?: { type: 'absolute' | 'relative'; value: number };
+  sendToPa?: boolean;
+  projectId?: string | null;
+  billId?: string | null;
+  creditedInvoiceId?: number | null;
+};
+
+/** Días que añade cada condición de pago a la fecha de la factura. */
+const TERM_DAYS: Record<string, number> = {
+  [articho.TermsOfPayment.UPON_RECEIPT]: 0,
+  [articho.TermsOfPayment.MONTH_END]: 30,
+  [articho.TermsOfPayment.DAYS_10]: 10,
+  [articho.TermsOfPayment.DAYS_20]: 20,
+  [articho.TermsOfPayment.DAYS_30]: 30,
+  [articho.TermsOfPayment.DAYS_30_END_MONTH]: 30,
+  [articho.TermsOfPayment.DAYS_45]: 45,
+  [articho.TermsOfPayment.DAYS_60]: 60,
+  [articho.TermsOfPayment.DAYS_60_END_MONTH]: 60,
+  [articho.TermsOfPayment.DAYS_90]: 90,
+  [articho.TermsOfPayment.DAYS_90_END_MONTH]: 90,
+  [articho.TermsOfPayment.DAYS_120]: 120,
+};
+
+/** Condición de pago de Articho → la que entiende PennyLane. */
+const PAYMENT_CONDITIONS: Record<string, articho.BillingPaymentConditions> = {
+  [articho.TermsOfPayment.UPON_RECEIPT]: articho.BillingPaymentConditions.UPON_RECEIPT,
+  [articho.TermsOfPayment.DAYS_10]: articho.BillingPaymentConditions.DAYS_7,
+  [articho.TermsOfPayment.DAYS_20]: articho.BillingPaymentConditions.DAYS_15,
+  [articho.TermsOfPayment.DAYS_30]: articho.BillingPaymentConditions.DAYS_30,
+  [articho.TermsOfPayment.MONTH_END]: articho.BillingPaymentConditions.DAYS_30_EOM,
+  [articho.TermsOfPayment.DAYS_30_END_MONTH]:
+    articho.BillingPaymentConditions.DAYS_30_EOM,
+  [articho.TermsOfPayment.DAYS_45]: articho.BillingPaymentConditions.DAYS_45,
+  [articho.TermsOfPayment.DAYS_60]: articho.BillingPaymentConditions.DAYS_60,
+  [articho.TermsOfPayment.DAYS_60_END_MONTH]: articho.BillingPaymentConditions.DAYS_60,
+  [articho.TermsOfPayment.DAYS_90]: articho.BillingPaymentConditions.DAYS_60,
+  [articho.TermsOfPayment.DAYS_90_END_MONTH]: articho.BillingPaymentConditions.DAYS_60,
+  [articho.TermsOfPayment.DAYS_120]: articho.BillingPaymentConditions.DAYS_60,
+};
+
+/**
+ * Porcentaje de IVA → código de PennyLane.
+ * @param {number} rate Porcentaje (20, 10, 5.5, 0).
+ * @param {boolean} hasTva false cuando la factura va sin IVA.
+ * @return {string} Código de IVA.
+ */
+export const toVatRateCode = (rate?: number, hasTva = true): string => {
+  if (!hasTva) return 'exempt';
+
+  switch (Math.round((rate ?? 0) * 10) / 10) {
+    case 20:
+      return 'FR_200';
+    case 10:
+      return 'FR_100';
+    case 5.5:
+      return 'FR_055';
+    case 2.1:
+      return 'FR_021';
+    case 0:
+      return 'exempt';
+    default:
+      return 'any';
+  }
+};
+
+const toISODate = (value: number) => new Date(value).toISOString().slice(0, 10);
+
+const toDiscount = (
+  value?: number,
+  type?: articho.BillDiscountType
+): { type: 'absolute' | 'relative'; value: number } | undefined => {
+  if (!value) return undefined;
+  return {
+    type: type === articho.BillDiscountType.PERCENT ? 'relative' : 'absolute',
+    value,
+  };
+};
+
+/**
+ * Determina si una factura emitida ya está sincronizada o enviada a PennyLane.
+ *
+ * Casos especiales:
+ * 1. Si el estado es FAILED, NO se considera enviada para permitir reintentar tras corregir el error.
+ * 2. Si fue importada desde PennyLane, ya existe en PennyLane.
+ * 3. Para avoirs (CREDIT_NOTE), invoiceId puede haber sido copiado de la factura origen.
+ *    Solo se considera verdaderamente enviada si está SYNCED, tiene un invoiceId propio y
+ *    un creditedInvoiceId distinto de su propio invoiceId.
+ *
+ * @param {articho.BillIssued} [bill] Factura emitida.
+ * @return {boolean} true si ya está enviada/sincronizada en PennyLane.
+ */
+export const isBillIssuedSentToPennylane = (bill?: articho.BillIssued): boolean => {
+  if (!bill) return false;
+
+  const isFailed = bill.metadata?.pennylane?.status === 'FAILED';
+  if (isFailed) return false;
+
+  if (
+    bill.imported === true ||
+    bill.source === 'pennylane' ||
+    Boolean(bill.metadata?.pennylane?.importedBillId)
+  ) {
+    return true;
+  }
+
+  const isCreditNote = bill.subType === articho.BillIssuedType.CREDIT_NOTE;
+  if (isCreditNote) {
+    return Boolean(
+      bill.metadata?.pennylane?.status === 'SYNCED' &&
+      bill.metadata?.pennylane?.invoiceId &&
+      bill.metadata?.pennylane?.creditedInvoiceId &&
+      String(bill.metadata.pennylane.invoiceId) !==
+        String(bill.metadata.pennylane.creditedInvoiceId)
+    );
+  }
+
+  return Boolean(
+    bill.metadata?.pennylane?.status === 'SYNCED' ||
+    bill.metadata?.pennylane?.invoiceId ||
+    bill.metadata?.sentToPennyLane
+  );
+};
+
+/**
+ * Motivos por los que una factura de Articho no se puede enviar a PennyLane.
+ * @param {articho.BillIssued} bill Factura emitida.
+ * @return {string[]} Claves de traducción de los bloqueos encontrados.
+ */
+export const getBillBlockers = (bill: articho.BillIssued): string[] => {
+  const blockers: string[] = [];
+
+  if (!bill?.elements?.length) blockers.push('pennylane.blocker.noElements');
+
+  if (bill?.subType === articho.BillIssuedType.CREDIT_NOTE) {
+    // Un avoir solo se puede enviar si tiene una factura de origen asociada
+    if (!bill?.billSource?.id) {
+      blockers.push('pennylane.blocker.creditNoteWithoutSource');
+    }
+  }
+
+  if (isBillIssuedSentToPennylane(bill)) {
+    blockers.push('pennylane.blocker.alreadySent');
+  }
+
+  const withoutLabel = bill?.elements?.some((element) => !element?.description?.trim());
+  if (withoutLabel) blockers.push('pennylane.blocker.elementWithoutLabel');
+
+  return blockers;
+};
+
+/**
+ * Traduce o formatea de forma legible los mensajes de error devueltos por PennyLane
+ * para que el usuario en la interfaz comprenda qué ocurrió sin ver códigos HTTP crudos.
+ *
+ * @param {string} [rawMessage] Mensaje de error recibido.
+ * @return {string} Mensaje traducido y formateado.
+ */
+export const formatPennylaneErrorMessage = (rawMessage?: string): string => {
+  if (!rawMessage) return '';
+
+  const msg = rawMessage.trim();
+
+  // Si el mensaje ya está estructurado y traducido en francés, conservarlo
+  if (
+    msg.includes('Authentification échouée') ||
+    msg.includes('Accès refusé par PennyLane') ||
+    msg.includes('Ressource introuvable sur PennyLane') ||
+    msg.includes('Données rejetées par PennyLane') ||
+    msg.includes('Limite de requêtes atteinte') ||
+    msg.includes('Le service PennyLane est temporairement indisponible')
+  ) {
+    return msg;
+  }
+
+  // Mapeo según patrones o códigos HTTP
+  if (msg.includes('401') || msg.toLowerCase().includes('unauthorized')) {
+    return "Authentification échouée auprès de PennyLane (401). Le jeton API est manquant, invalide ou a expiré.";
+  }
+  if (msg.includes('403') || msg.toLowerCase().includes('forbidden')) {
+    return "Accès refusé par PennyLane (403). La clé API ne dispose pas des droits nécessaires pour cette entreprise.";
+  }
+  if (msg.includes('404') || msg.toLowerCase().includes('not found')) {
+    return "Ressource introuvable sur PennyLane (404) : le client, le tiers ou la facture d'origine n'existe pas.";
+  }
+  if (msg.includes('409') || msg.toLowerCase().includes('conflict')) {
+    return "Conflit sur PennyLane (409) : une facture ou ressource similaire existe déjà.";
+  }
+  if (msg.includes('413') || msg.toLowerCase().includes('too large')) {
+    return "Le document envoyé dépasse la limite de taille autorisée par PennyLane (100 Mo max).";
+  }
+  if (msg.includes('422') || msg.toLowerCase().includes('unprocessable')) {
+    return msg.length > 40 && !msg.startsWith('PennyLane 422')
+      ? msg
+      : "Les données envoyées ne respectent pas les règles comptables de PennyLane (422) : vérifiez les montants, lignes et TVA.";
+  }
+  if (msg.includes('429') || msg.toLowerCase().includes('rate limit')) {
+    return "Limite de requêtes atteinte sur PennyLane (429). Veuillez patienter quelques instants avant de réessayer.";
+  }
+  if (
+    msg.includes('500') ||
+    msg.includes('502') ||
+    msg.includes('503') ||
+    msg.includes('504') ||
+    msg.toLowerCase().includes('internal server error')
+  ) {
+    return "Le service PennyLane est temporairement indisponible ou rencontre une erreur interne. Veuillez réessayer dans quelques instants.";
+  }
+
+  return msg;
+};
+
+/**
+ * Traduce una factura emitida de Articho a la entrada del callable de PennyLane.
+ *
+ * Cada `BillElement` se convierte en una línea: PennyLane calcula los totales
+ * a partir de ellas, así que no se envían ni el total ni el número de factura
+ * —ese lo asigna PennyLane, que es justo lo que se busca—.
+ *
+ * Para avoirs (`CREDIT_NOTE`), los precios unitarios se invierten a negativo
+ * según la especificación de PennyLane v2 y se vincula `credited_invoice_id`.
+ *
+ * @param {articho.BillIssued} bill Factura emitida.
+ * @param {object} context Destinatario y opciones de envío.
+ * @return {PennylaneInvoicePayload} Carga útil para el callable.
+ */
+export const billIssuedToPennylanePayload = (
+  bill: articho.BillIssued,
+  context: {
+    entity: articho.BillIssuedEntity;
+    billing: articho.BillingIdentity;
+    entityId?: string;
+    projectId?: string;
+    sendToPa?: boolean;
+    draft?: boolean;
+    creditedInvoiceId?: string | number | null;
+  }
+): PennylaneInvoicePayload => {
+  const isCreditNote = bill?.subType === articho.BillIssuedType.CREDIT_NOTE;
+  const date = bill?.date ?? Date.now();
+  const termDays = isCreditNote ? 0 : (TERM_DAYS[bill?.termsOfPayment ?? ''] ?? 30);
+  const deadline = date + termDays * 24 * 60 * 60 * 1000;
+
+  const { billing } = context;
+
+  const creditedInvoiceId =
+    context.creditedInvoiceId !== undefined && context.creditedInvoiceId !== null
+      ? Number(context.creditedInvoiceId)
+      : undefined;
+
+  const displayLabel = isCreditNote
+    ? bill?.billSource?.reference
+      ? `Avoir sur facture ${bill.billSource.reference}`
+      : bill?.title || 'Avoir'
+    : bill?.title;
+
+  return {
+    // Si ya sabemos el id en PennyLane lo usamos y nos ahorramos la búsqueda.
+    customerId: billing?.pennylaneCustomerId ? Number(billing.pennylaneCustomerId) : null,
+    customer: {
+      // En un particular la razón social no existe: se compone del nombre.
+      name: billingDisplayName(billing),
+      ...(billing.legalType ? { legalType: billing.legalType } : {}),
+      ...(billing.legalType === 'individual'
+        ? {
+            firstName: billing.firstName ?? '',
+            lastName: billing.lastName ?? '',
+          }
+        : {}),
+      billingAddress: {
+        address: billing.address.address,
+        postalCode: billing.address.postalCode,
+        city: billing.address.city,
+        countryAlpha2: (billing.address.countryAlpha2 || 'FR').toUpperCase(),
+      },
+      // Un particular no tiene ninguno de los dos. Si algo se coló en la
+      // ficha, no viaja: PennyLane rechazaría la creación del tercero.
+      ...(billing.legalType !== 'individual' && billing.registrationNumber
+        ? { regNo: billing.registrationNumber }
+        : {}),
+      ...(billing.legalType !== 'individual' && billing.vatNumber
+        ? { vatNumber: billing.vatNumber }
+        : {}),
+      ...(billing.emails?.length ? { emails: billing.emails } : {}),
+      ...(billing.phone ? { phone: billing.phone } : {}),
+      ...(billing.recipient ? { recipient: billing.recipient } : {}),
+      ...(billing.notes ? { notes: billing.notes } : {}),
+      paymentConditions:
+        billing.paymentConditions ??
+        PAYMENT_CONDITIONS[bill?.termsOfPayment ?? ''] ??
+        articho.BillingPaymentConditions.DAYS_30,
+      billingLanguage: billing.language ?? articho.BillingLanguage.FR,
+      ...(context.entityId ? { archiId: context.entityId } : {}),
+    },
+
+    date: toISODate(date),
+    deadline: toISODate(deadline),
+
+    lines: [...(bill?.elements ?? [])]
+      .sort((a, b) => (a?.order ?? 0) - (b?.order ?? 0))
+      .map((element) => {
+        const rawPrice = element.priceHT ?? 0;
+        const unitPrice = isCreditNote ? -Math.abs(rawPrice) : rawPrice;
+        return {
+          label: element.description,
+          quantity: element.quantity ?? 1,
+          unit: 'piece',
+          unitPrice,
+          vatRate: toVatRateCode(element.tva, bill?.tva !== false),
+          ...(toDiscount(element.discount, element.discountType)
+            ? { discount: toDiscount(element.discount, element.discountType) }
+            : {}),
+        };
+      }),
+
+    draft: context.draft ?? false,
+    currency: 'EUR',
+    language: billing.language ?? articho.BillingLanguage.FR,
+    label: displayLabel,
+    externalReference: bill?.id ? `articho:${bill.id}` : undefined,
+    pdfInvoiceSubject: displayLabel,
+    ...(bill?.comments ? { specialMention: bill.comments } : {}),
+    ...(toDiscount(bill?.discount, bill?.discountType)
+      ? { discount: toDiscount(bill?.discount, bill?.discountType) }
+      : {}),
+
+    sendToPa: context.sendToPa ?? false,
+    projectId: context.projectId ?? null,
+    billId: bill?.id ?? null,
+    ...(creditedInvoiceId ? { creditedInvoiceId } : {}),
+  };
+};
+
+/** Known PennyLane company IDs mapped by Articho enterprise ID. Used as fallback when not configured in Firestore. */
+export const ENTERPRISE_PENNYLANE_COMPANY_IDS: Record<string, string> = {
+  '45106373900119': '156553',
+};
+
+/**
+ * Generates a direct URL to view an invoice in the PennyLane web application.
+ * Returns null if the invoice ID or company ID is missing.
+ *
+ * Examples:
+ * - Customer (Ventes):
+ *   https://app.pennylane.com/companies/156553/clients/customer_invoices?invoice_id=28823318994944
+ * - Supplier (Achats):
+ *   https://app.pennylane.com/companies/156553/supplier_invoices?invoice_id=28645132099584
+ *
+ * @param {object} options
+ * @param {string | number} [options.invoiceId] PennyLane invoice ID (or prefixed ID like 'pl_123').
+ * @param {string | number} [options.companyId] PennyLane company ID (e.g. '156553', from Firestore config).
+ * @param {string} [options.enterpriseId] Articho enterprise ID.
+ * @param {'customer' | 'supplier'} [options.type] 'customer' for customer invoices (ventes), 'supplier' for supplier invoices (achats).
+ * @return {string | null} Full PennyLane app URL or null if cannot be formed.
+ */
+export const getPennylaneInvoiceUrl = (options?: {
+  invoiceId?: string | number | null;
+  companyId?: string | number | null;
+  enterpriseId?: string | null;
+  type?: 'customer' | 'supplier';
+}): string | null => {
+  if (!options?.invoiceId) {
+    return null;
+  }
+
+  const companyId =
+    options?.companyId ||
+    (options?.enterpriseId ? ENTERPRISE_PENNYLANE_COMPANY_IDS[options.enterpriseId] : undefined) ||
+    ENTERPRISE_PENNYLANE_COMPANY_IDS['45106373900119'];
+
+  if (!companyId) {
+    return null;
+  }
+
+  const base = 'https://app.pennylane.com';
+  const section =
+    options?.type === 'customer' ? 'clients/customer_invoices' : 'supplier_invoices';
+  const cleanId = String(options.invoiceId).replace(/^pl_/, '').trim();
+
+  return `${base}/companies/${companyId}/${section}?invoice_id=${cleanId}`;
+};
+
+/**
+ * Normalizes a string for loose comparison (lowercase, trimmed, collapsed whitespace, accent-free).
+ *
+ * @param {string | null | undefined} val Input string.
+ * @return {string} Normalized string.
+ */
+export const normalizeSupplierName = (val?: string | null): string => {
+  return (val ?? '')
+    .trim()
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/\s+/g, ' ');
+};
+
+/**
+ * Normalizes a SIREN / SIRET registration number (digits only).
+ *
+ * @param {string | null | undefined} val Registration number.
+ * @return {string} Normalized digits only.
+ */
+export const normalizeRegNo = (val?: string | null): string => {
+  return (val ?? '').replace(/\D/g, '');
+};
+
+/**
+ * Checks whether a counterparty matches any entry in the enterprise's ignored suppliers list.
+ *
+ * Match criteria:
+ * 1. Matching PennyLane supplier ID
+ * 2. Matching SIREN/SIRET registration number (at least 9 digits / SIREN match)
+ * 3. Matching normalized supplier name
+ *
+ * @param {object} [counterparty] Counterparty details from imported bill or invoice.
+ * @param {articho.PennylaneIgnoredSupplier[]} [ignoredSuppliers] Enterprise ignored suppliers list.
+ * @return {articho.PennylaneIgnoredSupplier | null} The matching rule if found, or null.
+ */
+export const findMatchingIgnoredSupplier = (
+  counterparty?: {
+    name?: string | null;
+    regNo?: string | null;
+    pennylaneId?: string | null;
+  } | null,
+  ignoredSuppliers?: articho.PennylaneIgnoredSupplier[]
+): articho.PennylaneIgnoredSupplier | null => {
+  if (!counterparty || !ignoredSuppliers || ignoredSuppliers.length === 0) return null;
+
+  const plId = counterparty.pennylaneId ? String(counterparty.pennylaneId).trim() : null;
+  const regNo = normalizeRegNo(counterparty.regNo);
+  const name = normalizeSupplierName(counterparty.name);
+
+  for (const rule of ignoredSuppliers) {
+    // 1. Match by PennyLane ID
+    if (plId && rule.pennylaneId && String(rule.pennylaneId).trim() === plId) {
+      return rule;
+    }
+
+    // 2. Match by SIREN / SIRET (at least 9 digits)
+    if (regNo.length >= 9 && rule.regNo) {
+      const ruleRegNo = normalizeRegNo(rule.regNo);
+      if (ruleRegNo.length >= 9 && regNo.substring(0, 9) === ruleRegNo.substring(0, 9)) {
+        return rule;
+      }
+    }
+
+    // 3. Match by normalized name (exact normalized string match)
+    if (name && rule.name) {
+      const ruleName = normalizeSupplierName(rule.name);
+      if (name === ruleName) {
+        return rule;
+      }
+    }
+  }
+
+  return null;
+};
+
+/**
+ * Returns true if the counterparty is ignored by the enterprise configuration.
+ *
+ * @param {object} [counterparty] Counterparty details.
+ * @param {articho.PennylaneIgnoredSupplier[]} [ignoredSuppliers] List of ignored suppliers.
+ * @return {boolean} True if ignored.
+ */
+export const isSupplierIgnored = (
+  counterparty?: {
+    name?: string | null;
+    regNo?: string | null;
+    pennylaneId?: string | null;
+  } | null,
+  ignoredSuppliers?: articho.PennylaneIgnoredSupplier[]
+): boolean => {
+  return Boolean(findMatchingIgnoredSupplier(counterparty, ignoredSuppliers));
+};

package/src/billing/permissions.ts

@@ -0,0 +1,25 @@
+import { ROLE } from '../auth';
+
+/**
+ * Roles que pueden enviar una factura a PennyLane.
+ *
+ * Deliberadamente corto: enviar una factura crea un asiento en la contabilidad
+ * real de la empresa y, cuando se transmite a la plataforma agréée, sale de
+ * Articho hacia un tercero. No es una acción reversible desde aquí.
+ *
+ * Un agent puede preparar la factura y rellenar los datos del tercero; el
+ * envío lo hace un administrador.
+ */
+export const PENNYLANE_SENDER_ROLES: ROLE[] = [ROLE.ADMIN, ROLE.OWNER, ROLE.SUPERADMIN];
+
+/**
+ * Única fuente de verdad sobre quién puede enviar a PennyLane. La usan tanto
+ * la interfaz (para no mostrar el botón) como las Cloud Functions (para
+ * rechazar la llamada). Si divergieran, el botón aparecería para gente a la
+ * que después le rebotaría el envío.
+ *
+ * @param {ROLE} role Rol del perfil que intenta enviar.
+ * @return {boolean} true si puede enviar.
+ */
+export const canSendToPennylane = (role?: ROLE | string | null): boolean =>
+  !!role && PENNYLANE_SENDER_ROLES.includes(role as ROLE);