@sonordev/contracts 2.21.0 → 2.23.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/CHANGELOG.md +15 -0
- package/README.md +60 -1
- package/dist/outreach.js +1 -45
- package/dist/outreach.mjs +1 -45
- package/dist/resonance.d.ts +803 -82
- package/dist/resonance.js +336 -14
- package/dist/resonance.mjs +319 -15
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,20 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 2.23.0
|
|
4
|
+
|
|
5
|
+
- Add optional per-channel `providerReporting.metaQueries` to the existing report selector and resolved grant. Each explicit query fixes its attribution window and conversion report time. Original UUID text, list order and omitted legacy fields stay unchanged; actual provider membership, original review and admission remain native checks.
|
|
6
|
+
- Add the closed `ResonanceMetaRetargetingReadiness` response parser, type and JSON schema. It keeps saved configuration facts separate from an observed audience check, preserves unknown size and size freshness, and carries no launch authority. The API classifier and consumers share one exported verdict and reason vocabulary.
|
|
7
|
+
|
|
8
|
+
## 2.22.0
|
|
9
|
+
|
|
10
|
+
- Add one additive set of rules for retargeting several properties from one campaign. A Meta channel can now carry an optional `channelGroup`, `property`, `tier`, `primaryText` and `convertersAcknowledged`. Channels in one group must share their site, account, dataset, Page, categories, countries, objective and optimization, each property keeps its own destination, and tiers of one property can't overlap in time. A grouped campaign's allocations can't exceed its total less its reserve, and a special category in a group requires provider-managed age. A definition that uses none of these fields parses and serializes exactly as before.
|
|
11
|
+
- Add `checkChannelGroups`, `splitBudget`, `suggestPropertyWeights` and `expandPropertyChannels`. The split conserves the total in whole provider quanta, the suggestion keeps every share between a floor and a ceiling, and the expander builds new property channels from the group's first channel with deterministic ids. It never sets a creative, a converter acknowledgement or an approval, and expanding twice is a no-op.
|
|
12
|
+
- Add an optional `minDaysSinceVisit` recency band to an audience reference and to the audience draft, `checkAudienceBand`, and the exported `META_WEBSITE_AUDIENCE_MAX_RETENTION_DAYS` (180), so the editor, the API and the contract share one number. Meta audiences hold at most ten rules, and Google audiences take no band.
|
|
13
|
+
- Add `metaExclusionPolicy` and `META_SAC_CUSTOM_AUDIENCE_EXCLUSION_VERIFIED`, which ships `false`: targeting-level exclusion under a special category stays refused until a reviewed release proves it. Add `META_CALL_TO_ACTIONS`, the one list the editor and compiler validate against.
|
|
14
|
+
- Raise the public observation page bound from 300 to 500 metrics, because one provider row can now expand to five (spend, impressions, clicks, reach and results). The bound of 100 native rows is unchanged.
|
|
15
|
+
- Add the provider metrics `reach` and `results`, the counting unit `provider_unique_reach` (reach only, never summed across channels), and `deriveProviderRatios`, the one place frequency and cost per result are computed. Zero, missing and mixed inputs are unknown with a reason, never zero.
|
|
16
|
+
- Add three optional fields to the Resonance measurement configuration: `metaEligible` on a page resource rule (absent means false), and `browserWitness` and `tagManagerAttested` on a Meta destination. Configurations that omit them parse as before and mean no Meta browser loading.
|
|
17
|
+
|
|
3
18
|
## 2.21.0
|
|
4
19
|
|
|
5
20
|
- Add optional, closed `page.experiment` authoring to managed Funnel drafts and definitions, with shared headline/body bounds and variant checks. Keep authored selection separate from the existing native-derived publication manifest. Plain documents stay compatible; older strict parsers reject extended documents, so consumers must adopt together before exposing authoring.
|
package/README.md
CHANGED
|
@@ -1611,6 +1611,8 @@ The native sequence starts with a managed draft and its owned sites; channels ca
|
|
|
1611
1611
|
|
|
1612
1612
|
Measurement configuration CAS is scoped to project/site. Zero expects actual absence; a legacy or malformed row without protected provenance must block. An audit campaign's revision check doesn't partition the site configuration or advance that campaign's review revision. `projectResonanceMeasurementConfiguration(command, context)` accepts an authorized project, protected current projection, reloaded safe page facts and a native transport expiry. It derives one rule per actual page UUID, sorted by page ID. The page resource revision is canonical UTC milliseconds; the rule revision is the existing full native evidence digest. This preserves distinctions between source updates within one millisecond. Native SQL must independently validate the facts and recompute CAS decisions under its locks.
|
|
1613
1613
|
|
|
1614
|
+
A page resource rule can carry `metaEligible`. It is set by a person with owner or admin standing, absent means false, and the browser never decides it. A Meta destination can carry `browserWitness`, the server's capability witness for the browser pixel loader (`controlsRevision`, `policyRevision`, `witnessId`, `assertedAt`), and `tagManagerAttested` for a site whose approved configuration states that its tag manager installs no Meta pixel. All three are optional, so earlier configurations still parse, and a configuration without a witness loads no Meta browser code.
|
|
1615
|
+
|
|
1614
1616
|
Native semantic `configRevision` and `policyRevision` are positive decimal strings. Identical semantics and a new cache expiry preserve them. Page evidence, selected rules or enabled-state changes advance the configuration revision; only consent-policy changes advance the policy revision. Initial provider destinations are `[]`; updates preserve explicitly configured destinations. The helper returns the configuration, friendly page projections and `configurationDigestInput` from the existing `resonanceMeasurementConfigDigestInput`. Hash that exact string once. The save-request digest helper retains original request array order, while derived semantic pages and purposes are sorted.
|
|
1615
1617
|
|
|
1616
1618
|
Measurement `Current` distinguishes actual `unconfigured` revision zero from a saved `configured` projection with current reasons. `Snapshot` contains the original audit campaign, operation, configuration and friendly page evidence. `SaveResponse` adds `replayed`. The native owner must return an exact original same-key result before fresh CAS/source checks, while enforcing current read permission; a changed request conflicts. No parser proves native provenance.
|
|
@@ -1686,7 +1688,7 @@ Every item has exactly one support entry at the same index, matching all four id
|
|
|
1686
1688
|
|
|
1687
1689
|
Provider support requires explicit nullable firstReceivedAt, receivedAt, recordedAt and readClock, plus providerFinality unknown, correctionsPossible true and coverageBasis closed_query_snapshot or not_established. Missing required flags fail parsing. First-party support forbids those provider-only fields. A complete closed query remains revisable and does not establish financial finality. Individual clicks or impressions may still be unknown even when row-level query coverage is complete; their value stays null and their metric reason remains separate from the support reason. Legacy/unestablished reporting stays explicit and supplies no operational freshness authority. Raw first/final HTTP timestamps are compared only within their own clock; native readClock bytes retain the final SQL-clock format without restamping.
|
|
1688
1690
|
|
|
1689
|
-
Pagination follows native-row UUID order, with at most 100 native rows and
|
|
1691
|
+
Pagination follows native-row UUID order, with at most 100 native rows and 500 expanded metrics per page (spend, impressions, clicks, reach and results). A non-null cursor references the last native row, never a metric offset. To display the latest snapshot, group by channel, exact window and metric, then compare support.fetchedAt, which must equal item.asOf as an instant. Do not sum repeated snapshots, turn unknown into zero or infer finality from coverage. The parser preserves reporting data; native API scope, protected producer lineage, original authority, current freshness and funding remain separate requirements.
|
|
1690
1692
|
|
|
1691
1693
|
|
|
1692
1694
|
### Original read-only provider reporting grant
|
|
@@ -1702,3 +1704,60 @@ This purpose permits read-only report collection and persistence only. It adds n
|
|
|
1702
1704
|
The existing review surface should display actual named agent, principal and selected scope from the native API projection. Parsing UUIDs is not proof of membership, an invitation, a token, a live acts-for relation or an accepted job claim. Native owners must verify the exact accepted parent grant, organization/project, current job/own claim, actor/principal, kill revision, policy/window, expiry and protected read/write admission before HTTP and persistence. Old mandates without this grant have no scheduled reporting authority. No new approval surface, grant store or bearer retrieval is introduced.
|
|
1703
1705
|
|
|
1704
1706
|
Observed provider values require complete closed-query support. This is one-way: individual metrics may remain unknown when native query coverage is complete; legacy unknown/null reporting remains readable. It grants no finality, freshness or native authority.
|
|
1707
|
+
|
|
1708
|
+
### Retargeting several properties from one campaign
|
|
1709
|
+
|
|
1710
|
+
A campaign can retarget visitors of several pages, one property each, without sharing audiences or creative between them. Each property is one Meta channel with its own audience, destination, creative and allocation, and the channels carry a shared `channelGroup` (`{ key, label }`). A channel names its `property` (`{ key, label }`) and may name a `tier` (`{ label }`) when one property has several recency tiers. Every one of these fields is optional, so a definition that uses none of them parses and serializes exactly as before.
|
|
1711
|
+
|
|
1712
|
+
`checkChannelGroups` is the one rule for a group. Its channels must share site, account, dataset, Page, special categories, countries, objective and optimization; channels for one property share one destination and channels for different properties don't; no two channels share a property and tier; tiers of one property can't overlap in time; and a group holds at most `RESONANCE_MAX_CHANNELS_PER_GROUP` (20) channels. A channel in a group with a special category must use provider-managed age. When a definition uses groups, the paid allocations can't add up to more than the campaign total less its reserve.
|
|
1713
|
+
|
|
1714
|
+
`splitBudget(total, weights, quantumMicros)` divides a total across whole weights in whole provider quanta, largest remainder first, ties to the lower index, so the shares add up to the total exactly. `suggestPropertyWeights(visitors, { floorBasisPoints, ceilingBasisPoints })` proposes weights in basis points from each property's unique visitors, 10 percent floor and 40 percent ceiling by default. It's a suggestion: equal weights are the default and a person approves any other split. `expandPropertyChannels(definition, groupKey, additions, { quantumMicros, weights })` returns the new channels for properties not yet in the group, built from the group's first channel, with ids derived from the project, campaign slug, group and property so expanding twice changes nothing. It also returns the group's new allocations and the reasons a person still has to act, such as `property_creative_required:<key>`. It never sets a creative, a converter acknowledgement (`convertersAcknowledged`) or an approval. The measurement rule, audience version and destination for a property are native objects you create first and pass in.
|
|
1715
|
+
|
|
1716
|
+
An audience reference can carry `minDaysSinceVisit` (1 to 179), a recency band that keeps only people whose latest visit is at least that many days old. `checkAudienceBand(ref, provider)` requires the band to be shorter than the retention window, caps a Meta window at `META_WEBSITE_AUDIENCE_MAX_RETENTION_DAYS` (180) and a Meta audience at ten rules, and refuses a band on Google. The recency, window and rule checks run on a definition only for a Meta channel that uses a group or a band.
|
|
1717
|
+
|
|
1718
|
+
`metaExclusionPolicy(channel, { targetingLevel, inRule })` answers whether an exclusion is allowed. Under a special category a targeting-level custom-audience exclusion is refused with `meta_exclusion_targeting_blocked_special_category` while `META_SAC_CUSTOM_AUDIENCE_EXCLUSION_VERIFIED` is `false`, and an in-rule exclusion or band is allowed only when Meta's own eligibility readback for that audience says so. `META_CALL_TO_ACTIONS` lists the call-to-action values a Meta ad accepts, and `primaryText` (up to 2200 characters) is the ad's main text, separate from the first card's description.
|
|
1719
|
+
|
|
1720
|
+
Provider metrics gain `reach` (unique people, counting unit `provider_unique_reach`) and `results`. Reach is never added across channels or windows. `deriveProviderRatios(items)` is the one place the ratios are computed, from provider-sourced, observed items that share one observation, channel and window. Frequency is impressions over reach, and cost per result is spend over results rounded half to even at one micro. Zero reach, zero results, a missing input or mixed inputs give an unknown result with a reason, never zero and never a guess.
|
|
1721
|
+
|
|
1722
|
+
|
|
1723
|
+
|
|
1724
|
+
### Explicit Meta reporting queries
|
|
1725
|
+
|
|
1726
|
+
The existing report selector and resolved grant accept optional `metaQueries`.
|
|
1727
|
+
Each row contains exactly `channelId`, `attributionWindow` (`1d_click`,
|
|
1728
|
+
`7d_click` or `1d_view`), `actionReportTime: 'conversion'` and
|
|
1729
|
+
`basis: 'explicit_query'`. A present list contains 1–100 rows, has unique
|
|
1730
|
+
channel identities and stays within the selected `channelIds`. UUID identity
|
|
1731
|
+
comparisons ignore case; parsers preserve the supplied text and order. The
|
|
1732
|
+
exported `RESONANCE_META_QUERY_ATTRIBUTION_WINDOWS` is the shared window list.
|
|
1733
|
+
|
|
1734
|
+
Omitting the field preserves legacy payloads and digest material. It doesn't
|
|
1735
|
+
upgrade a historical grant to permission for fresh automatic Meta reporting.
|
|
1736
|
+
The native owner checks actual Meta channel coverage, account/site/version
|
|
1737
|
+
membership and original human review. Human manual reporting and passive
|
|
1738
|
+
history keep their existing authorization rules. These are requested report
|
|
1739
|
+
queries; they don't describe configured attribution or claim parity with Ads
|
|
1740
|
+
Manager. Review and adopt the same contracts version across producers and
|
|
1741
|
+
consumers before sending the extended shape to an older strict parser.
|
|
1742
|
+
|
|
1743
|
+
### Explicit audience readiness checks
|
|
1744
|
+
|
|
1745
|
+
`parseResonanceMetaRetargetingReadiness`, its matching type and
|
|
1746
|
+
`RESONANCE_META_RETARGETING_READINESS_JSON_SCHEMA` describe one scoped public
|
|
1747
|
+
response. It contains the current campaign/channel/account identity, the
|
|
1748
|
+
existing configuration view and per-rule inclusion/exclusion page references.
|
|
1749
|
+
An audience check is either `not_checked` with a bounded reason, or `observed`
|
|
1750
|
+
with the existing classifier verdict/reasons, actual native audience ID and
|
|
1751
|
+
nullable estimated bounds. `RESONANCE_META_AUDIENCE_VERDICTS` and
|
|
1752
|
+
`RESONANCE_META_AUDIENCE_REASONS` define the shared public vocabulary; provider
|
|
1753
|
+
classification stays with the API owner.
|
|
1754
|
+
|
|
1755
|
+
An observed check's `observedAt` identifies the actual completed owner check.
|
|
1756
|
+
It doesn't date an estimated audience sample. `sizeObservedAt` and
|
|
1757
|
+
`sizeExpiresAt` are explicitly `null` in this version, and the current producer
|
|
1758
|
+
has no audience expiry to supply. Missing size stays `null`, independently of
|
|
1759
|
+
an observed status. Consumers mustn't add bounds across rules or infer fresh
|
|
1760
|
+
sample data from configuration expiry. A source/revision drift, denied scope
|
|
1761
|
+
or provider failure is a transport error, not a fabricated readiness result.
|
|
1762
|
+
The parser checks the closed response and its public scope relationships;
|
|
1763
|
+
actual native ownership, provider checks, launch and delivery remain separate.
|
package/dist/outreach.js
CHANGED
|
@@ -1,50 +1,6 @@
|
|
|
1
1
|
'use strict';
|
|
2
2
|
|
|
3
|
-
// src/contracts/
|
|
4
|
-
var TABLE = [
|
|
5
|
-
["do not", "don't"],
|
|
6
|
-
["does not", "doesn't"],
|
|
7
|
-
["did not", "didn't"],
|
|
8
|
-
["is not", "isn't"],
|
|
9
|
-
["are not", "aren't"],
|
|
10
|
-
["was not", "wasn't"],
|
|
11
|
-
["were not", "weren't"],
|
|
12
|
-
["cannot", "can't"],
|
|
13
|
-
["can not", "can't"],
|
|
14
|
-
["will not", "won't"],
|
|
15
|
-
["would not", "wouldn't"],
|
|
16
|
-
["should not", "shouldn't"],
|
|
17
|
-
["could not", "couldn't"],
|
|
18
|
-
["has not", "hasn't"],
|
|
19
|
-
["have not", "haven't"],
|
|
20
|
-
["had not", "hadn't"],
|
|
21
|
-
["must not", "mustn't"],
|
|
22
|
-
["need not", "needn't"],
|
|
23
|
-
["it is", "it's"],
|
|
24
|
-
["that is", "that's"],
|
|
25
|
-
["there is", "there's"],
|
|
26
|
-
["here is", "here's"],
|
|
27
|
-
["who is", "who's"],
|
|
28
|
-
["what is", "what's"],
|
|
29
|
-
["you are", "you're"],
|
|
30
|
-
["we are", "we're"],
|
|
31
|
-
["they are", "they're"],
|
|
32
|
-
["I am", "I'm"],
|
|
33
|
-
["you will", "you'll"],
|
|
34
|
-
["we will", "we'll"],
|
|
35
|
-
["they will", "they'll"],
|
|
36
|
-
["it will", "it'll"],
|
|
37
|
-
["we would", "we'd"],
|
|
38
|
-
["you would", "you'd"],
|
|
39
|
-
["they would", "they'd"],
|
|
40
|
-
["let us", "let's"]
|
|
41
|
-
];
|
|
42
|
-
TABLE.map(([full, contracted]) => ({
|
|
43
|
-
full,
|
|
44
|
-
contracted,
|
|
45
|
-
negation: / not$|^cannot$/.test(full),
|
|
46
|
-
pattern: new RegExp(`\\b${full.replace(/ /g, "[ \\t]+")}\\b`, "gi")
|
|
47
|
-
}));
|
|
3
|
+
// src/contracts/business-claims.ts
|
|
48
4
|
function fnv1a(text) {
|
|
49
5
|
let hash = 2166136261;
|
|
50
6
|
for (let i = 0; i < text.length; i++) {
|
package/dist/outreach.mjs
CHANGED
|
@@ -1,48 +1,4 @@
|
|
|
1
|
-
// src/contracts/
|
|
2
|
-
var TABLE = [
|
|
3
|
-
["do not", "don't"],
|
|
4
|
-
["does not", "doesn't"],
|
|
5
|
-
["did not", "didn't"],
|
|
6
|
-
["is not", "isn't"],
|
|
7
|
-
["are not", "aren't"],
|
|
8
|
-
["was not", "wasn't"],
|
|
9
|
-
["were not", "weren't"],
|
|
10
|
-
["cannot", "can't"],
|
|
11
|
-
["can not", "can't"],
|
|
12
|
-
["will not", "won't"],
|
|
13
|
-
["would not", "wouldn't"],
|
|
14
|
-
["should not", "shouldn't"],
|
|
15
|
-
["could not", "couldn't"],
|
|
16
|
-
["has not", "hasn't"],
|
|
17
|
-
["have not", "haven't"],
|
|
18
|
-
["had not", "hadn't"],
|
|
19
|
-
["must not", "mustn't"],
|
|
20
|
-
["need not", "needn't"],
|
|
21
|
-
["it is", "it's"],
|
|
22
|
-
["that is", "that's"],
|
|
23
|
-
["there is", "there's"],
|
|
24
|
-
["here is", "here's"],
|
|
25
|
-
["who is", "who's"],
|
|
26
|
-
["what is", "what's"],
|
|
27
|
-
["you are", "you're"],
|
|
28
|
-
["we are", "we're"],
|
|
29
|
-
["they are", "they're"],
|
|
30
|
-
["I am", "I'm"],
|
|
31
|
-
["you will", "you'll"],
|
|
32
|
-
["we will", "we'll"],
|
|
33
|
-
["they will", "they'll"],
|
|
34
|
-
["it will", "it'll"],
|
|
35
|
-
["we would", "we'd"],
|
|
36
|
-
["you would", "you'd"],
|
|
37
|
-
["they would", "they'd"],
|
|
38
|
-
["let us", "let's"]
|
|
39
|
-
];
|
|
40
|
-
TABLE.map(([full, contracted]) => ({
|
|
41
|
-
full,
|
|
42
|
-
contracted,
|
|
43
|
-
negation: / not$|^cannot$/.test(full),
|
|
44
|
-
pattern: new RegExp(`\\b${full.replace(/ /g, "[ \\t]+")}\\b`, "gi")
|
|
45
|
-
}));
|
|
1
|
+
// src/contracts/business-claims.ts
|
|
46
2
|
function fnv1a(text) {
|
|
47
3
|
let hash = 2166136261;
|
|
48
4
|
for (let i = 0; i < text.length; i++) {
|