@ampsec/platform-client 87.3.0 → 87.5.0

package/src/dto/rules.dto.ts

@@ -1,31 +1,90 @@
 import {z} from 'zod';
 
-/* ─── Create / Upsert Schemas ──── */
+/* ─── Database Input Schemas (Create / Upsert) ──── */
+
+/**
+ * Flat condition format (backward compatible)
+ * Used when submitting simple or flat conditions
+ */
+export const _FlatConditionSchema = z.object({
+  type: z.enum(['bool', 'numeric', 'string', 'array', 'datetime']),
+  name: z.string(),
+  operator: z.string(),
+  value: z.any().optional(),
+});
+
+/**
+ * Hierarchical condition group format (new)
+ * Supports nested AND/OR logic with unlimited depth
+ */
+export const _ConditionGroupSchema: z.ZodType<any> = z.lazy(() =>
+  z.object({
+    id: z.string().optional(),
+    behavior: z.enum(['any', 'all']),
+    sort_order: z.number().default(0),
+    conditions: z.array(_FlatConditionSchema).optional(),
+    childGroups: z.array(_ConditionGroupSchema).optional(),
+  })
+);
+
+/**
+ * Action format
+ * Each action has a type and associated data
+ */
+export const _ActionSchema = z.object({
+  action_type: z.enum(['then', 'else']),
+  action_data: z.record(z.any()).optional(),
+});
+
+/**
+ * Create rule schema - supports both flat and hierarchical conditions
+ */
 export const _CreateRuleSchema = z.object({
-  cid: z.string(),
+  rule_set_id: z.string(),
+  cid: z.string().optional(),
+  tid: z.string().optional(),
   priority: z.number().default(0),
-  conditions: z.any().optional(),
-  actions: z.any().optional(),
+  conditions: z.array(_FlatConditionSchema).optional(),
+  conditionGroups: z.array(_ConditionGroupSchema).optional(),
+  actions: z.array(_ActionSchema).optional(),
 });
 
+/**
+ * Upsert rule schema - for updates
+ */
 export const _RuleUpsertSchema = z.object({
   id: z.string(),
   priority: z.number().optional(),
-  conditions: z.any().optional(),
-  actions: z.any().optional(),
+  conditions: z.array(_FlatConditionSchema).optional(),
+  conditionGroups: z.array(_ConditionGroupSchema).optional(),
+  actions: z.array(_ActionSchema).optional(),
+  rule_set_id: z.string().optional(),
 });
 
 export type CreateRuleDtoSchema = z.infer<typeof _CreateRuleSchema> & {
   tid: string;
+  rule_set_id: string;
 };
 
 export type RuleUpsertDtoSchema = z.infer<typeof _RuleUpsertSchema>;
 
+export type FlatConditionSchema = z.infer<typeof _FlatConditionSchema>;
+export type ConditionGroupSchema = z.infer<typeof _ConditionGroupSchema>;
+export type ActionSchema = z.infer<typeof _ActionSchema>;
+
 /* ─── Compiled Rule Types ─────────────────────────────────────────────────
  * Describe the JSON shape produced by RuleService.compileRulesToJson()
  * and consumed by the rules engine.
+ *
+ * NOTE: The RulesEngine receives COMPILED conditions (CompiledConditionNode),
+ * NOT raw database ConditionGroups. The compilation process converts the
+ * hierarchical ConditionGroup structure to this CompositeConditions format.
  * ────────────────────────────────────────────────────────────────────────── */
 
+/**
+ * Leaf condition (single condition)
+ * e.g. { type: "string", name: "severity", operator: "equal_to", value: "CRITICAL" }
+ */
 export type CompiledLeafCondition = {
   type: string;
   name: string;
@@ -33,13 +92,26 @@ export type CompiledLeafCondition = {
   value: unknown;
 };
 
+/**
+ * Composite condition (AND/OR grouping)
+ * e.g. { any: [...], all: [...] }
+ * Supports unlimited nesting
+ */
 export type CompiledCompositeCondition = {
   any?: CompiledConditionNode[];
   all?: CompiledConditionNode[];
 };
 
+/**
+ * A condition node is either a leaf condition or composite group
+ * Recursive type supporting arbitrary nesting depth
+ */
 export type CompiledConditionNode = CompiledLeafCondition | CompiledCompositeCondition;
 
+/**
+ * Action payload structure
+ * Each action has a type and arbitrary metadata
+ */
 export type CompiledActionData = {
   type: string;
   [key: string]: unknown;
@@ -53,14 +125,75 @@ export type CompiledActions = {
   [action_type: string]: CompiledActionData[];
 };
 
-/** Compiled rule as produced by compileRulesToJson */
+/**
+ * Compiled rule as produced by compileRulesToJson()
+ * This is what RulesEngine.execute() receives
+ */
 export type CompiledRule = {
+  id: string;
   priority: number;
   conditions: CompiledConditionNode | null;
   actions: CompiledActions;
 };
 
+/**
+ * Result type for getRuleSetByRuleIds()
+ * Maps rule ID to its compiled ruleset
+ */
 export type RuleSetByIdResult = {
   ruleId: string;
   ruleSet: CompiledRule[];
 };
+
+/* ─── Internal Database Types ──────────────────────────────────────────── */
+
+/**
+ * Database representation of a condition group (hierarchical storage)
+ * NOT used by RulesEngine - only internal storage
+ */
+export type ConditionGroupEntity = {
+  id: string;
+  rule_id: string;
+  parent_group_id: string | null;
+  behavior: 'any' | 'all';
+  sort_order: number;
+  conditions?: FlatConditionSchema[];
+  childGroups?: ConditionGroupEntity[];
+};
+
+/**
+ * Database representation of a condition (flat storage)
+ * Can be used standalone (legacy) or within a ConditionGroup (new)
+ */
+export type ConditionEntity = {
+  id: string;
+  rule_id: string;
+  condition_group_id?: string | null;
+  type: string;
+  name: string;
+  operator: string;
+  value: unknown;
+};
+
+/**
+ * Compilation flow:
+ *
+ * Database Layer:
+ *   Rule.conditionGroups: ConditionGroupEntity[]  (hierarchical)
+ *   Rule.conditions: ConditionEntity[]             (flat - legacy fallback)
+ *
+ *   ↓ RuleService.compileRulesToJson()
+ *
+ * Compilation Layer:
+ *   buildConditionsFromGroups(conditionGroups, conditions)
+ *   - If conditionGroups exist: recursively build tree via buildGroupNode()
+ *   - If empty: fallback to flat conditions
+ *   buildActions() wraps in array-of-arrays
+ *
+ *   ↓ Returns CompiledRule[]
+ *
+ * RulesEngine Layer:
+ *   RulesEngine.execute(compiledRules, input)
+ *   - Processes CompiledConditionNode (any/all nested structure)
+ *   - Actions are array of arrays: `response.then.push(...rule.actions.then)`
+ */

package/src/services/AmpApi.ts

@@ -31,6 +31,7 @@ import {
   NotificationService,
   PredictionService,
   CustomActionsService,
+  RulesService,
 } from '.';
 import {KIND, TARGET_API_AGENT} from './constants';
 import {getAmpRestClient, AmpRestClientOptions, AgentIdentityService, ConnectorInstallService, DefaultEnumService, EnumService, RestClient} from './rest';
@@ -43,6 +44,7 @@ import {TrainingsService} from './trainings.service';
 import {AnalyticsService} from './analytics.service';
 import {EngagementLogsService} from './engagementLogs.service';
 import {ConnectorReadinessService} from './connectorReadiness.service';
+import {AmpSdkTagSpecsService} from './tagSpecs.service';
 
 export type AmpApiOptions = AmpRestClientOptions;
 
@@ -80,9 +82,11 @@ export class AmpApi {
   readonly providers: AmpDataService<ProviderDto>;
   readonly reportResults: AmpDataService<ReportResultDto>;
   readonly reports: AmpReportService;
+  readonly rules: RulesService;
   readonly saasAssets: AmpDataService<SaasAssetDto>;
   readonly saasComponents: AmpDataService<SaasComponentDto>;
   readonly saasUsers: AmpDataService<SaasUserDto>;
+  readonly tagSpecsService: AmpSdkTagSpecsService;
   readonly settings: AmpSettingsService;
   readonly tenants: AmpEntityService<TenantUpsertDto, TenantDto>;
   readonly tokens: AmpDataService<TokenDto>;
@@ -117,9 +121,12 @@ export class AmpApi {
     this.providers = new AmpDataServiceImpl<ProviderDto>(rest, KIND.PROVIDERS);
     this.reportResults = new AmpDataServiceImpl<ReportResultDto>(rest, KIND.REPORT_RESULTS);
     this.reports = new AmpReportServiceImpl(rest);
+    this.rules = new RulesService(rest, KIND.RULES, TARGET_API_AGENT);
     this.saasAssets = new AmpDataServiceImpl<SaasAssetDto>(rest, KIND.SAAS_ASSETS);
     this.saasComponents = new AmpDataServiceImpl<SaasComponentDto>(rest, KIND.SAAS_COMPONENTS);
     this.saasUsers = new AmpDataServiceImpl<SaasUserDto>(rest, KIND.SAAS_USERS);
+    //this.tagSpecsService = new TagSpecsService(rest, KIND.TAG_SPECS, TARGET_API_AGENT);
+    this.tagSpecsService = new AmpSdkTagSpecsService(rest, KIND.TAG_SPECS, TARGET_API_AGENT);
     this.settings = new AmpSettingsService(rest);
     this.tenants = new AmpEntityServiceImpl<TenantUpsertDto, TenantDto>(rest, KIND.TENANTS);
     this.tokens = new AmpDataServiceImpl<TokenDto>(rest, KIND.TOKENS);

package/src/services/AmpSdk.ts

@@ -60,7 +60,7 @@ import {
 } from './entity.service';
 import {AmpSdkCustomActionsService} from './customActions.platform.service';
 import {AmpRestClientOptions, RestClient, getAmpRestClient} from './rest';
-import {KIND, TARGET_API_PLATFORM} from './constants';
+import {KIND, TARGET_API_AGENT, TARGET_API_PLATFORM} from './constants';
 import {DefaultEnumService, EnumService} from './rest/EnumService';
 import {AmpSdkSettingsService} from './settings.service';
 import {AmpSaaSEntityService, AmpSaaSEntityServiceImpl, AmpSdkSaasAssetService, AmpSdkSaasComponentService, AmpSdkSaasUserService} from './saasEntity.service';
@@ -176,7 +176,7 @@ export class AmpSdkServices {
     this.stagedSaaSUsers = new TruncatableAmpEntityServiceImpl<PlatformStagedSaasUserUpsertDto, PlatformStagedSaasUserDto>(rest, KIND.STAGED_SAAS_USERS, TARGET_API_PLATFORM);
 
     this.settings = new AmpSdkSettingsService(rest);
-    this.tagSpecs = new AmpSdkTagSpecsService(rest);
+    this.tagSpecs = new AmpSdkTagSpecsService(rest, KIND.TAG_SPECS, TARGET_API_AGENT);
     this.tenants = new TenantsService(rest, TARGET_API_PLATFORM);
     this.tenantNotes = new TenantNotesService(rest, TARGET_API_PLATFORM);
     this.tokens = new AmpEntityServiceImpl<PlatformTokenUpsertDto, PlatformTokenDto>(rest, KIND.TOKENS, TARGET_API_PLATFORM);

package/src/services/tagSpecs.service.ts

@@ -1,16 +1,21 @@
 // sdk/services/tagSpec.sdk.service.ts
-import {RestClient} from './rest';
-import {TagSpecDto, TagSpecWithRuleSetDto} from '../dto/tagSpecs.dto';
-import {KIND} from './constants';
+import {RestClient, RestResponse} from './rest';
+import {TagSpecDto, TagSpecUpsertDto, TagSpecWithRuleSetDto} from '../dto/tagSpecs.dto';
+import {KIND, TargetApi} from './constants';
 import {Page} from '../dto';
+import {FilterCriteria} from '../FilterCriteria';
 
 const TAG_SPECS_PAGE_SIZE = 250;
 
 export class AmpSdkTagSpecsService {
   protected readonly rest: RestClient;
+  protected readonly targetApi: string;
+  protected readonly kind: string;
 
-  constructor(rest: RestClient) {
+  constructor(rest: RestClient, kind?: string, targetApi?: TargetApi) {
     this.rest = rest;
+    this.kind = kind || KIND.TAG_SPECS;
+    this.targetApi = targetApi || 'platform';
   }
 
   async listByTenant(tid: string): Promise<TagSpecWithRuleSetDto[]> {
@@ -50,4 +55,55 @@ export class AmpSdkTagSpecsService {
 
     return res.data as TagSpecDto;
   }
+
+  async create(dto: TagSpecUpsertDto): Promise<RestResponse> {
+    return await this.rest.call({
+      url: `/${this.targetApi}/v1/${this.kind}`,
+      method: 'POST',
+      data: dto,
+    });
+  }
+
+  async update(id: string, dto: TagSpecUpsertDto): Promise<RestResponse> {
+    return await this.rest.call({
+      url: `/${this.targetApi}/v1/${this.kind}/${id}`,
+      method: 'PUT',
+      data: dto,
+    });
+  }
+
+  async get(id: string): Promise<RestResponse> {
+    return await this.rest.call({
+      url: `/${this.targetApi}/v1/${this.kind}/${id}`,
+      method: 'GET',
+    });
+  }
+
+  async listWithRules(params: {tid?: string; limit?: number; offset?: number}): Promise<RestResponse> {
+    const queryParams: Record<string, unknown> = {
+      limit: 200,
+      ...params,
+    };
+
+    return await this.rest.call({
+      url: `/${this.targetApi}/v1/${this.kind}/with-rules`,
+      method: 'GET',
+      params: queryParams,
+    });
+  }
+
+  async list(params: FilterCriteria): Promise<RestResponse> {
+    return await this.rest.call({
+      url: `/${this.targetApi}/v1/${this.kind}`,
+      method: 'GET',
+      params,
+    });
+  }
+
+  async delete(id: string): Promise<RestResponse> {
+    return await this.rest.call({
+      url: `/${this.targetApi}/v1/${this.kind}/${id}`,
+      method: 'DELETE',
+    });
+  }
 }