outbound-sdk 0.2.1 → 0.4.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 (139) hide show
  1. package/dist/alerts/index.js +50 -19
  2. package/dist/alerts/plugin.d.ts +20 -3
  3. package/dist/audit/index.js +2 -2
  4. package/dist/benchmarks/index.js +5 -5
  5. package/dist/budget/index.d.ts +3 -2
  6. package/dist/budget/index.js +11 -10
  7. package/dist/cards/content.d.ts +6 -1
  8. package/dist/cards/format.d.ts +17 -2
  9. package/dist/cards/index.d.ts +1 -1
  10. package/dist/cards/index.js +297 -132
  11. package/dist/cards/parts.d.ts +9 -2
  12. package/dist/cards/render.d.ts +20 -3
  13. package/dist/chunks/{chunk-U2D34ARZ.js → chunk-2D42TQFU.js} +3 -3
  14. package/dist/chunks/chunk-4PA526S7.js +17 -0
  15. package/dist/chunks/{chunk-6CVZOUHB.js → chunk-5CFO3CXG.js} +24 -0
  16. package/dist/chunks/{chunk-XNFESPZH.js → chunk-5FVKRIEJ.js} +168 -31
  17. package/dist/chunks/{chunk-P3IJBJUI.js → chunk-7LNJJ2RO.js} +200 -57
  18. package/dist/chunks/{chunk-XC6CZP73.js → chunk-7ZDS6SZD.js} +7 -1
  19. package/dist/chunks/{chunk-SBIZDCRY.js → chunk-A6WVOCA4.js} +4 -4
  20. package/dist/chunks/{chunk-VQSCHOBV.js → chunk-BLCJHP5H.js} +11 -4
  21. package/dist/chunks/{chunk-4PSO6JEK.js → chunk-BOWXGMN3.js} +6 -21
  22. package/dist/chunks/{chunk-DJ2IUQEU.js → chunk-C4LS2HNV.js} +3 -3
  23. package/dist/chunks/{chunk-AFU5E5QB.js → chunk-E6DSDCPI.js} +98 -69
  24. package/dist/chunks/{chunk-IPUYZD4O.js → chunk-GFDNRWR3.js} +1 -1
  25. package/dist/chunks/{chunk-PURHK3JU.js → chunk-IZFTTMJP.js} +4 -4
  26. package/dist/chunks/{chunk-E7JHLNLG.js → chunk-J7DDZ4C2.js} +15 -2
  27. package/dist/chunks/{chunk-FKH5N47I.js → chunk-K4USHN4C.js} +1 -1
  28. package/dist/chunks/chunk-LVQUSKEX.js +17 -0
  29. package/dist/chunks/{chunk-YOTW5ESM.js → chunk-PQSTQKRD.js} +2 -2
  30. package/dist/chunks/chunk-PTZO4QXR.js +15 -0
  31. package/dist/chunks/{chunk-LVYG7XZJ.js → chunk-QAKJ76HB.js} +1 -1
  32. package/dist/chunks/chunk-QGRZDTX4.js +26 -0
  33. package/dist/chunks/{chunk-R3Y56YVF.js → chunk-Y5RAJ6PZ.js} +2 -2
  34. package/dist/chunks/{chunk-RCZ7ZZFU.js → chunk-ZFVHM5JI.js} +3 -3
  35. package/dist/chunks/{chunk-UAT3JSJZ.js → chunk-ZOAG2C6V.js} +2 -2
  36. package/dist/cli/bin.js +17 -13
  37. package/dist/cli/commands.d.ts +11 -0
  38. package/dist/cli/index.js +17 -13
  39. package/dist/cli/mcp.d.ts +5 -0
  40. package/dist/clients/index.d.ts +1 -1
  41. package/dist/clients/index.js +35 -10
  42. package/dist/clients/plugin.d.ts +9 -2
  43. package/dist/combine/index.js +7 -6
  44. package/dist/exporter/index.d.ts +5 -2
  45. package/dist/exporter/index.js +2 -2
  46. package/dist/failover/index.js +3 -3
  47. package/dist/fixtures/index.js +5 -4
  48. package/dist/heyreach/client.d.ts +2 -0
  49. package/dist/heyreach/index.js +71 -39
  50. package/dist/heyreach/map.d.ts +5 -2
  51. package/dist/identity/index.js +33 -17
  52. package/dist/identity/plugin.d.ts +2 -0
  53. package/dist/index.d.ts +2 -2
  54. package/dist/index.js +13 -10
  55. package/dist/insights/campaign.d.ts +3 -0
  56. package/dist/insights/capped.d.ts +29 -0
  57. package/dist/insights/copy/copy-audit.d.ts +2 -0
  58. package/dist/insights/copy/copy-reuse.d.ts +27 -3
  59. package/dist/insights/copy/index.d.ts +8 -8
  60. package/dist/insights/copy/reply-timing.d.ts +8 -0
  61. package/dist/insights/copy/reuse-base.d.ts +32 -0
  62. package/dist/insights/copy/shared.d.ts +39 -15
  63. package/dist/insights/copy/step-funnel.d.ts +16 -5
  64. package/dist/insights/copy/variant-test.d.ts +19 -8
  65. package/dist/insights/define.d.ts +56 -2
  66. package/dist/insights/fields.d.ts +16 -0
  67. package/dist/insights/index.d.ts +2 -1
  68. package/dist/insights/index.js +1494 -730
  69. package/dist/insights/inputs.generated.d.ts +951 -0
  70. package/dist/insights/ops/campaign-diagnosis.d.ts +3 -1
  71. package/dist/insights/ops/campaign-ranking.d.ts +12 -4
  72. package/dist/insights/ops/channel-mix.d.ts +2 -1
  73. package/dist/insights/ops/client-report.d.ts +18 -5
  74. package/dist/insights/ops/index.d.ts +6 -2
  75. package/dist/insights/ops/period-comparison.d.ts +14 -3
  76. package/dist/insights/ops/pipeline-forecast.d.ts +14 -4
  77. package/dist/insights/ops/shared.d.ts +29 -24
  78. package/dist/insights/ops/tag-rollup.d.ts +2 -1
  79. package/dist/insights/people/account-summary.d.ts +13 -0
  80. package/dist/insights/people/dropped-replies.d.ts +8 -0
  81. package/dist/insights/people/find.d.ts +7 -1
  82. package/dist/insights/people/hot-leads.d.ts +16 -1
  83. package/dist/insights/people/person-summary.d.ts +6 -0
  84. package/dist/insights/people/read.d.ts +26 -10
  85. package/dist/insights/people/suppression-check.d.ts +11 -2
  86. package/dist/insights/plugin.d.ts +7 -5
  87. package/dist/insights/ref.d.ts +6 -0
  88. package/dist/insights/registry.d.ts +28 -16
  89. package/dist/insights/senders/bounce-watch.d.ts +25 -8
  90. package/dist/insights/senders/capacity-sends.d.ts +22 -0
  91. package/dist/insights/senders/domain-health.d.ts +10 -4
  92. package/dist/insights/senders/index.d.ts +14 -6
  93. package/dist/insights/senders/read.d.ts +15 -14
  94. package/dist/insights/senders/sender-capacity.d.ts +5 -13
  95. package/dist/insights/senders/sender-load.d.ts +2 -0
  96. package/dist/insights/stats.d.ts +8 -0
  97. package/dist/insights/tools.d.ts +3 -2
  98. package/dist/instantly/client.d.ts +2 -0
  99. package/dist/instantly/index.js +44 -29
  100. package/dist/instantly/map.d.ts +6 -2
  101. package/dist/internal/engine/request.d.ts +5 -0
  102. package/dist/internal/entities.d.ts +3 -20
  103. package/dist/internal/errors.d.ts +44 -0
  104. package/dist/internal/fields.d.ts +1 -1
  105. package/dist/internal/json.d.ts +9 -2
  106. package/dist/internal/lists.d.ts +24 -0
  107. package/dist/internal/numbers.d.ts +8 -0
  108. package/dist/internal/outbound/collections.d.ts +4 -0
  109. package/dist/internal/outbound/create.d.ts +24 -3
  110. package/dist/internal/outbound/outbound.d.ts +13 -1
  111. package/dist/internal/outbound/validate.d.ts +4 -0
  112. package/dist/internal/outbound/walker.d.ts +3 -2
  113. package/dist/internal/plural.d.ts +12 -0
  114. package/dist/internal/renamed.d.ts +28 -0
  115. package/dist/internal/vocabulary.d.ts +20 -0
  116. package/dist/loader/index.js +5 -5
  117. package/dist/memory/adapter.d.ts +7 -0
  118. package/dist/memory/demo-stats.d.ts +3 -0
  119. package/dist/memory/demo.d.ts +14 -3
  120. package/dist/memory/index.d.ts +1 -0
  121. package/dist/memory/index.js +200 -95
  122. package/dist/providers/index.d.ts +72 -0
  123. package/dist/providers/index.js +3 -1
  124. package/dist/reconcile/index.js +5 -4
  125. package/dist/redact/index.js +10 -4
  126. package/dist/redact/plugin.d.ts +7 -0
  127. package/dist/smartlead/index.js +102 -49
  128. package/dist/smartlead/shared.d.ts +13 -0
  129. package/dist/sync/index.js +2 -2
  130. package/dist/tools/ai-sdk.js +8 -6
  131. package/dist/tools/campaign-tools.d.ts +1 -1
  132. package/dist/tools/claude-agent.js +8 -6
  133. package/dist/tools/index.js +9 -7
  134. package/dist/tools/input-problem.d.ts +8 -0
  135. package/dist/tools/registry.d.ts +7 -2
  136. package/dist/tools/shared.d.ts +7 -0
  137. package/dist/tracing/index.js +2 -2
  138. package/dist/webhooks/index.js +10 -9
  139. package/package.json +1 -1
@@ -26,6 +26,8 @@ export interface Person {
26
26
  readonly records: readonly Lead[];
27
27
  /** Every message to and from the person across tools, oldest first. */
28
28
  readonly timeline: readonly Message[];
29
+ /** Vendor requests the lookup made. */
30
+ readonly requests: number;
29
31
  }
30
32
  export interface IdentityExtension {
31
33
  readonly person: (identifier: string, options?: PersonOptions) => Promise<Person>;
package/dist/index.d.ts CHANGED
@@ -1,12 +1,12 @@
1
1
  export { createOutbound } from "./internal/outbound/create.ts";
2
- export type { ExtensionsOf } from "./internal/outbound/create.ts";
2
+ export type { ExtensionsOf, OutboundWith } from "./internal/outbound/create.ts";
3
3
  export { Outbound } from "./internal/outbound/outbound.ts";
4
4
  export type { OutboundOptions } from "./internal/outbound/outbound.ts";
5
5
  export type { BulkOptions, BulkResult, CampaignFilters, CampaignHandle, Collection, Estimate, EstimateQuery, Include, LeadFilters, LeadHandle, ListAll, ListHandle, ListAllOptions, ListOptions, MessageFilters, NativeClient, NativeParams, NativeReads, NativeResult, OutboundApi, PageResult, RawClient, RawRequestOptions, ReadCollection, ReplyFilters, ResultMeta, SenderFilters, SenderHandle, StatsOptions, StatsResult, ThreadHandle, TopLevelStatsOptions, WebhookFilters, WithMeta, } from "./internal/outbound/api.ts";
6
6
  export type { Operation, OperationKind, OperationOutput, OutboundRecord, } from "./internal/outbound/operations.ts";
7
7
  export type { NextOperation, OperationInfo, OutboundPlugin, } from "./internal/outbound/plugins.ts";
8
8
  export { makeErrorMapper, OutboundError } from "./internal/errors.ts";
9
- export type { ErrorMapper, ErrorMapperOptions, HttpFailure, OutboundErrorCode, OutboundErrorOptions, } from "./internal/errors.ts";
9
+ export type { ErrorMapper, ErrorMapperOptions, HttpFailure, OutboundErrorCode, OutboundErrorOptions, PartialWalk, RequestLimit, } from "./internal/errors.ts";
10
10
  export * from "./internal/records.ts";
11
11
  export { defineNative } from "./internal/native.ts";
12
12
  export type { NativeCatalog, NativeParam, NativeParamsOf, NativeRead, NoNative, } from "./internal/native.ts";
package/dist/index.js CHANGED
@@ -3,10 +3,11 @@ import {
3
3
  Outbound,
4
4
  createOutbound,
5
5
  fullJitterBackoff
6
- } from "./chunks/chunk-XNFESPZH.js";
6
+ } from "./chunks/chunk-5FVKRIEJ.js";
7
7
  import {
8
8
  MemoryRateLimitStore
9
9
  } from "./chunks/chunk-4O2HRTTI.js";
10
+ import "./chunks/chunk-PTZO4QXR.js";
10
11
  import {
11
12
  defineNative
12
13
  } from "./chunks/chunk-NAKXLBA6.js";
@@ -15,7 +16,7 @@ import {
15
16
  computeRates,
16
17
  emptyCounts,
17
18
  sumCounts
18
- } from "./chunks/chunk-YOTW5ESM.js";
19
+ } from "./chunks/chunk-PQSTQKRD.js";
19
20
  import {
20
21
  profileSlug
21
22
  } from "./chunks/chunk-NAWZ73QS.js";
@@ -37,11 +38,9 @@ import {
37
38
  senderHealthSchema,
38
39
  tagSchema,
39
40
  webhookSubscriptionSchema
40
- } from "./chunks/chunk-UAT3JSJZ.js";
41
+ } from "./chunks/chunk-ZOAG2C6V.js";
41
42
  import {
42
- SCHEMA_VERSION,
43
43
  campaignSchema,
44
- campaignStatusSchema,
45
44
  channelSchema,
46
45
  eventDataSchema,
47
46
  eventTypeSchema,
@@ -54,25 +53,29 @@ import {
54
53
  metricRowSchema,
55
54
  metricScopeSchema,
56
55
  outboundEventSchema,
57
- replyCategorySchema,
58
56
  replySchema,
59
57
  senderSchema,
60
58
  senderStatusSchema,
61
59
  sequenceSchema,
62
60
  workspaceSchema
63
- } from "./chunks/chunk-4PSO6JEK.js";
61
+ } from "./chunks/chunk-BOWXGMN3.js";
62
+ import {
63
+ SCHEMA_VERSION,
64
+ campaignStatusSchema,
65
+ replyCategorySchema
66
+ } from "./chunks/chunk-QGRZDTX4.js";
64
67
  import {
65
68
  makeRef,
66
69
  parseRef
67
- } from "./chunks/chunk-LVYG7XZJ.js";
70
+ } from "./chunks/chunk-QAKJ76HB.js";
68
71
  import {
69
72
  OutboundError,
70
73
  REDACTED_EMAIL,
71
74
  REDACTED_KEY,
72
75
  makeErrorMapper,
73
76
  redactText
74
- } from "./chunks/chunk-E7JHLNLG.js";
75
- import "./chunks/chunk-VQSCHOBV.js";
77
+ } from "./chunks/chunk-J7DDZ4C2.js";
78
+ import "./chunks/chunk-BLCJHP5H.js";
76
79
  export {
77
80
  CAPABILITY_KEYS,
78
81
  DEFAULT_SHARE,
@@ -0,0 +1,3 @@
1
+ import type { InsightContext } from "./define.ts";
2
+ /** Reads the campaign, which throws `NotFound` when it does not exist. One request. */
3
+ export declare const confirmCampaign: (context: InsightContext, campaign: string) => Promise<void>;
@@ -0,0 +1,29 @@
1
+ import type { Campaign, CampaignStatus } from "../internal/entities.ts";
2
+ import type { ListAll } from "../internal/outbound/api.ts";
3
+ import type { Cap, InsightContext } from "./define.ts";
4
+ export interface Capped<Item> {
5
+ readonly items: Item[];
6
+ /** `true` when the cap stopped the read with more records left. */
7
+ readonly capped: boolean;
8
+ }
9
+ /**
10
+ * Reads up to `room` records, which is the cap unless less is left under it,
11
+ * and says so in a note naming the cap's input when more exist.
12
+ */
13
+ export declare const readCapped: <Item>(context: InsightContext, open: (max: number) => ListAll<Item>, cap: Cap, room?: number) => Promise<Capped<Item>>;
14
+ /** How many campaigns an insight read, and whether its cap left some unread. */
15
+ export interface CampaignsRead {
16
+ /** Campaigns read, in the states asked for. */
17
+ readonly campaignsRead: number;
18
+ /** `true` when `max_campaigns` stopped the read with more campaigns left. */
19
+ readonly moreCampaignsExist: boolean;
20
+ }
21
+ export declare const campaignsReadOf: (read: Capped<Campaign>) => CampaignsRead;
22
+ /**
23
+ * The campaigns in the given states, up to `max` in all. Asks the vendor per
24
+ * state when it can filter, and filters after reading when it cannot, so
25
+ * there the cap counts every campaign read. A state read after the cap is
26
+ * reached still asks for its first page, so campaigns left out are reported
27
+ * instead of silently dropped.
28
+ */
29
+ export declare const readCampaignsIn: (context: InsightContext, statuses: readonly CampaignStatus[], max: number, input?: string) => Promise<Capped<Campaign>>;
@@ -17,6 +17,8 @@ export interface CheckCount {
17
17
  }
18
18
  export interface CopyAudit {
19
19
  readonly campaign: string;
20
+ /** The campaign's name, from the campaign record the audit reads. */
21
+ readonly campaignName: string;
20
22
  readonly channel: "email" | "linkedin";
21
23
  /** `true` when no check found anything in the copy that could be read. */
22
24
  readonly clean: boolean;
@@ -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.5.0. */
11
18
  readonly trials: number | null;
19
+ /** @deprecated Use `rates.replyRate.rate`. Removed in 0.5.0. */
12
20
  readonly replyRate: number | null;
21
+ /** @deprecated Use `rates.replyRate.low` and `.high`. Removed in 0.5.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.5.0. */
38
+ readonly trials: number | null;
39
+ /** @deprecated Use `rates.replyRate.rate`. Removed in 0.5.0. */
25
40
  readonly replyRate: number | null;
41
+ /** @deprecated Use `rates.replyRate.low` and `.high`. Removed in 0.5.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.5.0. */
53
+ readonly trials: number | null;
54
+ /** @deprecated Use `low` and `high`. Removed in 0.5.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.5.0. */
9
13
  readonly replyRate: number | null;
14
+ /** @deprecated Use `rates.replyRate.low` and `.high`. Removed in 0.5.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.5.0. */
22
31
  readonly replyRate: number | null;
32
+ /** @deprecated Use `rates.replyRate.low` and `.high`. Removed in 0.5.0. */
23
33
  readonly replyRateInterval: Interval | null;
34
+ /** @deprecated Use `rates.replyRate.basis`. Removed in 0.5.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.5.0. */
20
+ readonly trials: number | null;
21
+ /** @deprecated Use `low` and `high`. Removed in 0.5.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 {};
@@ -16,11 +16,47 @@ export interface InsightMeta {
16
16
  /** When the insight was computed, ISO 8601 UTC. */
17
17
  readonly computedAt: string;
18
18
  }
19
+ /** What the redact plugin masks on an instance. */
20
+ export interface Masking {
21
+ readonly fields: readonly string[];
22
+ readonly strategy: "hash" | "mask";
23
+ /** The token the plugin writes in place of a value in a masked field. */
24
+ readonly hash?: ((value: string) => string) | undefined;
25
+ }
26
+ /**
27
+ * Says why an insight cannot answer with these fields masked, for example
28
+ * `email addresses, which it matches people by`, or `null` when it can.
29
+ */
30
+ export type MaskedOut = (masking: Masking) => string | null;
31
+ /**
32
+ * Names what this adapter does not report that the insight needs, for
33
+ * example `campaign tags`, or `null` when it reports it.
34
+ */
35
+ export type Lacks = (outbound: OutboundApi) => string | null;
36
+ /** What the redact plugin masks here, or `null` without it. */
37
+ export declare const maskingOf: (outbound: OutboundApi) => Masking | null;
38
+ /** Why the entry cannot answer under this instance's redact plugin, or `null`. */
39
+ export declare const maskedOutBy: (outbound: OutboundApi, entry: Pick<InsightEntry, "maskedOut">) => string | null;
19
40
  export interface InsightResult<Data> {
20
41
  readonly insight: string;
21
42
  readonly data: Data;
22
43
  readonly meta: InsightMeta;
23
44
  }
45
+ /**
46
+ * The cap a listing was read up to, for the note when it stops early:
47
+ * `{ input: "max_campaigns", max: 25, what: "campaigns" }` gives "Stopped at
48
+ * 25 campaigns (max_campaigns); more exist."
49
+ */
50
+ export interface Cap {
51
+ /** The cap as the caller set it, not the room left under it. */
52
+ readonly max: number;
53
+ /** What was counted, in the plural: `campaigns`, `leads of a campaign`. */
54
+ readonly what: string;
55
+ /** The input that raises the cap, or `null` for a cap no input sets. */
56
+ readonly input: string | null;
57
+ }
58
+ /** The note for a listing that a cap stopped with more records left. */
59
+ export declare const capNote: (cap: Cap) => string;
24
60
  /** What an insight reads through. Every helper records the read's cost and evidence. */
25
61
  export interface InsightContext {
26
62
  readonly outbound: OutboundApi;
@@ -31,9 +67,11 @@ export interface InsightContext {
31
67
  /**
32
68
  * Walks a listing to its end or its `max`, records the cost and returns the
33
69
  * records. When `max` cut it short the answer is marked incomplete; `cap`
34
- * names what was capped for the note, for example `50 campaigns`.
70
+ * names what was capped and the input that raises it, for the note. A
71
+ * string such as `50 campaigns` is still accepted, for insights written
72
+ * before the input could be named.
35
73
  */
36
- readonly all: <Item>(walk: ListAll<Item>, cap?: string) => Promise<Item[]>;
74
+ readonly all: <Item>(walk: ListAll<Item>, cap?: Cap | string) => Promise<Item[]>;
37
75
  /** Records one lookup's cost and returns the record. */
38
76
  readonly one: <Item>(item: WithMeta<Item>) => Item;
39
77
  /** Records a stats read's cost and returns its rows. */
@@ -61,6 +99,10 @@ export interface InsightEntry {
61
99
  readonly needs: readonly CapabilityKey[];
62
100
  /** What to ask next, for an agent. */
63
101
  readonly next: string;
102
+ /** Why the insight cannot answer while the redact plugin masks what it matches on. */
103
+ readonly maskedOut?: MaskedOut | undefined;
104
+ /** What the adapter does not report that the insight needs, beyond a capability. */
105
+ readonly lacks?: Lacks | undefined;
64
106
  /** Checks the input and the capabilities, then runs the insight. */
65
107
  readonly execute: (outbound: OutboundApi, input?: Json, options?: RunOptions) => Promise<InsightResult<Json>>;
66
108
  }
@@ -80,6 +122,18 @@ export interface InsightSpec<Key extends string, Input, Data, Given = Input> {
80
122
  */
81
123
  readonly needsFor?: ((input: Input) => readonly CapabilityKey[]) | undefined;
82
124
  readonly next: string;
125
+ /**
126
+ * What makes the insight unable to answer under the redact plugin, for an
127
+ * insight that matches records by a field redact can mask. Checked before
128
+ * any request, and an insight it refuses is not offered as a tool.
129
+ */
130
+ readonly maskedOut?: MaskedOut | undefined;
131
+ /**
132
+ * What the adapter does not report that the insight needs beyond a
133
+ * capability, such as a field its records never fill. Checked before any
134
+ * request, and an insight it refuses is not offered as a tool.
135
+ */
136
+ readonly lacks?: Lacks | undefined;
83
137
  readonly run: (context: InsightContext, input: Input) => Promise<Data>;
84
138
  }
85
139
  export interface InsightDefinition<Key extends string = string, Input = never, Data = Json, Given = Input> extends InsightEntry {
@@ -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,10 @@
1
1
  export { insights, listInsights, runInsightByName } from "./plugin.ts";
2
2
  export type { Insights, InsightsExtension } from "./plugin.ts";
3
+ export type { InsightInputs } from "./inputs.generated.ts";
3
4
  export { insightTools } from "./tools.ts";
4
5
  export type { InsightToolsOptions } from "./tools.ts";
5
6
  export { defineInsight, runInsight } from "./define.ts";
6
- export type { InsightContext, InsightDefinition, InsightMeta, InsightResult, RunOptions, } from "./define.ts";
7
+ export type { Cap, InsightContext, InsightDefinition, InsightMeta, InsightResult, RunOptions, } from "./define.ts";
7
8
  export { INSIGHTS } from "./registry.ts";
8
9
  export { compareRates, deviation, mean, median, percentile, rate, round, tally, total, wilson, zScore, } from "./stats.ts";
9
10
  export type { Interval, ProportionTest, Sample } from "./stats.ts";