@veltrixsecops/app-sdk 2.0.0 → 2.2.0

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types/manifest.ts","../src/structure.ts"],"sourcesContent":["// ========================================================================\n// App manifest types\n//\n// Self-contained copy of the platform's manifest contract so the SDK can\n// be published and consumed outside the platform monorepo. The platform\n// keeps its own copy in shared/types/app.ts — changes to the manifest\n// contract must be applied to both files.\n// ========================================================================\n\nexport type AppSource = 'BUILT_IN' | 'MARKETPLACE' | 'CUSTOM'\nexport type AppStatusType = 'AVAILABLE' | 'DEPRECATED' | 'REMOVED'\nexport type AppInstallationStatus =\n  | 'INSTALLING'\n  | 'INSTALLED'\n  | 'ENABLED'\n  | 'DISABLED'\n  | 'FAILED'\n  | 'UNINSTALLING'\n\n// --- Manifest Types (parsed from manifest.yaml) ---\n\nexport interface AppManifest {\n  id: string\n  name: string\n  version: string\n  vendor: string\n  description: string\n  category: string\n  license?: string\n  homepage?: string\n  icon?: string\n  logo?: string\n\n  platform: {\n    minVersion: string\n  }\n\n  permissions: {\n    platform: string[] // Platform permissions the app needs\n    app: AppPermissionDeclaration[] // Permissions the app exposes\n  }\n\n  database?: {\n    migrations: string\n    tablePrefix: string\n  }\n\n  pipeline: {\n    configurationTypes: AppConfigurationTypeManifest[]\n    pipelineEvents?: string[]\n  }\n\n  server: {\n    entry: string\n    routes?: {\n      prefix: string\n    }\n  }\n\n  client?: {\n    entry: string\n    pages?: AppPageDeclaration[]\n  }\n\n  /**\n   * Vendor brand identity, applied by the platform in defined slots only —\n   * the app navbar (logo, accent) and scoped CSS variables. The platform,\n   * not the app, decides where brand color appears, so one vendor's palette\n   * never overwhelms the product shell.\n   */\n  branding?: AppBrandingDeclaration\n\n  hooks?: {\n    onInstall?: string\n    onUninstall?: string\n    onEnable?: string\n    onDisable?: string\n    onUpgrade?: string\n  }\n\n  events?: string[] // Platform events this app subscribes to\n\n  settings?: AppSettingDeclaration[]\n}\n\n/**\n * App brand identity. The platform renders it in a per-app navbar above the\n * app's pages and exposes the colors to app pages as scoped CSS variables\n * (--veltrix-app-primary, --veltrix-app-accent).\n */\nexport interface AppBrandingDeclaration {\n  /** Brand accent color as #RGB or #RRGGBB hex (e.g. CrowdStrike red). */\n  primaryColor?: string\n  /** Optional secondary color as #RGB or #RRGGBB hex. */\n  accentColor?: string\n  /**\n   * Vendor logo shown in the app navbar. Repo-relative .svg (preferred) or\n   * .png, at most 128 KB; rendered at 28px height, so use a wide/landscape\n   * mark with transparent background.\n   */\n  logo?: string\n  /** Optional logo variant for dark backgrounds; same constraints as logo. */\n  logoDark?: string\n}\n\nexport interface AppConfigurationTypeManifest {\n  id: string\n  name: string\n  description?: string\n  canvasTemplate: string // Path to canvas template YAML\n  defaultConfig?: string // Path to default config YAML\n\n  handlers: {\n    validate: string\n    deploy: string\n    rollback: string\n    healthCheck: string\n    driftDetect?: string | null\n    getStatus: string\n  }\n\n  targets: {\n    componentTypes: string[]\n    requiresCredential: boolean\n    requiresConnectivity: boolean\n  }\n}\n\nexport interface AppPermissionDeclaration {\n  resource: string\n  actions: string[]\n  description?: string\n}\n\n// --- App UI & navigation contract ---\n//\n// The platform owns the chrome: breadcrumb, app header, navigation, permission\n// gating, error boundary and loading states are rendered identically for every\n// app. Apps own the page body and compose it from @veltrixsecops/ui.\n// Predictable shell, flexible body.\n\n/**\n * How the platform frames an app page.\n * - `standard`   — page header + padded content area (default; use for most pages)\n * - `full-bleed` — content area with no padding/toolbar (custom canvases, maps)\n * - `canvas`     — Configuration Canvas chrome (section rail + save/validate bar)\n */\nexport type AppPageLayout = 'standard' | 'full-bleed' | 'canvas'\nexport const APP_PAGE_LAYOUTS = ['standard', 'full-bleed', 'canvas'] as const\n\n/**\n * Where the page surfaces in navigation.\n * - `sidebar` — an entry beneath the app in the sidebar\n * - `tab`     — a tab within its `parent` page\n * - `hidden`  — routable but not linked (details/drill-down pages)\n */\nexport type AppPageNav = 'sidebar' | 'tab' | 'hidden'\nexport const APP_PAGE_NAV = ['sidebar', 'tab', 'hidden'] as const\n\n/** An app-scoped permission (declared in `permissions.app`) required to see a page. */\nexport interface AppPagePermission {\n  resource: string\n  action: string\n}\n\nexport interface AppPageDeclaration {\n  /** Route beneath the app, e.g. `/indexes` → `/apps/<app-id>/indexes` */\n  path: string\n  /** Exported component name from the app's client entry */\n  component: string\n  label: string\n  description?: string\n  /** Icon name from the platform icon set; falls back to the app icon */\n  icon?: string\n  /** @deprecated use `nav: 'sidebar' | 'hidden'` — kept for backward compatibility */\n  sidebar?: boolean\n  /** Navigation placement. Defaults to `sidebar` when `sidebar: true`, else `hidden`. */\n  nav?: AppPageNav\n  /** Parent page `path` — required for `nav: 'tab'`, optional nesting for sidebar entries */\n  parent?: string\n  /** Optional sidebar section label, for apps with many pages */\n  group?: string\n  /** Deterministic ordering within its group/parent (ascending; ties break on label) */\n  order?: number\n  /** Layout preset the platform renders around the page body */\n  layout?: AppPageLayout\n  /** Hide the page (and its nav entry) unless the user holds this app permission */\n  requiresPermission?: AppPagePermission\n}\n\nexport interface AppSettingDeclaration {\n  key: string\n  type: 'string' | 'number' | 'boolean' | 'select'\n  label: string\n  description?: string\n  default?: string | number | boolean\n  required?: boolean\n  options?: Array<{ label: string; value: string }>\n}\n\n// --- API Response Types ---\n\nexport interface AppListItem {\n  id: string\n  appId: string\n  name: string\n  version: string\n  vendor: string\n  description: string\n  category: string\n  icon?: string\n  logo?: string\n  source: AppSource\n  isDefault: boolean\n  status: AppStatusType\n  installed?: boolean\n  enabled?: boolean\n}\n\nexport interface AppDetail extends AppListItem {\n  license?: string\n  homepage?: string\n  repository?: string\n  configurationTypes: Array<{\n    id: string\n    name: string\n    description?: string\n    componentTypes: string[]\n  }>\n  permissions: AppPermissionDeclaration[]\n  settings: AppSettingDeclaration[]\n}\n\nexport interface AppInstallationDetail {\n  id: string\n  appId: string\n  customerId: string\n  version: string\n  enabled: boolean\n  installedBy: string\n  installedAt: string\n  settings: Record<string, unknown>\n  status: AppInstallationStatus\n  app: AppListItem\n}\n","// ========================================================================\n// Canonical app layout\n//\n// Every Veltrix app follows one predictable folder structure so apps are\n// easy to set up, review, and load. The `veltrix` CLI scaffolds it,\n// `veltrix validate` (and repo CI) warn on deviations, and the platform's\n// app engine resolves manifest references against it.\n// ========================================================================\n\n/** Canonical locations inside an app directory. */\nexport const APP_LAYOUT = {\n  /** The app contract. Always at the app root. */\n  manifest: 'manifest.yaml',\n  /**\n   * The unit of extension: config-types/<configTypeId>/ colocates everything\n   * for one configuration type — canvas.yaml, defaults.yaml, the six pipeline\n   * handlers (extensionless in the manifest), and __tests__/.\n   */\n  configTypesDir: 'config-types',\n  /** Canvas form schema filename inside a config-type folder. */\n  canvasFile: 'canvas.yaml',\n  /** Default field values filename inside a config-type folder. */\n  defaultsFile: 'defaults.yaml',\n  /** Lifecycle hooks (camelCase): hooks/onInstall, hooks/onUninstall, ... */\n  hooksDir: 'hooks',\n  /** Shared app code used by multiple handlers (API clients, parsers). */\n  libDir: 'lib',\n  /** SQL migrations (requires manifest `database.tablePrefix`). */\n  migrationsDir: 'migrations',\n  /** Fastify route module receiving (fastify, AppRouteContext). */\n  serverEntry: 'server/index',\n  /** Client entry registering pages/sidebar items (optional). */\n  clientEntry: 'client/index',\n  /** Icons and logos (optional). */\n  assetsDir: 'assets',\n  /** Tests live next to the code they cover: handlers/<id>/__tests__/ */\n  testsDirName: '__tests__',\n} as const\n\n/** The six pipeline handler names, in lifecycle order. */\nexport const HANDLER_NAMES = [\n  'validate',\n  'deploy',\n  'rollback',\n  'healthCheck',\n  'driftDetect',\n  'getStatus',\n] as const\n\nexport type HandlerName = (typeof HANDLER_NAMES)[number]\n\n/**\n * Conventional manifest paths for one configuration type — handy when\n * generating or checking a manifest programmatically.\n *\n * @example\n * conventionalPaths('indexes').handlers.deploy // 'config-types/indexes/deploy'\n */\nexport function conventionalPaths(configTypeId: string): {\n  canvasTemplate: string\n  defaultConfig: string\n  handlers: Record<HandlerName, string>\n} {\n  const base = `${APP_LAYOUT.configTypesDir}/${configTypeId}`\n  const handlers = {} as Record<HandlerName, string>\n  for (const name of HANDLER_NAMES) {\n    handlers[name] = `${base}/${name}`\n  }\n  return {\n    canvasTemplate: `${base}/${APP_LAYOUT.canvasFile}`,\n    defaultConfig: `${base}/${APP_LAYOUT.defaultsFile}`,\n    handlers,\n  }\n}\n"],"mappings":";;;;;;;;;AAoJO,IAAM,mBAAmB,CAAC,YAAY,cAAc,QAAQ;AAS5D,IAAM,eAAe,CAAC,WAAW,OAAO,QAAQ;;;ACnJhD,IAAM,aAAa;AAAA;AAAA,EAExB,UAAU;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMV,gBAAgB;AAAA;AAAA,EAEhB,YAAY;AAAA;AAAA,EAEZ,cAAc;AAAA;AAAA,EAEd,UAAU;AAAA;AAAA,EAEV,QAAQ;AAAA;AAAA,EAER,eAAe;AAAA;AAAA,EAEf,aAAa;AAAA;AAAA,EAEb,aAAa;AAAA;AAAA,EAEb,WAAW;AAAA;AAAA,EAEX,cAAc;AAChB;AAGO,IAAM,gBAAgB;AAAA,EAC3B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAWO,SAAS,kBAAkB,cAIhC;AACA,QAAM,OAAO,GAAG,WAAW,cAAc,IAAI,YAAY;AACzD,QAAM,WAAW,CAAC;AAClB,aAAW,QAAQ,eAAe;AAChC,aAAS,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI;AAAA,EAClC;AACA,SAAO;AAAA,IACL,gBAAgB,GAAG,IAAI,IAAI,WAAW,UAAU;AAAA,IAChD,eAAe,GAAG,IAAI,IAAI,WAAW,YAAY;AAAA,IACjD;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/types/manifest.ts","../src/structure.ts"],"sourcesContent":["// ========================================================================\n// App manifest types\n//\n// Self-contained copy of the platform's manifest contract so the SDK can\n// be published and consumed outside the platform monorepo. The platform\n// keeps its own copy in shared/types/app.ts — changes to the manifest\n// contract must be applied to both files.\n// ========================================================================\n\nexport type AppSource = 'BUILT_IN' | 'MARKETPLACE' | 'CUSTOM'\nexport type AppStatusType = 'AVAILABLE' | 'DEPRECATED' | 'REMOVED'\nexport type AppInstallationStatus =\n  | 'INSTALLING'\n  | 'INSTALLED'\n  | 'ENABLED'\n  | 'DISABLED'\n  | 'FAILED'\n  | 'UNINSTALLING'\n\n// --- Manifest Types (parsed from manifest.yaml) ---\n\nexport interface AppManifest {\n  id: string\n  name: string\n  version: string\n  vendor: string\n  description: string\n  category: string\n  license?: string\n  homepage?: string\n  icon?: string\n  logo?: string\n\n  platform: {\n    minVersion: string\n  }\n\n  permissions: {\n    platform: string[] // Platform permissions the app needs\n    app: AppPermissionDeclaration[] // Permissions the app exposes\n  }\n\n  database?: {\n    migrations: string\n    tablePrefix: string\n  }\n\n  pipeline: {\n    configurationTypes: AppConfigurationTypeManifest[]\n    pipelineEvents?: string[]\n  }\n\n  server: {\n    entry: string\n    routes?: {\n      prefix: string\n    }\n  }\n\n  client?: {\n    entry: string\n    pages?: AppPageDeclaration[]\n    /**\n     * How the platform lays out this app's navigation (its client pages and\n     * one entry per configuration type):\n     *   - 'tabs' (default): a horizontal tab strip — best for a few items.\n     *   - 'sidebar': an embedded left rail, grouped into Pages and\n     *     Configurations — scales to many configuration types without the\n     *     tab strip overflowing.\n     */\n    navLayout?: 'tabs' | 'sidebar'\n  }\n\n  /**\n   * Vendor brand identity, applied by the platform in defined slots only —\n   * the app navbar (logo, accent) and scoped CSS variables. The platform,\n   * not the app, decides where brand color appears, so one vendor's palette\n   * never overwhelms the product shell.\n   */\n  branding?: AppBrandingDeclaration\n\n  hooks?: {\n    onInstall?: string\n    onUninstall?: string\n    onEnable?: string\n    onDisable?: string\n    onUpgrade?: string\n  }\n\n  events?: string[] // Platform events this app subscribes to\n\n  settings?: AppSettingDeclaration[]\n}\n\n/**\n * App brand identity. The platform renders it in a per-app navbar above the\n * app's pages and exposes the colors to app pages as scoped CSS variables\n * (--veltrix-app-primary, --veltrix-app-accent).\n */\nexport interface AppBrandingDeclaration {\n  /** Brand accent color as #RGB or #RRGGBB hex (e.g. CrowdStrike red). */\n  primaryColor?: string\n  /** Optional secondary color as #RGB or #RRGGBB hex. */\n  accentColor?: string\n  /**\n   * Vendor logo shown in the app navbar. Repo-relative .svg (preferred) or\n   * .png, at most 128 KB; rendered at 28px height, so use a wide/landscape\n   * mark with transparent background.\n   */\n  logo?: string\n  /** Optional logo variant for dark backgrounds; same constraints as logo. */\n  logoDark?: string\n}\n\nexport interface AppConfigurationTypeManifest {\n  id: string\n  name: string\n  description?: string\n  canvasTemplate: string // Path to canvas template YAML\n  defaultConfig?: string // Path to default config YAML\n\n  handlers: {\n    validate: string\n    deploy: string\n    rollback: string\n    healthCheck: string\n    driftDetect?: string | null\n    getStatus: string\n  }\n\n  targets: {\n    componentTypes: string[]\n    requiresCredential: boolean\n    requiresConnectivity: boolean\n  }\n}\n\nexport interface AppPermissionDeclaration {\n  resource: string\n  actions: string[]\n  description?: string\n}\n\n// --- App UI & navigation contract ---\n//\n// The platform owns the chrome: breadcrumb, app header, navigation, permission\n// gating, error boundary and loading states are rendered identically for every\n// app. Apps own the page body and compose it from @veltrixsecops/ui.\n// Predictable shell, flexible body.\n\n/**\n * How the platform frames an app page.\n * - `standard`   — page header + padded content area (default; use for most pages)\n * - `full-bleed` — content area with no padding/toolbar (custom canvases, maps)\n * - `canvas`     — Configuration Canvas chrome (section rail + save/validate bar)\n */\nexport type AppPageLayout = 'standard' | 'full-bleed' | 'canvas'\nexport const APP_PAGE_LAYOUTS = ['standard', 'full-bleed', 'canvas'] as const\n\n/**\n * Where the page surfaces in navigation.\n * - `sidebar` — an entry beneath the app in the sidebar\n * - `tab`     — a tab within its `parent` page\n * - `hidden`  — routable but not linked (details/drill-down pages)\n */\nexport type AppPageNav = 'sidebar' | 'tab' | 'hidden'\nexport const APP_PAGE_NAV = ['sidebar', 'tab', 'hidden'] as const\n\n/** An app-scoped permission (declared in `permissions.app`) required to see a page. */\nexport interface AppPagePermission {\n  resource: string\n  action: string\n}\n\nexport interface AppPageDeclaration {\n  /** Route beneath the app, e.g. `/indexes` → `/apps/<app-id>/indexes` */\n  path: string\n  /** Exported component name from the app's client entry */\n  component: string\n  label: string\n  description?: string\n  /** Icon name from the platform icon set; falls back to the app icon */\n  icon?: string\n  /** @deprecated use `nav: 'sidebar' | 'hidden'` — kept for backward compatibility */\n  sidebar?: boolean\n  /** Navigation placement. Defaults to `sidebar` when `sidebar: true`, else `hidden`. */\n  nav?: AppPageNav\n  /** Parent page `path` — required for `nav: 'tab'`, optional nesting for sidebar entries */\n  parent?: string\n  /** Optional sidebar section label, for apps with many pages */\n  group?: string\n  /** Deterministic ordering within its group/parent (ascending; ties break on label) */\n  order?: number\n  /** Layout preset the platform renders around the page body */\n  layout?: AppPageLayout\n  /** Hide the page (and its nav entry) unless the user holds this app permission */\n  requiresPermission?: AppPagePermission\n}\n\nexport interface AppSettingDeclaration {\n  key: string\n  type: 'string' | 'number' | 'boolean' | 'select'\n  label: string\n  description?: string\n  default?: string | number | boolean\n  required?: boolean\n  options?: Array<{ label: string; value: string }>\n}\n\n// --- API Response Types ---\n\nexport interface AppListItem {\n  id: string\n  appId: string\n  name: string\n  version: string\n  vendor: string\n  description: string\n  category: string\n  icon?: string\n  logo?: string\n  source: AppSource\n  isDefault: boolean\n  status: AppStatusType\n  installed?: boolean\n  enabled?: boolean\n}\n\nexport interface AppDetail extends AppListItem {\n  license?: string\n  homepage?: string\n  repository?: string\n  configurationTypes: Array<{\n    id: string\n    name: string\n    description?: string\n    componentTypes: string[]\n  }>\n  permissions: AppPermissionDeclaration[]\n  settings: AppSettingDeclaration[]\n}\n\nexport interface AppInstallationDetail {\n  id: string\n  appId: string\n  customerId: string\n  version: string\n  enabled: boolean\n  installedBy: string\n  installedAt: string\n  settings: Record<string, unknown>\n  status: AppInstallationStatus\n  app: AppListItem\n}\n","// ========================================================================\n// Canonical app layout\n//\n// Every Veltrix app follows one predictable folder structure so apps are\n// easy to set up, review, and load. The `veltrix` CLI scaffolds it,\n// `veltrix validate` (and repo CI) warn on deviations, and the platform's\n// app engine resolves manifest references against it.\n// ========================================================================\n\n/** Canonical locations inside an app directory. */\nexport const APP_LAYOUT = {\n  /** The app contract. Always at the app root. */\n  manifest: 'manifest.yaml',\n  /**\n   * The unit of extension: config-types/<configTypeId>/ colocates everything\n   * for one configuration type — canvas.yaml, defaults.yaml, the six pipeline\n   * handlers (extensionless in the manifest), and __tests__/.\n   */\n  configTypesDir: 'config-types',\n  /** Canvas form schema filename inside a config-type folder. */\n  canvasFile: 'canvas.yaml',\n  /** Default field values filename inside a config-type folder. */\n  defaultsFile: 'defaults.yaml',\n  /** Lifecycle hooks (camelCase): hooks/onInstall, hooks/onUninstall, ... */\n  hooksDir: 'hooks',\n  /** Shared app code used by multiple handlers (API clients, parsers). */\n  libDir: 'lib',\n  /** SQL migrations (requires manifest `database.tablePrefix`). */\n  migrationsDir: 'migrations',\n  /** Fastify route module receiving (fastify, AppRouteContext). */\n  serverEntry: 'server/index',\n  /** Client entry registering pages/sidebar items (optional). */\n  clientEntry: 'client/index',\n  /** Icons and logos (optional). */\n  assetsDir: 'assets',\n  /** Tests live next to the code they cover: handlers/<id>/__tests__/ */\n  testsDirName: '__tests__',\n} as const\n\n/** The six pipeline handler names, in lifecycle order. */\nexport const HANDLER_NAMES = [\n  'validate',\n  'deploy',\n  'rollback',\n  'healthCheck',\n  'driftDetect',\n  'getStatus',\n] as const\n\nexport type HandlerName = (typeof HANDLER_NAMES)[number]\n\n/**\n * Conventional manifest paths for one configuration type — handy when\n * generating or checking a manifest programmatically.\n *\n * @example\n * conventionalPaths('indexes').handlers.deploy // 'config-types/indexes/deploy'\n */\nexport function conventionalPaths(configTypeId: string): {\n  canvasTemplate: string\n  defaultConfig: string\n  handlers: Record<HandlerName, string>\n} {\n  const base = `${APP_LAYOUT.configTypesDir}/${configTypeId}`\n  const handlers = {} as Record<HandlerName, string>\n  for (const name of HANDLER_NAMES) {\n    handlers[name] = `${base}/${name}`\n  }\n  return {\n    canvasTemplate: `${base}/${APP_LAYOUT.canvasFile}`,\n    defaultConfig: `${base}/${APP_LAYOUT.defaultsFile}`,\n    handlers,\n  }\n}\n"],"mappings":";;;;;;;;;AA6JO,IAAM,mBAAmB,CAAC,YAAY,cAAc,QAAQ;AAS5D,IAAM,eAAe,CAAC,WAAW,OAAO,QAAQ;;;AC5JhD,IAAM,aAAa;AAAA;AAAA,EAExB,UAAU;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMV,gBAAgB;AAAA;AAAA,EAEhB,YAAY;AAAA;AAAA,EAEZ,cAAc;AAAA;AAAA,EAEd,UAAU;AAAA;AAAA,EAEV,QAAQ;AAAA;AAAA,EAER,eAAe;AAAA;AAAA,EAEf,aAAa;AAAA;AAAA,EAEb,aAAa;AAAA;AAAA,EAEb,WAAW;AAAA;AAAA,EAEX,cAAc;AAChB;AAGO,IAAM,gBAAgB;AAAA,EAC3B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAWO,SAAS,kBAAkB,cAIhC;AACA,QAAM,OAAO,GAAG,WAAW,cAAc,IAAI,YAAY;AACzD,QAAM,WAAW,CAAC;AAClB,aAAW,QAAQ,eAAe;AAChC,aAAS,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI;AAAA,EAClC;AACA,SAAO;AAAA,IACL,gBAAgB,GAAG,IAAI,IAAI,WAAW,UAAU;AAAA,IAChD,eAAe,GAAG,IAAI,IAAI,WAAW,YAAY;AAAA,IACjD;AAAA,EACF;AACF;","names":[]}