@apifuse/provider-sdk 2.2.0-beta.4 → 2.2.0-beta.40

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 (303) hide show
  1. package/AUTHORING.md +501 -13
  2. package/CHANGELOG.md +165 -1
  3. package/README.md +72 -14
  4. package/SUBMISSION.md +1 -1
  5. package/bin/apifuse-check.ts +88 -4
  6. package/bin/apifuse-dev.ts +38 -5
  7. package/bin/apifuse-pack-check.ts +22 -2
  8. package/bin/apifuse-pack-smoke.ts +57 -2
  9. package/bin/apifuse-pack-types.ts +356 -38
  10. package/bin/apifuse-perf.ts +14 -13
  11. package/bin/apifuse-record.ts +691 -68
  12. package/bin/apifuse-submit-check.ts +518 -37
  13. package/bin/apifuse-sync-assets.ts +117 -0
  14. package/bin/submit-check-delimited-text.ts +50 -0
  15. package/dist/auth-turn/index.d.ts +3 -3
  16. package/dist/auth-turn/index.js +1 -1
  17. package/dist/auth.d.ts +14 -0
  18. package/dist/auth.js +67 -0
  19. package/dist/ceremonies/index.d.ts +16 -0
  20. package/dist/ceremonies/index.js +141 -36
  21. package/dist/cli/commands.d.ts +1 -1
  22. package/dist/cli/commands.js +8 -0
  23. package/dist/cli/create.d.ts +3 -0
  24. package/dist/cli/create.js +34 -35
  25. package/dist/cli/prompt-assets.d.ts +80 -0
  26. package/dist/cli/prompt-assets.js +743 -0
  27. package/dist/cli/templates/provider/AGENTS.md.tpl +17 -8
  28. package/dist/cli/templates/provider/Dockerfile.tpl +1 -1
  29. package/dist/cli/templates/provider/README.md.tpl +4 -4
  30. package/dist/cli/templates/provider/index.ts.tpl +6 -3
  31. package/dist/cli/templates/provider/operations/ping.ts.tpl +2 -1
  32. package/dist/config/loader.d.ts +177 -16
  33. package/dist/config/loader.js +424 -127
  34. package/dist/contract-serialization.js +4 -8
  35. package/dist/contract-types.d.ts +1 -0
  36. package/dist/contract.js +2 -0
  37. package/dist/declaration-validation.d.ts +32 -0
  38. package/dist/declaration-validation.js +207 -0
  39. package/dist/define.d.ts +51 -25
  40. package/dist/define.js +752 -38
  41. package/dist/error-resolution.d.ts +4 -0
  42. package/dist/error-resolution.js +122 -0
  43. package/dist/errors.d.ts +18 -0
  44. package/dist/errors.js +40 -0
  45. package/dist/fixture-sanitization.d.ts +28 -0
  46. package/dist/fixture-sanitization.js +217 -0
  47. package/dist/health-scenario.d.ts +1842 -0
  48. package/dist/health-scenario.js +624 -0
  49. package/dist/index.d.ts +19 -9
  50. package/dist/index.js +10 -6
  51. package/dist/lint.d.ts +6 -1
  52. package/dist/lint.js +362 -3
  53. package/dist/native-address.d.ts +43 -0
  54. package/dist/native-address.js +281 -0
  55. package/dist/native-egress-policy.d.ts +31 -0
  56. package/dist/native-egress-policy.js +288 -0
  57. package/dist/observability.d.ts +5 -2
  58. package/dist/observability.js +48 -1
  59. package/dist/provider.d.ts +8 -2
  60. package/dist/provider.js +3 -1
  61. package/dist/runtime/auth-flow.d.ts +5 -1
  62. package/dist/runtime/auth-flow.js +6 -0
  63. package/dist/runtime/browser.d.ts +1 -0
  64. package/dist/runtime/browser.js +492 -49
  65. package/dist/runtime/cache.d.ts +1 -0
  66. package/dist/runtime/cache.js +169 -15
  67. package/dist/runtime/choice-wordlist.d.ts +9 -0
  68. package/dist/runtime/choice-wordlist.js +138 -0
  69. package/dist/runtime/choice.d.ts +13 -1
  70. package/dist/runtime/choice.js +490 -102
  71. package/dist/runtime/executor.d.ts +2 -2
  72. package/dist/runtime/executor.js +26 -2
  73. package/dist/runtime/http.d.ts +1 -0
  74. package/dist/runtime/http.js +515 -53
  75. package/dist/runtime/instrumentation.d.ts +2 -2
  76. package/dist/runtime/instrumentation.js +366 -8
  77. package/dist/runtime/native-network-errors.d.ts +33 -0
  78. package/dist/runtime/native-network-errors.js +69 -0
  79. package/dist/runtime/native-network.d.ts +96 -0
  80. package/dist/runtime/native-network.js +1232 -0
  81. package/dist/runtime/ocr.d.ts +29 -0
  82. package/dist/runtime/ocr.js +440 -0
  83. package/dist/runtime/proxy-errors.js +6 -2
  84. package/dist/runtime/proxy-nodemaven.d.ts +56 -0
  85. package/dist/runtime/proxy-nodemaven.js +146 -0
  86. package/dist/runtime/proxy-telemetry.d.ts +80 -1
  87. package/dist/runtime/proxy-telemetry.js +154 -47
  88. package/dist/runtime/redirects.d.ts +29 -0
  89. package/dist/runtime/redirects.js +36 -0
  90. package/dist/runtime/redis.d.ts +1 -1
  91. package/dist/runtime/redis.js +4 -2
  92. package/dist/runtime/request-options.d.ts +68 -1
  93. package/dist/runtime/request-options.js +548 -0
  94. package/dist/runtime/resolver-config.d.ts +6 -0
  95. package/dist/runtime/resolver-config.js +6 -0
  96. package/dist/runtime/resolver-public.d.ts +1 -0
  97. package/dist/runtime/resolver-public.js +1 -0
  98. package/dist/runtime/resolver-shared.d.ts +3 -0
  99. package/dist/runtime/resolver-shared.js +12 -0
  100. package/dist/runtime/resolver-vendors/bindings.d.ts +48 -0
  101. package/dist/runtime/resolver-vendors/bindings.js +40 -0
  102. package/dist/runtime/resolver-vendors/browser.d.ts +22 -0
  103. package/dist/runtime/resolver-vendors/browser.js +377 -0
  104. package/dist/runtime/resolver-vendors/capsolver.d.ts +22 -0
  105. package/dist/runtime/resolver-vendors/capsolver.js +526 -0
  106. package/dist/runtime/resolver-vendors/hosts.d.ts +2 -0
  107. package/dist/runtime/resolver-vendors/hosts.js +33 -0
  108. package/dist/runtime/resolver-vendors/twocaptcha.d.ts +24 -0
  109. package/dist/runtime/resolver-vendors/twocaptcha.js +407 -0
  110. package/dist/runtime/resolver-vendors/types.d.ts +94 -0
  111. package/dist/runtime/resolver-vendors/types.js +96 -0
  112. package/dist/runtime/resolver.d.ts +60 -0
  113. package/dist/runtime/resolver.js +737 -0
  114. package/dist/runtime/secrets.d.ts +27 -0
  115. package/dist/runtime/secrets.js +51 -0
  116. package/dist/runtime/state.d.ts +3 -0
  117. package/dist/runtime/state.js +277 -71
  118. package/dist/runtime/stealth-cookies.d.ts +20 -0
  119. package/dist/runtime/stealth-cookies.js +111 -0
  120. package/dist/runtime/stealth.d.ts +28 -3
  121. package/dist/runtime/stealth.js +519 -255
  122. package/dist/runtime/stt.js +1 -12
  123. package/dist/runtime/timeout.d.ts +5 -0
  124. package/dist/runtime/timeout.js +12 -0
  125. package/dist/runtime/trace-config.d.ts +12 -0
  126. package/dist/runtime/trace-config.js +61 -0
  127. package/dist/serve.d.ts +1 -1
  128. package/dist/serve.js +1 -1
  129. package/dist/server/index.d.ts +5 -3
  130. package/dist/server/index.js +3 -3
  131. package/dist/server/self-test-input-tokens.d.ts +2 -1
  132. package/dist/server/self-test-input-tokens.js +18 -14
  133. package/dist/server/self-test.d.ts +114 -0
  134. package/dist/server/self-test.js +784 -148
  135. package/dist/server/serve-implementation.d.ts +213 -0
  136. package/dist/server/serve-implementation.js +2173 -0
  137. package/dist/server/serve.d.ts +1 -70
  138. package/dist/server/serve.js +1 -1130
  139. package/dist/server/trace-output.d.ts +4 -0
  140. package/dist/server/trace-output.js +20 -0
  141. package/dist/server/types.d.ts +30 -5
  142. package/dist/server/types.js +13 -1
  143. package/dist/stateful/errors.d.ts +19 -0
  144. package/dist/stateful/errors.js +24 -0
  145. package/dist/stateful/http-provider-event-emitter.d.ts +40 -0
  146. package/dist/stateful/http-provider-event-emitter.js +237 -0
  147. package/dist/stateful/http-session-owner-registry.d.ts +44 -0
  148. package/dist/stateful/http-session-owner-registry.js +210 -0
  149. package/dist/stateful/index.d.ts +18 -0
  150. package/dist/stateful/index.js +18 -0
  151. package/dist/stateful/provider-event-delivery-failures.d.ts +32 -0
  152. package/dist/stateful/provider-event-delivery-failures.js +43 -0
  153. package/dist/stateful/provider-event-pipeline-metrics.d.ts +46 -0
  154. package/dist/stateful/provider-event-pipeline-metrics.js +48 -0
  155. package/dist/stateful/provider-event-pipeline.d.ts +50 -0
  156. package/dist/stateful/provider-event-pipeline.js +1 -0
  157. package/dist/stateful/provider-events.d.ts +101 -0
  158. package/dist/stateful/provider-events.js +289 -0
  159. package/dist/stateful/session-key.d.ts +15 -0
  160. package/dist/stateful/session-key.js +86 -0
  161. package/dist/stateful/stateful-provider-adapter-context.d.ts +5 -0
  162. package/dist/stateful/stateful-provider-adapter-context.js +42 -0
  163. package/dist/stateful/stateful-provider-adapter-metrics.d.ts +15 -0
  164. package/dist/stateful/stateful-provider-adapter-metrics.js +21 -0
  165. package/dist/stateful/stateful-provider-adapter.d.ts +98 -0
  166. package/dist/stateful/stateful-provider-adapter.js +287 -0
  167. package/dist/stateful/stateful-provider-observability.d.ts +62 -0
  168. package/dist/stateful/stateful-provider-observability.js +161 -0
  169. package/dist/stateful/stateful-provider-owner-forwarder.d.ts +41 -0
  170. package/dist/stateful/stateful-provider-owner-forwarder.js +215 -0
  171. package/dist/stateful/stateful-provider-runtime-context.d.ts +32 -0
  172. package/dist/stateful/stateful-provider-runtime-context.js +60 -0
  173. package/dist/stateful/stateful-provider-runtime-executor.d.ts +34 -0
  174. package/dist/stateful/stateful-provider-runtime-executor.js +52 -0
  175. package/dist/stateful/stateful-provider-session-routing.d.ts +67 -0
  176. package/dist/stateful/stateful-provider-session-routing.js +345 -0
  177. package/dist/stateful/stateful-provider-session-runtime.d.ts +98 -0
  178. package/dist/stateful/stateful-provider-session-runtime.js +245 -0
  179. package/dist/stateful-signing.d.ts +18 -0
  180. package/dist/stateful-signing.js +27 -0
  181. package/dist/stealth/profiles.js +16 -7
  182. package/dist/stream-evidence.d.ts +74 -0
  183. package/dist/stream-evidence.js +785 -0
  184. package/dist/stream.js +7 -1
  185. package/dist/testing/index.d.ts +2 -1
  186. package/dist/testing/index.js +2 -1
  187. package/dist/testing/run.d.ts +32 -2
  188. package/dist/testing/run.js +489 -21
  189. package/dist/trace-sanitization.d.ts +5 -0
  190. package/dist/trace-sanitization.js +45 -0
  191. package/dist/types.d.ts +545 -23
  192. package/dist/types.js +1 -0
  193. package/package.json +44 -5
  194. package/src/auth-turn/index.ts +1 -1
  195. package/src/auth.ts +118 -0
  196. package/src/ceremonies/index.ts +189 -46
  197. package/src/cli/commands.ts +10 -0
  198. package/src/cli/create.ts +42 -35
  199. package/src/cli/prompt-assets.ts +865 -0
  200. package/src/cli/templates/provider/AGENTS.md.tpl +17 -8
  201. package/src/cli/templates/provider/Dockerfile.tpl +1 -1
  202. package/src/cli/templates/provider/README.md.tpl +4 -4
  203. package/src/cli/templates/provider/index.ts.tpl +6 -3
  204. package/src/cli/templates/provider/operations/ping.ts.tpl +2 -1
  205. package/src/config/loader.ts +665 -163
  206. package/src/contract-serialization.ts +5 -7
  207. package/src/contract-types.ts +1 -0
  208. package/src/contract.ts +2 -0
  209. package/src/declaration-validation.ts +266 -0
  210. package/src/define.ts +970 -87
  211. package/src/error-resolution.ts +127 -0
  212. package/src/errors.ts +52 -0
  213. package/src/fixture-sanitization.ts +248 -0
  214. package/src/health-scenario.ts +875 -0
  215. package/src/index.ts +204 -8
  216. package/src/lint.ts +408 -4
  217. package/src/native-address.ts +340 -0
  218. package/src/native-egress-policy.ts +358 -0
  219. package/src/observability.ts +51 -1
  220. package/src/provider.ts +133 -0
  221. package/src/runtime/auth-flow.ts +12 -0
  222. package/src/runtime/browser.ts +661 -63
  223. package/src/runtime/cache.ts +189 -14
  224. package/src/runtime/choice-wordlist.ts +145 -0
  225. package/src/runtime/choice.ts +631 -120
  226. package/src/runtime/executor.ts +40 -7
  227. package/src/runtime/http.ts +641 -61
  228. package/src/runtime/instrumentation.ts +520 -15
  229. package/src/runtime/native-network-errors.ts +99 -0
  230. package/src/runtime/native-network.ts +1605 -0
  231. package/src/runtime/ocr.ts +523 -0
  232. package/src/runtime/proxy-errors.ts +12 -4
  233. package/src/runtime/proxy-nodemaven.ts +221 -0
  234. package/src/runtime/proxy-telemetry.ts +244 -75
  235. package/src/runtime/redirects.ts +66 -0
  236. package/src/runtime/redis.ts +7 -2
  237. package/src/runtime/request-options.ts +680 -1
  238. package/src/runtime/resolver-config.ts +6 -0
  239. package/src/runtime/resolver-public.ts +20 -0
  240. package/src/runtime/resolver-shared.ts +17 -0
  241. package/src/runtime/resolver-vendors/bindings.ts +56 -0
  242. package/src/runtime/resolver-vendors/browser.ts +533 -0
  243. package/src/runtime/resolver-vendors/capsolver.ts +700 -0
  244. package/src/runtime/resolver-vendors/hosts.ts +38 -0
  245. package/src/runtime/resolver-vendors/twocaptcha.ts +539 -0
  246. package/src/runtime/resolver-vendors/types.ts +212 -0
  247. package/src/runtime/resolver.ts +1103 -0
  248. package/src/runtime/secrets.ts +64 -0
  249. package/src/runtime/state.ts +394 -77
  250. package/src/runtime/stealth-cookies.ts +132 -0
  251. package/src/runtime/stealth.ts +675 -289
  252. package/src/runtime/stt.ts +1 -19
  253. package/src/runtime/timeout.ts +18 -0
  254. package/src/runtime/trace-config.ts +77 -0
  255. package/src/serve.ts +6 -1
  256. package/src/server/index.ts +37 -2
  257. package/src/server/self-test-input-tokens.ts +29 -14
  258. package/src/server/self-test.ts +1025 -175
  259. package/src/server/serve-implementation.ts +3250 -0
  260. package/src/server/serve.ts +1 -1626
  261. package/src/server/trace-output.ts +32 -0
  262. package/src/server/types.ts +13 -1
  263. package/src/stateful/README.md +146 -0
  264. package/src/stateful/errors.ts +35 -0
  265. package/src/stateful/http-provider-event-emitter.ts +314 -0
  266. package/src/stateful/http-session-owner-registry.ts +306 -0
  267. package/src/stateful/index.ts +18 -0
  268. package/src/stateful/provider-event-delivery-failures.ts +80 -0
  269. package/src/stateful/provider-event-pipeline-metrics.ts +95 -0
  270. package/src/stateful/provider-event-pipeline.ts +61 -0
  271. package/src/stateful/provider-events.ts +462 -0
  272. package/src/stateful/session-key.ts +111 -0
  273. package/src/stateful/stateful-provider-adapter-context.ts +59 -0
  274. package/src/stateful/stateful-provider-adapter-metrics.ts +48 -0
  275. package/src/stateful/stateful-provider-adapter.ts +562 -0
  276. package/src/stateful/stateful-provider-observability.ts +261 -0
  277. package/src/stateful/stateful-provider-owner-forwarder.ts +287 -0
  278. package/src/stateful/stateful-provider-runtime-context.ts +92 -0
  279. package/src/stateful/stateful-provider-runtime-executor.ts +96 -0
  280. package/src/stateful/stateful-provider-session-routing.ts +546 -0
  281. package/src/stateful/stateful-provider-session-runtime.ts +403 -0
  282. package/src/stateful-signing.ts +46 -0
  283. package/src/stealth/profiles.ts +17 -7
  284. package/src/stream-evidence.ts +988 -0
  285. package/src/stream.ts +8 -1
  286. package/src/testing/index.ts +10 -1
  287. package/src/testing/run.ts +658 -15
  288. package/src/trace-sanitization.ts +63 -0
  289. package/src/types.ts +660 -38
  290. package/dist/cli/templates/provider/CLAUDE.md.tpl +0 -1
  291. package/src/cli/templates/provider/CLAUDE.md.tpl +0 -1
  292. /package/dist/cli/templates/provider/{skills → .agents/skills}/fixtures-and-recording/SKILL.md.tpl +0 -0
  293. /package/dist/cli/templates/provider/{skills → .agents/skills}/health-checks-and-fail-closed/SKILL.md.tpl +0 -0
  294. /package/dist/cli/templates/provider/{skills → .agents/skills}/normalization-standards/SKILL.md.tpl +0 -0
  295. /package/dist/cli/templates/provider/{skills → .agents/skills}/pagination-and-counts/SKILL.md.tpl +0 -0
  296. /package/dist/cli/templates/provider/{skills → .agents/skills}/upstream-contract-verification/SKILL.md.tpl +0 -0
  297. /package/dist/cli/templates/provider/{skills → .agents/skills}/upstream-notes/README.md.tpl +0 -0
  298. /package/src/cli/templates/provider/{skills → .agents/skills}/fixtures-and-recording/SKILL.md.tpl +0 -0
  299. /package/src/cli/templates/provider/{skills → .agents/skills}/health-checks-and-fail-closed/SKILL.md.tpl +0 -0
  300. /package/src/cli/templates/provider/{skills → .agents/skills}/normalization-standards/SKILL.md.tpl +0 -0
  301. /package/src/cli/templates/provider/{skills → .agents/skills}/pagination-and-counts/SKILL.md.tpl +0 -0
  302. /package/src/cli/templates/provider/{skills → .agents/skills}/upstream-contract-verification/SKILL.md.tpl +0 -0
  303. /package/src/cli/templates/provider/{skills → .agents/skills}/upstream-notes/README.md.tpl +0 -0
@@ -18,7 +18,7 @@
18
18
  // 3. A Node (not bun) ESM runtime import — node does not tolerate
19
19
  // extensionless relative specifiers, bun does.
20
20
  //
21
- // A deliberate negative control proves the fixture compiler actually fails on
21
+ // Deliberate negative controls prove the fixture compiler actually fails on
22
22
  // type errors, so this check cannot rot into a false-positive green.
23
23
 
24
24
  import { execFileSync, spawnSync } from "node:child_process";
@@ -36,6 +36,263 @@ const PACK_RESULT_SCHEMA = z.array(
36
36
  const KEEP_TEMP = process.env.APIFUSE__PACK_TYPES__KEEP_TEMP === "1";
37
37
  const sdkRoot = process.cwd();
38
38
 
39
+ const NEGATIVE_CONTROLS = [
40
+ {
41
+ filename: "negative-control-provider-error-name.ts",
42
+ expectedCode: "TS2322",
43
+ description: "ProviderError.name remains a string",
44
+ source: [
45
+ 'import { ProviderError } from "@apifuse/provider-sdk";',
46
+ "",
47
+ "// Intentionally wrong: name is a string. If this file compiles, the",
48
+ "// fixture consumer is not actually type-checking and the guard is void.",
49
+ 'export const mustNotCompile: number = new ProviderError("boom").name;',
50
+ "",
51
+ ].join("\n"),
52
+ },
53
+ {
54
+ filename: "negative-control-unknown-resolver-vendor.ts",
55
+ expectedCode: "TS2322",
56
+ description: "ProviderResolverConfig rejects an unknown vendor",
57
+ source: [
58
+ 'import type { ProviderResolverConfig } from "@apifuse/provider-sdk";',
59
+ "",
60
+ "export const mustNotCompile: ProviderResolverConfig = {",
61
+ '\tvendors: ["unknown-vendor"],',
62
+ '\tkinds: ["turnstile"],',
63
+ "};",
64
+ "",
65
+ ].join("\n"),
66
+ },
67
+ {
68
+ filename: "negative-control-define-provider-resolver-vendor.ts",
69
+ expectedCode: "TS2322",
70
+ description: "defineProvider rejects an unknown resolver vendor",
71
+ source: [
72
+ 'import { defineProvider, z } from "@apifuse/provider-sdk";',
73
+ "",
74
+ "export const mustNotCompile = defineProvider({",
75
+ '\tid: "invalid-resolver-vendor",',
76
+ '\tversion: "1.0.0",',
77
+ '\truntime: "standard",',
78
+ '\tresolver: { vendors: ["unknown-vendor"], kinds: ["turnstile"] },',
79
+ '\tmeta: { displayName: "Invalid Resolver Vendor", descriptionKey: "meta.description", category: "test" },',
80
+ "})({",
81
+ "\toperations: {",
82
+ "\t\tprobe: {",
83
+ "\t\t\tinput: z.object({}),",
84
+ "\t\t\toutput: z.object({ ok: z.boolean() }),",
85
+ "\t\t\thandler: async () => ({ ok: true }),",
86
+ '\t\t\thealthCheckUnsupported: { reason: "type fixture" },',
87
+ "\t\t},",
88
+ "\t},",
89
+ "});",
90
+ "",
91
+ ].join("\n"),
92
+ },
93
+ {
94
+ filename: "negative-control-unknown-challenge-kind.ts",
95
+ expectedCode: "TS2820",
96
+ description: "ProviderChallenge rejects an unknown challenge kind",
97
+ source: [
98
+ 'import type { ProviderChallenge } from "@apifuse/provider-sdk";',
99
+ "",
100
+ "export const mustNotCompile: ProviderChallenge = {",
101
+ '\tkind: "funcaptcha",',
102
+ '\tsiteKey: "key",',
103
+ '\tpageUrl: "https://example.com",',
104
+ "};",
105
+ "",
106
+ ].join("\n"),
107
+ },
108
+ {
109
+ filename: "negative-control-provider-challenge-kind.ts",
110
+ expectedCode: "TS2820",
111
+ description: "ProviderChallengeKind rejects an unknown challenge kind",
112
+ source: [
113
+ 'import type { ProviderChallengeKind } from "@apifuse/provider-sdk";',
114
+ "",
115
+ 'export const mustNotCompile: ProviderChallengeKind = "funcaptcha";',
116
+ "",
117
+ ].join("\n"),
118
+ },
119
+ {
120
+ filename: "negative-control-cookie-solution-token-read.ts",
121
+ expectedCode: "TS2339",
122
+ description: "ChallengeSolution requires narrowing before reading token",
123
+ source: [
124
+ 'import type { ChallengeSolution } from "@apifuse/provider-sdk";',
125
+ "",
126
+ "export function mustNotCompile(solution: ChallengeSolution): string {",
127
+ "\treturn solution.token;",
128
+ "}",
129
+ "",
130
+ ].join("\n"),
131
+ },
132
+ {
133
+ filename: "negative-control-cookie-challenge-site-key.ts",
134
+ expectedCode: "TS2353",
135
+ description: "cookie-family challenges reject token-family fields",
136
+ source: [
137
+ 'import type { ProviderChallenge } from "@apifuse/provider-sdk";',
138
+ "",
139
+ "export const mustNotCompile: ProviderChallenge = {",
140
+ '\tkind: "cloudflare_interstitial",',
141
+ '\tpageUrl: "https://example.com",',
142
+ '\tsiteKey: "not-allowed",',
143
+ "};",
144
+ "",
145
+ ].join("\n"),
146
+ },
147
+ {
148
+ filename: "negative-control-aws-waf-site-key-type.ts",
149
+ expectedCode: "TS2322",
150
+ description: "aws_waf siteKey must be a string",
151
+ source: [
152
+ 'import type { ProviderChallenge } from "@apifuse/provider-sdk";',
153
+ "",
154
+ "export const mustNotCompile: ProviderChallenge = {",
155
+ '\tkind: "aws_waf",',
156
+ '\tpageUrl: "https://example.com",',
157
+ "\tsiteKey: 123,",
158
+ "};",
159
+ "",
160
+ ].join("\n"),
161
+ },
162
+ {
163
+ filename: "negative-control-aws-waf-context-type.ts",
164
+ expectedCode: "TS2322",
165
+ description: "aws_waf context must be a string",
166
+ source: [
167
+ 'import type { ProviderChallenge } from "@apifuse/provider-sdk";',
168
+ "",
169
+ "export const mustNotCompile: ProviderChallenge = {",
170
+ '\tkind: "aws_waf",',
171
+ '\tpageUrl: "https://example.com",',
172
+ "\tcontext: 123,",
173
+ "};",
174
+ "",
175
+ ].join("\n"),
176
+ },
177
+ {
178
+ filename: "negative-control-aws-waf-unknown-field.ts",
179
+ expectedCode: "TS2353",
180
+ description: "aws_waf rejects fields it does not declare",
181
+ source: [
182
+ 'import type { ProviderChallenge } from "@apifuse/provider-sdk";',
183
+ "",
184
+ "export const mustNotCompile: ProviderChallenge = {",
185
+ '\tkind: "aws_waf",',
186
+ '\tpageUrl: "https://example.com",',
187
+ "\tunknownField: 1,",
188
+ "};",
189
+ "",
190
+ ].join("\n"),
191
+ },
192
+ {
193
+ filename: "negative-control-recaptcha-v3-action.ts",
194
+ expectedCode: "TS2322",
195
+ description: "recaptcha_v3 challenges require action",
196
+ source: [
197
+ 'import type { ProviderChallenge } from "@apifuse/provider-sdk";',
198
+ "",
199
+ "export const mustNotCompile: ProviderChallenge = {",
200
+ '\tkind: "recaptcha_v3",',
201
+ '\tsiteKey: "key",',
202
+ '\tpageUrl: "https://example.com",',
203
+ "};",
204
+ "",
205
+ ].join("\n"),
206
+ },
207
+ {
208
+ filename: "negative-control-browser-cookie-expires.ts",
209
+ expectedCode: "TS2322",
210
+ description: "BrowserCookie.expires remains optional for session cookies",
211
+ source: [
212
+ 'import type { BrowserCookie } from "@apifuse/provider-sdk";',
213
+ "",
214
+ "export function mustNotCompile(cookie: BrowserCookie): number {",
215
+ "\treturn cookie.expires;",
216
+ "}",
217
+ "",
218
+ ].join("\n"),
219
+ },
220
+ {
221
+ filename: "negative-control-resolver-runtime-identity.ts",
222
+ expectedCode: "TS2353",
223
+ description: "ResolverRuntimeOptions does not accept caller-synthesized identity",
224
+ source: [
225
+ 'import type { ResolverRuntimeOptions } from "@apifuse/provider-sdk";',
226
+ "",
227
+ "export const mustNotCompile: ResolverRuntimeOptions = {",
228
+ '\tidentity: "caller-controlled",',
229
+ "};",
230
+ "",
231
+ ].join("\n"),
232
+ },
233
+ {
234
+ filename: "negative-control-resolver-runtime-adapter-factories.ts",
235
+ expectedCode: "TS2353",
236
+ description: "ResolverRuntimeOptions does not accept caller-supplied adapter factories",
237
+ source: [
238
+ 'import type { ResolverRuntimeOptions } from "@apifuse/provider-sdk";',
239
+ "",
240
+ "export const mustNotCompile: ResolverRuntimeOptions = {",
241
+ "\tadapterFactories: {},",
242
+ "};",
243
+ "",
244
+ ].join("\n"),
245
+ },
246
+ {
247
+ filename: "negative-control-resolver-default-user-agent-test-seam.ts",
248
+ expectedCode: "TS2305",
249
+ description: "the resolver subpath does not expose its default user-agent test seam",
250
+ source: [
251
+ 'import { swapResolverDefaultUserAgentForTests } from "@apifuse/provider-sdk/runtime/resolver";',
252
+ "",
253
+ "export const mustNotCompile = swapResolverDefaultUserAgentForTests;",
254
+ "",
255
+ ].join("\n"),
256
+ },
257
+ {
258
+ filename: "negative-control-cache-reset-test-seam.ts",
259
+ expectedCode: "TS2305",
260
+ description: "the package root does not expose its cache-reset test seam",
261
+ source: [
262
+ 'import { resetProviderCacheForTests } from "@apifuse/provider-sdk";',
263
+ "",
264
+ "export const mustNotCompile = resetProviderCacheForTests;",
265
+ "",
266
+ ].join("\n"),
267
+ },
268
+ {
269
+ filename: "negative-control-resolver-runtime-allowed-hosts.ts",
270
+ expectedCode: "TS2322",
271
+ description: "ResolverRuntimeOptions.allowedHosts accepts only host strings",
272
+ source: [
273
+ 'import type { ResolverRuntimeOptions } from "@apifuse/provider-sdk";',
274
+ "",
275
+ "export const mustNotCompile: ResolverRuntimeOptions = {",
276
+ '\tallowedHosts: ["example.com", 42],',
277
+ "};",
278
+ "",
279
+ ].join("\n"),
280
+ },
281
+ {
282
+ filename: "negative-control-resolver-signal.ts",
283
+ expectedCode: "TS2345",
284
+ description: "ResolverContext.solve accepts only AbortSignal as its optional signal",
285
+ source: [
286
+ 'import type { ProviderChallenge, ResolverContext } from "@apifuse/provider-sdk";',
287
+ "",
288
+ "declare const resolver: ResolverContext;",
289
+ "declare const challenge: ProviderChallenge;",
290
+ "resolver.solve(challenge, { aborted: false });",
291
+ "",
292
+ ].join("\n"),
293
+ },
294
+ ] as const;
295
+
39
296
  const tempRoot = mkdtempSync(join(tmpdir(), "apifuse-provider-sdk-pack-types-"));
40
297
  const packDir = join(tempRoot, "pack");
41
298
  const consumerDir = join(tempRoot, "consumer");
@@ -123,12 +380,16 @@ function setUpFixtureConsumer(consumerDir: string, tarballPath: string): void {
123
380
  writeFileSync(
124
381
  join(consumerDir, "consumer.ts"),
125
382
  [
126
- 'import { ProviderError, SessionExpiredError, z } from "@apifuse/provider-sdk";',
383
+ 'import { defineProvider, ProviderError, resolveProxy, SessionExpiredError, z } from "@apifuse/provider-sdk";',
384
+ 'import { invalidateResolverSolution } from "@apifuse/provider-sdk/runtime/resolver";',
385
+ 'import type { BrowserCookie, ChallengeSolution, NativeContext, NativeNetworkClient, NativeNetworkConnection, NativeProviderConfig, NativeTcpEgressGrant, ProviderChallenge, ProviderContext, ProviderFileRef, ProviderFilesContext, ProviderResolvedFile, ProviderResolverConfig, ResolverContext, ResolverRuntimeOptions } from "@apifuse/provider-sdk";',
386
+ 'import type { ProxyProtocol, ProxyResolutionOptions, ProxyResolutionSource, ProxyVendorName, RequestOptions, ResolvedProxyConfig } from "@apifuse/provider-sdk";',
127
387
  'import { defineCredentialsAuth } from "@apifuse/provider-sdk/provider";',
388
+ 'import type { NativeNetworkClient as ProviderEntryNativeNetworkClient, ProviderFilesContext as ProviderEntryFilesContext } from "@apifuse/provider-sdk/provider";',
128
389
  'import { extractProviderContract } from "@apifuse/provider-sdk/contract";',
129
390
  'import { AUTH_TURN_SCHEMA } from "@apifuse/provider-sdk/auth-turn";',
130
391
  'import { serve } from "@apifuse/provider-sdk/server";',
131
- 'import { runStandardTests } from "@apifuse/provider-sdk/testing";',
392
+ 'import { resetProviderCacheForTests, runStandardTests } from "@apifuse/provider-sdk/testing";',
132
393
  "",
133
394
  "// ProviderError must keep its inherited Error members under nodenext.",
134
395
  "// When dist d.ts imports fail to resolve, the class type degrades and",
@@ -143,6 +404,44 @@ function setUpFixtureConsumer(consumerDir: string, tarballPath: string): void {
143
404
  "// Re-exported zod must keep .refine() callback parameter inference.",
144
405
  "const refined = z.object({ shopId: z.string() }).refine((value) => value.shopId.length > 0);",
145
406
  'const refinedString = z.string().refine((value) => value.startsWith("tabelog:"));',
407
+ 'const proxyOptions: ProxyResolutionOptions = { proxyPolicy: { mode: "disabled" } };',
408
+ 'const proxyProtocol: ProxyProtocol = "http";',
409
+ "const proxyResult: Promise<ResolvedProxyConfig> = resolveProxy(proxyOptions);",
410
+ 'const proxySource: ProxyResolutionSource = "smartproxy-allocator";',
411
+ 'const proxyVendor: ProxyVendorName = "smartproxy";',
412
+ 'const requestFile: ProviderFileRef = { type: "request_file", id: "photo", filename: "photo.jpg", mime_type: "image/jpeg", size: 4 };',
413
+ 'const resolvedFile: ProviderResolvedFile = { type: "request_file", id: requestFile.id, filename: requestFile.filename, size: requestFile.size, sha256: requestFile.sha256, mimeType: requestFile.mime_type, arrayBuffer: async () => new ArrayBuffer(0), bytes: async () => new Uint8Array(), stream: () => new ReadableStream<Uint8Array>() };',
414
+ "const files: ProviderFilesContext = { has: () => true, resolve: async () => resolvedFile };",
415
+ "const providerEntryFiles: ProviderEntryFilesContext = files;",
416
+ "const connection: NativeNetworkConnection = { read: async () => null, write: async () => {}, close: async () => {} };",
417
+ "const network: NativeNetworkClient = { connectTcp: async () => connection, connectTls: async () => connection, grantTcpEgress: () => ({ revoke() {} }) };",
418
+ "const providerEntryNetwork: ProviderEntryNativeNetworkClient = network;",
419
+ "const nativeContext: NativeContext = { network };",
420
+ 'const grant: NativeTcpEgressGrant = network.grantTcpEgress({ sourceHost: "booking-loco.kakao.com", sourcePort: 443, host: "loco.kakao.com", port: 5228, tls: "disabled" });',
421
+ 'const nativeConfig: NativeProviderConfig = { network: { tcp: [{ host: "booking-loco.kakao.com", ports: [443], tls: "required" }] } };',
422
+ "const providerContext = undefined as unknown as ProviderContext;",
423
+ "const optionalFiles: ProviderFilesContext | undefined = providerContext.files;",
424
+ "const native: NativeContext = providerContext.native;",
425
+ "export const providerResolver: ResolverContext = providerContext.resolver;",
426
+ 'export const resolverRuntimeOptions: ResolverRuntimeOptions = { allowedHosts: ["example.com"], cache: providerContext.cache };',
427
+ "",
428
+ 'export const turnstileChallenge: ProviderChallenge = { kind: "turnstile", siteKey: "key", pageUrl: "https://example.com" };',
429
+ "export const abortableResolverSolve = providerResolver.solve(turnstileChallenge, new AbortController().signal);",
430
+ 'export const recaptchaV2Challenge: ProviderChallenge = { kind: "recaptcha_v2", siteKey: "key", pageUrl: "https://example.com" };',
431
+ 'export const recaptchaV3Challenge: ProviderChallenge = { kind: "recaptcha_v3", siteKey: "key", pageUrl: "https://example.com", action: "login" };',
432
+ 'export const hcaptchaChallenge: ProviderChallenge = { kind: "hcaptcha", siteKey: "key", pageUrl: "https://example.com" };',
433
+ 'export const cloudflareInterstitialChallenge: ProviderChallenge = { kind: "cloudflare_interstitial", pageUrl: "https://example.com", blockedHtml: "<html></html>" };',
434
+ 'export const awsWafChallenge: ProviderChallenge = { kind: "aws_waf", pageUrl: "https://example.com", captchaScript: "script" };',
435
+ 'export const tokenSolution: ChallengeSolution = { form: "token", token: "solved-token" };',
436
+ 'export const cookieSolution: ChallengeSolution = { form: "cookies", cookies: { cf_clearance: "clearance" }, userAgent: "fixture-agent" };',
437
+ "export const invalidation = invalidateResolverSolution(providerContext.resolver, awsWafChallenge, cookieSolution);",
438
+ 'export const resolverConfig: ProviderResolverConfig = { vendors: ["browser", "capsolver"], kinds: ["cloudflare_interstitial", "turnstile"] };',
439
+ 'export const resolverProvider = defineProvider({ id: "pack-types-resolver", version: "1.0.0", runtime: "standard", resolver: resolverConfig, meta: { displayName: "Pack Types Resolver", descriptionKey: "meta.description", category: "test" } })({ operations: { probe: { input: z.object({}), output: z.object({ ok: z.boolean() }), handler: async () => ({ ok: true }), healthCheckUnsupported: { reason: "type fixture" } } } });',
440
+ "export const resolverContext: ResolverContext = { solve: async () => tokenSolution };",
441
+ 'export const browserCookie: BrowserCookie = { name: "persistent-id", value: "persistent-token", domain: "example.com", path: "/", expires: 1786698176, httpOnly: true, secure: true };',
442
+ 'const browserPage = undefined as unknown as Awaited<ReturnType<ProviderContext["browser"]["newPage"]>>;',
443
+ "export const browserCookies: Promise<readonly BrowserCookie[]> = browserPage.cookies();",
444
+ 'const queryCredentialOptions: RequestOptions = { sensitiveParams: { serviceKey: "type-test-key" } };',
146
445
  "",
147
446
  "export const witnesses = {",
148
447
  " inheritedName,",
@@ -152,27 +451,39 @@ function setUpFixtureConsumer(consumerDir: string, tarballPath: string): void {
152
451
  " sessionExpired,",
153
452
  " refined,",
154
453
  " refinedString,",
454
+ " proxyResult,",
455
+ " proxyProtocol,",
456
+ " proxySource,",
457
+ " proxyVendor,",
458
+ " requestFile,",
459
+ " resolvedFile,",
460
+ " files,",
461
+ " providerEntryFiles,",
462
+ " connection,",
463
+ " network,",
464
+ " providerEntryNetwork,",
465
+ " nativeContext,",
466
+ " grant,",
467
+ " nativeConfig,",
468
+ " optionalFiles,",
469
+ " native,",
470
+ " browserCookie,",
471
+ " browserCookies,",
472
+ " queryCredentialOptions,",
155
473
  " defineCredentialsAuth,",
156
474
  " extractProviderContract,",
157
475
  " AUTH_TURN_SCHEMA,",
158
476
  " serve,",
477
+ " resetProviderCacheForTests,",
159
478
  " runStandardTests,",
160
479
  "};",
161
480
  "",
162
481
  ].join("\n"),
163
482
  );
164
483
 
165
- writeFileSync(
166
- join(consumerDir, "negative-control.ts"),
167
- [
168
- 'import { ProviderError } from "@apifuse/provider-sdk";',
169
- "",
170
- "// Intentionally wrong: name is a string. If this file compiles, the",
171
- "// fixture consumer is not actually type-checking and the guard is void.",
172
- 'export const mustNotCompile: number = new ProviderError("boom").name;',
173
- "",
174
- ].join("\n"),
175
- );
484
+ for (const negativeControl of NEGATIVE_CONTROLS) {
485
+ writeFileSync(join(consumerDir, negativeControl.filename), negativeControl.source);
486
+ }
176
487
  }
177
488
 
178
489
  function compileFixtureConsumer(consumerDir: string): void {
@@ -184,31 +495,38 @@ function compileFixtureConsumer(consumerDir: string): void {
184
495
  }
185
496
 
186
497
  function assertNegativeControlFails(consumerDir: string): void {
187
- const result = spawnSync(
188
- "bun",
189
- [
190
- join(consumerDir, "node_modules", ".bin", "tsc"),
191
- "--target",
192
- "ES2022",
193
- "--module",
194
- "nodenext",
195
- "--moduleResolution",
196
- "nodenext",
197
- "--strict",
198
- "--noEmit",
199
- "negative-control.ts",
200
- ],
201
- { cwd: consumerDir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] },
202
- );
203
- if (result.status === 0) {
204
- throw new Error(
205
- "Negative control compiled cleanly: the fixture consumer is not detecting type errors, so the nodenext guard proves nothing.",
206
- );
207
- }
208
- if (!`${result.stdout}\n${result.stderr}`.includes("TS2322")) {
209
- throw new Error(
210
- `Negative control failed for an unexpected reason (wanted TS2322):\n${result.stdout}\n${result.stderr}`,
498
+ for (const negativeControl of NEGATIVE_CONTROLS) {
499
+ const result = spawnSync(
500
+ "bun",
501
+ [
502
+ join(consumerDir, "node_modules", ".bin", "tsc"),
503
+ "--target",
504
+ "ES2022",
505
+ "--module",
506
+ "nodenext",
507
+ "--moduleResolution",
508
+ "nodenext",
509
+ "--strict",
510
+ "--noEmit",
511
+ negativeControl.filename,
512
+ ],
513
+ { cwd: consumerDir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] },
211
514
  );
515
+ if (result.status === 0) {
516
+ throw new Error(
517
+ 'Negative control "' +
518
+ negativeControl.description +
519
+ '" (' +
520
+ negativeControl.filename +
521
+ ") compiled cleanly: the fixture consumer is not detecting its error, so the guard proves nothing.",
522
+ );
523
+ }
524
+ const output = `${result.stdout}\n${result.stderr}`;
525
+ if (!output.includes(negativeControl.expectedCode)) {
526
+ throw new Error(
527
+ `Negative control "${negativeControl.description}" (${negativeControl.filename}) failed for an unexpected reason (wanted ${negativeControl.expectedCode}):\n${output}`,
528
+ );
529
+ }
212
530
  }
213
531
  }
214
532
 
@@ -11,7 +11,6 @@ import {
11
11
  createBypassProviderCache,
12
12
  createHttpClient,
13
13
  createProviderChoiceContext,
14
- createStealthClient,
15
14
  createSttClientFromEnv,
16
15
  executeOperation,
17
16
  getProviderBaseUrl,
@@ -20,6 +19,7 @@ import {
20
19
  type ProviderContext,
21
20
  type ProviderDefinition,
22
21
  ProviderError,
22
+ resolveProxy,
23
23
  type Span,
24
24
  type StealthClient,
25
25
  type StealthResponse,
@@ -27,6 +27,7 @@ import {
27
27
  } from "../src/index.js";
28
28
  import { computeStats, groupSpansByName, type PerfStats } from "../src/runtime/perf.js";
29
29
  import { createMemoryProviderRuntimeState } from "../src/runtime/state.js";
30
+ import { createStealthClient } from "../src/runtime/stealth.js";
30
31
  import { createTraceContext, resolveTraceContextOptions } from "../src/runtime/trace.js";
31
32
  import { renderWaterfall } from "../src/runtime/waterfall.js";
32
33
  import type { BrowserClient } from "../src/types.js";
@@ -122,7 +123,7 @@ export async function main() {
122
123
 
123
124
  let proxySuite: ProfileSuite | undefined;
124
125
  if (args.compareProxy) {
125
- assertProxyConfigured(config);
126
+ await assertProxyConfigured(provider);
126
127
  proxySuite = await runProfileSuite({
127
128
  args,
128
129
  config,
@@ -454,14 +455,18 @@ async function loadFixtureReplay(providerDirectory: string): Promise<FixtureRepl
454
455
  };
455
456
  }
456
457
 
457
- function assertProxyConfigured(config: ApiFuseConfig): void {
458
- if (config.proxy?.url || process.env.APIFUSE__PROXY__URL) {
459
- return;
458
+ async function assertProxyConfigured(provider: ProviderDefinition): Promise<void> {
459
+ const policy = provider.proxy;
460
+ if (!policy || typeof policy !== "object" || policy.mode === "disabled") {
461
+ throw new Error("--compare-proxy requires an enabled ProviderProxyPolicy on the provider.");
460
462
  }
461
463
 
462
- throw new Error(
463
- "--compare-proxy requires a proxy URL in apifuse.config.ts or APIFUSE__PROXY__URL.",
464
- );
464
+ const resolved = await resolveProxy({ proxyPolicy: policy });
465
+ if (!resolved.url) {
466
+ throw new Error(
467
+ "--compare-proxy could not resolve the provider proxy policy; configure its allocator credentials (for smartproxy, APIFUSE__PROXY__SMARTPROXY_APP_KEY).",
468
+ );
469
+ }
465
470
  }
466
471
 
467
472
  async function runProfileSuite(options: {
@@ -629,22 +634,18 @@ function createBaseContext(options: {
629
634
  traceContext: ReturnType<typeof createTraceContext>;
630
635
  }): ProviderContext {
631
636
  const upstream = {
632
- ...{ proxy: options.provider.proxy },
633
- proxy: options.proxyEnabled,
637
+ proxy: options.proxyEnabled ? options.provider.proxy : false,
634
638
  };
635
- const apifuseConfig = options.proxyEnabled ? options.config : {};
636
639
  const http =
637
640
  options.forceFixtureReplay && options.fixtureReplay
638
641
  ? createFixtureHttpClient(options.fixtureReplay.raw)
639
642
  : createHttpClient(getProviderBaseUrl(options.provider), {
640
- apifuseConfig,
641
643
  upstream,
642
644
  });
643
645
  const stealth =
644
646
  options.forceFixtureReplay && options.fixtureReplay
645
647
  ? createFixtureStealthClient(options.fixtureReplay.rawText)
646
648
  : createStealthClient(getProviderBaseUrl(options.provider), {
647
- apifuseConfig,
648
649
  upstream,
649
650
  });
650
651