@memberjunction/geo-core 0.0.1 → 5.25.0

package/dist/GeoCodeSyncService.d.ts

@@ -0,0 +1,120 @@
+import { BaseSingleton } from '@memberjunction/global';
+import { BaseEntity, EntityInfo, UserInfo } from '@memberjunction/core';
+import { MJRecordGeoCodeEntity } from '@memberjunction/core-entities';
+import { GeoFieldMapping, GeocodeResult } from './types.js';
+/**
+ * Singleton service that manages the geocoding lifecycle for entity records.
+ * Called by CodeGen-generated AfterSave hooks on geo-enabled entities.
+ *
+ * Responsibilities:
+ * - Computes source field hashes for change detection
+ * - Checks existing RecordGeoCode rows for staleness
+ * - Dispatches geocoding (delegates to registered geocoding providers)
+ * - Upserts RecordGeoCode rows with results or error status
+ *
+ * All geocoding is fire-and-forget — errors are captured in RecordGeoCode
+ * and retried by the scheduled geocoding job. Never throws.
+ */
+export declare class GeoCodeSyncService extends BaseSingleton<GeoCodeSyncService> {
+    constructor();
+    static get Instance(): GeoCodeSyncService;
+    /**
+     * Check if any geo field mappings have changed and dispatch geocoding if needed.
+     * Called from the GenericDatabaseProvider OnSaveCompleted hook.
+     *
+     * This method never throws — all errors are captured in RecordGeoCode rows.
+     *
+     * @param entity - The entity instance that was just saved
+     * @param contextUser - The user context for data operations
+     * @param mappings - Field-to-location mappings (if not provided, derived from EntityField.ExtendedType metadata)
+     * @returns The geocode result from the first successfully geocoded mapping, or null
+     *          if no geocoding was performed (e.g., hash unchanged) or all attempts failed.
+     *          The caller can use this to patch virtual lat/lng fields on the entity's
+     *          SP result before finalizeSave() loads it into the entity object.
+     */
+    SyncIfChanged(entity: BaseEntity, contextUser: UserInfo, mappings?: GeoFieldMapping[]): Promise<GeocodeResult | null>;
+    /**
+     * Derive geo field mappings from EntityField.ExtendedType metadata.
+     * Finds all fields with Geo* ExtendedType values and groups them into
+     * a Primary location mapping.
+     *
+     * @param entityInfo - The entity metadata to inspect
+     * @returns Array of geo field mappings (empty if no geo fields found)
+     */
+    static BuildMappingsFromMetadata(entityInfo: EntityInfo): GeoFieldMapping[];
+    /**
+     * Check if an entity has any geo fields defined in its metadata.
+     * @param entityInfo - The entity metadata to check
+     * @returns true if the entity has at least one field with a Geo* ExtendedType
+     */
+    static HasGeoFields(entityInfo: EntityInfo): boolean;
+    /**
+     * Process a single field mapping for a single entity record.
+     * @returns The geocode result if geocoding was performed successfully, or null if
+     *          no geocoding was needed (hash unchanged) or the attempt failed.
+     */
+    protected ProcessMapping(entity: BaseEntity, mapping: GeoFieldMapping, contextUser: UserInfo): Promise<GeocodeResult | null>;
+    /**
+     * Find an existing RecordGeoCode row for a given entity/record/location type.
+     */
+    protected FindExistingGeoCode(entityID: string, recordID: string, locationType: string, contextUser: UserInfo): Promise<MJRecordGeoCodeEntity | null>;
+    /**
+     * Create a new RecordGeoCode row.
+     */
+    protected CreateGeoCodeRow(entityID: string, recordID: string, locationType: string, contextUser: UserInfo): Promise<MJRecordGeoCodeEntity | null>;
+    /**
+     * Update a RecordGeoCode row with successful geocoding results.
+     */
+    protected UpdateSuccess(row: MJRecordGeoCodeEntity, result: GeocodeResult, hash: string): Promise<void>;
+    /**
+     * Mark a RecordGeoCode row as not geocodable — the address can't be resolved
+     * to coordinates (e.g., "Conference Room B", "TBD"). Won't be retried by the
+     * bulk job. If the source record's address fields change, the hash mismatch
+     * in SyncIfChanged will trigger a fresh attempt.
+     */
+    protected UpdateNotGeocodable(row: MJRecordGeoCodeEntity, reason: string): Promise<void>;
+    /**
+     * Update a RecordGeoCode row with failure information (transient error, eligible for retry).
+     */
+    protected UpdateFailure(row: MJRecordGeoCodeEntity, errorMessage: string): Promise<void>;
+    /**
+     * Perform the actual geocoding using a priority-based strategy:
+     *
+     * 1. Native lat/lng fields → copy directly (GeocodingSource = 'native')
+     * 2. Address-level fields → external geocoding API (GeocodingSource = 'google')
+     * 3. Country/state only → reference table centroid lookup (GeocodingSource = 'reference_data')
+     */
+    protected Geocode(entity: BaseEntity, _mapping: GeoFieldMapping): Promise<GeocodeResult | null>;
+    /**
+     * Extract geo field values organized by their ExtendedType role.
+     */
+    private extractGeoFieldValues;
+    /**
+     * Build an address string suitable for the Google Geocoding API from geo field values.
+     * Orders components logically: Address, City, StateProvince, PostalCode, Country.
+     */
+    private buildAddressString;
+    /**
+     * Call the Google Geocoding API to convert an address string to coordinates.
+     */
+    private geocodeViaGoogle;
+    /**
+     * Resolve CountryID and StateProvinceID from entity geo field values
+     * against the reference Country/StateProvince tables.
+     */
+    /**
+     * Resolve CountryID and StateProvinceID from entity geo field values
+     * using the in-memory GeoDataEngine (O(1) lookups, no DB queries).
+     */
+    private resolveReferenceIDs;
+    /**
+     * Fallback geocoding using reference table centroids from GeoDataEngine.
+     * All lookups are O(1) in-memory — no DB queries.
+     */
+    private geocodeViaReferenceData;
+    /**
+     * Get the Google Geocoding API key from config or environment.
+     */
+    private getGoogleApiKey;
+}
+//# sourceMappingURL=GeoCodeSyncService.d.ts.map

package/dist/GeoCodeSyncService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GeoCodeSyncService.d.ts","sourceRoot":"","sources":["../src/GeoCodeSyncService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAmB,UAAU,EAAqB,QAAQ,EAAuB,MAAM,sBAAsB,CAAC;AACjI,OAAO,EAAE,qBAAqB,EAAiB,MAAM,+BAA+B,CAAC;AACrF,OAAO,EAAE,eAAe,EAAE,aAAa,EAAmC,MAAM,SAAS,CAAC;AAuB1F;;;;;;;;;;;;GAYG;AACH,qBAAa,kBAAmB,SAAQ,aAAa,CAAC,kBAAkB,CAAC;;IAKrE,WAAkB,QAAQ,IAAI,kBAAkB,CAE/C;IAED;;;;;;;;;;;;;OAaG;IACU,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAclI;;;;;;;OAOG;WACW,yBAAyB,CAAC,UAAU,EAAE,UAAU,GAAG,eAAe,EAAE;IAgBlF;;;;OAIG;WACW,YAAY,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO;IAI3D;;;;OAIG;cACa,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAkElI;;OAEG;cACa,mBAAmB,CAC/B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,QAAQ,GACtB,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC;IAcxC;;OAEG;cACa,gBAAgB,CAC5B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,QAAQ,GACtB,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC;IAiBxC;;OAEG;cACa,aAAa,CACzB,GAAG,EAAE,qBAAqB,EAC1B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC;IAiBhB;;;;;OAKG;cACa,mBAAmB,CAAC,GAAG,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW9F;;OAEG;cACa,aAAa,CAAC,GAAG,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW9F;;;;;;OAMG;cACa,OAAO,CACnB,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,eAAe,GAC1B,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IA4ChC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAa7B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAW1B;;OAEG;YACW,gBAAgB;IAwC9B;;;OAGG;IACH;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAqB3B;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IA6C/B;;OAEG;IACH,OAAO,CAAC,eAAe;CAc1B"}

package/dist/GeoCodeSyncService.js

@@ -0,0 +1,435 @@
+import { BaseSingleton } from '@memberjunction/global';
+import { Metadata, RunView, LogError, LogStatus } from '@memberjunction/core';
+import { GeoDataEngine } from '@memberjunction/core-entities';
+import { ComputeGeoSourceHash } from './hash.js';
+/**
+ * Singleton service that manages the geocoding lifecycle for entity records.
+ * Called by CodeGen-generated AfterSave hooks on geo-enabled entities.
+ *
+ * Responsibilities:
+ * - Computes source field hashes for change detection
+ * - Checks existing RecordGeoCode rows for staleness
+ * - Dispatches geocoding (delegates to registered geocoding providers)
+ * - Upserts RecordGeoCode rows with results or error status
+ *
+ * All geocoding is fire-and-forget — errors are captured in RecordGeoCode
+ * and retried by the scheduled geocoding job. Never throws.
+ */
+export class GeoCodeSyncService extends BaseSingleton {
+    constructor() {
+        super();
+    }
+    static get Instance() {
+        return GeoCodeSyncService.getInstance();
+    }
+    /**
+     * Check if any geo field mappings have changed and dispatch geocoding if needed.
+     * Called from the GenericDatabaseProvider OnSaveCompleted hook.
+     *
+     * This method never throws — all errors are captured in RecordGeoCode rows.
+     *
+     * @param entity - The entity instance that was just saved
+     * @param contextUser - The user context for data operations
+     * @param mappings - Field-to-location mappings (if not provided, derived from EntityField.ExtendedType metadata)
+     * @returns The geocode result from the first successfully geocoded mapping, or null
+     *          if no geocoding was performed (e.g., hash unchanged) or all attempts failed.
+     *          The caller can use this to patch virtual lat/lng fields on the entity's
+     *          SP result before finalizeSave() loads it into the entity object.
+     */
+    async SyncIfChanged(entity, contextUser, mappings) {
+        const resolvedMappings = mappings ?? GeoCodeSyncService.BuildMappingsFromMetadata(entity.EntityInfo);
+        for (const mapping of resolvedMappings) {
+            try {
+                const result = await this.ProcessMapping(entity, mapping, contextUser);
+                if (result)
+                    return result;
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                LogError(`GeoCodeSyncService: Error processing ${mapping.LocationType} for ${entity.EntityInfo.Name} ${entity.PrimaryKey.ToString()}: ${message}`);
+            }
+        }
+        return null;
+    }
+    /**
+     * Derive geo field mappings from EntityField.ExtendedType metadata.
+     * Finds all fields with Geo* ExtendedType values and groups them into
+     * a Primary location mapping.
+     *
+     * @param entityInfo - The entity metadata to inspect
+     * @returns Array of geo field mappings (empty if no geo fields found)
+     */
+    static BuildMappingsFromMetadata(entityInfo) {
+        const geoExtTypes = new Set([
+            'Geo', 'GeoAddress', 'GeoCity', 'GeoStateProvince',
+            'GeoCountry', 'GeoPostalCode', 'GeoLatitude', 'GeoLongitude'
+        ]);
+        const geoFields = entityInfo.Fields.filter((f) => f.ExtendedType != null && geoExtTypes.has(f.ExtendedType));
+        if (geoFields.length === 0)
+            return [];
+        return [{
+                LocationType: 'Primary',
+                Fields: geoFields.map((f) => f.Name)
+            }];
+    }
+    /**
+     * Check if an entity has any geo fields defined in its metadata.
+     * @param entityInfo - The entity metadata to check
+     * @returns true if the entity has at least one field with a Geo* ExtendedType
+     */
+    static HasGeoFields(entityInfo) {
+        return entityInfo.SupportsGeoCoding && GeoCodeSyncService.BuildMappingsFromMetadata(entityInfo).length > 0;
+    }
+    /**
+     * Process a single field mapping for a single entity record.
+     * @returns The geocode result if geocoding was performed successfully, or null if
+     *          no geocoding was needed (hash unchanged) or the attempt failed.
+     */
+    async ProcessMapping(entity, mapping, contextUser) {
+        const hash = ComputeGeoSourceHash(entity, mapping.Fields);
+        // Build RecordID matching the format used in the view's LEFT JOIN to vwRecordGeoCodes:
+        // - Single PK: bare value as string (e.g., "38CB433E-F36B-1410-84B4-00BD01F02867")
+        // - Composite PK: values joined with "||" (e.g., "val1||val2")
+        // This must match sql_codegen.ts generateBaseViewJoins() geo JOIN format.
+        const pkPairs = entity.PrimaryKey.KeyValuePairs;
+        const recordId = pkPairs.length === 1
+            ? String(pkPairs[0].Value)
+            : pkPairs.map(pk => String(pk.Value)).join('||');
+        const existing = await this.FindExistingGeoCode(entity.EntityInfo.ID, recordId, mapping.LocationType, contextUser);
+        if (existing && existing.SourceFieldHash === hash && existing.Status === 'success') {
+            return null; // No change, already geocoded successfully
+        }
+        // Upsert a pending row
+        const row = existing ?? await this.CreateGeoCodeRow(entity.EntityInfo.ID, recordId, mapping.LocationType, contextUser);
+        if (!row) {
+            LogError(`GeoCodeSyncService: Failed to create/find RecordGeoCode row`);
+            return null;
+        }
+        row.SourceFieldHash = hash;
+        row.Status = 'pending';
+        row.RetryCount = 0; // Reset retries — fresh attempt for new/changed address
+        row.GeocodedAt = new Date();
+        const pendingSaved = await row.Save();
+        if (!pendingSaved) {
+            LogError(`GeoCodeSyncService: Failed to save pending RecordGeoCode: ${row.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+            return null;
+        }
+        // Attempt geocoding
+        try {
+            const result = await this.Geocode(entity, mapping);
+            if (result) {
+                await this.UpdateSuccess(row, result, hash);
+                return result;
+            }
+            else {
+                // No result means the address can't be geocoded (e.g., "Conference Room B").
+                // Mark as not_geocodable so the retry job skips it. If the user later edits
+                // the address, the hash will change and SyncIfChanged will re-attempt.
+                await this.UpdateNotGeocodable(row, 'Geocoding returned no result — address may not be a valid location');
+            }
+        }
+        catch (e) {
+            // Exception = transient API error — mark as failed for retry
+            const message = e instanceof Error ? e.message : String(e);
+            await this.UpdateFailure(row, message);
+        }
+        return null;
+    }
+    /**
+     * Find an existing RecordGeoCode row for a given entity/record/location type.
+     */
+    async FindExistingGeoCode(entityID, recordID, locationType, contextUser) {
+        const rv = new RunView();
+        const result = await rv.RunView({
+            EntityName: 'MJ: Record Geo Codes',
+            ExtraFilter: `EntityID='${entityID}' AND RecordID='${recordID}' AND LocationType='${locationType}'`,
+            ResultType: 'entity_object',
+            MaxRows: 1
+        }, contextUser);
+        if (result.Success && result.Results.length > 0) {
+            return result.Results[0];
+        }
+        return null;
+    }
+    /**
+     * Create a new RecordGeoCode row.
+     */
+    async CreateGeoCodeRow(entityID, recordID, locationType, contextUser) {
+        const md = new Metadata();
+        const row = await md.GetEntityObject('MJ: Record Geo Codes', contextUser);
+        row.NewRecord();
+        row.EntityID = entityID;
+        row.RecordID = recordID;
+        row.LocationType = locationType;
+        row.Status = 'pending';
+        row.RetryCount = 0;
+        const saved = await row.Save();
+        if (!saved) {
+            LogError(`GeoCodeSyncService: Failed to create RecordGeoCode row: ${row.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+            return null;
+        }
+        return row;
+    }
+    /**
+     * Update a RecordGeoCode row with successful geocoding results.
+     */
+    async UpdateSuccess(row, result, hash) {
+        row.Latitude = result.Latitude;
+        row.Longitude = result.Longitude;
+        row.Precision = result.Precision;
+        row.CountryID = result.CountryID ?? null;
+        row.StateProvinceID = result.StateProvinceID ?? null;
+        row.Status = 'success';
+        row.GeocodingSource = result.Source;
+        row.SourceFieldHash = hash;
+        row.GeocodedAt = new Date();
+        row.ErrorMessage = '';
+        const saved = await row.Save();
+        if (!saved) {
+            LogError(`GeoCodeSyncService: Failed to save successful geocode: ${row.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        }
+    }
+    /**
+     * Mark a RecordGeoCode row as not geocodable — the address can't be resolved
+     * to coordinates (e.g., "Conference Room B", "TBD"). Won't be retried by the
+     * bulk job. If the source record's address fields change, the hash mismatch
+     * in SyncIfChanged will trigger a fresh attempt.
+     */
+    async UpdateNotGeocodable(row, reason) {
+        row.Status = 'failed';
+        row.ErrorMessage = reason;
+        row.RetryCount = 9999; // Permanently skip retries — hash change will reset this
+        row.GeocodedAt = new Date();
+        const saved = await row.Save();
+        if (!saved) {
+            LogError(`GeoCodeSyncService: Failed to save not_geocodable status: ${row.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        }
+    }
+    /**
+     * Update a RecordGeoCode row with failure information (transient error, eligible for retry).
+     */
+    async UpdateFailure(row, errorMessage) {
+        row.Status = 'failed';
+        row.ErrorMessage = errorMessage;
+        row.RetryCount = (row.RetryCount ?? 0) + 1;
+        row.GeocodedAt = new Date();
+        const saved = await row.Save();
+        if (!saved) {
+            LogError(`GeoCodeSyncService: Failed to save failure status: ${row.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        }
+    }
+    /**
+     * Perform the actual geocoding using a priority-based strategy:
+     *
+     * 1. Native lat/lng fields → copy directly (GeocodingSource = 'native')
+     * 2. Address-level fields → external geocoding API (GeocodingSource = 'google')
+     * 3. Country/state only → reference table centroid lookup (GeocodingSource = 'reference_data')
+     */
+    async Geocode(entity, _mapping) {
+        // Strategy 1: Check for native (non-virtual) lat/lng fields.
+        // Virtual fields like __mj_Latitude/__mj_Longitude come from the RecordGeoCode JOIN
+        // and would create circular logic — reading old geocoded values instead of re-geocoding.
+        const latField = entity.EntityInfo.Fields.find(f => f.ExtendedType === 'GeoLatitude' && !f.IsVirtual);
+        const lngField = entity.EntityInfo.Fields.find(f => f.ExtendedType === 'GeoLongitude' && !f.IsVirtual);
+        if (latField && lngField) {
+            const latVal = entity.Get(latField.Name);
+            const lngVal = entity.Get(lngField.Name);
+            const lat = Number(latVal);
+            const lng = Number(lngVal);
+            if (latVal != null && lngVal != null && !isNaN(lat) && !isNaN(lng)) {
+                return {
+                    Latitude: lat,
+                    Longitude: lng,
+                    Precision: 'exact',
+                    CountryID: null,
+                    StateProvinceID: null,
+                    Source: 'native'
+                };
+            }
+        }
+        // Collect address field values organized by their geo role
+        const geoValues = this.extractGeoFieldValues(entity);
+        // Strategy 2: Google Geocoding API (if API key is available)
+        const apiKey = this.getGoogleApiKey();
+        if (apiKey) {
+            const addressString = this.buildAddressString(geoValues);
+            if (addressString) {
+                const googleResult = await this.geocodeViaGoogle(addressString, apiKey);
+                if (googleResult) {
+                    // Resolve country/state IDs from Google's response
+                    this.resolveReferenceIDs(googleResult, entity);
+                    return googleResult;
+                }
+            }
+        }
+        // Strategy 3: Reference data centroid lookup (country/state → approximate lat/lng)
+        return this.geocodeViaReferenceData(geoValues);
+    }
+    /**
+     * Extract geo field values organized by their ExtendedType role.
+     */
+    extractGeoFieldValues(entity) {
+        const values = {};
+        for (const field of entity.EntityInfo.Fields) {
+            if (field.ExtendedType && field.ExtendedType.startsWith('Geo')) {
+                const val = entity.Get(field.Name);
+                if (val != null && String(val).trim() !== '') {
+                    values[field.ExtendedType] = String(val).trim();
+                }
+            }
+        }
+        return values;
+    }
+    /**
+     * Build an address string suitable for the Google Geocoding API from geo field values.
+     * Orders components logically: Address, City, StateProvince, PostalCode, Country.
+     */
+    buildAddressString(geoValues) {
+        const parts = [];
+        if (geoValues['GeoAddress'])
+            parts.push(geoValues['GeoAddress']);
+        if (geoValues['GeoCity'])
+            parts.push(geoValues['GeoCity']);
+        if (geoValues['GeoStateProvince'])
+            parts.push(geoValues['GeoStateProvince']);
+        if (geoValues['GeoPostalCode'])
+            parts.push(geoValues['GeoPostalCode']);
+        if (geoValues['GeoCountry'])
+            parts.push(geoValues['GeoCountry']);
+        if (geoValues['Geo'])
+            parts.push(geoValues['Geo']); // generic location field
+        return parts.length > 0 ? parts.join(', ') : null;
+    }
+    /**
+     * Call the Google Geocoding API to convert an address string to coordinates.
+     */
+    async geocodeViaGoogle(address, apiKey) {
+        try {
+            const url = `https://maps.googleapis.com/maps/api/geocode/json?address=${encodeURIComponent(address)}&key=${apiKey}`;
+            const response = await fetch(url);
+            if (!response.ok) {
+                LogError(`GeoCodeSyncService: Google API HTTP error: ${response.status}`);
+                return null;
+            }
+            const data = await response.json();
+            if (data.status !== 'OK' || !data.results?.length) {
+                LogStatus(`GeoCodeSyncService: Google returned status "${data.status}" for "${address}"`);
+                return null;
+            }
+            const result = data.results[0];
+            const locationType = result.geometry.location_type;
+            // Map Google's location_type to our precision enum
+            let precision = 'city';
+            if (locationType === 'ROOFTOP')
+                precision = 'exact';
+            else if (locationType === 'RANGE_INTERPOLATED')
+                precision = 'exact';
+            else if (locationType === 'GEOMETRIC_CENTER')
+                precision = 'city';
+            else if (locationType === 'APPROXIMATE')
+                precision = 'state_province';
+            return {
+                Latitude: result.geometry.location.lat,
+                Longitude: result.geometry.location.lng,
+                Precision: precision,
+                CountryID: null, // resolved in resolveReferenceIDs
+                StateProvinceID: null, // resolved in resolveReferenceIDs
+                Source: 'google'
+            };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            LogError(`GeoCodeSyncService: Google geocoding error: ${msg}`);
+            return null;
+        }
+    }
+    /**
+     * Resolve CountryID and StateProvinceID from entity geo field values
+     * against the reference Country/StateProvince tables.
+     */
+    /**
+     * Resolve CountryID and StateProvinceID from entity geo field values
+     * using the in-memory GeoDataEngine (O(1) lookups, no DB queries).
+     */
+    resolveReferenceIDs(result, entity) {
+        const geoValues = this.extractGeoFieldValues(entity);
+        const geo = GeoDataEngine.Instance;
+        const countryVal = geoValues['GeoCountry'];
+        if (countryVal) {
+            const country = geo.ResolveCountry(countryVal);
+            if (country) {
+                result.CountryID = country.ID;
+                const stateVal = geoValues['GeoStateProvince'];
+                if (stateVal) {
+                    const state = geo.ResolveState(country.ID, stateVal);
+                    if (state) {
+                        result.StateProvinceID = state.ID;
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Fallback geocoding using reference table centroids from GeoDataEngine.
+     * All lookups are O(1) in-memory — no DB queries.
+     */
+    geocodeViaReferenceData(geoValues) {
+        const geo = GeoDataEngine.Instance;
+        const countryVal = geoValues['GeoCountry'];
+        const stateVal = geoValues['GeoStateProvince'];
+        if (!countryVal && !stateVal) {
+            return null;
+        }
+        // Try state-level first (more precise)
+        if (countryVal && stateVal) {
+            const country = geo.ResolveCountry(countryVal);
+            if (country) {
+                const state = geo.ResolveState(country.ID, stateVal);
+                if (state && state.Latitude != null && state.Longitude != null) {
+                    return {
+                        Latitude: state.Latitude,
+                        Longitude: state.Longitude,
+                        Precision: 'state_province',
+                        CountryID: country.ID,
+                        StateProvinceID: state.ID,
+                        Source: 'reference_data'
+                    };
+                }
+            }
+        }
+        // Fall back to country-level centroid
+        if (countryVal) {
+            const country = geo.ResolveCountry(countryVal);
+            if (country && country.Latitude != null && country.Longitude != null) {
+                return {
+                    Latitude: country.Latitude,
+                    Longitude: country.Longitude,
+                    Precision: 'country',
+                    CountryID: country.ID,
+                    StateProvinceID: null,
+                    Source: 'reference_data'
+                };
+            }
+        }
+        return null;
+    }
+    /**
+     * Get the Google Geocoding API key from config or environment.
+     */
+    getGoogleApiKey() {
+        // Check environment variables
+        const envKey = process.env.GOOGLE_GEOCODING_API_KEY || process.env.GOOGLE_MAPS_API_KEY;
+        if (envKey)
+            return envKey;
+        // Try mj.config.cjs via cosmiconfig pattern
+        try {
+            // Dynamic import to avoid hard dependency on cosmiconfig
+            const configVal = globalThis['__mj_config_apiIntegrations'];
+            return configVal?.google?.geocoding?.apiKey ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=GeoCodeSyncService.js.map

package/dist/GeoCodeSyncService.js.map

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

package/dist/hash.d.ts

@@ -0,0 +1,12 @@
+import { BaseEntity } from '@memberjunction/core';
+/**
+ * Computes a SHA-256 hash of the geo-relevant field values for change detection.
+ * When source fields change on entity save, the hash won't match the stored
+ * SourceFieldHash in RecordGeoCode, triggering re-geocoding.
+ *
+ * @param entity - The entity instance to extract field values from
+ * @param fieldNames - The field names that contribute to geocoding
+ * @returns SHA-256 hex digest of the concatenated field values
+ */
+export declare function ComputeGeoSourceHash(entity: BaseEntity, fieldNames: string[]): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAOrF"}

package/dist/hash.js

@@ -0,0 +1,19 @@
+import { createHash } from 'crypto';
+/**
+ * Computes a SHA-256 hash of the geo-relevant field values for change detection.
+ * When source fields change on entity save, the hash won't match the stored
+ * SourceFieldHash in RecordGeoCode, triggering re-geocoding.
+ *
+ * @param entity - The entity instance to extract field values from
+ * @param fieldNames - The field names that contribute to geocoding
+ * @returns SHA-256 hex digest of the concatenated field values
+ */
+export function ComputeGeoSourceHash(entity, fieldNames) {
+    const values = fieldNames.map(f => {
+        const val = entity.Get(f);
+        return val != null ? String(val).trim() : '';
+    });
+    const input = values.join('|');
+    return createHash('sha256').update(input, 'utf8').digest('hex');
+}
+//# sourceMappingURL=hash.js.map

package/dist/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAGpC;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAkB,EAAE,UAAoB;IACzE,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE;QAC9B,MAAM,GAAG,GAAY,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACnC,OAAO,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACjD,CAAC,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/B,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACpE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './hash.js';
+export * from './GeoCodeSyncService.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './hash.js';
+export * from './GeoCodeSyncService.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,sBAAsB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Mapping from entity fields to a geocodable location.
+ * CodeGen generates these per-entity based on LLM analysis of field names.
+ */
+export interface GeoFieldMapping {
+    /** Discriminator for the location. Currently only 'Primary' is generated by CodeGen. */
+    LocationType: 'Primary';
+    /** Entity field names that contribute to this location's address. */
+    Fields: string[];
+}
+/**
+ * Precision level of a geocoding result.
+ */
+export type GeocodePrecision = 'exact' | 'postal_code' | 'city' | 'county' | 'state_province' | 'country';
+/**
+ * Status of a geocoding attempt.
+ */
+export type GeocodeStatus = 'success' | 'failed' | 'pending';
+/**
+ * Source that produced the geocode.
+ */
+export type GeocodingSource = 'google' | 'reference_data' | 'manual' | 'ip_geolocation' | 'native' | 'reverse';
+/**
+ * Result from a geocoding operation.
+ */
+export interface GeocodeResult {
+    Latitude: number;
+    Longitude: number;
+    Precision: GeocodePrecision;
+    CountryID: string | null;
+    StateProvinceID: string | null;
+    Source: GeocodingSource;
+}
+/**
+ * Distance unit for proximity queries.
+ */
+export type DistanceUnit = 'mi' | 'km';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC5B,wFAAwF;IACxF,YAAY,EAAE,SAAS,CAAC;IACxB,qEAAqE;IACrE,MAAM,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAE1G;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,gBAAgB,GAAG,QAAQ,GAAG,gBAAgB,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE/G;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,eAAe,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,IAAI,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,10 +1,33 @@
 {
   "name": "@memberjunction/geo-core",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @memberjunction/geo-core",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+  "type": "module",
+  "version": "5.25.0",
+  "description": "MemberJunction: Core geo-spatial types, interfaces, and GeoCodeSyncService for geocoding lifecycle management",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "build": "tsc && tsc-alias -f",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "author": "MemberJunction.com",
+  "license": "ISC",
+  "dependencies": {
+    "@memberjunction/global": "5.25.0",
+    "@memberjunction/core": "5.25.0",
+    "@memberjunction/core-entities": "5.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.11",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MemberJunction/MJ"
+  }
 }

package/README.md

@@ -1,45 +0,0 @@
-# @memberjunction/geo-core
-
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/geo-core`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-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.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-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
-
-## DO NOT USE THIS PACKAGE
-
-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
-
-## More Information
-
-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)
-
----
-
-**Maintained for OIDC setup purposes only**