@trillboards/edge-sdk 0.2.4 → 0.2.6

package/deploy/windows/trillboards-setup.ps1

@@ -0,0 +1,456 @@
+[CmdletBinding()]
+param(
+  [switch]$SmokeTest
+)
+
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+[System.Windows.Forms.Application]::EnableVisualStyles()
+
+$BinDir = $PSScriptRoot
+$Pairer = Join-Path $BinDir 'trillboards-pair.cmd'
+$StateDir = Join-Path $env:LOCALAPPDATA 'Trillboards'
+$StatePath = Join-Path $StateDir 'setup-progress.json'
+$LogDir = Join-Path $StateDir 'logs'
+$SetupLogPath = Join-Path $LogDir 'setup-app.log'
+$LocalAiSetup = Join-Path $BinDir 'setup-litertlm.ps1'
+$script:LastStage = 'welcome'
+$script:SetupStarted = $false
+$script:PortalUrl = 'https://trillboards.com/earner/screens'
+$script:PairProcess = $null
+$script:SetupMutex = $null
+$StepNames = @('Welcome', 'Account', 'Recorder', 'Cameras', 'Local AI', 'Ready')
+$StepLabels = New-Object System.Collections.Generic.List[System.Windows.Forms.Label]
+
+function New-Label {
+  param([string]$Text, [float]$Size = 10, [System.Drawing.FontStyle]$Style = [System.Drawing.FontStyle]::Regular)
+  $label = New-Object System.Windows.Forms.Label
+  $label.Text = $Text
+  $label.Font = New-Object System.Drawing.Font('Segoe UI', $Size, $Style)
+  $label.AutoSize = $false
+  $label.BackColor = [System.Drawing.Color]::Transparent
+  return $label
+}
+
+function Get-StateValue {
+  param($State, [string]$Name)
+  if ($null -eq $State) { return $null }
+  $property = $State.PSObject.Properties[$Name]
+  if ($null -eq $property) { return $null }
+  return $property.Value
+}
+
+function Get-StepIndex([string]$Stage) {
+  switch ($Stage) {
+    { $_ -in @('waiting_for_account', 'account_attention') } { return 1 }
+    { $_ -in @('account_connected', 'discovering') } { return 2 }
+    'devices_found' { return 3 }
+    'validating' { return 3 }
+    'cameras_created' { return 4 }
+    { $_ -in @('local_ai', 'local_ai_error', 'starting_service') } { return 4 }
+    'ready' { return 5 }
+    default { return 0 }
+  }
+}
+
+function Get-ProgressValue([string]$Stage, $State) {
+  switch ($Stage) {
+    'waiting_for_account' { return 18 }
+    'account_attention' { return 18 }
+    'account_connected' { return 30 }
+    'discovering' { return 42 }
+    'devices_found' { return 50 }
+    'validating' { return 68 }
+    'cameras_created' { return 80 }
+    'local_ai' {
+      $localPercent = Get-StateValue $State 'localAiProgressPercent'
+      if ($null -ne $localPercent) {
+        return 84 + [Math]::Floor(([Math]::Max(0, [Math]::Min(100, [int]$localPercent))) * 0.14)
+      }
+      return 84
+    }
+    'local_ai_error' { return 95 }
+    'starting_service' { return 82 }
+    'ready' { return 100 }
+    default { return 8 }
+  }
+}
+
+function Update-Steps([int]$Active, [bool]$CompleteActive = $false) {
+  for ($index = 0; $index -lt $StepLabels.Count; $index++) {
+    $label = $StepLabels[$index]
+    $completed = $index -lt $Active -or ($CompleteActive -and $index -eq $Active)
+    $prefix = if ($completed) { [string][char]0x2713 } else { [string]($index + 1) }
+    $label.Text = "$prefix    $($StepNames[$index])"
+    $label.ForeColor = if ($index -le $Active) { [System.Drawing.Color]::FromArgb(30, 43, 49) } else { [System.Drawing.Color]::FromArgb(104, 119, 127) }
+    $style = if ($index -eq $Active) { [System.Drawing.FontStyle]::Bold } else { [System.Drawing.FontStyle]::Regular }
+    $label.Font = New-Object System.Drawing.Font('Segoe UI', 10, $style)
+  }
+}
+
+function Format-ByteCount($Value) {
+  if ($null -eq $Value) { return $null }
+  $bytes = [double]$Value
+  if ($bytes -ge 1GB) { return ('{0:N2} GB' -f ($bytes / 1GB)) }
+  if ($bytes -ge 1MB) { return ('{0:N0} MB' -f ($bytes / 1MB)) }
+  return ('{0:N0} KB' -f ($bytes / 1KB))
+}
+
+$Form = New-Object System.Windows.Forms.Form
+$Form.Text = 'Trillboards CCTV Setup'
+$Form.StartPosition = [System.Windows.Forms.FormStartPosition]::CenterScreen
+$Form.ClientSize = New-Object System.Drawing.Size(760, 540)
+$Form.MinimumSize = New-Object System.Drawing.Size(700, 520)
+$Form.BackColor = [System.Drawing.Color]::White
+$Form.MaximizeBox = $false
+
+$Sidebar = New-Object System.Windows.Forms.Panel
+$Sidebar.Dock = [System.Windows.Forms.DockStyle]::Left
+$Sidebar.Width = 190
+$Sidebar.BackColor = [System.Drawing.Color]::FromArgb(238, 243, 245)
+$Form.Controls.Add($Sidebar)
+
+$Brand = New-Label -Text 'Trillboards' -Size 12 -Style ([System.Drawing.FontStyle]::Bold)
+$Brand.Location = New-Object System.Drawing.Point(24, 28)
+$Brand.Size = New-Object System.Drawing.Size(145, 28)
+$Sidebar.Controls.Add($Brand)
+
+for ($index = 0; $index -lt $StepNames.Count; $index++) {
+  $step = New-Label -Text "$($index + 1)    $($StepNames[$index])" -Size 10
+  $step.Location = New-Object System.Drawing.Point(24, (92 + ($index * 48)))
+  $step.Size = New-Object System.Drawing.Size(150, 28)
+  $Sidebar.Controls.Add($step)
+  $StepLabels.Add($step)
+}
+
+$Eyebrow = New-Label -Text 'CUSTOMER SETUP' -Size 9 -Style ([System.Drawing.FontStyle]::Bold)
+$Eyebrow.ForeColor = [System.Drawing.Color]::FromArgb(0, 112, 153)
+$Eyebrow.Location = New-Object System.Drawing.Point(236, 48)
+$Eyebrow.Size = New-Object System.Drawing.Size(450, 22)
+$Form.Controls.Add($Eyebrow)
+
+$Headline = New-Label -Text '' -Size 21 -Style ([System.Drawing.FontStyle]::Bold)
+$Headline.Location = New-Object System.Drawing.Point(232, 76)
+$Headline.Size = New-Object System.Drawing.Size(475, 70)
+$Form.Controls.Add($Headline)
+
+$Detail = New-Label -Text '' -Size 11
+$Detail.ForeColor = [System.Drawing.Color]::FromArgb(96, 113, 122)
+$Detail.Location = New-Object System.Drawing.Point(236, 150)
+$Detail.Size = New-Object System.Drawing.Size(465, 74)
+$Form.Controls.Add($Detail)
+
+$StatusBox = New-Object System.Windows.Forms.Panel
+$StatusBox.Location = New-Object System.Drawing.Point(236, 242)
+$StatusBox.Size = New-Object System.Drawing.Size(465, 70)
+$StatusBox.BackColor = [System.Drawing.Color]::FromArgb(245, 248, 249)
+$StatusBox.BorderStyle = [System.Windows.Forms.BorderStyle]::FixedSingle
+$Form.Controls.Add($StatusBox)
+
+$StatusValue = New-Label -Text '' -Size 17 -Style ([System.Drawing.FontStyle]::Bold)
+$StatusValue.TextAlign = [System.Drawing.ContentAlignment]::MiddleCenter
+$StatusValue.Dock = [System.Windows.Forms.DockStyle]::Fill
+$StatusBox.Controls.Add($StatusValue)
+
+$Metric = New-Label -Text '' -Size 9
+$Metric.ForeColor = [System.Drawing.Color]::FromArgb(96, 113, 122)
+$Metric.Location = New-Object System.Drawing.Point(236, 330)
+$Metric.Size = New-Object System.Drawing.Size(465, 24)
+$Form.Controls.Add($Metric)
+
+$Progress = New-Object System.Windows.Forms.ProgressBar
+$Progress.Location = New-Object System.Drawing.Point(236, 364)
+$Progress.Size = New-Object System.Drawing.Size(465, 10)
+$Progress.Minimum = 0
+$Progress.Maximum = 100
+$Form.Controls.Add($Progress)
+
+$Privacy = New-Label -Text 'Camera credentials stay on this computer. Cloud inference is off by default.' -Size 8.5
+$Privacy.ForeColor = [System.Drawing.Color]::FromArgb(96, 113, 122)
+$Privacy.Location = New-Object System.Drawing.Point(236, 468)
+$Privacy.Size = New-Object System.Drawing.Size(300, 40)
+$Form.Controls.Add($Privacy)
+
+$Action = New-Object System.Windows.Forms.Button
+$Action.Text = 'Start setup'
+$Action.Font = New-Object System.Drawing.Font('Segoe UI', 10, [System.Drawing.FontStyle]::Bold)
+$Action.Location = New-Object System.Drawing.Point(562, 466)
+$Action.Size = New-Object System.Drawing.Size(139, 42)
+$Action.BackColor = [System.Drawing.Color]::FromArgb(0, 127, 174)
+$Action.ForeColor = [System.Drawing.Color]::White
+$Action.FlatStyle = [System.Windows.Forms.FlatStyle]::Flat
+$Action.FlatAppearance.BorderSize = 0
+$Form.Controls.Add($Action)
+
+function Show-Welcome {
+  $script:LastStage = 'welcome'
+  $Headline.Text = 'Set up this computer for CCTV'
+  $Detail.Text = 'Connect your Trillboards account, find your recorder, and verify every camera before screens are created.'
+  $StatusValue.Text = 'About 5 minutes'
+  $Metric.Text = 'Keep this computer and the recorder on the same network.'
+  $Progress.Value = 0
+  $Action.Text = 'Start setup'
+  $Action.Enabled = $true
+  Update-Steps 0
+}
+
+function Show-LocalError([string]$Title, [string]$Message) {
+  $script:LastStage = 'error'
+  $Headline.Text = $Title
+  $Detail.Text = $Message
+  $StatusValue.Text = 'Setup stopped'
+  $Metric.Text = 'Details are saved in logs\setup-app.log.'
+  $Progress.Value = 0
+  $Action.Text = 'Try again'
+  $Action.Enabled = $true
+}
+
+function Start-Setup {
+  if (-not (Test-Path $Pairer)) {
+    Show-LocalError 'Setup app is incomplete' 'Reinstall the Trillboards CCTV connector, then try again.'
+    return
+  }
+  Stop-SetupProcess
+  New-Item -ItemType Directory -Path $LogDir -Force | Out-Null
+  Remove-Item $StatePath -Force -ErrorAction SilentlyContinue
+  Add-Content -Path $SetupLogPath -Value "`r`n[$([DateTime]::Now.ToString('o'))] Starting Trillboards CCTV Setup"
+  $Headline.Text = 'Starting camera setup'
+  $Detail.Text = 'Connecting securely to Trillboards.'
+  $StatusValue.Text = 'Please wait'
+  $Metric.Text = 'No Terminal or command window is required.'
+  $Progress.Value = 8
+  $Action.Enabled = $false
+  $script:LastStage = 'starting'
+  $script:SetupStarted = $true
+
+  $startInfo = New-Object System.Diagnostics.ProcessStartInfo
+  $startInfo.FileName = $env:ComSpec
+  $startInfo.Arguments = ('/d /s /c ""{0}" --setup --status-file "{1}" >> "{2}" 2>&1"' -f $Pairer, $StatePath, $SetupLogPath)
+  $startInfo.UseShellExecute = $false
+  $startInfo.CreateNoWindow = $true
+  $startInfo.WindowStyle = [System.Diagnostics.ProcessWindowStyle]::Hidden
+  try {
+    $script:PairProcess = [System.Diagnostics.Process]::Start($startInfo)
+  } catch {
+    Show-LocalError 'Could not start setup' 'Reinstall the Trillboards CCTV connector, then try again.'
+  }
+}
+
+function Start-LocalAiSetup {
+  if (-not (Test-Path $LocalAiSetup)) {
+    Show-LocalError 'Local AI setup is incomplete' 'Reinstall the Trillboards CCTV connector, then try again.'
+    return
+  }
+  $Headline.Text = 'Preparing local AI'
+  $Detail.Text = 'Restarting the local AI installed with Trillboards. Your paired cameras will not be recreated.'
+  $StatusValue.Text = 'Starting local AI'
+  $Metric.Text = 'Cloud inference remains off.'
+  $Progress.Value = 82
+  $Action.Text = 'Working...'
+  $Action.Enabled = $false
+  $script:LastStage = 'local_ai'
+
+  $startInfo = New-Object System.Diagnostics.ProcessStartInfo
+  $startInfo.FileName = 'powershell.exe'
+  $startInfo.Arguments = ('-NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File "{0}" -RequireBundledModel -ProgressPath "{1}"' -f $LocalAiSetup, $StatePath)
+  $startInfo.UseShellExecute = $false
+  $startInfo.CreateNoWindow = $true
+  $startInfo.WindowStyle = [System.Diagnostics.ProcessWindowStyle]::Hidden
+  try {
+    [void][System.Diagnostics.Process]::Start($startInfo)
+  } catch {
+    Show-LocalError 'Could not start local AI' 'Reinstall the Trillboards CCTV connector, then try again.'
+  }
+}
+
+function Stop-SetupProcess {
+  $process = $script:PairProcess
+  $script:PairProcess = $null
+  if ($null -eq $process) { return }
+  try {
+    if (-not $process.HasExited) {
+      $taskkill = Join-Path $env:SystemRoot 'System32\taskkill.exe'
+      & $taskkill /PID $process.Id /T /F | Out-Null
+      [void]$process.WaitForExit(5000)
+    }
+  } catch {
+    try {
+      if (-not $process.HasExited) { $process.Kill() }
+    } catch {
+      # The process may have exited between checks.
+    }
+  } finally {
+    $process.Dispose()
+  }
+}
+
+function Render-State($State) {
+  $stage = [string](Get-StateValue $State 'stage')
+  if (-not $stage) { return }
+  $script:LastStage = $stage
+  $url = Get-StateValue $State 'portalUrl'
+  if ($url) { $script:PortalUrl = [string]$url }
+  $Headline.Text = [string](Get-StateValue $State 'title')
+  $Detail.Text = [string](Get-StateValue $State 'message')
+  $cameraCount = Get-StateValue $State 'cameraCount'
+  $validated = Get-StateValue $State 'validatedFeeds'
+  $devices = Get-StateValue $State 'devicesFound'
+  $rejected = Get-StateValue $State 'rejectedFeeds'
+  $localAiPhase = [string](Get-StateValue $State 'localAiPhase')
+  $localAiPercent = Get-StateValue $State 'localAiProgressPercent'
+  $localAiDownloaded = Get-StateValue $State 'localAiDownloadedBytes'
+  $localAiTotal = Get-StateValue $State 'localAiTotalBytes'
+
+  if ($stage -in @('waiting_for_account', 'account_attention')) {
+    $StatusValue.Text = [string](Get-StateValue $State 'displayCode')
+  } elseif ($stage -eq 'ready') {
+    $StatusValue.Text = 'Setup complete'
+  } elseif ($stage -eq 'local_ai_error') {
+    $StatusValue.Text = 'Local AI needs attention'
+  } elseif ($stage -eq 'starting_service') {
+    $StatusValue.Text = 'Starting Trillboards'
+  } elseif ($stage -eq 'local_ai') {
+    switch ($localAiPhase) {
+      'installing_model' {
+        $StatusValue.Text = if ($null -ne $localAiPercent) { "Installing Gemma - $localAiPercent%" } else { 'Installing Gemma' }
+      }
+      'starting_service' { $StatusValue.Text = 'Starting local AI' }
+      'verifying' { $StatusValue.Text = 'Checking local AI' }
+      default { $StatusValue.Text = 'Installing local AI' }
+    }
+  } elseif ($cameraCount -and [int]$cameraCount -gt 0) {
+    $StatusValue.Text = "$cameraCount camera$(if ([int]$cameraCount -eq 1) { '' } else { 's' })"
+  } elseif ($validated -and [int]$validated -gt 0) {
+    $StatusValue.Text = "$validated feed$(if ([int]$validated -eq 1) { '' } else { 's' }) ready"
+  } elseif ($null -ne $devices) {
+    $StatusValue.Text = "$devices device$(if ([int]$devices -eq 1) { '' } else { 's' }) found"
+  } elseif ($stage -eq 'error') {
+    $StatusValue.Text = 'Setup stopped'
+  } else {
+    $StatusValue.Text = 'In progress'
+  }
+
+  if ($stage -eq 'local_ai' -and $localAiPhase -eq 'installing_model' -and $null -ne $localAiTotal) {
+    $totalText = Format-ByteCount $localAiTotal
+    $Metric.Text = if ($totalText) { "Installing the $totalText model included with Trillboards. Cloud inference remains off." } else { 'Installing the included model. Cloud inference remains off.' }
+  } elseif ($stage -eq 'local_ai_error') {
+    $Metric.Text = 'Camera pairing is saved. Retry only the local AI step.'
+  } elseif ($rejected -and [int]$rejected -gt 0) {
+    $Metric.Text = "$rejected black or unavailable input$(if ([int]$rejected -eq 1) { ' was' } else { 's were' }) ignored."
+  } elseif ($stage -eq 'account_attention') {
+    $Metric.Text = 'No cameras were added. It is safe to switch accounts.'
+  } elseif ($stage -eq 'local_ai') {
+    $Metric.Text = 'The included model stays on this computer; cloud inference remains off.'
+  } elseif ($stage -eq 'ready') {
+    $Metric.Text = 'Trillboards starts automatically when this computer logs in.'
+  } elseif ($stage -eq 'error') {
+    $Metric.Text = 'Details are saved in logs\setup-app.log.'
+  } else {
+    $Metric.Text = 'Camera credentials stay encrypted on this computer.'
+  }
+
+  $Progress.Value = [Math]::Max(0, [Math]::Min(100, (Get-ProgressValue $stage $State)))
+  Update-Steps (Get-StepIndex $stage) ($stage -eq 'ready')
+  switch ($stage) {
+    'waiting_for_account' { $Action.Text = 'Open Trillboards'; $Action.Enabled = $true }
+    'account_attention' { $Action.Text = 'Switch account'; $Action.Enabled = $true }
+    'local_ai_error' { $Action.Text = 'Retry local AI'; $Action.Enabled = $true }
+    'ready' { $Action.Text = 'View cameras'; $Action.Enabled = $true }
+    'error' { $Action.Text = 'Try again'; $Action.Enabled = $true }
+    default { $Action.Text = 'Working...'; $Action.Enabled = $false }
+  }
+}
+
+$Action.Add_Click({
+  switch ($script:LastStage) {
+    'waiting_for_account' { Start-Process $script:PortalUrl }
+    'account_attention' { Start-Process $script:PortalUrl }
+    'local_ai_error' { Start-LocalAiSetup }
+    'ready' {
+      Start-Process 'https://trillboards.com/earner/screens'
+      $Form.Close()
+    }
+    'error' { Start-Setup }
+    'welcome' { Start-Setup }
+  }
+})
+
+$Form.Add_FormClosing({
+  Stop-SetupProcess
+  if ($null -ne $script:SetupMutex) {
+    try { $script:SetupMutex.ReleaseMutex() } catch { }
+    $script:SetupMutex.Dispose()
+    $script:SetupMutex = $null
+  }
+})
+
+$Timer = New-Object System.Windows.Forms.Timer
+$Timer.Interval = 500
+$Timer.Add_Tick({
+  if ($script:SetupStarted -and (Test-Path $StatePath)) {
+    try {
+      $state = Get-Content -Raw -Path $StatePath | ConvertFrom-Json
+      Render-State $state
+    } catch {
+      # Atomic writer means this is uncommon; retry on the next tick.
+    }
+  }
+  if ($null -ne $script:PairProcess -and $script:PairProcess.HasExited) {
+    $exitCode = $script:PairProcess.ExitCode
+    $script:PairProcess.Dispose()
+    $script:PairProcess = $null
+    if ($exitCode -ne 0 -and $script:LastStage -notin @('local_ai', 'local_ai_error', 'ready', 'error')) {
+      Show-LocalError 'Setup stopped before finishing' "The camera setup helper exited with code $exitCode. Try again; if it repeats, send setup-app.log to Trillboards support."
+    }
+  }
+})
+Show-Welcome
+if ($SmokeTest) {
+  if ($StepLabels.Count -ne 6 -or $Form.Controls.Count -lt 8 -or $Action.Text -ne 'Start setup') {
+    throw 'Windows setup UI did not construct its expected controls.'
+  }
+  $smokeStartInfo = New-Object System.Diagnostics.ProcessStartInfo
+  $smokeStartInfo.FileName = $env:ComSpec
+  $smokeStartInfo.Arguments = '/d /s /c "ping -n 120 127.0.0.1 >nul"'
+  $smokeStartInfo.UseShellExecute = $false
+  $smokeStartInfo.CreateNoWindow = $true
+  $script:PairProcess = [System.Diagnostics.Process]::Start($smokeStartInfo)
+  $smokeParentId = $script:PairProcess.Id
+  $smokeChildIds = @()
+  for ($attempt = 0; $attempt -lt 20 -and $smokeChildIds.Count -eq 0; $attempt++) {
+    Start-Sleep -Milliseconds 100
+    $smokeChildIds = @(Get-CimInstance Win32_Process -Filter "ParentProcessId = $smokeParentId" | Select-Object -ExpandProperty ProcessId)
+  }
+  Stop-SetupProcess
+  if ($smokeChildIds.Count -eq 0) {
+    throw 'Windows setup cancellation smoke test did not create its child process.'
+  }
+  $trackedIds = @($smokeParentId) + $smokeChildIds
+  $leftRunning = @($trackedIds)
+  for ($attempt = 0; $attempt -lt 20 -and $leftRunning.Count -gt 0; $attempt++) {
+    $leftRunning = @($trackedIds | Where-Object { Get-Process -Id $_ -ErrorAction SilentlyContinue })
+    if ($leftRunning.Count -gt 0) { Start-Sleep -Milliseconds 100 }
+  }
+  if ($leftRunning.Count -gt 0) {
+    throw "Windows setup cancellation left process IDs running: $($leftRunning -join ', ')"
+  }
+  Write-Host 'Trillboards CCTV Setup Windows Forms smoke test passed.'
+  $Form.Dispose()
+  exit 0
+}
+
+$createdNew = $false
+$script:SetupMutex = New-Object System.Threading.Mutex($true, 'Local\TrillboardsCctvSetup', [ref]$createdNew)
+if (-not $createdNew) {
+  $script:SetupMutex.Dispose()
+  $script:SetupMutex = $null
+  $Form.Dispose()
+  exit 0
+}
+
+$Timer.Start()
+[void]$Form.ShowDialog()
+$Timer.Stop()

package/deploy/windows/trillboards-setup.vbs

@@ -0,0 +1,13 @@
+Option Explicit
+
+Dim fso, shell, scriptDir, powerShellScript, command
+Set fso = CreateObject("Scripting.FileSystemObject")
+Set shell = CreateObject("WScript.Shell")
+
+scriptDir = fso.GetParentFolderName(WScript.ScriptFullName)
+powerShellScript = fso.BuildPath(scriptDir, "trillboards-setup.ps1")
+command = "powershell.exe -NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File """ & powerShellScript & """"
+
+' Window style 0 prevents a console flash; the PowerShell process displays only
+' the Windows Forms customer setup application.
+shell.Run command, 0, False

package/dist/AudienceAnalyzeClient.d.ts

@@ -0,0 +1,136 @@
+/**
+ * AudienceAnalyzeClient — POSTs a JPEG frame to the cloud VLM endpoint
+ * `POST {apiBaseUrl}/v2/earner/audience-analyze`.
+ *
+ * This is the ONE genuinely-new piece for cloud sensing: it replaces the
+ * edge-cloud Gemini-direct path. The cloud VLM does the inference; the edge
+ * only grabs a frame and ships it.
+ *
+ * Wire contract mirrors the Android agent-core `FrameCaptureManager.sendToApi`:
+ *   - body: JSON `{ fingerprint?, screenId?, imageBase64, capturedAt, ... }`
+ *   - headers required by `middleware/deviceRequestAuth.js`:
+ *       X-Device-Token            — the per-screen device token
+ *       X-Trillboard-Device-Token — alias header (back-compat)
+ *       X-Device-Timestamp        — epoch ms (replay skew window)
+ *       X-Device-Nonce            — unique per request (replay guard)
+ *
+ * Uses Node's built-in http/https (no extra dependency) so it works inside a
+ * self-contained binary and is trivially mockable in tests.
+ */
+export interface AudienceAnalyzeClientOptions {
+    /** Base URL, e.g. https://api.trillboards.com (no trailing slash needed). */
+    apiBaseUrl: string;
+    /** Device token for X-Device-Token (one feed = one token). */
+    deviceToken: string;
+    /** Screen this client posts for (one feed = one screen). Optional. */
+    screenId?: string;
+    /** Device fingerprint, sent in the body for legacy correlation. Optional. */
+    fingerprint?: string;
+    /** Request timeout in ms. Default: 30000. */
+    timeoutMs?: number;
+    /** Image width sent in the body metadata. Optional. */
+    imageWidth?: number;
+    /** Image height sent in the body metadata. Optional. */
+    imageHeight?: number;
+}
+export interface AudienceAnalyzeRequest {
+    /** Raw JPEG bytes for this frame. */
+    jpeg: Buffer;
+    /** Capture timestamp (epoch ms). Default: Date.now(). */
+    capturedAt?: number;
+    /** Capture mode hint forwarded to the cloud. Optional. */
+    captureMode?: string;
+    /** Extra body fields merged into the payload (e.g. per_face_observations). */
+    extra?: Record<string, unknown>;
+}
+export interface AudienceAnalyzeResponse {
+    /** HTTP status code. */
+    statusCode: number;
+    /** Whether the POST succeeded (2xx). */
+    ok: boolean;
+    /** Parsed JSON body (or null if the body was not valid JSON). */
+    body: Record<string, unknown> | null;
+    /** Raw response text. */
+    rawBody: string;
+}
+export type CameraHealthState = 'never_started' | 'starting' | 'open' | 'failed' | 'closed';
+export type CameraHealthFailureClass = 'rtsp_auth' | 'rtsp_unreachable' | 'rtsp_timeout' | 'nvr_busy' | 'no_frames' | 'decode_error';
+export type CameraSensingState = 'idle' | 'analyzing' | 'active' | 'waiting_for_capacity' | 'unavailable';
+export interface CameraHealthReport {
+    state: CameraHealthState;
+    lastFrameAtMs?: number;
+    retryCount?: number;
+    lastFailureClass?: CameraHealthFailureClass;
+    lastFailureMessage?: string;
+    /** AI/inference state, deliberately separate from RTSP/video health. */
+    sensingState?: CameraSensingState;
+    /** Authenticated attestation that the connector decoded a local frame. */
+    captureProof?: 'decoded_frame';
+}
+/** Minimal injectable HTTP transport — lets tests stub the network entirely. */
+export interface HttpPoster {
+    (url: string, options: {
+        method: string;
+        headers: Record<string, string>;
+        timeoutMs: number;
+    }, body: string): Promise<{
+        statusCode: number;
+        body: string;
+    }>;
+}
+export declare class AudienceAnalyzeClient {
+    private readonly endpoint;
+    private readonly deviceToken;
+    private readonly screenId?;
+    private readonly fingerprint?;
+    private readonly timeoutMs;
+    private readonly imageWidth?;
+    private readonly imageHeight?;
+    private readonly poster;
+    constructor(options: AudienceAnalyzeClientOptions, poster?: HttpPoster);
+    /** The resolved POST URL (exposed for assertions / logging). */
+    getEndpoint(): string;
+    private authHeaders;
+    /**
+     * POST a JPEG frame for cloud audience analysis. Returns the parsed response.
+     */
+    analyze(request: AudienceAnalyzeRequest): Promise<AudienceAnalyzeResponse>;
+    /**
+     * POST a PRE-ANALYZED structured result (computed ON-DEVICE by
+     * LiteRtVlmProvider) to the same audience-analyze endpoint. The server detects
+     * `preAnalyzed`, SKIPS the cloud VLM, and ingests the result directly —
+     * forcing provenance `local_connector` server-side so it drives the
+     * operator's Sense-Anything routes but is gated out of the sold bidstream.
+     * Same device-token auth + replay guard as analyze().
+     *
+     * EVIDENCE FRAME (optional): when `jpeg` (raw bytes) or `imageBase64` (already
+     * base64) is supplied, the SAME JPEG the on-device VLM analyzed is included as
+     * `imageBase64` ALONGSIDE `preAnalyzed`. The server uploads it and attaches it
+     * to any alert the result fires. The caller decides WHETHER to attach it — the
+     * connector only sends a frame for alert-worthy observations (see
+     * localSensing.ts), so this method just forwards what it's given. When neither
+     * is passed, NO `imageBase64` is sent (results-only, privacy-preserving
+     * default for empty/uninteresting scenes).
+     */
+    analyzePreAnalyzed(preAnalyzed: Record<string, unknown>, request?: {
+        capturedAt?: number;
+        captureMode?: string;
+        extra?: Record<string, unknown>;
+        /** Raw JPEG bytes of the analyzed frame — encoded to base64 and sent as `imageBase64`. */
+        jpeg?: Buffer;
+        /** Pre-encoded base64 JPEG of the analyzed frame (alternative to `jpeg`). */
+        imageBase64?: string;
+    }): Promise<AudienceAnalyzeResponse>;
+    /**
+     * POST a FRAMELESS camera-health beacon. This is used when the connector can
+     * pair but cannot open the RTSP stream, so the portal can show "Camera login
+     * failed" / "not reachable" instead of looking like the connector is absent.
+     */
+    reportCameraHealth(cameraHealth: CameraHealthReport): Promise<AudienceAnalyzeResponse>;
+}
+/**
+ * Default transport using Node's built-in http/https. No third-party deps so it
+ * survives bundling into a single self-contained binary.
+ */
+export declare const defaultHttpPoster: HttpPoster;
+//# sourceMappingURL=AudienceAnalyzeClient.d.ts.map

package/dist/AudienceAnalyzeClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudienceAnalyzeClient.d.ts","sourceRoot":"","sources":["../src/AudienceAnalyzeClient.ts"],"names":[],"mappings":"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"}