@libertas-ai/types 0.1.1 → 0.1.3

package/index.d.ts

@@ -47,7 +47,7 @@ declare type LibertasLanDevice = number;
 /** 
  * A virtual device. The behaviors of the device are managed by application code. 
  * 
- * Virtual devices interact with the user during the runtime of Thing-App tasks.
+ * Virtual devices interact with the user during the runtime of Libertas App tasks.
  * 
  * @see [Virtual Device API](/doc/developers_doc/virtual_device_api/)
  * @see {@link libertasVirtualDeviceCommandRsp}
@@ -79,10 +79,10 @@ declare type LibertasUser = number;
 declare type LibertasAction = number;
 
 /**
- * Specialized virtual device for agent/tool interactions.
+ * Specialized virtual device for endpoint interactions.
  * Data schema must be predefined and published by the server developer.
  */
-declare type LibertasAgentTool = LibertasVirtualDevice;
+declare type LibertasEndpoint = LibertasVirtualDevice;
 
 /**
  * A handle to an indexed database table.
@@ -90,9 +90,9 @@ declare type LibertasAgentTool = LibertasVirtualDevice;
 declare type LibertasDataStore = number;
 
 /**
- * Used to send broadcast data report in {@link libertasAgentToolSendResponse}. It should be 0xffffffff.
+ * Used to send broadcast data report in {@link libertasEndpointSendResponse}. It should be 0xffffffff.
  */
-declare const enum LibertasPeer {
+declare enum LibertasPeer {
     Broadcast = 0xffffffff,
 }
 
@@ -105,7 +105,7 @@ declare const enum LibertasPeer {
  * @see {@link LibertasVirtualDeviceCallback}
  * 
  */
-declare const enum LibertasDeviceAction {
+declare enum LibertasDeviceAction {
     StatusResponse        = 0x01,
     ReadRequest           = 0x02,
     SubscribeRequest      = 0x03,
@@ -234,7 +234,7 @@ declare type LibertasCommand = [cluster: number, id: number, data?: LibertasStru
 declare type LibertasClusterAttributes = [cluster: number, attributes: LibertasAttributes];
 
 /**
- * A tuple representing a read request from a Thing-App task.
+ * A tuple representing a read request from a Libertas App task.
  * 
  * @see {@link LibertasVirtualDeviceReq}
  * @see {@link libertasDeviceReadReq}
@@ -261,7 +261,7 @@ declare type LibertasClusterReadReq = [cluster: number, attributes: number[], ev
  * 
  * The effective minInterval and maxInterval may differ due to the varying requirements of multiple agents and device settings.
  * 
- * The maxInterval affects the report timeout. The underlying Libertas OS performs timeout detection. The Thing-App task can keep idling until a report or error occurs.
+ * The maxInterval affects the report timeout. The underlying Libertas OS performs timeout detection. The Libertas App task can keep idling until a report or error occurs.
  */
 declare type LibertasClusterSubscribeReq = [cluster: number, minInterval: number, maxInterval: number, attributes: number[], events?: LibertasClusterEventSubscription ];
 
@@ -350,55 +350,55 @@ declare type LibertasDeviceRsp = LibertasCommandRsp | LibertasClusterWriteRsp[]
 declare type LibertasDeviceCallback = (device: LibertasDevice, action: LibertasDeviceAction, data: LibertasDeviceRsp, tag?: any, ref?: number) => void;
 
 /**
- * Possible interactions of an agent tool connection.
+ * Possible interactions of an endpoint connection.
  */
-declare const enum LibertasAgentToolAction {
-    /// Agent/tool subscription request opcode.
+declare enum LibertasEndpointAction {
+    /// endpoint subscription request opcode.
     SubscriptionRequest = 3,
-    /// Agent/tool data message opcode.
+    /// endpoint data message opcode.
     ReportData = 5,
-    /// Agent/tool request opcode (expects response).
+    /// endpoint request opcode (expects response).
     Request = 8,
-    /// Agent/tool response opcode.
+    /// endpoint response opcode.
     Response = 9,
-    /// Agent/tool peer down notification opcode.
+    /// endpoint peer down notification opcode.
     PeerDown = 20,
 }
 
 /**
  * The signature of a virtual device I/O callback function.
  * 
- * @param device A {@link LibertasDevice}.
- * @param ref The reference number of the original request. See remarks.
+ * @param device A {@link LibertasVirtualDevice}.
+ * @param peer Uniquely identifies a peer as subscription ID. See remarks.
+ * @param transId The transaction Id of the original request. See remarks.
  * @param action The {@link LibertasDeviceAction}. See remarks
  * @param data The request data. It's a union type. The value shall be cast to a type decided by action.
  * @param tag The arbitrary data passed to {@link libertasSetOnVirtualDevice} with the callback instance.
- * @param peer Uniquely identifies a peer as subscription ID. See remarks.
  * 
  * @see {@link libertasSetOnVirtualDevice}
  * 
- * @remarks The callback is used to notify the virtual device of a request. Each request has an internally assigned ref number by the engine. 
- * The ref number must be passed back in the corresponding response.
+ * @remarks The callback is used to notify the virtual device of a request. Each request has an internally assigned transaction ID (transId) by the engine. 
+ * The transId must be passed back in the corresponding response.
  * 
  * Valid actions:
  * {@link LibertasDeviceAction.ReadRequest}, {@link LibertasDeviceAction.SubscribeRequest}, and {@link LibertasDeviceAction.ReportData} all request attribute data. {@link LibertasDeviceAction.ReadRequest}
  * is a one-time read. {@link LibertasDeviceAction.SubscribeRequest} is an initial subscribe request. {@link LibertasDeviceAction.ReportData} is for 
- * continuous subscription data report. Combined with `peer`, the Thing-App can keep track of current subscribers. The Thing-App can also keep the last subscription related request time to 
+ * continuous subscription data report. Combined with `peer`, the Libertas App can keep track of current subscribers. The Libertas App can also keep the last subscription related request time to 
  * calculate interval duration for more flexible subscrption delivery. A virtual device may even respond more data than requested if the common dirty-marking algorithm is not adequate.
  */
 
-declare type LibertasVirtualDeviceCallback = (device: LibertasVirtualDevice, ref: number, action: LibertasDeviceAction, data: LibertasVirtualDeviceReq, tag?: any, peer?: number) => void;
+declare type LibertasVirtualDeviceCallback = (device: LibertasVirtualDevice, peer: number, transId: number, action: LibertasDeviceAction, data: LibertasVirtualDeviceReq, tag?: any) => void;
 
 /**
- * Callback of an agent tool connection.
- * @param device A LibertasAgentTool client or server.
+ * Callback of an endpoint connection.
+ * @param device A LibertasEndpoint client or server.
  * @param action interaction action.
  * @param peer The peer that protocol from which message comes.
- * @param tag The arbitrary data passed to {@link libertasSetOnAgentTool} with the callback instance.
+ * @param tag The arbitrary data passed to {@link libertasSetOnEndpoint} with the callback instance.
  * @param data The protocol message, or undefined if `action` is `PeerDown`.
  * @param ref The transaction Id. May be undefined if this is unsolicited `ReportData`.
  */
-declare type LibertasAgentToolCallback<T> = (device: LibertasAgentTool, action: LibertasAgentToolAction, peer: number, tag: any, data?: T, ref?: number) => void;
+declare type LibertasEndpointCallback<T> = (device: LibertasEndpoint, action: LibertasEndpointAction, peer: number, tag: any, data?: T, ref?: number) => void;
 
 /**
  * Set a callback function to receive responses and reports to a device.
@@ -475,7 +475,7 @@ declare function libertasDeviceReadReq(device: LibertasDevice, requests: Liberta
  * {@link LibertasDeviceAction.StatusResponse} with a {@link Matter.Status.Timeout} will be received from the callback registered with 
  * {@link libertasSetOnDevice}.
  * 
- * The Thing-App task shall not assume that it is the only process that sends requests. Other agents
+ * The Libertas App task shall not assume that it is the only process that sends requests. Other agents
  * may also send requests. A task can only receive {@link LibertasClusterWriteRsp} to its written requests. 
  * 
  * To receive all changes to an attribute, use {@link libertasAppSubscribeReq}.
@@ -510,7 +510,7 @@ declare function libertasDeviceWriteReq(device: LibertasDevice, requests: Libert
  * {@link LibertasDeviceAction.StatusResponse} with a {@link Matter.Status.Timeout} will be received from the callback registered with 
  * {@link libertasSetOnDevice}.
  * 
- * The Thing-App task shall not assume that it is the only process that sends requests. Other agents
+ * The Libertas App task shall not assume that it is the only process that sends requests. Other agents
  * may also send requests. A task can only receive the {@link LibertasCommandRsp} to its command requests. 
  * 
  * To receive all changes to an attribute, use {@link libertasAppSubscribeReq}.
@@ -531,10 +531,10 @@ declare function libertasDeviceCommandReq(device: LibertasDevice, request: Liber
  * @remarks
  * An app only sends out one subscription request. The App must collect the list of all devices that require subscriptions and send them out all at once.
  * 
- * Because the Thing-App shares subscriptions with the host and possibly other Thing-Apps, the following behaviors may be observed:
+ * Because the Libertas App shares subscriptions with the host and possibly other Libertas Apps, the following behaviors may be observed:
  * 
  * 1. The first few data reports may be in response to ReadRequest.
- * 2. The data reports may contain attributes and events that are not subscribed to by this Thing-App.
+ * 2. The data reports may contain attributes and events that are not subscribed to by this Libertas App.
  * 3. Libertas-OS will handle errors, including timeout. A StatusResponse report will be generated in case of errors.
  * 
  * The report data will be passed to the callback function {@link LibertasDeviceCallback} registered with {@link libertasSetOnDevice}.
@@ -542,16 +542,16 @@ declare function libertasDeviceCommandReq(device: LibertasDevice, request: Liber
 declare function libertasAppSubscribeReq(requests: LibertasDeviceSubscribeReq[]) : void;
 
 /**
- * Notify the Libertas Thing-App engine that some attributes have changed values.
+ * Notify the Libertas Libertas App engine that some attributes have changed values.
  * @param device A {@link LibertasVirtualDevice}.
  * @param attributes The list of cluster attribute IDs. We reuse the {@link LibertasClusterReadReq} structure to hold the required data.
  * Note that the event field is always undefined because Libertas OS handles the event reports. 
  * @param peer The subscription ID, which can be inferred from the peer in earlier {@link LibertasVirtualDeviceCallback}. Usually it should be undefined, unless
- * the Thing-App needs to manage data report for each individual subscriber.
+ * the Libertas App needs to manage data report for each individual subscriber.
  * 
- * @remarks The Thing-App engine is responsible for reporting each subscription based on the subscribed attributes, events, and minimum/maximum intervals.
+ * @remarks The Libertas App engine is responsible for reporting each subscription based on the subscribed attributes, events, and minimum/maximum intervals.
  * Even if the virtual device reported the changes, the report may not be generated immediately if the minimum interval has not been reached.
- * Also, when the Libertas Thing-App engine decides to generate a report, it will send a {@link LibertasDeviceAction.ReadRequest} or 
+ * Also, when the Libertas Libertas App engine decides to generate a report, it will send a {@link LibertasDeviceAction.ReadRequest} or 
  * {@link LibertasDeviceAction.SubscribeRequest} with an array of {@link LibertasClusterReadReq} for the up-to-date values of the specified
  * attributes and expect a response from {@link libertasVirtualDeviceAttributesRsp} call. If this value is defined, the notification will 
  * only be delivered to a single subscriber.
@@ -570,40 +570,44 @@ declare function libertasVirtualDeviceUpdateEvents(device: LibertasVirtualDevice
 /**
  * Update attributes unsolicited, or in response to a ReadRequest or SubscribeRequest.
  * @param device A {@link LibertasVirtualDevice}.
- * @param ref The ref number of the request.
+ * @param peer The peer taskId.
+ * @param transId The transaction Id of the request.
  * @param attributes An array of {@link LibertasClusterReport}. Note that the events and eventStatus are undefined. Use {@link libertasVirtualDeviceUpdateEvents} to write events.
  * 
  * @remarks
  * The framework will maintain a cache of all attributes.
  * 
- * If a ref number is present, a read response or a report in response to this referenced request will be immediately sent out;
+ * If a transId is present, a read response or a report in response to this referenced request will be immediately sent out;
  * otherwise the Libertas OS engine will decide when to send out the subscription reports.
  */
-declare function libertasVirtualDeviceAttributesRsp(device: LibertasVirtualDevice, ref: number, attributes: LibertasClusterReport[]) : void;
+declare function libertasVirtualDeviceAttributesRsp(device: LibertasVirtualDevice, peer: number, transId: number, attributes: LibertasClusterReport[]) : void;
 
-/**
+/** 
  * Send out command responses.
  * @param device A {@link LibertasVirtualDevice}.
- * @param ref The ref number of the request.
+ * @param peer The peer taskId.
+ * @param transId The transaction Id of the request.
  * @param rsp A {@link LibertasCommandRsp}.
  */
-declare function libertasVirtualDeviceCommandRsp(device: LibertasVirtualDevice, ref: number, rsp: LibertasCommandRsp) : void;
+declare function libertasVirtualDeviceCommandRsp(device: LibertasVirtualDevice, peer: number, transId: number, rsp: LibertasCommandRsp) : void;
 
-/**
+/** 
  * Send out write response.
  * @param device A {@link LibertasVirtualDevice}.
- * @param ref The ref number of the request.
+ * @param peer The peer taskId.
+ * @param transId The transaction Id of the request.
  * @param responses An array of {@link LibertasClusterWriteRsp}.
  */
-declare function libertasVirtualDeviceWriteRsp(device: LibertasVirtualDevice, ref: number, responses: LibertasClusterWriteRsp[]) : void;
+declare function libertasVirtualDeviceWriteRsp(device: LibertasVirtualDevice, peer: number, transId: number, responses: LibertasClusterWriteRsp[]) : void;
 
-/**
+/** 
  * Send out an error status code against an incoming request.
  * @param device A {@link LibertasVirtualDevice}.
- * @param ref The ref number of the request.
+ * @param peer The peer taskId.
+ * @param transId The transaction Id of the request.
  * @param status A {@link Matter.Status}.
  */
-declare function libertasVirtualDeviceStatusRsp(device: LibertasVirtualDevice, ref: number, status: number) : void;
+declare function libertasVirtualDeviceStatusRsp(device: LibertasVirtualDevice, peer: number, transId: number, status: number) : void;
 
 /**
  * Listen to a virtual device events.
@@ -614,34 +618,34 @@ declare function libertasVirtualDeviceStatusRsp(device: LibertasVirtualDevice, r
 declare function libertasSetOnVirtualDevice(device: LibertasVirtualDevice, func: LibertasVirtualDeviceCallback, tag?: any): void;
 
 /**
- * Sends a request or subscribeRequest message to an agent tool.
+ * Sends a request or subscribeRequest message to an endpoint.
  * 
- * @param device The target {@link LibertasAgentTool}.
- * @param action The interaction action, such as {@link LibertasAgentToolAction.Request} or {@link LibertasAgentToolAction.SubscriptionRequest}.
+ * @param device The target {@link LibertasEndpoint}.
+ * @param action The interaction action, such as {@link LibertasEndpointAction.Request} or {@link LibertasEndpointAction.SubscriptionRequest}.
  * @param message The message payload to send.
  * 
  * @returns A transaction ID that can be used to track the request and match it with a future response.
  */
-declare function libertasAgentToolSendRequest<T>(device: LibertasAgentTool, action: LibertasAgentToolAction, message: T): number;
+declare function libertasEndpointSendRequest<T>(device: LibertasEndpoint, action: LibertasEndpointAction, message: T): number;
 
 /**
- * Sends a response to an agent tool for a previously received request.
+ * Sends a response to an endpoint for a previously received request.
  * 
- * @param device The target {@link LibertasAgentTool}.
- * @param action The interaction action, typically {@link LibertasAgentToolAction.Response} or {@link LibertasAgentToolAction.ReportData}.
+ * @param device The target {@link LibertasEndpoint}.
+ * @param action The interaction action, typically {@link LibertasEndpointAction.Response} or {@link LibertasEndpointAction.ReportData}.
  * @param message The message payload containing the response data.
- * @param dest The request peer Id. It could be {@link LibertasPeer.Broadcast} for {@link LibertasAgentToolAction.ReportData}.
+ * @param dest The request peer Id. It could be {@link LibertasPeer.Broadcast} for {@link LibertasEndpointAction.ReportData}.
  * @param transId The transaction ID (ref) from the original request being responded to.
  */
-declare function libertasAgentToolSendResponse<T>(device: LibertasAgentTool, action: LibertasAgentToolAction, message: T, dest: number, transId: number): void;
+declare function libertasEndpointSendResponse<T>(device: LibertasEndpoint, action: LibertasEndpointAction, message: T, dest: number, transId: number): void;
 
 /**
- * Agent tool message callback.
- * @param device A {@link LibertasAgentTool}.
+ * Endpoint message callback.
+ * @param device A {@link LibertasEndpoint}.
  * @param func Callback function.
  * @param tag Developer defined data that will be passed to callback function.
  */
-declare function libertasSetOnAgentTool<T>(device: LibertasAgentTool, func: LibertasAgentToolCallback<T>, tag?: any): void;
+declare function libertasSetOnEndpoint<T>(device: LibertasEndpoint, func: LibertasEndpointCallback<T>, tag?: any): void;
 
 /**
  * The signature of timer callback function.
@@ -756,7 +760,7 @@ declare function libertasTimerDestroy(timer: LibertasTimer): void;
 declare function libertasTimerUpdate(timer: LibertasTimer, timeout: number, func?: LibertasTimerCallback, tag?: any): void
 
 /**
- * Trigger a user defined action. Users can define action with a client UI tool during Thing-App task creation.
+ * Trigger a user defined action. Users can define action with a client UI tool during Libertas App task creation.
  * @param action A {@link LibertasAction}.
  */
 declare function libertasTriggerAction(action: LibertasAction): void;
@@ -772,7 +776,7 @@ declare function libertasTriggerAction(action: LibertasAction): void;
  * - `AlertHigh`: High alerts.
  * - `AlertSevere`: Severe alerts.
  */
-declare const enum NotificationImportance {
+declare enum NotificationImportance {
   Debug = 0,
   Info = 1,
   AlertLow = 2,
@@ -785,7 +789,7 @@ declare const enum NotificationImportance {
 /**
  * Notification argument variant tags.
  */
-declare const enum NotificationArgTag {
+declare enum NotificationArgTag {
   /**
    * A literal string argument included in the message as-is, without being
    * treated as a resource string. This can be used to include specific text that
@@ -912,7 +916,7 @@ declare type NotificationArgument =
  *
  * @throws On size limits or permission violations.
  */    
-declare function libertas_NotificationSend(recipients: number[], level: NotificationImportance, resource_name: string, args: NotificationArgument[], source?: number): void;
+declare function libertasNotificationSend(recipients: number[], level: NotificationImportance, resource_name: string, args: NotificationArgument[], source?: number): void;
 
 /**
  * Sends a literal text notification.
@@ -924,7 +928,7 @@ declare function libertas_NotificationSend(recipients: number[], level: Notifica
  *
  * @throws On size limits or permission violations.
  */
-declare function libertas_NotificationSendLiteral(recipients: number[], level: NotificationImportance, text: string, source?: number): void;
+declare function libertasNotificationSendLiteral(recipients: number[], level: NotificationImportance, text: string, source?: number): void;
 
 /**
  * Data name with resource and arguments.
@@ -936,7 +940,7 @@ declare interface DataName {
     arguments: NotificationArgument[];
 }
 
-declare const enum IndexDirection {
+declare enum IndexDirection {
     Above,
     Below,
 }
@@ -1137,7 +1141,7 @@ declare function libertasDataReadIndexed<T>(
 /**
  * Log levels
  */
-declare const enum LibertasLogLevel {
+declare enum LibertasLogLevel {
     TRACE,
     DEBUG,
     INFO,
@@ -1151,6 +1155,6 @@ declare const enum LibertasLogLevel {
  * @param level Log level.
  * @param message A text message.
  * 
- * @remarks The log source is the name of the Thing-App task.
+ * @remarks The log source is the name of the Libertas App task.
  */
 declare function libertasLog(level: LibertasLogLevel, message: string): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libertas-ai/types",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Libertas TypeScript SDK",
   "license": "ISC",
   "author": "Qingjun Wei",