primitive-admin 1.2.0-alpha.8 → 1.3.0-alpha.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 (563) hide show
  1. package/README.md +258 -186
  2. package/assets/skill/skills/primitive-platform/SKILL.md +103 -29
  3. package/dist/bin/primitive.js +15 -89
  4. package/dist/bin/primitive.js.map +1 -1
  5. package/dist/src/commands/admins.js +80 -17
  6. package/dist/src/commands/admins.js.map +1 -1
  7. package/dist/src/commands/agent-sessions.d.ts +129 -0
  8. package/dist/src/commands/agent-sessions.js +532 -20
  9. package/dist/src/commands/agent-sessions.js.map +1 -1
  10. package/dist/src/commands/analytics.js +207 -155
  11. package/dist/src/commands/analytics.js.map +1 -1
  12. package/dist/src/commands/apps-children.d.ts +1 -1
  13. package/dist/src/commands/apps-children.js +56 -145
  14. package/dist/src/commands/apps-children.js.map +1 -1
  15. package/dist/src/commands/apps-transitions.d.ts +39 -0
  16. package/dist/src/commands/apps-transitions.js +198 -0
  17. package/dist/src/commands/apps-transitions.js.map +1 -0
  18. package/dist/src/commands/apps.d.ts +17 -0
  19. package/dist/src/commands/apps.js +108 -3
  20. package/dist/src/commands/apps.js.map +1 -1
  21. package/dist/src/commands/auth-sessions.js +2 -0
  22. package/dist/src/commands/auth-sessions.js.map +1 -1
  23. package/dist/src/commands/auth.js +138 -44
  24. package/dist/src/commands/auth.js.map +1 -1
  25. package/dist/src/commands/blob-buckets.js +2 -0
  26. package/dist/src/commands/blob-buckets.js.map +1 -1
  27. package/dist/src/commands/collections.js +318 -256
  28. package/dist/src/commands/collections.js.map +1 -1
  29. package/dist/src/commands/comparisons.js +2 -0
  30. package/dist/src/commands/comparisons.js.map +1 -1
  31. package/dist/src/commands/config.d.ts +2 -2
  32. package/dist/src/commands/config.js +59 -33
  33. package/dist/src/commands/config.js.map +1 -1
  34. package/dist/src/commands/connections.js +2 -0
  35. package/dist/src/commands/connections.js.map +1 -1
  36. package/dist/src/commands/database-type-configs.js +5 -3
  37. package/dist/src/commands/database-type-configs.js.map +1 -1
  38. package/dist/src/commands/database-types.js +13 -313
  39. package/dist/src/commands/database-types.js.map +1 -1
  40. package/dist/src/commands/databases.js +6 -4
  41. package/dist/src/commands/databases.js.map +1 -1
  42. package/dist/src/commands/db3-types.d.ts +15 -0
  43. package/dist/src/commands/db3-types.js +159 -0
  44. package/dist/src/commands/db3-types.js.map +1 -0
  45. package/dist/src/commands/db3.d.ts +24 -0
  46. package/dist/src/commands/db3.js +1444 -0
  47. package/dist/src/commands/db3.js.map +1 -0
  48. package/dist/src/commands/documents.d.ts +110 -10
  49. package/dist/src/commands/documents.js +1012 -748
  50. package/dist/src/commands/documents.js.map +1 -1
  51. package/dist/src/commands/email-templates.js +74 -0
  52. package/dist/src/commands/email-templates.js.map +1 -1
  53. package/dist/src/commands/env.js +8 -4
  54. package/dist/src/commands/env.js.map +1 -1
  55. package/dist/src/commands/function-trigger-commands.d.ts +28 -0
  56. package/dist/src/commands/function-trigger-commands.js +341 -0
  57. package/dist/src/commands/function-trigger-commands.js.map +1 -0
  58. package/dist/src/commands/functions.js +376 -30
  59. package/dist/src/commands/functions.js.map +1 -1
  60. package/dist/src/commands/groups.js +168 -50
  61. package/dist/src/commands/groups.js.map +1 -1
  62. package/dist/src/commands/guides.js +7 -5
  63. package/dist/src/commands/guides.js.map +1 -1
  64. package/dist/src/commands/hosting.d.ts +8 -0
  65. package/dist/src/commands/hosting.js +346 -0
  66. package/dist/src/commands/hosting.js.map +1 -0
  67. package/dist/src/commands/init.js +129 -38
  68. package/dist/src/commands/init.js.map +1 -1
  69. package/dist/src/commands/integrations.js +82 -53
  70. package/dist/src/commands/integrations.js.map +1 -1
  71. package/dist/src/commands/llm.js +9 -6
  72. package/dist/src/commands/llm.js.map +1 -1
  73. package/dist/src/commands/locks.d.ts +5 -3
  74. package/dist/src/commands/locks.js +19 -61
  75. package/dist/src/commands/locks.js.map +1 -1
  76. package/dist/src/commands/metadata-category-configs.d.ts +2 -2
  77. package/dist/src/commands/metadata-category-configs.js +4 -2
  78. package/dist/src/commands/metadata-category-configs.js.map +1 -1
  79. package/dist/src/commands/metadata.js +41 -0
  80. package/dist/src/commands/metadata.js.map +1 -1
  81. package/dist/src/commands/prompts.js +75 -52
  82. package/dist/src/commands/prompts.js.map +1 -1
  83. package/dist/src/commands/rate-counters.d.ts +19 -0
  84. package/dist/src/commands/rate-counters.js +104 -0
  85. package/dist/src/commands/rate-counters.js.map +1 -0
  86. package/dist/src/commands/rule-sets.d.ts +1 -1
  87. package/dist/src/commands/rule-sets.js +2 -1
  88. package/dist/src/commands/rule-sets.js.map +1 -1
  89. package/dist/src/commands/schemas.d.ts +15 -0
  90. package/dist/src/commands/schemas.js +122 -0
  91. package/dist/src/commands/schemas.js.map +1 -0
  92. package/dist/src/commands/scripts.d.ts +9 -17
  93. package/dist/src/commands/scripts.js +24 -479
  94. package/dist/src/commands/scripts.js.map +1 -1
  95. package/dist/src/commands/secrets.js +47 -3
  96. package/dist/src/commands/secrets.js.map +1 -1
  97. package/dist/src/commands/sessions.js +2 -0
  98. package/dist/src/commands/sessions.js.map +1 -1
  99. package/dist/src/commands/settings.d.ts +12 -9
  100. package/dist/src/commands/settings.js +31 -79
  101. package/dist/src/commands/settings.js.map +1 -1
  102. package/dist/src/commands/skill.js +2 -0
  103. package/dist/src/commands/skill.js.map +1 -1
  104. package/dist/src/commands/sync-schemas.d.ts +202 -0
  105. package/dist/src/commands/sync-schemas.js +629 -0
  106. package/dist/src/commands/sync-schemas.js.map +1 -0
  107. package/dist/src/commands/sync-user-properties.d.ts +118 -0
  108. package/dist/src/commands/sync-user-properties.js +276 -0
  109. package/dist/src/commands/sync-user-properties.js.map +1 -0
  110. package/dist/src/commands/sync.d.ts +519 -554
  111. package/dist/src/commands/sync.js +3010 -4909
  112. package/dist/src/commands/sync.js.map +1 -1
  113. package/dist/src/commands/tokens.js +5 -3
  114. package/dist/src/commands/tokens.js.map +1 -1
  115. package/dist/src/commands/transitions.d.ts +54 -0
  116. package/dist/src/commands/transitions.js +418 -0
  117. package/dist/src/commands/transitions.js.map +1 -0
  118. package/dist/src/commands/usage.d.ts +18 -0
  119. package/dist/src/commands/usage.js +343 -0
  120. package/dist/src/commands/usage.js.map +1 -0
  121. package/dist/src/commands/user-properties.d.ts +14 -0
  122. package/dist/src/commands/user-properties.js +79 -0
  123. package/dist/src/commands/user-properties.js.map +1 -0
  124. package/dist/src/commands/users.js +911 -18
  125. package/dist/src/commands/users.js.map +1 -1
  126. package/dist/src/commands/vars.js +2 -0
  127. package/dist/src/commands/vars.js.map +1 -1
  128. package/dist/src/commands/waitlist.js +39 -4
  129. package/dist/src/commands/waitlist.js.map +1 -1
  130. package/dist/src/commands/workflows.d.ts +5 -83
  131. package/dist/src/commands/workflows.js +57 -2282
  132. package/dist/src/commands/workflows.js.map +1 -1
  133. package/dist/src/lib/analytics-query.d.ts +58 -0
  134. package/dist/src/lib/analytics-query.js +134 -0
  135. package/dist/src/lib/analytics-query.js.map +1 -0
  136. package/dist/src/lib/api-client.d.ts +1830 -429
  137. package/dist/src/lib/api-client.js +1025 -546
  138. package/dist/src/lib/api-client.js.map +1 -1
  139. package/dist/src/lib/app-settings-descriptor.d.ts +1 -1
  140. package/dist/src/lib/app-settings-descriptor.js +6 -0
  141. package/dist/src/lib/app-settings-descriptor.js.map +1 -1
  142. package/dist/src/lib/auth-fixtures.d.ts +44 -0
  143. package/dist/src/lib/auth-fixtures.js +61 -0
  144. package/dist/src/lib/auth-fixtures.js.map +1 -0
  145. package/dist/src/lib/auth-flow.d.ts +34 -1
  146. package/dist/src/lib/auth-flow.js +429 -13
  147. package/dist/src/lib/auth-flow.js.map +1 -1
  148. package/dist/src/lib/block-layout.d.ts +12 -23
  149. package/dist/src/lib/block-layout.js +26 -92
  150. package/dist/src/lib/block-layout.js.map +1 -1
  151. package/dist/src/lib/block-selector.d.ts +8 -14
  152. package/dist/src/lib/block-selector.js +8 -19
  153. package/dist/src/lib/block-selector.js.map +1 -1
  154. package/dist/src/lib/child-apps-local.d.ts +3 -47
  155. package/dist/src/lib/child-apps-local.js +11 -73
  156. package/dist/src/lib/child-apps-local.js.map +1 -1
  157. package/dist/src/lib/cli-manifest.d.ts +9 -0
  158. package/dist/src/lib/cli-manifest.js +10 -1
  159. package/dist/src/lib/cli-manifest.js.map +1 -1
  160. package/dist/src/lib/cli-version.d.ts +14 -0
  161. package/dist/src/lib/cli-version.js +38 -0
  162. package/dist/src/lib/cli-version.js.map +1 -0
  163. package/dist/src/lib/codegen-shared/prettierStable.d.ts +41 -0
  164. package/dist/src/lib/codegen-shared/prettierStable.js +146 -24
  165. package/dist/src/lib/codegen-shared/prettierStable.js.map +1 -1
  166. package/dist/src/lib/collection-export.d.ts +76 -15
  167. package/dist/src/lib/collection-export.js +116 -23
  168. package/dist/src/lib/collection-export.js.map +1 -1
  169. package/dist/src/lib/collection-principal.d.ts +22 -0
  170. package/dist/src/lib/collection-principal.js +35 -0
  171. package/dist/src/lib/collection-principal.js.map +1 -0
  172. package/dist/src/lib/command-groups.d.ts +30 -0
  173. package/dist/src/lib/command-groups.js +109 -0
  174. package/dist/src/lib/command-groups.js.map +1 -0
  175. package/dist/src/lib/command-status.d.ts +147 -0
  176. package/dist/src/lib/command-status.js +266 -0
  177. package/dist/src/lib/command-status.js.map +1 -0
  178. package/dist/src/lib/config-object-descriptor.d.ts +9 -22
  179. package/dist/src/lib/config-object-descriptor.js +107 -276
  180. package/dist/src/lib/config-object-descriptor.js.map +1 -1
  181. package/dist/src/lib/config-surface.d.ts +3 -7
  182. package/dist/src/lib/config-surface.js +9 -13
  183. package/dist/src/lib/config-surface.js.map +1 -1
  184. package/dist/src/lib/config-toml.d.ts +11 -2
  185. package/dist/src/lib/config-toml.js +25 -2
  186. package/dist/src/lib/config-toml.js.map +1 -1
  187. package/dist/src/lib/credentials-home.d.ts +7 -0
  188. package/dist/src/lib/credentials-home.js +45 -10
  189. package/dist/src/lib/credentials-home.js.map +1 -1
  190. package/dist/src/lib/credentials-lock.d.ts +14 -6
  191. package/dist/src/lib/credentials-lock.js +90 -10
  192. package/dist/src/lib/credentials-lock.js.map +1 -1
  193. package/dist/src/lib/credentials-store.d.ts +123 -70
  194. package/dist/src/lib/credentials-store.js +358 -113
  195. package/dist/src/lib/credentials-store.js.map +1 -1
  196. package/dist/src/lib/custodian.d.ts +8 -0
  197. package/dist/src/lib/custodian.js +18 -0
  198. package/dist/src/lib/custodian.js.map +1 -0
  199. package/dist/src/lib/data-input.d.ts +1 -1
  200. package/dist/src/lib/data-input.js +1 -1
  201. package/dist/src/lib/db-codegen/dbTsTypes.d.ts +1 -1
  202. package/dist/src/lib/db-codegen/dbTsTypes.js +3 -0
  203. package/dist/src/lib/db-codegen/dbTsTypes.js.map +1 -1
  204. package/dist/src/lib/db-codegen/dbTypeIR.d.ts +38 -1
  205. package/dist/src/lib/db-codegen/dbTypeIR.js +29 -7
  206. package/dist/src/lib/db-codegen/dbTypeIR.js.map +1 -1
  207. package/dist/src/lib/db-type-records.d.ts +106 -0
  208. package/dist/src/lib/db-type-records.js +224 -0
  209. package/dist/src/lib/db-type-records.js.map +1 -0
  210. package/dist/src/lib/db3-export.d.ts +287 -0
  211. package/dist/src/lib/db3-export.js +647 -0
  212. package/dist/src/lib/db3-export.js.map +1 -0
  213. package/dist/src/lib/db3-index-output.d.ts +116 -0
  214. package/dist/src/lib/db3-index-output.js +223 -0
  215. package/dist/src/lib/db3-index-output.js.map +1 -0
  216. package/dist/src/lib/db3-type-models.d.ts +134 -0
  217. package/dist/src/lib/db3-type-models.js +452 -0
  218. package/dist/src/lib/db3-type-models.js.map +1 -0
  219. package/dist/src/lib/deprecation.d.ts +2 -2
  220. package/dist/src/lib/deprecation.js +2 -2
  221. package/dist/src/lib/document-ingest-artifact.d.ts +13 -0
  222. package/dist/src/lib/document-ingest-artifact.js +36 -6
  223. package/dist/src/lib/document-ingest-artifact.js.map +1 -1
  224. package/dist/src/lib/document-ingest-format2.d.ts +36 -0
  225. package/dist/src/lib/document-ingest-format2.js +78 -0
  226. package/dist/src/lib/document-ingest-format2.js.map +1 -0
  227. package/dist/src/lib/document-ingest-input.d.ts +9 -0
  228. package/dist/src/lib/document-ingest-input.js +28 -1
  229. package/dist/src/lib/document-ingest-input.js.map +1 -1
  230. package/dist/src/lib/document-ingest.d.ts +11 -1
  231. package/dist/src/lib/document-ingest.js +16 -0
  232. package/dist/src/lib/document-ingest.js.map +1 -1
  233. package/dist/src/lib/document-schema-rows.d.ts +42 -0
  234. package/dist/src/lib/document-schema-rows.js +53 -0
  235. package/dist/src/lib/document-schema-rows.js.map +1 -0
  236. package/dist/src/lib/experimental-apis.d.ts +36 -0
  237. package/dist/src/lib/experimental-apis.js +46 -0
  238. package/dist/src/lib/experimental-apis.js.map +1 -0
  239. package/dist/src/lib/file-attachment.d.ts +24 -0
  240. package/dist/src/lib/file-attachment.js +31 -0
  241. package/dist/src/lib/file-attachment.js.map +1 -0
  242. package/dist/src/lib/function-authorize-check.d.ts +142 -0
  243. package/dist/src/lib/function-authorize-check.js +311 -0
  244. package/dist/src/lib/function-authorize-check.js.map +1 -0
  245. package/dist/src/lib/function-authorize-view.d.ts +27 -0
  246. package/dist/src/lib/function-authorize-view.js +88 -0
  247. package/dist/src/lib/function-authorize-view.js.map +1 -0
  248. package/dist/src/lib/function-bundle.d.ts +27 -5
  249. package/dist/src/lib/function-bundle.js +142 -7
  250. package/dist/src/lib/function-bundle.js.map +1 -1
  251. package/dist/src/lib/function-collect.d.ts +90 -12
  252. package/dist/src/lib/function-collect.js +482 -12
  253. package/dist/src/lib/function-collect.js.map +1 -1
  254. package/dist/src/lib/function-db-types.d.ts +65 -11
  255. package/dist/src/lib/function-db-types.js +297 -157
  256. package/dist/src/lib/function-db-types.js.map +1 -1
  257. package/dist/src/lib/function-document-types.d.ts +19 -7
  258. package/dist/src/lib/function-document-types.js +24 -12
  259. package/dist/src/lib/function-document-types.js.map +1 -1
  260. package/dist/src/lib/function-lint.d.ts +57 -0
  261. package/dist/src/lib/function-lint.js +234 -0
  262. package/dist/src/lib/function-lint.js.map +1 -0
  263. package/dist/src/lib/function-log-row.js +21 -2
  264. package/dist/src/lib/function-log-row.js.map +1 -1
  265. package/dist/src/lib/function-run.d.ts +13 -21
  266. package/dist/src/lib/function-run.js +14 -27
  267. package/dist/src/lib/function-run.js.map +1 -1
  268. package/dist/src/lib/function-schema-codegen.d.ts +86 -22
  269. package/dist/src/lib/function-schema-codegen.js +194 -88
  270. package/dist/src/lib/function-schema-codegen.js.map +1 -1
  271. package/dist/src/lib/function-schema-refs.d.ts +98 -0
  272. package/dist/src/lib/function-schema-refs.js +177 -0
  273. package/dist/src/lib/function-schema-refs.js.map +1 -0
  274. package/dist/src/lib/function-sync.d.ts +109 -6
  275. package/dist/src/lib/function-sync.js +179 -26
  276. package/dist/src/lib/function-sync.js.map +1 -1
  277. package/dist/src/lib/function-trigger-listing.d.ts +11 -6
  278. package/dist/src/lib/function-trigger-listing.js +32 -11
  279. package/dist/src/lib/function-trigger-listing.js.map +1 -1
  280. package/dist/src/lib/function-triggers.d.ts +15 -3
  281. package/dist/src/lib/function-triggers.js +72 -10
  282. package/dist/src/lib/function-triggers.js.map +1 -1
  283. package/dist/src/lib/function-typecheck.d.ts +52 -0
  284. package/dist/src/lib/function-typecheck.js +174 -54
  285. package/dist/src/lib/function-typecheck.js.map +1 -1
  286. package/dist/src/lib/function-versions.d.ts +2 -0
  287. package/dist/src/lib/function-versions.js +1 -0
  288. package/dist/src/lib/function-versions.js.map +1 -1
  289. package/dist/src/lib/generated-build-flags.d.ts +13 -0
  290. package/dist/src/lib/generated-build-flags.js +14 -0
  291. package/dist/src/lib/generated-build-flags.js.map +1 -0
  292. package/dist/src/lib/generated-command-status.d.ts +6 -0
  293. package/dist/src/lib/generated-command-status.js +469 -0
  294. package/dist/src/lib/generated-command-status.js.map +1 -0
  295. package/dist/src/lib/generated-config-surfaces.d.ts +586 -152
  296. package/dist/src/lib/generated-config-surfaces.js +1919 -1883
  297. package/dist/src/lib/generated-config-surfaces.js.map +1 -1
  298. package/dist/src/lib/generated-sdk-types.d.ts +1 -1
  299. package/dist/src/lib/generated-sdk-types.js +1 -1
  300. package/dist/src/lib/generated-sdk-types.js.map +1 -1
  301. package/dist/src/lib/generated-workflow-model-fields.d.ts +20 -0
  302. package/dist/src/lib/generated-workflow-model-fields.js +53 -0
  303. package/dist/src/lib/generated-workflow-model-fields.js.map +1 -0
  304. package/dist/src/lib/hosting-build.d.ts +97 -0
  305. package/dist/src/lib/hosting-build.js +204 -0
  306. package/dist/src/lib/hosting-build.js.map +1 -0
  307. package/dist/src/lib/hosting-client.d.ts +167 -0
  308. package/dist/src/lib/hosting-client.js +340 -0
  309. package/dist/src/lib/hosting-client.js.map +1 -0
  310. package/dist/src/lib/hosting-environments.d.ts +32 -0
  311. package/dist/src/lib/hosting-environments.js +74 -0
  312. package/dist/src/lib/hosting-environments.js.map +1 -0
  313. package/dist/src/lib/hosting-errors.d.ts +30 -0
  314. package/dist/src/lib/hosting-errors.js +43 -0
  315. package/dist/src/lib/hosting-errors.js.map +1 -0
  316. package/dist/src/lib/hosting-token.d.ts +46 -0
  317. package/dist/src/lib/hosting-token.js +60 -0
  318. package/dist/src/lib/hosting-token.js.map +1 -0
  319. package/dist/src/lib/hosting-wait.d.ts +42 -0
  320. package/dist/src/lib/hosting-wait.js +84 -0
  321. package/dist/src/lib/hosting-wait.js.map +1 -0
  322. package/dist/src/lib/hosting-wfp-upload.d.ts +86 -0
  323. package/dist/src/lib/hosting-wfp-upload.js +149 -0
  324. package/dist/src/lib/hosting-wfp-upload.js.map +1 -0
  325. package/dist/src/lib/init-assets.d.ts +2 -6
  326. package/dist/src/lib/init-assets.js +11 -27
  327. package/dist/src/lib/init-assets.js.map +1 -1
  328. package/dist/src/lib/init-ios-links.d.ts +11 -7
  329. package/dist/src/lib/init-ios-links.js +28 -22
  330. package/dist/src/lib/init-ios-links.js.map +1 -1
  331. package/dist/src/lib/init-login-note.d.ts +13 -0
  332. package/dist/src/lib/init-login-note.js +22 -0
  333. package/dist/src/lib/init-login-note.js.map +1 -0
  334. package/dist/src/lib/init-schema.d.ts +15 -0
  335. package/dist/src/lib/init-schema.js +54 -0
  336. package/dist/src/lib/init-schema.js.map +1 -1
  337. package/dist/src/lib/integration-test-request.d.ts +54 -0
  338. package/dist/src/lib/integration-test-request.js +207 -0
  339. package/dist/src/lib/integration-test-request.js.map +1 -0
  340. package/dist/src/lib/invoker-shared-enums.d.ts +35 -0
  341. package/dist/src/lib/invoker-shared-enums.js +98 -0
  342. package/dist/src/lib/invoker-shared-enums.js.map +1 -0
  343. package/dist/src/lib/json-value.d.ts +6 -0
  344. package/dist/src/lib/json-value.js +13 -0
  345. package/dist/src/lib/json-value.js.map +1 -0
  346. package/dist/src/lib/load-routes.d.ts +33 -0
  347. package/dist/src/lib/load-routes.js +35 -0
  348. package/dist/src/lib/load-routes.js.map +1 -0
  349. package/dist/src/lib/log-inspection.d.ts +23 -4
  350. package/dist/src/lib/log-inspection.js +14 -5
  351. package/dist/src/lib/log-inspection.js.map +1 -1
  352. package/dist/src/lib/login-exchange-check.d.ts +18 -0
  353. package/dist/src/lib/login-exchange-check.js +27 -0
  354. package/dist/src/lib/login-exchange-check.js.map +1 -0
  355. package/dist/src/lib/login-scope-lines.d.ts +17 -7
  356. package/dist/src/lib/login-scope-lines.js +33 -10
  357. package/dist/src/lib/login-scope-lines.js.map +1 -1
  358. package/dist/src/lib/metadata-report.d.ts +85 -0
  359. package/dist/src/lib/metadata-report.js +81 -0
  360. package/dist/src/lib/metadata-report.js.map +1 -0
  361. package/dist/src/lib/object-status-filter.d.ts +9 -1
  362. package/dist/src/lib/object-status-filter.js +9 -1
  363. package/dist/src/lib/object-status-filter.js.map +1 -1
  364. package/dist/src/lib/output.d.ts +1 -1
  365. package/dist/src/lib/output.js +3 -1
  366. package/dist/src/lib/output.js.map +1 -1
  367. package/dist/src/lib/pin-refusal-hint.d.ts +12 -0
  368. package/dist/src/lib/pin-refusal-hint.js +35 -0
  369. package/dist/src/lib/pin-refusal-hint.js.map +1 -0
  370. package/dist/src/lib/platform-owned.js +5 -0
  371. package/dist/src/lib/platform-owned.js.map +1 -1
  372. package/dist/src/lib/primitive-declaration-names.d.ts +21 -0
  373. package/dist/src/lib/primitive-declaration-names.js +22 -0
  374. package/dist/src/lib/primitive-declaration-names.js.map +1 -0
  375. package/dist/src/lib/primitive-declaration.d.ts +174 -0
  376. package/dist/src/lib/primitive-declaration.js +792 -0
  377. package/dist/src/lib/primitive-declaration.js.map +1 -0
  378. package/dist/src/lib/primitive-env-plugin.d.ts +99 -0
  379. package/dist/src/lib/primitive-env-plugin.js +408 -0
  380. package/dist/src/lib/primitive-env-plugin.js.map +1 -0
  381. package/dist/src/lib/project-login-apps.d.ts +8 -0
  382. package/dist/src/lib/project-login-apps.js +27 -0
  383. package/dist/src/lib/project-login-apps.js.map +1 -0
  384. package/dist/src/lib/prompt-schema-codegen.d.ts +46 -15
  385. package/dist/src/lib/prompt-schema-codegen.js +142 -108
  386. package/dist/src/lib/prompt-schema-codegen.js.map +1 -1
  387. package/dist/src/lib/prompt-schema-document.d.ts +35 -0
  388. package/dist/src/lib/prompt-schema-document.js +92 -0
  389. package/dist/src/lib/prompt-schema-document.js.map +1 -0
  390. package/dist/src/lib/prompt-schema-refs.d.ts +173 -0
  391. package/dist/src/lib/prompt-schema-refs.js +478 -0
  392. package/dist/src/lib/prompt-schema-refs.js.map +1 -0
  393. package/dist/src/lib/records-verbs.d.ts +79 -0
  394. package/dist/src/lib/records-verbs.js +45 -0
  395. package/dist/src/lib/records-verbs.js.map +1 -0
  396. package/dist/src/lib/register-commands.d.ts +36 -0
  397. package/dist/src/lib/register-commands.js +37 -0
  398. package/dist/src/lib/register-commands.js.map +1 -0
  399. package/dist/src/lib/retired-imports.d.ts +53 -0
  400. package/dist/src/lib/retired-imports.js +120 -0
  401. package/dist/src/lib/retired-imports.js.map +1 -0
  402. package/dist/src/lib/run-status.d.ts +1 -1
  403. package/dist/src/lib/run-status.generated.d.ts +2 -2
  404. package/dist/src/lib/run-status.generated.js +3 -1
  405. package/dist/src/lib/run-status.generated.js.map +1 -1
  406. package/dist/src/lib/run-status.js +1 -1
  407. package/dist/src/lib/schema-codegen/compiledSpace.d.ts +62 -0
  408. package/dist/src/lib/schema-codegen/compiledSpace.js +103 -0
  409. package/dist/src/lib/schema-codegen/compiledSpace.js.map +1 -0
  410. package/dist/src/lib/schema-codegen/generated-db3-bridge.d.ts +86 -0
  411. package/dist/src/lib/schema-codegen/generated-db3-bridge.js +227 -0
  412. package/dist/src/lib/schema-codegen/generated-db3-bridge.js.map +1 -0
  413. package/dist/src/lib/schema-codegen/generated-db3-query-capabilities.d.ts +85 -0
  414. package/dist/src/lib/schema-codegen/generated-db3-query-capabilities.js +86 -0
  415. package/dist/src/lib/schema-codegen/generated-db3-query-capabilities.js.map +1 -0
  416. package/dist/src/lib/schema-codegen/generated-field-grammar.d.ts +218 -0
  417. package/dist/src/lib/schema-codegen/generated-field-grammar.js +397 -0
  418. package/dist/src/lib/schema-codegen/generated-field-grammar.js.map +1 -0
  419. package/dist/src/lib/schema-codegen/generated-field-table.d.ts +80 -0
  420. package/dist/src/lib/schema-codegen/generated-field-table.js +542 -0
  421. package/dist/src/lib/schema-codegen/generated-field-table.js.map +1 -0
  422. package/dist/src/lib/schema-codegen/generated-prompt-schemas.d.ts +195 -0
  423. package/dist/src/lib/schema-codegen/generated-prompt-schemas.js +503 -0
  424. package/dist/src/lib/schema-codegen/generated-prompt-schemas.js.map +1 -0
  425. package/dist/src/lib/schema-codegen/generated-schema-descriptor.d.ts +258 -0
  426. package/dist/src/lib/schema-codegen/generated-schema-descriptor.js +422 -0
  427. package/dist/src/lib/schema-codegen/generated-schema-descriptor.js.map +1 -0
  428. package/dist/src/lib/schema-codegen/generated-schema-file.d.ts +129 -0
  429. package/dist/src/lib/schema-codegen/generated-schema-file.js +475 -0
  430. package/dist/src/lib/schema-codegen/generated-schema-file.js.map +1 -0
  431. package/dist/src/lib/schema-codegen/generated-schema-provenance.d.ts +115 -0
  432. package/dist/src/lib/schema-codegen/generated-schema-provenance.js +274 -0
  433. package/dist/src/lib/schema-codegen/generated-schema-provenance.js.map +1 -0
  434. package/dist/src/lib/schema-codegen/generated-schema-refs.d.ts +366 -0
  435. package/dist/src/lib/schema-codegen/generated-schema-refs.js +1789 -0
  436. package/dist/src/lib/schema-codegen/generated-schema-refs.js.map +1 -0
  437. package/dist/src/lib/schema-codegen/generated-schema-shape.d.ts +27 -0
  438. package/dist/src/lib/schema-codegen/generated-schema-shape.js +126 -0
  439. package/dist/src/lib/schema-codegen/generated-schema-shape.js.map +1 -0
  440. package/dist/src/lib/schema-codegen/namedRefs.d.ts +56 -0
  441. package/dist/src/lib/schema-codegen/namedRefs.js +143 -0
  442. package/dist/src/lib/schema-codegen/namedRefs.js.map +1 -0
  443. package/dist/src/lib/schema-codegen/naming.d.ts +35 -0
  444. package/dist/src/lib/schema-codegen/naming.js +83 -0
  445. package/dist/src/lib/schema-codegen/naming.js.map +1 -0
  446. package/dist/src/lib/schema-codegen/schemaChanges.d.ts +74 -0
  447. package/dist/src/lib/schema-codegen/schemaChanges.js +277 -0
  448. package/dist/src/lib/schema-codegen/schemaChanges.js.map +1 -0
  449. package/dist/src/lib/schema-codegen/schemaDocs.d.ts +69 -0
  450. package/dist/src/lib/schema-codegen/schemaDocs.js +219 -0
  451. package/dist/src/lib/schema-codegen/schemaDocs.js.map +1 -0
  452. package/dist/src/lib/schema-codegen/schemaIR.d.ts +158 -0
  453. package/dist/src/lib/schema-codegen/schemaIR.js +279 -0
  454. package/dist/src/lib/schema-codegen/schemaIR.js.map +1 -0
  455. package/dist/src/lib/schema-codegen/schemaToTs.d.ts +109 -0
  456. package/dist/src/lib/schema-codegen/schemaToTs.js +269 -0
  457. package/dist/src/lib/schema-codegen/schemaToTs.js.map +1 -0
  458. package/dist/src/lib/schema-codegen/valuesLists.d.ts +48 -0
  459. package/dist/src/lib/schema-codegen/valuesLists.js +144 -0
  460. package/dist/src/lib/schema-codegen/valuesLists.js.map +1 -0
  461. package/dist/src/lib/schema-family-index.d.ts +228 -0
  462. package/dist/src/lib/schema-family-index.js +813 -0
  463. package/dist/src/lib/schema-family-index.js.map +1 -0
  464. package/dist/src/lib/schema-pins.d.ts +82 -0
  465. package/dist/src/lib/schema-pins.js +198 -0
  466. package/dist/src/lib/schema-pins.js.map +1 -0
  467. package/dist/src/lib/schema-preview.d.ts +244 -0
  468. package/dist/src/lib/schema-preview.js +498 -0
  469. package/dist/src/lib/schema-preview.js.map +1 -0
  470. package/dist/src/lib/scope-request.d.ts +23 -11
  471. package/dist/src/lib/scope-request.js +69 -31
  472. package/dist/src/lib/scope-request.js.map +1 -1
  473. package/dist/src/lib/session-scope.d.ts +26 -0
  474. package/dist/src/lib/session-scope.js +58 -0
  475. package/dist/src/lib/session-scope.js.map +1 -0
  476. package/dist/src/lib/skill-installer.d.ts +2 -2
  477. package/dist/src/lib/skill-installer.js +2 -21
  478. package/dist/src/lib/skill-installer.js.map +1 -1
  479. package/dist/src/lib/step-run-table.d.ts +1 -2
  480. package/dist/src/lib/step-run-table.js +1 -2
  481. package/dist/src/lib/step-run-table.js.map +1 -1
  482. package/dist/src/lib/swift-codegen/agentGenerator.d.ts +8 -3
  483. package/dist/src/lib/swift-codegen/agentGenerator.js +76 -22
  484. package/dist/src/lib/swift-codegen/agentGenerator.js.map +1 -1
  485. package/dist/src/lib/swift-codegen/banners.d.ts +12 -0
  486. package/dist/src/lib/swift-codegen/banners.js +12 -0
  487. package/dist/src/lib/swift-codegen/banners.js.map +1 -1
  488. package/dist/src/lib/swift-codegen/functionGenerator.d.ts +36 -1
  489. package/dist/src/lib/swift-codegen/functionGenerator.js +169 -51
  490. package/dist/src/lib/swift-codegen/functionGenerator.js.map +1 -1
  491. package/dist/src/lib/swift-codegen/schemaToSwift.d.ts +33 -9
  492. package/dist/src/lib/swift-codegen/schemaToSwift.js +215 -179
  493. package/dist/src/lib/swift-codegen/schemaToSwift.js.map +1 -1
  494. package/dist/src/lib/swift-codegen/sharedGenerator.d.ts +45 -0
  495. package/dist/src/lib/swift-codegen/sharedGenerator.js +165 -0
  496. package/dist/src/lib/swift-codegen/sharedGenerator.js.map +1 -0
  497. package/dist/src/lib/swift-codegen/swiftKeys.d.ts +19 -0
  498. package/dist/src/lib/swift-codegen/swiftKeys.js +31 -0
  499. package/dist/src/lib/swift-codegen/swiftKeys.js.map +1 -0
  500. package/dist/src/lib/swift-codegen/userPropertiesGenerator.d.ts +30 -0
  501. package/dist/src/lib/swift-codegen/userPropertiesGenerator.js +69 -0
  502. package/dist/src/lib/swift-codegen/userPropertiesGenerator.js.map +1 -0
  503. package/dist/src/lib/sync-resource-types.d.ts +117 -31
  504. package/dist/src/lib/sync-resource-types.js +197 -189
  505. package/dist/src/lib/sync-resource-types.js.map +1 -1
  506. package/dist/src/lib/sync-selectors.d.ts +7 -0
  507. package/dist/src/lib/sync-selectors.js +22 -2
  508. package/dist/src/lib/sync-selectors.js.map +1 -1
  509. package/dist/src/lib/template.d.ts +39 -3
  510. package/dist/src/lib/template.js +103 -14
  511. package/dist/src/lib/template.js.map +1 -1
  512. package/dist/src/lib/test-case-file-names.d.ts +3 -5
  513. package/dist/src/lib/test-case-file-names.js +3 -5
  514. package/dist/src/lib/test-case-file-names.js.map +1 -1
  515. package/dist/src/lib/test-runs.d.ts +45 -0
  516. package/dist/src/lib/test-runs.js +150 -0
  517. package/dist/src/lib/test-runs.js.map +1 -0
  518. package/dist/src/lib/test-users.d.ts +25 -0
  519. package/dist/src/lib/test-users.js +36 -0
  520. package/dist/src/lib/test-users.js.map +1 -0
  521. package/dist/src/lib/toml-database-config.d.ts +4 -2
  522. package/dist/src/lib/toml-database-config.js +11 -6
  523. package/dist/src/lib/toml-database-config.js.map +1 -1
  524. package/dist/src/lib/toml-scalar-edit.js +6 -4
  525. package/dist/src/lib/toml-scalar-edit.js.map +1 -1
  526. package/dist/src/lib/transition-warnings.d.ts +21 -0
  527. package/dist/src/lib/transition-warnings.js +49 -0
  528. package/dist/src/lib/transition-warnings.js.map +1 -0
  529. package/dist/src/lib/user-index.d.ts +80 -0
  530. package/dist/src/lib/user-index.js +166 -0
  531. package/dist/src/lib/user-index.js.map +1 -0
  532. package/dist/src/lib/user-properties/generated-properties-schema.d.ts +159 -0
  533. package/dist/src/lib/user-properties/generated-properties-schema.js +471 -0
  534. package/dist/src/lib/user-properties/generated-properties-schema.js.map +1 -0
  535. package/dist/src/lib/user-properties/user-properties-codegen.d.ts +55 -0
  536. package/dist/src/lib/user-properties/user-properties-codegen.js +129 -0
  537. package/dist/src/lib/user-properties/user-properties-codegen.js.map +1 -0
  538. package/dist/src/lib/user-walk.d.ts +31 -0
  539. package/dist/src/lib/user-walk.js +102 -0
  540. package/dist/src/lib/user-walk.js.map +1 -0
  541. package/dist/src/lib/webhook-capture.d.ts +43 -0
  542. package/dist/src/lib/webhook-capture.js +91 -0
  543. package/dist/src/lib/webhook-capture.js.map +1 -0
  544. package/dist/src/lib/webhook-deliver.d.ts +18 -20
  545. package/dist/src/lib/webhook-deliver.js +34 -89
  546. package/dist/src/lib/webhook-deliver.js.map +1 -1
  547. package/dist/src/lib/webhook-test-run.d.ts +32 -0
  548. package/dist/src/lib/webhook-test-run.js +108 -0
  549. package/dist/src/lib/webhook-test-run.js.map +1 -0
  550. package/dist/src/lib/worker-perf-format.d.ts +22 -0
  551. package/dist/src/lib/worker-perf-format.js +27 -0
  552. package/dist/src/lib/worker-perf-format.js.map +1 -0
  553. package/dist/src/lib/workflow-field-descriptor.d.ts +91 -0
  554. package/dist/src/lib/workflow-field-descriptor.js +153 -0
  555. package/dist/src/lib/workflow-field-descriptor.js.map +1 -0
  556. package/dist/src/types/index.d.ts +20 -65
  557. package/dist/src/validators.d.ts +7 -55
  558. package/dist/src/validators.js +7 -53
  559. package/dist/src/validators.js.map +1 -1
  560. package/dist/src/vite.d.ts +17 -0
  561. package/dist/src/vite.js +18 -0
  562. package/dist/src/vite.js.map +1 -0
  563. package/package.json +20 -9
@@ -1,9 +1,13 @@
1
1
  import { loadCredentials, saveCredentials, isTokenExpiringSoon, } from "./config.js";
2
- import { getCurrentEnvNameSafe } from "./env-resolver.js";
2
+ import { reportTransitionWarnings } from "./transition-warnings.js";
3
+ import { getCurrentEnvNameSafe, getProjectConfig } from "./env-resolver.js";
4
+ import { pinRefusalHint } from "./pin-refusal-hint.js";
3
5
  import { fetchWithTLS } from "./fetch.js";
6
+ import { CLI_VERSION_HEADER, cliVersionHeaderValue } from "./cli-version.js";
4
7
  import { paginateAll, normalizeCliListEnvelope } from "./paginate.js";
5
8
  import { RefreshError, refreshAdminCredentials, } from "./refresh-admin-credentials.js";
6
- import { drainAppsUntilConverged, } from "./workflow-usage.js";
9
+ /** The `X-Primitive-CLI-Version` value, read from the package file once per process. */
10
+ let cliVersion;
7
11
  /**
8
12
  * Page size the admin per-user inventories are asked for (#3399).
9
13
  *
@@ -48,6 +52,15 @@ export class ApiError extends Error {
48
52
  }
49
53
  }
50
54
  }
55
+ /** The project's committed environments, or null outside a readable project. */
56
+ function projectEnvironments() {
57
+ try {
58
+ return getProjectConfig()?.environments ?? null;
59
+ }
60
+ catch {
61
+ return null;
62
+ }
63
+ }
51
64
  export class ConflictError extends ApiError {
52
65
  serverModifiedAt;
53
66
  expectedModifiedAt;
@@ -230,6 +243,8 @@ export class ApiClient {
230
243
  Authorization: `Bearer ${accessToken}`,
231
244
  "Content-Type": "application/json",
232
245
  ...(options.headers || {}),
246
+ // #5532 — every request names the CLI version that sent it.
247
+ [CLI_VERSION_HEADER]: (cliVersion ??= cliVersionHeaderValue()),
233
248
  };
234
249
  // Include globalAdminAppId if available (required for admin API calls)
235
250
  if (credentials.globalAdminAppId) {
@@ -247,10 +262,16 @@ export class ApiClient {
247
262
  // one. A retry refused 401 means the step-up is gone (revoked or expired
248
263
  // early): drop it and show the original refusal. The retry's own refusal
249
264
  // (say, a step-up without the scope this command needs) is shown as it is.
265
+ // #5822 — a successful write's platform transition warnings are printed.
266
+ const answered = (body) => {
267
+ const parsed = body ? JSON.parse(body) : null;
268
+ reportTransitionWarnings(options.method, parsed);
269
+ return parsed;
270
+ };
250
271
  if (response.status === 403 && this.stepUpApplies(response, text, path)) {
251
272
  const retried = await send(credentials.stepUp.accessToken);
252
273
  if (retried.response.ok) {
253
- return retried.text ? JSON.parse(retried.text) : null;
274
+ return answered(retried.text);
254
275
  }
255
276
  if (retried.response.status === 401) {
256
277
  this.dropStepUp();
@@ -262,7 +283,7 @@ export class ApiClient {
262
283
  if (!response.ok) {
263
284
  throw this.responseError(response, text, path);
264
285
  }
265
- return text ? JSON.parse(text) : null;
286
+ return answered(text);
266
287
  }
267
288
  /**
268
289
  * Whether a 403 should be retried with the stored step-up: it names
@@ -340,7 +361,9 @@ export class ApiClient {
340
361
  if (response.status === 400 && parsed.code === "TOML_PARSE_ERROR") {
341
362
  return new TomlParseError(parsed.message, detailsRecord);
342
363
  }
343
- return new ApiError(parsed.message, response.status, parsed.code, parsed.details);
364
+ // #4512 — a pin refusal on another environment's app names its login.
365
+ const hint = pinRefusalHint(parsed, this.credentials?.serverUrl ?? "", projectEnvironments());
366
+ return new ApiError(hint ? `${parsed.message} ${hint}` : parsed.message, response.status, parsed.code, parsed.details);
344
367
  }
345
368
  /**
346
369
  * `POST /admin/api/auth/token` — derive a token no wider than the stored
@@ -350,6 +373,60 @@ export class ApiClient {
350
373
  async exchangeToken(body) {
351
374
  return this.post("/admin/api/auth/token", body);
352
375
  }
376
+ /**
377
+ * #5787 — what `primitive hosting` may send for the current credentials:
378
+ * a CI token as it is (it cannot derive), or else nothing until a token is
379
+ * derived; and whether an unexpired step-up that may reach `appId` is
380
+ * stored. Throws the usual not-logged-in refusal.
381
+ */
382
+ async hostingCredentials(appId) {
383
+ const credentials = await this.ensureAuthenticated();
384
+ const stepUp = credentials.stepUp;
385
+ const usable = Boolean(stepUp?.accessToken) &&
386
+ new Date(stepUp.expiresAt).getTime() > Date.now() &&
387
+ (stepUp.apps.length === 0 || stepUp.apps.includes(appId));
388
+ // An opaque CI token (`primadm_…`, #3890) is no JWT and cannot derive.
389
+ const ci = credentials.accessToken.startsWith("primadm_");
390
+ return { ciToken: ci ? credentials.accessToken : null, stepUp: usable };
391
+ }
392
+ /**
393
+ * #5787 — `POST /admin/api/auth/token` for hosting: a `write`-only token of
394
+ * 15 minutes derived from the login, or from the stored step-up on a
395
+ * protected app, pinned to `appId` when that bearer is pinned and unpinned
396
+ * otherwise. Sent with exactly that bearer and never retried with another.
397
+ */
398
+ async deriveHostingToken(input) {
399
+ const credentials = await this.ensureAuthenticated();
400
+ const bearer = input.from === "step-up" ? credentials.stepUp?.accessToken : credentials.accessToken;
401
+ if (!bearer)
402
+ throw new ApiError("No step-up is stored for this login.", 403, "PROTECTED_APP_STEP_UP_REQUIRED");
403
+ let pins;
404
+ try {
405
+ pins = JSON.parse(Buffer.from(bearer.split(".")[1] ?? "", "base64url").toString("utf-8"))?.apps;
406
+ }
407
+ catch {
408
+ pins = undefined;
409
+ }
410
+ const pinned = Array.isArray(pins) && pins.length > 0;
411
+ const path = "/admin/api/auth/token";
412
+ const headers = {
413
+ Authorization: `Bearer ${bearer}`,
414
+ "Content-Type": "application/json",
415
+ [CLI_VERSION_HEADER]: (cliVersion ??= cliVersionHeaderValue()),
416
+ };
417
+ if (credentials.globalAdminAppId)
418
+ headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
419
+ const response = await fetchWithTLS(`${credentials.serverUrl}${path}`, {
420
+ method: "POST",
421
+ headers,
422
+ body: JSON.stringify({ scope: ["write"], ...(pinned ? { apps: [input.appId] } : {}), ttl: "15m" }),
423
+ });
424
+ const text = await response.text();
425
+ if (!response.ok)
426
+ throw this.responseError(response, text, path);
427
+ const derived = JSON.parse(text);
428
+ return { accessToken: derived.accessToken, expiresAt: derived.expiresAt };
429
+ }
353
430
  // Helper for GET requests with query params
354
431
  async get(path, params) {
355
432
  let fullPath = path;
@@ -436,38 +513,6 @@ export class ApiClient {
436
513
  });
437
514
  return { apps };
438
515
  }
439
- /**
440
- * Every app on the server, not just the caller's own.
441
- *
442
- * Deliberately separate from `listApps()`, whose contract is "apps assigned
443
- * to me" (`GET /admin/api/admins/me/apps`, backed by `admin.queryApps()`) —
444
- * the contract every other command depends on. `analytics workflow-usage
445
- * --all-apps` has to reach apps nobody is assigned to, which is the global
446
- * route `GET /admin/api/apps` (`App.iterateAll()`), and that route
447
- * identifies an app as `appId` rather than `id` (D3130-001).
448
- *
449
- * One drain of that route is lossy — its cursor re-scans `App.iterateAll()`
450
- * from the start of each page, so a list that changes under it both repeats
451
- * and drops rows — so the walk is the union of repeated drains
452
- * (`drainAppsUntilConverged`, which carries the measurement).
453
- */
454
- async listAllAppsGlobal() {
455
- const drainOnce = () => paginateAll(async (cursor) => {
456
- const qs = new URLSearchParams({ limit: "100" });
457
- if (cursor)
458
- qs.set("cursor", cursor);
459
- const resp = await this.get(`/admin/api/apps?${qs.toString()}`);
460
- const rows = resp.items ?? [];
461
- return {
462
- items: rows.map((row) => ({
463
- appId: String(row.appId ?? row.id ?? ""),
464
- name: String(row.name ?? ""),
465
- })),
466
- nextCursor: resp.nextCursor,
467
- };
468
- });
469
- return drainAppsUntilConverged(drainOnce);
470
- }
471
516
  /**
472
517
  * Create an app. An ordinary app takes `name` (and, for a super-admin,
473
518
  * `initialAdminEmail`). A child app takes `parentAppId` and `childSlug`
@@ -537,6 +582,15 @@ export class ApiClient {
537
582
  async addUserByEmail(appId, data) {
538
583
  return this.post(`/admin/api/apps/${appId}/users/add-by-email`, data);
539
584
  }
585
+ /**
586
+ * Invite an email to the app as a console admin
587
+ * (`POST /admin/api/apps/:appId/users/invite`): the invitation, with its
588
+ * `inviteToken` and the `initialProperties` it gives the invitee at
589
+ * acceptance (filling only what they have not set).
590
+ */
591
+ async inviteUser(appId, data) {
592
+ return this.post(`/admin/api/apps/${appId}/users/invite`, data);
593
+ }
540
594
  /**
541
595
  * Set a member's display name and/or avatar URL
542
596
  * (`PATCH /admin/api/apps/:appId/users/:userId/profile`). An omitted field
@@ -551,6 +605,168 @@ export class ApiClient {
551
605
  async rebuildUserSearchText(appId) {
552
606
  return this.post(`/admin/api/apps/${appId}/users/rebuild-search-text`, {});
553
607
  }
608
+ /**
609
+ * One page of an app's users from the user index
610
+ * (`POST /admin/api/apps/:appId/users/query`): the records-query filter and
611
+ * sort over base fields and `properties.<name>`, at most 1,000 per page.
612
+ */
613
+ async queryUsers(appId, body) {
614
+ return this.post(`/admin/api/apps/${appId}/users/query`, body);
615
+ }
616
+ /** How many of an app's users match (`POST /admin/api/apps/:appId/users/count`). */
617
+ async countUsers(appId, body) {
618
+ return this.post(`/admin/api/apps/${appId}/users/count`, body);
619
+ }
620
+ /**
621
+ * The state of an app's user index (`GET /admin/api/apps/:appId/users/index`):
622
+ * the generation, each shard with its bound and counts, superseded
623
+ * generations, a rebuild in progress, queued applies, the last apply and
624
+ * reconciliation, the limits and whether the shard ceiling is reached.
625
+ */
626
+ async getUserIndexStatus(appId) {
627
+ return this.get(`/admin/api/apps/${appId}/users/index`);
628
+ }
629
+ /**
630
+ * Start a report of which user metadata categories still hold rows on the
631
+ * app's current members (`POST /admin/api/apps/:appId/users/metadata-report`).
632
+ */
633
+ async startUserMetadataReport(appId) {
634
+ return this.post(`/admin/api/apps/${appId}/users/metadata-report`, {});
635
+ }
636
+ /**
637
+ * Read a user metadata report run, or the app's newest when `runId` is
638
+ * absent (`GET /admin/api/apps/:appId/users/metadata-report`).
639
+ */
640
+ async getUserMetadataReport(appId, runId) {
641
+ const query = runId ? `?runId=${encodeURIComponent(runId)}` : "";
642
+ return this.get(`/admin/api/apps/${appId}/users/metadata-report${query}`);
643
+ }
644
+ /** Start building the next generation of an app's user index (`POST /admin/api/apps/:appId/users/index/rebuild`). */
645
+ async rebuildUserIndex(appId) {
646
+ return this.post(`/admin/api/apps/${appId}/users/index/rebuild`, {});
647
+ }
648
+ /**
649
+ * Run one revalidation slice of an app's user index now
650
+ * (`POST /admin/api/apps/:appId/users/index/reconcile`), answered when it is
651
+ * done; `started: false` while the app is being deleted.
652
+ */
653
+ async reconcileUserIndex(appId) {
654
+ return this.post(`/admin/api/apps/${appId}/users/index/reconcile`, {});
655
+ }
656
+ /**
657
+ * Start (or find) a walk over an app's users with the admin as its starter
658
+ * (`POST /admin/api/apps/:appId/users/walks`); `existing` says the key named
659
+ * a walk that already existed.
660
+ */
661
+ async startUserWalk(appId, body) {
662
+ return this.post(`/admin/api/apps/${appId}/users/walks`, body);
663
+ }
664
+ /** A users walk by its run id (`GET /admin/api/apps/:appId/users/walks/:runId`). */
665
+ async getUserWalk(appId, runId) {
666
+ return this.get(`/admin/api/apps/${appId}/users/walks/${encodeURIComponent(runId)}`);
667
+ }
668
+ /** A rate counter's state by key (`GET /admin/api/apps/:appId/rate-counters/:key`). */
669
+ async getRateCounter(appId, key) {
670
+ return this.get(`/admin/api/apps/${appId}/rate-counters/${encodeURIComponent(key)}`);
671
+ }
672
+ /** Stop a users walk (`POST /admin/api/apps/:appId/users/walks/:runId/terminate`); batches in flight finish. */
673
+ async terminateUserWalk(appId, runId) {
674
+ return this.post(`/admin/api/apps/${appId}/users/walks/${encodeURIComponent(runId)}/terminate`, {});
675
+ }
676
+ /**
677
+ * An app's user index limit overrides and the limits in effect, with the
678
+ * property caps beside them (`GET /admin/api/apps/:appId/users/index/limits`).
679
+ */
680
+ async getUserIndexLimits(appId) {
681
+ return this.get(`/admin/api/apps/${appId}/users/index/limits`);
682
+ }
683
+ /**
684
+ * Set (a positive integer) or clear (`null`) an app's user index limit
685
+ * overrides (`PATCH /admin/api/apps/:appId/users/index/limits`).
686
+ */
687
+ async patchUserIndexLimits(appId, body) {
688
+ return this.patch(`/admin/api/apps/${appId}/users/index/limits`, body);
689
+ }
690
+ /**
691
+ * An app's user properties schema (`GET /admin/api/apps/:appId/users/properties`):
692
+ * the active version, a push being validated, the removed fields and the caps.
693
+ * While a push validates, this read also resumes its walk.
694
+ */
695
+ async getUserProperties(appId) {
696
+ return this.get(`/admin/api/apps/${appId}/users/properties`);
697
+ }
698
+ /**
699
+ * Push the text of `user-properties.toml` (`PUT /admin/api/apps/:appId/users/properties`):
700
+ * 200 `published` or `unchanged`, 400 when refused; `dryRun` judges it and
701
+ * writes nothing.
702
+ */
703
+ async pushUserProperties(appId, body, options = {}) {
704
+ return this.put(`/admin/api/apps/${appId}/users/properties${options.dryRun ? "?dryRun=true" : ""}`, body);
705
+ }
706
+ /**
707
+ * The current version of each of an app's `schemas/` files
708
+ * (`GET /admin/api/apps/:appId/schemas`); a tombstoned file only with
709
+ * `includeTombstoned`.
710
+ */
711
+ async listSchemaFiles(appId, options = {}) {
712
+ return this.get(`/admin/api/apps/${appId}/schemas${options.includeTombstoned ? "?includeTombstoned=true" : ""}`);
713
+ }
714
+ /**
715
+ * One version of a `schemas/` file, the current one unless `version` names
716
+ * another (`GET /admin/api/apps/:appId/schemas/:file`); 404
717
+ * `SCHEMA_FILE_NOT_FOUND` or `SCHEMA_VERSION_NOT_FOUND`.
718
+ */
719
+ async getSchemaFile(appId, file, options = {}) {
720
+ const query = options.version !== undefined ? `?version=${encodeURIComponent(String(options.version))}` : "";
721
+ return this.get(`/admin/api/apps/${appId}/schemas/${encodeURIComponent(file)}${query}`);
722
+ }
723
+ /**
724
+ * Push the text of `schemas/<file>.toml` with its compiled defs
725
+ * (`PUT /admin/api/apps/:appId/schemas/:file`): `created` or `unchanged`;
726
+ * 409 `CONFLICT` when the current version is not `expectedVersion`.
727
+ */
728
+ async pushSchemaFile(appId, file, body) {
729
+ return this.put(`/admin/api/apps/${appId}/schemas/${encodeURIComponent(file)}`, body);
730
+ }
731
+ /**
732
+ * Write a tombstone version of a `schemas/` file (`PUT
733
+ * /admin/api/apps/:appId/schemas/:file` with `{ tombstone: true }`), pinned
734
+ * to `expectedVersion` when given.
735
+ */
736
+ async tombstoneSchemaFile(appId, file, expectedVersion) {
737
+ return this.put(`/admin/api/apps/${appId}/schemas/${encodeURIComponent(file)}`, {
738
+ tombstone: true,
739
+ ...(expectedVersion !== undefined ? { expectedVersion } : {}),
740
+ });
741
+ }
742
+ /**
743
+ * The source of every live `schemas/` file, or of `files` only
744
+ * (`POST /admin/api/apps/:appId/schemas/pull`); a named file with no live
745
+ * version is listed under `missing`.
746
+ */
747
+ async pullSchemaFiles(appId, files) {
748
+ return this.post(`/admin/api/apps/${appId}/schemas/pull`, files ? { files } : {});
749
+ }
750
+ /** One member with their properties (`GET /admin/api/apps/:appId/users/:userId`); 404 `USER_NOT_FOUND` for a user who is no member. */
751
+ async getAppUser(appId, userId) {
752
+ return this.get(`/admin/api/apps/${appId}/users/${userId}`);
753
+ }
754
+ /**
755
+ * The member who holds a unique property value or a unique constraint's
756
+ * values (`POST /admin/api/apps/:appId/users/get-by`): `{ user }`, null when
757
+ * no member holds it.
758
+ */
759
+ async getAppUserBy(appId, selector) {
760
+ return this.post(`/admin/api/apps/${appId}/users/get-by`, selector);
761
+ }
762
+ /** Apply a property write to one member (`PATCH /admin/api/apps/:appId/users/:userId/properties`); answers the member after it. */
763
+ async setAppUserProperties(appId, userId, body) {
764
+ return this.patch(`/admin/api/apps/${appId}/users/${userId}/properties`, body);
765
+ }
766
+ /** An aggregate over an app's users (`POST /admin/api/apps/:appId/users/aggregate`). */
767
+ async aggregateUsers(appId, body) {
768
+ return this.post(`/admin/api/apps/${appId}/users/aggregate`, body);
769
+ }
554
770
  async listUsers(appId, params) {
555
771
  const query = new URLSearchParams();
556
772
  if (params?.name)
@@ -563,6 +779,8 @@ export class ApiClient {
563
779
  query.set("limit", String(params.limit));
564
780
  if (params?.cursor)
565
781
  query.set("cursor", params.cursor);
782
+ if (params?.testUsers)
783
+ query.set("testUsers", params.testUsers);
566
784
  const path = query.toString()
567
785
  ? `/app/${appId}/api/users?${query.toString()}`
568
786
  : `/app/${appId}/api/users`;
@@ -573,6 +791,8 @@ export class ApiClient {
573
791
  // page boundary rather than inferring one from the cursor (#3646).
574
792
  hasMore: result?.hasMore,
575
793
  nextCursor: result?.nextCursor ?? null,
794
+ // Rows a `testUsers` filtered read examined (#5104); absent otherwise.
795
+ ...(typeof result?.scanned === "number" ? { scanned: result.scanned } : {}),
576
796
  };
577
797
  }
578
798
  /**
@@ -591,36 +811,21 @@ export class ApiClient {
591
811
  async setUserAvailability(appId, userId, action) {
592
812
  return this.put(`/admin/api/apps/${appId}/users/${userId}/${action}`, {});
593
813
  }
594
- // ============================================
595
- // FEATURE FLAGS (super-admin)
596
- // ============================================
597
- /**
598
- * #2803 — the platform's feature flags. A server-owned admin toggle with a
599
- * console but, until now, no CLI: the same "one control, both surfaces" rule
600
- * the carrying types get.
601
- */
602
- async listFeatureFlags() {
603
- return this.get(`/admin/api/flags`);
604
- }
605
- /**
606
- * The flag itself, not the `{ flag }` envelope the route answers with —
607
- * `feature-flags get` prints the key, the enabled state and the per-app
608
- * overrides, and reading them off the envelope printed a blank row.
609
- */
610
- async getFeatureFlag(flagKey) {
611
- const result = await this.get(`/admin/api/flags/${flagKey}`);
612
- return result?.flag ?? result;
613
- }
614
- /** Same envelope, same unwrap: `enable`/`disable` print the updated flag. */
615
- async setFeatureFlagEnabled(flagKey, enabled) {
616
- const result = await this.put(`/admin/api/flags/${flagKey}`, { enabled });
617
- return result?.flag ?? result;
618
- }
619
814
  async updateUserRole(appId, userId, role) {
620
815
  return this.put(`/app/${appId}/api/users/${userId}/role`, { role });
621
816
  }
817
+ /**
818
+ * Make the app user with `newOwnerEmail` the app's owner; the previous
819
+ * owner becomes an admin. The email resolves to a userId through
820
+ * {@link lookupUserByEmail}, and an email no user of the app has rejects
821
+ * with a message naming it.
822
+ */
622
823
  async transferOwnership(appId, newOwnerEmail) {
623
- return this.post(`/app/${appId}/api/ownership`, { newOwnerEmail });
824
+ const lookup = await this.lookupUserByEmail(appId, newOwnerEmail);
825
+ if (!lookup.exists || !lookup.user?.userId) {
826
+ throw new Error(`No user with email ${newOwnerEmail} in app ${appId}`);
827
+ }
828
+ return this.post(`/admin/api/apps/${appId}/users/${lookup.user.userId}/transfer-ownership`, {});
624
829
  }
625
830
  async transferAdminOwnership(appId, adminId) {
626
831
  return this.post(`/admin/api/apps/${appId}/admins/transfer-ownership`, { adminId });
@@ -656,6 +861,14 @@ export class ApiClient {
656
861
  hasMore: result?.hasMore ?? nextCursor != null,
657
862
  };
658
863
  }
864
+ /**
865
+ * `GET /app/{appId}/api/invitations/{invitationId}` — one invitation with
866
+ * its `inviteToken` (the bearer credential an accept link carries) and its
867
+ * `status`. Readable by an app admin/owner or the inviter.
868
+ */
869
+ async getInvitation(appId, invitationId) {
870
+ return this.get(`/app/${appId}/api/invitations/${encodeURIComponent(invitationId)}`);
871
+ }
659
872
  async createInvitation(appId, data) {
660
873
  return this.post(`/app/${appId}/api/invitations`, data);
661
874
  }
@@ -704,14 +917,14 @@ export class ApiClient {
704
917
  nextCursor: result?.nextCursor ?? null,
705
918
  };
706
919
  }
707
- /** Integration detail (#2631: `accessRule` is on the detail, not the list summary). */
920
+ /** Integration detail (`requestConfig` is on the detail, not the list summary). */
708
921
  async getIntegration(appId, integrationId) {
709
922
  return this.get(`/admin/api/apps/${appId}/integrations/${integrationId}`);
710
923
  }
711
924
  /**
712
925
  * An integration's named configs. Test cases pin a config by NAME so the
713
926
  * sidecar is portable across apps (#2769); this is the map pull and push
714
- * resolve that name through, the same way prompts/workflows/scripts do.
927
+ * resolve that name through, the same way prompts do.
715
928
  */
716
929
  async listIntegrationConfigs(appId, integrationId) {
717
930
  const result = await this.get(`/admin/api/apps/${appId}/integrations/${integrationId}/configs`);
@@ -744,10 +957,6 @@ export class ApiClient {
744
957
  const result = await this.get(`/admin/api/apps/${appId}/integrations/${integrationId}/logs`, params);
745
958
  return result?.items ?? [];
746
959
  }
747
- async listWorkflowRunIntegrationLogs(appId, runId, params) {
748
- const result = await this.get(`/admin/api/apps/${appId}/workflows/runs/${runId}/integration-logs`, params);
749
- return result?.items ?? [];
750
- }
751
960
  // ============================================
752
961
  // APP SECRETS
753
962
  // ============================================
@@ -807,52 +1016,18 @@ export class ApiClient {
807
1016
  // ============================================
808
1017
  // WEBHOOKS
809
1018
  // ============================================
810
- async listWebhooks(appId, params) {
811
- const result = await this.get(`/admin/api/apps/${appId}/webhooks`, params);
812
- return {
813
- items: result?.items ?? [],
814
- hasMore: result?.hasMore,
815
- nextCursor: result?.nextCursor ?? null,
816
- };
817
- }
818
- async getWebhook(appId, webhookId) {
819
- return this.get(`/admin/api/apps/${appId}/webhooks/${webhookId}`);
820
- }
821
- async createWebhook(appId, payload) {
822
- return this.post(`/admin/api/apps/${appId}/webhooks`, payload);
823
- }
824
- async updateWebhook(appId, webhookId, payload, expectedModifiedAt) {
825
- const body = expectedModifiedAt ? { ...payload, expectedModifiedAt } : payload;
826
- return this.patch(`/admin/api/apps/${appId}/webhooks/${webhookId}`, body);
827
- }
828
- /**
829
- * Delete a webhook. Archives it by default; `hard` hard-deletes the row
830
- * instead (#2232), which is what frees a slot under the per-app webhook cap
831
- * and releases the webhook key for reuse. Same `?hard=true` verb the admin
832
- * integrations delete uses.
833
- */
834
- async deleteWebhook(appId, webhookId, options) {
835
- const query = options?.hard ? "?hard=true" : "";
836
- return this.delete(`/admin/api/apps/${appId}/webhooks/${webhookId}${query}`);
837
- }
838
- /**
839
- * #2803 — the operational verb pair for a webhook. It posts to the
840
- * enable/disable route rather than PATCHing `status`, which is server-owned
841
- * and refused on every configuration write path.
842
- */
843
- async setWebhookAvailability(appId, webhookId, action) {
844
- return this.post(`/admin/api/apps/${appId}/webhooks/${webhookId}/${action}`, {});
845
- }
846
1019
  // ── Server functions (#3179) ─────────────────────────────────────────
847
1020
  //
848
- // The `functions` family mirrors workflows and scripts: a header with the
849
- // gate and the entry, and append-only immutable config versions carrying the
850
- // authored TOML bytes, the sources and the built bundle. The listing drains
851
- // server-side, so it has no cursor.
1021
+ // The `functions` family is a header with the gate and the entry, and
1022
+ // append-only immutable config versions carrying the authored TOML bytes,
1023
+ // the sources and the built bundle. The listing drains server-side, so it
1024
+ // has no cursor.
1025
+ /** Every function of the app; each item carries {@link FunctionActiveInputFields}. */
852
1026
  async listFunctions(appId) {
853
1027
  const result = await this.get(`/admin/api/apps/${appId}/functions`);
854
1028
  return { items: result?.items ?? [] };
855
1029
  }
1030
+ /** One function; the answer carries {@link FunctionActiveInputFields}. */
856
1031
  async getFunction(appId, functionId) {
857
1032
  return this.get(`/admin/api/apps/${appId}/functions/${functionId}`);
858
1033
  }
@@ -887,6 +1062,38 @@ export class ApiClient {
887
1062
  const result = await this.get(`/admin/api/apps/${appId}/functions/${functionId}/runs`, params);
888
1063
  return { items: result?.items ?? [], nextCursor: result?.nextCursor ?? null };
889
1064
  }
1065
+ // ── A function's trigger operations (#3190) ──
1066
+ // The operational home of a function's webhook and cron triggers, keyed by
1067
+ // the function and a cron entry's name rather than a trigger row's id.
1068
+ functionTriggersPath(appId, functionId) {
1069
+ return `/admin/api/apps/${appId}/functions/${encodeURIComponent(functionId)}/triggers`;
1070
+ }
1071
+ /** The function's webhook delivery log, newest first. */
1072
+ async listFunctionWebhookEvents(appId, functionId, params) {
1073
+ const result = await this.get(`${this.functionTriggersPath(appId, functionId)}/webhook/events`, params);
1074
+ const nextCursor = result?.nextCursor ?? null;
1075
+ return {
1076
+ items: result?.items ?? [],
1077
+ hasMore: result?.hasMore ?? !!nextCursor,
1078
+ nextCursor,
1079
+ };
1080
+ }
1081
+ /** Sign a preview delivery for the function's webhook trigger. */
1082
+ async testFunctionWebhook(appId, functionId, payload) {
1083
+ return this.post(`${this.functionTriggersPath(appId, functionId)}/webhook/test`, payload || {});
1084
+ }
1085
+ /** Check captured headers and a captured body against the trigger's verifier. */
1086
+ async verifyFunctionWebhook(appId, functionId, payload) {
1087
+ return this.post(`${this.functionTriggersPath(appId, functionId)}/webhook/verify`, payload);
1088
+ }
1089
+ /** Point the trigger's `signingSecret` at a new `{{secrets.KEY}}` reference. */
1090
+ async rotateFunctionWebhookSecret(appId, functionId, payload) {
1091
+ return this.post(`${this.functionTriggersPath(appId, functionId)}/webhook/rotate-secret`, payload);
1092
+ }
1093
+ /** One cron entry verb: `fire`, `fire-scheduled`, `enable` or `disable`. */
1094
+ async functionCronEntryAction(appId, functionId, name, action) {
1095
+ return this.post(`${this.functionTriggersPath(appId, functionId)}/cron/${encodeURIComponent(name)}/${action}`, {});
1096
+ }
890
1097
  /**
891
1098
  * A function run's step trace — #3348.
892
1099
  *
@@ -900,6 +1107,16 @@ export class ApiClient {
900
1107
  const result = await this.get(`/admin/api/apps/${appId}/functions/${functionId}/runs/${runId}/steps`);
901
1108
  return { items: result?.items ?? [] };
902
1109
  }
1110
+ /**
1111
+ * The integration calls one function run made — #3190.
1112
+ *
1113
+ * The run → integration-logs pivot, addressed by the function that owns the
1114
+ * run (it was `workflows/runs/{runId}/integration-logs`).
1115
+ */
1116
+ async listFunctionRunIntegrationLogs(appId, functionId, runId, options) {
1117
+ const result = await this.get(`/admin/api/apps/${appId}/functions/${functionId}/runs/${runId}/integration-logs`, options?.limit !== undefined ? { limit: options.limit } : undefined);
1118
+ return { items: result?.items ?? [] };
1119
+ }
903
1120
  /**
904
1121
  * End a function run that will not settle — #3348.
905
1122
  *
@@ -972,9 +1189,10 @@ export class ApiClient {
972
1189
  async invokeFunction(appId, functionKey, body, options) {
973
1190
  const credentials = await this.ensureAuthenticated();
974
1191
  const base = `/app/${appId}/api/functions/${encodeURIComponent(functionKey)}`;
1192
+ const task = options?.runtime === "task";
975
1193
  const path = options?.asSystem
976
- ? `${base}/invoke-as-system`
977
- : options?.runtime === "task"
1194
+ ? `${base}/${task ? "start-as-system" : "invoke-as-system"}`
1195
+ : task
978
1196
  ? `${base}/start`
979
1197
  : base;
980
1198
  const init = (bearer) => {
@@ -1014,13 +1232,46 @@ export class ApiClient {
1014
1232
  body: parsed,
1015
1233
  };
1016
1234
  }
1235
+ /**
1236
+ * Run only a function's `authorize` and hand back the ANSWER, whatever its
1237
+ * HTTP status — #4732. Like `invokeFunction`, it returns a refusal rather
1238
+ * than throwing it, so `functions authorize` renders the server's own
1239
+ * answer (and a case run records it as a failed row); it throws only when
1240
+ * the request did not complete. The CLI's own credentials, with the
1241
+ * step-up retry a protected app's refusal asks for.
1242
+ */
1243
+ async authorizeFunction(appId, functionId, body) {
1244
+ const credentials = await this.ensureAuthenticated();
1245
+ const path = `/admin/api/apps/${appId}/functions/${encodeURIComponent(functionId)}/authorize`;
1246
+ const init = (bearer) => {
1247
+ const headers = {
1248
+ Authorization: `Bearer ${bearer}`,
1249
+ "Content-Type": "application/json",
1250
+ };
1251
+ if (credentials.globalAdminAppId) {
1252
+ headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
1253
+ }
1254
+ return { method: "POST", headers, body: JSON.stringify(body) };
1255
+ };
1256
+ const response = await this.fetchWithStepUp(`${credentials.serverUrl}${path}`, path, credentials.accessToken, init);
1257
+ const text = await response.text();
1258
+ let parsed = null;
1259
+ try {
1260
+ parsed = text ? JSON.parse(text) : null;
1261
+ }
1262
+ catch {
1263
+ parsed = { error: text };
1264
+ }
1265
+ return { httpStatus: response.status, body: parsed };
1266
+ }
1017
1267
  /**
1018
1268
  * A function's versions, newest first (#3462).
1019
1269
  *
1020
1270
  * Paging is opt-in on the server: with no `limit` and no `cursor` every
1021
1271
  * version comes back, which is what this method did before paging existed and
1022
1272
  * what an already-installed CLI still asks for. A caller that passes either
1023
- * gets the shared `{ items, hasMore, nextCursor }` page.
1273
+ * gets the shared `{ items, hasMore, nextCursor }` page. Each item carries
1274
+ * {@link FunctionVersionInputFields}.
1024
1275
  */
1025
1276
  async listFunctionConfigs(appId, functionId, options = {}) {
1026
1277
  const query = new URLSearchParams();
@@ -1044,6 +1295,7 @@ export class ApiClient {
1044
1295
  async activateFunctionConfig(appId, functionId, configId) {
1045
1296
  return this.post(`/admin/api/apps/${appId}/functions/${functionId}/configs/${configId}/activate`, {});
1046
1297
  }
1298
+ /** One version; the answer carries {@link FunctionVersionInputFields}. */
1047
1299
  async getFunctionConfig(appId, functionId, configId) {
1048
1300
  return this.get(`/admin/api/apps/${appId}/functions/${functionId}/configs/${configId}`);
1049
1301
  }
@@ -1066,18 +1318,6 @@ export class ApiClient {
1066
1318
  async setIntegrationAvailability(appId, integrationId, action) {
1067
1319
  return this.post(`/admin/api/apps/${appId}/integrations/${integrationId}/${action}`, {});
1068
1320
  }
1069
- async rotateWebhookSecret(appId, webhookId, payload) {
1070
- return this.post(`/admin/api/apps/${appId}/webhooks/${webhookId}/rotate-secret`, payload);
1071
- }
1072
- async listWebhookEvents(appId, webhookId, params) {
1073
- const result = await this.get(`/admin/api/apps/${appId}/webhooks/${webhookId}/events`, params);
1074
- const nextCursor = result?.nextCursor ?? null;
1075
- return {
1076
- items: result?.items ?? [],
1077
- hasMore: result?.hasMore ?? !!nextCursor,
1078
- nextCursor,
1079
- };
1080
- }
1081
1321
  // ============================================
1082
1322
  // CONNECTIONS INSPECTION (#1968)
1083
1323
  // ============================================
@@ -1148,20 +1388,6 @@ export class ApiClient {
1148
1388
  async revokeAdminSession(sessionId) {
1149
1389
  return this.delete(`/admin/api/auth/sessions/${encodeURIComponent(sessionId)}`);
1150
1390
  }
1151
- async testWebhook(appId, webhookId, payload) {
1152
- return this.post(`/admin/api/apps/${appId}/webhooks/${webhookId}/test`, payload || {});
1153
- }
1154
- /**
1155
- * Run a webhook's configured verifier over headers and a body captured from
1156
- * a real delivery, and report whether that signature checks out (#2445).
1157
- *
1158
- * `headers` is sent as ordered `[name, value]` pairs so a capture carrying a
1159
- * field name on more than one line survives the round trip. Nothing is
1160
- * delivered: no delivery record, no workflow run.
1161
- */
1162
- async verifyWebhook(appId, webhookId, payload) {
1163
- return this.post(`/admin/api/apps/${appId}/webhooks/${webhookId}/verify`, payload);
1164
- }
1165
1391
  // ============================================
1166
1392
  // NAMED LOCKS (#1518)
1167
1393
  // ============================================
@@ -1173,70 +1399,15 @@ export class ApiClient {
1173
1399
  return this.post(`/app/${appId}/api/locks/status`, { key });
1174
1400
  }
1175
1401
  /**
1176
- * #3562 — `owner` is sent only when one was given, so a call that names none
1177
- * composes byte for byte the body it always did.
1402
+ * #4959 — free a key whose lease is live, with no handle (admin). Acquire,
1403
+ * renew and release are server-function-only, so the CLI has no door to them.
1178
1404
  */
1179
- async acquireLock(appId, key, ttlMs, owner) {
1180
- return this.post(`/app/${appId}/api/locks/acquire`, {
1181
- key,
1182
- ttlMs,
1183
- ...(owner !== undefined ? { owner } : {}),
1184
- });
1185
- }
1186
- async releaseLock(appId, key, handleId) {
1187
- return this.post(`/app/${appId}/api/locks/release`, {
1188
- key,
1189
- handle: { handleId },
1190
- });
1405
+ async forceReleaseLock(appId, key) {
1406
+ return this.post(`/app/${appId}/api/locks/force-release`, { key });
1191
1407
  }
1192
1408
  // ============================================
1193
1409
  // CRON TRIGGERS
1194
1410
  // ============================================
1195
- async listCronTriggers(appId) {
1196
- const result = await this.get(`/app/${appId}/api/cron-triggers`);
1197
- return { items: result?.items ?? [] };
1198
- }
1199
- async getCronTrigger(appId, triggerId) {
1200
- return this.get(`/app/${appId}/api/cron-triggers/${triggerId}`);
1201
- }
1202
- async createCronTrigger(appId, payload) {
1203
- return this.post(`/app/${appId}/api/cron-triggers`, payload);
1204
- }
1205
- async updateCronTrigger(appId, triggerId, payload) {
1206
- return this.put(`/app/${appId}/api/cron-triggers/${triggerId}`, payload);
1207
- }
1208
- /**
1209
- * Retire a cron trigger. The default soft-deletes (writes the `archived`
1210
- * tombstone); `{ hard: true }` destroys the row, which is what
1211
- * `config push --prune` passes (#2803) so a pruned trigger stops consuming
1212
- * the per-app cap and holding its key.
1213
- */
1214
- async deleteCronTrigger(appId, triggerId, options = {}) {
1215
- const query = options.hard ? "?hard=true" : "";
1216
- return this.delete(`/app/${appId}/api/cron-triggers/${triggerId}${query}`);
1217
- }
1218
- async disableCronTrigger(appId, triggerId) {
1219
- return this.post(`/app/${appId}/api/cron-triggers/${triggerId}/disable`, {});
1220
- }
1221
- async enableCronTrigger(appId, triggerId) {
1222
- return this.post(`/app/${appId}/api/cron-triggers/${triggerId}/enable`, {});
1223
- }
1224
- async testCronTrigger(appId, triggerId) {
1225
- return this.post(`/app/${appId}/api/cron-triggers/${triggerId}/test`, {});
1226
- }
1227
- // ============================================
1228
- // ITERATIONS (iterate-users introspection / reset — #1209)
1229
- // ============================================
1230
- async listIterations(appId) {
1231
- const result = await this.get(`/app/${appId}/api/iterations`);
1232
- return { items: result?.items ?? [] };
1233
- }
1234
- async getIteration(appId, iterationName) {
1235
- return this.get(`/app/${appId}/api/iterations/${encodeURIComponent(iterationName)}`);
1236
- }
1237
- async resetIteration(appId, iterationName) {
1238
- return this.post(`/app/${appId}/api/iterations/${encodeURIComponent(iterationName)}/reset`, {});
1239
- }
1240
1411
  // ============================================
1241
1412
  // RESOURCE METADATA (values — issue #1352)
1242
1413
  // ============================================
@@ -1340,86 +1511,11 @@ export class ApiClient {
1340
1511
  async duplicatePromptConfig(appId, promptId, configId, payload) {
1341
1512
  return this.post(`/admin/api/apps/${appId}/prompts/${promptId}/configs/${configId}/duplicate`, payload || {});
1342
1513
  }
1343
- // ============================================
1344
- // SCRIPTS (Rhai transforms) — #1000 (prompt-model convergence)
1345
- // ============================================
1346
- //
1347
- // The `Script` model is the authoring surface for `script` workflow
1348
- // steps. A `Script` is a HEADER (name/description/activeConfigId); the
1349
- // Rhai body lives on versioned `ScriptConfig` rows resolved LIVE at run
1350
- // time. CLI `config push` reads `transforms/*.rhai` files and reconciles
1351
- // them: a new file → create script (mints a default config); a changed
1352
- // file → create a new config + activate it (zero fan-out — referencing
1353
- // workflows pick up the new body on their next run).
1354
- async listScripts(appId) {
1355
- const result = await this.get(`/admin/api/apps/${appId}/scripts`);
1356
- return { items: result?.items ?? [] };
1357
- }
1358
- async getScript(appId, scriptId) {
1359
- return this.get(`/admin/api/apps/${appId}/scripts/${scriptId}`);
1360
- }
1361
- /**
1362
- * List a script's versioned configs (the `ScriptConfig` rows). Each config
1363
- * is a distinct block version: `configId` is the stable version selector,
1364
- * `contentHash` is its content identity, and `status` reports whether it is
1365
- * `active`/`draft`/`archived`. The script header's `activeConfigId` names
1366
- * the live version. Used by `scripts configs list` and by the script test
1367
- * commands to run against a specific pinned version.
1368
- */
1369
- async listScriptConfigs(appId, scriptId) {
1370
- const result = await this.get(`/admin/api/apps/${appId}/scripts/${scriptId}/configs`);
1371
- return { items: result?.items ?? [] };
1372
- }
1373
- async createScript(appId, payload) {
1374
- // Mints the script header + a default `active` config carrying the body.
1375
- return this.post(`/admin/api/apps/${appId}/scripts`, payload);
1376
- }
1377
- /**
1378
- * Push a new body for an existing script by creating a new `ScriptConfig`
1379
- * and activating it (the prompt-model "edit → activate" flow). Referencing
1380
- * workflows pick up the new body on their next run with no fan-out. The
1381
- * config name is unique per script, so we mint a timestamped name.
1382
- */
1383
- async pushScriptBody(appId, scriptId, body,
1384
- /**
1385
- * The active state the caller believes holds right now (#2731 B10).
1386
- * Creating an inactive config races nothing, so the guard sits on the
1387
- * ACTIVATION step: if the active config has moved since the caller read it,
1388
- * the server rejects with a 409 instead of overwriting a concurrent script
1389
- * change. It takes BOTH halves of "what is active", because a config's body
1390
- * can be edited in place without the active id changing — the id alone
1391
- * would let such an edit through. Omitted (e.g. `--force`) means activate
1392
- * unconditionally.
1393
- */
1394
- expectedActive) {
1395
- const configName = `sync-${Date.now()}`;
1396
- const config = await this.post(`/admin/api/apps/${appId}/scripts/${scriptId}/configs`, { configName, body });
1397
- const activateBody = {};
1398
- if (expectedActive?.configId) {
1399
- activateBody.expectedActiveConfigId = expectedActive.configId;
1400
- }
1401
- if (expectedActive?.modifiedAt) {
1402
- activateBody.expectedActiveModifiedAt = expectedActive.modifiedAt;
1403
- }
1404
- await this.post(`/admin/api/apps/${appId}/scripts/${scriptId}/configs/${config.configId}/activate`, activateBody);
1405
- return config;
1406
- }
1407
- /**
1408
- * Delete a script header (cascades its configs). `force` overrides the
1409
- * server's guard against deleting a script that an active workflow still
1410
- * references by name — without it the server answers 409.
1411
- */
1412
- async deleteScript(appId, scriptId, force) {
1413
- const path = force
1414
- ? `/admin/api/apps/${appId}/scripts/${scriptId}?force=true`
1415
- : `/admin/api/apps/${appId}/scripts/${scriptId}`;
1416
- return this.delete(path);
1417
- }
1418
1514
  async getPromptSchema(appId, promptId) {
1419
1515
  return this.get(`/admin/api/apps/${appId}/prompts/${promptId}/schema`);
1420
1516
  }
1421
1517
  // ============================================
1422
- // BLOCK TEST CASES (Prompts, Integrations, Workflows)
1518
+ // BLOCK TEST CASES (Prompts, Integrations)
1423
1519
  // ============================================
1424
1520
  /**
1425
1521
  * One page of a block's test cases. The endpoint paginates (default 50, cap
@@ -1587,188 +1683,171 @@ export class ApiClient {
1587
1683
  async runAllTestCases(appId, blockType, blockId, payload) {
1588
1684
  return this.post(`/admin/api/apps/${appId}/blocks/${blockType}/${blockId}/test-all`, payload || {});
1589
1685
  }
1590
- async listTestRuns(appId, blockType, blockId, params) {
1591
- const result = await this.get(`/admin/api/apps/${appId}/blocks/${blockType}/${blockId}/runs`, params);
1592
- return { items: result?.items ?? result ?? [] };
1593
- }
1594
- // ============================================
1595
- // WORKFLOWS
1596
- // ============================================
1597
- async listWorkflows(appId, params) {
1598
- const result = await this.get(`/admin/api/apps/${appId}/workflows`, params);
1686
+ /**
1687
+ * One page of a block's test runs, newest first. The endpoint paginates
1688
+ * (default 50, cap 100) and reports `nextCursor`.
1689
+ */
1690
+ async listTestRuns(appId, blockType, blockId, params = {}) {
1691
+ const query = new URLSearchParams();
1692
+ if (params.limit !== undefined)
1693
+ query.set("limit", String(params.limit));
1694
+ if (params.cursor)
1695
+ query.set("cursor", params.cursor);
1696
+ const suffix = query.toString() ? `?${query.toString()}` : "";
1697
+ const result = await this.get(`/admin/api/apps/${appId}/blocks/${blockType}/${blockId}/runs${suffix}`);
1599
1698
  return {
1600
1699
  items: result?.items ?? [],
1601
1700
  hasMore: result?.hasMore,
1602
- nextCursor: result?.nextCursor ?? null,
1701
+ nextCursor: result?.nextCursor ?? undefined,
1603
1702
  };
1604
1703
  }
1605
- async getWorkflow(appId, workflowId) {
1606
- return this.get(`/admin/api/apps/${appId}/workflows/${workflowId}`);
1607
- }
1608
1704
  /**
1609
- * One app's workflow step usage report (#3132).
1610
- *
1611
- * `windowDays` is omitted from the query when the caller did not ask for a
1612
- * window, so the server applies its own default rather than the CLI
1613
- * restating it on the wire.
1705
+ * One of a block's test runs: the object `listTestRuns` lists for it. The
1706
+ * run id travels as one path segment, so a `/`, `?` or `#` in it can never
1707
+ * reach the listing or the query.
1614
1708
  */
1615
- async getWorkflowUsage(appId, params) {
1616
- return this.get(`/admin/api/apps/${appId}/workflows/usage`, params);
1709
+ async getTestRun(appId, blockType, blockId, runId) {
1710
+ return this.get(`/admin/api/apps/${appId}/blocks/${blockType}/${blockId}/runs/${encodeURIComponent(runId)}`);
1617
1711
  }
1618
- async createWorkflow(appId, payload) {
1619
- return this.post(`/admin/api/apps/${appId}/workflows`, payload);
1620
- }
1621
- async updateWorkflow(appId, workflowId, payload, expectedModifiedAt) {
1622
- const body = expectedModifiedAt ? { ...payload, expectedModifiedAt } : payload;
1623
- return this.patch(`/admin/api/apps/${appId}/workflows/${workflowId}`, body);
1712
+ // ============================================
1713
+ // ANALYTICS
1714
+ // ============================================
1715
+ async getAnalyticsTopUsers(appId, params) {
1716
+ return this.get(`/app/${appId}/api/analytics/users/top`, params);
1624
1717
  }
1625
- /**
1626
- * Retire a workflow, or destroy it (#2887).
1627
- *
1628
- * The plain call ARCHIVES: the definition row stays, so its runs, revisions
1629
- * and test cases keep resolving. `{ hard: true }` performs the full cascade
1630
- * and is what releases the `workflowKey` — the flag `config push --prune`
1631
- * sends, for the same reason it sends it for webhooks and integrations.
1632
- */
1633
- async deleteWorkflow(appId, workflowId, options) {
1634
- const path = `/admin/api/apps/${appId}/workflows/${workflowId}`;
1635
- return this.delete(options?.hard ? `${path}?hard=true` : path);
1718
+ async getAnalyticsIntegrationMetrics(appId, params) {
1719
+ return this.get(`/app/${appId}/api/analytics/integrations`, params);
1636
1720
  }
1637
- /**
1638
- * #2645 criterion 9 — the operational toggle. Deliberately NOT the config
1639
- * PATCH: `config push` owns every configuration field, and taking a workflow
1640
- * out of service must not touch one, or an operator's action would show up as
1641
- * drift against the repo. Same route shape as `cron-triggers pause|resume`.
1642
- */
1643
- async disableWorkflow(appId, workflowId) {
1644
- return this.post(`/app/${appId}/api/workflows/${workflowId}/disable`, {});
1721
+ async getAnalyticsOverviewDau(appId, params) {
1722
+ return this.get(`/app/${appId}/api/analytics/overview/dau`, params);
1645
1723
  }
1646
- async enableWorkflow(appId, workflowId) {
1647
- return this.post(`/app/${appId}/api/workflows/${workflowId}/enable`, {});
1724
+ async getAnalyticsOverviewWau(appId, params) {
1725
+ return this.get(`/app/${appId}/api/analytics/overview/wau`, params);
1648
1726
  }
1649
- async updateWorkflowDraft(appId, workflowId, payload) {
1650
- return this.put(`/admin/api/apps/${appId}/workflows/${workflowId}/draft`, payload);
1727
+ async getAnalyticsOverviewMau(appId, params) {
1728
+ return this.get(`/app/${appId}/api/analytics/overview/mau`, params);
1651
1729
  }
1652
- async previewWorkflow(appId, workflowId, payload) {
1653
- return this.post(`/admin/api/apps/${appId}/workflows/${workflowId}/preview`, payload);
1730
+ async getAnalyticsOverviewGrowth(appId, params) {
1731
+ return this.get(`/app/${appId}/api/analytics/overview/growth`, params);
1654
1732
  }
1655
- async getPreviewStatus(appId, workflowId, instanceId) {
1656
- return this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/preview/${instanceId}/status`);
1733
+ async getAnalyticsDailyActive(appId, params) {
1734
+ return this.get(`/app/${appId}/api/analytics/daily-active`, params);
1657
1735
  }
1658
- async listWorkflowRuns(appId, workflowId, params) {
1659
- const result = await this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/runs`, params);
1660
- const nextCursor = result?.nextCursor ?? null;
1661
- return {
1662
- items: result?.items ?? [],
1663
- hasMore: result?.hasMore,
1664
- nextCursor,
1665
- resumeAfter: result?.resumeAfter,
1666
- scanned: typeof result?.scanned === "number" ? result.scanned : undefined,
1667
- };
1736
+ async getAnalyticsRollingActive(appId, params) {
1737
+ return this.get(`/app/${appId}/api/analytics/rolling-active`, params);
1668
1738
  }
1669
- /**
1670
- * Workflow runs started by one app user, across every workflow (#1967).
1671
- * Backed by `GET /admin/api/apps/{appId}/users/{userId}/workflow-runs`,
1672
- * which resolves the app user before querying the `runsByUser` index.
1673
- */
1674
- async listUserWorkflowRuns(appId, userId, params) {
1675
- const result = await this.get(`/admin/api/apps/${appId}/users/${encodeURIComponent(userId)}/workflow-runs`, params);
1676
- const nextCursor = result?.nextCursor ?? null;
1677
- return {
1678
- items: result?.items ?? [],
1679
- hasMore: result?.hasMore,
1680
- nextCursor,
1681
- scanned: typeof result?.scanned === "number" ? result.scanned : undefined,
1682
- };
1739
+ async getAnalyticsCohortRetention(appId, params) {
1740
+ return this.get(`/app/${appId}/api/analytics/cohort-retention`, params);
1683
1741
  }
1684
- async getWorkflowRunStatus(appId, workflowId, runId) {
1685
- return this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/runs/${runId}/status`);
1742
+ async getAnalyticsUserSearch(appId, params) {
1743
+ return this.get(`/app/${appId}/api/analytics/users/search`, params);
1686
1744
  }
1687
- async getWorkflowStepRuns(appId, workflowId, runId) {
1688
- const result = await this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/runs/${runId}/steps`);
1689
- return { items: result?.items ?? [] };
1745
+ async getAnalyticsUserDetail(appId, userUlid, params) {
1746
+ return this.get(`/app/${appId}/api/analytics/users/${userUlid}/detail`, params);
1690
1747
  }
1691
- // Workflow analytics have one client path, `getAnalyticsTopWorkflows`
1692
- // (issue #2766): `getTopWorkflows` was a second name for the same endpoint,
1693
- // and `getWorkflowAnalytics` called a route the server never registered.
1694
- // ============================================
1695
- // WORKFLOW CONFIGURATIONS
1696
- // ============================================
1697
- async listWorkflowConfigs(appId, workflowId) {
1698
- const result = await this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/configs`);
1699
- return { items: result?.items ?? [] };
1748
+ async getAnalyticsUserSnapshot(appId, userUlid, params) {
1749
+ return this.get(`/app/${appId}/api/analytics/users/${userUlid}/snapshot`, params);
1700
1750
  }
1701
- async getWorkflowConfig(appId, workflowId, configId) {
1702
- return this.get(`/admin/api/apps/${appId}/workflows/${workflowId}/configs/${configId}`);
1751
+ /**
1752
+ * #5251 — `path` with `params` set as `get` sets them, then one appended
1753
+ * `filter[<field>][<operator>]` entry per filter, in order. `get`'s record
1754
+ * cannot hold two entries under one key; the server ANDs them all.
1755
+ */
1756
+ analyticsFilteredGet(path, params, filters) {
1757
+ if (!filters || filters.length === 0)
1758
+ return this.get(path, params);
1759
+ const query = new URLSearchParams();
1760
+ for (const [key, value] of Object.entries(params ?? {})) {
1761
+ if (value !== undefined && value !== null) {
1762
+ query.set(key, String(value));
1763
+ }
1764
+ }
1765
+ for (const filter of filters) {
1766
+ query.append(`filter[${filter.field}][${filter.operator}]`, filter.value);
1767
+ }
1768
+ return this.get(`${path}?${query.toString()}`);
1769
+ }
1770
+ async getAnalyticsEvents(appId, params, filters) {
1771
+ return this.analyticsFilteredGet(`/app/${appId}/api/analytics/events`, params, filters);
1703
1772
  }
1704
- async createWorkflowConfig(appId, workflowId, payload) {
1705
- return this.post(`/admin/api/apps/${appId}/workflows/${workflowId}/configs`, payload);
1773
+ async getAnalyticsEventsGrouped(appId, params, filters) {
1774
+ return this.analyticsFilteredGet(`/app/${appId}/api/analytics/events/grouped`, params, filters);
1706
1775
  }
1707
- async updateWorkflowConfig(appId, workflowId, configId, payload) {
1708
- return this.patch(`/admin/api/apps/${appId}/workflows/${workflowId}/configs/${configId}`, payload);
1776
+ async getAnalyticsErrorsGroups(appId, params, filters) {
1777
+ return this.analyticsFilteredGet(`/app/${appId}/api/analytics/errors/groups`, params, filters);
1709
1778
  }
1710
- async archiveWorkflowConfig(appId, workflowId, configId) {
1711
- return this.delete(`/admin/api/apps/${appId}/workflows/${workflowId}/configs/${configId}`);
1779
+ /** The app's db3 query shapes that read the most rows (#5244). */
1780
+ async getAnalyticsDb3Queries(appId, params) {
1781
+ return this.get(`/app/${appId}/api/analytics/db3/queries`, params);
1712
1782
  }
1713
- async activateWorkflowConfig(appId, workflowId, configId) {
1714
- return this.post(`/admin/api/apps/${appId}/workflows/${workflowId}/configs/${configId}/activate`, {});
1783
+ /** The app's request wall time and DynamoDB round trips per endpoint and function (#5244). */
1784
+ async getAnalyticsRequests(appId, params) {
1785
+ return this.get(`/app/${appId}/api/analytics/requests`, params);
1715
1786
  }
1716
- async duplicateWorkflowConfig(appId, workflowId, configId, payload) {
1717
- return this.post(`/admin/api/apps/${appId}/workflows/${workflowId}/configs/${configId}/duplicate`, payload || {});
1787
+ async getAnalyticsTopPrompts(appId, params) {
1788
+ return this.get(`/app/${appId}/api/analytics/prompts/top`, params);
1718
1789
  }
1719
1790
  // ============================================
1720
- // ANALYTICS
1791
+ // PLATFORM TRANSITIONS (#5821)
1721
1792
  // ============================================
1722
- async getAnalyticsTopUsers(appId, params) {
1723
- return this.get(`/app/${appId}/api/analytics/users/top`, params);
1724
- }
1725
- async getAnalyticsIntegrationMetrics(appId, params) {
1726
- return this.get(`/app/${appId}/api/analytics/integrations`, params);
1727
- }
1728
- async getAnalyticsOverviewDau(appId) {
1729
- return this.get(`/app/${appId}/api/analytics/overview/dau`);
1793
+ /** An app's platform transitions: each one's value and where it came from. */
1794
+ async getAppTransitions(appId) {
1795
+ return this.get(`/admin/api/apps/${encodeURIComponent(appId)}/transitions`);
1730
1796
  }
1731
- async getAnalyticsOverviewWau(appId) {
1732
- return this.get(`/app/${appId}/api/analytics/overview/wau`);
1797
+ /** Set one platform transition on one app, with a reason (super-admin). */
1798
+ async setAppTransition(appId, transition, body) {
1799
+ return this.put(`/super-admin/api/apps/${encodeURIComponent(appId)}/transitions/${encodeURIComponent(transition)}`, body);
1733
1800
  }
1734
- async getAnalyticsOverviewMau(appId) {
1735
- return this.get(`/app/${appId}/api/analytics/overview/mau`);
1801
+ /** One page of an app's transition changes, newest first (super-admin). */
1802
+ async listAppTransitionChanges(appId, params) {
1803
+ return this.get(`/super-admin/api/apps/${encodeURIComponent(appId)}/transitions/changes`, params);
1736
1804
  }
1737
- async getAnalyticsOverviewGrowth(appId, params) {
1738
- return this.get(`/app/${appId}/api/analytics/overview/growth`, params);
1739
- }
1740
- async getAnalyticsDailyActive(appId, params) {
1741
- return this.get(`/app/${appId}/api/analytics/daily-active`, params);
1805
+ /** The registered transitions, with apps per value from one budgeted walk (super-admin). */
1806
+ async listTransitions(params) {
1807
+ return this.get(`/super-admin/api/transitions`, params);
1742
1808
  }
1743
- async getAnalyticsRollingActive(appId, params) {
1744
- return this.get(`/app/${appId}/api/analytics/rolling-active`, params);
1809
+ /** One page of a transition's report: each app's state, use by call site and eligible date (super-admin). */
1810
+ async getTransitionReport(transition, params) {
1811
+ return this.get(`/super-admin/api/transitions/${encodeURIComponent(transition)}/report`, params);
1745
1812
  }
1746
- async getAnalyticsCohortRetention(appId) {
1747
- return this.get(`/app/${appId}/api/analytics/cohort-retention`);
1813
+ /** One page of a transition's move plan: what the daily move step would do with each unit (super-admin, #5824). */
1814
+ async getTransitionMovePlan(transition, params) {
1815
+ return this.get(`/super-admin/api/transitions/${encodeURIComponent(transition)}/move-plan`, params);
1748
1816
  }
1749
- async getAnalyticsUserSearch(appId, params) {
1750
- return this.get(`/app/${appId}/api/analytics/users/search`, params);
1817
+ /** Recent calls to deprecated operations, by app, operation, source and client (super-admin). */
1818
+ async getDeprecatedCalls(params) {
1819
+ return this.get(`/super-admin/api/transitions/deprecated-calls`, params);
1751
1820
  }
1752
- async getAnalyticsUserDetail(appId, userUlid) {
1753
- return this.get(`/app/${appId}/api/analytics/users/${userUlid}/detail`);
1821
+ // ============================================
1822
+ // USAGE (#5713)
1823
+ // ============================================
1824
+ /** An app's usage and estimated cost for `month` (`YYYY-MM`, default the current month). */
1825
+ async getAppUsage(appId, params) {
1826
+ return this.get(`/admin/api/apps/${encodeURIComponent(appId)}/usage`, params);
1754
1827
  }
1755
- async getAnalyticsUserSnapshot(appId, userUlid) {
1756
- return this.get(`/app/${appId}/api/analytics/users/${userUlid}/snapshot`);
1828
+ /** An app's top users over a window, by a meter's quantity or by cost. */
1829
+ async getAppUsageTopUsers(appId, params) {
1830
+ return this.get(`/admin/api/apps/${encodeURIComponent(appId)}/usage/users`, params);
1757
1831
  }
1758
- async getAnalyticsEvents(appId, params) {
1759
- return this.get(`/app/${appId}/api/analytics/events`, params);
1832
+ /** One user's usage over a window and the bytes they own. */
1833
+ async getAppUsageUser(appId, userId, params) {
1834
+ return this.get(`/admin/api/apps/${encodeURIComponent(appId)}/usage/users/${encodeURIComponent(userId)}`, params);
1760
1835
  }
1761
- async getAnalyticsEventsGrouped(appId, params) {
1762
- return this.get(`/app/${appId}/api/analytics/events/grouped`, params);
1836
+ /** An app's system usage over a window, by origin, source, resource and meter. */
1837
+ async getAppUsageSystem(appId, params) {
1838
+ return this.get(`/admin/api/apps/${encodeURIComponent(appId)}/usage/system`, params);
1763
1839
  }
1764
- async getAnalyticsErrorsGroups(appId, params) {
1765
- return this.get(`/app/${appId}/api/analytics/errors/groups`, params);
1840
+ /** The top apps by estimated cost, month to date (super-admin). */
1841
+ async listUsageTopApps(params) {
1842
+ return this.get("/super-admin/api/maintenance/usage/apps", params);
1766
1843
  }
1767
- async getAnalyticsTopWorkflows(appId, params) {
1768
- return this.get(`/app/${appId}/api/analytics/workflows/top`, params);
1844
+ /** The top developers by estimated cost, month to date (super-admin). */
1845
+ async listUsageTopDevelopers(params) {
1846
+ return this.get("/super-admin/api/maintenance/usage/developers", params);
1769
1847
  }
1770
- async getAnalyticsTopPrompts(appId, params) {
1771
- return this.get(`/app/${appId}/api/analytics/prompts/top`, params);
1848
+ /** The usage jobs' state (super-admin). */
1849
+ async getUsageJobs() {
1850
+ return this.get("/super-admin/api/maintenance/usage/jobs");
1772
1851
  }
1773
1852
  // ============================================
1774
1853
  // SUPER ADMIN: ADMINS
@@ -1784,7 +1863,7 @@ export class ApiClient {
1784
1863
  return this.get("/admin/api/me");
1785
1864
  }
1786
1865
  async listAllAdmins(params) {
1787
- const result = await this.get("/admin/api/admins", params);
1866
+ const result = await this.get("/super-admin/api/admins", params);
1788
1867
  const nextCursor = result?.nextCursor ?? null;
1789
1868
  const items = result?.items ?? [];
1790
1869
  return {
@@ -1794,70 +1873,32 @@ export class ApiClient {
1794
1873
  };
1795
1874
  }
1796
1875
  async searchAdminByEmail(email) {
1797
- return this.get("/admin/api/admins/search", { email });
1876
+ return this.get("/super-admin/api/admins/search", { email });
1798
1877
  }
1799
1878
  async getAdminApps(email) {
1800
- return this.get(`/admin/api/admins/${encodeURIComponent(email)}/apps`);
1879
+ return this.get(`/super-admin/api/admins/${encodeURIComponent(email)}/apps`);
1801
1880
  }
1802
1881
  async updateAdminSettings(adminId, data) {
1803
- return this.patch(`/admin/api/admins/${adminId}`, data);
1882
+ return this.patch(`/super-admin/api/admins/${adminId}`, data);
1804
1883
  }
1805
1884
  async reindexAdmin(adminId) {
1806
- return this.post(`/admin/api/admins/${adminId}/reindex`, {});
1885
+ return this.post(`/super-admin/api/admins/${adminId}/reindex`, {});
1886
+ }
1887
+ /** `reindexAdmin` with the route's answer, for callers that print it. */
1888
+ async reindexAdminWithResult(adminId) {
1889
+ return this.post(`/super-admin/api/admins/${adminId}/reindex`, {});
1807
1890
  }
1808
1891
  // Admin Invitations
1809
- async listAllAdminInvitations() {
1810
- const result = await this.get("/admin/api/admins/invitations");
1892
+ /** One address's pending admin invitations; the route requires the address. */
1893
+ async listAllAdminInvitations(email) {
1894
+ const result = await this.get("/super-admin/api/admins/invitations", { email });
1811
1895
  return result?.invitations ?? [];
1812
1896
  }
1813
1897
  async createGlobalAdminInvitation(data) {
1814
- return this.post("/admin/api/admins/invitations", data);
1898
+ return this.post("/super-admin/api/admins/invitations", data);
1815
1899
  }
1816
1900
  async deleteGlobalAdminInvitation(invitationId) {
1817
- return this.delete(`/admin/api/admins/invitations/${invitationId}`);
1818
- }
1819
- // ============================================
1820
- // SUPER ADMIN: CATALOG
1821
- // ============================================
1822
- async listPromptCatalog(params) {
1823
- const result = await this.get("/admin/api/catalog/prompts", params);
1824
- return {
1825
- items: result?.items ?? [],
1826
- hasMore: result?.hasMore,
1827
- nextCursor: result?.nextCursor ?? null,
1828
- };
1829
- }
1830
- async getPromptCatalogItem(catalogId) {
1831
- return this.get(`/admin/api/catalog/prompts/${catalogId}`);
1832
- }
1833
- async createPromptCatalogItem(payload) {
1834
- return this.post("/admin/api/catalog/prompts", payload);
1835
- }
1836
- async updatePromptCatalogItem(catalogId, payload) {
1837
- return this.patch(`/admin/api/catalog/prompts/${catalogId}`, payload);
1838
- }
1839
- async deletePromptCatalogItem(catalogId) {
1840
- return this.delete(`/admin/api/catalog/prompts/${catalogId}`);
1841
- }
1842
- async listIntegrationCatalog(params) {
1843
- const result = await this.get("/admin/api/catalog/integrations", params);
1844
- return {
1845
- items: result?.items ?? [],
1846
- hasMore: result?.hasMore,
1847
- nextCursor: result?.nextCursor ?? null,
1848
- };
1849
- }
1850
- async getIntegrationCatalogItem(catalogId) {
1851
- return this.get(`/admin/api/catalog/integrations/${catalogId}`);
1852
- }
1853
- async createIntegrationCatalogItem(payload) {
1854
- return this.post("/admin/api/catalog/integrations", payload);
1855
- }
1856
- async updateIntegrationCatalogItem(catalogId, payload) {
1857
- return this.patch(`/admin/api/catalog/integrations/${catalogId}`, payload);
1858
- }
1859
- async deleteIntegrationCatalogItem(catalogId) {
1860
- return this.delete(`/admin/api/catalog/integrations/${catalogId}`);
1901
+ return this.delete(`/super-admin/api/admins/invitations/${invitationId}`);
1861
1902
  }
1862
1903
  // ============================================
1863
1904
  // BATCH TEST EXECUTION
@@ -1904,6 +1945,15 @@ export class ApiClient {
1904
1945
  async testEmailTemplate(appId, emailType, payload) {
1905
1946
  return this.post(`/admin/api/apps/${appId}/email-templates/${emailType}/test`, payload || {});
1906
1947
  }
1948
+ /**
1949
+ * Render the saved template (or the built-in default) for an email type
1950
+ * without sending it. `variables` override the type's sample values. The
1951
+ * app id and the type are each encoded as one path segment, so no value of
1952
+ * either can select another route.
1953
+ */
1954
+ async previewEmailTemplate(appId, emailType, payload) {
1955
+ return this.post(`/admin/api/apps/${encodeURIComponent(appId)}/email-templates/${encodeURIComponent(emailType)}/preview`, payload || {});
1956
+ }
1907
1957
  // ============================================
1908
1958
  // ACCESS TOKENS
1909
1959
  // ============================================
@@ -2115,13 +2165,18 @@ export class ApiClient {
2115
2165
  const query = options?.dryRun ? "?dryRun=true" : "";
2116
2166
  return this.post(`/app/${appId}/api/databases/types${query}`, data);
2117
2167
  }
2118
- async updateDatabaseTypeConfig(appId, databaseType, data, expectedModifiedAt, options) {
2168
+ async updateDatabaseTypeConfig(appId, databaseType, data, expectedModifiedAt,
2169
+ // #6019: `allowFieldRemoval` asks for the append-only override, which the
2170
+ // server takes only on an app whose stored settings enable it.
2171
+ options) {
2119
2172
  const body = expectedModifiedAt ? { ...data, expectedModifiedAt } : data;
2120
2173
  const qs = new URLSearchParams();
2121
2174
  if (options?.dryRun)
2122
2175
  qs.set("dryRun", "true");
2123
2176
  if (options?.acceptWarnings)
2124
2177
  qs.set("acceptWarnings", "true");
2178
+ if (options?.allowFieldRemoval)
2179
+ qs.set("allowFieldRemoval", "true");
2125
2180
  const query = qs.toString();
2126
2181
  const path = `/app/${appId}/api/databases/types/${encodeURIComponent(databaseType)}${query ? `?${query}` : ""}`;
2127
2182
  return this.patch(path, body);
@@ -2150,31 +2205,55 @@ export class ApiClient {
2150
2205
  hasMore: result?.hasMore ?? nextCursor != null,
2151
2206
  };
2152
2207
  }
2208
+ /** One page of one custodian's groups (`app` or `user:<userId>`), through the admin API. */
2209
+ async listGroupsByCustodian(appId, custodian, params) {
2210
+ const result = await this.get(`/admin/api/apps/${appId}/groups`, { custodian, ...(params ?? {}) });
2211
+ const nextCursor = result?.nextCursor;
2212
+ return {
2213
+ items: result?.items ?? [],
2214
+ nextCursor,
2215
+ hasMore: result?.hasMore ?? nextCursor != null,
2216
+ };
2217
+ }
2218
+ /** Transfer a group to `to` (`app` or `user:<userId>`) through the admin API. */
2219
+ async transferGroup(appId, groupId, to) {
2220
+ return this.post(`/admin/api/apps/${appId}/groups/${encodeURIComponent(groupId)}/transfer`, { to });
2221
+ }
2222
+ /**
2223
+ * Create a group through the admin API; `custodian` is `app` or
2224
+ * `user:<userId>`. The server mints the group's id and answers it as
2225
+ * `groupId`.
2226
+ */
2153
2227
  async createGroup(appId, data) {
2154
- return this.post(`/app/${appId}/api/groups`, data);
2228
+ return this.post(`/admin/api/apps/${appId}/groups`, data);
2155
2229
  }
2156
- async getGroup(appId, groupType, groupId) {
2157
- return this.get(`/app/${appId}/api/groups/${groupType}/${groupId}`);
2230
+ /**
2231
+ * A group by id. `groupType` looks a group written before groups were
2232
+ * addressed by id up by its type first (the routes' deprecated
2233
+ * `?groupType=`), as an exported collection's grants still name them.
2234
+ */
2235
+ async getGroup(appId, groupId, options) {
2236
+ return this.get(`/app/${appId}/api/groups/${encodeURIComponent(groupId)}`, options?.groupType ? { groupType: options.groupType } : undefined);
2158
2237
  }
2159
- async updateGroup(appId, groupType, groupId, data) {
2160
- return this.patch(`/app/${appId}/api/groups/${groupType}/${groupId}`, data);
2238
+ async updateGroup(appId, groupId, data) {
2239
+ return this.patch(`/app/${appId}/api/groups/${encodeURIComponent(groupId)}`, data);
2161
2240
  }
2162
- async deleteGroup(appId, groupType, groupId) {
2163
- return this.delete(`/app/${appId}/api/groups/${groupType}/${groupId}`);
2241
+ async deleteGroup(appId, groupId) {
2242
+ return this.delete(`/app/${appId}/api/groups/${encodeURIComponent(groupId)}`);
2164
2243
  }
2165
2244
  // ============================================
2166
2245
  // GROUP MEMBERS
2167
2246
  // ============================================
2168
2247
  /**
2169
- * One page of a group's members.
2248
+ * One page of a group's members, with their roles.
2170
2249
  *
2171
2250
  * The route paginates cursor-style (no default limit, cap 200) and reports
2172
2251
  * the boundary, so `groups members list` carries `--limit`/`--cursor` and
2173
2252
  * forwards them (#3646) rather than printing a first page that claims to be
2174
2253
  * the whole membership.
2175
2254
  */
2176
- async listGroupMembers(appId, groupType, groupId, options) {
2177
- const result = await this.get(`/app/${appId}/api/groups/${groupType}/${groupId}/members`, {
2255
+ async listGroupMembers(appId, groupId, options) {
2256
+ const result = await this.get(`/app/${appId}/api/groups/${encodeURIComponent(groupId)}/members`, {
2178
2257
  ...(options?.include ? { include: options.include } : {}),
2179
2258
  ...(options?.limit !== undefined ? { limit: options.limit } : {}),
2180
2259
  ...(options?.cursor ? { cursor: options.cursor } : {}),
@@ -2186,17 +2265,23 @@ export class ApiClient {
2186
2265
  hasMore: result?.hasMore ?? nextCursor != null,
2187
2266
  };
2188
2267
  }
2189
- async addGroupMember(appId, groupType, groupId, data) {
2190
- return this.post(`/app/${appId}/api/groups/${groupType}/${groupId}/members`, data);
2268
+ /** Add a member through the admin API; `role: "owner"` restores the custodian's owner row. */
2269
+ async addGroupMember(appId, groupId, data) {
2270
+ return this.post(`/admin/api/apps/${appId}/groups/${encodeURIComponent(groupId)}/members`, data);
2271
+ }
2272
+ /** Change a member's role through the admin API, the owner row's included. */
2273
+ async setGroupMemberRole(appId, groupId, userId, role) {
2274
+ return this.patch(`/admin/api/apps/${appId}/groups/${encodeURIComponent(groupId)}/members/${encodeURIComponent(userId)}`, { role });
2191
2275
  }
2192
- async removeGroupMember(appId, groupType, groupId, userId) {
2193
- return this.delete(`/app/${appId}/api/groups/${groupType}/${groupId}/members/${userId}`);
2276
+ /** Remove a member through the admin API, the owner row included. */
2277
+ async removeGroupMember(appId, groupId, userId) {
2278
+ return this.delete(`/admin/api/apps/${appId}/groups/${encodeURIComponent(groupId)}/members/${encodeURIComponent(userId)}`);
2194
2279
  }
2195
2280
  // ============================================
2196
2281
  // GROUP RESOURCE LISTINGS
2197
2282
  // ============================================
2198
- async listGroupDocuments(appId, groupType, groupId) {
2199
- return this.get(`/app/${appId}/api/groups/${groupType}/${groupId}/documents`);
2283
+ async listGroupDocuments(appId, groupId) {
2284
+ return this.get(`/app/${appId}/api/groups/${encodeURIComponent(groupId)}/documents`);
2200
2285
  }
2201
2286
  // ============================================
2202
2287
  // USER MEMBERSHIPS
@@ -2250,6 +2335,33 @@ export class ApiClient {
2250
2335
  async createCollection(appId, data) {
2251
2336
  return this.post(`/app/${appId}/api/collections`, data);
2252
2337
  }
2338
+ /** One page of one custodian's collections (`app` or `user:<userId>`), through the admin API. */
2339
+ async listCollectionsByCustodian(appId, custodian, params) {
2340
+ const query = { custodian };
2341
+ if (params?.limit !== undefined)
2342
+ query.limit = params.limit;
2343
+ if (params?.cursor)
2344
+ query.cursor = params.cursor;
2345
+ const result = await this.get(`/admin/api/apps/${appId}/collections`, query);
2346
+ const nextCursor = result?.nextCursor;
2347
+ return {
2348
+ items: result?.items ?? [],
2349
+ nextCursor,
2350
+ hasMore: result?.hasMore ?? nextCursor != null,
2351
+ };
2352
+ }
2353
+ /** Transfer a collection to `to` (`app` or `user:<userId>`) through the admin API. */
2354
+ async transferCollection(appId, collectionId, to) {
2355
+ return this.post(`/admin/api/apps/${appId}/collections/${encodeURIComponent(collectionId)}/transfer`, { to });
2356
+ }
2357
+ /**
2358
+ * Create a collection through the admin API, for `custodian` (`app` or
2359
+ * `user:<userId>`; a user custodian holds the owner row). Spends no
2360
+ * create budget.
2361
+ */
2362
+ async createCollectionAsAdmin(appId, data) {
2363
+ return this.post(`/admin/api/apps/${appId}/collections`, data);
2364
+ }
2253
2365
  async getCollection(appId, collectionId) {
2254
2366
  return this.get(`/app/${appId}/api/collections/${collectionId}`);
2255
2367
  }
@@ -2296,41 +2408,30 @@ export class ApiClient {
2296
2408
  };
2297
2409
  }
2298
2410
  // ============================================
2299
- // COLLECTION ACCESS (GROUPS + MEMBERS)
2411
+ // COLLECTION MEMBERS (USERS + GROUPS)
2300
2412
  // ============================================
2301
- async getCollectionAccess(appId, collectionId) {
2302
- return this.get(`/app/${appId}/api/collections/${collectionId}/access`);
2303
- }
2304
- async grantCollectionGroupPermission(appId, collectionId, data) {
2305
- return this.post(`/app/${appId}/api/collections/${collectionId}/group-permissions`, data);
2306
- }
2307
- async revokeCollectionGroupPermission(appId, collectionId, groupType, groupId) {
2308
- return this.delete(`/app/${appId}/api/collections/${collectionId}/group-permissions/${groupType}/${groupId}`);
2413
+ /**
2414
+ * Every member of a collection, users and groups as principals with their
2415
+ * roles, in one answer.
2416
+ */
2417
+ async listCollectionMembers(appId, collectionId) {
2418
+ const result = await this.get(`/app/${appId}/api/collections/${encodeURIComponent(collectionId)}/members`);
2419
+ return { items: result?.items ?? [], hasMore: Boolean(result?.hasMore) };
2309
2420
  }
2421
+ /**
2422
+ * Add a user or a group to a collection through the admin API, with a role;
2423
+ * `role: "owner"` restores the custodian's owner row.
2424
+ */
2310
2425
  async addCollectionMember(appId, collectionId, data) {
2311
- return this.post(`/app/${appId}/api/collections/${collectionId}/members`, data);
2312
- }
2313
- async removeCollectionMember(appId, collectionId, userId) {
2314
- return this.delete(`/app/${appId}/api/collections/${collectionId}/members/${userId}`);
2315
- }
2316
- // ============================================
2317
- // COLLECTION TYPE CONFIGS
2318
- // ============================================
2319
- async listCollectionTypeConfigs(appId) {
2320
- return this.get(`/app/${appId}/api/collection-type-configs`);
2321
- }
2322
- async getCollectionTypeConfig(appId, collectionType) {
2323
- return this.get(`/app/${appId}/api/collection-type-configs/${collectionType}`);
2426
+ return this.post(`/admin/api/apps/${appId}/collections/${encodeURIComponent(collectionId)}/members`, data);
2324
2427
  }
2325
- async createCollectionTypeConfig(appId, data) {
2326
- return this.post(`/app/${appId}/api/collection-type-configs`, data);
2327
- }
2328
- async updateCollectionTypeConfig(appId, collectionType, data, expectedModifiedAt) {
2329
- const body = expectedModifiedAt ? { ...data, expectedModifiedAt } : data;
2330
- return this.patch(`/app/${appId}/api/collection-type-configs/${collectionType}`, body);
2428
+ /** Change a member's role through the admin API, the owner row's included. */
2429
+ async setCollectionMemberRole(appId, collectionId, principal, role) {
2430
+ return this.patch(`/admin/api/apps/${appId}/collections/${encodeURIComponent(collectionId)}/members/${encodeURIComponent(principal)}`, { role });
2331
2431
  }
2332
- async deleteCollectionTypeConfig(appId, collectionType) {
2333
- return this.delete(`/app/${appId}/api/collection-type-configs/${collectionType}`);
2432
+ /** Remove a user or `group:<groupId>` through the admin API, the owner row included. */
2433
+ async removeCollectionMember(appId, collectionId, principal) {
2434
+ return this.delete(`/admin/api/apps/${appId}/collections/${encodeURIComponent(collectionId)}/members/${encodeURIComponent(principal)}`);
2334
2435
  }
2335
2436
  // ============================================
2336
2437
  // METADATA CATEGORY CONFIGS (issue #1304, P-B)
@@ -2401,25 +2502,6 @@ export class ApiClient {
2401
2502
  return this.post(`/app/${appId}/api/rule-sets/debug`, data);
2402
2503
  }
2403
2504
  // ============================================
2404
- // GROUP TYPE CONFIGS
2405
- // ============================================
2406
- async listGroupTypeConfigs(appId) {
2407
- return this.get(`/app/${appId}/api/group-type-configs`);
2408
- }
2409
- async getGroupTypeConfig(appId, groupType) {
2410
- return this.get(`/app/${appId}/api/group-type-configs/${groupType}`);
2411
- }
2412
- async createGroupTypeConfig(appId, data) {
2413
- return this.post(`/app/${appId}/api/group-type-configs`, data);
2414
- }
2415
- async updateGroupTypeConfig(appId, groupType, data, expectedModifiedAt) {
2416
- const body = expectedModifiedAt ? { ...data, expectedModifiedAt } : data;
2417
- return this.patch(`/app/${appId}/api/group-type-configs/${groupType}`, body);
2418
- }
2419
- async deleteGroupTypeConfig(appId, groupType) {
2420
- return this.delete(`/app/${appId}/api/group-type-configs/${groupType}`);
2421
- }
2422
- // ============================================
2423
2505
  // DOCUMENT EXPORT / IMPORT
2424
2506
  // ============================================
2425
2507
  async exportDocumentState(appId, documentId) {
@@ -2504,6 +2586,8 @@ export class ApiClient {
2504
2586
  query.filter = JSON.stringify(queryOptions.filter);
2505
2587
  if (queryOptions?.sort !== undefined)
2506
2588
  query.sort = JSON.stringify(queryOptions.sort);
2589
+ if (queryOptions?.include !== undefined)
2590
+ query.include = JSON.stringify(queryOptions.include);
2507
2591
  if (queryOptions?.documentFormat !== undefined) {
2508
2592
  query.documentFormat = queryOptions.documentFormat;
2509
2593
  }
@@ -2532,13 +2616,14 @@ export class ApiClient {
2532
2616
  /**
2533
2617
  * Aggregate records in a document model (issue #2437) — the documents twin
2534
2618
  * of {@link aggregateDatabaseRecords}. `POST documents/:id/records/:model/aggregate`
2535
- * with `{ options: { operations, groupBy?, filter? } }`, answering `{ result }`
2536
- * in the same shape as the database endpoint.
2619
+ * with `{ options: { operations, groupBy?, filter?, sort?, limit? } }`,
2620
+ * answering `{ result }` in the same shape as the database endpoint.
2537
2621
  *
2538
2622
  * `groupBy` takes plain field names and period levels `{ field, period }`
2539
- * (keyed `<field>_<period>` in a row's `group`): StringSet facet grouping
2540
- * and `{ field, contains }` membership grouping are database-only, which is
2541
- * why this signature is narrower than the databases one.
2623
+ * (keyed `<field>_<period>` in a row's `group`). On a db3 (a format-3
2624
+ * document) a StringSet field name is a facet, `{ field, contains }` a
2625
+ * membership, and `sort` and `limit` order and bound the groups; a format-1
2626
+ * document refuses those four with a 400.
2542
2627
  */
2543
2628
  async aggregateDocumentRecords(appId, documentId, modelName, options, extra) {
2544
2629
  return this.post(`/app/${appId}/api/documents/${documentId}/records/${encodeURIComponent(modelName)}/aggregate` +
@@ -2618,6 +2703,10 @@ export class ApiClient {
2618
2703
  * would name one the body does not use.
2619
2704
  */
2620
2705
  async uploadDocumentIngestChunk(appId, documentId, sessionId, chunk) {
2706
+ return this.uploadIngestChunkAt(`/app/${appId}/api/documents/${documentId}`, sessionId, chunk);
2707
+ }
2708
+ /** A chunk upload to `<base>/ingest/<session>/chunks`: the documents route or its db3 mount. */
2709
+ async uploadIngestChunkAt(base, sessionId, chunk) {
2621
2710
  const credentials = await this.ensureAuthenticated();
2622
2711
  const form = new FormData();
2623
2712
  form.set("model", chunk.model);
@@ -2629,8 +2718,7 @@ export class ApiClient {
2629
2718
  form.set("firstId", chunk.firstId);
2630
2719
  form.set("lastId", chunk.lastId);
2631
2720
  form.set("chunk", new Blob([chunk.body]), `${chunk.index}.ndjson.gz`);
2632
- const url = `${credentials.serverUrl}/app/${appId}/api/documents/${documentId}` +
2633
- `/ingest/${encodeURIComponent(sessionId)}/chunks`;
2721
+ const url = `${credentials.serverUrl}${base}/ingest/${encodeURIComponent(sessionId)}/chunks`;
2634
2722
  const response = await this.fetchWithStepUp(url, url, credentials.accessToken, (bearer) => {
2635
2723
  const headers = {
2636
2724
  Authorization: `Bearer ${bearer}`,
@@ -2706,14 +2794,339 @@ export class ApiClient {
2706
2794
  }
2707
2795
  /**
2708
2796
  * Apply an ordered multi-model create/patch/delete blob atomically (issue
2709
- * #1964 Phase 4, wrapping the #1517 `bulkUpdate` facade). All-or-nothing:
2710
- * a validation failure commits nothing. Returns the facade's
2711
- * `{ applied, added, updated, deleted }`.
2797
+ * #1964 Phase 4, wrapping the #1517 `bulkUpdate` facade): `POST
2798
+ * records/batch`, at most 100 operations. All-or-nothing: a validation
2799
+ * failure commits nothing. Returns the facade's `{ applied, added,
2800
+ * updated, deleted }`, and on a db3 `reads` when the batch carried reads.
2712
2801
  */
2713
- async bulkDocumentRecords(appId, documentId, operations, extra) {
2714
- return this.post(`/app/${appId}/api/documents/${documentId}/records/bulk` +
2802
+ async batchDocumentRecords(appId, documentId, operations, extra) {
2803
+ return this.post(`/app/${appId}/api/documents/${documentId}/records/batch` +
2715
2804
  this.documentFormatQuery(extra?.documentFormat), { operations });
2716
2805
  }
2806
+ // ============================================
2807
+ // DB3 (format-3 documents)
2808
+ // ============================================
2809
+ /** `/app/<app>/api/db3/<id>`, the id encoded: every `db3.*` route's prefix. */
2810
+ db3Path(appId, db3Id) {
2811
+ return `/app/${appId}/api/db3/${encodeURIComponent(db3Id)}`;
2812
+ }
2813
+ /** `GET db3/:id/indexes` → `{ indexes }`, sorted by name. */
2814
+ async listDb3Indexes(appId, db3Id) {
2815
+ return this.get(`${this.db3Path(appId, db3Id)}/indexes`);
2816
+ }
2817
+ /**
2818
+ * `POST db3/:id/indexes` with `{ model, field | fields, unique?, name? }`,
2819
+ * `{ model, field, members: true }` for a member index, or `{ model, field
2820
+ * | fields, kind: "text", on, text? }` for a text index → `{ index }`. The
2821
+ * route applies the registration rules.
2822
+ */
2823
+ async registerDb3Index(appId, db3Id, body) {
2824
+ return this.post(`${this.db3Path(appId, db3Id)}/indexes`, body);
2825
+ }
2826
+ /** `DELETE db3/:id/indexes/:name` → `{ ok, name }`. */
2827
+ async dropDb3Index(appId, db3Id, name) {
2828
+ return this.delete(`${this.db3Path(appId, db3Id)}/indexes/${encodeURIComponent(name)}`);
2829
+ }
2830
+ /**
2831
+ * `GET db3/:id/indexes/:name/model` (#5229): a vector index's shared model,
2832
+ * its bytes as uploaded and the `X-Index-Model-*` headers it was uploaded
2833
+ * with.
2834
+ */
2835
+ async fetchDb3IndexModel(appId, db3Id, name) {
2836
+ const credentials = await this.ensureAuthenticated();
2837
+ const url = `${credentials.serverUrl}${this.db3Path(appId, db3Id)}/indexes/${encodeURIComponent(name)}/model`;
2838
+ const headers = { Authorization: `Bearer ${credentials.accessToken}` };
2839
+ if (credentials.globalAdminAppId)
2840
+ headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
2841
+ const response = await fetchWithTLS(url, { method: "GET", headers });
2842
+ if (!response.ok) {
2843
+ const text = await response.text();
2844
+ const parsed = parseErrorResponse(response, text, url);
2845
+ throw new ApiError(parsed.message, response.status, parsed.code, parsed.details);
2846
+ }
2847
+ const header = (key) => response.headers.get(`X-Index-Model-${key}`) ?? "";
2848
+ return {
2849
+ data: Buffer.from(await response.arrayBuffer()),
2850
+ generation: Number(header("Generation")),
2851
+ revision: Number(header("Revision")),
2852
+ rows: Number(header("Rows")),
2853
+ trainedAt: header("Trained-At"),
2854
+ format: header("Format"),
2855
+ };
2856
+ }
2857
+ /**
2858
+ * `DELETE db3/:id/indexes/:name/model` (#5229) → `{ ok, name, revision }`:
2859
+ * the model (or an upload under way) gone, `revision` the index's new one.
2860
+ */
2861
+ async deleteDb3IndexModel(appId, db3Id, name) {
2862
+ return this.delete(`${this.db3Path(appId, db3Id)}/indexes/${encodeURIComponent(name)}/model`);
2863
+ }
2864
+ /** The db3 mount of {@link queryDocumentRecords}: `GET db3/:id/records/:model`. */
2865
+ async queryDb3Records(appId, db3Id, modelName, queryOptions) {
2866
+ const query = {};
2867
+ if (queryOptions?.filter)
2868
+ query.filter = JSON.stringify(queryOptions.filter);
2869
+ if (queryOptions?.sort !== undefined)
2870
+ query.sort = JSON.stringify(queryOptions.sort);
2871
+ if (queryOptions?.include !== undefined)
2872
+ query.include = JSON.stringify(queryOptions.include);
2873
+ if (queryOptions?.limit !== undefined)
2874
+ query.limit = queryOptions.limit;
2875
+ if (queryOptions?.cursor)
2876
+ query.cursor = queryOptions.cursor;
2877
+ const raw = await this.get(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}`, query);
2878
+ return normalizeCliListEnvelope(raw);
2879
+ }
2880
+ /** The db3 mount of {@link countDocumentRecords}: `GET db3/:id/records/:model/count`. */
2881
+ async countDb3Records(appId, db3Id, modelName, queryOptions) {
2882
+ const query = {};
2883
+ if (queryOptions?.filter)
2884
+ query.filter = JSON.stringify(queryOptions.filter);
2885
+ return this.get(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}/count`, query);
2886
+ }
2887
+ /** The db3 mount of {@link aggregateDocumentRecords}: `POST db3/:id/records/:model/aggregate`. */
2888
+ async aggregateDb3Records(appId, db3Id, modelName, options) {
2889
+ return this.post(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}/aggregate`, { options });
2890
+ }
2891
+ /**
2892
+ * `POST db3/:id/records/:model/explain` (#5240): run a query, count or
2893
+ * aggregate on the server, forced onto `index` (or off indexes, `"none"`)
2894
+ * when given, and answer how it read.
2895
+ */
2896
+ async explainDb3Read(appId, db3Id, modelName, body) {
2897
+ return this.post(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}/explain`, body);
2898
+ }
2899
+ /** The db3 mount of {@link saveDocumentRecord}: `POST db3/:id/records/:model`. */
2900
+ async saveDb3Record(appId, db3Id, modelName, body) {
2901
+ return this.post(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}`, body);
2902
+ }
2903
+ /** The db3 mount of {@link patchDocumentRecord}: `PATCH db3/:id/records/:model/:recordId`. */
2904
+ async patchDb3Record(appId, db3Id, modelName, recordId, body) {
2905
+ return this.patch(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}/${encodeURIComponent(recordId)}`, body);
2906
+ }
2907
+ /** The db3 mount of {@link deleteDocumentRecord}: `DELETE db3/:id/records/:model/:recordId`. */
2908
+ async deleteDb3Record(appId, db3Id, modelName, recordId) {
2909
+ return this.delete(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}/${encodeURIComponent(recordId)}`);
2910
+ }
2911
+ /** The db3 mount of {@link batchDocumentRecords}: `POST db3/:id/records/batch`. */
2912
+ async batchDb3Records(appId, db3Id, operations) {
2913
+ return this.post(`${this.db3Path(appId, db3Id)}/records/batch`, { operations });
2914
+ }
2915
+ /**
2916
+ * Several reads of a db3 in one request (#5243): `POST db3/:id/records/batch-read`,
2917
+ * each answered at its index from one state of the db3. `atomic: false`
2918
+ * answers a refused read in its place rather than refusing the request.
2919
+ */
2920
+ async batchReadDb3Records(appId, db3Id, operations, options = {}) {
2921
+ return this.post(`${this.db3Path(appId, db3Id)}/records/batch-read`, {
2922
+ operations,
2923
+ ...(options.atomic === false ? { atomic: false } : {}),
2924
+ });
2925
+ }
2926
+ /** The db3 mount of {@link getDocumentSchema}: `GET db3/:id/schema`. */
2927
+ async getDb3Schema(appId, db3Id) {
2928
+ return this.get(`${this.db3Path(appId, db3Id)}/schema`);
2929
+ }
2930
+ /** `?limit=&cursor=` for a listing. */
2931
+ pageQuery(options = {}) {
2932
+ const params = new URLSearchParams();
2933
+ if (options.limit !== undefined)
2934
+ params.set("limit", String(options.limit));
2935
+ if (options.cursor)
2936
+ params.set("cursor", options.cursor);
2937
+ const query = params.toString();
2938
+ return query ? `?${query}` : "";
2939
+ }
2940
+ /** `GET db3/:id/ingest` (#4889): a db3's bulk-load sessions, newest first. */
2941
+ async listDb3Ingests(appId, db3Id, options = {}) {
2942
+ return this.get(`${this.db3Path(appId, db3Id)}/ingest${this.pageQuery(options)}`);
2943
+ }
2944
+ /** `GET db3/:id/ingest/:sessionId` (#4889). */
2945
+ async getDb3Ingest(appId, db3Id, sessionId) {
2946
+ return this.get(`${this.db3Path(appId, db3Id)}/ingest/${encodeURIComponent(sessionId)}`);
2947
+ }
2948
+ /** `POST db3/:id/ingest` (#4889): open a bulk-load session; `{}` keeps the defaults. */
2949
+ async createDb3Ingest(appId, db3Id, options = {}) {
2950
+ return this.post(`${this.db3Path(appId, db3Id)}/ingest`, options);
2951
+ }
2952
+ /** `POST db3/:id/ingest/:sessionId/chunks` (#4889): one chunk, multipart, as the documents upload sends it. */
2953
+ async uploadDb3IngestChunk(appId, db3Id, sessionId, chunk) {
2954
+ return this.uploadIngestChunkAt(this.db3Path(appId, db3Id), sessionId, chunk);
2955
+ }
2956
+ /** `POST db3/:id/ingest/:sessionId/commit` (#4889). */
2957
+ async commitDb3Ingest(appId, db3Id, sessionId) {
2958
+ return this.post(`${this.db3Path(appId, db3Id)}/ingest/${encodeURIComponent(sessionId)}/commit`, {});
2959
+ }
2960
+ /** `POST db3/:id/ingest/:sessionId/abort` (#4889). */
2961
+ async abortDb3Ingest(appId, db3Id, sessionId) {
2962
+ return this.post(`${this.db3Path(appId, db3Id)}/ingest/${encodeURIComponent(sessionId)}/abort`, {});
2963
+ }
2964
+ /** `GET db3/:id/snapshots` (#4889): a db3's segment exports, newest first. */
2965
+ async listDb3Snapshots(appId, db3Id, options = {}) {
2966
+ return this.get(`${this.db3Path(appId, db3Id)}/snapshots${this.pageQuery(options)}`);
2967
+ }
2968
+ /** `GET db3/:id/snapshots/:segmentId` (#4889). */
2969
+ async getDb3Snapshot(appId, db3Id, segmentId) {
2970
+ return this.get(`${this.db3Path(appId, db3Id)}/snapshots/${encodeURIComponent(segmentId)}`);
2971
+ }
2972
+ /** `POST db3/:id/snapshots` (#4889): start a segment export. */
2973
+ async requestDb3Snapshot(appId, db3Id) {
2974
+ return this.post(`${this.db3Path(appId, db3Id)}/snapshots`, {});
2975
+ }
2976
+ /** `GET db3/:id/export/chain` (#4889): the current segment, signed for download. */
2977
+ async exportDb3Chain(appId, db3Id) {
2978
+ return this.get(`${this.db3Path(appId, db3Id)}/export/chain`);
2979
+ }
2980
+ /** `GET db3/:id/blobs` (#4889): one page of a db3's blobs. */
2981
+ async listDb3Blobs(appId, db3Id, params) {
2982
+ return this.get(`${this.db3Path(appId, db3Id)}/blobs`, params);
2983
+ }
2984
+ /** `GET db3/:id/blobs/:blobId/download` (#4889): a blob's bytes. */
2985
+ async downloadDb3Blob(appId, db3Id, blobId) {
2986
+ return this.downloadBlobAt(this.db3Path(appId, db3Id), blobId);
2987
+ }
2988
+ /** `PUT db3/:id/blobs/:blobId` (#4889): a blob under its own id, as the documents upload sends it. */
2989
+ async uploadDb3Blob(appId, db3Id, blobId, data, meta) {
2990
+ return this.uploadBlobAt(this.db3Path(appId, db3Id), blobId, data, meta);
2991
+ }
2992
+ /** The db3 mount of {@link getDocumentRoom}: `GET db3/:id/room`. App admins only. */
2993
+ async getDb3Room(appId, db3Id, query = {}) {
2994
+ const params = new URLSearchParams();
2995
+ if (query.refused !== undefined)
2996
+ params.set("refused", query.refused);
2997
+ if (query.limit !== undefined)
2998
+ params.set("limit", String(query.limit));
2999
+ if (query.cursor !== undefined)
3000
+ params.set("cursor", query.cursor);
3001
+ const search = params.toString();
3002
+ return this.get(`${this.db3Path(appId, db3Id)}/room${search ? `?${search}` : ""}`);
3003
+ }
3004
+ /**
3005
+ * `POST db3` (#4804): create a db3 and answer it, `{ id, title, createdBy,
3006
+ * createdAt, modifiedAt, custodian, sync, type, tags }`. Without `custodian`
3007
+ * an admin token's create is held by the app. `id` keeps a caller-chosen id
3008
+ * (#4921), refused `DB3_ID_EXISTS` when the app holds it.
3009
+ */
3010
+ async createDb3(appId, body) {
3011
+ return this.post(`/app/${appId}/api/db3`, body);
3012
+ }
3013
+ /** `GET db3/:id` (#4804): the db3, with the caller's grant when it reads it through one. */
3014
+ async getDb3(appId, db3Id) {
3015
+ return this.get(this.db3Path(appId, db3Id));
3016
+ }
3017
+ /**
3018
+ * `PUT db3/:id` (#5890): rename a db3, answered as `getDb3` answers it with
3019
+ * the new title.
3020
+ */
3021
+ async updateDb3(appId, db3Id, body) {
3022
+ return this.put(this.db3Path(appId, db3Id), body);
3023
+ }
3024
+ /** `DELETE db3/:id` (#4804): the documents delete for a db3. */
3025
+ async deleteDb3(appId, db3Id) {
3026
+ return this.delete(this.db3Path(appId, db3Id));
3027
+ }
3028
+ /** The db3 mount of {@link getDocumentStats}: `GET db3/:id/stats`. */
3029
+ async getDb3Stats(appId, db3Id) {
3030
+ return this.get(`${this.db3Path(appId, db3Id)}/stats`);
3031
+ }
3032
+ /**
3033
+ * `POST db3/:id/records/:model/:recordId/increment` (#4797): add each of
3034
+ * `fields` to the record's field, answering `{ record, values }`.
3035
+ */
3036
+ async incrementDb3Record(appId, db3Id, modelName, recordId, body) {
3037
+ return this.post(`${this.db3Path(appId, db3Id)}/records/${encodeURIComponent(modelName)}/${encodeURIComponent(recordId)}/increment`, body);
3038
+ }
3039
+ /** `GET db3/:id/sync` (#4799): `{ id, sync }`. */
3040
+ async getDb3Sync(appId, db3Id) {
3041
+ return this.get(`${this.db3Path(appId, db3Id)}/sync`);
3042
+ }
3043
+ /** `PUT db3/:id/sync` (#4799): `{ id, sync, changed }`. */
3044
+ async setDb3Sync(appId, db3Id, sync) {
3045
+ return this.put(`${this.db3Path(appId, db3Id)}/sync`, { sync });
3046
+ }
3047
+ /** `GET db3/:id/app-access` (#4801): `{ id, level }`, the level every user of the app holds, or null. */
3048
+ async getDb3AppAccess(appId, db3Id) {
3049
+ return this.get(`${this.db3Path(appId, db3Id)}/app-access`);
3050
+ }
3051
+ /** `PUT db3/:id/app-access` (#4801): grant the db3 to every user of the app, or remove the grant with null. */
3052
+ async setDb3AppAccess(appId, db3Id, level) {
3053
+ return this.put(`${this.db3Path(appId, db3Id)}/app-access`, { level });
3054
+ }
3055
+ /** One custodian's db3s through the admin API (#4800): `custodian` is `app` or `user:<userId>`. */
3056
+ async listDb3ByCustodian(appId, custodian, params) {
3057
+ const result = await this.get(`/admin/api/apps/${appId}/db3`, { custodian, ...(params ?? {}) });
3058
+ const nextCursor = result?.nextCursor;
3059
+ return { items: result?.items ?? [], nextCursor, hasMore: result?.hasMore ?? nextCursor != null };
3060
+ }
3061
+ /**
3062
+ * Every db3 a member reaches through the admin API (#5253): held, shared
3063
+ * with them, then app access, each row with its `via`; `via` narrows to
3064
+ * some of the three ways.
3065
+ */
3066
+ async listDb3ForUser(appId, userId, params) {
3067
+ const result = await this.get(`/admin/api/apps/${appId}/users/${encodeURIComponent(userId)}/db3`, {
3068
+ ...(params?.via ? { via: params.via.join(",") } : {}),
3069
+ ...(params?.limit !== undefined ? { limit: params.limit } : {}),
3070
+ ...(params?.cursor ? { cursor: params.cursor } : {}),
3071
+ });
3072
+ const nextCursor = result?.nextCursor;
3073
+ return { items: result?.items ?? [], nextCursor, hasMore: result?.hasMore ?? nextCursor != null };
3074
+ }
3075
+ /** Transfer a db3 to `to` (`app` or `user:<userId>`) through the admin API (#4804). */
3076
+ async transferDb3(appId, db3Id, to) {
3077
+ return this.post(`/admin/api/apps/${appId}/db3/${encodeURIComponent(db3Id)}/transfer`, { to });
3078
+ }
3079
+ /** Remove or restore a db3's owner row through the admin API (#4804): `{ id, custodian, ownerRow, changed }`. */
3080
+ async setDb3OwnerRow(appId, db3Id, present) {
3081
+ return this.put(`/admin/api/apps/${appId}/db3/${encodeURIComponent(db3Id)}/owner-row`, { present });
3082
+ }
3083
+ /** `GET db3/:id/type` (#4802): the type the db3's row names, its revision, and what its room holds. */
3084
+ async getDb3Type(appId, db3Id) {
3085
+ return this.get(`${this.db3Path(appId, db3Id)}/type`);
3086
+ }
3087
+ /** `PUT db3/:id/type` (#4802): attach a type, installing its current revision whole or refusing it whole. */
3088
+ async attachDb3Type(appId, db3Id, type) {
3089
+ return this.put(`${this.db3Path(appId, db3Id)}/type`, { type });
3090
+ }
3091
+ /** `/app/<app>/api/db3-types/<name>`, the name encoded (#4802). */
3092
+ db3TypePath(appId, name) {
3093
+ return `/app/${appId}/api/db3-types/${encodeURIComponent(name)}`;
3094
+ }
3095
+ /** `GET db3-types` (#4802): the app's db3 types, each with its revision. */
3096
+ async listDb3Types(appId) {
3097
+ return this.get(`/app/${appId}/api/db3-types`);
3098
+ }
3099
+ /** `GET db3-types/:name` (#4802). */
3100
+ async getDb3TypeConfig(appId, name) {
3101
+ return this.get(this.db3TypePath(appId, name));
3102
+ }
3103
+ /**
3104
+ * `PUT db3-types/:name` (#4802): create or update the type, and push its new
3105
+ * revision to every db3 of it. `dryRun` judges the body and persists nothing;
3106
+ * `allowFieldRemoval` asks for the append-only override (#6019), which the
3107
+ * server takes only on an app whose stored settings enable it.
3108
+ */
3109
+ async pushDb3Type(appId, name, data, options) {
3110
+ const qs = new URLSearchParams();
3111
+ if (options?.dryRun)
3112
+ qs.set("dryRun", "true");
3113
+ if (options?.allowFieldRemoval)
3114
+ qs.set("allowFieldRemoval", "true");
3115
+ const query = qs.toString();
3116
+ return this.put(`${this.db3TypePath(appId, name)}${query ? `?${query}` : ""}`, data);
3117
+ }
3118
+ /** `DELETE db3-types/:name` (#4802): refused while a db3 is of the type. */
3119
+ async deleteDb3Type(appId, name) {
3120
+ return this.delete(this.db3TypePath(appId, name));
3121
+ }
3122
+ /** `GET db3-types/:name/push-status` (#4802): a push's outcome per db3; the latest without `runId`. */
3123
+ async getDb3TypePushStatus(appId, name, runId) {
3124
+ return this.get(`${this.db3TypePath(appId, name)}/push-status${runId ? `?runId=${encodeURIComponent(runId)}` : ""}`);
3125
+ }
3126
+ /** `POST db3-types/:name/push?runId=` (#4802): push the current revision again to a run's refused and failed db3s. */
3127
+ async retryDb3TypePush(appId, name, runId) {
3128
+ return this.post(`${this.db3TypePath(appId, name)}/push?runId=${encodeURIComponent(runId)}`, {});
3129
+ }
2717
3130
  async createDocument(appId, data) {
2718
3131
  return this.post(`/app/${appId}/api/documents`, data);
2719
3132
  }
@@ -2778,8 +3191,12 @@ export class ApiClient {
2778
3191
  return this.get(`/app/${appId}/api/documents/${documentId}/blobs`, params);
2779
3192
  }
2780
3193
  async downloadBlob(appId, documentId, blobId) {
3194
+ return this.downloadBlobAt(`/app/${appId}/api/documents/${documentId}`, blobId);
3195
+ }
3196
+ /** A blob's bytes from `<base>/blobs/<id>/download`: the documents route or its db3 mount. */
3197
+ async downloadBlobAt(base, blobId) {
2781
3198
  const credentials = await this.ensureAuthenticated();
2782
- const url = `${credentials.serverUrl}/app/${appId}/api/documents/${documentId}/blobs/${blobId}/download`;
3199
+ const url = `${credentials.serverUrl}${base}/blobs/${blobId}/download`;
2783
3200
  const headers = {
2784
3201
  Authorization: `Bearer ${credentials.accessToken}`,
2785
3202
  };
@@ -2794,8 +3211,12 @@ export class ApiClient {
2794
3211
  return Buffer.from(arrayBuffer);
2795
3212
  }
2796
3213
  async uploadBlob(appId, documentId, blobId, data, meta) {
3214
+ return this.uploadBlobAt(`/app/${appId}/api/documents/${documentId}`, blobId, data, meta);
3215
+ }
3216
+ /** A blob PUT to `<base>/blobs/<id>`: the documents route or its db3 mount. */
3217
+ async uploadBlobAt(base, blobId, data, meta) {
2797
3218
  const credentials = await this.ensureAuthenticated();
2798
- const url = `${credentials.serverUrl}/app/${appId}/api/documents/${documentId}/blobs/${blobId}`;
3219
+ const url = `${credentials.serverUrl}${base}/blobs/${blobId}`;
2799
3220
  const response = await this.fetchWithStepUp(url, url, credentials.accessToken, (bearer) => {
2800
3221
  const headers = {
2801
3222
  Authorization: `Bearer ${bearer}`,
@@ -2814,6 +3235,64 @@ export class ApiClient {
2814
3235
  }
2815
3236
  return response.json();
2816
3237
  }
3238
+ /**
3239
+ * Upload a file to an agent session by `sessionId` (#4585): the document
3240
+ * blob upload's headers and body, on the session's attachment route.
3241
+ */
3242
+ async uploadAgentSessionAttachment(appId, sessionId, blobId, data, meta) {
3243
+ const credentials = await this.ensureAuthenticated();
3244
+ const url = `${credentials.serverUrl}/app/${appId}/api/agent-sessions/${encodeURIComponent(sessionId)}/attachments/${encodeURIComponent(blobId)}`;
3245
+ const headers = {
3246
+ Authorization: `Bearer ${credentials.accessToken}`,
3247
+ "Content-Type": meta.contentType,
3248
+ "X-Blob-Filename": encodeURIComponent(meta.filename),
3249
+ "X-Blob-Size": String(data.length),
3250
+ "X-Blob-Sha256": meta.sha256,
3251
+ };
3252
+ if (credentials.globalAdminAppId) {
3253
+ headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
3254
+ }
3255
+ const response = await fetchWithTLS(url, { method: "PUT", headers, body: data });
3256
+ if (!response.ok) {
3257
+ throw await blobFailure(response, "Failed to upload attachment: ");
3258
+ }
3259
+ return response.json();
3260
+ }
3261
+ /** Download an agent session's file by `sessionId` (#4585). */
3262
+ async downloadAgentSessionAttachment(appId, sessionId, blobId) {
3263
+ const response = await this.agentSessionAttachmentRead("GET", appId, sessionId, blobId);
3264
+ if (!response.ok) {
3265
+ throw await blobFailure(response, "Failed to download attachment: ");
3266
+ }
3267
+ return Buffer.from(await response.arrayBuffer());
3268
+ }
3269
+ /**
3270
+ * An agent session file's download headers (lower-cased names) by
3271
+ * `sessionId` (#4585). A refusal has no body, so it fails with the status
3272
+ * alone and no code.
3273
+ */
3274
+ async headAgentSessionAttachment(appId, sessionId, blobId) {
3275
+ const response = await this.agentSessionAttachmentRead("HEAD", appId, sessionId, blobId);
3276
+ if (!response.ok && response.status !== 304) {
3277
+ throw new ApiError(`Failed to read attachment headers: HTTP ${response.status}`, response.status);
3278
+ }
3279
+ const headers = {};
3280
+ response.headers.forEach((value, name) => {
3281
+ headers[name.toLowerCase()] = value;
3282
+ });
3283
+ return { status: response.status, headers };
3284
+ }
3285
+ async agentSessionAttachmentRead(method, appId, sessionId, blobId) {
3286
+ const credentials = await this.ensureAuthenticated();
3287
+ const url = `${credentials.serverUrl}/app/${appId}/api/agent-sessions/${encodeURIComponent(sessionId)}/attachments/${encodeURIComponent(blobId)}/download`;
3288
+ const headers = {
3289
+ Authorization: `Bearer ${credentials.accessToken}`,
3290
+ };
3291
+ if (credentials.globalAdminAppId) {
3292
+ headers["X-Global-Admin-App-Id"] = credentials.globalAdminAppId;
3293
+ }
3294
+ return fetchWithTLS(url, { method, headers });
3295
+ }
2817
3296
  async listDocumentAliases(appId, documentId) {
2818
3297
  return this.get(`/app/${appId}/api/documents/${documentId}/aliases`);
2819
3298
  }