---
title: Ads Sync developer documentation
description: 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`:

```sh
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

```ts
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](/tutorial/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](/tutorial/configure-your-first-sync), then run the detailed [`configure-connections.ts` source tutorial](https://github.com/patronage/agentic-marketing-connectors/blob/main/packages/ads-sync/src/tutorials/configure-connections.ts).

## use the pages by task

- [Quickstart](/tutorial/quickstart) deploys the Ads Sync Reference Deployment to your Cloudflare account and Postgres and completes one scheduled Qualified Run.
- [Configure your first sync](/tutorial/configure-your-first-sync) is the package happy path for your own runner.
- [Verify a bounded run](/how-to/verify-a-bounded-run) covers canary evidence, backfill policy, storage keys, and the historical comparison gate.
- [Ejection Path](/how-to/eject-from-loop) is the procedure for a Loop tenant to resume single-tenant on the open-source core.
- [Admit a provider](/how-to/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](/reference/public-contract) lists the exact shipped inputs, defaults, provider definitions, the Qualified Run seam, and the reference routes.
- [Connector image HTTP contract](/reference/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](/explanation/architecture-and-boundaries) explains the package, reference deployment, custody, and private dogfood split.
- [Google Search Console caveats](/explanation/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.