outbound-sdk 0.11.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. package/dist/alerts/index.js +1 -1
  2. package/dist/budget/index.js +1 -1
  3. package/dist/cards/index.js +217 -100
  4. package/dist/cards/sender-tool-cards.d.ts +6 -0
  5. package/dist/chunks/{chunk-UAHYPASH.js → chunk-3LRIWQEJ.js} +2 -1
  6. package/dist/chunks/{chunk-UZLFZZ2U.js → chunk-6BSFR5SF.js} +14 -2
  7. package/dist/chunks/{chunk-FTK4JS65.js → chunk-BTIJ24UY.js} +89 -9
  8. package/dist/chunks/{chunk-OVTYA3IB.js → chunk-EAG5NIPM.js} +614 -206
  9. package/dist/chunks/{chunk-A7DLJUA6.js → chunk-FT6HMMMP.js} +3 -1
  10. package/dist/chunks/chunk-I7GBBHD2.js +80 -0
  11. package/dist/chunks/{chunk-UOJG4VYF.js → chunk-LD5OAELW.js} +1 -1
  12. package/dist/chunks/{chunk-KMQHXFIZ.js → chunk-LJNU4LAR.js} +2094 -1014
  13. package/dist/chunks/{chunk-POBAY3TI.js → chunk-NLYGMVXS.js} +30 -0
  14. package/dist/chunks/{chunk-V7JKTNRO.js → chunk-OE45PREW.js} +1 -1
  15. package/dist/chunks/{chunk-MEEJIIIA.js → chunk-OP2GL7ZT.js} +77 -8
  16. package/dist/chunks/{chunk-YFJ3OQZS.js → chunk-OPLXELPS.js} +5 -1
  17. package/dist/chunks/{chunk-CVLGFVDC.js → chunk-PDYE6CWS.js} +136 -64
  18. package/dist/chunks/{chunk-OMCDMELK.js → chunk-PUIHJFK4.js} +1 -1
  19. package/dist/chunks/{chunk-MPE6VLLY.js → chunk-UZ4YWUZ7.js} +1 -1
  20. package/dist/chunks/{tools-AVJ3XJ5A.js → tools-VCCH3JNL.js} +13 -6
  21. package/dist/cli/bin.js +11 -10
  22. package/dist/cli/config.d.ts +0 -2
  23. package/dist/cli/index.js +10 -9
  24. package/dist/cli/offered.d.ts +31 -2
  25. package/dist/cli/serve.d.ts +4 -2
  26. package/dist/combine/index.js +60 -4
  27. package/dist/emailbison/index.js +4 -4
  28. package/dist/fixtures/index.js +4 -4
  29. package/dist/heyreach/index.js +17 -6
  30. package/dist/identity/index.js +46 -11
  31. package/dist/identity/keys.d.ts +1 -1
  32. package/dist/index.js +8 -6
  33. package/dist/insights/capped.d.ts +14 -1
  34. package/dist/insights/define.d.ts +8 -6
  35. package/dist/insights/index.d.ts +1 -1
  36. package/dist/insights/index.js +12 -61
  37. package/dist/insights/inputs.generated.d.ts +91 -16
  38. package/dist/insights/ops/campaign-ranking.d.ts +8 -1
  39. package/dist/insights/ops/channel-mix.d.ts +8 -1
  40. package/dist/insights/ops/client-report.d.ts +28 -18
  41. package/dist/insights/ops/client-runway.d.ts +43 -0
  42. package/dist/insights/ops/index.d.ts +6 -1
  43. package/dist/insights/ops/period-comparison.d.ts +35 -2
  44. package/dist/insights/ops/pipeline-forecast.d.ts +14 -9
  45. package/dist/insights/ops/shared.d.ts +49 -2
  46. package/dist/insights/ops/tag-rollup.d.ts +8 -1
  47. package/dist/insights/people/coverage.d.ts +26 -0
  48. package/dist/insights/people/dropped-replies-check.d.ts +19 -3
  49. package/dist/insights/people/dropped-replies.d.ts +6 -2
  50. package/dist/insights/people/find.d.ts +5 -4
  51. package/dist/insights/people/hot-leads.d.ts +10 -1
  52. package/dist/insights/people/index.d.ts +26 -2
  53. package/dist/insights/people/lead-collisions.d.ts +18 -1
  54. package/dist/insights/people/person-summary.d.ts +15 -3
  55. package/dist/insights/people/suppression-check.d.ts +18 -1
  56. package/dist/insights/people/thread-context.d.ts +79 -0
  57. package/dist/insights/people/thread-contexts.d.ts +59 -0
  58. package/dist/insights/people/thread-read.d.ts +33 -0
  59. package/dist/insights/registry.d.ts +29 -3
  60. package/dist/insights/senders/domain-health.d.ts +1 -1
  61. package/dist/insights/senders/index.d.ts +1 -1
  62. package/dist/insights/senders/read.d.ts +9 -0
  63. package/dist/insights/tools.d.ts +35 -2
  64. package/dist/instantly/adapter.d.ts +3 -2
  65. package/dist/instantly/capabilities.d.ts +5 -0
  66. package/dist/instantly/index.js +255 -66
  67. package/dist/instantly/lead-ids.d.ts +11 -0
  68. package/dist/instantly/map-lead.d.ts +19 -2
  69. package/dist/instantly/senders.d.ts +3 -0
  70. package/dist/internal/adapter.d.ts +7 -0
  71. package/dist/internal/capabilities.d.ts +8 -0
  72. package/dist/internal/entities.d.ts +24 -1
  73. package/dist/internal/fields.d.ts +10 -0
  74. package/dist/internal/outbound/api.d.ts +12 -0
  75. package/dist/internal/outbound/operations-account.d.ts +4 -1
  76. package/dist/internal/outbound/outbound.d.ts +2 -1
  77. package/dist/internal/outbound/specs-account.d.ts +2 -1
  78. package/dist/internal/person.d.ts +32 -0
  79. package/dist/internal/records.d.ts +2 -2
  80. package/dist/internal/reply-people.d.ts +25 -7
  81. package/dist/internal/runway.d.ts +38 -5
  82. package/dist/internal/url.d.ts +2 -1
  83. package/dist/loader/index.js +1 -1
  84. package/dist/memory/data.d.ts +2 -1
  85. package/dist/memory/index.js +6 -4
  86. package/dist/redact/index.d.ts +1 -1
  87. package/dist/redact/index.js +62 -31
  88. package/dist/redact/plugin.d.ts +13 -11
  89. package/dist/redact/tokens.d.ts +18 -1
  90. package/dist/smartlead/index.js +21 -7
  91. package/dist/tools/account-tools.d.ts +0 -5
  92. package/dist/tools/ai-sdk.js +5 -3
  93. package/dist/tools/campaign-tools.d.ts +0 -4
  94. package/dist/tools/claude-agent.js +5 -3
  95. package/dist/tools/deliverability-check.d.ts +9 -0
  96. package/dist/tools/index.js +6 -4
  97. package/dist/tools/people-tools.d.ts +4 -1
  98. package/dist/tools/person-input.d.ts +17 -0
  99. package/dist/tools/registry.d.ts +8 -1
  100. package/dist/tools/sender-health.d.ts +8 -0
  101. package/dist/tools/sender-impact.d.ts +38 -0
  102. package/dist/tools/shared.d.ts +5 -0
  103. package/dist/webhooks/index.js +6 -6
  104. package/package.json +1 -1
  105. /package/dist/chunks/{chunk-5XLR6XVV.js → chunk-HNYJO6B4.js} +0 -0
@@ -1,90 +1,40 @@
1
1
  import {
2
- ENTRIES,
3
2
  INSIGHTS,
4
3
  INSIGHT_TOOL_CEILING,
5
- boundsOf,
6
4
  compareRates,
7
- defaultCap,
8
5
  defineInsight,
9
6
  deviation,
7
+ insightCost,
10
8
  insightTools,
9
+ insights,
10
+ listInsights,
11
11
  mean,
12
12
  median,
13
+ membersOf,
13
14
  percentile,
14
15
  rate,
15
16
  round,
16
17
  runInsight,
18
+ runInsightByName,
17
19
  tally,
18
20
  total,
19
21
  wilson,
20
22
  zScore
21
- } from "../chunks/chunk-KMQHXFIZ.js";
22
- import "../chunks/chunk-FTK4JS65.js";
23
+ } from "../chunks/chunk-LJNU4LAR.js";
24
+ import "../chunks/chunk-BTIJ24UY.js";
23
25
  import "../chunks/chunk-4PA526S7.js";
26
+ import "../chunks/chunk-I7GBBHD2.js";
24
27
  import "../chunks/chunk-HZCTYL22.js";
25
28
  import "../chunks/chunk-HPNGSG5E.js";
26
29
  import "../chunks/chunk-PTZO4QXR.js";
27
30
  import "../chunks/chunk-FALWG5U3.js";
28
- import "../chunks/chunk-POBAY3TI.js";
31
+ import "../chunks/chunk-NLYGMVXS.js";
29
32
  import "../chunks/chunk-CPACP4YD.js";
30
33
  import "../chunks/chunk-QGRZDTX4.js";
34
+ import "../chunks/chunk-OPLXELPS.js";
31
35
  import "../chunks/chunk-HXB2IOJJ.js";
32
- import "../chunks/chunk-YFJ3OQZS.js";
33
- import {
34
- OutboundError
35
- } from "../chunks/chunk-XYHM4KHC.js";
36
+ import "../chunks/chunk-XYHM4KHC.js";
36
37
  import "../chunks/chunk-45TXPJW7.js";
37
-
38
- // src/insights/plugin.ts
39
- import { z } from "zod";
40
- var entryNamed = (outbound, name) => {
41
- const entry = ENTRIES.find(
42
- (candidate) => candidate.name === name || candidate.key === name
43
- );
44
- if (entry === void 0) {
45
- throw new OutboundError(
46
- "Invalid",
47
- `There is no insight "${name}". Known: ${ENTRIES.map((each) => each.name).join(", ")}`,
48
- { provider: outbound.provider }
49
- );
50
- }
51
- return entry;
52
- };
53
- var runInsightByName = async (outbound, name, input = {}, options = {}) => await entryNamed(outbound, name).execute(outbound, input, options);
54
- var insightCost = (outbound, name, input = {}) => {
55
- const entry = entryNamed(outbound, name);
56
- const parsed = entry.inputSchema.safeParse(input);
57
- if (!parsed.success) {
58
- throw new OutboundError(
59
- "Invalid",
60
- `${entry.name}: ${parsed.error.issues[0]?.message ?? "the input is not valid"}`,
61
- { provider: outbound.provider }
62
- );
63
- }
64
- const bounds = boundsOf(outbound, entry.cost, parsed.data);
65
- return bounds === null ? null : { ...bounds, defaultCap: defaultCap(bounds) };
66
- };
67
- var listInsights = () => ENTRIES.map((entry) => ({
68
- description: entry.description,
69
- key: entry.key,
70
- name: entry.name,
71
- needs: [...entry.needs],
72
- // SAFETY: a JSON Schema document is JSON by definition.
73
- parameters: z.toJSONSchema(entry.inputSchema, { io: "input" })
74
- }));
75
- var insights = () => ({
76
- extend: (outbound) => {
77
- const methods = {};
78
- for (const entry of ENTRIES) {
79
- methods[entry.key] = (input, options) => (
80
- // SAFETY: the answer is the entry's own, typed per key by Insights.
81
- entry.execute(outbound, input, options)
82
- );
83
- }
84
- return { insights: methods };
85
- },
86
- name: "insights"
87
- });
88
38
  export {
89
39
  INSIGHTS,
90
40
  INSIGHT_TOOL_CEILING,
@@ -97,6 +47,7 @@ export {
97
47
  listInsights,
98
48
  mean,
99
49
  median,
50
+ membersOf,
100
51
  percentile,
101
52
  rate,
102
53
  round,
@@ -9,11 +9,29 @@ export interface InsightInputs {
9
9
  */
10
10
  readonly max_campaigns?: number | undefined;
11
11
  /**
12
- * The person's email address or LinkedIn profile URL, or a lead ref as the other people insights return
12
+ * The person's email address, for example jane@acme.com
13
13
  *
14
- * At least 3 characters. Required.
14
+ * Defaults to `null`.
15
+ */
16
+ readonly email?: string | undefined;
17
+ /**
18
+ * A lead ref exactly as another tool returned it (provider:workspace:id), for example a reply's leadRef or a lead's ref. A ref's provider picks the tool it is read from
19
+ *
20
+ * Defaults to `null`.
21
+ */
22
+ readonly lead_ref?: string | undefined;
23
+ /**
24
+ * The person's LinkedIn profile URL
25
+ *
26
+ * Defaults to `null`.
15
27
  */
16
- readonly person: string;
28
+ readonly linkedin_url?: string | undefined;
29
+ /**
30
+ * Any of an email address, a LinkedIn profile URL or a lead ref as another tool returned it (provider:workspace:id). Give exactly one of person, lead_ref, email and linkedin_url
31
+ *
32
+ * Defaults to `null`.
33
+ */
34
+ readonly person?: string | undefined;
17
35
  };
18
36
  /** The input of `accountSummary` (the `account_summary` tool). */
19
37
  readonly accountSummary: {
@@ -57,15 +75,15 @@ export interface InsightInputs {
57
75
  */
58
76
  readonly include_past?: boolean | undefined;
59
77
  /**
60
- * The most campaigns to read. Each costs one request per page of its leads.
78
+ * The most campaigns to read. Each costs one request per page of its leads. Defaults to the most allowed, so every campaign in the statuses is read.
61
79
  *
62
- * A whole number from 1 to 200. Defaults to `20`.
80
+ * A whole number from 1 to 200. Defaults to `200`.
63
81
  */
64
82
  readonly max_campaigns?: number | undefined;
65
83
  /**
66
- * The most leads to read from each campaign
84
+ * The most leads to read from each campaign. A campaign with more is read only in part, so totals.collisions is null.
67
85
  *
68
- * A whole number from 1 to 20,000. Defaults to `500`.
86
+ * A whole number from 1 to 20,000. Defaults to `1000`.
69
87
  */
70
88
  readonly max_leads_per_campaign?: number | undefined;
71
89
  /**
@@ -84,21 +102,21 @@ export interface InsightInputs {
84
102
  */
85
103
  readonly lead_statuses?: ("active" | "bounced" | "completed" | "paused" | "replied" | "skipped" | "unknown" | "unsubscribed")[] | undefined;
86
104
  /**
87
- * The most block list entries to read. A vendor request returns about 50 to 100.
105
+ * The most block list entries to read. A vendor request returns about 50 to 100. A lead on an entry past this cap is not found, so violations is null when entries are left unread.
88
106
  *
89
- * A whole number from 1 to 100,000. Defaults to `2000`.
107
+ * A whole number from 1 to 100,000. Defaults to `10000`.
90
108
  */
91
109
  readonly max_block_entries?: number | undefined;
92
110
  /**
93
- * The most campaigns to check. Each costs one request per page of its leads.
111
+ * The most campaigns to check. Each costs one request per page of its leads. Defaults to the most allowed, so every campaign in the statuses is checked.
94
112
  *
95
- * A whole number from 1 to 200. Defaults to `20`.
113
+ * A whole number from 1 to 200. Defaults to `200`.
96
114
  */
97
115
  readonly max_campaigns?: number | undefined;
98
116
  /**
99
- * The most leads to read from each campaign
117
+ * The most leads to read from each campaign. A campaign with more is checked only in part, so violations is null.
100
118
  *
101
- * A whole number from 1 to 20,000. Defaults to `500`.
119
+ * A whole number from 1 to 20,000. Defaults to `1000`.
102
120
  */
103
121
  readonly max_leads_per_campaign?: number | undefined;
104
122
  /**
@@ -117,7 +135,7 @@ export interface InsightInputs {
117
135
  */
118
136
  readonly categories?: ("bounce" | "negative" | "neutral" | "ooo" | "positive" | "unknown" | "unsubscribe")[] | undefined;
119
137
  /**
120
- * Set to true to also check replies flagged automatic, by the vendor or by a fixed rule
138
+ * Set to true to also check replies flagged automatic, by the vendor or by a fixed rule, and to list conversations whose latest message is an automatic reply
121
139
  *
122
140
  * Defaults to `false`.
123
141
  */
@@ -197,6 +215,12 @@ export interface InsightInputs {
197
215
  * Defaults to `["Interested","Meeting Booked","Meeting Completed"]`.
198
216
  */
199
217
  readonly positive_labels?: string[] | undefined;
218
+ /**
219
+ * Set to true to read each returned lead's conversation (one walk of messages each, up to limit) for who wrote last and a follow-up assessment. false leaves followUp.needed null with basis not_read; thread_context reads them later.
220
+ *
221
+ * Defaults to `false`.
222
+ */
223
+ readonly read_threads?: boolean | undefined;
200
224
  /**
201
225
  * A reply today earns the full recency points, fading evenly to none after this many days
202
226
  *
@@ -234,6 +258,45 @@ export interface InsightInputs {
234
258
  */
235
259
  readonly weight_reply?: number | undefined;
236
260
  };
261
+ /** The input of `threadContext` (the `thread_context` tool). */
262
+ readonly threadContext: {
263
+ /**
264
+ * snippet returns the first 280 characters of each message, wrapped as untrusted content; none returns no text. Null means snippet, or none when the redact plugin masks message bodies
265
+ *
266
+ * Defaults to `null`.
267
+ */
268
+ readonly bodies?: "none" | "snippet" | null | undefined;
269
+ /**
270
+ * coverage.nextCursor from the previous call with the same leads and threads, to read the next page of conversations
271
+ *
272
+ * Not empty. Defaults to `null`.
273
+ */
274
+ readonly cursor?: string | null | undefined;
275
+ /**
276
+ * Lead refs (provider:workspace:id), as dropped_replies, hot_leads and person_summary return them. Each lead's conversation in its campaign is read.
277
+ *
278
+ * Defaults to `[]`.
279
+ */
280
+ readonly leads?: string[] | undefined;
281
+ /**
282
+ * The newest messages returned per conversation. Every message is still read, so the latest is always found.
283
+ *
284
+ * A whole number from 1 to 100. Defaults to `10`.
285
+ */
286
+ readonly max_messages?: number | undefined;
287
+ /**
288
+ * Conversations read per call. Each costs one walk of its messages.
289
+ *
290
+ * A whole number from 1 to 50. Defaults to `20`.
291
+ */
292
+ readonly page_size?: number | undefined;
293
+ /**
294
+ * Thread ids, from a message's or reply's threadId
295
+ *
296
+ * Defaults to `[]`.
297
+ */
298
+ readonly threads?: string[] | undefined;
299
+ };
237
300
  /** The input of `personalizationGaps` (the `personalization_gaps` tool). */
238
301
  readonly personalizationGaps: {
239
302
  /**
@@ -468,9 +531,9 @@ export interface InsightInputs {
468
531
  /** The input of `domainHealth` (the `domain_health` tool). */
469
532
  readonly domainHealth: {
470
533
  /**
471
- * The most senders to check. Each costs 1 request.
534
+ * The most senders to check. Leave out for 500 where the vendor reads health a page at a time (a few requests per 100 senders), or 50 where each sender costs 1 to 3 requests.
472
535
  *
473
- * A whole number from 1 to 500. Defaults to `50`.
536
+ * A whole number from 1 to 500. Defaults to `null`.
474
537
  */
475
538
  readonly max_senders?: number | undefined;
476
539
  /**
@@ -1010,11 +1073,23 @@ export interface InsightInputs {
1010
1073
  * A whole number from 0 to 9,007,199,254,740,991. Defaults to `50`.
1011
1074
  */
1012
1075
  readonly min_sent?: number | undefined;
1076
+ /**
1077
+ * Read only one tool of a combined instance: its provider (instantly) or provider:workspace. Leave out for every tool.
1078
+ *
1079
+ * Not empty. Defaults to `null`.
1080
+ */
1081
+ readonly provider?: string | undefined;
1013
1082
  /**
1014
1083
  * A campaign with this many days of leads left or fewer is flagged
1015
1084
  *
1016
1085
  * A number, 0 or more. Defaults to `7`.
1017
1086
  */
1018
1087
  readonly runway_days?: number | undefined;
1088
+ /**
1089
+ * Read only the campaigns with this tag, for example one client's. Unusual days are then left out, since they are workspace-wide.
1090
+ *
1091
+ * Not empty. Defaults to `null`.
1092
+ */
1093
+ readonly tag?: string | undefined;
1019
1094
  };
1020
1095
  }
@@ -1,6 +1,6 @@
1
1
  import { z } from "zod";
2
2
  import type { CampaignsRead } from "../capped.ts";
3
- import type { CampaignLabel, CampaignTotals, Measured, OpenRange, ReplyBasis } from "./shared.ts";
3
+ import type { CampaignLabel, CampaignTotals, Measured, OpenRange, ReplyBasis, ToolLeftOut } from "./shared.ts";
4
4
  declare const metricSchema: z.ZodEnum<{
5
5
  bounce_rate: "bounce_rate";
6
6
  reply_rate: "reply_rate";
@@ -39,6 +39,13 @@ export interface CampaignRanking extends Ranking, CampaignsRead {
39
39
  readonly metric: RankingMetric;
40
40
  readonly better: "higher" | "lower";
41
41
  readonly period: OpenRange;
42
+ /**
43
+ * Tools of a combined instance none of whose campaigns is in `statuses`,
44
+ * so none of theirs is ranked, each with its own workspace totals for
45
+ * `period`. Always set by the insight; optional so a value built by hand
46
+ * stays valid.
47
+ */
48
+ readonly toolsLeftOut?: readonly ToolLeftOut[];
42
49
  }
43
50
  /**
44
51
  * Ranks campaigns that sent enough, and sets the rest aside with the reason.
@@ -1,7 +1,7 @@
1
1
  import type { Channel } from "../../internal/entities.ts";
2
2
  import type { CampaignsRead } from "../capped.ts";
3
3
  import type { ProportionTest } from "../stats.ts";
4
- import type { Measured, OpenRange, Totals } from "./shared.ts";
4
+ import type { Measured, OpenRange, ReplyBasis, Totals } from "./shared.ts";
5
5
  export interface ChannelGroup extends Totals {
6
6
  readonly channel: Channel;
7
7
  readonly campaigns: number;
@@ -29,6 +29,13 @@ export interface ChannelMix extends CampaignsRead {
29
29
  readonly finding: string;
30
30
  /** The same numbers for each tool and channel. */
31
31
  readonly byProvider: readonly ProviderGroup[];
32
+ /**
33
+ * What every reply and positive reply rate divides by: leads contacted, or
34
+ * messages sent when a campaign has replies in the range but contacted no
35
+ * new lead in it.
36
+ * Always set by the insight; optional so a value built by hand stays valid.
37
+ */
38
+ readonly replyRateBasis?: ReplyBasis;
32
39
  }
33
40
  export declare const channelMix: import("../define.ts").InsightDefinition<"channelMix", {
34
41
  alpha: number;
@@ -1,8 +1,9 @@
1
1
  import type { CampaignsRead } from "../capped.ts";
2
2
  import type { Anomaly } from "./anomalies.ts";
3
3
  import type { RankedCampaign } from "./campaign-ranking.ts";
4
+ import type { ActionItem, LeadRunway } from "./client-runway.ts";
4
5
  import type { Comparison } from "./period-comparison.ts";
5
- import type { CampaignLabel, DayRange, ReplyBasis } from "./shared.ts";
6
+ import type { CampaignLabel, CountsBasis, DayRange, ReplyBasis, ToolLeftOut } from "./shared.ts";
6
7
  export interface BounceProblem extends CampaignLabel {
7
8
  /** Bounces. The same as `bounced`. */
8
9
  readonly count: number | null;
@@ -14,22 +15,6 @@ export interface BounceProblem extends CampaignLabel {
14
15
  readonly low: number | null;
15
16
  readonly high: number | null;
16
17
  }
17
- export interface LeadRunway extends CampaignLabel {
18
- /** Leads still active in the campaign. */
19
- readonly remaining: number;
20
- readonly dailyContactRate: number | null;
21
- /** An estimate: `remaining` at the recent daily pace. `0` when no lead is left. */
22
- readonly daysLeft: number;
23
- }
24
- export interface ActionItem {
25
- readonly kind: "add_leads" | "check_anomaly" | "fix_bounces" | "reply_rate_fell" | "review_campaign";
26
- /** The campaign's ref, or `null` when the item is about the whole account. */
27
- readonly campaign: string | null;
28
- readonly campaignName: string | null;
29
- readonly action: string;
30
- /** The number behind the item. */
31
- readonly number: number | null;
32
- }
33
18
  export interface ClientReport extends CampaignsRead {
34
19
  readonly days: number;
35
20
  readonly period: DayRange;
@@ -37,6 +22,18 @@ export interface ClientReport extends CampaignsRead {
37
22
  readonly campaigns: number;
38
23
  /** Every campaign read, added together: this period, the one before and the change. */
39
24
  readonly totals: Comparison;
25
+ /**
26
+ * What `totals` counts: the campaigns read, in the states asked for.
27
+ * Always set by the insight, like `toolsLeftOut` and `stalled`; optional
28
+ * so a value built by hand stays valid.
29
+ */
30
+ readonly totalsBasis?: CountsBasis;
31
+ /**
32
+ * Tools of a combined instance none of whose campaigns is in `statuses`,
33
+ * so `totals` leaves them out, each with its own workspace totals for the
34
+ * period.
35
+ */
36
+ readonly toolsLeftOut?: readonly ToolLeftOut[];
40
37
  /**
41
38
  * What `top`, `bottom` and `totals` divide replies by: messages sent in
42
39
  * the period when both periods report them, since a period's replies also
@@ -51,8 +48,17 @@ export interface ClientReport extends CampaignsRead {
51
48
  readonly bounceProblems: readonly BounceProblem[];
52
49
  /** Unusual days in the period, workspace-wide. `null` when the adapter cannot serve them. */
53
50
  readonly anomalies: readonly Anomaly[] | null;
54
- /** Active campaigns about to run out of leads, soonest first. `null` when the adapter cannot serve them. */
51
+ /**
52
+ * Active campaigns with no lead left to start, then those whose leads left
53
+ * to start run out within `runway_days`, soonest first. `null` when the
54
+ * adapter cannot serve them.
55
+ */
55
56
  readonly runningOutOfLeads: readonly LeadRunway[] | null;
57
+ /**
58
+ * Active campaigns with leads left to start but no new lead started in the
59
+ * period, or no count of leads started. `null` with `runningOutOfLeads`.
60
+ */
61
+ readonly stalled?: readonly LeadRunway[] | null;
56
62
  /** What to do, most pressing first. */
57
63
  readonly actions: readonly ActionItem[];
58
64
  /** The sections left out because the adapter cannot serve them. */
@@ -71,6 +77,8 @@ export declare const clientReport: import("../define.ts").InsightDefinition<"cli
71
77
  runway_days: number;
72
78
  max_campaigns: number;
73
79
  statuses: ("active" | "archived" | "completed" | "draft" | "paused" | "unknown")[];
80
+ provider?: string | undefined;
81
+ tag?: string | undefined;
74
82
  }, ClientReport, {
75
83
  alpha?: number | undefined;
76
84
  anomaly_threshold?: number | undefined;
@@ -81,7 +89,9 @@ export declare const clientReport: import("../define.ts").InsightDefinition<"cli
81
89
  max_leads_per_campaign?: number | undefined;
82
90
  min_baseline_points?: number | undefined;
83
91
  min_sent?: number | undefined;
92
+ provider?: string | undefined;
84
93
  runway_days?: number | undefined;
94
+ tag?: string | undefined;
85
95
  max_campaigns?: number | undefined;
86
96
  statuses?: ("active" | "archived" | "completed" | "draft" | "paused" | "unknown")[] | undefined;
87
97
  }>;
@@ -0,0 +1,43 @@
1
+ import type { RunwayState } from "../../internal/runway.ts";
2
+ import type { InsightContext } from "../define.ts";
3
+ import type { CampaignPeriods } from "./period-comparison.ts";
4
+ import type { CampaignLabel } from "./shared.ts";
5
+ export interface LeadRunway extends CampaignLabel {
6
+ /**
7
+ * `draining`: leads left to start run out within `runway_days` at the
8
+ * recent pace. `out_of_leads`: none is left to start. `stalled`: some are
9
+ * left to start but none was started in the period, or the vendor reports
10
+ * no count of leads started. The same state lead_runway gives.
11
+ */
12
+ readonly state: Exclude<RunwayState, "unknown">;
13
+ /** Active leads not yet started. Those partway through the sequence are `inSequence`. */
14
+ readonly remaining: number;
15
+ /** Active leads partway through the sequence. `null` when the vendor does not say which have started. */
16
+ readonly inSequence: number | null;
17
+ /** New leads started per day over the period. `null` when the vendor reports no daily count of leads started. */
18
+ readonly dailyContactRate: number | null;
19
+ /** An estimate: `remaining` at `dailyContactRate`. `null` when the pace is 0 or unknown. */
20
+ readonly daysLeft: number | null;
21
+ }
22
+ export interface ActionItem {
23
+ readonly kind: "add_leads" | "check_anomaly" | "check_stalled" | "fix_bounces" | "reply_rate_fell" | "review_campaign";
24
+ /** The campaign's ref, or `null` when the item is about the whole account. */
25
+ readonly campaign: string | null;
26
+ readonly campaignName: string | null;
27
+ readonly action: string;
28
+ /** The number behind the item. For `add_leads` and `check_stalled`, the campaigns it names. */
29
+ readonly number: number | null;
30
+ }
31
+ export interface Runways {
32
+ readonly runningOut: readonly LeadRunway[];
33
+ readonly stalled: readonly LeadRunway[];
34
+ }
35
+ export interface RunwayOptions {
36
+ readonly days: number;
37
+ readonly max_leads_per_campaign: number;
38
+ readonly runway_days: number;
39
+ }
40
+ /** The active campaigns' runways: those running out, and those stalled. `null` when the adapter cannot serve them. */
41
+ export declare const readRunways: (context: InsightContext, campaigns: readonly CampaignPeriods[], options: RunwayOptions) => Promise<Runways | null>;
42
+ /** The runway's action items: one for every campaign that needs leads, one for every stalled campaign. */
43
+ export declare const runwayActions: (runways: Runways, options: Pick<RunwayOptions, "days" | "runway_days">) => ActionItem[];
@@ -113,6 +113,8 @@ export declare const OPS_INSIGHTS: readonly [import("../define.ts").InsightDefin
113
113
  runway_days: number;
114
114
  max_campaigns: number;
115
115
  statuses: ("active" | "archived" | "completed" | "draft" | "paused" | "unknown")[];
116
+ provider?: string | undefined;
117
+ tag?: string | undefined;
116
118
  }, import("./client-report.ts").ClientReport, {
117
119
  alpha?: number | undefined;
118
120
  anomaly_threshold?: number | undefined;
@@ -123,7 +125,9 @@ export declare const OPS_INSIGHTS: readonly [import("../define.ts").InsightDefin
123
125
  max_leads_per_campaign?: number | undefined;
124
126
  min_baseline_points?: number | undefined;
125
127
  min_sent?: number | undefined;
128
+ provider?: string | undefined;
126
129
  runway_days?: number | undefined;
130
+ tag?: string | undefined;
127
131
  max_campaigns?: number | undefined;
128
132
  statuses?: ("active" | "archived" | "completed" | "draft" | "paused" | "unknown")[] | undefined;
129
133
  }>];
@@ -131,7 +135,8 @@ export type { Anomalies, Anomaly, AnomalyMetric, MetricCoverage, } from "./anoma
131
135
  export type { CampaignDiagnosis } from "./campaign-diagnosis.ts";
132
136
  export type { CampaignRanking, RankedCampaign, RankingGap, RankingMetric, UnrankedCampaign, } from "./campaign-ranking.ts";
133
137
  export type { ChannelComparison, ChannelGroup, ChannelMix, ProviderGroup, } from "./channel-mix.ts";
134
- export type { ActionItem, BounceProblem, ClientReport, LeadRunway, } from "./client-report.ts";
138
+ export type { BounceProblem, ClientReport } from "./client-report.ts";
139
+ export type { ActionItem, LeadRunway } from "./client-runway.ts";
135
140
  export type { DiagnosisCode, DiagnosisFinding } from "./diagnosis-checks.ts";
136
141
  export type { CampaignComparison, Comparison, PeriodComparison, PeriodNumbers, ThinCampaign, } from "./period-comparison.ts";
137
142
  export type { Estimate, PipelineForecast } from "./pipeline-forecast.ts";
@@ -3,10 +3,11 @@ import type { MetricCounts } from "../../internal/metrics.ts";
3
3
  import type { CampaignsRead, Capped } from "../capped.ts";
4
4
  import type { InsightContext } from "../define.ts";
5
5
  import type { ProportionTest } from "../stats.ts";
6
- import type { CampaignLabel, DayRange, ReplyBasis, Totals } from "./shared.ts";
6
+ import type { CampaignLabel, CountsBasis, DayRange, Rates, ReplyBasis, ToolLeftOut, Totals } from "./shared.ts";
7
7
  /**
8
8
  * Counts and rates for one period, or the change between two. `null` is
9
- * unknown. The reply and positive reply rates are over `replyRateBasis`.
9
+ * unknown. The reply and positive reply rates are over `replyRateBasis`,
10
+ * and `Comparison.rates` has the count and the denominator behind each.
10
11
  */
11
12
  export interface PeriodNumbers extends Totals {
12
13
  readonly replyRate: number | null;
@@ -24,6 +25,16 @@ export interface Comparison {
24
25
  readonly replyRateBasis: ReplyBasis;
25
26
  /** `current` minus `previous`, field by field. Rates change in points: 0.02 is two points. */
26
27
  readonly change: PeriodNumbers;
28
+ /**
29
+ * Each period's rates with the counts behind them. Over several campaigns
30
+ * a rate counts only those that report both sides, so its `count` and
31
+ * `of` can be less than the totals in `current` and `previous`.
32
+ * Always set by the insight; optional so a value built by hand stays valid.
33
+ */
34
+ readonly rates?: {
35
+ readonly current: Rates;
36
+ readonly previous: Rates;
37
+ };
27
38
  /** The two-proportion test on the reply rate. `null` when it cannot be run. */
28
39
  readonly replyRateTest: ProportionTest | null;
29
40
  /** Whether the reply rate moved by more than chance. */
@@ -45,9 +56,31 @@ export interface PeriodComparison extends CampaignsRead {
45
56
  readonly tooFewSends: readonly ThinCampaign[];
46
57
  /** Every campaign read, added together. */
47
58
  readonly total: Comparison;
59
+ /**
60
+ * What `total` counts: the campaigns read, in the states asked for.
61
+ * Always set by the insight, like `workspaceBasis` and `toolsLeftOut`;
62
+ * optional so a value built by hand stays valid.
63
+ */
64
+ readonly totalBasis?: CountsBasis;
48
65
  /** The vendor's own workspace totals. `null` when the adapter has none. */
49
66
  readonly workspace: Comparison | null;
67
+ /** What `workspace` counts: every campaign, whatever its state. `null` with `workspace`. */
68
+ readonly workspaceBasis?: CountsBasis | null;
69
+ /**
70
+ * Tools of a combined instance none of whose campaigns is in `statuses`,
71
+ * so `total` leaves them out, each with its own workspace totals for this
72
+ * period.
73
+ */
74
+ readonly toolsLeftOut?: readonly ToolLeftOut[];
50
75
  }
76
+ /**
77
+ * Says why the campaigns' total and the workspace totals give different
78
+ * reply counts for the period, so neither reads as the wrong one.
79
+ */
80
+ export declare const noteRepliesApart: (context: InsightContext, campaigns: Totals, workspace: Totals, read: {
81
+ readonly campaigns: number;
82
+ readonly statuses: readonly string[];
83
+ }) => void;
51
84
  /** Compares two periods of counts: both sides, the change, and whether the reply rate really moved. */
52
85
  export declare const comparePeriods: (current: Totals, previous: Totals, alpha: number) => Comparison;
53
86
  export interface ComparedAcross {
@@ -1,4 +1,5 @@
1
1
  import type { Campaign, LeadStatus } from "../../internal/entities.ts";
2
+ import type { Runway, RunwayState } from "../../internal/runway.ts";
2
3
  import type { InsightContext } from "../define.ts";
3
4
  import type { CampaignLabel, Measured } from "./shared.ts";
4
5
  /** A figure with the range the 95% interval of the rate gives. */
@@ -28,12 +29,18 @@ export interface PipelineForecast extends CampaignLabel {
28
29
  * count, never emails sent. `null` when the vendor has no daily contacted count.
29
30
  */
30
31
  readonly dailyContactRate: number | null;
32
+ /**
33
+ * `draining`, `stalled` (leads left to start but no pace), `out_of_leads`
34
+ * (none left to start) or `unknown` (the leads left were not all counted).
35
+ * `lead_runway` returns the same state. Always set by the insight;
36
+ * optional so a value built by hand stays valid.
37
+ */
38
+ readonly runwayState?: RunwayState;
31
39
  /**
32
40
  * `notStarted` (or `remaining` when that is `null`) divided by
33
- * `dailyContactRate`, and `0` when every lead was read and none is left to
34
- * start. `null` when the leads left are unknown (the cap stopped the read,
35
- * or a lead's status is unknown) or some are left with no pace to divide by.
36
- * `lead_runway` returns the same figure as `runway_days`.
41
+ * `dailyContactRate`. `null` when the pace is `null` or 0, or the leads
42
+ * left are unknown (the cap stopped the read, or a lead's status is
43
+ * unknown). `lead_runway` returns the same figure as `runway_days`.
37
44
  */
38
45
  readonly daysLeft: number | null;
39
46
  /** The campaign's reply rate so far, over its whole history. */
@@ -58,15 +65,13 @@ export interface ForecastOptions {
58
65
  */
59
66
  readonly activeOnly?: boolean | undefined;
60
67
  }
61
- /** Reads one campaign's leads, totals and recent pace, and projects what is left. */
62
68
  /** How long a campaign's leads last: its leads by status and the recent pace of new leads started. */
63
- export declare const runwayOf: (context: InsightContext, campaign: Campaign, options: ForecastOptions) => Promise<{
69
+ export declare const readRunway: (context: InsightContext, campaign: Campaign, options: ForecastOptions) => Promise<{
70
+ active: number;
64
71
  byStatus: Record<"active" | "completed" | "paused" | "unknown" | "bounced" | "replied" | "skipped" | "unsubscribed", number>;
65
72
  complete: boolean;
66
- daysLeft: number | null;
67
73
  leadsRead: number;
68
- pace: number | null;
69
- remaining: number;
74
+ runway: Runway;
70
75
  split: import("../../internal/runway.ts").ActiveSplit;
71
76
  }>;
72
77
  export declare const forecastCampaign: (context: InsightContext, campaign: Campaign, options: ForecastOptions) => Promise<PipelineForecast>;