ampscript-data 3.0.0 → 3.1.1

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.
Files changed (3) hide show
  1. package/README.md +15 -1
  2. package/package.json +8 -8
  3. package/src/index.js +165 -21
package/README.md CHANGED
@@ -20,6 +20,7 @@ npm install ampscript-data
20
20
  import {
21
21
  FUNCTIONS,
22
22
  AMPSCRIPT_KEYWORDS,
23
+ AMPSCRIPT_GLOBALS,
23
24
  PERSONALIZATION_STRINGS,
24
25
  DEPRECATED_FUNCTIONS,
25
26
  functionLookup,
@@ -187,9 +188,22 @@ for (const kw of AMPSCRIPT_KEYWORDS) {
187
188
  }
188
189
  ```
189
190
 
191
+ ### `AMPSCRIPT_GLOBALS`
192
+
193
+ An array of read-only AMPscript language globals that are not subscriber personalization attributes:
194
+
195
+ ```js
196
+ import { AMPSCRIPT_GLOBALS } from 'ampscript-data';
197
+
198
+ for (const global of AMPSCRIPT_GLOBALS) {
199
+ console.log(global.name); // e.g. '@@ExecCtx'
200
+ console.log(global.description); // human-readable description
201
+ }
202
+ ```
203
+
190
204
  ### `PERSONALIZATION_STRINGS`
191
205
 
192
- An array of AMPscript personalization string descriptors (subscriber attributes, system variables, etc.):
206
+ An array of AMPscript system personalization string descriptors, including subscriber attributes and message-context values:
193
207
 
194
208
  ```js
195
209
  import { PERSONALIZATION_STRINGS } from 'ampscript-data';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ampscript-data",
3
- "version": "3.0.0",
3
+ "version": "3.1.1",
4
4
  "description": "Canonical AMPscript function catalog, keywords, and personalization strings for SFMC tooling",
5
5
  "type": "module",
6
6
  "main": "src/index.js",
@@ -41,15 +41,15 @@
41
41
  },
42
42
  "devDependencies": {
43
43
  "@eslint/js": "^10.0.1",
44
- "eslint": "^10.1.0",
44
+ "eslint": "^10.8.0",
45
45
  "eslint-config-prettier": "^10.1.8",
46
- "eslint-plugin-jsdoc": "^63.0.10",
47
- "eslint-plugin-prettier": "^5.5.0",
48
- "eslint-plugin-unicorn": "^70.0.0",
49
- "globals": "^17.4.0",
46
+ "eslint-plugin-jsdoc": "^63.3.3",
47
+ "eslint-plugin-prettier": "^5.5.6",
48
+ "eslint-plugin-unicorn": "^73.0.0",
49
+ "globals": "^17.9.0",
50
50
  "husky": "^9.1.7",
51
- "lint-staged": "^17.0.5",
52
- "prettier": "^3.8.1"
51
+ "lint-staged": "^17.3.0",
52
+ "prettier": "^3.9.6"
53
53
  },
54
54
  "lint-staged": {
55
55
  "*.{js,mjs,cjs}": [
package/src/index.js CHANGED
@@ -5186,18 +5186,26 @@ export const FUNCTIONS = [
5186
5186
  },
5187
5187
  ];
5188
5188
 
5189
- /** Case-insensitive lookup: lowercase name -> function entry */
5189
+ /**
5190
+ * Case-insensitive lookup: lowercase name -> function entry
5191
+ */
5190
5192
  export const functionLookup = new Map(FUNCTIONS.map((f) => [f.name.toLowerCase(), f]));
5191
5193
 
5192
- /** Set of lowercase function names for quick membership checks */
5194
+ /**
5195
+ * Set of lowercase function names for quick membership checks
5196
+ */
5193
5197
  export const functionNames = new Set(FUNCTIONS.map((f) => f.name.toLowerCase()));
5194
5198
 
5195
5199
  // ── Canonical casing map ─────────────────────────────────────────────────────
5196
5200
 
5197
- /** Ordered list of canonical PascalCase function names */
5201
+ /**
5202
+ * Ordered list of canonical PascalCase function names
5203
+ */
5198
5204
  export const CANONICAL_FUNCTIONS = FUNCTIONS.map((f) => f.name);
5199
5205
 
5200
- /** Map from lowercase -> canonical PascalCase name */
5206
+ /**
5207
+ * Map from lowercase -> canonical PascalCase name
5208
+ */
5201
5209
  export const FUNCTION_CANONICAL_MAP = new Map(
5202
5210
  CANONICAL_FUNCTIONS.map((name) => [name.toLowerCase(), name]),
5203
5211
  );
@@ -5268,7 +5276,9 @@ export function getMcnNotes(name) {
5268
5276
  // lookup below is derived from those flags for consumers that need a quick
5269
5277
  // name -> entry map of deprecated functions.
5270
5278
 
5271
- /** Case-insensitive lookup of deprecated functions: lowercase name -> function entry */
5279
+ /**
5280
+ * Case-insensitive lookup of deprecated functions: lowercase name -> function entry
5281
+ */
5272
5282
  export const deprecatedFunctionLookup = new Map(
5273
5283
  FUNCTIONS.filter((f) => f.deprecated).map((f) => [f.name.toLowerCase(), f]),
5274
5284
  );
@@ -5325,9 +5335,17 @@ export const AMPSCRIPT_KEYWORDS = [
5325
5335
 
5326
5336
  // ── Personalization strings ──────────────────────────────────────────────────
5327
5337
 
5338
+ export const AMPSCRIPT_GLOBALS = [
5339
+ {
5340
+ name: '@@ExecCtx',
5341
+ description:
5342
+ 'Read-only web-page execution context indicator. Returns load or post, although current Marketing Cloud behavior always returns load.',
5343
+ },
5344
+ ];
5345
+
5328
5346
  export const PERSONALIZATION_STRINGS = [
5329
5347
  {
5330
- name: '_subscriberKey',
5348
+ name: '_subscriberkey',
5331
5349
  mcnSince: null,
5332
5350
  mcnNotes: null,
5333
5351
  description: 'Unique identifier for the current subscriber or contact',
@@ -5335,21 +5353,30 @@ export const PERSONALIZATION_STRINGS = [
5335
5353
  { name: 'emailaddr', description: 'Email address associated with the current subscriber' },
5336
5354
  { name: 'subscriberid', description: 'Numeric identifier in the All Subscribers list' },
5337
5355
  { name: 'firstname', description: 'First name attribute of the subscriber' },
5356
+ {
5357
+ name: 'firstname_',
5358
+ description: 'First name attribute of the subscriber (underscored alias)',
5359
+ },
5338
5360
  { name: 'lastname', description: 'Last name attribute of the subscriber' },
5339
- { name: 'fullname', description: 'Full name attribute of the subscriber' },
5361
+ { name: 'lastname_', description: 'Last name attribute of the subscriber (underscored alias)' },
5340
5362
  { name: 'emailname_', description: 'Display name of the current email message' },
5341
5363
  { name: '_emailid', description: 'Numeric identifier of the current email' },
5342
5364
  { name: 'jobid', description: 'Numeric job identifier for the current send operation' },
5343
5365
  { name: '_JobSubscriberBatchID', description: 'Batch identifier within the current send job' },
5344
- { name: '_PreHeader', description: 'Preheader text associated with the current email' },
5366
+ {
5367
+ name: '_PreHeader',
5368
+ description:
5369
+ 'Preheader text associated with the current email; resolves only when retrieved through AttributeValue()',
5370
+ },
5345
5371
  { name: '_DataSourceName', description: 'Name of the data source driving the current send' },
5346
5372
  {
5347
- name: '_messageContext',
5373
+ name: '_messagecontext',
5348
5374
  mcnSince: null,
5349
5375
  mcnNotes: null,
5350
- description: 'Render context indicator: SEND, PREVIEW, VAWP, or FTAF',
5376
+ description:
5377
+ 'Render context indicator: SEND, PREVIEW, VAWP, FTAF, LANDINGPAGE, VALIDATION, LINKRESOLUTION, SMS, or SOCIAL',
5351
5378
  },
5352
- { name: '_isTestSend', description: 'Flag indicating whether this is a test send' },
5379
+ { name: '_IsTestSend', description: 'Flag indicating whether this is a test send' },
5353
5380
  {
5354
5381
  name: '_messagetypepreference',
5355
5382
  mcnSince: null,
@@ -5358,7 +5385,10 @@ export const PERSONALIZATION_STRINGS = [
5358
5385
  },
5359
5386
  { name: 'listid', description: 'Numeric identifier of the current send list' },
5360
5387
  { name: '_listname', description: 'Display name of the current send list' },
5361
- { name: 'list_', description: 'Name of the list associated with the subscriber' },
5388
+ {
5389
+ name: 'list_',
5390
+ description: 'List identifier suffixed with _TEXT or _HTML for the subscriber email type',
5391
+ },
5362
5392
  { name: 'listsubid', description: 'Subscriber identifier within a specific list' },
5363
5393
  { name: 'xtmonth', description: 'Full month name of the send date' },
5364
5394
  { name: 'xtmonthnumeric', description: 'Numeric month of the send date (1 through 12)' },
@@ -5367,12 +5397,12 @@ export const PERSONALIZATION_STRINGS = [
5367
5397
  { name: 'xtyear', description: 'Four-digit year of the send date' },
5368
5398
  { name: 'xtshortdate', description: 'Send date in short date format' },
5369
5399
  { name: 'xtlongdate', description: 'Send date in long date format' },
5370
- { name: 'replyname', description: 'Reply-to display name configured for the current send' },
5400
+ { name: 'replyname', description: 'From name configured for the current send' },
5371
5401
  {
5372
5402
  name: 'replyemailaddress',
5373
5403
  mcnSince: null,
5374
5404
  mcnNotes: null,
5375
- description: 'Reply-to email address configured for the current send',
5405
+ description: 'From email address configured for the current send',
5376
5406
  },
5377
5407
  { name: 'memberid', description: 'Member ID (MID) of the sending business unit' },
5378
5408
  { name: 'member_busname', description: 'Business name of the sending business unit' },
@@ -5391,7 +5421,48 @@ export const PERSONALIZATION_STRINGS = [
5391
5421
  name: '_replycontent',
5392
5422
  mcnSince: null,
5393
5423
  mcnNotes: null,
5394
- description: 'Body content of a subscriber reply via Reply Mail Management',
5424
+ description:
5425
+ 'Plain-text abstract of the first 10,000 characters from a subscriber reply via Reply Mail Management',
5426
+ },
5427
+ {
5428
+ name: '_RMM_Headers',
5429
+ description: 'Full email message header of the reply via Reply Mail Management',
5430
+ },
5431
+ {
5432
+ name: '_RMM_ReplyBodyText',
5433
+ description: 'Plain-text body of the reply via Reply Mail Management',
5434
+ },
5435
+ {
5436
+ name: '_RMM_ReplyBodyHTML',
5437
+ description: 'HTML body of the reply via Reply Mail Management',
5438
+ },
5439
+ {
5440
+ name: '_RMM_ReplySubject',
5441
+ description: 'Subject line of the reply via Reply Mail Management',
5442
+ },
5443
+ {
5444
+ name: '_RMM_JobID',
5445
+ description: 'Job ID of the email the subscriber replied to via Reply Mail Management',
5446
+ },
5447
+ {
5448
+ name: '_RMM_ListID',
5449
+ description: 'List ID of the email the subscriber replied to via Reply Mail Management',
5450
+ },
5451
+ {
5452
+ name: '_RMM_BatchID',
5453
+ description: 'Batch ID of the email the subscriber replied to via Reply Mail Management',
5454
+ },
5455
+ {
5456
+ name: '_RMM_SubscriberID',
5457
+ description: 'Subscriber ID of the replying subscriber via Reply Mail Management',
5458
+ },
5459
+ {
5460
+ name: '_RMM_RecipientEmailAddress',
5461
+ description: 'Email address of the replying subscriber via Reply Mail Management',
5462
+ },
5463
+ {
5464
+ name: '_RMM_RecipientSubscriberKey',
5465
+ description: 'Subscriber key of the replying subscriber via Reply Mail Management',
5395
5466
  },
5396
5467
  { name: 'linkname', description: 'Alias or name assigned to the current tracked link' },
5397
5468
  {
@@ -5401,14 +5472,33 @@ export const PERSONALIZATION_STRINGS = [
5401
5472
  description: 'Numeric identifier of the current impression region',
5402
5473
  },
5403
5474
  { name: '_ImpressionRegionName', description: 'Display name of the current impression region' },
5475
+ {
5476
+ name: 'AdditionalInfo_',
5477
+ description:
5478
+ 'Value of the Additional Info field, appended to email links (Parameter Manager)',
5479
+ },
5480
+ {
5481
+ name: '__AdditionalEmailAttribute[n]',
5482
+ description:
5483
+ 'Value of an Additional Email Attribute field (n is 1 through 5), appended to email links (Parameter Manager)',
5484
+ matcher: /^__AdditionalEmailAttribute[1-5]$/i,
5485
+ },
5404
5486
  { name: 'PAGEURL', description: 'URL of the current CloudPages or microsite page' },
5405
5487
  { name: 'MOBILE_NUMBER', description: 'Mobile number of the inbound SMS sender' },
5406
5488
  { name: 'SHORT_CODE', description: 'Short code or long code that received the SMS' },
5407
5489
  { name: 'MSG(0)', description: 'Complete text of the inbound SMS message' },
5408
5490
  { name: 'MSG(0).VERB', description: 'First word (keyword) of the inbound SMS' },
5409
5491
  { name: 'MSG(0).NOUNS', description: 'All text following the keyword in the inbound SMS' },
5410
- { name: 'MSG(0).NOUN(1)', description: 'Second word of the inbound SMS message' },
5411
- { name: 'MMS_CONTENT_URL(0)', description: 'URL of the first MMS attachment' },
5492
+ {
5493
+ name: 'MSG(0).NOUN([n])',
5494
+ description: 'The nth word (noun) of the inbound SMS message, zero-based index',
5495
+ matcher: /^MSG\(0\)\.NOUN\(\d+\)$/i,
5496
+ },
5497
+ {
5498
+ name: 'MMS_CONTENT_URL([n])',
5499
+ description: 'URL of the nth MMS attachment, zero-based index',
5500
+ matcher: /^MMS_CONTENT_URL\(\d+\)$/i,
5501
+ },
5412
5502
  { name: '_CarrierID', description: 'Carrier identifier for a MobileConnect contact' },
5413
5503
  { name: '_Channel', description: 'Messaging channel for a MobileConnect contact' },
5414
5504
  { name: '_City', description: 'City from MobileConnect contact demographics' },
@@ -5417,6 +5507,10 @@ export const PERSONALIZATION_STRINGS = [
5417
5507
  { name: '_CreatedBy', description: 'User who created the MobileConnect contact record' },
5418
5508
  { name: '_CreatedDate', description: 'Timestamp when the MobileConnect contact was created' },
5419
5509
  { name: '_FirstName', description: 'First name of the MobileConnect contact' },
5510
+ {
5511
+ name: '_IsHonorDST',
5512
+ description: "Whether the MobileConnect contact's time zone honors Daylight Savings Time",
5513
+ },
5420
5514
  { name: '_LastName', description: 'Last name of the MobileConnect contact' },
5421
5515
  { name: '_MobileNumber', description: 'Mobile number of the MobileConnect contact' },
5422
5516
  { name: '_ModifiedBy', description: 'User who last modified the MobileConnect contact' },
@@ -5444,10 +5538,60 @@ export const PERSONALIZATION_STRINGS = [
5444
5538
  { name: '_UTCOffset', description: 'UTC offset for the MobileConnect contact timezone' },
5445
5539
  { name: '_ZipCode', description: 'ZIP or postal code from MobileConnect contact demographics' },
5446
5540
  { name: 'LINE_ADDRESS_ID', description: 'LINE user address identifier for GroupConnect' },
5541
+ { name: 'LINE_JOB_ID', description: 'Unique LINE job identifier for GroupConnect' },
5447
5542
  {
5448
- name: '@@ExecCtx',
5449
- mcnSince: null,
5450
- mcnNotes: null,
5451
- description: 'Execution context indicator: returns load or post on web pages',
5543
+ name: 'LINE_SUBSCRIBER_ID',
5544
+ description: 'Corresponding Marketing Cloud subscriber identifier for GroupConnect',
5452
5545
  },
5546
+ { name: 'TEXT', description: 'Complete inbound GroupConnect message text' },
5547
+ { name: 'VERB', description: 'First word (keyword) of the inbound GroupConnect message' },
5548
+ { name: 'TEXT.NOUN', description: 'All words after the verb in the GroupConnect message' },
5549
+ {
5550
+ name: 'TEXT.NOUN([n])',
5551
+ description: 'The nth word (noun) of the GroupConnect message, zero-based index',
5552
+ matcher: /^TEXT\.NOUN\(\d+\)$/i,
5553
+ },
5554
+ {
5555
+ name: 'STKR.STKPKGID',
5556
+ description: 'Package ID of a sticker in a LINE GroupConnect message',
5557
+ },
5558
+ { name: 'STKR.STKID', description: 'ID of a sticker in a LINE GroupConnect message' },
5559
+ { name: 'STKR.STKTXT', description: 'Text of a sticker in a LINE GroupConnect message' },
5453
5560
  ];
5561
+
5562
+ /**
5563
+ * Set of lowercase names for system personalization strings that are matched
5564
+ * exactly (i.e. entries without a `matcher` pattern).
5565
+ */
5566
+ const personalizationStringExactNames = new Set(
5567
+ PERSONALIZATION_STRINGS.filter((entry) => !entry.matcher).map((entry) =>
5568
+ entry.name.toLowerCase(),
5569
+ ),
5570
+ );
5571
+
5572
+ /**
5573
+ * Regex matchers for parameterized system personalization strings (e.g.
5574
+ * `MSG(0).NOUN([n])`). Each matcher is anchored and case-insensitive.
5575
+ */
5576
+ const personalizationStringMatchers = PERSONALIZATION_STRINGS.filter((entry) => entry.matcher).map(
5577
+ (entry) => entry.matcher,
5578
+ );
5579
+
5580
+ /**
5581
+ * Returns true when the given name is a known Marketing Cloud system
5582
+ * personalization string, either as an exact catalog entry or a valid
5583
+ * parameterized form (e.g. `MSG(0).NOUN(0)`). Matching is case-insensitive.
5584
+ *
5585
+ * @param {string} name - Personalization string name to test (without brackets).
5586
+ * @returns {boolean} True when the name is a known system personalization string.
5587
+ */
5588
+ export function isSystemPersonalizationString(name) {
5589
+ if (typeof name !== 'string' || name.length === 0) {
5590
+ return false;
5591
+ }
5592
+ const trimmed = name.trim();
5593
+ if (personalizationStringExactNames.has(trimmed.toLowerCase())) {
5594
+ return true;
5595
+ }
5596
+ return personalizationStringMatchers.some((matcher) => matcher.test(trimmed));
5597
+ }