ai-publish-sdk 1.5.1 → 1.7.0

package/README.md

@@ -24,21 +24,6 @@ await withTimeout(() => getUserInfo(), 10_000)
 
 ## Core API
 
-### getAllowedModels()
-
-Get the list of allowed AI models and the default model.
-
-```typescript
-getAllowedModels(config?: RpcConfig): Promise<AllowedModelsInfo>
-
-interface AllowedModelsInfo {
-  models: string[]
-  defaultModel: string | null
-}
-```
-
-Returns an empty `models` array when no models are configured.
-
 ### getUserInfo()
 
 Get current user info.
@@ -78,6 +63,21 @@ interface GetTokenResult {
 }
 ```
 
+### getAllowedModels()
+
+Get the list of allowed AI models and the default model.
+
+```typescript
+getAllowedModels(): Promise<AllowedModelsInfo>
+
+interface AllowedModelsInfo {
+  models: string[]
+  defaultModel: string | null
+}
+```
+
+Returns an empty `models` array when no models are configured.
+
 ### generateMessage(prompt, options)
 
 Generate an AI message.
@@ -110,6 +110,56 @@ Execute JavaScript on the host page.
 executeScript(code: string): Promise<void>
 ```
 
+### trackEvent(params)
+
+Emit structured analytics events from your app. The host auto-populates `timestamp`, `userId`, `email`, `userName`, `tenantId`, `application`, `appType` (widget / fullpage / sidepanel), and (sidepanel only) `activeSite` — you only supply the app-specific fields.
+
+```typescript
+trackEvent(params: TrackEventParams): Promise<void>
+```
+
+## Device API
+
+Each `device.*` method returns `null` if the device API is unavailable
+
+### device.getSnapshot(options?)
+
+Get a full snapshot covering all sections in one call. Convenient for debugging or one-shot dumps; for repeated polling prefer the granular getters below.
+
+```typescript
+device.getSnapshot(options?: DeviceSnapshotOptions): Promise<DeviceSnapshot | null>
+```
+
+`DeviceSnapshot` contains: `software`, `device`, `browser`, `network`, `tabs`, `siteStatus`. Pass `options.knownStatusPages` (a `domain → statusPageUrl` map) to also resolve a status page for the active tab into `siteStatus.currentSiteStatus`.
+
+### Granular getters
+
+Each returns the same data as the corresponding field on `DeviceSnapshot`.
+
+```typescript
+device.getSoftware():  Promise<SoftwareVersions  | null>  // browser/extension/OS versions
+device.getDevice():    Promise<DeviceMetrics     | null>  // CPU, memory, displays, battery, processes
+device.getBrowser():   Promise<BrowserMetrics    | null>  // tab count, window count, extensions
+device.getNetwork():   Promise<NetworkInfo       | null>  // type, signal, IP, DNS, proxy latency
+device.getTabs():      Promise<TabSnapshot[]     | null>  // per-tab URL, title, errors
+device.getSiteStatus(options?: DeviceSnapshotOptions): Promise<SiteStatusInfo | null>
+```
+
+### device.getStatusPage(statusPageUrl)
+
+Fetch the status of an arbitrary Statuspage.io-compatible page by URL.
+
+```typescript
+device.getStatusPage(statusPageUrl: string): Promise<StatusPageResult | null>
+```
+
+`StatusPageResult.indicator` ∈ `'none' | 'minor' | 'major' | 'critical' | 'unknown'`. `'unknown'` is returned when the page is unreachable or its response is unrecognized.
+
+Example:
+```typescript
+const status = await device.getStatusPage('https://www.githubstatus.com')
+```
+
 ## TCP API
 
 All data is base64-encoded. Import as `import { tcp }`.

package/index.d.ts

@@ -1,5 +1,5 @@
-export { getAllowedModels, generateMessage, getBrandingAssets, getToken, getUserInfo } from './lib/functions';
+export { device, generateMessage, getAllowedModels, getBrandingAssets, getToken, getUserInfo, trackEvent } from './lib/functions';
 export { tcp } from './lib/tcp-socket';
 export type { TcpSocket } from './lib/tcp-socket';
 export { setGlobalTimeout, withTimeout } from './lib/rpc-bridge';
-export type { AllowedModelsInfo, BrandingAssets, GenerateMessageOptions, GetTokenOptions, GetTokenResult, IntegrationAppName, UserInfo } from './lib/types';
+export type { AllowedModelsInfo, BrandingAssets, BrowserMetrics, CertError, ConnectionError, DesktopAppInfo, DeviceMetrics, DeviceSnapshot, DeviceSnapshotOptions, DisplayUnit, FailedRequest, GenerateMessageOptions, GetTokenOptions, GetTokenResult, InstalledExtension, IntegrationAppName, NetworkInfo, ProcessInfo, SiteStatusInfo, SnakeCase, SoftwareVersions, StatusPageResult, TabSnapshot, TrackEventDetailValue, TrackEventDetails, TrackEventParams, UserInfo } from './lib/types';

package/index.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});let u=15e3;const c=new Map;let a=!1;function d(e){u=e}let i;function f(e,t){i=t;try{return e()}finally{i=void 0}}function m(){a||(a=!0,window.addEventListener("message",e=>{const t=e.data;if(!t?.messageId||!("name"in t))return;const n=c.get(t.messageId);n&&(clearTimeout(n.timer),c.delete(t.messageId),t.error?n.reject(new Error(t.error.message??"RPC error")):n.resolve(t.data))}))}function r(e,t){return m(),new Promise((n,s)=>{const o=crypto.randomUUID(),l=setTimeout(()=>{c.delete(o),s(new Error(`RPC timeout: ${e}`))},i??u);c.set(o,{resolve:n,reject:s,timer:l});const g={action:e,params:t,messageId:o};window.parent.postMessage(g,"*")})}async function y(){return r("getAllowedModels",[])}async function p(e,t){return r("generateMessage",[e,t])}async function w(e,t){return r("getToken",[e,t])}async function T(){return r("getUserInfo",[])}async function M(){return r("getBrandingAssets",[])}async function v(e){return r("tcpConnect",[e])}async function I(e,t){return r("tcpSend",[e,t])}async function C(e,t){return r("tcpReceive",[e,t])}async function b(e){return r("tcpClose",[e])}const A={async connect(e,t){const n=await v({host:e,port:t});return n===null?null:{send:async s=>(await I(n,{dataBase64:s}))?.bytesSent??null,receive:async()=>(await C(n))?.data??null,close:()=>b(n)}}};exports.generateMessage=p;exports.getAllowedModels=y;exports.getBrandingAssets=M;exports.getToken=w;exports.getUserInfo=T;exports.setGlobalTimeout=d;exports.tcp=A;exports.withTimeout=f;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});let u=15e3;const c=new Map;let i=!1;function d(e){u=e}let a;function f(e,t){a=t;try{return e()}finally{a=void 0}}function m(){i||(i=!0,window.addEventListener("message",e=>{const t=e.data;if(!t?.messageId||!("name"in t))return;const r=c.get(t.messageId);r&&(clearTimeout(r.timer),c.delete(t.messageId),t.error?r.reject(new Error(t.error.message??"RPC error")):r.resolve(t.data))}))}function n(e,t){return m(),new Promise((r,s)=>{const o=crypto.randomUUID(),l=setTimeout(()=>{c.delete(o),s(new Error(`RPC timeout: ${e}`))},a??u);c.set(o,{resolve:r,reject:s,timer:l});const g={action:e,params:t,messageId:o};window.parent.postMessage(g,"*")})}async function v(){return n("getAllowedModels",[])}async function w(e,t){return n("generateMessage",[e,t])}async function y(e,t){return n("getToken",[e,t])}async function p(){return n("getUserInfo",[])}async function S(){return n("getBrandingAssets",[])}async function T(e){return n("tcpConnect",[e])}async function G(e,t){return n("tcpSend",[e,t])}async function M(e,t){return n("tcpReceive",[e,t])}async function b(e){return n("tcpClose",[e])}async function k(e){return n("trackEvent",[e])}const I={getSnapshot:e=>n("deviceGetSnapshot",[e]),getSoftware:()=>n("deviceGetSoftware",[]),getDevice:()=>n("deviceGetDevice",[]),getBrowser:()=>n("deviceGetBrowser",[]),getNetwork:()=>n("deviceGetNetwork",[]),getTabs:()=>n("deviceGetTabs",[]),getSiteStatus:e=>n("deviceGetSiteStatus",[e]),getStatusPage:e=>n("deviceGetStatusPage",[e])},C={async connect(e,t){const r=await T({host:e,port:t});return r===null?null:{send:async s=>(await G(r,{dataBase64:s}))?.bytesSent??null,receive:async()=>(await M(r))?.data??null,close:()=>b(r)}}};exports.device=I;exports.generateMessage=w;exports.getAllowedModels=v;exports.getBrandingAssets=S;exports.getToken=y;exports.getUserInfo=p;exports.setGlobalTimeout=d;exports.tcp=C;exports.trackEvent=k;exports.withTimeout=f;

package/index.mjs

@@ -1,11 +1,11 @@
 let u = 15e3;
 const c = /* @__PURE__ */ new Map();
 let i = !1;
-function T(e) {
+function y(e) {
   u = e;
 }
 let a;
-function v(e, t) {
+function S(e, t) {
   a = t;
   try {
     return e();
@@ -17,17 +17,17 @@ function g() {
   i || (i = !0, window.addEventListener("message", (e) => {
     const t = e.data;
     if (!t?.messageId || !("name" in t)) return;
-    const n = c.get(t.messageId);
-    n && (clearTimeout(n.timer), c.delete(t.messageId), t.error ? n.reject(new Error(t.error.message ?? "RPC error")) : n.resolve(t.data));
+    const r = c.get(t.messageId);
+    r && (clearTimeout(r.timer), c.delete(t.messageId), t.error ? r.reject(new Error(t.error.message ?? "RPC error")) : r.resolve(t.data));
   }));
 }
-function r(e, t) {
-  return g(), new Promise((n, s) => {
+function n(e, t) {
+  return g(), new Promise((r, s) => {
     const o = crypto.randomUUID(), l = setTimeout(() => {
       c.delete(o), s(new Error(`RPC timeout: ${e}`));
     }, a ?? u);
     c.set(o, {
-      resolve: n,
+      resolve: r,
       reject: s,
       timer: l
     });
@@ -35,34 +35,46 @@ function r(e, t) {
     window.parent.postMessage(d, "*");
   });
 }
-async function C() {
-  return r("getAllowedModels", []);
+async function T() {
+  return n("getAllowedModels", []);
 }
-async function I(e, t) {
-  return r("generateMessage", [e, t]);
+async function G(e, t) {
+  return n("generateMessage", [e, t]);
 }
-async function M(e, t) {
-  return r("getToken", [e, t]);
+async function C(e, t) {
+  return n("getToken", [e, t]);
 }
-async function A() {
-  return r("getUserInfo", []);
+async function I() {
+  return n("getUserInfo", []);
 }
-async function R() {
-  return r("getBrandingAssets", []);
+async function k() {
+  return n("getBrandingAssets", []);
 }
 async function f(e) {
-  return r("tcpConnect", [e]);
+  return n("tcpConnect", [e]);
 }
 async function m(e, t) {
-  return r("tcpSend", [e, t]);
+  return n("tcpSend", [e, t]);
 }
-async function y(e, t) {
-  return r("tcpReceive", [e, t]);
+async function v(e, t) {
+  return n("tcpReceive", [e, t]);
 }
-async function p(e) {
-  return r("tcpClose", [e]);
+async function w(e) {
+  return n("tcpClose", [e]);
 }
-const U = {
+async function M(e) {
+  return n("trackEvent", [e]);
+}
+const b = {
+  getSnapshot: (e) => n("deviceGetSnapshot", [e]),
+  getSoftware: () => n("deviceGetSoftware", []),
+  getDevice: () => n("deviceGetDevice", []),
+  getBrowser: () => n("deviceGetBrowser", []),
+  getNetwork: () => n("deviceGetNetwork", []),
+  getTabs: () => n("deviceGetTabs", []),
+  getSiteStatus: (e) => n("deviceGetSiteStatus", [e]),
+  getStatusPage: (e) => n("deviceGetStatusPage", [e])
+}, E = {
   /**
    * Opens a TCP connection and returns a `TcpSocket` wrapper.
    *
@@ -72,21 +84,23 @@ const U = {
    * security guarantees.
    */
   async connect(e, t) {
-    const n = await f({ host: e, port: t });
-    return n === null ? null : {
-      send: async (s) => (await m(n, { dataBase64: s }))?.bytesSent ?? null,
-      receive: async () => (await y(n))?.data ?? null,
-      close: () => p(n)
+    const r = await f({ host: e, port: t });
+    return r === null ? null : {
+      send: async (s) => (await m(r, { dataBase64: s }))?.bytesSent ?? null,
+      receive: async () => (await v(r))?.data ?? null,
+      close: () => w(r)
     };
   }
 };
 export {
-  I as generateMessage,
-  C as getAllowedModels,
-  R as getBrandingAssets,
-  M as getToken,
-  A as getUserInfo,
-  T as setGlobalTimeout,
-  U as tcp,
-  v as withTimeout
+  b as device,
+  G as generateMessage,
+  T as getAllowedModels,
+  k as getBrandingAssets,
+  C as getToken,
+  I as getUserInfo,
+  y as setGlobalTimeout,
+  E as tcp,
+  M as trackEvent,
+  S as withTimeout
 };

package/lib/functions.d.ts

@@ -1,4 +1,4 @@
-import { AllowedModelsInfo, BrandingAssets, GenerateMessageOptions, GetTokenOptions, GetTokenResult, IntegrationAppName, TcpConnectOptions, TcpConnectionSettings, TcpReceiveOptions, TcpReceiveResult, TcpSendMessage, TcpSendResult, UserInfo } from './types';
+import { AllowedModelsInfo, BrandingAssets, BrowserMetrics, DeviceMetrics, DeviceSnapshot, DeviceSnapshotOptions, GenerateMessageOptions, GetTokenOptions, GetTokenResult, IntegrationAppName, NetworkInfo, SiteStatusInfo, SoftwareVersions, StatusPageResult, TabSnapshot, TcpConnectOptions, TcpConnectionSettings, TcpReceiveOptions, TcpReceiveResult, TcpSendMessage, TcpSendResult, TrackEventParams, UserInfo } from './types';
 export declare function getAllowedModels(): Promise<AllowedModelsInfo>;
 export declare function generateMessage(prompt: string, options: GenerateMessageOptions): Promise<string | null>;
 export declare function getToken(appName: IntegrationAppName, options?: GetTokenOptions): Promise<GetTokenResult | null>;
@@ -9,3 +9,14 @@ export declare function tcpConnect(options: TcpConnectOptions): Promise<TcpConne
 export declare function tcpSend(connection: TcpConnectionSettings, message: TcpSendMessage): Promise<TcpSendResult | null>;
 export declare function tcpReceive(connection: TcpConnectionSettings, options?: TcpReceiveOptions): Promise<TcpReceiveResult | null>;
 export declare function tcpClose(connection: TcpConnectionSettings): Promise<void>;
+export declare function trackEvent(params: TrackEventParams): Promise<void>;
+export declare const device: {
+    getSnapshot: (options?: DeviceSnapshotOptions) => Promise<DeviceSnapshot | null>;
+    getSoftware: () => Promise<SoftwareVersions | null>;
+    getDevice: () => Promise<DeviceMetrics | null>;
+    getBrowser: () => Promise<BrowserMetrics | null>;
+    getNetwork: () => Promise<NetworkInfo | null>;
+    getTabs: () => Promise<TabSnapshot[] | null>;
+    getSiteStatus: (options?: DeviceSnapshotOptions) => Promise<SiteStatusInfo | null>;
+    getStatusPage: (statusPageUrl: string) => Promise<StatusPageResult | null>;
+};

package/lib/types.d.ts

@@ -50,3 +50,126 @@ export interface TcpReceiveOptions {
 export interface TcpReceiveResult {
     data: string;
 }
+export interface DeviceSnapshotOptions {
+    knownStatusPages?: Record<string, string>;
+}
+export interface DeviceSnapshot {
+    software: SoftwareVersions;
+    device: DeviceMetrics;
+    browser: BrowserMetrics;
+    network: NetworkInfo;
+    tabs: TabSnapshot[];
+    siteStatus: SiteStatusInfo;
+}
+export interface SoftwareVersions {
+    browserVersion: string;
+    extensionVersion: string;
+    agentVersion?: string;
+    osVersion?: string;
+    deviceModel?: string;
+    deviceHostName?: string;
+}
+export interface DeviceMetrics {
+    cpuModel: string;
+    architecture: string;
+    numOfProcessors: number;
+    totalMemoryMb: number;
+    diskStorageGb?: number;
+    displays: DisplayUnit[];
+    batteryPercent?: number;
+    isCharging?: boolean;
+    isPowerSavingMode?: boolean;
+    lastRebootTime?: string;
+    processes: ProcessInfo[];
+    desktopApps?: DesktopAppInfo[];
+}
+export interface BrowserMetrics {
+    tabCount: number;
+    windowCount: number;
+    extensions: InstalledExtension[];
+    proxyConfig?: string;
+}
+export interface NetworkInfo {
+    type: 'WiFi' | 'Ethernet' | 'Unknown';
+    isOnline: boolean;
+    wifiSignalDbm?: number;
+    ssid?: string;
+    ipAddress?: string;
+    gateway?: string;
+    dnsServers?: string[];
+    ipaProxyLatencyMs?: number;
+    ipaProxyAddress?: string;
+}
+export interface TabSnapshot {
+    tabId: number;
+    url: string;
+    title: string;
+    isActive: boolean;
+    isUnresponsive?: boolean;
+    isCrashed?: boolean;
+    failedHttpRequests?: FailedRequest[];
+    failedDnsLookups?: string[];
+    certErrors?: CertError[];
+    connectionErrors?: ConnectionError[];
+}
+export interface SiteStatusInfo {
+    hostStatus: StatusPageResult;
+    currentSiteStatus: StatusPageResult | null;
+}
+export interface StatusPageResult {
+    indicator: 'none' | 'minor' | 'major' | 'critical' | 'unknown';
+    description: string;
+    domain: string;
+}
+export interface TrackEventParams {
+    eventName: SnakeCase<string>;
+    additionalDetails?: TrackEventDetails;
+}
+export interface DisplayUnit {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+    isPrimary: boolean;
+    isInternal: boolean;
+    isEnabled: boolean;
+    dpiX: number;
+    dpiY: number;
+}
+export interface ProcessInfo {
+    pid: number;
+    type: string;
+    title?: string;
+    cpuPercent?: number;
+    privateMemoryBytes?: number;
+    jsMemoryUsedBytes?: number;
+}
+export interface DesktopAppInfo {
+    name: string;
+    pid: number;
+    memoryBytes: number;
+}
+export interface InstalledExtension {
+    id: string;
+    name: string;
+    version: string;
+    enabled: boolean;
+}
+export interface FailedRequest {
+    url: string;
+    statusCode: number;
+}
+export interface CertError {
+    url: string;
+    errorCode: string;
+}
+export interface ConnectionError {
+    url: string;
+    errorCode: string;
+    reason: 'host-policy' | 'host-throttle' | 'other-extension' | 'network';
+    extensionId?: string;
+}
+export type SnakeCase<S extends string> = SnakeCaseInner<S> extends `_${infer Rest}` ? Rest : SnakeCaseInner<S>;
+export type TrackEventDetails = Record<string, TrackEventDetailValue | Record<string, TrackEventDetailValue>>;
+export type SnakeCaseInner<S extends string> = S extends `${infer T}${infer U}` ? `${T extends Uppercase<T> ? '_' : ''}${Lowercase<T>}${SnakeCaseInner<U>}` : S;
+export type TrackEventDetailValue = string | number | boolean | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-publish-sdk",
-  "version": "1.5.1",
+  "version": "1.7.0",
   "module": "./index.mjs",
   "main": "./index.js",
   "types": "./index.d.ts",