@nexia/sdk 0.8.3 → 0.8.4

package/changelog/0.8.4/en.md

@@ -0,0 +1,12 @@
+---
+status: published
+version: 0.8.4
+date: 2026-10-12
+title: Shared widget queries and dashboard refresh
+description: Custom App widgets use the host transport and participate in dashboard refresh.
+---
+
+- Use `useWidgetQueryRuntime()` from `@nexia/sdk/host` for scoped widget reads and cancellation.
+- Register active non-preview query keys with `useDashboardDataSource()` to include custom widgets in dashboard refresh and update times.
+- `SelfWorkContext` declares the legal-entity field already supplied by Core. Update typed fixtures accordingly.
+- Requires Core 0.8.0 host bindings. Rebuild consuming App bundles and reload existing browser sessions when adopting the new query endpoint.

package/changelog/0.8.4/ko.md

@@ -0,0 +1,12 @@
+---
+status: published
+version: 0.8.4
+date: 2026-10-12
+title: 공통 위젯 조회와 대시보드 새로고침
+description: 사용자 정의 App 위젯이 호스트 조회 기능과 대시보드 새로고침을 사용합니다.
+---
+
+- `@nexia/sdk/host`의 `useWidgetQueryRuntime()`으로 범위가 지정된 위젯 조회와 요청 취소를 처리합니다.
+- 활성 상태이며 미리보기가 아닌 조회 키를 `useDashboardDataSource()`에 등록하면 대시보드 새로고침과 갱신 시각에 참여합니다.
+- `SelfWorkContext`에 Core가 이미 제공하던 법인 필드를 명시합니다. 타입을 사용하는 테스트 데이터를 맞춰 주세요.
+- Core 0.8.0 호스트 연결이 필요합니다. 새 조회 경로 적용 시 사용 App 번들을 다시 빌드하고 기존 브라우저 화면을 새로고침하세요.

package/dist/host.d.ts

@@ -252,6 +252,8 @@ export interface NexiaAppFrontendHostBindings {
         WorkSurface: typeof WorkSurface;
     };
     hooks: {
+        useWidgetQueryRuntime: () => WidgetQueryRuntime;
+        useDashboardDataSource: (queryKey: readonly unknown[], enabled?: boolean) => void;
         useContextQuery: () => ContextQueryResult;
         useAffiliatedOperatingUnits: (tenantId: string | undefined, legalEntityPublicId: string | null | undefined, permission: string, enabled?: boolean) => OperatingUnitQueryResult;
         useAgentToolDataFreshness: (options: AgentToolDataFreshnessInput) => AgentToolDataFreshnessResult;
@@ -463,6 +465,18 @@ export declare function WorkSurface(props: WorkSurfaceProps): ReactNode;
 export declare function useContextQuery(): ContextQueryResult;
 export declare function useAffiliatedOperatingUnits(tenantId: string | undefined, legalEntityPublicId: string | null | undefined, permission: string, enabled?: boolean): OperatingUnitQueryResult;
 export declare function useAgentToolDataInvalidation(enabled?: boolean): void;
+/** Environment-owned, read-only widget queries. The host preserves actor and runtime scope. */
+export interface WidgetQueryRuntime {
+    readonly tenantId: string;
+    readonly legalEntityPublicId: string | null;
+    readonly timezone: string;
+    readonly supportsRealtimeInvalidation: boolean;
+    query<TResponse = unknown>(tool: string, args?: Record<string, unknown>, signal?: AbortSignal): Promise<TResponse>;
+}
+/** Use the surrounding widget runtime in both host and isolated App renderers. */
+export declare function useWidgetQueryRuntime(): WidgetQueryRuntime;
+/** Register a widget's query with its surrounding dashboard's refresh control. */
+export declare function useDashboardDataSource(queryKey: readonly unknown[], enabled?: boolean): void;
 export interface AgentToolDataFreshnessInput {
     enabled: boolean;
     refreshMs: number;

package/dist/host.js

@@ -498,6 +498,14 @@ export function useAffiliatedOperatingUnits(tenantId, legalEntityPublicId, permi
 export function useAgentToolDataInvalidation(enabled = true) {
     host().hooks.useAgentToolDataInvalidation(enabled);
 }
+/** Use the surrounding widget runtime in both host and isolated App renderers. */
+export function useWidgetQueryRuntime() {
+    return host().hooks.useWidgetQueryRuntime();
+}
+/** Register a widget's query with its surrounding dashboard's refresh control. */
+export function useDashboardDataSource(queryKey, enabled = true) {
+    host().hooks.useDashboardDataSource(queryKey, enabled);
+}
 /**
  * The freshness half of a widget's useQuery options, resolved by the host.
  * Polling pauses while the surrounding Work Tab is parked, the host enforces

package/dist/platform.d.ts

@@ -284,6 +284,7 @@ export interface ProfileSlotPropsV1 {
 }
 export interface SelfWorkContext {
     ref: string;
+    legalEntity: Pick<LegalEntityContext, 'name' | 'code' | 'public_id'>;
     label: string;
     description: string | null;
     status: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nexia/sdk",
-    "version": "0.8.3",
+    "version": "0.8.4",
     "description": "Frontend contracts for Nexia App Packages",
     "license": "UNLICENSED",
     "type": "module",