@memberjunction/connector-eventscribe 0.2.0

package/dist/EventscribeConnector.d.ts

@@ -0,0 +1,538 @@
+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 RateLimitPolicy, type ConnectionTestResult, type ExternalRecord, type FetchContext, type FetchBatchResult, type SourceSchemaInfo, type SyncErrorCode, type ErrorSeverity, type CreateRecordContext, type UpdateRecordContext, type DeleteRecordContext, type GetRecordContext, type CRUDResult } from '@memberjunction/integration-engine';
+/** Resolved auth for one connection. The API key is static — Cadmium documents no token endpoint. */
+export interface EventscribeAuthContext extends RESTAuthContext {
+    APIKey: string;
+    /** Per-CONNECTION (tenant) event scope. NEVER a value baked into this class. */
+    EventID?: string;
+    IntegrationID: string;
+}
+/** A classified vendor failure, kept structured so the engine can route it. */
+export interface EventscribeErrorClassification {
+    Code: SyncErrorCode;
+    Severity: ErrorSeverity;
+    Retryable: boolean;
+    Reason: string;
+}
+/** Typed transport failure carrying the vendor's own message and the classified verdict. */
+export declare class EventscribeAPIError extends Error {
+    readonly Status: number;
+    readonly Headers: Record<string, string>;
+    readonly Classification: EventscribeErrorClassification;
+    readonly VendorMessage?: string | undefined;
+    constructor(message: string, Status: number, Headers: Record<string, string>, Classification: EventscribeErrorClassification, VendorMessage?: string | undefined);
+}
+export declare class EventscribeConnector extends BaseRESTIntegrationConnector {
+    /**
+     * The object + verb the CURRENT async call chain is serving. The base class's `GetBaseURL`,
+     * `ExtractPaginationInfo`, `BuildOperationBody` and `ExtractIDFromResponse` hooks are called
+     * without an object argument, but every one of them is per-object on this vendor (five families,
+     * three hosts, per-object pagination envelope, per-object array-body write convention). An
+     * AsyncLocalStorage scope carries the identity correctly even when the engine pushes several
+     * objects concurrently — a mutable `this.currentObject` field would silently cross the wires.
+     */
+    private readonly scope;
+    /** Resolved auth per CompanyIntegration.ID. The APIKey is static; there is nothing to refresh. */
+    private readonly authCache;
+    /** Earliest permitted send time per `host|MethodValue`, so the vendor's documented spacing is honoured. */
+    private readonly nextAllowedAt;
+    /** Warnings already emitted, so a long sync logs honestly rather than noisily. */
+    private readonly warnedOnce;
+    /** Verbatim `MJ: Integrations.Name`. Load-bearing: T1 compares this === the metadata Name. */
+    get IntegrationName(): string;
+    /**
+     * TRUE. `Configuration.WriteCapability` documents `addUpdateAccount` (eventscribe-web),
+     * `addUpdateExhibitor` / `addUpdateBooth` / `addUpdateExhibitorStaff` (expo-harvester) and
+     * `addUpdatePresenter` / `addUpdatePresentation` (education-harvester); those objects carry
+     * populated `CreateAPIPath` + `CreateMethod` columns and ride the base class's generic create.
+     */
+    get SupportsCreate(): boolean;
+    /** TRUE for the same `addUpdate*` upsert operations — they are create-OR-update in one call. */
+    get SupportsUpdate(): boolean;
+    /**
+     * TRUE, but narrowly: only Account (`cancelAccount` / `deleteAccount`) and Presentation
+     * (`deletePresentation`) declare a delete operation. `Configuration.WriteCapability` records
+     * expo-harvester's `unassignBooth` as explicitly NOT a delete, and abstract-scorecard as 100%
+     * read-only, so those objects leave `DeleteAPIPath` null and the generic delete refuses them.
+     */
+    get SupportsDelete(): boolean;
+    /**
+     * FALSE, permanently. `Configuration.DiscoveryIsAuthoritativeReason` (metadata): Cadmium documents
+     * NO list/describe/schema endpoint anywhere in the corpus, so "absence from a sample response
+     * proves nothing about what the vendor's schema actually supports". A thin runtime result must
+     * never deactivate a persisted object or field — that would be tenant-visible data loss.
+     */
+    get DiscoveryIsAuthoritative(): boolean;
+    /**
+     * Read STRAIGHT off `Configuration.RateLimits.standard` ("1 request per 1000 ms, most methods,
+     * vendor-wide"). Returns null when the integration row carries no rate-limit facts — the engine
+     * then paces itself rather than obeying a number this class invented. The per-METHOD overrides
+     * (the two vendor-documented heavy methods at 1/60s) cannot be expressed in this connector-wide
+     * policy, so they are enforced per request in {@link PaceRequest}.
+     */
+    get RateLimitPolicy(): RateLimitPolicy | null;
+    /**
+     * One in flight when the vendor's documented standard allowance is one request per window —
+     * derived from the same `Configuration.RateLimits.standard` fact, not asserted here. Null when the
+     * metadata carries no allowance, so the engine keeps its own default.
+     */
+    get MaxConcurrencyHint(): number | null;
+    /**
+     * Strictly whatever the object's own `StableOrderingKey` column declares. Never synthesised: an
+     * invented resume cursor on a source with no server-side ordering guarantee silently skips rows.
+     */
+    StableOrderingKey(objectName: string): string | null;
+    /**
+     * TRUE. The `addUpdate*` operations are REAL batch endpoints: `Configuration.BatchSemantics`
+     * documents "JSON array in the raw POST body (single-object writes still require wrapping in a
+     * one-element array)" with per-record, NON-ATOMIC processing. See {@link BatchCreateRecords}.
+     */
+    get SupportsBatchWrite(): boolean;
+    /**
+     * Declared ∪ live-sampled, so a tenant's own columns reach the schema builder. Cadmium's field
+     * sets are demonstrably per-tenant (`AccountCustomField1..10`, `AuthorCustomFieldN`,
+     * `SubmitterCustomFieldN`, `ReviewAnswerN` are all templated in the vendor docs), and with no
+     * describe endpoint the ONLY way to learn which of them a given event actually populates is to
+     * read real records. The union is delegated to the shared never-shrink helper; this connector
+     * supplies no merge logic of its own, and a sampling failure leaves the DECLARED floor intact.
+     */
+    IntrospectSchema(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<SourceSchemaInfo>;
+    /**
+     * Runs the cheapest real read this connection can make: the first ACTIVE, directly-queryable
+     * object's own door. Objects whose only door needs a caller-supplied record key
+     * (`Configuration.requiresRecordKeyToRead`) are skipped — calling them unkeyed proves nothing.
+     * The message never carries credential bytes.
+     */
+    TestConnection(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<ConnectionTestResult>;
+    /**
+     * OVERRIDDEN for two evidenced reasons, and it delegates back to the base for everything else.
+     *
+     *   (a) MULTI-HOST. The object's identity has to be in scope before `GetBaseURL` runs, because the
+     *       base's signature has no object slot and this vendor has three hosts.
+     *   (b) NESTED ACCESS PATHS. A large minority of the declared objects carry `accessPath.depth >= 1`
+     *       with the note "This object has no read operation of its own; its records arrive nested
+     *       inside the door operation's response under the '<key>' key." A flat per-object query
+     *       returns ZERO rows for every one of them, so those walk the declared path instead.
+     *
+     * A depth-0 object goes straight back to `super.FetchChanges` — the base's pagination loop,
+     * batch limiting and record assembly are used AS IS. Two metadata-declared refusals run FIRST
+     * ({@link WireFormatGate}, {@link RecordKeyGate}) so an object this connector cannot honestly read
+     * reports a structured warning instead of a silent, green, zero-row batch.
+     */
+    FetchChanges(ctx: FetchContext): Promise<FetchBatchResult>;
+    /**
+     * Refuses an object whose metadata declares a wire format this connector does not parse.
+     * `Configuration.responseFormat` is a per-object FACT: the five in-scope families are all `json`,
+     * while the EdgeReg family ships `xml` (and its own `responseFormatNote`: "The connector must parse
+     * XML for this object") together with a DIFFERENT credential model. Those objects are seeded
+     * `Status = 'Disabled'` so they normally never reach a sync at all; this gate is what happens if an
+     * operator activates one anyway. Without it the XML body fails to parse as JSON, `NormalizeResponse`
+     * yields `[]`, and the run reports zero rows and GREEN — the silent-empty this framework exists to
+     * prevent. The refusal names the declared format and the credential model so the fix is obvious.
+     */
+    private WireFormatGate;
+    /**
+     * The DECLARED incremental window for one read, or undefined for a full pull. Everything is
+     * metadata: the parameter name comes from the object's own `Configuration.watermark.startParam`,
+     * and the VALUE is the watermark the engine handed back — which this connector originally took
+     * from the record's OWN `IncrementalWatermarkField` (see {@link WithMaxSeenWatermark}), so it is
+     * already in the vendor's own serialization and no format is invented on the wire.
+     *
+     * `endParam` is deliberately NOT sent even where declared: an upper bound would silently drop any
+     * record the vendor writes between the request being built and being served. No `startParam` in
+     * metadata ⇒ no window — this vendor's per-object `watermarkProvenNegative` records that the five
+     * in-scope families document no server-side modified-since filter at all, and an invented one
+     * either returns nothing or is ignored.
+     */
+    private WindowParamsFor;
+    /**
+     * Advances the watermark to the MAX value SEEN in this batch, and only for an object whose metadata
+     * declares one (`SupportsIncrementalSync` + `IncrementalWatermarkField`). Never advances past a
+     * value already recorded, and never invents a watermark for a full-pull object — the five in-scope
+     * families are all `FullPullHashDiff`, where the engine's content-hash idempotency does the work.
+     */
+    private WithMaxSeenWatermark;
+    /** Chronological when BOTH values parse as dates, lexicographic otherwise. Never coerces one side. */
+    private CompareWatermark;
+    /**
+     * Walks a declared nesting path: fire the DOOR operation, then descend into the declared container
+     * key on each door record and emit the leaf rows. Everything that varies — the door's Method value,
+     * the container key, the parent key field to tag the leaf with — comes from the object's own
+     * `Configuration.accessPath` / `nestedContainerKey` / `parentObjectIDFieldName`; nothing is guessed.
+     *
+     * Returns ONE batch with `HasMore: false`. Every depth>=1 object declares
+     * `SupportsPagination = false`, so the door is a single unpaged call: splitting the leaves across
+     * batches would force a full re-read of the door per batch for no benefit.
+     */
+    private FetchNestedViaDoor;
+    /**
+     * The honest refusal for an object whose ONLY read door needs a caller-supplied record key.
+     * `Configuration.requiresRecordKeyToRead` states it verbatim: "A full sync cannot enumerate this
+     * object unaided". The vendor documents no parameter name for that key on the read side, so this
+     * returns an empty batch with a loud, structured warning rather than firing a call that is
+     * guaranteed to fail — or, worse, inventing a query parameter.
+     */
+    private RecordKeyGate;
+    /**
+     * Resolves the per-connection credential. Cadmium's APIKey is a single static per-client string
+     * with no authorize/token endpoint, no scopes and no documented expiry, so there is nothing to
+     * refresh and the resolved context is cached per CompanyIntegration. `eID` is the per-CONNECTION
+     * (TENANT) event scope — `Configuration.AuthMultiTenantParam` is explicit that it is "never baked
+     * into connector code" — and is optional, used only when the key is provisioned for multi-event
+     * access. The credential is read through the standard `MJ: Credentials` record when the connection
+     * carries one, with the connection's own `Configuration` JSON as the fallback. No inline crypto.
+     */
+    protected Authenticate(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<EventscribeAuthContext>;
+    /**
+     * Transport headers ONLY — deliberately NOTHING auth-related. `Configuration.AuthHeaderPattern` is
+     * null and `AuthCredentialParamLocation` is 'query': the API key travels in the query string, and a
+     * Bearer/Basic header on this vendor is simply wrong. The credential is injected in
+     * {@link SendRequest}, which is the one place it ever touches the wire.
+     */
+    protected BuildHeaders(_auth: RESTAuthContext): Record<string, string>;
+    /**
+     * The wire choke point used by every read and every single-record write. On top of
+     * {@link SendRequest} (credential injection, vendor pacing, the documented 404+`[]` empty case) it
+     * adds ONE rule: a 2xx response whose body carries the vendor's `{"error": ...}` envelope is a
+     * FAILURE, not an empty read. `Configuration.ErrorContract` documents that envelope as applying
+     * "across API methods"; a body-blind success check would sync zero rows and report green.
+     *
+     * On a READ it adds the SAME status gate the connector's other two read call sites already apply
+     * ({@link FetchNestedViaDoor}, {@link GetRecord}): a non-2xx never reaches record assembly, and it
+     * surfaces as the connector's own classified {@link EventscribeAPIError} rather than an unclassified
+     * failure — a 5xx must reach the engine as `Retryable: true`, a 401/403 as a non-retryable
+     * configuration error. The flat/paginated read the base class drives was the one transport path
+     * with no such gate, so its errors carried no `Code`/`Severity`/`Retryable` verdict at all.
+     *
+     * OUTSIDE a read, NON-2xx responses are returned, not thrown, so the base class's generic CRUD can
+     * build a proper `CRUDResult`, `GetRecord` keeps its documented 404 ⇒ null, and `TestConnection`
+     * can report the status it observed. The batch path calls {@link SendRequest} directly because for
+     * `addUpdateAccount` an HTTP 400 can accompany partially-succeeded records and must be INSPECTED
+     * rather than treated as total failure.
+     */
+    protected MakeHTTPRequest(auth: RESTAuthContext, url: string, method: string, headers: Record<string, string>, body?: unknown): Promise<RESTResponse>;
+    /**
+     * Credential injection + vendor pacing + the documented empty-result special case. Returns the
+     * response verbatim for every status; classification is the caller's decision.
+     *
+     * `Configuration.ErrorContract.specialCases` is explicit for the asset family: HTTP 404 with a body
+     * of `[]` means "no presentations or posters were found" — an EMPTY RESULT, never a connector
+     * failure. It is normalised to a 200 here so both the base read path (which validates on status)
+     * and this connector's own paths see an empty success.
+     */
+    protected SendRequest(auth: RESTAuthContext, url: string, method: string, headers: Record<string, string>, body?: unknown): Promise<RESTResponse>;
+    /** Raw transport. Isolated so tests can substitute it without touching any connector behaviour. */
+    protected rawRequest(url: string, method: string, headers: Record<string, string>, body?: unknown): Promise<RESTResponse>;
+    /**
+     * Strips the vendor envelope. A BARE JSON ARRAY is the common shape across this vendor (Asset,
+     * Expo, Education Harvester); `ResponseDataKey` is applied ONLY where the object's metadata
+     * declares one (the abstract-scorecard family's `{ metadata: {...}, results: [...] }`). A single
+     * record object is a one-element result — several doors (`getAccount`, `getSingle*`) answer with
+     * one object, not an array — but an error envelope is never mistaken for a record.
+     */
+    protected NormalizeResponse(rawBody: unknown, responseDataKey: string | null): Record<string, unknown>[];
+    /**
+     * PageNumber only, and only from the object's OWN declared envelope
+     * (`Configuration.pagination.envelope` = `{ container: 'metadata', totalRecordsKey: 'totalRecords',
+     * totalPagesKey: 'pages', currentPageKey: 'page' }`). An object whose metadata declares
+     * `SupportsPagination = false` never reaches here — the base short-circuits it — and when the
+     * envelope is not declared this returns `HasMore: false` rather than inventing a counter name.
+     * Inventing one either truncates the sync or loops it forever.
+     */
+    protected ExtractPaginationInfo(rawBody: unknown, paginationType: PaginationType, currentPage: number, _currentOffset: number, pageSize: number, obj?: MJIntegrationObjectEntity): PaginationState;
+    /**
+     * Emits ONLY the page parameter the object's metadata proves
+     * (`Configuration.pagination.paramName`). The base class's default would append `page=` AND
+     * `pageSize=`; Cadmium's vendor table documents the page-number parameter and NO page-size
+     * parameter at all, so sending one would be an invented name on the wire.
+     */
+    protected BuildPaginatedURL(basePath: string, obj: MJIntegrationObjectEntity, page: number, _offset: number, _cursor?: string, _effectivePageSize?: number): string;
+    /**
+     * PER-OBJECT, multi-host. Resolution order, all of it metadata:
+     *   1. the object's own `Configuration.baseUrl`, when a build ever declares one;
+     *   2. `Integration.Configuration.BaseURLsByFamily` keyed by the object's `Configuration.family`
+     *      (falling back to `IntegrationObject.Category`, which carries the same family tag);
+     *   3. the object's `Configuration.absoluteEndpoint` with its own declared `APIPath` suffix
+     *      removed — the last resort that still rescues a family with no table entry.
+     *
+     * 'asset' and 'eventscribe-web' both key this table and both must stay: they resolve to the same
+     * host TODAY, which is data, not a licence to collapse the tags in code. There is no default and
+     * no baked host — a family with no resolvable base URL raises, it does not silently pick one.
+     */
+    protected GetBaseURL(companyIntegration: MJCompanyIntegrationEntity, _auth: RESTAuthContext, objectName?: string): string;
+    /** `BaseURL` off a connection's Configuration JSON, when present and non-empty. */
+    private SingleOriginOverride;
+    /** The per-object base URL resolution described on {@link GetBaseURL}. */
+    private BaseURLForObject;
+    /** Scope-only wrapper; the create itself is the base class's metadata-driven generic dispatch. */
+    CreateRecord(ctx: CreateRecordContext): Promise<CRUDResult>;
+    /** Scope-only wrapper; the update itself is the base class's metadata-driven generic dispatch. */
+    UpdateRecord(ctx: UpdateRecordContext): Promise<CRUDResult>;
+    /**
+     * Scope-only wrapper around the base class's metadata-driven generic dispatch, PLUS one refusal:
+     * a delete whose declared request carries NO record identifier never goes on the wire. See
+     * {@link UnidentifiedDeleteGuard} — this is a safety gate, not a re-implementation.
+     */
+    DeleteRecord(ctx: DeleteRecordContext): Promise<CRUDResult>;
+    /**
+     * Refuses a DESTRUCTIVE request that cannot name the record it is destroying.
+     *
+     * The base's generic delete substitutes the external id into the path ONLY when
+     * `DeleteIDLocation = 'path'` and the path carries an `{ID}` placeholder, and it sends NO body at
+     * all. Some of this vendor's delete-adjacent operations declare `DeleteIDLocation = 'n/a'` with
+     * `deleteOperation.idParam = null` because — per the frozen contract's own gap list — "the op
+     * documents no ID parameter at all in its parameters array". Firing that path verbatim would put
+     * an UNIDENTIFIED delete on a live event with nothing but the API key, the event scope and the
+     * Method name. Best case it 400s; worst case the vendor interprets it broadly. Neither is a risk
+     * worth taking to make a capability flag look satisfied.
+     *
+     * So this returns a FAILED CRUDResult naming the exact missing fact, rather than either (a) firing
+     * blind or (b) inventing a query-parameter name the vendor never documented — which would be the
+     * connector silently working around a metadata gap. Objects whose delete DOES carry an identifier
+     * (`...&AccountID={ID}` with `DeleteIDLocation = 'path'`) are untouched and ride the generic path.
+     */
+    private UnidentifiedDeleteGuard;
+    /**
+     * THE SECOND GENUINELY IDIOSYNCRATIC PATH. This is the one read the base class cannot express on an
+     * RPC-over-querystring API: its generic `GetRecord` reuses `UpdateAPIPath` as the get-one path
+     * ("typically the same as the get-one path" — true of resource-oriented REST, where `/accounts/{id}`
+     * is both). Here `UpdateAPIPath` is `...?Method=addUpdateAccount&AccountID={ID}`, so the generic path
+     * would send a GET whose `Method` names a WRITE operation. `Configuration.ReadContract` is explicit
+     * that "the Method query param IS the routing/dispatch mechanism" — the verb does not disambiguate
+     * it — so that request is an upsert dispatched with no body, aimed at a live event. Refusing to build
+     * it is the same judgement as {@link UnidentifiedDeleteGuard}.
+     *
+     * Instead the read goes through the object's DECLARED READ DOOR ({@link DoorOperationFor}) with the
+     * record key on the query string under its DECLARED parameter name ({@link RecordKeyParamFor}).
+     * Everything is metadata; nothing is inferred from the verb or invented from a naming convention.
+     * A throw here is safe and preferred over a wrong request: the engine's only caller treats a failed
+     * re-read as "proceed with the full attribute set", so a refusal degrades to prior behaviour.
+     */
+    GetRecord(ctx: GetRecordContext): Promise<ExternalRecord | null>;
+    /**
+     * The query-parameter name that names ONE record on a read, in metadata order: the operation's own
+     * declared `idParam` first, then the object's single declared primary key. A COMPOSITE key returns
+     * null — this vendor documents no multi-key single-record door, and splitting one across invented
+     * parameter names would be a fabrication. So does an object with no declared key at all: the frozen
+     * contract withdrew seven weakly-evidenced keys, and its no-identity path forbids substituting a guess.
+     */
+    private RecordKeyParamFor;
+    /**
+     * Wraps the generic flat body in a ONE-ELEMENT ARRAY for the operations whose metadata declares the
+     * array-body convention. `Configuration.BatchSemantics` is explicit: "JSON array in the raw POST
+     * body (single-object writes still require wrapping in a one-element array)". Sending the bare
+     * object instead is a malformed request for those operations. Everything else keeps the base
+     * class's shape untouched — the decision is per-operation and read from metadata (see
+     * {@link UsesArrayBody}), never a list of vendor operation names written into this file.
+     */
+    protected BuildOperationBody(attributes: Record<string, unknown>, bodyShape: string | null, bodyKey: string | null): unknown;
+    /**
+     * Reads the new record's id from the vendor's response. The base helper only knows the generic
+     * `id`/`ID` names; Cadmium returns the record's OWN key (Booth's `createIDBasis`: "the operation's
+     * own sample response contains the record key 'BoothID'"), and for an array-body write the response
+     * is an ARRAY of per-record results. Candidate names come from the object's declared
+     * `writeOperation.idParam` and then its declared primary-key columns — from metadata, in order.
+     * `IDLocation = 'n/a'` means the vendor documents NO id in the response; that returns undefined
+     * rather than reaching for a field that was never promised.
+     */
+    protected ExtractIDFromResponse(response: RESTResponse, idLocation: string | null): string | undefined;
+    /** Reads the vendor's own message out of the documented `{"error": ...}` envelope. */
+    protected ExtractErrorMessage(response: RESTResponse): string | undefined;
+    /**
+     * THE ONE GENUINELY IDIOSYNCRATIC WRITE PATH. `Configuration.BatchSemantics.addUpdateAccount`:
+     * "non-atomic -- each record in the array is processed INDEPENDENTLY ... If ANY record in the batch
+     * fails, the overall HTTP response status is 400 -- but valid records in the SAME request are still
+     * created/updated. Callers must inspect the individual per-record results in the response body".
+     *
+     * So this sends ONE request carrying the whole array and then reads the PER-RECORD results out of
+     * the body — a 400 is not treated as total failure. When the per-record results cannot be located
+     * positionally, it degrades CONSERVATIVELY: a 2xx reports success, a non-2xx reports failure for
+     * every record with the vendor's message, and no record is ever claimed successful on a guess
+     * (the `addUpdate*` operations are upserts, so a conservative re-push is idempotent).
+     */
+    BatchCreateRecords(ctxs: CreateRecordContext[]): Promise<CRUDResult[]>;
+    /**
+     * Same array-body batch, for the `addUpdate*` upserts on the update side — but ONLY when the
+     * object's declared `UpdateAPIPath` carries no `{ID}` placeholder. Every current object declares
+     * one (`...&AccountID={ID}`), which is the SINGLE-record URL shape, and stripping it to force a
+     * batch would be inventing a request. Those fall back to the per-record path: correctness first,
+     * throughput second.
+     */
+    BatchUpdateRecords(ctxs: UpdateRecordContext[]): Promise<CRUDResult[]>;
+    /** Groups by object, batches the eligible groups, and routes the rest through the single-record path. */
+    private RunArrayBodyBatch;
+    /**
+     * Reads the per-record results out of a non-atomic array-body response. The vendor documents that
+     * they exist and must be inspected, but never prints their exact schema, so this locates them
+     * POSITIONALLY: the response array (or the first array-valued property of the response object)
+     * whose length matches the request array. Each item fails when it carries the documented error
+     * envelope; otherwise it succeeded — even under an overall HTTP 400, which is precisely the
+     * partial-success case. No positional array ⇒ the conservative all-or-nothing verdict.
+     */
+    private ReadPerRecordOutcomes;
+    /** The response array whose length matches the request array, at the root or one level down. */
+    private LocatePositionalResults;
+    /**
+     * Whether the object's write/delete operation takes a JSON ARRAY body, decided ENTIRELY from
+     * metadata: a structural `requestShape` on the operation, a structural
+     * `Integration.Configuration.BatchSemantics[<operationId>]` entry, or the vendor's own
+     * cross-operation convention statement — which is matched against the operation id the OBJECT's
+     * metadata supplies, so no vendor operation name is ever written into this file.
+     */
+    private UsesArrayBody;
+    /** Candidate id field names for the CURRENT scope's object, in metadata order. Never a guessed name. */
+    private WriteIDFieldNames;
+    /**
+     * Honours the vendor's documented spacing before every request. The window comes from metadata —
+     * `Integration.Configuration.RateLimits.standard` for the vendor-wide allowance, its `overrides`
+     * (and any object whose own `Configuration.rateLimit` is scoped `object-override`) for the two
+     * documented heavy methods that require 60 s between calls. Keyed by `host|MethodValue`, because
+     * on this RPC API a "method" is the operation, not the URL path. No window in metadata ⇒ no pacing
+     * invented here; the engine's own adaptive limiter still applies.
+     *
+     * SCOPED TO THE HOSTS THE METADATA DECLARES ({@link VendorHosts}). The documented allowance is a
+     * property of Cadmium's OWN service, identified in metadata by host. When a connection is pointed
+     * somewhere else — an operator's gateway, a staging or replay endpoint — this connector holds NO
+     * documented allowance for that host, and imposing a 60-second sleep on a service whose real policy
+     * is unknown is an invented number, not a safe default. Those requests are governed by the engine's
+     * adaptive limiter and its 429 handling instead. Declares no host at all ⇒ everything is paced.
+     */
+    private PaceRequest;
+    /** The documented spacing for one operation: per-method override first, vendor-wide standard second. */
+    private RateWindowFor;
+    /** A per-object `Configuration.rateLimit` explicitly scoped `object-override`, matched by Method value. */
+    private ObjectRateOverrideFor;
+    /**
+     * The hosts the METADATA declares for this vendor: every `BaseURLsByFamily` entry plus every
+     * object's own `Configuration.absoluteEndpoint` (which is what carries the out-of-scope families
+     * whose hosts the family table deliberately omits). This is the set the vendor's documented
+     * rate-limit applies to — see {@link PaceRequest}. Never a literal: an empty set means the
+     * metadata named no host, and the conservative "pace everything" branch takes over.
+     */
+    private VendorHosts;
+    /** Sleeps. Isolated so tests can assert the pacing decision without waiting for it. */
+    protected Sleep(ms: number): Promise<void>;
+    /**
+     * Adds the credential query parameters. Their NAMES come from
+     * `Integration.Configuration.AuthCredentialParamName` ("APIKey") and
+     * `Configuration.AuthMultiTenantParam.name` ("eID"); if the metadata does not name the credential
+     * parameter, this raises rather than guessing a name onto the wire. `eID` is added only when the
+     * connection actually carries an event id, and an existing value in the URL is never overwritten.
+     */
+    private WithCredentialParams;
+    /**
+     * Appends the DECLARED incremental-window parameters resolved by {@link WindowParamsFor} for the
+     * read currently in scope. Absent scope, or an object with no declared window, is a no-op — so a
+     * full-pull object's URL is byte-identical to what it was before. An existing value on the URL is
+     * never overwritten.
+     */
+    private WithWindowParams;
+    /**
+     * `<familyBase><APIPath>?<MethodParam>=<operation>` for one object's door.
+     *
+     * The base URL is resolved through {@link GetBaseURL} — NOT by calling {@link BaseURLForObject}
+     * directly — so that EVERY request this connector makes goes through the ONE resolution seam.
+     * `GetBaseURL` is the documented per-connection override point (an operator pointing a connection
+     * at a gateway, a harness redirecting the origin); a path that reaches around it would obey the
+     * declared vendor host while the rest of the connector obeyed the override, which is exactly the
+     * kind of split-brain routing that sends half a sync to the wrong origin.
+     */
+    private DoorURL;
+    /** The dispatch parameter name: the object's own declaration first, the integration contract second. */
+    private MethodParamName;
+    /** The Method value carried on a built URL, used only to key the vendor's per-method pacing. */
+    private MethodValueFromURL;
+    /**
+     * The operation that RETURNS this object's records. For a nested object that is the DOOR
+     * (`accessPath.doorOperation`); for a directly-queryable object it is its own read method. The
+     * declared access path wins over `dispatch.methodValue`, because the access path is the statement
+     * about where the records actually come from.
+     */
+    private DoorOperationFor;
+    /** How deep this object sits under its door. 0 = directly queryable. */
+    private DepthOf;
+    /**
+     * The response key carrying a nested object's rows: the explicit `nestedContainerKey`, else the
+     * last segment of the declared `accessPath.nestingFieldPath` (`"Exhibitor → Booths[]"` → `Booths`).
+     * Both are metadata; nothing is inferred from the payload.
+     */
+    private NestedContainerKeyFor;
+    /** Parsed `Configuration` JSON for one IntegrationObject; malformed degrades to absent. */
+    private ObjectConfig;
+    /** Parsed `Integration.Configuration` — the connector-wide vendor facts. */
+    private IntegrationConfig;
+    /** The raw `Integration.Configuration` string. Isolated so tests can supply it without the engine. */
+    protected IntegrationConfigurationJSON(): string | null;
+    /** The object the current async call chain is serving, when one is in scope. */
+    private ScopedObject;
+    /** The cached IntegrationObject by name, or null. Routes through the same seam every read path uses. */
+    private TryGetCachedObject;
+    /** ACTIVE objects for this integration; absent metadata degrades to an empty list, never a throw. */
+    protected getCachedObjects(integrationID: string): MJIntegrationObjectEntity[];
+    /** This integration's ID by its verbatim name, or null when metadata is not loaded. */
+    protected tryGetIntegrationID(): string | null;
+    /** The per-call scope a generic CRUD verb runs inside. */
+    private ScopeFor;
+    /**
+     * Builds an `ExternalRecord` whose `Fields` is the COMPLETE source row — never a projection — so
+     * the framework's custom-column capture can still see a per-tenant column this build never
+     * declared. Composite keys join with `|`. When a declared key value is missing (several of this
+     * vendor's nested leaves have only a WEAK, shape-derived key) the identity falls back to a content
+     * hash: a soft key must never be able to REJECT a valid row.
+     */
+    private ToEventscribeRecord;
+    /**
+     * The DECLARED primary-key names in Sequence order — and NOTHING else. Deliberately does NOT use
+     * the base class's synthetic `['ID']` fallback: the frozen contract WITHDREW seven weakly-evidenced
+     * keys (they survive as ordinary nullable columns, and the `StableOrderingKey` columns that pointed
+     * at them were nulled to match), and its no-identity path is explicit that a PK-less object must
+     * make NO idempotent-identity claim and must NOT substitute a guessed alternative. Returning `['ID']`
+     * here would be exactly that guess — and would silently start claiming identity the day a tenant's
+     * payload happens to carry a column literally named `ID`. An empty list routes the object to the
+     * content-hash identity in {@link ToEventscribeRecord}, i.e. the append/full-refresh path the
+     * contract prescribes, where the engine's own hash idempotency does the deduplication.
+     */
+    private PrimaryKeyNames;
+    /** Credential record first, connection Configuration second. No inline crypto; nothing is logged. */
+    private LoadCredentials;
+    /** Extracts the two credential values from a credential / Configuration JSON string. */
+    private ParseCredentialJSON;
+    /**
+     * Classifies from the vendor's own envelope AND the status. `Configuration.ErrorContract` documents
+     * `{"error": "<human-readable message>"}` with 400 and 404 observed, and states it applies "across
+     * API methods" — so a 2xx carrying that envelope is a FAILURE, which is exactly how a sync would
+     * otherwise report zero rows and green at the same time. The one documented exception (404 with a
+     * body of `[]`) is normalised to an empty success in {@link SendRequest} and never reaches here.
+     */
+    private ErrorFor;
+    /** The status/envelope → structured verdict mapping, exposed so tests can assert it directly. */
+    ClassifyEventscribeResponse(status: number, vendorMessage: string | undefined): EventscribeErrorClassification;
+    /** The vendor's message from the documented envelope, or undefined when the body carries no error. */
+    private VendorMessage;
+    /** Walks a dotted path into a parsed body. Returns undefined at the first missing segment. */
+    private ReadPath;
+    /** Joins a base URL with an API path exactly as declared — no path is invented or normalised away. */
+    private JoinURL;
+    private TrimTrailingSlash;
+    /** Lowercased query-parameter keys already present on a URL. */
+    private QueryKeys;
+    /** Host of a URL, for pacing keys. Falls back to the raw string when it is not parseable. */
+    private HostOf;
+    /** Path-only view of a URL, for messages that must never carry a query string or a credential. */
+    private PathOf;
+    /** A narrowing cast to a plain object, or null. */
+    private AsObject;
+    /** First non-empty string value among `keys` on a parsed object. */
+    private FirstString;
+    /** A finite number from an arbitrary JSON value, or null. Vendor counters arrive as either type. */
+    private FiniteNumber;
+    /** Tolerant JSON-object parse; malformed configuration degrades to "absent" rather than crashing. */
+    private ParseJSONObject;
+    /** An error message safe to log: never carries credential bytes. */
+    private SafeMessage;
+    /** Emits a warning at most once per connector lifetime, so the log stays honest rather than noisy. */
+    private WarnOnce;
+}
+/** Forces the module (and its `@RegisterClass` side effect) to be retained by a bundler. */
+export declare function LoadEventscribeConnector(): void;