Public contract reference
Exact public configuration, provider, canary, storage, and reference deployment contracts.
This page describes the public @patronage/ads-sync entry point and nested deploy/ shell. For working compositions, run configure-connections.ts, prepare-bounded-run.ts, and run-historical-comparison.ts.
configuration
defineAdsSyncConfig() parses an object with a required, non-empty connections array.
| connection field | input | default or effect |
|---|---|---|
catalog |
required unknown value | Configured Airbyte catalog |
catalogRef |
optional non-empty string | Generated ads-sync.config.ts#<connection>.catalog reference |
connectionId |
optional non-empty string | <provider>_default |
displayName |
optional non-empty string | Provider display name plus stream group |
destinationSchema |
optional non-empty string | Provider default Airbyte schema |
provider |
google_ads or meta_ads |
Required |
reportingEnabled |
boolean | true |
scheduleCron |
null |
null |
scheduleEveryMinutes |
positive integer or null |
360 |
selectedStreams |
optional array of non-empty strings | Streams found in the catalog |
sourceConfigSecret |
required non-empty string | Secret name, never a credential value |
stateSecret |
optional non-empty string | Curated provider state secret name |
streamGroup |
optional non-empty string | Provider default stream |
streamName |
optional non-empty string | Provider default stream |
syncConnectionDefinitionFromConfig() also requires the resolved source configuration value. It returns a SyncConnectionDefinition with source identity and hashes, catalog hash and reference, schedule, selected streams, state reference, and destination schema. validateDestinationSchemaIsolation() rejects two enabled connections that share a destination schema.
curated provider definitions
| provider | source image | default schema | backfill policy | rate limit policy |
|---|---|---|---|---|
google_ads |
airbyte/source-google-ads:6.1.0 |
airbyte_google_ads |
7-day steps, 8 windows per run | none |
meta_ads |
airbyte/source-facebook-marketing:5.2.11 |
airbyte_meta_ads |
3-day steps, 4 windows per run | stop on code 17, 3600-second cooldown |
The pinned destination image is airbyte/destination-postgres:3.0.13. defineProvider() is an advanced definition helper. Calling it does not register a provider, add a catalog, build a Container image, or add a reporting view. The shipped supported set remains Google Ads and Meta Ads.
canary request
parseAdsSyncCanaryRequest() accepts exactly:
| field | contract |
|---|---|
connectionId |
lowercase identifier matching ^[a-z][a-z0-9_]{2,63}$ |
provider |
google_ads or meta_ads |
windowStart |
string accepted by the JavaScript Date parser |
windowEnd |
accepted date string after the start |
The window must be no longer than 24 hours. adsSyncCanaryRequestSha256() hashes the canonical request with ISO-normalized dates.
storage and state
controlSchemaSql defines Postgres runtime tables for Sync Connections, Backfill Plans, Sync Run Windows, runs, stream runs, committed state, artifacts, catalog snapshots, errors, generations, and stream leases. The package emits SQL and primitives; the operator owns migration authorization and execution.
artifactKeys() returns a prefix and keys for configured catalog, source stdout and stderr, optional state input, destination input, destination stdout and stderr, and summary. The package does not write R2 objects. committedStateAfterDestinationResult() returns no state after a failed destination write.
historical comparison
runHistoricalComparisonGate() reads provider and ads_sync_reporting.ads_campaign_daily rows for the same window. Its Source Comparison Artifact covers impressions, clicks, spend, conversions, and conversion value. Missing rows, duplicate rows, failed tolerances, or an unstable window result in "review".
Default absolute or relative tolerance is zero for impressions and clicks, 0.01 absolute or 0.001 relative for spend, conversions, and conversion value. A known delta needs an exact account, entity, date, metric, and reason.
reference deployment
The nested packages/ads-sync/deploy workspace is private to npm packaging but present in the public repository tree. Its Worker currently serves:
| operation | local effect | remote effect | output |
|---|---|---|---|
GET /health |
none | none | { ok: true, service } |
GET / |
none | none | service name, route list, and supported provider summaries |
It has no migration, run, canary, or backfill endpoint. Its check command runs type checking, tests, and the public-import boundary check. Its build command performs a Wrangler deployment dry run after building the package. dev starts local Wrangler. deploy mutates Cloudflare resources and requires operator authorization; this documentation workflow does not run it.