@memberjunction/connector-neon-crm 1.0.0

package/dist/NeonCRMConnector.d.ts

@@ -0,0 +1,272 @@
+import { type UserInfo } from '@memberjunction/core';
+import type { MJCompanyIntegrationEntity, MJIntegrationObjectEntity, MJIntegrationObjectFieldEntity } from '@memberjunction/core-entities';
+import { BaseRESTIntegrationConnector, type RESTAuthContext, type RESTResponse, type PaginationState, type PaginationType, type ConnectionTestResult, type ExternalObjectSchema, type ExternalFieldSchema, type FetchContext, type FetchBatchResult, type RateLimitPolicy, type CreateRecordContext, type CRUDResult } from '@memberjunction/integration-engine';
+/**
+ * Neon CRM connection configuration, parsed from the attached MJ Credential (preferred)
+ * or the CompanyIntegration.Configuration JSON. Field names are read case-insensitively.
+ * NONE of these values are read at build time — resolved from the bound credential at runtime.
+ */
+export interface NeonCRMConnectionConfig {
+    /** Neon organization id — the HTTP Basic userid. */
+    OrgID: string;
+    /** Neon API key — the HTTP Basic password. */
+    APIKey: string;
+    /** API base URL (defaults to https://api.neoncrm.com/v2). */
+    BaseURL: string;
+    /** NEON-API-VERSION header value (defaults to 2.11). */
+    APIVersion: string;
+    /** Maximum retries for transient (429/503/network) failures. Default 3. */
+    MaxRetries: number;
+    /** HTTP request timeout in ms. Default 30000. */
+    RequestTimeoutMs: number;
+}
+export declare class NeonCRMConnector extends BaseRESTIntegrationConnector {
+    /** Cached auth context for the current sync run. */
+    private authCache;
+    /** Current watermark value, available to FetchChanges-driven filtering. */
+    private currentWatermark;
+    get IntegrationName(): string;
+    get SupportsCreate(): boolean;
+    get SupportsUpdate(): boolean;
+    get SupportsDelete(): boolean;
+    /** True when any cached IntegrationObject satisfies the predicate. []→false when the
+     *  engine cache is unavailable (capability probed before configuration) — fail-safe read-only. */
+    private anyObjectDeclares;
+    get RateLimitPolicy(): RateLimitPolicy | null;
+    /** Parse Neon's Retry-After (seconds or http-date) into ms for the engine's AIMD bucket. */
+    ExtractRetryAfterMs(error: unknown): number | undefined;
+    protected TransformRecord(raw: Record<string, unknown>, obj: MJIntegrationObjectEntity, _fields: MJIntegrationObjectFieldEntity[]): Record<string, unknown>;
+    /**
+     * Lifts a nested `individualAccount.accountId` / `companyAccount.accountId` to a top-level
+     * `accountId` WITHOUT overwriting an existing top-level value and WITHOUT dropping the nested
+     * blobs (full-record pass-through). Returns the input unchanged when there is nothing to lift.
+     * Reused by {@link TransformRecord} (Account direct sync) and by the access-path descent's
+     * door-PK resolution (so a Consent leaf can be stamped with its account's id — DEFECT 2).
+     */
+    private liftNestedAccountId;
+    /** Reads a scalar `accountId` from a nested individual/company account blob, if present. */
+    private readNestedAccountId;
+    CreateRecord(ctx: CreateRecordContext): Promise<CRUDResult>;
+    /** Whether an error is a request timeout / aborted fetch (distinct from a clean non-2xx response). */
+    private isTimeoutError;
+    /**
+     * HTTP Basic authentication. Builds the `Basic base64(orgId:apiKey)` header via the
+     * shared auth-helper (no inline base64). Credential bytes are resolved at runtime.
+     */
+    protected Authenticate(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<RESTAuthContext>;
+    /** Sends the Basic auth header + NEON-API-VERSION + JSON content negotiation on every request. */
+    protected BuildHeaders(auth: RESTAuthContext): Record<string, string>;
+    protected GetBaseURL(_companyIntegration: MJCompanyIntegrationEntity, auth: RESTAuthContext): string;
+    /**
+     * Normalizes Neon CRM responses. Handles the real shapes:
+     *   1. List/search envelope `{ <dataKey>: [...], pagination: {...} }` — the dataKey is the
+     *      resource collection (e.g. `accounts`, `searchResults`, `donations`, `memberships`).
+     *      When ResponseDataKey is set on the IO we read it; otherwise we auto-detect the first
+     *      array-valued property that is NOT the `pagination` envelope.
+     *   2. Raw array at the root.
+     *   3. Single object — per-id GET endpoints return ONE record (often itself wrapped, e.g.
+     *      `{ accountId, individualAccount: {...} }`); kept as a single-element list.
+     *
+     * The FULL source record passes through (no field filtering) so the framework's custom-column
+     * capture sees everything Neon returned.
+     */
+    protected NormalizeResponse(rawBody: unknown, responseDataKey: string | null): Record<string, unknown>[];
+    /**
+     * Finds the records array inside a Neon list/search envelope. Neon names the collection
+     * after the resource (`accounts`, `donations`, `memberships`, `searchResults`, …) and always
+     * carries a sibling `pagination` object. We pick the first array-valued property that is not
+     * `pagination`. Returns null when no collection array is present (a single-object response).
+     */
+    private findCollectionArray;
+    /**
+     * Derives Neon page-number pagination state. Neon returns a `pagination` envelope with
+     * `currentPage` (0-based), `totalPages`, `totalResults`. More pages remain while
+     * currentPage + 1 < totalPages. Falls back to an empty-page terminator when no envelope.
+     */
+    protected ExtractPaginationInfo(rawBody: unknown, _paginationType: PaginationType, currentPage: number, currentOffset: number, _pageSize: number): PaginationState;
+    /**
+     * Emits Neon page-number pagination params: `currentPage` (0-based) + `pageSize` (capped at
+     * the vendor's 200 ceiling). currentPage is page-1 because the base loop counts from 1.
+     */
+    protected BuildPaginatedURL(basePath: string, obj: MJIntegrationObjectEntity, page: number, _offset: number, _cursor?: string, effectivePageSize?: number): string;
+    /**
+     * Executes an HTTP request with retry/backoff for 429/503 and transient network errors.
+     * Parses Neon's Retry-After header into the error so ExtractRetryAfterMs can surface it.
+     * NOTE: retry is applied to GET/idempotent reads and to non-financial writes only — the
+     * CreateRecord override above handles the financial reconcile-before-retry contract.
+     */
+    protected MakeHTTPRequest(auth: RESTAuthContext, url: string, method: string, headers: Record<string, string>, body?: unknown): Promise<RESTResponse>;
+    /**
+     * Tests connectivity by listing one account via GET /accounts?currentPage=0&pageSize=1.
+     * A 2xx confirms the Basic credentials (org id + API key) + base URL are valid. 401/403 are
+     * surfaced with clear messages (auth failure path); a network error is surfaced too.
+     */
+    TestConnection(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<ConnectionTestResult>;
+    /**
+     * Discovers the full object universe from the IntegrationEngineBase cache (the Declared
+     * metadata seeded from Neon's credential-free OAS3 spec). NEVER a hardcoded catalog; never
+     * sampled at build. When no Declared metadata is loaded (a credential-free static self-check
+     * with no DB-backed engine), this throws explicitly so credential-free tiers SKIP honestly
+     * rather than misread an empty result as catalog drift.
+     */
+    DiscoverObjects(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<ExternalObjectSchema[]>;
+    /** Discovers fields for an object from the cached Declared metadata. */
+    DiscoverFields(companyIntegration: MJCompanyIntegrationEntity, objectName: string, contextUser: UserInfo): Promise<ExternalFieldSchema[]>;
+    /**
+     * Enumerates an object's records per the THREE metadata-driven enumeration modes (read from the
+     * IO's Configuration), then advances the watermark from the returned records on the FINAL batch
+     * only (partial-failure-safe — a mid-batch failure leaves the watermark unchanged so the next sync
+     * resumes from the same point). Watermark advancement reads the latest
+     * `timestamps.lastModifiedDateTime` (Neon's documented incremental cursor).
+     *
+     *   Mode 1 — Direct collection, GET   → delegate to the base GET pagination path (super.FetchChanges).
+     *   Mode 2 — Direct collection, POST  → POST the Configuration.ListBody to APIPath, paginate via body.
+     *   Mode 3 — Access-path descent       → list the DOOR, then descend the nesting chain in memory.
+     *
+     * Mode is inferred from the IO's parsed Configuration; a missing/GET-direct Configuration keeps the
+     * exact prior behavior (the 34 direct-GET objects ride the base path unchanged).
+     */
+    FetchChanges(ctx: FetchContext): Promise<FetchBatchResult>;
+    /** Routes the fetch to the GET-direct base path, POST-search listing, or access-path descent. */
+    private dispatchEnumeration;
+    /** Parses the IO's Configuration JSON into a typed NeonObjectConfig (GET-direct default on absence). */
+    private parseObjectConfig;
+    /** Narrows an unknown AccessPath blob to the typed shape (provable-only — undefined when absent). */
+    private coerceAccessPath;
+    /** True when this object's door must be LISTED via POST (search). */
+    private isPostList;
+    private coerceString;
+    private coerceRecord;
+    /**
+     * Lists a direct-collection object whose door is a POST `/…/search` endpoint. POSTs the
+     * Configuration.ListBody (parsed JSON) to APIPath, parses the same Neon envelope as GET, and
+     * paginates by injecting the page into the POST body's `pagination` object
+     * (`{"pagination":{"currentPage":N,"pageSize":M}}`). Returns a single full batch.
+     */
+    private fetchViaPostSearch;
+    /**
+     * Lists the DOOR (via GET or POST per the access path), then descends the in-memory nesting chain
+     * to collect the LEAF records of `obj`. Each leaf carries the FULL leaf object in `Fields`
+     * (full-record pass-through), is tagged with the resolved ancestor FK id(s), and uses its own
+     * declared PK for identity (the synthetic content-hash fallback covers PK-less leaves).
+     */
+    private fetchViaAccessPath;
+    /**
+     * Lists the access-path door, choosing GET or POST-search per the access path's listMethod.
+     * NOTE: NO server-side watermark filter is applied here. A date filter on the DOOR would narrow
+     * by the PARENT's last-modified date, which is NOT the LEAF object's watermark — filtering doors
+     * could drop leaf records whose owning parent wasn't modified recently (lossy). For nested/descent
+     * objects, content-hash narrowing remains the correct, lossless incremental strategy.
+     */
+    private listDoor;
+    /** Splits a nesting chain string ("A -> b[] -> c") into typed segments (IsList for `[]`). */
+    private parseNestingChain;
+    /**
+     * Descends the nesting segments from a single door record IN MEMORY, collecting the leaf records,
+     * CARRYING the ancestor FK tags down the WHOLE chain (DEFECT 2). A `[]` segment expands an
+     * array-valued field (iterate each element); a plain segment dives into an object-valued field
+     * (single child). Records and primitives are skipped gracefully. Recurses so ≥2-level chains
+     * (e.g. pledges[] -> pledgePayments[]) are supported.
+     *
+     * `fkTagFields` is the leaf's set of ancestor-FK field names; `inheritedTags` is the accumulator
+     * seeded with the DOOR (root ancestor) record's resolved PK value(s). At EACH descended node we
+     * re-collect FK values present on that node (so a nearer ancestor — e.g. an intermediate Pledge —
+     * overrides a farther one), then at the leaf we stamp every accumulated tag the leaf does NOT
+     * already carry (the leaf's own value always wins). This makes the door's `accountId` reach a
+     * Consent leaf in `Account -> individualAccount -> consent`, while preserving the existing
+     * immediate-parent / 1-level behavior.
+     */
+    private descendNesting;
+    /** Merges an intermediate node's own ancestor-FK values into the accumulator (node value wins). */
+    private mergeNodeTags;
+    /** Stamps accumulated ancestor FK id(s) onto a leaf, never overwriting an id the leaf already carries. */
+    private stampInheritedTags;
+    /**
+     * Resolves, from the leaf object's own IOFs, the FK field names that point at an ancestor object
+     * (RelatedIntegrationObjectID set). These are the columns to populate from an ancestor record so the
+     * leaf links back to its owner.
+     */
+    private resolveAncestorFKFields;
+    /**
+     * Reads each ancestor-FK value from an ancestor record so it can be stamped onto the leaf. Applies
+     * the nested-account-id lift first so the DOOR Account record's nested `accountId` (DEFECT 1) is
+     * found — then reads the matching FK key (e.g. `accountId`, `pledgeId`). Neon ancestor records carry
+     * their own id under a key whose name matches the leaf's FK field name.
+     */
+    private collectParentTags;
+    /** Lists a door via GET, paginating to exhaustion (Neon 0-based currentPage). Returns all records. */
+    private listAllViaGet;
+    /**
+     * Lists a door via POST search, paginating to exhaustion by injecting `{pagination:{currentPage,pageSize}}`
+     * into the POST body (Neon search pagination). Returns all records.
+     */
+    private listAllViaPost;
+    /** Builds the POST search body with the page injected into the `pagination` envelope. */
+    private buildSearchBody;
+    /**
+     * Builds the effective POST-search `ListBody` for the incremental pass: when a watermark is
+     * present AND the door has a resolvable last-modified SEARCH FIELD, appends a
+     * `{ field, operator: GREATER_AND_EQUAL, value }` criterion to `searchFields` (the OAS3
+     * SearchRequest shape) so the API returns ONLY records changed at/after the watermark. On first
+     * sync (no watermark) — or for a door with no documented search field — returns the configured
+     * ListBody unchanged (full pull; content-hash narrowing remains the lossless fallback).
+     *
+     * Provable-only: a criterion is emitted ONLY when the search-field name is known — from the
+     * per-connection `Configuration.WatermarkSearchField` override or the documented
+     * {@link DOOR_WATERMARK_SEARCH_FIELD} map. A criterion is NEVER appended to a `searchFields` the
+     * connector already carries one for (idempotent), and the existing authored searchFields are
+     * preserved.
+     */
+    private buildIncrementalListBody;
+    /**
+     * Resolves the door's last-modified SEARCH FIELD display name (the OAS3 SearchCriteria.field
+     * value), preferring the per-connection `Configuration.WatermarkSearchField` override, then the
+     * documented {@link DOOR_WATERMARK_SEARCH_FIELD} map keyed by the door path. Returns undefined
+     * when neither knows the door (⇒ no server-side filter).
+     */
+    private resolveWatermarkSearchField;
+    /**
+     * Formats an ISO watermark timestamp to Neon's documented date-search value (`yyyy-MM-dd`).
+     * Neon date search fields filter at day granularity; a date-only `>=` is a safe, slightly
+     * conservative bound that never drops a same-day record (the engine still re-narrows via
+     * content hash). Returns undefined for an unparseable watermark.
+     */
+    private formatNeonSearchDate;
+    /** Reads the Neon pagination envelope to decide whether another door page remains (0-based). */
+    private hasMorePages;
+    /** Returns the declared PK field names (by Sequence) or ['ID'] fallback — mirrors the base helper. */
+    private findPKFieldNames;
+    /**
+     * Builds an ExternalRecord with the SAME identity semantics the base uses: declared PK when every
+     * component is present + non-empty, else a deterministic content hash (the synthetic-PK fallback for
+     * PK-less / partial-key leaves). The FULL record passes through in `Fields` (full-record pass-through).
+     */
+    private buildExternalRecord;
+    /** A zero-record batch carrying a structured FetchWarning so the silent-empty is surfaced. */
+    private zeroWithWarning;
+    /**
+     * Parses the connection config, preferring the attached MJ Credential over the raw
+     * Configuration JSON. Credential bytes are resolved at runtime — never at build.
+     */
+    private ParseConfig;
+    /** Loads the config from the MJ: Credentials entity Values JSON. */
+    private parseConfigFromCredential;
+    /** Validates the parsed config + applies defaults. Field names are case-insensitive. */
+    private validateConfig;
+    /** Extracts the latest timestamps.lastModifiedDateTime across a batch for watermark advancement. */
+    private extractLatestModifiedDate;
+    /** Reads timestamps.lastModifiedDateTime (Neon's nested cursor) or a flat top-level fallback. */
+    private readLastModified;
+    /** Parses a Retry-After header (seconds or http-date) into ms, if present. */
+    private retryAfterMs;
+    /** Exponential backoff delay for retry attempts (capped at 30s). */
+    private backoffDelay;
+    /** Checks whether an error is transient (network/timeout). */
+    private isTransientNetworkError;
+    /** Builds the normalized RESTResponse from a fetch Response. */
+    private buildRESTResponse;
+    /** Promise-wrapped setTimeout. */
+    private sleep;
+}
+/** Tree-shaking prevention — import and call from the package entry point. */
+export declare function LoadNeonCRMConnector(): void;