@sonordev/contracts 2.21.0 → 2.22.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 CHANGED
@@ -1,5 +1,15 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.22.0
4
+
5
+ - 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.
6
+ - 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.
7
+ - 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.
8
+ - 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.
9
+ - 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.
10
+ - 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.
11
+ - 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.
12
+
3
13
  ## 2.21.0
4
14
 
5
15
  - 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 300 expanded metrics per page. 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.
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,18 @@ 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
+
package/dist/outreach.js CHANGED
@@ -1,50 +1,6 @@
1
1
  'use strict';
2
2
 
3
- // src/contracts/voice.ts
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/voice.ts
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++) {