deepline 0.3.372 → 0.3.373

package/dist/bundling-sources/sdk/src/release.ts

@@ -200,7 +200,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.372',
+  version: '0.3.373',
   updateSummary:
     'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {

package/dist/bundling-sources/shared_libs/plays/email-status.ts

@@ -53,6 +53,101 @@ export type EmailStatus = {
   };
 };
 
+const nullable = (type: string) => ({ type: [type, 'null'] });
+const oneOf = (values: readonly string[]) => ({ type: 'string', enum: values });
+
+/** `EmailStatus` as a JSON schema, for describing it where TypeScript types are not at hand. */
+export const 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',
+    ] satisfies EmailStatusVerdict[]),
+    status: oneOf([
+      'valid',
+      'invalid',
+      'catch_all',
+      'valid_catch_all',
+      'unknown',
+      'do_not_mail',
+      'spamtrap',
+      'abuse',
+      'disposable',
+    ] satisfies EmailStatusValue[]),
+    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',
+      ] satisfies Array<keyof EmailStatus['signals']>,
+      properties: {
+        catch_all: nullable('boolean'),
+        deliverability: oneOf([
+          'high',
+          'medium',
+          'low',
+          'unknown',
+        ] satisfies EmailDeliverability[]),
+        mx_class: oneOf([
+          'consumer_mailbox',
+          'workspace_mailbox',
+          'security_gateway',
+          'on_prem',
+          'unknown',
+        ] satisfies EmailMxClass[]),
+        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'] satisfies Array<
+        keyof EmailStatus['provider']
+      >,
+      properties: {
+        name: { type: 'string' },
+        raw_status: { type: ['string', 'boolean', 'number', 'null'] },
+        raw_score: nullable('number'),
+      },
+    },
+  },
+} as const;
+
 export type EmailStatusMapEntry = {
   status: EmailStatusValue;
   verdict?: EmailStatusVerdict;

package/dist/bundling-sources/shared_libs/plays/extractor-targets.ts

@@ -18,6 +18,20 @@ export type JobChangeGetterValue = {
   new_title: string | null;
 };
 
+/** `JobChangeGetterValue` as a JSON schema. */
+export const JOB_CHANGE_JSON_SCHEMA = {
+  type: 'object',
+  required: ['status', 'date', 'new_company', 'new_title'] satisfies Array<
+    keyof JobChangeGetterValue
+  >,
+  properties: {
+    status: { type: 'string', enum: JOB_CHANGE_STATUS_VALUES },
+    date: { type: ['string', 'null'] },
+    new_company: { type: ['string', 'null'] },
+    new_title: { type: ['string', 'null'] },
+  },
+} as const;
+
 export const PHONE_STATUS_VALUES = ['valid', 'invalid', 'unknown'] as const;
 
 export type PhoneStatus = (typeof PHONE_STATUS_VALUES)[number];

package/dist/bundling-sources/shared_libs/plays/field-catalog.ts

@@ -0,0 +1,253 @@
+import type { DeeplineExtractorTarget } from './extractor-targets';
+
+/**
+ * The catalog of things a tool or play can take or return about a person or
+ * a company, named by what they are instead of by what a provider calls them.
+ *
+ * An id is a dotted path that always ends in a leaf:
+ *
+ *   person.email.value            any email for the person
+ *   person.email.work.value       their work email
+ *   person.email.work.validated   whether that work email was validated
+ *
+ * It reads `<entity>.<group>[.<kind>].<leaf>`. A group is one thing about the
+ * entity (an email). A leaf is one fact about that thing (its value, whether
+ * it was validated). A kind narrows which one is meant (work, personal). No
+ * id is both a field and a parent of fields, so `person.email` alone is never
+ * a field; the plain value is `person.email.value`.
+ *
+ * A kind is a narrowing, so a field with a kind also answers for the same
+ * field without it: a tool that returns `person.email.work.value` satisfies a
+ * request for `person.email.value`. A tool that cannot tell which kind it has
+ * declares the id without one.
+ *
+ * This is an addition. Existing short names (`email`, `name`) keep working;
+ * `EXTRACTOR_TARGET_FIELDS` records what each can mean.
+ */
+type Leaf = { type: string; description: string };
+
+type Group = {
+  description: string;
+  leaves: Record<string, Leaf>;
+  /** Narrowings of this group. Each has every leaf the group has. */
+  kinds?: Record<string, string>;
+};
+
+const value = (description: string): Leaf => ({ type: 'string', description });
+
+const SOURCE: Leaf = {
+  type: 'string',
+  description: 'The provider or step that found it.',
+};
+
+export const FIELD_CATALOG = {
+  person: {
+    name: {
+      description: "The person's name.",
+      leaves: {
+        value: value('Full name.'),
+        first: value('First (given) name.'),
+        last: value('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.') },
+    },
+    job: {
+      description: "The person's current role.",
+      leaves: {
+        title: value('Job title.'),
+        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.") },
+    },
+  },
+} as const satisfies Record<string, Record<string, Group>>;
+
+export type FieldEntity = keyof typeof FIELD_CATALOG;
+
+export type CatalogField = Leaf & {
+  id: string;
+  entity: FieldEntity;
+  group: string;
+  kind?: string;
+  leaf: string;
+};
+
+/** Every field in the catalog, with and without each kind. */
+export function catalogFields(): CatalogField[] {
+  return Object.entries(FIELD_CATALOG).flatMap(([entity, groups]) =>
+    Object.entries<Group>(groups).flatMap(([group, definition]) =>
+      [undefined, ...Object.keys(definition.kinds ?? {})].flatMap((kind) =>
+        Object.entries(definition.leaves).map(([leaf, described]) => ({
+          ...described,
+          id: [entity, group, kind, leaf].filter(Boolean).join('.'),
+          entity: entity as FieldEntity,
+          group,
+          ...(kind ? { kind } : {}),
+          leaf,
+        })),
+      ),
+    ),
+  );
+}
+
+const FIELDS_BY_ID = new Map(catalogFields().map((field) => [field.id, field]));
+
+export function catalogField(id: string): CatalogField | undefined {
+  return FIELDS_BY_ID.get(id);
+}
+
+/** The same field without its kind, or null when it has none to drop. */
+export function generalField(id: string): string | null {
+  const field = FIELDS_BY_ID.get(id);
+  return field?.kind ? [field.entity, field.group, field.leaf].join('.') : null;
+}
+
+/** Whether a tool returning `offered` gives a caller what `wanted` asks for. */
+export function fieldSatisfies(offered: string, wanted: string): boolean {
+  return offered === wanted || generalField(offered) === wanted;
+}
+
+/**
+ * What each existing short output name can mean, as the general field: a tool
+ * may also declare any narrowing of one (`email` as `person.email.work.value`).
+ * One entry means the name means that everywhere unless a tool narrows it.
+ * Several mean it depends on the tool, which has to say. None means the name
+ * is used for things outside the catalog and stays a per-tool name.
+ */
+export const EXTRACTOR_TARGET_FIELDS: Record<
+  DeeplineExtractorTarget,
+  readonly string[]
+> = {
+  email: ['person.email.value'],
+  personal_email: ['person.email.personal.value'],
+  email_status: ['person.email.status'],
+  phone: ['person.phone.value', 'company.phone.value'],
+  phone_status: ['person.phone.status'],
+  first_name: ['person.name.first'],
+  last_name: ['person.name.last'],
+  full_name: ['person.name.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', 'company.linkedin.url'],
+  linkedin_url: ['person.linkedin.url'],
+  title: ['person.job.title'],
+  job_change: ['person.job.change'],
+  job_change_status: ['person.job.change_status'],
+  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'],
+  // Also used for a podcast URL.
+  website: ['company.website.url'],
+  company_linkedin_url: ['company.linkedin.url'],
+  industry: ['company.industry.value'],
+  id: ['person.record.id', 'company.record.id'],
+  // Used for unrelated provider statuses; none is a catalog field.
+  status: [],
+};
+
+/**
+ * The catalog field a short name stands for on one tool: what the tool
+ * declares, or else the name's one meaning. Undefined when the name is
+ * ambiguous and the tool has not said, or when what it said is not something
+ * the name can mean.
+ */
+export function fieldOfName(
+  name: string,
+  declared?: string,
+): string | undefined {
+  const meanings: readonly string[] =
+    EXTRACTOR_TARGET_FIELDS[name as DeeplineExtractorTarget] ?? [];
+  if (declared === undefined) {
+    return meanings.length === 1 ? meanings[0] : undefined;
+  }
+  return meanings.some((meaning) => fieldSatisfies(declared, meaning))
+    ? declared
+    : undefined;
+}

package/dist/bundling-sources/shared_libs/plays/tool-result-types.ts

@@ -55,6 +55,8 @@ export type ToolResultListMetadata = {
 
 export type ToolResultExtractorDescriptor = {
   paths: readonly string[];
+  /** The field catalog id this output is on this tool, when it declares one. */
+  means?: string;
   transforms?: readonly string[];
   enum?: readonly string[];
   overrides?: readonly ToolResultExtractorOverride[];

package/dist/cli/{auth-ODSACXLF.mjs → auth-7BMCDCRH.mjs}

@@ -10,12 +10,12 @@ import {
   registerAuthCommands,
   reportSetupCompleted,
   resolvePendingAuthClaimForResume
-} from "./chunk-3CTB7V5F.mjs";
-import "./chunk-MIMV5LTU.mjs";
-import "./chunk-FGHRRJ3D.mjs";
+} from "./chunk-XMME4SCK.mjs";
+import "./chunk-HNLXC5BP.mjs";
+import "./chunk-IUYKSTWB.mjs";
 import "./chunk-DLIRSHV6.mjs";
 import "./chunk-NXGCO4JB.mjs";
-import "./chunk-JAERLCMH.mjs";
+import "./chunk-P5JPGZNI.mjs";
 import "./chunk-WZYKRD7T.mjs";
 import "./chunk-KRD6H754.mjs";
 export {

package/dist/cli/auth-BWCNRUG3.js

@@ -0,0 +1,33 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+
+
+
+
+
+
+
+
+var _chunkORBVXCTLjs = require('./chunk-ORBVXCTL.js');
+require('./chunk-JHUMUIU6.js');
+require('./chunk-ND4BVWWZ.js');
+require('./chunk-XNYIZMNQ.js');
+require('./chunk-7P5AA3SN.js');
+require('./chunk-CLEB5KUZ.js');
+require('./chunk-OG64RBAC.js');
+require('./chunk-COGTRVWW.js');
+
+
+
+
+
+
+
+
+
+
+
+
+exports.EXIT_WORKSPACE_MISMATCH = _chunkORBVXCTLjs.EXIT_WORKSPACE_MISMATCH; exports.authStatusLine = _chunkORBVXCTLjs.authStatusLine; exports.clearPendingClaim = _chunkORBVXCTLjs.clearPendingClaim; exports.clearSatisfiedPendingClaim = _chunkORBVXCTLjs.clearSatisfiedPendingClaim; exports.handleRegister = _chunkORBVXCTLjs.handleRegister; exports.handleStatus = _chunkORBVXCTLjs.handleStatus; exports.handleWait = _chunkORBVXCTLjs.handleWait; exports.readPendingAuthClaim = _chunkORBVXCTLjs.readPendingAuthClaim; exports.registerAuthCommands = _chunkORBVXCTLjs.registerAuthCommands; exports.reportSetupCompleted = _chunkORBVXCTLjs.reportSetupCompleted; exports.resolvePendingAuthClaimForResume = _chunkORBVXCTLjs.resolvePendingAuthClaimForResume;