@koda-sl/baker-cli 0.500.0 → 0.503.0

package/dist/chunk-DGKGOBCZ.js

@@ -0,0 +1,387 @@
+import {
+  CRM_COLUMN_FIELDS,
+  CRM_DEAL_STATUSES,
+  targetAccountsSchema,
+  targetsSummarySchema
+} from "./chunk-MGYC2IRC.js";
+import {
+  calendarDaySchema,
+  todayUtc,
+  windowTooLong
+} from "./chunk-JDJQKN27.js";
+
+// ../api/src/accounts/crm-columns.ts
+var COLUMN_HELD = 0.7;
+var SAMPLE_CHARS = 60;
+var EMAIL = /[^\s@]+@[^\s@]+\.[^\s@]+/g;
+var CRITERIA = {
+  id: "The deal's own unique id or number in the CRM (a deal, opportunity or record id of the deal), not the company's id",
+  name: "The deal's own title (a deal or opportunity name), not the name of the company or of a person",
+  companyId: "The CRM's unique id (or record id) of the company or account the row is about or the deal is with",
+  companyName: "The name of the company, account or organization the row is about or the deal is with",
+  companyDomain: "The company's website or web domain, like acme.com",
+  companyLinkedinPage: "The company's LinkedIn page address",
+  amount: "The deal's own value in money (its amount, value or size), not a weighted or forecast amount, not a company's revenue or turnover, not a probability, a percentage or a count",
+  currency: "The currency the amount is in, like EUR or USD",
+  pipeline: "Which sales pipeline the deal belongs to, not its stage",
+  stage: "The deal's stage or state in the sales pipeline, in any words (like Proposal, Negotiation, Closed Won, Ganado), not the status of a lead or a contact",
+  status: "Whether the deal is open, won or lost, written as exactly the English word open, won or lost",
+  createdAt: "The date the deal or the company was created, opened or added to the CRM",
+  closedAt: "The date the deal was closed (won or lost) or is expected to close",
+  none: "Anything else: a person (an owner, a contact, a person's name, email or phone), who created or last changed the record, a probability, a weighted amount, a company's revenue or size, a lead's or contact's status, a next step, a source, notes, an industry, a date of last activity, or any other field"
+};
+var QUESTION = "`column` is the header of a column in a spreadsheet exported from a CRM, in any language or in the CRM's own wording, and `cells` are values from that column. `sheet` lists every header of the spreadsheet, for context. Which field does `column` hold?";
+function sampleCell(cell) {
+  return cell.replace(EMAIL, "<email address>").slice(0, SAMPLE_CHARS);
+}
+function crmColumnQuestions(columns, headers = columns.map((column) => column.header)) {
+  const sheet = headers.join(" | ");
+  return columns.map(({ header, samples }) => ({
+    type: "choice",
+    instructions: {
+      sheet,
+      column: header,
+      cells: samples.length > 0 ? samples.map(sampleCell).join(" | ") : "(empty)",
+      question: QUESTION
+    },
+    criteria: CRITERIA
+  }));
+}
+var isCrmColumnField = (choice) => CRM_COLUMN_FIELDS.includes(choice);
+var isStatusCell = (cell) => CRM_DEAL_STATUSES.includes(cell.trim().toLowerCase());
+function crmColumnMeanings(columns, answers, held = COLUMN_HELD) {
+  const meanings = {};
+  columns.forEach(({ header, samples }, index) => {
+    const answer = answers[index];
+    if (answer === void 0 || !("choice" in answer)) return;
+    const { choice, probabilities } = answer;
+    if (!isCrmColumnField(choice) || (probabilities[choice] ?? 0) < held) return;
+    meanings[header] = choice === "status" && !samples.every(isStatusCell) ? "stage" : choice;
+  });
+  return meanings;
+}
+
+// ../api/src/accounts/index.ts
+import { z } from "zod";
+var INFLUENCE_MODEL_KINDS = ["engagement", "awareness", "intent"];
+var INFLUENCE_METRICS = ["impressions", "engagements", "clicks"];
+var DEFAULT_LOOKBACK_MONTHS = 12;
+var MATCH_CONFIDENCES = ["high", "low"];
+var MODEL_METRIC = {
+  engagement: { metric: "engagements", threshold: 3 },
+  awareness: { metric: "impressions", threshold: 7 },
+  intent: { metric: "clicks", threshold: 3 }
+};
+function influenceParams(settings, override = {}) {
+  const kind = override.model ?? settings.model.kind;
+  const model = MODEL_METRIC[kind];
+  const wholeAtLeastOne = (value) => value !== void 0 && Number.isInteger(value) && value >= 1;
+  const threshold = override.threshold ?? (override.model === void 0 ? settings.model.threshold : void 0);
+  return {
+    metric: model.metric,
+    threshold: wholeAtLeastOne(threshold) ? threshold : model.threshold,
+    lookbackMonths: wholeAtLeastOne(settings.lookbackMonths) ? settings.lookbackMonths : DEFAULT_LOOKBACK_MONTHS
+  };
+}
+var ACCOUNTS_MAX_MONTHS = 24;
+var windowFields = {
+  /** Calendar months including the current one. */
+  lastMonths: z.number().int().min(1).max(ACCOUNTS_MAX_MONTHS).optional(),
+  start: calendarDaySchema.optional(),
+  end: calendarDaySchema.optional()
+};
+var ruleOverrideFields = {
+  model: z.enum(INFLUENCE_MODEL_KINDS).optional(),
+  threshold: z.number().int().min(1).optional()
+};
+var targetsField = { targets: targetAccountsSchema.optional() };
+var targetsSummaryField = { targets: targetsSummarySchema.optional() };
+function windowRules(req, ctx) {
+  if (req.start !== void 0 && req.lastMonths !== void 0) {
+    ctx.addIssue({ code: "custom", path: ["lastMonths"], message: "pass lastMonths or start/end, not both" });
+  }
+  if (req.end !== void 0 && req.start === void 0) {
+    ctx.addIssue({ code: "custom", path: ["end"], message: "end needs a start" });
+  }
+  if (req.start !== void 0 && req.end !== void 0 && req.end < req.start) {
+    ctx.addIssue({ code: "custom", path: ["end"], message: "end is before start" });
+    return;
+  }
+  const tooLong = req.start === void 0 ? null : windowTooLong(req.start, req.end ?? todayUtc(), ACCOUNTS_MAX_MONTHS);
+  if (tooLong !== null) ctx.addIssue({ code: "custom", path: ["start"], message: tooLong });
+}
+var accountsWindowSchema = z.object({ start: z.string(), end: z.string() });
+var influenceParamsSchema = z.object({
+  metric: z.enum(INFLUENCE_METRICS),
+  threshold: z.number(),
+  lookbackMonths: z.number()
+});
+var ACCOUNTS_ENGAGEMENT_DEFAULT_LIMIT = 500;
+var ACCOUNTS_ENGAGEMENT_MAX_LIMIT = 5e3;
+var accountEngagementRowSchema = z.object({
+  /** LinkedIn organization id; `urn:li:organization:<orgId>` on LinkedIn. */
+  orgId: z.string(),
+  /** Empty until the nightly sync has looked the company up. */
+  name: z.string(),
+  domain: z.string(),
+  impressions: z.number(),
+  clicks: z.number(),
+  engagements: z.number(),
+  videoViews: z.number(),
+  /** LinkedIn does not always report spend per company; 0 then. */
+  costLocal: z.number(),
+  currency: z.string(),
+  /** Months in the window the company saw or did anything. */
+  monthsActive: z.number(),
+  lastMonth: z.string().nullable(),
+  /** The same-length period just before the window. */
+  previous: z.object({ impressions: z.number(), clicks: z.number(), engagements: z.number() }),
+  /** By engagements against the previous period. */
+  flag: z.enum(["new", "rising"]).nullable(),
+  crmCompanyId: z.string().nullable(),
+  /** The matched CRM company's name; null without a match. Optional for older servers. */
+  crmCompanyName: z.string().nullable().optional(),
+  matchConfidence: z.enum(MATCH_CONFIDENCES).nullable(),
+  hasOpenDeal: z.boolean(),
+  hasWonDeal: z.boolean(),
+  hasLostDeal: z.boolean(),
+  /** When the company's most recent lost deal closed (created, when it has no close date), ISO; null without one. */
+  lastLostAt: z.string().nullable(),
+  /**
+   * People whose work email named the company's domain on the website or the
+   * API in the period, and how many became leads — the touches beside the ads.
+   * Null when none did; absent from older servers.
+   */
+  website: z.object({ people: z.number(), leads: z.number() }).nullable().optional(),
+  /**
+   * Visits from the company's own network in the period (`baker analytics
+   * companies`): visits, distinct pages read, and when it was last seen.
+   * Matched by normalised name (`companyNameKey`) against the LinkedIn name or
+   * the CRM match's name — the network gives no website to match on. Null when
+   * none matched; absent from older servers.
+   */
+  visitorCompany: z.object({ visits: z.number(), pages: z.number(), lastSeen: z.string() }).nullable().optional()
+});
+var accountWebsiteRowSchema = z.object({
+  domain: z.string(),
+  people: z.number(),
+  leads: z.number(),
+  /** ISO. */
+  firstSeen: z.string(),
+  /** ISO. */
+  lastSeen: z.string()
+});
+function accountDealStatus(row) {
+  if (row.hasWonDeal) return "won";
+  if (row.hasOpenDeal) return "open";
+  if (row.hasLostDeal) return "lost";
+  return "none";
+}
+var LOST_DEAL_COOLDOWN_MONTHS = 6;
+function monthsBefore(day, months) {
+  const [year, month, date] = day.split("-").map(Number);
+  const index = (year ?? 1970) * 12 + ((month ?? 1) - 1) - months;
+  const lastDate = new Date(Date.UTC(Math.floor(index / 12), index % 12 + 1, 0)).getUTCDate();
+  return new Date(Date.UTC(Math.floor(index / 12), index % 12, Math.min(date ?? 1, lastDate))).toISOString().slice(0, 10);
+}
+function warmAccounts(rows, today, options = {}) {
+  const cooldownStart = monthsBefore(today, LOST_DEAL_COOLDOWN_MONTHS);
+  const { minimum } = options;
+  return rows.filter(
+    (row) => row.flag !== null && (minimum === void 0 || row[minimum.metric] >= minimum.value) && !row.hasOpenDeal && !row.hasWonDeal && !(row.lastLostAt !== null && row.lastLostAt.slice(0, 10) >= cooldownStart)
+  );
+}
+var accountsEngagementRequestSchema = z.object({
+  ...windowFields,
+  /** One campaign's companies; every campaign together when absent. */
+  campaignId: z.string().regex(/^\d+$/, "use the numeric campaign id").optional(),
+  /** Companies per page. */
+  limit: z.number().int().min(1).max(ACCOUNTS_ENGAGEMENT_MAX_LIMIT).default(ACCOUNTS_ENGAGEMENT_DEFAULT_LIMIT),
+  /** Which page, 1-based, most engaged first. */
+  page: z.number().int().min(1).default(1),
+  ...targetsField
+}).superRefine(windowRules);
+var accountsEngagementResponseSchema = z.object({
+  ok: z.literal(true),
+  data: z.object({
+    window: accountsWindowSchema,
+    previousWindow: accountsWindowSchema,
+    companies: z.array(accountEngagementRowSchema),
+    /** True when more companies were reached than this page and the ones before it hold. */
+    truncated: z.boolean(),
+    /** Which page this is, and how many companies there are in all. Absent from older servers. */
+    pageInfo: z.object({ page: z.number(), pageSize: z.number(), total: z.number(), hasMore: z.boolean() }).optional(),
+    /** The company's influence rule (the default one before setup): the minimum `baker accounts warm` applies. */
+    rule: influenceParamsSchema.optional(),
+    ...targetsSummaryField
+  })
+});
+var INFLUENCE_BASES = ["pipeline", "revenue"];
+var accountDealRowSchema = z.object({
+  dealId: z.string(),
+  dealName: z.string(),
+  crmCompanyId: z.string(),
+  companyName: z.string(),
+  domain: z.string(),
+  /** Null when the deal has no amount — unknown, not zero. */
+  amount: z.number().nullable(),
+  currency: z.string(),
+  /** Created (pipeline) or closed won (revenue), ISO. The date the lookback counts back from. */
+  referenceAt: z.string(),
+  /** By the won and lost stages chosen in the settings. */
+  status: z.enum(["open", "won", "lost"]),
+  /** The model's metric, summed over the company's lookback months. */
+  touchValue: z.number(),
+  /** The first month inside the lookback the company was reached, `YYYY-MM-01`. */
+  firstTouchMonth: z.string().nullable(),
+  /** How surely the CRM company is the LinkedIn one; null when no LinkedIn company matched. */
+  matchConfidence: z.enum(MATCH_CONFIDENCES).nullable(),
+  /** The company crossed the threshold — whatever the match confidence. */
+  influenced: z.boolean()
+});
+var moneyByCurrencySchema = z.record(z.string(), z.number());
+var influenceSummarySchema = z.object({
+  /** Every deal in the window for this basis. */
+  deals: z.number(),
+  /** Influenced, confirmed matches only — the headline. */
+  influencedDeals: z.number(),
+  influencedValue: moneyByCurrencySchema,
+  /** Influenced deals with no amount entered: counted, not valued. */
+  dealsWithoutAmount: z.number(),
+  /** Influenced through a match nobody confirmed yet; not in the headline. */
+  lowConfidenceDeals: z.number(),
+  lowConfidenceValue: moneyByCurrencySchema,
+  /** LinkedIn spend on the companies reached in the window, per currency. */
+  spend: moneyByCurrencySchema,
+  /** Influenced value per 1 of spend — only when both are in the same single currency. */
+  valuePerSpend: z.object({ currency: z.string(), value: z.number() }).nullable()
+});
+var accountsInfluencedRequestSchema = z.object({
+  ...windowFields,
+  /** `pipeline`: deals created in the window and not won. `revenue`: deals closed won in the window. */
+  basis: z.enum(INFLUENCE_BASES).default("pipeline"),
+  /** Every deal in the window, influenced or not; compact returns the influenced ones. */
+  full: z.boolean().default(false),
+  ...ruleOverrideFields,
+  ...targetsField
+}).superRefine(windowRules);
+var accountsInfluencedResponseSchema = z.object({
+  ok: z.literal(true),
+  data: z.object({
+    window: accountsWindowSchema,
+    basis: z.enum(INFLUENCE_BASES),
+    rule: influenceParamsSchema,
+    summary: influenceSummarySchema,
+    /** Influenced deals on confirmed matches; with `full`, every deal in the window. */
+    deals: z.array(accountDealRowSchema),
+    /** Influenced through a match nobody confirmed yet. Not in `summary`'s headline. */
+    lowConfidence: z.array(accountDealRowSchema),
+    /** True when the window held more deals than one read returns. */
+    truncated: z.boolean(),
+    ...targetsSummaryField
+  })
+});
+var accountsCompanyRequestSchema = z.object({
+  /** LinkedIn organization id, or its `urn:li:organization:` URN. */
+  orgId: z.string().transform((value) => value.replace(/^urn:li:organization:/, "")).pipe(z.string().regex(/^\d+$/, "use the LinkedIn company id or its urn:li:organization URN")).optional(),
+  /** The company's website domain, `acme.com`. */
+  domain: z.string().min(3).max(253).transform(
+    (value) => value.trim().toLowerCase().replace(/^https?:\/\//, "").replace(/^www\./, "").replace(/\/.*$/, "")
+  ).optional()
+}).refine((req) => req.orgId === void 0 !== (req.domain === void 0), {
+  message: "Give a LinkedIn company id or a domain, one of the two."
+});
+var accountCompanyMonthSchema = z.object({
+  orgId: z.string(),
+  /** Empty for the whole ad account; a campaign id otherwise. */
+  campaignId: z.string(),
+  /** LinkedIn's name for the campaign; null for the account-wide row, or when LinkedIn could not be asked. */
+  campaignName: z.string().nullable(),
+  month: z.string(),
+  impressions: z.number(),
+  clicks: z.number(),
+  engagements: z.number()
+});
+var accountCompanyDealSchema = z.object({
+  dealId: z.string(),
+  dealName: z.string(),
+  amount: z.number().nullable(),
+  currency: z.string(),
+  status: z.enum(["open", "won", "lost"]),
+  createdAt: z.string(),
+  closedAt: z.string().nullable(),
+  /**
+   * The rule's metric over the lookback ending with the deal's reference month
+   * (created; closed for a won deal), from the pages in `orgs`. Absent before
+   * setup or when the company matched no CRM company.
+   */
+  touchValue: z.number().optional(),
+  /** `touchValue` reached the rule's threshold. */
+  influenced: z.boolean().optional()
+});
+var accountCompanyOrgSchema = z.object({
+  orgId: z.string(),
+  name: z.string(),
+  domain: z.string(),
+  crmCompanyId: z.string().nullable(),
+  matchConfidence: z.enum(MATCH_CONFIDENCES).nullable()
+});
+var accountsCompanyResponseSchema = z.object({
+  ok: z.literal(true),
+  data: z.object({
+    /** Usually one; a domain can name several LinkedIn pages of the same company. */
+    orgs: z.array(accountCompanyOrgSchema),
+    /** Month by month, per campaign (and the account-wide row, `campaignId: ""`), oldest first. */
+    months: z.array(accountCompanyMonthSchema),
+    /** Deals of the matched CRM company, oldest first. */
+    deals: z.array(accountCompanyDealSchema),
+    /** The rule `influenced` and `touchValue` on each deal were read with; absent before setup. */
+    rule: influenceParamsSchema.optional()
+  })
+});
+var accountsCampaignsRequestSchema = z.object({
+  ...windowFields,
+  ...ruleOverrideFields,
+  basis: z.enum(INFLUENCE_BASES).default("pipeline"),
+  ...targetsField
+}).superRefine(windowRules);
+var accountCampaignRowSchema = z.object({
+  campaignId: z.string(),
+  /** LinkedIn's name for the campaign; null when LinkedIn could not be asked or no longer lists it. */
+  campaignName: z.string().nullable(),
+  /** Companies that saw at least one impression in the window. */
+  companiesReached: z.number(),
+  /** Companies with at least one engagement in the window. */
+  companiesEngaged: z.number(),
+  /** Influenced deals (of the read's basis) this campaign touched in their lookback. Overlaps other campaigns. */
+  influencedDeals: z.number(),
+  influencedValue: moneyByCurrencySchema
+});
+var accountsCampaignsResponseSchema = z.object({
+  ok: z.literal(true),
+  data: z.object({
+    window: accountsWindowSchema,
+    /** Optional for older servers, which read pipeline only. */
+    basis: z.enum(INFLUENCE_BASES).optional(),
+    rule: influenceParamsSchema,
+    campaigns: z.array(accountCampaignRowSchema),
+    ...targetsSummaryField
+  })
+});
+var ACCOUNTS_NO_SETTINGS_MESSAGE = "Account insights are not set up yet: in Measure \u2192 Accounts, say where your deals are (HubSpot or another CRM) and what won and lost mean.";
+
+export {
+  crmColumnQuestions,
+  crmColumnMeanings,
+  INFLUENCE_MODEL_KINDS,
+  influenceParams,
+  ACCOUNTS_ENGAGEMENT_MAX_LIMIT,
+  accountDealStatus,
+  warmAccounts,
+  accountsEngagementRequestSchema,
+  accountsInfluencedRequestSchema,
+  accountsCompanyRequestSchema,
+  accountsCampaignsRequestSchema,
+  ACCOUNTS_NO_SETTINGS_MESSAGE
+};
+//# sourceMappingURL=chunk-DGKGOBCZ.js.map