@placeshakr/config 10.29.4 → 10.31.0-alpha.2

package/dist/types/types.d.ts

@@ -396,6 +396,8 @@ export interface Enterprise extends Resource {
         whatsapp?: boolean;
         marketplace?: boolean;
         multiProfessionals?: boolean;
+        /** PennyLane integration: enables the Bills listing and the sync. */
+        pennylane?: boolean;
     };
     /**
      * Used to save the last reference created for the two types of bills
@@ -532,6 +534,12 @@ 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;
     /**
      *
      */
@@ -872,6 +880,11 @@ 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
      */
@@ -2041,9 +2054,31 @@ export type Bill = Resource & {
     files?: File[];
     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 & {
     status: BillReceivedStatus;
@@ -2181,6 +2216,11 @@ 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
      */
@@ -3801,5 +3841,456 @@ export declare enum EmailEventsEnum {
     RESET_USER_PASSWORD = "RESET_USER_PASSWORD",
     DOCUMENTS_ISSUES = "DOCUMENTS_ISSUES"
 }
+/** 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 declare 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 declare 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;
+};
+/**
+ * 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 declare 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 declare 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 declare 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;
+}
 export {};
 //# sourceMappingURL=types.d.ts.map