@aglyn/plugins-crm 1.0.0-beta.218 → 1.0.0-beta.219

package/src/lib/server/api-v1/crm-shared.d.ts

@@ -0,0 +1,271 @@
+/**
+ * @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.
+ */
+/**
+ * What the CRM resources of `/v1` have in common (AGL-2606).
+ *
+ * Companies, pipelines, deals, tasks and activities are five collections
+ * with one shape (`CrmScoped`), one scope model (`crmScopeTokens`) and one
+ * set of questions every write has to answer — which site is this for, is
+ * that uid a member here, does the contact it names exist. Each handler
+ * module answers those through this file, so the answer cannot differ by
+ * resource.
+ *
+ * ## Reads are org-wide, writes name a site
+ *
+ * An API key is an ORGANIZATION credential (`api-keys.ts`), so a list here
+ * reads the whole collection: every company the org's sites know, whichever
+ * site created it. That is the same answer `GET /v1/contacts` gives, and it
+ * is right for the caller the key represents — an integration acting for the
+ * account, not a member sitting on one site.
+ *
+ * A write is different, because a CRM record carries `visibleTo` and the
+ * console enforces it: a record stamped for the wrong scope is a record a
+ * site's own team cannot open. So every create names the site it belongs to
+ * — `consentSiteId`, the parameter the contacts write already uses for the
+ * same question — and the record is stamped exactly as that site's console
+ * would stamp it ({@link crmCreateStamp}). There is no default site for the
+ * reason the contacts write gives: picking the org's only site works until
+ * the org has two.
+ */
+import { type ContactFieldDefinition, type CrmCollection, type CrmCustomValue, type CrmFieldObject, type CrmPicklist } from '@aglyn/aglyn/server';
+import { Timestamp } from 'firebase-admin/firestore';
+import { type ApiV1Context } from '@aglyn/tenant-data-admin/server/api-v1-kit';
+/** A title, a name — one line. */
+export declare const CRM_TITLE_MAX = 200;
+/** Free text — notes, a body, a lost reason. */
+export declare const CRM_TEXT_MAX = 5000;
+/** A short label — an industry, an outcome, a job title. */
+export declare const CRM_LABEL_MAX = 120;
+/** A stored id — Firestore's own ceiling is 1,500 bytes; nothing here is close. */
+export declare const CRM_ID_MAX = 200;
+/**
+ * `orgs/{orgId}/{name}` — every CRM collection sits directly under the org.
+ *
+ * Nothing in this module dereferences `CRM_COLLECTIONS` at load time, on
+ * purpose: the `/v1` suites mock `@aglyn/aglyn/server` as a closed world,
+ * and a module-level `CRM_COLLECTIONS.x` would throw at import in every
+ * suite that never asked for the CRM, reading as a failure of theirs.
+ */
+export declare function crmCollection(ctx: ApiV1Context, name: CrmCollection): FirebaseFirestore.CollectionReference;
+/**
+ * The records band, asked before a company or a deal is created (AGL-2611).
+ *
+ * `null` when there is room; the refusal otherwise, in the shape
+ * `POST /v1/contacts` has always answered at the same band — `plan_required`
+ * with a code, because on the one plan that refuses (Free) an upgrade is the
+ * whole remedy, and every paid plan meters the excess instead. The measure
+ * is the same three aggregates the monthly rollup bills from, so the API
+ * and the invoice cannot disagree about whether the band was full.
+ */
+export declare function crmRecordsBandRefusal(ctx: ApiV1Context): Promise<Response | null>;
+/**
+ * The `consentSiteId` a create carries, validated.
+ *
+ * Required, and required to be one of the organization's own sites, for the
+ * reason the module header gives. The message names the field so an
+ * integrator sees the same key they would on a contact write.
+ */
+export declare function readCrmSite(ctx: ApiV1Context, noun: string, body: Record<string, unknown>): {
+    siteId: string;
+} | {
+    response: Response;
+};
+/**
+ * The fields every CRM create stamps, for a record created from `siteId`.
+ *
+ * `visibleTo` is `crmScopeTokens` — the contact create path's own expression,
+ * which is what puts an API-created deal in exactly the scope a deal created
+ * from that site's console would land in. `hostId` is provenance and is never
+ * rewritten. `createdByUid` is the literal `'api'` because a key has no uid;
+ * it is the attribution the contact create makes through `sources.api`, in
+ * the field the CRM types already carry.
+ *
+ * Both timestamps are set here, once, so a fresh record's `updated` equals
+ * its `created` and an `updatedAfter` sweep that started before the create
+ * picks it up.
+ */
+export declare function crmCreateStamp(ctx: ApiV1Context, siteId: string): {
+    visibleTo: import("@aglyn/aglyn/src").ScopeToken[];
+    hostId: string;
+    createdByUid: string;
+    createdAt: Timestamp;
+    updatedAt: Timestamp;
+};
+/**
+ * Whether `uid` is a member of the authenticated organization.
+ *
+ * One document read at `orgs/{orgId}/members/{uid}` — the roster
+ * `listOrgMembers` reads whole answers the same question for the price of
+ * the whole roster, and a create should not pay for members it never asked
+ * about.
+ */
+export declare function isOrgMember(ctx: ApiV1Context, uid: string): Promise<boolean>;
+/** A clearable scalar: a value to write, `null` to delete, absent to leave. */
+export type Clearable<T> = T | null | undefined;
+/**
+ * The membership check for an owner or assignee, run after the synchronous
+ * grammar so a body that is already refused never spends the read.
+ */
+export declare function memberError(ctx: ApiV1Context, field: string, uid: Clearable<string>): Promise<Record<string, string>>;
+/**
+ * `values` as an `update()` payload: `null` becomes a field delete, an
+ * `undefined` is left out, so an omitted key leaves the field alone and an
+ * explicit `null` clears it — the PATCH contract every resource here shares.
+ */
+export declare function updatePayload(values: Record<string, unknown>): Record<string, unknown>;
+/**
+ * `values` as a `create()` payload: `null` and `undefined` are both left out,
+ * because a fresh document has nothing to clear.
+ */
+export declare function createPayload(values: Record<string, unknown>): Record<string, unknown>;
+/** The three records a CRM row can point at, by the field that points. */
+export interface CrmRefs {
+    contactId?: string;
+    companyId?: string;
+    dealId?: string;
+}
+/**
+ * Each reference in `refs` that points at nothing, as `field → reason`.
+ *
+ * A dangling id is refused rather than stored because the console renders a
+ * task by the contact it names, and a task pointing at a contact that does
+ * not exist is a task nobody can find from anywhere. One read per reference
+ * given, none for a reference omitted.
+ */
+export declare function crmRefErrors(ctx: ApiV1Context, refs: CrmRefs): Promise<Record<string, string>>;
+/**
+ * An ISO 8601 instant as milliseconds, or `null` when the value is not one.
+ *
+ * `Date.parse` is permissive — it takes `"2026"` and `"March 3"` — and a
+ * client sending a bare date almost always means midnight in THEIR zone,
+ * which we cannot know. So only the full form is accepted: a date, a `T`, a
+ * time and an offset (`Z` or `±hh:mm`). Anything less answers `null` and the
+ * caller names the field.
+ */
+export declare function parseIsoInstant(value: unknown): number | null;
+/** Milliseconds as ISO 8601, or `null` for anything that is not a finite number. */
+export declare function isoFromMs(value: unknown): string | null;
+/** The `created`/`updated` pair every CRM view publishes. */
+export declare function crmTimes(data: FirebaseFirestore.DocumentData): {
+    created: string;
+    updated: string;
+};
+/**
+ * A trimmed, bounded string from a body field, or `null` for an explicit
+ * `null`, or `undefined` when the field was not sent.
+ *
+ * `null` is how a PATCH clears an optional field — the caller turns it into
+ * a delete — so it has to survive as a value distinct from "absent". A
+ * number or a boolean is not silently stringified: the field is named.
+ */
+export declare function readOptionalText(body: Record<string, unknown>, key: string, max: number, errors: Record<string, string>): string | null | undefined;
+/** One of a fixed list, or the field is named with the list. */
+export declare function readChoice<T extends string>(body: Record<string, unknown>, key: string, choices: readonly T[], errors: Record<string, string>): T | undefined;
+/**
+ * A reference id from a body field — trimmed and bounded, `null` to clear.
+ *
+ * Existence is the caller's question ({@link crmRefErrors}); this only rules
+ * out a value that could never be an id.
+ */
+export declare function readRefId(body: Record<string, unknown>, key: string, errors: Record<string, string>): string | null | undefined;
+/** Every key of `body` that is not in `allowed`, named as not writable. */
+export declare function refuseUnknownKeys(body: Record<string, unknown>, allowed: ReadonlySet<string>, noun: string, errors: Record<string, string>): void;
+/** The `400 validation_failed` every CRM write and filter answers with. */
+export declare function crmValidationFailed(ctx: ApiV1Context, noun: string, fields: Record<string, string>): Response;
+/** One `?field=value` a list accepts, in the order it prefers to index them. */
+export interface CrmEqualityFilter {
+    field: string;
+    value: string;
+}
+/**
+ * The CRM list grammar: at most one Firestore clause, the rest on the page.
+ *
+ * ## Why one clause
+ *
+ * Every equality here has a single-field index, and every list in this API
+ * ends in `orderBy(__name__)`, so ONE `where` is served without anything
+ * shipped. Two equalities, or an equality beside a range, is a composite
+ * index per combination — five resources with four filters each is more
+ * indexes than the whole product carries today, every one a query that
+ * answers `500` in production until it is deployed by hand. So the FIRST
+ * filter in `filters` goes to Firestore, and the caller orders them by
+ * selectivity: an id before a status, because `?dealId=` selects a handful
+ * of rows and `?status=open` selects most of the collection. The rest are
+ * applied to the page, which can come back short — the
+ * [short page](apps/docs/api/conventions.md) every filtered list already
+ * documents.
+ *
+ * ## `updatedAfter` changes the order
+ *
+ * The one range filter, and the one filter that cannot be a post-filter
+ * without becoming useless: a sync asking "what changed since T" over an
+ * id-ordered list still walks the whole collection to find out. So when it is
+ * given the list is ordered by `updated` ascending (then id), the range goes
+ * to Firestore, and EVERY equality moves to the page — a range on one field
+ * beside an equality on another is the composite index above. The cursor
+ * carries the timestamp and the id together, at Firestore's own precision,
+ * because a millisecond cursor would replay a row updated in the same
+ * millisecond on the next page.
+ */
+export declare function listCrm(ctx: ApiV1Context, collection: FirebaseFirestore.CollectionReference, url: URL, filters: CrmEqualityFilter[], view: (doc: FirebaseFirestore.QueryDocumentSnapshot) => unknown): Promise<Response>;
+/**
+ * The equality filters a list URL carries, in the caller's order, with an
+ * empty value meaning "absent" as every filter in this API does.
+ */
+export declare function readEqualityFilters(url: URL, fields: readonly string[]): CrmEqualityFilter[];
+/**
+ * The org's custom field definitions, retired ones included and every
+ * object's, for a resource's `custom` validation (AGL-2661).
+ *
+ * One bounded read of a small collection, paid only when a body carries
+ * `custom` — the contacts resource's own reader, shared so the three
+ * resources judge a map the same way. Retired definitions come back too
+ * because the reader refuses a write under one BY NAME, which is a better
+ * answer than "no such field" for a key the integration wrote last month.
+ */
+export declare function readOrgFieldDefinitions(ctx: ApiV1Context): Promise<ContactFieldDefinition[]>;
+/**
+ * The org's lead source list (AGL-3298) — the values a lead's
+ * `leadSource` is restricted to on every write through the API.
+ */
+export declare function readOrgLeadSourcePicklist(ctx: ApiV1Context): Promise<CrmPicklist>;
+/**
+ * A body's `custom` map, judged against the org's definitions for ONE
+ * object, or the refusals to answer with (AGL-2661).
+ *
+ * `undefined` when the body carried no map — nothing to validate and
+ * nothing to write. The read happens only then, so a body without
+ * `custom` pays for no definitions.
+ */
+export declare function readCrmCustomBody(ctx: ApiV1Context, body: Record<string, unknown>, object: CrmFieldObject): Promise<{
+    values: Record<string, CrmCustomValue>;
+} | {
+    errors: Record<string, string>;
+} | undefined>;
+/**
+ * A stored `custom` map as published: the map itself, or `{}` on a record
+ * that has none, so a client can index it without a guard (AGL-2661).
+ */
+export declare function crmCustomView(data: FirebaseFirestore.DocumentData): Record<string, CrmCustomValue>;
+/**
+ * The `custom` values as a PATCH writes them: one dotted path per key, so
+ * the stored map is merged rather than replaced — `custom` on a PATCH
+ * means "these keys", and an integration correcting one value must not
+ * have to resend the other nine to keep them. A `null` stays a `null`:
+ * the key remains, explicitly cleared, the shape a `where` can find.
+ */
+export declare function crmCustomUpdate(values: Record<string, CrmCustomValue>): Record<string, unknown>;