@peopl-health/nexus 6.0.0-dev.466 → 6.0.0-dev.619

package/lib/fhir/resources/MedicationStatement.js

@@ -0,0 +1,42 @@
+const { getSystems } = require('../config/fhirConfig');
+const { fhirId } = require('../helpers/fhirHelper');
+const { identifier, patientReference, codeableConcept } = require('../helpers/elementHelper');
+
+class MedicationStatement {
+  constructor(payload) {
+    Object.assign(this, payload);
+  }
+
+  static fromMentionProjection({ fact, provenance, code, extensions, slug }) {
+    const assertion = fact.assertion;
+    const notes = provenance.verbatimQuotes && provenance.verbatimQuotes.length
+      ? provenance.verbatimQuotes.map((text) => ({ text }))
+      : null;
+    const payload = {
+      resourceType: 'MedicationStatement',
+      id: fhirId(fact.mentionId),
+      identifier: [identifier(slug, fact.mentionId)],
+      status: 'recorded',
+      medication: { concept: code },
+      subject: patientReference(fact.patientId),
+      effectiveDateTime: new Date(fact.reportedAt).toISOString(),
+      extension: extensions,
+    };
+    const adherence = adherenceFor(assertion);
+    if (adherence) {
+      payload.adherence = {
+        code: codeableConcept(adherence, { code: adherence, system: getSystems().medicationStatementAdherence }),
+      };
+    }
+    if (notes) payload.note = notes;
+    return new MedicationStatement(payload);
+  }
+}
+
+function adherenceFor(assertion) {
+  if (assertion.negated) return 'not-taking';
+  if (assertion.temporal === 'historical') return 'stopped';
+  return null;
+}
+
+module.exports = { MedicationStatement };

package/lib/fhir/resources/Observation.js

@@ -0,0 +1,79 @@
+const { getSystems } = require('../config/fhirConfig');
+const { fhirId } = require('../helpers/fhirHelper');
+const { identifier, patientReference, codeableConcept } = require('../helpers/elementHelper');
+
+const OBSERVED_FIELD_SYSTEM_KEY = 'observedField';
+
+const CATEGORY_TO_OBSERVATION_CATEGORY = {
+  symptom: 'survey',
+  lab_value: 'laboratory',
+  emotion: 'survey',
+  indication: 'exam',
+  diagnosis: 'exam',
+};
+
+class Observation {
+  constructor(payload) {
+    Object.assign(this, payload);
+  }
+
+  static fromMentionProjection({ fact, provenance, code, extensions, slug }) {
+    const assertion = fact.assertion;
+    const notes = provenance.verbatimQuotes && provenance.verbatimQuotes.length
+      ? provenance.verbatimQuotes.map((text) => ({ text }))
+      : null;
+    const categoryCode = CATEGORY_TO_OBSERVATION_CATEGORY[fact.category] || 'exam';
+    const payload = {
+      resourceType: 'Observation',
+      id: fhirId(fact.mentionId),
+      identifier: [identifier(slug, fact.mentionId)],
+      status: 'preliminary',
+      category: [observationCategory(categoryCode)],
+      code,
+      subject: patientReference(fact.patientId),
+      performer: [patientReference(fact.patientId)],
+      effectiveDateTime: new Date(fact.reportedAt).toISOString(),
+      issued: new Date(provenance.recordedAt).toISOString(),
+      extension: extensions,
+    };
+    if (assertion.negated) {
+      payload.interpretation = [codeableConcept('Negative', { code: 'NEG', system: getSystems().observationInterpretation, display: 'Negative' })];
+      payload.valueCodeableConcept = codeableConcept('Ausente (negado por el paciente)');
+    }
+    if (notes) payload.note = notes;
+    const components = observedFieldComponents(fact.observedFields);
+    if (components.length) payload.component = components;
+    return new Observation(payload);
+  }
+}
+
+function observationCategory(code) {
+  const label = code.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+  return codeableConcept(label, { code, system: getSystems().observationCategory, display: label });
+}
+
+function observedFieldComponents(observedFields) {
+  const components = [];
+  for (const [key, raw] of Object.entries(observedFields || {})) {
+    const text = stringifyObserved(raw);
+    if (!text) continue;
+    components.push({
+      code: codeableConcept(key, { code: key, system: getSystems()[OBSERVED_FIELD_SYSTEM_KEY] }),
+      valueString: text,
+    });
+  }
+  return components;
+}
+
+function stringifyObserved(value) {
+  if (value === null || value === undefined) return '';
+  if (Array.isArray(value)) {
+    return value.filter((v) => v !== null && v !== undefined).map((v) => String(v).trim()).filter(Boolean).join('; ');
+  }
+  if (typeof value === 'object') {
+    return Object.entries(value).filter(([, v]) => v !== null && v !== undefined && String(v).trim()).map(([k, v]) => `${k}: ${v}`).join('; ');
+  }
+  return String(value).trim();
+}
+
+module.exports = { Observation };

package/lib/fhir/resources/Procedure.js

@@ -0,0 +1,30 @@
+const { fhirId } = require('../helpers/fhirHelper');
+const { identifier, patientReference } = require('../helpers/elementHelper');
+
+class Procedure {
+  constructor(payload) {
+    Object.assign(this, payload);
+  }
+
+  static fromMentionProjection({ fact, provenance, code, extensions, slug }) {
+    const assertion = fact.assertion;
+    const notes = provenance.verbatimQuotes && provenance.verbatimQuotes.length
+      ? provenance.verbatimQuotes.map((text) => ({ text }))
+      : null;
+    const payload = {
+      resourceType: 'Procedure',
+      id: fhirId(fact.mentionId),
+      identifier: [identifier(slug, fact.mentionId)],
+      status: assertion.negated ? 'not-done' : 'completed',
+      code,
+      subject: patientReference(fact.patientId),
+      occurrenceDateTime: new Date(fact.reportedAt).toISOString(),
+      recorder: patientReference(fact.patientId),
+      extension: extensions,
+    };
+    if (notes) payload.note = notes;
+    return new Procedure(payload);
+  }
+}
+
+module.exports = { Procedure };

package/lib/fhir/resources/Provenance.js

@@ -0,0 +1,28 @@
+const { getDeviceId, getOrganizationId } = require('../config/fhirConfig');
+const { fhirId } = require('../helpers/fhirHelper');
+const { extension, reference, codeableConcept } = require('../helpers/elementHelper');
+
+class Provenance {
+  constructor(payload) {
+    Object.assign(this, payload);
+  }
+
+  static fromMentionProjection({ target, provenance, activityText }) {
+    const payload = {
+      resourceType: 'Provenance',
+      id: fhirId(`${provenance.mentionId}-prov`),
+      target: [{ reference: `${target.resourceType}/${target.id}` }],
+      recorded: new Date(provenance.recordedAt).toISOString(),
+      agent: [{ who: reference('Device', getDeviceId()), onBehalfOf: reference('Organization', getOrganizationId()) }],
+      activity: codeableConcept(activityText),
+      extension: [
+        extension('mention-turn-id', { valueString: provenance.turnId }),
+        extension('mention-source', { valueString: provenance.source }),
+        extension('mention-extractor-confidence', { valueDecimal: provenance.extractorConfidence }),
+      ],
+    };
+    return new Provenance(payload);
+  }
+}
+
+module.exports = { Provenance };

package/lib/fhir/services/clinicalMentionService.js

@@ -0,0 +1,18 @@
+const { PROJECTOR_NAME } = require('../projections/clinicalMentionProjection');
+const { project, storeResources } = require('./fhirService');
+
+async function storeClinicalMentions({ patientId, mentions }) {
+  for (const mention of mentions) {
+    if (mention.fact.patientId !== patientId || mention.provenance.patientId !== patientId) {
+      throw new Error(`storeClinicalMentions patientId mismatch: expected ${patientId}`);
+    }
+  }
+  const bundle = project(mentions.map((mention) => ({ name: PROJECTOR_NAME, aggregate: mention })));
+  const resources = bundle.entry.map((entry) => entry.resource);
+  const { stored } = await storeResources(resources);
+  return { stored: stored.length, ids: stored, patientId };
+}
+
+module.exports = {
+  storeClinicalMentions,
+};

package/lib/fhir/services/fhirService.js

@@ -0,0 +1,31 @@
+const { createProjectorRegistry } = require('../../helpers/projectorHelper');
+const { getFhirStore } = require('../stores/fhirStore');
+
+const registry = createProjectorRegistry({
+  label: 'FHIR projector',
+  assemble: (items) => {
+    const entry = items
+      .flatMap(({ content }) => (content || []).flat())
+      .map((resource) => ({ resource }));
+    return { resourceType: 'Bundle', type: 'collection', entry };
+  },
+});
+
+function project(items) {
+  return registry.project(items);
+}
+
+async function storeResources(resources, { store = null } = {}) {
+  const resourceStore = store || getFhirStore();
+  const stored = [];
+  for (const resource of [resources].flat(Infinity).filter((entry) => entry && entry.resourceType)) {
+    stored.push(await resourceStore.upsert(resource));
+  }
+  return { stored };
+}
+
+module.exports = {
+  registerProjector: registry.register,
+  project,
+  storeResources,
+};

package/lib/fhir/stores/fhirStore.js

@@ -0,0 +1,187 @@
+const { isDeepStrictEqual } = require('node:util');
+
+const { fhirConnection } = require('../config/connection');
+const { getCatalog } = require('../config/catalogConfig');
+const { identifierSystem } = require('../helpers/fhirHelper');
+
+const { envelopeSchema } = require('../models/envelopeModel');
+const { historySchema } = require('../models/historyModel');
+
+const FHIR_VIEW = 'fhirResourceView';
+const FHIR_HISTORY = 'fhirHistory';
+const UPSERT_ATTEMPTS = 3;
+const NEWEST_FIRST = { 'index.date': -1 };
+
+class FhirStore {
+  constructor({ conn = null } = {}) {
+    this.connection = conn || fhirConnection();
+    this.db = this.connection.db;
+    this.viewSignature = null;
+  }
+
+  async upsert(resourceInput, { merge = null } = {}) {
+    const incoming = this._toStoredResource(resourceInput);
+    const entry = await this._entryFor(incoming.resourceType);
+    const model = this._modelFrom(entry);
+    const resourceKey = model.resourceKeyOf(incoming);
+    for (let attempt = 0; attempt < UPSERT_ATTEMPTS; attempt++) {
+      const priorVersion = await model.findOne({ resourceKey }).lean();
+      const resource = merge && priorVersion ? this._toStoredResource(merge(priorVersion.resource, incoming)) : incoming;
+      if (resource !== incoming && model.resourceKeyOf(resource) !== resourceKey) {
+        throw new Error(`merge changed the resource key for ${resourceKey}`);
+      }
+      assertDeclaredIdentifiers(resource, entry);
+      if (!priorVersion) {
+        try {
+          await model.create(model.buildEnvelope(resource));
+          return resourceKey;
+        } catch (error) {
+          if (error.code !== 11000) throw error;
+          continue;
+        }
+      }
+      if (isDeepStrictEqual(priorVersion.resource, resource) && !priorVersion.meta.deleted) return resourceKey;
+      await this._archivePriorVersion(priorVersion);
+      const result = await model.updateOne(
+        { resourceKey, 'meta.version': priorVersion.meta.version },
+        { $set: { index: model.deriveIndex(resource), resource, 'meta.version': priorVersion.meta.version + 1, 'meta.deleted': false } },
+      );
+      if (result.matchedCount === 1) return resourceKey;
+    }
+    throw new Error(`concurrent updates exhausted ${UPSERT_ATTEMPTS} attempts for ${resourceKey}`);
+  }
+
+  async delete(resourceKey) {
+    const [resourceType] = resourceKey.split('|');
+    const model = await this._modelFor(resourceType);
+    for (let attempt = 0; attempt < UPSERT_ATTEMPTS; attempt++) {
+      const priorVersion = await model.findOne({ resourceKey }).lean();
+      if (!priorVersion || priorVersion.meta.deleted) return null;
+      await this._archivePriorVersion(priorVersion);
+      const result = await model.updateOne(
+        { resourceKey, 'meta.version': priorVersion.meta.version },
+        { $set: { 'meta.version': priorVersion.meta.version + 1, 'meta.deleted': true } },
+      );
+      if (result.matchedCount === 1) return resourceKey;
+    }
+    throw new Error(`concurrent updates exhausted ${UPSERT_ATTEMPTS} attempts for ${resourceKey}`);
+  }
+
+  async getByKey(resourceKey) {
+    const [resourceType] = resourceKey.split('|');
+    const model = await this._modelFor(resourceType);
+    const envelope = await model.findOne({ resourceKey }).lean();
+    if (!envelope || envelope.meta.deleted) return null;
+    return envelope.resource;
+  }
+
+  async getByReference(reference) {
+    const [resourceType] = String(reference).split('/');
+    const model = await this._modelFor(resourceType);
+    const envelope = await model.findOne({ 'index.reference': reference, 'meta.deleted': false }).lean();
+    return envelope ? envelope.resource : null;
+  }
+
+  async find({ patient = null, resourceType = null, symptomTerm = null } = {}) {
+    const query = { 'meta.deleted': false };
+    if (patient) query['index.patient'] = patient;
+    if (symptomTerm) query['index.symptomTerm'] = symptomTerm;
+    if (resourceType) {
+      const model = await this._modelFor(resourceType);
+      const envelopes = await model.find(query, null, { sort: NEWEST_FIRST }).lean();
+      return envelopes.map((envelope) => envelope.resource);
+    }
+    await this._ensureView();
+    const envelopes = await this.db.collection(FHIR_VIEW).find(query, { sort: NEWEST_FIRST }).toArray();
+    return envelopes.map((envelope) => envelope.resource);
+  }
+
+  async getHistory(resourceKey) {
+    return this._historyModel().find({ resourceKey }, null, { sort: { 'meta.version': 1 } }).lean();
+  }
+
+  async ensureIndexes() {
+    const { resourceTypes } = await getCatalog();
+    for (const resourceType of resourceTypes) {
+      await (await this._modelFor(resourceType)).createIndexes();
+    }
+    await this._historyModel().createIndexes();
+  }
+
+  _toStoredResource(resource) {
+    return JSON.parse(JSON.stringify(resource));
+  }
+
+  async _entryFor(resourceType) {
+    const { catalog } = await getCatalog();
+    const entry = catalog[resourceType];
+    if (!entry) throw new Error(`cannot route resourceType ${resourceType} to a collection`);
+    return entry;
+  }
+
+  _modelFrom(entry) {
+    const name = entry.collection;
+    return this.connection.models[name] || this.connection.model(name, envelopeSchema, name);
+  }
+
+  async _modelFor(resourceType) {
+    const entry = await this._entryFor(resourceType);
+    return this._modelFrom(entry);
+  }
+
+  _historyModel() {
+    return this.connection.models[FHIR_HISTORY] || this.connection.model(FHIR_HISTORY, historySchema, FHIR_HISTORY);
+  }
+
+  async _archivePriorVersion(priorVersion) {
+    try {
+      await this._historyModel().create({
+        resourceKey: priorVersion.resourceKey,
+        resource: priorVersion.resource,
+        meta: priorVersion.meta,
+      });
+    } catch (error) {
+      if (error.code !== 11000) throw error;
+    }
+  }
+
+  async _ensureView() {
+    const { catalog, resourceTypes } = await getCatalog();
+    const collections = resourceTypes.map((type) => catalog[type].collection);
+    const signature = collections.join(',');
+    if (this.viewSignature === signature) return;
+    const [primary, ...rest] = collections;
+    const pipeline = rest.map((name) => ({ $unionWith: name }));
+    try {
+      await this.db.createCollection(FHIR_VIEW, { viewOn: primary, pipeline });
+    } catch (error) {
+      if (error.codeName !== 'NamespaceExists') throw error;
+      await this.db.command({ collMod: FHIR_VIEW, viewOn: primary, pipeline });
+    }
+    this.viewSignature = signature;
+  }
+}
+
+function assertDeclaredIdentifiers(resource, entry) {
+  const slugs = entry.identifierSlugs || [];
+  if (!slugs.length) return;
+  const allowed = new Set(slugs.map((slug) => identifierSystem(slug)));
+  for (const id of resource.identifier || []) {
+    if (id.system && id.value && !allowed.has(id.system)) {
+      throw new Error(
+        `${resource.resourceType} identifier ${id.system} is not a declared identifierSlug (${slugs.join(', ')})`,
+      );
+    }
+  }
+}
+
+let instance = null;
+
+function getFhirStore() {
+  if (!instance) instance = new FhirStore();
+  return instance;
+}
+
+const ensureFhirIndexes = () => getFhirStore().ensureIndexes();
+
+module.exports = { FhirStore, getFhirStore, ensureFhirIndexes };

package/lib/helpers/deliveryAttemptHelper.js

@@ -3,8 +3,6 @@ const { logger } = require('../utils/logger');
 const { Message } = require('../models/messageModel');
 const { DeliveryAttempt, DELIVERY_ATTEMPT_TERMINAL_STATUSES } = require('../models/deliveryAttemptModel');
 
-const { getMessages } = require('../services/messageService');
-
 async function recordDeliveryAttempt({
   messageData = null, messageId = null, twilioResult = null, kind, body = null,
   errorSource = null, errorCode = null, errorMessage = null
@@ -12,22 +10,16 @@ async function recordDeliveryAttempt({
   const sid = twilioResult?.sid || null;
   if (!sid && !errorSource) return null;
 
-  let targetId = messageId;
-  if (!targetId) {
-    if (!sid) return null;
-    const [msgDoc] = await getMessages({ message_id: sid }, { select: '_id', limit: 1 });
-    if (!msgDoc) {
-      logger.warn('[deliveryAttemptHelper] Message not found for SID; skipping attempt record', { twilioSid: sid });
-      return null;
-    }
-    targetId = msgDoc._id;
+  if (!messageId) {
+    logger.warn('[deliveryAttemptHelper] No messageId provided; skipping attempt record', { twilioSid: sid, kind });
+    return null;
   }
 
   try {
     const status = errorSource ? 'failed' : (twilioResult?.status?.toLowerCase() || null);
 
     const attempt = await DeliveryAttempt.create({
-      messageId: targetId,
+      messageId,
       kind,
       twilioSid: sid,
       contentSid: messageData?.contentSid || null,
@@ -41,7 +33,7 @@ async function recordDeliveryAttempt({
 
     if (status) {
       await Message.updateOne(
-        { _id: targetId },
+        { _id: messageId },
         { $set: {
           'statusInfo.status': status,
           'statusInfo.updatedAt': new Date(),

package/lib/helpers/projectorHelper.js

@@ -0,0 +1,18 @@
+function createProjectorRegistry({ assemble, label = 'projector' }) {
+  const projectors = new Map();
+  return {
+    register: (name, fn) => projectors.set(name, fn),
+    project: (items) =>
+      assemble(
+        items.map(({ name, aggregate }) => {
+          const fn = projectors.get(name);
+          if (!fn) throw new Error(`no ${label} registered for '${name}'`);
+          return { name, content: fn(aggregate) };
+        }),
+      ),
+  };
+}
+
+module.exports = {
+  createProjectorRegistry,
+};

package/lib/helpers/twilioMediaHelper.js

@@ -3,6 +3,7 @@ const { Monitoreo_ID } = require('../config/airtableConfig');
 const runtimeConfig = require('../config/runtimeConfig');
 
 const { validateMedia } = require('../utils/mediaValidator');
+const { extractContact } = require('../utils/vcardParser');
 const { logger } = require('../utils/logger');
 
 const { addLinkedRecord } = require('../services/airtableService');
@@ -15,6 +16,8 @@ const {
 } = require('./twilioHelper');
 const { uploadMediaToS3 } = require('./mediaHelper');
 
+const CONTACT_CONTENT_TYPES = new Set(['text/vcard', 'text/x-vcard']);
+
 const normalizeMediaType = (type) => {
   if (!type || typeof type !== 'string') return 'document';
   return type.replace(/Message$/i, '').replace(/WithCaption$/i, '').toLowerCase();
@@ -155,7 +158,28 @@ async function enrichMessageWithTwilioMedia(rawMessage) {
   return { mediaPayload, caption: primary.caption };
 }
 
+function isContactContentType(contentType) {
+  return CONTACT_CONTENT_TYPES.has((contentType || '').split(';')[0].trim().toLowerCase());
+}
+
+async function resolveContactFromTwilioMedia(rawMessage) {
+  const numMedia = parseInt(rawMessage?.NumMedia || '0', 10);
+  if (numMedia <= 0 || !rawMessage.MediaUrl0 || !isContactContentType(rawMessage.MediaContentType0)) return null;
+
+  let buffer;
+  try {
+    buffer = await downloadMediaFromTwilio(rawMessage.MediaUrl0, logger);
+  } catch (error) {
+    logger.error('[TwilioMedia] Contact download failed', { error: error.message });
+    return null;
+  }
+  if (!buffer) return null;
+
+  return extractContact(buffer.toString('utf8'));
+}
+
 module.exports = {
   processTwilioMediaMessage,
-  enrichMessageWithTwilioMedia
+  enrichMessageWithTwilioMedia,
+  resolveContactFromTwilioMedia
 };

package/lib/index.js

@@ -15,7 +15,9 @@ const {
   configureAssistants: setAssistantsConfig,
   DefaultMemoryManager,
   EnhancedMemoryManager,
+  initialize: initializeClinical,
 } = require('./clinical');
+const { initialize: initializeFhir } = require('./fhir');
 const { logger } = require('./utils/logger');
 const runtimeConfig = require('./config/runtimeConfig');
 const { setModelDatabases, setModelDatabase, getModelDatabase, connect: mongoConnect, disconnect: mongoDisconnect, getConnection: mongoGetConnection } = require('./config/mongoConfig');
@@ -143,6 +145,18 @@ class Nexus {
       logger.warn('Warning: failed to configure assistants:', e?.message || e);
     }
 
+    try {
+      await initializeFhir();
+    } catch (e) {
+      logger.warn('[Nexus] fhir init skipped', { error: e?.message || e });
+    }
+
+    try {
+      await initializeClinical();
+    } catch (e) {
+      logger.warn('[Nexus] clinical init skipped', { error: e?.message || e });
+    }
+
     this.isInitialized = true;
   }
 

package/lib/services/airtableService.js

@@ -4,6 +4,10 @@ const { logger } = require('../utils/logger');
 const { isBenchMode } = require('../utils/benchModeHelper');
 const { isShadowRun } = require('../clinical/helpers/shadowHelper');
 
+const TRANSIENT_STATUS_CODES = [500, 502, 503];
+const MAX_ATTEMPTS = 3;
+const RETRY_BASE_DELAY_MS = 1000;
+
 let evalMode = false;
 
 function setEvalMode(enabled) {
@@ -16,6 +20,23 @@ function getBase(baseID) {
   return airtable.base(baseID);
 }
 
+const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+
+async function withAirtableRetry(operation, label) {
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      const isTransient = TRANSIENT_STATUS_CODES.includes(error.statusCode);
+      if (!isTransient || attempt === MAX_ATTEMPTS) {
+        throw error;
+      }
+      logger.warn(`[${label}] Airtable unavailable, retrying`, { statusCode: error.statusCode, attempt, maxAttempts: MAX_ATTEMPTS });
+      await delay(RETRY_BASE_DELAY_MS * attempt);
+    }
+  }
+}
+
 async function collectRecords(query, mapper = r => r.fields) {
   const records = [];
   await query.eachPage((pageRecords, fetchNextPage) => {
@@ -35,7 +56,7 @@ async function addRecord(baseID, tableName, fields, context = null) {
     return { id: 'eval_mock_record', fields: Array.isArray(fields) ? fields[0]?.fields || {} : fields };
   }
   try {
-    const record = await getBase(baseID)(tableName).create(fields);
+    const record = await withAirtableRetry(() => getBase(baseID)(tableName).create(fields), 'addRecord');
     logger.info('[addRecord] Created', { tableName });
     return record;
   } catch (error) {
@@ -46,8 +67,9 @@ async function addRecord(baseID, tableName, fields, context = null) {
 
 async function getRecords(baseID, tableName) {
   try {
-    return await collectRecords(
-      getBase(baseID)(tableName).select({ maxRecords: 3 })
+    return await withAirtableRetry(
+      () => collectRecords(getBase(baseID)(tableName).select({ maxRecords: 3 })),
+      'getRecords'
     );
   } catch (error) {
     logger.error('[getRecords] Failed', { tableName, error: error.message });
@@ -58,8 +80,9 @@ async function getRecordByFilter(baseID, tableName, filter, view = 'Grid view',
   try {
     const selectOptions = { filterByFormula: filter, view };
     if (fields && fields.length) selectOptions.fields = fields;
-    return await collectRecords(
-      getBase(baseID)(tableName).select(selectOptions)
+    return await withAirtableRetry(
+      () => collectRecords(getBase(baseID)(tableName).select(selectOptions)),
+      'getRecordByFilter'
     );
   } catch (error) {
     logger.error('[getRecordByFilter] Failed', { tableName, filter, fields, error: error.message });
@@ -77,16 +100,18 @@ async function updateRecordByFilter(baseID, tableName, filter, updateFields, con
   }
   try {
     const base = getBase(baseID);
-    const records = [];
 
-    await base(tableName).select({ filterByFormula: filter }).eachPage((pageRecords, fetchNextPage) => {
-      records.push(...pageRecords);
-      fetchNextPage();
-    });
+    const records = await withAirtableRetry(
+      () => collectRecords(base(tableName).select({ filterByFormula: filter }), r => r),
+      'updateRecordByFilter'
+    );
 
     const updatedRecords = [];
     for (const record of records) {
-      updatedRecords.push(await base(tableName).update(record.id, updateFields));
+      updatedRecords.push(await withAirtableRetry(
+        () => base(tableName).update(record.id, updateFields),
+        'updateRecordByFilter'
+      ));
     }
 
     return updatedRecords;
@@ -106,9 +131,10 @@ async function addLinkedRecord(baseID, targetTable, fields, linkConfig, context
   try {
     if (linkConfig) {
       const { referenceTable, referenceFilter, linkFieldName } = linkConfig;
-      const referenceRecords = await getBase(baseID)(referenceTable)
-        .select({ filterByFormula: referenceFilter })
-        .firstPage();
+      const referenceRecords = await withAirtableRetry(
+        () => getBase(baseID)(referenceTable).select({ filterByFormula: referenceFilter }).firstPage(),
+        'addLinkedRecord'
+      );
 
       if (linkFieldName && referenceRecords?.[0]?.id) {
         fields[linkFieldName] = [referenceRecords[0].id];

package/lib/shared/dtos/BaseDto.js

@@ -0,0 +1,13 @@
+class BaseDto {
+  constructor(payload) {
+    if (new.target === BaseDto) {
+      throw new Error('BaseDto is abstract and cannot be instantiated directly');
+    }
+    if (typeof new.target.schema?.parse !== 'function') {
+      throw new Error(`${new.target.name} must define a static Zod schema`);
+    }
+    Object.assign(this, new.target.schema.parse(payload));
+  }
+}
+
+module.exports = { BaseDto };