ampscript-data 2.1.1 → 3.1.0

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 +2 -2
  3. package/src/index.js +150 -16
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": "2.1.1",
3
+ "version": "3.1.0",
4
4
  "description": "Canonical AMPscript function catalog, keywords, and personalization strings for SFMC tooling",
5
5
  "type": "module",
6
6
  "main": "src/index.js",
@@ -37,7 +37,7 @@
37
37
  "format:check": "prettier --check ."
38
38
  },
39
39
  "engines": {
40
- "node": ">=18.0.0"
40
+ "node": ">=22.0.0"
41
41
  },
42
42
  "devDependencies": {
43
43
  "@eslint/js": "^10.0.1",
package/src/index.js CHANGED
@@ -5325,9 +5325,17 @@ export const AMPSCRIPT_KEYWORDS = [
5325
5325
 
5326
5326
  // ── Personalization strings ──────────────────────────────────────────────────
5327
5327
 
5328
+ export const AMPSCRIPT_GLOBALS = [
5329
+ {
5330
+ name: '@@ExecCtx',
5331
+ description:
5332
+ 'Read-only web-page execution context indicator. Returns load or post, although current Marketing Cloud behavior always returns load.',
5333
+ },
5334
+ ];
5335
+
5328
5336
  export const PERSONALIZATION_STRINGS = [
5329
5337
  {
5330
- name: '_subscriberKey',
5338
+ name: '_subscriberkey',
5331
5339
  mcnSince: null,
5332
5340
  mcnNotes: null,
5333
5341
  description: 'Unique identifier for the current subscriber or contact',
@@ -5335,21 +5343,30 @@ export const PERSONALIZATION_STRINGS = [
5335
5343
  { name: 'emailaddr', description: 'Email address associated with the current subscriber' },
5336
5344
  { name: 'subscriberid', description: 'Numeric identifier in the All Subscribers list' },
5337
5345
  { name: 'firstname', description: 'First name attribute of the subscriber' },
5346
+ {
5347
+ name: 'firstname_',
5348
+ description: 'First name attribute of the subscriber (underscored alias)',
5349
+ },
5338
5350
  { name: 'lastname', description: 'Last name attribute of the subscriber' },
5339
- { name: 'fullname', description: 'Full name attribute of the subscriber' },
5351
+ { name: 'lastname_', description: 'Last name attribute of the subscriber (underscored alias)' },
5340
5352
  { name: 'emailname_', description: 'Display name of the current email message' },
5341
5353
  { name: '_emailid', description: 'Numeric identifier of the current email' },
5342
5354
  { name: 'jobid', description: 'Numeric job identifier for the current send operation' },
5343
5355
  { name: '_JobSubscriberBatchID', description: 'Batch identifier within the current send job' },
5344
- { name: '_PreHeader', description: 'Preheader text associated with the current email' },
5356
+ {
5357
+ name: '_PreHeader',
5358
+ description:
5359
+ 'Preheader text associated with the current email; resolves only when retrieved through AttributeValue()',
5360
+ },
5345
5361
  { name: '_DataSourceName', description: 'Name of the data source driving the current send' },
5346
5362
  {
5347
- name: '_messageContext',
5363
+ name: '_messagecontext',
5348
5364
  mcnSince: null,
5349
5365
  mcnNotes: null,
5350
- description: 'Render context indicator: SEND, PREVIEW, VAWP, or FTAF',
5366
+ description:
5367
+ 'Render context indicator: SEND, PREVIEW, VAWP, FTAF, LANDINGPAGE, VALIDATION, LINKRESOLUTION, SMS, or SOCIAL',
5351
5368
  },
5352
- { name: '_isTestSend', description: 'Flag indicating whether this is a test send' },
5369
+ { name: '_IsTestSend', description: 'Flag indicating whether this is a test send' },
5353
5370
  {
5354
5371
  name: '_messagetypepreference',
5355
5372
  mcnSince: null,
@@ -5358,7 +5375,10 @@ export const PERSONALIZATION_STRINGS = [
5358
5375
  },
5359
5376
  { name: 'listid', description: 'Numeric identifier of the current send list' },
5360
5377
  { name: '_listname', description: 'Display name of the current send list' },
5361
- { name: 'list_', description: 'Name of the list associated with the subscriber' },
5378
+ {
5379
+ name: 'list_',
5380
+ description: 'List identifier suffixed with _TEXT or _HTML for the subscriber email type',
5381
+ },
5362
5382
  { name: 'listsubid', description: 'Subscriber identifier within a specific list' },
5363
5383
  { name: 'xtmonth', description: 'Full month name of the send date' },
5364
5384
  { name: 'xtmonthnumeric', description: 'Numeric month of the send date (1 through 12)' },
@@ -5367,12 +5387,12 @@ export const PERSONALIZATION_STRINGS = [
5367
5387
  { name: 'xtyear', description: 'Four-digit year of the send date' },
5368
5388
  { name: 'xtshortdate', description: 'Send date in short date format' },
5369
5389
  { name: 'xtlongdate', description: 'Send date in long date format' },
5370
- { name: 'replyname', description: 'Reply-to display name configured for the current send' },
5390
+ { name: 'replyname', description: 'From name configured for the current send' },
5371
5391
  {
5372
5392
  name: 'replyemailaddress',
5373
5393
  mcnSince: null,
5374
5394
  mcnNotes: null,
5375
- description: 'Reply-to email address configured for the current send',
5395
+ description: 'From email address configured for the current send',
5376
5396
  },
5377
5397
  { name: 'memberid', description: 'Member ID (MID) of the sending business unit' },
5378
5398
  { name: 'member_busname', description: 'Business name of the sending business unit' },
@@ -5391,7 +5411,48 @@ export const PERSONALIZATION_STRINGS = [
5391
5411
  name: '_replycontent',
5392
5412
  mcnSince: null,
5393
5413
  mcnNotes: null,
5394
- description: 'Body content of a subscriber reply via Reply Mail Management',
5414
+ description:
5415
+ 'Plain-text abstract of the first 10,000 characters from a subscriber reply via Reply Mail Management',
5416
+ },
5417
+ {
5418
+ name: '_RMM_Headers',
5419
+ description: 'Full email message header of the reply via Reply Mail Management',
5420
+ },
5421
+ {
5422
+ name: '_RMM_ReplyBodyText',
5423
+ description: 'Plain-text body of the reply via Reply Mail Management',
5424
+ },
5425
+ {
5426
+ name: '_RMM_ReplyBodyHTML',
5427
+ description: 'HTML body of the reply via Reply Mail Management',
5428
+ },
5429
+ {
5430
+ name: '_RMM_ReplySubject',
5431
+ description: 'Subject line of the reply via Reply Mail Management',
5432
+ },
5433
+ {
5434
+ name: '_RMM_JobID',
5435
+ description: 'Job ID of the email the subscriber replied to via Reply Mail Management',
5436
+ },
5437
+ {
5438
+ name: '_RMM_ListID',
5439
+ description: 'List ID of the email the subscriber replied to via Reply Mail Management',
5440
+ },
5441
+ {
5442
+ name: '_RMM_BatchID',
5443
+ description: 'Batch ID of the email the subscriber replied to via Reply Mail Management',
5444
+ },
5445
+ {
5446
+ name: '_RMM_SubscriberID',
5447
+ description: 'Subscriber ID of the replying subscriber via Reply Mail Management',
5448
+ },
5449
+ {
5450
+ name: '_RMM_RecipientEmailAddress',
5451
+ description: 'Email address of the replying subscriber via Reply Mail Management',
5452
+ },
5453
+ {
5454
+ name: '_RMM_RecipientSubscriberKey',
5455
+ description: 'Subscriber key of the replying subscriber via Reply Mail Management',
5395
5456
  },
5396
5457
  { name: 'linkname', description: 'Alias or name assigned to the current tracked link' },
5397
5458
  {
@@ -5401,14 +5462,33 @@ export const PERSONALIZATION_STRINGS = [
5401
5462
  description: 'Numeric identifier of the current impression region',
5402
5463
  },
5403
5464
  { name: '_ImpressionRegionName', description: 'Display name of the current impression region' },
5465
+ {
5466
+ name: 'AdditionalInfo_',
5467
+ description:
5468
+ 'Value of the Additional Info field, appended to email links (Parameter Manager)',
5469
+ },
5470
+ {
5471
+ name: '__AdditionalEmailAttribute[n]',
5472
+ description:
5473
+ 'Value of an Additional Email Attribute field (n is 1 through 5), appended to email links (Parameter Manager)',
5474
+ matcher: /^__AdditionalEmailAttribute[1-5]$/i,
5475
+ },
5404
5476
  { name: 'PAGEURL', description: 'URL of the current CloudPages or microsite page' },
5405
5477
  { name: 'MOBILE_NUMBER', description: 'Mobile number of the inbound SMS sender' },
5406
5478
  { name: 'SHORT_CODE', description: 'Short code or long code that received the SMS' },
5407
5479
  { name: 'MSG(0)', description: 'Complete text of the inbound SMS message' },
5408
5480
  { name: 'MSG(0).VERB', description: 'First word (keyword) of the inbound SMS' },
5409
5481
  { 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' },
5482
+ {
5483
+ name: 'MSG(0).NOUN([n])',
5484
+ description: 'The nth word (noun) of the inbound SMS message, zero-based index',
5485
+ matcher: /^MSG\(0\)\.NOUN\(\d+\)$/i,
5486
+ },
5487
+ {
5488
+ name: 'MMS_CONTENT_URL([n])',
5489
+ description: 'URL of the nth MMS attachment, zero-based index',
5490
+ matcher: /^MMS_CONTENT_URL\(\d+\)$/i,
5491
+ },
5412
5492
  { name: '_CarrierID', description: 'Carrier identifier for a MobileConnect contact' },
5413
5493
  { name: '_Channel', description: 'Messaging channel for a MobileConnect contact' },
5414
5494
  { name: '_City', description: 'City from MobileConnect contact demographics' },
@@ -5417,6 +5497,10 @@ export const PERSONALIZATION_STRINGS = [
5417
5497
  { name: '_CreatedBy', description: 'User who created the MobileConnect contact record' },
5418
5498
  { name: '_CreatedDate', description: 'Timestamp when the MobileConnect contact was created' },
5419
5499
  { name: '_FirstName', description: 'First name of the MobileConnect contact' },
5500
+ {
5501
+ name: '_IsHonorDST',
5502
+ description: "Whether the MobileConnect contact's time zone honors Daylight Savings Time",
5503
+ },
5420
5504
  { name: '_LastName', description: 'Last name of the MobileConnect contact' },
5421
5505
  { name: '_MobileNumber', description: 'Mobile number of the MobileConnect contact' },
5422
5506
  { name: '_ModifiedBy', description: 'User who last modified the MobileConnect contact' },
@@ -5444,10 +5528,60 @@ export const PERSONALIZATION_STRINGS = [
5444
5528
  { name: '_UTCOffset', description: 'UTC offset for the MobileConnect contact timezone' },
5445
5529
  { name: '_ZipCode', description: 'ZIP or postal code from MobileConnect contact demographics' },
5446
5530
  { name: 'LINE_ADDRESS_ID', description: 'LINE user address identifier for GroupConnect' },
5531
+ { name: 'LINE_JOB_ID', description: 'Unique LINE job identifier for GroupConnect' },
5447
5532
  {
5448
- name: '@@ExecCtx',
5449
- mcnSince: null,
5450
- mcnNotes: null,
5451
- description: 'Execution context indicator: returns load or post on web pages',
5533
+ name: 'LINE_SUBSCRIBER_ID',
5534
+ description: 'Corresponding Marketing Cloud subscriber identifier for GroupConnect',
5535
+ },
5536
+ { name: 'TEXT', description: 'Complete inbound GroupConnect message text' },
5537
+ { name: 'VERB', description: 'First word (keyword) of the inbound GroupConnect message' },
5538
+ { name: 'TEXT.NOUN', description: 'All words after the verb in the GroupConnect message' },
5539
+ {
5540
+ name: 'TEXT.NOUN([n])',
5541
+ description: 'The nth word (noun) of the GroupConnect message, zero-based index',
5542
+ matcher: /^TEXT\.NOUN\(\d+\)$/i,
5452
5543
  },
5544
+ {
5545
+ name: 'STKR.STKPKGID',
5546
+ description: 'Package ID of a sticker in a LINE GroupConnect message',
5547
+ },
5548
+ { name: 'STKR.STKID', description: 'ID of a sticker in a LINE GroupConnect message' },
5549
+ { name: 'STKR.STKTXT', description: 'Text of a sticker in a LINE GroupConnect message' },
5453
5550
  ];
5551
+
5552
+ /**
5553
+ * Set of lowercase names for system personalization strings that are matched
5554
+ * exactly (i.e. entries without a `matcher` pattern).
5555
+ */
5556
+ const personalizationStringExactNames = new Set(
5557
+ PERSONALIZATION_STRINGS.filter((entry) => !entry.matcher).map((entry) =>
5558
+ entry.name.toLowerCase(),
5559
+ ),
5560
+ );
5561
+
5562
+ /**
5563
+ * Regex matchers for parameterized system personalization strings (e.g.
5564
+ * `MSG(0).NOUN([n])`). Each matcher is anchored and case-insensitive.
5565
+ */
5566
+ const personalizationStringMatchers = PERSONALIZATION_STRINGS.filter((entry) => entry.matcher).map(
5567
+ (entry) => entry.matcher,
5568
+ );
5569
+
5570
+ /**
5571
+ * Returns true when the given name is a known Marketing Cloud system
5572
+ * personalization string, either as an exact catalog entry or a valid
5573
+ * parameterized form (e.g. `MSG(0).NOUN(0)`). Matching is case-insensitive.
5574
+ *
5575
+ * @param {string} name - Personalization string name to test (without brackets).
5576
+ * @returns {boolean} True when the name is a known system personalization string.
5577
+ */
5578
+ export function isSystemPersonalizationString(name) {
5579
+ if (typeof name !== 'string' || name.length === 0) {
5580
+ return false;
5581
+ }
5582
+ const trimmed = name.trim();
5583
+ if (personalizationStringExactNames.has(trimmed.toLowerCase())) {
5584
+ return true;
5585
+ }
5586
+ return personalizationStringMatchers.some((matcher) => matcher.test(trimmed));
5587
+ }