@memberjunction/connector-reply 1.0.0

package/dist/ReplyConnector.d.ts

@@ -0,0 +1,355 @@
+import { type UserInfo } from '@memberjunction/core';
+import type { MJCompanyIntegrationEntity, MJIntegrationObjectEntity } from '@memberjunction/core-entities';
+import { BaseRESTIntegrationConnector, type RESTAuthContext, type RESTResponse, type PaginationState, type PaginationType, type ConnectionTestResult, type FetchContext, type FetchBatchResult, type RateLimitPolicy, type SyncErrorCode, type CreateRecordContext, type UpdateRecordContext, type DeleteRecordContext, type CRUDResult, type SourceSchemaInfo } from '@memberjunction/integration-engine';
+/** RFC 9457 problem-details body. `code` is present on business problems, absent on middleware problems. */
+interface ReplyProblem {
+    /** Short, human-readable summary. */
+    title?: string;
+    /** HTTP status code echoed in the body. */
+    status?: number;
+    /** Human-readable explanation — for DISPLAY only; never classify on this. */
+    detail?: string;
+    /** Stable, machine-readable slug `<resource>.<variant>` — the classification key. */
+    code?: string;
+    /** Validation problems add a per-field error array. */
+    errors?: unknown;
+}
+/** One per-item failure from a non-atomic (bulk) response dictionary. */
+interface ReplyNotProcessedItem {
+    /** camelCase resource-specific failure variant (`contactAlreadyInSequence`, `notFound`, …). */
+    error?: string;
+    /** Human-readable detail, nullable per the vendor schema. */
+    errorDetails?: string | null;
+}
+/**
+ * Reply.io connector — extends BaseRESTIntegrationConnector (REST/JSON over HTTP).
+ *
+ * Discovery, template-var read traversal (second-layer objects resolve their parent through
+ * Configuration.parentObjectName), the paginated GET loop and the generic per-operation CRUD dispatch are
+ * all INHERITED. This class supplies the Reply-specific protocol surface: Bearer auth, top/skip offset
+ * pagination with per-endpoint ceilings, cross-page PK dedupe, embedded-array projection, RFC 9457 problem
+ * handling with entitlement (403) separation, non-atomic bulk outcome assertion, and the §7/§10
+ * sync-efficiency hooks the frozen contract evidences.
+ */
+export declare class ReplyConnector extends BaseRESTIntegrationConnector {
+    /** Cached auth for the lifetime of a sync run — Reply API keys are static, there is no refresh step. */
+    private cachedAuth;
+    /** Last non-2xx problem seen on the wire, used to explain an empty fetch instead of failing silently. */
+    private lastProblem;
+    /**
+     * `Retry-After` (in ms) captured from the most recent 429 seen on the wire, held for exactly ONE read.
+     *
+     * WHY this exists: the inherited read path validates a non-2xx by throwing a PLAIN `Error` carrying only
+     * a status + body preview — the response HEADERS are gone by the time the engine calls
+     * `ExtractRetryAfterMs(error)`. Without this capture the vendor's own `Retry-After` instruction is
+     * silently discarded on every throttled read and the engine falls back to a generic backoff curve,
+     * which is precisely what the contract forbids (100/min AND 3,000/hr are SHARED per user — guessing the
+     * wait either wastes the client's quota or hammers a closed window). Captured at the wire boundary,
+     * consumed once, then cleared so a stale value can never be replayed against a later error.
+     */
+    private pendingRetryAfterMs;
+    /** Wall-clock ms at which the last STRICT-family (reporting/stats) request was issued. */
+    private lastStrictFamilyRequestAt;
+    /** Verbatim `MJ: Integrations.Name`. Load-bearing: the T1 three-way check compares this === metadata Name. */
+    get IntegrationName(): string;
+    get SupportsCreate(): boolean;
+    get SupportsUpdate(): boolean;
+    get SupportsDelete(): boolean;
+    /**
+     * Discovery is NON-authoritative. Reply.io publishes no describe-all endpoint (Configuration
+     * DiscoveryIsAuthoritative=false in the frozen contract; the 270-path spec has no introspection route),
+     * so a refresh can only re-yield what is already Active. Absence in a refresh proves nothing → never
+     * deactivate an object on its basis.
+     */
+    get DiscoveryIsAuthoritative(): boolean;
+    /**
+     * Sample-union enrichment (MJ connector standard). The Declared metadata is spec-derived and cannot know
+     * a tenant's CUSTOM fields (Reply exposes user-defined custom fields on contacts). After the base
+     * cache-driven introspection, each object's live read shape is sampled via `DiscoverFieldsViaFetch` and
+     * UNIONed into the declared set with `mergeDeclaredWithSampledFields` (never-shrink, declared-wins).
+     * Best-effort + parallel — a sample failure (or an unentitled 403 family) leaves the declared set
+     * untouched. Overrides `IntrospectSchema`, NOT `DiscoverFields` (that would recurse into
+     * `DiscoverFieldsViaFetch`'s own fallback). Connector-agnostic: no Reply-specific field logic.
+     */
+    IntrospectSchema(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<SourceSchemaInfo>;
+    /**
+     * From every IO's Configuration.rateLimit: 100 requests/minute AND 3,000/hour, SHARED per API user
+     * across all of that user's tools. 100/min ≈ 1.67/s; we publish 1.5/s with a small burst so the hourly
+     * ceiling (0.83/s sustained) is approached conservatively rather than sprinting into a 429 wall. The
+     * engine's AIMD bucket cuts on 429 (honoring Retry-After below) and ramps back slowly.
+     */
+    get RateLimitPolicy(): RateLimitPolicy | null;
+    /**
+     * Reply.io returns `Retry-After` (integer SECONDS, minimum 1) on 429 — the vendor's own instruction, so
+     * it is honored exactly rather than approximated with a local backoff curve.
+     *
+     * Two sources, in order: (1) headers carried ON the error, when the caller surfaced a rich error; (2) the
+     * value captured at the wire boundary on the last 429, because the inherited read path throws a plain
+     * `Error` with the headers already discarded. The captured value is consumed once and cleared, so it can
+     * never be replayed against an unrelated later error.
+     */
+    ExtractRetryAfterMs(error: unknown): number | undefined;
+    /** Parses a `Retry-After` header (integer seconds per the vendor) into ms; undefined when absent/unparseable. */
+    private retryAfterFromHeaders;
+    /**
+     * Deliberately LOW. The rate budget is per-user and shared, and the vendor's guidance is sequential /
+     * low-concurrency access; parallelism here buys nothing but 429s against a 100/min ceiling.
+     */
+    get MaxConcurrencyHint(): number | null;
+    /**
+     * Every object is no-watermark (FullPullHashDiff), so resume relies on the object's declared stable
+     * ordering key (the extractor emitted `StableOrderingKey` per IO — usually `id`). Returns null when the
+     * object declares none and has no single primary key.
+     */
+    StableOrderingKey(objectName: string): string | null;
+    /**
+     * Resolves the Bearer credential from the linked Credential entity (preferred — `apiKey`, per the
+     * "API Key" credential type schema) or the CompanyIntegration Configuration JSON (fallback). Cached for
+     * the run. There is no token exchange, no signature and no expiry, so no auth-helper grant flow applies.
+     */
+    protected Authenticate(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<RESTAuthContext>;
+    /** Static header set — the Bearer value is composed once in Authenticate. */
+    protected BuildHeaders(auth: RESTAuthContext): Record<string, string>;
+    /**
+     * HTTP transport (fetch). Owns the wire boundary; test subclasses override this to capture requests.
+     *
+     * CRITICAL: a Reply.io 401 is documented to carry an EMPTY BODY (the scheme is signalled by the
+     * `WWW-Authenticate` header). Parsing is therefore guarded on a non-empty payload — `JSON.parse('')`
+     * on the most common failure path would crash the connector before it could report the auth failure.
+     * Any non-2xx is recorded (status + parsed problem) so FetchChanges can explain an empty result.
+     */
+    protected MakeHTTPRequest(_auth: RESTAuthContext, url: string, method: string, headers: Record<string, string>, body?: unknown): Promise<RESTResponse>;
+    /**
+     * Extra self-throttle for the reporting / statistics families. The rate budget (100/min AND 3,000/hr) is
+     * SHARED per API user across every tool that key drives, and these paths are the expensive ones — so this
+     * connector paces them to roughly one request per second rather than letting a stats-heavy object sprint
+     * the shared budget into a 429 wall that then stalls the whole sync.
+     *
+     * Deliberately NOT a retry and NOT a backoff: 429 handling stays with the engine's AIMD bucket +
+     * `ExtractRetryAfterMs` (which honors the vendor's `Retry-After` exactly). This is pure pre-emptive
+     * spacing, and it is a no-op for every ordinary collection read.
+     */
+    protected PaceStrictFamily(url: string): Promise<void>;
+    /** Clock seam — overridable so a test can assert pacing without real elapsed time. */
+    protected NowMs(): number;
+    /** Sleep seam — overridable so a test can assert pacing without actually waiting. */
+    protected Sleep(ms: number): Promise<void>;
+    /**
+     * Strips the Reply.io list envelope. Resolution order (deterministic — never "pick any array"):
+     *   1. the object's declared ResponseDataKey, when it names an array;
+     *   2. a bare array body;
+     *   3. the vendor-wide `items` envelope key (documented on every paginated collection);
+     *   4. a single non-enveloped object → a one-record array (get-one and the singleton doors such as
+     *      `/v3/contacts/{id}/statuses`, `/v3/whoami`, `/v3/sequence-templates`).
+     */
+    protected NormalizeResponse(rawBody: unknown, responseDataKey: string | null): Record<string, unknown>[];
+    /**
+     * Reply.io pagination is OFFSET ONLY. Continuation is the envelope's explicit `hasMore` boolean; when a
+     * response omits it (the non-enveloped singleton doors) a full page is treated as "more may follow" and
+     * a short page ends the walk. Cursor / page-number never occur in this vendor's surface.
+     */
+    protected ExtractPaginationInfo(rawBody: unknown, paginationType: PaginationType, _currentPage: number, currentOffset: number, pageSize: number): PaginationState;
+    /**
+     * Reply.io offset params are `top` (page size) + `skip` (offset) — NOT the base defaults `limit`/`offset`.
+     * The page size is clamped to the endpoint's DECLARED ceiling (IO.DefaultPageSize, probe-confirmed) and
+     * to the vendor-wide documented maximum, so a batch-capacity request can never exceed what the endpoint
+     * accepts (an over-large `top` is a 400 `*.invalidPagination`, not a silent truncation).
+     */
+    protected BuildPaginatedURL(basePath: string, obj: MJIntegrationObjectEntity, _page: number, offset: number, _cursor?: string, effectivePageSize?: number): string;
+    /** Base host for every request. A Configuration override (sandbox / spec-mock) wins over the vendor host. */
+    protected GetBaseURL(_companyIntegration: MJCompanyIntegrationEntity, auth: RESTAuthContext): string;
+    /**
+     * OVERRIDDEN for three Reply-specific read concerns; everything else delegates to the inherited base
+     * GET path (which uses the pagination overrides above and resolves template vars per-parent).
+     *
+     *  1. EMBEDDED-ARRAY PROJECTION — 17 of the 84 IOs have no endpoint of their own: their records live
+     *     inside another object's payload, declared as `Configuration.resourceKey = "<Owner>.<key>[]"`
+     *     (e.g. `Contact.customFields[]`, `HolidayCalendar.holidays[]`, `SequenceStep.variants[]`). For those
+     *     we fetch the OWNER through the inherited path — so the owner's own pagination, parent-iteration and
+     *     resume state all apply — then descend the declared key to emit the leaf records.
+     *  2. CROSS-PAGE PRIMARY-KEY DEDUPE — offset paging over a mutating collection shifts the window, so the
+     *     same record can appear on two pages of one walk. Records are de-duplicated by ExternalID.
+     *  3. ENTITLEMENT REPORTING — a 403 means "reachable but not entitled" (missing scope / plan feature).
+     *     The base skips 403 objects with a console.warn; we additionally attach a structured FetchWarning so
+     *     an unentitled family is REPORTED, not silently dropped and not counted as a pass.
+     */
+    FetchChanges(ctx: FetchContext): Promise<FetchBatchResult>;
+    /**
+     * Caps a fetch call to ONE endpoint page so the engine checkpoints after every page.
+     *
+     * The inherited pagination loop keeps requesting pages until it has accumulated `BatchSize` records,
+     * and only THEN returns `NextOffset` for the engine to persist. With Reply.io's 3,000-requests/hour
+     * ceiling a first full sync of a large tenant runs for HOURS, and an interruption anywhere inside that
+     * loop discards every page fetched since the last engine checkpoint — pages that cost real, shared,
+     * per-user quota that cannot be bought back. Clamping the batch to the endpoint's own page ceiling
+     * makes the loop return after a single request, so `NextOffset` is persisted per PAGE and a resumed
+     * sync re-requests at most one page. Cost: nothing — the same number of HTTP requests either way.
+     *
+     * No-op for non-offset / non-paginated objects (single-shot doors) and when the engine already asked
+     * for a batch at or below the page ceiling.
+     */
+    protected ClampBatchToOnePage(ctx: FetchContext, walked: MJIntegrationObjectEntity): FetchContext;
+    /**
+     * Reads the embedded-projection declaration off an IO. The extractor writes
+     * `Configuration.resourceKey = "<OwnerObjectName>.<nestedKey>[]"` for an object that is an array nested
+     * inside another payload, and a plain slash-path (`"contacts/statuses"`) for one that has its own
+     * endpoint — so the two cases are distinguished by DECLARED metadata, never by guessing at the URL.
+     */
+    private resolveEmbeddedProjection;
+    /**
+     * Fetches an embedded-projection object: pull the CONTAINER records through the inherited fetch path,
+     * then descend the declared nested key on each one to emit the leaf records.
+     *
+     * The container is the OWNER object named in `resourceKey` when that object exists and shares this
+     * object's APIPath (so the owner's declared pagination/parent-iteration governs the walk); otherwise —
+     * e.g. the sequence-template groups, whose owner is declared as `null` — the projection's own IO row is
+     * the container. Both cases read only DECLARED metadata.
+     */
+    private fetchProjected;
+    /** The IO whose endpoint actually returns the container payload for a projection (owner, else self). */
+    private resolveContainerObject;
+    /**
+     * Copies owner-record keys down onto a leaf record — but ONLY keys the leaf object DECLARES as its own
+     * fields and does not already carry. This links a nested row back to its owner (the parent id the base
+     * tagged onto the container) without inventing columns: an undeclared owner key is never copied.
+     */
+    private inheritDeclaredOwnerKeys;
+    /**
+     * Drops repeats of the same primary key WITHIN one fetch batch — which is exactly "across pages", since
+     * the inherited loop accumulates every page of the walk into one batch. Records with no resolvable
+     * ExternalID are passed through untouched (they cannot be compared, and silently collapsing them would
+     * lose data). Across BATCHES the engine's content-hash idempotency makes a repeat a no-op update.
+     */
+    private dedupeByExternalID;
+    /**
+     * Turns an observed 403/401 into a structured warning when the fetch produced nothing, so an unentitled
+     * or unauthenticated family is REPORTED rather than read as "this object is legitimately empty".
+     * 403 is explicitly NOT an invalid credential and NOT a connector defect.
+     */
+    private collectWarnings;
+    /**
+     * Diagnoses a parent-iterated object whose DECLARED parent cannot actually yield the ids its path
+     * needs, and reports it as a structured warning.
+     *
+     * This does NOT repair the declaration — a wrong `Configuration.parentObjectName` is an upstream
+     * metadata defect that belongs in the extractor's amendment loop, and guessing a replacement here is
+     * exactly the silent cross-owner corruption the base class refuses to commit. What it prevents is the
+     * WORSE outcome: such an object fetches zero rows (the parent yields no usable ids) and, with no
+     * warning attached, that empty result is indistinguishable from "this object is legitimately empty" —
+     * a green sync that quietly carries nothing.
+     *
+     * Two detectable defects, both provable from metadata alone:
+     *  - a MULTI-var path (`/v3/sequences/{sequence_id}/contacts/{contact_id}/preview`) with only the
+     *    single-valued `parentObjectName` — both vars would resolve to the same parent, which the base
+     *    rejects as a dependency cycle;
+     *  - a declared parent that is missing, or that declares NO primary key (e.g. an embedded projection
+     *    such as `ContactCustomField`, whose fields are `key`/`value`) — there is no id column to iterate.
+     */
+    private parentDeclarationWarning;
+    /** True when the IO's Configuration carries KEY as a non-empty object (used for the per-var parent map). */
+    private hasConfigObject;
+    /** Create — generic per-operation dispatch + parent-var substitution + partial-success assertion. */
+    CreateRecord(ctx: CreateRecordContext): Promise<CRUDResult>;
+    /** Update — generic per-operation dispatch (PUT or PATCH per IO) + partial-success assertion. */
+    UpdateRecord(ctx: UpdateRecordContext): Promise<CRUDResult>;
+    /** Delete — generic per-operation dispatch (hard delete; the vendor has no universal tombstone). */
+    DeleteRecord(ctx: DeleteRecordContext): Promise<CRUDResult>;
+    /** Authenticates, resolves the URL and fires ONE write request. No retry — see the CRUD section note. */
+    private executeWrite;
+    /**
+     * Asserts a write actually happened. Returns a failure CRUDResult, or null when the write succeeded.
+     *
+     * Order matters: a non-2xx is a failure classified off the problem CODE; a 2xx is only a success once the
+     * body has been checked for the non-atomic per-item failure dictionary. HTTP 200 alone proves the request
+     * was ACCEPTED, not that the item was PROCESSED — the two are different on this vendor.
+     */
+    private assertWriteOutcome;
+    /**
+     * Parses a non-atomic (bulk) response body: a dictionary keyed by item id whose values are
+     * `{ error, errorDetails }` — ONLY failed items appear, and `{}` means everything succeeded. Returns null
+     * when the body is not that shape (an ordinary single-record response), so this check costs nothing on
+     * the normal path and can never misread a created record as a failure.
+     */
+    parseNotProcessed(body: unknown): Map<string, ReplyNotProcessedItem> | null;
+    /**
+     * OVERRIDDEN so the generic Update/Delete/Get path can template Reply's NAMED and NESTED path vars
+     * (`{step_id}`, `{variant_id}`, `{knowledge_base_id}`, `{document_id}`, `{tagId}`) — the base substitutes
+     * only `{id}`/`{ExternalID}`. A single-var path takes the whole ExternalID; a multi-var (nested) path
+     * takes the composite `parent|child` ExternalID split in path order.
+     */
+    protected SubstituteIDInPath(path: string, externalID: string, idLocation: string | null): string;
+    /** Fills a create path's PARENT template vars from the record's own attributes (nested creates). */
+    private substitutePathVarsFromAttributes;
+    /**
+     * OVERRIDDEN for the RFC 9457 `application/problem+json` envelope. Never assumes a body exists — a
+     * Reply.io 401 carries none. The message leads with the STABLE machine `code` so the engine's classifier
+     * and any human reader both key off the slug rather than the localized `detail`.
+     */
+    protected ExtractErrorMessage(response: RESTResponse): string | undefined;
+    /** Parses an RFC 9457 problem body; null for an empty/non-problem payload (401 has NO body). */
+    parseProblem(body: unknown): ReplyProblem | null;
+    /**
+     * Maps a Reply.io response to a `SyncErrorCode` using the STABLE machine slug first and the HTTP status
+     * as the fallback — never the human-readable `detail`, which is localized prose and free to change.
+     *
+     * 403 maps to CONFIGURATION_ERROR (an entitlement/scope gap the operator resolves), deliberately NOT to
+     * an auth failure: the credential is valid, the tenant simply is not entitled to that surface.
+     */
+    ClassifyProblem(status: number, problem: ReplyProblem | null): SyncErrorCode;
+    /**
+     * Renders a problem into a message that (a) leads with the machine slug, (b) states the classification,
+     * and (c) carries wording the engine's message-based `ClassifyError` maps to the SAME SyncErrorCode —
+     * so the code the connector determined survives the string boundary instead of being re-guessed.
+     */
+    private describeProblem;
+    /** A phrase the engine's message-based ClassifyError maps to the given code (keeps both paths in sync). */
+    private classifierHint;
+    /**
+     * Records the last non-2xx seen on the wire so an empty fetch can be explained rather than guessed at,
+     * and captures a 429's `Retry-After` before the inherited validator throws it away (see
+     * {@link pendingRetryAfterMs}).
+     */
+    private recordProblem;
+    /**
+     * Verifies the credential against `GET /v3/whoami` — documented `x-required-scope: none`, so ANY valid
+     * key can call it and a failure there is unambiguous. 401 = bad/missing key (empty body by design);
+     * 403 on this endpoint would still mean the key is valid but the account is restricted, so it is reported
+     * as a NON-credential problem.
+     */
+    TestConnection(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<ConnectionTestResult>;
+    /** Reads the API key from the linked Credential entity, falling back to the Configuration JSON. */
+    private loadCredentials;
+    /** Loads a credential row and parses its Values JSON. */
+    private loadFromCredentialEntity;
+    /** Extracts the API key from a credential/config JSON string (tolerant of absent/invalid). */
+    private parseCredentialJson;
+    /**
+     * Reads an explicit base-URL override from the connection Configuration. Only an absolute http(s) URL is
+     * honored, so a stray value cannot misroute a production tenant. Null (the normal case) → the vendor host.
+     */
+    private resolveBaseURLOverride;
+    /** Joins a base URL and a path (mirrors the base's private BuildFullURL). */
+    private joinURL;
+    /** PK field names in declared Sequence order; empty when the object declares none. */
+    private pkFieldNames;
+    /**
+     * Builds an ExternalRecord whose Fields carry the FULL source record (full-record pass-through — the
+     * framework's custom-column capture diffs keys(Fields) against the active field maps, so a narrowed
+     * literal would make custom columns permanently invisible). ExternalID is the composite of the declared
+     * PK fields when all are present, else the vendor's universal `id`, else empty.
+     */
+    private buildExternalRecord;
+    /**
+     * Gets an IO by NAME alone from the engine cache, without throwing (callers may run before the cache is
+     * warm, and StableOrderingKey has no IntegrationID to hand). Protected so a test/mock subclass can
+     * substitute fixture rows exactly as it does for GetCachedObject.
+     */
+    protected tryGetCachedObject(objectName: string): MJIntegrationObjectEntity | null;
+    /** Reads a trimmed string value from an IntegrationObject's Configuration JSON (tolerant of absent/invalid). */
+    private readConfigString;
+    /** Returns the first present, non-empty string value among the given keys. */
+    private firstString;
+    /** Best-effort extraction of response headers from an error object (for ExtractRetryAfterMs). */
+    private extractHeadersFromError;
+}
+export {};