@memberjunction/connector-wordpress 1.0.0

package/dist/WordPressConnector.d.ts

@@ -0,0 +1,499 @@
+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 ExternalObjectSchema, type ExternalFieldSchema, type FetchContext, type FetchBatchResult, type SourceSchemaInfo, type SyncErrorCode, type ErrorSeverity, type DeleteRecordContext, type CRUDResult } from '@memberjunction/integration-engine';
+/** A classified WordPress failure — derived from the error ENVELOPE, not from the status alone. */
+export interface WordPressErrorClassification {
+    /** Engine-level sync error code (the `SyncErrorCode` union the run artifact reports). */
+    Code: SyncErrorCode;
+    /** Engine-level severity. */
+    Severity: ErrorSeverity;
+    /** The vendor's stable machine code (`rest_no_route`, `woocommerce_rest_authentication_error`, …), when present. */
+    VendorCode: string | null;
+    /** Whether the engine should retry (429/503/transport), per `IsRetryableError` semantics. */
+    Retryable: boolean;
+    /** Short machine-ish reason naming WHY this classification was chosen. */
+    Reason: string;
+}
+/**
+ * WordPress connector — extends BaseRESTIntegrationConnector (REST/JSON over HTTP).
+ *
+ * Serves BOTH in-scope namespaces (`wp/v2` core and `wc/v3` WooCommerce) off ONE self-hosted site root.
+ * Pagination, template-var (per-parent) read traversal and the generic metadata-driven CRUD are
+ * inherited; this class supplies the WordPress-specific protocol surface plus the §7/§10 sync-efficiency
+ * hooks the frozen contract actually evidences.
+ */
+export declare class WordPressConnector extends BaseRESTIntegrationConnector {
+    /** Resolved auth per CompanyIntegration.ID — Application Passwords and Woo keys never expire. */
+    private authCache;
+    /** Route index per API root, fetched once per connector lifetime (656 routes on a stock install). */
+    private routeIndexCache;
+    /** Response headers keyed by the PARSED BODY OBJECT — the race-free way to get `X-WP-TotalPages`
+     *  into `ExtractPaginationInfo`, whose signature only receives the body. Weak so nothing is retained. */
+    private headersByBody;
+    /** Route paths that answered 401/403 to `context=edit` and have been degraded to `context=view`. */
+    private contextDegraded;
+    /** Per-object query params for the ACTIVE fetch, consumed by AppendDefaultQueryParams. Keyed by object name. */
+    private activeFetchParams;
+    /** Objects whose capability warnings have already been logged (keep the log honest, not noisy). */
+    private warnedOnce;
+    /** Last non-2xx READ outcome per route path. The base's paginated loop SWALLOWS a 403 into an empty
+     *  result; without this the connector could not tell "forbidden" from "genuinely no records". */
+    private lastReadFailureByPath;
+    /** Verbatim `MJ: Integrations.Name`. Load-bearing: T1 compares this === the metadata Name. */
+    get IntegrationName(): string;
+    get SupportsCreate(): boolean;
+    get SupportsUpdate(): boolean;
+    get SupportsDelete(): boolean;
+    /**
+     * FALSE, and deliberately so — the two levels of authority differ and one boolean cannot express both.
+     * OBJECT level: the route index enumerates every route the site REGISTERED for that request, but a
+     * namespace can be absent because of a feature flag (`wc/v4` needs `rest-api-v4`) or WooCommerce's
+     * per-request lazy-load filter, so absence does not mean the vendor dropped it. FIELD level: schema
+     * visibility is capability-gated (`context=edit` + the matching capability), so an under-privileged
+     * credential legitimately receives a THINNER schema. Deactivating on either would wipe real metadata.
+     */
+    get DiscoveryIsAuthoritative(): boolean;
+    /**
+     * NULL on purpose. Neither `wp/v2` nor `wc/v3` documents ANY rate limit — WordPress core imposes none
+     * and the WooCommerce v3 docs have no rate-limit section (`Configuration.RateLimitPolicy.vendorDocumented
+     * = false`, and the metadata records that no number may be emitted). Real limits are HOST/CDN-imposed and
+     * per-tenant. Publishing a `TokensPerSec` here would fabricate a vendor commitment that does not exist;
+     * the engine derives a conservative rate instead and `ExtractRetryAfterMs` + `MaxConcurrencyHint` below
+     * carry the obligations that ARE real.
+     */
+    get RateLimitPolicy(): null;
+    /**
+     * Deliberately LOW. The thing being loaded is the TENANT'S OWN WEBSITE — the same PHP workers that serve
+     * their visitors — and deep offset paging is O(offset) in their database. Two in flight is the
+     * conservative default the metadata's `connectorObligation` calls for.
+     */
+    get MaxConcurrencyHint(): number;
+    /**
+     * Honours `429` + `Retry-After` (and `503`) ADAPTIVELY: parses both the delta-seconds and the HTTP-date
+     * forms of the header off the error the transport threw, so the engine's AIMD bucket backs off by the
+     * host's actual instruction rather than a guess.
+     */
+    ExtractRetryAfterMs(error: unknown): number | undefined;
+    /**
+     * Keyset resume for the objects with NO usable server-side watermark — read from the IO metadata's
+     * `StableOrderingKey` (`id` for most collections, `slug`/`code`/`name`/`instance_id` where that is the
+     * declared key), never guessed. Null when the object declares no stable key.
+     *
+     * DELIBERATELY NULL for every object that DOES declare a usable server-side date filter. That is the
+     * ENGINE'S OWN CONTRACT, not a preference: `IntegrationEngine`'s §8a keyset block treats "has a
+     * StableOrderingKey" and "uses a timestamp watermark" as MUTUALLY EXCLUSIVE — `isKeysetConnector`
+     * forces `initialWatermark = null` on every run, and a clean scan then CLEARS the keyset marker instead
+     * of saving a timestamp (its own comment: a connector whose object has a usable server-side date
+     * incremental MUST NOT declare a StableOrderingKey for that object). Declaring a key for a
+     * watermark-capable object therefore (a) never hands `FetchContext.WatermarkValue` back to the
+     * connector, so the `modified_after` filter is built but never issued, and (b) never persists a
+     * watermark at all — a DEAD incremental that silently full-re-lists forever. Which of the two applies
+     * is a PER-OBJECT metadata fact, so it is READ from metadata here rather than declaring both and
+     * getting neither.
+     *
+     * The metadata `StableOrderingKey` COLUMN is untouched and still drives the `orderby=id&order=asc`
+     * stable sort in {@link buildObjectQueryParams}; only the engine-facing keyset signal is withheld.
+     */
+    StableOrderingKey(objectName: string): string | null;
+    /**
+     * Whether this object has a LIVE server-side incremental filter — all three metadata facts present:
+     * the `SupportsIncrementalSync` flag, the `IncrementalWatermarkField` the max-seen is read from, and a
+     * `Configuration.incrementalWatermark.filterParam` to actually put on the wire. Anything less is a
+     * DECORATIVE watermark and the object is treated as full-scan-only.
+     *
+     * FALSE, correctly, for `wp/v2/users` and `wc/v3/customers` (their controllers inherit no date params
+     * at all) and for the six objects that register `modified_after` but expose no modified column
+     * (MenuItem, GlobalStyle, FontFamily, FontFamilyFontFace, OrderRefund, Refund) — every one of which
+     * carries a null `incrementalWatermark` plus an `incrementalNote` in the metadata.
+     */
+    private hasLiveIncrementalWatermark;
+    /**
+     * DYNAMIC discovery. The Declared metadata is the stock-install FLOOR — never the ceiling — so this
+     * reads the CONNECTION's OWN route index (`GET <apiRoot>`) and UNIONS the per-site remainder on top:
+     * custom post types, custom taxonomies and third-party plugin namespaces, all of which flow through the
+     * same core controllers with a different `rest_base` and are therefore invisible to any pinned source.
+     *
+     * A route becomes a candidate object when it is a GET collection route (no path capture in its own last
+     * segment) that registers `per_page` — i.e. a LISTABLE collection, the discriminator that separates a
+     * record set from the RPC routes (`/wp/v2/block-renderer/…`, `/oembed/1.0/proxy`).
+     *
+     * Namespaces the OPERATOR scoped out are skipped by READING the metadata's own structured
+     * `Configuration.OutOfScopeObjectFamilies[].kind` — first-party RPC/admin/legacy/transport surfaces are
+     * not record collections. Third-party plugin namespaces are NOT skipped: the metadata's own reason text
+     * says they are "reachable at runtime via route-index discovery", which is exactly this path.
+     *
+     * A discovery failure NEVER removes the declared floor — the union degrades to the floor with a warning.
+     */
+    DiscoverObjects(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<ExternalObjectSchema[]>;
+    /**
+     * Field discovery via `OPTIONS <route>` — WordPress's self-describing endpoint schema. The result is
+     * UNIONED over the Declared field set and NEVER shrinks it: field visibility is capability-gated, so an
+     * under-privileged credential legitimately sees a thinner schema and its ABSENCES prove nothing.
+     *
+     * A templated collection path (`/wc/v3/orders/{order_id}/notes`) has no literal URL to OPTIONS without a
+     * real parent id, so those objects return their declared fields unchanged rather than a fabricated set.
+     */
+    DiscoverFields(companyIntegration: MJCompanyIntegrationEntity, objectName: string, contextUser: UserInfo): Promise<ExternalFieldSchema[]>;
+    /**
+     * Union introspection — the layer where the per-site truth actually lands in the schema:
+     *   1. `super.IntrospectSchema` returns the persisted DECLARED objects (the stock-install floor).
+     *   2. Objects the ROUTE INDEX exposes but the floor never declared are APPENDED (per-site customs).
+     *   3. Every object's field set is UNIONED with the live `OPTIONS` schema and with a live record SAMPLE
+     *      (`DiscoverFieldsViaFetch` → `mergeDeclaredWithSampledFields`, never-shrink / declared-wins /
+     *      capacities widened), so a tenant's registered `meta` keys and plugin-added properties reach the
+     *      schema instead of being silently dropped at field-mapping time.
+     * Every step is best-effort and additive — a failure leaves the declared set exactly as it was.
+     */
+    IntrospectSchema(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<SourceSchemaInfo>;
+    /**
+     * OVERRIDDEN for four things the generic path cannot express, then delegated:
+     *   1. DUAL-NAMESPACE CREDENTIAL GUARD — a Woo-only consumer key/secret cannot read `wp/v2` at ALL
+     *      (`WC_REST_Authentication::is_request_to_rest_api()` matches only `wc/`/`wc-` URIs), so those
+     *      objects surface an explicit capability warning instead of an empty-but-green sync.
+     *   2. PER-OBJECT QUERY PARAMS — the stable sort and the metadata-declared incremental filter, staged
+     *      for `AppendDefaultQueryParams` (which the base calls for every page of every request).
+     *   3. WATERMARK — max-seen over the object's declared `IncrementalWatermarkField`, persisted ONLY on a
+     *      fully-drained pass so a partial batch never advances it.
+     *   4. GRACEFUL DEGRADES — an unregistered route (a gated Woo feature such as order fulfillments) and a
+     *      capability-forbidden collection become a WARNED zero-record result, not a failed sync.
+     *
+     * `ctx.RequestedSourceFields` is deliberately IGNORED: WordPress's `_fields` param would truncate the
+     * record to whatever the connector thought to ask for, which is exactly what breaks the framework's
+     * custom/overflow capture of per-site `meta` and plugin-added properties.
+     */
+    FetchChanges(ctx: FetchContext): Promise<FetchBatchResult>;
+    /**
+     * Resolves the per-connection credential AND the DERIVED REST API root. Cached per CompanyIntegration —
+     * Application Passwords and Woo consumer keys are long-lived with no refresh endpoint, so there is
+     * nothing to renew. A credential-free connection is LEGAL and does not throw: WordPress's route index
+     * and `OPTIONS` are public, which is what lets discovery work without a secret.
+     */
+    protected Authenticate(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<RESTAuthContext>;
+    /** Static request headers plus the resolved Basic credential (absent on a credential-free connection). */
+    protected BuildHeaders(auth: RESTAuthContext): Record<string, string>;
+    /**
+     * The single wire choke point. Beyond the raw transport it owns four WordPress-specific concerns:
+     *   1. `?rest_route=` rewriting for a site without pretty permalinks.
+     *   2. The Woo consumer key/secret QUERY-PARAM fallback on `wc/*` URLs, for hosts that strip
+     *      `Authorization` (Woo gives query params precedence over the header).
+     *   3. `context=edit` injection on reads, with a ONE-SHOT graceful degrade to `context=view` on 401/403
+     *      that LOGS the fields that will now be missing rather than downgrading silently.
+     *   4. Throwing `429`/`503` as a typed error carrying the response headers, so the engine's adaptive
+     *      limiter can honour `Retry-After` instead of seeing an opaque message.
+     */
+    protected MakeHTTPRequest(auth: RESTAuthContext, url: string, method: string, headers: Record<string, string>, body?: unknown): Promise<RESTResponse>;
+    /**
+     * Strips the WordPress collection envelope. Three declared response shapes, discriminated STRUCTURALLY
+     * from the body itself (the signature receives no object row, and the shape is unambiguous in the bytes):
+     *   - `array`         → a bare JSON array of records (73 of the declared objects).
+     *   - `object-map`    → `{ "<slug>": {…}, … }` (types, statuses, taxonomies, menu-locations) → its values.
+     *   - `single-object` → one document (settings, system status) → a one-element list.
+     * A `responseDataKey` still wins when the metadata declares one.
+     */
+    protected NormalizeResponse(rawBody: unknown, responseDataKey: string | null): Record<string, unknown>[];
+    /**
+     * WordPress pagination is OFFSET-based page numbering whose termination signal lives in the RESPONSE
+     * HEADERS, not the body — so the headers recorded against this exact body object are consulted first:
+     *   `X-WP-TotalPages` (authoritative), else the RFC-5988 `Link rel="next"`, else a short page.
+     * `X-WP-Total` is surfaced as the expected count. Completeness on a deep scan is BEST-EFFORT: page
+     * numbering is offset arithmetic, so concurrent writes shift rows across page boundaries; the
+     * `orderby=id&order=asc` stable sort reduces but does not eliminate that drift, and exactness is never claimed.
+     */
+    protected ExtractPaginationInfo(rawBody: unknown, paginationType: PaginationType, currentPage: number, _currentOffset: number, pageSize: number): PaginationState;
+    /** The DERIVED per-connection REST API root (resolved in Authenticate — never `siteUrl + '/wp-json'`). */
+    protected GetBaseURL(_companyIntegration: MJCompanyIntegrationEntity, auth: RESTAuthContext): string;
+    /**
+     * `page` + `per_page`, with `per_page` CLAMPED to the cap the object's own metadata declares
+     * (`Configuration.pagination.maxPageSize`, 100 on every in-scope collection). WordPress REJECTS a
+     * request above the cap rather than clamping it server-side, so the clamp has to happen here.
+     */
+    protected BuildPaginatedURL(basePath: string, obj: MJIntegrationObjectEntity, page: number, offset: number, cursor?: string, effectivePageSize?: number): string;
+    /**
+     * Appends the DECLARED default query params (base behaviour) and then the per-object params this fetch
+     * staged: the stable sort and the metadata-declared incremental filter. Params already present in the
+     * URL are never duplicated.
+     */
+    protected AppendDefaultQueryParams(url: string, obj: MJIntegrationObjectEntity): string;
+    /** Reads the vendor's `message` out of the `{ code, message, data:{ status } }` envelope. */
+    protected ExtractErrorMessage(response: RESTResponse): string | undefined;
+    /**
+     * OVERRIDDEN for the one genuinely idiosyncratic verb: WordPress DELETE semantics are PER-OBJECT and
+     * parameterised, which the generic path (a bare `DELETE <path>`) cannot express.
+     *   - `requiresForce` (revisions, terms, users, widgets, Woo terms/notes/webhooks…) → `?force=true`;
+     *     without it those routes reject the request outright.
+     *   - `requiresReassign` (wp/v2/users) → `&reassign=<user id>`; WordPress requires it because deleting a
+     *     user must say where their content goes. The id comes from the connection's
+     *     `Configuration.userDeleteReassignID` and is NEVER guessed — an unset value is a loud error, because
+     *     inventing one would silently reassign a customer's content to an arbitrary account.
+     *   - Everything else keeps the vendor default, which for post types is a SOFT delete to `status=trash`.
+     * All of this is READ FROM METADATA (`Configuration.deleteSemantics`), not decided here.
+     */
+    DeleteRecord(ctx: DeleteRecordContext): Promise<CRUDResult>;
+    /**
+     * Two-part test, because "reachable" and "authenticated" are different facts:
+     *   1. The site's REST root must answer with a route index (proves it IS a WordPress REST API, and that
+     *      the derived API root — Link header / `/wp-json/` / `?rest_route=/` — was resolved correctly).
+     *   2. The supplied credential must actually authenticate: `wp/v2/users/me` for an Application Password,
+     *      or a `wc/v3` read for a Woo-only key pair.
+     * A credential-free connection reports failure with an explicit message — discovery works without a
+     * secret, but a connection is not "successful" when nothing can be authorised.
+     */
+    TestConnection(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<ConnectionTestResult>;
+    /**
+     * Classifies from the ERROR ENVELOPE, not the status alone. WordPress serialises every failure across
+     * wp/v2, wc/v3 and /batch/v1 as `{ code, message, data:{ status } }`, and `code` is the stable
+     * machine-readable discriminator (`message` is localised and must never be parsed).
+     *
+     * The distinction that matters operationally: a `403` carrying a WordPress JSON envelope is the API
+     * refusing a capability (fix the credential), while a `403` carrying an HTML body never reached the API
+     * at all — it is a WAF / host / mod_security block, and retrying it is pointless. Anything unrecognised
+     * falls through to the engine's own `ClassifyError`.
+     */
+    ClassifyWordPressResponse(status: number, body: unknown): WordPressErrorClassification;
+    /** The raw HTTP call. Isolated so test subclasses can capture the wire without losing the WP behaviours above. */
+    protected rawRequest(url: string, method: string, headers: Record<string, string>, body?: unknown): Promise<RESTResponse>;
+    /** Rewrites `<site>/__mj_rest_route__/wp/v2/posts?x=1` → `<site>/?rest_route=/wp/v2/posts&x=1`. */
+    private rewriteForRestRoute;
+    /**
+     * WooCommerce accepts `?consumer_key=&consumer_secret=` and gives them PRECEDENCE over the
+     * `Authorization` header — the one hard functional advantage of the Woo key pair, for hosts that strip
+     * `Authorization`. Applied ONLY to `wc/` routes and ONLY when the connection opts in.
+     */
+    private appendWooQueryAuth;
+    /**
+     * Derives the REST API root the way WordPress itself advertises it — NEVER by concatenating
+     * `siteUrl + '/wp-json'`. The REST prefix is filterable via `rest_get_url_prefix()`, so a site can serve
+     * it from anywhere, and a site without pretty permalinks answers only at `?rest_route=/`. Order:
+     *   1. an explicit `apiRoot` on the connection (sandbox/mock redirection by DATA);
+     *   2. the `Link: <…>; rel="https://api.w.org/"` response header on the site root (HEAD, then GET);
+     *   3. the same `<link>` element in the homepage HTML;
+     *   4. `{siteUrl}/wp-json/`, verified by an actual route index;
+     *   5. `{siteUrl}/?rest_route=/`, verified the same way.
+     */
+    private deriveApiRoot;
+    /** Reads the advertised REST root out of a `Link` response header or a homepage `<link>` element. */
+    private readAdvertisedApiRoot;
+    /** Extracts the `<url>` whose `rel` is the WordPress API rel from an RFC-5988 Link header value. */
+    private matchApiLink;
+    /** A body is a route index when it carries the `routes` map (and usually `namespaces`). */
+    private looksLikeRouteIndex;
+    /** Fetches (and caches per API root) the site's own route index. `context=view` is explicit so the
+     *  `context=edit` injector leaves this public discovery call alone. */
+    private loadRouteIndex;
+    /**
+     * Derives LISTABLE COLLECTIONS from the route index. A route qualifies when it is readable, carries no
+     * path capture of its own, is not a namespace root, and registers `per_page` — the discriminator that
+     * separates a record collection from the RPC routes WordPress also registers.
+     */
+    private deriveCollectionRoutes;
+    /**
+     * Namespaces the OPERATOR scoped out of 1.0.0, read from the Integration row's own
+     * `Configuration.OutOfScopeObjectFamilies[].kind`. First-party RPC / admin / analytics / legacy /
+     * transport / alias namespaces are not record collections and stay out. `third-party-plugin` and the
+     * per-site remainder are NOT excluded — the metadata's own reasons say those are "reachable at runtime
+     * via route-index discovery", which is precisely this path.
+     */
+    private readScopedOutNamespaces;
+    /** Issues `OPTIONS <route>` and maps the endpoint's JSON Schema properties to ExternalFieldSchema. */
+    private describeRoute;
+    /**
+     * Maps ONE JSON Schema property to a field schema, provable-only throughout: `IsPrimaryKey` is set only
+     * when the property is the one the route's own ITEM path addresses records by (Tier-1 addressing-path
+     * evidence, the same class the extractor used); `AllowsNull` only when the declared type union contains
+     * `null`; `IsForeignKey` is never inferred, because WordPress publishes no machine-readable FK model.
+     */
+    private schemaPropertyToField;
+    /**
+     * UNION of declared × described, keyed by field name. Declared WINS on every attribute (it is the
+     * docs-provable maximum a fully-privileged credential sees); a described-only field is APPENDED as a
+     * per-site custom. Nothing is ever removed — a thinner runtime schema is a capability artefact.
+     */
+    private unionFieldSchemas;
+    /** The literal (untemplated) collection path to OPTIONS for an object, or null when it is parent-templated. */
+    private optionsRoutePathFor;
+    /** Name of the key an item route addresses records by, e.g. `/wp/v2/posts` → `id` via its `{id}` sibling. */
+    private itemRouteKeyName;
+    /**
+     * The per-object read parameters, every one of them READ FROM METADATA:
+     *   - STABLE SORT (`orderby=id&order=asc`) on the page-numbered collections whose declared
+     *     `StableOrderingKey` is `id`, to minimise the offset drift page arithmetic is prone to.
+     *   - The INCREMENTAL filter, and ONLY where the object declares one. The six objects that register
+     *     `modified_after` but expose no modified column, plus `wp/v2/users` and `wc/v3/customers` (whose
+     *     controllers inherit no date params at all), carry a null watermark in metadata and therefore get
+     *     NO delta path here. The connector never synthesises one, and never rounds an insert-only
+     *     high-water up to "incremental supported".
+     */
+    private buildObjectQueryParams;
+    /**
+     * Renders the stored watermark into the exact string the object's declared filter param compares
+     * against, with ROUND-TRIP FIDELITY as the first rule: the value normally came FROM this object's own
+     * watermark field, so it is already in the vendor's own representation and goes back verbatim.
+     *
+     * THE ONE CASE THAT IS NOT A ROUND TRIP: after a CLEAN FULL sync the engine deliberately replaces the
+     * connector's max-seen value with wall-clock `new Date().toISOString()` — an INSTANT, in UTC, carrying
+     * a `Z`. For a `dates_are_gmt` object that is exactly right: WooCommerce compares against the `_gmt`
+     * columns, and this connector already sends `dates_are_gmt=true` alongside. For a SITE-LOCAL object it
+     * is not: `WP_REST_Posts_Controller` date_query's `modified_after` against `post_modified`, the
+     * site-local column, so on a site behind UTC a UTC instant is LATER than the same moment's local wall
+     * clock and the next incremental would silently SKIP everything modified inside the offset window.
+     * Project it into the site's own wall clock using the `gmt_offset` the REST index publishes.
+     *
+     * When the site publishes no usable offset the value is passed through UNSHIFTED and the gap is said
+     * out loud — a guessed offset would fabricate a vendor fact, and an unshifted filter is no worse than
+     * the value the engine stored.
+     */
+    private watermarkFilterValue;
+    /**
+     * The site's UTC offset in MINUTES, read from the `gmt_offset` the public REST index advertises
+     * (hours, possibly fractional — India is 5.5, Chatham is 12.75). Null when the site does not publish
+     * one or the index is unreachable; callers must then decline to shift rather than assume UTC.
+     */
+    private siteGmtOffsetMinutes;
+    /**
+     * Normalises a stored watermark to the ISO-8601 form WordPress's date params accept — with ROUND-TRIP
+     * FIDELITY as the first rule. The watermark came FROM the object's own `modified` / `date_modified_gmt`
+     * field, which WordPress renders WITHOUT a timezone designator and interprets in the SITE's timezone
+     * (unless `dates_are_gmt` is set). Re-projecting such a value through UTC would silently shift the
+     * filter by the site's offset and skip or re-fetch records, so an already-ISO value is handed back
+     * verbatim; only a non-ISO representation is converted.
+     */
+    private toWordPressDate;
+    /** Max value of the object's declared watermark field across a batch — max-SEEN, never most-recent. */
+    private maxWatermark;
+    /**
+     * A WooCommerce consumer key/secret CANNOT read `wp/v2` — `WC_REST_Authentication::is_request_to_rest_api()`
+     * matches only URIs whose path after the REST prefix begins `wc/` or `wc-`. So a Woo-only connection must
+     * report every core object as an explicit CAPABILITY GAP rather than sync it empty and green.
+     */
+    private namespaceCredentialGuard;
+    /**
+     * Turns the two failures that are FACTS ABOUT THE SITE (rather than sync faults) into a warned
+     * zero-record result:
+     *   - 404 / `rest_no_route` — the route is not registered on THIS site. WooCommerce order fulfillments
+     *     sit behind `FeaturesUtil::feature_is_enabled('fulfillments')`, and any gated or plugin-provided
+     *     route can be absent the same way. That is correct behaviour for the site, not a broken sync.
+     *   - 401 / 403 with a WordPress envelope — the credential lacks the capability for this collection.
+     * Everything else (5xx, transport, throttling) propagates so the engine retries or fails loudly.
+     */
+    private gracefulFetchFailure;
+    /**
+     * A NESTED collection (`/wc/v3/orders/{order_id}/notes`, `/wp/v2/posts/{parent}/revisions`, …) fans out
+     * one request per parent, and the base resolves those parent ids from the ALREADY-SYNCED rows in the MJ
+     * target database. When no metadata provider is reachable — the parent object has not been mapped or
+     * synced yet, or the connector is running outside a database context — that is a DAG-ordering fact, not
+     * a connector fault: surface it as a named warning so the run artifact shows WHY the object is empty,
+     * instead of failing the whole sync or reporting a silent zero.
+     */
+    private parentResolutionUnavailable;
+    /** Clears any read failure remembered for this object's route, so a retry starts from a clean slate. */
+    private clearReadFailures;
+    /** The non-2xx read outcome recorded for this object's route during the pass just completed. */
+    private recordedReadFailure;
+    /**
+     * WordPress post types SOFT-delete: `DELETE` moves the row to `status=trash` and trashed rows stay
+     * listable via `status=trash`. This sweep captures them so a soft delete is visible to the engine.
+     *
+     * HONEST LIMITS, stated rather than papered over: there is NO deleted-records feed anywhere in wp/v2 or
+     * wc/v3, and a HARD delete (`?force=true`) leaves no tombstone at all — so full deletion reconciliation
+     * remains a declared KEY SWEEP, not detection. The sweep runs only on a fully-drained pass, only for
+     * objects whose metadata declares trash semantics in `wp/v2`, and only for an AUTHENTICATED connection
+     * (an anonymous caller can never see trash, and `status` is itself capability-gated).
+     */
+    private fetchTrashedRecords;
+    /** Flags any record carrying WordPress's `trash` status so the engine applies the connection's DeleteBehavior. */
+    private markTrashedAsDeleted;
+    /** True for the one declared object whose collection route WordPress never registers. */
+    private isGlobalStylesObject;
+    /**
+     * WordPress core registers NO collection route for global styles — only `/wp/v2/global-styles/{id}` and
+     * `/revisions` — so the ids cannot be listed and the object would otherwise sync zero rows while looking
+     * healthy (the declared metadata records this in `KnownGaps: "wp/v2 global styles enumeration"`).
+     *
+     * The ids ARE reachable through WordPress's own HAL links: each theme record advertises its user global
+     * styles post as `_links["wp:user-global-styles"]`. This walks that link — the source's own model, not a
+     * guessed URL — and fetches each id. When the link is absent the object reports an EXPLICIT warning
+     * rather than a silent empty success.
+     */
+    private fetchGlobalStyles;
+    /** Extracts global-styles ids from a theme record's HAL `_links`. */
+    private userGlobalStyleIDs;
+    /** The honest, named warning for an unenumerable global-styles object. */
+    private globalStylesWarning;
+    /**
+     * Builds an ExternalRecord with the FULL source record in `Fields` — never a narrow literal. The
+     * framework's custom-column capture diffs `keys(Fields)` against the active field maps, so anything
+     * dropped here (per-site `meta`, plugin-added properties) would be invisible and unrecoverable.
+     */
+    private buildRecord;
+    /** Reads the credential from the linked `MJ: Credentials` row, merged over the connection Configuration JSON. */
+    private loadCredentials;
+    /** Extracts the WordPress credential fields from a credential/Configuration JSON string. */
+    private parseCredentialJson;
+    /** Whether this connection opted into Woo's query-param credential fallback (hosts that strip Authorization). */
+    private wooQueryParamAuthEnabled;
+    /** Reads a trimmed string value from the connection Configuration JSON. */
+    private readConnectionConfigString;
+    /** All ACTIVE IntegrationObjects for the integration; `[]` when the engine cache is unavailable. */
+    protected getCachedObjects(integrationID: string): MJIntegrationObjectEntity[];
+    /** The Integration row itself (for the Integration-level Configuration blob); null when unavailable. */
+    protected tryGetIntegration(_integrationID: string): {
+        Configuration?: string | null;
+    } | null;
+    /** Non-throwing IntegrationObject lookup by integration + name. */
+    private tryGetCachedObject;
+    /** Non-throwing IntegrationObject lookup by name alone (used by StableOrderingKey, called early). */
+    private tryGetCachedObjectByName;
+    /** This connector's own `MJ: Integrations.ID`; null when the engine cache is not loaded yet. */
+    protected tryGetIntegrationID(): string | null;
+    /** The declared collection path for an object (`Configuration.listPath`, else its APIPath). */
+    private declaredListPath;
+    /** Typed view of an IntegrationObject's Configuration JSON. */
+    private objectConfig;
+    /** The `context=edit`-gated field names declared for whichever object owns this request path. */
+    private contextGatedFieldsForPath;
+    /** Canonical form of a route path with its captures collapsed, so `{id}` and `(?P<id>[\\d]+)` compare equal. */
+    private canonicalRoutePath;
+    /** A readable label for a discovered route, e.g. `/wp/v2/my-events` → `My Events (wp/v2)`. */
+    private humanLabelForRoute;
+    /** Builds a SourceObjectInfo for a route-index-discovered object. */
+    private toSourceObjectInfo;
+    /** Parses the `{ code, message, data:{ status } }` envelope out of a response body. */
+    private errorEnvelope;
+    /** The vendor's stable machine code from a response body, when it carries one. */
+    private vendorCodeOf;
+    /**
+     * Reads the HTTP status back out of a failure. `WordPressHTTPError` carries it directly; the base
+     * class's paginated loop raises `HTTP <status> from <url>: <body preview>`, which is our own package's
+     * stable message format.
+     */
+    private statusFromError;
+    /**
+     * Recovers the response body from a failure so it can be classified from the WordPress error ENVELOPE
+     * rather than the bare status. The base class's paginated loop raises
+     * `HTTP <status> from <url>: <body preview>`, so the preview is parsed back out; an HTML body (a WAF
+     * block) is returned as the raw string, which is exactly what the classifier keys on.
+     */
+    private bodyFromError;
+    /** Best-effort header extraction from an arbitrary thrown value (for ExtractRetryAfterMs). */
+    private headersFromUnknownError;
+    /** Parses a JSON string into a plain object; null for absent/invalid/non-object input. */
+    private parseJsonObject;
+    /** First present, non-empty string among the given keys. */
+    private firstString;
+    /** Coerces a header/metadata value to a positive integer, or null. */
+    private toPositiveInt;
+    /** Path component of a URL (no query), tolerant of a non-absolute input. */
+    private pathOf;
+    /** Splits a URL into `[beforeQuery, query]`. */
+    private splitQuery;
+    /** Whether the URL already carries a query param of this name (case-insensitive). */
+    private hasQueryParam;
+    /** Appends a query param (URL-encoded), preserving anything already present. */
+    private withQueryParam;
+    /** Removes every occurrence of a query param from a URL. */
+    private stripQueryParam;
+    /** Logs a capability/diagnostic warning exactly once per key, so an honest signal never becomes noise. */
+    private warnOnce;
+    /** Message text of an arbitrary thrown value. */
+    private errText;
+}