outbound-sdk 0.12.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 (67) hide show
  1. package/dist/alerts/index.js +1 -1
  2. package/dist/budget/index.js +1 -1
  3. package/dist/cards/index.js +16 -8
  4. package/dist/chunks/{chunk-AWNH4I5D.js → chunk-6BSFR5SF.js} +3 -0
  5. package/dist/chunks/{chunk-KNWJIJVO.js → chunk-BTIJ24UY.js} +17 -6
  6. package/dist/chunks/{chunk-HDTOGEVN.js → chunk-EAG5NIPM.js} +85 -27
  7. package/dist/chunks/{chunk-B72F56HF.js → chunk-FT6HMMMP.js} +1 -1
  8. package/dist/chunks/{chunk-CTRYCW4G.js → chunk-LJNU4LAR.js} +1471 -857
  9. package/dist/chunks/{chunk-HXCZMMSD.js → chunk-NLYGMVXS.js} +9 -0
  10. package/dist/chunks/{chunk-3DDYXUDG.js → chunk-OE45PREW.js} +1 -1
  11. package/dist/chunks/{chunk-2ADIGC2N.js → chunk-OP2GL7ZT.js} +2 -2
  12. package/dist/chunks/{chunk-UIINRLHQ.js → chunk-PDYE6CWS.js} +130 -62
  13. package/dist/chunks/{chunk-UWNQEQIX.js → chunk-PUIHJFK4.js} +1 -1
  14. package/dist/chunks/{tools-EKLZKXZU.js → tools-VCCH3JNL.js} +11 -5
  15. package/dist/cli/bin.js +9 -9
  16. package/dist/cli/config.d.ts +0 -2
  17. package/dist/cli/index.js +8 -8
  18. package/dist/cli/offered.d.ts +31 -2
  19. package/dist/cli/serve.d.ts +4 -2
  20. package/dist/combine/index.js +26 -4
  21. package/dist/emailbison/index.js +2 -2
  22. package/dist/fixtures/index.js +1 -1
  23. package/dist/heyreach/index.js +4 -1
  24. package/dist/index.js +3 -3
  25. package/dist/insights/capped.d.ts +14 -1
  26. package/dist/insights/define.d.ts +7 -5
  27. package/dist/insights/index.d.ts +1 -1
  28. package/dist/insights/index.js +10 -60
  29. package/dist/insights/inputs.generated.d.ts +26 -14
  30. package/dist/insights/ops/campaign-ranking.d.ts +8 -1
  31. package/dist/insights/ops/client-report.d.ts +28 -18
  32. package/dist/insights/ops/client-runway.d.ts +43 -0
  33. package/dist/insights/ops/index.d.ts +6 -1
  34. package/dist/insights/ops/period-comparison.d.ts +23 -1
  35. package/dist/insights/ops/pipeline-forecast.d.ts +14 -9
  36. package/dist/insights/ops/shared.d.ts +38 -1
  37. package/dist/insights/people/coverage.d.ts +26 -0
  38. package/dist/insights/people/dropped-replies-check.d.ts +5 -1
  39. package/dist/insights/people/dropped-replies.d.ts +6 -2
  40. package/dist/insights/people/index.d.ts +2 -2
  41. package/dist/insights/people/lead-collisions.d.ts +18 -1
  42. package/dist/insights/people/suppression-check.d.ts +18 -1
  43. package/dist/insights/people/thread-contexts.d.ts +2 -2
  44. package/dist/insights/people/thread-read.d.ts +11 -0
  45. package/dist/insights/registry.d.ts +6 -2
  46. package/dist/insights/tools.d.ts +35 -2
  47. package/dist/instantly/index.js +108 -22
  48. package/dist/instantly/lead-ids.d.ts +11 -0
  49. package/dist/instantly/map-lead.d.ts +19 -2
  50. package/dist/internal/entities.d.ts +4 -1
  51. package/dist/internal/fields.d.ts +2 -0
  52. package/dist/internal/reply-people.d.ts +25 -7
  53. package/dist/internal/runway.d.ts +38 -5
  54. package/dist/loader/index.js +1 -1
  55. package/dist/memory/index.js +1 -1
  56. package/dist/redact/index.d.ts +1 -1
  57. package/dist/redact/index.js +59 -28
  58. package/dist/redact/plugin.d.ts +13 -11
  59. package/dist/redact/tokens.d.ts +18 -1
  60. package/dist/smartlead/index.js +4 -1
  61. package/dist/tools/ai-sdk.js +3 -3
  62. package/dist/tools/claude-agent.js +3 -3
  63. package/dist/tools/index.js +4 -4
  64. package/dist/tools/registry.d.ts +8 -1
  65. package/dist/webhooks/index.js +2 -2
  66. package/package.json +1 -1
  67. /package/dist/chunks/{chunk-TOZKA7JR.js → chunk-HNYJO6B4.js} +0 -0
@@ -22,8 +22,21 @@ export interface CampaignsRead {
22
22
  export declare const campaignsReadOf: (read: Capped<Campaign>) => CampaignsRead;
23
23
  /** `active`, `active or paused`, `active, paused or completed`. */
24
24
  export declare const either: (words: readonly string[]) => string;
25
+ /** A tool of a combined instance none of whose campaigns was read, because none is in the states asked for. */
26
+ export interface SkippedTool {
27
+ /** The tool's `provider:workspaceId`. */
28
+ readonly tool: string;
29
+ readonly provider: string;
30
+ readonly workspaceId: string;
31
+ /** Why none of its campaigns was read. */
32
+ readonly reason: string;
33
+ }
34
+ /** The campaigns read, and the tools of a combined instance left out because none of theirs is in the states asked for. */
35
+ export interface CampaignsListed extends Capped<Campaign> {
36
+ readonly skipped: readonly SkippedTool[];
37
+ }
25
38
  /**
26
39
  * The campaigns in the given states, up to `max` in all. On a combined
27
40
  * instance `max` is shared among its tools, so each gets its share.
28
41
  */
29
- export declare const readCampaignsIn: (context: InsightContext, statuses: readonly CampaignStatus[], max: number, input?: string) => Promise<Capped<Campaign>>;
42
+ export declare const readCampaignsIn: (context: InsightContext, statuses: readonly CampaignStatus[], max: number, input?: string) => Promise<CampaignsListed>;
@@ -74,7 +74,7 @@ export interface InsightContext {
74
74
  readonly rows: (stats: StatsResult) => readonly MetricRow[];
75
75
  /**
76
76
  * Reads each item, a few side by side, and returns the results in order.
77
- * In an insight with `partialOnCap`, an item whose read a request cap
77
+ * Unless the insight sets `partialOnCap: false`, an item whose read a request cap
78
78
  * stopped is left out, and the answer is marked incomplete with a note
79
79
  * such as `Read 18 of 24 campaigns`; `what` names the items in the plural.
80
80
  * Any other failure, and every failure elsewhere, is thrown.
@@ -157,10 +157,12 @@ export interface InsightSpec<Key extends string, Input, Data, Given = Input> {
157
157
  /** The input that makes a run cheaper when lowered, such as `max_campaigns`. */
158
158
  readonly scales?: (keyof Input & string) | undefined;
159
159
  /**
160
- * `true` when the answer still means something over part of the data: a
161
- * request cap that stops `context.all` or `context.each` part way then
162
- * keeps what they read, and the answer comes back with `complete: false`
163
- * and a note naming the cap, instead of failing with `RateLimited`.
160
+ * `false` for an insight whose answer means nothing over part of the
161
+ * data. By default a request cap that stops `context.all` or
162
+ * `context.each` part way keeps what they read, and the answer comes back
163
+ * with `complete: false` and a note naming the cap, instead of throwing
164
+ * away the requests already spent; with `false` the run fails with
165
+ * `RateLimited` instead.
164
166
  */
165
167
  readonly partialOnCap?: boolean | undefined;
166
168
  readonly run: (context: InsightContext, input: Input) => Promise<Data>;
@@ -2,7 +2,7 @@ export { insightCost, insights, listInsights, runInsightByName, } from "./plugin
2
2
  export type { InsightCostEstimate, Insights, InsightsExtension, } from "./plugin.ts";
3
3
  export type { InsightCost, Price } from "./cost.ts";
4
4
  export type { InsightInputs } from "./inputs.generated.ts";
5
- export { INSIGHT_TOOL_CEILING, insightTools } from "./tools.ts";
5
+ export { INSIGHT_TOOL_CEILING, insightTools, membersOf } from "./tools.ts";
6
6
  export type { InsightToolsOptions } from "./tools.ts";
7
7
  export { defineInsight, runInsight } from "./define.ts";
8
8
  export type { Cap, InsightContext, InsightDefinition, InsightMeta, InsightResult, RunOptions, } from "./define.ts";
@@ -1,91 +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-CTRYCW4G.js";
22
- import "../chunks/chunk-KNWJIJVO.js";
23
+ } from "../chunks/chunk-LJNU4LAR.js";
24
+ import "../chunks/chunk-BTIJ24UY.js";
23
25
  import "../chunks/chunk-4PA526S7.js";
24
26
  import "../chunks/chunk-I7GBBHD2.js";
25
27
  import "../chunks/chunk-HZCTYL22.js";
26
28
  import "../chunks/chunk-HPNGSG5E.js";
27
29
  import "../chunks/chunk-PTZO4QXR.js";
28
30
  import "../chunks/chunk-FALWG5U3.js";
29
- import "../chunks/chunk-HXCZMMSD.js";
31
+ import "../chunks/chunk-NLYGMVXS.js";
30
32
  import "../chunks/chunk-CPACP4YD.js";
31
33
  import "../chunks/chunk-QGRZDTX4.js";
32
34
  import "../chunks/chunk-OPLXELPS.js";
33
35
  import "../chunks/chunk-HXB2IOJJ.js";
34
- import {
35
- OutboundError
36
- } from "../chunks/chunk-XYHM4KHC.js";
36
+ import "../chunks/chunk-XYHM4KHC.js";
37
37
  import "../chunks/chunk-45TXPJW7.js";
38
-
39
- // src/insights/plugin.ts
40
- import { z } from "zod";
41
- var entryNamed = (outbound, name) => {
42
- const entry = ENTRIES.find(
43
- (candidate) => candidate.name === name || candidate.key === name
44
- );
45
- if (entry === void 0) {
46
- throw new OutboundError(
47
- "Invalid",
48
- `There is no insight "${name}". Known: ${ENTRIES.map((each) => each.name).join(", ")}`,
49
- { provider: outbound.provider }
50
- );
51
- }
52
- return entry;
53
- };
54
- var runInsightByName = async (outbound, name, input = {}, options = {}) => await entryNamed(outbound, name).execute(outbound, input, options);
55
- var insightCost = (outbound, name, input = {}) => {
56
- const entry = entryNamed(outbound, name);
57
- const parsed = entry.inputSchema.safeParse(input);
58
- if (!parsed.success) {
59
- throw new OutboundError(
60
- "Invalid",
61
- `${entry.name}: ${parsed.error.issues[0]?.message ?? "the input is not valid"}`,
62
- { provider: outbound.provider }
63
- );
64
- }
65
- const bounds = boundsOf(outbound, entry.cost, parsed.data);
66
- return bounds === null ? null : { ...bounds, defaultCap: defaultCap(bounds) };
67
- };
68
- var listInsights = () => ENTRIES.map((entry) => ({
69
- description: entry.description,
70
- key: entry.key,
71
- name: entry.name,
72
- needs: [...entry.needs],
73
- // SAFETY: a JSON Schema document is JSON by definition.
74
- parameters: z.toJSONSchema(entry.inputSchema, { io: "input" })
75
- }));
76
- var insights = () => ({
77
- extend: (outbound) => {
78
- const methods = {};
79
- for (const entry of ENTRIES) {
80
- methods[entry.key] = (input, options) => (
81
- // SAFETY: the answer is the entry's own, typed per key by Insights.
82
- entry.execute(outbound, input, options)
83
- );
84
- }
85
- return { insights: methods };
86
- },
87
- name: "insights"
88
- });
89
38
  export {
90
39
  INSIGHTS,
91
40
  INSIGHT_TOOL_CEILING,
@@ -98,6 +47,7 @@ export {
98
47
  listInsights,
99
48
  mean,
100
49
  median,
50
+ membersOf,
101
51
  percentile,
102
52
  rate,
103
53
  round,
@@ -75,15 +75,15 @@ export interface InsightInputs {
75
75
  */
76
76
  readonly include_past?: boolean | undefined;
77
77
  /**
78
- * 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.
79
79
  *
80
- * A whole number from 1 to 200. Defaults to `20`.
80
+ * A whole number from 1 to 200. Defaults to `200`.
81
81
  */
82
82
  readonly max_campaigns?: number | undefined;
83
83
  /**
84
- * 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.
85
85
  *
86
- * A whole number from 1 to 20,000. Defaults to `500`.
86
+ * A whole number from 1 to 20,000. Defaults to `1000`.
87
87
  */
88
88
  readonly max_leads_per_campaign?: number | undefined;
89
89
  /**
@@ -102,21 +102,21 @@ export interface InsightInputs {
102
102
  */
103
103
  readonly lead_statuses?: ("active" | "bounced" | "completed" | "paused" | "replied" | "skipped" | "unknown" | "unsubscribed")[] | undefined;
104
104
  /**
105
- * 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.
106
106
  *
107
- * A whole number from 1 to 100,000. Defaults to `2000`.
107
+ * A whole number from 1 to 100,000. Defaults to `10000`.
108
108
  */
109
109
  readonly max_block_entries?: number | undefined;
110
110
  /**
111
- * 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.
112
112
  *
113
- * A whole number from 1 to 200. Defaults to `20`.
113
+ * A whole number from 1 to 200. Defaults to `200`.
114
114
  */
115
115
  readonly max_campaigns?: number | undefined;
116
116
  /**
117
- * 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.
118
118
  *
119
- * A whole number from 1 to 20,000. Defaults to `500`.
119
+ * A whole number from 1 to 20,000. Defaults to `1000`.
120
120
  */
121
121
  readonly max_leads_per_campaign?: number | undefined;
122
122
  /**
@@ -135,7 +135,7 @@ export interface InsightInputs {
135
135
  */
136
136
  readonly categories?: ("bounce" | "negative" | "neutral" | "ooo" | "positive" | "unknown" | "unsubscribe")[] | undefined;
137
137
  /**
138
- * 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
139
139
  *
140
140
  * Defaults to `false`.
141
141
  */
@@ -261,11 +261,11 @@ export interface InsightInputs {
261
261
  /** The input of `threadContext` (the `thread_context` tool). */
262
262
  readonly threadContext: {
263
263
  /**
264
- * snippet returns the first 280 characters of each message, wrapped as untrusted content; none returns no text
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
265
  *
266
- * Defaults to `"snippet"`.
266
+ * Defaults to `null`.
267
267
  */
268
- readonly bodies?: "none" | "snippet" | undefined;
268
+ readonly bodies?: "none" | "snippet" | null | undefined;
269
269
  /**
270
270
  * coverage.nextCursor from the previous call with the same leads and threads, to read the next page of conversations
271
271
  *
@@ -1073,11 +1073,23 @@ export interface InsightInputs {
1073
1073
  * A whole number from 0 to 9,007,199,254,740,991. Defaults to `50`.
1074
1074
  */
1075
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;
1076
1082
  /**
1077
1083
  * A campaign with this many days of leads left or fewer is flagged
1078
1084
  *
1079
1085
  * A number, 0 or more. Defaults to `7`.
1080
1086
  */
1081
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;
1082
1094
  };
1083
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,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,7 +3,7 @@ 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, Rates, 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
9
  * unknown. The reply and positive reply rates are over `replyRateBasis`,
@@ -56,9 +56,31 @@ export interface PeriodComparison extends CampaignsRead {
56
56
  readonly tooFewSends: readonly ThinCampaign[];
57
57
  /** Every campaign read, added together. */
58
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;
59
65
  /** The vendor's own workspace totals. `null` when the adapter has none. */
60
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[];
61
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;
62
84
  /** Compares two periods of counts: both sides, the change, and whether the reply rate really moved. */
63
85
  export declare const comparePeriods: (current: Totals, previous: Totals, alpha: number) => Comparison;
64
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>;
@@ -1,7 +1,7 @@
1
1
  import { z } from "zod";
2
2
  import type { Campaign, CampaignStatus } from "../../internal/entities.ts";
3
3
  import type { MetricCounts } from "../../internal/metrics.ts";
4
- import type { CampaignsRead } from "../capped.ts";
4
+ import type { CampaignsRead, SkippedTool } from "../capped.ts";
5
5
  import type { Price } from "../cost.ts";
6
6
  import type { InsightContext } from "../define.ts";
7
7
  /** The UTC day of a time, as `YYYY-MM-DD`. */
@@ -156,6 +156,8 @@ export interface CampaignTotals {
156
156
  export interface EveryCampaignTotals {
157
157
  readonly entries: CampaignTotals[];
158
158
  readonly read: CampaignsRead;
159
+ /** The tools of a combined instance none of whose campaigns was read. */
160
+ readonly skipped: readonly SkippedTool[];
159
161
  }
160
162
  export interface ListInput extends OpenRange {
161
163
  readonly max_campaigns: number;
@@ -169,6 +171,41 @@ export interface ListInput extends OpenRange {
169
171
  * having no counts when it has some.
170
172
  */
171
173
  export declare const readCampaignTotals: (context: InsightContext, input: ListInput) => Promise<EveryCampaignTotals>;
174
+ /**
175
+ * A tool of a combined instance left out of the answer because none of its
176
+ * campaigns is in the states asked for, with its own workspace totals for
177
+ * the period, so activity it had there is named rather than lost.
178
+ */
179
+ export interface ToolLeftOut extends SkippedTool {
180
+ /** The tool's workspace totals for the period. `null` when it has no workspace stats. */
181
+ readonly counts: Totals | null;
182
+ }
183
+ /**
184
+ * The tools left out, each with its workspace totals for the range: one
185
+ * stats request each. A note names those that sent or got replies in it.
186
+ */
187
+ export declare const toolsLeftOut: (context: InsightContext, skipped: readonly SkippedTool[], range: OpenRange) => Promise<ToolLeftOut[]>;
188
+ /**
189
+ * What a set of counts covers, so two reply figures that differ can be told
190
+ * apart. `replied` and `positive` count leads, not reply messages, with
191
+ * automatic replies left out of `replied`.
192
+ */
193
+ export interface CountsBasis {
194
+ /**
195
+ * `campaigns`: the campaigns read, added together, so only those in the
196
+ * states asked for. `workspace`: the vendor's own workspace totals, which
197
+ * count every campaign whatever its state.
198
+ */
199
+ readonly covers: "campaigns" | "workspace";
200
+ /** `people`: `replied` and `positive` count leads, not reply messages. */
201
+ readonly replies: "people";
202
+ /** Automatic replies are left out of `replied`. */
203
+ readonly autoReplies: "excluded";
204
+ /** The same, in a sentence. */
205
+ readonly description: string;
206
+ }
207
+ export declare const campaignsBasis: (campaigns: number, statuses: readonly string[]) => CountsBasis;
208
+ export declare const WORKSPACE_BASIS: CountsBasis;
172
209
  export interface DayCounts {
173
210
  /** `YYYY-MM-DD`. */
174
211
  readonly date: string;
@@ -0,0 +1,26 @@
1
+ /** One part of the data a cap left unread, and the input that raises it. */
2
+ export interface Gap {
3
+ /** What was read and what was left, for example `20 campaigns, with more unread`. */
4
+ readonly read: string;
5
+ /** The input that raises the cap, or `null` when a request cap stopped the read. */
6
+ readonly input: string | null;
7
+ }
8
+ /** What a check over campaigns read of them and of their leads. */
9
+ export interface CampaignsChecked {
10
+ readonly campaigns: number;
11
+ readonly moreCampaignsExist: boolean;
12
+ /** `true` when a request cap, not `max_campaigns`, stopped the campaign listing. */
13
+ readonly campaignsCut: boolean;
14
+ readonly campaignsWithMoreLeads: number;
15
+ /** Campaigns whose leads a request cap, not `max_leads_per_campaign`, stopped. */
16
+ readonly leadsCut: number;
17
+ readonly maxLeads: number;
18
+ }
19
+ /** The gaps in the campaigns and their leads. */
20
+ export declare const campaignGaps: (read: CampaignsChecked) => Gap[];
21
+ /**
22
+ * What a check left out, or `null` when it covered everything: "The check
23
+ * is incomplete: it read only 20 campaigns, with more in those statuses
24
+ * unread (max_campaigns). Raise max_campaigns to check the rest."
25
+ */
26
+ export declare const gapsSentence: (gaps: readonly Gap[]) => string | null;
@@ -58,6 +58,10 @@ export interface Checkable extends Conversation {
58
58
  }
59
59
  interface Checked {
60
60
  answered: number;
61
+ /** Conversations whose latest message, read in full, is an automatic reply. */
62
+ automatic: number;
63
+ /** The listed replies of those conversations. */
64
+ automaticReplies: number;
61
65
  readonly dropped: FoundDropped[];
62
66
  tooRecent: number;
63
67
  /** Conversations whose read failed. */
@@ -70,5 +74,5 @@ interface Checked {
70
74
  * and its answer may lie past the stop. The rest are read in full, since a
71
75
  * campaign send after the reply counts as an answer too.
72
76
  */
73
- export declare const check: (context: InsightContext, checkable: readonly Checkable[], sent: SentByHand | null, olderThanHours: number) => Promise<Checked>;
77
+ export declare const check: (context: InsightContext, checkable: readonly Checkable[], sent: SentByHand | null, olderThanHours: number, includeAuto: boolean) => Promise<Checked>;
74
78
  export {};