Ads Sync developer documentation

Configure, verify, and understand the Patronage Ads Sync public contract.

Ads Sync is a Cloudflare-hosted ingestion toolkit for Google Ads, Google Search Console, and Meta Ads data. The public product has two parts: the @patronage/ads-sync package and its nested reference deployment.

@patronage/ads-sync 0.3.0 is on npm as latest:

pnpm add @patronage/ads-sync@0.3.0

0.2.0 and 0.1.0 remain available. 0.3.0 adds @patronage/ads-sync/run and the catalog and token-only source-config builder exports. Start with defineAdsSyncConfig.

start with a working configuration

import { defineAdsSyncConfig } from "@patronage/ads-sync";

export const adsSyncConfig = defineAdsSyncConfig({
  connections: [
    {
      catalog: { streams: [] },
      destinationSchema: "airbyte_google_ads_performance",
      provider: "google_ads",
      sourceConfigSecret: "GOOGLE_ADS_SOURCE_CONFIG_JSON",
    },
  ],
});

The config names a secret. It does not contain the credential value. To deploy, follow the quickstart: your own Cloudflare account, your own Postgres, one Supported Provider, one scheduled Qualified Run, under an hour. To compose the package into your own runner, follow configure your first sync, then run the detailed configure-connections.ts source tutorial.

use the pages by task

• Quickstart deploys the Ads Sync Reference Deployment to your Cloudflare account and Postgres and completes one scheduled Qualified Run.
• Configure your first sync is the package happy path for your own runner.
• Verify a bounded run covers canary evidence, backfill policy, storage keys, and the historical comparison gate.
• Ejection Path is the procedure for a Loop tenant to resume single-tenant on the open-source core.
• Admit a provider runs pnpm --filter @patronage/ads-sync-deploy provider-admission -- --provider <id>, the executable check that a Supported Provider is wired end to end in a deployment; run it before you trust a new connection.
• Public contract reference lists the exact shipped inputs, defaults, provider definitions, the Qualified Run seam, and the reference routes.
• Connector image HTTP contract is the wrapper surface every connector image reports, and the Dockerfiles and build command that produce the images.
• Architecture and boundaries explains the package, reference deployment, custody, and private dogfood split.
• Google Search Console caveats covers the seven-day Testing-mode refresh token, the seam’s cold-start retry, final versus provisional data, and the image auth modes.