@veltrixsecops/app-sdk 1.0.0

package/dist/index-BI8f_mBw.d.ts

@@ -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 };

package/dist/index-CKeIf4Jx.d.cts

@@ -0,0 +1,239 @@
+interface ValidationError {
+    field: string;
+    message: string;
+    code: string;
+}
+interface ValidationWarning {
+    field: string;
+    message: string;
+    code: string;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+interface DeployResult {
+    success: boolean;
+    message: string;
+    artifacts?: Record<string, unknown>;
+    rollbackData?: unknown;
+}
+interface RollbackResult {
+    success: boolean;
+    message: string;
+}
+interface HealthCheck {
+    name: string;
+    passed: boolean;
+    message: string;
+    latencyMs?: number;
+}
+interface HealthCheckResult {
+    healthy: boolean;
+    score: number;
+    checks: HealthCheck[];
+}
+interface DriftDiff {
+    field: string;
+    expected: unknown;
+    actual: unknown;
+    severity: 'info' | 'warning' | 'critical';
+}
+interface DriftResult {
+    hasDrift: boolean;
+    diffs: DriftDiff[];
+}
+interface ComponentConfigStatus {
+    componentId: string;
+    hostname: string;
+    deployed: boolean;
+    version?: string;
+    lastDeployedAt?: string;
+    healthy?: boolean;
+    healthScore?: number;
+}
+interface ConfigStatus {
+    deployed: boolean;
+    version: string;
+    lastDeployedAt: string;
+    componentStatuses: ComponentConfigStatus[];
+}
+interface CanvasSectionSnapshot {
+    name: string;
+    fields: Record<string, unknown>;
+}
+interface CanvasSnapshot {
+    id: string;
+    canvasId: string;
+    version: number;
+    name: string;
+    toolType: string;
+    entityType: string;
+    sections: CanvasSectionSnapshot[];
+    snapshot: Record<string, unknown>;
+}
+type DeploymentStrategy = 'DIRECT' | 'CANARY' | 'BLUE_GREEN' | 'ROLLING';
+interface EnvironmentRef {
+    id: string;
+    name: string;
+}
+interface UserRef {
+    id: string;
+    email: string;
+    name: string | null;
+}
+interface ComponentRef {
+    id: string;
+    hostname: string;
+    port: string;
+    type: string[];
+    toolId: string;
+}
+interface CredentialRef {
+    id: string;
+    name: string;
+    username: string;
+    password: string;
+    apiToken: string | null;
+    certificate: string | null;
+}
+interface ConnectivityRef {
+    id: string;
+    status: string;
+    sshCommand: string | null;
+    httpsUrl: string | null;
+    tailscaleDeviceIP: string | null;
+}
+/** Provider-aware connectivity passed to handlers when a ConnectivityProvider is configured */
+interface ConnectivityProviderRef {
+    id: string;
+    providerType: string;
+    name: string;
+    status: string;
+    config: Record<string, unknown>;
+}
+/** Summary of a deployment record, returned by PlatformDataApi */
+interface DeploymentSummary {
+    id: string;
+    canvasId: string;
+    status: string;
+    healthScore: number | null;
+    startedAt: string;
+    completedAt: string | null;
+    environment: EnvironmentRef;
+}
+/**
+ * Tenant-scoped, read-only access to platform data, provided on every
+ * handler context as `ctx.platform`. Apps must use this instead of
+ * querying the platform database directly — it is the only supported
+ * way to read platform records from an app.
+ */
+interface PlatformDataApi {
+    /** Latest deployment for a canvas, optionally filtered by status (e.g. 'SUCCEEDED'). */
+    getLatestDeployment(canvasId: string, opts?: {
+        status?: string;
+    }): Promise<DeploymentSummary | null>;
+    /** Components for the current customer, optionally filtered by component types. */
+    listComponents(filter?: {
+        types?: string[];
+    }): Promise<ComponentRef[]>;
+}
+interface PipelineContext {
+    appId: string;
+    customerId: string;
+    configTypeId: string;
+    canvas: CanvasSnapshot;
+    environment: EnvironmentRef;
+    user: UserRef;
+    settings: Record<string, unknown>;
+    platform: PlatformDataApi;
+}
+interface DeployContext extends PipelineContext {
+    component: ComponentRef;
+    credential: CredentialRef | null;
+    connectivity: ConnectivityRef | null;
+    connectivityProvider: ConnectivityProviderRef | null;
+    previousConfig: CanvasSnapshot | null;
+    strategy: DeploymentStrategy;
+    canaryPercent?: number;
+}
+interface RollbackContext extends PipelineContext {
+    component: ComponentRef;
+    credential: CredentialRef | null;
+    connectivity: ConnectivityRef | null;
+    connectivityProvider: ConnectivityProviderRef | null;
+    rollbackData: unknown;
+    targetVersion: CanvasSnapshot;
+}
+interface HealthCheckContext extends PipelineContext {
+    component: ComponentRef;
+    credential: CredentialRef | null;
+    connectivity: ConnectivityRef | null;
+    connectivityProvider: ConnectivityProviderRef | null;
+}
+interface DriftContext extends PipelineContext {
+    component: ComponentRef;
+    credential: CredentialRef | null;
+    connectivity: ConnectivityRef | null;
+    connectivityProvider: ConnectivityProviderRef | null;
+    deployedConfig: CanvasSnapshot;
+}
+type ValidateHandler = (ctx: PipelineContext) => Promise<ValidationResult>;
+type DeployHandler = (ctx: DeployContext) => Promise<DeployResult>;
+type RollbackHandler = (ctx: RollbackContext) => Promise<RollbackResult>;
+type HealthCheckHandler = (ctx: HealthCheckContext) => Promise<HealthCheckResult>;
+type DriftDetectHandler = (ctx: DriftContext) => Promise<DriftResult>;
+type GetStatusHandler = (ctx: PipelineContext) => Promise<ConfigStatus>;
+
+/**
+ * Define a validation handler for a configuration type.
+ *
+ * @example
+ * ```ts
+ * import { defineValidator } from '@veltrixsecops/app-sdk/pipeline'
+ *
+ * export default defineValidator(async (ctx) => {
+ *   const errors = []
+ *   const name = ctx.canvas.sections[0]?.fields['name']
+ *   if (!name) {
+ *     errors.push({ field: 'name', message: 'Name is required', code: 'REQUIRED' })
+ *   }
+ *   return { valid: errors.length === 0, errors, warnings: [] }
+ * })
+ * ```
+ */
+declare function defineValidator(handler: (ctx: PipelineContext) => Promise<ValidationResult>): (ctx: PipelineContext) => Promise<ValidationResult>;
+
+/**
+ * Define a deploy handler for a configuration type.
+ *
+ * @example
+ * ```ts
+ * import { defineDeployer } from '@veltrixsecops/app-sdk/pipeline'
+ *
+ * export default defineDeployer(async (ctx) => {
+ *   const { component, credential, connectivity, canvas } = ctx
+ *   // Push configuration to the tool
+ *   return { success: true, message: 'Deployed', rollbackData: previousState }
+ * })
+ * ```
+ */
+declare function defineDeployer(handler: (ctx: DeployContext) => Promise<DeployResult>): (ctx: DeployContext) => Promise<DeployResult>;
+
+/**
+ * Define a rollback handler for a configuration type.
+ */
+declare function defineRollbackHandler(handler: (ctx: RollbackContext) => Promise<RollbackResult>): (ctx: RollbackContext) => Promise<RollbackResult>;
+
+/**
+ * Define a health check handler for a configuration type.
+ */
+declare function defineHealthChecker(handler: (ctx: HealthCheckContext) => Promise<HealthCheckResult>): (ctx: HealthCheckContext) => Promise<HealthCheckResult>;
+
+/**
+ * Define a drift detection handler for a configuration type.
+ */
+declare function defineDriftDetector(handler: (ctx: DriftContext) => Promise<DriftResult>): (ctx: DriftContext) => Promise<DriftResult>;
+
+export { defineHealthChecker as A, defineRollbackHandler as B, type CanvasSectionSnapshot as C, type DeployContext as D, type EnvironmentRef as E, defineValidator as F, type GetStatusHandler as G, type HealthCheck as H, type PipelineContext as P, type RollbackContext as R, type UserRef as U, type ValidateHandler as V, type CanvasSnapshot as a, type ComponentConfigStatus as b, type ComponentRef as c, type ConfigStatus as d, type ConnectivityProviderRef as e, type ConnectivityRef as f, type CredentialRef as g, type DeployHandler as h, type DeployResult as i, type DeploymentStrategy as j, type DeploymentSummary as k, type DriftContext as l, type DriftDetectHandler as m, type DriftDiff as n, type DriftResult as o, type HealthCheckContext as p, type HealthCheckHandler as q, type HealthCheckResult as r, type PlatformDataApi as s, type RollbackHandler as t, type RollbackResult as u, type ValidationError as v, type ValidationResult as w, type ValidationWarning as x, defineDeployer as y, defineDriftDetector as z };