lib.advertising-runtime

Advertising runtime

Shared scoped HTTP mechanics and durable execution of compiled provider recipes. Provider adapters live in provider-meta-ads, provider-google-ads and provider-tiktok. No provider credentials, API version, account permissions or spend grant is supplied by default. Hosts inject current authorization, connection-bound secrets and transport.

AdvertisingRecipeExecutor claims each step before dispatch and stores every response before resolving dependent resource IDs. Unknown creates are never retried. Reconciliation is read-only; explicit execution can continue only after the uncertain step is proven accepted. AdvertisingMarketingProvider connects this to the existing marketing budget reservation/execution system. Its trusted compiler must resolve brand copy/assets, audiences, ownership and native budgets from the reviewed plan. It is not an LLM payload passthrough. Recipe keys are namespaced by tenant/workspace/brand.

Validation-only results never count as applied effects. Google mutation batches reject partial-failure mode; conversion endpoints retain their platform-required semantics. HTTP errors remain unknown unless independent provider reconciliation proves the result. Platform API acceptance does not mean an ad is approved, delivering or converting.

API limits and budget pacing differ by platform. The host must qualify native budget constraints and overdelivery exposure; the local reservation is not a universal provider spend cap. This layer does not itself implement OAuth onboarding or every product-level campaign preset. Live account and campaign-format qualification remains required.

AdvertisingLaunchCompiler loads immutable, plan-bound native materials. Meta and TikTok create disabled parents before creating children, and activate the campaign last. Google uses a single atomic multi-resource mutation, preserving asset groups and keyword match semantics. Google budgets require an explicit maximum-exposure assessment; account IANA timezones determine provider-local dates. TikTok uses bounded lifetime ad-group budgets. AdvertisingControlCompiler supports reviewed pause/resume with an exact observed-state digest. Host preflight must recheck that state immediately before execution. Google conversion corrections are available through the separate conversion service; live qualification remains outstanding.

AdvertisingBudgetCompiler consumes the immutable MarketingBudgetChange document. Its digest must appear in the reviewed plan evidence; currencies, previous observations, exclusive campaign budget ownership, expiry and maximum additional exposure are checked before compilation. Meta/TikTok lifetime changes remain distinct from Google's daily budgets. Google amounts are converted to micros using exact integer arithmetic. The host must verify pacing/overdelivery exposure; native budget changes never release earned liability.

AdvertisingCreativeCompiler consumes an immutable MarketingCreativeReplacement, bound to current provider state, the previous creative digest, desired revision and rights. Meta retains the ad ID while replacing its creative; TikTok stages a disabled successor before pausing the old ad. Google ad replacements and PMax asset-link replacements are atomic. PMax activation applies to the selected asset group. Old assets are retained for audit. Hosts must qualify the exact format and approved native materialization, and must recheck rights and scope for every request. These compilers do not prove platform review approval or successful delivery.

AdvertisingCampaignCompiler routes launch, pause/resume, budget changes and optional creative replacement. Conversion delivery uses the separate consent-gated service described below. All compiled actions use the existing durable recipe and reservation engine.

Native field references: Google REST mutation examples, TikTok ad-group update model, TikTok creative model.

AdvertisingConversionProvider maps single-event conversion receipts to Meta/TikTok website events and Google click conversions. Google additionally supports offline click imports, restatements and retractions. advertisingConversionCapabilities is an executable protocol matrix; app-origin events and Meta/TikTok corrections remain unavailable. Protocol support is independent of current tenant/account qualification.

Matching data is loaded only by an authorized host and is never stored by the shared receipt service. Email and phone fields require pre-hashed SHA-256 values. Native event and order IDs derive from the durable source/destination identity. One event per request avoids accepting a partly failed batch. Response evidence is stored as a digest, not a copy of matching data. Reconciliation requires independent read-only provider evidence.

See Google adjustment rules and Google terminal adjustments: retractions and Google zero-value restatements cannot subsequently be restored through this adjustment workflow.

AdvertisingCampaignObserver reads explicitly authorized campaign/ad-set/ad-group/ad/ asset-group references using scoped native reads. Google policy review and primary status are separate from configuration. Unknown native statuses stay unknown; eligibility never proves impressions or actual delivery. A complete response means only the requested resources were returned, not that an entire account or campaign graph was discovered.

The host must persist sanitized source responses through the required evidence port. Failed reads or failed evidence capture remain unavailable. Snapshot state digests omit poll timestamps and evidence locations, so an unchanged provider state remains stable. Use the native API version qualified for the installation; these tests do not qualify live accounts or every provider status value.