@sonordev/contracts 2.22.0 → 2.25.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,22 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.25.0
4
+
5
+ - Add guided Meta dataset selection and setup contracts, including exact verified dataset readback and a shared dataset name validator.
6
+ - Add audience setup review for one saved rule and an explicit opt-in for future eligible visits. Keep the verified audience receipt separate from the revocable visit grant.
7
+ - Add combined readiness and paginated recovery contracts. Accepted visit counts and provider audience readiness remain separate observations.
8
+
9
+ ## 2.24.0 (2026-11-02)
10
+
11
+ - Align UUID JSON Schema patterns with the existing runtime acceptance of lowercase, uppercase and mixed spelling in call preparation, Resonance and experiment measurement. Keep UUID versions 1–8 and existing variant restrictions, with original identity text preserved.
12
+
13
+ - Add the dependency-free `sales-call-prep` entry for bounded call guides, captured objective/style, immutable version and explicit use/correction receipts. Keep resolved context and native provenance separate from model content. Add private observational learning summaries and deterministic server hash-input serializers without changing existing ledger approval controls.
14
+
15
+ ## 2.23.0
16
+
17
+ - 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.
18
+ - 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.
19
+
3
20
  ## 2.22.0
4
21
 
5
22
  - 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.
package/README.md CHANGED
@@ -1426,8 +1426,8 @@ without that witness, the evidence bound remains unknown. Coverage stays separat
1426
1426
 
1427
1427
  ### Successor management and attribution fields
1428
1428
 
1429
- The local 2.20 candidate adds `@sonordev/contracts/signal-experiments` as the
1430
- single parser for the existing Signal create/update payload. It exports
1429
+ Added in 2.20.0, `@sonordev/contracts/signal-experiments` is the single parser
1430
+ for the existing Signal create/update payload. It exports
1431
1431
  `parseSignalExperimentCreate`, `parseSignalExperimentUpdate`, their types and
1432
1432
  JSON Schemas. Both operations check unique variant keys and the existing
1433
1433
  weight-sum tolerance of 0.01. Percentages must be finite and within 0 to 100.
@@ -1660,7 +1660,7 @@ The additional closed original Meta intent is `{mode: 'provider_managed'}`. It a
1660
1660
  Native create and validation requests must omit both age keys. Before activation, the first genuine same-root PAUSED AdSet creator receipt and complete scoped read must seal initial age values **and key presence** once in the existing protected operation. Activation must compare that unchanged observation and every independent non-age, consent, authority and budget gate. Later changes block. This intent makes no claim about exclusive default authorship, unlimited ages, legality or serving. Existing three-mode consumers need explicit preservation, editing and review support before adopting this branch.
1661
1661
 
1662
1662
 
1663
- ### Reported-cost SQL clock candidate
1663
+ ### Reported-cost SQL clock
1664
1664
 
1665
1665
  The explicit `reported_cpql_conserved_transfer_v1` policy requires `costBasis: 'provider_reported_snapshot_v1'`, `costRevisionRisk: 'accepted_provisional'`, `readClockKind: 'sql_before_provider_read_lower_bound_v1'` and the existing observational allocation thresholds. This is the sole reported-cost policy in this candidate. Earlier unpublished no-clock draft policy/evidence is rejected. Existing mature, finite and default profiles keep their meanings. Adoption requires compatible consumers and this exact policy in the original prepared plan, review and accepted mandate; parsing never grants authority.
1666
1666
 
@@ -1677,7 +1677,7 @@ Keep one exact nonfinal provider spend observation and independent first-party q
1677
1677
 
1678
1678
  `reportedCpqlMissingOutcomeBound` shares the integer outcome sensitivity arithmetic, conditional on reportedSpend. It does not bound cost corrections, establish financial finality, prove causal lift or guarantee cost ordering. Zero cost or no qualified contacts leaves it unavailable. Existing canonical digest functions bind clock kind, immutable cost and independent outcome provenance. Decisions retain observational_allocation/reduce_then_increase, include cost observation IDs and qualification source revisions, and expire by the conservative SQL anchor deadline.
1679
1679
 
1680
- No new approval surface or engine is introduced. Native budget actions retain their supported original graph and period restrictions. Reported cost releases no donor hold or recipient funding; genuine incremental headroom above reserve remains required. Unknown donor effect stops recipient execution, unsupported funding stays unavailable, and corrections create new immutable history. Parser/schema/source checks cannot authenticate a provider exchange, prove native run binding, grant an action or replace those native checks. This source candidate has no compiled package while the shared build resource is reserved.
1680
+ No new approval surface or engine is introduced. Native budget actions retain their supported original graph and period restrictions. Reported cost releases no donor hold or recipient funding; genuine incremental headroom above reserve remains required. Unknown donor effect stops recipient execution, unsupported funding stays unavailable, and corrections create new immutable history. Parser/schema/source checks cannot authenticate a provider exchange, prove native run binding, grant an action or replace those native checks.
1681
1681
 
1682
1682
 
1683
1683
  ### Public observation pages
@@ -1719,3 +1719,146 @@ An audience reference can carry `minDaysSinceVisit` (1 to 179), a recency band t
1719
1719
 
1720
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
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.
1764
+
1765
+
1766
+ ### Guided Meta audience setup
1767
+
1768
+ Use `@sonordev/contracts/resonance` to review audience setup for a saved draft before you add creative or budget. For example, a fictional bike shop could select an existing dataset and review an audience for visits to its repair page.
1769
+
1770
+ - Use `parseResonanceMetaDatasetSelectionRequest` for existing selection and `parseResonanceMetaDatasetSelectionWitness` for the verified dataset ID, resource revision, and observation time. For dataset creation, use the `parseResonanceMetaDatasetSetupPrepareRequest`, `parseResonanceMetaDatasetSetupReview`, and `parseResonanceMetaDatasetSetupReceipt` contracts. Prepare and intent share `parseResonanceMetaDatasetName`, which limits trimmed names to 160 UTF-16 code units.
1771
+ - Use `parseResonanceMetaAudienceSetupPrepareRequest` to select one saved audience rule and an exact dataset revision. The owner resolves the reviewed scope in `parseResonanceMetaAudienceSetupReview`. Choose `feed: { kind: 'off' }` or explicitly opt in with `feed: { kind: 'enable', expiresAt }`. Opt-in lets the native owner activate a separate revocable grant after it verifies the exact approved audience. A later enablement or scope change needs fresh review.
1772
+ - Use `parseResonanceMetaAudienceSetupStatus` for the provider receipt and any linked grant. The receipt preserves the first provider outcome separately from verified readback. Use `parseResonanceMetaAudienceSetupReadiness` to read accepted visits and provider audience readiness as separate observations. A null observation means the corresponding evidence is unavailable. Use `parseResonanceMetaAudienceSetupList` to restore saved operations after reload, with up to 25 items and a UUID or null cursor.
1773
+
1774
+ Only eligible visits from the active grant window can be considered for delivery. The native owner checks approval, current scope and consent before dispatch. The parsers validate wire shape and consistency. Campaign launch and spend require their own authorization.
1775
+
1776
+
1777
+ ## Sales call preparation
1778
+
1779
+ Added in 2.24.0, `@sonordev/contracts/sales-call-prep` provides pure request,
1780
+ content, context, version, use and learning-summary parsers, matching types and
1781
+ JSON schemas. It adds no network, storage, hashing or browser Node dependency.
1782
+
1783
+ ```ts
1784
+ import {
1785
+ parseSalesCallPrepRequest,
1786
+ salesCallPrepRequestDigestInput,
1787
+ SALES_CALL_PREP_STYLE_POLICY_VERSION,
1788
+ } from '@sonordev/contracts/sales-call-prep'
1789
+
1790
+ const request = parseSalesCallPrepRequest({
1791
+ schemaVersion: 1,
1792
+ requestId: '00000000-0000-4000-8000-000000000001',
1793
+ projectId: '00000000-0000-4000-8000-000000000002',
1794
+ selectedContactId: null,
1795
+ objective: 'qualify',
1796
+ style: 33,
1797
+ stylePolicyVersion: SALES_CALL_PREP_STYLE_POLICY_VERSION,
1798
+ callNotes: '',
1799
+ regenerate: false,
1800
+ })
1801
+ const canonicalRequest = salesCallPrepRequestDigestInput(request)
1802
+ ```
1803
+
1804
+ Objectives are `qualify`, `book`, `follow_up` and `advance`. Style is an integer
1805
+ from 0 to 100, with anchors Professional (0), Conversational (33), Bold (67)
1806
+ and Wild (100). The selected number and policy version stay explicit. A style
1807
+ setting doesn't authorize invented facts, promises or consent. `callNotes`
1808
+ holds at most 4,000 characters. The request carries no organization, actor or
1809
+ offer authority; the authenticated owner resolves those relationships.
1810
+
1811
+ `parseSalesCallPrepContent` keeps the compatible camelCase briefing fields
1812
+ and adds one closed `callGuide`. Its main opener must match
1813
+ `recommendedOpening`. The guide separates observations, cited source IDs,
1814
+ hypotheses and unknowns, with distinct interested, busy, existing-provider,
1815
+ send-information and not-a-fit responses. `needs_context` identifies what is
1816
+ missing and has no ready opener. Source observation dates may be unknown;
1817
+ they aren't filled with the current time. Supply actual resolved source
1818
+ references to check citation metadata, or use
1819
+ `parseSalesCallPrepContentForContext` to also check saved-voice availability.
1820
+ Shape validation alone doesn't establish factual truth or source permission.
1821
+ The guide can cite at most 30 sources; the actual resolved witness can retain
1822
+ up to 100, so bounded history and seller guidance don't need to be discarded.
1823
+
1824
+ The context and witness parsers accept a closed, server-resolved projection
1825
+ of actual private bindings, source revisions, Brain/voice availability,
1826
+ history, approved-guidance references and prompt/schema versions. Private
1827
+ notes stay outside that witness. `salesCallPrepNotesDigestInput` serializes the
1828
+ exact note as a JSON string, including whitespace. The server hashes its UTF-8
1829
+ bytes and supplies `notesDigest` in the context. Context, witness and content
1830
+ have their own `*DigestInput` serializers. Object keys are sorted; witness
1831
+ reference sets sort by ID; meaningful content list order stays unchanged.
1832
+ These functions don't create hashes or native IDs.
1833
+
1834
+ `parseSalesCallPrepVersion` describes an actual persisted immutable version.
1835
+ Human edits name their parent and expected head/context. A cached version keeps
1836
+ its original request and version identities; a later cache request doesn't
1837
+ rewrite them. `parseSalesCallPrepGenerateResult` keeps the current operation's
1838
+ `requestId` and `reused` flag outside the original version receipt. A model result or legacy unversioned briefing isn't a saved
1839
+ version. Native owners must validate digests, current context, access,
1840
+ idempotency and fencing before returning a saved receipt.
1841
+
1842
+ `parseSalesCallPrepConfirmUseRequest` requires an actual `attemptId`, the final
1843
+ `versionId`, `confirmedUsed: true`, and a `callId` or `manualEventId`.
1844
+ Generated, shown, copied, dialed and transcript-inferred activity cannot enter
1845
+ that confirmed-use command. Native owners validate the selected person and
1846
+ actual source. Corrections and retractions append to the use chain. A
1847
+ retraction retains its source snapshot without a confirmed-use assertion.
1848
+ Current source eligibility and manual-event ambiguity are separate from the
1849
+ immutable receipt. `parseSalesCallPrepScriptUseResult` can report a missing
1850
+ use link and a retry even when the surrounding disposition was saved.
1851
+
1852
+ Learning summaries remain principal-private and observational. Generated,
1853
+ confirmed, inferred, connected, qualified, booked, held, won, lost and unknown
1854
+ counts stay separate. Booked doesn't mean held; missing doesn't mean failed.
1855
+ Bounded eligible-use references aren't a whole-cohort denominator. The summary
1856
+ serializer omits only its self `snapshotDigest`; the server computes it.
1857
+ Only the existing human-reviewed ledger owner can supply eligible generalized
1858
+ principles. Parsing a principle or proposal receipt neither approves it nor
1859
+ makes private scripts, notes or transcripts shareable. Existing ledger review
1860
+ and revert controls remain authoritative.
1861
+
1862
+ Packed import, require and declaration checks are package
1863
+ proof; each application's native joins, permissions and behavior still need
1864
+ its own verification before a release.