@engine9/schemas 1.9.0

package/person/ui.console.json5

@@ -0,0 +1,165 @@
+{
+  menu: {
+    people: {
+      title: 'People',
+      icon: 'people',
+      type: 'collapse',
+      children: {
+        'person-list': {
+          title: 'Everybody',
+          icon: 'person',
+          url: '/person'
+        }
+      }
+    }
+  },
+  routes: {
+    person: {
+      layout: 'full_width',
+      components: {
+        header: [
+          'Everybody',
+          {
+            component: 'Button',
+            properties: {
+              icon: 'plus',
+              content: 'Add Person',
+              onClick: {
+                action: 'navigate',
+                url: '/person/create'
+              }
+            }
+          }
+        ],
+        main: [
+          {
+            component: 'RecordList',
+            properties: {
+              table: 'person',
+              includes: {
+                emails: {
+                  table: 'person_email'
+                }
+              },
+              columns: [
+                {
+                  title: 'Id',
+                  dataIndex: 'id',
+                  sorter: true,
+                  width: '20%'
+                },
+                {
+                  title: 'Name',
+                  dataIndex: 'name',
+                  sorter: true,
+                  template: '{{given_name}} {{family_name}} {{emails.0.email}}',
+                  width: '40%'
+                },
+                {
+                  title: 'Email',
+                  template: '{{emails.0.email}}',
+                  width: '40%'
+                }
+              ],
+              onRow: {
+                onClick: {
+                  action: 'navigate',
+                  url: '/person/{{record.id}}'
+                }
+              }
+            }
+          }
+        ]
+      }
+    },
+    'person/create': {
+      layout: 'full_width',
+      components: {
+        main: [
+          {
+            path: 'edit',
+            component: 'RecordForm',
+            properties: {
+              table: 'person',
+              form: {
+                title: 'Todo',
+                type: 'object',
+                required: [],
+                properties: {
+                  given_name: { type: 'string', title: 'First Name', default: '' },
+                  family_name: { type: 'string', title: 'Last Name', default: '' }
+                }
+              },
+              uiSchema: {
+                family_name: { 'ui:widget': 'textarea' }
+              },
+              onSave: {
+                action: 'navigate',
+                url: '/person/{{record.id}}'
+              }
+            }
+          }
+        ]
+      }
+    },
+    'person/:id/*': {
+      layout: 'sidebar',
+      components: {
+        sidebar: {
+          title: 'Person Details',
+          items: [
+            {
+              component: 'RecordDisplay',
+              properties: {
+                table: 'person',
+                id: '{{parameters.id}}',
+                includes: {
+                  emails: {
+                    table: 'person_email',
+                    orderBy: 'preference_order'
+                  }
+                },
+                template: '{{given_name}} {{family_name}} {{#if emails.0.email}}<{{emails.0.email}}>{{/if}}'
+              }
+            },
+            {
+              component: 'Link',
+              properties: {
+                label: 'Edit',
+                to: 'edit'
+              }
+            }
+          ]
+        },
+        main: [
+          {
+            // 'path':'overview', //no path is the default
+            component: 'RecordDisplay',
+            properties: {
+              table: 'person',
+              id: '{{parameters.id}}',
+              template: '{{given_name}} {{family_name}}'
+            }
+          },
+          {
+            path: 'edit',
+            component: 'RecordForm',
+            properties: {
+              table: 'person',
+              id: '{{parameters.id}}',
+              form: {
+                title: 'Todo',
+                type: 'object',
+                required: [],
+                properties: {
+                  given_name: { type: 'string', title: 'First Name', default: '' },
+                  family_name: { type: 'string', title: 'Last Name', default: '' }
+                }
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/person/upsert.test.js

@@ -0,0 +1,72 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import upsertPerson from './transforms/inbound/upsert_tables.js';
+
+describe('person upsert_tables', () => {
+  it('queues a name column only when that key is present', async () => {
+    const tablesToUpsert = {};
+    await upsertPerson.transform({
+      batch: [{ person_id: 1, email: 'ada@example.com', given_name: 'Ada' }],
+      tablesToUpsert
+    });
+    assert.deepEqual(tablesToUpsert.person, [{ id: 1, given_name: 'Ada' }]);
+    assert.equal('family_name' in tablesToUpsert.person[0], false);
+  });
+
+  it('queues family_name alone when given_name is omitted', async () => {
+    const tablesToUpsert = {};
+    await upsertPerson.transform({
+      batch: [{ person_id: 2, email: 'lovelace@example.com', family_name: 'Lovelace' }],
+      tablesToUpsert
+    });
+    assert.deepEqual(tablesToUpsert.person, [{ id: 2, family_name: 'Lovelace' }]);
+    assert.equal('given_name' in tablesToUpsert.person[0], false);
+  });
+
+  it('queues both names when both keys are present', async () => {
+    const tablesToUpsert = {};
+    await upsertPerson.transform({
+      batch: [{ person_id: 3, given_name: 'Ada', family_name: 'Lovelace' }],
+      tablesToUpsert
+    });
+    assert.deepEqual(tablesToUpsert.person, [{ id: 3, given_name: 'Ada', family_name: 'Lovelace' }]);
+  });
+
+  it('keeps an explicit null so that column clears', async () => {
+    const tablesToUpsert = {};
+    await upsertPerson.transform({
+      batch: [{ person_id: 4, given_name: 'Ada', family_name: null }],
+      tablesToUpsert
+    });
+    assert.deepEqual(tablesToUpsert.person, [{ id: 4, given_name: 'Ada', family_name: null }]);
+  });
+
+  it('clears a name when that key is present and null and the other name is omitted', async () => {
+    const tablesToUpsert = {};
+    await upsertPerson.transform({
+      batch: [{ person_id: 5, family_name: null }],
+      tablesToUpsert
+    });
+    assert.deepEqual(tablesToUpsert.person, [{ id: 5, family_name: null }]);
+  });
+
+  it('omits the person upsert when neither name key is present', async () => {
+    const tablesToUpsert = {};
+    await upsertPerson.transform({
+      batch: [{ person_id: 6, email: 'ada@example.com' }, { email: 'no-id@example.com' }],
+      tablesToUpsert
+    });
+    assert.equal('person' in tablesToUpsert, false);
+  });
+
+  it('throws when a name is present and person_id is missing', async () => {
+    await assert.rejects(
+      () =>
+        upsertPerson.transform({
+          batch: [{ given_name: 'Ada' }],
+          tablesToUpsert: {}
+        }),
+      /no person_id/
+    );
+  });
+});

package/person_address/index.js

@@ -0,0 +1,30 @@
+import upsertPersonAddress from './transforms/inbound/upsert_tables.js';
+import normalize from './transforms/inbound/normalize.js';
+import appendAddress from './transforms/outbound/appendAddress.js';
+import schema from './schema.js';
+
+const metadata = {
+  name: '@engine9/schemas/person_address',
+  dependencies: {
+    '@engine9/schemas/person': '>=1.9.0'
+  },
+  // Inbound people pipeline slots -> transform export keys (woven by core when installed).
+  // `normalize` stays a standalone export; upsert already normalizes inline.
+  inbound: {
+    upsert: ['upsertPersonAddress']
+  }
+};
+
+export const transforms = {
+  normalize,
+  upsertPersonAddress,
+  appendAddress
+};
+
+export { metadata };
+export { schema };
+export default {
+  metadata,
+  schema,
+  transforms
+};

package/person_address/normalize.js

@@ -0,0 +1,232 @@
+import { addressNormalize } from '@zerodep/address-normalize';
+import countries from 'i18n-iso-countries';
+import enLocale from 'i18n-iso-countries/langs/en.json' with { type: 'json' };
+
+countries.registerLocale(enLocale);
+
+/** US state / DC / territory names and common aliases → ISO-3166-2 region codes */
+const US_REGION_ALIASES = {
+  alabama: 'AL',
+  alaska: 'AK',
+  arizona: 'AZ',
+  arkansas: 'AR',
+  california: 'CA',
+  colorado: 'CO',
+  connecticut: 'CT',
+  delaware: 'DE',
+  'district of columbia': 'DC',
+  florida: 'FL',
+  georgia: 'GA',
+  hawaii: 'HI',
+  idaho: 'ID',
+  illinois: 'IL',
+  indiana: 'IN',
+  iowa: 'IA',
+  kansas: 'KS',
+  kentucky: 'KY',
+  louisiana: 'LA',
+  maine: 'ME',
+  maryland: 'MD',
+  massachusetts: 'MA',
+  michigan: 'MI',
+  minnesota: 'MN',
+  mississippi: 'MS',
+  missouri: 'MO',
+  montana: 'MT',
+  nebraska: 'NE',
+  nevada: 'NV',
+  'new hampshire': 'NH',
+  'new jersey': 'NJ',
+  'new mexico': 'NM',
+  'new york': 'NY',
+  'north carolina': 'NC',
+  'north dakota': 'ND',
+  ohio: 'OH',
+  oklahoma: 'OK',
+  oregon: 'OR',
+  pennsylvania: 'PA',
+  'rhode island': 'RI',
+  'south carolina': 'SC',
+  'south dakota': 'SD',
+  tennessee: 'TN',
+  texas: 'TX',
+  utah: 'UT',
+  vermont: 'VT',
+  virginia: 'VA',
+  washington: 'WA',
+  'west virginia': 'WV',
+  wisconsin: 'WI',
+  wyoming: 'WY',
+  'puerto rico': 'PR',
+  guam: 'GU',
+  'american samoa': 'AS',
+  'us virgin islands': 'VI',
+  'u.s. virgin islands': 'VI',
+  'virgin islands': 'VI',
+  'northern mariana islands': 'MP'
+};
+
+/** Canadian province / territory names → codes */
+const CA_REGION_ALIASES = {
+  alberta: 'AB',
+  'british columbia': 'BC',
+  manitoba: 'MB',
+  'new brunswick': 'NB',
+  'newfoundland and labrador': 'NL',
+  newfoundland: 'NL',
+  'northwest territories': 'NT',
+  'nova scotia': 'NS',
+  nunavut: 'NU',
+  ontario: 'ON',
+  'prince edward island': 'PE',
+  quebec: 'QC',
+  québec: 'QC',
+  saskatchewan: 'SK',
+  yukon: 'YT',
+  'yukon territory': 'YT'
+};
+
+const VALID_US_REGIONS = new Set(Object.values(US_REGION_ALIASES));
+const VALID_CA_REGIONS = new Set(Object.values(CA_REGION_ALIASES));
+
+function emptyToNull(value) {
+  if (value == null) return null;
+  const s = String(value).trim();
+  return s === '' ? null : s;
+}
+
+/**
+ * Normalize a street / city string for storage and dedupe.
+ * Does not validate deliverability — only standardizes abbreviations and punctuation.
+ */
+export function normalizeStreetLine(value) {
+  const raw = emptyToNull(value);
+  if (!raw) return null;
+  try {
+    const normalized = addressNormalize(raw);
+    return emptyToNull(normalized);
+  } catch {
+    // e.g. ZeroDep 200-char limit — fall back to a light cleanup
+    return emptyToNull(
+      raw
+        .normalize('NFKD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toUpperCase()
+        .replace(/[^A-Z0-9#/\-.\s]/g, ' ')
+        .replace(/\s+/g, ' ')
+    );
+  }
+}
+
+/**
+ * Map country names / alpha-3 / numeric codes to ISO 3166-1 alpha-2.
+ * Unknown values are uppercased (not rejected) so inbound data is not dropped.
+ */
+export function normalizeCountry(value, { defaultCountry = 'US' } = {}) {
+  const raw = emptyToNull(value);
+  if (!raw) return defaultCountry;
+
+  const trimmed = raw.trim();
+  const upper = trimmed.toUpperCase();
+
+  if (countries.isValid(upper) && upper.length === 2) return upper;
+
+  const fromAlpha3 = countries.alpha3ToAlpha2(upper);
+  if (fromAlpha3) return fromAlpha3;
+
+  if (/^\d{1,3}$/.test(upper)) {
+    const fromNumeric = countries.numericToAlpha2(upper.padStart(3, '0'));
+    if (fromNumeric) return fromNumeric;
+  }
+
+  const fromName = countries.getSimpleAlpha2Code(trimmed, 'en') || countries.getAlpha2Code(trimmed, 'en');
+  if (fromName) return fromName;
+
+  // Common non-ISO alias
+  if (upper === 'UK') return 'GB';
+
+  // Keep short codes; otherwise leave a cleaned uppercase token (do not invent a code)
+  if (upper.length <= 3) return upper;
+  return upper;
+}
+
+export function normalizeRegion(value, country) {
+  const raw = emptyToNull(value);
+  if (!raw) return null;
+  const upper = raw.toUpperCase().replace(/\./g, '').trim();
+  const lower = upper.toLowerCase();
+
+  if (country === 'US') {
+    if (VALID_US_REGIONS.has(upper)) return upper;
+    if (US_REGION_ALIASES[lower]) return US_REGION_ALIASES[lower];
+  }
+  if (country === 'CA') {
+    if (VALID_CA_REGIONS.has(upper)) return upper;
+    if (CA_REGION_ALIASES[lower]) return CA_REGION_ALIASES[lower];
+  }
+
+  // Already a short code (e.g. NY, ON) or unknown — keep compact uppercase
+  if (upper.length <= 3) return upper;
+  return upper;
+}
+
+/**
+ * Light postal cleanup: US ZIP+4 → ZIP5, CA → A1A 1A1, otherwise trim/uppercase.
+ */
+export function normalizePostalCode(value, country) {
+  const raw = emptyToNull(value);
+  if (!raw) return null;
+  const upper = raw.toUpperCase().trim();
+
+  if (country === 'US') {
+    const digits = upper.replace(/\D/g, '');
+    if (digits.length >= 5) return digits.slice(0, 5);
+    return emptyToNull(upper.replace(/[^A-Z0-9]/g, ''));
+  }
+
+  if (country === 'CA') {
+    const alnum = upper.replace(/[^A-Z0-9]/g, '');
+    if (alnum.length === 6) return `${alnum.slice(0, 3)} ${alnum.slice(3)}`;
+    return emptyToNull(alnum);
+  }
+
+  return emptyToNull(upper.replace(/\s+/g, ' '));
+}
+
+/**
+ * Normalize address fields used by person_address upsert / hashing.
+ * Mutates and returns a plain object of normalized fields (does not mutate input).
+ */
+export function normalizeAddressFields(addr = {}, { defaultCountry = 'US' } = {}) {
+  const country = normalizeCountry(addr.country, { defaultCountry });
+  return {
+    street_1: normalizeStreetLine(addr.street_1),
+    street_2: normalizeStreetLine(addr.street_2),
+    street_3: normalizeStreetLine(addr.street_3),
+    city: normalizeStreetLine(addr.city),
+    region: normalizeRegion(addr.region, country),
+    postal_code: normalizePostalCode(addr.postal_code, country),
+    country
+  };
+}
+
+/**
+ * Dedupe hash for addresses: alnum of street_1 + street_2 + postal_code after normalize.
+ */
+export function hashAddress(addr, { defaultCountry = 'US' } = {}) {
+  const n = normalizeAddressFields(addr, { defaultCountry });
+  return [n.street_1, n.street_2, n.postal_code]
+    .filter(Boolean)
+    .join('')
+    .replace(/[^a-z0-9]+/gi, '')
+    .toLowerCase();
+}
+
+export default {
+  normalizeStreetLine,
+  normalizeCountry,
+  normalizeRegion,
+  normalizePostalCode,
+  normalizeAddressFields,
+  hashAddress
+};

package/person_address/normalize.test.js

@@ -0,0 +1,69 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  hashAddress,
+  normalizeAddressFields,
+  normalizeCountry,
+  normalizePostalCode,
+  normalizeRegion,
+  normalizeStreetLine
+} from './normalize.js';
+
+describe('person_address normalize', () => {
+  it('normalizes street abbreviations without validating deliverability', () => {
+    assert.equal(normalizeStreetLine('1234 Main Street south-west, apt 14-a'), '1234 MAIN ST SW APT 14-A');
+    assert.equal(normalizeStreetLine('p.o.b 1234'), 'PO BOX 1234');
+  });
+
+  it('normalizes country names and codes to ISO alpha-2', () => {
+    assert.equal(normalizeCountry('USA'), 'US');
+    assert.equal(normalizeCountry('United States'), 'US');
+    assert.equal(normalizeCountry('840'), 'US');
+    assert.equal(normalizeCountry('UK'), 'GB');
+    assert.equal(normalizeCountry('Canada'), 'CA');
+    assert.equal(normalizeCountry(null), 'US');
+  });
+
+  it('normalizes US/CA regions', () => {
+    assert.equal(normalizeRegion('California', 'US'), 'CA');
+    assert.equal(normalizeRegion('ny', 'US'), 'NY');
+    assert.equal(normalizeRegion('Ontario', 'CA'), 'ON');
+  });
+
+  it('normalizes postal codes', () => {
+    assert.equal(normalizePostalCode('10001-1234', 'US'), '10001');
+    assert.equal(normalizePostalCode('m5v0h5', 'CA'), 'M5V 0H5');
+  });
+
+  it('hashes equivalent addresses the same after normalize', () => {
+    const a = hashAddress({
+      street_1: '123 Main Street',
+      street_2: 'Apt 2',
+      postal_code: '10001-9999',
+      country: 'USA'
+    });
+    const b = hashAddress({
+      street_1: '123 MAIN ST',
+      street_2: 'APT 2',
+      postal_code: '10001',
+      country: 'US'
+    });
+    assert.equal(a, b);
+    assert.ok(a.length > 0);
+  });
+
+  it('returns normalized field set', () => {
+    const n = normalizeAddressFields({
+      street_1: '1005 N Gravenstein Highway',
+      city: 'Sebastopol',
+      region: 'California',
+      postal_code: '95472-1234',
+      country: 'United States of America'
+    });
+    assert.equal(n.country, 'US');
+    assert.equal(n.region, 'CA');
+    assert.equal(n.postal_code, '95472');
+    assert.equal(n.city, 'SEBASTOPOL');
+    assert.match(n.street_1, /GRAVENSTEIN/);
+  });
+});

package/person_address/schema.js

@@ -0,0 +1,49 @@
+export const tables = [
+  {
+    name: 'person_address',
+    columns: {
+      id: 'id',
+      person_id: 'person_id',
+      name: 'string',
+      type: {
+        type: 'string',
+        values: ['', 'Home', 'School', 'Office']
+      },
+      status: 'string',
+      street_1: 'string',
+      street_2: 'string',
+      street_3: 'string',
+      city: 'string',
+      region: 'string',
+      postal_code: 'string',
+      country: 'string',
+      subscription_status: {
+        type: 'string',
+        nullable: false,
+        default_value: 'Not Subscribed',
+        values: ['Blocked', 'Bounced', 'Not Subscribed', 'Subscribed', 'Unsubscribed']
+      },
+      deliverability_score: {
+        type: 'int',
+        description:
+          'Score representating deliverability status of address, e.g. undeliverable(0), deliverable(1), higher values mean different things',
+        nullable: false,
+        default_value: 1
+      },
+      preference_order: {
+        type: 'int',
+        description: 'Order in the preference stack, lower is better, -1 means set by user',
+        nullable: false,
+        default_value: 0
+      },
+      is_best_address: 'boolean',
+      created_at: 'created_at',
+      modified_at: 'modified_at',
+      source_input_id: 'foreign_uuid'
+    },
+    indexes: [{ columns: 'person_id' }]
+  }
+];
+export default {
+  tables
+};

package/person_address/transforms/inbound/normalize.js

@@ -0,0 +1,23 @@
+import { normalizeAddressFields } from '../../normalize.js';
+
+export const description =
+  'Normalize postal address fields (street abbreviations, region codes, country ISO alpha-2, postal). Does not validate deliverability.';
+
+/**
+ * Mutate batch rows in place with normalized address components.
+ */
+export async function transform({ batch, options = {} }) {
+  const defaultCountry = options.defaultCountry || options.default_country || 'US';
+  batch.forEach((row) => {
+    const hasAddressHint = row.street_1 || row.street_2 || row.postal_code || row.city || row.region || row.country;
+    if (!hasAddressHint) return;
+    const normalized = normalizeAddressFields(row, { defaultCountry });
+    Object.assign(row, normalized);
+  });
+  return batch;
+}
+
+export default {
+  description,
+  transform
+};

package/person_address/transforms/inbound/upsert_tables.js

@@ -0,0 +1,51 @@
+import { hashAddress, normalizeAddressFields } from '../../normalize.js';
+
+export const bindings = {
+  existingAddresses: { path: 'sql.query', options: { table: 'person_address', lookup: ['person_id'] } },
+  tablesToUpsert: { path: 'sql.tables.upsert' }
+};
+
+export async function transform({ batch, tablesToUpsert, existingAddresses, options = {} }) {
+  const defaultCountry = options.defaultCountry || options.default_country || 'US';
+  tablesToUpsert.person_address = tablesToUpsert.person_address || [];
+  batch.forEach((o) => {
+    const normalized = normalizeAddressFields(o, { defaultCountry });
+    const hash = hashAddress(normalized, { defaultCountry });
+    if (hash.length === 0) return;
+
+    const matchingAddress = existingAddresses.find(
+      (a) => a.person_id === o.person_id && hashAddress(a, { defaultCountry }) === hash
+    );
+
+    const record = {
+      id: null,
+      type: o.type || 'Home',
+      person_id: o.person_id,
+      street_1: normalized.street_1,
+      street_2: normalized.street_2,
+      street_3: normalized.street_3,
+      city: normalized.city,
+      region: normalized.region,
+      postal_code: normalized.postal_code,
+      country: normalized.country,
+      subscription_status: 'Not Subscribed',
+      source_input_id: o.input_id
+    };
+    if (matchingAddress) {
+      /* Put logic here for dealing with overrides, subscription status, etc */
+      if (matchingAddress.subscription_status === 'Unsubscribed') {
+        record.subscription_status = 'Unsubscribed';
+      }
+      record.id = matchingAddress.id;
+      record.source_input_id = matchingAddress.source_input_id; // keep this the same
+      if (matchingAddress.type) record.type = matchingAddress.type;
+    }
+    tablesToUpsert.person_address.push(record);
+  });
+  return batch;
+}
+
+export default {
+  bindings,
+  transform
+};