@peernova/cuneiform-sf 1.0.2 → 1.0.4-beta.8

package/lib/services/ContactPointService.d.ts

@@ -0,0 +1,111 @@
+import type { IRestApiAdapter } from '../adapters/rest/rest-api-adapter.js';
+import type { ServiceResult } from '../models/service-result.js';
+/**
+ * Classification type for a contact point field.
+ */
+export type ContactPointType = 'email' | 'phone' | 'name' | 'social' | 'url' | 'other';
+/**
+ * Represents a field identified as a contact point.
+ */
+export type ContactPointField = {
+    /** API name of the field */
+    fieldName: string;
+    /** User-friendly label */
+    fieldLabel: string;
+    /** Salesforce field type (string, email, phone, textarea, etc.) */
+    fieldType: string;
+    /** Classified contact point type */
+    contactPointType: ContactPointType;
+    /** Classification confidence level */
+    confidence: 'high' | 'medium' | 'low';
+    /** Reason for classification */
+    reason: string;
+};
+/**
+ * Result of analyzing an object's fields for contact points.
+ */
+export type ContactPointAnalysis = {
+    /** API name of the analyzed object */
+    objectName: string;
+    /** Total number of fields on the object */
+    totalFields: number;
+    /** Fields identified as contact points */
+    contactPointFields: ContactPointField[];
+    /** Number of contact point fields found */
+    contactPointCount: number;
+};
+/**
+ * Configuration for ContactPointService.
+ */
+export type IContactPointServiceConfig = {
+    /** REST API adapter for describing objects */
+    restApiAdapter: IRestApiAdapter;
+    /** Optional logger for debug output */
+    logger?: Console;
+};
+/**
+ * Service for analyzing Salesforce object fields to identify contact points.
+ *
+ * Contact points are fields that likely contain personal or contact information
+ * such as email addresses, phone numbers, names, and social media identifiers.
+ * This service uses field metadata (type and name) to classify fields with
+ * high, medium, or low confidence.
+ *
+ * @example
+ * ```typescript
+ * const service = new ContactPointService({ restApiAdapter });
+ * const result = await service.analyzeContactPoints('Contact');
+ * if (result.success) {
+ *   result.data.contactPointFields.forEach(f => console.log(f.fieldName, f.contactPointType));
+ * }
+ * ```
+ */
+export declare class ContactPointService {
+    private readonly restApiAdapter;
+    private readonly logger?;
+    constructor(config: IContactPointServiceConfig);
+    /**
+     * Checks whether a field is a system field that should be excluded from analysis.
+     *
+     * @param fieldName - The API name of the field
+     * @returns true if the field is a system field
+     */
+    private static isSystemField;
+    /**
+     * Attempts to classify a field by its Salesforce field type (high confidence).
+     *
+     * @param field - The field metadata to classify
+     * @returns ContactPointField if classified, or undefined if no match
+     */
+    private static classifyByFieldType;
+    /**
+     * Attempts to classify a field by its name using heuristic patterns (medium/low confidence).
+     *
+     * @param field - The field metadata to classify
+     * @returns ContactPointField if classified, or undefined if no match
+     */
+    private static classifyByFieldName;
+    /**
+     * Classifies a single field as a contact point, if applicable.
+     *
+     * Applies classification in priority order:
+     * 1. Skip system fields
+     * 2. High confidence: field type matching (email, phone, url)
+     * 3. Medium/Low confidence: field name heuristics
+     *
+     * @param field - The field metadata to classify
+     * @returns ContactPointField if classified, or undefined if not a contact point
+     */
+    private static classifyField;
+    /**
+     * Analyzes a Salesforce object's fields to identify contact point fields.
+     *
+     * Uses the REST API describe endpoint to retrieve field metadata, then
+     * classifies each field based on its type and name to identify fields
+     * that likely contain personal or contact information.
+     *
+     * @param objectName - The Salesforce object API name (e.g., 'Contact', 'Account')
+     * @returns ServiceResult containing the ContactPointAnalysis
+     */
+    analyzeContactPoints(objectName: string): Promise<ServiceResult<ContactPointAnalysis>>;
+}

package/lib/services/ContactPointService.js

@@ -0,0 +1,286 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+import { createSuccessResult, createFailureResult } from '../models/service-result.js';
+import { ServiceErrorCodes } from '../adapters/errors.js';
+import { validateRequiredString, validateObjectName } from './validation.js';
+/**
+ * Service for identifying contact point fields within Salesforce objects.
+ *
+ * Analyzes object field metadata to detect fields that likely contain
+ * contact information (email, phone, name, social handles). Uses a
+ * combination of field type analysis and naming pattern matching.
+ *
+ * @design
+ * **Classification Strategy**: Uses a two-pass approach:
+ * 1. Field type detection (email, phone types are high confidence)
+ * 2. Name pattern matching (e.g., fields containing "email", "phone")
+ *
+ * This dual approach catches both explicitly typed fields and custom
+ * text fields that follow naming conventions for contact data.
+ *
+ * @design
+ * **System Field Exclusion**: Excludes audit fields (CreatedById, OwnerId, etc.)
+ * to prevent false positives. These are references to users, not contact points.
+ *
+ * @example
+ * ```typescript
+ * const service = new ContactPointService({ restApiAdapter, logger: console });
+ * const result = await service.analyzeContactPoints('Contact');
+ * if (result.success) {
+ *   console.log(`Found ${result.data.contactPointCount} contact fields`);
+ * }
+ * ```
+ */
+/**
+ * System fields to exclude from contact point analysis.
+ *
+ * These are audit/metadata fields managed by Salesforce that:
+ * - Cannot contain user-provided contact information
+ * - Are auto-populated by the platform (not editable by users)
+ * - Exist on every object regardless of its purpose
+ *
+ * Excluding them prevents false positives (e.g., "OwnerId" is not a contact point).
+ */
+const SYSTEM_FIELDS = new Set([
+    'Id', // Record identifier (auto-generated)
+    'IsDeleted', // Soft delete flag (system-managed)
+    'CreatedDate', // Audit timestamp (auto-populated)
+    'CreatedById', // Audit user reference (auto-populated)
+    'LastModifiedDate', // Audit timestamp (auto-populated)
+    'LastModifiedById', // Audit user reference (auto-populated)
+    'SystemModstamp', // System timestamp (auto-populated)
+    'OwnerId', // Record owner reference (not contact info)
+    'RecordTypeId', // Record type reference (not contact info)
+]);
+/**
+ * Field name patterns for medium-confidence phone detection.
+ */
+const PHONE_PATTERNS = ['phone', 'fax', 'mobile'];
+/**
+ * Field name patterns for low-confidence social media detection.
+ */
+const SOCIAL_PATTERNS = ['twitter', 'facebook', 'linkedin', 'social'];
+/**
+ * Field name patterns for medium-confidence URL detection.
+ */
+const URL_PATTERNS = ['website', 'url', 'homepage', 'link'];
+/**
+ * Service for analyzing Salesforce object fields to identify contact points.
+ *
+ * Contact points are fields that likely contain personal or contact information
+ * such as email addresses, phone numbers, names, and social media identifiers.
+ * This service uses field metadata (type and name) to classify fields with
+ * high, medium, or low confidence.
+ *
+ * @example
+ * ```typescript
+ * const service = new ContactPointService({ restApiAdapter });
+ * const result = await service.analyzeContactPoints('Contact');
+ * if (result.success) {
+ *   result.data.contactPointFields.forEach(f => console.log(f.fieldName, f.contactPointType));
+ * }
+ * ```
+ */
+export class ContactPointService {
+    restApiAdapter;
+    logger;
+    constructor(config) {
+        this.restApiAdapter = config.restApiAdapter;
+        this.logger = config.logger;
+    }
+    /**
+     * Checks whether a field is a system field that should be excluded from analysis.
+     *
+     * @param fieldName - The API name of the field
+     * @returns true if the field is a system field
+     */
+    static isSystemField(fieldName) {
+        return SYSTEM_FIELDS.has(fieldName);
+    }
+    /**
+     * Attempts to classify a field by its Salesforce field type (high confidence).
+     *
+     * @param field - The field metadata to classify
+     * @returns ContactPointField if classified, or undefined if no match
+     */
+    static classifyByFieldType(field) {
+        const typeMap = {
+            email: 'email',
+            phone: 'phone',
+            url: 'url',
+        };
+        const contactPointType = typeMap[field.type];
+        if (contactPointType) {
+            return {
+                fieldName: field.name,
+                fieldLabel: field.label,
+                fieldType: field.type,
+                contactPointType,
+                confidence: 'high',
+                reason: `Field type is ${field.type}`,
+            };
+        }
+        return undefined;
+    }
+    /**
+     * Attempts to classify a field by its name using heuristic patterns (medium/low confidence).
+     *
+     * @param field - The field metadata to classify
+     * @returns ContactPointField if classified, or undefined if no match
+     */
+    static classifyByFieldName(field) {
+        const lowerName = field.name.toLowerCase();
+        // Medium confidence: email by name
+        if (lowerName.includes('email')) {
+            return {
+                fieldName: field.name,
+                fieldLabel: field.label,
+                fieldType: field.type,
+                contactPointType: 'email',
+                confidence: 'medium',
+                reason: "Field name contains 'email'",
+            };
+        }
+        // Medium confidence: phone by name
+        const phoneMatch = PHONE_PATTERNS.find((pattern) => lowerName.includes(pattern));
+        if (phoneMatch) {
+            return {
+                fieldName: field.name,
+                fieldLabel: field.label,
+                fieldType: field.type,
+                contactPointType: 'phone',
+                confidence: 'medium',
+                reason: `Field name contains '${phoneMatch}'`,
+            };
+        }
+        // Medium confidence: name fields (must be string type)
+        // Check patterns in specificity order: firstname/lastname are more specific than 'name'
+        const namePatterns = ['firstname', 'lastname', 'name'];
+        const nameMatch = namePatterns.find((pattern) => lowerName.includes(pattern));
+        if (nameMatch && field.type === 'string') {
+            return {
+                fieldName: field.name,
+                fieldLabel: field.label,
+                fieldType: field.type,
+                contactPointType: 'name',
+                confidence: 'medium',
+                reason: `Field name contains '${nameMatch}'`,
+            };
+        }
+        // Low confidence: social media (check before URL since 'linkedin' contains 'link')
+        const socialMatch = SOCIAL_PATTERNS.find((pattern) => lowerName.includes(pattern));
+        if (socialMatch) {
+            return {
+                fieldName: field.name,
+                fieldLabel: field.label,
+                fieldType: field.type,
+                contactPointType: 'social',
+                confidence: 'low',
+                reason: `Field name contains '${socialMatch}'`,
+            };
+        }
+        // Medium confidence: URL by name
+        const urlMatch = URL_PATTERNS.find((pattern) => lowerName.includes(pattern));
+        if (urlMatch) {
+            return {
+                fieldName: field.name,
+                fieldLabel: field.label,
+                fieldType: field.type,
+                contactPointType: 'url',
+                confidence: 'medium',
+                reason: `Field name contains '${urlMatch}'`,
+            };
+        }
+        return undefined;
+    }
+    /**
+     * Classifies a single field as a contact point, if applicable.
+     *
+     * Applies classification in priority order:
+     * 1. Skip system fields
+     * 2. High confidence: field type matching (email, phone, url)
+     * 3. Medium/Low confidence: field name heuristics
+     *
+     * @param field - The field metadata to classify
+     * @returns ContactPointField if classified, or undefined if not a contact point
+     */
+    static classifyField(field) {
+        if (ContactPointService.isSystemField(field.name)) {
+            return undefined;
+        }
+        return ContactPointService.classifyByFieldType(field) ?? ContactPointService.classifyByFieldName(field);
+    }
+    /**
+     * Analyzes a Salesforce object's fields to identify contact point fields.
+     *
+     * Uses the REST API describe endpoint to retrieve field metadata, then
+     * classifies each field based on its type and name to identify fields
+     * that likely contain personal or contact information.
+     *
+     * @param objectName - The Salesforce object API name (e.g., 'Contact', 'Account')
+     * @returns ServiceResult containing the ContactPointAnalysis
+     */
+    async analyzeContactPoints(objectName) {
+        const startTime = Date.now();
+        const emptyResult = {
+            objectName: objectName ?? '',
+            totalFields: 0,
+            contactPointFields: [],
+            contactPointCount: 0,
+        };
+        // Validate required
+        const requiredError = validateRequiredString(objectName, 'Object name');
+        if (requiredError) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.CONTACT_POINT_OBJECT_NAME_REQUIRED, requiredError, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        // Validate format
+        const formatError = validateObjectName(objectName);
+        if (formatError) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.CONTACT_POINT_INVALID_OBJECT_NAME, formatError, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        try {
+            this.logger?.log(`Analyzing contact points for: ${objectName}`);
+            const describeResult = await this.restApiAdapter.describeObject(objectName);
+            if (!describeResult.success) {
+                return createFailureResult(emptyResult, ServiceErrorCodes.CONTACT_POINT_ANALYSIS_FAILED, describeResult.message ?? 'Object describe failed', { metadata: { duration: Date.now() - startTime } });
+            }
+            const fields = describeResult.data.fields;
+            const contactPointFields = [];
+            for (const field of fields) {
+                const classified = ContactPointService.classifyField(field);
+                if (classified) {
+                    contactPointFields.push(classified);
+                }
+            }
+            const analysis = {
+                objectName,
+                totalFields: fields.length,
+                contactPointFields,
+                contactPointCount: contactPointFields.length,
+            };
+            const duration = Date.now() - startTime;
+            this.logger?.log(`Found ${contactPointFields.length} contact point fields out of ${fields.length} total for ${objectName}`);
+            return createSuccessResult(analysis, {
+                message: `Found ${contactPointFields.length} contact point fields for ${objectName}`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Contact point analysis failed: ${errorMessage}`);
+            return createFailureResult(emptyResult, ServiceErrorCodes.CONTACT_POINT_ANALYSIS_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+}
+//# sourceMappingURL=ContactPointService.js.map

package/lib/services/ContactPointService.js.map

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

package/lib/services/DataAvailabilityService.d.ts

@@ -0,0 +1,81 @@
+import { type ServiceResult } from '../models/service-result.js';
+import type { YearRange } from '../models/year-range.js';
+import type { ISoqlQueryAdapter } from '../adapters/soql/soql-query-adapter.js';
+/**
+ * Per-object availability result for a single year.
+ */
+export type YearAvailability = {
+    /** The year checked */
+    readonly year: number;
+    /** Whether data exists in this year (records created in this calendar year) */
+    readonly hasData: boolean;
+};
+/**
+ * Per-object availability row in the grid.
+ */
+export type AvailabilityRow = {
+    /** Salesforce object API name */
+    readonly objectApiName: string;
+    /** Oldest record year (minimum CALENDAR_YEAR from GROUP BY results), or null if no records exist */
+    readonly oldestYear: number | null;
+    /** Per-year data availability flags */
+    readonly years: readonly YearAvailability[];
+};
+/**
+ * Complete availability grid result.
+ */
+export type AvailabilityGrid = {
+    /** Column headers: the years checked (from YearRange entries) */
+    readonly yearColumns: readonly number[];
+    /** Per-object rows */
+    readonly rows: readonly AvailabilityRow[];
+};
+/**
+ * Configuration for DataAvailabilityService.
+ */
+export type DataAvailabilityServiceConfig = {
+    /** SOQL query adapter for executing probes */
+    readonly soqlAdapter: ISoqlQueryAdapter;
+    /** Number of objects to process concurrently per batch (default: 5) */
+    readonly concurrencyLimit?: number;
+    /** Optional logger */
+    readonly logger?: Console;
+};
+/**
+ * Service that builds a data availability grid for objects across a year range.
+ *
+ * Uses a single CALENDAR_YEAR(CreatedDate) GROUP BY query per object, which returns
+ * all years with data in one round-trip. This replaces the previous approach of
+ * Y+1 queries per object (one probe per year + one MIN(CreatedDate) for oldest).
+ *
+ * Objects are processed in batched parallel groups (default: 5 concurrent).
+ * API call count: 1 per object (vs. N×(Y+1) in the sequential pre-fix approach).
+ */
+export declare class DataAvailabilityService {
+    private readonly soqlAdapter;
+    private readonly concurrencyLimit;
+    private readonly logger?;
+    constructor(config: DataAvailabilityServiceConfig);
+    /**
+     * Builds a data availability grid for the given objects and year range.
+     *
+     * @param objectNames - Salesforce object API names to check
+     * @param yearRange - The year range to check (from resolveYearRange)
+     * @returns Grid with per-object, per-year presence flags and oldest record year
+     */
+    buildGrid(objectNames: string[], yearRange: YearRange): Promise<ServiceResult<AvailabilityGrid>>;
+    /**
+     * Builds a single row for one object using a single CALENDAR_YEAR GROUP BY query.
+     * Derives both per-year presence flags and the oldest year from one round-trip.
+     */
+    private buildRowForObject;
+    /**
+     * Issues a single CALENDAR_YEAR(CreatedDate) GROUP BY query for an object.
+     *
+     * Returns a year → hasData map and the oldest year (minimum year in results).
+     * Returns empty map and null oldestYear when no records exist or query fails.
+     *
+     * Single query replaces Y+1 separate probes per object (CLI-1513 optimization).
+     */
+    private queryYearAvailabilityByGroupBy;
+}

package/lib/services/DataAvailabilityService.js

@@ -0,0 +1,128 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+import { createSuccessResult, createFailureResult } from '../models/service-result.js';
+import { ServiceErrorCodes, sanitizeSoqlIdentifier } from '../adapters/errors.js';
+import { CuneiformQueryBuilder } from '../adapters/soql/cuneiform-query-builder.js';
+import { processInBatches } from '../utils/batch-processor.js';
+/** Default number of objects to process concurrently in each batch. */
+const DEFAULT_CONCURRENCY_LIMIT = 5;
+/**
+ * Service that builds a data availability grid for objects across a year range.
+ *
+ * Uses a single CALENDAR_YEAR(CreatedDate) GROUP BY query per object, which returns
+ * all years with data in one round-trip. This replaces the previous approach of
+ * Y+1 queries per object (one probe per year + one MIN(CreatedDate) for oldest).
+ *
+ * Objects are processed in batched parallel groups (default: 5 concurrent).
+ * API call count: 1 per object (vs. N×(Y+1) in the sequential pre-fix approach).
+ */
+export class DataAvailabilityService {
+    soqlAdapter;
+    concurrencyLimit;
+    logger;
+    constructor(config) {
+        this.soqlAdapter = config.soqlAdapter;
+        this.concurrencyLimit = config.concurrencyLimit ?? DEFAULT_CONCURRENCY_LIMIT;
+        this.logger = config.logger;
+    }
+    /**
+     * Builds a data availability grid for the given objects and year range.
+     *
+     * @param objectNames - Salesforce object API names to check
+     * @param yearRange - The year range to check (from resolveYearRange)
+     * @returns Grid with per-object, per-year presence flags and oldest record year
+     */
+    async buildGrid(objectNames, yearRange) {
+        const startTime = Date.now();
+        if (objectNames.length === 0 || yearRange.entries.length === 0) {
+            return createSuccessResult({ yearColumns: yearRange.entries.map((e) => e.year), rows: [] }, { message: 'No objects or years to check', metadata: { duration: Date.now() - startTime } });
+        }
+        const yearColumns = yearRange.entries.map((e) => e.year);
+        try {
+            this.logger?.log(`Processing ${objectNames.length} objects in batches of ${this.concurrencyLimit}`);
+            const rows = await processInBatches(objectNames, this.concurrencyLimit, (objectName) => this.buildRowForObject(objectName, yearRange.entries));
+            const duration = Date.now() - startTime;
+            const gapCount = rows.reduce((sum, r) => sum + r.years.filter((y) => !y.hasData).length, 0);
+            this.logger?.log(`Availability grid: ${rows.length} objects × ${yearColumns.length} years, ${gapCount} gaps in ${duration}ms`);
+            return createSuccessResult({ yearColumns, rows }, {
+                message: `Checked ${rows.length} objects across ${yearColumns.length} years`,
+                metadata: {
+                    duration,
+                    apiCallCount: rows.length,
+                    concurrencyLimit: this.concurrencyLimit,
+                },
+            });
+        }
+        catch (error) {
+            return createFailureResult({ yearColumns, rows: [] }, ServiceErrorCodes.DATA_AVAILABILITY_GRID_BUILD_FAILED, `Availability grid failed: ${error instanceof Error ? error.message : String(error)}`, { metadata: { duration: Date.now() - startTime } });
+        }
+    }
+    /**
+     * Builds a single row for one object using a single CALENDAR_YEAR GROUP BY query.
+     * Derives both per-year presence flags and the oldest year from one round-trip.
+     */
+    async buildRowForObject(objectName, entries) {
+        const { yearMap, oldestYear } = await this.queryYearAvailabilityByGroupBy(objectName);
+        const years = entries.map((entry) => ({
+            year: entry.year,
+            hasData: yearMap.get(entry.year) ?? false,
+        }));
+        return {
+            objectApiName: objectName,
+            oldestYear,
+            years,
+        };
+    }
+    /**
+     * Issues a single CALENDAR_YEAR(CreatedDate) GROUP BY query for an object.
+     *
+     * Returns a year → hasData map and the oldest year (minimum year in results).
+     * Returns empty map and null oldestYear when no records exist or query fails.
+     *
+     * Single query replaces Y+1 separate probes per object (CLI-1513 optimization).
+     */
+    async queryYearAvailabilityByGroupBy(objectName) {
+        let soql;
+        try {
+            // sanitizeSoqlIdentifier rejects anything that isn't a valid Salesforce API name
+            // (^[A-Za-z][A-Za-z0-9_]*$). Quote characters, spaces, and SOQL comment markers
+            // all fail the regex and throw before the query is built.
+            const sanitizedObject = sanitizeSoqlIdentifier(objectName);
+            soql = new CuneiformQueryBuilder()
+                .select(['CALENDAR_YEAR(CreatedDate) yr', 'COUNT(Id) cnt'])
+                .from(sanitizedObject)
+                .andWhereNull('CreatedDate', false)
+                .groupBy(['CALENDAR_YEAR(CreatedDate)'])
+                .toSOQL();
+        }
+        catch {
+            this.logger?.log(`GROUP BY availability query rejected: invalid object name "${objectName}"`);
+            return { yearMap: new Map(), oldestYear: null };
+        }
+        try {
+            const result = await this.soqlAdapter.query(soql);
+            if (!result.success || result.data.records.length === 0) {
+                return { yearMap: new Map(), oldestYear: null };
+            }
+            const yearMap = new Map();
+            let minYear = null;
+            for (const record of result.data.records) {
+                yearMap.set(record.yr, record.cnt > 0);
+                if (minYear === null || record.yr < minYear) {
+                    minYear = record.yr;
+                }
+            }
+            return { yearMap, oldestYear: minYear };
+        }
+        catch {
+            this.logger?.log(`GROUP BY availability query failed for ${objectName}`);
+            return { yearMap: new Map(), oldestYear: null };
+        }
+    }
+}
+//# sourceMappingURL=DataAvailabilityService.js.map

package/lib/services/DataAvailabilityService.js.map

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