@apifuse/provider-sdk 2.2.0-beta.62 → 2.2.0-beta.63

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 (243) hide show
  1. package/AUTHORING.md +268 -9
  2. package/CHANGELOG.md +4 -0
  3. package/README.md +1 -0
  4. package/bin/apifuse-check.ts +84 -2
  5. package/bin/apifuse-dev.ts +11 -31
  6. package/bin/apifuse-migrate-deployment.ts +200 -0
  7. package/bin/apifuse-pack-check.ts +11 -4
  8. package/bin/apifuse-pack-types.ts +187 -4
  9. package/bin/apifuse-record.ts +44 -32
  10. package/bin/apifuse-test.ts +3 -1
  11. package/dist/cli/commands.d.ts +1 -1
  12. package/dist/cli/commands.js +11 -0
  13. package/dist/cli/deployment-intent.d.ts +178 -0
  14. package/dist/cli/deployment-intent.js +277 -0
  15. package/dist/cli/migrate-deployment-intent.d.ts +132 -0
  16. package/dist/cli/migrate-deployment-intent.js +1552 -0
  17. package/dist/cli/migrate-provider-shape.d.ts +5 -1
  18. package/dist/cli/migrate-provider-shape.js +4 -2
  19. package/dist/cli/resolver-runtime.d.ts +21 -0
  20. package/dist/cli/resolver-runtime.js +31 -0
  21. package/dist/define.d.ts +3 -0
  22. package/dist/define.js +5 -0
  23. package/dist/dev.d.ts +3 -1
  24. package/dist/dev.js +6 -1
  25. package/dist/engine.d.ts +35 -1
  26. package/dist/engine.js +21 -2
  27. package/dist/error-resolution.d.ts +1 -0
  28. package/dist/error-resolution.js +54 -0
  29. package/dist/errors.d.ts +39 -1
  30. package/dist/errors.js +50 -0
  31. package/dist/i18n/error-messages.d.ts +86 -0
  32. package/dist/i18n/error-messages.js +192 -0
  33. package/dist/i18n/index.d.ts +1 -0
  34. package/dist/i18n/index.js +1 -0
  35. package/dist/i18n/keys.d.ts +12 -0
  36. package/dist/i18n/keys.js +76 -5
  37. package/dist/index.d.ts +7 -1
  38. package/dist/index.js +6 -0
  39. package/dist/lint.d.ts +10 -0
  40. package/dist/lint.js +412 -49
  41. package/dist/provider.d.ts +5 -5
  42. package/dist/provider.js +2 -2
  43. package/dist/runtime/browser-telemetry-binding.d.ts +5 -0
  44. package/dist/runtime/browser-telemetry-binding.js +83 -0
  45. package/dist/runtime/browser-telemetry.d.ts +76 -0
  46. package/dist/runtime/browser-telemetry.js +165 -0
  47. package/dist/runtime/browser.d.ts +3 -0
  48. package/dist/runtime/browser.js +208 -47
  49. package/dist/runtime/cache-telemetry.d.ts +71 -0
  50. package/dist/runtime/cache-telemetry.js +177 -0
  51. package/dist/runtime/cache.js +67 -7
  52. package/dist/runtime/capability-response.d.ts +3 -0
  53. package/dist/runtime/capability-response.js +56 -0
  54. package/dist/runtime/capability-telemetry.d.ts +46 -0
  55. package/dist/runtime/capability-telemetry.js +68 -0
  56. package/dist/runtime/diagnostic-env.d.ts +3 -0
  57. package/dist/runtime/diagnostic-env.js +10 -1
  58. package/dist/runtime/engine-mode.d.ts +74 -0
  59. package/dist/runtime/engine-mode.js +152 -0
  60. package/dist/runtime/http-telemetry-guard.d.ts +10 -0
  61. package/dist/runtime/http-telemetry-guard.js +62 -10
  62. package/dist/runtime/http.js +141 -35
  63. package/dist/runtime/instrumentation.js +92 -13
  64. package/dist/runtime/ocr-telemetry.d.ts +82 -0
  65. package/dist/runtime/ocr-telemetry.js +192 -0
  66. package/dist/runtime/ocr.js +30 -8
  67. package/dist/runtime/request-telemetry.d.ts +2 -0
  68. package/dist/runtime/request-telemetry.js +2 -1
  69. package/dist/runtime/resolver-runtime-options.d.ts +14 -0
  70. package/dist/runtime/resolver-runtime-options.js +33 -0
  71. package/dist/runtime/resolver-shared.d.ts +3 -2
  72. package/dist/runtime/resolver-shared.js +4 -4
  73. package/dist/runtime/resolver-telemetry.d.ts +1 -0
  74. package/dist/runtime/resolver-telemetry.js +1 -1
  75. package/dist/runtime/resolver-vendors/browser.d.ts +2 -0
  76. package/dist/runtime/resolver-vendors/browser.js +46 -0
  77. package/dist/runtime/resolver-vendors/hosts.d.ts +21 -0
  78. package/dist/runtime/resolver-vendors/hosts.js +35 -0
  79. package/dist/runtime/resolver-vendors/hypersolutions.js +2 -2
  80. package/dist/runtime/resolver-vendors/types.d.ts +5 -4
  81. package/dist/runtime/resolver.d.ts +4 -1
  82. package/dist/runtime/resolver.js +46 -13
  83. package/dist/runtime/state-telemetry.d.ts +79 -0
  84. package/dist/runtime/state-telemetry.js +194 -0
  85. package/dist/runtime/state.d.ts +3 -0
  86. package/dist/runtime/state.js +26 -7
  87. package/dist/runtime/stealth-cookies.d.ts +5 -1
  88. package/dist/runtime/stealth-cookies.js +21 -1
  89. package/dist/runtime/stealth-owned-headers.d.ts +26 -0
  90. package/dist/runtime/stealth-owned-headers.js +37 -0
  91. package/dist/runtime/stealth-telemetry.d.ts +92 -0
  92. package/dist/runtime/stealth-telemetry.js +179 -0
  93. package/dist/runtime/stealth.d.ts +4 -1
  94. package/dist/runtime/stealth.js +228 -85
  95. package/dist/runtime/stt-telemetry.d.ts +77 -0
  96. package/dist/runtime/stt-telemetry.js +176 -0
  97. package/dist/runtime/stt.js +15 -6
  98. package/dist/server/error-stack-frames.d.ts +35 -0
  99. package/dist/server/error-stack-frames.js +219 -0
  100. package/dist/server/index.d.ts +7 -0
  101. package/dist/server/index.js +4 -0
  102. package/dist/server/sdk-version.d.ts +3 -0
  103. package/dist/server/sdk-version.js +19 -0
  104. package/dist/server/self-test.js +1 -18
  105. package/dist/server/sensitive-values.d.ts +1 -1
  106. package/dist/server/sensitive-values.js +9 -0
  107. package/dist/server/serve-implementation.d.ts +51 -2
  108. package/dist/server/serve-implementation.js +337 -90
  109. package/dist/server/types.d.ts +1 -0
  110. package/dist/server/types.js +7 -0
  111. package/dist/stateful/stateful-provider-owner-forwarder.js +22 -0
  112. package/dist/stateful/stateful-provider-runtime-context.d.ts +3 -0
  113. package/dist/stateful/stateful-provider-runtime-context.js +1 -0
  114. package/dist/types.d.ts +94 -1
  115. package/package.json +6 -1
  116. package/src/cli/commands.ts +14 -0
  117. package/src/cli/deployment-intent.ts +364 -0
  118. package/src/cli/migrate-deployment-intent.ts +1908 -0
  119. package/src/cli/migrate-provider-shape.ts +10 -4
  120. package/src/cli/resolver-runtime.ts +72 -0
  121. package/src/define.ts +13 -0
  122. package/src/dev.ts +9 -2
  123. package/src/engine.ts +38 -2
  124. package/src/error-resolution.ts +58 -0
  125. package/src/errors.ts +77 -1
  126. package/src/i18n/error-messages.ts +255 -0
  127. package/src/i18n/index.ts +1 -0
  128. package/src/i18n/keys.ts +80 -6
  129. package/src/index.ts +72 -0
  130. package/src/lint.ts +522 -50
  131. package/src/provider.ts +10 -0
  132. package/src/runtime/browser-telemetry-binding.ts +92 -0
  133. package/src/runtime/browser-telemetry.ts +289 -0
  134. package/src/runtime/browser.ts +249 -65
  135. package/src/runtime/cache-telemetry.ts +247 -0
  136. package/src/runtime/cache.ts +68 -17
  137. package/src/runtime/capability-response.ts +53 -0
  138. package/src/runtime/capability-telemetry.ts +101 -0
  139. package/src/runtime/diagnostic-env.ts +11 -1
  140. package/src/runtime/engine-mode.ts +233 -0
  141. package/src/runtime/http-telemetry-guard.ts +66 -13
  142. package/src/runtime/http.ts +168 -37
  143. package/src/runtime/instrumentation.ts +105 -16
  144. package/src/runtime/ocr-telemetry.ts +308 -0
  145. package/src/runtime/ocr.ts +109 -74
  146. package/src/runtime/request-telemetry.ts +2 -1
  147. package/src/runtime/resolver-runtime-options.ts +50 -0
  148. package/src/runtime/resolver-shared.ts +9 -4
  149. package/src/runtime/resolver-telemetry.ts +1 -1
  150. package/src/runtime/resolver-vendors/browser.ts +65 -7
  151. package/src/runtime/resolver-vendors/hosts.ts +43 -0
  152. package/src/runtime/resolver-vendors/hypersolutions.ts +2 -2
  153. package/src/runtime/resolver-vendors/types.ts +5 -4
  154. package/src/runtime/resolver.ts +64 -21
  155. package/src/runtime/state-telemetry.ts +298 -0
  156. package/src/runtime/state.ts +46 -45
  157. package/src/runtime/stealth-cookies.ts +24 -1
  158. package/src/runtime/stealth-owned-headers.ts +41 -0
  159. package/src/runtime/stealth-telemetry.ts +304 -0
  160. package/src/runtime/stealth.ts +355 -150
  161. package/src/runtime/stt-telemetry.ts +282 -0
  162. package/src/runtime/stt.ts +93 -71
  163. package/src/server/error-stack-frames.ts +214 -0
  164. package/src/server/index.ts +53 -0
  165. package/src/server/sdk-version.ts +22 -0
  166. package/src/server/self-test.ts +1 -21
  167. package/src/server/sensitive-values.ts +14 -0
  168. package/src/server/serve-implementation.ts +569 -108
  169. package/src/server/types.ts +7 -0
  170. package/src/stateful/stateful-provider-owner-forwarder.ts +23 -0
  171. package/src/stateful/stateful-provider-runtime-context.ts +4 -0
  172. package/src/types.ts +99 -1
  173. package/src/cli/__tests__/fixtures/migrate-operation-declaration/approval-override.ts.txt +0 -6
  174. package/src/cli/__tests__/fixtures/migrate-operation-declaration/codemod-syntax.ts.txt +0 -3
  175. package/src/cli/__tests__/fixtures/migrate-operation-declaration/connection-precedence.ts.txt +0 -10
  176. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-ambiguous-a.ts.txt +0 -3
  177. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-ambiguous-b.ts.txt +0 -3
  178. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-ambiguous-barrel.ts.txt +0 -2
  179. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-ambiguous-index.ts.txt +0 -3
  180. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-computed.ts.txt +0 -6
  181. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-cycle-a.ts.txt +0 -1
  182. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-cycle-b.ts.txt +0 -1
  183. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-cycle-index.ts.txt +0 -3
  184. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-daiso-barrel.ts.txt +0 -7
  185. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-daiso-catalog.ts.txt +0 -19
  186. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-daiso-docs.ts.txt +0 -6
  187. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-daiso-index.ts.txt +0 -3
  188. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-daiso-stores.ts.txt +0 -8
  189. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-indirect-config.ts.txt +0 -5
  190. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-nonstatic.ts.txt +0 -4
  191. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-package-index.ts.txt +0 -3
  192. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-reexport-index.ts.txt +0 -3
  193. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-reexport-leaf.ts.txt +0 -10
  194. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-reexport-one.ts.txt +0 -1
  195. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-reexport-two.ts.txt +0 -1
  196. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-runtime-composed-index.ts.txt +0 -3
  197. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-runtime-composed-one.ts.txt +0 -6
  198. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-runtime-composed-two.ts.txt +0 -6
  199. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-runtime-mixed-index.ts.txt +0 -14
  200. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-runtime-registry.ts.txt +0 -3
  201. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-star-package-barrel.ts.txt +0 -2
  202. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-star-package-index.ts.txt +0 -3
  203. package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-star-package-leaf.ts.txt +0 -3
  204. package/src/cli/__tests__/fixtures/migrate-operation-declaration/docs-conflict.ts.txt +0 -8
  205. package/src/cli/__tests__/fixtures/migrate-operation-declaration/examples-hoisted-array-spread.ts.txt +0 -15
  206. package/src/cli/__tests__/fixtures/migrate-operation-declaration/examples-imported-array-spread.ts.txt +0 -9
  207. package/src/cli/__tests__/fixtures/migrate-operation-declaration/examples-kebab-operation-id.ts.txt +0 -17
  208. package/src/cli/__tests__/fixtures/migrate-operation-declaration/examples-map.ts.txt +0 -5
  209. package/src/cli/__tests__/fixtures/migrate-operation-declaration/examples-mixed-array-spread.ts.txt +0 -24
  210. package/src/cli/__tests__/fixtures/migrate-operation-declaration/examples-operation.ts.txt +0 -16
  211. package/src/cli/__tests__/fixtures/migrate-operation-declaration/examples-snake-operation-id.ts.txt +0 -21
  212. package/src/cli/__tests__/fixtures/migrate-operation-declaration/factory-duplicate-provider.ts.txt +0 -11
  213. package/src/cli/__tests__/fixtures/migrate-operation-declaration/factory-id-unresolved.ts.txt +0 -7
  214. package/src/cli/__tests__/fixtures/migrate-operation-declaration/factory-map.ts.txt +0 -3
  215. package/src/cli/__tests__/fixtures/migrate-operation-declaration/factory-one-to-many.ts.txt +0 -18
  216. package/src/cli/__tests__/fixtures/migrate-operation-declaration/factory-one-to-one.ts.txt +0 -13
  217. package/src/cli/__tests__/fixtures/migrate-operation-declaration/hoist-all.ts.txt +0 -31
  218. package/src/cli/__tests__/fixtures/migrate-operation-declaration/hoisted-const.ts.txt +0 -11
  219. package/src/cli/__tests__/fixtures/migrate-operation-declaration/imported-spread.ts.txt +0 -11
  220. package/src/cli/__tests__/fixtures/migrate-operation-declaration/inline-map.ts.txt +0 -11
  221. package/src/cli/__tests__/fixtures/migrate-operation-declaration/inline-spread-cast-tail.ts.txt +0 -21
  222. package/src/cli/__tests__/fixtures/migrate-operation-declaration/inline-spread-ekitan.ts.txt +0 -11
  223. package/src/cli/__tests__/fixtures/migrate-operation-declaration/inline-spread-override.ts.txt +0 -14
  224. package/src/cli/__tests__/fixtures/migrate-operation-declaration/locale-canonical-en.json +0 -1
  225. package/src/cli/__tests__/fixtures/migrate-operation-declaration/locale-canonical-ja.json +0 -1
  226. package/src/cli/__tests__/fixtures/migrate-operation-declaration/locale-canonical-ko.json +0 -1
  227. package/src/cli/__tests__/fixtures/migrate-operation-declaration/locale-existing-operation-namespace-en.json +0 -8
  228. package/src/cli/__tests__/fixtures/migrate-operation-declaration/missing-english-locale.ts.txt +0 -7
  229. package/src/cli/__tests__/fixtures/migrate-operation-declaration/no-safety.ts.txt +0 -6
  230. package/src/cli/__tests__/fixtures/migrate-operation-declaration/non-literal.ts.txt +0 -7
  231. package/src/cli/__tests__/fixtures/migrate-operation-declaration/redundant-approval.ts.txt +0 -6
  232. package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-binding-ambiguous.ts.txt +0 -12
  233. package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-imported-other.ts.txt +0 -7
  234. package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-imported.ts.txt +0 -5
  235. package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-key-ambiguous.ts.txt +0 -19
  236. package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-shorthand.ts.txt +0 -9
  237. package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-typed.ts.txt +0 -11
  238. package/src/cli/__tests__/fixtures/migrate-operation-declaration/registry-unrelated.ts.txt +0 -13
  239. package/src/cli/__tests__/fixtures/migrate-operation-declaration/safety-conflict.ts.txt +0 -7
  240. package/src/cli/__tests__/fixtures/migrate-operation-declaration/stream.ts.txt +0 -7
  241. package/src/cli/__tests__/fixtures/migrate-operation-declaration/tool-router-spread.ts.txt +0 -15
  242. package/src/cli/__tests__/fixtures/migrate-operation-declaration/unparseable.ts.txt +0 -4
  243. package/src/cli/__tests__/fixtures/migrate-operation-declaration/verbatim-template.ts.txt +0 -12
@@ -25,6 +25,13 @@ export const OperationRequestSchema = z.object({
25
25
  input: z.record(z.string(), z.unknown()),
26
26
  connectionId: z.string().optional(),
27
27
  connection: OperationConnectionSchema.optional(),
28
+ /**
29
+ * Gateway-asserted principal scope: the organization id for customer
30
+ * subjects, the service-account id for platform service accounts. Absent
31
+ * on direct calls and self-test. Trusted exactly like `connectionId`; it is
32
+ * never derived from caller headers or `input`.
33
+ */
34
+ tenantId: z.string().optional(),
28
35
  headers: z.record(z.string(), z.string()).optional(),
29
36
  trace: z.record(z.string(), z.string()).optional(),
30
37
  });
@@ -205,6 +205,7 @@ function buildForwardingEnvelope(input: {
205
205
  requestId: input.request.requestId,
206
206
  input: input.request.input as Record<string, unknown>,
207
207
  connection: metadata.connection,
208
+ ...(metadata.tenantId ? { tenantId: metadata.tenantId } : {}),
208
209
  headers: sanitizeForwardedHeaders(metadata.headers),
209
210
  ...(metadata.trace ? { trace: metadata.trace } : {}),
210
211
  },
@@ -213,6 +214,7 @@ function buildForwardingEnvelope(input: {
213
214
 
214
215
  function forwardedMetadata(request: StatefulOperationRequest): {
215
216
  readonly connection: OperationConnection;
217
+ readonly tenantId?: string;
216
218
  readonly headers?: Record<string, string>;
217
219
  readonly trace?: Record<string, string>;
218
220
  } {
@@ -225,13 +227,34 @@ function forwardedMetadata(request: StatefulOperationRequest): {
225
227
  }
226
228
  const operationRequest = forwardingContext.operationRequest;
227
229
  const connection = OperationConnectionSchema.parse(operationRequest?.connection);
230
+ const tenantId = forwardedTenantId(operationRequest?.tenantId);
228
231
  return {
229
232
  connection,
233
+ ...(tenantId !== undefined ? { tenantId } : {}),
230
234
  ...(operationRequest?.headers ? { headers: operationRequest.headers } : {}),
231
235
  ...(operationRequest?.trace ? { trace: operationRequest.trace } : {}),
232
236
  };
233
237
  }
234
238
 
239
+ /**
240
+ * The runtime context is consumer-supplied and typed `unknown`, and only its
241
+ * `requestId` is guarded on read. A malformed principal scope must fail at the
242
+ * source with a forwarding error — the owner would otherwise reject the whole
243
+ * forwarded operation, and dropping it silently would downgrade a per-principal
244
+ * policy to the shared scope. `""` is not a principal (same rule as ids on the
245
+ * ingress envelope), so it is absent rather than invalid.
246
+ */
247
+ function forwardedTenantId(value: unknown): string | undefined {
248
+ if (value === undefined || value === "") return undefined;
249
+ if (typeof value !== "string") {
250
+ throw new StatefulOwnerForwardingError({
251
+ code: "STATEFUL_FORWARDING_CONTEXT_INVALID",
252
+ message: "Stateful operation forwarding requires a string tenantId when it is present.",
253
+ });
254
+ }
255
+ return value;
256
+ }
257
+
235
258
  function sanitizeForwardedHeaders(
236
259
  headers: Record<string, string> | undefined,
237
260
  ): Record<string, string> {
@@ -6,6 +6,8 @@ export interface StatefulForwardingRuntimeContext {
6
6
  readonly operationRequest?: {
7
7
  readonly requestId: string;
8
8
  readonly connection?: unknown;
9
+ /** Gateway-asserted principal scope; forwarded verbatim to the owner pod. */
10
+ readonly tenantId?: string;
9
11
  readonly headers?: Record<string, string>;
10
12
  readonly trace?: Record<string, string>;
11
13
  };
@@ -36,6 +38,7 @@ export function withStatefulLocalProviderContext(
36
38
  export function statefulForwardingContextFromProviderRequest(request: {
37
39
  readonly requestId: string;
38
40
  readonly connection?: unknown;
41
+ readonly tenantId?: string;
39
42
  readonly headers?: Record<string, string>;
40
43
  readonly trace?: Record<string, string>;
41
44
  }): StatefulForwardingRuntimeContext {
@@ -43,6 +46,7 @@ export function statefulForwardingContextFromProviderRequest(request: {
43
46
  operationRequest: {
44
47
  requestId: request.requestId,
45
48
  ...(request.connection !== undefined ? { connection: request.connection } : {}),
49
+ ...(request.tenantId ? { tenantId: request.tenantId } : {}),
46
50
  ...(request.headers ? { headers: request.headers } : {}),
47
51
  ...(request.trace ? { trace: request.trace } : {}),
48
52
  },
package/src/types.ts CHANGED
@@ -924,8 +924,17 @@ export type ProviderErrorStatus = (typeof VALID_OPERATION_ERROR_STATUSES)[number
924
924
  export interface OperationErrorCode {
925
925
  code: string;
926
926
  status?: ProviderErrorStatus;
927
+ /** Developer-facing English prose for docs and MCP tool text. Never localized. */
927
928
  description: string;
928
929
  retryable?: boolean;
930
+ /**
931
+ * Locale catalog key for the client-facing `message` of every error thrown
932
+ * with this `code`. A throw site's own `messageKey` wins; when neither is
933
+ * present the SDK derives `errors.<code>.message`.
934
+ */
935
+ messageKey?: ProviderLocaleKeyInput;
936
+ /** Locale catalog key for the client-facing `fix`. Derived default: `errors.<code>.fix`. */
937
+ fixKey?: ProviderLocaleKeyInput;
929
938
  }
930
939
 
931
940
  export type StealthPlatform = "macos" | "windows" | "linux" | "android" | "ios";
@@ -1229,8 +1238,48 @@ export interface HttpRetrySummary {
1229
1238
  lastStatus?: number;
1230
1239
  }
1231
1240
 
1241
+ /** Per-attempt input for a `RequestOptions.headers` factory. */
1242
+ export interface HttpAttemptContext {
1243
+ /**
1244
+ * 1-based number of this request build: the first request is `1`, its first
1245
+ * retry `2`. Only attempts that reach header resolution count; a failed
1246
+ * proxy allocation or a skipped duplicate proxy offset builds no request
1247
+ * and is not numbered.
1248
+ */
1249
+ attempt: number;
1250
+ /**
1251
+ * Resolved request URL: `baseUrl` + path + `params` + `sensitiveParams`.
1252
+ * It is the exact URL the attempt is issued against, so bind signature
1253
+ * targets to it rather than to a URL the caller rebuilds. Strip the query
1254
+ * and fragment for fields that are defined without them — RFC 9449 §4.2
1255
+ * requires that of DPoP `htu`. It carries any sensitive query values, so
1256
+ * never log it and never copy it verbatim into a signed field that a
1257
+ * verifier logs.
1258
+ */
1259
+ url: string;
1260
+ /** Normalized upper-case HTTP method of the request. */
1261
+ method: Uppercase<HttpMethod>;
1262
+ }
1263
+
1264
+ /**
1265
+ * Builds the request headers for one issued attempt. Managed retry calls it
1266
+ * again for every retry, so request-bound single-use proofs (DPoP `jti`,
1267
+ * HTTP message signatures, HMAC nonces) can be re-minted instead of replayed.
1268
+ * A throw is raised as a non-retryable `TransportError` with code
1269
+ * `http_header_factory_failed`.
1270
+ */
1271
+ export type HttpHeadersFactory = (
1272
+ attempt: HttpAttemptContext,
1273
+ ) => Record<string, string> | Promise<Record<string, string>>;
1274
+
1232
1275
  export interface RequestOptions {
1233
- headers?: Record<string, string>;
1276
+ /**
1277
+ * Request headers, or a factory resolved once per issued attempt (see
1278
+ * `HttpHeadersFactory`). The factory runs after proxy resolution, before the
1279
+ * first redirect hop of that attempt; redirect hops reuse the attempt's
1280
+ * headers. `ctx.stealth` declares its own header option and is not affected.
1281
+ */
1282
+ headers?: Record<string, string> | HttpHeadersFactory;
1234
1283
  params?: RequestParams;
1235
1284
  /**
1236
1285
  * Query parameters whose values contain credentials or other secret material.
@@ -1238,7 +1287,23 @@ export interface RequestOptions {
1238
1287
  */
1239
1288
  sensitiveParams?: Record<string, string>;
1240
1289
  proxy?: string;
1290
+ /**
1291
+ * Per-attempt timeout for the response-header phase. It is disarmed once a
1292
+ * successful response's headers arrive, so it never bounds consumption of
1293
+ * that body — on the buffered path as well as on streams; use `signal` for
1294
+ * that. A non-2xx body the transport discards on the caller's behalf is
1295
+ * still drained under this deadline, so a wedged error body cannot hang the
1296
+ * attempt.
1297
+ */
1241
1298
  timeout?: number;
1299
+ /**
1300
+ * Cancels this request only — its retries, its backoff sleep and its
1301
+ * response-body consumption — leaving the client's other in-flight requests
1302
+ * untouched. Merged with the client-level `signal`, so a rejection reads as
1303
+ * `transport_cancelled` either way; inspect `signal.reason` to tell a
1304
+ * per-request abort from a fleet-wide one.
1305
+ */
1306
+ signal?: AbortSignal;
1242
1307
  /**
1243
1308
  * Defaults to true. Set to false when callers need to inspect upstream
1244
1309
  * non-2xx bodies themselves instead of converting them to TransportError.
@@ -1290,6 +1355,13 @@ export type HttpMethod =
1290
1355
  | "patch";
1291
1356
 
1292
1357
  export interface StealthFetchOptions extends Omit<RequestOptions, "redirectPolicy" | "headers"> {
1358
+ /**
1359
+ * Not supported by the stealth transport, which observes only the
1360
+ * client-level `signal` passed to `createStealthClient`. Typed as `never` so
1361
+ * a per-request signal fails to compile instead of being silently ignored;
1362
+ * threading one through the stealth session is a separate change.
1363
+ */
1364
+ signal?: never;
1293
1365
  /**
1294
1366
  * Defaults to true. Set to false when callers need to inspect upstream
1295
1367
  * non-2xx bodies themselves instead of converting them to TransportError.
@@ -1995,6 +2067,16 @@ export interface CredentialContext {
1995
2067
 
1996
2068
  export interface ProviderRequestContext {
1997
2069
  connectionId?: string;
2070
+ /**
2071
+ * Gateway-asserted principal scope of the operation request: the
2072
+ * organization id for customer subjects, the service-account id for
2073
+ * platform service accounts. `undefined` on direct calls and self-test
2074
+ * (unlike `FlowContext.tenantId`, which is coerced to `""`); an empty
2075
+ * string on the wire is normalised to `undefined` like `connectionId`.
2076
+ * Key per-principal policy (quota, fairness, correlation) for
2077
+ * connectionless operations on it. It does not scope `ctx.state`.
2078
+ */
2079
+ tenantId?: string;
1998
2080
  headers: Record<string, string>;
1999
2081
  }
2000
2082
 
@@ -2294,10 +2376,18 @@ export interface AuthConfig {
2294
2376
  flow?: AuthFlowDefinition;
2295
2377
  }
2296
2378
 
2379
+ /** Who provisions a declared secret: the platform (`apifuse`) or the provider author (`contributor`). */
2380
+ export type ProviderSecretIssuer = "apifuse" | "contributor";
2381
+
2297
2382
  export interface ProviderSecretDeclaration {
2298
2383
  name: string;
2299
2384
  description?: string;
2300
2385
  required?: boolean;
2386
+ /**
2387
+ * Optional today; ADR-0011 D3 makes it required once every deployed provider
2388
+ * declares it. Metadata only: it does not change which secrets are projected.
2389
+ */
2390
+ issuer?: ProviderSecretIssuer;
2301
2391
  }
2302
2392
 
2303
2393
  export interface CredentialDeclaration {
@@ -2398,6 +2488,14 @@ export interface OperationDefinition<
2398
2488
  * optional. Note that the deployment `runtime` axis
2399
2489
  * (`shared`/`dedicated`/`browser`) is distinct from the provider execution
2400
2490
  * `runtime` (`standard`/`shared`/`browser`).
2491
+ *
2492
+ * This key is the ONLY authored deployment surface. Declare it inside the
2493
+ * `defineProvider({...})` literal, not on a spread default export and not
2494
+ * in a standalone `deploy.ts` (legacy; `apifuse migrate-deployment` hoists
2495
+ * and deletes it). Write only what differs from the runtime profile —
2496
+ * shared `25m/128Mi`, browser `200m/256Mi`, `language: "typescript"`,
2497
+ * `replicas: 1`, HPA enabled 1-1 at 70% CPU — so most providers declare
2498
+ * nothing and `apifuse check` warns on restated defaults.
2401
2499
  */
2402
2500
  export interface ProviderDeploymentOverrides {
2403
2501
  runtime?: "shared" | "dedicated" | "browser";
@@ -1,6 +0,0 @@
1
- const reserveOperation = defineOperation<ProviderContext>()({
2
- toolRouter: { riskClass: "write", approval: "always" },
3
- input: InputSchema,
4
- output: OutputSchema,
5
- handler,
6
- });
@@ -1,3 +0,0 @@
1
- const migrated = {
2
- riskClass: "read",;
3
- };
@@ -1,10 +0,0 @@
1
- const connectOperation = defineOperation<ProviderContext>()({
2
- annotations: { readOnly: true },
3
- toolRouter: {
4
- connectionMode: "optional",
5
- requiresConnection: true,
6
- },
7
- input: InputSchema,
8
- output: OutputSchema,
9
- handler,
10
- });
@@ -1,3 +0,0 @@
1
- export const registry = {
2
- first: { annotations: { readOnly: true }, input: InputSchema, output: OutputSchema, handler },
3
- };
@@ -1,3 +0,0 @@
1
- export const registry = {
2
- second: { annotations: { readOnly: true }, input: InputSchema, output: OutputSchema, handler },
3
- };
@@ -1,2 +0,0 @@
1
- export * from "./ambiguous-a";
2
- export * from "./ambiguous-b";
@@ -1,3 +0,0 @@
1
- import { registry } from "./ambiguous-barrel";
2
-
3
- export default buildProvider({ operations: registry });
@@ -1,6 +0,0 @@
1
- const operationId = "ping";
2
- const registry = {
3
- [operationId]: { annotations: { readOnly: true }, input: InputSchema, output: OutputSchema, handler },
4
- };
5
-
6
- export default buildProvider({ operations: registry });
@@ -1 +0,0 @@
1
- export { registry } from "./cycle-b";
@@ -1 +0,0 @@
1
- export { registry } from "./cycle-a";
@@ -1,3 +0,0 @@
1
- import { registry } from "./cycle-a";
2
-
3
- export default buildProvider({ operations: registry });
@@ -1,7 +0,0 @@
1
- import { catalogOperations } from "./catalog";
2
- import { storeOperations } from "./stores";
3
-
4
- export const daisoOperations = {
5
- ...catalogOperations,
6
- ...storeOperations,
7
- };
@@ -1,19 +0,0 @@
1
- import { OPERATION_DOCS } from "./docs";
2
-
3
- export const catalogOperations = {
4
- "browse-catalog": {
5
- docs: { ...OPERATION_DOCS.catalog },
6
- descriptionKey: "operations.browseCatalog.description",
7
- annotations: { readOnly: true },
8
- inputExamples: [{ scenario: "Browse the catalog", input: {} }],
9
- input: InputSchema,
10
- output: OutputSchema,
11
- handler,
12
- },
13
- "search-products": {
14
- annotations: { readOnly: true },
15
- input: InputSchema,
16
- output: OutputSchema,
17
- handler,
18
- },
19
- };
@@ -1,6 +0,0 @@
1
- export const OPERATION_DOCS = {
2
- catalog: {
3
- titleKey: "operations.groupedRead.title",
4
- descriptionKey: "operations.groupedRead.description",
5
- },
6
- };
@@ -1,3 +0,0 @@
1
- import { daisoOperations } from "./operations";
2
-
3
- export default buildProvider({ operations: daisoOperations });
@@ -1,8 +0,0 @@
1
- export const storeOperations = {
2
- "search-stores": {
3
- annotations: { readOnly: true },
4
- input: InputSchema,
5
- output: OutputSchema,
6
- handler,
7
- },
8
- };
@@ -1,5 +0,0 @@
1
- import { packageRegistry } from "provider-operation-package";
2
-
3
- const config = { operations: packageRegistry };
4
-
5
- export default buildProvider(config);
@@ -1,4 +0,0 @@
1
- const first = { ping: pingOperation };
2
- const second = { pong: pongOperation };
3
-
4
- export default buildProvider({ operations: enabled ? first : second });
@@ -1,3 +0,0 @@
1
- import { packageRegistry } from "provider-operation-package";
2
-
3
- export default buildProvider({ operations: packageRegistry });
@@ -1,3 +0,0 @@
1
- import { registry } from "./barrel-one.js";
2
-
3
- export default buildProvider({ operations: registry });
@@ -1,10 +0,0 @@
1
- const leafRegistry = {
2
- ping: {
3
- annotations: { readOnly: true },
4
- input: InputSchema,
5
- output: OutputSchema,
6
- handler,
7
- },
8
- };
9
-
10
- export const registry = leafRegistry;
@@ -1 +0,0 @@
1
- export { registry } from "./barrel-two.js";
@@ -1 +0,0 @@
1
- export { registry } from "./leaf";
@@ -1,3 +0,0 @@
1
- import { makeRegistry } from "./operations/registry";
2
-
3
- export default buildProvider({ operations: makeRegistry({ publicOnly: true }) });
@@ -1,6 +0,0 @@
1
- export const firstOperation = defineOperation<ProviderContext>()({
2
- annotations: { readOnly: true },
3
- input: FirstInputSchema,
4
- output: FirstOutputSchema,
5
- handler: firstHandler,
6
- });
@@ -1,6 +0,0 @@
1
- export const secondOperation = defineOperation<ProviderContext>()({
2
- annotations: { readOnly: true },
3
- input: SecondInputSchema,
4
- output: SecondOutputSchema,
5
- handler: secondHandler,
6
- });
@@ -1,14 +0,0 @@
1
- import { makeRegistry } from "./operations/registry";
2
-
3
- const literalOperation = defineOperation<ProviderContext>()({
4
- annotations: { readOnly: true },
5
- input: LiteralInputSchema,
6
- output: LiteralOutputSchema,
7
- handler: literalHandler,
8
- });
9
-
10
- export const literalProvider = buildProvider({
11
- operations: { literal: literalOperation },
12
- });
13
-
14
- export default buildProvider({ operations: makeRegistry({ publicOnly: true }) });
@@ -1,3 +0,0 @@
1
- export function makeRegistry(_options: { publicOnly: boolean }) {
2
- return {};
3
- }
@@ -1,2 +0,0 @@
1
- export * from "provider-operation-package";
2
- export * from "./star-leaf";
@@ -1,3 +0,0 @@
1
- import { registry } from "./star-barrel";
2
-
3
- export default buildProvider({ operations: registry });
@@ -1,3 +0,0 @@
1
- export const registry = {
2
- ping: { annotations: { readOnly: true }, input: InputSchema, output: OutputSchema, handler },
3
- };
@@ -1,8 +0,0 @@
1
- const searchOperation = defineOperation<ProviderContext>()({
2
- riskClass: "read",
3
- titleKey: "operations.search.title",
4
- docs: { titleKey: "operations.search.otherTitle" },
5
- input: InputSchema,
6
- output: OutputSchema,
7
- handler,
8
- });
@@ -1,15 +0,0 @@
1
- const LIST_INPUT_EXAMPLES = [
2
- {
3
- scenario: "List a full year",
4
- rationale: "Shows the common calendar query",
5
- input: { year: 2026 },
6
- },
7
- ] as const;
8
-
9
- const listOperation = defineOperation<ProviderContext>()({
10
- annotations: { readOnly: true },
11
- inputExamples: [...LIST_INPUT_EXAMPLES],
12
- input: InputSchema,
13
- output: OutputSchema,
14
- handler,
15
- });
@@ -1,9 +0,0 @@
1
- import { LIST_INPUT_EXAMPLES } from "./shared.js";
2
-
3
- const importedExamplesOperation = defineOperation<ProviderContext>()({
4
- annotations: { readOnly: true },
5
- inputExamples: [...LIST_INPUT_EXAMPLES],
6
- input: InputSchema,
7
- output: OutputSchema,
8
- handler,
9
- });
@@ -1,17 +0,0 @@
1
- const listHospitalsOperation = defineOperation<ProviderContext>()({
2
- annotations: { readOnly: true },
3
- inputExamples: [
4
- {
5
- scenario: "List nearby hospitals",
6
- input: { latitude: 37.5665, longitude: 126.978 },
7
- rationale: "Exercises a kebab-case operation id.",
8
- },
9
- ],
10
- input: InputSchema,
11
- output: OutputSchema,
12
- handler,
13
- });
14
-
15
- export default buildProvider({
16
- operations: { "list-hospitals": listHospitalsOperation },
17
- });
@@ -1,5 +0,0 @@
1
- import { searchOperation } from "./search";
2
-
3
- export const operations = {
4
- search: searchOperation,
5
- };
@@ -1,24 +0,0 @@
1
- const SHARED_INPUT_EXAMPLES = [
2
- {
3
- scenario: "Shared middle example",
4
- input: { page: 2 },
5
- },
6
- ] as const;
7
-
8
- const mixedOperation = defineOperation<ProviderContext>()({
9
- annotations: { readOnly: true },
10
- inputExamples: [
11
- {
12
- scenario: "Literal first example",
13
- input: { page: 1 },
14
- },
15
- ...SHARED_INPUT_EXAMPLES,
16
- {
17
- scenario: "Literal last example",
18
- input: { page: 3 },
19
- },
20
- ],
21
- input: InputSchema,
22
- output: OutputSchema,
23
- handler,
24
- });
@@ -1,16 +0,0 @@
1
- export const searchOperation = defineOperation<ProviderContext>()({
2
- annotations: { readOnly: true },
3
- inputExamples: [
4
- {
5
- scenario: "Search by a precise phrase",
6
- input: {
7
- query: `京都
8
- ホテル`,
9
- },
10
- rationale: "Shows whitespace preservation",
11
- },
12
- ],
13
- input: InputSchema,
14
- output: OutputSchema,
15
- handler,
16
- });
@@ -1,21 +0,0 @@
1
- const listRecentEarthquakesOperation = defineOperation<ProviderContext>()({
2
- annotations: { readOnly: true },
3
- docs: {
4
- titleKey: "operations.listRecentEarthquakes.title",
5
- descriptionKey: "operations.listRecentEarthquakes.description",
6
- },
7
- inputExamples: [
8
- {
9
- scenario: "List recent earthquakes",
10
- input: { limit: 10 },
11
- rationale: "Exercises a snake-case operation id.",
12
- },
13
- ],
14
- input: InputSchema,
15
- output: OutputSchema,
16
- handler,
17
- });
18
-
19
- export default buildProvider({
20
- operations: { list_recent_earthquakes: listRecentEarthquakesOperation },
21
- });
@@ -1,11 +0,0 @@
1
- function makePingOperation() {
2
- return defineOperation<ProviderContext>()({
3
- annotations: { readOnly: true },
4
- input: InputSchema,
5
- output: OutputSchema,
6
- handler,
7
- });
8
- }
9
-
10
- export const first = buildProvider({ operations: { ping: makePingOperation() } });
11
- export default buildProvider({ operations: { ping: makePingOperation() } });
@@ -1,7 +0,0 @@
1
- defineOperation<ProviderContext>()({
2
- annotations: { readOnly: true },
3
- inputExamples: [{ scenario: "Anonymous", input: {} }],
4
- input: InputSchema,
5
- output: OutputSchema,
6
- handler,
7
- });
@@ -1,3 +0,0 @@
1
- export default buildProvider({
2
- operations: createTabelogProvider(client),
3
- });
@@ -1,18 +0,0 @@
1
- function makeSearchOperation(kind: string) {
2
- return defineOperation<ProviderContext>()({
3
- annotations: { readOnly: true },
4
- inputExamples: [{ scenario: "Search items", input: { kind } }],
5
- input: InputSchema,
6
- output: OutputSchema,
7
- handler,
8
- });
9
- }
10
-
11
- export default buildProvider({
12
- operations: {
13
- "used-goods-search": makeSearchOperation("used"),
14
- "realty-search-listings": makeSearchOperation("realty"),
15
- "jobs-search": makeSearchOperation("jobs"),
16
- "cars-search": makeSearchOperation("cars"),
17
- },
18
- });
@@ -1,13 +0,0 @@
1
- function makeSearchOperation(kind: string) {
2
- return defineOperation<ProviderContext>()({
3
- annotations: { readOnly: true },
4
- inputExamples: [{ scenario: "Search items", input: { kind } }],
5
- input: InputSchema,
6
- output: OutputSchema,
7
- handler,
8
- });
9
- }
10
-
11
- export default buildProvider({
12
- operations: { "search-items": makeSearchOperation("items") },
13
- });