outbound-sdk 0.7.0 → 0.8.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 (121) hide show
  1. package/dist/alerts/index.js +3 -3
  2. package/dist/audit/index.js +1 -1
  3. package/dist/benchmarks/index.js +3 -3
  4. package/dist/budget/index.d.ts +7 -0
  5. package/dist/budget/index.js +3 -3
  6. package/dist/cache/index.js +2 -2
  7. package/dist/cards/index.js +17 -5
  8. package/dist/chunks/{chunk-ZJCVLBAE.js → chunk-4GK56PRO.js} +667 -363
  9. package/dist/chunks/{chunk-MW4C6LTN.js → chunk-7TASUWPC.js} +2 -2
  10. package/dist/chunks/{chunk-M2VXGLLZ.js → chunk-CPACP4YD.js} +1 -1
  11. package/dist/chunks/{chunk-4AVYRVN5.js → chunk-FTK4JS65.js} +31 -10
  12. package/dist/chunks/{chunk-YW6FFVSZ.js → chunk-HXB2IOJJ.js} +1 -1
  13. package/dist/chunks/{chunk-Y7KECJAV.js → chunk-IKKCMWBK.js} +1 -1
  14. package/dist/chunks/{chunk-FHKSLCVW.js → chunk-KVAG5GM2.js} +19 -0
  15. package/dist/chunks/{chunk-7I3EPR23.js → chunk-MPE6VLLY.js} +3 -3
  16. package/dist/chunks/{chunk-UFQ4WMLU.js → chunk-NFWWA7MI.js} +1 -1
  17. package/dist/chunks/{chunk-GL7BABF2.js → chunk-OMCDMELK.js} +1 -1
  18. package/dist/chunks/{chunk-JRL3QRBS.js → chunk-OVTYA3IB.js} +88 -28
  19. package/dist/chunks/{chunk-HIAK2GCI.js → chunk-RMAHQ2OZ.js} +5 -1
  20. package/dist/chunks/{chunk-65YAGEWZ.js → chunk-RQLOPMMR.js} +153 -39
  21. package/dist/chunks/{chunk-OK3GAZMT.js → chunk-SYUMA3CP.js} +12 -0
  22. package/dist/chunks/{chunk-LVZGIKNF.js → chunk-U5AK6OJM.js} +1 -1
  23. package/dist/chunks/{chunk-KTYTE2BU.js → chunk-UAHYPASH.js} +20 -11
  24. package/dist/chunks/{chunk-BNDHEDHD.js → chunk-UOJG4VYF.js} +3 -3
  25. package/dist/chunks/{chunk-LD6F46UT.js → chunk-UWD65SK7.js} +2 -2
  26. package/dist/chunks/{chunk-I7DXXGNZ.js → chunk-UZLFZZ2U.js} +5 -5
  27. package/dist/chunks/{chunk-DNPNTD5W.js → chunk-VVDBCQLK.js} +1 -1
  28. package/dist/chunks/{chunk-IVH3NMQZ.js → chunk-WROJO6XB.js} +1 -1
  29. package/dist/chunks/chunk-XMCNRU4H.js +7279 -0
  30. package/dist/chunks/{chunk-QFC4ZHD3.js → chunk-XYHM4KHC.js} +1 -1
  31. package/dist/chunks/{chunk-NAWZ73QS.js → chunk-YFJ3OQZS.js} +8 -1
  32. package/dist/chunks/tools-II7GXAOM.js +23 -0
  33. package/dist/cli/args.d.ts +48 -0
  34. package/dist/cli/bin.js +14 -14
  35. package/dist/cli/commands.d.ts +0 -7
  36. package/dist/cli/config.d.ts +31 -2
  37. package/dist/cli/envelope.d.ts +2 -0
  38. package/dist/cli/index.d.ts +6 -0
  39. package/dist/cli/index.js +19 -15
  40. package/dist/cli/listing.d.ts +5 -2
  41. package/dist/cli/mcp.d.ts +9 -0
  42. package/dist/cli/offered.d.ts +10 -0
  43. package/dist/cli/options.d.ts +6 -0
  44. package/dist/cli/progress.d.ts +27 -0
  45. package/dist/cli/serve.d.ts +17 -0
  46. package/dist/cli/update.d.ts +25 -2
  47. package/dist/clients/index.js +3 -3
  48. package/dist/combine/index.js +154 -35
  49. package/dist/combine/newest.d.ts +18 -0
  50. package/dist/combine/route.d.ts +19 -5
  51. package/dist/emailbison/index.js +22 -14
  52. package/dist/emailbison/map-sequence.d.ts +2 -1
  53. package/dist/exporter/index.js +1 -1
  54. package/dist/failover/index.js +3 -3
  55. package/dist/fixtures/index.js +4 -4
  56. package/dist/heyreach/capabilities.d.ts +4 -0
  57. package/dist/heyreach/conversations.d.ts +23 -0
  58. package/dist/heyreach/inbox.d.ts +0 -1
  59. package/dist/heyreach/index.js +251 -92
  60. package/dist/identity/index.js +2 -2
  61. package/dist/index.js +7 -7
  62. package/dist/insights/capped.d.ts +6 -6
  63. package/dist/insights/copy/index.d.ts +2 -0
  64. package/dist/insights/copy/reply-timing.d.ts +4 -0
  65. package/dist/insights/cost.d.ts +11 -1
  66. package/dist/insights/define.d.ts +25 -16
  67. package/dist/insights/inbox.d.ts +12 -0
  68. package/dist/insights/index.js +42 -6578
  69. package/dist/insights/inputs.generated.d.ts +60 -24
  70. package/dist/insights/ops/anomalies.d.ts +9 -0
  71. package/dist/insights/ops/index.d.ts +2 -0
  72. package/dist/insights/ops/period-comparison.d.ts +7 -8
  73. package/dist/insights/ops/pipeline-forecast.d.ts +10 -0
  74. package/dist/insights/ops/shared.d.ts +6 -1
  75. package/dist/insights/people/auto-replies.d.ts +11 -7
  76. package/dist/insights/people/dropped-replies.d.ts +13 -4
  77. package/dist/insights/people/hot-leads-read.d.ts +31 -0
  78. package/dist/insights/people/hot-leads.d.ts +15 -3
  79. package/dist/insights/people/index.d.ts +10 -2
  80. package/dist/insights/people/read.d.ts +1 -1
  81. package/dist/insights/registry.d.ts +14 -2
  82. package/dist/insights/run-cap.d.ts +10 -0
  83. package/dist/insights/senders/read.d.ts +0 -3
  84. package/dist/insights/tools.d.ts +12 -0
  85. package/dist/insights/tracked-reads.d.ts +53 -0
  86. package/dist/instantly/capabilities.d.ts +13 -1
  87. package/dist/instantly/index.js +122 -46
  88. package/dist/instantly/map-account.d.ts +2 -1
  89. package/dist/instantly/map-lead.d.ts +1 -0
  90. package/dist/instantly/map.d.ts +4 -3
  91. package/dist/internal/adapter.d.ts +17 -0
  92. package/dist/internal/capabilities.d.ts +13 -0
  93. package/dist/internal/engine/budget.d.ts +9 -1
  94. package/dist/internal/engine/engine.d.ts +2 -1
  95. package/dist/internal/engine/request.d.ts +2 -0
  96. package/dist/internal/errors.d.ts +5 -0
  97. package/dist/internal/hooks.d.ts +11 -0
  98. package/dist/internal/notes.d.ts +16 -0
  99. package/dist/internal/outbound/api.d.ts +14 -0
  100. package/dist/internal/outbound/core.d.ts +4 -1
  101. package/dist/internal/outbound/operation-shared.d.ts +2 -0
  102. package/dist/internal/sha256.d.ts +2 -0
  103. package/dist/internal/url.d.ts +1 -0
  104. package/dist/loader/index.js +3 -3
  105. package/dist/memory/index.js +6 -6
  106. package/dist/redact/index.d.ts +1 -1
  107. package/dist/redact/index.js +107 -19
  108. package/dist/redact/plugin.d.ts +26 -3
  109. package/dist/smartlead/index.js +22 -13
  110. package/dist/smartlead/map.d.ts +3 -2
  111. package/dist/sync/index.js +2 -2
  112. package/dist/tools/ai-sdk.js +5 -5
  113. package/dist/tools/by-name.d.ts +9 -1
  114. package/dist/tools/campaign-tools.d.ts +3 -1
  115. package/dist/tools/claude-agent.js +5 -5
  116. package/dist/tools/index.js +6 -6
  117. package/dist/tools/registry.d.ts +6 -0
  118. package/dist/tools/shared.d.ts +5 -1
  119. package/dist/tracing/index.js +1 -1
  120. package/dist/webhooks/index.js +11 -11
  121. package/package.json +1 -1
@@ -0,0 +1,53 @@
1
+ import type { ListAll, ResultMeta } from "../internal/outbound/api.ts";
2
+ /**
3
+ * The cap a listing was read up to, for the note when it stops early:
4
+ * `{ input: "max_campaigns", max: 25, what: "campaigns" }` gives "Stopped at
5
+ * 25 campaigns (max_campaigns); more exist."
6
+ */
7
+ export interface Cap {
8
+ /** The cap as the caller set it, not the room left under it. */
9
+ readonly max: number;
10
+ /** What was counted, in the plural: `campaigns`, `leads of a campaign`. */
11
+ readonly what: string;
12
+ /** The input that raises the cap, or `null` for a cap no input sets. */
13
+ readonly input: string | null;
14
+ /**
15
+ * What the cap applies to each of, in the plural, for a cap read once per
16
+ * record such as `max_senders_per_campaign`: `campaigns`. Every stop at
17
+ * it shares one note that counts them: "Stopped at 100 senders in 22
18
+ * campaigns (max_senders_per_campaign); more exist."
19
+ */
20
+ readonly per?: string | undefined;
21
+ }
22
+ export declare const stopNote: (cap: Cap | string | undefined) => string;
23
+ /**
24
+ * The note for a listing that a cap stopped with more records left. `times`
25
+ * is how many records of `cap.per` it stopped in.
26
+ */
27
+ export declare const capNote: (cap: Cap, times?: number) => string;
28
+ /** `true` when `items` came from a listing a request cap stopped part way. */
29
+ export declare const wasCutShort: (items: readonly unknown[]) => boolean;
30
+ /** What `context.all` is. */
31
+ export type All = <Item>(walk: ListAll<Item>, cap?: Cap | string) => Promise<Item[]>;
32
+ /** What `context.each` is. */
33
+ export type Each = <Item, Result>(items: readonly Item[], read: (item: Item) => Promise<Result>, what: string) => Promise<Result[]>;
34
+ /** What the reads record into the answer they are part of. */
35
+ export interface Recorder {
36
+ /** What stopped the read when a request cap did and the insight keeps what it read. */
37
+ readonly kept: (cause: unknown) => string | undefined;
38
+ readonly partial: (reason: string) => void;
39
+ readonly seen: (meta: ResultMeta | undefined) => void;
40
+ /** Notes a listing its cap stopped with more records left. */
41
+ readonly stopped: (cap: Cap | string | undefined) => void;
42
+ }
43
+ /**
44
+ * `context.all` and `context.each` over one answer. A listing read while
45
+ * items are being read is part of an item, so a cap stop there drops the
46
+ * item instead of keeping a listing cut short: a campaign with its senders
47
+ * cut off is left out, never counted with fewer senders.
48
+ */
49
+ export interface TrackedReads {
50
+ readonly all: All;
51
+ readonly each: Each;
52
+ }
53
+ export declare const readsOf: ({ kept, partial, seen, stopped, }: Recorder) => TrackedReads;
@@ -4,7 +4,14 @@ import type { LimitDeclaration } from "../internal/limits.ts";
4
4
  export declare const BASE_URL = "https://api.instantly.ai/api/v2";
5
5
  export declare const API_KEY_ENV = "INSTANTLY_API_KEY";
6
6
  export declare const WORKSPACE_ENV = "INSTANTLY_WORKSPACE_ID";
7
- /** `GET /emails` has its own limit, far below the workspace limit. */
7
+ /**
8
+ * `GET /emails` has its own limit of 20 a minute, far below the workspace
9
+ * limit. Every process on the workspace draws on it: the general limit is
10
+ * documented as workspace-wide, and on 2026-11-16 a second process reading
11
+ * emails slowed the first from 0.76 s to 121 s. The SDK counts per process
12
+ * unless a shared `rateLimitStore` is given, so two processes on one key
13
+ * meet at Instantly's 429. See docs/research/instantly.md.
14
+ */
8
15
  export declare const EMAILS_LANE = "emails";
9
16
  export declare const PAGE_SIZE = 100;
10
17
  /** Three native reads have a limit of their own; each is a lane. */
@@ -68,6 +75,11 @@ export declare const costs: {
68
75
  "senders.health": {
69
76
  perPage: number;
70
77
  };
78
+ "senders.byCampaign": {
79
+ pageSize: number;
80
+ perPage: number;
81
+ perWalk: number;
82
+ };
71
83
  "senders.list": {
72
84
  pageSize: number;
73
85
  perPage: number;
@@ -1,16 +1,17 @@
1
1
  import {
2
2
  EVENT_TYPES,
3
3
  instantlyEvents
4
- } from "../chunks/chunk-7I3EPR23.js";
4
+ } from "../chunks/chunk-MPE6VLLY.js";
5
5
  import {
6
6
  applyTracking,
7
7
  ownTracking,
8
8
  unlessFailed
9
- } from "../chunks/chunk-DNPNTD5W.js";
9
+ } from "../chunks/chunk-VVDBCQLK.js";
10
10
  import {
11
11
  answeredAtOnce,
12
- detectAutoReply
13
- } from "../chunks/chunk-OK3GAZMT.js";
12
+ detectAutoReply,
13
+ notNegative
14
+ } from "../chunks/chunk-SYUMA3CP.js";
14
15
  import {
15
16
  flatMapPage,
16
17
  mapPage,
@@ -23,7 +24,7 @@ import {
23
24
  listIn,
24
25
  toVariant,
25
26
  variantKey
26
- } from "../chunks/chunk-BNDHEDHD.js";
27
+ } from "../chunks/chunk-UOJG4VYF.js";
27
28
  import {
28
29
  normalizeBody
29
30
  } from "../chunks/chunk-FALWG5U3.js";
@@ -40,28 +41,28 @@ import {
40
41
  recordBase,
41
42
  refTo,
42
43
  refsTo
43
- } from "../chunks/chunk-LVZGIKNF.js";
44
+ } from "../chunks/chunk-U5AK6OJM.js";
44
45
  import "../chunks/chunk-POBAY3TI.js";
45
46
  import {
46
47
  emptyCounts,
47
48
  metricRow,
48
49
  sumCounts
49
- } from "../chunks/chunk-M2VXGLLZ.js";
50
+ } from "../chunks/chunk-CPACP4YD.js";
50
51
  import "../chunks/chunk-QGRZDTX4.js";
51
52
  import {
52
53
  assertWorkspaceId
53
- } from "../chunks/chunk-YW6FFVSZ.js";
54
- import "../chunks/chunk-NAWZ73QS.js";
55
- import "../chunks/chunk-FHKSLCVW.js";
54
+ } from "../chunks/chunk-HXB2IOJJ.js";
55
+ import "../chunks/chunk-YFJ3OQZS.js";
56
+ import "../chunks/chunk-KVAG5GM2.js";
56
57
  import {
57
58
  readEnv,
58
59
  requireCredential
59
- } from "../chunks/chunk-UFQ4WMLU.js";
60
+ } from "../chunks/chunk-NFWWA7MI.js";
60
61
  import {
61
62
  OutboundError,
62
63
  makeErrorMapper,
63
64
  requireObject
64
- } from "../chunks/chunk-QFC4ZHD3.js";
65
+ } from "../chunks/chunk-XYHM4KHC.js";
65
66
  import {
66
67
  count,
67
68
  emailAddress,
@@ -69,6 +70,7 @@ import {
69
70
  flag,
70
71
  fullName,
71
72
  isJsonObject,
73
+ isNumber,
72
74
  isString,
73
75
  list,
74
76
  objects,
@@ -95,16 +97,20 @@ var toWindow = (raw) => ({
95
97
  timezone: text(raw.timezone),
96
98
  to: matching(field(raw.timing, "to"), CLOCK)
97
99
  });
98
- var toCampaignSettings = (identity, raw) => {
100
+ var toCampaignSettings = (identity, raw, note) => {
99
101
  const id = text(raw.id) ?? "";
100
102
  const schedule = raw.campaign_schedule;
103
+ const setting = (value, what, unit) => notNegative(count(value), { note, unit, vendor: "Instantly", what });
101
104
  return {
102
105
  ...recordBase(identity, id, raw),
103
106
  campaignRef: refTo(identity, id) ?? "",
104
- dailyLimit: count(raw.daily_limit),
105
- dailyNewLeads: count(raw.daily_max_leads),
107
+ dailyLimit: setting(raw.daily_limit, "The campaign's daily limit"),
108
+ dailyNewLeads: setting(
109
+ raw.daily_max_leads,
110
+ "The campaign's daily limit of new leads"
111
+ ),
106
112
  endDate: matching(field(schedule, "end_date"), DATE),
107
- gapMinutes: count(raw.email_gap),
113
+ gapMinutes: setting(raw.email_gap, "The gap between emails", "minutes"),
108
114
  plainText: flag(raw.text_only),
109
115
  schedule: objects(field(schedule, "schedules")).map(toWindow),
110
116
  startDate: matching(field(schedule, "start_date"), DATE),
@@ -313,23 +319,39 @@ var DELAY_DAYS = /* @__PURE__ */ new Map([
313
319
  ["hours", 1 / 24],
314
320
  ["minutes", 1 / 1440]
315
321
  ]);
316
- var days = (value, unit) => {
322
+ var days = (value, unit, step, note) => {
317
323
  const delay = count(value);
318
- const perUnit = DELAY_DAYS.get(text(unit) ?? "days");
319
- return delay === null || perUnit === void 0 ? null : delay * perUnit;
324
+ const unitName = text(unit) ?? "days";
325
+ const perUnit = DELAY_DAYS.get(unitName);
326
+ if (delay === null) {
327
+ return null;
328
+ }
329
+ if (perUnit === void 0) {
330
+ note(
331
+ `Step ${step}'s delay is in a unit Instantly does not document (${unitName}); left out.`
332
+ );
333
+ return null;
334
+ }
335
+ const known = notNegative(delay, {
336
+ note,
337
+ unit: unitName,
338
+ vendor: "Instantly",
339
+ what: `Step ${step}'s delay`
340
+ });
341
+ return known === null ? null : known * perUnit;
320
342
  };
321
- var waitBefore = (step, previous, subsequence) => {
343
+ var waitBefore = (step, previous, index, subsequence, note) => {
322
344
  if (previous !== void 0) {
323
- return days(previous.delay, previous.delay_unit);
345
+ return days(previous.delay, previous.delay_unit, index + 1, note);
324
346
  }
325
- return subsequence ? days(step.pre_delay, step.pre_delay_unit) : 0;
347
+ return subsequence ? days(step.pre_delay, step.pre_delay_unit, index + 1, note) : 0;
326
348
  };
327
- var toSteps = (sequences, subsequence) => {
349
+ var toSteps = (sequences, subsequence, note) => {
328
350
  const steps = objects(objects(sequences)[0]?.steps);
329
351
  return steps.map((step, index) => ({
330
352
  action: text(step.type) ?? "email",
331
353
  branch: null,
332
- delayDays: waitBefore(step, steps[index - 1], subsequence),
354
+ delayDays: waitBefore(step, steps[index - 1], index, subsequence, note),
333
355
  index,
334
356
  parentIndex: index === 0 ? null : index - 1,
335
357
  // Variants are positional: Instantly gives them no ids.
@@ -342,22 +364,22 @@ var toSteps = (sequences, subsequence) => {
342
364
  )
343
365
  }));
344
366
  };
345
- var toSequence = (identity, raw) => {
367
+ var toSequence = (identity, raw, note) => {
346
368
  const id = text(raw.id) ?? "";
347
369
  return {
348
370
  ...recordBase(identity, id, raw.sequences ?? null),
349
371
  campaignRef: refTo(identity, id) ?? "",
350
372
  kind: "main",
351
373
  name: null,
352
- steps: toSteps(raw.sequences, false)
374
+ steps: toSteps(raw.sequences, false, note)
353
375
  };
354
376
  };
355
- var toSubsequence = (identity, raw, campaignId) => ({
377
+ var toSubsequence = (identity, raw, campaignId, note) => ({
356
378
  ...recordBase(identity, text(raw.id) ?? "", raw),
357
379
  campaignRef: refTo(identity, text(raw.parent_campaign) ?? campaignId) ?? "",
358
380
  kind: "subsequence",
359
381
  name: text(raw.name),
360
- steps: toSteps(raw.sequences, true)
382
+ steps: toSteps(raw.sequences, true, note)
361
383
  });
362
384
  var SENDER_STATUS = /* @__PURE__ */ new Map([
363
385
  [-3, "error"],
@@ -375,13 +397,17 @@ var MAIL_PROVIDER = /* @__PURE__ */ new Map([
375
397
  [8, "other"],
376
398
  [11, "other"]
377
399
  ]);
378
- var toSender = (identity, raw) => {
400
+ var toSender = (identity, raw, note) => {
379
401
  const address = emailAddress(raw.email);
380
402
  const warmupStatus = count(raw.warmup_status);
381
403
  return {
382
404
  ...recordBase(identity, address ?? "", raw),
383
405
  address,
384
- dailyLimit: count(raw.daily_limit),
406
+ dailyLimit: notNegative(count(raw.daily_limit), {
407
+ note,
408
+ vendor: "Instantly",
409
+ what: `The daily limit of ${address ?? "a mailbox"}`
410
+ }),
385
411
  kind: "mailbox",
386
412
  linkedinUrl: null,
387
413
  mailProvider: MAIL_PROVIDER.get(count(raw.provider_code) ?? Number.NaN) ?? null,
@@ -434,12 +460,17 @@ var capabilities = {
434
460
  // The `search` field of POST /leads/list, which matches whole words of the
435
461
  // lead's email; the adapter keeps only addresses at exactly that domain.
436
462
  "leads.byDomain": true,
463
+ // The `filter` field of POST /leads/list, one positive interest status
464
+ // (FILTER_LEAD_INTERESTED and the rest) after another.
465
+ "leads.byInterest": true,
437
466
  "leads.engagement": true,
438
467
  "leads.get": true,
439
468
  "leads.list": true,
440
469
  // By email only, with the `contacts` filter of POST /leads/list. A lead has
441
470
  // no LinkedIn profile, so a lookup by profile finds nothing.
442
471
  "leads.lookup": true,
472
+ // The same `contacts` filter, given many addresses at once.
473
+ "leads.lookupMany": true,
443
474
  // POST /leads/list has no date filter, so the wrapper filters after fetching.
444
475
  "leads.since": "client",
445
476
  "leads.timeline": true,
@@ -452,6 +483,8 @@ var capabilities = {
452
483
  // A list response can cut a large body short (`body_fallback_reason`); the
453
484
  // adapter then reads that email on its own, where the body is whole.
454
485
  "messages.body": "full",
486
+ // email_type=manual on GET /emails, kept to ue_type 3 (sent, not from a campaign).
487
+ "messages.byHand": true,
455
488
  "messages.byThread": true,
456
489
  "messages.list": true,
457
490
  "messages.since": "server",
@@ -560,6 +593,10 @@ var costs = {
560
593
  "senders.get": { perPage: 1 },
561
594
  // The account, its DNS test, then its warmup analytics.
562
595
  "senders.health": { perPage: 3 },
596
+ // A campaign's senders: the campaign again with each page of every mailbox,
597
+ // kept when the campaign names it (see the caveats). Pages follow the
598
+ // workspace's mailboxes, not the senders kept.
599
+ "senders.byCampaign": { pageSize: PAGE_SIZE, perPage: 2, perWalk: 1 },
563
600
  "senders.list": { pageSize: PAGE_SIZE, perPage: 1, perWalk: 1 },
564
601
  "sequence.get": { perPage: 1 },
565
602
  "sequence.subsequences": { pageSize: PAGE_SIZE, perPage: 1, perWalk: 1 },
@@ -578,6 +615,7 @@ var caveats = [
578
615
  "A placement test's kind reads type 1 as a one-time test and 2 as an automated one: the reference names the two kinds in that order and gives the numbers no names. A test's results stay native, because Instantly reports them as one row per test email.",
579
616
  "Instantly sends next_starting_after on a last page too (seen live), and the page after it is empty. A listing therefore ends one request late; the small lookups for tags and labels stop at the first page that is not full.",
580
617
  `A reply's category is read from the email's i_status using the lead interest status values (seen live: 0, 1, -1 and -2). An email names its lead by address (lead_id was absent live), so a message's or reply's leadRef holds the lead's lowercased address, from lead or, on a received email, from_address_email. leads.get and leads.timeline take that ref; leads.get then returns the first record with the address, one of several when the person is in several campaigns. No live email carried the documented is_auto_reply and the email list cannot filter by it, so when it is missing isAuto is decided by a fixed rule (isAutoSource rule): a machine sender address (noreply, auto-responder, mailer-daemon), an automatic subject (OOO, Out of Office, Automatic reply, "is no longer at"), a canned autoresponder phrase in the body, or, in a timeline or thread, a reply within a minute of the send it answers. An Out of Office i_status counts as the vendor saying so. leftCompany is true when the reply says the person left or the contact changed. In a timeline or thread a received email takes its stepIndex from the send it answers, since its own step lags on the last step.`,
618
+ "Messages sent by hand (byHand) are read with email_type=manual on GET /emails, which the reference names but does not describe, and only emails with ue_type 3 (Sent) are kept: a campaign send is ue_type 1. Not run against a live workspace.",
581
619
  "An email's step and a lead's last step are ids of the form sequence_step_variant, each counted from 0 (seen live, not documented); any other form gives a null step. Step analytics count steps from 0 too, and can hold a row with no step for counts Instantly could not tie to one.",
582
620
  "Whether reply_count includes automatic replies is not documented; replied uses the unique reply count and repliedAuto the unique automatic count.",
583
621
  "Open counts are returned even when a campaign has open tracking turned off, because the analytics response does not say whether tracking was on.",
@@ -723,6 +761,7 @@ var toLead = (identity, raw, labels = NO_LABELS) => ({
723
761
  });
724
762
  var SCHEDULED = 4;
725
763
  var RECEIVED = 2;
764
+ var SENT_BY_HAND = 3;
726
765
  var leadOf = (raw) => emailAddress(raw.lead) ?? (count(raw.ue_type) === RECEIVED ? emailAddress(raw.from_address_email) : null) ?? text(raw.lead_id);
727
766
  var messageFields = (identity, raw, includeBody) => {
728
767
  const body = field(raw.body, "html") ?? field(raw.body, "text");
@@ -740,6 +779,7 @@ var messageFields = (identity, raw, includeBody) => {
740
779
  };
741
780
  };
742
781
  var isScheduled = (raw) => count(raw.ue_type) === SCHEDULED;
782
+ var isSentByHand = (raw) => count(raw.ue_type) === SENT_BY_HAND;
743
783
  var isTruncated = (raw) => text(raw.body_fallback_reason) !== null;
744
784
  var oneOrZero = (value) => flag(value) ?? (count(value) === null ? null : count(value) === 1);
745
785
  var rawBody = (raw) => text(field(raw.body, "text")) ?? text(field(raw.body, "html")) ?? text(raw.content_preview);
@@ -850,7 +890,8 @@ var accountReaders = (client) => {
850
890
  },
851
891
  getCampaignSettings: async (id, ctx) => toCampaignSettings(
852
892
  identity,
853
- await client.getObject(ctx, `/campaigns/${encodeURIComponent(id)}`)
893
+ await client.getObject(ctx, `/campaigns/${encodeURIComponent(id)}`),
894
+ ctx.note
854
895
  ),
855
896
  getSenderHealth: async (id, ctx) => {
856
897
  const account = await client.getObject(
@@ -896,7 +937,7 @@ var accountReaders = (client) => {
896
937
  });
897
938
  return mapPage(
898
939
  page,
899
- (item) => toSubsequence(identity, item, query.campaignId)
940
+ (item) => toSubsequence(identity, item, query.campaignId, ctx.note)
900
941
  );
901
942
  },
902
943
  listTags: async (query, ctx) => {
@@ -982,13 +1023,15 @@ var listEmails = async (client, ctx, query, received) => {
982
1023
  const cursor = emailCursor(query.next);
983
1024
  const leadId = "leadId" in query ? query.leadId : void 0;
984
1025
  const threadId = "threadId" in query ? query.threadId : void 0;
1026
+ const byHand = "byHand" in query && query.byHand === true;
1027
+ const sentByHand = byHand ? "manual" : void 0;
985
1028
  const lead = await leadAddress(client, ctx, leadId, cursor);
986
1029
  const envelope = listEnvelope(
987
1030
  await client.get(ctx, "/emails", {
988
1031
  lane: EMAILS_LANE,
989
1032
  query: {
990
1033
  campaign_id: query.campaignId,
991
- email_type: received ? "received" : void 0,
1034
+ email_type: received ? "received" : sentByHand,
992
1035
  is_unread: "unread" in query ? query.unread : void 0,
993
1036
  lead,
994
1037
  limit: pageSize(query.limit),
@@ -1001,7 +1044,9 @@ var listEmails = async (client, ctx, query, received) => {
1001
1044
  client.identity.provider,
1002
1045
  "/emails"
1003
1046
  );
1004
- const sent = envelope.items.filter((item) => !isScheduled(item));
1047
+ const sent = envelope.items.filter(
1048
+ (item) => byHand ? isSentByHand(item) : !isScheduled(item)
1049
+ );
1005
1050
  return {
1006
1051
  items: query.includeBody ? await Promise.all(
1007
1052
  sent.map(async (item) => await withFullBody(client, ctx, item))
@@ -1354,10 +1399,18 @@ var campaignSenders = async (client, ctx, query) => {
1354
1399
  });
1355
1400
  const attached = (account) => byTagOnly || addresses.has(emailAddress(account.email) ?? "") || texts(objects(account.tags), "id").some((id) => tagIds.has(id));
1356
1401
  return {
1357
- items: page.items.filter((account) => attached(account)).map((account) => toSender(client.identity, account)),
1402
+ items: page.items.filter((account) => attached(account)).map((account) => toSender(client.identity, account, ctx.note)),
1358
1403
  next: page.next
1359
1404
  };
1360
1405
  };
1406
+ var POSITIVE_FILTERS = [
1407
+ "FILTER_LEAD_INTERESTED",
1408
+ "FILTER_LEAD_MEETING_BOOKED",
1409
+ "FILTER_LEAD_MEETING_COMPLETED",
1410
+ "FILTER_LEAD_CLOSED",
1411
+ "FILTER_LEAD_CUSTOM_LABEL_POSITIVE"
1412
+ ];
1413
+ var interestAt = (next) => isJsonObject(next) && isNumber(next.at) ? { after: isString(next.after) ? next.after : null, at: next.at } : { after: null, at: 0 };
1361
1414
  var leadListBody = (query) => {
1362
1415
  const body = { limit: pageSize(query.limit) };
1363
1416
  if (query.campaignId !== void 0) {
@@ -1369,10 +1422,19 @@ var leadListBody = (query) => {
1369
1422
  if (query.email !== void 0) {
1370
1423
  body.contacts = [query.email];
1371
1424
  }
1425
+ if (query.emails !== void 0) {
1426
+ body.contacts = [...query.emails];
1427
+ }
1372
1428
  if (query.domain !== void 0) {
1373
1429
  body.search = query.domain;
1374
1430
  }
1375
- if (isString(query.next)) {
1431
+ if (query.interest === "positive") {
1432
+ const { after: after2, at } = interestAt(query.next);
1433
+ body.filter = POSITIVE_FILTERS[at] ?? null;
1434
+ if (after2 !== null) {
1435
+ body.starting_after = after2;
1436
+ }
1437
+ } else if (isString(query.next)) {
1376
1438
  body.starting_after = query.next;
1377
1439
  }
1378
1440
  return body;
@@ -1395,15 +1457,27 @@ var listLeads = async (client, query, ctx) => {
1395
1457
  (item) => toLead(client.identity, item, labels)
1396
1458
  );
1397
1459
  return {
1398
- // `contacts` is documented as the emails a lead needs to have, but not
1399
- // how it compares them, and `search` matches more than the address, so
1400
- // both matches are made exact here.
1401
- items: leads.filter(
1402
- (lead) => (query.email === void 0 || lead.email === query.email) && (query.domain === void 0 || lead.email?.split("@").at(-1) === query.domain)
1403
- ),
1404
- next: envelope.next
1460
+ items: chosen(query, leads),
1461
+ next: query.interest === "positive" || query.emails !== void 0 ? nextOf(query, envelope) : envelope.next
1405
1462
  };
1406
1463
  };
1464
+ var chosen = (query, leads) => {
1465
+ const wanted = new Set(query.emails);
1466
+ return leads.filter(
1467
+ (lead) => (query.email === void 0 || lead.email === query.email) && (query.emails === void 0 || lead.email !== null && wanted.has(lead.email)) && (query.domain === void 0 || lead.email?.split("@").at(-1) === query.domain) && (query.interest === void 0 || lead.interestCategory === "positive")
1468
+ );
1469
+ };
1470
+ var nextOf = (query, envelope) => {
1471
+ const next = envelope.items.length >= pageSize(query.limit) ? envelope.next : void 0;
1472
+ if (query.interest !== "positive") {
1473
+ return next;
1474
+ }
1475
+ const { at } = interestAt(query.next);
1476
+ if (next !== void 0) {
1477
+ return { after: next, at };
1478
+ }
1479
+ return at + 1 < POSITIVE_FILTERS.length ? { at: at + 1 } : void 0;
1480
+ };
1407
1481
  var leadReaders = (client) => ({
1408
1482
  getLead: async (id, ctx) => {
1409
1483
  const address = emailAddress(id);
@@ -1445,11 +1519,13 @@ var readers = (client) => {
1445
1519
  },
1446
1520
  getSender: async (id, ctx) => toSender(
1447
1521
  identity,
1448
- await client.getObject(ctx, `/accounts/${encodeURIComponent(id)}`)
1522
+ await client.getObject(ctx, `/accounts/${encodeURIComponent(id)}`),
1523
+ ctx.note
1449
1524
  ),
1450
1525
  getSequence: async (id, ctx) => toSequence(
1451
1526
  identity,
1452
- await client.getObject(ctx, `/campaigns/${encodeURIComponent(id)}`)
1527
+ await client.getObject(ctx, `/campaigns/${encodeURIComponent(id)}`),
1528
+ ctx.note
1453
1529
  ),
1454
1530
  listCampaigns: async (query, ctx) => await listCampaigns(client, ctx, query),
1455
1531
  listSenders: async (query, ctx) => {
@@ -1462,7 +1538,7 @@ var readers = (client) => {
1462
1538
  const page = await listPage(client, ctx, "/accounts", query, {
1463
1539
  include_tags: true
1464
1540
  });
1465
- return mapPage(page, (item) => toSender(identity, item));
1541
+ return mapPage(page, (item) => toSender(identity, item, ctx.note));
1466
1542
  },
1467
1543
  listWorkspaces: async (_query, ctx) => {
1468
1544
  const workspace = await client.get(ctx, "/workspaces/current");
@@ -1,8 +1,9 @@
1
1
  import type { BlockEntry, CampaignProgress, CampaignSettings, LeadList, PlacementTest, SenderHealth, Tag, WebhookSubscription } from "../internal/entities-account.ts";
2
2
  import type { Json, JsonObject } from "../internal/json.ts";
3
+ import type { Note } from "../internal/notes.ts";
3
4
  import type { Identity } from "../internal/record.ts";
4
5
  /** The settings are fields of the campaign object itself. */
5
- export declare const toCampaignSettings: (identity: Identity, raw: JsonObject) => CampaignSettings;
6
+ export declare const toCampaignSettings: (identity: Identity, raw: JsonObject, note: Note) => CampaignSettings;
6
7
  /**
7
8
  * One campaign's row of `GET /campaigns/analytics`: `leads_count` is every
8
9
  * lead and `completed_count` the leads the campaign was completed for. The
@@ -12,6 +12,7 @@ export declare const toLead: (identity: Identity, raw: JsonObject, labels?: Labe
12
12
  /** `ue_type`: 1 sent from a campaign, 2 received, 3 sent by hand, 4 scheduled. */
13
13
  export declare const SCHEDULED = 4;
14
14
  export declare const isScheduled: (raw: JsonObject) => boolean;
15
+ export declare const isSentByHand: (raw: JsonObject) => boolean;
15
16
  /** `true` when a list response holds an excerpt instead of the whole body. */
16
17
  export declare const isTruncated: (raw: JsonObject) => boolean;
17
18
  export declare const toMessage: (identity: Identity, raw: JsonObject, includeBody: boolean) => Message;
@@ -1,5 +1,6 @@
1
1
  import type { Campaign, CampaignStatus, Sender, Sequence, Workspace } from "../internal/entities.ts";
2
2
  import type { Json, JsonObject } from "../internal/json.ts";
3
+ import type { Note } from "../internal/notes.ts";
3
4
  import type { Identity } from "../internal/record.ts";
4
5
  /**
5
6
  * The status Instantly can filter for us. Active and paused each cover
@@ -8,11 +9,11 @@ import type { Identity } from "../internal/record.ts";
8
9
  export declare const campaignStatusCode: (status: CampaignStatus) => number | undefined;
9
10
  export declare const toCampaign: (identity: Identity, raw: JsonObject, tags?: readonly string[]) => Campaign;
10
11
  /** A campaign's steps live inside the campaign object; there is no sequence endpoint. */
11
- export declare const toSequence: (identity: Identity, raw: JsonObject) => Sequence;
12
+ export declare const toSequence: (identity: Identity, raw: JsonObject, note: Note) => Sequence;
12
13
  /** `GET /subsequences`: a follow-up path a lead enters when its conditions are met. */
13
- export declare const toSubsequence: (identity: Identity, raw: JsonObject, campaignId: string) => Sequence;
14
+ export declare const toSubsequence: (identity: Identity, raw: JsonObject, campaignId: string, note: Note) => Sequence;
14
15
  /** A mailbox. Instantly keys accounts by email address, not by an id. */
15
- export declare const toSender: (identity: Identity, raw: JsonObject) => Sender;
16
+ export declare const toSender: (identity: Identity, raw: JsonObject, note: Note) => Sender;
16
17
  export declare const toWorkspace: (identity: Identity, raw: JsonObject) => Workspace;
17
18
  export interface ListEnvelope {
18
19
  readonly items: JsonObject[];
@@ -25,6 +25,12 @@ export interface AdapterContext {
25
25
  readonly request: (spec: RequestSpec) => Promise<VendorResponse>;
26
26
  /** The context for another adapter, with that adapter's own rate budget. */
27
27
  readonly forAdapter: (adapter: Adapter) => AdapterContext;
28
+ /**
29
+ * Says what the adapter left out of a record and why, for example a value
30
+ * the vendor sent that cannot be right. It reaches the caller in
31
+ * `meta.notes`.
32
+ */
33
+ readonly note: (text: string) => void;
28
34
  }
29
35
  /** One page from the vendor. `next` is whatever the adapter needs to continue. */
30
36
  export interface Page<Item> {
@@ -64,12 +70,18 @@ export interface LeadQuery extends PageQuery, TimeRange {
64
70
  * A subdomain is another domain.
65
71
  */
66
72
  readonly domain?: string | undefined;
73
+ /** Only the lead records with one of these addresses, each lowercased. One per campaign each person is in. */
74
+ readonly emails?: readonly string[] | undefined;
75
+ /** `positive`: only the leads the vendor labels positive, whose `interestCategory` is `positive`. */
76
+ readonly interest?: "positive" | undefined;
67
77
  }
68
78
  export interface MessageQuery extends PageQuery, TimeRange {
69
79
  readonly campaignId?: string | undefined;
70
80
  readonly leadId?: string | undefined;
71
81
  /** A `threadId` from an earlier message. */
72
82
  readonly threadId?: string | undefined;
83
+ /** `true` for the messages a person sent by hand only. */
84
+ readonly byHand?: true | undefined;
73
85
  /** Bodies are expensive on some vendors, so they are fetched only on request. */
74
86
  readonly includeBody: boolean;
75
87
  }
@@ -78,6 +90,11 @@ export interface ReplyQuery extends PageQuery, TimeRange {
78
90
  readonly category?: ReplyCategory | undefined;
79
91
  /** `true` for unread replies only, `false` for read ones only. */
80
92
  readonly unread?: boolean | undefined;
93
+ /**
94
+ * Also return replies from conversations that belong to no campaign. Only
95
+ * an adapter whose `replies.inbox` capability is true has any.
96
+ */
97
+ readonly includeInbox?: boolean | undefined;
81
98
  readonly includeBody: boolean;
82
99
  }
83
100
  export interface SubsequenceQuery extends PageQuery {
@@ -33,6 +33,10 @@ export interface Capabilities {
33
33
  "leads.lookup": boolean;
34
34
  /** Find the leads whose email address is at one domain, without walking every lead. */
35
35
  "leads.byDomain": boolean;
36
+ /** Find the leads of many exact email addresses in one listing, without one lookup each. */
37
+ "leads.lookupMany": boolean;
38
+ /** List only the leads the vendor labels positive, without walking every lead. */
39
+ "leads.byInterest": boolean;
36
40
  /** Leads carry open, click and reply counts. */
37
41
  "leads.engagement": boolean;
38
42
  /** List the saved lead lists. */
@@ -49,12 +53,21 @@ export interface Capabilities {
49
53
  "messages.since": FilterGrade;
50
54
  /** Every message of one conversation, by its thread id. */
51
55
  "messages.byThread": boolean;
56
+ /** Only the messages a person sent by hand, not the ones a campaign sent. */
57
+ "messages.byHand": boolean;
52
58
  "replies.list": boolean;
53
59
  /** Reply categories come from the vendor, or are not available. */
54
60
  "replies.category": "vendor" | false;
55
61
  "replies.since": FilterGrade;
56
62
  /** Only the replies that are unread, or only the ones that are read. */
57
63
  "replies.unread": FilterGrade;
64
+ /**
65
+ * The vendor's inbox also holds conversations that belong to no campaign,
66
+ * such as a LinkedIn account's own messages. Their replies are left out of
67
+ * `replies.list` unless it is asked for `includeInbox`, and their messages
68
+ * and replies carry a null `campaignRef`.
69
+ */
70
+ "replies.inbox": boolean;
58
71
  "stats.workspace": StatGrade;
59
72
  "stats.campaign": StatGrade;
60
73
  /**
@@ -1,5 +1,5 @@
1
1
  import type { OutboundHooks } from "../hooks.ts";
2
- import type { LimitDeclaration } from "../limits.ts";
2
+ import type { LimitDeclaration, RateWindow } from "../limits.ts";
3
3
  import type { RateLimitStore } from "./rate-store.ts";
4
4
  import type { Runtime } from "./runtime.ts";
5
5
  export declare const DEFAULT_LANE = "default";
@@ -28,12 +28,20 @@ export interface BudgetOptions {
28
28
  export declare class Budget {
29
29
  #private;
30
30
  constructor(options: BudgetOptions);
31
+ /** The windows a request on `lane` must fit, after `share` and any slowdown. */
32
+ windows(lane: string): readonly RateWindow[];
31
33
  /**
32
34
  * Waits for a concurrency slot and for room in every window. Returns how
33
35
  * long it waited. The caller must call `release()` afterwards.
34
36
  */
35
37
  acquire(options: AcquireOptions): Promise<number>;
36
38
  release(): void;
39
+ /**
40
+ * How long to pause a lane after a 429 that names no wait: the spacing of
41
+ * its tightest published window, at least a second. For a limit of 20 a
42
+ * minute that is 3 s, the time one more request takes to fit.
43
+ */
44
+ vendorPauseMs(lane: string): number;
37
45
  /** Called on a 429: pause the lane and halve the rate. */
38
46
  rateLimited(lane: string, retryAfterMs: number, now: number): Promise<void>;
39
47
  /** Called when the vendor's headers say the window is spent. */
@@ -40,6 +40,7 @@ export declare class RequestEngine {
40
40
  now(): number;
41
41
  /** Starts the accounting for one SDK call. */
42
42
  begin(options?: OperationOptions): CallState;
43
- contextFor(adapter: Adapter, state: CallState): AdapterContext;
43
+ /** `notes` collects what the adapter says it left out; the call's own by default. */
44
+ contextFor(adapter: Adapter, state: CallState, notes?: string[]): AdapterContext;
44
45
  limits(adapter: Adapter): Promise<LimitsSnapshot>;
45
46
  }
@@ -27,6 +27,8 @@ export interface CallState {
27
27
  * the one already set.
28
28
  */
29
29
  beforeRequest: (() => void) | undefined;
30
+ /** What the adapter left out of the answer, and why. Each note once. */
31
+ readonly notes: string[];
30
32
  }
31
33
  export interface RequestEnvironment {
32
34
  readonly adapter: Adapter;
@@ -47,6 +47,11 @@ export interface OutboundErrorOptions {
47
47
  readonly limit?: RequestLimit | undefined;
48
48
  /** What a `toArray()` walk had fetched when it stopped. */
49
49
  readonly partial?: PartialWalk | undefined;
50
+ /**
51
+ * `true` when the same call fails the same way again, whatever the code:
52
+ * for example a `Provider` error for a vendor record the SDK cannot read.
53
+ */
54
+ readonly permanent?: boolean | undefined;
50
55
  /** Secrets to strip from the message. */
51
56
  readonly secrets?: readonly string[] | undefined;
52
57
  }