@coasys/ad4m 0.13.0-test-7 → 0.13.0-test-8

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 (264) hide show
  1. package/lib/index.cjs +1109 -828
  2. package/lib/index.js +1096 -828
  3. package/lib/src/Ad4mClient.d.ts +4 -1
  4. package/lib/src/Ad4mClient.js +2 -2
  5. package/lib/src/agent/AgentClient.js +17 -0
  6. package/lib/src/ai/AIClient.js +1 -1
  7. package/lib/src/apiClient.d.ts +5 -1
  8. package/lib/src/apiClient.js +14 -6
  9. package/lib/src/generated/rest/AIModelLoadingStatus.d.ts +7 -0
  10. package/lib/src/generated/rest/AIModelLoadingStatus.js +2 -0
  11. package/lib/src/generated/rest/AddAgentInfosRequest.d.ts +3 -0
  12. package/lib/src/generated/rest/AddAgentInfosRequest.js +2 -0
  13. package/lib/src/generated/rest/AddLinkExpressionRequest.d.ts +6 -0
  14. package/lib/src/generated/rest/AddLinkExpressionRequest.js +1 -0
  15. package/lib/src/generated/rest/AddLinkRequest.d.ts +6 -0
  16. package/lib/src/generated/rest/AddLinkRequest.js +1 -0
  17. package/lib/src/generated/rest/AddLinksBulkRequest.d.ts +6 -0
  18. package/lib/src/generated/rest/AddLinksBulkRequest.js +1 -0
  19. package/lib/src/generated/rest/AddSdnaRequest.d.ts +6 -0
  20. package/lib/src/generated/rest/AddSdnaRequest.js +2 -0
  21. package/lib/src/generated/rest/ApplyTemplateRequest.d.ts +4 -0
  22. package/lib/src/generated/rest/ApplyTemplateRequest.js +2 -0
  23. package/lib/src/generated/rest/AuthInfoInput.d.ts +10 -0
  24. package/lib/src/generated/rest/AuthInfoInput.js +1 -0
  25. package/lib/src/generated/rest/BroadcastRequest.d.ts +6 -0
  26. package/lib/src/generated/rest/BroadcastRequest.js +1 -0
  27. package/lib/src/generated/rest/CapabilityInput.d.ts +5 -0
  28. package/lib/src/generated/rest/CapabilityInput.js +1 -0
  29. package/lib/src/generated/rest/CommitBatchRequest.d.ts +3 -0
  30. package/lib/src/generated/rest/CommitBatchRequest.js +2 -0
  31. package/lib/src/generated/rest/ComputeLogEntry.d.ts +9 -0
  32. package/lib/src/generated/rest/ComputeLogEntry.js +2 -0
  33. package/lib/src/generated/rest/CreateExpressionRequest.d.ts +4 -0
  34. package/lib/src/generated/rest/CreateExpressionRequest.js +2 -0
  35. package/lib/src/generated/rest/CreatePerspectiveRequest.d.ts +3 -0
  36. package/lib/src/generated/rest/CreatePerspectiveRequest.js +2 -0
  37. package/lib/src/generated/rest/CreateSubjectRequest.d.ts +6 -0
  38. package/lib/src/generated/rest/CreateSubjectRequest.js +2 -0
  39. package/lib/src/generated/rest/CreateUserRequest.d.ts +4 -0
  40. package/lib/src/generated/rest/CreateUserRequest.js +2 -0
  41. package/lib/src/generated/rest/CreateUserResponse.d.ts +5 -0
  42. package/lib/src/generated/rest/CreateUserResponse.js +2 -0
  43. package/lib/src/generated/rest/DecoratedExpressionProof.d.ts +6 -0
  44. package/lib/src/generated/rest/DecoratedExpressionProof.js +2 -0
  45. package/lib/src/generated/rest/DecoratedLinkExpression.d.ts +10 -0
  46. package/lib/src/generated/rest/DecoratedLinkExpression.js +1 -0
  47. package/lib/src/generated/rest/DisposeQueryRequest.d.ts +3 -0
  48. package/lib/src/generated/rest/DisposeQueryRequest.js +2 -0
  49. package/lib/src/generated/rest/EmailTestRequest.d.ts +6 -0
  50. package/lib/src/generated/rest/EmailTestRequest.js +2 -0
  51. package/lib/src/generated/rest/EmbedRequest.d.ts +4 -0
  52. package/lib/src/generated/rest/EmbedRequest.js +2 -0
  53. package/lib/src/generated/rest/EntanglementProofInput.d.ts +6 -0
  54. package/lib/src/generated/rest/EntanglementProofInput.js +2 -0
  55. package/lib/src/generated/rest/EntanglementProofPreflightRequest.d.ts +4 -0
  56. package/lib/src/generated/rest/EntanglementProofPreflightRequest.js +2 -0
  57. package/lib/src/generated/rest/ExecuteCommandsRequest.d.ts +4 -0
  58. package/lib/src/generated/rest/ExecuteCommandsRequest.js +2 -0
  59. package/lib/src/generated/rest/ExportRequest.d.ts +5 -0
  60. package/lib/src/generated/rest/ExportRequest.js +2 -0
  61. package/lib/src/generated/rest/ExpressionManyRequest.d.ts +3 -0
  62. package/lib/src/generated/rest/ExpressionManyRequest.js +2 -0
  63. package/lib/src/generated/rest/ExpressionProof.d.ts +4 -0
  64. package/lib/src/generated/rest/ExpressionProof.js +2 -0
  65. package/lib/src/generated/rest/ExpressionProofInput.d.ts +6 -0
  66. package/lib/src/generated/rest/ExpressionProofInput.js +2 -0
  67. package/lib/src/generated/rest/FriendSendMessageRequest.d.ts +3 -0
  68. package/lib/src/generated/rest/FriendSendMessageRequest.js +2 -0
  69. package/lib/src/generated/rest/FriendsListRequest.d.ts +3 -0
  70. package/lib/src/generated/rest/FriendsListRequest.js +2 -0
  71. package/lib/src/generated/rest/GenerateAgentRequest.d.ts +3 -0
  72. package/lib/src/generated/rest/GenerateAgentRequest.js +2 -0
  73. package/lib/src/generated/rest/GenerateJwtRequest.d.ts +4 -0
  74. package/lib/src/generated/rest/GenerateJwtRequest.js +2 -0
  75. package/lib/src/generated/rest/GetSubjectDataRequest.d.ts +4 -0
  76. package/lib/src/generated/rest/GetSubjectDataRequest.js +2 -0
  77. package/lib/src/generated/rest/HostingInfoResponse.d.ts +5 -0
  78. package/lib/src/generated/rest/HostingInfoResponse.js +2 -0
  79. package/lib/src/generated/rest/HostingWalletResponse.d.ts +4 -0
  80. package/lib/src/generated/rest/HostingWalletResponse.js +2 -0
  81. package/lib/src/generated/rest/ImportAgentRequest.d.ts +6 -0
  82. package/lib/src/generated/rest/ImportAgentRequest.js +2 -0
  83. package/lib/src/generated/rest/ImportRequest.d.ts +4 -0
  84. package/lib/src/generated/rest/ImportRequest.js +2 -0
  85. package/lib/src/generated/rest/JoinNeighbourhoodRequest.d.ts +3 -0
  86. package/lib/src/generated/rest/JoinNeighbourhoodRequest.js +2 -0
  87. package/lib/src/generated/rest/KeepAliveQueryRequest.d.ts +3 -0
  88. package/lib/src/generated/rest/KeepAliveQueryRequest.js +2 -0
  89. package/lib/src/generated/rest/LanguageMetaInput.d.ts +6 -0
  90. package/lib/src/generated/rest/LanguageMetaInput.js +2 -0
  91. package/lib/src/generated/rest/Link.d.ts +5 -0
  92. package/lib/src/generated/rest/Link.js +2 -0
  93. package/lib/src/generated/rest/LinkExpression.d.ts +10 -0
  94. package/lib/src/generated/rest/LinkExpression.js +1 -0
  95. package/lib/src/generated/rest/LinkExpressionInput.d.ts +10 -0
  96. package/lib/src/generated/rest/LinkExpressionInput.js +1 -0
  97. package/lib/src/generated/rest/LinkInput.d.ts +5 -0
  98. package/lib/src/generated/rest/LinkInput.js +2 -0
  99. package/lib/src/generated/rest/LinkLanguageTemplatesRequest.d.ts +3 -0
  100. package/lib/src/generated/rest/LinkLanguageTemplatesRequest.js +2 -0
  101. package/lib/src/generated/rest/LinkMutationRequest.d.ts +12 -0
  102. package/lib/src/generated/rest/LinkMutationRequest.js +1 -0
  103. package/lib/src/generated/rest/LinkMutationResponse.d.ts +9 -0
  104. package/lib/src/generated/rest/LinkMutationResponse.js +1 -0
  105. package/lib/src/generated/rest/LinkMutations.d.ts +6 -0
  106. package/lib/src/generated/rest/LinkMutations.js +1 -0
  107. package/lib/src/generated/rest/LinkMutationsRequest.d.ts +5 -0
  108. package/lib/src/generated/rest/LinkMutationsRequest.js +1 -0
  109. package/lib/src/generated/rest/LinkStatus.d.ts +1 -0
  110. package/lib/src/generated/rest/LinkStatus.js +2 -0
  111. package/lib/src/generated/rest/LinkUpdateInput.d.ts +5 -0
  112. package/lib/src/generated/rest/LinkUpdateInput.js +1 -0
  113. package/lib/src/generated/rest/LockAgentRequest.d.ts +3 -0
  114. package/lib/src/generated/rest/LockAgentRequest.js +2 -0
  115. package/lib/src/generated/rest/LoginUserRequest.d.ts +5 -0
  116. package/lib/src/generated/rest/LoginUserRequest.js +2 -0
  117. package/lib/src/generated/rest/ModelType.d.ts +1 -0
  118. package/lib/src/generated/rest/ModelType.js +2 -0
  119. package/lib/src/generated/rest/NotificationGrantRequest.d.ts +3 -0
  120. package/lib/src/generated/rest/NotificationGrantRequest.js +2 -0
  121. package/lib/src/generated/rest/NotificationInput.d.ts +10 -0
  122. package/lib/src/generated/rest/NotificationInput.js +2 -0
  123. package/lib/src/generated/rest/OpenLinkRequest.d.ts +3 -0
  124. package/lib/src/generated/rest/OpenLinkRequest.js +2 -0
  125. package/lib/src/generated/rest/PermitCapabilityRequest.d.ts +3 -0
  126. package/lib/src/generated/rest/PermitCapabilityRequest.js +2 -0
  127. package/lib/src/generated/rest/PerspectiveInput.d.ts +4 -0
  128. package/lib/src/generated/rest/PerspectiveInput.js +1 -0
  129. package/lib/src/generated/rest/PromptRequest.d.ts +4 -0
  130. package/lib/src/generated/rest/PromptRequest.js +2 -0
  131. package/lib/src/generated/rest/PublicPerspectiveInput.d.ts +4 -0
  132. package/lib/src/generated/rest/PublicPerspectiveInput.js +1 -0
  133. package/lib/src/generated/rest/PublishLanguageRequest.d.ts +5 -0
  134. package/lib/src/generated/rest/PublishLanguageRequest.js +1 -0
  135. package/lib/src/generated/rest/PublishNeighbourhoodRequest.d.ts +6 -0
  136. package/lib/src/generated/rest/PublishNeighbourhoodRequest.js +1 -0
  137. package/lib/src/generated/rest/QueryRequest.d.ts +7 -0
  138. package/lib/src/generated/rest/QueryRequest.js +2 -0
  139. package/lib/src/generated/rest/RemoveLinkRequest.d.ts +5 -0
  140. package/lib/src/generated/rest/RemoveLinkRequest.js +1 -0
  141. package/lib/src/generated/rest/RemoveLinksBulkRequest.d.ts +5 -0
  142. package/lib/src/generated/rest/RemoveLinksBulkRequest.js +1 -0
  143. package/lib/src/generated/rest/RequestCapabilityRequest.d.ts +4 -0
  144. package/lib/src/generated/rest/RequestCapabilityRequest.js +1 -0
  145. package/lib/src/generated/rest/RequestPaymentRequest.d.ts +3 -0
  146. package/lib/src/generated/rest/RequestPaymentRequest.js +2 -0
  147. package/lib/src/generated/rest/RequestVerificationRequest.d.ts +4 -0
  148. package/lib/src/generated/rest/RequestVerificationRequest.js +2 -0
  149. package/lib/src/generated/rest/ResourceInput.d.ts +4 -0
  150. package/lib/src/generated/rest/ResourceInput.js +2 -0
  151. package/lib/src/generated/rest/SetDefaultModelRequest.d.ts +4 -0
  152. package/lib/src/generated/rest/SetDefaultModelRequest.js +1 -0
  153. package/lib/src/generated/rest/SetFreeHostingEnabledRequest.d.ts +3 -0
  154. package/lib/src/generated/rest/SetFreeHostingEnabledRequest.js +2 -0
  155. package/lib/src/generated/rest/SetHotWalletAddressRequest.d.ts +3 -0
  156. package/lib/src/generated/rest/SetHotWalletAddressRequest.js +2 -0
  157. package/lib/src/generated/rest/SetMultiUserRequest.d.ts +3 -0
  158. package/lib/src/generated/rest/SetMultiUserRequest.js +2 -0
  159. package/lib/src/generated/rest/SetOnlineStatusRequest.d.ts +5 -0
  160. package/lib/src/generated/rest/SetOnlineStatusRequest.js +1 -0
  161. package/lib/src/generated/rest/SetStatusRequest.d.ts +3 -0
  162. package/lib/src/generated/rest/SetStatusRequest.js +2 -0
  163. package/lib/src/generated/rest/SetUserFreeAccessRequest.d.ts +4 -0
  164. package/lib/src/generated/rest/SetUserFreeAccessRequest.js +2 -0
  165. package/lib/src/generated/rest/SignMessageRequest.d.ts +3 -0
  166. package/lib/src/generated/rest/SignMessageRequest.js +2 -0
  167. package/lib/src/generated/rest/SignalRequest.d.ts +6 -0
  168. package/lib/src/generated/rest/SignalRequest.js +1 -0
  169. package/lib/src/generated/rest/SubscribeQueryRequest.d.ts +3 -0
  170. package/lib/src/generated/rest/SubscribeQueryRequest.js +2 -0
  171. package/lib/src/generated/rest/SubscribeQueryResponse.d.ts +4 -0
  172. package/lib/src/generated/rest/SubscribeQueryResponse.js +2 -0
  173. package/lib/src/generated/rest/TrustedAgentsRequest.d.ts +3 -0
  174. package/lib/src/generated/rest/TrustedAgentsRequest.js +2 -0
  175. package/lib/src/generated/rest/UnlockAgentRequest.d.ts +4 -0
  176. package/lib/src/generated/rest/UnlockAgentRequest.js +2 -0
  177. package/lib/src/generated/rest/UpdateLinkRequest.d.ts +7 -0
  178. package/lib/src/generated/rest/UpdateLinkRequest.js +1 -0
  179. package/lib/src/generated/rest/UpdatePerspectiveRequest.d.ts +3 -0
  180. package/lib/src/generated/rest/UpdatePerspectiveRequest.js +2 -0
  181. package/lib/src/generated/rest/UpdateProfileRequest.d.ts +5 -0
  182. package/lib/src/generated/rest/UpdateProfileRequest.js +1 -0
  183. package/lib/src/generated/rest/UserStatistics.d.ts +9 -0
  184. package/lib/src/generated/rest/UserStatistics.js +2 -0
  185. package/lib/src/generated/rest/VerificationRequestResult.d.ts +6 -0
  186. package/lib/src/generated/rest/VerificationRequestResult.js +2 -0
  187. package/lib/src/generated/rest/VerifyEmailRequest.d.ts +6 -0
  188. package/lib/src/generated/rest/VerifyEmailRequest.js +2 -0
  189. package/lib/src/generated/rest/VerifySignatureRequest.d.ts +5 -0
  190. package/lib/src/generated/rest/VerifySignatureRequest.js +2 -0
  191. package/lib/src/generated/rest/WriteSettingsRequest.d.ts +3 -0
  192. package/lib/src/generated/rest/WriteSettingsRequest.js +2 -0
  193. package/lib/src/generated/rest/index.d.ts +73 -0
  194. package/lib/src/generated/rest/index.js +8 -0
  195. package/lib/src/generated/rest/routes.d.ts +587 -0
  196. package/lib/src/generated/rest/routes.js +3 -0
  197. package/lib/src/index.d.ts +4 -0
  198. package/lib/src/index.js +4 -0
  199. package/lib/src/model/Ad4mModel.d.ts +30 -36
  200. package/lib/src/model/Ad4mModel.js +93 -382
  201. package/lib/src/model/Ad4mModel.test.js +735 -480
  202. package/lib/src/model/ModelQueryBuilder.d.ts +5 -10
  203. package/lib/src/model/ModelQueryBuilder.js +142 -62
  204. package/lib/src/model/decorators.d.ts +7 -4
  205. package/lib/src/model/decorators.js +0 -7
  206. package/lib/src/model/query-sparql.d.ts +0 -10
  207. package/lib/src/model/query-sparql.js +10 -15
  208. package/lib/src/model/query-sparql.test.js +10 -92
  209. package/lib/src/model/query-surreal.d.ts +44 -0
  210. package/lib/src/model/query-surreal.js +249 -0
  211. package/lib/src/model/shacl-gen.js +120 -47
  212. package/lib/src/model/surreal-utils.d.ts +42 -0
  213. package/lib/src/model/surreal-utils.js +128 -0
  214. package/lib/src/model/types.d.ts +140 -4
  215. package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +33 -33
  216. package/lib/src/perspectives/PerspectiveClient.d.ts +13 -4
  217. package/lib/src/perspectives/PerspectiveClient.js +22 -6
  218. package/lib/src/perspectives/PerspectiveProxy.d.ts +27 -7
  219. package/lib/src/perspectives/PerspectiveProxy.js +60 -12
  220. package/lib/src/perspectives/PerspectiveProxy.test.d.ts +1 -0
  221. package/lib/src/perspectives/PerspectiveProxy.test.js +34 -0
  222. package/lib/src/perspectives/SparqlBindings.d.ts +47 -0
  223. package/lib/src/perspectives/SparqlBindings.js +65 -0
  224. package/lib/src/perspectives/WakerSubscriptionManager.js +5 -4
  225. package/lib/src/restClient.d.ts +52 -0
  226. package/lib/src/restClient.js +227 -0
  227. package/lib/src/shacl/NodeExpression.d.ts +44 -0
  228. package/lib/src/shacl/NodeExpression.js +39 -0
  229. package/lib/src/shacl/SHACLShape.d.ts +23 -0
  230. package/lib/src/shacl/SHACLShape.js +115 -1
  231. package/lib/src/shacl/SHACLShape.test.js +0 -82
  232. package/lib/src/shacl/builders.d.ts +58 -0
  233. package/lib/src/shacl/builders.js +76 -0
  234. package/lib/src/shacl/index.d.ts +36 -0
  235. package/lib/src/shacl/index.js +33 -0
  236. package/package.json +11 -8
  237. package/src/Ad4mClient.ts +7 -2
  238. package/src/agent/AgentClient.ts +23 -0
  239. package/src/ai/AIClient.ts +1 -1
  240. package/src/apiClient.ts +17 -6
  241. package/src/index.ts +4 -0
  242. package/src/model/Ad4mModel.test.ts +274 -72
  243. package/src/model/Ad4mModel.ts +140 -420
  244. package/src/model/ModelQueryBuilder.ts +136 -71
  245. package/src/model/decorators.ts +7 -13
  246. package/src/model/query-sparql.test.ts +35 -19
  247. package/src/model/query-sparql.ts +10 -16
  248. package/src/model/relation-filtering.test.ts +46 -39
  249. package/src/model/shacl-gen.ts +128 -54
  250. package/src/model/shacl-roundtrip.test.ts +197 -0
  251. package/src/model/types-typed-query.test.ts +360 -0
  252. package/src/model/types.ts +196 -4
  253. package/src/perspectives/PerspectiveClient.ts +24 -8
  254. package/src/perspectives/PerspectiveProxy.test.ts +85 -1
  255. package/src/perspectives/PerspectiveProxy.ts +65 -20
  256. package/src/perspectives/SparqlBindings.ts +79 -0
  257. package/src/perspectives/WakerSubscriptionManager.ts +5 -4
  258. package/src/shacl/NodeExpression.ts +54 -0
  259. package/src/shacl/SHACLShape.test.ts +172 -0
  260. package/src/shacl/SHACLShape.ts +173 -1
  261. package/src/shacl/builders.ts +86 -0
  262. package/src/shacl/index.ts +72 -0
  263. package/lib/src/model/model-manifest.d.ts +0 -41
  264. package/lib/src/model/model-manifest.js +0 -11
@@ -0,0 +1,47 @@
1
+ /**
2
+ * SPARQL binding helpers — typed shapes and parsers for `querySparql<T>()`.
3
+ *
4
+ * AD4M stores non-string property values as URL-encoded `Literal` payloads
5
+ * (see {@link Literal}). When raw SPARQL queries pull these values out of the
6
+ * RDF store the bindings are still in encoded form; consumers must decode
7
+ * before use. The helpers here centralise that decode step so each call site
8
+ * can pick the variant matching its declared binding type.
9
+ *
10
+ * @example
11
+ * ```ts
12
+ * interface MessageBinding {
13
+ * id: string;
14
+ * timestamp: string; // raw literal — decode with parseLitNumber
15
+ * body?: string; // raw literal — decode with parseLit
16
+ * }
17
+ * const rows = await perspective.querySparql<MessageBinding[]>(query);
18
+ * const ts = parseLitNumber(rows[0].timestamp); // number
19
+ * const body = rows[0].body ? parseLit(rows[0].body) : '';
20
+ * ```
21
+ */
22
+ /** Common AD4M link binding — matches the `?source/?predicate/?target/?author/?timestamp` pattern. */
23
+ export interface LinkBinding {
24
+ source: string;
25
+ predicate: string;
26
+ target: string;
27
+ author?: string;
28
+ timestamp?: string;
29
+ }
30
+ /** COUNT(?x) result binding — SPARQL returns counts as string literals. */
31
+ export interface CountBinding {
32
+ count: string;
33
+ }
34
+ /** Sum a SPARQL COUNT(?x) result down to a plain number (returns 0 on empty). */
35
+ export declare function parseSparqlCount(result: CountBinding[] | undefined | null): number;
36
+ /**
37
+ * Decode a `Literal`-encoded SPARQL binding back to a plain string.
38
+ *
39
+ * Mirrors Flux's local `parseLit` helper. Returns `''` for `undefined`/empty
40
+ * input. Falls through to the raw value if decoding fails (defensive — the
41
+ * binding may already be a plain string for unwrapped properties).
42
+ */
43
+ export declare function parseLit(val: string | undefined | null): string;
44
+ /** Decode a `Literal`-encoded binding to a number. Returns 0 on empty/invalid input. */
45
+ export declare function parseLitNumber(val: string | undefined | null): number;
46
+ /** Decode a `Literal`-encoded binding to a boolean. Returns false on empty input. */
47
+ export declare function parseLitBoolean(val: string | undefined | null): boolean;
@@ -0,0 +1,65 @@
1
+ /**
2
+ * SPARQL binding helpers — typed shapes and parsers for `querySparql<T>()`.
3
+ *
4
+ * AD4M stores non-string property values as URL-encoded `Literal` payloads
5
+ * (see {@link Literal}). When raw SPARQL queries pull these values out of the
6
+ * RDF store the bindings are still in encoded form; consumers must decode
7
+ * before use. The helpers here centralise that decode step so each call site
8
+ * can pick the variant matching its declared binding type.
9
+ *
10
+ * @example
11
+ * ```ts
12
+ * interface MessageBinding {
13
+ * id: string;
14
+ * timestamp: string; // raw literal — decode with parseLitNumber
15
+ * body?: string; // raw literal — decode with parseLit
16
+ * }
17
+ * const rows = await perspective.querySparql<MessageBinding[]>(query);
18
+ * const ts = parseLitNumber(rows[0].timestamp); // number
19
+ * const body = rows[0].body ? parseLit(rows[0].body) : '';
20
+ * ```
21
+ */
22
+ import { Literal } from "../Literal";
23
+ /** Sum a SPARQL COUNT(?x) result down to a plain number (returns 0 on empty). */
24
+ export function parseSparqlCount(result) {
25
+ if (!result || result.length === 0)
26
+ return 0;
27
+ const raw = result[0].count;
28
+ const n = parseInt(raw, 10);
29
+ return Number.isNaN(n) ? 0 : n;
30
+ }
31
+ /**
32
+ * Decode a `Literal`-encoded SPARQL binding back to a plain string.
33
+ *
34
+ * Mirrors Flux's local `parseLit` helper. Returns `''` for `undefined`/empty
35
+ * input. Falls through to the raw value if decoding fails (defensive — the
36
+ * binding may already be a plain string for unwrapped properties).
37
+ */
38
+ export function parseLit(val) {
39
+ if (val === undefined || val === null || val === '')
40
+ return '';
41
+ try {
42
+ const result = Literal.fromUrl(val).get();
43
+ if (result && typeof result === 'object') {
44
+ return result.data ?? JSON.stringify(result);
45
+ }
46
+ return String(result);
47
+ }
48
+ catch {
49
+ return val;
50
+ }
51
+ }
52
+ /** Decode a `Literal`-encoded binding to a number. Returns 0 on empty/invalid input. */
53
+ export function parseLitNumber(val) {
54
+ if (val === undefined || val === null || val === '')
55
+ return 0;
56
+ const decoded = parseLit(val);
57
+ const n = Number(decoded);
58
+ return Number.isNaN(n) ? 0 : n;
59
+ }
60
+ /** Decode a `Literal`-encoded binding to a boolean. Returns false on empty input. */
61
+ export function parseLitBoolean(val) {
62
+ if (val === undefined || val === null || val === '')
63
+ return false;
64
+ return parseLit(val) === 'true';
65
+ }
@@ -97,10 +97,11 @@ export class WakerSubscriptionManager {
97
97
  const parentQuery = `SELECT ?source WHERE { ?source <ad4m://has_child> <${msgAddr}> . }`;
98
98
  this.logger.info(`[waker] ${sub.id}: resolving parents for ${msgAddr}`);
99
99
  const parentResult = await this.perspectiveClient.querySparql(sub.perspective, parentQuery);
100
- if (Array.isArray(parentResult)) {
101
- for (const link of parentResult) {
102
- if (link && link.source) {
103
- parents.push(link.source);
100
+ const bindings = parentResult?.results?.bindings;
101
+ if (Array.isArray(bindings)) {
102
+ for (const binding of bindings) {
103
+ if (binding?.source?.value) {
104
+ parents.push(binding.source.value);
104
105
  }
105
106
  }
106
107
  }
@@ -0,0 +1,52 @@
1
+ /** Shape of event data parsed from JSON. Callers can narrow via generics. */
2
+ export interface SseEvent {
3
+ type: string;
4
+ [key: string]: unknown;
5
+ }
6
+ /** Error thrown by RestClient when an RPC call fails. */
7
+ export declare class RestError extends Error {
8
+ /** Error code (maps to HTTP status semantics: 400, 401, 403, 404, 500). */
9
+ readonly status: number;
10
+ /** Raw error message from server. */
11
+ readonly body: string;
12
+ constructor(status: number, body: string);
13
+ }
14
+ export declare class RestClient {
15
+ private baseUrl;
16
+ private token?;
17
+ constructor(baseUrl: string, token?: string);
18
+ getBaseUrl(): string;
19
+ getToken(): string | undefined;
20
+ setToken(token: string): void;
21
+ private _ws;
22
+ private _wsCallbacks;
23
+ private _pendingCalls;
24
+ private _wsReady;
25
+ private _wsReadyResolve;
26
+ private _wsReconnectTimer;
27
+ private _wsReconnectDelay;
28
+ private _wsClosed;
29
+ private _wsPingTimer;
30
+ private _getWsUrl;
31
+ private _ensureWs;
32
+ private _startPing;
33
+ private _stopPing;
34
+ private _scheduleReconnect;
35
+ /** Ensure WS is connected and ready. Lazy — connects on first use. */
36
+ private _ready;
37
+ /**
38
+ * Send an RPC call over the WebSocket connection.
39
+ * @param type - The operation type (e.g. 'agent.get', 'perspective.all')
40
+ * @param params - Optional parameters to include in the message
41
+ * @returns Promise that resolves with the result from the server
42
+ */
43
+ call<T>(type: string, params?: Record<string, unknown>): Promise<T>;
44
+ subscribe<T = SseEvent>(path: string, callback: (data: T) => void): () => void;
45
+ /** Wait until the WebSocket connection is established. */
46
+ waitForSubscription(path: string): Promise<void>;
47
+ /** Explicitly connect the WebSocket (optional — connection is lazy). */
48
+ connect(): void;
49
+ private _closeWs;
50
+ /** Close all open WebSocket connections and reject pending calls. */
51
+ closeAll(): void;
52
+ }
@@ -0,0 +1,227 @@
1
+ /** Error thrown by RestClient when an RPC call fails. */
2
+ export class RestError extends Error {
3
+ constructor(status, body) {
4
+ super(`RPC error ${status}: ${body}`);
5
+ this.name = 'RestError';
6
+ this.status = status;
7
+ this.body = body;
8
+ }
9
+ }
10
+ /** Default RPC call timeout in milliseconds (30 seconds). */
11
+ const DEFAULT_TIMEOUT_MS = 30000;
12
+ /** Maximum reconnect delay in ms. */
13
+ const MAX_RECONNECT_DELAY_MS = 30000;
14
+ /** Initial reconnect delay in ms. */
15
+ const INITIAL_RECONNECT_DELAY_MS = 500;
16
+ /** Counter for generating unique request IDs. */
17
+ let _idCounter = 0;
18
+ function nextId() {
19
+ return String(++_idCounter);
20
+ }
21
+ export class RestClient {
22
+ constructor(baseUrl, token) {
23
+ // ── WebSocket RPC core ──────────────────────────────────────────────────
24
+ this._ws = null;
25
+ this._wsCallbacks = new Set();
26
+ this._pendingCalls = new Map();
27
+ this._wsReady = null;
28
+ this._wsReadyResolve = null;
29
+ this._wsReconnectTimer = null;
30
+ this._wsReconnectDelay = INITIAL_RECONNECT_DELAY_MS;
31
+ this._wsClosed = false;
32
+ this._wsPingTimer = null;
33
+ this.baseUrl = baseUrl;
34
+ this.token = token;
35
+ }
36
+ getBaseUrl() { return this.baseUrl; }
37
+ getToken() { return this.token; }
38
+ setToken(token) {
39
+ this.token = token;
40
+ }
41
+ _getWsUrl() {
42
+ const wsBase = this.baseUrl
43
+ .replace(/^http:\/\//, 'ws://')
44
+ .replace(/^https:\/\//, 'wss://');
45
+ const tokenParam = this.token ? `token=${encodeURIComponent(this.token)}` : '';
46
+ const path = '/api/v1/ws';
47
+ return tokenParam ? `${wsBase}${path}?${tokenParam}` : `${wsBase}${path}`;
48
+ }
49
+ _ensureWs() {
50
+ if (this._ws && (this._ws.readyState === WebSocket.OPEN || this._ws.readyState === WebSocket.CONNECTING)) {
51
+ return;
52
+ }
53
+ this._wsClosed = false;
54
+ this._wsReady = new Promise((resolve) => {
55
+ this._wsReadyResolve = resolve;
56
+ });
57
+ const url = this._getWsUrl();
58
+ const ws = new WebSocket(url);
59
+ this._ws = ws;
60
+ ws.onopen = () => {
61
+ this._wsReconnectDelay = INITIAL_RECONNECT_DELAY_MS;
62
+ if (this._wsReadyResolve) {
63
+ this._wsReadyResolve();
64
+ this._wsReadyResolve = null;
65
+ }
66
+ this._startPing();
67
+ };
68
+ ws.onmessage = (event) => {
69
+ let parsed;
70
+ try {
71
+ parsed = JSON.parse(event.data);
72
+ }
73
+ catch (e) {
74
+ console.error('Error parsing WebSocket data:', e);
75
+ return;
76
+ }
77
+ // Ignore pong messages
78
+ if (parsed.type === 'pong')
79
+ return;
80
+ // Check if this is a response to a pending RPC call (has an id field)
81
+ const id = parsed.id;
82
+ if (id && this._pendingCalls.has(id)) {
83
+ const pending = this._pendingCalls.get(id);
84
+ this._pendingCalls.delete(id);
85
+ clearTimeout(pending.timer);
86
+ if (parsed.error) {
87
+ const err = parsed.error;
88
+ pending.reject(new RestError(err.code ?? 500, err.message ?? 'Unknown error'));
89
+ }
90
+ else {
91
+ pending.resolve(parsed.result);
92
+ }
93
+ return;
94
+ }
95
+ // Server-push event (no id, or id not in pending) → route to subscribers
96
+ for (const cb of this._wsCallbacks)
97
+ cb(parsed);
98
+ };
99
+ ws.onerror = (e) => {
100
+ console.error('WebSocket error:', e);
101
+ };
102
+ ws.onclose = () => {
103
+ this._stopPing();
104
+ this._ws = null;
105
+ // Reset the readiness promise so future calls reconnect
106
+ this._wsReady = null;
107
+ // Reject all pending calls
108
+ for (const [id, pending] of this._pendingCalls) {
109
+ clearTimeout(pending.timer);
110
+ pending.reject(new RestError(503, 'WebSocket connection closed'));
111
+ }
112
+ this._pendingCalls.clear();
113
+ if (!this._wsClosed && (this._wsCallbacks.size > 0 || this._pendingCalls.size > 0)) {
114
+ this._scheduleReconnect();
115
+ }
116
+ };
117
+ }
118
+ _startPing() {
119
+ this._stopPing();
120
+ this._wsPingTimer = setInterval(() => {
121
+ if (this._ws && this._ws.readyState === WebSocket.OPEN) {
122
+ this._ws.send(JSON.stringify({ type: 'ping' }));
123
+ }
124
+ }, 30000);
125
+ }
126
+ _stopPing() {
127
+ if (this._wsPingTimer) {
128
+ clearInterval(this._wsPingTimer);
129
+ this._wsPingTimer = null;
130
+ }
131
+ }
132
+ _scheduleReconnect() {
133
+ if (this._wsReconnectTimer)
134
+ return;
135
+ const delay = this._wsReconnectDelay;
136
+ this._wsReconnectDelay = Math.min(this._wsReconnectDelay * 2, MAX_RECONNECT_DELAY_MS);
137
+ this._wsReconnectTimer = setTimeout(() => {
138
+ this._wsReconnectTimer = null;
139
+ if (!this._wsClosed) {
140
+ this._ensureWs();
141
+ }
142
+ }, delay);
143
+ }
144
+ /** Ensure WS is connected and ready. Lazy — connects on first use. */
145
+ async _ready() {
146
+ this._ensureWs();
147
+ if (this._wsReady)
148
+ await this._wsReady;
149
+ }
150
+ // ── RPC call method ─────────────────────────────────────────────────────
151
+ /**
152
+ * Send an RPC call over the WebSocket connection.
153
+ * @param type - The operation type (e.g. 'agent.get', 'perspective.all')
154
+ * @param params - Optional parameters to include in the message
155
+ * @returns Promise that resolves with the result from the server
156
+ */
157
+ async call(type, params) {
158
+ await this._ready();
159
+ const id = nextId();
160
+ // Put params under a "params" key to avoid collision with
161
+ // protocol fields "id" and "type" (e.g. params might contain
162
+ // { id: modelId } or { type: "db" }).
163
+ const message = { id, type, params: params || {} };
164
+ return new Promise((resolve, reject) => {
165
+ const timer = setTimeout(() => {
166
+ this._pendingCalls.delete(id);
167
+ reject(new RestError(408, `RPC call '${type}' timed out after ${DEFAULT_TIMEOUT_MS}ms`));
168
+ }, DEFAULT_TIMEOUT_MS);
169
+ this._pendingCalls.set(id, {
170
+ resolve: resolve,
171
+ reject,
172
+ timer,
173
+ });
174
+ if (this._ws && this._ws.readyState === WebSocket.OPEN) {
175
+ this._ws.send(JSON.stringify(message));
176
+ }
177
+ else {
178
+ this._pendingCalls.delete(id);
179
+ clearTimeout(timer);
180
+ reject(new RestError(503, 'WebSocket not connected'));
181
+ }
182
+ });
183
+ }
184
+ // ── Event subscriptions (same interface as before) ──────────────────────
185
+ subscribe(path, callback) {
186
+ this._wsCallbacks.add(callback);
187
+ this._ensureWs();
188
+ return () => {
189
+ this._wsCallbacks.delete(callback);
190
+ if (this._wsCallbacks.size === 0 && this._pendingCalls.size === 0) {
191
+ this._closeWs();
192
+ }
193
+ };
194
+ }
195
+ /** Wait until the WebSocket connection is established. */
196
+ async waitForSubscription(path) {
197
+ await this._ready();
198
+ }
199
+ // ── Explicit connection ─────────────────────────────────────────────────
200
+ /** Explicitly connect the WebSocket (optional — connection is lazy). */
201
+ connect() {
202
+ this._ensureWs();
203
+ }
204
+ _closeWs() {
205
+ this._stopPing();
206
+ if (this._wsReconnectTimer) {
207
+ clearTimeout(this._wsReconnectTimer);
208
+ this._wsReconnectTimer = null;
209
+ }
210
+ if (this._ws) {
211
+ this._wsClosed = true;
212
+ this._ws.close();
213
+ this._ws = null;
214
+ }
215
+ }
216
+ /** Close all open WebSocket connections and reject pending calls. */
217
+ closeAll() {
218
+ // Reject pending calls
219
+ for (const [id, pending] of this._pendingCalls) {
220
+ clearTimeout(pending.timer);
221
+ pending.reject(new RestError(503, 'Client closed'));
222
+ }
223
+ this._pendingCalls.clear();
224
+ this._closeWs();
225
+ this._wsCallbacks.clear();
226
+ }
227
+ }
@@ -0,0 +1,44 @@
1
+ /**
2
+ * SHACL-AF Node Expressions for property transforms.
3
+ *
4
+ * A `NodeExpression` is a JSON-serializable tree that describes how to transform
5
+ * a resolved property value. Unlike JS lambdas, these are portable, inspectable,
6
+ * and can be executed in the Rust model query engine.
7
+ *
8
+ * Each expression is a tagged union that evaluates to a `Value` (JSON-compatible).
9
+ */
10
+ /**
11
+ * Union type representing all supported transform expressions.
12
+ * Each variant maps to a SHACL-AF §6 expression construct.
13
+ */
14
+ export type NodeExpression = {
15
+ type: 'focus';
16
+ } | {
17
+ type: 'literal';
18
+ value: string | number | boolean;
19
+ } | {
20
+ type: 'path';
21
+ predicate: string;
22
+ } | {
23
+ type: 'exists';
24
+ expr: NodeExpression;
25
+ } | {
26
+ type: 'if';
27
+ cond: NodeExpression;
28
+ then: NodeExpression;
29
+ else?: NodeExpression;
30
+ } | {
31
+ type: 'concat';
32
+ args: NodeExpression[];
33
+ } | {
34
+ type: 'coalesce';
35
+ args: NodeExpression[];
36
+ } | {
37
+ type: 'function';
38
+ iri: string;
39
+ args: NodeExpression[];
40
+ };
41
+ /**
42
+ * Type guard to check if a value is a valid NodeExpression.
43
+ */
44
+ export declare function isNodeExpression(v: unknown): v is NodeExpression;
@@ -0,0 +1,39 @@
1
+ /**
2
+ * SHACL-AF Node Expressions for property transforms.
3
+ *
4
+ * A `NodeExpression` is a JSON-serializable tree that describes how to transform
5
+ * a resolved property value. Unlike JS lambdas, these are portable, inspectable,
6
+ * and can be executed in the Rust model query engine.
7
+ *
8
+ * Each expression is a tagged union that evaluates to a `Value` (JSON-compatible).
9
+ */
10
+ /**
11
+ * Type guard to check if a value is a valid NodeExpression.
12
+ */
13
+ export function isNodeExpression(v) {
14
+ if (typeof v !== 'object' || v === null)
15
+ return false;
16
+ const obj = v;
17
+ const type = obj.type;
18
+ switch (type) {
19
+ case 'focus':
20
+ return typeof obj.type === 'string';
21
+ case 'literal':
22
+ return typeof obj.value === 'string' || typeof obj.value === 'number' || typeof obj.value === 'boolean';
23
+ case 'path':
24
+ return typeof obj.predicate === 'string';
25
+ case 'exists':
26
+ return isNodeExpression(obj.expr);
27
+ case 'if':
28
+ return isNodeExpression(obj.cond) && isNodeExpression(obj.then) &&
29
+ (obj.else === undefined || isNodeExpression(obj.else));
30
+ case 'concat':
31
+ return Array.isArray(obj.args) && obj.args.every(isNodeExpression);
32
+ case 'coalesce':
33
+ return Array.isArray(obj.args) && obj.args.every(isNodeExpression);
34
+ case 'function':
35
+ return typeof obj.iri === 'string' && Array.isArray(obj.args) && obj.args.every(isNodeExpression);
36
+ default:
37
+ return false;
38
+ }
39
+ }
@@ -1,4 +1,5 @@
1
1
  import { Link } from "../links/Links";
2
+ import type { NodeExpression } from "./NodeExpression";
2
3
  /**
3
4
  * AD4M Action - represents a link operation
4
5
  */
@@ -76,6 +77,28 @@ export interface SHACLPropertyShape {
76
77
  value: string;
77
78
  label?: string;
78
79
  }>;
80
+ /** AD4M-specific: kind of relation this property describes.
81
+ * Drives direction (forward/reverse), scalar-vs-collection rendering,
82
+ * and default max-count. */
83
+ relationKind?: 'hasMany' | 'hasOne' | 'belongsToOne' | 'belongsToMany';
84
+ /** AD4M-specific: target class name (local-name) for a relation property.
85
+ * Complements `class` (the SHACL node-shape URI) by providing the bare
86
+ * model class name used by the executor to look up the target shape
87
+ * through the perspective's shape cache. */
88
+ targetClassName?: string;
89
+ /** AD4M-specific: post-getter where-clause filter for a relation property. */
90
+ whereFilter?: any;
91
+ /** AD4M-specific: predicate-IRI lookup map for `whereFilter` keys
92
+ * (property name → predicate URI on the target class). */
93
+ wherePredicates?: Record<string, string>;
94
+ /** AD4M-specific: whether conformance/type filtering is enabled for this
95
+ * relation. `false` opts out of DB-level type filtering while keeping
96
+ * hydration via `include`. */
97
+ filter?: boolean;
98
+ /** AD4M-specific: Transform expression (SHACL-AF Node Expression).
99
+ * Applied to resolved property values in the Rust model query engine.
100
+ * Only used for properties with resolveLanguage set. */
101
+ transform?: NodeExpression;
79
102
  }
80
103
  /**
81
104
  * SHACL Node Shape