@veltrixsecops/app-sdk 1.0.0

package/README.md

@@ -0,0 +1,92 @@
+# @veltrixsecops/app-sdk
+
+The official SDK for building [Veltrix](https://github.com/captivatortechnologies/Veltrix) Security-as-Code apps.
+
+A Veltrix app packages everything needed to manage one security tool's configuration as code: pipeline handlers (validate → deploy → rollback → health-check → drift-detect → status), canvas templates, database migrations, lifecycle hooks, and optional client pages. This SDK provides the typed contracts and helpers for all of it.
+
+## Installation
+
+```bash
+npm install --save-dev @veltrixsecops/app-sdk
+```
+
+The SDK is types-first: pipeline handlers typically only need `import type`, so it can be a dev dependency.
+
+## Writing pipeline handlers
+
+Every configuration type your app declares in `manifest.yaml` implements six handlers. Each receives a typed context built by the platform:
+
+```ts
+// handlers/indexes/validate.ts
+import type { PipelineContext, ValidationResult } from '@veltrixsecops/app-sdk'
+
+export default async function validate(ctx: PipelineContext): Promise<ValidationResult> {
+  const errors = []
+  for (const section of ctx.canvas.sections) {
+    if (!section.fields['name']) {
+      errors.push({ field: 'name', message: 'Name is required', code: 'required' })
+    }
+  }
+  return { valid: errors.length === 0, errors, warnings: [] }
+}
+```
+
+Or use the `define*` helpers for inference:
+
+```ts
+import { defineDeployer } from '@veltrixsecops/app-sdk/pipeline'
+
+export default defineDeployer(async (ctx) => {
+  // ctx.component, ctx.credential, ctx.connectivity, ctx.connectivityProvider
+  // ctx.previousConfig, ctx.strategy, ctx.canaryPercent
+  return { success: true, message: 'Deployed', rollbackData: {/* prior state */} }
+})
+```
+
+## Reading platform data
+
+Handlers must never query the platform database directly. Use the tenant-scoped
+data API on every context instead:
+
+```ts
+import type { PipelineContext, ConfigStatus } from '@veltrixsecops/app-sdk'
+
+export default async function getStatus(ctx: PipelineContext): Promise<ConfigStatus> {
+  const latest = await ctx.platform.getLatestDeployment(ctx.canvas.canvasId, { status: 'SUCCEEDED' })
+  const components = await ctx.platform.listComponents({ types: ['indexer'] })
+  // ...
+}
+```
+
+## Lifecycle hooks
+
+```ts
+// hooks/on-install.ts
+import type { AppHookContext } from '@veltrixsecops/app-sdk'
+
+export default async function onInstall({ db, appId }: AppHookContext): Promise<void> {
+  // Seed your app's own (prefixed) tables here.
+}
+```
+
+## Client pages
+
+```tsx
+import { useAppContext, usePipelineStatus } from '@veltrixsecops/app-sdk/hooks'
+```
+
+## Package layout
+
+| Entry point | Contents |
+|---|---|
+| `@veltrixsecops/app-sdk` | All types: handler contexts/results, manifest, platform refs, hook contexts |
+| `@veltrixsecops/app-sdk/pipeline` | `defineValidator`, `defineDeployer`, `defineRollbackHandler`, `defineHealthChecker`, `defineDriftDetector` |
+| `@veltrixsecops/app-sdk/hooks` | React hooks for app client pages (requires `react`) |
+
+## Building an app
+
+Start from the [`_template`](https://github.com/captivatortechnologies/Veltrix/tree/main/apps-and-tools/_template) app and see the contribution guide in `apps-and-tools/CONTRIBUTING.md`.
+
+## License
+
+MIT

package/dist/chunk-PJCHU6ZZ.js

@@ -0,0 +1,33 @@
+// src/pipeline/define-validator.ts
+function defineValidator(handler) {
+  return handler;
+}
+
+// src/pipeline/define-deployer.ts
+function defineDeployer(handler) {
+  return handler;
+}
+
+// src/pipeline/define-rollback-handler.ts
+function defineRollbackHandler(handler) {
+  return handler;
+}
+
+// src/pipeline/define-health-checker.ts
+function defineHealthChecker(handler) {
+  return handler;
+}
+
+// src/pipeline/define-drift-detector.ts
+function defineDriftDetector(handler) {
+  return handler;
+}
+
+export {
+  defineValidator,
+  defineDeployer,
+  defineRollbackHandler,
+  defineHealthChecker,
+  defineDriftDetector
+};
+//# sourceMappingURL=chunk-PJCHU6ZZ.js.map

package/dist/chunk-PJCHU6ZZ.js.map

@@ -0,0 +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":[]}

package/dist/chunk-TSEIWO6T.js

@@ -0,0 +1,43 @@
+// src/hooks/use-app-context.ts
+import { createContext, useContext } from "react";
+var AppContext = createContext(null);
+function useAppContext() {
+  const ctx = useContext(AppContext);
+  if (!ctx) {
+    throw new Error("useAppContext must be used within an AppContextProvider");
+  }
+  return ctx;
+}
+
+// src/hooks/use-pipeline-status.ts
+import { useState, useEffect, useCallback } from "react";
+function usePipelineStatus(appId) {
+  const [data, setData] = useState(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState(null);
+  const refresh = useCallback(async () => {
+    try {
+      setIsLoading(true);
+      const response = await fetch(`/api/pipeline/summary?appId=${appId}`);
+      if (!response.ok) throw new Error(`Failed to fetch pipeline status`);
+      const result = await response.json();
+      setData(result);
+      setError(null);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error("Unknown error"));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [appId]);
+  useEffect(() => {
+    refresh();
+  }, [refresh]);
+  return { data, isLoading, error, refresh };
+}
+
+export {
+  AppContext,
+  useAppContext,
+  usePipelineStatus
+};
+//# sourceMappingURL=chunk-TSEIWO6T.js.map

package/dist/chunk-TSEIWO6T.js.map

@@ -0,0 +1 @@
+{"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":[]}

package/dist/hooks/index.cjs

@@ -0,0 +1,71 @@
+"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/hooks/index.ts
+var hooks_exports = {};
+__export(hooks_exports, {
+  AppContext: () => AppContext,
+  useAppContext: () => useAppContext,
+  usePipelineStatus: () => usePipelineStatus
+});
+module.exports = __toCommonJS(hooks_exports);
+
+// src/hooks/use-app-context.ts
+var import_react = require("react");
+var AppContext = (0, import_react.createContext)(null);
+function useAppContext() {
+  const ctx = (0, import_react.useContext)(AppContext);
+  if (!ctx) {
+    throw new Error("useAppContext must be used within an AppContextProvider");
+  }
+  return ctx;
+}
+
+// src/hooks/use-pipeline-status.ts
+var import_react2 = require("react");
+function usePipelineStatus(appId) {
+  const [data, setData] = (0, import_react2.useState)(null);
+  const [isLoading, setIsLoading] = (0, import_react2.useState)(true);
+  const [error, setError] = (0, import_react2.useState)(null);
+  const refresh = (0, import_react2.useCallback)(async () => {
+    try {
+      setIsLoading(true);
+      const response = await fetch(`/api/pipeline/summary?appId=${appId}`);
+      if (!response.ok) throw new Error(`Failed to fetch pipeline status`);
+      const result = await response.json();
+      setData(result);
+      setError(null);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error("Unknown error"));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [appId]);
+  (0, import_react2.useEffect)(() => {
+    refresh();
+  }, [refresh]);
+  return { data, isLoading, error, refresh };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AppContext,
+  useAppContext,
+  usePipelineStatus
+});
+//# sourceMappingURL=index.cjs.map

package/dist/hooks/index.cjs.map

@@ -0,0 +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"]}

package/dist/hooks/index.d.cts

@@ -0,0 +1,2 @@
+export { a as AppContext, b as AppContextValue, P as PipelineStatusData, u as useAppContext, s as usePipelineStatus } from '../index-BI8f_mBw.cjs';
+import 'react';

package/dist/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { a as AppContext, b as AppContextValue, P as PipelineStatusData, u as useAppContext, s as usePipelineStatus } from '../index-BI8f_mBw.js';
+import 'react';

package/dist/hooks/index.js

@@ -0,0 +1,11 @@
+import {
+  AppContext,
+  useAppContext,
+  usePipelineStatus
+} from "../chunk-TSEIWO6T.js";
+export {
+  AppContext,
+  useAppContext,
+  usePipelineStatus
+};
+//# sourceMappingURL=index.js.map

package/dist/hooks/index.js.map

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

package/dist/index-BI8f_mBw.d.cts

@@ -0,0 +1,286 @@
+import * as react from 'react';
+
+type AppSource = 'BUILT_IN' | 'MARKETPLACE' | 'CUSTOM';
+type AppStatusType = 'AVAILABLE' | 'DEPRECATED' | 'REMOVED';
+type AppInstallationStatus = 'INSTALLING' | 'INSTALLED' | 'ENABLED' | 'DISABLED' | 'FAILED' | 'UNINSTALLING';
+interface AppManifest {
+    id: string;
+    name: string;
+    version: string;
+    vendor: string;
+    description: string;
+    category: string;
+    license?: string;
+    homepage?: string;
+    icon?: string;
+    logo?: string;
+    platform: {
+        minVersion: string;
+    };
+    permissions: {
+        platform: string[];
+        app: AppPermissionDeclaration[];
+    };
+    database?: {
+        migrations: string;
+        tablePrefix: string;
+    };
+    pipeline: {
+        configurationTypes: AppConfigurationTypeManifest[];
+        pipelineEvents?: string[];
+    };
+    server: {
+        entry: string;
+        routes?: {
+            prefix: string;
+        };
+    };
+    client?: {
+        entry: string;
+        pages?: AppPageDeclaration[];
+    };
+    hooks?: {
+        onInstall?: string;
+        onUninstall?: string;
+        onEnable?: string;
+        onDisable?: string;
+        onUpgrade?: string;
+    };
+    events?: string[];
+    settings?: AppSettingDeclaration[];
+}
+interface AppConfigurationTypeManifest {
+    id: string;
+    name: string;
+    description?: string;
+    canvasTemplate: string;
+    defaultConfig?: string;
+    handlers: {
+        validate: string;
+        deploy: string;
+        rollback: string;
+        healthCheck: string;
+        driftDetect?: string | null;
+        getStatus: string;
+    };
+    targets: {
+        componentTypes: string[];
+        requiresCredential: boolean;
+        requiresConnectivity: boolean;
+    };
+}
+interface AppPermissionDeclaration {
+    resource: string;
+    actions: string[];
+    description?: string;
+}
+interface AppPageDeclaration {
+    path: string;
+    component: string;
+    label: string;
+    icon?: string;
+    sidebar?: boolean;
+    parent?: string;
+}
+interface AppSettingDeclaration {
+    key: string;
+    type: 'string' | 'number' | 'boolean' | 'select';
+    label: string;
+    description?: string;
+    default?: string | number | boolean;
+    required?: boolean;
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+}
+interface AppListItem {
+    id: string;
+    appId: string;
+    name: string;
+    version: string;
+    vendor: string;
+    description: string;
+    category: string;
+    icon?: string;
+    logo?: string;
+    source: AppSource;
+    isDefault: boolean;
+    status: AppStatusType;
+    installed?: boolean;
+    enabled?: boolean;
+}
+interface AppDetail extends AppListItem {
+    license?: string;
+    homepage?: string;
+    repository?: string;
+    configurationTypes: Array<{
+        id: string;
+        name: string;
+        description?: string;
+        componentTypes: string[];
+    }>;
+    permissions: AppPermissionDeclaration[];
+    settings: AppSettingDeclaration[];
+}
+interface AppInstallationDetail {
+    id: string;
+    appId: string;
+    customerId: string;
+    version: string;
+    enabled: boolean;
+    installedBy: string;
+    installedAt: string;
+    settings: Record<string, unknown>;
+    status: AppInstallationStatus;
+    app: AppListItem;
+}
+
+interface Component {
+    id: string;
+    hostname: string;
+    port: string;
+    type: string[];
+    toolId: string;
+    customerId: string;
+}
+interface Credential {
+    id: string;
+    name: string;
+    username: string;
+    password: string;
+    apiToken: string | null;
+    certificate: string | null;
+    toolId: string;
+    customerId: string;
+}
+interface Connectivity {
+    id: string;
+    componentId: string;
+    status: string;
+    sshCommand: string | null;
+    httpsUrl: string | null;
+    tailscaleDeviceIP: string | null;
+}
+interface Tag {
+    id: string;
+    name: string;
+    customerId: string;
+}
+interface User {
+    id: string;
+    email: string;
+    name: string | null;
+    customerId: string;
+    roleId: string;
+}
+interface Customer {
+    id: string;
+    name: string;
+    domain: string | null;
+    isActive: boolean;
+}
+/**
+ * Loosely-typed handle to the platform database, passed to lifecycle hooks.
+ * At runtime this is the platform's Prisma client; model delegates are
+ * accessed by name (e.g. `db.splunkVersion.upsert(...)` for an app table).
+ * Apps should only touch their own prefixed tables and the raw-query
+ * escape hatches — anything else is unsupported and may break between
+ * platform versions.
+ */
+interface PlatformDatabaseClient {
+    $queryRawUnsafe<T = unknown>(query: string, ...values: unknown[]): Promise<T>;
+    $executeRawUnsafe(query: string, ...values: unknown[]): Promise<number>;
+    [modelDelegate: string]: any;
+}
+/**
+ * Context passed to app lifecycle hooks
+ * (onInstall / onUninstall / onEnable / onDisable / onUpgrade).
+ * `customerId` is present only for customer-scoped hooks (onEnable/onDisable).
+ */
+interface AppHookContext {
+    db: PlatformDatabaseClient;
+    appId: string;
+    customerId?: string;
+}
+/**
+ * Context passed to an app's server route module (the `server.entry`
+ * declared in manifest.yaml). The platform mounts the module as a Fastify
+ * plugin under `/api/apps/<appId>` with auth + app-enabled checks applied;
+ * `hasPermission` returns a preHandler enforcing an app-scoped permission.
+ */
+interface AppRouteContext {
+    appId: string;
+    appDir: string;
+    manifest: AppManifest;
+    db: PlatformDatabaseClient;
+    /**
+     * Returns a Fastify preHandler enforcing an app-scoped permission.
+     * Typed `any` so the SDK does not depend on Fastify's hook types —
+     * pass it straight into a route's `preHandler` array.
+     */
+    hasPermission: (resource: string, action: string) => any;
+}
+
+interface AppContextValue {
+    appId: string;
+    customerId: string;
+    user: User | null;
+    customer: Customer | null;
+    getComponents: () => Promise<Component[]>;
+    getCredentials: () => Promise<Credential[]>;
+    getTags: () => Promise<Tag[]>;
+    settings: Record<string, unknown>;
+}
+declare const AppContext: react.Context<AppContextValue | null>;
+/**
+ * Access the app context in any app component.
+ *
+ * @example
+ * ```tsx
+ * import { useAppContext } from '@veltrixsecops/app-sdk/hooks'
+ *
+ * function MyComponent() {
+ *   const { appId, settings, getComponents } = useAppContext()
+ *   // ...
+ * }
+ * ```
+ */
+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 };