@accounter/server
Version:
Accounter GraphQL server
89 lines (88 loc) • 4.68 kB
TypeScript
/**
* Server-side issuer-selection policy, ported from the legacy gmail-listener
* `getIssuerEmail`.
*
* In the v2 split (see docs/multi-tenant-gmail-listener/business-recognition-plan.md,
* Workstream A) the gateway parses the MIME message and forwards candidate sender
* addresses — header-derived (`from`, `replyTo`, …) plus any `From: <mailto:…>`
* links found in the body — as sender evidence. The selection policy that decides
* *which* address identifies the issuing business stays here, next to the
* `suggestion_data.emails` lookup it feeds, as the single DB-adjacent source of
* truth.
*/
export interface SenderEvidence {
/** From header address. */
from?: string | null;
/** Reply-To header address. */
replyTo?: string | null;
/** X-Original-From / X-Original-Sender address. */
originalFrom?: string | null;
/** X-Forwarded-To / Envelope-To address. */
forwardedTo?: string | null;
/** Addresses parsed from `From: <mailto:…>` lines in the body, in document order. */
issuerCandidates?: ReadonlyArray<string | null> | null;
}
/**
* Pick the issuer email used for business recognition, or `null` if none can be
* determined. Mirrors the legacy precedence:
*
* 1. the first body `mailto:` candidate that is either not a known provider,
* or — when there is no Reply-To — the first candidate regardless;
* 2. else the first of `originalFrom` / `from` that is not a known provider;
* 3. else `replyTo`;
* 4. else `from`.
*
* `extraProviders` (lower-cased) lets a caller treat additional addresses as
* non-issuer forwarders for this call only — e.g. the tenant's own inbound
* alias, which a mailing-list forward rewrites into `From`. It augments, never
* replaces, {@link INVOICE_ISSUING_PROVIDER_EMAILS}, and defaults to empty so
* existing callers are unaffected.
*/
export declare function selectIssuerEmail(evidence: SenderEvidence | null | undefined, extraProviders?: ReadonlySet<string>): string | null;
/**
* Detect a **self-issued** document: an email whose only determinable issuer is
* one of the tenant's own invoice-issuing platforms (Morning/Sumit) or its own
* forwarding address — i.e. no external counterparty can be identified.
*
* These are the confirmation emails a tenant receives for invoices *it* issued
* through such a platform (e.g. Morning/greeninvoice). The underlying document
* was already inserted on the server at creation time, so ingesting the email
* would duplicate it. This mirrors the legacy gmail-listener skip, where
* `getEmailData` dropped mail whose `From` carried the tenant's own name.
*
* The check reuses {@link selectIssuerEmail}: it commits to a provider address
* only after every non-provider candidate has been ruled out, so a provider
* result means the email has no external issuer. Forwarded supplier invoices —
* which carry the real issuer as a quoted-header `mailto:` in the body — resolve
* to that (non-provider) address and are therefore *not* treated as self-issued.
*
* `ownInboundAddresses` are the tenant's own inbound addresses (its recipient
* alias/es). A mailing-list forward (e.g. a Google Group) rewrites the live
* `From` into that alias, which would otherwise look like an external issuer and
* defeat detection. Passing them makes the check tenant-agnostic instead of
* relying on the hard-coded {@link INVOICE_ISSUING_PROVIDER_EMAILS} carrying
* each tenant's forwarding address.
*/
export declare function isSelfIssuedSenderEvidence(evidence: SenderEvidence | null | undefined, ownInboundAddresses?: Iterable<string>): boolean;
/**
* Build the ordered, de-duplicated list of issuer emails to try against the
* `suggestion_data.emails` lookup, most-likely-real issuer first. Unlike
* {@link selectIssuerEmail} (which commits to a single address), this lets the
* caller try each candidate until one matches a business — important for
* **manually forwarded** mail, where the real issuer survives only as a
* quoted-header address in the body and the live `From`/`Reply-To` belong to the
* forwarder.
*
* Order:
* 1. body candidates that are not known forwarding providers (the real issuer);
* 2. `originalFrom` / `from` when not a known provider;
* 3. `replyTo`;
* 4. `from` (any, including a provider);
* 5. body candidates that ARE known providers (a business may be keyed on a
* forwarder address);
* 6. `originalFrom` (any).
*
* All addresses are bare-extracted and lower-cased so the lookup can match
* case-insensitively.
*/
export declare function selectIssuerCandidates(evidence: SenderEvidence | null | undefined): string[];