@openfin/workspace 45.1.2 → 45.1.3-alpha.ba7558c8

package/storefront-vpw/src/api/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const STOREFRONT_VPW_WINDOW_NAME = "storefront-vpw";
+export declare const getStorefrontVpwChannelName: (uuid?: string) => string;

package/storefront-vpw/src/api/ensure-infrastructure.d.ts

@@ -0,0 +1,6 @@
+import type { StorefrontAllowedWindowOptions } from '../shapes/shapes';
+import { StorefrontVpwProvider } from './provider';
+/** Creates the platform channel and {@link StorefrontVpwProvider} instance if not already running. */
+export declare const ensureStorefrontVpwChannel: () => Promise<StorefrontVpwProvider>;
+/** Launches the browser-zone Storefront VPW window and waits for the client `ready` handshake. */
+export declare const launchStorefrontVpwWindow: (windowOptions?: StorefrontAllowedWindowOptions) => Promise<void>;

package/storefront-vpw/src/api/index.d.ts

@@ -0,0 +1,5 @@
+export { register, deregister, showWhenReady, type StorefrontRegistration, type StorefrontRegisterOptions } from './register';
+export { show, hide } from './visibility';
+export { StorefrontVpwProvider } from './provider';
+export { getStorefrontVpwChannelName, STOREFRONT_VPW_WINDOW_NAME } from './constants';
+export type { StorefrontAllowedWindowOptions, StorefrontProvider } from '../shapes/shapes';

package/storefront-vpw/src/api/internal/assert-provider-process.d.ts

@@ -0,0 +1,2 @@
+/** Ensures Storefront VPW platform APIs run from the provider window, not content views. */
+export declare const assertStorefrontVpwProviderProcess: () => void;

package/storefront-vpw/src/api/internal/provider-registration.d.ts

@@ -0,0 +1,7 @@
+import type { RegisterMetaInfoInternal, StorefrontProvider } from '../../../../client-api/src/shapes';
+import { StorefrontVpwProvidersMap } from './providers-map';
+/** VPW storefront providers — separate from legacy Storefront provider registration in client-api. */
+export declare const StorefrontVpwProviders: StorefrontVpwProvidersMap<StorefrontProvider>;
+export declare const registerStorefrontVpwProviderInternal: (provider: StorefrontProvider) => Promise<RegisterMetaInfoInternal>;
+export declare const deregisterStorefrontVpwProviderInternal: (providerId: string) => Promise<void>;
+export declare const hasAnyRegisteredStorefrontVpwProvider: () => boolean;

package/storefront-vpw/src/api/internal/providers-map.d.ts

@@ -0,0 +1,23 @@
+import { PlatformError } from '../../../../common/src/errors';
+type StorefrontVpwProviderRecord = {
+    id: string;
+};
+export declare class StorefrontVpwProviderAlreadyRegisteredError extends PlatformError {
+    constructor(id: string);
+}
+/**
+ * In-process registry for Storefront VPW provider callbacks.
+ * VPW-only — not shared with legacy Storefront provider registration in client-api.
+ */
+export declare class StorefrontVpwProvidersMap<T extends StorefrontVpwProviderRecord> {
+    private readonly providersMap;
+    getProvider(id: string): T | undefined;
+    hasProvider(id: string): boolean;
+    assertNotAlreadyRegistered(id: string): void;
+    hasProviderMatching(predicate: (id: string) => boolean): boolean;
+    addProvider(provider: T): void;
+    deleteProvider(id: string): void;
+    listProviders(): T[];
+    getProviderOrFail(id: string): T;
+}
+export {};

package/storefront-vpw/src/api/launch.d.ts

@@ -0,0 +1,2 @@
+import type { StorefrontAllowedWindowOptions } from '../shapes/shapes';
+export declare function launchStorefrontVpw(additionalOptions?: StorefrontAllowedWindowOptions): Promise<void>;

package/storefront-vpw/src/api/protocol.d.ts

@@ -0,0 +1,67 @@
+import type { OpenFin } from '@openfin/core';
+import type { App, StorefrontFooter, StorefrontLandingPage, StorefrontNavigationItemAppGrid, StorefrontNavigationSection } from '../../../client-api/src/shapes';
+type ChannelActionMap = {
+    [action: string]: (...args: any[]) => any;
+};
+type TypedChannelClient<ProviderActions extends ChannelActionMap, ClientActions extends ChannelActionMap> = Omit<OpenFin.ChannelClient, 'dispatch' | 'register'> & {
+    dispatch: <T extends keyof ProviderActions>(action: T, payload: Parameters<ProviderActions[T]>[0]) => Promise<Awaited<ReturnType<ProviderActions[T]>>>;
+    register: <T extends keyof ClientActions>(action: T, handler: (payload: Parameters<ClientActions[T]>[0], id: OpenFin.ProviderIdentity | OpenFin.ClientIdentity) => Promise<Awaited<ReturnType<ClientActions[T]>>>) => boolean;
+};
+type TypedChannelProvider<ProviderActions extends ChannelActionMap, ClientActions extends ChannelActionMap> = Omit<OpenFin.ChannelProvider, 'dispatch' | 'register'> & {
+    dispatch: <T extends keyof ClientActions>(to: OpenFin.ClientIdentity, action: T, payload: Parameters<ClientActions[T]>[0]) => Promise<Awaited<ReturnType<ClientActions[T]>>>;
+    register: <T extends keyof ProviderActions>(action: T, handler: (payload: Parameters<ProviderActions[T]>[0], id: OpenFin.ProviderIdentity | OpenFin.ClientIdentity) => Promise<Awaited<ReturnType<ProviderActions[T]>>>) => boolean;
+};
+export type UpdateAppCardButtonConfigPayload = {
+    id: string;
+    appId: string;
+    primaryButton?: unknown;
+    secondaryButtons?: unknown[];
+};
+export type StorefrontVpwProviderListItem = {
+    id: string;
+    title: string;
+    icon: string;
+    identity: OpenFin.Identity;
+    buttonVisibility?: 'hidden' | 'visible';
+    cardClickBehavior?: 'show-app-details' | 'perform-primary-button-action';
+};
+/**
+ * Actions the VPW window dispatches TO the platform provider.
+ * @internal
+ */
+export type StorefrontVpwChannelProviderChannelActions = {
+    'ready': () => void;
+    'get-apps': (payload: {
+        providerId: string;
+    }) => Promise<App[]>;
+    'get-navigation': (payload: {
+        providerId: string;
+    }) => Promise<[StorefrontNavigationSection?, StorefrontNavigationSection?, StorefrontNavigationSection?]>;
+    'get-landing-page': (payload: {
+        providerId: string;
+    }) => Promise<StorefrontLandingPage | undefined>;
+    'get-footer': (payload: {
+        providerId: string;
+    }) => Promise<StorefrontFooter>;
+    'get-template': (payload: {
+        providerId: string;
+        templateId: string;
+    }) => Promise<StorefrontNavigationItemAppGrid | undefined>;
+    'launch-app': (payload: {
+        providerId: string;
+        app: App;
+    }) => Promise<void>;
+    'list-providers': () => Promise<StorefrontVpwProviderListItem[]>;
+};
+/**
+ * Actions the platform provider dispatches TO the VPW window.
+ * @internal
+ */
+export type StorefrontVpwChannelClientChannelActions = {
+    'show': () => void;
+    'show-when-ready': () => void;
+    'update-app-card-button-config': (payload: UpdateAppCardButtonConfigPayload) => void;
+};
+export type StorefrontVpwChannelProvider = TypedChannelProvider<StorefrontVpwChannelProviderChannelActions, StorefrontVpwChannelClientChannelActions>;
+export type StorefrontVpwChannelClient = TypedChannelClient<StorefrontVpwChannelProviderChannelActions, StorefrontVpwChannelClientChannelActions>;
+export {};

package/storefront-vpw/src/api/provider.d.ts

@@ -0,0 +1,23 @@
+import type { OpenFin } from '@openfin/core';
+import type { StorefrontVpwChannelProvider } from './protocol';
+export declare class StorefrontVpwProvider {
+    #private;
+    static instance: StorefrontVpwProvider | null;
+    constructor(channel: StorefrontVpwChannelProvider);
+    get ready(): Promise<void>;
+    private ensureClientConnected;
+    show(): Promise<void>;
+    showWhenReady(): Promise<void>;
+    hide(): Promise<void>;
+    shutdown(): Promise<void>;
+    getWindowSync(): OpenFin.Window;
+    private getProviderOrFail;
+    private resolveTemplate;
+    private registerChannelActions;
+    updateAppCardButtons(payload: {
+        providerId: string;
+        appId: string;
+        primaryButton?: unknown;
+        secondaryButtons?: unknown[];
+    }): Promise<void>;
+}

package/storefront-vpw/src/api/register.d.ts

@@ -0,0 +1,79 @@
+import type { RegisterMetaInfoInternal, StorefrontProvider, UpdateButtonConfigRequest } from '../../../client-api/src/shapes';
+import { showWhenReady } from './visibility';
+import type { StorefrontAllowedWindowOptions } from '../shapes/shapes';
+/**
+ * Response from {@link register} which includes workspace metadata and a helper to update app card buttons.
+ */
+export type StorefrontRegistration = RegisterMetaInfoInternal & {
+    /** Client SDK version active at registration time. */
+    clientAPIVersion: string;
+    /**
+     * Updates primary and secondary button configuration for an app card in the Storefront VPW UI.
+     *
+     * @param request App id and button configs to apply.
+     */
+    updateAppCardButtons: (request: UpdateButtonConfigRequest) => Promise<void>;
+};
+/**
+ * Options for {@link register}.
+ */
+export type StorefrontRegisterOptions = {
+    /** Window creation options applied when launching the browser-zone Storefront VPW window. */
+    windowOptions?: StorefrontAllowedWindowOptions;
+};
+/**
+ * Registers a Storefront VPW integrator.
+ *
+ * Creates the VPW channel (if needed), launches the browser-zone Storefront window hidden,
+ * then adds the provider to the in-process registry.
+ *
+ * @remarks Call from the **provider process** (the platform/provider window), not from
+ * arbitrary content views. The channel and host singleton are bound to the caller's
+ * `fin.me.identity` — same constraint as legacy `Storefront.register()`.
+ *
+ * @throws Error if `provider.icon` is missing.
+ * @throws {@link StorefrontVpwProviderAlreadyRegisteredError} if a provider with the same id is already registered.
+ *
+ * @param provider Storefront integrator implementation.
+ * @param options Optional launch options for the VPW window.
+ * @returns Registration metadata and an `updateAppCardButtons` helper.
+ *
+ * @example
+ * ```ts
+ * import { Storefront, type StorefrontProvider } from '@openfin/workspace-platform';
+ *
+ * const provider: StorefrontProvider = {
+ *     id: 'my-store',
+ *     title: 'My Store',
+ *     icon: 'https://example.com/icon.png',
+ *     getApps: async () => [],
+ *     getNavigation: async () => [],
+ *     getLandingPage: async () => undefined,
+ *     getFooter: async () => ({ logo: { src: '' } }),
+ *     launchApp: async () => undefined
+ * };
+ *
+ * await Storefront.register(provider);
+ * await Storefront.show();
+ * ```
+ */
+export declare const register: (provider: StorefrontProvider, options?: StorefrontRegisterOptions) => Promise<StorefrontRegistration>;
+/**
+ * Deregisters a Storefront VPW integrator by id.
+ *
+ * Removes the provider from the in-process registry. Shuts down the VPW channel and window
+ * when no providers remain registered.
+ *
+ * @remarks Call from the **provider process**, matching {@link register}.
+ *
+ * @param providerId Id of the provider to remove.
+ *
+ * @example
+ * ```ts
+ * import { Storefront } from '@openfin/workspace-platform';
+ *
+ * await Storefront.deregister('my-store');
+ * ```
+ */
+export declare const deregister: (providerId: string) => Promise<void>;
+export { showWhenReady };

package/storefront-vpw/src/api/visibility.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shows the Storefront VPW window and brings it to the foreground.
+ *
+ * @remarks At least one provider must be registered. Call from the **provider process**,
+ * matching {@link register}.
+ *
+ * @returns A promise that resolves once the VPW window is shown.
+ *
+ * @example
+ * ```ts
+ * import { Storefront } from '@openfin/workspace-platform';
+ *
+ * await Storefront.show();
+ * ```
+ */
+export declare const show: () => Promise<void>;
+/**
+ * Hides the Storefront VPW window.
+ *
+ * @remarks At least one provider must be registered. Call from the **provider process**,
+ * matching {@link register}.
+ *
+ * @returns A promise that resolves once the VPW window is hidden.
+ *
+ * @example
+ * ```ts
+ * import { Storefront } from '@openfin/workspace-platform';
+ *
+ * await Storefront.hide();
+ * ```
+ */
+export declare const hide: () => Promise<void>;
+/**
+ * Shows the Storefront VPW window after the client `ready` handshake completes.
+ *
+ * Unlike {@link show}, this does not focus the window.
+ *
+ * @remarks At least one provider must be registered. Call from the **provider process**,
+ * matching {@link register}.
+ *
+ * @returns A promise that resolves once the VPW window is shown.
+ */
+export declare const showWhenReady: () => Promise<void>;

package/storefront-vpw/src/shapes/index.d.ts

@@ -0,0 +1 @@
+export * from './shapes';

package/storefront-vpw/src/shapes/shapes.d.ts

@@ -0,0 +1,4 @@
+import type { OpenFin } from '@openfin/core';
+import type { StorefrontProvider } from '../../../client-api/src/shapes';
+export type StorefrontAllowedWindowOptions = Pick<OpenFin.PlatformWindowCreationOptions, 'defaultLeft' | 'defaultTop' | 'defaultWidth' | 'defaultHeight' | 'taskbarIconGroup' | 'saveWindowState'>;
+export type { StorefrontProvider };