@trillboards/edge-sdk 0.2.24 → 0.2.25

package/deploy/windows/build-windows.ps1

@@ -202,6 +202,7 @@ Copy-Item -Force "$Here\trillboards-hidden-run.vbs" "$Payload\bin\trillboards-hi
 Copy-Item -Force "$Here\ensure-sensing.ps1"   "$Payload\bin\ensure-sensing.ps1"
 Copy-Item -Force "$Here\run-connector.ps1"      "$Payload\bin\run-connector.ps1"
 Copy-Item -Force "$Here\register-task.ps1"    "$Payload\bin\register-task.ps1"
+Copy-Item -Force "$Here\enroll-connector.ps1" "$Payload\bin\enroll-connector.ps1"
 Copy-Item -Force "$Here\stop-existing.ps1"    "$Payload\bin\stop-existing.ps1"
 Copy-Item -Force "$Here\install-update.ps1"    "$Payload\bin\install-update.ps1"
 # The in-field updater. Ships in bin\ so an INSTALLED connector can drive its own

package/deploy/windows/enroll-connector.ps1

@@ -0,0 +1,169 @@
+<#
+  enroll-connector.ps1 - UNATTENDED provisioning step for an MDM/Intune/SCCM
+  deployment. Invoked by installer.nsi when /ENROLLMENT_TOKEN= was supplied.
+
+  WHAT IT DOES
+    1. Writes the fleet enrollment credential to $InstallDir\trillboards.enrollment
+       with an ACL that grants the installing user ONLY (inheritance disabled),
+       because a plain %LOCALAPPDATA% file inherits whatever the parent grants
+       and this is the one credential in the package that can enroll machines.
+    2. Runs `trillboards-edge enroll`, which exchanges it for THIS machine's own
+       credential, writes that into trillboards.config.json, and DELETES the
+       enrollment file.
+    3. Deletes the file itself if the CLI could not (belt and braces - a fleet
+       credential left on 200 store PCs is the failure this whole design exists
+       to prevent).
+
+  EXIT CODES - these are the installer's, and they are deliberately NOT fatal to
+  the install:
+    0  enrolled, or already enrolled (a re-push is idempotent and free)
+    1  the credential was rejected: expired, revoked, or every enrollment it was
+       issued for is already used. A human must issue a new one.
+    6  network/server failure. The credential was NOT spent; the scheduled task
+       retries on the next logon.
+
+  A failed enrollment leaves a correctly INSTALLED connector that is simply not
+  yet provisioned, which is recoverable by re-running this script or by the
+  ordinary interactive setup. Aborting the whole install instead would leave the
+  machine with nothing and no way to retry.
+#>
+[CmdletBinding()]
+param(
+  [Parameter(Mandatory = $true)][string]$InstallDir,
+  [Parameter(Mandatory = $true)][string]$EnrollmentToken,
+  [string]$SiteLabel = "",
+  [string]$ApiBase = "",
+  # Optional recorder credentials. Passed straight through to the CLI and never
+  # written to disk or to the log - only their PRESENCE is logged.
+  [string]$NvrUser = "",
+  [string]$NvrPass = ""
+)
+
+$ErrorActionPreference = "Stop"
+
+$logDir = Join-Path $env:LOCALAPPDATA "Trillboards\logs"
+New-Item -ItemType Directory -Force -Path $logDir | Out-Null
+$logPath = Join-Path $logDir "enroll.log"
+
+function Write-Log([string]$Message) {
+  # NEVER log the token. Only its shape, so support can match it to a portal row
+  # without the log becoming a credential store.
+  $stamp = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
+  Add-Content -Path $logPath -Value "[$stamp] $Message"
+}
+
+$enrollmentFile = Join-Path $InstallDir "trillboards.enrollment"
+$configPath = Join-Path $InstallDir "trillboards.config.json"
+
+function Remove-EnrollmentFile {
+  if (Test-Path $enrollmentFile) {
+    try {
+      Remove-Item -Force $enrollmentFile
+      Write-Log "enrollment file removed"
+    } catch {
+      Write-Log "WARNING: could not remove enrollment file: $($_.Exception.Message)"
+    }
+  }
+}
+
+try {
+  if ([string]::IsNullOrWhiteSpace($EnrollmentToken)) {
+    Write-Log "no enrollment token supplied; nothing to do"
+    exit 0
+  }
+
+  $tokenShape = if ($EnrollmentToken.Length -gt 11) {
+    "$($EnrollmentToken.Substring(0,7))...$($EnrollmentToken.Substring($EnrollmentToken.Length-4))"
+  } else { "(short)" }
+  $credState = if ([string]::IsNullOrWhiteSpace($NvrUser)) { "absent" } else { "supplied" }
+  Write-Log "starting unattended enrollment (credential $tokenShape, site '$SiteLabel', recorder credentials $credState)"
+
+  New-Item -ItemType Directory -Force -Path $InstallDir | Out-Null
+  # -NoNewline so the CLI's trim() sees exactly the token; ASCII because the key
+  # alphabet is hex and a BOM would corrupt the first character.
+  [System.IO.File]::WriteAllText($enrollmentFile, $EnrollmentToken, [System.Text.UTF8Encoding]::new($false))
+
+  # Owner-only ACL with inheritance broken. %LOCALAPPDATA% is already per-user,
+  # but this file is the one credential that can enroll further machines, so it
+  # does not ride on a directory default that a group policy may widen.
+  try {
+    $acl = Get-Acl $enrollmentFile
+    $acl.SetAccessRuleProtection($true, $false)   # break inheritance, drop inherited ACEs
+    $me = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
+    $rule = New-Object System.Security.AccessControl.FileSystemAccessRule(
+      $me, "FullControl", "None", "None", "Allow")
+    $acl.SetAccessRule($rule)
+    Set-Acl -Path $enrollmentFile -AclObject $acl
+    Write-Log "enrollment file ACL set to owner-only"
+  } catch {
+    # Non-fatal: the file is deleted seconds from now. Losing the ACL is worth a
+    # log line, not a failed rollout.
+    Write-Log "WARNING: could not tighten enrollment file ACL: $($_.Exception.Message)"
+  }
+
+  $node = Join-Path $InstallDir "bin\node.exe"
+  $cli = Join-Path $InstallDir "lib\edge-sdk\dist\cli.js"
+  if (-not (Test-Path $node) -or -not (Test-Path $cli)) {
+    # Retryable and the credential is UNSPENT - keep it so the next-logon retry
+    # can use it once the install finishes laying the tree down.
+    Write-Log "ERROR: connector is not installed at $InstallDir (retryable, credential preserved)"
+    exit 6
+  }
+
+  $cliArgs = @($cli, "enroll", "--config", $configPath, "--enrollment-file", $enrollmentFile)
+  if (-not [string]::IsNullOrWhiteSpace($SiteLabel)) { $cliArgs += @("--site", $SiteLabel) }
+  if (-not [string]::IsNullOrWhiteSpace($ApiBase)) { $cliArgs += @("--api-base", $ApiBase) }
+  if (-not [string]::IsNullOrWhiteSpace($NvrUser)) { $cliArgs += @("--nvr-user", $NvrUser) }
+  if (-not [string]::IsNullOrWhiteSpace($NvrPass)) { $cliArgs += @("--nvr-pass", $NvrPass) }
+
+  $oldPath = $env:PATH
+  $oldNodePath = $env:NODE_PATH
+  try {
+    $env:PATH = "$(Join-Path $InstallDir 'bin');$oldPath"
+    $env:NODE_PATH = Join-Path $InstallDir "lib\node_modules"
+    $output = (& $node @cliArgs 2>&1 | Out-String)
+    $code = $LASTEXITCODE
+  } finally {
+    $env:PATH = $oldPath
+    $env:NODE_PATH = $oldNodePath
+  }
+
+  # The CLI never prints the credential (see maskConnectorKey), so its output is
+  # safe to log verbatim and is the only diagnostic a field failure leaves.
+  Write-Log "enroll exit=$code output=$($output.Trim())"
+
+  # DELETE ONLY ON A TERMINAL OUTCOME.
+  #
+  # The CLI already deletes the file itself on success. The dangerous case is a
+  # RETRYABLE failure: an unconditional delete here would destroy the only
+  # persisted copy of the fleet credential on a transient outage during install,
+  # leaving that store permanently unprovisioned with nothing to retry from - the
+  # opposite of what the exit code says. So the file survives exit 6 and the
+  # next-logon retry in run-connector.ps1 picks it up.
+  #
+  # It IS deleted on a credential REJECTION (exit 1), because that token can
+  # never enroll anything again and leaving a dead credential on disk is pure
+  # exposure.
+  switch ($code) {
+    0 { Remove-EnrollmentFile; Write-Log "enrollment complete, cameras registered"; exit 0 }
+    5 {
+      # Provisioned, but no feeds. The credential is SPENT, so the enrollment
+      # file is done - what is missing is recorder credentials, not a retry.
+      Remove-EnrollmentFile
+      Write-Log "enrolled, but NO camera feeds registered (recorder credentials absent or no recorder found)"
+      exit 5
+    }
+    1 { Remove-EnrollmentFile; Write-Log "enrollment credential REJECTED - a new one must be issued"; exit 1 }
+    4 { Remove-EnrollmentFile; Write-Log "no enrollment token was readable"; exit 1 }
+    default {
+      Write-Log "enrollment deferred (retryable) - credential PRESERVED for the next-logon retry"
+      exit 6
+    }
+  }
+} catch {
+  # An exception here is a local/environmental failure, not a rejected
+  # credential, so it is retryable and the token is preserved for the same
+  # reason as exit 6 above.
+  Write-Log "ERROR (retryable, credential preserved): $($_.Exception.Message)"
+  exit 6
+}

package/deploy/windows/installer.nsi

@@ -1,4 +1,4 @@
-; installer.nsi — Trillboards Edge on-device (local-sense) CCTV connector (Windows).
+; installer.nsi - Trillboards Edge on-device (local-sense) CCTV connector (Windows).
 ; Per-user, no-admin install (RequestExecutionLevel user) that mirrors the
 ; home-domain macOS .pkg: lays down the self-contained tree under
 ; %LOCALAPPDATA%\Trillboards\edge, registers a per-user Scheduled Task that
@@ -26,6 +26,16 @@
 !define LITERT_TASK_NAME "TrillboardsLiteRtLm"
 
 Var ModelSource
+; -- Unattended (MDM/Intune/SCCM) parameters --------------------------------
+; Before these, the installer parsed exactly ONE switch (/MODEL_SOURCE=) and a
+; perfect silent install still left the machine UNPAIRED, because deviceToken is
+; per-camera-feed and the only writers were the interactive pair/setup paths. A
+; silent install that produces a non-working install is not a deployment story.
+Var EnrollmentToken
+Var SiteLabel
+Var NvrUser
+Var NvrPass
+Var IsUnattended
 
 Name "${APP_NAME}"
 OutFile "${OUT_FILE}"
@@ -47,16 +57,61 @@ BrandingText "Trillboards"
 
 ; Finish page: launch the native Windows Forms setup app through wscript. The
 ; setup engine and its cmd wrapper run with CreateNoWindow, so no console flashes.
-!define MUI_FINISHPAGE_RUN "$INSTDIR\bin\trillboards-setup.vbs"
+; MUI_FINISHPAGE_RUN_FUNCTION rather than a bare RUN: an admin who passes
+; /ENROLLMENT_TOKEN= without /S still gets the pages, and launching the
+; interactive camera wizard on a machine that just provisioned itself is exactly
+; the human step this feature removes. (Under /S the finish page never renders
+; at all, so this only matters for the visible-but-unattended case.)
+!define MUI_FINISHPAGE_RUN
+!define MUI_FINISHPAGE_RUN_FUNCTION LaunchSetupAppUnlessUnattended
 !define MUI_FINISHPAGE_RUN_TEXT "Set up my CCTV cameras now"
 !define MUI_FINISHPAGE_TEXT "The connector and private local AI are installed. Continue in the Trillboards CCTV Setup app to pair your cameras."
 !insertmacro MUI_PAGE_FINISH
 
+Function LaunchSetupAppUnlessUnattended
+  ${If} $IsUnattended == 1
+    Return
+  ${EndIf}
+  Exec '"$WINDIR\System32\wscript.exe" "$INSTDIR\bin\trillboards-setup.vbs"'
+FunctionEnd
+
 !insertmacro MUI_UNPAGE_CONFIRM
 !insertmacro MUI_UNPAGE_INSTFILES
 !insertmacro MUI_LANGUAGE "English"
 
 Function .onInit
+  ; -- Unattended parameters ------------------------------------------------
+  ;   /S                        NSIS silent install (no pages, no prompts)
+  ;   /ENROLLMENT_TOKEN=<tok>   the FLEET enrollment credential from the portal
+  ;   /SITE="Store 0417"        free-text install label carried into the rollout
+  ;                             view and prefixed onto camera names
+  ;
+  ; The token is written to $INSTDIR\trillboards.enrollment and the connector
+  ; DELETES that file the moment it has exchanged it for this machine's own
+  ; credential - a bootstrap credential must not outlive its bootstrap, or every
+  ; store PC keeps something that can enroll more machines.
+  ${GetParameters} $R0
+  ${GetOptions} $R0 "/ENROLLMENT_TOKEN=" $EnrollmentToken
+  ${GetOptions} $R0 "/SITE=" $SiteLabel
+  ; Recorder credentials are OPTIONAL and the deployment is useful without them:
+  ; with none, the machine still provisions its own identity and simply registers
+  ; no feeds. With them the install is genuinely zero-touch, because the channels
+  ; on the cheap DVRs this product targets cannot be opened otherwise - and
+  ; registering a channel we cannot open would mint a screen that is permanently
+  ; dark. Whether the recorder password belongs in an MDM package is the
+  ; customer's call, which is why this is a switch and not a requirement.
+  ${GetOptions} $R0 "/NVR_USER=" $NvrUser
+  ${GetOptions} $R0 "/NVR_PASS=" $NvrPass
+
+  ; "Unattended" is silent OR token-driven: an admin scripting a visible install
+  ; still wants no prompts to block the run.
+  StrCpy $IsUnattended 0
+  ${If} ${Silent}
+    StrCpy $IsUnattended 1
+  ${ElseIf} $EnrollmentToken != ""
+    StrCpy $IsUnattended 1
+  ${EndIf}
+
   ; The SFX launcher passes its absolute extraction path. Keep the environment
   ; value as an engineering and recovery fallback for the signed inner package.
   ReadEnvStr $ModelSource "TRILLBOARDS_BUNDLED_MODEL_PATH"
@@ -70,7 +125,12 @@ Function .onInit
       SetErrorLevel 2
       Quit
     ${EndIf}
-    MessageBox MB_ICONSTOP|MB_OK "This installer is missing its included local AI model. Download the complete Trillboards CCTV installer and try again."
+    ; /SD IDOK: under /S a modal has nobody to click it and the install hangs
+    ; forever. The default answer dismisses the box; the Abort on the next line
+    ; is what actually decides the outcome, so a silent run FAILS here rather
+    ; than proceeding without a model.
+    MessageBox MB_ICONSTOP|MB_OK "This installer is missing its included local AI model. Download the complete Trillboards CCTV installer and try again." /SD IDOK
+    SetErrorLevel 2
     Abort
   ${EndIf}
 
@@ -111,7 +171,8 @@ Section "Install"
   nsExec::ExecToLog 'powershell -NoProfile -ExecutionPolicy Bypass -File "$PLUGINSDIR\install-update.ps1" -InstallDir "$INSTDIR" -StagingDir "$INSTDIR\.update-staging"'
   Pop $0
   ${If} $0 != 0
-    MessageBox MB_ICONSTOP|MB_OK "Trillboards CCTV setup could not be updated safely. Your previous connector was restored. Please retry the installer."
+    MessageBox MB_ICONSTOP|MB_OK "Trillboards CCTV setup could not be updated safely. Your previous connector was restored. Please retry the installer." /SD IDOK
+    SetErrorLevel 3
     Abort
   ${EndIf}
   SetOutPath "$INSTDIR"
@@ -120,18 +181,49 @@ Section "Install"
   ; is synchronous and required: pairing is never offered while AI is absent or
   ; still downloading in the background.
   ${IfNot} ${FileExists} "$ModelSource"
-    MessageBox MB_ICONSTOP|MB_OK "The local AI model included with this installer could not be found. Download a fresh Trillboards CCTV installer."
+    MessageBox MB_ICONSTOP|MB_OK "The local AI model included with this installer could not be found. Download a fresh Trillboards CCTV installer." /SD IDOK
+    SetErrorLevel 2
     Abort
   ${EndIf}
   DetailPrint "Installing and verifying private local AI..."
   nsExec::ExecToLog '"$WINDIR\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -ExecutionPolicy Bypass -File "$INSTDIR\bin\setup-litertlm.ps1" -BundledModelPath "$ModelSource" -RequireBundledModel'
   Pop $0
   ${If} $0 != 0
-    MessageBox MB_ICONSTOP|MB_OK "Private local AI could not be installed. Camera pairing has not started. Download a fresh installer or contact Trillboards support."
+    MessageBox MB_ICONSTOP|MB_OK "Private local AI could not be installed. Camera pairing has not started. Download a fresh installer or contact Trillboards support." /SD IDOK
+    SetErrorLevel 4
     Abort
   ${EndIf}
   DetailPrint "Private local AI is installed and healthy."
 
+  ; -- Unattended provisioning ----------------------------------------------
+  ; With /ENROLLMENT_TOKEN=, the machine provisions ITSELF here - no code typed
+  ; at the machine, no browser, no human. enroll-connector.ps1 writes the
+  ; credential owner-only, exchanges it for this machine's own credential, and
+  ; deletes it.
+  ;
+  ; A failed enrollment does NOT abort the install. The connector is correctly
+  ; installed either way; what is missing is provisioning, which is retryable
+  ; (re-run the package, or use the ordinary interactive setup). Aborting would
+  ; leave the store with nothing and no path forward - strictly worse than an
+  ; installed-but-unprovisioned connector that a support call can finish.
+  ${If} $EnrollmentToken != ""
+    DetailPrint "Provisioning this connector..."
+    nsExec::ExecToLog '"$WINDIR\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -ExecutionPolicy Bypass -File "$INSTDIR\bin\enroll-connector.ps1" -InstallDir "$INSTDIR" -EnrollmentToken "$EnrollmentToken" -SiteLabel "$SiteLabel" -NvrUser "$NvrUser" -NvrPass "$NvrPass"'
+    Pop $0
+    ${If} $0 == 0
+      DetailPrint "Connector provisioned and cameras registered."
+    ${ElseIf} $0 == 5
+      DetailPrint "Connector provisioned, but no camera feeds were registered. Supply /NVR_USER= and /NVR_PASS=, or finish in the portal."
+      SetErrorLevel 5
+    ${ElseIf} $0 == 1
+      DetailPrint "Enrollment credential was rejected (expired, revoked, or fully used). Issue a new one in the portal."
+      SetErrorLevel 5
+    ${Else}
+      DetailPrint "Enrollment could not reach Trillboards; it will be retried. The credential was not used."
+      SetErrorLevel 6
+    ${EndIf}
+  ${EndIf}
+
   ; Start Menu shortcuts.
   CreateDirectory "$SMPROGRAMS\Trillboards"
   CreateShortcut "$SMPROGRAMS\Trillboards\Trillboards CCTV Setup.lnk" "$WINDIR\System32\wscript.exe" '$\"$INSTDIR\bin\trillboards-setup.vbs$\"'
@@ -154,6 +246,10 @@ Section "Uninstall"
   nsExec::ExecToLog 'schtasks /Delete /F /TN "${TASK_NAME}"'
   nsExec::ExecToLog 'schtasks /End /TN "${LITERT_TASK_NAME}"'
   nsExec::ExecToLog 'schtasks /Delete /F /TN "${LITERT_TASK_NAME}"'
+  ; Explicit, ahead of RMDir /r: a fleet enrollment credential must never
+  ; survive an uninstall, and relying on the recursive delete makes that a
+  ; property of statement ORDER rather than of intent.
+  Delete "$INSTDIR\trillboards.enrollment"
   Delete "$SMPROGRAMS\Trillboards\Pair a camera.lnk"
   Delete "$SMPROGRAMS\Trillboards\Trillboards CCTV Setup.lnk"
   Delete "$SMPROGRAMS\Trillboards\Uninstall Trillboards Edge.lnk"

package/deploy/windows/run-connector.ps1

@@ -30,6 +30,36 @@ if ((Test-Path $logPath) -and (Get-Item $logPath).Length -ge $maxLogBytes) {
   Move-ConnectorLogs
 }
 
+# ---------------------------------------------------------------------------
+# Unattended-provisioning retry, at every logon.
+#
+# THE FAILURE THIS EXISTS FOR: enrollment runs once, inside the installer. If the
+# store's link is down at that moment - a DSL blip, a captive portal, a firewall
+# rule not yet pushed - the credential is unspent and the machine is installed
+# but unprovisioned, with nothing scheduled to try again. Across a 200-store push
+# that is a handful of stores permanently dark for a reason nobody can see.
+#
+# The scheduled task already runs this supervisor at every logon, so the retry
+# belongs here rather than in a second task nobody would remember to register.
+#
+# It fires ONLY when the enrollment file still exists, and enroll-connector.ps1
+# leaves it there only for retryable outcomes - a spent or rejected credential is
+# deleted, so this cannot become a loop hammering a dead token.
+$enrollmentFile = Join-Path $InstallDir "trillboards.enrollment"
+$enrollScript = Join-Path $InstallDir "bin\enroll-connector.ps1"
+if ((Test-Path $enrollmentFile) -and (Test-Path $enrollScript)) {
+  try {
+    $pendingToken = (Get-Content -Raw -Path $enrollmentFile).Trim()
+    if ($pendingToken) {
+      & $enrollScript -InstallDir $InstallDir -EnrollmentToken $pendingToken | Out-Null
+    }
+  } catch {
+    # Never let a provisioning retry stop the connector from starting: a machine
+    # that is already provisioned and simply has a stale file must still sense.
+    # The detail lands in enroll.log, which is where a support call looks.
+  }
+}
+
 $writer = $null
 $process = $null
 try {

package/dist/ConnectorCameraClient.d.ts

@@ -0,0 +1,79 @@
+import { type HttpPoster } from './AudienceAnalyzeClient';
+import type { CameraFeedConfig } from './config';
+import type { DiscoveredCamera } from './discovery';
+/**
+ * ConnectorCameraClient — registers the feeds this machine found, using THIS
+ * machine's own connector credential, and turns the answer into `cameras[]`.
+ *
+ * This is the consumer of `connector.key` and the producer for
+ * `POST /v2/earner/connectors/cameras`. Without it the unattended path stops one
+ * step short of useful: the machine has an identity, and no feeds, and no device
+ * tokens — so `auto-sense` finds no `cameras[]` and exits through its no-feeds
+ * path while the installer reports success. A human would still have to run the
+ * interactive camera setup, which is the exact step this whole feature removes.
+ *
+ * WHAT IT SENDS, AND WHAT IT DOES NOT. The body carries only a stable
+ * `cameraKey` per feed plus a display name — never the RTSP URL and never the
+ * recorder credentials. Those stay on this machine: the server mints one screen
+ * + device token per `cameraKey`, and the URLs are matched back to the returned
+ * tokens locally, below. That preserves the property the interactive setup
+ * already has and is worth selling — the connection details never leave the
+ * venue on this path.
+ *
+ * The owner is NOT in the body. It comes from the credential server-side.
+ */
+export interface ConnectorCameraClientOptions {
+    apiBaseUrl: string;
+    /** This machine's connector credential (`connector.key`). */
+    connectorKey: string;
+    timeoutMs?: number;
+}
+/** One feed as the server needs to see it — no URL, no credentials. */
+export interface RegisterCameraInput {
+    cameraKey: string;
+    name?: string;
+    brand?: string;
+    latitude?: number;
+    longitude?: number;
+}
+export interface RegisteredCamera {
+    screenId: string;
+    deviceId: string;
+    deviceToken: string;
+    cameraKey: string;
+    name: string;
+    isReRegistration?: boolean;
+}
+export interface RegisterResult {
+    ok: boolean;
+    cameras?: RegisteredCamera[];
+    error?: string;
+    /** Same taxonomy as EnrollClient — see there for why it matters. */
+    kind?: 'auth' | 'network' | 'server' | 'invalid';
+}
+/** The server caps a single registration call; mirrors MAX_CAMERAS_PER_CALL. */
+export declare const MAX_CAMERAS_PER_CALL = 64;
+export declare class ConnectorCameraClient {
+    private readonly endpoint;
+    private readonly connectorKey;
+    private readonly timeoutMs;
+    private readonly poster;
+    constructor(options: ConnectorCameraClientOptions, poster?: HttpPoster);
+    registerCameras(cameras: RegisterCameraInput[]): Promise<RegisterResult>;
+}
+/**
+ * Join the server's answer back to the LOCAL stream URLs, producing the
+ * `cameras[]` the connector runs on.
+ *
+ * Matching is by `cameraKey` and ONLY by `cameraKey` — never by name and never
+ * by array position. Names are truncated server-side (200 chars) so two feeds
+ * differing only past that point would collapse onto one screen, and the server
+ * is free to return fewer rows than were sent. `cameraKey` is the deterministic
+ * idempotency key both sides already agree on.
+ *
+ * A returned camera with no local match is DROPPED rather than guessed at: a
+ * feed configured with the wrong URL would sense the wrong room, which is worse
+ * than a feed that is absent and visibly missing from the camera board.
+ */
+export declare function buildCameraFeeds(registered: RegisteredCamera[], discovered: DiscoveredCamera[]): CameraFeedConfig[];
+//# sourceMappingURL=ConnectorCameraClient.d.ts.map

package/dist/ConnectorCameraClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConnectorCameraClient.d.ts","sourceRoot":"","sources":["../src/ConnectorCameraClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC7E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,4BAA4B;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,uEAAuE;AACvE,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;CAClD;AAED,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;gBAExB,OAAO,EAAE,4BAA4B,EAAE,MAAM,GAAE,UAA8B;IAUnF,eAAe,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC;CAmE/E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,gBAAgB,EAAE,EAC9B,UAAU,EAAE,gBAAgB,EAAE,GAC7B,gBAAgB,EAAE,CAiBpB"}

package/dist/ConnectorCameraClient.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectorCameraClient = exports.MAX_CAMERAS_PER_CALL = void 0;
+exports.buildCameraFeeds = buildCameraFeeds;
+const AudienceAnalyzeClient_1 = require("./AudienceAnalyzeClient");
+/** The server caps a single registration call; mirrors MAX_CAMERAS_PER_CALL. */
+exports.MAX_CAMERAS_PER_CALL = 64;
+class ConnectorCameraClient {
+    constructor(options, poster = AudienceAnalyzeClient_1.defaultHttpPoster) {
+        if (!options?.apiBaseUrl)
+            throw new Error('ConnectorCameraClient requires an apiBaseUrl');
+        if (!options?.connectorKey)
+            throw new Error('ConnectorCameraClient requires a connectorKey');
+        const base = options.apiBaseUrl.replace(/\/+$/, '');
+        this.endpoint = `${base}/v2/earner/connectors/cameras`;
+        this.connectorKey = options.connectorKey;
+        this.timeoutMs = options.timeoutMs ?? 60000;
+        this.poster = poster;
+    }
+    async registerCameras(cameras) {
+        if (!Array.isArray(cameras) || cameras.length === 0) {
+            return { ok: false, error: 'registerCameras() requires at least one camera', kind: 'invalid' };
+        }
+        if (cameras.length > exports.MAX_CAMERAS_PER_CALL) {
+            return {
+                ok: false,
+                error: `registerCameras() accepts at most ${exports.MAX_CAMERAS_PER_CALL} cameras per call`,
+                kind: 'invalid',
+            };
+        }
+        let response;
+        try {
+            response = await this.poster(this.endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                    Authorization: `Bearer ${this.connectorKey}`,
+                },
+                timeoutMs: this.timeoutMs,
+            }, JSON.stringify({ cameras }));
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: `camera registration failed: ${err?.message ?? 'unknown error'}`,
+                kind: 'network',
+            };
+        }
+        let parsed = null;
+        try {
+            parsed = JSON.parse(response.body);
+        }
+        catch {
+            parsed = null;
+        }
+        const code = response.statusCode;
+        if (code < 200 || code >= 300) {
+            const kind = code === 401 || code === 403 ? 'auth' : code === 400 ? 'invalid' : 'server';
+            return {
+                ok: false,
+                error: parsed?.error || `camera registration failed (HTTP ${code})`,
+                kind,
+            };
+        }
+        const list = Array.isArray(parsed?.cameras) ? parsed.cameras : [];
+        // A 2xx that carries no tokens is a failure, not an empty success — treating
+        // it as success would write a `cameras[]` with no credentials and the defect
+        // would surface much later as a feed that never posts.
+        if (list.length === 0 || list.some((c) => !c?.deviceToken || !c?.screenId)) {
+            return {
+                ok: false,
+                error: 'registration response did not contain device tokens for every camera',
+                kind: 'server',
+            };
+        }
+        return { ok: true, cameras: list };
+    }
+}
+exports.ConnectorCameraClient = ConnectorCameraClient;
+/**
+ * Join the server's answer back to the LOCAL stream URLs, producing the
+ * `cameras[]` the connector runs on.
+ *
+ * Matching is by `cameraKey` and ONLY by `cameraKey` — never by name and never
+ * by array position. Names are truncated server-side (200 chars) so two feeds
+ * differing only past that point would collapse onto one screen, and the server
+ * is free to return fewer rows than were sent. `cameraKey` is the deterministic
+ * idempotency key both sides already agree on.
+ *
+ * A returned camera with no local match is DROPPED rather than guessed at: a
+ * feed configured with the wrong URL would sense the wrong room, which is worse
+ * than a feed that is absent and visibly missing from the camera board.
+ */
+function buildCameraFeeds(registered, discovered) {
+    const byKey = new Map(discovered.map((d) => [d.cameraKey, d]));
+    const feeds = [];
+    for (const cam of registered) {
+        const local = byKey.get(cam.cameraKey);
+        if (!local?.rtspUrl)
+            continue;
+        feeds.push({
+            name: cam.name || local.name,
+            screenId: cam.screenId,
+            deviceToken: cam.deviceToken,
+            rtspUrl: local.rtspUrl,
+            sourceType: local.source === 'channel-range' ? 'recorder' : 'direct_url',
+            channelKey: cam.cameraKey,
+            transport: 'tcp',
+        });
+    }
+    return feeds;
+}
+//# sourceMappingURL=ConnectorCameraClient.js.map

package/dist/ConnectorCameraClient.js.map

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

package/dist/EdgeAgent.js

@@ -44,7 +44,7 @@ const edge_ads_1 = require("@trillboards/edge-ads");
 const CommandRouter_1 = require("./CommandRouter");
 const config_1 = require("./config");
 const dataDir_1 = require("./dataDir");
-const SDK_VERSION = '0.2.24';
+const SDK_VERSION = '0.2.25';
 class EdgeAgent extends events_1.EventEmitter {
     constructor(config, deps) {
         super();