outbound-sdk 0.4.0 → 0.6.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 (104) 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 +635 -2
  8. package/dist/budget/index.d.ts +2 -0
  9. package/dist/budget/index.js +1 -0
  10. package/dist/cards/format.d.ts +1 -1
  11. package/dist/cards/index.js +49 -19
  12. package/dist/cards/parts.d.ts +1 -6
  13. package/dist/chunks/{chunk-7LNJJ2RO.js → chunk-3JOC5DGD.js} +127 -17
  14. package/dist/chunks/chunk-53DCVFUB.js +55 -0
  15. package/dist/chunks/{chunk-E6DSDCPI.js → chunk-BK5SLY32.js} +92 -101
  16. package/dist/chunks/chunk-HPNGSG5E.js +51 -0
  17. package/dist/chunks/chunk-HWHI4LFY.js +102 -0
  18. package/dist/chunks/chunk-MGR6HREO.js +91 -0
  19. package/dist/chunks/{chunk-Y5RAJ6PZ.js → chunk-OLPMBRXM.js} +3 -2
  20. package/dist/chunks/{chunk-IZFTTMJP.js → chunk-PHNQ3WC2.js} +5 -5
  21. package/dist/chunks/chunk-SXGCKCAR.js +678 -0
  22. package/dist/chunks/chunk-TFICTGM2.js +18 -0
  23. package/dist/chunks/{chunk-ZFVHM5JI.js → chunk-UWUPUMM2.js} +11 -4
  24. package/dist/chunks/{chunk-A6WVOCA4.js → chunk-W22SDX6S.js} +4 -4
  25. package/dist/chunks/{chunk-7ZDS6SZD.js → chunk-WH6V3YNN.js} +25 -0
  26. package/dist/chunks/chunk-XL6LJVHJ.js +71 -0
  27. package/dist/chunks/{chunk-5FVKRIEJ.js → chunk-YYCT3NGV.js} +35 -11
  28. package/dist/cli/bin.js +13 -28
  29. package/dist/cli/index.d.ts +3 -0
  30. package/dist/cli/index.js +12 -11
  31. package/dist/cli/output.d.ts +9 -0
  32. package/dist/cli/update.d.ts +15 -0
  33. package/dist/emailbison/account.d.ts +7 -0
  34. package/dist/emailbison/adapter.d.ts +5 -0
  35. package/dist/emailbison/capabilities.d.ts +78 -0
  36. package/dist/emailbison/client.d.ts +29 -0
  37. package/dist/emailbison/index.d.ts +30 -0
  38. package/dist/emailbison/index.js +1018 -0
  39. package/dist/emailbison/mail.d.ts +5 -0
  40. package/dist/emailbison/map-mail.d.ts +13 -0
  41. package/dist/emailbison/map-sequence.d.ts +12 -0
  42. package/dist/emailbison/map-stats.d.ts +47 -0
  43. package/dist/emailbison/map.d.ts +24 -0
  44. package/dist/emailbison/native-params.d.ts +5 -0
  45. package/dist/emailbison/native-workspace.d.ts +167 -0
  46. package/dist/emailbison/native.d.ts +327 -0
  47. package/dist/emailbison/stats.d.ts +4 -0
  48. package/dist/emailbison/webhooks.d.ts +2 -0
  49. package/dist/fixtures/index.js +6 -6
  50. package/dist/heyreach/capabilities.d.ts +3 -0
  51. package/dist/heyreach/index.js +22 -20
  52. package/dist/index.js +19 -18
  53. package/dist/insights/copy/copy-preview.d.ts +58 -0
  54. package/dist/insights/copy/copy-reuse.d.ts +0 -13
  55. package/dist/insights/copy/index.d.ts +9 -0
  56. package/dist/insights/copy/reuse-base.d.ts +0 -2
  57. package/dist/insights/copy/shared.d.ts +3 -8
  58. package/dist/insights/copy/step-funnel.d.ts +1 -12
  59. package/dist/insights/copy/variant-test.d.ts +0 -5
  60. package/dist/insights/cost.d.ts +91 -0
  61. package/dist/insights/define.d.ts +22 -1
  62. package/dist/insights/index.d.ts +4 -3
  63. package/dist/insights/index.js +810 -415
  64. package/dist/insights/inputs.generated.d.ts +21 -24
  65. package/dist/insights/ops/campaign-diagnosis.d.ts +0 -2
  66. package/dist/insights/ops/campaign-ranking.d.ts +3 -3
  67. package/dist/insights/ops/client-report.d.ts +0 -2
  68. package/dist/insights/ops/index.d.ts +2 -6
  69. package/dist/insights/ops/shared.d.ts +10 -2
  70. package/dist/insights/plugin.d.ts +19 -0
  71. package/dist/insights/registry.d.ts +10 -10
  72. package/dist/insights/run-cap.d.ts +35 -0
  73. package/dist/insights/senders/bounce-watch.d.ts +0 -11
  74. package/dist/insights/senders/domain-health.d.ts +0 -7
  75. package/dist/insights/senders/index.d.ts +0 -4
  76. package/dist/insights/senders/sender-load.d.ts +0 -2
  77. package/dist/insights/tools.d.ts +10 -0
  78. package/dist/insights/types.d.ts +1 -1
  79. package/dist/insights/variables.d.ts +33 -0
  80. package/dist/instantly/capabilities.d.ts +13 -0
  81. package/dist/instantly/index.js +43 -28
  82. package/dist/internal/adapter.d.ts +12 -0
  83. package/dist/internal/outbound/outbound.d.ts +5 -1
  84. package/dist/internal/request-cap.d.ts +35 -0
  85. package/dist/loader/index.js +2 -2
  86. package/dist/memory/index.js +10 -10
  87. package/dist/providers/index.d.ts +21 -1
  88. package/dist/providers/index.js +1 -1
  89. package/dist/redact/index.js +4 -4
  90. package/dist/smartlead/capabilities.d.ts +5 -0
  91. package/dist/smartlead/index.js +26 -24
  92. package/dist/tools/ai-sdk.js +5 -3
  93. package/dist/tools/claude-agent.js +5 -3
  94. package/dist/tools/index.d.ts +2 -2
  95. package/dist/tools/index.js +11 -6
  96. package/dist/tools/registry.d.ts +20 -1
  97. package/dist/tools/shared.d.ts +20 -1
  98. package/dist/webhooks/index.js +17 -7
  99. package/package.json +8 -2
  100. package/dist/chunks/chunk-5CFO3CXG.js +0 -176
  101. package/dist/chunks/chunk-K4USHN4C.js +0 -40
  102. package/dist/chunks/chunk-LVQUSKEX.js +0 -17
  103. package/dist/internal/renamed.d.ts +0 -28
  104. package/dist/chunks/{chunk-C4LS2HNV.js → chunk-JWGSB7PT.js} +3 -3
@@ -29,10 +29,12 @@ export declare const costs: {
29
29
  "leads.list": {
30
30
  pageSize: number;
31
31
  perPage: number;
32
+ perWalk: number;
32
33
  };
33
34
  "leads.lookup": {
34
35
  pageSize: number;
35
36
  perPage: number;
37
+ perWalk: number;
36
38
  };
37
39
  "lists.list": {
38
40
  pageSize: number;
@@ -55,6 +57,7 @@ export declare const costs: {
55
57
  "senders.list": {
56
58
  pageSize: number;
57
59
  perPage: number;
60
+ perWalk: number;
58
61
  };
59
62
  "sequence.get": {
60
63
  perPage: number;
@@ -1,27 +1,40 @@
1
1
  import {
2
2
  EVENT_TYPES,
3
3
  heyreachEvents
4
- } from "../chunks/chunk-C4LS2HNV.js";
4
+ } from "../chunks/chunk-JWGSB7PT.js";
5
5
  import {
6
- createVendorClient,
7
- listIn,
8
6
  mapPage,
9
- normalizeBody,
10
7
  withLeadFields,
11
8
  withMappedFields
12
- } from "../chunks/chunk-5CFO3CXG.js";
9
+ } from "../chunks/chunk-XL6LJVHJ.js";
13
10
  import {
11
+ createVendorClient,
14
12
  leadStanding,
13
+ listIn,
15
14
  toVariant,
16
15
  variantKey
17
- } from "../chunks/chunk-K4USHN4C.js";
16
+ } from "../chunks/chunk-MGR6HREO.js";
17
+ import {
18
+ normalizeBody
19
+ } from "../chunks/chunk-53DCVFUB.js";
18
20
  import {
19
21
  defineNative
20
22
  } from "../chunks/chunk-NAKXLBA6.js";
23
+ import {
24
+ eventTypesOf,
25
+ recordBase,
26
+ refTo,
27
+ refsTo
28
+ } from "../chunks/chunk-2D42TQFU.js";
29
+ import "../chunks/chunk-BOWXGMN3.js";
21
30
  import {
22
31
  emptyCounts,
23
32
  metricRow
24
33
  } from "../chunks/chunk-PQSTQKRD.js";
34
+ import "../chunks/chunk-QGRZDTX4.js";
35
+ import {
36
+ assertWorkspaceId
37
+ } from "../chunks/chunk-QAKJ76HB.js";
25
38
  import {
26
39
  profileSlug
27
40
  } from "../chunks/chunk-NAWZ73QS.js";
@@ -32,17 +45,6 @@ import {
32
45
  readEnv,
33
46
  requireCredential
34
47
  } from "../chunks/chunk-GFDNRWR3.js";
35
- import {
36
- eventTypesOf,
37
- recordBase,
38
- refTo,
39
- refsTo
40
- } from "../chunks/chunk-2D42TQFU.js";
41
- import "../chunks/chunk-BOWXGMN3.js";
42
- import "../chunks/chunk-QGRZDTX4.js";
43
- import {
44
- assertWorkspaceId
45
- } from "../chunks/chunk-QAKJ76HB.js";
46
48
  import {
47
49
  OutboundError,
48
50
  isHttpFailure,
@@ -488,12 +490,12 @@ var costs = {
488
490
  "leads.get": { perPage: 2 },
489
491
  // A campaign's leads. A saved list's leads come up to 1000 a page. Without
490
492
  // a campaign or a list, each new page of campaigns costs one more request.
491
- "leads.list": { pageSize: PAGE_SIZE, perPage: 1 },
493
+ "leads.list": { pageSize: PAGE_SIZE, perPage: 1, perWalk: 1 },
492
494
  // One person by profile URL: the campaigns and the profile, two requests.
493
495
  // By email it is three (campaigns, the lists the address is in, a name
494
496
  // search in one list) and one more per profile read to find the address,
495
497
  // eight at most; a later page is two again.
496
- "leads.lookup": { pageSize: PAGE_SIZE, perPage: 2 },
498
+ "leads.lookup": { pageSize: PAGE_SIZE, perPage: 2, perWalk: 6 },
497
499
  "lists.list": { pageSize: PAGE_SIZE, perPage: 1 },
498
500
  // One conversation by thread id is a single request.
499
501
  "messages.list": { pageSize: PAGE_SIZE, perPage: 1 },
@@ -501,7 +503,7 @@ var costs = {
501
503
  "senders.get": { perPage: 1 },
502
504
  "senders.health": { perPage: 1 },
503
505
  // A campaign's senders cost one more request, once, to read the campaign.
504
- "senders.list": { pageSize: PAGE_SIZE, perPage: 1 },
506
+ "senders.list": { pageSize: PAGE_SIZE, perPage: 1, perWalk: 1 },
505
507
  "sequence.get": { perPage: 1 },
506
508
  stats: { perPage: 1 },
507
509
  "webhooks.list": { pageSize: PAGE_SIZE, perPage: 1 }
package/dist/index.js CHANGED
@@ -3,27 +3,11 @@ import {
3
3
  Outbound,
4
4
  createOutbound,
5
5
  fullJitterBackoff
6
- } from "./chunks/chunk-5FVKRIEJ.js";
6
+ } from "./chunks/chunk-YYCT3NGV.js";
7
7
  import {
8
8
  MemoryRateLimitStore
9
9
  } from "./chunks/chunk-4O2HRTTI.js";
10
- import "./chunks/chunk-PTZO4QXR.js";
11
- import {
12
- defineNative
13
- } from "./chunks/chunk-NAKXLBA6.js";
14
- import {
15
- METRIC_DEFINITIONS,
16
- computeRates,
17
- emptyCounts,
18
- sumCounts
19
- } from "./chunks/chunk-PQSTQKRD.js";
20
- import {
21
- profileSlug
22
- } from "./chunks/chunk-NAWZ73QS.js";
23
- import {
24
- sha256Hex,
25
- stableId
26
- } from "./chunks/chunk-FHKSLCVW.js";
10
+ import "./chunks/chunk-HPNGSG5E.js";
27
11
  import {
28
12
  CAPABILITY_KEYS,
29
13
  NO_CAPABILITIES,
@@ -39,6 +23,10 @@ import {
39
23
  tagSchema,
40
24
  webhookSubscriptionSchema
41
25
  } from "./chunks/chunk-ZOAG2C6V.js";
26
+ import "./chunks/chunk-PTZO4QXR.js";
27
+ import {
28
+ defineNative
29
+ } from "./chunks/chunk-NAKXLBA6.js";
42
30
  import {
43
31
  campaignSchema,
44
32
  channelSchema,
@@ -59,6 +47,12 @@ import {
59
47
  sequenceSchema,
60
48
  workspaceSchema
61
49
  } from "./chunks/chunk-BOWXGMN3.js";
50
+ import {
51
+ METRIC_DEFINITIONS,
52
+ computeRates,
53
+ emptyCounts,
54
+ sumCounts
55
+ } from "./chunks/chunk-PQSTQKRD.js";
62
56
  import {
63
57
  SCHEMA_VERSION,
64
58
  campaignStatusSchema,
@@ -68,6 +62,13 @@ import {
68
62
  makeRef,
69
63
  parseRef
70
64
  } from "./chunks/chunk-QAKJ76HB.js";
65
+ import {
66
+ profileSlug
67
+ } from "./chunks/chunk-NAWZ73QS.js";
68
+ import {
69
+ sha256Hex,
70
+ stableId
71
+ } from "./chunks/chunk-FHKSLCVW.js";
71
72
  import {
72
73
  OutboundError,
73
74
  REDACTED_EMAIL,
@@ -0,0 +1,58 @@
1
+ export interface CopyText {
2
+ readonly subject: string | null;
3
+ readonly body: string | null;
4
+ }
5
+ export interface RenderedCopy extends CopyText {
6
+ /** The rendered body as plain text, with HTML tags removed. `null` when there is no body. */
7
+ readonly bodyText: string | null;
8
+ }
9
+ export interface PreviewVariant {
10
+ readonly variantKey: string;
11
+ /** The copy exactly as the campaign stores it. */
12
+ readonly template: CopyText;
13
+ /** The copy with the lead's values, or each variable's fallback, put in. */
14
+ readonly rendered: RenderedCopy;
15
+ /**
16
+ * Variables left as written because the lead has no value and the copy no
17
+ * fallback. A sender signature or another variable the tool fills itself
18
+ * at send time is listed here too.
19
+ */
20
+ readonly unfilled: readonly string[];
21
+ }
22
+ export interface PreviewStep {
23
+ /** The step, counted from 0. */
24
+ readonly step: number;
25
+ readonly action: string;
26
+ readonly delayDays: number | null;
27
+ readonly variants: readonly PreviewVariant[];
28
+ }
29
+ export interface PreviewLead {
30
+ readonly lead: string;
31
+ readonly email: string | null;
32
+ readonly linkedinUrl: string | null;
33
+ /** How many of the copy's variables this lead has a value for. */
34
+ readonly variablesFilled: number;
35
+ }
36
+ export interface CopyPreview {
37
+ readonly campaign: string;
38
+ /** The lead the copy is rendered for. `null` when no lead was read. */
39
+ readonly lead: PreviewLead | null;
40
+ readonly steps: readonly PreviewStep[];
41
+ readonly totals: {
42
+ readonly steps: number;
43
+ readonly variants: number;
44
+ /** Distinct variables in the copy. */
45
+ readonly variables: number;
46
+ /** Distinct variables left as written in at least one variant. */
47
+ readonly unfilled: number;
48
+ };
49
+ }
50
+ export declare const copyPreview: import("../define.ts").InsightDefinition<"copyPreview", {
51
+ campaign: string;
52
+ lead: string | null;
53
+ max_leads: number;
54
+ }, CopyPreview, {
55
+ campaign: string;
56
+ lead?: string | null | undefined;
57
+ max_leads?: number | undefined;
58
+ }>;
@@ -1,4 +1,3 @@
1
- import type { Interval } from "../stats.ts";
2
1
  import type { BasedRate, RateBasis } from "./shared.ts";
3
2
  export interface CopyUse {
4
3
  readonly campaign: string;
@@ -14,12 +13,6 @@ export interface CopyUse {
14
13
  };
15
14
  /** What the rate divides by: leads contacted or messages sent. */
16
15
  readonly basis: RateBasis | null;
17
- /** @deprecated Use `rates.replyRate.of`. Removed in 0.5.0. */
18
- readonly trials: number | null;
19
- /** @deprecated Use `rates.replyRate.rate`. Removed in 0.5.0. */
20
- readonly replyRate: number | null;
21
- /** @deprecated Use `rates.replyRate.low` and `.high`. Removed in 0.5.0. */
22
- readonly replyRateInterval: Interval | null;
23
16
  }
24
17
  export interface CopyPiece {
25
18
  readonly contentHash: string;
@@ -34,12 +27,6 @@ export interface CopyPiece {
34
27
  readonly replyRate: BasedRate;
35
28
  };
36
29
  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. */
40
- readonly replyRate: number | null;
41
- /** @deprecated Use `rates.replyRate.low` and `.high`. Removed in 0.5.0. */
42
- readonly replyRateInterval: Interval | null;
43
30
  }
44
31
  export interface ReusedCopy extends CopyPiece {
45
32
  /** Best reply rate first; a campaign with no known rate is last. */
@@ -40,6 +40,14 @@ export declare const COPY_INSIGHTS: readonly [import("../define.ts").InsightDefi
40
40
  max_links?: number | undefined;
41
41
  max_subject_chars?: number | undefined;
42
42
  spam_words?: string[] | undefined;
43
+ }>, import("../define.ts").InsightDefinition<"copyPreview", {
44
+ campaign: string;
45
+ lead: string | null;
46
+ max_leads: number;
47
+ }, import("./copy-preview.ts").CopyPreview, {
48
+ campaign: string;
49
+ lead?: string | null | undefined;
50
+ max_leads?: number | undefined;
43
51
  }>, import("../define.ts").InsightDefinition<"copyReuse", {
44
52
  max_campaigns: number;
45
53
  min_sent: number;
@@ -61,6 +69,7 @@ export declare const COPY_INSIGHTS: readonly [import("../define.ts").InsightDefi
61
69
  }>];
62
70
  export type { CheckName, Severity } from "./copy-checks.ts";
63
71
  export type { CheckCount, CopyAudit, CopyFinding } from "./copy-audit.ts";
72
+ export type { CopyPreview, CopyText, PreviewLead, PreviewStep, PreviewVariant, RenderedCopy, } from "./copy-preview.ts";
64
73
  export type { CopyPiece, CopyReuse, CopyUse, ReusedCopy, } from "./copy-reuse.ts";
65
74
  export type { HourCount, ReplyTiming, TimeTable, WeekdayCount, } from "./reply-timing.ts";
66
75
  export type { FunnelStep, FunnelVariant, StepFunnel } from "./step-funnel.ts";
@@ -6,8 +6,6 @@ import type { Base, RateBasis } from "./shared.ts";
6
6
  export type BaseOf = (counts: MetricCounts) => Base;
7
7
  export declare const pooled: (counts: readonly (MetricCounts | null)[], baseOf: BaseOf) => {
8
8
  sent: number | null;
9
- trials: number | null;
10
- interval: import("../stats.ts").Interval | null;
11
9
  basis: RateBasis | null;
12
10
  count: number | null;
13
11
  of: number | null;
@@ -1,7 +1,6 @@
1
1
  import type { MetricRow } from "../../internal/entities.ts";
2
2
  import type { MetricCounts } from "../../internal/metrics.ts";
3
3
  import type { Measured as Rate } from "../ops/shared.ts";
4
- import type { Interval } from "../stats.ts";
5
4
  export interface DayRange {
6
5
  readonly from: string | undefined;
7
6
  readonly to: string | undefined;
@@ -48,14 +47,10 @@ export interface BasedRate extends Rate {
48
47
  /** What `of` counts. */
49
48
  readonly basis: RateBasis | null;
50
49
  }
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. */
55
- readonly interval: Interval | null;
56
- }
50
+ /** A measured rate. */
51
+ export type Measured = BasedRate;
57
52
  export declare const measure: (count: number | null, base: Base) => Measured;
58
- /** The rate alone, without the deprecated `trials` and `interval`. */
53
+ /** The rate alone, without any field a caller added beside it. */
59
54
  export declare const replyRateOf: (measured: Measured | null) => BasedRate;
60
55
  /** Adds rows of counts; a count no row reports stays `null`. */
61
56
  export declare const sumRows: (rows: readonly MetricRow[]) => MetricCounts;
@@ -1,5 +1,4 @@
1
- import type { Interval } from "../stats.ts";
2
- import type { BasedRate, RateBasis } from "./shared.ts";
1
+ import type { BasedRate } from "./shared.ts";
3
2
  export interface FunnelVariant {
4
3
  readonly variantKey: string;
5
4
  /** The hash of the variant's current copy. `null` when the sequence no longer has the variant. */
@@ -9,10 +8,6 @@ export interface FunnelVariant {
9
8
  readonly rates: {
10
9
  readonly replyRate: BasedRate;
11
10
  };
12
- /** @deprecated Use `rates.replyRate.rate`. Removed in 0.5.0. */
13
- readonly replyRate: number | null;
14
- /** @deprecated Use `rates.replyRate.low` and `.high`. Removed in 0.5.0. */
15
- readonly replyRateInterval: Interval | null;
16
11
  }
17
12
  export interface FunnelStep {
18
13
  /** Counted from 0. */
@@ -27,12 +22,6 @@ export interface FunnelStep {
27
22
  readonly rates: {
28
23
  readonly replyRate: BasedRate;
29
24
  };
30
- /** @deprecated Use `rates.replyRate.rate`. Removed in 0.5.0. */
31
- readonly replyRate: number | null;
32
- /** @deprecated Use `rates.replyRate.low` and `.high`. Removed in 0.5.0. */
33
- readonly replyRateInterval: Interval | null;
34
- /** @deprecated Use `rates.replyRate.basis`. Removed in 0.5.0. */
35
- readonly replyRateBasis: RateBasis | null;
36
25
  /** This step's replies divided by every reply in the campaign, unattributed ones included. */
37
26
  readonly shareOfReplies: number | null;
38
27
  /** Sends of the step before minus this step's sends. `null` for the first step or an unknown count. */
@@ -1,4 +1,3 @@
1
- import type { Interval } from "../stats.ts";
2
1
  import type { RateBasis } from "./shared.ts";
3
2
  declare const METRICS: readonly ["replied", "positive", "opened", "clicked"];
4
3
  type Metric = (typeof METRICS)[number];
@@ -16,10 +15,6 @@ export interface TestedVariant {
16
15
  /** The 95% Wilson interval of the rate. `null` when the rate is unknown. */
17
16
  readonly low: number | null;
18
17
  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. */
22
- readonly interval: Interval | null;
23
18
  /** `false` when the base is under `min_sent` or the rate is unknown; such a variant is not compared. */
24
19
  readonly enoughData: boolean;
25
20
  /** Two-sided p-value against the leader. `null` for the leader, a variant not compared, and two rates that are both 0 or both 1. */
@@ -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;
@@ -80,8 +82,13 @@ export interface InsightContext {
80
82
  readonly note: (text: string) => void;
81
83
  /** Marks the answer as covering part of the data, with the reason as a note. */
82
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;
83
90
  }
84
- export interface RunOptions {
91
+ export interface RunOptions extends CapOptions {
85
92
  /** Replaces the clock. Meant for tests. */
86
93
  readonly now?: number | undefined;
87
94
  }
@@ -103,6 +110,10 @@ export interface InsightEntry {
103
110
  readonly maskedOut?: MaskedOut | undefined;
104
111
  /** What the adapter does not report that the insight needs, beyond a capability. */
105
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;
106
117
  /** Checks the input and the capabilities, then runs the insight. */
107
118
  readonly execute: (outbound: OutboundApi, input?: Json, options?: RunOptions) => Promise<InsightResult<Json>>;
108
119
  }
@@ -134,12 +145,22 @@ export interface InsightSpec<Key extends string, Input, Data, Given = Input> {
134
145
  * request, and an insight it refuses is not offered as a tool.
135
146
  */
136
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;
137
157
  readonly run: (context: InsightContext, input: Input) => Promise<Data>;
138
158
  }
139
159
  export interface InsightDefinition<Key extends string = string, Input = never, Data = Json, Given = Input> extends InsightEntry {
140
160
  readonly key: Key;
141
161
  readonly inputSchema: ZodObject & ZodType<Input, Given>;
142
162
  readonly run: (context: InsightContext, input: Input) => Promise<Data>;
163
+ readonly cost?: InsightCost<Input> | undefined;
143
164
  /** Never set. It carries the caller's input type to `outbound.insights`. */
144
165
  readonly given?: Given;
145
166
  }
@@ -1,7 +1,8 @@
1
- export { insights, listInsights, runInsightByName } from "./plugin.ts";
2
- export type { Insights, InsightsExtension } from "./plugin.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";
3
4
  export type { InsightInputs } from "./inputs.generated.ts";
4
- export { insightTools } from "./tools.ts";
5
+ export { INSIGHT_TOOL_CEILING, insightTools } from "./tools.ts";
5
6
  export type { InsightToolsOptions } from "./tools.ts";
6
7
  export { defineInsight, runInsight } from "./define.ts";
7
8
  export type { Cap, InsightContext, InsightDefinition, InsightMeta, InsightResult, RunOptions, } from "./define.ts";