@memberjunction/integration-connectors 0.0.1 → 5.9.0

package/README.md

@@ -1,45 +1,124 @@
 # @memberjunction/integration-connectors
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+Concrete integration connectors for the MemberJunction Integration Engine. This package provides four connectors that implement `BaseIntegrationConnector` from `@memberjunction/integration-engine`.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+## Connectors
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+### RelationalDBConnector (Base Class)
 
-## Purpose
+Abstract base class for connectors that read from SQL Server databases via the `mssql` package. Provides shared logic for connection management, object/field discovery, and batched record fetching with watermark support.
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/integration-connectors`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+**Configuration JSON:**
+```json
+{
+  "server": "your-sql-server",
+  "database": "YourDatabase",
+  "user": "username",
+  "password": "password"
+}
+```
 
-## What is OIDC Trusted Publishing?
+**Shared capabilities:**
+- `TestConnection` — runs `SELECT @@VERSION` to verify connectivity
+- `DiscoverObjects` — queries `INFORMATION_SCHEMA.TABLES` for all base tables
+- `DiscoverFields` — queries `INFORMATION_SCHEMA.COLUMNS` for a given table
+- `FetchChangesFromTable` — parameterized incremental fetch with watermark filtering and batch limiting
+- Connection pool caching per server+database pair
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+### HubSpotConnector
 
-## Setup Instructions
+Reads from MockHubSpot database tables: `hs_Contacts`, `hs_Companies`, `hs_Deals`, `hs_Owners`.
 
-To properly configure OIDC trusted publishing for this package:
+**Registration:** `@RegisterClass(BaseIntegrationConnector, 'HubSpotConnector')`
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+**Default field mappings:**
+| Source Object | Target Entity | Mappings |
+|---|---|---|
+| `hs_Contacts` | Contacts | email→Email (key), firstname→FirstName, lastname→LastName, phone→Phone, company→CompanyName, lifecyclestage→Status |
+| `hs_Companies` | Companies | name→Name (key), domain→Website, industry→Industry, city→City, state→State |
+| `hs_Deals` | — | No default mappings |
 
-## DO NOT USE THIS PACKAGE
+**To swap for real HubSpot API:** Replace `RelationalDBConnector` with direct HTTP calls to the HubSpot V3 API. The `FetchChanges` method would use the HubSpot Search API with `lastmodifieddate` filters, and `Configuration` would store an API key or OAuth tokens instead of database credentials.
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+### SalesforceConnector
 
-## More Information
+Reads from MockSalesforce database tables: `sf_Contact`, `sf_Account`, `sf_Opportunity`, `sf_User`.
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+**Registration:** `@RegisterClass(BaseIntegrationConnector, 'SalesforceConnector')`
 
----
+**Default field mappings:**
+| Source Object | Target Entity | Mappings |
+|---|---|---|
+| `sf_Contact` | Contacts | Email→Email (key), FirstName→FirstName, LastName→LastName, Phone→Phone, Title→Title, Department→Department |
+| `sf_Account` | Companies | Name→Name (key), Industry→Industry, BillingCity→City, BillingState→State, Phone→Phone |
 
-**Maintained for OIDC setup purposes only**
+**To swap for real Salesforce API:** Replace `RelationalDBConnector` with `jsforce` or direct REST calls to the Salesforce SOQL API. Use `SystemModstamp` for watermarks and the Salesforce Bulk API for large datasets.
+
+### YourMembershipConnector
+
+Reads from MockYourMembership database tables: `ym_Members`, `ym_Events`, `ym_EventRegistrations`, `ym_Chapters`, `ym_MembershipLevels`.
+
+**Registration:** `@RegisterClass(BaseIntegrationConnector, 'YourMembershipConnector')`
+
+**Default field mappings:**
+| Source Object | Target Entity | Mappings |
+|---|---|---|
+| `ym_Members` | Contacts | email→Email (key), first_name→FirstName, last_name→LastName, phone→Phone, status→Status |
+
+### FileFeedConnector
+
+Reads data from local CSV files. Always performs a full load (no incremental sync support).
+
+**Registration:** `@RegisterClass(BaseIntegrationConnector, 'FileFeedConnector')`
+
+**Configuration JSON:**
+```json
+{
+  "storagePath": "/absolute/path/to/file.csv",
+  "fileType": "csv"
+}
+```
+
+**Capabilities:**
+- `TestConnection` — checks that the file exists on disk
+- `DiscoverObjects` — returns the file name as the single available object
+- `DiscoverFields` — parses the CSV header row
+- `FetchChanges` — parses all data rows into `ExternalRecord[]` (watermark is ignored)
+
+**CSV parsing rules:**
+- First row is treated as the header
+- Supports quoted fields with commas inside
+- Supports escaped quotes (`""`) inside quoted fields
+- Empty values are mapped to `null`
+
+## Building
+
+```bash
+cd packages/Integration/connectors
+npm run build
+```
+
+## Testing
+
+Tests are integration tests that connect to the mock SQL Server databases.
+
+```bash
+cd packages/Integration/connectors
+npm run test          # single run
+npm run test:watch    # watch mode
+```
+
+## Architecture
+
+```
+src/
+  index.ts                     # Package exports
+  RelationalDBConnector.ts     # Base class for SQL-based connectors
+  HubSpotConnector.ts          # HubSpot mock connector
+  SalesforceConnector.ts       # Salesforce mock connector
+  YourMembershipConnector.ts   # YourMembership mock connector
+  FileFeedConnector.ts         # CSV file connector
+  __tests__/                   # Integration tests
+test-fixtures/
+  sample-contacts.csv          # 100-row sample for FileFeed testing
+```

package/dist/FileFeedConnector.d.ts

@@ -0,0 +1,64 @@
+import type { UserInfo } from '@memberjunction/core';
+import type { MJCompanyIntegrationEntity } from '@memberjunction/core-entities';
+import { BaseIntegrationConnector, type ConnectionTestResult, type ExternalObjectSchema, type ExternalFieldSchema, type FetchContext, type FetchBatchResult } from '@memberjunction/integration-engine';
+/**
+ * Connector for file-based data feeds (CSV).
+ * Reads data from local CSV files. Always performs a full load (no incremental sync).
+ * Supports quoted fields with commas inside and empty values mapped to null.
+ */
+export declare class FileFeedConnector extends BaseIntegrationConnector {
+    /**
+     * Tests connectivity by checking that the configured file exists on disk.
+     * @param companyIntegration - The entity with Configuration JSON containing storagePath
+     * @param _contextUser - User context for authorization
+     * @returns Success if the file exists, failure otherwise
+     */
+    TestConnection(companyIntegration: MJCompanyIntegrationEntity, _contextUser: UserInfo): Promise<ConnectionTestResult>;
+    /**
+     * Discovers available objects by returning the file name as the single object.
+     * @param companyIntegration - The entity with Configuration JSON
+     * @param _contextUser - User context for authorization
+     * @returns Array with one entry for the configured file
+     */
+    DiscoverObjects(companyIntegration: MJCompanyIntegrationEntity, _contextUser: UserInfo): Promise<ExternalObjectSchema[]>;
+    /**
+     * Discovers fields by parsing the CSV header row.
+     * @param companyIntegration - The entity with Configuration JSON
+     * @param _objectName - Object name (file name), not used since we only have one file
+     * @param _contextUser - User context for authorization
+     * @returns Array of field schemas from the CSV header
+     */
+    DiscoverFields(companyIntegration: MJCompanyIntegrationEntity, _objectName: string, _contextUser: UserInfo): Promise<ExternalFieldSchema[]>;
+    /**
+     * Fetches all records from the CSV file as a full load.
+     * CSV files do not support incremental sync — watermark is ignored.
+     * @param ctx - Fetch context (watermark is always ignored for file feeds)
+     * @returns All records from the CSV file in a single batch
+     */
+    FetchChanges(ctx: FetchContext): Promise<FetchBatchResult>;
+    /**
+     * Parses the Configuration JSON to extract file feed settings.
+     * @param companyIntegration - The entity containing Configuration JSON
+     * @returns Parsed file feed configuration
+     */
+    private parseConfig;
+    /**
+     * Parses an array of CSV data lines into ExternalRecord objects.
+     * @param lines - CSV data lines (excluding header)
+     * @param headers - Column header names
+     * @param objectName - Object type name for the records
+     * @returns Array of ExternalRecord objects
+     */
+    private parseDataLines;
+}
+/**
+ * Parses a single CSV line handling quoted fields with commas.
+ * Supports:
+ * - Unquoted fields separated by commas
+ * - Quoted fields that may contain commas
+ * - Escaped quotes ("") inside quoted fields
+ * @param line - A single CSV line to parse
+ * @returns Array of field values
+ */
+export declare function parseCsvLine(line: string): string[];
+//# sourceMappingURL=FileFeedConnector.d.ts.map

package/dist/FileFeedConnector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileFeedConnector.d.ts","sourceRoot":"","sources":["../src/FileFeedConnector.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,EACH,wBAAwB,EACxB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAExB,MAAM,oCAAoC,CAAC;AAY5C;;;;GAIG;AACH,qBACa,iBAAkB,SAAQ,wBAAwB;IAC3D;;;;;OAKG;IACU,cAAc,CACvB,kBAAkB,EAAE,0BAA0B,EAC9C,YAAY,EAAE,QAAQ,GACvB,OAAO,CAAC,oBAAoB,CAAC;IAahC;;;;;OAKG;IACU,eAAe,CACxB,kBAAkB,EAAE,0BAA0B,EAC9C,YAAY,EAAE,QAAQ,GACvB,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAalC;;;;;;OAMG;IACU,cAAc,CACvB,kBAAkB,EAAE,0BAA0B,EAC9C,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,QAAQ,GACvB,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAmBjC;;;;;OAKG;IACU,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAcvE;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAiBnB;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;CAsBzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAqCnD"}

package/dist/FileFeedConnector.js

@@ -0,0 +1,190 @@
+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 { BaseIntegrationConnector, } from '@memberjunction/integration-engine';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Connector for file-based data feeds (CSV).
+ * Reads data from local CSV files. Always performs a full load (no incremental sync).
+ * Supports quoted fields with commas inside and empty values mapped to null.
+ */
+let FileFeedConnector = class FileFeedConnector extends BaseIntegrationConnector {
+    /**
+     * Tests connectivity by checking that the configured file exists on disk.
+     * @param companyIntegration - The entity with Configuration JSON containing storagePath
+     * @param _contextUser - User context for authorization
+     * @returns Success if the file exists, failure otherwise
+     */
+    async TestConnection(companyIntegration, _contextUser) {
+        try {
+            const config = this.parseConfig(companyIntegration);
+            if (!fs.existsSync(config.StoragePath)) {
+                return { Success: false, Message: `File not found: ${config.StoragePath}` };
+            }
+            return { Success: true, Message: `File exists: ${config.StoragePath}` };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { Success: false, Message: `Configuration error: ${message}` };
+        }
+    }
+    /**
+     * Discovers available objects by returning the file name as the single object.
+     * @param companyIntegration - The entity with Configuration JSON
+     * @param _contextUser - User context for authorization
+     * @returns Array with one entry for the configured file
+     */
+    async DiscoverObjects(companyIntegration, _contextUser) {
+        const config = this.parseConfig(companyIntegration);
+        const fileName = path.basename(config.StoragePath);
+        return [
+            {
+                Name: fileName,
+                Label: fileName,
+                SupportsIncrementalSync: false,
+                SupportsWrite: false,
+            },
+        ];
+    }
+    /**
+     * Discovers fields by parsing the CSV header row.
+     * @param companyIntegration - The entity with Configuration JSON
+     * @param _objectName - Object name (file name), not used since we only have one file
+     * @param _contextUser - User context for authorization
+     * @returns Array of field schemas from the CSV header
+     */
+    async DiscoverFields(companyIntegration, _objectName, _contextUser) {
+        const config = this.parseConfig(companyIntegration);
+        const content = fs.readFileSync(config.StoragePath, 'utf-8');
+        const firstLine = content.split('\n')[0]?.trim();
+        if (!firstLine) {
+            return [];
+        }
+        const headers = parseCsvLine(firstLine);
+        return headers.map((header) => ({
+            Name: header,
+            Label: header,
+            DataType: 'string',
+            IsRequired: false,
+            IsUniqueKey: false,
+            IsReadOnly: true,
+        }));
+    }
+    /**
+     * Fetches all records from the CSV file as a full load.
+     * CSV files do not support incremental sync — watermark is ignored.
+     * @param ctx - Fetch context (watermark is always ignored for file feeds)
+     * @returns All records from the CSV file in a single batch
+     */
+    async FetchChanges(ctx) {
+        const config = this.parseConfig(ctx.CompanyIntegration);
+        const content = fs.readFileSync(config.StoragePath, 'utf-8');
+        const lines = content.split('\n').filter((line) => line.trim().length > 0);
+        if (lines.length < 2) {
+            return { Records: [], HasMore: false };
+        }
+        const headers = parseCsvLine(lines[0]);
+        const records = this.parseDataLines(lines.slice(1), headers, ctx.ObjectName);
+        return { Records: records, HasMore: false };
+    }
+    /**
+     * Parses the Configuration JSON to extract file feed settings.
+     * @param companyIntegration - The entity containing Configuration JSON
+     * @returns Parsed file feed configuration
+     */
+    parseConfig(companyIntegration) {
+        const configJson = companyIntegration.Get('Configuration');
+        if (!configJson) {
+            throw new Error('CompanyIntegration.Configuration is null or empty');
+        }
+        const parsed = JSON.parse(configJson);
+        const storagePath = parsed['storagePath'];
+        const fileType = parsed['fileType'] ?? 'csv';
+        if (!storagePath) {
+            throw new Error('Configuration JSON must contain a storagePath field');
+        }
+        return { StoragePath: storagePath, FileType: fileType };
+    }
+    /**
+     * Parses an array of CSV data lines into ExternalRecord objects.
+     * @param lines - CSV data lines (excluding header)
+     * @param headers - Column header names
+     * @param objectName - Object type name for the records
+     * @returns Array of ExternalRecord objects
+     */
+    parseDataLines(lines, headers, objectName) {
+        return lines.map((line, index) => {
+            const values = parseCsvLine(line);
+            const fields = {};
+            for (let i = 0; i < headers.length; i++) {
+                const rawValue = i < values.length ? values[i] : '';
+                fields[headers[i]] = rawValue === '' ? null : rawValue;
+            }
+            return {
+                ExternalID: String(index + 1),
+                ObjectType: objectName,
+                Fields: fields,
+                IsDeleted: false,
+            };
+        });
+    }
+};
+FileFeedConnector = __decorate([
+    RegisterClass(BaseIntegrationConnector, 'FileFeedConnector')
+], FileFeedConnector);
+export { FileFeedConnector };
+/**
+ * Parses a single CSV line handling quoted fields with commas.
+ * Supports:
+ * - Unquoted fields separated by commas
+ * - Quoted fields that may contain commas
+ * - Escaped quotes ("") inside quoted fields
+ * @param line - A single CSV line to parse
+ * @returns Array of field values
+ */
+export function parseCsvLine(line) {
+    const fields = [];
+    let current = '';
+    let inQuotes = false;
+    let i = 0;
+    while (i < line.length) {
+        const char = line[i];
+        if (inQuotes) {
+            if (char === '"' && i + 1 < line.length && line[i + 1] === '"') {
+                current += '"';
+                i += 2;
+            }
+            else if (char === '"') {
+                inQuotes = false;
+                i++;
+            }
+            else {
+                current += char;
+                i++;
+            }
+        }
+        else {
+            if (char === '"') {
+                inQuotes = true;
+                i++;
+            }
+            else if (char === ',') {
+                fields.push(current.trim());
+                current = '';
+                i++;
+            }
+            else {
+                current += char;
+                i++;
+            }
+        }
+    }
+    fields.push(current.trim());
+    return fields;
+}
+//# sourceMappingURL=FileFeedConnector.js.map

package/dist/FileFeedConnector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileFeedConnector.js","sourceRoot":"","sources":["../src/FileFeedConnector.ts"],"names":[],"mappings":"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"}

package/dist/HubSpotConnector.d.ts

@@ -0,0 +1,96 @@
+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 DefaultFieldMapping, type DefaultIntegrationConfig } from '@memberjunction/integration-engine';
+/** HubSpot property definition (from /crm/v3/properties/{objectType}) */
+interface HubSpotPropertyDef {
+    name: string;
+    label: string;
+    type: string;
+    fieldType: string;
+    groupName: string;
+    description: string;
+    hasUniqueValue: boolean;
+    calculated: boolean;
+    externalOptions: boolean;
+    modificationMetadata?: {
+        readOnlyValue: boolean;
+    };
+}
+/**
+ * Connector for HubSpot CRM via the HubSpot REST API v3.
+ *
+ * Extends BaseRESTIntegrationConnector to leverage metadata-driven object/field
+ * discovery from IntegrationEngineBase cache and generic pagination handling.
+ *
+ * Uses Bearer token authentication (private app key or OAuth access token).
+ * Supports cursor-based pagination and automatic response flattening.
+ *
+ * DATA SAFETY: This connector is READ-ONLY. It never writes data back to HubSpot.
+ */
+export declare class HubSpotConnector extends BaseRESTIntegrationConnector {
+    /** Timestamp of the last API request, used for throttling */
+    private lastRequestTime;
+    protected Authenticate(companyIntegration: MJCompanyIntegrationEntity): Promise<RESTAuthContext>;
+    protected BuildHeaders(auth: RESTAuthContext): Record<string, string>;
+    protected MakeHTTPRequest(_auth: RESTAuthContext, url: string, method: string, headers: Record<string, string>, _body?: unknown): Promise<RESTResponse>;
+    protected NormalizeResponse(rawBody: unknown, responseDataKey: string | null): Record<string, unknown>[];
+    protected ExtractPaginationInfo(rawBody: unknown, _paginationType: PaginationType, _currentPage: number, _currentOffset: number, _pageSize: number): PaginationState;
+    protected GetBaseURL(_companyIntegration: MJCompanyIntegrationEntity): string;
+    /**
+     * Overrides base pagination URL building to use HubSpot's parameter names.
+     * HubSpot uses `after` for cursor pagination (not `cursor`), and needs
+     * `limit` instead of `pageSize`. Also appends `properties` query param.
+     */
+    protected BuildPaginatedURL(basePath: string, obj: MJIntegrationObjectEntity, _page: number, _offset: number, cursor?: string): string;
+    /** Tests connectivity by authenticating and fetching 1 contact. */
+    TestConnection(companyIntegration: MJCompanyIntegrationEntity, _contextUser: UserInfo): Promise<ConnectionTestResult>;
+    GetDefaultFieldMappings(objectName: string, _entityName: string): DefaultFieldMapping[];
+    GetDefaultConfiguration(): DefaultIntegrationConfig;
+    /** Converts a HubSpot property definition to ExternalFieldSchema format */
+    MapPropertyToField(prop: HubSpotPropertyDef): {
+        Name: string;
+        Label: string;
+        DataType: string;
+        IsRequired: boolean;
+        IsUniqueKey: boolean;
+        IsReadOnly: boolean;
+    };
+    /** Maps HubSpot type + fieldType to a simplified data type string */
+    MapHubSpotType(type: string, fieldType: string): string;
+    /**
+     * Reads credentials from CompanyIntegration.CredentialID -> Credential.Values JSON,
+     * or falls back to CompanyIntegration Configuration JSON for backwards compat.
+     */
+    private LoadCredentials;
+    /** Loads credentials from a Credential entity by ID. */
+    private LoadFromCredentialEntity;
+    /** Parses a JSON string to extract HubSpot credentials. Returns null if no token found. */
+    private ParseCredentialJson;
+    /**
+     * Flattens a HubSpot CRM record from the nested format:
+     *   { id, properties: { field1, field2 }, createdAt, updatedAt, archived }
+     * into a flat record with all properties at the top level,
+     * plus system fields (hs_object_id, createdAt, updatedAt, archived).
+     */
+    private FlattenHubSpotRecord;
+    /**
+     * Extracts the HubSpot object name from an API path.
+     * E.g., "/crm/v3/objects/contacts" -> "contacts"
+     */
+    private ExtractObjectNameFromPath;
+    /**
+     * Builds the `properties` query parameter for a HubSpot object type.
+     * Returns empty string if no properties are configured for the object.
+     */
+    private BuildPropertiesParam;
+    /** Executes an HTTP request with a timeout. */
+    private FetchWithTimeout;
+    /** Calculates retry delay from Retry-After header or exponential backoff. */
+    private CalculateRetryDelay;
+    /** Converts a fetch Response + parsed body into a RESTResponse. */
+    private BuildRESTResponse;
+    /** Returns a promise that resolves after the specified number of milliseconds. */
+    private Sleep;
+}
+export {};
+//# sourceMappingURL=HubSpotConnector.d.ts.map

package/dist/HubSpotConnector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HubSpotConnector.d.ts","sourceRoot":"","sources":["../src/HubSpotConnector.ts"],"names":[],"mappings":"AACA,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAE,0BAA0B,EAAsB,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAC/H,OAAO,EAEH,4BAA4B,EAC5B,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAChC,MAAM,oCAAoC,CAAC;AAe5C,yEAAyE;AACzE,UAAU,kBAAkB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,OAAO,CAAC;IACxB,UAAU,EAAE,OAAO,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;IACzB,oBAAoB,CAAC,EAAE;QACnB,aAAa,EAAE,OAAO,CAAC;KAC1B,CAAC;CACL;AAgHD;;;;;;;;;;GAUG;AACH,qBACa,gBAAiB,SAAQ,4BAA4B;IAE9D,6DAA6D;IAC7D,OAAO,CAAC,eAAe,CAAK;cAIZ,YAAY,CACxB,kBAAkB,EAAE,0BAA0B,GAC/C,OAAO,CAAC,eAAe,CAAC;IAS3B,SAAS,CAAC,YAAY,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;cAOrD,eAAe,CAC3B,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,KAAK,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,YAAY,CAAC;IA4BxB,SAAS,CAAC,iBAAiB,CACvB,OAAO,EAAE,OAAO,EAChB,eAAe,EAAE,MAAM,GAAG,IAAI,GAC/B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE;IAmB5B,SAAS,CAAC,qBAAqB,CAC3B,OAAO,EAAE,OAAO,EAChB,eAAe,EAAE,cAAc,EAC/B,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,GAClB,eAAe;IAYlB,SAAS,CAAC,UAAU,CAAC,mBAAmB,EAAE,0BAA0B,GAAG,MAAM;IAM7E;;;;OAIG;cACgB,iBAAiB,CAChC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,yBAAyB,EAC9B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GAChB,MAAM;IAcT,mEAAmE;IACtD,cAAc,CACvB,kBAAkB,EAAE,0BAA0B,EAC9C,YAAY,EAAE,QAAQ,GACvB,OAAO,CAAC,oBAAoB,CAAC;IAmChB,uBAAuB,CACnC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GACpB,mBAAmB,EAAE;IAkCR,uBAAuB,IAAI,wBAAwB;IASnE,2EAA2E;IACpE,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,GAAG;QACjD,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,OAAO,CAAC;QACpB,WAAW,EAAE,OAAO,CAAC;QACrB,UAAU,EAAE,OAAO,CAAC;KACvB;IAWD,qEAAqE;IAC9D,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAsB9D;;;OAGG;YACW,eAAe;IAuB7B,wDAAwD;YAC1C,wBAAwB;IAStC,2FAA2F;IAC3F,OAAO,CAAC,mBAAmB;IAkB3B;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAsB5B;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAQjC;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAU5B,+CAA+C;YACjC,gBAAgB;IAmB9B,6EAA6E;IAC7E,OAAO,CAAC,mBAAmB;IAK3B,mEAAmE;IACnE,OAAO,CAAC,iBAAiB;IAMzB,kFAAkF;IAClF,OAAO,CAAC,KAAK;CAGhB"}