@final-commerce/command-frame 0.1.46 → 0.1.48

package/README.md

@@ -61,7 +61,7 @@ const products = await client.getProducts();
 For building applications that run inside the Final Commerce Management Dashboard.
 
 - **[Manage Documentation](./src/projects/manage/README.md)**
-- **Features:** Context information, Dashboard widgets (more coming soon).
+- **Features:** Context, catalog, entities, custom tables, secrets, and optional host-specific commands (navigation, media, tax, branding, notifications) when the dashboard implements them.
 
 ```typescript
 import { ManageClient } from '@final-commerce/command-frame';

package/dist/actions/get-branding/action.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Get branding action — current theme tokens from the Manage host.
+ */
+import type { GetBranding } from "./types";
+export declare const getBranding: GetBranding;

package/dist/actions/get-branding/action.js

@@ -0,0 +1,7 @@
+/**
+ * Get branding action — current theme tokens from the Manage host.
+ */
+import { commandFrameClient } from "../../client";
+export const getBranding = async () => {
+    return await commandFrameClient.call("getBranding");
+};

package/dist/actions/get-branding/mock.d.ts

@@ -0,0 +1,2 @@
+import { GetBranding } from "./types";
+export declare const mockGetBranding: GetBranding;

package/dist/actions/get-branding/mock.js

@@ -0,0 +1,24 @@
+export const mockGetBranding = async () => {
+    console.log("[Mock] getBranding called");
+    return {
+        theme: "light",
+        colors: {
+            primary: "#2563eb",
+            secondary: "#64748b",
+            accent: "#0ea5e9",
+            destructive: "#dc2626",
+            sidebar: "#1e293b",
+            background: "#ffffff",
+            foreground: "#0f172a",
+            muted: "#f1f5f9",
+            border: "#e2e8f0"
+        },
+        borderRadius: "round",
+        borderRadiusValue: "0.5rem",
+        font: {
+            family: "system-ui, sans-serif"
+        },
+        logo: null,
+        timestamp: new Date().toISOString()
+    };
+};

package/dist/actions/get-branding/types.d.ts

@@ -0,0 +1,23 @@
+export type BorderRadiusPreset = "sharp" | "soft" | "round" | "pill";
+export interface GetBrandingResponse {
+    theme: "light" | "dark";
+    colors: {
+        primary: string;
+        secondary: string;
+        accent: string;
+        destructive: string;
+        sidebar: string;
+        background: string;
+        foreground: string;
+        muted: string;
+        border: string;
+    };
+    borderRadius: BorderRadiusPreset;
+    borderRadiusValue: string;
+    font: {
+        family: string;
+    };
+    logo: string | null;
+    timestamp: string;
+}
+export type GetBranding = () => Promise<GetBrandingResponse>;

package/dist/actions/get-branding/types.js

@@ -0,0 +1,2 @@
+// Get Branding Types (Manage host extension)
+export {};

package/dist/actions/get-media/action.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Get media action — list media library items from the Manage host.
+ */
+import type { GetMedia } from "./types";
+export declare const getMedia: GetMedia;

package/dist/actions/get-media/action.js

@@ -0,0 +1,7 @@
+/**
+ * Get media action — list media library items from the Manage host.
+ */
+import { commandFrameClient } from "../../client";
+export const getMedia = async (params) => {
+    return await commandFrameClient.call("getMedia", params);
+};

package/dist/actions/get-media/mock.d.ts

@@ -0,0 +1,2 @@
+import { GetMedia } from "./types";
+export declare const mockGetMedia: GetMedia;

package/dist/actions/get-media/mock.js

@@ -0,0 +1,35 @@
+const now = new Date().toISOString();
+export const mockGetMedia = async (params) => {
+    console.log("[Mock] getMedia called", params);
+    const items = [
+        {
+            _id: "mock_media_1",
+            url: "https://example.com/media/photo1.jpg",
+            filename: "photo1.jpg",
+            mimeType: "image/jpeg",
+            size: 102400,
+            folder: "images",
+            title: "Sample photo",
+            alt: "Sample",
+            width: 800,
+            height: 600,
+            createdAt: now
+        },
+        {
+            _id: "mock_media_2",
+            url: "https://example.com/media/doc.pdf",
+            filename: "doc.pdf",
+            mimeType: "application/pdf",
+            size: 51200,
+            folder: "documents",
+            createdAt: now
+        }
+    ];
+    return {
+        items,
+        total: items.length,
+        page: params?.page ?? 1,
+        pageSize: params?.pageSize ?? 20,
+        timestamp: new Date().toISOString()
+    };
+};

package/dist/actions/get-media/types.d.ts

@@ -0,0 +1,30 @@
+export interface GetMediaParams {
+    search?: string;
+    mimeType?: string[];
+    folder?: string;
+    page?: number;
+    pageSize?: number;
+    sortBy?: "createdAt" | "filename" | "size" | "title";
+    sortDir?: "asc" | "desc";
+}
+export interface MediaItemPayload {
+    _id: string;
+    url: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+    folder: string;
+    title?: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+    createdAt: string;
+}
+export interface GetMediaResponse {
+    items: MediaItemPayload[];
+    total: number;
+    page: number;
+    pageSize: number;
+    timestamp: string;
+}
+export type GetMedia = (params?: GetMediaParams) => Promise<GetMediaResponse>;

package/dist/actions/get-media/types.js

@@ -0,0 +1,2 @@
+// Get Media Types (Manage host extension)
+export {};

package/dist/actions/get-tax-tables/action.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Get tax tables action — list tax tables for the company.
+ */
+import type { GetTaxTables } from "./types";
+export declare const getTaxTables: GetTaxTables;

package/dist/actions/get-tax-tables/action.js

@@ -0,0 +1,7 @@
+/**
+ * Get tax tables action — list tax tables for the company.
+ */
+import { commandFrameClient } from "../../client";
+export const getTaxTables = async () => {
+    return await commandFrameClient.call("getTaxTables");
+};

package/dist/actions/get-tax-tables/mock.d.ts

@@ -0,0 +1,2 @@
+import { GetTaxTables } from "./types";
+export declare const mockGetTaxTables: GetTaxTables;

package/dist/actions/get-tax-tables/mock.js

@@ -0,0 +1,21 @@
+export const mockGetTaxTables = async () => {
+    console.log("[Mock] getTaxTables called");
+    return {
+        taxTables: [
+            {
+                _id: "mock_table_1",
+                name: "Standard",
+                rates: [
+                    { _id: "mock_rate_1", name: "GST", isCompounding: false },
+                    { _id: "mock_rate_2", name: "PST", isCompounding: true }
+                ]
+            },
+            {
+                _id: "mock_table_2",
+                name: "Zero",
+                rates: [{ _id: "mock_rate_3", name: "Zero rated", isCompounding: false }]
+            }
+        ],
+        timestamp: new Date().toISOString()
+    };
+};

package/dist/actions/get-tax-tables/types.d.ts

@@ -0,0 +1,15 @@
+export interface TaxRatePayload {
+    _id: string;
+    name: string;
+    isCompounding: boolean;
+}
+export interface TaxTablePayload {
+    _id: string;
+    name: string;
+    rates: TaxRatePayload[];
+}
+export interface GetTaxTablesResponse {
+    taxTables: TaxTablePayload[];
+    timestamp: string;
+}
+export type GetTaxTables = () => Promise<GetTaxTablesResponse>;

package/dist/actions/get-tax-tables/types.js

@@ -0,0 +1,2 @@
+// Get Tax Tables Types (Manage host extension)
+export {};

package/dist/actions/navigate-to/action.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Navigate to action — SPA navigation in the Manage host.
+ */
+import type { NavigateTo } from "./types";
+export declare const navigateTo: NavigateTo;

package/dist/actions/navigate-to/action.js

@@ -0,0 +1,7 @@
+/**
+ * Navigate to action — SPA navigation in the Manage host.
+ */
+import { commandFrameClient } from "../../client";
+export const navigateTo = async (params) => {
+    return await commandFrameClient.call("navigateTo", params);
+};

package/dist/actions/navigate-to/mock.d.ts

@@ -0,0 +1,2 @@
+import { NavigateTo } from "./types";
+export declare const mockNavigateTo: NavigateTo;

package/dist/actions/navigate-to/mock.js

@@ -0,0 +1,7 @@
+export const mockNavigateTo = async (params) => {
+    console.log("[Mock] navigateTo called", params.path);
+    return {
+        success: true,
+        timestamp: new Date().toISOString()
+    };
+};

package/dist/actions/navigate-to/types.d.ts

@@ -0,0 +1,9 @@
+export interface NavigateToParams {
+    /** In-app path (must start with `/`). Hosts may restrict allowed prefixes. */
+    path: string;
+}
+export interface NavigateToResponse {
+    success: boolean;
+    timestamp: string;
+}
+export type NavigateTo = (params: NavigateToParams) => Promise<NavigateToResponse>;

package/dist/actions/navigate-to/types.js

@@ -0,0 +1,2 @@
+// Navigate To Types (Manage host extension)
+export {};

package/dist/actions/refresh-resource/action.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Refresh resource action — invalidate cached list/detail data in the Manage host.
+ */
+import type { RefreshResource } from "./types";
+export declare const refreshResource: RefreshResource;

package/dist/actions/refresh-resource/action.js

@@ -0,0 +1,7 @@
+/**
+ * Refresh resource action — invalidate cached list/detail data in the Manage host.
+ */
+import { commandFrameClient } from "../../client";
+export const refreshResource = async (params) => {
+    return await commandFrameClient.call("refreshResource", params);
+};

package/dist/actions/refresh-resource/mock.d.ts

@@ -0,0 +1,2 @@
+import { RefreshResource } from "./types";
+export declare const mockRefreshResource: RefreshResource;

package/dist/actions/refresh-resource/mock.js

@@ -0,0 +1,7 @@
+export const mockRefreshResource = async (params) => {
+    console.log("[Mock] refreshResource called", params.resource);
+    return {
+        success: true,
+        timestamp: new Date().toISOString()
+    };
+};

package/dist/actions/refresh-resource/types.d.ts

@@ -0,0 +1,9 @@
+export interface RefreshResourceParams {
+    /** Resource key used by the host data layer (e.g. Refine resource name). */
+    resource: string;
+}
+export interface RefreshResourceResponse {
+    success: boolean;
+    timestamp: string;
+}
+export type RefreshResource = (params: RefreshResourceParams) => Promise<RefreshResourceResponse>;

package/dist/actions/refresh-resource/types.js

@@ -0,0 +1,2 @@
+// Refresh Resource Types (Manage host extension)
+export {};

package/dist/actions/show-notification/mock.js

@@ -1,6 +1,6 @@
 export const mockShowNotification = async (params) => {
-    console.log("[Mock] showNotification called", params);
-    window.alert(`Notification: ${params?.message || "No message"}`);
+    console.log("[Mock] showNotification called", params?.message, params?.type);
+    window.alert(`Notification${params?.type ? ` (${params.type})` : ""}: ${params?.message || "No message"}`);
     return {
         success: true,
         message: params?.message || "",

package/dist/actions/show-notification/types.d.ts

@@ -1,5 +1,7 @@
 export interface ShowNotificationParams {
     message: string;
+    /** Visual style when the host supports it (e.g. toast variant). */
+    type?: "success" | "error" | "info" | "warning";
 }
 export interface ShowNotificationResponse {
     success: boolean;

package/dist/actions/upload-media/action.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Upload media action — upload a file via the Manage host.
+ */
+import type { UploadMedia } from "./types";
+export declare const uploadMedia: UploadMedia;

package/dist/actions/upload-media/action.js

@@ -0,0 +1,7 @@
+/**
+ * Upload media action — upload a file via the Manage host.
+ */
+import { commandFrameClient } from "../../client";
+export const uploadMedia = async (params) => {
+    return await commandFrameClient.call("uploadMedia", params);
+};

package/dist/actions/upload-media/mock.d.ts

@@ -0,0 +1,2 @@
+import { UploadMedia } from "./types";
+export declare const mockUploadMedia: UploadMedia;

package/dist/actions/upload-media/mock.js

@@ -0,0 +1,14 @@
+export const mockUploadMedia = async (params) => {
+    console.log("[Mock] uploadMedia called", params.filename, params.mimeType);
+    return {
+        success: true,
+        url: `https://example.com/media/mock/${encodeURIComponent(params.filename)}`,
+        id: "mock_upload_id",
+        filename: params.filename,
+        mimeType: params.mimeType,
+        size: 1234,
+        width: null,
+        height: null,
+        timestamp: new Date().toISOString()
+    };
+};

package/dist/actions/upload-media/types.d.ts

@@ -0,0 +1,20 @@
+export interface UploadMediaParams {
+    /** Base64-encoded file content (no data URL prefix). */
+    base64: string;
+    filename: string;
+    mimeType: string;
+    /** Target folder label; host default if omitted. */
+    folder?: string;
+}
+export interface UploadMediaResponse {
+    success: boolean;
+    url: string;
+    id?: string | null;
+    filename?: string;
+    mimeType?: string;
+    size?: number;
+    width?: number | null;
+    height?: number | null;
+    timestamp: string;
+}
+export type UploadMedia = (params: UploadMediaParams) => Promise<UploadMediaResponse>;

package/dist/actions/upload-media/types.js

@@ -0,0 +1,2 @@
+// Upload Media Types (Manage host extension)
+export {};

package/dist/index.d.ts

@@ -72,6 +72,12 @@ export declare const command: {
     readonly getSecretsKeys: import("./actions/get-secrets-keys/types").GetSecretsKeys;
     readonly getSecretVal: import("./actions/get-secret-val/types").GetSecretVal;
     readonly setSecretVal: import("./actions/set-secret-val/types").SetSecretVal;
+    readonly navigateTo: import("./actions/navigate-to/types").NavigateTo;
+    readonly refreshResource: import("./actions/refresh-resource/types").RefreshResource;
+    readonly getMedia: import("./actions/get-media/types").GetMedia;
+    readonly uploadMedia: import("./actions/upload-media/types").UploadMedia;
+    readonly getTaxTables: import("./actions/get-tax-tables/types").GetTaxTables;
+    readonly getBranding: import("./actions/get-branding/types").GetBranding;
 };
 export type { ExampleFunction, ExampleFunctionParams, ExampleFunctionResponse } from "./actions/example-function/types";
 export type { GenerateAPIKey, GenerateAPIKeyParams, GenerateAPIKeyResponse } from "./actions/generate-api-key/types";
@@ -128,6 +134,12 @@ export type { RemoveCustomerFromCart, RemoveCustomerFromCartResponse } from "./a
 export type { GoToStationHome, GoToStationHomeResponse } from "./actions/go-to-station-home/types";
 export type { OpenCashDrawer, OpenCashDrawerResponse } from "./actions/open-cash-drawer/types";
 export type { ShowNotification, ShowNotificationParams, ShowNotificationResponse } from "./actions/show-notification/types";
+export type { NavigateTo, NavigateToParams, NavigateToResponse } from "./actions/navigate-to/types";
+export type { RefreshResource, RefreshResourceParams, RefreshResourceResponse } from "./actions/refresh-resource/types";
+export type { GetMedia, GetMediaParams, GetMediaResponse, MediaItemPayload } from "./actions/get-media/types";
+export type { UploadMedia, UploadMediaParams, UploadMediaResponse } from "./actions/upload-media/types";
+export type { GetTaxTables, GetTaxTablesResponse, TaxRatePayload, TaxTablePayload } from "./actions/get-tax-tables/types";
+export type { BorderRadiusPreset, GetBranding, GetBrandingResponse } from "./actions/get-branding/types";
 export type { ShowConfirmation, ShowConfirmationParams, ShowConfirmationResponse } from "./actions/show-confirmation/types";
 export type { AuthenticateUser, AuthenticateUserParams, AuthenticateUserResponse } from "./actions/authenticate-user/types";
 export type { PartialPayment, PartialPaymentParams, PartialPaymentResponse } from "./actions/partial-payment/types";

package/dist/index.js

@@ -83,6 +83,13 @@ import { deleteProduct } from "./actions/delete-product/action";
 // Entity Actions
 import { getOutlets } from "./actions/get-outlets/action";
 import { getStations } from "./actions/get-stations/action";
+// Manage extension actions (optional hosts: Deerlake, etc.)
+import { navigateTo } from "./actions/navigate-to/action";
+import { refreshResource } from "./actions/refresh-resource/action";
+import { getMedia } from "./actions/get-media/action";
+import { uploadMedia } from "./actions/upload-media/action";
+import { getTaxTables } from "./actions/get-tax-tables/action";
+import { getBranding } from "./actions/get-branding/action";
 // Export actions as command object
 export const command = {
     exampleFunction,
@@ -170,6 +177,13 @@ export const command = {
     getSecretsKeys,
     getSecretVal,
     setSecretVal,
+    // Manage extension actions (optional on ManageProviderActions)
+    navigateTo,
+    refreshResource,
+    getMedia,
+    uploadMedia,
+    getTaxTables,
+    getBranding,
 };
 export { EXTENSION_REFUND_REQUEST_ACTION } from "./actions/extension-refund/constants";
 export { installExtensionRefundListener } from "./actions/extension-refund/extension-refund-listener";

package/dist/projects/manage/mocks.js

@@ -26,6 +26,14 @@ import { mockDeleteProduct } from "../../actions/delete-product/mock";
 import { mockGetOutlets } from "../../actions/get-outlets/mock";
 import { mockGetStations } from "../../actions/get-stations/mock";
 import { mockGetOrders } from "../../actions/get-orders/mock";
+// Manage extension mocks
+import { mockShowNotification } from "../../actions/show-notification/mock";
+import { mockNavigateTo } from "../../actions/navigate-to/mock";
+import { mockRefreshResource } from "../../actions/refresh-resource/mock";
+import { mockGetMedia } from "../../actions/get-media/mock";
+import { mockUploadMedia } from "../../actions/upload-media/mock";
+import { mockGetTaxTables } from "../../actions/get-tax-tables/mock";
+import { mockGetBranding } from "../../actions/get-branding/mock";
 // Manage-specific mock for getFinalContext
 const mockGetFinalContextManage = async () => {
     console.log("[Mock] getFinalContext called (Manage)");
@@ -63,4 +71,12 @@ export const MANAGE_MOCKS = {
     getOutlets: mockGetOutlets,
     getStations: mockGetStations,
     getOrders: mockGetOrders,
+    // Manage extension mocks
+    showNotification: mockShowNotification,
+    navigateTo: mockNavigateTo,
+    refreshResource: mockRefreshResource,
+    getMedia: mockGetMedia,
+    uploadMedia: mockUploadMedia,
+    getTaxTables: mockGetTaxTables,
+    getBranding: mockGetBranding,
 };

package/dist/projects/manage/types.d.ts

@@ -1,4 +1,4 @@
-import type { GetContext, GetFinalContext, GetSecretsKeys, GetSecretVal, SetSecretVal, GenerateAPIKey, GetCustomTables, GetCustomTableData, UpsertCustomTableData, DeleteCustomTableData, GetCustomExtensions, GetCurrentCompanyCustomExtensions, GetCustomExtensionCustomTables, GetCustomers, GetProducts, GetCategories, EditProduct, EditProductVariants, DeleteProduct, GetOutlets, GetStations, GetOrders, GetUsers, GetRoles } from "../../index";
+import type { GetContext, GetFinalContext, GetSecretsKeys, GetSecretVal, SetSecretVal, GenerateAPIKey, GetCustomTables, GetCustomTableData, UpsertCustomTableData, DeleteCustomTableData, GetCustomExtensions, GetCurrentCompanyCustomExtensions, GetCustomExtensionCustomTables, GetCustomers, GetProducts, GetCategories, EditProduct, EditProductVariants, DeleteProduct, GetOutlets, GetStations, GetOrders, GetUsers, GetRoles, ShowNotification, NavigateTo, RefreshResource, GetMedia, UploadMedia, GetTaxTables, GetBranding } from "../../index";
 export interface ManageProviderActions {
     getContext: GetContext;
     getFinalContext: GetFinalContext;
@@ -24,4 +24,18 @@ export interface ManageProviderActions {
     getOutlets: GetOutlets;
     getStations: GetStations;
     getOrders: GetOrders;
+    /** Optional: toast / notification in host shell (e.g. Deerlake). */
+    showNotification?: ShowNotification;
+    /** Optional: SPA navigation (e.g. Deerlake). */
+    navigateTo?: NavigateTo;
+    /** Optional: invalidate cached data for a resource key (e.g. Deerlake). */
+    refreshResource?: RefreshResource;
+    /** Optional: list media library (e.g. Deerlake). */
+    getMedia?: GetMedia;
+    /** Optional: upload media via host (e.g. Deerlake). */
+    uploadMedia?: UploadMedia;
+    /** Optional: tax tables for company (e.g. Deerlake). */
+    getTaxTables?: GetTaxTables;
+    /** Optional: theme tokens for iframe styling (e.g. Deerlake). */
+    getBranding?: GetBranding;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@final-commerce/command-frame",
-    "version": "0.1.46",
+    "version": "0.1.48",
     "description": "Commands Frame library",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",