@solidxai/core 0.1.12 → 0.1.13-beta.2

package/src/services/workflow/nodes/solidx-send-sms.node.ts

@@ -0,0 +1,377 @@
+import { BadRequestException } from '@nestjs/common';
+import { WorkflowNodeProvider } from '../../../decorators/workflow-node-provider.decorator';
+import { SmsFactory } from '../../../factories/sms.factory';
+import { WorkflowNodeHandler } from '../../../interfaces/workflow-node-handler.interface';
+import {
+  WorkflowNodeExecutionContext,
+  WorkflowNodeHandlerResult,
+} from '../../../types/workflow-dsl.types';
+
+const fullWidthField = {
+  layout: {
+    width: 'full',
+  },
+};
+
+const jsonEditorField = {
+  ...fullWidthField,
+  editor: {
+    language: 'json',
+  },
+};
+
+@WorkflowNodeProvider({
+  type: 'solidx.sms.send',
+  kind: 'task',
+  version: '1.0.0',
+  category: 'integration',
+  subcategory: 'solidx',
+  label: 'Send SMS',
+  description:
+    'Sends an SMS using the native SolidX SMS provider and queue settings.',
+  tags: ['solidx', 'sms', 'notification', 'template', 'text-message'],
+  aliases: ['sms.send', 'text.send', 'solidx.text.send'],
+  configSchema: {
+    type: 'object',
+    required: ['to', 'mode'],
+    properties: {
+      mode: {
+        type: 'string',
+        enum: ['template', 'raw'],
+        default: 'template',
+      },
+      to: {},
+      body: { type: 'string' },
+      templateName: { type: 'string' },
+      templateParams: { type: 'object', default: {} },
+      shouldQueueSms: { type: 'boolean', default: true },
+      providerName: { type: 'string' },
+    },
+  },
+  outputSchema: {
+    type: 'object',
+    properties: {
+      ok: { type: 'boolean' },
+      mode: { type: 'string' },
+      to: {},
+      body: { type: 'string' },
+      templateName: { type: 'string' },
+      queued: { type: 'boolean' },
+      providerName: { type: 'string' },
+      response: {},
+    },
+  },
+  examples: [
+    {
+      key: 'template-sms',
+      label: 'Template SMS',
+      description:
+        'Render a SolidX SMS template and queue the message for delivery.',
+      language: 'yaml',
+      snippet:
+        'mode: template\nto: "{{ input.mobile }}"\ntemplateName: workflow-alert\ntemplateParams:\n  name: "{{ input.name }}"\n  reference: "{{ execution.executionIdentifier }}"\nshouldQueueSms: true\n',
+      configurationOnly: true,
+    },
+    {
+      key: 'raw-sms',
+      label: 'Raw SMS',
+      description:
+        'Send a direct SMS body. Use only with providers that support raw SMS, such as Twilio.',
+      language: 'yaml',
+      snippet:
+        'mode: raw\nto:\n  - "+15551234567"\nbody: "Workflow {{ execution.executionIdentifier }} completed."\nshouldQueueSms: true\n',
+      configurationOnly: true,
+    },
+  ],
+  definitions: [
+    {
+      key: 'native-sms-provider',
+      label: 'Native SolidX SMS provider',
+      content:
+        'This task resolves the active SolidX SMS provider through SmsFactory, so Twilio, Msg91, or consuming-project providers can be selected by the existing smsProvider setting.',
+    },
+    {
+      key: 'template-first',
+      label: 'Template-first delivery',
+      content:
+        'Some SMS gateways require registered templates and do not support raw text. Template mode is therefore the default, while raw mode remains available for providers that support it.',
+    },
+    {
+      key: 'queueing',
+      label: 'Queueing',
+      content:
+        'shouldQueueSms is passed to the native provider. Providers may still queue based on system settings even when this value is false.',
+    },
+  ],
+  authoring: {
+    defaultConfiguration: {
+      mode: 'template',
+      templateParams: {},
+      shouldQueueSms: true,
+    },
+    configurationFields: [
+      {
+        key: 'mode',
+        label: 'Mode',
+        description: 'Send a raw SMS or render a SolidX SMS template.',
+        valueType: 'string',
+        enumValues: ['template', 'raw'],
+        defaultValue: 'template',
+        required: true,
+        group: 'Message',
+        uiSchema: fullWidthField,
+      },
+      {
+        key: 'to',
+        label: 'To',
+        description:
+          'Recipient mobile number, comma-separated list, or array. Expressions are allowed.',
+        valueType: 'array',
+        required: true,
+        expressionAllowed: true,
+        group: 'Recipients',
+        widgetHint: 'json-editor',
+        uiSchema: fullWidthField,
+      },
+      {
+        key: 'templateName',
+        label: 'Template Name',
+        description:
+          'SolidX SMS template name/user key for template mode. Expressions are allowed.',
+        valueType: 'string',
+        required: true,
+        expressionAllowed: true,
+        group: 'Template',
+        uiSchema: {
+          ...fullWidthField,
+          visibleWhen: {
+            field: 'mode',
+            equals: 'template',
+          },
+        },
+      },
+      {
+        key: 'templateParams',
+        label: 'Template Parameters',
+        description:
+          'JSON parameters used when rendering the SMS template. Expressions are allowed.',
+        valueType: 'object',
+        expressionAllowed: true,
+        group: 'Template',
+        widgetHint: 'json-editor',
+        uiSchema: {
+          ...jsonEditorField,
+          visibleWhen: {
+            field: 'mode',
+            equals: 'template',
+          },
+        },
+      },
+      {
+        key: 'body',
+        label: 'Body',
+        description:
+          'SMS body for raw mode. Expressions are allowed. Some providers require template mode instead.',
+        valueType: 'string',
+        required: true,
+        expressionAllowed: true,
+        group: 'Message',
+        widgetHint: 'raw-editor',
+        uiSchema: {
+          ...fullWidthField,
+          visibleWhen: {
+            field: 'mode',
+            equals: 'raw',
+          },
+        },
+      },
+      {
+        key: 'shouldQueueSms',
+        label: 'Queue SMS',
+        description: 'Use the native SolidX SMS queue when available.',
+        valueType: 'boolean',
+        defaultValue: true,
+        group: 'Delivery',
+        uiSchema: fullWidthField,
+      },
+      {
+        key: 'providerName',
+        label: 'Provider Name',
+        description:
+          'Optional registered SMS provider class name. If omitted, the smsProvider setting is used.',
+        valueType: 'string',
+        expressionAllowed: true,
+        group: 'Advanced',
+        uiSchema: fullWidthField,
+      },
+    ],
+    outputs: [
+      {
+        key: 'ok',
+        label: 'OK',
+        description: 'Whether the SMS provider call completed.',
+        valueType: 'boolean',
+        path: 'ok',
+      },
+      {
+        key: 'response',
+        label: 'Provider Response',
+        description: 'Response returned by the active native SMS provider.',
+        valueType: 'any',
+        path: 'response',
+      },
+      {
+        key: 'to',
+        label: 'To',
+        description: 'Resolved recipients.',
+        valueType: 'array',
+        path: 'to',
+      },
+      {
+        key: 'mode',
+        label: 'Mode',
+        description: 'Resolved send mode.',
+        valueType: 'string',
+        path: 'mode',
+      },
+    ],
+    supportsExpressions: true,
+    supportsRetryPolicy: true,
+    supportsTimeoutMs: true,
+    supportsOnError: true,
+    supportsDisableToggle: true,
+    supportsName: true,
+    supportsDescription: true,
+    searchableText: [
+      'sms',
+      'text',
+      'send',
+      'notification',
+      'template',
+      'solidx',
+    ],
+  },
+  runtime: {
+    emitsLogs: true,
+    emitsArtifacts: false,
+    deterministicOutputs: false,
+    executionMode: 'task',
+    successStatuses: ['success'],
+  },
+  documentation: {
+    summary:
+      'Sends raw or template-based SMS through the configured native SolidX SMS provider.',
+  },
+  ui: {
+    icon: 'si-send',
+    iconColor: '#0f766e',
+    iconBackgroundColor: '#ccfbf1',
+    iconBorderColor: '#99f6e4',
+    defaultEditorMode: 'schema',
+    modalSize: 'xl',
+    layoutHints: {
+      preferredPanel: 'flow',
+      groupOrder: ['Recipients', 'Message', 'Template', 'Delivery', 'Advanced'],
+      stickySummary: true,
+    },
+  },
+})
+export class SolidXSendSmsNode implements WorkflowNodeHandler {
+  constructor(private readonly smsFactory: SmsFactory) {}
+
+  async execute(
+    context: WorkflowNodeExecutionContext,
+  ): Promise<WorkflowNodeHandlerResult> {
+    const configuration = context.expression.interpolate(
+      context.node.configuration ?? {},
+      context,
+    );
+
+    const mode = configuration.mode ?? 'template';
+    const to = this.normalizeRecipients(configuration.to);
+    if (!to.length) {
+      throw new BadRequestException('solidx.sms.send requires recipients.');
+    }
+
+    const shouldQueueSms = configuration.shouldQueueSms !== false;
+    const smsService = this.smsFactory.getSmsService(configuration.providerName);
+
+    if (!smsService) {
+      throw new BadRequestException('No SolidX SMS provider is configured.');
+    }
+
+    let response: any;
+    let body = configuration.body;
+    let templateName = configuration.templateName;
+
+    if (mode === 'template') {
+      if (!templateName) {
+        throw new BadRequestException(
+          'solidx.sms.send requires templateName in template mode.',
+        );
+      }
+
+      response = await smsService.sendSMSUsingTemplate(
+        to.join(','),
+        templateName,
+        configuration.templateParams ?? {},
+        shouldQueueSms,
+      );
+    } else {
+      body = configuration.body;
+      if (!body) {
+        throw new BadRequestException(
+          'solidx.sms.send requires body in raw mode.',
+        );
+      }
+
+      response = await smsService.sendSMS(to.join(','), body, shouldQueueSms);
+    }
+
+    await context.emitLog({
+      level: 'info',
+      eventType: 'node.solidx.sms.sent',
+      source: 'solidx.sms.send',
+      message:
+        mode === 'template'
+          ? `SolidX SMS template "${templateName}" queued/sent to ${to.join(', ')}.`
+          : `SolidX SMS queued/sent to ${to.join(', ')}.`,
+      metadata: {
+        mode,
+        to,
+        shouldQueueSms,
+        providerName: configuration.providerName,
+      },
+    });
+
+    return {
+      output: {
+        ok: true,
+        mode,
+        to,
+        body,
+        templateName,
+        queued: shouldQueueSms,
+        providerName: configuration.providerName,
+        response,
+      },
+    };
+  }
+
+  private normalizeRecipients(value: any): string[] {
+    if (value === undefined || value === null || value === '') {
+      return [];
+    }
+
+    if (Array.isArray(value)) {
+      return value
+        .flatMap((entry) => this.normalizeRecipients(entry))
+        .filter(Boolean);
+    }
+
+    return String(value)
+      .split(',')
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+  }
+}

package/src/services/workflow/nodes/switch.node.ts

@@ -0,0 +1,125 @@
+import { WorkflowNodeProvider } from '../../../decorators/workflow-node-provider.decorator';
+import { WorkflowNodeHandler } from '../../../interfaces/workflow-node-handler.interface';
+import {
+  WorkflowNodeDefinition,
+  WorkflowNodeExecutionContext,
+  WorkflowNodeHandlerResult,
+} from '../../../types/workflow-dsl.types';
+
+@WorkflowNodeProvider({
+  type: 'switch',
+  kind: 'control',
+  category: 'control-flow',
+  label: 'Switch',
+  description:
+    'Runs one case sequence based on a contextual value, with an optional default sequence.',
+  tags: ['switch', 'case', 'branching', 'condition'],
+  authoring: {
+    defaultConfiguration: {
+      value: '{{ input.value }}',
+    },
+    configurationFields: [
+      {
+        key: 'value',
+        label: 'Value',
+        description:
+          'Expression or literal value used to choose the matching case key.',
+        valueType: 'expression',
+        required: true,
+        expressionAllowed: true,
+        widgetHint: 'textarea',
+        group: 'General',
+      },
+    ],
+    childSlots: [
+      {
+        key: 'cases',
+        label: 'Cases',
+        description: 'Named case sequences. The matching case key is executed.',
+        kind: 'case-collection',
+        required: true,
+        minItems: 1,
+      },
+      {
+        key: 'defaults',
+        label: 'Default',
+        description:
+          'Fallback sequence that runs when no case key matches the resolved value.',
+        kind: 'sequence',
+      },
+    ],
+    supportsDescription: true,
+    supportsName: true,
+  },
+  documentation: {
+    summary:
+      'Evaluates a contextual value and runs the child node sequence under the matching case key. If no case matches, the optional default sequence runs.',
+  },
+  ui: {
+    icon: 'si-git-branch',
+    iconColor: '#db2777',
+    iconBackgroundColor: '#fce7f3',
+    iconBorderColor: '#f9a8d4',
+    modalSize: 'lg',
+    layoutHints: {
+      groupOrder: ['General'],
+    },
+  },
+})
+export class SwitchNode implements WorkflowNodeHandler {
+  async execute(
+    context: WorkflowNodeExecutionContext,
+  ): Promise<WorkflowNodeHandlerResult> {
+    const configuration = context.node.configuration ?? {};
+    const resolvedValue = context.expression.interpolate(
+      configuration.value,
+      context,
+    );
+    const caseKey = this.resolveCaseKey(resolvedValue, context.node.cases ?? {});
+    const selectedNodes = caseKey
+      ? context.node.cases?.[caseKey] ?? []
+      : context.node.defaults ?? [];
+
+    await context.emitLog({
+      level: 'info',
+      eventType: 'node.switch.evaluated',
+      source: 'switch',
+      message: caseKey
+        ? `Switch node "${context.node.id}" matched case "${caseKey}".`
+        : `Switch node "${context.node.id}" did not match a case and will run defaults.`,
+      context: {
+        value: resolvedValue,
+        caseKey,
+      },
+    });
+
+    await context.runNodes(selectedNodes);
+
+    return {
+      output: {
+        value: resolvedValue,
+        case: caseKey,
+        matched: Boolean(caseKey),
+      },
+    };
+  }
+
+  private resolveCaseKey(
+    value: any,
+    cases: Record<string, WorkflowNodeDefinition[]>,
+  ): string | undefined {
+    const exactKey = String(value);
+    if (Object.prototype.hasOwnProperty.call(cases, exactKey)) {
+      return exactKey;
+    }
+
+    if (typeof value === 'boolean') {
+      const booleanKey = value ? 'true' : 'false';
+      if (Object.prototype.hasOwnProperty.call(cases, booleanKey)) {
+        return booleanKey;
+      }
+    }
+
+    return undefined;
+  }
+}

package/src/services/workflow/workflow-definition-metadata-sync.service.ts

@@ -0,0 +1,196 @@
+import { Injectable, Logger } from '@nestjs/common';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { WorkflowDefinition } from 'src/entities/workflow-definition.entity';
+import { ModuleMetadataHelperService } from 'src/helpers/module-metadata-helper.service';
+
+type WorkflowMetadataEntry = {
+  key: string;
+  moduleUserKey: string;
+  displayName: string;
+  namespace?: string;
+  description?: string;
+  status?: string;
+  definitionVersion?: string;
+  tags?: any;
+  definitionYaml: string;
+};
+
+@Injectable()
+export class WorkflowDefinitionMetadataSyncService {
+  private readonly logger = new Logger(WorkflowDefinitionMetadataSyncService.name);
+
+  constructor(
+    private readonly moduleMetadataHelperService: ModuleMetadataHelperService,
+  ) {}
+
+  async upsertWorkflowDefinition(
+    workflowDefinition: WorkflowDefinition,
+    previousWorkflowDefinition?: WorkflowDefinition | null,
+  ): Promise<void> {
+    const moduleName = workflowDefinition.moduleMetadata?.name;
+    if (!moduleName) {
+      this.logger.warn(`Skipping workflow metadata sync for ${workflowDefinition.key}: moduleMetadata relation is not loaded.`);
+      return;
+    }
+
+    if (
+      previousWorkflowDefinition &&
+      (
+        previousWorkflowDefinition.key !== workflowDefinition.key ||
+        previousWorkflowDefinition.moduleMetadata?.name !== moduleName
+      )
+    ) {
+      await this.removeWorkflowDefinition(previousWorkflowDefinition);
+    }
+
+    const metadataFilePath = await this.getExistingMetadataFilePath(moduleName);
+    if (!metadataFilePath) {
+      return;
+    }
+
+    const metadata = await this.moduleMetadataHelperService.getModuleMetadataConfiguration(metadataFilePath);
+    if (!metadata) {
+      return;
+    }
+
+    const yamlRelativePath = this.getWorkflowYamlRelativePath(workflowDefinition.key);
+    const yamlFilePath = path.resolve(path.dirname(metadataFilePath), yamlRelativePath);
+
+    await fs.mkdir(path.dirname(yamlFilePath), { recursive: true });
+    await fs.writeFile(yamlFilePath, this.withTrailingNewline(workflowDefinition.definitionYaml ?? ''), 'utf8');
+
+    if (!Array.isArray(metadata.workflowDefinitions)) {
+      metadata.workflowDefinitions = [];
+    }
+
+    const entry = this.toMetadataEntry(workflowDefinition, moduleName, yamlRelativePath);
+    const existingIndex = metadata.workflowDefinitions.findIndex(
+      (definition: WorkflowMetadataEntry) => definition.key === workflowDefinition.key,
+    );
+
+    if (existingIndex === -1) {
+      metadata.workflowDefinitions.push(entry);
+    } else {
+      metadata.workflowDefinitions[existingIndex] = entry;
+    }
+
+    await this.writeMetadataFile(metadataFilePath, metadata);
+    this.logger.log(`Synced workflow definition ${workflowDefinition.key} to ${metadataFilePath}`);
+  }
+
+  async removeWorkflowDefinition(workflowDefinition: WorkflowDefinition): Promise<void> {
+    const moduleName = workflowDefinition.moduleMetadata?.name;
+    if (!moduleName) {
+      this.logger.warn(`Skipping workflow metadata removal for ${workflowDefinition.key}: moduleMetadata relation is not loaded.`);
+      return;
+    }
+
+    const metadataFilePath = await this.getExistingMetadataFilePath(moduleName);
+    if (!metadataFilePath) {
+      return;
+    }
+
+    const metadata = await this.moduleMetadataHelperService.getModuleMetadataConfiguration(metadataFilePath);
+    if (!metadata || !Array.isArray(metadata.workflowDefinitions)) {
+      return;
+    }
+
+    const existingEntry = metadata.workflowDefinitions.find(
+      (definition: WorkflowMetadataEntry) => definition.key === workflowDefinition.key,
+    );
+    const previousLength = metadata.workflowDefinitions.length;
+    metadata.workflowDefinitions = metadata.workflowDefinitions.filter(
+      (definition: WorkflowMetadataEntry) => definition.key !== workflowDefinition.key,
+    );
+
+    const yamlRelativePath = this.resolveWorkflowYamlReference(workflowDefinition, existingEntry);
+    if (yamlRelativePath) {
+      await this.removeYamlFile(path.resolve(path.dirname(metadataFilePath), yamlRelativePath));
+    }
+
+    if (metadata.workflowDefinitions.length !== previousLength) {
+      await this.writeMetadataFile(metadataFilePath, metadata);
+      this.logger.log(`Removed workflow definition ${workflowDefinition.key} from ${metadataFilePath}`);
+    }
+  }
+
+  private async getExistingMetadataFilePath(moduleName: string): Promise<string | null> {
+    const metadataFilePath = await this.moduleMetadataHelperService.getModuleMetadataFilePath(moduleName);
+    try {
+      await fs.access(metadataFilePath);
+      return metadataFilePath;
+    } catch {
+      this.logger.warn(`Skipping workflow metadata sync because metadata file was not found: ${metadataFilePath}`);
+      return null;
+    }
+  }
+
+  private toMetadataEntry(
+    workflowDefinition: WorkflowDefinition,
+    moduleName: string,
+    yamlRelativePath: string,
+  ): WorkflowMetadataEntry {
+    const entry: WorkflowMetadataEntry = {
+      key: workflowDefinition.key,
+      moduleUserKey: moduleName,
+      displayName: workflowDefinition.displayName,
+      definitionYaml: `file:${yamlRelativePath}`,
+    };
+
+    this.assignIfPresent(entry, 'namespace', workflowDefinition.namespace);
+    this.assignIfPresent(entry, 'description', workflowDefinition.description);
+    this.assignIfPresent(entry, 'status', workflowDefinition.status);
+    this.assignIfPresent(entry, 'definitionVersion', workflowDefinition.definitionVersion);
+    this.assignIfPresent(entry, 'tags', workflowDefinition.tags);
+
+    return entry;
+  }
+
+  private assignIfPresent(target: WorkflowMetadataEntry, key: keyof WorkflowMetadataEntry, value: any) {
+    if (value !== undefined && value !== null && value !== '') {
+      (target as any)[key] = value;
+    }
+  }
+
+  private getWorkflowYamlRelativePath(workflowKey: string) {
+    return path.posix.join('workflows', `${this.safeWorkflowFileName(workflowKey)}.yaml`);
+  }
+
+  private safeWorkflowFileName(workflowKey: string) {
+    return String(workflowKey ?? 'workflow')
+      .trim()
+      .replace(/[\\/]/g, '-')
+      .replace(/^\.+/, '')
+      || 'workflow';
+  }
+
+  private resolveWorkflowYamlReference(
+    workflowDefinition: WorkflowDefinition,
+    metadataEntry?: WorkflowMetadataEntry,
+  ): string | null {
+    if (typeof metadataEntry?.definitionYaml === 'string' && metadataEntry.definitionYaml.startsWith('file:')) {
+      return metadataEntry.definitionYaml.slice('file:'.length).trim();
+    }
+
+    return this.getWorkflowYamlRelativePath(workflowDefinition.key);
+  }
+
+  private async removeYamlFile(filePath: string) {
+    try {
+      await fs.unlink(filePath);
+    } catch (error: any) {
+      if (error?.code !== 'ENOENT') {
+        this.logger.warn(`Unable to remove workflow YAML file ${filePath}: ${error?.message ?? String(error)}`);
+      }
+    }
+  }
+
+  private async writeMetadataFile(metadataFilePath: string, metadata: any) {
+    await fs.writeFile(metadataFilePath, `${JSON.stringify(metadata, null, 2)}\n`, 'utf8');
+  }
+
+  private withTrailingNewline(value: string) {
+    return value.endsWith('\n') ? value : `${value}\n`;
+  }
+}