docs(iot-hub): implementation plan for item deep-link feature

Nine bite-sized tasks (i18n, utils, API methods, warning dialog, detail dialog badge, resolver component, routing, type-page handoff, smoke test) each verified by build + manual walkthrough. No frontend unit tests because ui-ngx has no test runner configured.
5 months ago · 214329e437
1 changed files with 936 additions and 0 deletions
--- a/docs/superpowers/plans/2026-04-22-iot-hub-item-deep-link.md
+++ b/docs/superpowers/plans/2026-04-22-iot-hub-item-deep-link.md
@ -0,0 +1,936 @@
 # IoT Hub item deep link — Implementation Plan
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 **Goal:** Ship `/iot-hub/{itemId}` (published) and `/iot-hub/{itemId}/preview` (unpublished-with-warning) deep links that resolve an item, navigate to its type-specific browse page, and open the existing detail dialog.
 **Architecture:** A router-reachable `TbIotHubItemResolverComponent` owns resolution: fetch by itemId, (optionally) gate on a blocking warning dialog, then `router.navigate` to `/iot-hub/{typeSegment(type)}` carrying the version in `history.state`. The target type-page consumes the state once and opens the existing `TbIotHubItemDetailDialogComponent` via `IotHubActionsService`, with a new `preview` flag that adds an "Unpublished preview" badge. Zero ThingsBoard backend changes — install flows reuse existing versionId endpoints.
 **Tech Stack:** Angular 20, Angular Material dialogs, NgRx (for toast dispatch), RxJS. TypeScript strict mode.
 **Note on testing:** `ui-ngx` has no frontend test runner wired up (no `npm test` script, no karma/jest config). Each task is verified by `npm run lint` + `npm run build:prod` passing and, for flow-level tasks, a manual dev-server smoke test documented in the final task.
 **Prerequisite (external):** The two new IoT Hub endpoints (`GET /api/items/{itemId}/published` and `GET /api/items/{itemId}/latest`) must be deployed on the target IoT Hub instance for end-to-end testing. Until they land, local verification can be done against a mocked IoT Hub or against the published endpoint only. See the spec (`docs/superpowers/specs/2026-04-22-iot-hub-item-deep-link-design.md`) for the full IoT Hub-side contract.
 ---
 ## File structure
 **Create:**
 - `ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub-deep-link.utils.ts` — UUID check, type→route-segment mapping, `isPublished` predicate
 - `ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub-item-resolver.component.ts` — route-reachable controller
 - `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-unpublished-warning-dialog.component.ts` — warning dialog logic
 - `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-unpublished-warning-dialog.component.html` — warning dialog template
 - `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-unpublished-warning-dialog.component.scss` — warning dialog styles
 **Modify:**
 - `ui-ngx/src/app/core/http/iot-hub-api.service.ts` — add `getPublishedVersion`, `getLatestVersion`
 - `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-detail-dialog.component.ts` — add `preview` field on data + component
 - `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-detail-dialog.component.html` — preview badge markup
 - `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-detail-dialog.component.scss` — preview badge styles
 - `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-actions.service.ts` — propagate `preview` in `openItemDetail`
 - `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-components.module.ts` — declare + export warning dialog
 - `ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub-routing.module.ts` — two new child routes (placed last)
 - `ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub.module.ts` — declare resolver component
 - `ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub-items-page.component.ts` — `maybeOpenDeepLinkedItem` handoff
 - `ui-ngx/src/assets/locale/locale.constant-en_US.json` — 9 new i18n keys under the existing `"iot-hub"` block
 ---
 ### Task 1: Add i18n keys
 Add all new English strings up front so later tasks can reference them freely. Other locales follow the existing project convention (en_US only for new iot-hub keys; translators backfill later).
 **Files:**
 - Modify: `ui-ngx/src/assets/locale/locale.constant-en_US.json`
 - [ ] **Step 1: Add keys inside the existing `"iot-hub"` block**
 Open `ui-ngx/src/assets/locale/locale.constant-en_US.json`, find the `"iot-hub"` block (starts at the line matching `"iot-hub": {`), and append the following nine keys to it (place them immediately before the closing `}` of the `"iot-hub"` object, keeping JSON valid — i.e. add a trailing comma to the previous key):
 ```json
        "item-detail": "IoT Hub item",
        "item-preview": "IoT Hub item preview",
        "unpublished-warning-title": "Unpublished content",
        "unpublished-warning-text": "This is a preview of unpublished content. It has not been reviewed by IoT Hub. Installing unverified content can introduce security and stability risks — only continue if you trust the creator.",
        "unpublished-warning-confirm": "I understand the risk, continue",
        "unpublished-preview": "Unpublished preview",
        "deep-link-invalid-id": "Invalid IoT Hub item link.",
        "deep-link-not-found": "This IoT Hub item doesn't exist or was removed.",
        "deep-link-fetch-failed": "Couldn't load IoT Hub item. Please try again."
 ```
 - [ ] **Step 2: Validate JSON**
 Run:
 ```bash
 cd ui-ngx && node -e "JSON.parse(require('fs').readFileSync('src/assets/locale/locale.constant-en_US.json', 'utf8')); console.log('OK')"
 ```
 Expected output: `OK`.
 - [ ] **Step 3: Commit**
 ```bash
 git add ui-ngx/src/assets/locale/locale.constant-en_US.json
 git commit -m "feat(iot-hub): add i18n keys for item deep-link and unpublished warning"
 ```
 ---
 ### Task 2: Deep-link utility module
 A tiny, pure-TS helper file. No Angular deps. Exported functions are used by the resolver and (for `isPublished`) by the detail dialog.
 **Files:**
 - Create: `ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub-deep-link.utils.ts`
 - [ ] **Step 1: Create the file**
 Create `ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub-deep-link.utils.ts` with:
 ```ts
 ///
 /// Copyright © 2016-2026 The Thingsboard Authors
 ///
 /// Licensed under the Apache License, Version 2.0 (the "License");
 /// you may not use this file except in compliance with the License.
 /// You may obtain a copy of the License at
 ///
 ///     http://www.apache.org/licenses/LICENSE-2.0
 ///
 /// Unless required by applicable law or agreed to in writing, software
 /// distributed under the License is distributed on an "AS IS" BASIS,
 /// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 /// See the License for the specific language governing permissions and
 /// limitations under the License.
 ///
 import { ItemType } from '@shared/models/iot-hub/iot-hub-item.models';
 import { MpItemVersionView } from '@shared/models/iot-hub/iot-hub-version.models';
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export function isUUID(s: string | null | undefined): s is string {
  return !!s && UUID_RE.test(s);
 }
 export function typeSegment(t: ItemType): string | undefined {
  switch (t) {
    case ItemType.WIDGET: return 'widgets';
    case ItemType.DASHBOARD: return 'dashboards';
    case ItemType.SOLUTION_TEMPLATE: return 'solution-templates';
    case ItemType.CALCULATED_FIELD: return 'calculated-fields';
    case ItemType.RULE_CHAIN: return 'rule-chains';
    case ItemType.DEVICE: return 'devices';
    default: return undefined;
  }
 }
 export function isPublished(v: MpItemVersionView): boolean {
  return !!v.publishedTime && v.publishedTime > 0;
 }
 export interface DeepLinkOpenItem {
  version: MpItemVersionView;
  preview: boolean;
 }
 ```
 - [ ] **Step 2: Verify TypeScript compiles**
 Run:
 ```bash
 cd ui-ngx && node --max_old_space_size=4096 ./node_modules/@angular/cli/bin/ng build --configuration production 2>&1 | tail -20
 ```
 Expected: build succeeds. If `ng build` is too slow for iteration, use `npx tsc --noEmit -p tsconfig.json 2>&1 | grep iot-hub-deep-link || echo 'no type errors in utils file'`.
 - [ ] **Step 3: Commit**
 ```bash
 git add ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub-deep-link.utils.ts
 git commit -m "feat(iot-hub): add deep-link utility helpers (isUUID, typeSegment, isPublished)"
 ```
 ---
 ### Task 3: IoT Hub API service — two new methods
 Add `getPublishedVersion` and `getLatestVersion` to `IotHubApiService`. Both hit IoT Hub cross-origin endpoints (same `baseUrl` as existing `/api/versions/published`).
 **Files:**
 - Modify: `ui-ngx/src/app/core/http/iot-hub-api.service.ts`
 - [ ] **Step 1: Add the two methods**
 Open `ui-ngx/src/app/core/http/iot-hub-api.service.ts`. Insert the following two methods immediately after `getVersionInfo` (which ends near line 100):
 ```ts
  public getPublishedVersion(itemId: string, config?: IotHubRequestConfig): Observable<MpItemVersionView> {
    return this.http.get<MpItemVersionView>(
      `${this.baseUrl}/api/items/${itemId}/published`,
      { params: this.buildParams(config) }
    );
  }
  public getLatestVersion(itemId: string, config?: IotHubRequestConfig): Observable<MpItemVersionView> {
    return this.http.get<MpItemVersionView>(
      `${this.baseUrl}/api/items/${itemId}/latest`,
      { params: this.buildParams(config) }
    );
  }
 ```
 Use the exact `Edit` tool call: `old_string` should be the line `  public getVersionReadme(versionId: string, config?: IotHubRequestConfig): Observable<string> {` (and enough context around it), and `new_string` should prepend the two new methods above it.
 - [ ] **Step 2: Verify build**
 Run:
 ```bash
 cd ui-ngx && node --max_old_space_size=4096 ./node_modules/@angular/cli/bin/ng build --configuration production 2>&1 | tail -15
 ```
 Expected: build succeeds.
 - [ ] **Step 3: Commit**
 ```bash
 git add ui-ngx/src/app/core/http/iot-hub-api.service.ts
 git commit -m "feat(iot-hub): add getPublishedVersion and getLatestVersion API methods"
 ```
 ---
 ### Task 4: Unpublished warning dialog component
 New dialog styled after `TbIotHubDeleteDialogComponent`: title, description, item summary, Cancel + danger-accented confirm button. Returns `boolean` from `afterClosed`.
 **Files:**
 - Create: `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-unpublished-warning-dialog.component.ts`
 - Create: `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-unpublished-warning-dialog.component.html`
 - Create: `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-unpublished-warning-dialog.component.scss`
 - Modify: `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-components.module.ts`
 - [ ] **Step 1: Create the component .ts**
 Create `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-unpublished-warning-dialog.component.ts`:
 ```ts
 ///
 /// Copyright © 2016-2026 The Thingsboard Authors
 ///
 /// Licensed under the Apache License, Version 2.0 (the "License");
 /// you may not use this file except in compliance with the License.
 /// You may obtain a copy of the License at
 ///
 ///     http://www.apache.org/licenses/LICENSE-2.0
 ///
 /// Unless required by applicable law or agreed to in writing, software
 /// distributed under the License is distributed on an "AS IS" BASIS,
 /// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 /// See the License for the specific language governing permissions and
 /// limitations under the License.
 ///
 import { Component, Inject } from '@angular/core';
 import { MAT_DIALOG_DATA, MatDialogRef } from '@angular/material/dialog';
 import { Router } from '@angular/router';
 import { Store } from '@ngrx/store';
 import { AppState } from '@core/core.state';
 import { DialogComponent } from '@shared/components/dialog.component';
 import { MpItemVersionView } from '@shared/models/iot-hub/iot-hub-version.models';
 export interface IotHubUnpublishedWarningDialogData {
  item: MpItemVersionView;
 }
@Component({
  selector: 'tb-iot-hub-unpublished-warning-dialog',
  standalone: false,
  templateUrl: './iot-hub-unpublished-warning-dialog.component.html',
  styleUrls: ['./iot-hub-unpublished-warning-dialog.component.scss']
 })
 export class TbIotHubUnpublishedWarningDialogComponent extends DialogComponent<TbIotHubUnpublishedWarningDialogComponent, boolean> {
  constructor(
    protected store: Store<AppState>,
    protected router: Router,
    protected dialogRef: MatDialogRef<TbIotHubUnpublishedWarningDialogComponent, boolean>,
    @Inject(MAT_DIALOG_DATA) public data: IotHubUnpublishedWarningDialogData
  ) {
    super(store, router, dialogRef);
  }
  confirm(): void {
    this.dialogRef.close(true);
  }
  cancel(): void {
    this.dialogRef.close(false);
  }
 }
 ```
 - [ ] **Step 2: Create the component .html**
 Create `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-unpublished-warning-dialog.component.html`:
 ```html
 <!--
    Copyright © 2016-2026 The Thingsboard Authors
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
        http://www.apache.org/licenses/LICENSE-2.0
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
 -->
 <div class="tb-iot-hub-warning-content">
  <div class="tb-iot-hub-warning-title-row">
    <mat-icon class="tb-iot-hub-warning-icon">warning</mat-icon>
    <h2 class="tb-iot-hub-warning-title">{{ 'iot-hub.unpublished-warning-title' | translate }}</h2>
  </div>
  <p class="tb-iot-hub-warning-text">{{ 'iot-hub.unpublished-warning-text' | translate }}</p>
  <div class="tb-iot-hub-warning-item">
    <span class="tb-iot-hub-warning-item-name">{{ data.item.name }}</span>
    <span class="tb-iot-hub-warning-item-version">v {{ data.item.version }}</span>
  </div>
 </div>
 <div class="tb-iot-hub-warning-actions">
  <button mat-button (click)="cancel()">{{ 'action.cancel' | translate }}</button>
  <button mat-flat-button color="warn" (click)="confirm()">{{ 'iot-hub.unpublished-warning-confirm' | translate }}</button>
 </div>
 ```
 - [ ] **Step 3: Create the component .scss**
 Create `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-unpublished-warning-dialog.component.scss`:
 ```scss
 /**
 * Copyright © 2016-2026 The Thingsboard Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 .tb-iot-hub-warning-content {
  display: flex;
  flex-direction: column;
  gap: 16px;
  padding: 24px;
  max-width: 480px;
 }
 .tb-iot-hub-warning-title-row {
  display: flex;
  align-items: center;
  gap: 12px;
 }
 .tb-iot-hub-warning-icon {
  color: #d32f2f;
  font-size: 28px;
  width: 28px;
  height: 28px;
 }
 .tb-iot-hub-warning-title {
  font-size: 20px;
  font-weight: 600;
  line-height: 24px;
  letter-spacing: 0.1px;
  color: rgba(0, 0, 0, 0.87);
  margin: 0;
 }
 .tb-iot-hub-warning-text {
  font-size: 14px;
  font-weight: 400;
  line-height: 20px;
  letter-spacing: 0.2px;
  color: rgba(0, 0, 0, 0.75);
  margin: 0;
 }
 .tb-iot-hub-warning-item {
  display: flex;
  align-items: baseline;
  gap: 8px;
  padding: 12px 16px;
  background: rgba(211, 47, 47, 0.08);
  border-left: 3px solid #d32f2f;
  border-radius: 2px;
  .tb-iot-hub-warning-item-name {
    font-weight: 600;
    color: rgba(0, 0, 0, 0.87);
  }
  .tb-iot-hub-warning-item-version {
    font-size: 13px;
    color: rgba(0, 0, 0, 0.54);
  }
 }
 .tb-iot-hub-warning-actions {
  display: flex;
  align-items: center;
  justify-content: flex-end;
  gap: 8px;
  padding: 8px;
 }
 ```
 - [ ] **Step 4: Register in `IotHubComponentsModule`**
 Open `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-components.module.ts`.
 Add the import line after the existing `TbIotHubDeleteDialogComponent` import:
 ```ts
 import { TbIotHubUnpublishedWarningDialogComponent } from './iot-hub-unpublished-warning-dialog.component';
 ```
 In the `declarations` array, add `TbIotHubUnpublishedWarningDialogComponent` after `TbIotHubDeleteDialogComponent`.
 In the `exports` array, add `TbIotHubUnpublishedWarningDialogComponent` after `TbIotHubDeleteDialogComponent`.
 - [ ] **Step 5: Verify build**
 Run:
 ```bash
 cd ui-ngx && node --max_old_space_size=4096 ./node_modules/@angular/cli/bin/ng build --configuration production 2>&1 | tail -15
 ```
 Expected: build succeeds.
 - [ ] **Step 6: Commit**
 ```bash
 git add ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-unpublished-warning-dialog.component.ts \
        ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-unpublished-warning-dialog.component.html \
        ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-unpublished-warning-dialog.component.scss \
        ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-components.module.ts
 git commit -m "feat(iot-hub): add unpublished content warning dialog"
 ```
 ---
 ### Task 5: Detail dialog `preview` flag + badge, actions service signature
 Add `preview?: boolean` to `IotHubItemDetailDialogData`, store on the component, render an "Unpublished preview" badge in the meta-bar next to the version chip. Extend `IotHubActionsService.openItemDetail` to forward the flag.
 **Files:**
 - Modify: `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-detail-dialog.component.ts`
 - Modify: `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-detail-dialog.component.html`
 - Modify: `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-detail-dialog.component.scss`
 - Modify: `ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-actions.service.ts`
 - [ ] **Step 1: Extend `IotHubItemDetailDialogData` + component field**
 In `iot-hub-item-detail-dialog.component.ts`, find the `IotHubItemDetailDialogData` interface (around line 43) and add the optional `preview` field:
 ```ts
 export interface IotHubItemDetailDialogData {
  item: MpItemVersionView;
  installedItem?: IotHubInstalledItem;
  installedItemsCount?: number;
  mode?: IotHubItemDetailDialogMode;
  showCreator?: boolean;
  preview?: boolean;
 }
 ```
 In the component class, add a new public field below `showCreator`:
 ```ts
  preview: boolean;
 ```
 In the constructor body (below `this.showCreator = data.showCreator !== false;`), add:
 ```ts
    this.preview = data.preview === true;
 ```
 - [ ] **Step 2: Add badge markup in template**
 In `iot-hub-item-detail-dialog.component.html`, find the block starting with `<span class="dlg-subtitle-group">` that contains the version icon (around line 39, the `update` mat-icon). Immediately **after** the closing `</span>` of that version group (just before the `@if (item.publishedTime)` block), insert:
 ```html
        @if (preview) {
          <span class="dlg-dot"></span>
          <span class="dlg-subtitle-group tb-unpublished-preview-badge">
            <mat-icon class="dlg-subtitle-icon">warning</mat-icon>
            <span>{{ 'iot-hub.unpublished-preview' | translate }}</span>
          </span>
        }
 ```
 - [ ] **Step 3: Style the badge**
 Append to `iot-hub-item-detail-dialog.component.scss`:
 ```scss
 .dlg-subtitle-group.tb-unpublished-preview-badge {
  color: #d32f2f;
  font-weight: 600;
  .dlg-subtitle-icon {
    color: #d32f2f;
  }
 }
 ```
 - [ ] **Step 4: Extend `IotHubActionsService.openItemDetail`**
 In `iot-hub-actions.service.ts`, replace the `openItemDetail` method signature and body with:
 ```ts
  openItemDetail(item: MpItemVersionView, installedItem?: IotHubInstalledItem, installedItemsCount?: number,
                 mode?: IotHubItemDetailDialogMode, showCreator?: boolean, preview?: boolean): Observable<any> {
    return this.dialog.open(TbIotHubItemDetailDialogComponent, {
      panelClass: ['tb-dialog', 'tb-fullscreen-dialog'],
      autoFocus: false,
      data: { item, installedItem, installedItemsCount, mode, showCreator, preview } as IotHubItemDetailDialogData
    }).afterClosed();
  }
 ```
 Existing callers pass 5 or fewer args and remain valid — the new parameter is optional.
 - [ ] **Step 5: Verify build**
 Run:
 ```bash
 cd ui-ngx && node --max_old_space_size=4096 ./node_modules/@angular/cli/bin/ng build --configuration production 2>&1 | tail -15
 ```
 Expected: build succeeds.
 - [ ] **Step 6: Commit**
 ```bash
 git add ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-detail-dialog.component.ts \
        ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-detail-dialog.component.html \
        ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-item-detail-dialog.component.scss \
        ui-ngx/src/app/modules/home/components/iot-hub/iot-hub-actions.service.ts
 git commit -m "feat(iot-hub): add unpublished preview badge to item detail dialog"
 ```
 ---
 ### Task 6: Resolver component
 The heart of the feature. Fetches the version, gates on warning for unpublished preview, redirects to the type-page with router state.
 **Files:**
 - Create: `ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub-item-resolver.component.ts`
 - [ ] **Step 1: Create the component**
 Create `ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub-item-resolver.component.ts`:
 ```ts
 ///
 /// Copyright © 2016-2026 The Thingsboard Authors
 ///
 /// Licensed under the Apache License, Version 2.0 (the "License");
 /// you may not use this file except in compliance with the License.
 /// You may obtain a copy of the License at
 ///
 ///     http://www.apache.org/licenses/LICENSE-2.0
 ///
 /// Unless required by applicable law or agreed to in writing, software
 /// distributed under the License is distributed on an "AS IS" BASIS,
 /// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 /// See the License for the specific language governing permissions and
 /// limitations under the License.
 ///
 import { Component, OnInit } from '@angular/core';
 import { ActivatedRoute, Router } from '@angular/router';
 import { MatDialog } from '@angular/material/dialog';
 import { Store } from '@ngrx/store';
 import { TranslateService } from '@ngx-translate/core';
 import { AppState } from '@core/core.state';
 import { ActionNotificationShow } from '@core/notification/notification.actions';
 import { IotHubApiService } from '@core/http/iot-hub-api.service';
 import { MpItemVersionView } from '@shared/models/iot-hub/iot-hub-version.models';
 import {
  DeepLinkOpenItem,
  isPublished,
  isUUID,
  typeSegment
 } from './iot-hub-deep-link.utils';
 import {
  IotHubUnpublishedWarningDialogData,
  TbIotHubUnpublishedWarningDialogComponent
 } from '@home/components/iot-hub/iot-hub-unpublished-warning-dialog.component';
@Component({
  selector: 'tb-iot-hub-item-resolver',
  standalone: false,
  template: ''
 })
 export class TbIotHubItemResolverComponent implements OnInit {
  constructor(
    private route: ActivatedRoute,
    private router: Router,
    private dialog: MatDialog,
    private store: Store<AppState>,
    private translate: TranslateService,
    private iotHubApi: IotHubApiService
  ) {}
  ngOnInit(): void {
    const itemId = this.route.snapshot.paramMap.get('itemId');
    const preview = this.route.snapshot.data['preview'] === true;
    if (!isUUID(itemId)) {
      this.failTo('iot-hub.deep-link-invalid-id');
      return;
    }
    const fetch$ = preview
      ? this.iotHubApi.getLatestVersion(itemId, { ignoreErrors: true })
      : this.iotHubApi.getPublishedVersion(itemId, { ignoreErrors: true });
    fetch$.subscribe({
      next: v => this.handleResolved(v, preview),
      error: err => {
        const key = err?.status === 404
          ? 'iot-hub.deep-link-not-found'
          : 'iot-hub.deep-link-fetch-failed';
        this.failTo(key);
      }
    });
  }
  private handleResolved(version: MpItemVersionView, preview: boolean): void {
    const segment = typeSegment(version.type);
    if (!segment) {
      this.failTo('iot-hub.deep-link-fetch-failed');
      return;
    }
    const showWarning = preview && !isPublished(version);
    if (showWarning) {
      this.dialog.open<
        TbIotHubUnpublishedWarningDialogComponent,
        IotHubUnpublishedWarningDialogData,
        boolean
      >(TbIotHubUnpublishedWarningDialogComponent, {
        panelClass: ['tb-dialog'],
        disableClose: true,
        autoFocus: false,
        data: { item: version }
      }).afterClosed().subscribe(confirmed => {
        if (confirmed) {
          this.openOnTypePage(version, segment, true);
        } else {
          this.router.navigate(['/iot-hub'], { replaceUrl: true });
        }
      });
    } else {
      this.openOnTypePage(version, segment, false);
    }
  }
  private openOnTypePage(version: MpItemVersionView, segment: string, preview: boolean): void {
    const openItem: DeepLinkOpenItem = { version, preview };
    this.router.navigate(['/iot-hub', segment], {
      state: { openItem },
      replaceUrl: true
    });
  }
  private failTo(messageKey: string): void {
    this.store.dispatch(new ActionNotificationShow({
      message: this.translate.instant(messageKey),
      type: 'error',
      duration: 5000
    }));
    this.router.navigate(['/iot-hub'], { replaceUrl: true });
  }
 }
 ```
 - [ ] **Step 2: Verify TypeScript compiles (the module wiring comes in Task 7)**
 The component is not yet declared in any module, so a full `ng build` will fail. Run a type-check only on this file:
 ```bash
 cd ui-ngx && npx tsc --noEmit -p tsconfig.json 2>&1 | grep -E "iot-hub-item-resolver|iot-hub-deep-link" || echo "no type errors in new files"
 ```
 Expected: `no type errors in new files`.
 - [ ] **Step 3: Commit**
 ```bash
 git add ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub-item-resolver.component.ts
 git commit -m "feat(iot-hub): add item resolver component for deep links"
 ```
 ---
 ### Task 7: Routing + module registration
 Register the resolver component in `IotHubModule` and add the two new child routes to `iot-hub-routing.module.ts`. Reserved words must be matched first, so the `:itemId` wildcard routes go **last** in the children array.
 **Files:**
 - Modify: `ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub.module.ts`
 - Modify: `ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub-routing.module.ts`
 - [ ] **Step 1: Declare resolver in `IotHubModule`**
 In `ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub.module.ts`, add the import:
 ```ts
 import { TbIotHubItemResolverComponent } from './iot-hub-item-resolver.component';
 ```
 In the `declarations` array, add `TbIotHubItemResolverComponent` after `TbIotHubSearchPageComponent`.
 - [ ] **Step 2: Add routes**
 In `ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub-routing.module.ts`, add the import:
 ```ts
 import { TbIotHubItemResolverComponent } from './iot-hub-item-resolver.component';
 ```
 In the `children` array of the `/iot-hub` route, **immediately before** the closing `]` (after the existing `creator/:creatorId` entry), insert:
 ```ts
      {
        path: ':itemId',
        component: TbIotHubItemResolverComponent,
        data: {
          auth: [Authority.TENANT_ADMIN],
          title: 'iot-hub.item-detail'
        }
      },
      {
        path: ':itemId/preview',
        component: TbIotHubItemResolverComponent,
        data: {
          auth: [Authority.TENANT_ADMIN],
          title: 'iot-hub.item-preview',
          preview: true
        }
      }
 ```
 Make sure there is a comma after the preceding `creator/:creatorId` entry.
 - [ ] **Step 3: Verify build**
 Run:
 ```bash
 cd ui-ngx && node --max_old_space_size=4096 ./node_modules/@angular/cli/bin/ng build --configuration production 2>&1 | tail -15
 ```
 Expected: build succeeds.
 - [ ] **Step 4: Commit**
 ```bash
 git add ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub.module.ts \
        ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub-routing.module.ts
 git commit -m "feat(iot-hub): wire resolver component into routing and module"
 ```
 ---
 ### Task 8: Type-page handoff
 `TbIotHubItemsPageComponent` consumes `history.state.openItem` on init: resolves installed state, opens the detail dialog with the `preview` flag, then clears the state entry so refresh does not re-open.
 **Files:**
 - Modify: `ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub-items-page.component.ts`
 - [ ] **Step 1: Extend imports + constructor**
 Open `ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub-items-page.component.ts`.
 Replace the import block (top of file, currently lines 17-20) with:
 ```ts
 import { Component, OnInit } from '@angular/core';
 import { ActivatedRoute, Router } from '@angular/router';
 import { map } from 'rxjs/operators';
 import { Observable } from 'rxjs';
 import { ItemType } from '@shared/models/iot-hub/iot-hub-item.models';
 import { IotHubApiService } from '@core/http/iot-hub-api.service';
 import { IotHubActionsService } from '@home/components/iot-hub/iot-hub-actions.service';
 import { IotHubInstalledItem } from '@shared/models/iot-hub/iot-hub-installed-item.models';
 import { MpItemVersionView } from '@shared/models/iot-hub/iot-hub-version.models';
 import { PageLink } from '@shared/models/page/page-link';
 import { DeepLinkOpenItem } from './iot-hub-deep-link.utils';
 ```
 Replace the constructor with:
 ```ts
  constructor(
    private route: ActivatedRoute,
    private router: Router,
    private iotHubApiService: IotHubApiService,
    private iotHubActions: IotHubActionsService
  ) {}
 ```
 - [ ] **Step 2: Extend `ngOnInit` and add handoff method**
 Replace the existing `ngOnInit` body with:
 ```ts
  ngOnInit(): void {
    const itemType = this.route.snapshot.data['itemType'] as string;
    this.config = PAGE_CONFIGS[itemType];
    this.loadInstalledCount();
    this.maybeOpenDeepLinkedItem();
  }
 ```
 Add these two new methods anywhere in the class (e.g. after `loadInstalledCount`):
 ```ts
  private maybeOpenDeepLinkedItem(): void {
    const openItem = history.state?.openItem as DeepLinkOpenItem | undefined;
    if (!openItem || openItem.version.type !== this.config.type) {
      return;
    }
    history.replaceState({ ...history.state, openItem: undefined }, '');
    this.resolveInstalledItem(openItem.version).subscribe(installed => {
      this.iotHubActions.openItemDetail(
        openItem.version,
        installed ?? undefined,
        installed ? 1 : 0,
        'default',
        true,
        openItem.preview
      ).subscribe();
    });
  }
  private resolveInstalledItem(version: MpItemVersionView): Observable<IotHubInstalledItem | null> {
    return this.iotHubApiService
      .getInstalledItems(new PageLink(1), undefined, version.itemId, { ignoreLoading: true })
      .pipe(map(page => page.data[0] ?? null));
  }
 ```
 - [ ] **Step 3: Verify build**
 Run:
 ```bash
 cd ui-ngx && node --max_old_space_size=4096 ./node_modules/@angular/cli/bin/ng build --configuration production 2>&1 | tail -15
 ```
 Expected: build succeeds.
 - [ ] **Step 4: Commit**
 ```bash
 git add ui-ngx/src/app/modules/home/pages/iot-hub/iot-hub-items-page.component.ts
 git commit -m "feat(iot-hub): open deep-linked item from history state on type-page init"
 ```
 ---
 ### Task 9: Lint, build, and manual smoke test
 Final verification gate. Runs the lint and production build, then walks each user-facing flow in a dev server to confirm behavior.
 **Files:** none (verification only)
 - [ ] **Step 1: Lint**
 Run:
 ```bash
 cd ui-ngx && node --max_old_space_size=4096 ./node_modules/@angular/cli/bin/ng lint 2>&1 | tail -30
 ```
 Expected: no new errors introduced by files created/modified in tasks 1–8. Warnings in unrelated files are acceptable.
 - [ ] **Step 2: Production build**
 Run:
 ```bash
 cd ui-ngx && node --max_old_space_size=4096 ./node_modules/@angular/cli/bin/ng build --configuration production 2>&1 | tail -20
 ```
 Expected: build completes without errors.
 - [ ] **Step 3: Start dev server**
 Run:
 ```bash
 cd ui-ngx && node --max_old_space_size=8048 ./node_modules/@angular/cli/bin/ng serve --configuration development --host 0.0.0.0
 ```
 Dev server should be reachable at `http://localhost:4200`. Log in as a TENANT_ADMIN user. (A running ThingsBoard backend at the default proxy target is required per `proxy.conf.js`.)
 - [ ] **Step 4: Manual smoke test — published deep link**
 Pick an itemId from `/iot-hub/widgets` (the card's click handler logs it, or inspect the dialog URL via browser dev tools; alternatively, query `iotHubBaseUrl/api/versions/published` and copy an `itemId`).
 Navigate to `http://localhost:4200/iot-hub/{that-itemId}`. Verify:
 - URL bar ends at `/iot-hub/widgets` (or the correct type page for the item) after resolution
 - Detail dialog opens with the item's info, no "Unpublished preview" badge, and Install/Update actions behave normally
 - Closing the dialog leaves the user on the type-page
 Navigate to `http://localhost:4200/iot-hub/00000000-0000-0000-0000-000000000000` (a valid-shaped but non-existent UUID). Verify:
 - URL bar ends at `/iot-hub`
 - Red toast: "This IoT Hub item doesn't exist or was removed."
 Navigate to `http://localhost:4200/iot-hub/not-a-uuid`. Verify:
 - URL bar ends at `/iot-hub`
 - Red toast: "Invalid IoT Hub item link."
 - [ ] **Step 5: Manual smoke test — preview deep link (requires IoT Hub `/latest` endpoint)**
 **If the IoT Hub-side endpoints are not yet deployed**, skip this step and record that end-to-end preview verification is deferred until the IoT Hub PR lands. The per-URL flow is exercised in Step 4; the preview URL hitting a non-existent endpoint will trigger the "fetch failed" toast, which is the correct fallback behavior.
 **If the endpoints are available**, navigate to `http://localhost:4200/iot-hub/{unpublished-itemId}/preview`. Verify:
 - Warning dialog opens immediately with the item's name/version, red warning icon, and two buttons
 - "Cancel" → closes dialog, lands on `/iot-hub` (home)
 - Revisit the URL, click "I understand the risk, continue" → URL advances to `/iot-hub/{typePage}`, detail dialog opens with the red "Unpublished preview" badge in the meta bar
 - Install button still works end-to-end (calls the TB install endpoint, which proxies to IoT Hub using the unpublished versionId)
 Navigate to `http://localhost:4200/iot-hub/{published-only-itemId}/preview`. Verify:
 - No warning shown (preview fell back to the published version)
 - Detail dialog opens with **no** preview badge
 - Behavior matches the regular published URL
 - [ ] **Step 6: Commit the final verification (if any lint/build fixes were needed)**
 If the smoke test uncovered issues that required fixes, stage and commit them with a message like `fix(iot-hub): address smoke-test findings for deep-link flow`. Otherwise, this step is a no-op — all previous commits already capture the work.
 ---
 ## IoT Hub-side changes required (recap)
 From the design doc, the following IoT Hub (external) backend work is needed to ship the preview flow end-to-end:
 1. **New endpoint** `GET /api/items/{itemId}/published` — latest PUBLISHED version as `MpItemVersionView`, 404 if none. Anonymous cross-origin.
 2. **New endpoint** `GET /api/items/{itemId}/latest` — latest version regardless of state, preferring non-published and falling back to published. Anonymous cross-origin.
 3. **`MpItemVersionView`**: for unpublished versions, either keep `publishedTime` falsy (`0`/`null`) or add an explicit `state` field. The frontend's `isPublished()` uses `publishedTime > 0` today.
 4. **By-versionId endpoints** (`GET /api/versions/{versionId}`, `/readme`, `/fileData`, `POST /install`) must serve unpublished versions when queried by ID.
 5. **Install counter policy** for unpublished versions — recommended: skip counting.
 6. **CORS** on the two new endpoints must permit cross-origin GET from any origin.
 These live in the IoT Hub repository, not ThingsBoard CE.