deepline 0.3.463 → 0.3.465

package/dist/cli/chunk-7YDN6AEK.mjs

@@ -0,0 +1,649 @@
+// ../plays/extractor-targets.ts
+var JOB_CHANGE_STATUS_VALUES = [
+  "moved",
+  "no_change",
+  "left_company",
+  "unknown",
+  "profile_unavailable",
+  "no_new_company"
+];
+var JOB_CHANGE_JSON_SCHEMA = {
+  type: "object",
+  required: ["status", "date", "new_company", "new_title"],
+  properties: {
+    status: { type: "string", enum: JOB_CHANGE_STATUS_VALUES },
+    date: { type: ["string", "null"] },
+    new_company: { type: ["string", "null"] },
+    new_title: { type: ["string", "null"] }
+  }
+};
+var PHONE_STATUS_VALUES = ["valid", "invalid", "unknown"];
+var DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS = {
+  id: { identity: true, valueKind: "string" },
+  name: { identity: true, valueKind: "string" },
+  email: { identity: true, valueKind: "string" },
+  personal_email: { identity: true, valueKind: "string" },
+  phone: { identity: true, valueKind: "string" },
+  linkedin: { identity: true, valueKind: "string" },
+  linkedin_url: { identity: true, valueKind: "string" },
+  domain: { identity: true, valueKind: "string" },
+  website: { identity: true, valueKind: "string" },
+  first_name: { identity: true, valueKind: "string" },
+  last_name: { identity: true, valueKind: "string" },
+  full_name: { identity: true, valueKind: "string" },
+  company: { identity: true, valueKind: "string" },
+  company_name: { identity: true, valueKind: "string" },
+  organization_name: { identity: true, valueKind: "string" },
+  company_domain: { identity: true, valueKind: "string" },
+  company_website: { identity: true, valueKind: "string" },
+  company_linkedin_url: { identity: true, valueKind: "string" },
+  title: { identity: false, valueKind: "string" },
+  industry: { identity: false, valueKind: "string" },
+  status: { identity: false, valueKind: "string" },
+  job_change: { identity: false, valueKind: "job_change" },
+  job_change_status: {
+    identity: false,
+    valueKind: "job_change_status",
+    enum: JOB_CHANGE_STATUS_VALUES
+  },
+  email_status: { identity: false, valueKind: "email_status" },
+  phone_status: {
+    identity: false,
+    valueKind: "phone_status",
+    enum: PHONE_STATUS_VALUES
+  }
+};
+var DEEPLINE_EXTRACTOR_TARGETS = Object.keys(
+  DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS
+);
+function isDeeplineExtractorTarget(value2) {
+  return value2 in DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS;
+}
+
+// ../plays/email-status.ts
+var nullable = (type) => ({ type: [type, "null"] });
+var oneOf = (values) => ({ type: "string", enum: values });
+var EMAIL_STATUS_JSON_SCHEMA = {
+  type: "object",
+  required: [
+    "verdict",
+    "status",
+    "verified",
+    "confidence",
+    "reasons",
+    "signals",
+    "provider"
+  ],
+  properties: {
+    verdict: oneOf([
+      "send",
+      "send_with_caution",
+      "verify_next",
+      "hold",
+      "drop"
+    ]),
+    status: oneOf([
+      "valid",
+      "invalid",
+      "catch_all",
+      "valid_catch_all",
+      "unknown",
+      "do_not_mail",
+      "spamtrap",
+      "abuse",
+      "disposable"
+    ]),
+    verified: { type: "boolean" },
+    confidence: nullable("number"),
+    reasons: { type: "array", items: { type: "string" } },
+    signals: {
+      type: "object",
+      required: [
+        "catch_all",
+        "deliverability",
+        "mx_class",
+        "mx_provider",
+        "mx_record",
+        "fraud_score",
+        "disposable",
+        "role_based",
+        "free_email",
+        "abuse",
+        "spamtrap",
+        "suspect",
+        "valid"
+      ],
+      properties: {
+        catch_all: nullable("boolean"),
+        deliverability: oneOf([
+          "high",
+          "medium",
+          "low",
+          "unknown"
+        ]),
+        mx_class: oneOf([
+          "consumer_mailbox",
+          "workspace_mailbox",
+          "security_gateway",
+          "on_prem",
+          "unknown"
+        ]),
+        mx_provider: nullable("string"),
+        mx_record: nullable("string"),
+        fraud_score: nullable("number"),
+        disposable: nullable("boolean"),
+        role_based: nullable("boolean"),
+        free_email: nullable("boolean"),
+        abuse: nullable("boolean"),
+        spamtrap: nullable("boolean"),
+        suspect: nullable("boolean"),
+        valid: nullable("boolean")
+      }
+    },
+    provider: {
+      type: "object",
+      required: ["name", "raw_status", "raw_score"],
+      properties: {
+        name: { type: "string" },
+        raw_status: { type: ["string", "boolean", "number", "null"] },
+        raw_score: nullable("number")
+      }
+    }
+  }
+};
+function normalizeKey(value2) {
+  if (value2 == null) return null;
+  if (typeof value2 === "boolean") return String(value2);
+  const normalized = String(value2).trim().toLowerCase().replace(/\s+/g, "_");
+  return normalized || null;
+}
+function boolish(value2) {
+  if (typeof value2 === "boolean") return value2;
+  if (typeof value2 === "number")
+    return value2 === 1 ? true : value2 === 0 ? false : null;
+  if (typeof value2 !== "string") return null;
+  const normalized = value2.trim().toLowerCase();
+  if (["true", "yes", "y", "1"].includes(normalized)) return true;
+  if (["false", "no", "n", "0"].includes(normalized)) return false;
+  return null;
+}
+function numberish(value2) {
+  if (typeof value2 === "number" && Number.isFinite(value2)) return value2;
+  if (typeof value2 !== "string" || value2.trim() === "") return null;
+  const parsed = Number(value2);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function stringish(value2) {
+  return typeof value2 === "string" && value2.trim() ? value2.trim() : null;
+}
+function deliverability(value2) {
+  const normalized = normalizeKey(value2);
+  return normalized === "high" || normalized === "medium" || normalized === "low" ? normalized : "unknown";
+}
+function mxClass(mxProvider, mxRecord) {
+  const haystack = `${stringish(mxProvider) ?? ""} ${stringish(mxRecord) ?? ""}`.toLowerCase();
+  if (!haystack.trim()) return "unknown";
+  if (/proofpoint|pphosted|mimecast|barracuda|ess\.barracudanetworks|ironport|cisco|iphmx|messagelabs|symantec/.test(
+    haystack
+  )) {
+    return "security_gateway";
+  }
+  if (/aspmx\.l\.google|google|g-suite|google workspace/.test(haystack)) {
+    return "workspace_mailbox";
+  }
+  if (/protection\.outlook|office365|microsoft|outlook|exchange online/.test(
+    haystack
+  )) {
+    return "workspace_mailbox";
+  }
+  if (/gmail|yahoo|icloud|aol|hotmail/.test(haystack))
+    return "consumer_mailbox";
+  if (/postfix|exim|sendmail|zimbra|plesk|cpanel|mail\./.test(haystack))
+    return "on_prem";
+  return "unknown";
+}
+function entryForStatus(key, map) {
+  if (!key) return null;
+  return map?.[key] ?? null;
+}
+function read(values, name) {
+  return values[name];
+}
+function matchesRule(rule, values) {
+  return Object.entries(rule.when).every(([key, expected]) => {
+    const actual = read(values, key);
+    if (key.endsWith("Lt")) {
+      const source = numberish(read(values, key.slice(0, -2)));
+      return typeof expected === "number" && source != null && source < expected;
+    }
+    if (typeof expected === "boolean") return boolish(actual) === expected;
+    if (typeof expected === "number") return numberish(actual) === expected;
+    return normalizeKey(actual) === normalizeKey(expected);
+  });
+}
+function buildEmailStatus({
+  config,
+  values
+}) {
+  const rawStatus = read(values, "rawStatus");
+  const rawScore = numberish(read(values, "rawScore"));
+  const valid = boolish(read(values, "valid"));
+  const catchAll = boolish(read(values, "catchAll"));
+  const disposable = boolish(read(values, "disposable"));
+  const abuse = boolish(read(values, "abuse"));
+  const spamtrap = boolish(read(values, "spamtrap"));
+  const suspect = boolish(read(values, "suspect"));
+  const rawKey = normalizeKey(rawStatus);
+  const mapped = config.rules?.find((rule) => matchesRule(rule, values)) ?? entryForStatus(rawKey, config.statusMap) ?? entryForStatus(valid == null ? null : String(valid), config.statusMap);
+  const status = mapped?.status ?? (disposable ? "disposable" : abuse ? "abuse" : spamtrap ? "spamtrap" : catchAll ? "catch_all" : valid === true ? "valid" : valid === false ? "invalid" : "unknown");
+  const defaultVerdict = status === "valid" ? "send" : status === "valid_catch_all" ? "send_with_caution" : status === "catch_all" ? "verify_next" : status === "unknown" ? "hold" : "drop";
+  const verdict = mapped?.verdict ?? defaultVerdict;
+  const verified = mapped?.verified ?? (status === "valid" || status === "valid_catch_all" || verdict === "send");
+  const reasons = [
+    mapped?.reason,
+    catchAll ? "catch_all_domain" : null,
+    mxClass(read(values, "mxProvider"), read(values, "mxRecord")) === "security_gateway" ? "security_gateway_mx" : null,
+    suspect ? "provider_marked_suspect" : null
+  ].filter((reason) => typeof reason === "string");
+  return {
+    verdict,
+    status,
+    verified,
+    confidence: rawScore,
+    reasons,
+    signals: {
+      catch_all: catchAll,
+      deliverability: deliverability(read(values, "deliverability")),
+      mx_class: mxClass(read(values, "mxProvider"), read(values, "mxRecord")),
+      mx_provider: stringish(read(values, "mxProvider")),
+      mx_record: stringish(read(values, "mxRecord")),
+      fraud_score: numberish(read(values, "fraudScore")),
+      disposable,
+      role_based: boolish(read(values, "roleBased")),
+      free_email: boolish(read(values, "freeEmail")),
+      abuse,
+      spamtrap,
+      suspect,
+      valid
+    },
+    provider: {
+      name: config.provider,
+      raw_status: typeof rawStatus === "string" || typeof rawStatus === "boolean" || typeof rawStatus === "number" ? rawStatus : null,
+      raw_score: rawScore
+    }
+  };
+}
+
+// ../plays/field-catalog.ts
+var value = (description) => ({ type: "string", description });
+var SOURCE = {
+  type: "string",
+  description: "The provider or step that found it."
+};
+var FIELD_CATALOG = {
+  person: {
+    name: {
+      description: "The person's name. Without a kind, a name in some form.",
+      leaves: { value: value("The name.") },
+      kinds: {
+        full: "Their full name.",
+        first: "Their first (given) name.",
+        last: "Their last (family) name."
+      }
+    },
+    email: {
+      description: "An email address for the person.",
+      leaves: {
+        value: value("The address."),
+        validated: {
+          type: "boolean",
+          description: "Whether the address passed validation."
+        },
+        status: {
+          type: "EmailStatus",
+          description: "The validation verdict and its signals."
+        },
+        source: SOURCE
+      },
+      kinds: {
+        work: "At their employer.",
+        personal: "Their own, not tied to an employer."
+      }
+    },
+    phone: {
+      description: "A phone number for the person.",
+      leaves: {
+        value: value("The number."),
+        validated: {
+          type: "boolean",
+          description: "Whether the number passed validation."
+        },
+        status: {
+          type: '"valid" | "invalid" | "unknown"',
+          description: "The validation verdict."
+        },
+        line_type: value("Mobile, landline, VoIP and so on."),
+        carrier: value("The carrier serving the number."),
+        source: SOURCE
+      },
+      kinds: {
+        mobile: "Their mobile.",
+        work: "A direct line at their employer."
+      }
+    },
+    linkedin: {
+      description: "The person's LinkedIn profile.",
+      leaves: {
+        url: value("The profile URL."),
+        id: value("LinkedIn's id or public identifier for the profile.")
+      }
+    },
+    job: {
+      description: "The person's current role.",
+      groups: {
+        title: {
+          description: "What their role is called. Without a kind, a job title or, failing one, their profile headline.",
+          leaves: { value: value("The title.") },
+          kinds: {
+            exact: "Their job title, never a headline.",
+            headline: "Their profile headline, used as a title."
+          }
+        }
+      },
+      leaves: {
+        change: {
+          type: "JobChange",
+          description: "Whether they changed jobs, and to what."
+        },
+        change_status: {
+          type: "JobChangeStatus",
+          description: "The job-change verdict alone."
+        }
+      }
+    },
+    record: {
+      description: "A provider's own record of the person.",
+      leaves: { id: value("The provider's id for the person.") }
+    }
+  },
+  company: {
+    name: {
+      description: "The company's name.",
+      leaves: { value: value("The name.") },
+      kinds: { legal: "As registered with a government." }
+    },
+    domain: {
+      description: "The company's web domain.",
+      leaves: { value: value("The bare domain, such as example.com.") }
+    },
+    website: {
+      description: "The company's website.",
+      leaves: { url: value("The site URL.") }
+    },
+    linkedin: {
+      description: "The company's LinkedIn page.",
+      leaves: { url: value("The page URL.") }
+    },
+    phone: {
+      description: "A phone number for the company.",
+      leaves: { value: value("The number.") }
+    },
+    industry: {
+      description: "The industry the company is in.",
+      leaves: { value: value("The industry.") }
+    },
+    record: {
+      description: "A provider's own record of the company.",
+      leaves: { id: value("The provider's id for the company.") }
+    }
+  },
+  job: {
+    posting: {
+      description: "A job posting.",
+      groups: {
+        title: {
+          description: "The posting's title. Not a person's job title.",
+          leaves: { value: value("The title.") }
+        }
+      }
+    }
+  },
+  podcast: {
+    name: {
+      description: "A podcast's name.",
+      leaves: { value: value("The name.") }
+    },
+    website: {
+      description: "A podcast's own page.",
+      leaves: { url: value("The URL.") }
+    }
+  },
+  post: {
+    title: {
+      description: "A social or business post's title.",
+      leaves: { value: value("The title.") }
+    },
+    author: {
+      description: "A post's author, who may be a person or a company.",
+      groups: {
+        name: {
+          description: "The author's name.",
+          leaves: { value: value("The name.") }
+        }
+      }
+    }
+  },
+  page: {
+    title: {
+      description: "A web page's title.",
+      leaves: { value: value("The title.") }
+    }
+  },
+  // Some entity's value, when a tool cannot say whether it is a person's or a
+  // company's. Each field here is answered by the same field of either.
+  entity: {
+    name: {
+      description: "A person's or company's name.",
+      leaves: { value: value("The name.") }
+    },
+    email: {
+      description: "An email address for a person or company.",
+      leaves: { value: value("The address.") }
+    },
+    phone: {
+      description: "A phone number for a person or company.",
+      leaves: { value: value("The number.") }
+    },
+    linkedin: {
+      description: "A person's or company's LinkedIn page.",
+      leaves: { url: value("The page URL.") }
+    },
+    record: {
+      description: "A provider's own record of a person or company.",
+      leaves: { id: value("The provider's id for the record.") }
+    }
+  }
+};
+function fieldId(entity, group, kind, leaf) {
+  return [entity, group, kind, leaf === "value" ? void 0 : leaf, "value"].filter(Boolean).join(".");
+}
+function groupFields(entity, group, definition) {
+  const own = [void 0, ...Object.keys(definition.kinds ?? {})].flatMap(
+    (kind) => Object.entries(definition.leaves ?? {}).map(([leaf, described]) => ({
+      ...described,
+      id: fieldId(entity, group, kind, leaf),
+      entity,
+      group,
+      ...kind ? { kind } : {},
+      leaf
+    }))
+  );
+  const nested = Object.entries(definition.groups ?? {}).flatMap(
+    ([name, child]) => groupFields(entity, `${group}.${name}`, child)
+  );
+  return [...own, ...nested];
+}
+function catalogFields() {
+  return Object.entries(FIELD_CATALOG).flatMap(
+    ([entity, groups]) => Object.entries(groups).flatMap(
+      ([group, definition]) => groupFields(entity, group, definition)
+    )
+  );
+}
+var FIELDS_BY_ID = new Map(catalogFields().map((field) => [field.id, field]));
+var PROVIDER_FIELD = /^provider\.[a-z0-9_-]+(\.[a-z0-9_]+)+\.value$/;
+function isFieldId(id) {
+  return FIELDS_BY_ID.has(id) || PROVIDER_FIELD.test(id);
+}
+function generalField(id) {
+  const field = FIELDS_BY_ID.get(id);
+  return field?.kind ? fieldId(field.entity, field.group, void 0, field.leaf) : null;
+}
+function generalFields(id) {
+  const field = FIELDS_BY_ID.get(id);
+  if (!field) return [];
+  const general = generalField(id);
+  const entity = fieldId("entity", field.group, void 0, field.leaf);
+  return [
+    ...general ? [general] : [],
+    ...(field.entity === "person" || field.entity === "company") && FIELDS_BY_ID.has(entity) ? [entity] : []
+  ];
+}
+function fieldSatisfies(offered, wanted) {
+  return offered === wanted || generalFields(offered).includes(wanted);
+}
+var EXTRACTOR_TARGET_FIELDS = {
+  email: ["person.email.value"],
+  personal_email: ["person.email.personal.value"],
+  email_status: ["person.email.status.value"],
+  phone: ["person.phone.value", "company.phone.value"],
+  phone_status: ["person.phone.status.value"],
+  first_name: ["person.name.first.value"],
+  last_name: ["person.name.last.value"],
+  full_name: ["person.name.full.value"],
+  // Also used for a list name, a channel title and a search suggestion.
+  name: ["person.name.value", "company.name.value"],
+  linkedin: [
+    "person.linkedin.url.value",
+    "person.linkedin.id.value",
+    "company.linkedin.url.value"
+  ],
+  linkedin_url: ["person.linkedin.url.value"],
+  title: ["person.job.title.value"],
+  job_change: ["person.job.change.value"],
+  job_change_status: ["person.job.change_status.value"],
+  company: ["company.name.value"],
+  company_name: ["company.name.value"],
+  organization_name: ["company.name.value"],
+  company_domain: ["company.domain.value"],
+  domain: ["company.domain.value"],
+  company_website: ["company.website.url.value"],
+  // Also used for a podcast URL.
+  website: ["company.website.url.value"],
+  company_linkedin_url: ["company.linkedin.url.value"],
+  industry: ["company.industry.value"],
+  id: ["person.record.id.value", "company.record.id.value"],
+  // Used for unrelated provider statuses; none is a catalog field.
+  status: []
+};
+function fieldOfName(name, declared) {
+  const meanings = nameMeanings(name);
+  if (declared === void 0) {
+    return meanings.length === 1 ? meanings[0] : void 0;
+  }
+  return isOtherThing(declared) || meanings.some((meaning) => relatedFields(declared, meaning)) ? declared : void 0;
+}
+function nameMeanings(name) {
+  return EXTRACTOR_TARGET_FIELDS[name] ?? [];
+}
+function relatedFields(a, b) {
+  return fieldSatisfies(a, b) || fieldSatisfies(b, a);
+}
+function isOtherThing(id) {
+  if (PROVIDER_FIELD.test(id)) return true;
+  const entity = FIELDS_BY_ID.get(id)?.entity;
+  return entity !== void 0 && entity !== "person" && entity !== "company" && entity !== "entity";
+}
+function resolveFieldName(name, bindings, outputs = []) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const binding of bindings) {
+    if (!byId.has(binding.id)) byId.set(binding.id, binding);
+  }
+  const fields = [...byId.values()];
+  const pick = (matches) => {
+    if (matches.length > 1) {
+      throw new Error(
+        `"${name}" could be ${matches.map((match) => `${match.id} (${match.name})`).join(" or ")}. Use one of those ids.`
+      );
+    }
+    return matches[0];
+  };
+  const viaId = (id) => byId.get(id) ?? pick(fields.filter((field) => fieldSatisfies(field.id, id)));
+  if (isFieldId(name)) return viaId(name);
+  const own = bindings.find((binding) => binding.name === name);
+  if (own) {
+    return nameMeanings(name).some((id) => relatedFields(own.id, id)) ? byId.get(own.id) : void 0;
+  }
+  if (outputs.includes(name)) return void 0;
+  const found = nameMeanings(name).flatMap((id) => {
+    const binding = viaId(id);
+    return binding ? [binding] : [];
+  });
+  return pick([...new Set(found)]);
+}
+function fieldPaths(bindings, outputs, lists) {
+  const names = /* @__PURE__ */ new Set();
+  for (const binding of bindings) {
+    names.add(binding.id);
+    for (const general of generalFields(binding.id)) names.add(general);
+    names.add(binding.name);
+  }
+  for (const [name, ids] of Object.entries(EXTRACTOR_TARGET_FIELDS)) {
+    if (ids.some(
+      (id) => bindings.some((binding) => fieldSatisfies(binding.id, id))
+    )) {
+      names.add(name);
+    }
+  }
+  const paths = [];
+  for (const name of names) {
+    let output;
+    try {
+      const binding = resolveFieldName(name, bindings, outputs);
+      if (!binding) continue;
+      output = binding.name;
+    } catch {
+      if (!isFieldId(name) || name.startsWith("entity.")) continue;
+      output = null;
+    }
+    if (!isFieldId(name) && lists.includes(name)) continue;
+    const path = isFieldId(name) ? name.split(".") : [name, "value"];
+    paths.push({ path, name, output, list: false });
+  }
+  for (const name of lists) {
+    paths.push({ path: [name, "value"], name, output: name, list: true });
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const { path } of paths) {
+    const key = path.join(".");
+    if (seen.has(key) || paths.some((other) => other.path.join(".").startsWith(`${key}.`))) {
+      throw new Error(`Two outputs land on result.fields.${key}. Rename one.`);
+    }
+    seen.add(key);
+  }
+  return paths;
+}
+
+export {
+  EMAIL_STATUS_JSON_SCHEMA,
+  buildEmailStatus,
+  JOB_CHANGE_STATUS_VALUES,
+  JOB_CHANGE_JSON_SCHEMA,
+  PHONE_STATUS_VALUES,
+  DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS,
+  DEEPLINE_EXTRACTOR_TARGETS,
+  isDeeplineExtractorTarget,
+  fieldOfName,
+  resolveFieldName,
+  fieldPaths
+};