@veltrixsecops/app-sdk 1.0.1 → 1.3.0

package/README.md

@@ -73,6 +73,66 @@ export default async function onInstall({ db, appId }: AppHookContext): Promise<
 
 ```tsx
 import { useAppContext, usePipelineStatus } from '@veltrixsecops/app-sdk/hooks'
+import { authFetch } from '@veltrixsecops/app-sdk/client'
+```
+
+Your `client/index.tsx` default-exports an `AppClientModule` (`{ id, pages, sidebarItems }`;
+`pages` keys must match `manifest.client.pages[].component`). At packaging time the CLI
+compiles it into a hermetic browser bundle (`client/dist/index.mjs`): `react`, `react-dom`,
+`react/jsx-runtime`, and all `@veltrixsecops/app-sdk` imports are replaced with shims that
+read the platform-provided runtime from `globalThis.__VELTRIX_APP_RUNTIME__`, so your
+components render inside the host React tree with working hooks and shared context — never
+bundle your own copy of React.
+
+Two rules for app pages:
+
+- Use **`authFetch`** (not plain `fetch`) for calls to your app's server routes
+  (`/api/apps/<app-id>/...`) — they are bearer-token protected and a plain `fetch`
+  receives 401s.
+- Only import third-party client libraries if you accept them being compiled into your
+  bundle; keep pages lean.
+
+## Branding
+
+Declare your vendor identity in the manifest and the platform applies it in defined
+slots — the app's navbar (logo + accent color) and scoped CSS variables. The platform
+controls where brand color appears, so it stays meaningful rather than theming the shell:
+
+```yaml
+branding:
+  primaryColor: "#FC0000"     # #RGB or #RRGGBB
+  logo: ./assets/logo.svg     # svg (preferred) or png, <=128 KB, ~28px display height
+```
+
+In pages, prefer the CSS variables (`--veltrix-app-primary`, `--veltrix-app-accent`);
+use `useAppBranding()` from `./hooks` when you need the values programmatically.
+SVG logos must not contain scripts or event handlers — the validator rejects them.
+
+## Standard app layout
+
+Every Veltrix app follows one canonical folder structure — the CLI scaffolds it (`veltrix init`), `veltrix validate` warns on deviations, and the SDK exports it as constants (`APP_LAYOUT`, `HANDLER_NAMES`, `conventionalPaths(configTypeId)`):
+
+```
+apps/<app-id>/
+├── manifest.yaml                          # App contract
+├── package.json / tsconfig.json / README.md
+├── config-types/<configTypeId>/           # Everything for one configuration type:
+│   ├── canvas.yaml                        #   form schema
+│   ├── defaults.yaml                      #   default values
+│   ├── validate.ts, deploy.ts, rollback.ts,
+│   ├── healthCheck.ts, driftDetect.ts, getStatus.ts
+│   └── __tests__/
+├── lib/                                   # Shared app code (API clients)
+├── hooks/                                 # onInstall.ts, onUninstall.ts, ...
+├── migrations/                            # SQL (with database.tablePrefix)
+├── server/index.ts                        # Route module (AppRouteContext)
+├── client/index.tsx + client/pages/       # Optional UI
+└── assets/                                # Optional icons
+```
+
+```ts
+import { conventionalPaths } from '@veltrixsecops/app-sdk'
+conventionalPaths('indexes').handlers.deploy // 'config-types/indexes/deploy'
 ```
 
 ## Package layout

package/dist/{chunk-TSEIWO6T.js → chunk-JOJTOQZQ.js}

@@ -1,6 +1,11 @@
+import {
+  authFetch
+} from "./chunk-PJN3ATPH.js";
+
 // src/hooks/use-app-context.ts
 import { createContext, useContext } from "react";
-var AppContext = createContext(null);
+var hostContext = globalThis.__VELTRIX_APP_RUNTIME__?.AppContext;
+var AppContext = hostContext ?? createContext(null);
 function useAppContext() {
   const ctx = useContext(AppContext);
   if (!ctx) {
@@ -18,7 +23,7 @@ function usePipelineStatus(appId) {
   const refresh = useCallback(async () => {
     try {
       setIsLoading(true);
-      const response = await fetch(`/api/pipeline/summary?appId=${appId}`);
+      const response = await authFetch(`/api/pipeline/summary?appId=${appId}`);
       if (!response.ok) throw new Error(`Failed to fetch pipeline status`);
       const result = await response.json();
       setData(result);
@@ -35,9 +40,15 @@ function usePipelineStatus(appId) {
   return { data, isLoading, error, refresh };
 }
 
+// src/hooks/use-app-branding.ts
+function useAppBranding() {
+  return useAppContext().branding ?? null;
+}
+
 export {
   AppContext,
   useAppContext,
-  usePipelineStatus
+  usePipelineStatus,
+  useAppBranding
 };
-//# sourceMappingURL=chunk-TSEIWO6T.js.map
+//# sourceMappingURL=chunk-JOJTOQZQ.js.map

package/dist/chunk-JOJTOQZQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hooks/use-app-context.ts","../src/hooks/use-pipeline-status.ts","../src/hooks/use-app-branding.ts"],"sourcesContent":["// ========================================================================\n// React hooks for app developers\n// These provide access to platform data and pipeline state\n// ========================================================================\n\nimport { createContext, useContext, type Context } from 'react'\nimport type { Component, Credential, Tag, User, Customer } from '../types/platform'\nimport type { AppBrandingDeclaration } from '../types/manifest'\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  /** The app's manifest branding, resolved by the platform (null when unset). */\n  branding?: AppBrandingDeclaration | null\n}\n\n// Anchor the context on the host runtime when running inside the platform,\n// so a bundle that inlined its own SDK copy still shares the host's context\n// (two createContext objects never match, even with identical shapes).\nconst hostContext = (\n  (globalThis as Record<string, unknown>).__VELTRIX_APP_RUNTIME__ as\n    | { AppContext?: Context<AppContextValue | null> }\n    | undefined\n)?.AppContext\n\nexport const AppContext: Context<AppContextValue | null> =\n  hostContext ?? 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'\nimport { authFetch } from '../client'\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      // Platform APIs are bearer-token protected — plain fetch would 401\n      const response = await authFetch(`/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","import { useAppContext } from './use-app-context'\nimport type { AppBrandingDeclaration } from '../types/manifest'\n\n/**\n * The app's brand identity as declared in manifest.yaml `branding`.\n *\n * The platform already applies it in the defined slots (the app navbar and\n * the scoped CSS variables --veltrix-app-primary / --veltrix-app-accent on\n * the app page container). Use this hook only when a page needs the values\n * programmatically — prefer the CSS variables for styling:\n *\n * @example\n * ```tsx\n * <span style={{ color: 'var(--veltrix-app-primary)' }}>12 detections</span>\n * ```\n */\nexport function useAppBranding(): AppBrandingDeclaration | null {\n  return useAppContext().branding ?? null\n}\n"],"mappings":";;;;;AAKA,SAAS,eAAe,kBAAgC;AAyBxD,IAAM,cACH,WAAuC,yBAGvC;AAEI,IAAM,aACX,eAAe,cAAsC,IAAI;AAepD,SAAS,gBAAiC;AAC/C,QAAM,MAAM,WAAW,UAAU;AACjC,MAAI,CAAC,KAAK;AACR,UAAM,IAAI,MAAM,yDAAyD;AAAA,EAC3E;AACA,SAAO;AACT;;;AC1DA,SAAS,UAAU,WAAW,mBAAmB;AAgC1C,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;AAEjB,YAAM,WAAW,MAAM,UAAU,+BAA+B,KAAK,EAAE;AACvE,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;;;AC1CO,SAAS,iBAAgD;AAC9D,SAAO,cAAc,EAAE,YAAY;AACrC;","names":[]}

package/dist/chunk-PJN3ATPH.js

@@ -0,0 +1,28 @@
+// src/client/index.ts
+var HOST_RUNTIME_GLOBAL = "__VELTRIX_APP_RUNTIME__";
+function getHostRuntime() {
+  const runtime = globalThis[HOST_RUNTIME_GLOBAL];
+  return runtime ?? null;
+}
+function requireHostRuntime() {
+  const runtime = getHostRuntime();
+  if (!runtime) {
+    throw new Error(
+      `Veltrix host runtime not found \u2014 app client bundles only run inside the Veltrix platform (missing globalThis.${HOST_RUNTIME_GLOBAL})`
+    );
+  }
+  return runtime;
+}
+function authFetch(input, init) {
+  const runtime = getHostRuntime();
+  if (runtime) return runtime.authFetch(input, init);
+  return fetch(input, init);
+}
+
+export {
+  HOST_RUNTIME_GLOBAL,
+  getHostRuntime,
+  requireHostRuntime,
+  authFetch
+};
+//# sourceMappingURL=chunk-PJN3ATPH.js.map

package/dist/chunk-PJN3ATPH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client/index.ts"],"sourcesContent":["// ========================================================================\n// Client runtime contract — how app client bundles talk to the host.\n//\n// App client code is packaged as a hermetic ESM bundle in which `react`,\n// `react-dom`, `react/jsx-runtime`, and every `@veltrixsecops/app-sdk`\n// subpath are compile-time shims that read the host-provided runtime from\n// `globalThis.__VELTRIX_APP_RUNTIME__`. The platform installs that global\n// (with ITS React instance, the shared AppContext, and an authenticated\n// fetch) before dynamically importing any app bundle, so app components\n// render inside the host React tree with working hooks and context.\n//\n// App authors: import from '@veltrixsecops/app-sdk/client' (and /hooks) —\n// never bundle your own copy of react. Use `authFetch` for calls to your\n// app's server routes (/api/apps/<app-id>/...): plain fetch() lacks the\n// platform's Authorization header and will receive 401s.\n// ========================================================================\n\nimport type { ComponentType, Context, LazyExoticComponent } from 'react'\nimport type { AppContextValue } from '../hooks/use-app-context'\n\nexport type { AppBrandingDeclaration } from '../types/manifest'\n\n/** Name of the global the platform installs before loading app bundles. */\nexport const HOST_RUNTIME_GLOBAL = '__VELTRIX_APP_RUNTIME__'\n\n/**\n * The runtime surface the platform exposes to app client bundles.\n * The react/reactDom/jsxRuntime members are the host's own module objects —\n * app bundles are compiled with shims that re-export them, guaranteeing a\n * single React instance per page.\n */\nexport interface VeltrixHostRuntime {\n  /** The host's `react` module object. */\n  react: unknown\n  /** The host's `react-dom` module object. */\n  reactDom: unknown\n  /** The host's `react-dom/client` module object. */\n  reactDomClient?: unknown\n  /** The host's `react/jsx-runtime` module object. */\n  jsxRuntime: unknown\n  /** Shared app context — the host wraps app pages in its Provider. */\n  AppContext: Context<AppContextValue | null>\n  /** fetch() with the platform's Authorization header attached. */\n  authFetch: (input: string, init?: RequestInit) => Promise<Response>\n  /**\n   * The SDK surface app bundles receive for `@veltrixsecops/app-sdk`,\n   * `.../hooks`, and `.../client` imports (useAppContext, AppContext,\n   * usePipelineStatus, authFetch, getHostRuntime, ...).\n   */\n  sdk: Record<string, unknown>\n}\n\n/** Read the host runtime, or null outside the platform (tests, storybook). */\nexport function getHostRuntime(): VeltrixHostRuntime | null {\n  const runtime = (globalThis as Record<string, unknown>)[HOST_RUNTIME_GLOBAL]\n  return (runtime as VeltrixHostRuntime) ?? null\n}\n\n/** Read the host runtime, throwing a diagnosable error when absent. */\nexport function requireHostRuntime(): VeltrixHostRuntime {\n  const runtime = getHostRuntime()\n  if (!runtime) {\n    throw new Error(\n      'Veltrix host runtime not found — app client bundles only run inside the ' +\n        `Veltrix platform (missing globalThis.${HOST_RUNTIME_GLOBAL})`,\n    )\n  }\n  return runtime\n}\n\n/**\n * fetch() that carries the platform's Authorization header. Required for an\n * app page to call its own server routes (/api/apps/<app-id>/...), which are\n * bearer-token protected. Falls back to plain fetch outside the platform.\n */\nexport function authFetch(input: string, init?: RequestInit): Promise<Response> {\n  const runtime = getHostRuntime()\n  if (runtime) return runtime.authFetch(input, init)\n  return fetch(input, init)\n}\n\n/** A sidebar entry contributed by the app's client entry module. */\nexport interface AppSidebarItem {\n  path: string\n  label: string\n  icon?: string\n}\n\n/**\n * Shape of the default export of an app's `client/index.tsx`.\n * `pages` keys must match `manifest.client.pages[].component`.\n */\nexport interface AppClientModule {\n  id: string\n  pages: Record<string, ComponentType | LazyExoticComponent<ComponentType>>\n  sidebarItems?: AppSidebarItem[]\n}\n"],"mappings":";AAuBO,IAAM,sBAAsB;AA8B5B,SAAS,iBAA4C;AAC1D,QAAM,UAAW,WAAuC,mBAAmB;AAC3E,SAAQ,WAAkC;AAC5C;AAGO,SAAS,qBAAyC;AACvD,QAAM,UAAU,eAAe;AAC/B,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI;AAAA,MACR,qHAC0C,mBAAmB;AAAA,IAC/D;AAAA,EACF;AACA,SAAO;AACT;AAOO,SAAS,UAAU,OAAe,MAAuC;AAC9E,QAAM,UAAU,eAAe;AAC/B,MAAI,QAAS,QAAO,QAAQ,UAAU,OAAO,IAAI;AACjD,SAAO,MAAM,OAAO,IAAI;AAC1B;","names":[]}

package/dist/{chunk-PJCHU6ZZ.js → chunk-VWFTOFTI.js}

@@ -30,4 +30,4 @@ export {
   defineHealthChecker,
   defineDriftDetector
 };
-//# sourceMappingURL=chunk-PJCHU6ZZ.js.map
+//# sourceMappingURL=chunk-VWFTOFTI.js.map

package/dist/{chunk-PJCHU6ZZ.js.map → chunk-VWFTOFTI.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/pipeline/define-validator.ts","../src/pipeline/define-deployer.ts","../src/pipeline/define-rollback-handler.ts","../src/pipeline/define-health-checker.ts","../src/pipeline/define-drift-detector.ts"],"sourcesContent":["import type { PipelineContext, ValidationResult } from '../types/pipeline'\n\n/**\n * Define a validation handler for a configuration type.\n *\n * @example\n * ```ts\n * import { defineValidator } from '@veltrixsecops/app-sdk/pipeline'\n *\n * export default defineValidator(async (ctx) => {\n *   const errors = []\n *   const name = ctx.canvas.sections[0]?.fields['name']\n *   if (!name) {\n *     errors.push({ field: 'name', message: 'Name is required', code: 'REQUIRED' })\n *   }\n *   return { valid: errors.length === 0, errors, warnings: [] }\n * })\n * ```\n */\nexport function defineValidator(\n  handler: (ctx: PipelineContext) => Promise<ValidationResult>,\n): (ctx: PipelineContext) => Promise<ValidationResult> {\n  return handler\n}\n","import type { DeployContext, DeployResult } from '../types/pipeline'\n\n/**\n * Define a deploy handler for a configuration type.\n *\n * @example\n * ```ts\n * import { defineDeployer } from '@veltrixsecops/app-sdk/pipeline'\n *\n * export default defineDeployer(async (ctx) => {\n *   const { component, credential, connectivity, canvas } = ctx\n *   // Push configuration to the tool\n *   return { success: true, message: 'Deployed', rollbackData: previousState }\n * })\n * ```\n */\nexport function defineDeployer(\n  handler: (ctx: DeployContext) => Promise<DeployResult>,\n): (ctx: DeployContext) => Promise<DeployResult> {\n  return handler\n}\n","import type { RollbackContext, RollbackResult } from '../types/pipeline'\r\n\r\n/**\r\n * Define a rollback handler for a configuration type.\r\n */\r\nexport function defineRollbackHandler(\r\n  handler: (ctx: RollbackContext) => Promise<RollbackResult>,\r\n): (ctx: RollbackContext) => Promise<RollbackResult> {\r\n  return handler\r\n}\r\n","import type { HealthCheckContext, HealthCheckResult } from '../types/pipeline'\r\n\r\n/**\r\n * Define a health check handler for a configuration type.\r\n */\r\nexport function defineHealthChecker(\r\n  handler: (ctx: HealthCheckContext) => Promise<HealthCheckResult>,\r\n): (ctx: HealthCheckContext) => Promise<HealthCheckResult> {\r\n  return handler\r\n}\r\n","import type { DriftContext, DriftResult } from '../types/pipeline'\r\n\r\n/**\r\n * Define a drift detection handler for a configuration type.\r\n */\r\nexport function defineDriftDetector(\r\n  handler: (ctx: DriftContext) => Promise<DriftResult>,\r\n): (ctx: DriftContext) => Promise<DriftResult> {\r\n  return handler\r\n}\r\n"],"mappings":";AAmBO,SAAS,gBACd,SACqD;AACrD,SAAO;AACT;;;ACPO,SAAS,eACd,SAC+C;AAC/C,SAAO;AACT;;;ACfO,SAAS,sBACd,SACmD;AACnD,SAAO;AACT;;;ACJO,SAAS,oBACd,SACyD;AACzD,SAAO;AACT;;;ACJO,SAAS,oBACd,SAC6C;AAC7C,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/pipeline/define-validator.ts","../src/pipeline/define-deployer.ts","../src/pipeline/define-rollback-handler.ts","../src/pipeline/define-health-checker.ts","../src/pipeline/define-drift-detector.ts"],"sourcesContent":["import type { PipelineContext, ValidationResult } from '../types/pipeline'\n\n/**\n * Define a validation handler for a configuration type.\n *\n * @example\n * ```ts\n * import { defineValidator } from '@veltrixsecops/app-sdk/pipeline'\n *\n * export default defineValidator(async (ctx) => {\n *   const errors = []\n *   const name = ctx.canvas.sections[0]?.fields['name']\n *   if (!name) {\n *     errors.push({ field: 'name', message: 'Name is required', code: 'REQUIRED' })\n *   }\n *   return { valid: errors.length === 0, errors, warnings: [] }\n * })\n * ```\n */\nexport function defineValidator(\n  handler: (ctx: PipelineContext) => Promise<ValidationResult>,\n): (ctx: PipelineContext) => Promise<ValidationResult> {\n  return handler\n}\n","import type { DeployContext, DeployResult } from '../types/pipeline'\n\n/**\n * Define a deploy handler for a configuration type.\n *\n * @example\n * ```ts\n * import { defineDeployer } from '@veltrixsecops/app-sdk/pipeline'\n *\n * export default defineDeployer(async (ctx) => {\n *   const { component, credential, connectivity, canvas } = ctx\n *   // Push configuration to the tool\n *   return { success: true, message: 'Deployed', rollbackData: previousState }\n * })\n * ```\n */\nexport function defineDeployer(\n  handler: (ctx: DeployContext) => Promise<DeployResult>,\n): (ctx: DeployContext) => Promise<DeployResult> {\n  return handler\n}\n","import type { RollbackContext, RollbackResult } from '../types/pipeline'\n\n/**\n * Define a rollback handler for a configuration type.\n */\nexport function defineRollbackHandler(\n  handler: (ctx: RollbackContext) => Promise<RollbackResult>,\n): (ctx: RollbackContext) => Promise<RollbackResult> {\n  return handler\n}\n","import type { HealthCheckContext, HealthCheckResult } from '../types/pipeline'\n\n/**\n * Define a health check handler for a configuration type.\n */\nexport function defineHealthChecker(\n  handler: (ctx: HealthCheckContext) => Promise<HealthCheckResult>,\n): (ctx: HealthCheckContext) => Promise<HealthCheckResult> {\n  return handler\n}\n","import type { DriftContext, DriftResult } from '../types/pipeline'\n\n/**\n * Define a drift detection handler for a configuration type.\n */\nexport function defineDriftDetector(\n  handler: (ctx: DriftContext) => Promise<DriftResult>,\n): (ctx: DriftContext) => Promise<DriftResult> {\n  return handler\n}\n"],"mappings":";AAmBO,SAAS,gBACd,SACqD;AACrD,SAAO;AACT;;;ACPO,SAAS,eACd,SAC+C;AAC/C,SAAO;AACT;;;ACfO,SAAS,sBACd,SACmD;AACnD,SAAO;AACT;;;ACJO,SAAS,oBACd,SACyD;AACzD,SAAO;AACT;;;ACJO,SAAS,oBACd,SAC6C;AAC7C,SAAO;AACT;","names":[]}

package/dist/client/index.cjs

@@ -0,0 +1,55 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client/index.ts
+var client_exports = {};
+__export(client_exports, {
+  HOST_RUNTIME_GLOBAL: () => HOST_RUNTIME_GLOBAL,
+  authFetch: () => authFetch,
+  getHostRuntime: () => getHostRuntime,
+  requireHostRuntime: () => requireHostRuntime
+});
+module.exports = __toCommonJS(client_exports);
+var HOST_RUNTIME_GLOBAL = "__VELTRIX_APP_RUNTIME__";
+function getHostRuntime() {
+  const runtime = globalThis[HOST_RUNTIME_GLOBAL];
+  return runtime ?? null;
+}
+function requireHostRuntime() {
+  const runtime = getHostRuntime();
+  if (!runtime) {
+    throw new Error(
+      `Veltrix host runtime not found \u2014 app client bundles only run inside the Veltrix platform (missing globalThis.${HOST_RUNTIME_GLOBAL})`
+    );
+  }
+  return runtime;
+}
+function authFetch(input, init) {
+  const runtime = getHostRuntime();
+  if (runtime) return runtime.authFetch(input, init);
+  return fetch(input, init);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HOST_RUNTIME_GLOBAL,
+  authFetch,
+  getHostRuntime,
+  requireHostRuntime
+});
+//# sourceMappingURL=index.cjs.map

package/dist/client/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/index.ts"],"sourcesContent":["// ========================================================================\n// Client runtime contract — how app client bundles talk to the host.\n//\n// App client code is packaged as a hermetic ESM bundle in which `react`,\n// `react-dom`, `react/jsx-runtime`, and every `@veltrixsecops/app-sdk`\n// subpath are compile-time shims that read the host-provided runtime from\n// `globalThis.__VELTRIX_APP_RUNTIME__`. The platform installs that global\n// (with ITS React instance, the shared AppContext, and an authenticated\n// fetch) before dynamically importing any app bundle, so app components\n// render inside the host React tree with working hooks and context.\n//\n// App authors: import from '@veltrixsecops/app-sdk/client' (and /hooks) —\n// never bundle your own copy of react. Use `authFetch` for calls to your\n// app's server routes (/api/apps/<app-id>/...): plain fetch() lacks the\n// platform's Authorization header and will receive 401s.\n// ========================================================================\n\nimport type { ComponentType, Context, LazyExoticComponent } from 'react'\nimport type { AppContextValue } from '../hooks/use-app-context'\n\nexport type { AppBrandingDeclaration } from '../types/manifest'\n\n/** Name of the global the platform installs before loading app bundles. */\nexport const HOST_RUNTIME_GLOBAL = '__VELTRIX_APP_RUNTIME__'\n\n/**\n * The runtime surface the platform exposes to app client bundles.\n * The react/reactDom/jsxRuntime members are the host's own module objects —\n * app bundles are compiled with shims that re-export them, guaranteeing a\n * single React instance per page.\n */\nexport interface VeltrixHostRuntime {\n  /** The host's `react` module object. */\n  react: unknown\n  /** The host's `react-dom` module object. */\n  reactDom: unknown\n  /** The host's `react-dom/client` module object. */\n  reactDomClient?: unknown\n  /** The host's `react/jsx-runtime` module object. */\n  jsxRuntime: unknown\n  /** Shared app context — the host wraps app pages in its Provider. */\n  AppContext: Context<AppContextValue | null>\n  /** fetch() with the platform's Authorization header attached. */\n  authFetch: (input: string, init?: RequestInit) => Promise<Response>\n  /**\n   * The SDK surface app bundles receive for `@veltrixsecops/app-sdk`,\n   * `.../hooks`, and `.../client` imports (useAppContext, AppContext,\n   * usePipelineStatus, authFetch, getHostRuntime, ...).\n   */\n  sdk: Record<string, unknown>\n}\n\n/** Read the host runtime, or null outside the platform (tests, storybook). */\nexport function getHostRuntime(): VeltrixHostRuntime | null {\n  const runtime = (globalThis as Record<string, unknown>)[HOST_RUNTIME_GLOBAL]\n  return (runtime as VeltrixHostRuntime) ?? null\n}\n\n/** Read the host runtime, throwing a diagnosable error when absent. */\nexport function requireHostRuntime(): VeltrixHostRuntime {\n  const runtime = getHostRuntime()\n  if (!runtime) {\n    throw new Error(\n      'Veltrix host runtime not found — app client bundles only run inside the ' +\n        `Veltrix platform (missing globalThis.${HOST_RUNTIME_GLOBAL})`,\n    )\n  }\n  return runtime\n}\n\n/**\n * fetch() that carries the platform's Authorization header. Required for an\n * app page to call its own server routes (/api/apps/<app-id>/...), which are\n * bearer-token protected. Falls back to plain fetch outside the platform.\n */\nexport function authFetch(input: string, init?: RequestInit): Promise<Response> {\n  const runtime = getHostRuntime()\n  if (runtime) return runtime.authFetch(input, init)\n  return fetch(input, init)\n}\n\n/** A sidebar entry contributed by the app's client entry module. */\nexport interface AppSidebarItem {\n  path: string\n  label: string\n  icon?: string\n}\n\n/**\n * Shape of the default export of an app's `client/index.tsx`.\n * `pages` keys must match `manifest.client.pages[].component`.\n */\nexport interface AppClientModule {\n  id: string\n  pages: Record<string, ComponentType | LazyExoticComponent<ComponentType>>\n  sidebarItems?: AppSidebarItem[]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAuBO,IAAM,sBAAsB;AA8B5B,SAAS,iBAA4C;AAC1D,QAAM,UAAW,WAAuC,mBAAmB;AAC3E,SAAQ,WAAkC;AAC5C;AAGO,SAAS,qBAAyC;AACvD,QAAM,UAAU,eAAe;AAC/B,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI;AAAA,MACR,qHAC0C,mBAAmB;AAAA,IAC/D;AAAA,EACF;AACA,SAAO;AACT;AAOO,SAAS,UAAU,OAAe,MAAuC;AAC9E,QAAM,UAAU,eAAe;AAC/B,MAAI,QAAS,QAAO,QAAQ,UAAU,OAAO,IAAI;AACjD,SAAO,MAAM,OAAO,IAAI;AAC1B;","names":[]}

package/dist/client/index.d.cts

@@ -0,0 +1,59 @@
+import { ComponentType, LazyExoticComponent, Context } from 'react';
+import { A as AppContextValue } from '../use-app-context-DdrtEPeb.cjs';
+export { a as AppBrandingDeclaration } from '../use-app-context-DdrtEPeb.cjs';
+
+/** Name of the global the platform installs before loading app bundles. */
+declare const HOST_RUNTIME_GLOBAL = "__VELTRIX_APP_RUNTIME__";
+/**
+ * The runtime surface the platform exposes to app client bundles.
+ * The react/reactDom/jsxRuntime members are the host's own module objects —
+ * app bundles are compiled with shims that re-export them, guaranteeing a
+ * single React instance per page.
+ */
+interface VeltrixHostRuntime {
+    /** The host's `react` module object. */
+    react: unknown;
+    /** The host's `react-dom` module object. */
+    reactDom: unknown;
+    /** The host's `react-dom/client` module object. */
+    reactDomClient?: unknown;
+    /** The host's `react/jsx-runtime` module object. */
+    jsxRuntime: unknown;
+    /** Shared app context — the host wraps app pages in its Provider. */
+    AppContext: Context<AppContextValue | null>;
+    /** fetch() with the platform's Authorization header attached. */
+    authFetch: (input: string, init?: RequestInit) => Promise<Response>;
+    /**
+     * The SDK surface app bundles receive for `@veltrixsecops/app-sdk`,
+     * `.../hooks`, and `.../client` imports (useAppContext, AppContext,
+     * usePipelineStatus, authFetch, getHostRuntime, ...).
+     */
+    sdk: Record<string, unknown>;
+}
+/** Read the host runtime, or null outside the platform (tests, storybook). */
+declare function getHostRuntime(): VeltrixHostRuntime | null;
+/** Read the host runtime, throwing a diagnosable error when absent. */
+declare function requireHostRuntime(): VeltrixHostRuntime;
+/**
+ * fetch() that carries the platform's Authorization header. Required for an
+ * app page to call its own server routes (/api/apps/<app-id>/...), which are
+ * bearer-token protected. Falls back to plain fetch outside the platform.
+ */
+declare function authFetch(input: string, init?: RequestInit): Promise<Response>;
+/** A sidebar entry contributed by the app's client entry module. */
+interface AppSidebarItem {
+    path: string;
+    label: string;
+    icon?: string;
+}
+/**
+ * Shape of the default export of an app's `client/index.tsx`.
+ * `pages` keys must match `manifest.client.pages[].component`.
+ */
+interface AppClientModule {
+    id: string;
+    pages: Record<string, ComponentType | LazyExoticComponent<ComponentType>>;
+    sidebarItems?: AppSidebarItem[];
+}
+
+export { type AppClientModule, type AppSidebarItem, HOST_RUNTIME_GLOBAL, type VeltrixHostRuntime, authFetch, getHostRuntime, requireHostRuntime };

package/dist/client/index.d.ts

@@ -0,0 +1,59 @@
+import { ComponentType, LazyExoticComponent, Context } from 'react';
+import { A as AppContextValue } from '../use-app-context-DdrtEPeb.js';
+export { a as AppBrandingDeclaration } from '../use-app-context-DdrtEPeb.js';
+
+/** Name of the global the platform installs before loading app bundles. */
+declare const HOST_RUNTIME_GLOBAL = "__VELTRIX_APP_RUNTIME__";
+/**
+ * The runtime surface the platform exposes to app client bundles.
+ * The react/reactDom/jsxRuntime members are the host's own module objects —
+ * app bundles are compiled with shims that re-export them, guaranteeing a
+ * single React instance per page.
+ */
+interface VeltrixHostRuntime {
+    /** The host's `react` module object. */
+    react: unknown;
+    /** The host's `react-dom` module object. */
+    reactDom: unknown;
+    /** The host's `react-dom/client` module object. */
+    reactDomClient?: unknown;
+    /** The host's `react/jsx-runtime` module object. */
+    jsxRuntime: unknown;
+    /** Shared app context — the host wraps app pages in its Provider. */
+    AppContext: Context<AppContextValue | null>;
+    /** fetch() with the platform's Authorization header attached. */
+    authFetch: (input: string, init?: RequestInit) => Promise<Response>;
+    /**
+     * The SDK surface app bundles receive for `@veltrixsecops/app-sdk`,
+     * `.../hooks`, and `.../client` imports (useAppContext, AppContext,
+     * usePipelineStatus, authFetch, getHostRuntime, ...).
+     */
+    sdk: Record<string, unknown>;
+}
+/** Read the host runtime, or null outside the platform (tests, storybook). */
+declare function getHostRuntime(): VeltrixHostRuntime | null;
+/** Read the host runtime, throwing a diagnosable error when absent. */
+declare function requireHostRuntime(): VeltrixHostRuntime;
+/**
+ * fetch() that carries the platform's Authorization header. Required for an
+ * app page to call its own server routes (/api/apps/<app-id>/...), which are
+ * bearer-token protected. Falls back to plain fetch outside the platform.
+ */
+declare function authFetch(input: string, init?: RequestInit): Promise<Response>;
+/** A sidebar entry contributed by the app's client entry module. */
+interface AppSidebarItem {
+    path: string;
+    label: string;
+    icon?: string;
+}
+/**
+ * Shape of the default export of an app's `client/index.tsx`.
+ * `pages` keys must match `manifest.client.pages[].component`.
+ */
+interface AppClientModule {
+    id: string;
+    pages: Record<string, ComponentType | LazyExoticComponent<ComponentType>>;
+    sidebarItems?: AppSidebarItem[];
+}
+
+export { type AppClientModule, type AppSidebarItem, HOST_RUNTIME_GLOBAL, type VeltrixHostRuntime, authFetch, getHostRuntime, requireHostRuntime };

package/dist/client/index.js

@@ -0,0 +1,13 @@
+import {
+  HOST_RUNTIME_GLOBAL,
+  authFetch,
+  getHostRuntime,
+  requireHostRuntime
+} from "../chunk-PJN3ATPH.js";
+export {
+  HOST_RUNTIME_GLOBAL,
+  authFetch,
+  getHostRuntime,
+  requireHostRuntime
+};
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/hooks/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var hooks_exports = {};
 __export(hooks_exports, {
   AppContext: () => AppContext,
+  useAppBranding: () => useAppBranding,
   useAppContext: () => useAppContext,
   usePipelineStatus: () => usePipelineStatus
 });
@@ -28,7 +29,8 @@ module.exports = __toCommonJS(hooks_exports);
 
 // src/hooks/use-app-context.ts
 var import_react = require("react");
-var AppContext = (0, import_react.createContext)(null);
+var hostContext = globalThis.__VELTRIX_APP_RUNTIME__?.AppContext;
+var AppContext = hostContext ?? (0, import_react.createContext)(null);
 function useAppContext() {
   const ctx = (0, import_react.useContext)(AppContext);
   if (!ctx) {
@@ -39,6 +41,20 @@ function useAppContext() {
 
 // src/hooks/use-pipeline-status.ts
 var import_react2 = require("react");
+
+// src/client/index.ts
+var HOST_RUNTIME_GLOBAL = "__VELTRIX_APP_RUNTIME__";
+function getHostRuntime() {
+  const runtime = globalThis[HOST_RUNTIME_GLOBAL];
+  return runtime ?? null;
+}
+function authFetch(input, init) {
+  const runtime = getHostRuntime();
+  if (runtime) return runtime.authFetch(input, init);
+  return fetch(input, init);
+}
+
+// src/hooks/use-pipeline-status.ts
 function usePipelineStatus(appId) {
   const [data, setData] = (0, import_react2.useState)(null);
   const [isLoading, setIsLoading] = (0, import_react2.useState)(true);
@@ -46,7 +62,7 @@ function usePipelineStatus(appId) {
   const refresh = (0, import_react2.useCallback)(async () => {
     try {
       setIsLoading(true);
-      const response = await fetch(`/api/pipeline/summary?appId=${appId}`);
+      const response = await authFetch(`/api/pipeline/summary?appId=${appId}`);
       if (!response.ok) throw new Error(`Failed to fetch pipeline status`);
       const result = await response.json();
       setData(result);
@@ -62,9 +78,15 @@ function usePipelineStatus(appId) {
   }, [refresh]);
   return { data, isLoading, error, refresh };
 }
+
+// src/hooks/use-app-branding.ts
+function useAppBranding() {
+  return useAppContext().branding ?? null;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AppContext,
+  useAppBranding,
   useAppContext,
   usePipelineStatus
 });

package/dist/hooks/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/hooks/index.ts","../../src/hooks/use-app-context.ts","../../src/hooks/use-pipeline-status.ts"],"sourcesContent":["export { useAppContext, AppContext, type AppContextValue } from './use-app-context'\r\nexport { usePipelineStatus, type PipelineStatusData } from './use-pipeline-status'\r\n","// ========================================================================\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":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACKA,mBAA0C;AAkBnC,IAAM,iBAAa,4BAAsC,IAAI;AAe7D,SAAS,gBAAiC;AAC/C,QAAM,UAAM,yBAAW,UAAU;AACjC,MAAI,CAAC,KAAK;AACR,UAAM,IAAI,MAAM,yDAAyD;AAAA,EAC3E;AACA,SAAO;AACT;;;AC5CA,IAAAA,gBAAiD;AA+B1C,SAAS,kBAAkB,OAAe;AAC/C,QAAM,CAAC,MAAM,OAAO,QAAI,wBAAoC,IAAI;AAChE,QAAM,CAAC,WAAW,YAAY,QAAI,wBAAS,IAAI;AAC/C,QAAM,CAAC,OAAO,QAAQ,QAAI,wBAAuB,IAAI;AAErD,QAAM,cAAU,2BAAY,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,+BAAU,MAAM;AACd,YAAQ;AAAA,EACV,GAAG,CAAC,OAAO,CAAC;AAEZ,SAAO,EAAE,MAAM,WAAW,OAAO,QAAQ;AAC3C;","names":["import_react"]}
+{"version":3,"sources":["../../src/hooks/index.ts","../../src/hooks/use-app-context.ts","../../src/hooks/use-pipeline-status.ts","../../src/client/index.ts","../../src/hooks/use-app-branding.ts"],"sourcesContent":["export { useAppContext, AppContext, type AppContextValue } from './use-app-context'\nexport { usePipelineStatus, type PipelineStatusData } from './use-pipeline-status'\nexport { useAppBranding } from './use-app-branding'\n","// ========================================================================\n// React hooks for app developers\n// These provide access to platform data and pipeline state\n// ========================================================================\n\nimport { createContext, useContext, type Context } from 'react'\nimport type { Component, Credential, Tag, User, Customer } from '../types/platform'\nimport type { AppBrandingDeclaration } from '../types/manifest'\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  /** The app's manifest branding, resolved by the platform (null when unset). */\n  branding?: AppBrandingDeclaration | null\n}\n\n// Anchor the context on the host runtime when running inside the platform,\n// so a bundle that inlined its own SDK copy still shares the host's context\n// (two createContext objects never match, even with identical shapes).\nconst hostContext = (\n  (globalThis as Record<string, unknown>).__VELTRIX_APP_RUNTIME__ as\n    | { AppContext?: Context<AppContextValue | null> }\n    | undefined\n)?.AppContext\n\nexport const AppContext: Context<AppContextValue | null> =\n  hostContext ?? 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'\nimport { authFetch } from '../client'\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      // Platform APIs are bearer-token protected — plain fetch would 401\n      const response = await authFetch(`/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","// ========================================================================\n// Client runtime contract — how app client bundles talk to the host.\n//\n// App client code is packaged as a hermetic ESM bundle in which `react`,\n// `react-dom`, `react/jsx-runtime`, and every `@veltrixsecops/app-sdk`\n// subpath are compile-time shims that read the host-provided runtime from\n// `globalThis.__VELTRIX_APP_RUNTIME__`. The platform installs that global\n// (with ITS React instance, the shared AppContext, and an authenticated\n// fetch) before dynamically importing any app bundle, so app components\n// render inside the host React tree with working hooks and context.\n//\n// App authors: import from '@veltrixsecops/app-sdk/client' (and /hooks) —\n// never bundle your own copy of react. Use `authFetch` for calls to your\n// app's server routes (/api/apps/<app-id>/...): plain fetch() lacks the\n// platform's Authorization header and will receive 401s.\n// ========================================================================\n\nimport type { ComponentType, Context, LazyExoticComponent } from 'react'\nimport type { AppContextValue } from '../hooks/use-app-context'\n\nexport type { AppBrandingDeclaration } from '../types/manifest'\n\n/** Name of the global the platform installs before loading app bundles. */\nexport const HOST_RUNTIME_GLOBAL = '__VELTRIX_APP_RUNTIME__'\n\n/**\n * The runtime surface the platform exposes to app client bundles.\n * The react/reactDom/jsxRuntime members are the host's own module objects —\n * app bundles are compiled with shims that re-export them, guaranteeing a\n * single React instance per page.\n */\nexport interface VeltrixHostRuntime {\n  /** The host's `react` module object. */\n  react: unknown\n  /** The host's `react-dom` module object. */\n  reactDom: unknown\n  /** The host's `react-dom/client` module object. */\n  reactDomClient?: unknown\n  /** The host's `react/jsx-runtime` module object. */\n  jsxRuntime: unknown\n  /** Shared app context — the host wraps app pages in its Provider. */\n  AppContext: Context<AppContextValue | null>\n  /** fetch() with the platform's Authorization header attached. */\n  authFetch: (input: string, init?: RequestInit) => Promise<Response>\n  /**\n   * The SDK surface app bundles receive for `@veltrixsecops/app-sdk`,\n   * `.../hooks`, and `.../client` imports (useAppContext, AppContext,\n   * usePipelineStatus, authFetch, getHostRuntime, ...).\n   */\n  sdk: Record<string, unknown>\n}\n\n/** Read the host runtime, or null outside the platform (tests, storybook). */\nexport function getHostRuntime(): VeltrixHostRuntime | null {\n  const runtime = (globalThis as Record<string, unknown>)[HOST_RUNTIME_GLOBAL]\n  return (runtime as VeltrixHostRuntime) ?? null\n}\n\n/** Read the host runtime, throwing a diagnosable error when absent. */\nexport function requireHostRuntime(): VeltrixHostRuntime {\n  const runtime = getHostRuntime()\n  if (!runtime) {\n    throw new Error(\n      'Veltrix host runtime not found — app client bundles only run inside the ' +\n        `Veltrix platform (missing globalThis.${HOST_RUNTIME_GLOBAL})`,\n    )\n  }\n  return runtime\n}\n\n/**\n * fetch() that carries the platform's Authorization header. Required for an\n * app page to call its own server routes (/api/apps/<app-id>/...), which are\n * bearer-token protected. Falls back to plain fetch outside the platform.\n */\nexport function authFetch(input: string, init?: RequestInit): Promise<Response> {\n  const runtime = getHostRuntime()\n  if (runtime) return runtime.authFetch(input, init)\n  return fetch(input, init)\n}\n\n/** A sidebar entry contributed by the app's client entry module. */\nexport interface AppSidebarItem {\n  path: string\n  label: string\n  icon?: string\n}\n\n/**\n * Shape of the default export of an app's `client/index.tsx`.\n * `pages` keys must match `manifest.client.pages[].component`.\n */\nexport interface AppClientModule {\n  id: string\n  pages: Record<string, ComponentType | LazyExoticComponent<ComponentType>>\n  sidebarItems?: AppSidebarItem[]\n}\n","import { useAppContext } from './use-app-context'\nimport type { AppBrandingDeclaration } from '../types/manifest'\n\n/**\n * The app's brand identity as declared in manifest.yaml `branding`.\n *\n * The platform already applies it in the defined slots (the app navbar and\n * the scoped CSS variables --veltrix-app-primary / --veltrix-app-accent on\n * the app page container). Use this hook only when a page needs the values\n * programmatically — prefer the CSS variables for styling:\n *\n * @example\n * ```tsx\n * <span style={{ color: 'var(--veltrix-app-primary)' }}>12 detections</span>\n * ```\n */\nexport function useAppBranding(): AppBrandingDeclaration | null {\n  return useAppContext().branding ?? null\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACKA,mBAAwD;AAyBxD,IAAM,cACH,WAAuC,yBAGvC;AAEI,IAAM,aACX,mBAAe,4BAAsC,IAAI;AAepD,SAAS,gBAAiC;AAC/C,QAAM,UAAM,yBAAW,UAAU;AACjC,MAAI,CAAC,KAAK;AACR,UAAM,IAAI,MAAM,yDAAyD;AAAA,EAC3E;AACA,SAAO;AACT;;;AC1DA,IAAAA,gBAAiD;;;ACuB1C,IAAM,sBAAsB;AA8B5B,SAAS,iBAA4C;AAC1D,QAAM,UAAW,WAAuC,mBAAmB;AAC3E,SAAQ,WAAkC;AAC5C;AAmBO,SAAS,UAAU,OAAe,MAAuC;AAC9E,QAAM,UAAU,eAAe;AAC/B,MAAI,QAAS,QAAO,QAAQ,UAAU,OAAO,IAAI;AACjD,SAAO,MAAM,OAAO,IAAI;AAC1B;;;AD/CO,SAAS,kBAAkB,OAAe;AAC/C,QAAM,CAAC,MAAM,OAAO,QAAI,wBAAoC,IAAI;AAChE,QAAM,CAAC,WAAW,YAAY,QAAI,wBAAS,IAAI;AAC/C,QAAM,CAAC,OAAO,QAAQ,QAAI,wBAAuB,IAAI;AAErD,QAAM,cAAU,2BAAY,YAAY;AACtC,QAAI;AACF,mBAAa,IAAI;AAEjB,YAAM,WAAW,MAAM,UAAU,+BAA+B,KAAK,EAAE;AACvE,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,+BAAU,MAAM;AACd,YAAQ;AAAA,EACV,GAAG,CAAC,OAAO,CAAC;AAEZ,SAAO,EAAE,MAAM,WAAW,OAAO,QAAQ;AAC3C;;;AE1CO,SAAS,iBAAgD;AAC9D,SAAO,cAAc,EAAE,YAAY;AACrC;","names":["import_react"]}

package/dist/hooks/index.d.cts

@@ -1,2 +1,55 @@
-export { a as AppContext, b as AppContextValue, P as PipelineStatusData, u as useAppContext, s as usePipelineStatus } from '../index-BI8f_mBw.cjs';
+import { a as AppBrandingDeclaration } from '../use-app-context-DdrtEPeb.cjs';
+export { e as AppContext, A as AppContextValue, x as useAppContext } from '../use-app-context-DdrtEPeb.cjs';
 import 'react';
+
+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>;
+};
+
+/**
+ * The app's brand identity as declared in manifest.yaml `branding`.
+ *
+ * The platform already applies it in the defined slots (the app navbar and
+ * the scoped CSS variables --veltrix-app-primary / --veltrix-app-accent on
+ * the app page container). Use this hook only when a page needs the values
+ * programmatically — prefer the CSS variables for styling:
+ *
+ * @example
+ * ```tsx
+ * <span style={{ color: 'var(--veltrix-app-primary)' }}>12 detections</span>
+ * ```
+ */
+declare function useAppBranding(): AppBrandingDeclaration | null;
+
+export { type PipelineStatusData, useAppBranding, usePipelineStatus };

package/dist/hooks/index.d.ts

@@ -1,2 +1,55 @@
-export { a as AppContext, b as AppContextValue, P as PipelineStatusData, u as useAppContext, s as usePipelineStatus } from '../index-BI8f_mBw.js';
+import { a as AppBrandingDeclaration } from '../use-app-context-DdrtEPeb.js';
+export { e as AppContext, A as AppContextValue, x as useAppContext } from '../use-app-context-DdrtEPeb.js';
 import 'react';
+
+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>;
+};
+
+/**
+ * The app's brand identity as declared in manifest.yaml `branding`.
+ *
+ * The platform already applies it in the defined slots (the app navbar and
+ * the scoped CSS variables --veltrix-app-primary / --veltrix-app-accent on
+ * the app page container). Use this hook only when a page needs the values
+ * programmatically — prefer the CSS variables for styling:
+ *
+ * @example
+ * ```tsx
+ * <span style={{ color: 'var(--veltrix-app-primary)' }}>12 detections</span>
+ * ```
+ */
+declare function useAppBranding(): AppBrandingDeclaration | null;
+
+export { type PipelineStatusData, useAppBranding, usePipelineStatus };

package/dist/hooks/index.js

@@ -1,10 +1,13 @@
 import {
   AppContext,
+  useAppBranding,
   useAppContext,
   usePipelineStatus
-} from "../chunk-TSEIWO6T.js";
+} from "../chunk-JOJTOQZQ.js";
+import "../chunk-PJN3ATPH.js";
 export {
   AppContext,
+  useAppBranding,
   useAppContext,
   usePipelineStatus
 };