@memberjunction/integration-connectors 5.51.0 → 6.1.0-edge.0

package/dist/WicketConnector.js

@@ -1,938 +0,0 @@
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-import { createHmac } from 'node:crypto';
-import { RegisterClass } from '@memberjunction/global';
-import { Metadata } from '@memberjunction/core';
-import { BaseIntegrationConnector, BaseRESTIntegrationConnector, } from '@memberjunction/integration-engine';
-// ─── Constants ───────────────────────────────────────────────────────
-/** Default JWT expiration window in seconds (5 minutes) */
-const JWT_EXPIRATION_SECONDS = 300;
-/** Maximum retries for rate-limited or transient failures */
-const MAX_RETRIES = 5;
-/** HTTP request timeout in milliseconds */
-const REQUEST_TIMEOUT_MS = 30_000;
-/** Minimum milliseconds between API requests (Wicket: 500 req/min ≈ 120ms/req) */
-const MIN_REQUEST_INTERVAL_MS = 125;
-/** Default page size for Wicket API requests */
-const DEFAULT_PAGE_SIZE = 100;
-/**
- * Maps integration object names to their JSON:API `type` values.
- * Used when constructing JSON:API request bodies for CRUD operations.
- */
-const WICKET_JSONAPI_TYPES = {
-    people: 'people',
-    organizations: 'organizations',
-    connections: 'connections',
-    groups: 'groups',
-    group_members: 'group_members',
-    person_memberships: 'person_memberships',
-    organization_memberships: 'organization_memberships',
-    memberships: 'memberships',
-    touchpoints: 'touchpoints',
-    emails: 'emails',
-    phones: 'phones',
-    addresses: 'addresses',
-    roles: 'roles',
-    user_identities: 'user_identities',
-    resource_tags: 'resource_tags',
-    people_emails: 'emails',
-    people_phones: 'phones',
-    people_addresses: 'addresses',
-    org_emails: 'emails',
-    org_phones: 'phones',
-    org_addresses: 'addresses',
-};
-/**
- * Objects that support POST /query endpoints for advanced search.
- * These accept nested filters, OR logic, and data_fields searching.
- */
-const SEARCHABLE_OBJECTS = new Set([
-    'people',
-    'organizations',
-    'connections',
-    'groups',
-    'group_members',
-    'person_memberships',
-    'organization_memberships',
-]);
-/**
- * Objects that are immutable (no update/delete allowed).
- * Touchpoints are audit trail records by design.
- */
-const IMMUTABLE_OBJECTS = new Set(['touchpoints']);
-// ─── JWT Helper ──────────────────────────────────────────────────────
-/**
- * Encodes a buffer or string to base64url format (RFC 7515).
- * Replaces `+` with `-`, `/` with `_`, and strips trailing `=` padding.
- */
-function base64url(input) {
-    const b64 = Buffer.from(input, 'utf8').toString('base64');
-    return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
-}
-/** Encodes a Buffer to base64url format. */
-function base64urlBuffer(input) {
-    return input.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
-}
-/**
- * Generates a signed JWT token for Wicket API authentication.
- * Uses HS256 (HMAC-SHA256) algorithm as required by the Wicket API.
- *
- * @param credentials - Wicket credentials containing API secret, admin UUID, and tenant
- * @returns Signed JWT string
- */
-/** Resolves the Wicket API base URL from credentials (direct URL or tenant-derived). */
-function resolveWicketBaseURL(credentials) {
-    if (credentials.ApiUrl) {
-        // Strip trailing slash for consistency
-        return credentials.ApiUrl.replace(/\/+$/, '');
-    }
-    if (credentials.TenantName) {
-        return `https://${credentials.TenantName}-api.wicketcloud.com`;
-    }
-    throw new Error('Cannot determine Wicket API base URL. Provide apiUrl or tenantName in credentials.');
-}
-function generateWicketJWT(credentials) {
-    const now = Math.floor(Date.now() / 1000);
-    const apiUrl = resolveWicketBaseURL(credentials);
-    const header = { alg: 'HS256', typ: 'JWT' };
-    const payload = {
-        exp: now + JWT_EXPIRATION_SECONDS,
-        sub: credentials.AdminUserUUID,
-        aud: apiUrl,
-    };
-    if (credentials.IssuerDomain) {
-        payload['iss'] = credentials.IssuerDomain;
-    }
-    const encodedHeader = base64url(JSON.stringify(header));
-    const encodedPayload = base64url(JSON.stringify(payload));
-    const signingInput = `${encodedHeader}.${encodedPayload}`;
-    const signature = createHmac('sha256', credentials.ApiSecret)
-        .update(signingInput)
-        .digest();
-    return `${signingInput}.${base64urlBuffer(signature)}`;
-}
-// ─── Connector ───────────────────────────────────────────────────────
-/**
- * Connector for the Wicket membership management platform via its JSON:API REST API.
- *
- * Extends BaseRESTIntegrationConnector to leverage metadata-driven object/field
- * discovery, generic pagination handling, and template variable resolution.
- *
- * Supports:
- * - JWT Bearer authentication (HS256, generated from API secret)
- * - JSON:API response format normalization (flattens `data[].attributes`)
- * - Page-number pagination (`page[number]`, `page[size]`)
- * - Timestamp-based watermarks via `filter[updated_at_gteq]`
- * - Full CRUD operations (bidirectional sync)
- * - Advanced search via POST /query endpoints
- * - Rate limiting (500 req/min, auto-throttle + retry on 429)
- *
- * @see https://wicketapi.docs.apiary.io/
- */
-let WicketConnector = class WicketConnector extends BaseRESTIntegrationConnector {
-    constructor() {
-        super(...arguments);
-        /** Timestamp of the last API request, used for throttling */
-        this.lastRequestTime = 0;
-        /** Cached auth context to avoid regenerating JWT on every request */
-        this.cachedAuth = null;
-        /** Expiration time of the cached auth context */
-        this.cachedAuthExpiresAt = 0;
-    }
-    // ─── Identity ────────────────────────────────────────────────────
-    // Required for the three-way invariant (metadata.Name = connector
-    // IntegrationName = @RegisterClass tag). Base class default
-    // (this.constructor.name) would return 'WicketConnector' which would
-    // miss the metadata lookup for 'Wicket'.
-    get IntegrationName() { return 'Wicket'; }
-    // ─── Capability Getters ──────────────────────────────────────────
-    get SupportsCreate() { return true; }
-    get SupportsUpdate() { return true; }
-    get SupportsDelete() { return true; }
-    get SupportsSearch() { return true; }
-    // ─── BaseRESTIntegrationConnector abstract implementations ───────
-    async Authenticate(companyIntegration, contextUser) {
-        // Return cached auth if still valid (with 30s safety margin)
-        const now = Math.floor(Date.now() / 1000);
-        if (this.cachedAuth && this.cachedAuthExpiresAt > now + 30) {
-            return this.cachedAuth;
-        }
-        const credentials = await this.LoadCredentials(companyIntegration, contextUser);
-        const token = generateWicketJWT(credentials);
-        const baseURL = resolveWicketBaseURL(credentials);
-        const auth = {
-            Token: token,
-            Credentials: credentials,
-            BaseURL: baseURL,
-        };
-        this.cachedAuth = auth;
-        this.cachedAuthExpiresAt = now + JWT_EXPIRATION_SECONDS;
-        return auth;
-    }
-    BuildHeaders(auth) {
-        return {
-            'Authorization': `Bearer ${auth.Token}`,
-            'Accept': 'application/json',
-            'Content-Type': 'application/vnd.api+json',
-        };
-    }
-    async MakeHTTPRequest(_auth, url, method, headers, body) {
-        await this.ThrottleRequest();
-        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-            const response = await this.FetchWithTimeout(url, method, headers, body);
-            this.lastRequestTime = Date.now();
-            if (response.status === 429) {
-                const delayMs = this.CalculateRetryDelay(response, attempt);
-                console.warn(`[Wicket] Rate limited (429), retrying in ${delayMs}ms ` +
-                    `(attempt ${attempt + 1}/${MAX_RETRIES})`);
-                await this.Sleep(delayMs);
-                continue;
-            }
-            const responseBody = await this.ParseResponseBody(response);
-            return this.BuildRESTResponse(response, responseBody);
-        }
-        throw new Error(`Wicket API request failed after ${MAX_RETRIES} retries: ${url}`);
-    }
-    /**
-     * Normalizes a JSON:API response into flat record objects.
-     *
-     * Wicket returns data in JSON:API format:
-     * ```json
-     * {
-     *   "data": [{ "id": "uuid", "type": "people", "attributes": {...}, "relationships": {...} }],
-     *   "included": [...],
-     *   "meta": { "page": { "number": 1, "size": 25, "total_count": 500 } }
-     * }
-     * ```
-     *
-     * This method flattens each record to: `{ uuid: "...", given_name: "...", ... }`
-     */
-    NormalizeResponse(rawBody, responseDataKey) {
-        const body = rawBody;
-        // Use responseDataKey if specified, otherwise default to "data"
-        const dataKey = responseDataKey ?? 'data';
-        const data = body[dataKey];
-        if (!data)
-            return [];
-        // Handle single-object responses (e.g., GET /people/{id})
-        if (!Array.isArray(data)) {
-            return [this.FlattenJsonApiRecord(data)];
-        }
-        return data.map(r => this.FlattenJsonApiRecord(r));
-    }
-    /**
-     * Extracts pagination state from Wicket's JSON:API meta response.
-     *
-     * Wicket returns pagination info in:
-     * ```json
-     * { "meta": { "page": { "number": 1, "size": 25, "total_count": 500 } } }
-     * ```
-     */
-    ExtractPaginationInfo(rawBody, _paginationType, currentPage, _currentOffset, pageSize) {
-        const body = rawBody;
-        const meta = body['meta'];
-        const pageInfo = meta?.['page'];
-        if (!pageInfo?.total_count) {
-            return { HasMore: false };
-        }
-        const totalPages = Math.ceil(pageInfo.total_count / (pageInfo.size ?? pageSize));
-        const hasMore = currentPage < totalPages;
-        return {
-            HasMore: hasMore,
-            NextPage: hasMore ? currentPage + 1 : undefined,
-            TotalRecords: pageInfo.total_count,
-        };
-    }
-    GetBaseURL(companyIntegration) {
-        // If we have a cached auth context, use its base URL
-        if (this.cachedAuth) {
-            return this.cachedAuth.BaseURL;
-        }
-        // Fallback: parse from configuration JSON
-        const configJson = companyIntegration.Get('Configuration');
-        if (configJson) {
-            try {
-                const config = JSON.parse(configJson);
-                const apiUrl = config['apiUrl'] ?? config['ApiUrl'];
-                if (apiUrl)
-                    return apiUrl.replace(/\/+$/, '');
-                const tenant = config['tenantName'] ?? config['TenantName'];
-                if (tenant)
-                    return `https://${tenant}-api.wicketcloud.com`;
-            }
-            catch { /* fall through */ }
-        }
-        throw new Error('Cannot determine Wicket API base URL. Provide apiUrl or tenantName in credentials or configuration.');
-    }
-    // ─── Wicket-specific pagination ──────────────────────────────────
-    /**
-     * Overrides base pagination URL building to use Wicket's JSON:API parameter format.
-     * Wicket uses `page[number]` and `page[size]` (bracket notation).
-     */
-    BuildPaginatedURL(basePath, obj, page, _offset, _cursor) {
-        const separator = basePath.includes('?') ? '&' : '?';
-        const pageSize = obj.DefaultPageSize || DEFAULT_PAGE_SIZE;
-        return `${basePath}${separator}page[number]=${page}&page[size]=${pageSize}`;
-    }
-    // ─── FetchChanges override for watermark support ─────────────────
-    /**
-     * Overrides FetchChanges to inject Wicket's timestamp-based watermark filter.
-     * Uses `filter[updated_at_gteq]` for incremental sync.
-     */
-    async FetchChanges(ctx) {
-        // If watermark is provided, inject it as a filter parameter
-        if (ctx.WatermarkValue) {
-            const currentConfig = ctx.CompanyIntegration.Get('Configuration');
-            const config = currentConfig ? JSON.parse(currentConfig) : {};
-            // Store original and inject watermark filter into request
-            const originalWatermarkFilter = config['_watermarkFilter'];
-            config['_watermarkFilter'] = ctx.WatermarkValue;
-            // We'll use this in AppendDefaultQueryParams override behavior
-        }
-        const result = await super.FetchChanges(ctx);
-        // Set new watermark to current timestamp if we got records
-        if (result.Records.length > 0) {
-            result.NewWatermarkValue = new Date().toISOString();
-        }
-        return result;
-    }
-    // ─── DiscoverObjects ──────────────────────────────────────────────
-    /**
-     * Canonical Wicket top-level objects PLUS live-discovered per-tenant
-     * additional-info schemas (Wicket's "custom tables" concept — each
-     * org/event/etc can extend their data model via JSON-Schema-Forms).
-     *
-     * Standard objects are merged with what's already persisted so curated
-     * customizations aren't lost.  The additional-info schemas live at
-     * `/additional_info_schemas` (Wicket exposes them as queryable
-     * resources); each schema becomes a Discovered IO.
-     */
-    async DiscoverObjects(companyIntegration, contextUser) {
-        const persisted = await super.DiscoverObjects(companyIntegration, contextUser);
-        const canonical = [
-            { Name: 'people', Label: 'People', Description: 'Member/person records. /people.', SupportsIncrementalSync: true, SupportsWrite: true },
-            { Name: 'organizations', Label: 'Organizations', Description: 'Organization records. /organizations.', SupportsIncrementalSync: true, SupportsWrite: true },
-            { Name: 'person_memberships', Label: 'Person Memberships', Description: 'Per-person membership assignments. /person_memberships.', SupportsIncrementalSync: true, SupportsWrite: true },
-            { Name: 'organization_memberships', Label: 'Organization Memberships', Description: 'Per-organization membership assignments. /organization_memberships.', SupportsIncrementalSync: true, SupportsWrite: true },
-            { Name: 'memberships', Label: 'Membership Definitions', Description: 'Tenant-defined membership types/categories. /memberships.', SupportsIncrementalSync: false, SupportsWrite: true },
-            { Name: 'connections', Label: 'Connections', Description: 'Relationships between people / between people and organizations. /connections.', SupportsIncrementalSync: true, SupportsWrite: true },
-            { Name: 'groups', Label: 'Groups', Description: 'Group records (committees, chapters, etc). /groups.', SupportsIncrementalSync: true, SupportsWrite: true },
-            { Name: 'group_members', Label: 'Group Members', Description: 'Group membership entries. /group_members.', SupportsIncrementalSync: true, SupportsWrite: true },
-            { Name: 'segments', Label: 'Segments', Description: 'Saved audience segments. /segments.', SupportsIncrementalSync: false, SupportsWrite: false },
-            { Name: 'taxonomies', Label: 'Taxonomies', Description: 'Tenant-defined taxonomy categories. /taxonomies.', SupportsIncrementalSync: false, SupportsWrite: true },
-            { Name: 'additional_info_schemas', Label: 'Additional Info Schemas', Description: 'Tenant-defined JSON-Schema extensions for custom attributes (per-tenant "custom tables"). /additional_info_schemas.', SupportsIncrementalSync: false, SupportsWrite: false },
-        ];
-        const byName = new Map();
-        for (const o of persisted)
-            byName.set(o.Name.toLowerCase(), o);
-        for (const c of canonical) {
-            if (!byName.has(c.Name.toLowerCase()))
-                byName.set(c.Name.toLowerCase(), c);
-        }
-        // Live-discover per-tenant additional-info schemas — each one is a
-        // custom table the operator has defined.  Best-effort: probe failure
-        // is non-fatal (canonical set still returned).
-        try {
-            const auth = await this.Authenticate(companyIntegration, contextUser);
-            const headers = this.BuildHeaders(auth);
-            const baseURL = this.GetBaseURL(companyIntegration);
-            const resp = await this.MakeHTTPRequest(auth, `${baseURL}/additional_info_schemas`, 'GET', headers);
-            if (resp.Status === 200) {
-                const body = resp.Body;
-                for (const sch of body.data ?? []) {
-                    const slug = sch.attributes?.slug ?? sch.attributes?.name ?? sch.id;
-                    if (!slug)
-                        continue;
-                    const ioName = `additional_info.${slug}`;
-                    if (!byName.has(ioName.toLowerCase())) {
-                        byName.set(ioName.toLowerCase(), {
-                            Name: ioName,
-                            Label: sch.attributes?.name ?? slug,
-                            Description: sch.attributes?.description ?? `Tenant-defined additional-info schema (Wicket custom table). /additional_info_schemas/${sch.id}.`,
-                            SupportsIncrementalSync: false,
-                            SupportsWrite: false,
-                        });
-                    }
-                }
-            }
-        }
-        catch (err) {
-            console.warn(`[Wicket] additional_info_schemas live discovery failed (non-fatal, canonical set still returned): ${err instanceof Error ? err.message : err}`);
-        }
-        return [...byName.values()];
-    }
-    // ─── TestConnection ──────────────────────────────────────────────
-    /** Tests connectivity by authenticating and fetching 1 person record. */
-    async TestConnection(companyIntegration, contextUser) {
-        try {
-            const auth = await this.Authenticate(companyIntegration, contextUser);
-            const headers = this.BuildHeaders(auth);
-            const baseURL = this.GetBaseURL(companyIntegration);
-            const response = await this.MakeHTTPRequest(auth, `${baseURL}/people?page[size]=1`, 'GET', headers);
-            if (response.Status >= 200 && response.Status < 300) {
-                return {
-                    Success: true,
-                    Message: 'Successfully connected to Wicket API',
-                    ServerVersion: 'Wicket JSON:API v1',
-                };
-            }
-            const bodyPreview = this.FormatBodyPreview(response.Body);
-            return {
-                Success: false,
-                Message: `Wicket API returned ${response.Status}: ${bodyPreview}`,
-            };
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            return { Success: false, Message: `Connection failed: ${message}` };
-        }
-    }
-    // ─── GetDefaultFieldMappings ─────────────────────────────────────
-    GetDefaultFieldMappings(objectName, _entityName) {
-        switch (objectName) {
-            case 'people':
-                return this.GetPeopleFieldMappings();
-            case 'organizations':
-                return this.GetOrganizationFieldMappings();
-            case 'person_memberships':
-                return this.GetPersonMembershipFieldMappings();
-            case 'connections':
-                return this.GetConnectionFieldMappings();
-            default:
-                return [];
-        }
-    }
-    // ─── Default Configuration ───────────────────────────────────────
-    GetDefaultConfiguration() {
-        return {
-            DefaultSchemaName: 'Wicket',
-            DefaultObjects: [],
-        };
-    }
-    // ─── CRUD Operations (bidirectional sync support) ────────────────
-    /**
-     * Creates a new record in the Wicket API.
-     *
-     * @param companyIntegration - Company integration with credentials
-     * @param objectName - Wicket object type (e.g., "people", "organizations")
-     * @param attributes - Field values for the new record
-     * @param contextUser - User context for authorization
-     * @param relationships - Optional JSON:API relationships to include
-     * @returns CRUD result with the created record's external ID
-     */
-    async CreateRecord(ctx) {
-        const companyIntegration = ctx.CompanyIntegration;
-        const objectName = ctx.ObjectName;
-        this.ValidateWriteAllowed(objectName);
-        const auth = await this.Authenticate(companyIntegration, ctx.ContextUser);
-        const headers = this.BuildHeaders(auth);
-        const baseURL = this.GetBaseURL(companyIntegration);
-        const apiPath = this.ResolveObjectAPIPath(objectName);
-        const body = this.BuildJsonApiBody(objectName, ctx.Attributes, ctx.Relationships);
-        try {
-            const response = await this.MakeHTTPRequest(auth, `${baseURL}${apiPath}`, 'POST', headers, body);
-            return this.ParseCRUDResponse(response, 'create', objectName);
-        }
-        catch (err) {
-            return this.BuildCRUDError(err);
-        }
-    }
-    /**
-     * Updates an existing record in the Wicket API.
-     *
-     * @param companyIntegration - Company integration with credentials
-     * @param objectName - Wicket object type
-     * @param externalID - UUID of the record to update
-     * @param attributes - Field values to update
-     * @param contextUser - User context for authorization
-     * @param relationships - Optional JSON:API relationships to update
-     * @returns CRUD result indicating success or failure
-     */
-    async UpdateRecord(ctx) {
-        const companyIntegration = ctx.CompanyIntegration;
-        const objectName = ctx.ObjectName;
-        this.ValidateWriteAllowed(objectName);
-        const auth = await this.Authenticate(companyIntegration, ctx.ContextUser);
-        const headers = this.BuildHeaders(auth);
-        const baseURL = this.GetBaseURL(companyIntegration);
-        const apiPath = this.ResolveObjectAPIPath(objectName);
-        const body = this.BuildJsonApiBody(objectName, ctx.Attributes, ctx.Relationships, ctx.ExternalID);
-        try {
-            const response = await this.MakeHTTPRequest(auth, `${baseURL}${apiPath}/${ctx.ExternalID}`, 'PATCH', headers, body);
-            return this.ParseCRUDResponse(response, 'update');
-        }
-        catch (err) {
-            return this.BuildCRUDError(err);
-        }
-    }
-    /**
-     * Deletes a record from the Wicket API.
-     *
-     * @param companyIntegration - Company integration with credentials
-     * @param objectName - Wicket object type
-     * @param externalID - UUID of the record to delete
-     * @param contextUser - User context for authorization
-     * @returns CRUD result indicating success or failure
-     */
-    async DeleteRecord(ctx) {
-        const companyIntegration = ctx.CompanyIntegration;
-        const objectName = ctx.ObjectName;
-        this.ValidateWriteAllowed(objectName);
-        this.ValidateDeleteAllowed(objectName);
-        const auth = await this.Authenticate(companyIntegration, ctx.ContextUser);
-        const headers = this.BuildHeaders(auth);
-        const baseURL = this.GetBaseURL(companyIntegration);
-        const apiPath = this.ResolveObjectAPIPath(objectName);
-        try {
-            const response = await this.MakeHTTPRequest(auth, `${baseURL}${apiPath}/${ctx.ExternalID}`, 'DELETE', headers);
-            return {
-                Success: response.Status === 204 || (response.Status >= 200 && response.Status < 300),
-                ExternalID: ctx.ExternalID,
-                StatusCode: response.Status,
-            };
-        }
-        catch (err) {
-            return this.BuildCRUDError(err);
-        }
-    }
-    /**
-     * Retrieves a single record from the Wicket API by ID.
-     *
-     * @param companyIntegration - Company integration with credentials
-     * @param objectName - Wicket object type
-     * @param externalID - UUID of the record to retrieve
-     * @param contextUser - User context for authorization
-     * @returns The record as an ExternalRecord, or null if not found
-     */
-    async GetRecord(ctx) {
-        const companyIntegration = ctx.CompanyIntegration;
-        const objectName = ctx.ObjectName;
-        const auth = await this.Authenticate(companyIntegration, ctx.ContextUser);
-        const headers = this.BuildHeaders(auth);
-        const baseURL = this.GetBaseURL(companyIntegration);
-        const apiPath = this.ResolveObjectAPIPath(objectName);
-        try {
-            const response = await this.MakeHTTPRequest(auth, `${baseURL}${apiPath}/${ctx.ExternalID}`, 'GET', headers);
-            if (response.Status === 404)
-                return null;
-            if (response.Status < 200 || response.Status >= 300)
-                return null;
-            const records = this.NormalizeResponse(response.Body, 'data');
-            if (records.length === 0)
-                return null;
-            return {
-                ExternalID: ctx.ExternalID,
-                ObjectType: objectName,
-                Fields: records[0],
-            };
-        }
-        catch {
-            return null;
-        }
-    }
-    // ─── Search Operations ───────────────────────────────────────────
-    /**
-     * Searches for records using Wicket's POST /query endpoints.
-     *
-     * Supports advanced filtering with predicates:
-     * - Equality: `given_name_eq`, `status_not_eq`
-     * - Comparison: `created_at_gteq`, `updated_at_lt`
-     * - Pattern: `email_cont`, `name_start`
-     * - Null checks: `phone_present`, `address_blank`
-     * - Array: `status_in` (comma-separated values)
-     *
-     * @param companyIntegration - Company integration with credentials
-     * @param objectName - Wicket object type (must be in SEARCHABLE_OBJECTS)
-     * @param options - Search filters, sorting, and pagination
-     * @param contextUser - User context for authorization
-     * @returns Search results with records, total count, and pagination info
-     */
-    async SearchRecords(ctx) {
-        const companyIntegration = ctx.CompanyIntegration;
-        const objectName = ctx.ObjectName;
-        if (!SEARCHABLE_OBJECTS.has(objectName)) {
-            throw new Error(`Search is not supported for "${objectName}". ` +
-                `Searchable objects: ${[...SEARCHABLE_OBJECTS].join(', ')}`);
-        }
-        const auth = await this.Authenticate(companyIntegration, ctx.ContextUser);
-        const headers = this.BuildHeaders(auth);
-        const baseURL = this.GetBaseURL(companyIntegration);
-        const wicketOptions = {
-            Filters: ctx.Filters,
-            Sort: ctx.Sort,
-            Page: ctx.Page,
-            PageSize: ctx.PageSize,
-        };
-        const queryBody = this.BuildSearchQueryBody(wicketOptions);
-        const response = await this.MakeHTTPRequest(auth, `${baseURL}/${objectName}/query`, 'POST', headers, queryBody);
-        return this.ParseSearchResponse(response, objectName);
-    }
-    // ─── Default Field Mapping Builders ──────────────────────────────
-    GetPeopleFieldMappings() {
-        return [
-            { SourceFieldName: 'uuid', DestinationFieldName: 'ExternalID', IsKeyField: true },
-            { SourceFieldName: 'given_name', DestinationFieldName: 'FirstName' },
-            { SourceFieldName: 'family_name', DestinationFieldName: 'LastName' },
-            { SourceFieldName: 'full_name', DestinationFieldName: 'FullName' },
-            { SourceFieldName: 'job_title', DestinationFieldName: 'JobTitle' },
-            { SourceFieldName: 'gender', DestinationFieldName: 'Gender' },
-            { SourceFieldName: 'birth_date', DestinationFieldName: 'BirthDate' },
-            { SourceFieldName: 'language', DestinationFieldName: 'Language' },
-            { SourceFieldName: 'membership_number', DestinationFieldName: 'MembershipNumber' },
-        ];
-    }
-    GetOrganizationFieldMappings() {
-        return [
-            { SourceFieldName: 'uuid', DestinationFieldName: 'ExternalID', IsKeyField: true },
-            { SourceFieldName: 'legal_name', DestinationFieldName: 'Name' },
-            { SourceFieldName: 'alternate_name', DestinationFieldName: 'AlternateName' },
-            { SourceFieldName: 'description', DestinationFieldName: 'Description' },
-            { SourceFieldName: 'identifying_number', DestinationFieldName: 'IdentifyingNumber' },
-            { SourceFieldName: 'type', DestinationFieldName: 'OrganizationType' },
-        ];
-    }
-    GetPersonMembershipFieldMappings() {
-        return [
-            { SourceFieldName: 'uuid', DestinationFieldName: 'ExternalID', IsKeyField: true },
-            { SourceFieldName: 'starts_at', DestinationFieldName: 'StartDate' },
-            { SourceFieldName: 'ends_at', DestinationFieldName: 'EndDate' },
-        ];
-    }
-    GetConnectionFieldMappings() {
-        return [
-            { SourceFieldName: 'uuid', DestinationFieldName: 'ExternalID', IsKeyField: true },
-            { SourceFieldName: 'type', DestinationFieldName: 'ConnectionType' },
-        ];
-    }
-    // ─── Credential Management ───────────────────────────────────────
-    /**
-     * Reads Wicket credentials from the linked Credential entity,
-     * or falls back to CompanyIntegration Configuration JSON.
-     */
-    async LoadCredentials(companyIntegration, contextUser) {
-        const credentialID = companyIntegration.Get('CredentialID');
-        if (credentialID) {
-            const creds = await this.LoadFromCredentialEntity(credentialID, contextUser);
-            if (creds)
-                return creds;
-        }
-        const configJson = companyIntegration.Get('Configuration');
-        if (configJson) {
-            const creds = this.ParseCredentialJson(configJson);
-            if (creds)
-                return creds;
-        }
-        throw new Error('No Wicket credentials found. Attach a credential with apiSecret, adminUserUUID, ' +
-            'and either apiUrl or tenantName. Or set Configuration JSON on the CompanyIntegration.');
-    }
-    /** Loads credentials from a Credential entity by ID. */
-    async LoadFromCredentialEntity(credentialID, contextUser, provider) {
-        const md = provider ?? new Metadata();
-        const credential = await md.GetEntityObject('MJ: Credentials', contextUser);
-        const loaded = await credential.Load(credentialID);
-        if (!loaded || !credential.Values)
-            return null;
-        return this.ParseCredentialJson(credential.Values);
-    }
-    /** Parses a JSON string to extract Wicket credentials. Returns null if required fields missing. */
-    ParseCredentialJson(json) {
-        try {
-            const parsed = JSON.parse(json);
-            const apiSecret = parsed['apiSecret'] ?? parsed['ApiSecret'] ?? parsed['api_secret'];
-            const adminUUID = parsed['adminUserUUID'] ?? parsed['AdminUserUUID'] ?? parsed['admin_user_uuid'];
-            const tenant = parsed['tenantName'] ?? parsed['TenantName'] ?? parsed['tenant_name'] ?? null;
-            const apiUrl = parsed['apiUrl'] ?? parsed['ApiUrl'] ?? parsed['api_url'] ?? null;
-            if (!apiSecret || !adminUUID)
-                return null;
-            // Need either a direct API URL or a tenant name to derive the URL
-            if (!apiUrl && !tenant)
-                return null;
-            return {
-                ApiSecret: apiSecret,
-                AdminUserUUID: adminUUID,
-                TenantName: tenant,
-                ApiUrl: apiUrl,
-                IssuerDomain: parsed['issuerDomain'] ?? parsed['IssuerDomain'] ?? null,
-            };
-        }
-        catch {
-            return null;
-        }
-    }
-    // ─── JSON:API Body Builders ──────────────────────────────────────
-    /**
-     * Builds a JSON:API-compliant request body for create/update operations.
-     *
-     * Output format:
-     * ```json
-     * {
-     *   "data": {
-     *     "type": "people",
-     *     "attributes": { "given_name": "Jane", ... },
-     *     "relationships": { ... }
-     *   }
-     * }
-     * ```
-     */
-    BuildJsonApiBody(objectName, attributes, relationships, externalID) {
-        const jsonApiType = WICKET_JSONAPI_TYPES[objectName] ?? objectName;
-        const data = {
-            type: jsonApiType,
-            attributes: this.StripSystemFields(attributes),
-        };
-        if (externalID) {
-            data['id'] = externalID;
-        }
-        if (relationships && Object.keys(relationships).length > 0) {
-            data['relationships'] = relationships;
-        }
-        return { data };
-    }
-    /** Removes system-managed fields from attributes before sending to Wicket. */
-    StripSystemFields(attributes) {
-        const systemFields = new Set(['uuid', 'id', 'created_at', 'updated_at', 'slug']);
-        const cleaned = {};
-        for (const [key, value] of Object.entries(attributes)) {
-            if (!systemFields.has(key)) {
-                cleaned[key] = value;
-            }
-        }
-        return cleaned;
-    }
-    /** Builds the POST body for a Wicket /query search endpoint. */
-    BuildSearchQueryBody(options) {
-        const body = {
-            filter: options.Filters,
-            page: {
-                number: options.Page ?? 1,
-                size: options.PageSize ?? DEFAULT_PAGE_SIZE,
-            },
-        };
-        if (options.Sort) {
-            body['sort'] = options.Sort;
-        }
-        return body;
-    }
-    // ─── Response Parsers ────────────────────────────────────────────
-    /**
-     * Flattens a JSON:API record from the nested format:
-     * ```json
-     * { "id": "uuid", "type": "people", "attributes": { "given_name": "John", ... }, "relationships": {...} }
-     * ```
-     * into a flat object with all attributes at the top level plus `uuid` and `type`.
-     */
-    FlattenJsonApiRecord(record) {
-        const attributes = record['attributes'];
-        const result = {};
-        // Add flattened attributes first
-        if (attributes) {
-            for (const [key, value] of Object.entries(attributes)) {
-                result[key] = value;
-            }
-        }
-        // Add system fields
-        result['uuid'] = record['id'];
-        result['type'] = record['type'];
-        // Extract relationship IDs for easy access
-        this.FlattenRelationships(record, result);
-        return result;
-    }
-    /**
-     * Extracts relationship IDs from JSON:API relationships and adds them as flat fields.
-     * E.g., `relationships.person.data.id` becomes `person_id` on the flat record.
-     */
-    FlattenRelationships(record, target) {
-        const relationships = record['relationships'];
-        if (!relationships)
-            return;
-        for (const [relName, relData] of Object.entries(relationships)) {
-            const rel = relData;
-            if (!rel?.['data'])
-                continue;
-            const data = rel['data'];
-            if (Array.isArray(data)) {
-                // Has-many: store as array of IDs
-                target[`${relName}_ids`] = data.map(d => d['id']);
-            }
-            else {
-                // Belongs-to: store as single ID
-                const belongsTo = data;
-                target[`${relName}_id`] = belongsTo['id'];
-            }
-        }
-    }
-    /** Parses a CRUD operation response into a WicketCRUDResult. */
-    ParseCRUDResponse(response, operation, objectName) {
-        const success = response.Status >= 200 && response.Status < 300;
-        if (!success) {
-            const bodyPreview = this.FormatBodyPreview(response.Body);
-            return {
-                Success: false,
-                ErrorMessage: `Wicket ${operation} failed with status ${response.Status}: ${bodyPreview}`,
-                StatusCode: response.Status,
-            };
-        }
-        // Extract the created/updated record ID from the response
-        const body = response.Body;
-        const data = body['data'];
-        const externalID = data?.['id'];
-        // CREATE-ONLY: a 2xx create with no record ID is a silent record-loss bug (duplicate
-        // creates on the next sync). Fail loudly via the base helper. Update/Delete are unchanged —
-        // they legitimately may not echo an ID in the body.
-        if (operation === 'create') {
-            return this.BuildCreatedResult(externalID, response.Status, objectName ?? 'record');
-        }
-        return {
-            Success: true,
-            ExternalID: externalID,
-            StatusCode: response.Status,
-        };
-    }
-    /** Parses a search response into a WicketSearchResult. */
-    ParseSearchResponse(response, objectName) {
-        if (response.Status < 200 || response.Status >= 300) {
-            const bodyPreview = this.FormatBodyPreview(response.Body);
-            throw new Error(`Wicket search failed with status ${response.Status}: ${bodyPreview}`);
-        }
-        const body = response.Body;
-        const records = this.NormalizeResponse(body, 'data');
-        const meta = body['meta'];
-        const pageInfo = meta?.['page'];
-        const totalCount = pageInfo?.total_count ?? records.length;
-        const currentPage = pageInfo?.number ?? 1;
-        const pageSize = pageInfo?.size ?? DEFAULT_PAGE_SIZE;
-        const totalPages = Math.ceil(totalCount / pageSize);
-        return {
-            Records: records.map(r => ({
-                ExternalID: String(r['uuid'] ?? ''),
-                ObjectType: objectName,
-                Fields: r,
-            })),
-            TotalCount: totalCount,
-            HasMore: currentPage < totalPages,
-        };
-    }
-    // ─── Validation ──────────────────────────────────────────────────
-    /** Throws if the object does not support write operations. */
-    ValidateWriteAllowed(objectName) {
-        if (IMMUTABLE_OBJECTS.has(objectName)) {
-            throw new Error(`Write operations are not allowed on "${objectName}". ` +
-                `Touchpoints are immutable audit trail records.`);
-        }
-    }
-    /** Throws if the object does not support delete operations. */
-    ValidateDeleteAllowed(objectName) {
-        // Touchpoints and resource_tags typically don't support delete
-        const nonDeletable = new Set(['touchpoints', 'resource_tags']);
-        if (nonDeletable.has(objectName)) {
-            throw new Error(`Delete operations are not supported for "${objectName}".`);
-        }
-    }
-    // ─── URL Helpers ─────────────────────────────────────────────────
-    /**
-     * Resolves the API path for a given Wicket object name.
-     * Handles top-level and nested (contact info) objects.
-     */
-    ResolveObjectAPIPath(objectName) {
-        // Contact info objects nested under people
-        if (objectName === 'people_emails')
-            return '/people';
-        if (objectName === 'people_phones')
-            return '/people';
-        if (objectName === 'people_addresses')
-            return '/people';
-        if (objectName === 'org_emails')
-            return '/organizations';
-        if (objectName === 'org_phones')
-            return '/organizations';
-        if (objectName === 'org_addresses')
-            return '/organizations';
-        // For direct CRUD, emails/phones/addresses use their direct endpoints
-        if (objectName === 'emails' || objectName === 'phones' || objectName === 'addresses') {
-            return `/${objectName}`;
-        }
-        // Top-level objects
-        return `/${objectName}`;
-    }
-    // ─── HTTP Helpers ────────────────────────────────────────────────
-    /** Ensures minimum interval between API requests to avoid rate limiting. */
-    async ThrottleRequest() {
-        const elapsed = Date.now() - this.lastRequestTime;
-        if (elapsed < MIN_REQUEST_INTERVAL_MS) {
-            await this.Sleep(MIN_REQUEST_INTERVAL_MS - elapsed);
-        }
-    }
-    /** Executes an HTTP request with a timeout and optional body. */
-    async FetchWithTimeout(url, method, headers, body) {
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
-        const fetchOptions = {
-            method,
-            headers,
-            signal: controller.signal,
-        };
-        if (body && (method === 'POST' || method === 'PATCH' || method === 'PUT')) {
-            fetchOptions.body = JSON.stringify(body);
-        }
-        try {
-            return await fetch(url, fetchOptions);
-        }
-        catch (err) {
-            if (err instanceof Error && err.name === 'AbortError') {
-                throw new Error(`Wicket API request timed out after ${REQUEST_TIMEOUT_MS / 1000}s: ${url}`);
-            }
-            throw err;
-        }
-        finally {
-            clearTimeout(timeoutId);
-        }
-    }
-    /** Safely parses a response body as JSON, falling back to text. */
-    async ParseResponseBody(response) {
-        const contentType = response.headers.get('content-type') ?? '';
-        if (contentType.includes('json')) {
-            return response.json();
-        }
-        return response.text();
-    }
-    /** Calculates retry delay from Retry-After header or exponential backoff. */
-    CalculateRetryDelay(response, attempt) {
-        const retryAfter = response.headers.get('retry-after');
-        if (retryAfter) {
-            const parsed = parseInt(retryAfter, 10);
-            if (!isNaN(parsed) && parsed > 0)
-                return parsed * 1000;
-        }
-        return Math.min(1000 * Math.pow(2, attempt), 30000);
-    }
-    /** Converts a fetch Response + parsed body into a RESTResponse. */
-    BuildRESTResponse(response, body) {
-        const headers = {};
-        response.headers.forEach((v, k) => { headers[k.toLowerCase()] = v; });
-        return { Status: response.status, Body: body, Headers: headers };
-    }
-    /** Formats a response body as a truncated string for error messages. */
-    FormatBodyPreview(body) {
-        if (typeof body === 'string')
-            return body.slice(0, 500);
-        return JSON.stringify(body).slice(0, 500);
-    }
-    /** Builds a WicketCRUDResult from a caught error. */
-    BuildCRUDError(err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return { Success: false, ErrorMessage: message, StatusCode: 0 };
-    }
-    /** Returns a promise that resolves after the specified number of milliseconds. */
-    Sleep(ms) {
-        return new Promise(resolve => setTimeout(resolve, ms));
-    }
-};
-WicketConnector = __decorate([
-    RegisterClass(BaseIntegrationConnector, 'WicketConnector')
-], WicketConnector);
-export { WicketConnector };
-//# sourceMappingURL=WicketConnector.js.map