@placeshakr/config 10.29.4 → 10.31.0-alpha.2

package/src/types.ts

@@ -527,6 +527,8 @@ export interface Enterprise extends Resource {
     whatsapp?: boolean;
     marketplace?: boolean;
     multiProfessionals?: boolean;
+    /** PennyLane integration: enables the Bills listing and the sync. */
+    pennylane?: boolean;
   };
 
   /**
@@ -690,6 +692,13 @@ export interface User extends Resource {
 type Permissions = Record<string, boolean>;
 
 export interface Profile extends Resource {
+  /**
+   * 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;
+
   /**
    *
    */
@@ -1105,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
    */
@@ -2493,9 +2508,33 @@ export type Bill = Resource & {
   // used to save information related with any possible external system
   metadata?: {
     sentToIpaidthat?: boolean;
+    /** @deprecated use metadata.pennylane. Kept until email delivery is retired. */
     sentToPennyLane?: boolean;
+    /** @deprecated usar metadata.pennylane.lastSyncAt */
     sentToPennyLaneDate?: number;
+    /**
+     * 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;
   };
+
+  /**
+   * 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;
+
+  /**
+   * 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;
 };
 
 export type BillReceived = Bill & {
@@ -2656,6 +2695,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
    */
@@ -4563,3 +4608,482 @@ export enum EmailEventsEnum {
   RESET_USER_PASSWORD = 'RESET_USER_PASSWORD',
   DOCUMENTS_ISSUES = 'DOCUMENTS_ISSUES',
 }
+
+/* -------------------------------------------------------------------------- */
+/*                                 PennyLane                                  */
+/* -------------------------------------------------------------------------- */
+
+/** Sync state of one specific bill against PennyLane. */
+export type PennylaneBillSync = {
+  status: 'PENDING' | 'SYNCED' | 'FAILED' | 'SKIPPED';
+  /** Invoice id in PennyLane. */
+  invoiceId?: string;
+  /** Id of the credited invoice in PennyLane (for credit notes). */
+  creditedInvoiceId?: string;
+  /** Id of the PennyLane credit note that cancels this invoice. */
+  creditNoteId?: string;
+  creditNoteNumber?: string;
+  creditNoteStatus?: 'PENDING' | 'SYNCED' | 'FAILED' | 'SKIPPED';
+  creditNoteError?: string;
+  /** Mirror document under enterprises/{id}/importedBills. */
+  importedBillId?: string;
+  fileAttachmentId?: string;
+  /**
+   * 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;
+  lastAttemptAt?: number;
+  lastSyncAt?: number;
+  syncedAt?: number;
+  error?: { code: string; message: string; status?: number };
+};
+
+/** Which field of the PennyLane invoice each reference is read from. */
+export type PennylaneReferenceConfig = {
+  /** Field where the supplier writes the chantier reference. */
+  projectField: 'label' | 'invoice_number' | 'lines';
+  /** Field where the supplier writes the devis reference. */
+  devisField: 'label' | 'invoice_number' | 'lines';
+  /** Regular expression with a single capture group. */
+  projectPattern?: string;
+  devisPattern?: string;
+};
+
+export type PennylaneIgnoredSupplier = {
+  name: string;
+  regNo?: string | null;
+  pennylaneId?: string | null;
+  ignoredAt: number;
+  ignoredBy?: string | null;
+};
+
+/** Per-enterprise PennyLane configuration: enterprises/{id}/configurations/pennylane */
+export type PennylaneConfiguration = {
+  enabled: boolean;
+  /** Numeric id of the company in PennyLane (e.g. '156553'). */
+  companyId?: string;
+  push: { issued: boolean; received: boolean };
+  pull: { supplierInvoices: boolean };
+  /** false = send aggregate amounts + PDF only. */
+  sendLineItems: boolean;
+  /** true while the accounting mapping is not settled with the accountant. */
+  importAsIncomplete: boolean;
+  references: PennylaneReferenceConfig;
+  /** PennyLane states that are not pulled (drafts and initial noise). */
+  excludedStates?: string[];
+  /** Days to look back on the initial load or a full resync. */
+  lookbackDays?: number;
+  defaultLedgerAccountId?: string;
+  ledgerAccountByCategory?: Record<string, string>;
+  /** Analytical breakdown per chantier. See [[PennylaneCategoryConfig]]. */
+  categories?: PennylaneCategoryConfig;
+  /** Suppliers whose invoices are ignored automatically on sync. */
+  ignoredSuppliers?: PennylaneIgnoredSupplier[];
+  /** Sync state. Written by the Cloud Functions only. */
+  sync?: {
+    supplierInvoices?: PennylaneSyncState;
+    customerInvoices?: PennylaneSyncState;
+  };
+};
+
+/**
+ * Analytical breakdown per chantier: one PennyLane category per Articho
+ * project, the same one for that project's issued and received invoices.
+ *
+ * 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 = {
+  /** Master switch. Without it the sync never touches categories. */
+  enabled: boolean;
+  /**
+   * Id of the group created by hand in PennyLane (e.g. "Chantiers Articho").
+   * It differs per enterprise: they are separate PennyLane workspaces.
+   */
+  groupId: number;
+  /** Also categorise the invoices Articho issues. */
+  includeCustomerInvoices?: boolean;
+};
+
+export type PennylaneSyncState = {
+  /**
+   * 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 {
+  /** Arrived from PennyLane; project or devis could not be resolved. */
+  PENDING_ASSIGNMENT = 'PENDING_ASSIGNMENT',
+  /** Project and devis resolved: waiting for an administrator to confirm. */
+  READY_TO_ASSIGN = 'READY_TO_ASSIGN',
+  /** Already has a bill created inside a project. */
+  ASSIGNED = 'ASSIGNED',
+  /** Discarded by hand. */
+  IGNORED = 'IGNORED',
+  /** Duplicate of another imported invoice. */
+  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',
+}
+
+/**
+ * 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;
+  date: number;
+  type: PennylaneSyncEventType;
+  message: string;
+  before?: Record<string, unknown>;
+  after?: Record<string, unknown>;
+  payload?: Record<string, unknown>;
+};
+
+/**
+ * Mirror of a PennyLane invoice inside Articho.
+ *
+ * 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 in PennyLane. The deduplication key. */
+  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;
+    /** How it got into PennyLane: Email, API, PA/PDP… */
+    externalSource?: string | null;
+    fileUrl?: string | null;
+  };
+
+  counterparty: {
+    name: string;
+    regNo?: string | null;
+    pennylaneId?: string | null;
+  };
+
+  /** 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 };
+  };
+
+  /** Automatic resolution. It never creates the bill on its own. */
+  suggestion?: {
+    projectId?: string | null;
+    devisId?: string | null;
+    reasons: string[];
+  };
+
+  /** Association confirmed by an administrator. */
+  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;
+};
+
+/* -------------------------------------------------------------------------- */
+/*                              Billing identity                              */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Postal address, broken down.
+ *
+ * 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;
+  /** Two-letter ISO code: 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',
+}
+
+/**
+ * Everything needed to issue an invoice to this entity.
+ *
+ * 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.
+ *
+ * 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.
+ */
+/**
+ * Legal person or natural person.
+ *
+ * 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.
+ *
+ * `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 = {
+  /** Company or private individual. See [[BillingLegalType]]. */
+  legalType?: BillingLegalType;
+
+  /**
+   * Legal name. Mandatory for companies.
+   *
+   * 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;
+
+  /** First name. Mandatory for individuals; PennyLane wants it separate. */
+  firstName?: string;
+  /** Last name. Mandatory for individuals. */
+  lastName?: string;
+  /** Billing address. Mandatory. */
+  address: PostalAddress;
+  /** Delivery address, when it differs from the billing one. */
+  deliveryAddress?: PostalAddress;
+  /** SIREN (9 digits) or SIRET (14). */
+  registrationNumber?: string;
+  /** Intra-community VAT number. Not to be confused with the VAT rate. */
+  vatNumber?: string;
+  /** Addresses the invoice is sent to. */
+  emails?: string[];
+  phone?: string;
+  /** Recipient person or department inside the company. */
+  recipient?: string;
+  paymentConditions?: BillingPaymentConditions;
+  language?: BillingLanguage;
+  /** Notes attached to the third party's record. */
+  notes?: string;
+  /**
+   * 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;
+
+  /**
+   * 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;
+
+  /**
+   * 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;
+
+  updatedAt?: number;
+  updatedBy?: string;
+};
+
+/**
+ * What the public register says about a third party's company.
+ *
+ * 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 digits. */
+  siren?: string;
+  /** SIRET of the establishment queried, 14 digits. */
+  siret?: string;
+  /** Whether the establishment queried is the registered office. */
+  siege?: boolean;
+  /** Legal form (`categorieJuridiqueUniteLegale`). */
+  legalForm?: string | null;
+  /** APE/NAF code (`activitePrincipaleUniteLegale`). */
+  nafCode?: string | null;
+  /** Legal unit state: `A` active, `C` ceased. */
+  state?: string | null;
+  /** Establishment state: `A` open, `F` closed. */
+  establishmentState?: string | null;
+  /** Trade name, when it differs from the legal name. */
+  tradeName?: string | null;
+  /** How it was resolved: `siret`, `siege` or `siege-fallback`. */
+  matchedBy?: string;
+  /**
+   * 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;
+  /** Result of checking the VAT number against VIES. */
+  vatCheck?: BillingVatCheck;
+  /** When the register was last queried. */
+  checkedAt?: number;
+}
+
+/**
+ * Validation of the intra-community VAT number against the VIES register.
+ *
+ * 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 {
+  /** The number that was checked. */
+  number: string;
+  status: 'VALID' | 'INVALID' | 'UNAVAILABLE';
+  /** `null` when VIES did not answer: unknown, which is not the same as no. */
+  valid: boolean | null;
+  reason?: string | null;
+  source: string;
+  checkedAt: number;
+}
+
+/**
+ * Severity of an enrichment issue.
+ *
+ * - `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';
+
+/**
+ * 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 {
+  /** The record carries neither SIREN nor SIRET. */
+  NO_IDENTIFIER = 'NO_IDENTIFIER',
+  /** Several companies share that legal name: a human must choose. */
+  SIREN_AMBIGUOUS = 'SIREN_AMBIGUOUS',
+  /** The identifier does not appear in the register. */
+  NOT_FOUND = 'NOT_FOUND',
+  /** The legal unit is recorded as ceased. */
+  COMPANY_CLOSED = 'COMPANY_CLOSED',
+  /** The establishment is closed; the company may still be alive. */
+  ESTABLISHMENT_CLOSED = 'ESTABLISHMENT_CLOSED',
+  /** The VAT number is unknown to VIES. Likely franchise en base. */
+  VAT_NOT_REGISTERED = 'VAT_NOT_REGISTERED',
+  /** VIES did not answer: the number was stored unverified. */
+  VAT_UNVERIFIED = 'VAT_UNVERIFIED',
+  /** VIES returns a legal name different from INSEE's. */
+  VAT_NAME_MISMATCH = 'VAT_NAME_MISMATCH',
+  /** 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',
+  /** The register lookup failed (network, quota, credentials). */
+  LOOKUP_ERROR = 'LOOKUP_ERROR',
+}
+
+/**
+ * What happened the last time this record's billing data was completed from
+ * the public registers.
+ *
+ * `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.
+ *
+ * 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 {
+  /** One message per line, separated by `\n`. Empty when `level` is `ok`. */
+  text: string;
+  /** The same messages, unjoined. */
+  messages: string[];
+  codes: BillingEnrichmentCode[];
+  level: BillingEnrichmentLevel;
+  /** Who wrote it, e.g. `insee-script`. */
+  source: string;
+  checkedAt: number;
+}