ai-publish-sdk

SDK for embedded apps to communicate with the host environment.

Installation

npm install ai-publish-sdk

Timeout Configuration

Default timeout is 15 seconds. You can change it globally or wrap a single call:

import { setGlobalTimeout, withTimeout, getUserInfo } from 'ai-publish-sdk'

// Change the default for all calls
setGlobalTimeout(30_000)

// Override for a single call
await withTimeout(() => getUserInfo(), 10_000)

Core API

getUserInfo()

Get current user info.

getUserInfo(): Promise<UserInfo | null>

interface UserInfo {
  userId: string
  tenantId: string
  tenantName?: string
  name?: string
  givenName?: string
  familyName?: string
  displayName?: string
  email?: string
  picture?: string
}

getToken(appName, options?)

Get OAuth token for an integration.

getToken(appName: IntegrationAppName, options?: GetTokenOptions): Promise<GetTokenResult | null>

type IntegrationAppName = 'gmail' | 'jira' | 'googledrive' | 'salesforce' | 'googlecalendar' | 'slack'

interface GetTokenOptions {
  interactive?: boolean // show OAuth flow if not yet authorized
}

interface GetTokenResult {
  token: string
  instanceUrl?: string // e.g. Salesforce instance URL
}

getAllowedModels()

Get the list of allowed AI models and the default model.

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.

generateMessage(prompt: string, options: GenerateMessageOptions): Promise<string | null>

interface GenerateMessageOptions {
  withPageContext?: boolean // include current page content as context
  systemPrompt?: string    // guide AI behavior
  model?: string           // model name from getAllowedModels(); omit for default
}

Example — use a specific model from getAllowedModels():

const { models, defaultModel } = await getAllowedModels()
const response = await generateMessage('Summarize this page', {
  withPageContext: true,
  model: models[0], // or defaultModel
})

getBrandingAssets()

Get branding assets for white-label styling.

getBrandingAssets(): Promise<BrandingAssets | null>

Returns BrandingAssets with fields: logoUrl, darkLogoUrl, brandColor (all string | null).

executeScript(code)

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.

trackEvent(params: TrackEventParams): Promise<void>

interface TrackEventParams {
  eventName: SnakeCase<string>          // required — snake_case identifier (e.g. 'quiz_completed')
  additionalDetails?: TrackEventDetails // optional — primitive-valued bag, one level of nesting allowed
}

type TrackEventDetailValue = string | number | boolean | null

type TrackEventDetails = Record<
  string,
  TrackEventDetailValue | Record<string, TrackEventDetailValue>
>

Only eventName is required. Example:

await trackEvent({ eventName: 'quiz_completed' })
await trackEvent({
  eventName: 'quiz_completed',
  additionalDetails: { score: 8, total: 10, module: 'phishing' },
})

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.

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.

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.

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:

const status = await device.getStatusPage('https://www.githubstatus.com')

TCP API

All data is base64-encoded. Import as import { tcp }.

tcp.connect(host, port)

Open a TCP connection. Returns a TcpSocket object for subsequent operations, or null if TCP is unavailable.

tcp.connect(host: string, port: number): Promise<TcpSocket | null>

interface TcpSocket {
  send(dataBase64: string): Promise<number | null>
  receive(): Promise<string | null>
  close(): Promise<void>
}

TcpSocket.send(dataBase64)

Send data over an open socket. Data must be base64-encoded. Returns the number of bytes sent, or null if TCP is unavailable.

TcpSocket.receive()

Wait for and receive data from an open socket. Returns base64-encoded data, or null if TCP is unavailable. Use withTimeout(() => socket.receive(), ms) for custom timeouts.

TcpSocket.close()

Disconnect and close an open socket.