getaero-io/gtm-eng-skills / skills/deepline-ads-audiences
deepline-ads-audiences
VerifiedUse 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 37.6 KB |
| plays/audit-no-double-hash.play.ts | script | 3.1 KB |
| plays/build-contactout-hash-pool.play.ts | script | 9.7 KB |
| plays/build-hash-only-audience.play.ts | script | 7.0 KB |
| plays/enrich-audience-waterfall.play.ts | script | 16.7 KB |
| plays/evaluate-leadmagic-personal-email.play.ts | script | 3.7 KB |
| plays/evaluate-personal-email-provider.play.ts | script | 13.8 KB |
| plays/report-google-coverage-lift.play.ts | script | 8.6 KB |
| plays/shared/audience-hash.ts | script | 10.8 KB |
| plays/upload-facebook-google-hash-only-audience.play.ts | script | 5.4 KB |
| plays/upload-google-hash-only-audience.play.ts | script | 3.3 KB |
| recipes/enrich-and-upload-facebook-google.md | markdown | 6.9 KB |
| recipes/max-coverage-audience.md | markdown | 11.3 KB |
| recipes/sample-abm-segment-example.md | markdown | 4.9 KB |
| shared/audience-basics.md | markdown | 4.5 KB |
| shared/contactout-hash-pool.md | markdown | 7.9 KB |
| shared/meta-connection.md | markdown | 3.7 KB |
| shared/upload-failure-modes.md | markdown | 9.3 KB |
| skill-metadata.json | config | 3.3 KB |
plays/shared/audience-hash.ts
View on GitHubexport type HashAudit = {
inputRows: number;
outputRows: number;
malformedHashes: number;
duplicateHashes: number;
rawEmailFieldsPresent: boolean;
};
export type HashOnlyUploadRow = {
email_sha256: string;
};
type HashInputRow = {
email_sha256?: unknown;
email?: unknown;
};
const SHA256_K = [
0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1,
0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147,
0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
];
declare const TextEncoder: {
new (): { encode(value: string): ArrayLike<number> };
};
function rightRotate(value: number, shift: number): number {
return (value >>> shift) | (value << (32 - shift));
}
function utf8Bytes(value: string): number[] {
return Array.from(new TextEncoder().encode(value));
}
export function sha256Hex(value: string): string {
const bytes = utf8Bytes(value);
const bitLength = bytes.length * 8;
bytes.push(0x80);
while (bytes.length % 64 !== 56) bytes.push(0);
for (let shift = 56; shift >= 0; shift -= 8) {
bytes.push(Math.floor(bitLength / 2 ** shift) & 0xff);
}
let h0 = 0x6a09e667;
let h1 = 0xbb67ae85;
let h2 = 0x3c6ef372;
let h3 = 0xa54ff53a;
let h4 = 0x510e527f;
let h5 = 0x9b05688c;
let h6 = 0x1f83d9ab;
let h7 = 0x5be0cd19;
for (let offset = 0; offset < bytes.length; offset += 64) {
const words = Array.from({ length: 64 }, () => 0);
for (let index = 0; index < 16; index += 1) {
const i = offset + index * 4;
words[index] =
((bytes[i] ?? 0) << 24) |
((bytes[i + 1] ?? 0) << 16) |
((bytes[i + 2] ?? 0) << 8) |
(bytes[i + 3] ?? 0);
}
for (let index = 16; index < 64; index += 1) {
const s0 =
rightRotate(words[index - 15]!, 7) ^
rightRotate(words[index - 15]!, 18) ^
(words[index - 15]! >>> 3);
const s1 =
rightRotate(words[index - 2]!, 17) ^
rightRotate(words[index - 2]!, 19) ^
(words[index - 2]! >>> 10);
words[index] = (words[index - 16]! + s0 + words[index - 7]! + s1) >>> 0;
}
let a = h0;
let b = h1;
let c = h2;
let d = h3;
let e = h4;
let f = h5;
let g = h6;
let h = h7;
for (let index = 0; index < 64; index += 1) {
const s1 = rightRotate(e, 6) ^ rightRotate(e, 11) ^ rightRotate(e, 25);
const ch = (e & f) ^ (~e & g);
const temp1 = (h + s1 + ch + SHA256_K[index]! + words[index]!) >>> 0;
const s0 = rightRotate(a, 2) ^ rightRotate(a, 13) ^ rightRotate(a, 22);
const maj = (a & b) ^ (a & c) ^ (b & c);
const temp2 = (s0 + maj) >>> 0;
h = g;
g = f;
f = e;
e = (d + temp1) >>> 0;
d = c;
c = b;
b = a;
a = (temp1 + temp2) >>> 0;
}
h0 = (h0 + a) >>> 0;
h1 = (h1 + b) >>> 0;
h2 = (h2 + c) >>> 0;
h3 = (h3 + d) >>> 0;
h4 = (h4 + e) >>> 0;
h5 = (h5 + f) >>> 0;
h6 = (h6 + g) >>> 0;
h7 = (h7 + h) >>> 0;
}
return [h0, h1, h2, h3, h4, h5, h6, h7].map(wordHex).join('');
}
function wordHex(value: number): string {
const alphabet = '0123456789abcdef';
let output = '';
for (let shift = 28; shift >= 0; shift -= 4) {
output += alphabet[(value >>> shift) & 0xf];
}
return output;
}
/**
* Literal normalization every platform agrees on: trim, drop internal
* whitespace, lowercase. This is what the person typed, minus noise.
*/
export function normalizeEmail(value: unknown): string | null {
if (typeof value !== 'string') return null;
const normalized = value.replace(/\s+/g, '').toLowerCase();
if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(normalized)) return null;
return normalized;
}
/**
* Google Customer Match canonical form: for gmail.com and googlemail.com the
* dots and the +tag in the local part are removed before hashing. Google
* matches on this form, so a dotted Gmail address hashed literally never
* matches on Google. Other domains are left exactly as typed.
*/
export function googleCanonicalEmail(value: unknown): string | null {
const normalized = normalizeEmail(value);
if (!normalized) return null;
const at = normalized.lastIndexOf('@');
const local = normalized.slice(0, at);
const domain = normalized.slice(at + 1);
if (domain !== 'gmail.com' && domain !== 'googlemail.com') return normalized;
const canonicalLocal = local.split('+')[0]!.replace(/\./g, '');
return canonicalLocal ? `${canonicalLocal}@${domain}` : null;
}
/**
* Every SHA-256 an upload needs for one raw email: the Google canonical form
* first, then the literal form when it differs (Meta matches the literal). A
* non-Gmail address yields one hash. Each hash is computed exactly once.
*/
export function emailHashes(value: unknown): string[] {
const literal = normalizeEmail(value);
if (!literal) return [];
const canonical = googleCanonicalEmail(literal) ?? literal;
const hashes = [sha256Hex(canonical)];
if (canonical !== literal) hashes.push(sha256Hex(literal));
return hashes;
}
/** Digits only, country code included, 10 to 15 digits (E.164 length). */
export function normalizePhoneDigits(value: unknown): string | null {
if (typeof value !== 'string' && typeof value !== 'number') return null;
const digits = String(value).replace(/\D/g, '').replace(/^0+/, '');
if (digits.length < 10 || digits.length > 15) return null;
return digits;
}
/**
* The two platforms hash different strings for the same number. Google hashes
* E.164 with the leading plus; Meta hashes the digits with no plus (its
* published example: 15559876543 ->
* 1ef970831d7963307784fa8688e8fce101a15685d62aa765fed23f3a2c576a4e). One
* digest cannot serve both, so a shared file carries one column per platform.
*/
export function phoneHashes(
value: unknown,
): { digits: string; google: string; meta: string } | null {
const digits = normalizePhoneDigits(value);
if (!digits) return null;
return { digits, google: sha256Hex(`+${digits}`), meta: sha256Hex(digits) };
}
/** Google and Meta name rule: trim, lowercase; prefixes and suffixes are the caller's job. */
export function normalizeName(value: unknown): string | null {
if (typeof value !== 'string') return null;
const normalized = value.trim().toLowerCase().replace(/\s+/g, ' ');
return normalized || null;
}
export type UploadColumnAudit = {
column: string;
populated: number;
hashed: number;
plain: number;
};
export type UploadFileAudit = {
rows: number;
columns: UploadColumnAudit[];
mixedColumns: string[];
plainIdentifierColumns: string[];
hashOfHashPairs: number;
incompleteAddressRows: number;
ok: boolean;
};
const HASHED_COLUMNS = new Set([
'email',
'email_sha256',
'phone',
'phone_sha256',
'phone_google',
'phone_google_sha256',
'phone_meta',
'phone_meta_sha256',
'fn',
'ln',
'first_name_sha256',
'last_name_sha256',
]);
const ADDRESS_COLUMNS: Array<[string, string[]]> = [
['fn', ['fn', 'first_name_sha256']],
['ln', ['ln', 'last_name_sha256']],
['country', ['country', 'country_code']],
['zip', ['zip', 'postal_code']],
];
/**
* Gate a platform upload file before it leaves Deepline. Three failures upload
* cleanly and match nothing: a column mixing raw values and digests (the
* platform re-hashes the digests), a plain-text name beside a hashed email
* (Google rejects the file; a re-hash step then risks hashing the email
* column twice), and a name block without Zip (Google ignores names unless
* first name, last name, country and zip are all present).
*/
export function auditUploadFile(
rows: Array<Record<string, unknown>>,
): UploadFileAudit {
const columnNames = new Set<string>();
rows.forEach((row) =>
Object.keys(row).forEach((key) => columnNames.add(key)),
);
const columns: UploadColumnAudit[] = [];
const mixedColumns: string[] = [];
const plainIdentifierColumns: string[] = [];
const digests = new Set<string>();
for (const column of columnNames) {
let populated = 0;
let hashed = 0;
for (const row of rows) {
const raw = row[column];
if (typeof raw !== 'string' || !raw.trim()) continue;
populated += 1;
const hash = normalizeSha256(raw);
if (hash) {
hashed += 1;
digests.add(hash);
}
}
const plain = populated - hashed;
columns.push({ column, populated, hashed, plain });
if (hashed > 0 && plain > 0) mixedColumns.push(column);
if (HASHED_COLUMNS.has(column) && plain > 0)
plainIdentifierColumns.push(column);
}
let hashOfHashPairs = 0;
for (const digest of digests) {
if (digests.has(sha256Hex(digest))) hashOfHashPairs += 1;
}
let incompleteAddressRows = 0;
for (const row of rows) {
const present = ADDRESS_COLUMNS.map(([, names]) =>
names.some(
(name) => typeof row[name] === 'string' && (row[name] as string).trim(),
),
);
if (present.some(Boolean) && !present.every(Boolean))
incompleteAddressRows += 1;
}
return {
rows: rows.length,
columns,
mixedColumns,
plainIdentifierColumns,
hashOfHashPairs,
incompleteAddressRows,
ok:
mixedColumns.length === 0 &&
plainIdentifierColumns.length === 0 &&
hashOfHashPairs === 0 &&
incompleteAddressRows === 0,
};
}
export function normalizeSha256(value: unknown): string | null {
if (typeof value !== 'string') return null;
const normalized = value.trim().toLowerCase();
if (!/^[a-f0-9]{64}$/.test(normalized)) return null;
return normalized;
}
export function auditHashRows(rows: HashInputRow[]): HashAudit {
const hashes = rows
.map((row) => normalizeSha256(row.email_sha256))
.filter((hash): hash is string => Boolean(hash));
return {
inputRows: rows.length,
outputRows: hashes.length,
malformedHashes: rows.length - hashes.length,
duplicateHashes: hashes.length - new Set(hashes).size,
rawEmailFieldsPresent: rows.some((row) =>
Object.prototype.hasOwnProperty.call(row, 'email'),
),
};
}
export function prepareHashOnlyUploadRows(rows: HashInputRow[]): {
rows: HashOnlyUploadRow[];
audit: HashAudit;
} {
const audit = auditHashRows(rows);
const output: HashOnlyUploadRow[] = [];
const seen = new Set<string>();
for (const row of rows) {
const hash = normalizeSha256(row.email_sha256);
if (!hash || seen.has(hash)) continue;
seen.add(hash);
output.push({ email_sha256: hash });
}
return { rows: output, audit };
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |