@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 +17 -0
- package/README.md +147 -4
- package/dist/resonance.d.ts +1449 -348
- package/dist/resonance.js +421 -9
- package/dist/resonance.mjs +376 -10
- package/dist/sales-call-prep.d.ts +666 -0
- package/dist/sales-call-prep.js +334 -0
- package/dist/sales-call-prep.mjs +288 -0
- package/dist/signal-experiments.d.ts +0 -1
- package/dist/signal-experiments.js +4 -1
- package/dist/signal-experiments.mjs +4 -1
- package/dist/wire-uuid.d.ts +5 -0
- package/package.json +6 -1
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
|
-
|
|
1430
|
-
|
|
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
|
|
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.
|
|
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.
|