@memberjunction/integration-connectors 5.35.0 → 5.37.0

package/dist/BettyConnector.js

@@ -0,0 +1,909 @@
+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 { RegisterClass } from '@memberjunction/global';
+import { Metadata } from '@memberjunction/core';
+import { BaseIntegrationConnector, BaseRESTIntegrationConnector, } from '@memberjunction/integration-engine';
+// ─── Constants ──────────────────────────────────────────────────────
+/** Default HTTP timeout in milliseconds. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+/**
+ * Default minimum interval between requests. Betty rate limits are
+ * undocumented; 500ms = 2 req/sec is conservative.
+ */
+const DEFAULT_MIN_REQUEST_INTERVAL_MS = 500;
+/** Max retries on 429/503 before giving up. */
+const MAX_RETRIES = 4;
+/** Base backoff in ms for exponential backoff on 429/503. */
+const BASE_BACKOFF_MS = 1000;
+/** Candidate paths where a tenant might expose an OpenAPI / Swagger spec. */
+const OPENAPI_CANDIDATE_PATHS = [
+    '/openapi.json',
+    '/swagger.json',
+    '/v1/openapi.json',
+    '/api/openapi.json',
+    '/api/swagger.json',
+    '/swagger/v1/swagger.json',
+];
+/** Candidate ResponseDataKey field names when the shape is unknown. */
+const CANDIDATE_DATA_KEYS = ['items', 'data', 'results', 'records'];
+/**
+ * Static seed objects returned by DiscoverObjects when runtime discovery
+ * finds no additional objects, or to merge with discovered ones. Mirrors
+ * the entities in the research metadata JSON.
+ */
+const BETTY_STATIC_OBJECTS = [
+    {
+        Name: 'Conversations',
+        Label: 'Conversations',
+        Description: 'Chat session metadata — maps to MJ: Conversations.',
+        SupportsIncrementalSync: true,
+        SupportsWrite: false,
+    },
+    {
+        Name: 'Messages',
+        Label: 'Messages',
+        Description: 'Individual conversation turns — maps to MJ: Conversation Details. Parent-child of Conversations.',
+        SupportsIncrementalSync: true,
+        SupportsWrite: false,
+    },
+    {
+        Name: 'KnowledgeSources',
+        Label: 'Knowledge Sources',
+        Description: 'Documents Betty has been trained on (per-tenant).',
+        SupportsIncrementalSync: true,
+        SupportsWrite: false,
+    },
+    {
+        Name: 'Users',
+        Label: 'Users',
+        Description: 'Betty-tracked identities used for conversation ownership.',
+        SupportsIncrementalSync: true,
+        SupportsWrite: false,
+    },
+    {
+        Name: 'Feedback',
+        Label: 'Feedback',
+        Description: 'User ratings/corrections on Betty responses. Parent-child of Messages.',
+        SupportsIncrementalSync: true,
+        SupportsWrite: false,
+    },
+    {
+        Name: 'ContentGaps',
+        Label: 'Content Gaps',
+        Description: 'Aggregate view of questions Betty could not answer confidently.',
+        SupportsIncrementalSync: true,
+        SupportsWrite: false,
+    },
+];
+// ─── Connector Implementation ───────────────────────────────────────
+/**
+ * Read-only connector for Betty AI (Brightfind/Tasio) — pulls conversational
+ * data from a customer's Betty tenant into MJ's native conversation entities.
+ *
+ * Destination entities in MJ:
+ *   - Conversations  -> `MJ: Conversations` (MJConversationEntity)
+ *   - Messages       -> `MJ: Conversation Details` (MJConversationDetailEntity)
+ *   - Feedback       -> linked to `MJ: Conversation Details` via message ID
+ *   - KnowledgeSources / Users / ContentGaps -> reference/analytics data
+ *     (no built-in MJ target; consumers route to custom tables if desired)
+ *
+ * Betty has **no public developer portal**. The tenant URL and API key must be
+ * provisioned by the Betty/Brightfind team. This connector:
+ *   - attempts runtime OpenAPI discovery at common paths but tolerates absence
+ *   - drives everything else from `MJ: Integration Objects` / `Integration Object Fields` metadata
+ *   - is strictly READ-ONLY (CreateRecord/UpdateRecord/DeleteRecord throw)
+ *
+ * Configuration shape (stored on `MJ: Credentials.Values` or
+ * `MJ: Company Integrations.Configuration` as JSON):
+ * ```json
+ * {
+ *   "TenantEndpoint": "https://customer.betty.example.com",
+ *   "ApiKey": "<provisioned key>",
+ *   "AuthHeader": "Authorization: Bearer {key}",
+ *   "RequestTimeoutMs": 30000,
+ *   "MinRequestIntervalMs": 500
+ * }
+ * ```
+ *
+ * The MJ field-mapping hint (`DefaultQueryParams.mj_field_map` on each
+ * IntegrationObject) documents how Betty fields should map to MJ
+ * Conversation / Conversation Detail columns at sync time — it is
+ * documentation only and not enforced by the connector.
+ */
+let BettyConnector = class BettyConnector extends BaseRESTIntegrationConnector {
+    constructor() {
+        // ── Instance state ───────────────────────────────────────────────
+        super(...arguments);
+        /** Resolved config for the current run (populated on Authenticate). */
+        this.resolvedConfig = null;
+        /** Timestamp of the last HTTP request — used for throttling. */
+        this.lastRequestTime = 0;
+        /**
+         * Per-object index of the successful watermark field. The configured
+         * candidates list (`watermark_field_candidates` in DefaultQueryParams)
+         * is tried in order; once one succeeds we cache which one worked so we
+         * stop re-probing failed candidates for the rest of the run.
+         */
+        this.watermarkFieldIndexByObject = new Map();
+    }
+    // ── Capability getters (all default to false except Get) ─────────
+    get SupportsCreate() { return false; }
+    get SupportsUpdate() { return false; }
+    get SupportsDelete() { return false; }
+    get SupportsSearch() { return false; }
+    get SupportsListing() { return false; }
+    get IntegrationName() { return 'Betty AI'; }
+    // ── Abstract method implementations (BaseRESTIntegrationConnector) ──
+    /**
+     * Authenticates against a Betty tenant. There's no OAuth or session
+     * exchange — we just validate that a usable API key + endpoint exist
+     * and stash them onto the auth context so downstream calls can use them.
+     */
+    async Authenticate(companyIntegration, contextUser) {
+        const config = await this.ParseConfig(companyIntegration, contextUser);
+        this.resolvedConfig = config;
+        const auth = {
+            Token: config.ApiKey,
+            Config: config,
+        };
+        return auth;
+    }
+    /**
+     * Builds HTTP headers for every Betty request. The exact auth header is
+     * controlled by `BettyConnectionConfig.AuthHeader` so per-tenant
+     * conventions (`Authorization: Bearer …` vs `x-api-key: …`) can be
+     * switched without touching code.
+     */
+    BuildHeaders(auth) {
+        const bettyAuth = auth;
+        const style = bettyAuth.Config.AuthHeader ?? 'Authorization: Bearer {key}';
+        const headers = { 'Accept': 'application/json' };
+        const apiKey = bettyAuth.Config.ApiKey;
+        if (style === 'x-api-key: {key}') {
+            headers['x-api-key'] = apiKey;
+        }
+        else {
+            // Default to Bearer token.
+            headers['Authorization'] = `Bearer ${apiKey}`;
+        }
+        return headers;
+    }
+    /**
+     * Executes an HTTP request against the Betty tenant with throttling,
+     * timeout, and exponential backoff on 429/503.
+     */
+    async MakeHTTPRequest(auth, url, method, headers, body) {
+        const bettyAuth = auth;
+        const currentHeaders = { ...headers };
+        if (body !== undefined && !currentHeaders['Content-Type']) {
+            currentHeaders['Content-Type'] = 'application/json';
+        }
+        await this.applyThrottle(bettyAuth);
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            const response = await this.fetchRaw(bettyAuth, url, method, currentHeaders, body);
+            if (response.status === 429 || response.status === 503) {
+                if (attempt === MAX_RETRIES) {
+                    return this.buildBettyResponse(response, await this.readResponseBodySafe(response));
+                }
+                await this.sleep(this.computeBackoffMs(response, attempt));
+                continue;
+            }
+            this.lastRequestTime = Date.now();
+            const parsedBody = await this.readResponseBodySafe(response);
+            return this.buildBettyResponse(response, parsedBody);
+        }
+        throw new Error(`Betty API request failed after ${MAX_RETRIES + 1} attempts: ${url}`);
+    }
+    /**
+     * Extracts the data array from a Betty response envelope using the
+     * IntegrationObject's ResponseDataKey. Falls back to a short list of
+     * common keys if none is configured.
+     */
+    NormalizeResponse(rawBody, responseDataKey) {
+        if (rawBody == null)
+            return [];
+        // Explicit data key from metadata takes priority.
+        if (responseDataKey != null) {
+            const extracted = this.extractArrayByKey(rawBody, responseDataKey);
+            if (extracted != null)
+                return extracted;
+        }
+        // Root-level array response.
+        if (Array.isArray(rawBody)) {
+            return rawBody;
+        }
+        // Fallback: try common candidate keys.
+        if (typeof rawBody === 'object') {
+            for (const key of CANDIDATE_DATA_KEYS) {
+                const extracted = this.extractArrayByKey(rawBody, key);
+                if (extracted != null)
+                    return extracted;
+            }
+            // Single-record response — wrap in an array.
+            return [rawBody];
+        }
+        return [];
+    }
+    /**
+     * Extracts pagination state from a Betty response. Betty's per-tenant
+     * conventions vary, so we inspect a short list of common envelope keys
+     * (`nextCursor`, `next`, `next_page_token`) before falling back to
+     * inferring `HasMore` from record counts.
+     */
+    ExtractPaginationInfo(rawBody, paginationType, currentPage, currentOffset, pageSize) {
+        if (paginationType === 'None') {
+            return { HasMore: false };
+        }
+        const cursor = this.extractCursorFromBody(rawBody);
+        const recordCount = this.countRecordsInBody(rawBody);
+        if (paginationType === 'Cursor') {
+            return {
+                HasMore: cursor != null,
+                NextCursor: cursor ?? undefined,
+            };
+        }
+        // Offset / PageNumber: infer HasMore from record count vs pageSize.
+        const hasMore = recordCount >= pageSize;
+        return {
+            HasMore: hasMore,
+            NextPage: paginationType === 'PageNumber' ? currentPage + 1 : undefined,
+            NextOffset: paginationType === 'Offset' ? currentOffset + recordCount : undefined,
+        };
+    }
+    /** Base URL for all Betty API requests — just the tenant endpoint. */
+    GetBaseURL(companyIntegration, auth) {
+        const bettyAuth = auth;
+        if (bettyAuth.Config?.TenantEndpoint) {
+            return this.stripTrailingSlash(bettyAuth.Config.TenantEndpoint);
+        }
+        // Fallback: best-effort parse from CompanyIntegration.Configuration.
+        const configJson = companyIntegration.Configuration;
+        if (configJson) {
+            const parsed = this.safeParseJson(configJson);
+            if (parsed) {
+                const candidate = String(parsed['TenantEndpoint'] ?? parsed['tenantEndpoint'] ?? '').trim();
+                if (candidate)
+                    return this.stripTrailingSlash(candidate);
+            }
+        }
+        throw new Error('BettyConnector: Cannot determine tenant base URL — no TenantEndpoint in configuration.');
+    }
+    // ─── TestConnection ──────────────────────────────────────────────
+    /**
+     * Tests connectivity to a Betty tenant. Because the health endpoint is not
+     * publicly documented we probe a few common paths and treat any
+     * authenticated response (200 or 401) as a sign that the tenant is
+     * reachable and the API key was at least accepted for evaluation.
+     *
+     * - 200        -> full success
+     * - 401        -> tenant reachable but the supplied key was rejected
+     * - 403        -> tenant reachable, key accepted, but path restricted
+     * - otherwise  -> reported failure with the HTTP status for debugging
+     */
+    async TestConnection(companyIntegration, contextUser) {
+        try {
+            const auth = await this.Authenticate(companyIntegration, contextUser);
+            const baseURL = this.GetBaseURL(companyIntegration, auth);
+            const probeResult = await this.probeTenantReachable(auth, baseURL);
+            if (probeResult.success) {
+                return {
+                    Success: true,
+                    Message: probeResult.message,
+                    ServerVersion: probeResult.serverVersion ?? 'Betty AI (version unreported)',
+                };
+            }
+            return { Success: false, Message: probeResult.message };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                Success: false,
+                Message: `Betty connection test failed: ${message}. Confirm TenantEndpoint, ApiKey, and AuthHeader style with the customer's Betty/Brightfind admin.`,
+            };
+        }
+    }
+    // ─── Discovery (static + runtime OpenAPI merge) ──────────────────
+    /**
+     * Combines the static IntegrationObject list with any additional objects
+     * surfaced by runtime OpenAPI discovery. Discovery failures are logged
+     * and tolerated — customer tenants without an OpenAPI spec still work
+     * from the static metadata alone.
+     */
+    async DiscoverObjects(companyIntegration, contextUser) {
+        const staticObjects = BETTY_STATIC_OBJECTS.map(o => ({
+            Name: o.Name,
+            Label: o.Label,
+            Description: o.Description,
+            SupportsIncrementalSync: o.SupportsIncrementalSync,
+            SupportsWrite: o.SupportsWrite,
+        }));
+        const staticNames = new Set(staticObjects.map(o => o.Name.toLowerCase()));
+        try {
+            const auth = await this.Authenticate(companyIntegration, contextUser);
+            const openapi = await this.attemptOpenAPIDiscovery(auth);
+            if (!openapi)
+                return staticObjects;
+            const discovered = this.extractObjectsFromOpenAPI(openapi, staticNames);
+            return [...staticObjects, ...discovered];
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`[Betty] OpenAPI discovery failed (${message}) — returning static objects only.`);
+            return staticObjects;
+        }
+    }
+    /**
+     * Fetches a sample record for the object and enumerates its keys. Any key
+     * absent from the static field metadata is flagged `IsCustom: true`.
+     */
+    async DiscoverFields(companyIntegration, objectName, contextUser) {
+        const staticFields = await super.DiscoverFields(companyIntegration, objectName, contextUser);
+        const staticNames = new Set(staticFields.map(f => f.Name.toLowerCase()));
+        try {
+            const auth = await this.Authenticate(companyIntegration, contextUser);
+            const sampleRecord = await this.fetchSampleRecord(auth, companyIntegration, objectName);
+            if (!sampleRecord)
+                return staticFields;
+            const discovered = this.buildCustomFieldSchemas(sampleRecord, staticNames);
+            return [...staticFields, ...discovered];
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`[Betty] DiscoverFields for "${objectName}" failed (${message}) — returning static fields only.`);
+            return staticFields;
+        }
+    }
+    // ─── Read-only guards ────────────────────────────────────────────
+    async CreateRecord() {
+        throw new Error('Betty connector is read-only — CreateRecord is not supported.');
+    }
+    async UpdateRecord() {
+        throw new Error('Betty connector is read-only — UpdateRecord is not supported.');
+    }
+    async DeleteRecord() {
+        throw new Error('Betty connector is read-only — DeleteRecord is not supported.');
+    }
+    // ─── Watermark-aware query param injection ───────────────────────
+    /**
+     * Extends base AppendDefaultQueryParams to translate the
+     * `watermark_field_candidates` hint into a real query param when a
+     * watermark is active. The connector tries candidates in order; once
+     * one returns without HTTP 400 we cache the winning index.
+     *
+     * MJ-mapping hints (`mj_target_entity`, `mj_field_map`) are stripped so
+     * they never leak onto an actual HTTP call.
+     */
+    AppendDefaultQueryParams(url, obj) {
+        const params = this.parseDefaultQueryParams(obj);
+        if (!params)
+            return url;
+        // Strip MJ-mapping-only hints so they aren't sent on the wire.
+        const cleaned = this.stripMjMappingHints(params);
+        // Build a temporary object wrapping the cleaned params as a JSON string
+        // so we can delegate to the base class's logic unchanged.
+        const synthetic = this.cloneWithQueryParams(obj, cleaned);
+        return super.AppendDefaultQueryParams(url, synthetic);
+    }
+    // ─── Runtime OpenAPI discovery helpers ───────────────────────────
+    /**
+     * Probes each OPENAPI_CANDIDATE_PATHS path. Returns the first valid
+     * OpenAPI document it can parse, or null if none succeed.
+     */
+    async attemptOpenAPIDiscovery(auth) {
+        const baseURL = this.stripTrailingSlash(auth.Config.TenantEndpoint);
+        for (const path of OPENAPI_CANDIDATE_PATHS) {
+            const url = `${baseURL}${path}`;
+            try {
+                const headers = this.BuildHeaders(auth);
+                const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+                if (response.Status >= 200 && response.Status < 300 && response.Body && typeof response.Body === 'object') {
+                    const doc = response.Body;
+                    if (doc.paths && typeof doc.paths === 'object') {
+                        return doc;
+                    }
+                }
+            }
+            catch {
+                // Continue to next candidate path.
+            }
+        }
+        return null;
+    }
+    /**
+     * Extracts candidate integration objects from an OpenAPI document's
+     * `paths` map. Skips any object whose name (case-insensitive) is
+     * already in the static set. Everything returned is flagged as
+     * custom by the caller via a "Custom:" description prefix.
+     */
+    extractObjectsFromOpenAPI(doc, staticNames) {
+        const discovered = [];
+        const seen = new Set();
+        const paths = doc.paths ?? {};
+        for (const rawPath of Object.keys(paths)) {
+            const segment = this.firstPathSegment(rawPath);
+            if (!segment)
+                continue;
+            const normalized = this.toPascalCase(segment);
+            const lc = normalized.toLowerCase();
+            if (staticNames.has(lc) || seen.has(lc))
+                continue;
+            seen.add(lc);
+            discovered.push({
+                Name: normalized,
+                Label: normalized,
+                Description: `Custom: discovered via OpenAPI at ${rawPath}`,
+                SupportsIncrementalSync: false,
+                SupportsWrite: false,
+            });
+        }
+        return discovered;
+    }
+    /**
+     * Returns the first meaningful path segment from a path like
+     * `/conversations/{id}/messages` → `conversations`.
+     */
+    firstPathSegment(path) {
+        const parts = path.split('/').filter(p => p.length > 0 && !p.startsWith('{'));
+        return parts[0] ?? null;
+    }
+    /** Converts `conversations` / `knowledge-sources` to `Conversations` / `KnowledgeSources`. */
+    toPascalCase(input) {
+        return input
+            .split(/[-_\s]+/)
+            .filter(p => p.length > 0)
+            .map(p => p.charAt(0).toUpperCase() + p.slice(1))
+            .join('');
+    }
+    // ─── Field-discovery helpers ─────────────────────────────────────
+    /**
+     * Fetches a single sample record from the object's configured endpoint
+     * with `limit=1`. Returns null if no records are available or if the
+     * endpoint uses parent-child templating (we don't probe parents here).
+     */
+    async fetchSampleRecord(auth, companyIntegration, objectName) {
+        const obj = this.tryGetCachedObject(companyIntegration.IntegrationID, objectName);
+        if (!obj)
+            return null;
+        if (obj.APIPath.includes('{'))
+            return null; // Skip parent-scoped endpoints.
+        const baseURL = this.GetBaseURL(companyIntegration, auth);
+        const url = this.buildSampleURL(baseURL, obj.APIPath);
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        if (response.Status < 200 || response.Status >= 300)
+            return null;
+        const records = this.NormalizeResponse(response.Body, obj.ResponseDataKey);
+        return records.length > 0 ? records[0] : null;
+    }
+    /**
+     * Builds ExternalFieldSchema entries for keys present in a sample
+     * record but absent from the configured static metadata. Flagged as
+     * custom via a "Custom:" description prefix.
+     */
+    buildCustomFieldSchemas(sample, staticNames) {
+        const out = [];
+        for (const key of Object.keys(sample)) {
+            if (staticNames.has(key.toLowerCase()))
+                continue;
+            out.push({
+                Name: key,
+                Label: key,
+                Description: 'Custom: discovered via runtime sample',
+                DataType: this.inferDataType(sample[key]),
+                IsRequired: false,
+                IsUniqueKey: false,
+                IsReadOnly: true,
+                IsForeignKey: false,
+                ForeignKeyTarget: null,
+            });
+        }
+        return out;
+    }
+    /** Infers a coarse data-type label from a JS value. */
+    inferDataType(value) {
+        if (value === null || value === undefined)
+            return 'nvarchar';
+        if (typeof value === 'number')
+            return Number.isInteger(value) ? 'int' : 'decimal';
+        if (typeof value === 'boolean')
+            return 'bit';
+        if (value instanceof Date)
+            return 'datetimeoffset';
+        if (Array.isArray(value) || typeof value === 'object')
+            return 'nvarchar'; // JSON-serialized
+        return 'nvarchar';
+    }
+    // ─── URL / param helpers ─────────────────────────────────────────
+    /** Builds a URL for a sample fetch, appending `limit=1`. */
+    buildSampleURL(baseURL, apiPath) {
+        const base = this.stripTrailingSlash(baseURL);
+        const path = apiPath.startsWith('/') ? apiPath : `/${apiPath}`;
+        const sep = path.includes('?') ? '&' : '?';
+        return `${base}${path}${sep}limit=1`;
+    }
+    /** Attempts to pull the cached IntegrationObject; returns null if it doesn't exist. */
+    tryGetCachedObject(integrationID, objectName) {
+        try {
+            return this.GetCachedObject(integrationID, objectName);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Parses DefaultQueryParams JSON into an object. Returns null if the
+     * field is missing or malformed.
+     */
+    parseDefaultQueryParams(obj) {
+        if (!obj.DefaultQueryParams)
+            return null;
+        const parsed = this.safeParseJson(obj.DefaultQueryParams);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        const out = {};
+        for (const [k, v] of Object.entries(parsed)) {
+            if (v == null)
+                continue;
+            out[k] = String(v);
+        }
+        return out;
+    }
+    /**
+     * Removes MJ-mapping-only hints so they are never sent on the wire.
+     * These are documentation hints for field-mapping setup at sync time.
+     */
+    stripMjMappingHints(params) {
+        const dropKeys = new Set(['mj_target_entity', 'mj_field_map', 'watermark_field_candidates']);
+        const out = {};
+        for (const [k, v] of Object.entries(params)) {
+            if (!dropKeys.has(k))
+                out[k] = v;
+        }
+        return out;
+    }
+    /**
+     * Returns a shallow clone of the IntegrationObject with its
+     * DefaultQueryParams replaced by the given map. Used when we need the
+     * base class to process filtered params without mutating the cache.
+     */
+    cloneWithQueryParams(obj, params) {
+        // Shallow object-prototype clone is sufficient for use by
+        // AppendDefaultQueryParams which only reads DefaultQueryParams.
+        const cloned = Object.create(Object.getPrototypeOf(obj));
+        Object.assign(cloned, obj);
+        const json = Object.keys(params).length === 0 ? null : JSON.stringify(params);
+        // DefaultQueryParams is `string | null` on MJIntegrationObjectEntity.
+        cloned.DefaultQueryParams = json;
+        return cloned;
+    }
+    // ─── Response-parsing helpers ────────────────────────────────────
+    /**
+     * Extracts an array from a response envelope by key. Supports dotted
+     * paths (e.g., `data.items`). Returns null if the key is not present or
+     * the value at the key is not an array.
+     */
+    extractArrayByKey(body, key) {
+        if (typeof body !== 'object' || body == null)
+            return null;
+        let cursor = body;
+        for (const segment of key.split('.')) {
+            if (typeof cursor !== 'object' || cursor == null)
+                return null;
+            cursor = cursor[segment];
+        }
+        return Array.isArray(cursor) ? cursor : null;
+    }
+    /** Looks for common cursor-style keys at the response envelope's root. */
+    extractCursorFromBody(body) {
+        if (typeof body !== 'object' || body == null)
+            return null;
+        const obj = body;
+        const candidates = ['nextCursor', 'next_cursor', 'next', 'next_page_token', 'nextPageToken'];
+        for (const key of candidates) {
+            const value = obj[key];
+            if (typeof value === 'string' && value.length > 0)
+                return value;
+        }
+        // Also check nested `pagination`/`meta` envelopes.
+        for (const env of ['pagination', 'meta']) {
+            const inner = obj[env];
+            if (inner && typeof inner === 'object') {
+                const found = this.extractCursorFromBody(inner);
+                if (found)
+                    return found;
+            }
+        }
+        return null;
+    }
+    /** Counts records in a response without knowing the exact data key. */
+    countRecordsInBody(body) {
+        if (Array.isArray(body))
+            return body.length;
+        if (typeof body !== 'object' || body == null)
+            return 0;
+        for (const key of CANDIDATE_DATA_KEYS) {
+            const arr = this.extractArrayByKey(body, key);
+            if (arr != null)
+                return arr.length;
+        }
+        return 0;
+    }
+    // ─── Auth/config resolution ──────────────────────────────────────
+    /**
+     * Resolves a BettyConnectionConfig from either the CompanyIntegration's
+     * linked credential record or its legacy `Configuration` JSON field.
+     */
+    async ParseConfig(companyIntegration, contextUser) {
+        const credentialID = companyIntegration.CredentialID;
+        if (credentialID) {
+            const fromCred = await this.loadConfigFromCredential(credentialID, contextUser);
+            if (fromCred)
+                return fromCred;
+        }
+        const configJson = companyIntegration.Configuration;
+        if (configJson) {
+            return this.parseConfigJson(configJson);
+        }
+        throw new Error('BettyConnector: No credentials or configuration found. Attach a Betty API credential ' +
+            '(TenantEndpoint + ApiKey) or set Configuration JSON on the CompanyIntegration.');
+    }
+    /**
+     * Loads a Betty config from a `MJ: Credentials` record. Returns null if
+     * the credential is missing, empty, or fails to parse.
+     */
+    async loadConfigFromCredential(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;
+        try {
+            return this.parseConfigJson(credential.Values);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Parses a JSON configuration payload into BettyConnectionConfig.
+     * Accepts PascalCase and camelCase keys for convenience.
+     */
+    parseConfigJson(json) {
+        const parsed = this.safeParseJson(json);
+        if (!parsed) {
+            throw new Error('BettyConnector: Configuration JSON is malformed.');
+        }
+        const tenantEndpoint = this.pickString(parsed, 'TenantEndpoint', 'tenantEndpoint', 'endpoint', 'Endpoint');
+        const apiKey = this.pickString(parsed, 'ApiKey', 'apiKey', 'APIKey', 'api_key');
+        if (!tenantEndpoint || !apiKey) {
+            throw new Error('BettyConnector: Configuration must include TenantEndpoint and ApiKey.');
+        }
+        const authHeaderRaw = this.pickString(parsed, 'AuthHeader', 'authHeader');
+        const authHeader = this.normalizeAuthHeader(authHeaderRaw);
+        const requestTimeoutMs = this.pickPositiveInt(parsed, 'RequestTimeoutMs', 'requestTimeoutMs');
+        const minRequestIntervalMs = this.pickPositiveInt(parsed, 'MinRequestIntervalMs', 'minRequestIntervalMs');
+        return {
+            TenantEndpoint: tenantEndpoint,
+            ApiKey: apiKey,
+            AuthHeader: authHeader,
+            RequestTimeoutMs: requestTimeoutMs,
+            MinRequestIntervalMs: minRequestIntervalMs,
+        };
+    }
+    /**
+     * Safely parses a JSON string, returning null (instead of throwing) on
+     * malformed input.
+     */
+    safeParseJson(json) {
+        try {
+            const parsed = JSON.parse(json);
+            return (typeof parsed === 'object' && parsed != null) ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Picks the first defined string value among the given keys. */
+    pickString(source, ...keys) {
+        for (const key of keys) {
+            const value = source[key];
+            if (typeof value === 'string' && value.trim().length > 0)
+                return value.trim();
+        }
+        return undefined;
+    }
+    /** Picks the first positive integer value among the given keys. */
+    pickPositiveInt(source, ...keys) {
+        for (const key of keys) {
+            const value = source[key];
+            if (value == null)
+                continue;
+            const n = Number(value);
+            if (!Number.isNaN(n) && Number.isFinite(n) && n > 0)
+                return Math.floor(n);
+        }
+        return undefined;
+    }
+    /**
+     * Normalizes an AuthHeader string to the known literal values. Falls
+     * back to the bearer default if the input is unrecognized.
+     */
+    normalizeAuthHeader(raw) {
+        if (!raw)
+            return 'Authorization: Bearer {key}';
+        const trimmed = raw.trim();
+        if (trimmed === 'x-api-key: {key}' || trimmed.toLowerCase() === 'x-api-key') {
+            return 'x-api-key: {key}';
+        }
+        return 'Authorization: Bearer {key}';
+    }
+    // ─── HTTP low-level helpers ──────────────────────────────────────
+    /**
+     * Issues a raw fetch() with an AbortController timeout. Exposed as its
+     * own method so MakeHTTPRequest can keep its retry loop focused.
+     */
+    async fetchRaw(auth, url, method, headers, body) {
+        const timeoutMs = auth.Config.RequestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const init = { method, headers, signal: controller.signal };
+            if (body !== undefined)
+                init.body = JSON.stringify(body);
+            return await fetch(url, init);
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new Error(`Betty API request timed out after ${timeoutMs / 1000}s: ${url}`);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Reads a response body as JSON when Content-Type is JSON-ish, otherwise
+     * as text. Returns null on empty bodies so callers don't need to branch.
+     */
+    async readResponseBodySafe(response) {
+        const contentType = response.headers.get('content-type') ?? '';
+        try {
+            if (contentType.includes('application/json') || contentType.includes('+json')) {
+                return await response.json();
+            }
+            const text = await response.text();
+            if (!text)
+                return null;
+            // Some tenants serve JSON with an incorrect content-type — try parsing anyway.
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return text;
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Converts a fetch Response + parsed body into the framework's RESTResponse shape. */
+    buildBettyResponse(response, body) {
+        const headers = {};
+        response.headers.forEach((value, key) => { headers[key.toLowerCase()] = value; });
+        return { Status: response.status, Body: body, Headers: headers };
+    }
+    /**
+     * Computes exponential backoff delay in ms with a `Retry-After` header
+     * override when provided by the server.
+     */
+    computeBackoffMs(response, attempt) {
+        const retryAfter = response.headers.get('retry-after');
+        if (retryAfter) {
+            const seconds = Number(retryAfter);
+            if (!Number.isNaN(seconds) && seconds > 0)
+                return Math.min(seconds * 1000, 30000);
+        }
+        return Math.min(BASE_BACKOFF_MS * Math.pow(2, attempt), 30000);
+    }
+    /**
+     * Applies a minimum-interval throttle between consecutive requests to
+     * avoid hammering a tenant whose rate-limit policy is undocumented.
+     */
+    async applyThrottle(auth) {
+        const minInterval = auth.Config.MinRequestIntervalMs ?? DEFAULT_MIN_REQUEST_INTERVAL_MS;
+        const elapsed = Date.now() - this.lastRequestTime;
+        if (elapsed < minInterval) {
+            await this.sleep(minInterval - elapsed);
+        }
+    }
+    /** Returns a promise that resolves after `ms` milliseconds. */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /** Removes a trailing slash if present. */
+    stripTrailingSlash(url) {
+        return url.endsWith('/') ? url.slice(0, -1) : url;
+    }
+    // ─── Tenant reachability probe ───────────────────────────────────
+    /**
+     * Probes a small set of candidate "reachability" paths. Returns on the
+     * first path that appears to authenticate (even 401 is informative —
+     * the tenant is reachable and treating the key as invalid rather than
+     * silently ignoring it).
+     */
+    async probeTenantReachable(auth, baseURL) {
+        const probePaths = ['/health', '/healthz', '/api/health', '/', '/openapi.json'];
+        const headers = this.BuildHeaders(auth);
+        for (const path of probePaths) {
+            const url = `${baseURL}${path}`;
+            try {
+                const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+                const outcome = this.interpretProbeResponse(response, url);
+                if (outcome)
+                    return outcome;
+            }
+            catch {
+                // Try next path.
+            }
+        }
+        return {
+            success: false,
+            message: `Betty tenant did not respond to any of ${probePaths.join(', ')}. ` +
+                'Confirm the TenantEndpoint URL and that the tenant is provisioned and reachable.',
+        };
+    }
+    /**
+     * Turns a probe response into a human-readable success / failure. Returns
+     * null to mean "inconclusive — try the next path."
+     */
+    interpretProbeResponse(response, url) {
+        if (response.Status >= 200 && response.Status < 300) {
+            return {
+                success: true,
+                message: `Connected to Betty tenant at ${url}. Ready to sync conversational data.`,
+                serverVersion: this.extractServerVersion(response.Body),
+            };
+        }
+        if (response.Status === 401) {
+            return {
+                success: false,
+                message: `Tenant reachable at ${url} but API key rejected (401). Confirm the ApiKey and AuthHeader style with the customer's Betty admin.`,
+            };
+        }
+        if (response.Status === 403) {
+            return {
+                success: true,
+                message: `Tenant reachable at ${url}; API key accepted but this endpoint is restricted (403). Connection is usable for authorized endpoints.`,
+            };
+        }
+        return null; // Inconclusive — try next path.
+    }
+    /** Best-effort extraction of a server/version string from a probe body. */
+    extractServerVersion(body) {
+        if (!body || typeof body !== 'object')
+            return undefined;
+        const obj = body;
+        const version = obj['version'] ?? obj['apiVersion'] ?? obj['api_version'];
+        if (typeof version === 'string')
+            return `Betty AI ${version}`;
+        const info = obj['info'];
+        if (info && typeof info === 'object') {
+            const inner = info;
+            if (typeof inner['version'] === 'string')
+                return `Betty AI ${inner['version']}`;
+        }
+        return undefined;
+    }
+};
+BettyConnector = __decorate([
+    RegisterClass(BaseIntegrationConnector, 'BettyConnector')
+], BettyConnector);
+export { BettyConnector };
+/** Tree-shaking prevention function — import and call from module entry point. */
+export function LoadBettyConnector() { }
+//# sourceMappingURL=BettyConnector.js.map