Skip to content

getaero-io/gtm-eng-skills / skills/deepline-ads-audiences

deepline-ads-audiences

Verified

Use this skill when building, enriching, auditing, or uploading B2B paid ads audiences to Google Customer Match, Meta/Facebook Custom Audiences, or LinkedIn Matched Audiences. Triggers on phrases like '/deepline-ads-audience', '/deepline-ads-audiences', 'upload this audience', 'create custom audiences', 'personal email hashes', 'increase Facebook match rate', 'Google ads audience', 'Meta audience', 'FB audience', or any workflow that turns CRM/customer/contact data into paid ads upload lists. Skip for outbound prospecting sequences, cold email, or pure campaign copywriting.

plays/evaluate-personal-email-provider.play.ts

View on GitHub
import deepline from 'deepline';
import { normalizeEmail, sha256Hex } from './shared/audience-hash';

type SourceRow = {
  contact_id: string;
  first_name?: string;
  last_name?: string;
  full_name?: string;
  linkedin_url?: string;
  work_email?: string;
  account_name?: string;
  domain?: string;
  title?: string;
  lead_score?: string;
};

type ProviderName =
  | 'leadmagic_personal_email_finder'
  | 'crustdata_v3_person_enrich'
  | 'contactout_enrich_person'
  | 'datagma_full_enrichment'
  | 'enformion_person_search'
  | 'fullenrich_bulk_enrich'
  | 'limadata_find_personal_email'
  | 'lusha_enrich_person'
  | 'wiza_reveal_person';

type EvaluatedRow = SourceRow & {
  provider: ProviderName;
  validated_personal_email_hashes_sha256: string;
  validated_hash_count: number;
  candidate_email_count: number;
  accepted: boolean;
  rejection_reason?: string;
};

function asRecord(value: unknown): Record<string, unknown> {
  return value && typeof value === 'object'
    ? (value as Record<string, unknown>)
    : {};
}

function providerData(result: unknown): Record<string, unknown> {
  const response = asRecord(asRecord(result).toolResponse);
  if (!Object.prototype.hasOwnProperty.call(response, 'rawV2')) {
    throw new Error(
      'Tool response has no rawV2; upgrade the SDK and rebundle this Play.',
    );
  }
  const canonical = asRecord(response.rawV2);
  return response.view === 'data' ? asRecord(canonical.data) : canonical;
}

function stringValue(value: unknown): string | null {
  return typeof value === 'string' && value.trim() ? value.trim() : null;
}

function arrayValue(value: unknown): unknown[] {
  return Array.isArray(value) ? value : [];
}

function objectValue(value: unknown): Record<string, unknown> {
  return value && typeof value === 'object' && !Array.isArray(value)
    ? (value as Record<string, unknown>)
    : {};
}

function hashEmails(emails: string[]): string[] {
  return [...new Set(emails.map((email) => sha256Hex(email)))];
}

function emailsFromCandidates(candidates: unknown[]): string[] {
  return [
    ...new Set(
      candidates
        .map((value) => normalizeEmail(stringValue(value)))
        .filter((email): email is string => Boolean(email)),
    ),
  ];
}

function collectValuesByKey(value: unknown, keyMatcher: RegExp): unknown[] {
  if (Array.isArray(value)) {
    return value.flatMap((item) => collectValuesByKey(item, keyMatcher));
  }
  if (!value || typeof value !== 'object') return [];
  const output: unknown[] = [];
  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
    if (keyMatcher.test(key)) output.push(child);
    output.push(...collectValuesByKey(child, keyMatcher));
  }
  return output;
}

function flattenValues(values: unknown[]): unknown[] {
  const output: unknown[] = [];
  for (const value of values) {
    if (Array.isArray(value)) output.push(...flattenValues(value));
    else output.push(value);
  }
  return output;
}

function leadmagicEmails(result: unknown): string[] {
  const data = providerData(result);
  return emailsFromCandidates([
    data.personal_email,
    data.first_personal_email,
    ...arrayValue(data.personal_emails),
  ]);
}

function crustdataPersonalEmails(result: unknown): string[] {
  const data = providerData(result);
  const candidates = flattenValues(
    collectValuesByKey(data, /personal.*email|email.*personal/i),
  );
  return emailsFromCandidates(
    candidates.flatMap((candidate) => [
      candidate,
      objectValue(candidate).email,
    ]),
  );
}

function contactoutPersonalEmails(result: unknown): string[] {
  const data = providerData(result);
  return emailsFromCandidates([
    data.personal_email,
    ...arrayValue(data.personal_email),
  ]);
}

function datagmaPersonalEmails(result: unknown): string[] {
  const data = providerData(result);
  return emailsFromCandidates(
    flattenValues(collectValuesByKey(data, /personal.*email|email.*personal/i)),
  );
}

function enformionPersonalEmails(result: unknown): string[] {
  const data = providerData(result);
  const candidates: unknown[] = [];
  for (const person of arrayValue(data.persons)) {
    for (const email of arrayValue(objectValue(person).emailAddresses)) {
      const row = objectValue(email);
      if (row.nonBusiness === 1 || row.nonBusiness === true) {
        candidates.push(row.emailAddress);
      }
    }
  }
  return emailsFromCandidates(candidates);
}

function fullenrichPersonalEmails(result: unknown): string[] {
  const data = providerData(result);
  return emailsFromCandidates(
    flattenValues(collectValuesByKey(data, /personal.*email/i)),
  );
}

function lushaPersonalEmails(result: unknown): string[] {
  const data = providerData(result);
  const output: string[] = [];
  for (const item of [
    ...arrayValue(data.emails),
    ...arrayValue(data.emailAddresses),
  ]) {
    const row = asRecord(item);
    const type = String(row.type ?? row.emailType ?? '').toLowerCase();
    const email = normalizeEmail(stringValue(row.email));
    if (email && /personal|private|home/.test(type)) output.push(email);
  }
  return [...new Set(output)];
}

function wizaPersonalEmails(result: unknown): string[] {
  const data = providerData(result);
  return emailsFromCandidates([
    data.personal_email,
    data.personal_email1,
    data.personal_email2,
    data.personal_email3,
    ...arrayValue(data.personal_emails),
  ]);
}

function providerInput(
  provider: ProviderName,
  row: SourceRow,
): Record<string, unknown> {
  if (provider === 'leadmagic_personal_email_finder') {
    return { profile_url: row.linkedin_url };
  }
  if (provider === 'crustdata_v3_person_enrich') {
    return {
      professional_network_profile_urls: [row.linkedin_url],
      fields: ['contact.personal_emails'],
    };
  }
  if (provider === 'contactout_enrich_person') {
    return {
      linkedin_url: row.linkedin_url,
      include: ['personal_email'],
    };
  }
  if (provider === 'datagma_full_enrichment') {
    return {
      data: row.linkedin_url || row.work_email,
      fullName:
        row.full_name ||
        [row.first_name, row.last_name].filter(Boolean).join(' '),
      company: row.account_name || row.domain,
      phoneFull: false,
    };
  }
  if (provider === 'enformion_person_search') {
    return {
      first_name: row.first_name,
      last_name: row.last_name,
    };
  }
  if (provider === 'fullenrich_bulk_enrich') {
    return {
      name: `ads-audience-personal-email-${row.contact_id}`,
      wait_for_completion: true,
      max_wait_ms: 120000,
      data: [
        {
          first_name: row.first_name,
          last_name: row.last_name,
          domain: row.domain,
          company_name: row.account_name,
          linkedin_url: row.linkedin_url,
          enrich_fields: ['contact.personal_emails'],
          custom: { contact_id: row.contact_id },
        },
      ],
    };
  }
  if (provider === 'limadata_find_personal_email') {
    return {
      linkedin_url: row.linkedin_url,
      work_email: row.work_email,
    };
  }
  if (provider === 'lusha_enrich_person') {
    return {
      linkedin_url: row.linkedin_url,
      first_name: row.first_name,
      last_name: row.last_name,
      company_name: row.account_name,
      company_domain: row.domain,
      reveal_emails: true,
      reveal_phones: false,
    };
  }
  return {
    linkedin_url: row.linkedin_url,
    full_name:
      row.full_name ||
      [row.first_name, row.last_name].filter(Boolean).join(' '),
    company_name: row.account_name,
    company_domain: row.domain,
    enrichment_level: 'partial',
  };
}

function providerDescription(provider: ProviderName): string {
  return `Evaluate ${provider} personal emails for one remaining ads-audience miss.`;
}

function extractEmails(provider: ProviderName, result: unknown): string[] {
  if (provider === 'leadmagic_personal_email_finder') {
    return leadmagicEmails(result);
  }
  if (provider === 'crustdata_v3_person_enrich') {
    return crustdataPersonalEmails(result);
  }
  if (provider === 'contactout_enrich_person') {
    return contactoutPersonalEmails(result);
  }
  if (provider === 'datagma_full_enrichment') {
    return datagmaPersonalEmails(result);
  }
  if (provider === 'enformion_person_search') {
    return enformionPersonalEmails(result);
  }
  if (provider === 'fullenrich_bulk_enrich') {
    return fullenrichPersonalEmails(result);
  }
  if (provider === 'limadata_find_personal_email') {
    return emailsFromCandidates(arrayValue(providerData(result).emails));
  }
  if (provider === 'lusha_enrich_person') {
    return lushaPersonalEmails(result);
  }
  return wizaPersonalEmails(result);
}

export const config = {
  compatibility: { authoringContract: 'explicit-freshness' },
  name: 'ads-audience-provider-eval',
  description:
    'Compare personal-email providers on the same contact sample, reporting hit rate, unique hashes added, and Deepline spend.',
};

export default async function (input: {
  file: string;
  provider: ProviderName;
  limit?: number;
}) {
  const rows = (await deepline.csv<SourceRow>(input.file))
    .filter((row) => Boolean(row.contact_id && row.linkedin_url))
    .slice(0, Math.max(1, Math.min(input.limit ?? 25, 500)));
  const rowCount = await rows.count();

  const evaluated = await deepline
    .dataset('eval_rows', rows)
    .withColumn('provider_result', (row) => {
      if (input.provider === 'leadmagic_personal_email_finder') {
        return deepline.tools.execute({
          staleAfterSeconds: 0,
          id: 'leadmagic_personal_email_finder',
          tool: 'leadmagic_personal_email_finder',
          input: providerInput(input.provider, row) as never,
          description: providerDescription(input.provider),
        }) as Promise<unknown>;
      }
      if (input.provider === 'crustdata_v3_person_enrich') {
        return deepline.tools.execute({
          staleAfterSeconds: 0,
          id: 'crustdata_v3_person_enrich',
          tool: 'crustdata_v3_person_enrich',
          input: providerInput(input.provider, row) as never,
          description: providerDescription(input.provider),
        }) as Promise<unknown>;
      }
      if (input.provider === 'contactout_enrich_person') {
        return deepline.tools.execute({
          staleAfterSeconds: 0,
          id: 'contactout_enrich_person',
          tool: 'contactout_enrich_person',
          input: providerInput(input.provider, row) as never,
          description: providerDescription(input.provider),
        }) as Promise<unknown>;
      }
      if (input.provider === 'datagma_full_enrichment') {
        return deepline.tools.execute({
          staleAfterSeconds: 0,
          id: 'datagma_full_enrichment',
          tool: 'datagma_full_enrichment',
          input: providerInput(input.provider, row) as never,
          description: providerDescription(input.provider),
        }) as Promise<unknown>;
      }
      if (input.provider === 'enformion_person_search') {
        return deepline.tools.execute({
          staleAfterSeconds: 0,
          id: 'enformion_person_search',
          tool: 'enformion_person_search',
          input: providerInput(input.provider, row) as never,
          description: providerDescription(input.provider),
        }) as Promise<unknown>;
      }
      if (input.provider === 'fullenrich_bulk_enrich') {
        return deepline.tools.execute({
          staleAfterSeconds: 0,
          id: 'fullenrich_bulk_enrich',
          tool: 'fullenrich_bulk_enrich',
          input: providerInput(input.provider, row) as never,
          description: providerDescription(input.provider),
        }) as Promise<unknown>;
      }
      if (input.provider === 'limadata_find_personal_email') {
        return deepline.tools.execute({
          staleAfterSeconds: 0,
          id: 'limadata_find_personal_email',
          tool: 'limadata_find_personal_email',
          input: providerInput(input.provider, row) as never,
          description: providerDescription(input.provider),
        }) as Promise<unknown>;
      }
      if (input.provider === 'lusha_enrich_person') {
        return deepline.tools.execute({
          staleAfterSeconds: 0,
          id: 'lusha_enrich_person',
          tool: 'lusha_enrich_person',
          input: providerInput(input.provider, row) as never,
          description: providerDescription(input.provider),
        }) as Promise<unknown>;
      }
      return deepline.tools.execute({
        staleAfterSeconds: 0,
        id: 'wiza_reveal_person',
        tool: 'wiza_reveal_person',
        input: providerInput(input.provider, row) as never,
        description: providerDescription(input.provider),
      }) as Promise<unknown>;
    })
    .withColumn('evaluated', (row) => {
      const emails = extractEmails(input.provider, row.provider_result);
      const hashes = hashEmails(emails);
      return {
        ...row,
        provider: input.provider,
        validated_personal_email_hashes_sha256: hashes.join(';'),
        validated_hash_count: hashes.length,
        candidate_email_count: emails.length,
        accepted: hashes.length > 0,
        rejection_reason: hashes.length ? undefined : 'no_valid_personal_email',
      } satisfies EvaluatedRow;
    })
    .run({
      key: 'contact_id',
      description:
        'Evaluate one personal-email provider on remaining paid-audience misses.',
    });

  const outputRows = (await evaluated.materialize(500)) as Array<{
    evaluated?: EvaluatedRow;
  }>;
  const rowsOut = outputRows
    .map((row) => row.evaluated)
    .filter((row): row is EvaluatedRow => Boolean(row));
  const hitRows = rowsOut.filter((row) => row.accepted);
  const hashes = new Set(
    hitRows.flatMap((row) =>
      row.validated_personal_email_hashes_sha256.split(';').filter(Boolean),
    ),
  );

  return {
    provider: input.provider,
    attempted_rows: rowCount,
    validated_contacts: hitRows.length,
    validated_hashes: hashes.size,
    hit_rate_pct: rowCount === 0 ? 0 : (hitRows.length * 100) / rowCount,
    evaluated_rows: evaluated,
  };
}
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 196kUpdated Claude CodeCodexVerifiedInstall