@nexia/sdk 0.8.8 → 0.8.10

package/README.md

@@ -8,8 +8,64 @@ Report SDK, setup, CLI, Docker, AI-tool and sandbox problems in the [central dev
 
 SDK·개발환경·CLI·Docker·AI 도구·샌드박스 문제는 [통합 이슈 창구](https://github.com/nexia-cloud-os/developer-support/issues)에 신고하세요. 기존 이슈를 먼저 검색하고 패키지 버전과 최소 재현 단계를 포함하세요. 인증 정보, 비공개 Core 소스와 고객 데이터는 첨부하지 마세요.
 
+## Standalone App frontend tests
+
+Run Vitest in the App repository with `environment: 'jsdom'`, its own setup file,
+and the App's React dependencies. Install `@testing-library/react`,
+`@testing-library/jest-dom`, `jsdom`, `i18next`, `msw`, and `vitest` as App test
+dependencies. No Core checkout or Core test setup is required.
+
+The existing `configureNexiaAppFrontendHost` API accepts a complete explicit host
+fixture. `configureNexiaAppFrontendTestHost` connects the suite's i18n and MSW
+instances to `appTestI18n` and `appTestServer`.
+
+Configure explicit host capabilities through the existing public API in the
+suite's setup file. Supply a real axios instance and explicit public component,
+hook, runtime, and registry fixtures for the capabilities exercised by that suite.
+Missing capabilities should throw instead of supplying automatic UI or permission
+substitutes. No new SDK API or SDK release is needed.
+
+Connect the suite's own i18n and MSW instances with
+`configureNexiaAppFrontendTestHost({ i18n, server })`. Register
+`server.listen({ onUnhandledRequest: 'error' })` in Vitest `beforeAll`, run React
+Testing Library `cleanup()` and `server.resetHandlers()` in `afterEach`, and call
+`server.close()` in `afterAll`. Use one installed SDK instance throughout the
+suite so its main and `/testing` exports share the same configured host.
+
+App fixtures can verify App branching, validation, and request payloads. A DOM
+substitute for a host component does not verify that component's accessibility,
+keyboard behavior, or production rendering; those checks belong to its host.
+Reconfigure mutable fixtures per test to avoid state leaking between cases.
+
 ## Standalone App styles
 
 `nexiaAppConfig(import.meta.url)` generates Tailwind utilities from the App resources, including lazy screens, and records emitted CSS in `nexia-host.json`. The build references the shared `@nexia/sdk/theme.css` token aliases; Core supplies token values and resets. Keep those aliases aligned with the Core theme contract. Do not bundle a second preflight or global theme.
 
 After adopting the SDK release containing this fix, rebuild and resubmit each standalone App. Existing deployed bundles are unchanged until replaced. Custom builds must declare every emitted stylesheet in `nexia-host.json`.
+
+### App API and Core host capabilities
+
+`api` from `@nexia/sdk/host` is bound to the calling App. It is not an
+unrestricted HTTP client for Core. Development frames and installed App surfaces
+use the same host transport policy; a mocked Axios response or direct HTTP test
+does not exercise that boundary.
+
+Use `useOrganizationTargetsQuery`, `useAffiliatedOperatingUnits` and Resource
+Reference options for scoped business choices. Tenant-wide administration is a
+different authority. Core's explicit host routes preserve their tenant-wide
+permissions: legal-entity/operating-unit reads, operating-unit creation,
+party duplicate lookup, user creation/invitation/credential sending, and the
+actor's self-service profile. Unsupported methods and arbitrary Core routes
+remain unavailable. A host refusal reports `APP_HOST_ROUTE_UNAVAILABLE` rather
+than proving that the actor lacks a business permission.
+
+`sendUserInvitation` and `useDataMigrationBackgroundOperation` retain the calling
+App's client. Do not replace it with a global client to bypass a refusal.
+Background operation status is accessible only to the originating App and actor;
+Core returns 404 for another App's ticket even when the actor is the same.
+The Core host-capability fix must be deployed before relying on these paths;
+an SDK-only update does not install server routes.
+
+Test both a successful call and a denied call through an actual development
+frame or installed App transport. For invitations, use a test mail sink; for
+imports, verify the terminal result as well as the initial 202 response.

package/changelog/0.8.9/en.md

@@ -0,0 +1,17 @@
+---
+status: published
+version: 0.8.9
+date: 2026-10-16
+title: App frontend compatibility metadata
+description: App frontend compatibility metadata
+---
+
+# App frontend compatibility metadata
+
+The standalone App build records its declared `@nexia/sdk` range, the SDK used to build it, and the shared host exports imported by the generated JavaScript. Platforms supporting this metadata can check compatibility before changing the host or opening a new App bundle. SDK version ranges do not replace behavioral compatibility tests.
+
+Keep the supported SDK range in the App's `package.json` `peerDependencies` or `dependencies` and retain the dependency lock. Peer requirements take precedence when both are present. Rebuild with this SDK to include the metadata; the metadata alone does not require a new App version or change existing published bundles.
+
+Apps without an explicit SDK requirement still build with their existing frontend manifest. Their host compatibility remains unknown and must be verified before a platform update. No automatic App upgrade is introduced.
+
+Standalone builds warn when emitted JavaScript uses the deprecated `allowsManualAppFallback` or `isRetryableHandoffFailure` aliases. Replace them with `permitsManualFallback` or `isRetryableFailure`, respectively. No removal version is scheduled. This import check does not inspect erased TypeScript types or PHP annotations.

package/changelog/0.8.9/ko.md

@@ -0,0 +1,17 @@
+---
+status: published
+version: 0.8.9
+date: 2026-10-16
+title: 앱 프런트엔드 호환성 메타데이터
+description: 앱 프런트엔드 호환성 메타데이터
+---
+
+# 앱 프런트엔드 호환성 정보
+
+독립 앱 빌드에 선언된 `@nexia/sdk` 지원 범위, 빌드에 사용한 SDK 버전, 생성된 JavaScript가 가져오는 공용 호스트 export 목록이 기록됩니다. 이 정보를 지원하는 플랫폼은 호스트를 바꾸거나 새 앱 번들을 열기 전에 호환성을 확인할 수 있습니다. SDK 버전 범위만으로 실제 동작의 호환성 검증을 대신할 수는 없습니다.
+
+앱 `package.json`의 `peerDependencies` 또는 `dependencies`에 지원 SDK 범위를 유지하고 의존성 잠금 파일을 보관하세요. 두 곳에 모두 있으면 peer 요구사항을 우선합니다. 이번 SDK로 다시 빌드하면 정보가 포함되며, 정보 추가만으로 앱 버전을 올릴 필요는 없습니다. 이미 게시된 번들은 바뀌지 않습니다.
+
+명시적인 SDK 요구사항이 없는 앱도 기존 프런트엔드 manifest 형식으로 빌드됩니다. 다만 호스트 호환성이 확인된 것은 아니므로 플랫폼 업데이트 전에 별도 검증이 필요합니다. 앱을 자동으로 업그레이드하지 않습니다.
+
+독립 빌드의 JavaScript에서 deprecated 별칭인 `allowsManualAppFallback` 또는 `isRetryableHandoffFailure`를 사용하면 경고합니다. 각각 `permitsManualFallback`, `isRetryableFailure`로 바꾸세요. 제거 버전은 정해지지 않았습니다. 이 import 검사는 컴파일 후 사라지는 TypeScript 타입이나 PHP 주석을 검사하지 않습니다.

package/dist/platform.d.ts

@@ -302,6 +302,18 @@ export interface ProfileSlotPropsV2 {
     familyKey: string;
     workContext: SelfWorkContext | null;
 }
+/** App-owned workforce view in the Core organization surface. No access memberships are implied. */
+export interface OrganizationWorkforceSlotPropsV1 {
+    slot: 'organization.workforce';
+    slotApiVersion: 1;
+    tenant: Pick<TenantContext, 'id' | 'name'>;
+    legalEntity: Pick<LegalEntityContext, 'name' | 'code' | 'public_id'>;
+    descriptorKey: string;
+    appKey: string;
+    familyKey: string;
+    view: 'chart' | 'table';
+    search: string;
+}
 export interface OperatingUnitScopeReference {
     public_id: string;
     code: string;

package/dist/testing.d.ts

@@ -6,7 +6,7 @@ export interface NexiaAppFrontendTestHostBindings {
         use: (...handlers: unknown[]) => void;
     };
 }
-/** Core test setup installs its i18n and request-interception harness here. */
+/** App or host test setup installs its own i18n and request-interception harness here. */
 export declare function configureNexiaAppFrontendTestHost(bindings: NexiaAppFrontendTestHostBindings): void;
 export declare const appTestI18n: {
     changeLanguage: (language: string) => unknown;

package/dist/testing.js

@@ -1,11 +1,11 @@
 let activeTestHost = null;
-/** Core test setup installs its i18n and request-interception harness here. */
+/** App or host test setup installs its own i18n and request-interception harness here. */
 export function configureNexiaAppFrontendTestHost(bindings) {
     activeTestHost = bindings;
 }
 function testHost() {
     if (activeTestHost === null) {
-        throw new Error('Nexia App frontend test host is not configured. Core test setup must configure it before App specs run.');
+        throw new Error('Nexia App frontend test host is not configured. Configure it with the test suite’s own i18n and request-interception fixtures before App specs run.');
     }
     return activeTestHost;
 }

package/dist/vite.mjs

@@ -76,10 +76,39 @@ export const { api, openFile, sendUserInvitation, useDataMigrationBackgroundOper
         },
         generateBundle: { order: 'post', handler(_options, bundle) {
             // Standalone App builds expose compatibility before executing their entry.
-            if (owners.length === 1) this.emitFile({
+            if (owners.length !== 1) return;
+            let appPackage = {};
+            try { appPackage = JSON.parse(readFileSync(path.join(owners[0].root, 'package.json'), 'utf8')); }
+            catch (error) { if (error.code !== 'ENOENT') throw error; }
+            const required = appPackage.peerDependencies?.['@nexia/sdk'] ?? appPackage.dependencies?.['@nexia/sdk'];
+            const sdk = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+            const imports = {};
+            for (const chunk of Object.values(bundle)) {
+                if (chunk.type !== 'chunk') continue;
+                for (const [specifier, bindings] of Object.entries(chunk.importedBindings)) {
+                    if (!nexiaHostPeers.includes(specifier)) continue;
+                    imports[specifier] = [...new Set([...(imports[specifier] ?? []), ...bindings])].sort();
+                }
+                for (const specifier of chunk.dynamicImports) {
+                    if (nexiaHostPeers.includes(specifier)) imports[specifier] = ['*'];
+                }
+            }
+            // These aliases are explicitly deprecated in index.ts; no removal release is declared.
+            const deprecated = { allowsManualAppFallback: 'permitsManualFallback', isRetryableHandoffFailure: 'isRetryableFailure' };
+            for (const [name, replacement] of Object.entries(deprecated)) {
+                if (imports['@nexia/sdk']?.includes(name)) {
+                    this.warn(`[NEXIA_SDK_DEPRECATED] ${name}: use ${replacement}. Removal version is not scheduled.`);
+                }
+            }
+            this.emitFile({
                 type: 'asset', fileName: 'nexia-host.json',
                 source: JSON.stringify({ version: 1, development_updates: 1, app_key: owners[0].appKey,
-                    styles: Object.keys(bundle).filter(file => file.endsWith('.css')) }),
+                    styles: Object.keys(bundle).filter(file => file.endsWith('.css')),
+                    // Preserve builds that predate explicit host requirements. Their compatibility
+                    // remains unknown; operators must not infer permission to change the host.
+                    ...(typeof required === 'string' && required.trim() && required.length <= 256
+                        ? { compatibility: { schema_version: 1, host_contract: 1,
+                            sdk: { package: '@nexia/sdk', required, built_with: sdk.version }, imports } } : {}) }),
             });
         } },
     };

package/package.json

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