@veltrixsecops/app-sdk 1.0.1 → 1.3.0

package/dist/{index-BI8f_mBw.d.ts → use-app-context-DdrtEPeb.d.ts}

@@ -1,4 +1,4 @@
-import * as react from 'react';
+import { Context } from 'react';
 
 type AppSource = 'BUILT_IN' | 'MARKETPLACE' | 'CUSTOM';
 type AppStatusType = 'AVAILABLE' | 'DEPRECATED' | 'REMOVED';
@@ -39,6 +39,13 @@ interface AppManifest {
         entry: string;
         pages?: AppPageDeclaration[];
     };
+    /**
+     * Vendor brand identity, applied by the platform in defined slots only —
+     * the app navbar (logo, accent) and scoped CSS variables. The platform,
+     * not the app, decides where brand color appears, so one vendor's palette
+     * never overwhelms the product shell.
+     */
+    branding?: AppBrandingDeclaration;
     hooks?: {
         onInstall?: string;
         onUninstall?: string;
@@ -49,6 +56,25 @@ interface AppManifest {
     events?: string[];
     settings?: AppSettingDeclaration[];
 }
+/**
+ * App brand identity. The platform renders it in a per-app navbar above the
+ * app's pages and exposes the colors to app pages as scoped CSS variables
+ * (--veltrix-app-primary, --veltrix-app-accent).
+ */
+interface AppBrandingDeclaration {
+    /** Brand accent color as #RGB or #RRGGBB hex (e.g. CrowdStrike red). */
+    primaryColor?: string;
+    /** Optional secondary color as #RGB or #RRGGBB hex. */
+    accentColor?: string;
+    /**
+     * Vendor logo shown in the app navbar. Repo-relative .svg (preferred) or
+     * .png, at most 128 KB; rendered at 28px height, so use a wide/landscape
+     * mark with transparent background.
+     */
+    logo?: string;
+    /** Optional logo variant for dark backgrounds; same constraints as logo. */
+    logoDark?: string;
+}
 interface AppConfigurationTypeManifest {
     id: string;
     name: string;
@@ -74,13 +100,50 @@ interface AppPermissionDeclaration {
     actions: string[];
     description?: string;
 }
+/**
+ * How the platform frames an app page.
+ * - `standard`   — page header + padded content area (default; use for most pages)
+ * - `full-bleed` — content area with no padding/toolbar (custom canvases, maps)
+ * - `canvas`     — Configuration Canvas chrome (section rail + save/validate bar)
+ */
+type AppPageLayout = 'standard' | 'full-bleed' | 'canvas';
+declare const APP_PAGE_LAYOUTS: readonly ["standard", "full-bleed", "canvas"];
+/**
+ * Where the page surfaces in navigation.
+ * - `sidebar` — an entry beneath the app in the sidebar
+ * - `tab`     — a tab within its `parent` page
+ * - `hidden`  — routable but not linked (details/drill-down pages)
+ */
+type AppPageNav = 'sidebar' | 'tab' | 'hidden';
+declare const APP_PAGE_NAV: readonly ["sidebar", "tab", "hidden"];
+/** An app-scoped permission (declared in `permissions.app`) required to see a page. */
+interface AppPagePermission {
+    resource: string;
+    action: string;
+}
 interface AppPageDeclaration {
+    /** Route beneath the app, e.g. `/indexes` → `/apps/<app-id>/indexes` */
     path: string;
+    /** Exported component name from the app's client entry */
     component: string;
     label: string;
+    description?: string;
+    /** Icon name from the platform icon set; falls back to the app icon */
     icon?: string;
+    /** @deprecated use `nav: 'sidebar' | 'hidden'` — kept for backward compatibility */
     sidebar?: boolean;
+    /** Navigation placement. Defaults to `sidebar` when `sidebar: true`, else `hidden`. */
+    nav?: AppPageNav;
+    /** Parent page `path` — required for `nav: 'tab'`, optional nesting for sidebar entries */
     parent?: string;
+    /** Optional sidebar section label, for apps with many pages */
+    group?: string;
+    /** Deterministic ordering within its group/parent (ascending; ties break on label) */
+    order?: number;
+    /** Layout preset the platform renders around the page body */
+    layout?: AppPageLayout;
+    /** Hide the page (and its nav entry) unless the user holds this app permission */
+    requiresPermission?: AppPagePermission;
 }
 interface AppSettingDeclaration {
     key: string;
@@ -231,8 +294,10 @@ interface AppContextValue {
     getCredentials: () => Promise<Credential[]>;
     getTags: () => Promise<Tag[]>;
     settings: Record<string, unknown>;
+    /** The app's manifest branding, resolved by the platform (null when unset). */
+    branding?: AppBrandingDeclaration | null;
 }
-declare const AppContext: react.Context<AppContextValue | null>;
+declare const AppContext: Context<AppContextValue | null>;
 /**
  * Access the app context in any app component.
  *
@@ -248,39 +313,4 @@ declare const AppContext: react.Context<AppContextValue | null>;
  */
 declare function useAppContext(): AppContextValue;
 
-interface PipelineStatusData {
-    pendingApprovals: number;
-    activeDeployments: number;
-    failedDeployments: number;
-    unresolvedDrifts: number;
-    recentDeployments: Array<{
-        id: string;
-        canvasName: string;
-        environment: string;
-        status: string;
-        startedAt: string;
-        completedAt?: string;
-    }>;
-}
-/**
- * Hook to access pipeline status for the current app/customer.
- *
- * @example
- * ```tsx
- * import { usePipelineStatus } from '@veltrixsecops/app-sdk/hooks'
- *
- * function Dashboard() {
- *   const { data, isLoading } = usePipelineStatus('my-app')
- *   if (isLoading) return <Spinner />
- *   return <div>{data.activeDeployments} active deployments</div>
- * }
- * ```
- */
-declare function usePipelineStatus(appId: string): {
-    data: PipelineStatusData | null;
-    isLoading: boolean;
-    error: Error | null;
-    refresh: () => Promise<void>;
-};
-
-export { type AppConfigurationTypeManifest as A, type Component as C, type PipelineStatusData as P, type Tag as T, type User as U, AppContext as a, type AppContextValue as b, type AppDetail as c, type AppHookContext as d, type AppInstallationDetail as e, type AppInstallationStatus as f, type AppListItem as g, type AppManifest as h, type AppPageDeclaration as i, type AppPermissionDeclaration as j, type AppRouteContext as k, type AppSettingDeclaration as l, type AppSource as m, type AppStatusType as n, type Connectivity as o, type Credential as p, type Customer as q, type PlatformDatabaseClient as r, usePipelineStatus as s, useAppContext as u };
+export { type AppContextValue as A, type Component as C, type PlatformDatabaseClient as P, type Tag as T, type User as U, type AppBrandingDeclaration as a, APP_PAGE_LAYOUTS as b, APP_PAGE_NAV as c, type AppConfigurationTypeManifest as d, AppContext as e, type AppDetail as f, type AppHookContext as g, type AppInstallationDetail as h, type AppInstallationStatus as i, type AppListItem as j, type AppManifest as k, type AppPageDeclaration as l, type AppPageLayout as m, type AppPageNav as n, type AppPagePermission as o, type AppPermissionDeclaration as p, type AppRouteContext as q, type AppSettingDeclaration as r, type AppSource as s, type AppStatusType as t, type Connectivity as u, type Credential as v, type Customer as w, useAppContext as x };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veltrixsecops/app-sdk",
-  "version": "1.0.1",
+  "version": "1.3.0",
   "description": "Official SDK for building Veltrix Security-as-Code apps — typed pipeline handler contracts, lifecycle hook types, manifest types, and React hooks.",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -38,6 +38,16 @@
         "default": "./dist/hooks/index.cjs"
       }
     },
+    "./client": {
+      "import": {
+        "types": "./dist/client/index.d.ts",
+        "default": "./dist/client/index.js"
+      },
+      "require": {
+        "types": "./dist/client/index.d.cts",
+        "default": "./dist/client/index.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "files": [

package/dist/chunk-TSEIWO6T.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/hooks/use-app-context.ts","../src/hooks/use-pipeline-status.ts"],"sourcesContent":["// ========================================================================\n// React hooks for app developers\n// These provide access to platform data and pipeline state\n// ========================================================================\n\nimport { createContext, useContext } from 'react'\nimport type { Component, Credential, Tag, User, Customer } from '../types/platform'\n\nexport interface AppContextValue {\n  appId: string\n  customerId: string\n  user: User | null\n  customer: Customer | null\n\n  // Platform data accessors\n  getComponents: () => Promise<Component[]>\n  getCredentials: () => Promise<Credential[]>\n  getTags: () => Promise<Tag[]>\n\n  // App settings\n  settings: Record<string, unknown>\n}\n\nexport const AppContext = createContext<AppContextValue | null>(null)\n\n/**\n * Access the app context in any app component.\n *\n * @example\n * ```tsx\n * import { useAppContext } from '@veltrixsecops/app-sdk/hooks'\n *\n * function MyComponent() {\n *   const { appId, settings, getComponents } = useAppContext()\n *   // ...\n * }\n * ```\n */\nexport function useAppContext(): AppContextValue {\n  const ctx = useContext(AppContext)\n  if (!ctx) {\n    throw new Error('useAppContext must be used within an AppContextProvider')\n  }\n  return ctx\n}\n","import { useState, useEffect, useCallback } from 'react'\n\nexport interface PipelineStatusData {\n  pendingApprovals: number\n  activeDeployments: number\n  failedDeployments: number\n  unresolvedDrifts: number\n  recentDeployments: Array<{\n    id: string\n    canvasName: string\n    environment: string\n    status: string\n    startedAt: string\n    completedAt?: string\n  }>\n}\n\n/**\n * Hook to access pipeline status for the current app/customer.\n *\n * @example\n * ```tsx\n * import { usePipelineStatus } from '@veltrixsecops/app-sdk/hooks'\n *\n * function Dashboard() {\n *   const { data, isLoading } = usePipelineStatus('my-app')\n *   if (isLoading) return <Spinner />\n *   return <div>{data.activeDeployments} active deployments</div>\n * }\n * ```\n */\nexport function usePipelineStatus(appId: string) {\n  const [data, setData] = useState<PipelineStatusData | null>(null)\n  const [isLoading, setIsLoading] = useState(true)\n  const [error, setError] = useState<Error | null>(null)\n\n  const refresh = useCallback(async () => {\n    try {\n      setIsLoading(true)\n      const response = await fetch(`/api/pipeline/summary?appId=${appId}`)\n      if (!response.ok) throw new Error(`Failed to fetch pipeline status`)\n      const result = await response.json()\n      setData(result)\n      setError(null)\n    } catch (err) {\n      setError(err instanceof Error ? err : new Error('Unknown error'))\n    } finally {\n      setIsLoading(false)\n    }\n  }, [appId])\n\n  useEffect(() => {\n    refresh()\n  }, [refresh])\n\n  return { data, isLoading, error, refresh }\n}\n"],"mappings":";AAKA,SAAS,eAAe,kBAAkB;AAkBnC,IAAM,aAAa,cAAsC,IAAI;AAe7D,SAAS,gBAAiC;AAC/C,QAAM,MAAM,WAAW,UAAU;AACjC,MAAI,CAAC,KAAK;AACR,UAAM,IAAI,MAAM,yDAAyD;AAAA,EAC3E;AACA,SAAO;AACT;;;AC5CA,SAAS,UAAU,WAAW,mBAAmB;AA+B1C,SAAS,kBAAkB,OAAe;AAC/C,QAAM,CAAC,MAAM,OAAO,IAAI,SAAoC,IAAI;AAChE,QAAM,CAAC,WAAW,YAAY,IAAI,SAAS,IAAI;AAC/C,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAuB,IAAI;AAErD,QAAM,UAAU,YAAY,YAAY;AACtC,QAAI;AACF,mBAAa,IAAI;AACjB,YAAM,WAAW,MAAM,MAAM,+BAA+B,KAAK,EAAE;AACnE,UAAI,CAAC,SAAS,GAAI,OAAM,IAAI,MAAM,iCAAiC;AACnE,YAAM,SAAS,MAAM,SAAS,KAAK;AACnC,cAAQ,MAAM;AACd,eAAS,IAAI;AAAA,IACf,SAAS,KAAK;AACZ,eAAS,eAAe,QAAQ,MAAM,IAAI,MAAM,eAAe,CAAC;AAAA,IAClE,UAAE;AACA,mBAAa,KAAK;AAAA,IACpB;AAAA,EACF,GAAG,CAAC,KAAK,CAAC;AAEV,YAAU,MAAM;AACd,YAAQ;AAAA,EACV,GAAG,CAAC,OAAO,CAAC;AAEZ,SAAO,EAAE,MAAM,WAAW,OAAO,QAAQ;AAC3C;","names":[]}