ampscript-data 3.1.1 → 3.3.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 +62 -5
  2. package/package.json +1 -1
  3. package/src/index.js +1204 -317
package/README.md CHANGED
@@ -32,6 +32,7 @@ import {
32
32
  isMcnSupported,
33
33
  getMcnApiVersion,
34
34
  getMcnNotes,
35
+ VERIFICATION_BLOCKED_REASONS,
35
36
  } from 'ampscript-data';
36
37
  ```
37
38
 
@@ -54,13 +55,69 @@ for (const fn of FUNCTIONS) {
54
55
  console.log(fn.example); // usage example (where available)
55
56
  console.log(fn.docUrl); // URL to official Salesforce developer docs
56
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)
57
59
  console.log(fn.mcnSince); // API version when MCN support was added (null = MCE only)
58
60
  console.log(fn.mcnNotes); // behavioral differences on MCN (null = none)
59
61
  console.log(fn.handlebarsEquivalent); // MCN Handlebars helper name, or null when none exists
60
- 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
61
63
  }
62
64
  ```
63
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
+
77
+ #### Optional: `validArities`
78
+
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:
80
+
81
+ ```js
82
+ import { functionLookup } from 'ampscript-data';
83
+
84
+ const entry = functionLookup.get('somefunction');
85
+ if (entry.validArities) {
86
+ // e.g. minArgs: 1, maxArgs: 6, validArities: [1, 6] — 2-5 arguments are invalid
87
+ const isValidCall = entry.validArities.includes(argumentCount);
88
+ }
89
+ ```
90
+
91
+ The array is always strictly ascending integers and includes both `minArgs` (first element) and `maxArgs` (last element). When absent, the arity range is purely contiguous — which is currently the case for every AMPscript function.
92
+
93
+ #### Optional: verification state
94
+
95
+ | Field | Type | Description |
96
+ |---|---|---|
97
+ | `isConfirmed` | `boolean` | `true` when the behavior was verified against the live AMPscript engine; absent means never checked |
98
+ | `verificationBlocked` | `boolean` | `true` when verification was attempted but could not complete; requires `isConfirmed: false` and a `verificationBlockedReason` |
99
+ | `verificationBlockedReason` | `string` | One of `VERIFICATION_BLOCKED_REASONS`; only valid together with `verificationBlocked: true` |
100
+ | `differsFromOfficialDocs` | `boolean` | `true` when the verified runtime behavior contradicts the official Salesforce reference; requires `officialDocsNote` |
101
+ | `officialDocsNote` | `string` | What the official docs claim, what the runtime actually did, and what was tried |
102
+
103
+ ### `VERIFICATION_BLOCKED_REASONS`
104
+
105
+ A frozen array of the blocker categories that may be used as `verificationBlockedReason`:
106
+
107
+ ```js
108
+ import { VERIFICATION_BLOCKED_REASONS } from 'ampscript-data';
109
+ // ['no-working-invocation', 'needs-auth-context', 'no-test-data',
110
+ // 'classic-only-no-assets', 'destructive-unsafe']
111
+ ```
112
+
113
+ | Value | Meaning |
114
+ |---|---|
115
+ | `no-working-invocation` | Probing found no invocation shape that works |
116
+ | `needs-auth-context` | Requires an authenticated / session / subscriber state the probe context cannot supply |
117
+ | `no-test-data` | Requires pre-existing data or an integration not provisioned on the BU |
118
+ | `classic-only-no-assets` | Only works with classic (legacy) assets and none exist to test against |
119
+ | `destructive-unsafe` | Cannot be exercised without unacceptable side effects |
120
+
64
121
  ### `functionLookup`
65
122
 
66
123
  A `Map<string, FunctionEntry>` keyed by lowercase function name for O(1) lookups:
@@ -127,16 +184,16 @@ isEmailExcluded('HTTPGet'); // true — not available in email
127
184
 
128
185
  ## Marketing Cloud Next (MCN) compatibility
129
186
 
130
- Each `FunctionEntry` has two MCN fields:
187
+ Each `FunctionEntry` has these MCN fields:
131
188
 
132
189
  | Field | Type | Description |
133
190
  |---|---|---|
134
191
  | `mcnSince` | `number \| null` | API version when MCN support was added (e.g. `67`); `null` means MCE only |
135
192
  | `mcnNotes` | `string \| null` | Behavioral differences on MCN vs MCE; `null` means no known differences |
136
- | `handlebarsEquivalent` | `string \| null` | Name of the MCN Handlebars helper that replaces this function (e.g. `'add'`); `null` when no direct helper exists |
137
- | `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) |
138
195
 
139
- `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.
140
197
 
141
198
  Three helper functions are exported for programmatic MCN checks:
142
199
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ampscript-data",
3
- "version": "3.1.1",
3
+ "version": "3.3.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",