outbound-sdk 0.0.0-stage → 0.2.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 (284) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +119 -2
  3. package/dist/alerts/index.d.ts +2 -0
  4. package/dist/alerts/index.js +140 -0
  5. package/dist/alerts/plugin.d.ts +58 -0
  6. package/dist/audit/index.d.ts +33 -0
  7. package/dist/audit/index.js +60 -0
  8. package/dist/benchmarks/index.d.ts +29 -0
  9. package/dist/benchmarks/index.js +72 -0
  10. package/dist/budget/index.d.ts +21 -0
  11. package/dist/budget/index.js +71 -0
  12. package/dist/cache/index.d.ts +31 -0
  13. package/dist/cache/index.js +11 -0
  14. package/dist/cards/content.d.ts +43 -0
  15. package/dist/cards/copy-cards.d.ts +2 -0
  16. package/dist/cards/format.d.ts +39 -0
  17. package/dist/cards/index.d.ts +9 -0
  18. package/dist/cards/index.js +2070 -0
  19. package/dist/cards/notify-cards.d.ts +14 -0
  20. package/dist/cards/ops-cards.d.ts +2 -0
  21. package/dist/cards/parts.d.ts +22 -0
  22. package/dist/cards/people-cards.d.ts +2 -0
  23. package/dist/cards/render.d.ts +28 -0
  24. package/dist/cards/sender-cards.d.ts +2 -0
  25. package/dist/cards/slack-rich.d.ts +19 -0
  26. package/dist/cards/slack-text.d.ts +10 -0
  27. package/dist/cards/slack.d.ts +21 -0
  28. package/dist/cards/spec.d.ts +86 -0
  29. package/dist/cards/tool-cards.d.ts +4 -0
  30. package/dist/chunks/chunk-4O2HRTTI.js +75 -0
  31. package/dist/chunks/chunk-4PSO6JEK.js +357 -0
  32. package/dist/chunks/chunk-6CVZOUHB.js +152 -0
  33. package/dist/chunks/chunk-AFU5E5QB.js +714 -0
  34. package/dist/chunks/chunk-DJ2IUQEU.js +111 -0
  35. package/dist/chunks/chunk-E7JHLNLG.js +187 -0
  36. package/dist/chunks/chunk-FHKSLCVW.js +154 -0
  37. package/dist/chunks/chunk-FKH5N47I.js +40 -0
  38. package/dist/chunks/chunk-HZCTYL22.js +29 -0
  39. package/dist/chunks/chunk-IPUYZD4O.js +25 -0
  40. package/dist/chunks/chunk-IVH3NMQZ.js +61 -0
  41. package/dist/chunks/chunk-LVYG7XZJ.js +45 -0
  42. package/dist/chunks/chunk-NAKXLBA6.js +30 -0
  43. package/dist/chunks/chunk-NAWZ73QS.js +22 -0
  44. package/dist/chunks/chunk-PMSSUWD7.js +636 -0
  45. package/dist/chunks/chunk-PURHK3JU.js +432 -0
  46. package/dist/chunks/chunk-R3Y56YVF.js +43 -0
  47. package/dist/chunks/chunk-RCZ7ZZFU.js +92 -0
  48. package/dist/chunks/chunk-SBIZDCRY.js +106 -0
  49. package/dist/chunks/chunk-U2D34ARZ.js +41 -0
  50. package/dist/chunks/chunk-UAT3JSJZ.js +331 -0
  51. package/dist/chunks/chunk-VQSCHOBV.js +111 -0
  52. package/dist/chunks/chunk-XC6CZP73.js +80 -0
  53. package/dist/chunks/chunk-XNFESPZH.js +2307 -0
  54. package/dist/chunks/chunk-YOTW5ESM.js +118 -0
  55. package/dist/cli/bin.d.ts +2 -0
  56. package/dist/cli/bin.js +35 -0
  57. package/dist/cli/commands.d.ts +19 -0
  58. package/dist/cli/config.d.ts +22 -0
  59. package/dist/cli/index.d.ts +17 -0
  60. package/dist/cli/index.js +30 -0
  61. package/dist/cli/mcp.d.ts +14 -0
  62. package/dist/cli/stdio.d.ts +9 -0
  63. package/dist/clients/index.d.ts +2 -0
  64. package/dist/clients/index.js +117 -0
  65. package/dist/clients/plugin.d.ts +42 -0
  66. package/dist/combine/account.d.ts +4 -0
  67. package/dist/combine/adapter.d.ts +9 -0
  68. package/dist/combine/index.d.ts +2 -0
  69. package/dist/combine/index.js +420 -0
  70. package/dist/combine/route.d.ts +24 -0
  71. package/dist/exporter/index.d.ts +29 -0
  72. package/dist/exporter/index.js +77 -0
  73. package/dist/failover/index.d.ts +11 -0
  74. package/dist/failover/index.js +45 -0
  75. package/dist/fixtures/index.d.ts +27 -0
  76. package/dist/fixtures/index.js +260 -0
  77. package/dist/fixtures/scrub.d.ts +5 -0
  78. package/dist/heyreach/account.d.ts +11 -0
  79. package/dist/heyreach/adapter.d.ts +5 -0
  80. package/dist/heyreach/capabilities.d.ts +70 -0
  81. package/dist/heyreach/client.d.ts +18 -0
  82. package/dist/heyreach/inbox.d.ts +7 -0
  83. package/dist/heyreach/index.d.ts +25 -0
  84. package/dist/heyreach/index.js +1931 -0
  85. package/dist/heyreach/leads.d.ts +4 -0
  86. package/dist/heyreach/lookup.d.ts +15 -0
  87. package/dist/heyreach/map-account.d.ts +31 -0
  88. package/dist/heyreach/map-sequence.d.ts +5 -0
  89. package/dist/heyreach/map-stats.d.ts +13 -0
  90. package/dist/heyreach/map.d.ts +37 -0
  91. package/dist/heyreach/native-organization.d.ts +128 -0
  92. package/dist/heyreach/native-voice.d.ts +106 -0
  93. package/dist/heyreach/native.d.ts +496 -0
  94. package/dist/heyreach/paging.d.ts +7 -0
  95. package/dist/heyreach/webhooks.d.ts +3 -0
  96. package/dist/identity/index.d.ts +3 -0
  97. package/dist/identity/index.js +159 -0
  98. package/dist/identity/keys.d.ts +9 -0
  99. package/dist/identity/plugin.d.ts +34 -0
  100. package/dist/index.d.ts +33 -0
  101. package/dist/index.js +131 -0
  102. package/dist/insights/copy/copy-audit.d.ts +55 -0
  103. package/dist/insights/copy/copy-checks.d.ts +44 -0
  104. package/dist/insights/copy/copy-reuse.d.ts +59 -0
  105. package/dist/insights/copy/index.d.ts +67 -0
  106. package/dist/insights/copy/reply-timing.d.ts +63 -0
  107. package/dist/insights/copy/shared.d.ts +53 -0
  108. package/dist/insights/copy/step-funnel.d.ts +66 -0
  109. package/dist/insights/copy/variant-test.d.ts +64 -0
  110. package/dist/insights/define.d.ts +98 -0
  111. package/dist/insights/index.d.ts +10 -0
  112. package/dist/insights/index.js +4937 -0
  113. package/dist/insights/ops/anomalies.d.ts +80 -0
  114. package/dist/insights/ops/campaign-diagnosis.d.ts +39 -0
  115. package/dist/insights/ops/campaign-ranking.d.ts +56 -0
  116. package/dist/insights/ops/channel-mix.d.ts +44 -0
  117. package/dist/insights/ops/client-report.d.ts +76 -0
  118. package/dist/insights/ops/diagnosis-checks.d.ts +48 -0
  119. package/dist/insights/ops/index.d.ts +135 -0
  120. package/dist/insights/ops/period-comparison.d.ts +86 -0
  121. package/dist/insights/ops/pipeline-forecast.d.ts +44 -0
  122. package/dist/insights/ops/shared.d.ts +155 -0
  123. package/dist/insights/ops/tag-rollup.d.ts +32 -0
  124. package/dist/insights/people/account-summary.d.ts +68 -0
  125. package/dist/insights/people/dropped-replies.d.ts +51 -0
  126. package/dist/insights/people/find.d.ts +18 -0
  127. package/dist/insights/people/hot-leads.d.ts +67 -0
  128. package/dist/insights/people/index.d.ts +88 -0
  129. package/dist/insights/people/lead-collisions.d.ts +43 -0
  130. package/dist/insights/people/person-summary.d.ts +46 -0
  131. package/dist/insights/people/personalization-gaps.d.ts +60 -0
  132. package/dist/insights/people/read.d.ts +40 -0
  133. package/dist/insights/people/suppression-check.d.ts +53 -0
  134. package/dist/insights/plugin.d.ts +40 -0
  135. package/dist/insights/registry.d.ts +335 -0
  136. package/dist/insights/senders/bounce-watch.d.ts +70 -0
  137. package/dist/insights/senders/domain-health.d.ts +69 -0
  138. package/dist/insights/senders/index.d.ts +74 -0
  139. package/dist/insights/senders/read.d.ts +37 -0
  140. package/dist/insights/senders/sender-capacity.d.ts +67 -0
  141. package/dist/insights/senders/sender-load.d.ts +52 -0
  142. package/dist/insights/senders/settings-audit.d.ts +48 -0
  143. package/dist/insights/senders/warmup-readiness.d.ts +39 -0
  144. package/dist/insights/stats.d.ts +45 -0
  145. package/dist/insights/tools.d.ts +16 -0
  146. package/dist/insights/types.d.ts +4 -0
  147. package/dist/instantly/adapter-account.d.ts +5 -0
  148. package/dist/instantly/adapter-mail.d.ts +3 -0
  149. package/dist/instantly/adapter.d.ts +7 -0
  150. package/dist/instantly/capabilities.d.ts +85 -0
  151. package/dist/instantly/client.d.ts +24 -0
  152. package/dist/instantly/index.d.ts +27 -0
  153. package/dist/instantly/index.js +2627 -0
  154. package/dist/instantly/map-account.d.ts +38 -0
  155. package/dist/instantly/map-lead.d.ts +18 -0
  156. package/dist/instantly/map-stats.d.ts +25 -0
  157. package/dist/instantly/map.d.ts +22 -0
  158. package/dist/instantly/native-agents-sales.d.ts +161 -0
  159. package/dist/instantly/native-agents.d.ts +156 -0
  160. package/dist/instantly/native-campaigns.d.ts +101 -0
  161. package/dist/instantly/native-leads.d.ts +93 -0
  162. package/dist/instantly/native-params.d.ts +7 -0
  163. package/dist/instantly/native-search.d.ts +82 -0
  164. package/dist/instantly/native-senders.d.ts +182 -0
  165. package/dist/instantly/native-supersearch.d.ts +149 -0
  166. package/dist/instantly/native-workspace.d.ts +170 -0
  167. package/dist/instantly/native.d.ts +1081 -0
  168. package/dist/instantly/pages.d.ts +29 -0
  169. package/dist/instantly/stats.d.ts +5 -0
  170. package/dist/instantly/webhooks.d.ts +3 -0
  171. package/dist/internal/adapter.d.ts +211 -0
  172. package/dist/internal/capabilities.d.ts +104 -0
  173. package/dist/internal/client.d.ts +15 -0
  174. package/dist/internal/concurrency.d.ts +8 -0
  175. package/dist/internal/cursor.d.ts +10 -0
  176. package/dist/internal/engine/budget.d.ts +44 -0
  177. package/dist/internal/engine/engine.d.ts +45 -0
  178. package/dist/internal/engine/rate-store.d.ts +25 -0
  179. package/dist/internal/engine/request.d.ts +34 -0
  180. package/dist/internal/engine/retry.d.ts +21 -0
  181. package/dist/internal/engine/runtime.d.ts +13 -0
  182. package/dist/internal/entities-account.d.ts +205 -0
  183. package/dist/internal/entities.d.ts +493 -0
  184. package/dist/internal/env.d.ts +4 -0
  185. package/dist/internal/errors.d.ts +62 -0
  186. package/dist/internal/fields.d.ts +462 -0
  187. package/dist/internal/hooks.d.ts +55 -0
  188. package/dist/internal/json.d.ts +49 -0
  189. package/dist/internal/lead-fields.d.ts +21 -0
  190. package/dist/internal/lead-status.d.ts +13 -0
  191. package/dist/internal/limits.d.ts +34 -0
  192. package/dist/internal/metrics.d.ts +64 -0
  193. package/dist/internal/native.d.ts +81 -0
  194. package/dist/internal/outbound/api.d.ts +292 -0
  195. package/dist/internal/outbound/collections.d.ts +31 -0
  196. package/dist/internal/outbound/core.d.ts +36 -0
  197. package/dist/internal/outbound/create.d.ts +16 -0
  198. package/dist/internal/outbound/handles.d.ts +7 -0
  199. package/dist/internal/outbound/native.d.ts +4 -0
  200. package/dist/internal/outbound/operation-shared.d.ts +28 -0
  201. package/dist/internal/outbound/operations-account.d.ts +41 -0
  202. package/dist/internal/outbound/operations.d.ts +42 -0
  203. package/dist/internal/outbound/outbound.d.ts +67 -0
  204. package/dist/internal/outbound/plugins.d.ts +40 -0
  205. package/dist/internal/outbound/raw.d.ts +9 -0
  206. package/dist/internal/outbound/specs-account.d.ts +20 -0
  207. package/dist/internal/outbound/specs.d.ts +14 -0
  208. package/dist/internal/outbound/stats.d.ts +7 -0
  209. package/dist/internal/outbound/validate.d.ts +5 -0
  210. package/dist/internal/outbound/walker.d.ts +22 -0
  211. package/dist/internal/page.d.ts +14 -0
  212. package/dist/internal/record.d.ts +36 -0
  213. package/dist/internal/records.d.ts +7 -0
  214. package/dist/internal/redact.d.ts +18 -0
  215. package/dist/internal/ref.d.ts +16 -0
  216. package/dist/internal/sequence.d.ts +14 -0
  217. package/dist/internal/sha256.d.ts +6 -0
  218. package/dist/internal/text.d.ts +11 -0
  219. package/dist/internal/url.d.ts +9 -0
  220. package/dist/loader/index.d.ts +24 -0
  221. package/dist/loader/index.js +16 -0
  222. package/dist/memory/account-reads.d.ts +5 -0
  223. package/dist/memory/account.d.ts +81 -0
  224. package/dist/memory/adapter.d.ts +16 -0
  225. package/dist/memory/data.d.ts +137 -0
  226. package/dist/memory/demo.d.ts +7 -0
  227. package/dist/memory/index.d.ts +5 -0
  228. package/dist/memory/index.js +867 -0
  229. package/dist/memory/stats.d.ts +6 -0
  230. package/dist/memory/store.d.ts +18 -0
  231. package/dist/providers/index.d.ts +22 -0
  232. package/dist/providers/index.js +10 -0
  233. package/dist/reconcile/index.d.ts +2 -0
  234. package/dist/reconcile/index.js +72 -0
  235. package/dist/reconcile/plugin.d.ts +55 -0
  236. package/dist/redact/index.d.ts +2 -0
  237. package/dist/redact/index.js +197 -0
  238. package/dist/redact/plugin.d.ts +22 -0
  239. package/dist/redis/index.d.ts +41 -0
  240. package/dist/redis/index.js +114 -0
  241. package/dist/smartlead/account.d.ts +5 -0
  242. package/dist/smartlead/adapter.d.ts +5 -0
  243. package/dist/smartlead/capabilities.d.ts +87 -0
  244. package/dist/smartlead/client.d.ts +18 -0
  245. package/dist/smartlead/hmac.d.ts +7 -0
  246. package/dist/smartlead/index.d.ts +24 -0
  247. package/dist/smartlead/index.js +2329 -0
  248. package/dist/smartlead/leads.d.ts +9 -0
  249. package/dist/smartlead/lookup.d.ts +8 -0
  250. package/dist/smartlead/mail.d.ts +5 -0
  251. package/dist/smartlead/map-account.d.ts +34 -0
  252. package/dist/smartlead/map-messages.d.ts +31 -0
  253. package/dist/smartlead/map-stats.d.ts +36 -0
  254. package/dist/smartlead/map.d.ts +62 -0
  255. package/dist/smartlead/native-analytics.d.ts +242 -0
  256. package/dist/smartlead/native-campaigns.d.ts +211 -0
  257. package/dist/smartlead/native-inbox.d.ts +141 -0
  258. package/dist/smartlead/native-params.d.ts +12 -0
  259. package/dist/smartlead/native-services.d.ts +204 -0
  260. package/dist/smartlead/native.d.ts +785 -0
  261. package/dist/smartlead/shared.d.ts +29 -0
  262. package/dist/smartlead/stats.d.ts +5 -0
  263. package/dist/smartlead/webhooks.d.ts +3 -0
  264. package/dist/sync/index.d.ts +2 -0
  265. package/dist/sync/index.js +158 -0
  266. package/dist/sync/plugin.d.ts +58 -0
  267. package/dist/tools/account-tools.d.ts +21 -0
  268. package/dist/tools/ai-sdk.d.ts +8 -0
  269. package/dist/tools/ai-sdk.js +28 -0
  270. package/dist/tools/campaign-tools.d.ts +59 -0
  271. package/dist/tools/claude-agent.d.ts +18 -0
  272. package/dist/tools/claude-agent.js +42 -0
  273. package/dist/tools/index.d.ts +28 -0
  274. package/dist/tools/index.js +22 -0
  275. package/dist/tools/people-tools.d.ts +19 -0
  276. package/dist/tools/registry.d.ts +34 -0
  277. package/dist/tools/shared.d.ts +75 -0
  278. package/dist/tracing/index.d.ts +25 -0
  279. package/dist/tracing/index.js +69 -0
  280. package/dist/webhooks/index.d.ts +3 -0
  281. package/dist/webhooks/index.js +227 -0
  282. package/dist/webhooks/parse.d.ts +41 -0
  283. package/dist/webhooks/secret.d.ts +4 -0
  284. package/package.json +181 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Orchid Automation
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,120 @@
1
- # Temporary Holding Version
1
+ # outbound-sdk
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ One small, typed, read-only TypeScript API over outbound sending tools: Instantly, Smartlead and HeyReach.
4
+
5
+ - **Read-only.** It never sends, pauses, edits or deletes anything in a vendor tool.
6
+ - **Stores nothing.** A plugin that keeps state takes a store you supply.
7
+ - **Calls no AI model.** Your agent does the reasoning; the SDK supplies the numbers.
8
+ - **Swap the adapter, keep the code.**
9
+
10
+ > HeyReach and Instantly are `beta`: their reads were run against a live workspace each. Smartlead ships untested: it has never been run against a live account, and is written from public documentation and tested offline only.
11
+
12
+ ## Install
13
+
14
+ ```sh
15
+ npm install outbound-sdk
16
+ ```
17
+
18
+ Node 22 or later, Bun, or any runtime with `fetch`. `zod` is the only dependency.
19
+
20
+ ## Use
21
+
22
+ ```ts
23
+ import { createOutbound } from "outbound-sdk";
24
+ import { instantly } from "outbound-sdk/instantly";
25
+
26
+ const outbound = createOutbound({ adapter: instantly() }); // reads INSTANTLY_API_KEY
27
+
28
+ const page = await outbound.campaigns.list({ status: "active", limit: 100 });
29
+
30
+ for await (const campaign of outbound.campaigns.listAll()) {
31
+ // every page, fetched under the vendor's rate limit
32
+ }
33
+
34
+ const campaign = outbound.campaign(page.items[0].ref);
35
+ await campaign.sequence();
36
+ await campaign.stats({ from: "2026-10-01", to: "2026-10-31", by: "day" });
37
+ for await (const lead of campaign.leads.listAll()) {
38
+ }
39
+ ```
40
+
41
+ Change the vendor by changing one import:
42
+
43
+ ```ts
44
+ import { heyreach } from "outbound-sdk/heyreach";
45
+ import { smartlead } from "outbound-sdk/smartlead";
46
+ ```
47
+
48
+ Several tools or several clients behind one instance:
49
+
50
+ ```ts
51
+ import { combine } from "outbound-sdk/combine";
52
+
53
+ const outbound = createOutbound({
54
+ adapter: combine([
55
+ instantly({ apiKey: clientA.instantlyKey, workspaceId: "client-a" }),
56
+ heyreach({ apiKey: clientA.heyreachKey, workspaceId: "client-a" }),
57
+ ]),
58
+ });
59
+ ```
60
+
61
+ ## What you get back
62
+
63
+ Every record carries `provider`, `workspaceId` and a `ref` (`provider:workspace:id`), so data from two tools or two clients can never be confused. A count the vendor does not report is `null`, never `0`. Every result carries `meta`:
64
+
65
+ ```ts
66
+ page.meta; // { evidence: "exact" | "sampled" | "derived", fetchedAt, complete, requests, throttledMs, stale, ... }
67
+ ```
68
+
69
+ Collections: `campaigns`, `senders`, `leads`, `messages`, `replies`, `lists`, `tags`, `blocklist`, `webhooks` and `workspaces`, each with `list` and `listAll`, and `get`, `exists` and `getMany` where a record can be looked up. Handles: `campaign(id)` (with `settings()`, `sequence()`, `subsequences`, `stats()`), `sender(id)` (with `health()`, `warmup()`, `stats()`), `lead(id)`, `list(id)` and `thread(id)`. Also `stats()`, `limits()`, `estimate()`, `capabilities` and `caveats`.
70
+
71
+ ## Nothing a vendor reports is dropped
72
+
73
+ The collections above are what every vendor shares. Everything else a vendor can report is in `outbound.native`, a catalog typed from the adapter you passed:
74
+
75
+ ```ts
76
+ const outbound = createOutbound({ adapter: smartlead() });
77
+ const unread = await outbound.native.reads.inboxUnread({ limit: 20 });
78
+ unread.data; // Smartlead's own response
79
+ ```
80
+
81
+ Native reads are rate limited and retried like the rest, can only read, and return the vendor's payload as sent. `outbound.raw` remains for a request the catalog does not name (reads only unless `allowWrites: true`).
82
+
83
+ ## Answers, not only records
84
+
85
+ `outbound-sdk/insights` adds 26 computed answers on top of the reads: one person across email and LinkedIn, replies nobody answered, where a sequence's replies come from, whether an A/B winner is real, deliverability per domain, why a campaign is underperforming, a weekly client report. Each is a typed method, an agent tool and a CLI command, and none calls a model.
86
+
87
+ ```ts
88
+ const outbound = createOutbound({ adapter, plugins: [insights()] });
89
+ const person = await outbound.insights.personSummary({
90
+ person: "jane@example.com",
91
+ });
92
+ ```
93
+
94
+ See [the insights](https://outbound-sdk.dev/docs/insights).
95
+
96
+ ## It tells you what it cannot do
97
+
98
+ An adapter declares what it supports. A call that needs something unsupported throws `Unsupported` before any request leaves:
99
+
100
+ ```ts
101
+ outbound.capabilities["replies.category"]; // "vendor" or false
102
+ ```
103
+
104
+ There is one error class, `OutboundError`, with a `code`: `NotFound`, `Unauthorized`, `RateLimited`, `Provider`, `Invalid` or `Unsupported`. API keys and email addresses are removed from every message, and from the `cause` an error keeps (a redacted copy of the vendor response or the original error).
105
+
106
+ ## Rate limits, retries and resuming
107
+
108
+ You never write a sleep or a retry loop, and you can fire hundreds of reads at once. Every request stays inside every limit the vendor publishes, one budget is shared by every instance on the same key, a 429 is waited out, and reads are retried with backoff. `listAll` exposes a `cursor`, so a job that dies on page 40 restarts on page 40. Set `timeout`, `retries`, `deadline` and `maxRequests` on the constructor or on any call. With several workers on one key, `outbound-sdk/redis` shares one budget between them.
109
+
110
+ ## More
111
+
112
+ - [Adapters and what each can do](https://outbound-sdk.dev/docs/adapters)
113
+ - [Plugins](https://outbound-sdk.dev/docs/plugins): `combine`, `clients`, `identity`, `redact`, `cache`, `budget`, `audit`, `tracing`, `sync`, `reconcile`, `alerts`, `benchmarks`, `fixtures`, `exporter`, `failover`
114
+ - [AI tools](https://outbound-sdk.dev/docs/tools), the [CLI and MCP server](https://outbound-sdk.dev/docs/cli) and [webhooks](https://outbound-sdk.dev/docs/webhooks)
115
+ - [Guides](https://outbound-sdk.dev/guides) and [what is verified](https://outbound-sdk.dev/docs/status)
116
+ - [Architecture](https://github.com/orchidautomation/outbound-sdk/blob/main/docs/architecture.md)
117
+
118
+ ## License
119
+
120
+ MIT
@@ -0,0 +1,2 @@
1
+ export { alerts, bounceRateAbove, memoryAlertDedupe, noSends, replyRateBelow, senderNotActive, } from "./plugin.ts";
2
+ export type { Alert, AlertDedupe, AlertRule, AlertsExtension, AlertsOptions, RateRuleOptions, } from "./plugin.ts";
@@ -0,0 +1,140 @@
1
+ import {
2
+ computeRates
3
+ } from "../chunks/chunk-YOTW5ESM.js";
4
+ import "../chunks/chunk-4PSO6JEK.js";
5
+ import "../chunks/chunk-LVYG7XZJ.js";
6
+ import "../chunks/chunk-E7JHLNLG.js";
7
+ import "../chunks/chunk-VQSCHOBV.js";
8
+
9
+ // src/alerts/plugin.ts
10
+ var memoryAlertDedupe = () => {
11
+ const keys = /* @__PURE__ */ new Set();
12
+ return {
13
+ add: (key) => {
14
+ keys.add(key);
15
+ },
16
+ has: (key) => keys.has(key)
17
+ };
18
+ };
19
+ var isMetricRow = (record) => "scope" in record;
20
+ var isSender = (record) => "kind" in record && "dailyLimit" in record;
21
+ var percent = (value) => `${(value * 100).toFixed(1)}%`;
22
+ var bounceRateAbove = (threshold, options = {}) => ({
23
+ check: (record) => {
24
+ if (!isMetricRow(record) || (record.sent ?? 0) < (options.minSent ?? 50)) {
25
+ return null;
26
+ }
27
+ const { value } = computeRates(record).bounceRate;
28
+ return value !== null && value > threshold ? {
29
+ message: `Bounce rate is ${percent(value)}, above ${percent(threshold)}`,
30
+ rule: "bounce-rate-above",
31
+ subject: record.scopeRef,
32
+ threshold,
33
+ value
34
+ } : null;
35
+ },
36
+ name: "bounce-rate-above"
37
+ });
38
+ var replyRateBelow = (threshold, options = {}) => ({
39
+ check: (record) => {
40
+ if (!isMetricRow(record) || (record.sent ?? 0) < (options.minSent ?? 50)) {
41
+ return null;
42
+ }
43
+ const { value } = computeRates(record).replyRate;
44
+ return value !== null && value < threshold ? {
45
+ message: `Reply rate is ${percent(value)}, below ${percent(threshold)}`,
46
+ rule: "reply-rate-below",
47
+ subject: record.scopeRef,
48
+ threshold,
49
+ value
50
+ } : null;
51
+ },
52
+ name: "reply-rate-below"
53
+ });
54
+ var senderNotActive = () => ({
55
+ check: (record) => isSender(record) && record.status !== "active" && record.status !== "unknown" ? {
56
+ message: `Sender is ${record.status}`,
57
+ rule: "sender-not-active",
58
+ subject: record.ref,
59
+ threshold: "active",
60
+ value: record.status
61
+ } : null,
62
+ name: "sender-not-active"
63
+ });
64
+ var noSends = () => ({
65
+ check: (record) => isMetricRow(record) && record.date !== null && record.sent === 0 ? {
66
+ message: `Nothing was sent on ${record.date}`,
67
+ rule: "no-sends",
68
+ subject: record.scopeRef,
69
+ threshold: 1,
70
+ value: 0
71
+ } : null,
72
+ name: "no-sends"
73
+ });
74
+ var ignore = () => {
75
+ };
76
+ var fresh = async (fired, seen) => {
77
+ const unseen = [];
78
+ for (const alert of fired) {
79
+ const key = `${alert.rule}|${alert.subject}`;
80
+ if (!await seen.has(key)) {
81
+ await seen.add(key);
82
+ unseen.push(alert);
83
+ }
84
+ }
85
+ return unseen;
86
+ };
87
+ var alerts = (options) => {
88
+ const evaluate = (records) => records.flatMap(
89
+ (record) => options.rules.flatMap((rule) => {
90
+ const alert = rule.check(record);
91
+ return alert === null ? [] : [alert];
92
+ })
93
+ );
94
+ const { dedupe } = options;
95
+ let last = Promise.resolve();
96
+ const notifyFresh = (fired, seen) => {
97
+ last = (async () => {
98
+ try {
99
+ await last;
100
+ const due = await fresh(fired, seen);
101
+ if (due.length > 0) {
102
+ await options.notify(due);
103
+ }
104
+ } catch {
105
+ ignore();
106
+ }
107
+ })();
108
+ };
109
+ const notifyAll = (fired) => {
110
+ try {
111
+ Promise.resolve(options.notify(fired)).catch(ignore);
112
+ } catch {
113
+ ignore();
114
+ }
115
+ };
116
+ return {
117
+ extend: () => ({ alerts: { evaluate } }),
118
+ name: "alerts",
119
+ wrap: async (operation, next) => {
120
+ const output = await next(operation);
121
+ const fired = evaluate(output.items);
122
+ if (fired.length > 0) {
123
+ if (dedupe === void 0) {
124
+ notifyAll(fired);
125
+ } else {
126
+ notifyFresh(fired, dedupe);
127
+ }
128
+ }
129
+ return output;
130
+ }
131
+ };
132
+ };
133
+ export {
134
+ alerts,
135
+ bounceRateAbove,
136
+ memoryAlertDedupe,
137
+ noSends,
138
+ replyRateBelow,
139
+ senderNotActive
140
+ };
@@ -0,0 +1,58 @@
1
+ import type { OutboundRecord } from "../internal/outbound/operations.ts";
2
+ import type { OutboundPlugin } from "../internal/outbound/plugins.ts";
3
+ export interface Alert {
4
+ /** The rule's name. */
5
+ readonly rule: string;
6
+ /** The ref of the campaign, sender or workspace it is about. */
7
+ readonly subject: string;
8
+ readonly message: string;
9
+ /** What was measured. */
10
+ readonly value: number | string | null;
11
+ /** What it was compared with. */
12
+ readonly threshold: number | string | null;
13
+ }
14
+ export interface AlertRule {
15
+ readonly name: string;
16
+ /** Returns an alert when the record breaks the rule, otherwise `null`. */
17
+ readonly check: (record: OutboundRecord) => Alert | null;
18
+ }
19
+ /**
20
+ * Remembers which alerts were already notified, by a key per alert. Supply
21
+ * your own to remember across runs; the SDK stores nothing itself.
22
+ */
23
+ export interface AlertDedupe {
24
+ readonly has: (key: string) => boolean | Promise<boolean>;
25
+ readonly add: (key: string) => void | Promise<void>;
26
+ }
27
+ /** Remembers notified alerts in this process's memory, for one run or a test. */
28
+ export declare const memoryAlertDedupe: () => AlertDedupe;
29
+ export interface AlertsOptions {
30
+ readonly rules: readonly AlertRule[];
31
+ readonly notify: (alerts: readonly Alert[]) => void | Promise<void>;
32
+ /**
33
+ * Notify once per distinct alert, where an alert is its rule and its
34
+ * subject: `sender-not-active|<sender ref>`. Without it, every read that
35
+ * shows the condition notifies again.
36
+ */
37
+ readonly dedupe?: AlertDedupe | undefined;
38
+ }
39
+ export interface AlertsExtension {
40
+ readonly alerts: {
41
+ /** Checks records against the rules without notifying. */
42
+ readonly evaluate: (records: readonly OutboundRecord[]) => Alert[];
43
+ };
44
+ }
45
+ export interface RateRuleOptions {
46
+ /** Ignore rows with fewer sends than this, where a rate is noise. Defaults to 50. */
47
+ readonly minSent?: number | undefined;
48
+ }
49
+ /** Fires when a row's bounce rate is above `threshold` (0 to 1). */
50
+ export declare const bounceRateAbove: (threshold: number, options?: RateRuleOptions) => AlertRule;
51
+ /** Fires when a row's reply rate is below `threshold` (0 to 1). */
52
+ export declare const replyRateBelow: (threshold: number, options?: RateRuleOptions) => AlertRule;
53
+ /** Fires for a sender that is paused, disconnected or in error. */
54
+ export declare const senderNotActive: () => AlertRule;
55
+ /** Fires for a row that reported sends on a day with none: a sender gone quiet. */
56
+ export declare const noSends: () => AlertRule;
57
+ /** Runs fixed rules after reads and calls `notify` with what fired. */
58
+ export declare const alerts: (options: AlertsOptions) => OutboundPlugin<AlertsExtension>;
@@ -0,0 +1,33 @@
1
+ import type { RequestEvent } from "../internal/hooks.ts";
2
+ import type { OutboundPlugin } from "../internal/outbound/plugins.ts";
3
+ export interface AuditCall {
4
+ readonly type: "call";
5
+ /** ISO 8601 UTC. */
6
+ readonly at: string;
7
+ readonly operation: string;
8
+ readonly provider: string;
9
+ readonly workspaceId: string;
10
+ readonly durationMs: number;
11
+ /** Vendor requests this operation made. */
12
+ readonly requests: number;
13
+ readonly throttledMs: number;
14
+ /** Records returned. `null` when the call failed. */
15
+ readonly records: number | null;
16
+ /** The error code when the call failed. */
17
+ readonly error: string | null;
18
+ }
19
+ export interface AuditRequest extends RequestEvent {
20
+ readonly type: "request";
21
+ readonly at: string;
22
+ }
23
+ export type AuditEntry = AuditCall | AuditRequest;
24
+ export interface AuditOptions {
25
+ /** Receives every entry. A sink that throws or rejects is ignored. */
26
+ readonly sink: (entry: AuditEntry) => void | Promise<void>;
27
+ /** Also record each HTTP request, with its redacted URL. Defaults to `false`. */
28
+ readonly requests?: boolean | undefined;
29
+ /** The clock, for tests. */
30
+ readonly now?: (() => number) | undefined;
31
+ }
32
+ /** Records every call and its rate cost. */
33
+ export declare const audit: (options: AuditOptions) => OutboundPlugin;
@@ -0,0 +1,60 @@
1
+ import {
2
+ OutboundError
3
+ } from "../chunks/chunk-E7JHLNLG.js";
4
+ import "../chunks/chunk-VQSCHOBV.js";
5
+
6
+ // src/audit/index.ts
7
+ var ignore = () => {
8
+ };
9
+ var audit = (options) => {
10
+ const now = options.now ?? (() => Date.now());
11
+ const record = (entry) => {
12
+ try {
13
+ Promise.resolve(options.sink(entry)).catch(ignore);
14
+ } catch {
15
+ ignore();
16
+ }
17
+ };
18
+ return {
19
+ hooks: options.requests ? {
20
+ onRequest: (event) => {
21
+ record({
22
+ ...event,
23
+ at: new Date(now()).toISOString(),
24
+ type: "request"
25
+ });
26
+ }
27
+ } : void 0,
28
+ name: "audit",
29
+ wrap: async (operation, next, info) => {
30
+ const startedAt = now();
31
+ const before = {
32
+ requests: info.state.requests,
33
+ throttledMs: info.state.throttledMs
34
+ };
35
+ const entry = (records, error) => ({
36
+ at: new Date(startedAt).toISOString(),
37
+ durationMs: now() - startedAt,
38
+ error,
39
+ operation: operation.kind,
40
+ provider: info.provider,
41
+ records,
42
+ requests: info.state.requests - before.requests,
43
+ throttledMs: info.state.throttledMs - before.throttledMs,
44
+ type: "call",
45
+ workspaceId: info.workspaceId
46
+ });
47
+ try {
48
+ const output = await next(operation);
49
+ record(entry(output.items.length, null));
50
+ return output;
51
+ } catch (error) {
52
+ record(entry(null, OutboundError.is(error) ? error.code : "Provider"));
53
+ throw error;
54
+ }
55
+ }
56
+ };
57
+ };
58
+ export {
59
+ audit
60
+ };
@@ -0,0 +1,29 @@
1
+ import type { OperationOptions } from "../internal/engine/engine.ts";
2
+ import type { MetricName } from "../internal/metrics.ts";
3
+ import type { OutboundPlugin } from "../internal/outbound/plugins.ts";
4
+ export interface BenchmarkOptions extends OperationOptions {
5
+ readonly from?: string | undefined;
6
+ readonly to?: string | undefined;
7
+ }
8
+ export interface Comparison {
9
+ /** The campaign's rate, 0 to 1, or `null` when it cannot be computed. */
10
+ readonly value: number | null;
11
+ /** The workspace's rate over the same dates. */
12
+ readonly baseline: number | null;
13
+ /** `value / baseline`: 1.2 means 20% above the workspace. */
14
+ readonly ratio: number | null;
15
+ }
16
+ export interface CampaignBenchmark {
17
+ readonly campaign: string;
18
+ readonly comparisons: Readonly<Record<MetricName, Comparison>>;
19
+ /** Vendor requests it cost. */
20
+ readonly requests: number;
21
+ }
22
+ export interface BenchmarksExtension {
23
+ readonly benchmarks: {
24
+ /** A campaign's rates beside the whole workspace's. Costs two stats requests. */
25
+ readonly campaign: (id: string, options?: BenchmarkOptions) => Promise<CampaignBenchmark>;
26
+ };
27
+ }
28
+ /** Compares a campaign with its own workspace. */
29
+ export declare const benchmarks: () => OutboundPlugin<BenchmarksExtension>;
@@ -0,0 +1,72 @@
1
+ import {
2
+ computeRates
3
+ } from "../chunks/chunk-YOTW5ESM.js";
4
+ import "../chunks/chunk-4PSO6JEK.js";
5
+ import "../chunks/chunk-LVYG7XZJ.js";
6
+ import {
7
+ OutboundError
8
+ } from "../chunks/chunk-E7JHLNLG.js";
9
+ import "../chunks/chunk-VQSCHOBV.js";
10
+
11
+ // src/benchmarks/index.ts
12
+ var compare = (value, baseline) => ({
13
+ baseline,
14
+ ratio: value === null || baseline === null || baseline === 0 ? null : value / baseline,
15
+ value
16
+ });
17
+ var benchmarkCampaign = async (outbound, id, options) => {
18
+ const [campaign, workspace] = await Promise.all([
19
+ outbound.campaign(id).stats(options),
20
+ outbound.stats(options)
21
+ ]);
22
+ const [own] = campaign.rows;
23
+ const baseline = workspace.rows.find(
24
+ (row) => row.provider === own?.provider && row.workspaceId === own.workspaceId
25
+ );
26
+ if (own === void 0 || baseline === void 0) {
27
+ throw new OutboundError(
28
+ "NotFound",
29
+ `No stats were returned for campaign ${id}`,
30
+ {
31
+ provider: outbound.provider
32
+ }
33
+ );
34
+ }
35
+ const rates = computeRates(own);
36
+ const baselineRates = computeRates(baseline);
37
+ return {
38
+ campaign: own.scopeRef,
39
+ comparisons: {
40
+ acceptanceRate: compare(
41
+ rates.acceptanceRate.value,
42
+ baselineRates.acceptanceRate.value
43
+ ),
44
+ bounceRate: compare(
45
+ rates.bounceRate.value,
46
+ baselineRates.bounceRate.value
47
+ ),
48
+ openRate: compare(rates.openRate.value, baselineRates.openRate.value),
49
+ positiveReplyRate: compare(
50
+ rates.positiveReplyRate.value,
51
+ baselineRates.positiveReplyRate.value
52
+ ),
53
+ replyRate: compare(rates.replyRate.value, baselineRates.replyRate.value),
54
+ unsubscribeRate: compare(
55
+ rates.unsubscribeRate.value,
56
+ baselineRates.unsubscribeRate.value
57
+ )
58
+ },
59
+ requests: campaign.meta.requests + workspace.meta.requests
60
+ };
61
+ };
62
+ var benchmarks = () => ({
63
+ extend: (outbound) => ({
64
+ benchmarks: {
65
+ campaign: (id, options = {}) => benchmarkCampaign(outbound, id, options)
66
+ }
67
+ }),
68
+ name: "benchmarks"
69
+ });
70
+ export {
71
+ benchmarks
72
+ };
@@ -0,0 +1,21 @@
1
+ import type { OutboundPlugin } from "../internal/outbound/plugins.ts";
2
+ export interface BudgetOptions {
3
+ /** The most vendor requests allowed. */
4
+ readonly maxRequests: number;
5
+ /**
6
+ * `call` allows `maxRequests` for each SDK call. `run` allows it in total
7
+ * across every call on the instance, until `reset()`.
8
+ */
9
+ readonly per?: "call" | "run" | undefined;
10
+ }
11
+ export interface BudgetExtension {
12
+ readonly requestBudget: {
13
+ /** Requests counted against a `run` budget so far. */
14
+ readonly used: () => number;
15
+ readonly remaining: () => number;
16
+ /** Starts a new run. */
17
+ readonly reset: () => void;
18
+ };
19
+ }
20
+ /** Caps vendor requests per call or per run. */
21
+ export declare const budget: (options: BudgetOptions) => OutboundPlugin<BudgetExtension>;
@@ -0,0 +1,71 @@
1
+ import {
2
+ OutboundError
3
+ } from "../chunks/chunk-E7JHLNLG.js";
4
+ import "../chunks/chunk-VQSCHOBV.js";
5
+
6
+ // src/budget/index.ts
7
+ var budget = (options) => {
8
+ if (!Number.isInteger(options.maxRequests) || options.maxRequests < 1) {
9
+ throw new OutboundError(
10
+ "Invalid",
11
+ "budget() needs maxRequests to be a positive integer"
12
+ );
13
+ }
14
+ const perRun = options.per === "run";
15
+ let used = 0;
16
+ const remaining = () => Math.max(0, options.maxRequests - used);
17
+ const live = /* @__PURE__ */ new WeakMap();
18
+ const spent = (provider) => new OutboundError(
19
+ "RateLimited",
20
+ `The run used its budget of ${options.maxRequests} request(s) to ${provider}`,
21
+ { provider }
22
+ );
23
+ return {
24
+ extend: () => ({
25
+ requestBudget: {
26
+ remaining,
27
+ reset: () => {
28
+ used = 0;
29
+ },
30
+ used: () => used
31
+ }
32
+ }),
33
+ name: "budget",
34
+ wrap: async (operation, next, info) => {
35
+ const { state } = info;
36
+ if (perRun && remaining() === 0) {
37
+ throw spent(info.provider);
38
+ }
39
+ if (!perRun) {
40
+ state.maxRequests = Math.min(
41
+ state.maxRequests ?? options.maxRequests,
42
+ options.maxRequests
43
+ );
44
+ }
45
+ if (!live.has(state)) {
46
+ live.set(state, 0);
47
+ const prior = state.beforeRequest;
48
+ state.beforeRequest = () => {
49
+ prior?.();
50
+ if (perRun && remaining() === 0) {
51
+ throw spent(info.provider);
52
+ }
53
+ used += 1;
54
+ live.set(state, (live.get(state) ?? 0) + 1);
55
+ };
56
+ }
57
+ const before = state.requests;
58
+ const liveBefore = live.get(state) ?? 0;
59
+ try {
60
+ return await next(operation);
61
+ } finally {
62
+ const recorded = state.requests - before;
63
+ const sent = (live.get(state) ?? 0) - liveBefore;
64
+ used += Math.max(0, recorded - sent);
65
+ }
66
+ }
67
+ };
68
+ };
69
+ export {
70
+ budget
71
+ };
@@ -0,0 +1,31 @@
1
+ import type { Operation, OperationOutput } from "../internal/outbound/operations.ts";
2
+ import type { OutboundPlugin } from "../internal/outbound/plugins.ts";
3
+ export interface CacheEntry {
4
+ readonly output: OperationOutput;
5
+ /** When the answer was fetched, as an epoch in milliseconds. */
6
+ readonly storedAt: number;
7
+ }
8
+ export interface CacheStore {
9
+ readonly get: (key: string) => Promise<CacheEntry | undefined>;
10
+ readonly set: (key: string, entry: CacheEntry, ttlMs: number) => Promise<void>;
11
+ readonly delete: (key: string) => Promise<void>;
12
+ }
13
+ export interface CacheOptions {
14
+ /** How long an answer may be reused, in seconds. */
15
+ readonly ttl: number;
16
+ readonly store?: CacheStore | undefined;
17
+ /** Which operations to cache. Defaults to all of them. */
18
+ readonly only?: readonly Operation["kind"][] | undefined;
19
+ /** The clock, for tests. */
20
+ readonly now?: (() => number) | undefined;
21
+ }
22
+ /** An in-memory store that drops its oldest entry once it is full. */
23
+ export declare const memoryCacheStore: (maxEntries?: number) => CacheStore;
24
+ export interface CacheScope {
25
+ readonly provider: string;
26
+ readonly workspaceId: string;
27
+ }
28
+ /** The store key for one operation on one credential. */
29
+ export declare const cacheKey: (scope: CacheScope, operation: Operation) => string;
30
+ /** Serves repeat reads from a store. */
31
+ export declare const cache: (options: CacheOptions) => OutboundPlugin;
@@ -0,0 +1,11 @@
1
+ import {
2
+ cache,
3
+ cacheKey,
4
+ memoryCacheStore
5
+ } from "../chunks/chunk-IVH3NMQZ.js";
6
+ import "../chunks/chunk-FHKSLCVW.js";
7
+ export {
8
+ cache,
9
+ cacheKey,
10
+ memoryCacheStore
11
+ };