@aglyn/aglyn 1.0.0-beta.217 → 1.0.0-beta.219

package/src/lib/app-utils/crm-csv.d.ts

@@ -1,239 +0,0 @@
-/**
- * @license
- * Copyright 2026 Aglyn LLC
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *   http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-/**
- * EVERY CRM CSV, WRITTEN ONCE (AGL-2662).
- *
- * ## Why these moved out of the plugin
- *
- * Each CRM section already wrote a file from the rows it had LOADED, and
- * the whole-collection export writes the same file from the server over
- * every row there is. The console app may not import a feature plugin —
- * plugins reach an app only through the generated loader manifests — so a
- * server route could not have called the plugin's writers, and writing a
- * second set would have given one feature two file formats, discovered by
- * whichever merchant opened both in a spreadsheet.
- *
- * So the columns and the cells live here, in the library both sides may
- * import. The plugin's `contacts-csv.ts`, `companies-csv.ts`,
- * `deals-csv.ts`, `tasks-csv.ts` and `leads-csv.ts` keep their names and
- * delegate: the sections import what they always did, and there is one
- * implementation under all of it. Their specs are unchanged and are the
- * proof that the move changed no byte of any file.
- *
- * ## What a resolver is for, and what an absent one means
- *
- * A stored document holds ids — an owner uid, a pipeline id, a linked
- * record id — and a spreadsheet cannot read an id. Each writer therefore
- * takes optional resolvers, and every one of them degrades the same way:
- * ABSENT resolver writes the id itself rather than an empty cell, because
- * a row whose owner is a uid is still a row whose owner can be found, and
- * a blank is a claim that nobody owns it.
- *
- * The owner columns carry an ADDRESS where they can, which is also what
- * the contacts and companies imports resolve an owner by — so an exported
- * file re-imports without a hand mapping.
- */
-import type { AglynPostalAddress } from '../foundation';
-import { type ContactCustomValue, type ContactFieldDefinition, type ContactLifecycleStage, type CrmCompany, type CrmLeadFields, type CrmTask } from './crm';
-/** Cents as a major-unit decimal — `125000` → `1250.00`; `''` for none. */
-export declare function csvAmount(cents: number | null | undefined): string;
-/** An epoch as an ISO timestamp, or `''` for none. */
-export declare function csvInstant(ms: number | null | undefined): string;
-/**
- * An epoch as a local calendar DATE — `YYYY-MM-DD`.
- *
- * For the fields that are a day rather than a moment: an expected close is
- * stored at local noon precisely so the day survives a timezone round trip,
- * and writing it as an instant would hand a spreadsheet a time nobody
- * chose. The same arithmetic the deal drawer's date field uses, so the
- * file and the field read one day.
- */
-export declare function csvLocalDate(ms: number | null | undefined): string;
-/** Epoch millis or a Firestore timestamp as an ISO instant, or `''`. */
-export declare function csvStoredInstant(value: unknown): string;
-/** As much of a projected contact row as the file reads. */
-export interface ContactCsvRow {
-    email?: string;
-    name?: string;
-    phone?: string;
-    jobTitle?: string;
-    companyName?: string;
-    ownerUid?: string;
-    lifecycleStage?: ContactLifecycleStage | '';
-    address?: AglynPostalAddress | null;
-    tags?: string[];
-    sources?: Record<string, unknown>;
-    interactions?: Array<{
-        atMs: number;
-    }>;
-    /** The last open or click on one of the site's campaigns (AGL-2616). */
-    lastEmailEngagementAtMs?: number;
-    notes?: string;
-    /** This holder's custom values, keyed by definition key. */
-    custom?: Record<string, ContactCustomValue>;
-}
-export interface ContactCsvOptions {
-    /**
-     * The owner's address for a stored uid — what the import resolves an
-     * owner by. Absent, the uid is written as it is.
-     */
-    ownerEmail?: (uid: string) => string;
-    /** The org's custom fields, one column each, headed by the field's label. */
-    customFields?: readonly Pick<ContactFieldDefinition, 'key' | 'label'>[];
-}
-/**
- * The standard columns, in order, headed as the import reads them. A
- * custom field's column follows these, headed by its label.
- */
-export declare const CONTACT_CSV_COLUMNS: readonly ["Email", "Name", "Phone", "Job title", "Company", "Owner", "Lifecycle stage", "Address line 1", "Address line 2", "City", "State", "Postal code", "Country", "Tags", "Sources", "Last interaction", "Last engaged", "Notes"];
-/** The header row, with one column per custom field after the standard ones. */
-export declare function contactCsvHeader(customFields?: ContactCsvOptions['customFields']): string[];
-/** One contact's cells, in the header's order. */
-export declare function contactCsvCells(contact: ContactCsvRow, options?: ContactCsvOptions): unknown[];
-/** The whole file, header first. */
-export declare function contactsCsv(rows: readonly ContactCsvRow[], options?: ContactCsvOptions): string;
-/** As much of a company row as the file reads. */
-export type CompanyCsvRow = Partial<Pick<CrmCompany, 'name' | 'domain' | 'website' | 'phone' | 'industry' | 'ownerUid' | 'tags' | 'notes' | 'contactsCount'>> & {
-    address?: AglynPostalAddress | null;
-};
-export interface CompanyCsvOptions {
-    /** The owner's address for a stored uid; absent, the uid is written. */
-    ownerEmail?: (uid: string) => string;
-}
-/** The columns, in order, headed as the import reads them. */
-export declare const COMPANY_CSV_COLUMNS: readonly ["Company", "Domain", "Website", "Phone", "Industry", "Owner", "Address line 1", "Address line 2", "City", "State", "Postal code", "Country", "Tags", "Notes", "Contacts"];
-/** One company's cells, in the header's order. */
-export declare function companyCsvCells(company: CompanyCsvRow, options?: CompanyCsvOptions): unknown[];
-/** The whole file, header first. */
-export declare function companiesCsv(rows: readonly CompanyCsvRow[], options?: CompanyCsvOptions): string;
-/** The currency a deal with no code of its own is read in. */
-export declare const CSV_DEFAULT_DEAL_CURRENCY = "usd";
-/** How a deal's `status` reads in a file. */
-export declare const CSV_DEAL_STATUS_LABELS: Record<string, string>;
-/** As much of a deal row as the file reads. */
-export interface DealCsvRow {
-    title?: string;
-    pipelineId?: string;
-    stageId?: string;
-    status?: string;
-    amountCents?: number;
-    currency?: string;
-    ownerUid?: string;
-    expectedCloseAtMs?: number | null;
-    closedAtMs?: number | null;
-    contactName?: string;
-    companyName?: string;
-    lostReason?: string;
-    notes?: string;
-}
-export interface DealCsvOptions {
-    /** The pipeline's name for a stored id; absent, the id is written. */
-    pipelineName?: (pipelineId: string) => string | undefined;
-    /** The stage's name within its pipeline; absent, the stage id is written. */
-    stageName?: (pipelineId: string, stageId: string) => string | undefined;
-    /** The owner's address for a stored uid; absent, the uid is written. */
-    ownerEmail?: (uid: string) => string;
-}
-export declare const DEAL_CSV_COLUMNS: readonly ["Title", "Pipeline", "Stage", "Amount", "Currency", "Owner", "Expected close", "Status", "Contact", "Company", "Closed", "Lost reason", "Notes"];
-/** One deal's cells, in the header's order. */
-export declare function dealCsvCells(deal: DealCsvRow, options?: DealCsvOptions): unknown[];
-/** The whole file, header first. */
-export declare function dealsCsv(rows: readonly DealCsvRow[], options?: DealCsvOptions): string;
-/** As much of a task row as the file reads. */
-export type TaskCsvRow = Partial<Pick<CrmTask, 'title' | 'kind' | 'priority' | 'status' | 'dueAtMs' | 'completedAtMs' | 'assigneeUid' | 'contactId' | 'companyId' | 'dealId' | 'notes'>>;
-export interface TaskCsvOptions {
-    /** The assignee's address for a stored uid; absent, the uid is written. */
-    assigneeEmail?: (uid: string) => string;
-    /** What a linked record is called; absent, the id is written. */
-    recordName?: (kind: 'contact' | 'company' | 'deal', id: string) => string | undefined;
-}
-export declare const TASK_CSV_COLUMNS: readonly ["Title", "Kind", "Priority", "Status", "Due", "Assignee", "Contact", "Company", "Deal", "Completed", "Notes"];
-/** One task's cells, in the header's order. */
-export declare function taskCsvCells(task: TaskCsvRow, options?: TaskCsvOptions): unknown[];
-/** The whole file, header first. */
-export declare function tasksCsv(rows: readonly TaskCsvRow[], options?: TaskCsvOptions): string;
-/** How one capture surface reads in a file. */
-export declare function csvLeadSourceLabel(source: string): string;
-/** Every surface that produced a capture — the array, or the older single field. */
-export declare function csvLeadSources(lead: Record<string, unknown>): string[];
-/** As much of a lead row as the file reads. */
-export type LeadCsvRow = Record<string, unknown> & Pick<CrmLeadFields, 'status' | 'ownerUid' | 'notes' | 'unqualifiedReason' | 'convertedAtMs' | 'company' | 'jobTitle' | 'phone' | 'website' | 'address' | 'tags' | 'leadSource'> & {
-    /** The site the lead lives under — what the `Site` column names. */
-    hostId?: string;
-};
-export interface LeadCsvOptions {
-    /** The owner's address for a stored uid; absent, the uid is written. */
-    ownerEmail?: (uid: string) => string;
-    /**
-     * The site's name for a row's `hostId`. Given, the file carries a `Site`
-     * column — the organization-level file; absent, it does not.
-     */
-    siteName?: (hostId: string) => string | undefined;
-}
-/**
- * The columns every leads file carries, in the list's order.
- *
- * The lead's own profile (AGL-3231) — company, title, phone, website, the
- * address parts, tags and the lead source — sits where the contacts file
- * keeps the same facts, under the same headers, so one spreadsheet of
- * people reads into either import with the same mapping.
- */
-export declare const LEAD_CSV_COLUMNS: readonly ["Email", "Name", "Company", "Job title", "Phone", "Website", "Status", "Owner", "Lead source", "Sources", "First seen", "Last seen", "Captures", "Address line 1", "Address line 2", "City", "State", "Postal code", "Country", "Tags", "Unqualified reason", "Converted", "Notes"];
-/** The header row: the standard columns, with `Site` after `Owner` at the org level. */
-export declare function leadCsvHeader(options?: LeadCsvOptions): string[];
-/** One lead's cells, in the header's order. */
-export declare function leadCsvCells(lead: LeadCsvRow, options?: LeadCsvOptions): unknown[];
-/** The whole file, header first. */
-export declare function leadsCsv(rows: readonly LeadCsvRow[], options?: LeadCsvOptions): string;
-/** The five tables a whole-collection export can be asked for. */
-export declare const CRM_EXPORT_RESOURCES: readonly ["contacts", "companies", "deals", "tasks", "leads"];
-export type CrmExportResource = (typeof CRM_EXPORT_RESOURCES)[number];
-export declare function isCrmExportResource(value: unknown): value is CrmExportResource;
-/** Every resolver any of the five writers takes, in one bag. */
-export type CrmExportOptions = ContactCsvOptions & DealCsvOptions & TaskCsvOptions & LeadCsvOptions & {
-    assigneeEmail?: (uid: string) => string;
-};
-/** The header row one resource's file carries. */
-export declare function crmExportHeader(resource: CrmExportResource, options?: CrmExportOptions): string[];
-/**
- * One stored document's cells for one resource's file.
- *
- * The bridge the server route stands on: it holds a raw document rather
- * than the projected row a list built, and this is the one place that
- * turns the first into the second — so the streamed file and the file the
- * Export button writes are the same columns filled the same way.
- */
-export declare function crmExportCells(resource: CrmExportResource, document: Record<string, unknown>, options?: CrmExportOptions): unknown[];
-/** What the contacts file needs to know about the holder it is written for. */
-export interface CrmExportContactHolder {
-    /** The consent group whose facet the file reads — a facet is per holder. */
-    groupId: string;
-    /** The sites in that group, which bound the timeline the file reads. */
-    hostIds: readonly string[];
-}
-/**
- * A stored contact document as the contacts file reads it.
- *
- * The projection the Contacts list makes before it writes its own file,
- * spelled here so the server can make the same one: a contact document
- * holds one facet per HOLDER, and every field the file writes but the
- * address itself — the phone, the company, the tags, the notes, the
- * lifecycle stage, the custom values — lives in the viewing holder's facet.
- * Reading them off the top of the document is how one business's file ends
- * up carrying another's notes.
- */
-export declare function contactCsvRowFromDoc(document: Record<string, unknown>, holder: CrmExportContactHolder): ContactCsvRow;