ampscript-data 3.2.0 → 3.4.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 +17 -5
  2. package/package.json +1 -1
  3. package/src/index.js +1531 -375
package/README.md CHANGED
@@ -55,13 +55,25 @@ for (const fn of FUNCTIONS) {
55
55
  console.log(fn.example); // usage example (where available)
56
56
  console.log(fn.docUrl); // URL to official Salesforce developer docs
57
57
  console.log(fn.guideUrl); // URL to ampscript.guide reference page
58
+ console.log(fn.sfmcGuideUrl); // URL to our own sfmc.guide reference page (only when published)
58
59
  console.log(fn.mcnSince); // API version when MCN support was added (null = MCE only)
59
60
  console.log(fn.mcnNotes); // behavioral differences on MCN (null = none)
60
61
  console.log(fn.handlebarsEquivalent); // MCN Handlebars helper name, or null when none exists
61
- console.log(fn.mcnHandlebarsGap); // true when MCN-supported but no Handlebars helper yet
62
+ console.log(fn.handlebarsExact); // true = drop-in replacement, false = same job, different call shape
62
63
  }
63
64
  ```
64
65
 
66
+ #### Optional: `sfmcGuideUrl`
67
+
68
+ `docUrl` and `guideUrl` point at third-party documentation and are set for (almost) every function. `sfmcGuideUrl` is different: it links to our own published reference page and only exists once that page has been written, which happens at the end of a runtime verification sweep. It is therefore a reliable marker for "this function has a proven, self-hosted reference page":
69
+
70
+ ```js
71
+ const entry = functionLookup.get('add');
72
+ entry.sfmcGuideUrl; // 'https://sfmc.guide/engagement/ampscript/functions/add/'
73
+ ```
74
+
75
+ The URL is always `https://sfmc.guide/engagement/ampscript/functions/<lowercase-name>/`, and an entry carrying it is always `isConfirmed: true`.
76
+
65
77
  #### Optional: `validArities`
66
78
 
67
79
  Most functions accept any argument count in the contiguous `minArgs..maxArgs` range. A function with a **discontinuous overload** — where intermediate counts are invalid — additionally sets `validArities`, the exact set of permitted argument counts:
@@ -172,16 +184,16 @@ isEmailExcluded('HTTPGet'); // true — not available in email
172
184
 
173
185
  ## Marketing Cloud Next (MCN) compatibility
174
186
 
175
- Each `FunctionEntry` has two MCN fields:
187
+ Each `FunctionEntry` has these MCN fields:
176
188
 
177
189
  | Field | Type | Description |
178
190
  |---|---|---|
179
191
  | `mcnSince` | `number \| null` | API version when MCN support was added (e.g. `67`); `null` means MCE only |
180
192
  | `mcnNotes` | `string \| null` | Behavioral differences on MCN vs MCE; `null` means no known differences |
181
- | `handlebarsEquivalent` | `string \| null` | Name of the MCN Handlebars helper that replaces this function (e.g. `'add'`); `null` when no direct helper exists |
182
- | `mcnHandlebarsGap` | `boolean` | `true` when the function is documented as MCN-supported but currently has no working Handlebars helper (runtime gap) |
193
+ | `handlebarsEquivalent` | `string \| null` | Name of the MCN Handlebars helper that replaces this function (e.g. `'add'`); `null` when no counterpart exists |
194
+ | `handlebarsExact` | `boolean` | Only meaningful when `handlebarsEquivalent` is set: `true` = argument-for-argument drop-in, `false` = same job but different call shape (converter emits a hint) |
183
195
 
184
- `handlebarsEquivalent` and `mcnHandlebarsGap` drive AMPscript ↔ Handlebars conversion tooling. When `mcnHandlebarsGap` is `true`, `handlebarsEquivalent` is always `null` — the function cannot yet be expressed in MCN Handlebars and needs a manual rewrite.
196
+ `handlebarsEquivalent` and `handlebarsExact` drive AMPscript ↔ Handlebars conversion tooling. When `handlebarsExact` is `false`, the helper does the same job but with a different call shape, so conversion emits a hint for a human to finish rather than a mechanical substitution.
185
197
 
186
198
  Three helper functions are exported for programmatic MCN checks:
187
199
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ampscript-data",
3
- "version": "3.2.0",
3
+ "version": "3.4.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",