@coasys/ad4m 0.10.0 → 0.10.1-dev-1

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 (64) hide show
  1. package/lib/index.cjs +3785 -843
  2. package/lib/index.js +3777 -839
  3. package/lib/src/Ad4mClient.js +2 -1
  4. package/lib/src/Literal.js +4 -1
  5. package/lib/src/ai/AIClient.d.ts +8 -2
  6. package/lib/src/ai/AIClient.js +25 -14
  7. package/lib/src/ai/AIResolver.d.ts +25 -6
  8. package/lib/src/ai/AIResolver.js +102 -18
  9. package/lib/src/index.d.ts +4 -3
  10. package/lib/src/index.js +4 -3
  11. package/lib/src/model/Ad4mModel.d.ts +730 -0
  12. package/lib/src/model/Ad4mModel.js +1399 -0
  13. package/lib/src/{subject → model}/Subject.d.ts +2 -2
  14. package/lib/src/{subject → model}/Subject.js +18 -18
  15. package/lib/src/model/decorators.d.ts +502 -0
  16. package/lib/src/model/decorators.js +683 -0
  17. package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +2 -2
  18. package/lib/src/neighbourhood/NeighbourhoodClient.js +13 -10
  19. package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +2 -2
  20. package/lib/src/neighbourhood/NeighbourhoodProxy.js +4 -4
  21. package/lib/src/neighbourhood/NeighbourhoodProxy.test.d.ts +1 -0
  22. package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +73 -0
  23. package/lib/src/neighbourhood/NeighbourhoodResolver.d.ts +2 -2
  24. package/lib/src/neighbourhood/NeighbourhoodResolver.js +6 -4
  25. package/lib/src/perspectives/PerspectiveClient.d.ts +23 -11
  26. package/lib/src/perspectives/PerspectiveClient.js +147 -51
  27. package/lib/src/perspectives/PerspectiveProxy.d.ts +494 -54
  28. package/lib/src/perspectives/PerspectiveProxy.js +684 -67
  29. package/lib/src/perspectives/PerspectiveResolver.d.ts +24 -9
  30. package/lib/src/perspectives/PerspectiveResolver.js +151 -46
  31. package/lib/src/runtime/RuntimeClient.d.ts +8 -2
  32. package/lib/src/runtime/RuntimeClient.js +64 -0
  33. package/lib/src/runtime/RuntimeResolver.d.ts +27 -1
  34. package/lib/src/runtime/RuntimeResolver.js +138 -0
  35. package/lib/src/schema.gql +55 -16
  36. package/lib/src/typeDefs.js +55 -16
  37. package/package.json +4 -3
  38. package/src/Ad4mClient.test.ts +51 -19
  39. package/src/Ad4mClient.ts +3 -1
  40. package/src/Literal.ts +4 -1
  41. package/src/ai/AIClient.ts +35 -14
  42. package/src/ai/AIResolver.ts +78 -16
  43. package/src/index.ts +4 -3
  44. package/src/model/Ad4mModel.ts +1651 -0
  45. package/src/{subject → model}/Subject.ts +16 -16
  46. package/src/{subject/SDNADecorators.ts → model/decorators.ts} +384 -50
  47. package/src/neighbourhood/NeighbourhoodClient.ts +13 -10
  48. package/src/neighbourhood/NeighbourhoodProxy.test.ts +100 -0
  49. package/src/neighbourhood/NeighbourhoodProxy.ts +4 -4
  50. package/src/neighbourhood/NeighbourhoodResolver.ts +2 -2
  51. package/src/perspectives/PerspectiveClient.ts +156 -51
  52. package/src/perspectives/PerspectiveProxy.ts +766 -82
  53. package/src/perspectives/PerspectiveResolver.ts +134 -23
  54. package/src/runtime/RuntimeClient.ts +71 -2
  55. package/src/runtime/RuntimeResolver.ts +91 -1
  56. package/lib/src/subject/SDNADecorators.d.ts +0 -188
  57. package/lib/src/subject/SDNADecorators.js +0 -360
  58. package/lib/src/subject/SubjectEntity.d.ts +0 -102
  59. package/lib/src/subject/SubjectEntity.js +0 -267
  60. package/src/subject/SubjectEntity.ts +0 -315
  61. package/yarn-error.log +0 -90
  62. /package/lib/src/{subject → model}/util.d.ts +0 -0
  63. /package/lib/src/{subject → model}/util.js +0 -0
  64. /package/src/{subject → model}/util.ts +0 -0
@@ -6,86 +6,462 @@ import { Perspective } from "./Perspective";
6
6
  import { ExpressionRendered } from "../expression/Expression";
7
7
  import { NeighbourhoodProxy } from "../neighbourhood/NeighbourhoodProxy";
8
8
  import { NeighbourhoodExpression } from "../neighbourhood/Neighbourhood";
9
+ import { AIClient } from "../ai/AIClient";
10
+ import { AllInstancesResult } from "../model/Ad4mModel";
11
+ type QueryCallback = (result: AllInstancesResult) => void;
12
+ /** Proxy object for a subscribed Prolog query that provides real-time updates
13
+ *
14
+ * This class handles:
15
+ * - Keeping the subscription alive by sending periodic keepalive signals
16
+ * - Managing callbacks for result updates
17
+ * - Subscribing to query updates via GraphQL subscriptions
18
+ * - Maintaining the latest query result
19
+ * - Ensuring subscription is fully initialized before allowing access
20
+ * - Cleaning up resources when disposed
21
+ *
22
+ * The subscription will remain active as long as keepalive signals are sent.
23
+ * Make sure to call dispose() when you're done with the subscription to clean up
24
+ * resources, stop keepalive signals, and notify the backend to remove the subscription.
25
+ *
26
+ * The subscription goes through an initialization process where it waits for the first
27
+ * result to come through the subscription channel. You can await the `initialized`
28
+ * promise to ensure the subscription is ready. The initialization will timeout after
29
+ * 30 seconds if no result is received.
30
+ *
31
+ * Example usage:
32
+ * ```typescript
33
+ * const subscription = await perspective.subscribeInfer("my_query(X)");
34
+ * // At this point the subscription is already initialized since subscribeInfer waits
35
+ *
36
+ * // Set up callback for future updates
37
+ * const removeCallback = subscription.onResult(result => {
38
+ * console.log("New result:", result);
39
+ * });
40
+ *
41
+ * // Later: clean up subscription and notify backend
42
+ * subscription.dispose();
43
+ * ```
44
+ */
45
+ export declare class QuerySubscriptionProxy {
46
+ #private;
47
+ /** Creates a new query subscription
48
+ * @param uuid - The UUID of the perspective
49
+ * @param query - The Prolog query to subscribe to
50
+ * @param client - The PerspectiveClient instance to use for communication
51
+ */
52
+ constructor(uuid: string, query: string, client: PerspectiveClient);
53
+ subscribe(): Promise<void>;
54
+ /** Get the subscription ID for this query subscription
55
+ *
56
+ * This is a unique identifier assigned when the subscription was created.
57
+ * It can be used to reference this specific subscription, for example when
58
+ * sending keepalive signals.
59
+ *
60
+ * @returns The subscription ID string
61
+ */
62
+ get id(): string;
63
+ /** Promise that resolves when the subscription has received its first result
64
+ * through the subscription channel. This ensures the subscription is fully
65
+ * set up before allowing access to results or updates.
66
+ *
67
+ * The promise will reject if no result is received within 30 seconds.
68
+ *
69
+ * Note: You typically don't need to await this directly since the subscription
70
+ * creation methods (like subscribeInfer) already wait for initialization.
71
+ */
72
+ get initialized(): Promise<boolean>;
73
+ /** Get the latest query result
74
+ *
75
+ * This returns the most recent result from the query, which could be either:
76
+ * - The initial result from when the subscription was created
77
+ * - The latest update received through the subscription
78
+ *
79
+ * @returns The latest query result as a string (usually a JSON array of bindings)
80
+ */
81
+ get result(): AllInstancesResult;
82
+ /** Add a callback that will be called whenever new results arrive
83
+ *
84
+ * The callback will be called immediately with the current result,
85
+ * and then again each time the query results change.
86
+ *
87
+ * @param callback - Function that takes a result string and processes it
88
+ * @returns A function that can be called to remove this callback
89
+ *
90
+ * Example:
91
+ * ```typescript
92
+ * const removeCallback = subscription.onResult(result => {
93
+ * const bindings = JSON.parse(result);
94
+ * console.log("New bindings:", bindings);
95
+ * });
96
+ *
97
+ * // Later: stop receiving updates
98
+ * removeCallback();
99
+ * ```
100
+ */
101
+ onResult(callback: QueryCallback): () => void;
102
+ /** Clean up the subscription and stop keepalive signals
103
+ *
104
+ * This method:
105
+ * 1. Stops the keepalive timer
106
+ * 2. Unsubscribes from GraphQL subscription updates
107
+ * 3. Clears all registered callbacks
108
+ * 4. Cleans up any pending initialization timeout
109
+ *
110
+ * After calling this method, the subscription is no longer active and
111
+ * will not receive any more updates. The instance should be discarded.
112
+ */
113
+ dispose(): void;
114
+ }
9
115
  type PerspectiveListenerTypes = "link-added" | "link-removed" | "link-updated";
10
116
  export type LinkStatus = "shared" | "local";
11
117
  interface Parameter {
12
118
  name: string;
13
119
  value: string;
14
120
  }
15
- /** Perspective UI proxy object
121
+ /**
122
+ * PerspectiveProxy provides a high-level interface for working with AD4M Perspectives - agent-centric semantic graphs
123
+ * that store and organize links between expressions.
124
+ *
125
+ * A Perspective is fundamentally a collection of links (subject-predicate-object triples) that represent an agent's view
126
+ * of their digital world. Through PerspectiveProxy, you can:
127
+ * - Add, remove, and query links
128
+ * - Work with Social DNA (subject classes and flows)
129
+ * - Subscribe to real-time updates
130
+ * - Share perspectives as Neighbourhoods
131
+ * - Execute Prolog queries for complex graph patterns
132
+ *
133
+ *
134
+ * @example
135
+ * ```typescript
136
+ * // Create and work with links
137
+ * const perspective = await ad4m.perspective.add("My Space");
138
+ * await perspective.add({
139
+ * source: "did:key:alice",
140
+ * predicate: "knows",
141
+ * target: "did:key:bob"
142
+ * });
16
143
  *
17
- * Convenience object for UIs to interact with a perspective.
18
- * It is created by some of the methods in the PerspectiveClient class and includes
19
- * a reference to the PerspectiveClient object that created it.
144
+ * // Query links
145
+ * const friends = await perspective.get({
146
+ * source: "did:key:alice",
147
+ * predicate: "knows"
148
+ * });
149
+ *
150
+ * // Use Social DNA
151
+ * await perspective.addSdna(todoClass, "subject_class");
152
+ * const todo = await perspective.createSubject("Todo", "expression://123");
153
+ *
154
+ * // Subscribe to changes
155
+ * perspective.addListener("link-added", (link) => {
156
+ * console.log("New link added:", link);
157
+ * });
158
+ * ```
20
159
  */
21
160
  export declare class PerspectiveProxy {
22
161
  #private;
23
- /** Unique ID of the perspective */
162
+ /** Unique identifier of this perspective */
24
163
  uuid: string;
25
- /** Given name of the perspective */
164
+ /** Human-readable name of this perspective */
26
165
  name: string;
27
- /** If the perspective is shared as a Neighbourhood, this is the Neighbourhood URL */
166
+ /** If this perspective is shared as a Neighbourhood, this is its URL */
28
167
  sharedUrl: string | null;
29
- /** If the perspective is shared as a Neighbourhood, this is the Neighbourhood Expression */
168
+ /** If this perspective is shared, this contains the Neighbourhood metadata */
30
169
  neighbourhood: NeighbourhoodExpression | null;
31
- /** Returns the state of the perspective **/
170
+ /** Current sync state if this perspective is shared */
32
171
  state: PerspectiveState | null;
172
+ /**
173
+ * Creates a new PerspectiveProxy instance.
174
+ * Note: Don't create this directly, use ad4m.perspective.add() instead.
175
+ */
33
176
  constructor(handle: PerspectiveHandle, ad4m: PerspectiveClient);
34
- executeAction(actions: any, expression: any, parameters: Parameter[]): Promise<boolean>;
35
- /** Returns all the links of this perspective that matches the LinkQuery */
177
+ /**
178
+ * Executes a set of actions on an expression with optional parameters.
179
+ * Used internally by Social DNA flows and subject class operations.
180
+ *
181
+ * Actions are specified as an array of commands that modify links in the perspective.
182
+ * Each action is an object with the following format:
183
+ * ```typescript
184
+ * {
185
+ * action: "addLink" | "removeLink" | "setSingleTarget" | "collectionSetter",
186
+ * source: string, // Usually "this" to reference the current expression
187
+ * predicate: string, // The predicate URI
188
+ * target: string // The target value or "value" for parameters
189
+ * }
190
+ * ```
191
+ *
192
+ * Available commands:
193
+ * - `addLink`: Creates a new link
194
+ * - `removeLink`: Removes an existing link
195
+ * - `setSingleTarget`: Removes all existing links with the same source/predicate and adds a new one
196
+ * - `collectionSetter`: Special command for setting collection properties
197
+ *
198
+ * When used with parameters, the special value "value" in the target field will be
199
+ * replaced with the actual parameter value.
200
+ *
201
+ * @example
202
+ * ```typescript
203
+ * // Add a state link and remove an old one
204
+ * await perspective.executeAction([
205
+ * {
206
+ * action: "addLink",
207
+ * source: "this",
208
+ * predicate: "todo://state",
209
+ * target: "todo://doing"
210
+ * },
211
+ * {
212
+ * action: "removeLink",
213
+ * source: "this",
214
+ * predicate: "todo://state",
215
+ * target: "todo://ready"
216
+ * }
217
+ * ], "expression://123");
218
+ *
219
+ * // Set a property using a parameter
220
+ * await perspective.executeAction([
221
+ * {
222
+ * action: "setSingleTarget",
223
+ * source: "this",
224
+ * predicate: "todo://title",
225
+ * target: "value"
226
+ * }
227
+ * ], "expression://123", [
228
+ * { name: "title", value: "New Title" }
229
+ * ]);
230
+ * ```
231
+ *
232
+ * @param actions - Array of action objects to execute
233
+ * @param expression - Target expression address (replaces "this" in actions)
234
+ * @param parameters - Optional parameters that replace "value" in actions
235
+ * @param batchId - Optional batch ID to group this operation with others
236
+ */
237
+ executeAction(actions: any, expression: any, parameters: Parameter[], batchId?: string): Promise<boolean>;
238
+ /**
239
+ * Retrieves links from the perspective that match the given query.
240
+ *
241
+ * @param query - Query parameters to filter links
242
+ * @returns Array of matching LinkExpressions
243
+ *
244
+ * @example
245
+ * ```typescript
246
+ * // Get all links where Alice knows someone
247
+ * const links = await perspective.get({
248
+ * source: "did:key:alice",
249
+ * predicate: "knows"
250
+ * });
251
+ *
252
+ * // Get all comments on a post
253
+ * const comments = await perspective.get({
254
+ * source: "post://123",
255
+ * predicate: "comment"
256
+ * });
257
+ * ```
258
+ */
36
259
  get(query: LinkQuery): Promise<LinkExpression[]>;
37
- /** Runs a Prolog query on the perspective's Prolog engine */
260
+ /**
261
+ * Executes a Prolog query against the perspective's knowledge base.
262
+ * This is a powerful way to find complex patterns in the graph.
263
+ *
264
+ * @param query - Prolog query string
265
+ * @returns Query results or false if no results
266
+ *
267
+ * @example
268
+ * ```typescript
269
+ * // Find friends of friends
270
+ * const results = await perspective.infer(`
271
+ * triple(A, "knows", B),
272
+ * triple(B, "knows", C),
273
+ * A \= C
274
+ * `);
275
+ *
276
+ * // Find all active todos
277
+ * const todos = await perspective.infer(`
278
+ * instance(Todo, "Todo"),
279
+ * property_getter("Todo", Todo, "state", "active")
280
+ * `);
281
+ * ```
282
+ */
38
283
  infer(query: string): Promise<any>;
39
- /** Adds a link to this perspective */
40
- add(link: Link, status?: LinkStatus): Promise<LinkExpression>;
41
- /** Adds multiple links to this perspective **/
42
- addLinks(links: Link[], status?: LinkStatus): Promise<LinkExpression[]>;
43
- /** Removes multiple links from this perspective **/
44
- removeLinks(links: LinkExpressionInput[]): Promise<LinkExpression[]>;
45
- /** Adds and removes multiple links from this perspective **/
284
+ /**
285
+ * Adds a new link to the perspective.
286
+ *
287
+ * @param link - The link to add
288
+ * @param status - Whether the link should be shared in a Neighbourhood
289
+ * @param batchId - Optional batch ID to group this operation with others
290
+ * @returns The created LinkExpression
291
+ *
292
+ * @example
293
+ * ```typescript
294
+ * // Add a simple relationship
295
+ * await perspective.add({
296
+ * source: "did:key:alice",
297
+ * predicate: "follows",
298
+ * target: "did:key:bob"
299
+ * });
300
+ *
301
+ * // Add a local-only link
302
+ * await perspective.add({
303
+ * source: "note://123",
304
+ * predicate: "tag",
305
+ * target: "private"
306
+ * }, "local");
307
+ * ```
308
+ */
309
+ add(link: Link, status?: LinkStatus, batchId?: string): Promise<LinkExpression>;
310
+ /**
311
+ * Adds multiple links to the perspective in a single operation.
312
+ * More efficient than adding links one by one.
313
+ *
314
+ * @param links - Array of links to add
315
+ * @param status - Whether the links should be shared
316
+ * @param batchId - Optional batch ID to group this operation with others
317
+ * @returns Array of created LinkExpressions
318
+ */
319
+ addLinks(links: Link[], status?: LinkStatus, batchId?: string): Promise<LinkExpression[]>;
320
+ /**
321
+ * Removes multiple links from the perspective.
322
+ *
323
+ * @param links - Array of links to remove
324
+ * @param batchId - Optional batch ID to group this operation with others
325
+ * @returns Array of removed LinkExpressions
326
+ */
327
+ removeLinks(links: LinkExpressionInput[], batchId?: string): Promise<LinkExpression[]>;
328
+ /**
329
+ * Applies a set of link mutations (adds and removes) in a single operation.
330
+ * Useful for atomic updates to the perspective.
331
+ *
332
+ * @param mutations - Object containing links to add and remove
333
+ * @param status - Whether new links should be shared
334
+ * @returns Object containing results of the mutations
335
+ */
46
336
  linkMutations(mutations: LinkMutations, status?: LinkStatus): Promise<LinkExpressionMutations>;
47
- /** Adds a linkExpression to this perspective */
48
- addLinkExpression(link: LinkExpression, status?: LinkStatus): Promise<LinkExpression>;
49
- update(oldLink: LinkExpressionInput, newLink: Link): Promise<LinkExpression>;
50
- remove(link: LinkExpressionInput): Promise<{
51
- perspectiveRemoveLink: boolean;
52
- }>;
337
+ /**
338
+ * Adds a pre-signed LinkExpression to the perspective.
339
+ *
340
+ * @param link - The signed LinkExpression to add
341
+ * @param status - Whether the link should be shared
342
+ * @param batchId - Optional batch ID to group this operation with others
343
+ * @returns The added LinkExpression
344
+ */
345
+ addLinkExpression(link: LinkExpression, status?: LinkStatus, batchId?: string): Promise<LinkExpression>;
346
+ /**
347
+ * Updates an existing link with new data.
348
+ *
349
+ * @param oldLink - The existing link to update
350
+ * @param newLink - The new link data
351
+ * @param batchId - Optional batch ID to group this operation with others
352
+ */
353
+ update(oldLink: LinkExpressionInput, newLink: Link, batchId?: string): Promise<LinkExpression>;
354
+ /**
355
+ * Removes a link from the perspective.
356
+ *
357
+ * @param link - The link to remove
358
+ * @param batchId - Optional batch ID to group this operation with others
359
+ */
360
+ remove(link: LinkExpressionInput, batchId?: string): Promise<boolean>;
361
+ /** Creates a new batch for grouping operations */
362
+ createBatch(): Promise<string>;
363
+ /** Commits a batch of operations */
364
+ commitBatch(batchId: string): Promise<LinkExpressionMutations>;
365
+ /**
366
+ * Retrieves and renders an Expression referenced in this perspective.
367
+ *
368
+ * @param expressionURI - URI of the Expression to retrieve
369
+ * @returns The rendered Expression
370
+ */
53
371
  getExpression(expressionURI: string): Promise<ExpressionRendered>;
372
+ /**
373
+ * Creates a new Expression in the specified Language.
374
+ *
375
+ * @param content - Content for the new Expression
376
+ * @param languageAddress - Address of the Language to use
377
+ * @returns URI of the created Expression
378
+ */
54
379
  createExpression(content: any, languageAddress: string): Promise<string>;
55
- /** Adds a link listener
56
- * @param type Can be 'link-added' or 'link-removed'
57
- * @param cb Callback function that is called when a link is added to the perspective
380
+ /**
381
+ * Subscribes to link changes in the perspective.
382
+ *
383
+ * @param type - Type of change to listen for
384
+ * @param cb - Callback function
385
+ *
386
+ * @example
387
+ * ```typescript
388
+ * // Listen for new links
389
+ * perspective.addListener("link-added", (link) => {
390
+ * console.log("New link:", link);
391
+ * });
392
+ *
393
+ * // Listen for removed links
394
+ * perspective.addListener("link-removed", (link) => {
395
+ * console.log("Link removed:", link);
396
+ * });
397
+ * ```
58
398
  */
59
399
  addListener(type: PerspectiveListenerTypes, cb: LinkCallback): Promise<void>;
60
- /** Adds a sync state listener
61
- * @param cb Callback function that is called when the sync state of the perspective changes
62
- * @returns A function that can be called to remove the listener
400
+ /**
401
+ * Subscribes to sync state changes if this perspective is shared.
402
+ *
403
+ * @param cb - Callback function
404
+ *
405
+ * @example
406
+ * ```typescript
407
+ * perspective.addSyncStateChangeListener((state) => {
408
+ * console.log("Sync state:", state);
409
+ * });
410
+ * ```
63
411
  */
64
412
  addSyncStateChangeListener(cb: SyncStateChangeCallback): Promise<void>;
65
- /** Removes a previously added link listener
66
- * @param type Can be 'link-added' or 'link-removed'
67
- * @param cb Callback function that is called when a link is added to the perspective
413
+ /**
414
+ * Unsubscribes from link changes.
415
+ *
416
+ * @param type - Type of change to stop listening for
417
+ * @param cb - The callback function to remove
68
418
  */
69
419
  removeListener(type: PerspectiveListenerTypes, cb: LinkCallback): Promise<void>;
70
- /** Create and return a snapshot of this perspective
71
- * A snapshot is a rendered Perspectie object that contains all the links of the perspective.
420
+ /**
421
+ * Creates a snapshot of the current perspective state.
422
+ * Useful for backup or sharing.
423
+ *
424
+ * @returns Perspective object containing all links
72
425
  */
73
426
  snapshot(): Promise<Perspective>;
74
- /** Take and load all the links from the given snapshot */
427
+ /**
428
+ * Loads a perspective snapshot, replacing current content.
429
+ *
430
+ * @param snapshot - Perspective snapshot to load
431
+ */
75
432
  loadSnapshot(snapshot: Perspective): Promise<void>;
76
- /** Convenience function to get the target of the first link that matches the given query
77
- * This makes sense when the query is expected to return only one link
78
- * and the target of that link is what you are looking for.
433
+ /**
434
+ * Gets a single target value matching a query.
435
+ * Useful when you expect only one result.
436
+ *
437
+ * @param query - Query to find the target
438
+ * @returns Target value or void if not found
79
439
  *
80
- * Works best together with @member setSingelTarget()
440
+ * @example
441
+ * ```typescript
442
+ * // Get a user's name
443
+ * const name = await perspective.getSingleTarget({
444
+ * source: "did:key:alice",
445
+ * predicate: "name"
446
+ * });
447
+ * ```
81
448
  */
82
449
  getSingleTarget(query: LinkQuery): Promise<string | void>;
83
- /** Convenience function to ensure there is only one link with given source and predicate
84
- * This function will remove all links with the same source and predicate as the given link,
85
- * and then add the given link.
86
- * This ensures there is only one target for the given source and predicate.
450
+ /**
451
+ * Sets a single target value, removing any existing targets.
87
452
  *
88
- * Works best together with @member getSingleTarget()
453
+ * @param link - Link defining the new target
454
+ * @param status - Whether the link should be shared
455
+ *
456
+ * @example
457
+ * ```typescript
458
+ * // Set a user's status
459
+ * await perspective.setSingleTarget({
460
+ * source: "did:key:alice",
461
+ * predicate: "status",
462
+ * target: "online"
463
+ * });
464
+ * ```
89
465
  */
90
466
  setSingleTarget(link: Link, status?: LinkStatus): Promise<void>;
91
467
  /** Returns all the Social DNA flows defined in this perspective */
@@ -106,21 +482,28 @@ export declare class PerspectiveProxy {
106
482
  * This will return all SDNA code elements in an array.
107
483
  */
108
484
  getSdna(): Promise<string[]>;
485
+ /** Returns the Social DNA code for a specific class
486
+ * This will return the SDNA code for the specified class, or null if not found.
487
+ */
488
+ getSdnaForClass(className: string): Promise<string | null>;
109
489
  /** Adds the given Social DNA code to the perspective's SDNA code */
110
490
  addSdna(name: string, sdnaCode: string, sdnaType: "subject_class" | "flow" | "custom"): Promise<boolean>;
111
491
  /** Returns all the Subject classes defined in this perspectives SDNA */
112
492
  subjectClasses(): Promise<string[]>;
113
- stringOrTemplateObjectToSubjectClass<T>(subjectClass: T): Promise<string>;
114
- /** Creates a new subject instance by running its (SDNA defined) constructor,
115
- * which means adding links around the given expression address so that it
116
- * conforms to the given subject class.
493
+ stringOrTemplateObjectToSubjectClassName<T>(subjectClass: T): Promise<string>;
494
+ /**
495
+ * Creates a new subject instance of the given subject class
117
496
  *
118
497
  * @param subjectClass Either a string with the name of the subject class, or an object
119
- * with the properties of the subject class. In the latter case, the first subject class
120
- * that matches the given properties will be used.
498
+ * with the properties of the subject class.
121
499
  * @param exprAddr The address of the expression to be turned into a subject instance
500
+ * @param initialValues Optional initial values for properties. If provided, these will be
501
+ * merged with constructor actions for better performance.
502
+ * @param batchId Optional batch ID for grouping operations. If provided, returns the expression address
503
+ * instead of the subject proxy since the subject won't exist until the batch is committed.
504
+ * @returns A proxy object for the created subject, or just the expression address if in batch mode
122
505
  */
123
- createSubject<T>(subjectClass: T, exprAddr: string): Promise<T>;
506
+ createSubject<T, B extends string | undefined = undefined>(subjectClass: T, exprAddr: string, initialValues?: Record<string, any>, batchId?: B): Promise<B extends undefined ? T : string>;
124
507
  getSubjectData<T>(subjectClass: T, exprAddr: string): Promise<T>;
125
508
  /** Removes a subject instance by running its (SDNA defined) destructor,
126
509
  * which means removing links around the given expression address
@@ -129,8 +512,10 @@ export declare class PerspectiveProxy {
129
512
  * with the properties of the subject class. In the latter case, the first subject class
130
513
  * that matches the given properties will be used.
131
514
  * @param exprAddr The address of the expression to be turned into a subject instance
515
+ * @param batchId Optional batch ID for grouping operations. If provided, the removal will be part of the batch
516
+ * and won't be executed until the batch is committed.
132
517
  */
133
- removeSubject<T>(subjectClass: T, exprAddr: string): Promise<void>;
518
+ removeSubject<T>(subjectClass: T, exprAddr: string, batchId?: string): Promise<void>;
134
519
  /** Checks if the given expression is a subject instance of the given subject class
135
520
  * @param expression The expression to be checked
136
521
  * @param subjectClass Either a string with the name of the subject class, or an object
@@ -181,5 +566,60 @@ export declare class PerspectiveProxy {
181
566
  */
182
567
  ensureSDNASubjectClass(jsClass: any): Promise<void>;
183
568
  getNeighbourhoodProxy(): NeighbourhoodProxy;
569
+ /**
570
+ * Returns a proxy object for working with AI capabilities.
571
+ *
572
+ * @returns AIClient instance
573
+ *
574
+ * @example
575
+ * ```typescript
576
+ * // Use AI to analyze perspective content
577
+ * const summary = await perspective.ai.summarize();
578
+ *
579
+ * // Generate new content
580
+ * const suggestion = await perspective.ai.suggest("next action");
581
+ * ```
582
+ */
583
+ get ai(): AIClient;
584
+ /**
585
+ * Creates a subscription for a Prolog query that updates in real-time.
586
+ *
587
+ * This method:
588
+ * 1. Creates the subscription on the Rust side
589
+ * 2. Sets up the subscription callback
590
+ * 3. Waits for the initial result to come through the subscription channel
591
+ * 4. Returns a fully initialized QuerySubscriptionProxy
592
+ *
593
+ * The returned subscription is guaranteed to be ready to receive updates,
594
+ * as this method waits for the initialization process to complete.
595
+ *
596
+ * The subscription will be automatically cleaned up on both frontend and backend
597
+ * when dispose() is called. Make sure to call dispose() when you're done to
598
+ * prevent memory leaks and ensure proper cleanup of resources.
599
+ *
600
+ * @param query - Prolog query string
601
+ * @returns Initialized QuerySubscriptionProxy instance
602
+ *
603
+ * @example
604
+ * ```typescript
605
+ * // Subscribe to active todos
606
+ * const subscription = await perspective.subscribeInfer(`
607
+ * instance(Todo, "Todo"),
608
+ * property_getter("Todo", Todo, "state", "active")
609
+ * `);
610
+ *
611
+ * // Subscription is already initialized here
612
+ * console.log("Initial result:", subscription.result);
613
+ *
614
+ * // Set up callback for future updates
615
+ * subscription.onResult((todos) => {
616
+ * console.log("Active todos:", todos);
617
+ * });
618
+ *
619
+ * // Clean up subscription when done
620
+ * subscription.dispose();
621
+ * ```
622
+ */
623
+ subscribeInfer(query: string): Promise<QuerySubscriptionProxy>;
184
624
  }
185
625
  export {};