@memberjunction/connector-eventbrite 1.0.0 → 2.0.0

package/dist/EventbriteConnector.d.ts

@@ -1,178 +1,204 @@
 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 } from '@memberjunction/integration-engine';
+import { BaseRESTIntegrationConnector, type RESTAuthContext, type RESTResponse, type PaginationState, type PaginationType, type ConnectionTestResult, type FetchContext, type FetchBatchResult, type RateLimitPolicy, type CreateRecordContext, type UpdateRecordContext, type DeleteRecordContext, type CRUDResult, type SourceSchemaInfo } from '@memberjunction/integration-engine';
 /**
- * Per-connection configuration for the Eventbrite Platform REST API v3 connector.
+ * Eventbrite events/ticketing connector — extends BaseRESTIntegrationConnector (REST/JSON over HTTP).
  *
- * Eventbrite has a single shared host (`https://www.eventbriteapi.com/v3`). Auth is
- * a Bearer token — either a long-lived private token (issued from the account API Keys
- * page) or an OAuth2 authorization-code access token. Both are used verbatim as
- * `Authorization: Bearer <token>`; the connector does not perform the token exchange
- * (the resolved token lives in the credential store).
+ * Discovery, template-var parent traversal, and the paginated GET loop are inherited. This class supplies
+ * only the Eventbrite-specific protocol surface: Bearer auth, the continuation-token cursor, the
+ * `changed_since` incremental pull, connection testing, the write path (vendor-named path vars), and the
+ * §7/§10 sync-efficiency hooks the frozen contract evidences.
  */
-export interface EventbriteConnectionConfig {
-    /**
-     * The resolved Bearer token (private token OR OAuth2 access token). From the credential
-     * store (keys PrivateToken / Token / AccessToken / apiKey). Secrets never live in code.
-     */
-    Token?: string;
+export declare class EventbriteConnector extends BaseRESTIntegrationConnector {
+    /** Cached auth for the lifetime of a single sync run (Eventbrite tokens are long-lived, no refresh). */
+    private cachedAuth;
     /**
-     * Non-secret API host override (e.g. a local mock for replay/contract testing). When set,
-     * it WINS over the production host. Mirrors the ORCID/Novi `ApiBaseUrl` pattern — required
-     * for the mock-floor e2e testability tier.
+     * The active incremental watermark for the object currently being fetched, stashed by the FetchChanges
+     * override so the (ctx-less) BuildPaginatedURL can append `changed_since`. Set at the top of an
+     * incremental FetchChanges, cleared in its finally. Safe because the engine drives one FetchChanges per
+     * object at a time (single-threaded async; no concurrent BuildPaginatedURL for a different watermark).
      */
-    ApiBaseUrl?: string;
-    /** HTTP request timeout in milliseconds. Default: 30000. */
-    RequestTimeoutMs?: number;
-    /** Maximum retries for rate-limited / transient failures. Default: 4. */
-    MaxRetries?: number;
-    /** Minimum interval between outbound requests (ms). Default: 100. */
-    MinRequestIntervalMs?: number;
-}
-/**
- * Connector for the Eventbrite Platform REST API v3.
- *
- * Authenticates via a Bearer token (private token or OAuth2 access token, resolved
- * upstream and held in the credential store). Reads ride the base
- * {@link BaseRESTIntegrationConnector} pull path; this class overrides only the
- * genuinely Eventbrite-specific bits:
- *  - {@link BuildHeaders}: `Authorization: Bearer <token>` + `Accept: application/json`.
- *  - {@link GetBaseURL}: the shared `https://www.eventbriteapi.com/v3` host (or a
- *    non-secret `ApiBaseUrl` override for mock testing).
- *  - {@link NormalizeResponse}: unwraps the named-key list envelope (the IO's
- *    `ResponseDataKey`, e.g. `events`/`attendees`/`orders`) which sits alongside a
- *    `pagination` object; a bare object is a one-record detail; null → [].
- *  - {@link ExtractPaginationInfo} / {@link BuildPaginatedURL}: Eventbrite continuation-cursor
- *    pagination (`?continuation=<token>` + `pagination.has_more_items`/`.continuation`),
- *    plus the `changed_since=<watermark>` param for incremental objects (Order/Attendee) —
- *    fully metadata-driven (read `obj.IncrementalWatermarkField` + `obj.SupportsIncrementalSync`),
- *    NEVER keyed off a hardcoded object name.
- *  - {@link FetchChanges}: sets the watermark context, delegates to the base, then advances
- *    the watermark from the records' `changed` field on the final batch only (HasMore=false)
- *    so a partial-failure mid-pagination leaves the watermark unchanged.
- *
- * Create/Update/Delete use the generic per-operation column path
- * (CreateAPIPath/Method/BodyShape/BodyKey/IDLocation, Update*, Delete*) driven entirely
- * by the IO metadata — no per-verb override. Eventbrite uses POST for update (its
- * convention) and wrapped bodies for most resources (CreateBodyKey =
- * event|ticket_class|venue|discount|question|webhook|...). Parent template vars
- * ({organization_id}/{event_id}) are resolved by the engine's parent-iteration from each
- * IO's `Configuration.parentObjectName`.
- */
-export declare class EventbriteConnector extends BaseRESTIntegrationConnector {
-    /** Cached auth context (token + resolved host). */
-    private authState;
-    /** Timestamp of the last outbound request, used for throttling. */
-    private lastRequestTime;
-    /** Watermark for the current FetchChanges cycle, emitted as the IO's incremental param. */
-    private currentWatermark;
-    /** Verbatim from the metadata Integration row — part of the three-way name invariant. */
+    private activeChangedSince;
+    /** Verbatim `MJ: Integrations.Name`. Load-bearing: the T1 three-way name check compares this === metadata Name. */
     get IntegrationName(): string;
     get SupportsCreate(): boolean;
     get SupportsUpdate(): boolean;
     get SupportsDelete(): boolean;
     /**
-     * Eventbrite documents a default 2,000 calls/hour per token (HTTP 429 HIT_RATE_LIMIT
-     * over it). Run under that ceiling; the engine's AIMD bucket throttles + backs off.
+     * Discovery is NON-authoritative: DiscoverObjects / IntrospectSchema are cache-driven (they re-read
+     * persisted ACTIVE Declared metadata, NOT a live full-gamut enumeration). Eventbrite publishes no
+     * schema/describe/introspection endpoint enumerating everything a credential can access, so absence in a
+     * refresh proves nothing → never deactivate. Matches Configuration.DiscoveryIsAuthoritative=false.
      */
-    get RateLimitPolicy(): RateLimitPolicy | null;
+    get DiscoveryIsAuthoritative(): boolean;
+    /**
+     * IntrospectSchema — pure WIRING of MJ's existing sampler into the declared catalog (the connector
+     * sample-union standard; see CONNECTOR_DISCOVERY_STANDARD.md). This connector adds NO discovery,
+     * merge, or sync logic — it only wires `DiscoverFieldsViaFetch` (MJ's sampler) into IntrospectSchema.
+     *
+     * `super.IntrospectSchema` yields the cache-driven Declared catalog (no measured widths). For each
+     * object we then call MJ's `DiscoverFieldsViaFetch` — MJ's own read-path sampler that measures real
+     * field widths and surfaces custom columns — and the shared PURE `mergeDeclaredWithSampledFields`
+     * unions the two by field name (adopt MJ's measured width; append MJ-discovered custom columns). MJ
+     * owns everything else (measurement, type/PK inference, persistence, reconcile, sync).
+     *
+     * Recursion note: `DiscoverFieldsViaFetch` falls back to the UNCHANGED `DiscoverFields` (cache-driven)
+     * when the read path can't run — never back into THIS method — so there is no infinite recursion.
+     * This connector does NOT override `DiscoverFields` to call any ViaFetch/ViaStream.
+     *
+     * Robustness: objects are sampled IN PARALLEL under a small bounded pool; any per-object failure
+     * keeps that object's declared fields, so a single bad sample never breaks introspection.
+     */
+    IntrospectSchema(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<SourceSchemaInfo>;
     /**
-     * Cap how many EVENT/ORG parents a second-layer object (TicketClass, Attendee, Question,
-     * EventTeam, InventoryTier, …) iterates per FetchChanges call. At Eventbrite's deliberately
-     * conservative 0.27 tok/s (~3.7 s/request once the SHARED burst is spent by earlier objects in
-     * the same sync), the base default of 10 parents costs ~37 s and blows the 30 s FetchChanges
-     * op-timeout — the batch is then abandoned and the object syncs 0 records for any org with that
-     * many events. A batch of 4 costs ~15 s (well under 30 s) and the engine resumes the remaining
-     * parents via HasMore/keyset, so a high-event-count org still syncs completely.
+     * From Configuration.RateLimitPolicy: 2,000 calls/hour per token (blueprint ## Errors, 429
+     * HIT_RATE_LIMIT). 2000/3600 ≈ 0.556 tokens/sec sustained. Burst kept small (the hourly ceiling is the
+     * real constraint; there is no documented per-second burst allowance).
      */
-    protected TemplateVarParentBatchSize(): number;
-    /** Parse Eventbrite's Retry-After header (delta-seconds or HTTP-date) into milliseconds. */
-    ExtractRetryAfterMs(error: unknown): number | undefined;
+    get RateLimitPolicy(): RateLimitPolicy | null;
     /**
-     * Verifies connectivity via `GET /users/me/`. A 2xx confirms the Bearer token is valid;
-     * a 401/403 means the token was rejected (NOT_AUTH / NOT_PERMITTED).
+     * The frozen contract records NO Retry-After header shape for Eventbrite's 429 (HIT_RATE_LIMIT)
+     * (Configuration.RateLimitPolicy.retryAfterHeaderDocumented=false), so there is nothing to parse
+     * reliably. Left as the base default (undefined) rather than guessing a header name — the engine's AIMD
+     * bucket backs off on the 429 regardless. Documented as a soft gap for live-probe confirmation.
      */
-    TestConnection(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<ConnectionTestResult>;
+    /** Conservative in-flight cap. The 2,000/hour ceiling is the real limiter; a low cap avoids bursts. */
+    get MaxConcurrencyHint(): number | null;
     /**
-     * Sets the watermark context that {@link BuildPaginatedURL} emits as the IO's
-     * incremental `changed_since` param (for Order/Attendee), delegates the actual fetch +
-     * cursor pagination to the base, then advances the watermark from the returned records'
-     * `changed` field on the FINAL batch only (HasMore=false) so a partial-failure
-     * mid-pagination leaves the watermark unchanged.
+     * No-watermark objects resume by their StableOrderingKey — read from the IO metadata when the extractor
+     * emitted one, else the object's PK (Eventbrite's universal `id`). Returns null when the object has no
+     * stable key or the cache is unavailable (unit-test context).
      */
-    FetchChanges(ctx: FetchContext): Promise<FetchBatchResult>;
+    StableOrderingKey(objectName: string): string | null;
     /**
-     * Scans a batch for the latest watermark value. Eventbrite's incremental objects
-     * (Order, Attendee) carry a `changed` ISO-8601 timestamp per record (the field named by
-     * the IO's `IncrementalWatermarkField`); we take the max so the next run's `changed_since`
-     * resumes from there.
+     * Resolves the pre-minted Bearer token from the linked Credential entity (preferred) or the
+     * CompanyIntegration Configuration JSON (fallback). Cached for the run.
      */
-    private ExtractLatestWatermark;
     protected Authenticate(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<RESTAuthContext>;
-    /** Builds the Eventbrite auth header: `Authorization: Bearer <token>` + `Accept: application/json`. */
+    /** Eventbrite OAuth2 auth: a pre-minted Bearer token. No signing, no crypto. */
     protected BuildHeaders(auth: RESTAuthContext): Record<string, string>;
+    /** HTTP transport (fetch). Owns the wire boundary; test subclasses override this to capture requests. */
+    protected MakeHTTPRequest(_auth: RESTAuthContext, url: string, method: string, headers: Record<string, string>, body?: unknown): Promise<RESTResponse>;
     /**
-     * Unwraps Eventbrite's response shapes:
-     *  - List endpoints: `{ <responseDataKey>: [ ... ], pagination: { ... } }` → the named array.
-     *  - Single-record detail (no responseDataKey): a bare object → a one-element array.
-     *  - null → [].
-     * The IO metadata's `responseDataKey` (e.g. `events`/`attendees`/`orders`) is the
-     * authoritative envelope key; when absent the body is treated as a bare detail object.
+     * Strips the Eventbrite list envelope. Each list endpoint nests records under a plural snake_case
+     * resource key (`events`, `attendees`, `orders`, …), stored per-IO as ResponseDataKey. When
+     * ResponseDataKey is unset (the extractor left it null), the key is DERIVED from the last non-templated
+     * path segment of the APIPath — but NormalizeResponse doesn't have the IO here, so the fallback scans the
+     * envelope for the sole array-valued key alongside `pagination`. A bare-array or single-object body (the
+     * get-one / non-paginated shape) is handled directly.
      */
     protected NormalizeResponse(rawBody: unknown, responseDataKey: string | null): Record<string, unknown>[];
-    private coerceToArray;
-    private isRecord;
     /**
-     * Continuation-cursor pagination: Eventbrite returns a `pagination` envelope carrying
-     * `has_more_items` (boolean) and `continuation` (opaque cursor token). There are more
-     * records while `has_more_items` is true AND a continuation token is present. The
-     * total record count (`object_count`) is surfaced when available.
-     *
-     * The `Cursor` pagination type drives this; non-cursor objects (`None`) report no more.
+     * Eventbrite pagination is the CONTINUATION-TOKEN scheme (NOT page-number/offset). Read
+     * `pagination.has_more_items` and `pagination.continuation` from the envelope. When has_more_items is
+     * true AND a continuation token is present, the next page is requested with that token; otherwise the set
+     * is exhausted. Source: Configuration.PaginationDefaults.advanceProtocol.
+     * currentPage/offset/pageSize are unused for continuation pagination.
+     */
+    protected ExtractPaginationInfo(rawBody: unknown, _paginationType: PaginationType, _currentPage: number, _currentOffset: number, _pageSize: number): PaginationState;
+    /**
+     * Eventbrite v3 host. Defaults to the fixed `https://www.eventbriteapi.com/v3` host (the version
+     * segment is part of the base URL; metadata APIPaths are relative). Honors a
+     * `CompanyIntegration.Configuration.BaseURL` override when present — used for region redirects and
+     * for pointing the connector at a mock ORIGIN server in credential-free e2e testing without touching
+     * the vendor's real endpoint. Falls back to the fixed host on absence or malformed Configuration.
+     */
+    protected GetBaseURL(companyIntegration?: MJCompanyIntegrationEntity): string;
+    /**
+     * Eventbrite pages via the `continuation` query param (NOT the base default `cursor=`). The first page
+     * sends no continuation token; subsequent pages send `continuation=<token>`. When an incremental
+     * watermark is active (Attendee/Order this run), `changed_since=<watermark>` is appended so the API
+     * returns only records changed after the watermark. Eventbrite has no client-controlled page-size param
+     * on these list endpoints (page_size is server-fixed and reported in the envelope), so no limit is sent.
      */
-    protected ExtractPaginationInfo(rawBody: unknown, paginationType: PaginationType, currentPage: number, currentOffset: number, _pageSize: number): PaginationState;
+    protected BuildPaginatedURL(basePath: string, _obj: MJIntegrationObjectEntity, _page: number, _offset: number, cursor?: string, _effectivePageSize?: number): string;
     /**
-     * Builds the paginated request URL. Eventbrite cursor pagination uses `?continuation=<token>`
-     * (the base default emits `?cursor=...&limit=...`), so we override to emit the vendor's
-     * param. Also emits the IO's `IncrementalWatermarkField` as `changed_since=<watermark>`
-     * when this is an incremental object (Order/Attendee) and a watermark is in context —
-     * fully metadata-driven (read `obj.IncrementalWatermarkField` + `obj.SupportsIncrementalSync`),
-     * NEVER keyed off a hardcoded object name.
+     * OVERRIDDEN to (1) inject the `changed_since` param for the two incremental objects (Attendee, Order —
+     * SupportsIncrementalSync + a watermark this run) and (2) EMIT the new watermark. The base flat/template
+     * fetch path threads no watermark into the URL and returns no NewWatermarkValue, so the connector owns
+     * both. All fetching (continuation pagination, template-var parent traversal) is delegated to the base;
+     * this override only sets activeChangedSince around the super call and computes the watermark on a fully
+     * drained batch.
      *
-     * Parent template vars ({organization_id}/{event_id}) are NOT substituted here — those are
-     * resolved by the engine's parent-iteration from the IO's `Configuration.parentObjectName`.
-     */
-    protected BuildPaginatedURL(basePath: string, obj: MJIntegrationObjectEntity, _page: number, _offset: number, cursor?: string, _effectivePageSize?: number): string;
-    /**
-     * Resolves the vendor-side query param name for an incremental object. Eventbrite's
-     * incremental filter param is `changed_since` (the IO's `IncrementalWatermarkField` is the
-     * RECORD field `changed`). Metadata-driven: only objects whose `SupportsIncrementalSync` is
-     * true and whose watermark field is set receive the param.
-     */
-    private resolveWatermarkParam;
-    protected GetBaseURL(_companyIntegration: MJCompanyIntegrationEntity, auth: RESTAuthContext): string;
-    protected MakeHTTPRequest(auth: RESTAuthContext, url: string, method: string, headers: Record<string, string>, body?: unknown): Promise<RESTResponse>;
-    /** Single fetch() with an AbortController-backed timeout. */
-    private doFetch;
-    private safeParseJSON;
-    private isRetryableError;
-    private backoffMs;
-    private backoffFromResponse;
-    private throttle;
-    private sleep;
-    private asObject;
-    /**
-     * Resolves the connection config: the Bearer token from the credential store; the
-     * non-secret host override + transport tunables from CompanyIntegration.Configuration.
-     * Secrets are NEVER baked into code.
-     */
-    private parseConfig;
-    /** Resolves the API host: the non-secret override wins over the production host. */
-    private resolveBaseUrl;
-    /** Parses the non-secret host/tunables config from CompanyIntegration.Configuration JSON. */
-    private parseConfigurationJson;
-    /** Loads the Bearer token from the MJ credential store. */
-    private loadFromCredential;
+     * Partial-failure safety: NewWatermarkValue is emitted ONLY when the whole object is drained
+     * (HasMore=false). A mid-stream batch (HasMore=true — more parents to iterate) advances no watermark, so a
+     * failure between batches resumes from the unchanged prior watermark. When the final batch's max `changed`
+     * is below an earlier batch's, the watermark under-advances (worst case re-fetches already-seen records
+     * next run — idempotent, safe) rather than skipping records (data loss).
+     */
+    FetchChanges(ctx: FetchContext): Promise<FetchBatchResult>;
+    /**
+     * Create: substitutes the create path's parent vars from Attributes/Relationships (create paths carry
+     * only parent vars — the record has no id yet), POSTs the body shaped per CreateBodyShape/CreateBodyKey,
+     * and routes the result through BuildCreatedResult so a 2xx with no usable id FAILS LOUDLY.
+     */
+    CreateRecord(ctx: CreateRecordContext): Promise<CRUDResult>;
+    /**
+     * Update: substitutes the record's own id (ExternalID) into the LAST path var and any parent vars from
+     * Attributes/Relationships, then POSTs the wrapped body (Eventbrite uses POST, not PATCH/PUT, for update).
+     */
+    UpdateRecord(ctx: UpdateRecordContext): Promise<CRUDResult>;
+    /**
+     * Delete: substitutes the record's own id (ExternalID) into the last path var and any parent vars, then
+     * issues DeleteMethod (metadata-driven — Eventbrite uses hard DELETE, but the verb is read from metadata,
+     * not assumed).
+     */
+    DeleteRecord(ctx: DeleteRecordContext): Promise<CRUDResult>;
+    /**
+     * Tests the connection by hitting the current-user endpoint (`/users/me/`). A 2xx confirms the Bearer
+     * token is valid; 401/403 → auth failure; anything else → error.
+     */
+    TestConnection(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<ConnectionTestResult>;
+    /** Reads the Bearer token from the linked Credential entity, or the Configuration JSON fallback. */
+    private LoadCredentials;
+    /** Loads a credential row and parses its Values JSON. */
+    private LoadFromCredentialEntity;
+    /** Extracts an Eventbrite token from a credential/config JSON string. Returns null when no token is present. */
+    private ParseCredentialJson;
+    /**
+     * Substitutes EVERY `{var}` in a write path. The record's own id (recordID, when provided) fills the
+     * generic `{ID}`/`{id}`/`{ExternalID}` placeholders AND the LAST vendor-named var in the path (the
+     * record's own id segment for update/delete, e.g. `{ticket_class_id}` in
+     * `/events/{event_id}/ticket_classes/{ticket_class_id}/`). Every OTHER var is a parent id resolved from
+     * the resolution map (Attributes ∪ Relationships), matched case-insensitively. Returns the resolved path
+     * plus the list of vars that could NOT be resolved (caller fails loudly on a non-empty list).
+     */
+    private SubstituteAllPathVars;
+    /**
+     * A delete carries no Attributes, so a child-object delete path with a parent var (e.g.
+     * `/events/{event_id}/ticket_classes/{...}`) has no place to source the parent id — EXCEPT the composite
+     * ExternalID. When the path has >1 var, the ExternalID is expected as `parentId|...|recordId` (the base's
+     * composite-PK ExternalID form): the trailing segment is the record id, the leading segments fill the
+     * parent vars in path order. When the path has ≤1 var, the whole ExternalID is the record id.
+     */
+    private SplitCompositeExternalID;
+    /** Detects `{var}` placeholders in a path. */
+    private DetectPathVars;
+    /** Builds a case-insensitive lookup map of parent-id candidates from Attributes ∪ Relationships. */
+    private BuildResolutionMap;
+    /** Builds a consistent unresolved-var CRUD failure result (never a broken URL to the wire). */
+    private UnresolvedVarError;
+    /**
+     * Formats a watermark value into the `changed_since` datetime the API expects (UTC ISO-8601). Accepts an
+     * ISO string (passed through) or an epoch-ms string (converted). Eventbrite documents `changed_since` as
+     * a UTC datetime; passing an unparseable value through unchanged lets the API reject it loudly rather than
+     * silently widening the window.
+     */
+    private FormatChangedSince;
+    /**
+     * Computes the new watermark = the max `changed` timestamp across the fetched records, floored at the
+     * incoming watermark so it never regresses. Records that don't carry the field are skipped. Returns the
+     * incoming watermark unchanged when no record advances it (idempotent no-op next run).
+     */
+    private MaxWatermark;
+    /** Parses a watermark (ISO datetime or epoch-ms string) to epoch ms; 0 when unparseable/empty. */
+    private ToMs;
+    /** Returns the first present, non-empty string value among the given keys. */
+    private FirstString;
+    /**
+     * Resolves an IO by name from the engine cache (via this integration's id) without throwing. Returns null
+     * when the cache is unavailable (unit-test context) or the object isn't found — StableOrderingKey then
+     * degrades to null, a safe default (the engine simply doesn't use keyset resume for that object).
+     */
+    private TryGetActiveObject;
 }
-/** Tree-shaking prevention function — import and call from the package entry point. */
-export declare function LoadEventbriteConnector(): void;