ptech-shell-sdk

Shared contracts, tokens, constants, and runtime service registry for shell-hosted Module Federation apps.

Install

npm i ptech-shell-sdk

React is a peer dependency because the package exports React hook helpers such as useService.

What This Package Owns

• Service registry primitives: createToken, registerService, getService, clearService, resetServices, subscribeService, whenReady.
• React helpers: useService, useServiceOrThrow.
• Shell tokens: TOKENS.
• Service contracts under src/services/contracts/**.
• Shared constants such as roles, permissions, feature flags, analytics events, and shared state keys.
• The optional AppLaunchAwareProps contract used by a host to coordinate its launch overlay with a mounted remote.
• The UI-neutral onboarding catalog, campaign, registration, progress, and orchestration contracts used by host pages and remotes.

This package does not own standalone/mock behavior, HTTP implementation details, MSAL adapters, or runtime side effects. Production-neutral HTTP/runtime implementations live in ptech-shell-runtime; standalone mocks live in ptech-shell-dev.

Basic Usage

import { TOKENS, registerService, useService } from 'ptech-shell-sdk';

registerService(TOKENS.i18n, i18nService);

export function ToolbarTitle() {
  const i18n = useService(TOKENS.i18n);
  return i18n?.t('toolbar.title') ?? null;
}

Language Ownership

LocaleCode is intentionally an open string contract (normally a canonical BCP 47 tag), not an SDK-owned union of supported languages. The host owns the active locale, validation, persistence, and fallback policy. Remotes read and subscribe to that host state through TOKENS.i18n, and register only the message catalogs they currently ship.

setLang(locale) is a request to the registered implementation; a host may normalize, accept, or reject that request according to its own locale catalog. Standalone implementations provide their own policy. The legacy Lang export remains as a deprecated alias of LocaleCode for source compatibility.

Host Registration Pattern

Hosts should register concrete service implementations during shell bootstrap.

import { TOKENS, registerService } from 'ptech-shell-sdk';

registerService(TOKENS.apiClient, apiClient);
registerService(TOKENS.userService, userService);
registerService(TOKENS.requestContext, requestContext);

Remotes should consume services through tokens instead of importing host internals.

import { TOKENS, getService } from 'ptech-shell-sdk';

const api = getService(TOKENS.apiClient);
if (!api) {
  throw new Error('ApiClient not registered');
}

Remote App Launch Readiness

A host may keep its launch experience visible while mounting a remote behind it. The host passes a mount-scoped appLaunch handle to the remote root and removes the overlay when the remote reports that its first usable screen is ready. Hosts should also enforce a deadline so older remotes that do not support this contract remain compatible.

import { useEffect } from 'react';
import type { AppLaunchAwareProps } from 'ptech-shell-sdk';

export default function RemoteApp({ appLaunch }: AppLaunchAwareProps) {
  const criticalResourcesSettled = true; // Replace with the app's real state.

  useEffect(() => {
    if (criticalResourcesSettled) {
      appLaunch?.notifyReady();
    }
  }, [appLaunch, criticalResourcesSettled]);

  return <main>{/* Remote UI */}</main>;
}

notifyReady() means the app can present a usable success, empty, or handled error state. Background requests should continue without blocking it. The handle is optional so the same remote remains usable standalone and under older hosts.

Service Tokens

Current built-in tokens:

• TOKENS.i18n
• TOKENS.userService
• TOKENS.apiClient
• TOKENS.navigation
• TOKENS.configService
• TOKENS.permissionService
• TOKENS.requestContext
• TOKENS.sharedState
• TOKENS.realtime
• TOKENS.observability
• TOKENS.notification
• TOKENS.analytics
• TOKENS.tenantService
• TOKENS.appSettingsService
• TOKENS.onboarding

Onboarding Ownership

TOKENS.onboarding lets a mounted host page or remote register a page-local tour without coupling the SDK to React Joyride or another rendering library.

• A remote publishes OnboardingTourCatalogEntry metadata so an administrator can discover the tour without loading the remote.
• The page registers an OnboardingTourDefinition and UI controller only while that surface is mounted. The page continues to own steps, DOM targets, localization, and rendering.
• The host service loads backend-owned OnboardingCampaign decisions and user progress, matches contentVersion, serializes starts, and persists reports.
• contentVersion is owned by the frontend bundle. revision is owned by the backend campaign, so administrators may replay the same content without a new remote deployment.

import { TOKENS, getService } from 'ptech-shell-sdk';

const onboarding = getService(TOKENS.onboarding);
const unregister = onboarding?.registerTour({
  definition: {
    tourKey: 'audit-tool.evidence',
    appKey: 'audit-tool',
    surfaceKey: 'evidence-list',
    contentVersion: '3',
    campaignScopes: ['app', 'tenant-app'],
  },
  controller: {
    isReady: () => true,
    start: ({ reason, campaign }) => {
      // Open the page-owned tour UI. Do not send DOM selectors to the backend.
      void reason;
      void campaign;
    },
  },
});

// Call when the page unmounts.
unregister?.();

Contract-First Changes

When adding or changing a shell capability:

1. Update or add the contract in src/services/contracts/**.
2. Export the contract from src/services/contracts/index.ts and package entrypoints as needed.
3. Add or update a token in src/services/tokens.ts when a new service is introduced.
4. Update ptech-shell-dev implementations and tests after the SDK contract is stable.

Avoid any in exported contracts. Prefer explicit unions, records, and readonly shapes where appropriate.

ApiClient Contract Summary

ApiClient exposes:

• fetch(input, init): low-level shared fetch helper that does not throw on HTTP status.
• request<T>(options): typed parsed request helper that throws normalized ApiErrorPayload failures.
• requestRaw(options): raw response helper with shared auth, timeout, retry, tenant, and trace behavior.

Callers should route runtime API access through this contract instead of creating feature-specific HTTP wrappers.

Shell context follows destination trust. Same-origin requests and host-configured API bases/routes receive auth, tenant, trace, and correlation context. Arbitrary cross-origin URLs do not. shellContext: 'omit' is the explicit request-level opt-out. There is intentionally no request-level include override; the host must add an exact origin to the runtime trusted-origin policy.

Build

npm run build -w ptech-shell-sdk

The package builds src/index.ts to ESM and declaration files in dist/.