Skip to content

armgit / dub

Public Imported from GitHub
0

The modern link attribution platform. Loved by world-class engineering teams at Twilio, Zillow, Jobber, Vercel, Raycast, and more.

15.6 KB
Raw Blame
import * as z from "zod/v4";
import { GOOGLE_ADS_API_VERSION } from "./constants";
import {
  googleAdsConversionActionSchema,
  googleAdsConversionUploadSchema,
  googleAdsCustomerSchema,
} from "./schema";

export type GoogleAdsClickId =
  | { gclid: string }
  | { gbraid: string }
  | { wbraid: string };

type UploadClickConversionParams = {
  customerId: string;
  conversionAction: string;
  googleClickId: GoogleAdsClickId;
} & Pick<
  z.infer<typeof googleAdsConversionUploadSchema>,
  | "conversionDateTime"
  | "eventId"
  | "conversionValue"
  | "currencyCode"
  | "conversionCount"
>;

type GoogleAdsRequestOptions = {
  accessToken: string;
  loginCustomerId?: string | null;
};

const getGoogleAdsHeaders = ({
  accessToken,
  loginCustomerId,
}: GoogleAdsRequestOptions) => {
  const headers: Record<string, string> = {
    Authorization: `Bearer ${accessToken}`,
    "developer-token": process.env.GOOGLE_ADS_DEVELOPER_TOKEN!,
    "Content-Type": "application/json",
  };

  if (loginCustomerId) {
    headers["login-customer-id"] = loginCustomerId.replace(/-/g, "");
  }

  return headers;
};

const googleAdsFetch = async <T>({
  path,
  method = "GET",
  body,
  ...options
}: GoogleAdsRequestOptions & {
  path: string;
  method?: "GET" | "POST";
  body?: unknown;
}): Promise<T> => {
  const response = await fetch(
    `https://googleads.googleapis.com/${GOOGLE_ADS_API_VERSION}/${path}`,
    {
      method,
      headers: getGoogleAdsHeaders(options),
      ...(body ? { body: JSON.stringify(body) } : {}),
    },
  );

  const text = await response.text();
  let data: any;

  try {
    data = text ? JSON.parse(text) : null;
  } catch {
    console.error("[Google Ads API]", path, text);

    throw new Error(
      `[Google Ads API] Request failed for ${path} (${response.status}): ${text || "Unknown error"}`,
    );
  }

  if (!response.ok) {
    console.error("[Google Ads API]", path, data);

    throw new Error(
      `[Google Ads API] Request failed for ${path} (${response.status}): ${formatApiErrorDetail(data, text)}`,
    );
  }

  return data as T;
};

const dataManagerFetch = async <T>({
  accessToken,
  path,
  body,
}: {
  accessToken: string;
  path: string;
  body: unknown;
}): Promise<T> => {
  const response = await fetch(
    `https://datamanager.googleapis.com/v1/${path}`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    },
  );

  const text = await response.text();
  let data: any;

  try {
    data = text ? JSON.parse(text) : null;
  } catch {
    console.error("[Data Manager API]", path, text);

    throw new Error(
      `[Data Manager API] Request failed for ${path} (${response.status}): ${text || "Unknown error"}`,
    );
  }

  if (!response.ok) {
    console.error("[Data Manager API]", path, data);

    throw new Error(
      `[Data Manager API] Request failed for ${path} (${response.status}): ${formatApiErrorDetail(data, text)}`,
    );
  }

  return data as T;
};

export const formatApiErrorDetail = (data: any, rawText: string) => {
  const payload = Array.isArray(data) ? data[0] : data;
  const adsError = payload?.error?.details?.[0]?.errors?.[0];
  const authorizationError = adsError?.errorCode?.authorizationError;
  const googleAdsError = adsError?.message;

  const detail =
    googleAdsError ??
    payload?.error?.message ??
    (data ? JSON.stringify(data) : rawText);

  if (authorizationError && !String(detail).includes(authorizationError)) {
    return `${authorizationError}: ${detail}`;
  }

  return detail;
};

const normalizeGoogleAdsCustomerId = (customerId: string) =>
  customerId.replace(/-/g, "").replace(/^customers\//, "");

export const isGoogleAdsPermissionDenied = (error: unknown) => {
  const message = error instanceof Error ? error.message : String(error);
  return message.includes("USER_PERMISSION_DENIED");
};

type SearchStreamRow = {
  customer?: {
    id?: string | number;
    descriptiveName?: string;
    manager?: boolean;
  };
  conversionAction?: {
    id?: string | number;
    resourceName?: string;
    name?: string;
  };
  customerClient?: {
    id?: string | number;
    resourceName?: string;
    descriptiveName?: string;
    manager?: boolean;
  };
};

const searchStream = async ({
  customerId,
  query,
  ...options
}: GoogleAdsRequestOptions & {
  customerId: string;
  query: string;
}) => {
  const normalizedCustomerId = normalizeGoogleAdsCustomerId(customerId);

  const response = await googleAdsFetch<
    { results?: SearchStreamRow[] }[] | { results?: SearchStreamRow[] }
  >({
    ...options,
    path: `customers/${normalizedCustomerId}/googleAds:searchStream`,
    method: "POST",
    body: { query },
  });

  const batches = Array.isArray(response) ? response : [response];
  return batches.flatMap((batch) => batch.results ?? []);
};

export class GoogleAdsApi {
  constructor(
    private options: GoogleAdsRequestOptions & {
      customerId?: string | null;
    },
  ) {}

  // Lists accounts the OAuth user can access, then hydrates each with name/manager
  // via searchStream. Client accounts under an MCC often need login-customer-id.
  async listAccessibleCustomers() {
    const response = await googleAdsFetch<{
      resourceNames?: string[];
    }>({
      ...this.options,
      path: "customers:listAccessibleCustomers",
    });

    const resourceNames = response.resourceNames ?? [];
    const customersById = new Map<
      string,
      z.infer<typeof googleAdsCustomerSchema>
    >();

    const toCustomer = ({
      id,
      resourceName,
      descriptiveName,
      manager,
      loginCustomerId,
    }: {
      id: string;
      resourceName?: string;
      descriptiveName?: string;
      manager?: boolean;
      loginCustomerId?: string | null;
    }) => {
      const normalizedId = normalizeGoogleAdsCustomerId(id);

      return googleAdsCustomerSchema.parse({
        id: normalizedId,
        resourceName: resourceName ?? `customers/${normalizedId}`,
        descriptiveName: descriptiveName || `Account ${normalizedId}`,
        manager: manager ?? false,
        loginCustomerId: loginCustomerId ?? (manager ? normalizedId : null),
      });
    };

    const setCustomer = (customer: z.infer<typeof googleAdsCustomerSchema>) => {
      const id = normalizeGoogleAdsCustomerId(customer.id);

      if (!customersById.has(id)) {
        customersById.set(id, customer);
      }
    };

    const fetchCustomer = async ({
      resourceName,
      loginCustomerId,
    }: {
      resourceName: string;
      loginCustomerId?: string | null;
    }) => {
      const customerId = normalizeGoogleAdsCustomerId(resourceName);

      const results = await searchStream({
        ...this.options,
        customerId,
        loginCustomerId,
        query:
          "SELECT customer.id, customer.descriptive_name, customer.manager FROM customer LIMIT 1",
      });

      const customer = results[0]?.customer;

      if (!customer) {
        throw new Error(
          `[Google Ads API] No customer data returned for ${customerId}`,
        );
      }

      const id = customer.id?.toString() ?? customerId;

      return toCustomer({
        id,
        resourceName,
        descriptiveName: customer.descriptiveName,
        manager: customer.manager,
        loginCustomerId: loginCustomerId ?? (customer.manager ? id : null),
      });
    };

    const directResults = await Promise.all(
      resourceNames.map(async (resourceName) => {
        try {
          return {
            resourceName,
            customer: await fetchCustomer({ resourceName }),
          };
        } catch (error) {
          if (!isGoogleAdsPermissionDenied(error)) {
            console.error(
              `[Google Ads API] Failed to fetch customer ${normalizeGoogleAdsCustomerId(resourceName)}`,
              error,
            );
          }

          return {
            resourceName,
            customer: null,
          };
        }
      }),
    );

    for (const { customer } of directResults) {
      if (customer) {
        setCustomer(customer);
      }
    }

    // Only directly accessible managers are valid login-customer-id values.
    const managerAccounts = [...customersById.values()].filter(
      (customer) => customer.manager,
    );

    const failedResourceNames = directResults
      .filter((result) => result.customer === null)
      .map((result) => result.resourceName);

    for (const manager of managerAccounts) {
      const remainingResourceNames = failedResourceNames.filter(
        (resourceName) =>
          !customersById.has(normalizeGoogleAdsCustomerId(resourceName)),
      );

      if (remainingResourceNames.length === 0) {
        break;
      }

      await Promise.all(
        remainingResourceNames.map(async (resourceName) => {
          const customerId = normalizeGoogleAdsCustomerId(resourceName);

          try {
            setCustomer(
              await fetchCustomer({
                resourceName,
                loginCustomerId: manager.id,
              }),
            );
          } catch (error) {
            if (!isGoogleAdsPermissionDenied(error)) {
              console.error(
                `[Google Ads API] Failed to fetch customer ${customerId} with login-customer-id ${manager.id}`,
                error,
              );
            }
          }
        }),
      );
    }

    await Promise.all(
      managerAccounts.map(async (manager) => {
        try {
          const results = await searchStream({
            ...this.options,
            customerId: manager.id,
            loginCustomerId: manager.id,
            query:
              "SELECT customer_client.id, customer_client.descriptive_name, customer_client.manager, customer_client.resource_name FROM customer_client WHERE customer_client.status = ENABLED",
          });

          for (const result of results) {
            const client = result.customerClient;

            if (!client?.id) {
              continue;
            }

            const normalizedId = normalizeGoogleAdsCustomerId(
              client.id.toString(),
            );

            if (customersById.has(normalizedId)) {
              continue;
            }

            setCustomer(
              toCustomer({
                id: normalizedId,
                resourceName: `customers/${normalizedId}`,
                descriptiveName: client.descriptiveName,
                manager: client.manager,
                loginCustomerId: manager.id,
              }),
            );
          }
        } catch (error) {
          console.error(
            `[Google Ads API] Failed to list client accounts for manager ${manager.id}`,
            error,
          );
        }
      }),
    );

    return [...customersById.values()];
  }

  async listUploadClickConversionActions(customerId: string) {
    const results = await searchStream({
      ...this.options,
      customerId,
      query:
        "SELECT conversion_action.id, conversion_action.name, conversion_action.resource_name FROM conversion_action WHERE conversion_action.type = UPLOAD_CLICKS AND conversion_action.status = ENABLED",
    });

    const conversionActions = results
      .map((result) => result.conversionAction)
      .filter(
        (
          conversionAction,
        ): conversionAction is NonNullable<typeof conversionAction> =>
          conversionAction != null,
      );

    return conversionActions.map((conversionAction) =>
      googleAdsConversionActionSchema.parse({
        id: conversionAction.id!.toString(),
        resourceName: conversionAction.resourceName!,
        name: conversionAction.name!,
      }),
    );
  }

  // Uploads an offline click conversion via the Data Manager API.
  // New integrations cannot use ConversionUploadService.UploadClickConversions.
  async uploadClickConversion({
    customerId,
    conversionAction,
    googleClickId,
    conversionDateTime,
    conversionValue,
    currencyCode,
    conversionCount,
    eventId,
  }: UploadClickConversionParams) {
    const normalizedCustomerId = customerId.replace(/-/g, "");
    const conversionActionId = conversionAction.includes("/")
      ? conversionAction.split("/").pop()!
      : conversionAction;

    const destination: Record<string, unknown> = {
      operatingAccount: {
        accountType: "GOOGLE_ADS",
        accountId: normalizedCustomerId,
      },
      productDestinationId: conversionActionId,
    };

    if (this.options.loginCustomerId) {
      destination.loginAccount = {
        accountType: "GOOGLE_ADS",
        accountId: this.options.loginCustomerId.replace(/-/g, ""),
      };
    }

    const event: Record<string, unknown> = {
      eventTimestamp: formatGoogleAdsEventTimestamp(conversionDateTime),
      transactionId: eventId,
      eventSource: "WEB",
      adIdentifiers: googleClickId,
      consent: {
        adUserData: "CONSENT_GRANTED",
      },
    };

    if (conversionValue !== undefined) {
      event.conversionValue = conversionValue;
    }

    if (currencyCode) {
      event.currency = currencyCode.toUpperCase();
    }

    if (conversionCount !== undefined) {
      event.conversionCount = conversionCount;
    }

    return dataManagerFetch<{ requestId: string }>({
      accessToken: this.options.accessToken,
      path: "events:ingest",
      body: {
        destinations: [destination],
        events: [event],
      },
    });
  }
}

// Resolves the login-customer-id header for a selected account.
// Prefers the manager that actually granted access; does not guess a sole MCC
// because that 403s when the client isn't under that manager.
export const inferLoginCustomerId = ({
  customers,
  selectedCustomerId,
}: {
  customers: {
    id: string;
    manager: boolean;
    loginCustomerId?: string | null;
  }[];
  selectedCustomerId: string;
}) => {
  const normalizedSelectedId = selectedCustomerId.replace(/-/g, "");
  const selectedCustomer = customers.find(
    (customer) => customer.id.replace(/-/g, "") === normalizedSelectedId,
  );

  if (!selectedCustomer) {
    return null;
  }

  if (selectedCustomer.loginCustomerId) {
    return selectedCustomer.loginCustomerId.replace(/-/g, "");
  }

  if (selectedCustomer.manager) {
    return normalizedSelectedId;
  }

  return null;
};

// login-customer-id candidates to try when the stored/inferred value 403s.
export const getLoginCustomerIdCandidates = ({
  customers,
  selectedCustomerId,
  loginCustomerId,
}: {
  customers: {
    id: string;
    manager: boolean;
    loginCustomerId?: string | null;
  }[];
  selectedCustomerId: string;
  loginCustomerId?: string | null;
}) => {
  const persistedLoginCustomerId = loginCustomerId?.replace(/-/g, "") || null;

  const managerIds = customers
    .filter((customer) => {
      if (!customer.manager) {
        return false;
      }

      const id = customer.id.replace(/-/g, "");
      const customerLoginCustomerId = customer.loginCustomerId?.replace(
        /-/g,
        "",
      );

      // Sub-managers discovered via hierarchy aren't valid login-customer-ids.
      return !customerLoginCustomerId || customerLoginCustomerId === id;
    })
    .map((customer) => customer.id.replace(/-/g, ""));

  const candidates: (string | null)[] = [
    ...(persistedLoginCustomerId ? [persistedLoginCustomerId] : []),
    inferLoginCustomerId({ customers, selectedCustomerId }),
    null,
    ...managerIds,
  ];

  const seen = new Set<string>();
  const unique: (string | null)[] = [];

  for (const candidate of candidates) {
    const key = candidate ?? "";

    if (seen.has(key)) {
      continue;
    }

    seen.add(key);
    unique.push(candidate);
  }

  return unique;
};

// Formats a date as RFC 3339 for Data Manager API event uploads.
const formatGoogleAdsEventTimestamp = (input: string | Date) => {
  const date = typeof input === "string" ? new Date(input) : input;
  return date.toISOString();
};