@sdflc/backend-helpers 1.0.144 → 1.0.145

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1349,7 +1349,9 @@ await hubspot.addNote(contactId, '<p>Registered for …</p>', new Date());
1349
1349
  const lists = await hubspot.listStaticLists(); // [{ id, name, processingType }] — the contact lists that take members
1350
1350
  ```
1351
1351
 
1352
- - One upsert by email: only the values given are written — an empty one never blanks what HubSpot holds.
1352
+ - One upsert by email: only the values given are written — an empty one never blanks what HubSpot holds. Other
1353
+ properties by their internal names in `properties` (`address`, `city`, `state`, `zip`, `country`, a custom one) — never
1354
+ the email the contact is found by.
1353
1355
  - Scopes the key needs: `crm.objects.contacts.read` / `.write`, `crm.lists.read` / `.write`.
1354
1356
  - `verify()` reads one contact (nothing is written). The token is scrubbed out of everything returned.
1355
1357
 
@@ -1371,7 +1373,9 @@ const audiences = await mailchimp.listAudiences(); // [{ id, name, memberCount }
1371
1373
  on the audience, not subscribed to marketing; `pending` sends a confirmation email; `subscribed` only with consent).
1372
1374
  - Required merge fields the host added are not demanded (`skip_merge_validation`); an audience id that could leave the
1373
1375
  path is refused before sending. The key (and the Basic header made of it) is scrubbed out of everything returned.
1374
- - Pure helpers: `mailchimpDataCenterOf(apiKey)`, `mailchimpSubscriberHash(email)`.
1376
+ - `mergeFields.ADDRESS` takes an object (`addr1`, `addr2`, `city`, `state`, `zip`, `country`): sent only when addr1,
1377
+ city, state and zip are all there (Mailchimp refuses the member over a partial one), the country only as two letters.
1378
+ - Pure helpers: `mailchimpDataCenterOf(apiKey)`, `mailchimpSubscriberHash(email)`, `mailchimpAddressOf(address)`.
1375
1379
 
1376
1380
  ### HttpWebhookGw
1377
1381
 
@@ -2525,7 +2529,7 @@ START_READY_TIMEOUT_MS; // 60000: startService alerts when the server is not lis
2525
2529
  | `SlackWebhookSettings` / `SlackMessage` | `SlackWebhookGw` settings and message |
2526
2530
  | `DiscordWebhookSettings` / `DiscordMessage` / `DiscordEmbed` | `DiscordWebhookGw` settings, message and embed |
2527
2531
  | `HubSpotSettings` / `HubSpotContact` / `HubSpotList` | `HubSpotGw` settings, a contact, a static list |
2528
- | `MailchimpSettings` / `MailchimpMember` / `MailchimpAudience` / `MailchimpStatusIfNew` | `MailchimpGw` settings, a member, an audience, a new member's subscription |
2532
+ | `MailchimpSettings` / `MailchimpMember` / `MailchimpAudience` / `MailchimpStatusIfNew` / `MailchimpAddress` | `MailchimpGw` settings, a member, an audience, a new member's subscription |
2529
2533
  | `HttpWebhookSettings` / `HttpWebhookSend` / `HttpWebhookGwProps` | `HttpWebhookGw` settings, one send, and its constructor props (`allowPrivateNetwork`, `lookup`, `dnsLookup`) |
2530
2534
  | `ExternalUrlOptions` | Options for `checkExternalUrl()`: `{ protocols?, lookup?, field? }` |
2531
2535
  | `GuardedFetchOptions` | Options for `createGuardedFetch()`: `{ dnsLookup?, isBlocked? }` |
@@ -12,6 +12,8 @@ export interface HubSpotContact {
12
12
  lastName?: string | null;
13
13
  phone?: string | null;
14
14
  company?: string | null;
15
+ /** Any other contact properties by their internal names — `address`, `city`, `state`, `zip`, `country`, a custom one. */
16
+ properties?: Record<string, string | null | undefined>;
15
17
  }
16
18
  /** A static list as `listStaticLists` returns it. */
17
19
  export interface HubSpotList {
@@ -70,6 +70,8 @@ class HubSpotGw extends BaseExternalApiGateway {
70
70
  ['lastname', contact.lastName],
71
71
  ['phone', contact.phone],
72
72
  ['company', contact.company],
73
+ // ⓘ After the named ones, so `properties` cannot replace the email the contact is found by.
74
+ ...Object.entries(contact.properties ?? {}).filter(([name]) => /^[a-z0-9_]{1,100}$/.test(name) && name !== 'email'),
73
75
  ];
74
76
  for (const [name, value] of given) {
75
77
  if (text(value)) {
@@ -10,11 +10,25 @@ export type MailchimpStatusIfNew = 'transactional' | 'pending' | 'subscribed';
10
10
  export declare const MAILCHIMP_STATUSES_IF_NEW: MailchimpStatusIfNew[];
11
11
  export interface MailchimpMember {
12
12
  email: string;
13
- /** By merge tag — FNAME, LNAME (every audience has them unless the host removed them). Empty values are not sent. */
14
- mergeFields?: Record<string, string | null | undefined>;
13
+ /**
14
+ * By merge tag — FNAME, LNAME (every audience has them unless the host removed them), ADDRESS as an object (`addr1`,
15
+ * `addr2`, `city`, `state`, `zip`, `country` — Mailchimp refuses one without addr1, city, state and zip). Empty values
16
+ * are not sent.
17
+ */
18
+ mergeFields?: Record<string, string | MailchimpAddress | null | undefined>;
15
19
  /** Default `transactional`: on the audience, not subscribed to marketing. */
16
20
  statusIfNew?: MailchimpStatusIfNew;
17
21
  }
22
+ /** The ADDRESS merge field's value. */
23
+ export interface MailchimpAddress {
24
+ addr1: string;
25
+ addr2?: string | null;
26
+ city: string;
27
+ state: string;
28
+ zip: string;
29
+ /** Two letters (`CA`); left out, the audience's default country. */
30
+ country?: string | null;
31
+ }
18
32
  /** An audience as `listAudiences` returns it. */
19
33
  export interface MailchimpAudience {
20
34
  id: string;
@@ -27,6 +41,11 @@ export declare const MAILCHIMP_NOTE_MAX = 1000;
27
41
  export declare const MAILCHIMP_TAG_MAX = 100;
28
42
  /** The data centre at the end of an API key (`us21`), or null. Pure. */
29
43
  export declare const mailchimpDataCenterOf: (apiKey: unknown) => string | null;
44
+ /**
45
+ * An address as Mailchimp takes it — addr1, city, state and zip all there (it refuses the member otherwise), the country
46
+ * only as two letters — or null. Pure.
47
+ */
48
+ export declare const mailchimpAddressOf: (value: Partial<MailchimpAddress> | null | undefined) => Record<string, string> | null;
30
49
  /** The member's id in Mailchimp's paths: the MD5 of the lowercase email. Pure. */
31
50
  export declare const mailchimpSubscriberHash: (email: string) => string;
32
51
  declare class MailchimpGw extends BaseExternalApiGateway<MailchimpSettings> {
@@ -29,6 +29,31 @@ export const mailchimpDataCenterOf = (apiKey) => {
29
29
  const match = /^[0-9a-f]{32}-([a-z]{2,4}\d{1,3})$/i.exec(text(apiKey));
30
30
  return match ? match[1].toLowerCase() : null;
31
31
  };
32
+ /**
33
+ * An address as Mailchimp takes it — addr1, city, state and zip all there (it refuses the member otherwise), the country
34
+ * only as two letters — or null. Pure.
35
+ */
36
+ export const mailchimpAddressOf = (value) => {
37
+ const parts = {
38
+ addr1: text(value?.addr1),
39
+ addr2: text(value?.addr2),
40
+ city: text(value?.city),
41
+ state: text(value?.state),
42
+ zip: text(value?.zip),
43
+ };
44
+ if (!parts.addr1 || !parts.city || !parts.state || !parts.zip) {
45
+ return null;
46
+ }
47
+ const country = text(value?.country).toUpperCase();
48
+ const out = { addr1: parts.addr1, city: parts.city, state: parts.state, zip: parts.zip };
49
+ if (parts.addr2) {
50
+ out.addr2 = parts.addr2;
51
+ }
52
+ if (/^[A-Z]{2}$/.test(country)) {
53
+ out.country = country;
54
+ }
55
+ return out;
56
+ };
32
57
  /** The member's id in Mailchimp's paths: the MD5 of the lowercase email. Pure. */
33
58
  export const mailchimpSubscriberHash = (email) => createHash('md5').update(text(email).toLowerCase()).digest('hex');
34
59
  class MailchimpGw extends BaseExternalApiGateway {
@@ -96,7 +121,17 @@ class MailchimpGw extends BaseExternalApiGateway {
96
121
  : 'transactional';
97
122
  const mergeFields = {};
98
123
  for (const [tag, value] of Object.entries(member.mergeFields ?? {})) {
99
- if (/^[A-Z0-9_]{1,10}$/.test(tag) && text(value)) {
124
+ if (!/^[A-Z0-9_]{1,10}$/.test(tag)) {
125
+ continue;
126
+ }
127
+ if (value && typeof value === 'object') {
128
+ // An address goes whole or not at all: Mailchimp refuses the member over a partial one.
129
+ const address = mailchimpAddressOf(value);
130
+ if (address) {
131
+ mergeFields[tag] = address;
132
+ }
133
+ }
134
+ else if (text(value)) {
100
135
  mergeFields[tag] = text(value);
101
136
  }
102
137
  }
@@ -12,6 +12,8 @@ export interface HubSpotContact {
12
12
  lastName?: string | null;
13
13
  phone?: string | null;
14
14
  company?: string | null;
15
+ /** Any other contact properties by their internal names — `address`, `city`, `state`, `zip`, `country`, a custom one. */
16
+ properties?: Record<string, string | null | undefined>;
15
17
  }
16
18
  /** A static list as `listStaticLists` returns it. */
17
19
  export interface HubSpotList {
@@ -73,6 +73,8 @@ class HubSpotGw extends BaseExternalApiGateway_1.BaseExternalApiGateway {
73
73
  ['lastname', contact.lastName],
74
74
  ['phone', contact.phone],
75
75
  ['company', contact.company],
76
+ // ⓘ After the named ones, so `properties` cannot replace the email the contact is found by.
77
+ ...Object.entries(contact.properties ?? {}).filter(([name]) => /^[a-z0-9_]{1,100}$/.test(name) && name !== 'email'),
76
78
  ];
77
79
  for (const [name, value] of given) {
78
80
  if (text(value)) {
@@ -10,11 +10,25 @@ export type MailchimpStatusIfNew = 'transactional' | 'pending' | 'subscribed';
10
10
  export declare const MAILCHIMP_STATUSES_IF_NEW: MailchimpStatusIfNew[];
11
11
  export interface MailchimpMember {
12
12
  email: string;
13
- /** By merge tag — FNAME, LNAME (every audience has them unless the host removed them). Empty values are not sent. */
14
- mergeFields?: Record<string, string | null | undefined>;
13
+ /**
14
+ * By merge tag — FNAME, LNAME (every audience has them unless the host removed them), ADDRESS as an object (`addr1`,
15
+ * `addr2`, `city`, `state`, `zip`, `country` — Mailchimp refuses one without addr1, city, state and zip). Empty values
16
+ * are not sent.
17
+ */
18
+ mergeFields?: Record<string, string | MailchimpAddress | null | undefined>;
15
19
  /** Default `transactional`: on the audience, not subscribed to marketing. */
16
20
  statusIfNew?: MailchimpStatusIfNew;
17
21
  }
22
+ /** The ADDRESS merge field's value. */
23
+ export interface MailchimpAddress {
24
+ addr1: string;
25
+ addr2?: string | null;
26
+ city: string;
27
+ state: string;
28
+ zip: string;
29
+ /** Two letters (`CA`); left out, the audience's default country. */
30
+ country?: string | null;
31
+ }
18
32
  /** An audience as `listAudiences` returns it. */
19
33
  export interface MailchimpAudience {
20
34
  id: string;
@@ -27,6 +41,11 @@ export declare const MAILCHIMP_NOTE_MAX = 1000;
27
41
  export declare const MAILCHIMP_TAG_MAX = 100;
28
42
  /** The data centre at the end of an API key (`us21`), or null. Pure. */
29
43
  export declare const mailchimpDataCenterOf: (apiKey: unknown) => string | null;
44
+ /**
45
+ * An address as Mailchimp takes it — addr1, city, state and zip all there (it refuses the member otherwise), the country
46
+ * only as two letters — or null. Pure.
47
+ */
48
+ export declare const mailchimpAddressOf: (value: Partial<MailchimpAddress> | null | undefined) => Record<string, string> | null;
30
49
  /** The member's id in Mailchimp's paths: the MD5 of the lowercase email. Pure. */
31
50
  export declare const mailchimpSubscriberHash: (email: string) => string;
32
51
  declare class MailchimpGw extends BaseExternalApiGateway<MailchimpSettings> {
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.MailchimpGw = exports.mailchimpSubscriberHash = exports.mailchimpDataCenterOf = exports.MAILCHIMP_TAG_MAX = exports.MAILCHIMP_NOTE_MAX = exports.MAILCHIMP_STATUSES_IF_NEW = void 0;
3
+ exports.MailchimpGw = exports.mailchimpSubscriberHash = exports.mailchimpAddressOf = exports.mailchimpDataCenterOf = exports.MAILCHIMP_TAG_MAX = exports.MAILCHIMP_NOTE_MAX = exports.MAILCHIMP_STATUSES_IF_NEW = void 0;
4
4
  // ./src/gateways/MailchimpGw.ts
5
5
  //
6
6
  // Mailchimp's Marketing API (https://mailchimp.com/developer/marketing/api/) — the calls that put a person into a host's
@@ -33,6 +33,32 @@ const mailchimpDataCenterOf = (apiKey) => {
33
33
  return match ? match[1].toLowerCase() : null;
34
34
  };
35
35
  exports.mailchimpDataCenterOf = mailchimpDataCenterOf;
36
+ /**
37
+ * An address as Mailchimp takes it — addr1, city, state and zip all there (it refuses the member otherwise), the country
38
+ * only as two letters — or null. Pure.
39
+ */
40
+ const mailchimpAddressOf = (value) => {
41
+ const parts = {
42
+ addr1: text(value?.addr1),
43
+ addr2: text(value?.addr2),
44
+ city: text(value?.city),
45
+ state: text(value?.state),
46
+ zip: text(value?.zip),
47
+ };
48
+ if (!parts.addr1 || !parts.city || !parts.state || !parts.zip) {
49
+ return null;
50
+ }
51
+ const country = text(value?.country).toUpperCase();
52
+ const out = { addr1: parts.addr1, city: parts.city, state: parts.state, zip: parts.zip };
53
+ if (parts.addr2) {
54
+ out.addr2 = parts.addr2;
55
+ }
56
+ if (/^[A-Z]{2}$/.test(country)) {
57
+ out.country = country;
58
+ }
59
+ return out;
60
+ };
61
+ exports.mailchimpAddressOf = mailchimpAddressOf;
36
62
  /** The member's id in Mailchimp's paths: the MD5 of the lowercase email. Pure. */
37
63
  const mailchimpSubscriberHash = (email) => (0, crypto_1.createHash)('md5').update(text(email).toLowerCase()).digest('hex');
38
64
  exports.mailchimpSubscriberHash = mailchimpSubscriberHash;
@@ -101,7 +127,17 @@ class MailchimpGw extends BaseExternalApiGateway_1.BaseExternalApiGateway {
101
127
  : 'transactional';
102
128
  const mergeFields = {};
103
129
  for (const [tag, value] of Object.entries(member.mergeFields ?? {})) {
104
- if (/^[A-Z0-9_]{1,10}$/.test(tag) && text(value)) {
130
+ if (!/^[A-Z0-9_]{1,10}$/.test(tag)) {
131
+ continue;
132
+ }
133
+ if (value && typeof value === 'object') {
134
+ // An address goes whole or not at all: Mailchimp refuses the member over a partial one.
135
+ const address = (0, exports.mailchimpAddressOf)(value);
136
+ if (address) {
137
+ mergeFields[tag] = address;
138
+ }
139
+ }
140
+ else if (text(value)) {
105
141
  mergeFields[tag] = text(value);
106
142
  }
107
143
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sdflc/backend-helpers",
3
- "version": "1.0.144",
3
+ "version": "1.0.145",
4
4
  "description": "Set of helper functions and classes to simplify building backend apps within @sdflc ecosystem",
5
5
  "type": "commonjs",
6
6
  "exports": {