outbound-sdk 0.2.1 → 0.5.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 (175) hide show
  1. package/README.md +2 -2
  2. package/dist/alerts/check-evaluate.d.ts +53 -0
  3. package/dist/alerts/check-measure.d.ts +100 -0
  4. package/dist/alerts/check-schema.d.ts +184 -0
  5. package/dist/alerts/check-validate.d.ts +18 -0
  6. package/dist/alerts/index.d.ts +7 -0
  7. package/dist/alerts/index.js +684 -20
  8. package/dist/alerts/plugin.d.ts +20 -3
  9. package/dist/audit/index.js +2 -2
  10. package/dist/benchmarks/index.js +5 -5
  11. package/dist/budget/index.d.ts +5 -2
  12. package/dist/budget/index.js +12 -10
  13. package/dist/cards/content.d.ts +6 -1
  14. package/dist/cards/format.d.ts +17 -2
  15. package/dist/cards/index.d.ts +1 -1
  16. package/dist/cards/index.js +298 -132
  17. package/dist/cards/parts.d.ts +9 -2
  18. package/dist/cards/render.d.ts +20 -3
  19. package/dist/chunks/{chunk-U2D34ARZ.js → chunk-2D42TQFU.js} +3 -3
  20. package/dist/chunks/{chunk-6CVZOUHB.js → chunk-3S32R2MH.js} +53 -63
  21. package/dist/chunks/chunk-4PA526S7.js +17 -0
  22. package/dist/chunks/{chunk-RCZ7ZZFU.js → chunk-5J7GGV62.js} +12 -5
  23. package/dist/chunks/chunk-6TKFISG4.js +676 -0
  24. package/dist/chunks/{chunk-AFU5E5QB.js → chunk-BK5SLY32.js} +104 -84
  25. package/dist/chunks/{chunk-VQSCHOBV.js → chunk-BLCJHP5H.js} +11 -4
  26. package/dist/chunks/{chunk-SBIZDCRY.js → chunk-BN6WCAWX.js} +7 -7
  27. package/dist/chunks/{chunk-4PSO6JEK.js → chunk-BOWXGMN3.js} +6 -21
  28. package/dist/chunks/{chunk-PURHK3JU.js → chunk-EHSJGQ5K.js} +8 -8
  29. package/dist/chunks/{chunk-IPUYZD4O.js → chunk-GFDNRWR3.js} +1 -1
  30. package/dist/chunks/chunk-HPNGSG5E.js +51 -0
  31. package/dist/chunks/chunk-HWHI4LFY.js +102 -0
  32. package/dist/chunks/{chunk-E7JHLNLG.js → chunk-J7DDZ4C2.js} +15 -2
  33. package/dist/chunks/{chunk-DJ2IUQEU.js → chunk-JWGSB7PT.js} +6 -6
  34. package/dist/chunks/{chunk-R3Y56YVF.js → chunk-OLPMBRXM.js} +4 -3
  35. package/dist/chunks/{chunk-YOTW5ESM.js → chunk-PQSTQKRD.js} +2 -2
  36. package/dist/chunks/chunk-PTZO4QXR.js +15 -0
  37. package/dist/chunks/{chunk-LVYG7XZJ.js → chunk-QAKJ76HB.js} +1 -1
  38. package/dist/chunks/chunk-QGRZDTX4.js +26 -0
  39. package/dist/chunks/chunk-WGW3ROLY.js +18 -0
  40. package/dist/chunks/{chunk-XC6CZP73.js → chunk-WH6V3YNN.js} +32 -1
  41. package/dist/chunks/{chunk-P3IJBJUI.js → chunk-X4RDBD4J.js} +296 -62
  42. package/dist/chunks/chunk-XL6LJVHJ.js +71 -0
  43. package/dist/chunks/{chunk-XNFESPZH.js → chunk-YYCT3NGV.js} +200 -39
  44. package/dist/chunks/{chunk-UAT3JSJZ.js → chunk-ZOAG2C6V.js} +2 -2
  45. package/dist/cli/bin.js +19 -30
  46. package/dist/cli/commands.d.ts +11 -0
  47. package/dist/cli/index.d.ts +3 -0
  48. package/dist/cli/index.js +18 -13
  49. package/dist/cli/mcp.d.ts +5 -0
  50. package/dist/cli/update.d.ts +15 -0
  51. package/dist/clients/index.d.ts +1 -1
  52. package/dist/clients/index.js +35 -10
  53. package/dist/clients/plugin.d.ts +9 -2
  54. package/dist/combine/index.js +7 -6
  55. package/dist/emailbison/account.d.ts +7 -0
  56. package/dist/emailbison/adapter.d.ts +5 -0
  57. package/dist/emailbison/capabilities.d.ts +78 -0
  58. package/dist/emailbison/client.d.ts +29 -0
  59. package/dist/emailbison/index.d.ts +30 -0
  60. package/dist/emailbison/index.js +1017 -0
  61. package/dist/emailbison/mail.d.ts +5 -0
  62. package/dist/emailbison/map-mail.d.ts +13 -0
  63. package/dist/emailbison/map-sequence.d.ts +12 -0
  64. package/dist/emailbison/map-stats.d.ts +47 -0
  65. package/dist/emailbison/map.d.ts +24 -0
  66. package/dist/emailbison/native-params.d.ts +5 -0
  67. package/dist/emailbison/native-workspace.d.ts +167 -0
  68. package/dist/emailbison/native.d.ts +327 -0
  69. package/dist/emailbison/stats.d.ts +4 -0
  70. package/dist/emailbison/webhooks.d.ts +2 -0
  71. package/dist/exporter/index.d.ts +5 -2
  72. package/dist/exporter/index.js +2 -2
  73. package/dist/failover/index.js +3 -3
  74. package/dist/fixtures/index.js +10 -9
  75. package/dist/heyreach/capabilities.d.ts +3 -0
  76. package/dist/heyreach/client.d.ts +2 -0
  77. package/dist/heyreach/index.js +83 -51
  78. package/dist/heyreach/map.d.ts +5 -2
  79. package/dist/identity/index.js +33 -17
  80. package/dist/identity/plugin.d.ts +2 -0
  81. package/dist/index.d.ts +2 -2
  82. package/dist/index.js +29 -25
  83. package/dist/insights/campaign.d.ts +3 -0
  84. package/dist/insights/capped.d.ts +29 -0
  85. package/dist/insights/copy/copy-audit.d.ts +2 -0
  86. package/dist/insights/copy/copy-reuse.d.ts +27 -3
  87. package/dist/insights/copy/index.d.ts +8 -8
  88. package/dist/insights/copy/reply-timing.d.ts +8 -0
  89. package/dist/insights/copy/reuse-base.d.ts +32 -0
  90. package/dist/insights/copy/shared.d.ts +39 -15
  91. package/dist/insights/copy/step-funnel.d.ts +16 -5
  92. package/dist/insights/copy/variant-test.d.ts +19 -8
  93. package/dist/insights/cost.d.ts +91 -0
  94. package/dist/insights/define.d.ts +78 -3
  95. package/dist/insights/fields.d.ts +16 -0
  96. package/dist/insights/index.d.ts +6 -4
  97. package/dist/insights/index.js +1816 -748
  98. package/dist/insights/inputs.generated.d.ts +951 -0
  99. package/dist/insights/ops/campaign-diagnosis.d.ts +3 -1
  100. package/dist/insights/ops/campaign-ranking.d.ts +15 -7
  101. package/dist/insights/ops/channel-mix.d.ts +2 -1
  102. package/dist/insights/ops/client-report.d.ts +18 -5
  103. package/dist/insights/ops/index.d.ts +8 -4
  104. package/dist/insights/ops/period-comparison.d.ts +14 -3
  105. package/dist/insights/ops/pipeline-forecast.d.ts +14 -4
  106. package/dist/insights/ops/shared.d.ts +39 -24
  107. package/dist/insights/ops/tag-rollup.d.ts +2 -1
  108. package/dist/insights/people/account-summary.d.ts +13 -0
  109. package/dist/insights/people/dropped-replies.d.ts +8 -0
  110. package/dist/insights/people/find.d.ts +7 -1
  111. package/dist/insights/people/hot-leads.d.ts +16 -1
  112. package/dist/insights/people/person-summary.d.ts +6 -0
  113. package/dist/insights/people/read.d.ts +26 -10
  114. package/dist/insights/people/suppression-check.d.ts +11 -2
  115. package/dist/insights/plugin.d.ts +26 -5
  116. package/dist/insights/ref.d.ts +6 -0
  117. package/dist/insights/registry.d.ts +30 -18
  118. package/dist/insights/run-cap.d.ts +35 -0
  119. package/dist/insights/senders/bounce-watch.d.ts +25 -8
  120. package/dist/insights/senders/capacity-sends.d.ts +22 -0
  121. package/dist/insights/senders/domain-health.d.ts +10 -4
  122. package/dist/insights/senders/index.d.ts +14 -6
  123. package/dist/insights/senders/read.d.ts +15 -14
  124. package/dist/insights/senders/sender-capacity.d.ts +5 -13
  125. package/dist/insights/senders/sender-load.d.ts +2 -0
  126. package/dist/insights/stats.d.ts +8 -0
  127. package/dist/insights/tools.d.ts +13 -2
  128. package/dist/instantly/capabilities.d.ts +13 -0
  129. package/dist/instantly/client.d.ts +2 -0
  130. package/dist/instantly/index.js +77 -49
  131. package/dist/instantly/map.d.ts +6 -2
  132. package/dist/internal/adapter.d.ts +12 -0
  133. package/dist/internal/engine/request.d.ts +5 -0
  134. package/dist/internal/entities.d.ts +3 -20
  135. package/dist/internal/errors.d.ts +44 -0
  136. package/dist/internal/fields.d.ts +1 -1
  137. package/dist/internal/json.d.ts +9 -2
  138. package/dist/internal/lists.d.ts +24 -0
  139. package/dist/internal/numbers.d.ts +8 -0
  140. package/dist/internal/outbound/collections.d.ts +4 -0
  141. package/dist/internal/outbound/create.d.ts +24 -3
  142. package/dist/internal/outbound/outbound.d.ts +18 -2
  143. package/dist/internal/outbound/validate.d.ts +4 -0
  144. package/dist/internal/outbound/walker.d.ts +3 -2
  145. package/dist/internal/plural.d.ts +12 -0
  146. package/dist/internal/renamed.d.ts +28 -0
  147. package/dist/internal/request-cap.d.ts +35 -0
  148. package/dist/internal/vocabulary.d.ts +20 -0
  149. package/dist/loader/index.js +5 -5
  150. package/dist/memory/adapter.d.ts +7 -0
  151. package/dist/memory/demo-stats.d.ts +3 -0
  152. package/dist/memory/demo.d.ts +14 -3
  153. package/dist/memory/index.d.ts +1 -0
  154. package/dist/memory/index.js +209 -104
  155. package/dist/providers/index.d.ts +92 -0
  156. package/dist/providers/index.js +3 -1
  157. package/dist/reconcile/index.js +5 -4
  158. package/dist/redact/index.js +13 -7
  159. package/dist/redact/plugin.d.ts +7 -0
  160. package/dist/smartlead/capabilities.d.ts +5 -0
  161. package/dist/smartlead/index.js +119 -66
  162. package/dist/smartlead/shared.d.ts +13 -0
  163. package/dist/sync/index.js +2 -2
  164. package/dist/tools/ai-sdk.js +10 -6
  165. package/dist/tools/campaign-tools.d.ts +1 -1
  166. package/dist/tools/claude-agent.js +10 -6
  167. package/dist/tools/index.d.ts +2 -2
  168. package/dist/tools/index.js +16 -9
  169. package/dist/tools/input-problem.d.ts +8 -0
  170. package/dist/tools/registry.d.ts +26 -2
  171. package/dist/tools/shared.d.ts +27 -1
  172. package/dist/tracing/index.js +2 -2
  173. package/dist/webhooks/index.js +22 -12
  174. package/package.json +8 -2
  175. package/dist/chunks/chunk-FKH5N47I.js +0 -40
@@ -1,4 +1,5 @@
1
1
  import type { Interval } from "../stats.ts";
2
+ import type { BasedRate, RateBasis } from "./shared.ts";
2
3
  export interface CopyUse {
3
4
  readonly campaign: string;
4
5
  readonly campaignName: string;
@@ -7,9 +8,17 @@ export interface CopyUse {
7
8
  readonly places: readonly string[];
8
9
  readonly sent: number | null;
9
10
  readonly replies: number | null;
10
- /** What the rate is divided by. `null` when the vendor reports no counts for this copy. */
11
+ /** Replies over leads contacted or messages sent, as `basis` says. */
12
+ readonly rates: {
13
+ readonly replyRate: BasedRate;
14
+ };
15
+ /** What the rate divides by: leads contacted or messages sent. */
16
+ readonly basis: RateBasis | null;
17
+ /** @deprecated Use `rates.replyRate.of`. Removed in 0.6.0. */
11
18
  readonly trials: number | null;
19
+ /** @deprecated Use `rates.replyRate.rate`. Removed in 0.6.0. */
12
20
  readonly replyRate: number | null;
21
+ /** @deprecated Use `rates.replyRate.low` and `.high`. Removed in 0.6.0. */
13
22
  readonly replyRateInterval: Interval | null;
14
23
  }
15
24
  export interface CopyPiece {
@@ -20,9 +29,16 @@ export interface CopyPiece {
20
29
  readonly campaigns: number;
21
30
  readonly sent: number | null;
22
31
  readonly replies: number | null;
23
- readonly trials: number | null;
24
32
  /** Replies over the base, added up across campaigns. */
33
+ readonly rates: {
34
+ readonly replyRate: BasedRate;
35
+ };
36
+ readonly basis: RateBasis | null;
37
+ /** @deprecated Use `rates.replyRate.of`. Removed in 0.6.0. */
38
+ readonly trials: number | null;
39
+ /** @deprecated Use `rates.replyRate.rate`. Removed in 0.6.0. */
25
40
  readonly replyRate: number | null;
41
+ /** @deprecated Use `rates.replyRate.low` and `.high`. Removed in 0.6.0. */
26
42
  readonly replyRateInterval: Interval | null;
27
43
  }
28
44
  export interface ReusedCopy extends CopyPiece {
@@ -41,9 +57,17 @@ export interface ReusedCopy extends CopyPiece {
41
57
  export interface CopyReuse {
42
58
  /** Copy used in two or more campaigns, widest spread first. */
43
59
  readonly reused: readonly ReusedCopy[];
44
- /** The copy with the highest pooled reply rate among those with a base of `min_sent`. `null` when none has. */
60
+ /** The copy with the highest pooled reply rate among those with a base of `min_sent`. `null` when none has, or the campaigns report no base in common. */
45
61
  readonly bestCopy: CopyPiece | null;
62
+ /**
63
+ * What every reply rate is divided by: leads contacted when every
64
+ * campaign counts them, otherwise messages sent. `null` when the campaigns
65
+ * report no base in common, so their rates are listed but not compared.
66
+ */
67
+ readonly basis: RateBasis | null;
46
68
  readonly campaignsRead: number;
69
+ /** `true` when `max_campaigns` stopped the read with more campaigns left. */
70
+ readonly moreCampaignsExist: boolean;
47
71
  readonly piecesOfCopy: number;
48
72
  /** Variants whose counts the vendor does not split out, so their copy has no numbers. */
49
73
  readonly variantsWithoutStats: number;
@@ -1,27 +1,27 @@
1
1
  export declare const COPY_INSIGHTS: readonly [import("../define.ts").InsightDefinition<"stepFunnel", {
2
- campaign: string;
3
- from: string | null;
4
2
  min_reply_rate: number;
3
+ from: string | null;
5
4
  to: string | null;
5
+ campaign: string;
6
6
  }, import("./step-funnel.ts").StepFunnel, {
7
7
  campaign: string;
8
- from?: string | null | undefined;
9
8
  min_reply_rate?: number | undefined;
9
+ from?: string | null | undefined;
10
10
  to?: string | null | undefined;
11
11
  }>, import("../define.ts").InsightDefinition<"variantTest", {
12
- alpha: number;
13
- campaign: string;
14
- from: string | null;
15
12
  metric: "positive" | "replied" | "clicked" | "opened";
16
13
  min_sent: number;
14
+ from: string | null;
17
15
  to: string | null;
16
+ alpha: number;
17
+ campaign: string;
18
18
  }, import("./variant-test.ts").VariantTest, {
19
19
  campaign: string;
20
- alpha?: number | undefined;
21
- from?: string | null | undefined;
22
20
  metric?: "positive" | "replied" | "clicked" | "opened" | undefined;
23
21
  min_sent?: number | undefined;
22
+ from?: string | null | undefined;
24
23
  to?: string | null | undefined;
24
+ alpha?: number | undefined;
25
25
  }>, import("../define.ts").InsightDefinition<"copyAudit", {
26
26
  campaign: string;
27
27
  max_body_words: number;
@@ -1,3 +1,9 @@
1
+ /**
2
+ * Over this share of replies left unpaired, the answer is partial. A reply
3
+ * to a send from before `since` cannot pair, and those are the slow ones, so
4
+ * leaving many out makes replies look faster than they are.
5
+ */
6
+ export declare const MAX_UNPAIRED_SHARE = 0.25;
1
7
  declare const WEEKDAYS: readonly ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
2
8
  export interface WeekdayCount {
3
9
  readonly weekday: (typeof WEEKDAYS)[number];
@@ -47,6 +53,8 @@ export interface ReplyTiming {
47
53
  readonly followOnReplies: number;
48
54
  /** Replies with no earlier send in what was read, no thread or lead to match on, or no time. */
49
55
  readonly unpaired: number;
56
+ /** `unpaired` over `received`. Over 0.25 the answer is marked partial. `null` with no reply. */
57
+ readonly unpairedShare: number | null;
50
58
  };
51
59
  }
52
60
  export declare const replyTiming: import("../define.ts").InsightDefinition<"replyTiming", {
@@ -0,0 +1,32 @@
1
+ import type { Campaign } from "../../internal/entities.ts";
2
+ import type { MetricCounts } from "../../internal/metrics.ts";
3
+ import type { InsightContext } from "../define.ts";
4
+ import type { Base, RateBasis } from "./shared.ts";
5
+ /** The base a placement's replies are divided by. */
6
+ export type BaseOf = (counts: MetricCounts) => Base;
7
+ export declare const pooled: (counts: readonly (MetricCounts | null)[], baseOf: BaseOf) => {
8
+ sent: number | null;
9
+ trials: number | null;
10
+ interval: import("../stats.ts").Interval | null;
11
+ basis: RateBasis | null;
12
+ count: number | null;
13
+ of: number | null;
14
+ rate: number | null;
15
+ low: number | null;
16
+ high: number | null;
17
+ };
18
+ export interface Counted {
19
+ readonly campaign: Campaign;
20
+ readonly counts: MetricCounts;
21
+ }
22
+ export interface SharedBase {
23
+ readonly baseOf: BaseOf;
24
+ readonly basis: RateBasis | null;
25
+ readonly comparable: boolean;
26
+ }
27
+ /**
28
+ * One base for every rate: leads contacted when every campaign counts them,
29
+ * otherwise messages sent. Without one they all report, each placement keeps
30
+ * its own and a note says the rates are not compared.
31
+ */
32
+ export declare const sharedBaseOf: (context: InsightContext, counted: readonly Counted[]) => SharedBase;
@@ -1,20 +1,12 @@
1
- import { z } from "zod";
2
- import type { Campaign, CampaignStatus, MetricRow } from "../../internal/entities.ts";
1
+ import type { MetricRow } from "../../internal/entities.ts";
3
2
  import type { MetricCounts } from "../../internal/metrics.ts";
4
- import type { ListAll } from "../../internal/outbound/api.ts";
5
- import type { InsightContext } from "../define.ts";
3
+ import type { Measured as Rate } from "../ops/shared.ts";
6
4
  import type { Interval } from "../stats.ts";
7
- /** A `YYYY-MM-DD` input that defaults to `null`, meaning no bound. */
8
- export declare const dayInput: (description: string) => z.ZodDefault<z.ZodNullable<z.ZodString>>;
9
5
  export interface DayRange {
10
6
  readonly from: string | undefined;
11
7
  readonly to: string | undefined;
12
8
  }
13
9
  export declare const rangeOf: (from: string | null, to: string | null) => DayRange;
14
- /** Reads a listing up to `max` records; a listing that holds more is reported as cut off. */
15
- export declare const readCapped: <Item>(context: InsightContext, walk: (max: number) => ListAll<Item>, max: number) => Promise<Item[]>;
16
- /** The campaigns in the given statuses, up to `max` in all. */
17
- export declare const campaignsIn: (context: InsightContext, statuses: readonly CampaignStatus[], max: number) => Promise<Campaign[]>;
18
10
  export type RateBasis = "contacted" | "delivered" | "sent";
19
11
  export interface Base {
20
12
  /** What the rate is divided by. `null` when the vendor reports no base. */
@@ -25,15 +17,46 @@ export interface Base {
25
17
  export declare const perLead: (counts: MetricCounts) => Base;
26
18
  /** Opens and clicks are counted per message delivered, or per message sent. */
27
19
  export declare const perMessage: (counts: MetricCounts) => Base;
28
- export interface Measured {
29
- readonly count: number | null;
30
- readonly trials: number | null;
20
+ /** The counts' base of one kind, or no base when they do not report it. */
21
+ export declare const baseIn: (counts: MetricCounts, basis: RateBasis) => Base;
22
+ declare const ORDER: {
23
+ readonly lead: readonly ["contacted", "sent"];
24
+ readonly message: readonly ["delivered", "sent"];
25
+ };
26
+ export interface SharedBases {
27
+ /** One base per entry of counts, in order. */
28
+ readonly bases: readonly Base[];
29
+ /** The base every entry is divided by. `null` when they are not comparable or none reports a base. */
30
+ readonly basis: RateBasis | null;
31
+ /** `false` when no one base is reported by every entry, so each has its own and they cannot be compared. */
32
+ readonly comparable: boolean;
33
+ }
34
+ /**
35
+ * One base for counts that are compared with each other: the first in the
36
+ * usual order that every entry with a base reports. One variant divided by
37
+ * leads contacted and another by messages sent would differ for no reason
38
+ * but the base.
39
+ */
40
+ export declare const sharedBases: (counts: readonly MetricCounts[], per: keyof typeof ORDER) => SharedBases;
41
+ /** `A per lead contacted, B per message sent`, for a note that bases differ. */
42
+ export declare const basesInWords: (named: readonly {
43
+ readonly name: string;
31
44
  readonly basis: RateBasis | null;
32
- readonly rate: number | null;
33
- /** The 95% Wilson interval of the rate. `null` when the rate is unknown. */
45
+ }[]) => string;
46
+ /** A rate with its counts and 95% Wilson interval, and what it divides by. */
47
+ export interface BasedRate extends Rate {
48
+ /** What `of` counts. */
49
+ readonly basis: RateBasis | null;
50
+ }
51
+ export interface Measured extends BasedRate {
52
+ /** @deprecated Use `of`. Removed in 0.6.0. */
53
+ readonly trials: number | null;
54
+ /** @deprecated Use `low` and `high`. Removed in 0.6.0. */
34
55
  readonly interval: Interval | null;
35
56
  }
36
57
  export declare const measure: (count: number | null, base: Base) => Measured;
58
+ /** The rate alone, without the deprecated `trials` and `interval`. */
59
+ export declare const replyRateOf: (measured: Measured | null) => BasedRate;
37
60
  /** Adds rows of counts; a count no row reports stays `null`. */
38
61
  export declare const sumRows: (rows: readonly MetricRow[]) => MetricCounts;
39
62
  /** Groups values by a key, in first-seen order. */
@@ -51,3 +74,4 @@ export interface SplitStats {
51
74
  }
52
75
  /** Sorts step stats rows into steps and their variants. */
53
76
  export declare const splitStats: (rows: readonly MetricRow[]) => SplitStats;
77
+ export {};
@@ -1,12 +1,17 @@
1
1
  import type { Interval } from "../stats.ts";
2
- import type { RateBasis } from "./shared.ts";
2
+ import type { BasedRate, RateBasis } from "./shared.ts";
3
3
  export interface FunnelVariant {
4
4
  readonly variantKey: string;
5
5
  /** The hash of the variant's current copy. `null` when the sequence no longer has the variant. */
6
6
  readonly contentHash: string | null;
7
7
  readonly sent: number | null;
8
8
  readonly replies: number | null;
9
+ readonly rates: {
10
+ readonly replyRate: BasedRate;
11
+ };
12
+ /** @deprecated Use `rates.replyRate.rate`. Removed in 0.6.0. */
9
13
  readonly replyRate: number | null;
14
+ /** @deprecated Use `rates.replyRate.low` and `.high`. Removed in 0.6.0. */
10
15
  readonly replyRateInterval: Interval | null;
11
16
  }
12
17
  export interface FunnelStep {
@@ -18,9 +23,15 @@ export interface FunnelStep {
18
23
  readonly inSequence: boolean;
19
24
  readonly sent: number | null;
20
25
  readonly replies: number | null;
21
- /** Replies divided by `replyRateBasis`. `null` when either count is unknown. */
26
+ /** Replies divided by leads contacted, or messages sent, as `basis` says. */
27
+ readonly rates: {
28
+ readonly replyRate: BasedRate;
29
+ };
30
+ /** @deprecated Use `rates.replyRate.rate`. Removed in 0.6.0. */
22
31
  readonly replyRate: number | null;
32
+ /** @deprecated Use `rates.replyRate.low` and `.high`. Removed in 0.6.0. */
23
33
  readonly replyRateInterval: Interval | null;
34
+ /** @deprecated Use `rates.replyRate.basis`. Removed in 0.6.0. */
24
35
  readonly replyRateBasis: RateBasis | null;
25
36
  /** This step's replies divided by every reply in the campaign, unattributed ones included. */
26
37
  readonly shareOfReplies: number | null;
@@ -54,13 +65,13 @@ export interface StepFunnel {
54
65
  };
55
66
  }
56
67
  export declare const stepFunnel: import("../define.ts").InsightDefinition<"stepFunnel", {
57
- campaign: string;
58
- from: string | null;
59
68
  min_reply_rate: number;
69
+ from: string | null;
60
70
  to: string | null;
71
+ campaign: string;
61
72
  }, StepFunnel, {
62
73
  campaign: string;
63
- from?: string | null | undefined;
64
74
  min_reply_rate?: number | undefined;
75
+ from?: string | null | undefined;
65
76
  to?: string | null | undefined;
66
77
  }>;
@@ -9,9 +9,16 @@ export interface TestedVariant {
9
9
  /** The metric's count. `null` when the vendor does not report it. */
10
10
  readonly count: number | null;
11
11
  /** What the rate is divided by. */
12
- readonly trials: number | null;
12
+ readonly of: number | null;
13
+ /** What `of` counts. The same for every variant of a step unless they report no base in common, and then the step is not compared. */
13
14
  readonly basis: RateBasis | null;
14
15
  readonly rate: number | null;
16
+ /** The 95% Wilson interval of the rate. `null` when the rate is unknown. */
17
+ readonly low: number | null;
18
+ readonly high: number | null;
19
+ /** @deprecated Use `of`. Removed in 0.6.0. */
20
+ readonly trials: number | null;
21
+ /** @deprecated Use `low` and `high`. Removed in 0.6.0. */
15
22
  readonly interval: Interval | null;
16
23
  /** `false` when the base is under `min_sent` or the rate is unknown; such a variant is not compared. */
17
24
  readonly enoughData: boolean;
@@ -35,8 +42,12 @@ export interface VariantTest {
35
42
  readonly campaign: string;
36
43
  readonly metric: Metric;
37
44
  readonly alpha: number;
38
- /** `false` when the vendor's step stats carry no variant rows at all. */
39
- readonly variantStatsReported: boolean;
45
+ /**
46
+ * `false` when the vendor's step stats carry no variant rows at all, and
47
+ * `null` when it reported no step stats in the date range, which cannot
48
+ * tell either way.
49
+ */
50
+ readonly variantStatsReported: boolean | null;
40
51
  /** Winners first, then steps with no difference yet, then steps with too little data. */
41
52
  readonly steps: readonly VariantStepTest[];
42
53
  readonly totals: {
@@ -47,18 +58,18 @@ export interface VariantTest {
47
58
  };
48
59
  }
49
60
  export declare const variantTest: import("../define.ts").InsightDefinition<"variantTest", {
50
- alpha: number;
51
- campaign: string;
52
- from: string | null;
53
61
  metric: "positive" | "replied" | "clicked" | "opened";
54
62
  min_sent: number;
63
+ from: string | null;
55
64
  to: string | null;
65
+ alpha: number;
66
+ campaign: string;
56
67
  }, VariantTest, {
57
68
  campaign: string;
58
- alpha?: number | undefined;
59
- from?: string | null | undefined;
60
69
  metric?: "positive" | "replied" | "clicked" | "opened" | undefined;
61
70
  min_sent?: number | undefined;
71
+ from?: string | null | undefined;
62
72
  to?: string | null | undefined;
73
+ alpha?: number | undefined;
63
74
  }>;
64
75
  export {};
@@ -0,0 +1,91 @@
1
+ import type { Capabilities } from "../internal/capabilities.ts";
2
+ import { OutboundError } from "../internal/errors.ts";
3
+ import type { OutboundApi } from "../internal/outbound/api.ts";
4
+ /**
5
+ * Prices reads on the adapter an insight runs on. Write the insight's cost
6
+ * once with it: it is evaluated at the least and at the most each read and
7
+ * count can be.
8
+ */
9
+ export interface Price {
10
+ /** What the instance can do, to price the same branches the insight takes. */
11
+ readonly capabilities: Capabilities;
12
+ /** A listing read up to `max` records: one page at the least, every page and its extras at the most. */
13
+ readonly list: (action: string, max: number) => number;
14
+ /**
15
+ * A listing read to its end, such as a lead's timeline or a thread, priced
16
+ * as one page: a thread longer than a page is not foreseen, and the 25%
17
+ * margin of the default cap absorbs the odd one.
18
+ */
19
+ readonly walk: (action: string) => number;
20
+ /** One lookup, such as `stats` or `campaigns.get`. */
21
+ readonly one: (action: string) => number;
22
+ /** Leads found by an email or a profile, up to `max`: `leads.lookup` where the adapter prices it. */
23
+ readonly lookup: (max: number) => number;
24
+ /**
25
+ * A count only the data decides, up to `max`: 0 at the least, `max` at the
26
+ * most. For example the active campaigns among those read.
27
+ */
28
+ readonly upTo: (max: number) => number;
29
+ /**
30
+ * The campaigns the insight reads, up to `max`: the number actually found
31
+ * once the listing is read, otherwise 0 at the least and `max` at the most.
32
+ */
33
+ readonly campaigns: (max: number) => number;
34
+ /**
35
+ * The campaign listing of `readCampaignsIn` for `statuses` states, up to
36
+ * `max` campaigns: one walk per state where the vendor filters by state.
37
+ */
38
+ readonly campaignsIn: (statuses: number, max: number) => number;
39
+ }
40
+ /** What a run of the insight costs, as a function of its input. */
41
+ export type InsightCost<Input> = (input: Input, price: Price) => number;
42
+ export interface Bounds {
43
+ readonly min: number;
44
+ readonly max: number;
45
+ }
46
+ /**
47
+ * The least and the most this input can cost on this instance, or `null`
48
+ * when the insight states no cost or the adapter declares none for a read it
49
+ * makes, as a combined instance does.
50
+ */
51
+ export declare const boundsOf: <Input>(outbound: OutboundApi, cost: InsightCost<Input> | undefined, input: Input, found?: number) => Bounds | null;
52
+ /**
53
+ * The cap an insight runs under when none is set: the most it can cost, a
54
+ * quarter more for retries (each retry is a request too) and 4 on top.
55
+ */
56
+ export declare const defaultCap: (bounds: Bounds | null) => number;
57
+ /** The cap a run is under, and where it came from, for the message when it stops. */
58
+ export interface CapInEffect {
59
+ readonly cap: number;
60
+ /** `true` when no cap was set and the default applies. */
61
+ readonly isDefault: boolean;
62
+ /** The setting that raises it: `maxRequests` or `maxRequestsPerToolCall`. */
63
+ readonly setting: string;
64
+ }
65
+ /** What made a run stop at its cap, for the tool result built from the error. */
66
+ export interface CapStop extends CapInEffect {
67
+ /** Requests sent before the stop. */
68
+ readonly requests: number;
69
+ /** The input to lower and the value that fits, when one does. */
70
+ readonly lower: Lower | undefined;
71
+ }
72
+ /** What a cap stop of an insight says, or `undefined` for any other error. */
73
+ export declare const capStopOf: (cause: unknown) => CapStop | undefined;
74
+ export declare const capError: (message: string, stop: CapStop, provider: string) => OutboundError;
75
+ /** The error for a run refused before a request it cannot afford. */
76
+ export declare const refusal: (name: string, bounds: Bounds, room: number, stop: CapStop, provider: string) => OutboundError;
77
+ /** The error for a run that reached its cap part way. */
78
+ export declare const stopped: (name: string, stop: CapStop, provider: string) => OutboundError;
79
+ /** An input to lower, and the value to lower it to. */
80
+ export interface Lower {
81
+ readonly input: string;
82
+ readonly to: number;
83
+ /** `true` when even the most a run can cost at that value fits; otherwise only its least does. */
84
+ readonly sure: boolean;
85
+ }
86
+ /**
87
+ * The largest value of `input` under its current one at which a run fits in
88
+ * `room`: where the most it can cost fits, or failing that where its least
89
+ * does. `undefined` when not even one does.
90
+ */
91
+ export declare const fitting: <Input>(outbound: OutboundApi, cost: InsightCost<Input>, input: Input, name: string, room: number, found?: number) => Lower | undefined;
@@ -3,6 +3,8 @@ import type { CapabilityKey } from "../internal/capabilities.ts";
3
3
  import type { Evidence, MetricRow } from "../internal/entities.ts";
4
4
  import type { Json } from "../internal/json.ts";
5
5
  import type { ListAll, OutboundApi, PageResult, StatsResult, WithMeta } from "../internal/outbound/api.ts";
6
+ import type { InsightCost } from "./cost.ts";
7
+ import type { CapOptions } from "./run-cap.ts";
6
8
  export interface InsightMeta {
7
9
  /** `exact` only when every read behind the answer was exact. */
8
10
  readonly evidence: Evidence;
@@ -16,11 +18,47 @@ export interface InsightMeta {
16
18
  /** When the insight was computed, ISO 8601 UTC. */
17
19
  readonly computedAt: string;
18
20
  }
21
+ /** What the redact plugin masks on an instance. */
22
+ export interface Masking {
23
+ readonly fields: readonly string[];
24
+ readonly strategy: "hash" | "mask";
25
+ /** The token the plugin writes in place of a value in a masked field. */
26
+ readonly hash?: ((value: string) => string) | undefined;
27
+ }
28
+ /**
29
+ * Says why an insight cannot answer with these fields masked, for example
30
+ * `email addresses, which it matches people by`, or `null` when it can.
31
+ */
32
+ export type MaskedOut = (masking: Masking) => string | null;
33
+ /**
34
+ * Names what this adapter does not report that the insight needs, for
35
+ * example `campaign tags`, or `null` when it reports it.
36
+ */
37
+ export type Lacks = (outbound: OutboundApi) => string | null;
38
+ /** What the redact plugin masks here, or `null` without it. */
39
+ export declare const maskingOf: (outbound: OutboundApi) => Masking | null;
40
+ /** Why the entry cannot answer under this instance's redact plugin, or `null`. */
41
+ export declare const maskedOutBy: (outbound: OutboundApi, entry: Pick<InsightEntry, "maskedOut">) => string | null;
19
42
  export interface InsightResult<Data> {
20
43
  readonly insight: string;
21
44
  readonly data: Data;
22
45
  readonly meta: InsightMeta;
23
46
  }
47
+ /**
48
+ * The cap a listing was read up to, for the note when it stops early:
49
+ * `{ input: "max_campaigns", max: 25, what: "campaigns" }` gives "Stopped at
50
+ * 25 campaigns (max_campaigns); more exist."
51
+ */
52
+ export interface Cap {
53
+ /** The cap as the caller set it, not the room left under it. */
54
+ readonly max: number;
55
+ /** What was counted, in the plural: `campaigns`, `leads of a campaign`. */
56
+ readonly what: string;
57
+ /** The input that raises the cap, or `null` for a cap no input sets. */
58
+ readonly input: string | null;
59
+ }
60
+ /** The note for a listing that a cap stopped with more records left. */
61
+ export declare const capNote: (cap: Cap) => string;
24
62
  /** What an insight reads through. Every helper records the read's cost and evidence. */
25
63
  export interface InsightContext {
26
64
  readonly outbound: OutboundApi;
@@ -31,9 +69,11 @@ export interface InsightContext {
31
69
  /**
32
70
  * Walks a listing to its end or its `max`, records the cost and returns the
33
71
  * records. When `max` cut it short the answer is marked incomplete; `cap`
34
- * names what was capped for the note, for example `50 campaigns`.
72
+ * names what was capped and the input that raises it, for the note. A
73
+ * string such as `50 campaigns` is still accepted, for insights written
74
+ * before the input could be named.
35
75
  */
36
- readonly all: <Item>(walk: ListAll<Item>, cap?: string) => Promise<Item[]>;
76
+ readonly all: <Item>(walk: ListAll<Item>, cap?: Cap | string) => Promise<Item[]>;
37
77
  /** Records one lookup's cost and returns the record. */
38
78
  readonly one: <Item>(item: WithMeta<Item>) => Item;
39
79
  /** Records a stats read's cost and returns its rows. */
@@ -42,8 +82,13 @@ export interface InsightContext {
42
82
  readonly note: (text: string) => void;
43
83
  /** Marks the answer as covering part of the data, with the reason as a note. */
44
84
  readonly partial: (reason: string) => void;
85
+ /**
86
+ * Says how many campaigns the insight found, once its campaign listing is
87
+ * read. A run whose least cost for that many is over its cap stops there.
88
+ */
89
+ readonly campaignsFound: (count: number) => void;
45
90
  }
46
- export interface RunOptions {
91
+ export interface RunOptions extends CapOptions {
47
92
  /** Replaces the clock. Meant for tests. */
48
93
  readonly now?: number | undefined;
49
94
  }
@@ -61,6 +106,14 @@ export interface InsightEntry {
61
106
  readonly needs: readonly CapabilityKey[];
62
107
  /** What to ask next, for an agent. */
63
108
  readonly next: string;
109
+ /** Why the insight cannot answer while the redact plugin masks what it matches on. */
110
+ readonly maskedOut?: MaskedOut | undefined;
111
+ /** What the adapter does not report that the insight needs, beyond a capability. */
112
+ readonly lacks?: Lacks | undefined;
113
+ /** What a run costs, for the default cap and the check before the first request. */
114
+ readonly cost?: InsightCost<never> | undefined;
115
+ /** The input that makes the insight cheaper when lowered, named in cap messages. */
116
+ readonly scales?: string | undefined;
64
117
  /** Checks the input and the capabilities, then runs the insight. */
65
118
  readonly execute: (outbound: OutboundApi, input?: Json, options?: RunOptions) => Promise<InsightResult<Json>>;
66
119
  }
@@ -80,12 +133,34 @@ export interface InsightSpec<Key extends string, Input, Data, Given = Input> {
80
133
  */
81
134
  readonly needsFor?: ((input: Input) => readonly CapabilityKey[]) | undefined;
82
135
  readonly next: string;
136
+ /**
137
+ * What makes the insight unable to answer under the redact plugin, for an
138
+ * insight that matches records by a field redact can mask. Checked before
139
+ * any request, and an insight it refuses is not offered as a tool.
140
+ */
141
+ readonly maskedOut?: MaskedOut | undefined;
142
+ /**
143
+ * What the adapter does not report that the insight needs beyond a
144
+ * capability, such as a field its records never fill. Checked before any
145
+ * request, and an insight it refuses is not offered as a tool.
146
+ */
147
+ readonly lacks?: Lacks | undefined;
148
+ /**
149
+ * What a run costs in vendor requests, written once with `price`. It is
150
+ * worked out at the least and the most every read can cost: the most sets
151
+ * the default cap, and a run whose least is over its cap is refused before
152
+ * the first request. Without it the insight has no default cap.
153
+ */
154
+ readonly cost?: InsightCost<Input> | undefined;
155
+ /** The input that makes a run cheaper when lowered, such as `max_campaigns`. */
156
+ readonly scales?: (keyof Input & string) | undefined;
83
157
  readonly run: (context: InsightContext, input: Input) => Promise<Data>;
84
158
  }
85
159
  export interface InsightDefinition<Key extends string = string, Input = never, Data = Json, Given = Input> extends InsightEntry {
86
160
  readonly key: Key;
87
161
  readonly inputSchema: ZodObject & ZodType<Input, Given>;
88
162
  readonly run: (context: InsightContext, input: Input) => Promise<Data>;
163
+ readonly cost?: InsightCost<Input> | undefined;
89
164
  /** Never set. It carries the caller's input type to `outbound.insights`. */
90
165
  readonly given?: Given;
91
166
  }
@@ -0,0 +1,16 @@
1
+ import { z } from "zod";
2
+ import type { CampaignStatus } from "../internal/entities.ts";
3
+ /** `from` and `to`: an inclusive range of UTC days, where `null` is no bound. */
4
+ export declare const rangeFields: {
5
+ from: z.ZodDefault<z.ZodNullable<z.ZodISODate>>;
6
+ to: z.ZodDefault<z.ZodNullable<z.ZodISODate>>;
7
+ };
8
+ /** `statuses`: only campaigns in one of these states are read. */
9
+ export declare const statusesInput: (fallback: readonly [CampaignStatus, ...CampaignStatus[]]) => z.ZodDefault<z.ZodArray<z.ZodEnum<{
10
+ active: "active";
11
+ archived: "archived";
12
+ completed: "completed";
13
+ draft: "draft";
14
+ paused: "paused";
15
+ unknown: "unknown";
16
+ }>>>;
@@ -1,9 +1,11 @@
1
- export { insights, listInsights, runInsightByName } from "./plugin.ts";
2
- export type { Insights, InsightsExtension } from "./plugin.ts";
3
- export { insightTools } from "./tools.ts";
1
+ export { insightCost, insights, listInsights, runInsightByName, } from "./plugin.ts";
2
+ export type { InsightCostEstimate, Insights, InsightsExtension, } from "./plugin.ts";
3
+ export type { InsightCost, Price } from "./cost.ts";
4
+ export type { InsightInputs } from "./inputs.generated.ts";
5
+ export { INSIGHT_TOOL_CEILING, insightTools } from "./tools.ts";
4
6
  export type { InsightToolsOptions } from "./tools.ts";
5
7
  export { defineInsight, runInsight } from "./define.ts";
6
- export type { InsightContext, InsightDefinition, InsightMeta, InsightResult, RunOptions, } from "./define.ts";
8
+ export type { Cap, InsightContext, InsightDefinition, InsightMeta, InsightResult, RunOptions, } from "./define.ts";
7
9
  export { INSIGHTS } from "./registry.ts";
8
10
  export { compareRates, deviation, mean, median, percentile, rate, round, tally, total, wilson, zScore, } from "./stats.ts";
9
11
  export type { Interval, ProportionTest, Sample } from "./stats.ts";