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.
- package/README.md +62 -5
- package/package.json +1 -1
- 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.
|
|
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
|
|
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
|
|
137
|
-
| `
|
|
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 `
|
|
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
|
|