@veltrixsecops/app-sdk 3.1.0 → 3.5.0

package/dist/client/index.d.ts

@@ -1,7 +1,7 @@
 import { ComponentType, LazyExoticComponent, Context } from 'react';
-import { D as InventoryItemInput, I as InventoryItem, w as ConnectivityProviderRef, y as CredentialInput, z as CredentialSummary, b as AppContextValue } from '../use-app-context-SEU1tyZd.js';
-export { A as AppBrandingDeclaration, x as Credential } from '../use-app-context-SEU1tyZd.js';
-import { E as EnvironmentRef } from '../pipeline-A-gSsPRR.js';
+import { F as InventoryItemInput, I as InventoryItem, y as ConnectivityProviderRef, B as CredentialInput, D as CredentialSummary, d as AppContextValue, r as AppPermissionsApi } from '../use-app-context-Byv_fam0.js';
+export { b as AppBrandingDeclaration, z as Credential, P as PermissionCheckOptions, G as PermissionEntry } from '../use-app-context-Byv_fam0.js';
+import { E as EnvironmentRef, B as TestConnectionResult } from '../pipeline-beeT8dje.js';
 
 /**
  * A platform Tool. Each installed app is upserted as a Tool keyed by its
@@ -18,8 +18,13 @@ interface Tool {
  * when creating an inventory item, so call this once and pass the id as
  * `toolId` to {@link addInventoryItem}. Returns null when no tool matches.
  *
- * GET /api/tools (the endpoint is paginated — `{ data, pagination }` — or a
- * bare array; both are handled).
+ * GET /api/tools (paginated — `{ data, pagination }` — or a bare array; both are
+ * handled). We MUST filter server-side by name: the list is paginated (default 20,
+ * ordered by createdAt) so once a tenant has enough apps installed, a bare
+ * client-side find over just the first page silently misses a real tool whose row
+ * fell to a later page — surfacing a false "no <app> tool found, install the app
+ * first" error for an app that is in fact installed. `search` is a case-insensitive
+ * contains match, so we still exact-match `tool.name === name` on the result.
  */
 declare function resolveTool(name: string): Promise<Tool | null>;
 /** List the customer's inventory (deployment targets). GET /api/components */
@@ -71,6 +76,113 @@ declare function updateCredential(id: string, input: Partial<CredentialInput>):
 /** Remove a credential. DELETE /api/credentials/:id. */
 declare function removeCredential(id: string): Promise<void>;
 
+/**
+ * Test a Connection's endpoint + credential. The platform decrypts the secret,
+ * runs the owning app's connectivity-test handler in-process (the secret is
+ * never returned), and reports whether the endpoint + credentials actually work.
+ * A failed test resolves normally with `{ ok: false, message }` — it does not
+ * throw. Only transport/auth errors (401/404) surface as `{ ok: false }` too.
+ *
+ * @param appId        the app that owns the connection, e.g. `splunk-cloud`
+ * @param credentialId the connection (credential) id
+ * @param opts.endpoint optional endpoint to test against instead of the one stored
+ *                      on the credential — e.g. an Access Server's reachable address
+ *                      (`<host>:<port>`). The host is scoped to the caller's tenant.
+ */
+declare function testConnection(appId: string, credentialId: string, opts?: {
+    endpoint?: string;
+}): Promise<TestConnectionResult>;
+/** Result of running an app operation. Mirrors the server operation handler's return. */
+interface OperationResult {
+    ok: boolean;
+    message: string;
+    details?: string[];
+    /** Optional structured payload (e.g. an export download URL, a job id). */
+    data?: Record<string, unknown>;
+}
+/**
+ * Run an app operation — a one-off action (restart, export, retry, …), NOT a
+ * configuration deploy. The platform decrypts the chosen connection's secret and
+ * runs the app's operation handler in-process (the secret is never returned). A
+ * failed operation resolves normally with `{ ok: false, message }` rather than
+ * throwing.
+ *
+ * @param appId       the app that owns the operation, e.g. `splunk-cloud`
+ * @param operationId the operation id declared in the app manifest
+ * @param opts        the connection (credentialId) to authenticate with, + params
+ */
+declare function runOperation(appId: string, operationId: string, opts?: {
+    credentialId?: string;
+    params?: Record<string, unknown>;
+}): Promise<OperationResult>;
+
+/** The client-safe onboarding descriptor an app advertises in /apps/enabled. */
+interface AppOnboardingDescriptor {
+    provider: string;
+    label: string;
+    brokered?: boolean;
+    requiredSettings?: string[];
+}
+/**
+ * Fetch an app's connection-onboarding descriptor from GET /api/apps/enabled,
+ * so the Connections UI can offer an "Integrate via OAuth" option without the
+ * app page having to pass it in. Returns null when the app declares no
+ * onboarding (its connections stay credential-only).
+ */
+declare function fetchAppOnboarding(appId: string): Promise<AppOnboardingDescriptor | null>;
+interface StartOnboardingInput {
+    /** The deployment scope (environment) the new connection belongs to. */
+    environmentId: string;
+    /** Display name for the new connection. */
+    connectionName: string;
+    /**
+     * Settings the admin supplies BEFORE consent (e.g. Sentinel's
+     * subscription_id / resource_group / workspace_name, or a cloud override).
+     */
+    settings?: Record<string, unknown>;
+}
+interface StartOnboardingResult {
+    /** Open this in the browser — the provider's hosted consent page. */
+    authorizeUrl: string;
+    provider: string;
+}
+/** Begin onboarding a connection. POST /api/apps/:appId/connections/onboard/start. */
+declare function startOnboarding(appId: string, input: StartOnboardingInput): Promise<StartOnboardingResult>;
+interface OnboardingStatus {
+    provider: string;
+    brokered: boolean;
+    tenantId: string | null;
+    cloud: string;
+    manualSteps: Array<{
+        type: string;
+        title: string;
+        description: string;
+        deepLink?: string;
+        cliCommand?: string;
+        verifiable: boolean;
+    }>;
+    verify?: {
+        effective: boolean;
+        message: string;
+    };
+}
+/**
+ * Read onboarding status for a connection, optionally running the verify probe
+ * for pending manual steps (e.g. the Sentinel role assignment).
+ * GET /api/apps/:appId/connections/:credentialId/onboard/status.
+ */
+declare function getOnboardingStatus(appId: string, credentialId: string, opts?: {
+    verify?: boolean;
+}): Promise<OnboardingStatus>;
+/**
+ * Disconnect an onboarded connection (best-effort tenant-side teardown, then
+ * delete). POST /api/apps/:appId/connections/:credentialId/onboard/revoke.
+ */
+declare function revokeOnboarding(appId: string, credentialId: string): Promise<{
+    cleaned: boolean;
+    message: string;
+}>;
+
 /** Name of the global the platform installs before loading app bundles. */
 declare const HOST_RUNTIME_GLOBAL = "__VELTRIX_APP_RUNTIME__";
 /**
@@ -105,6 +217,15 @@ interface VeltrixHostRuntime {
      * DataTable, useToast, ...). Present only inside the platform.
      */
     ui?: Record<string, unknown>;
+    /**
+     * Platform-scoped permission checks (RBAC/IdP hardening, Wave C4) —
+     * `opts.appId` is NOT defaulted here (omit for a platform-scoped check).
+     * App page code should prefer `usePermissions()`
+     * (`@veltrixsecops/app-sdk/hooks`), which defaults `opts.appId` to the
+     * app's own id. Optional for compatibility with a host that hasn't
+     * deployed this surface yet.
+     */
+    permissions?: AppPermissionsApi;
 }
 /** Read the host runtime, or null outside the platform (tests, storybook). */
 declare function getHostRuntime(): VeltrixHostRuntime | null;
@@ -132,4 +253,4 @@ interface AppClientModule {
     sidebarItems?: AppSidebarItem[];
 }
 
-export { type AppClientModule, type AppSidebarItem, ConnectivityProviderRef, CredentialInput, CredentialSummary, EnvironmentRef, HOST_RUNTIME_GLOBAL, InventoryItem, InventoryItemInput, type Tool, type VeltrixHostRuntime, addInventoryItem, authFetch, createCredential, getHostRuntime, listConnectivityProviders, listCredentials, listEnvironments, listInventory, removeCredential, removeInventoryItem, requireHostRuntime, resolveTool, updateCredential, updateInventoryItem };
+export { type AppClientModule, type AppOnboardingDescriptor, AppPermissionsApi, type AppSidebarItem, ConnectivityProviderRef, CredentialInput, CredentialSummary, EnvironmentRef, HOST_RUNTIME_GLOBAL, InventoryItem, InventoryItemInput, type OnboardingStatus, type OperationResult, type StartOnboardingInput, type StartOnboardingResult, TestConnectionResult, type Tool, type VeltrixHostRuntime, addInventoryItem, authFetch, createCredential, fetchAppOnboarding, getHostRuntime, getOnboardingStatus, listConnectivityProviders, listCredentials, listEnvironments, listInventory, removeCredential, removeInventoryItem, requireHostRuntime, resolveTool, revokeOnboarding, runOperation, startOnboarding, testConnection, updateCredential, updateInventoryItem };

package/dist/client/index.js

@@ -3,7 +3,9 @@ import {
   addInventoryItem,
   authFetch,
   createCredential,
+  fetchAppOnboarding,
   getHostRuntime,
+  getOnboardingStatus,
   listConnectivityProviders,
   listCredentials,
   listEnvironments,
@@ -12,15 +14,21 @@ import {
   removeInventoryItem,
   requireHostRuntime,
   resolveTool,
+  revokeOnboarding,
+  runOperation,
+  startOnboarding,
+  testConnection,
   updateCredential,
   updateInventoryItem
-} from "../chunk-6KUTYJW5.js";
+} from "../chunk-HIL6RIDG.js";
 export {
   HOST_RUNTIME_GLOBAL,
   addInventoryItem,
   authFetch,
   createCredential,
+  fetchAppOnboarding,
   getHostRuntime,
+  getOnboardingStatus,
   listConnectivityProviders,
   listCredentials,
   listEnvironments,
@@ -29,6 +37,10 @@ export {
   removeInventoryItem,
   requireHostRuntime,
   resolveTool,
+  revokeOnboarding,
+  runOperation,
+  startOnboarding,
+  testConnection,
   updateCredential,
   updateInventoryItem
 };