Integration Examples

This section provides practical, real-world examples of integrating Supernal Coding with various development tools, CI/CD systems, and custom applications.

Development Environment Examples

VS Code Extension Integration

// .vscode/settings.json
{
  "supernal-coding.apiKey": "${SUPERNAL_API_KEY}",
  "supernal-coding.framework": "iso13485",
  "supernal-coding.autoValidate": true,
  "supernal-coding.showComplianceStatus": true
}

// VS Code extension usage
import { SupernalCoding } from 'vscode-supernal-coding';

const sc = new SupernalCoding();

// Auto-validate on file save
vscode.workspace.onDidSaveTextDocument(async (document) => {
  if (document.languageId === 'typescript') {
    const validation = await sc.validateFile(document.uri.fsPath);
    showValidationResults(validation);
  }
});

Git Hooks Integration

#!/bin/bash
# .git/hooks/pre-commit

echo "Running Supernal Coding validation..."

# Validate changed requirements
changed_files=$(git diff --cached --name-only | grep -E '\.(md|json)$')

if [ ! -z "$changed_files" ]; then
  for file in $changed_files; do
    if [[ $file == *"requirements"* ]]; then
      sc req validate --file="$file"
      if [ $? -ne 0 ]; then
        echo "❌ Validation failed for $file"
        exit 1
      fi
    fi
  done
fi

echo "✅ All validations passed"

CI/CD Integration Examples

GitHub Actions Workflow

# .github/workflows/compliance-validation.yml
name: Compliance Validation

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  validate-compliance:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install Supernal Coding CLI
        run: npm install -g supernal-coding

      - name: Validate Requirements
        env:
          SUPERNAL_API_KEY: ${{ secrets.SUPERNAL_API_KEY }}
        run: |
          sc req validate --all --framework=iso13485
          sc compliance report --format=json --output=compliance-report.json

      - name: Upload Compliance Report
        uses: actions/upload-artifact@v3
        with:
          name: compliance-report
          path: compliance-report.json

      - name: Comment PR with Results
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const report = JSON.parse(fs.readFileSync('compliance-report.json', 'utf8'));

            const comment = `## 🏥 Compliance Validation Results

            **Overall Score:** ${report.overallScore}%
            **Framework:** ${report.framework}
            **Status:** ${report.status}

            ### Requirements Summary
            - ✅ Passed: ${report.requirements.passed}
            - ❌ Failed: ${report.requirements.failed}
            - ⏳ Pending: ${report.requirements.pending}
            `;

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: comment
            });

Jenkins Pipeline Integration

// Jenkinsfile
pipeline {
    agent any

    environment {
        SUPERNAL_API_KEY = credentials('supernal-api-key')
    }

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Install Dependencies') {
            steps {
                sh 'npm install -g supernal-coding'
            }
        }

        stage('Validate Compliance') {
            steps {
                script {
                    def validationResult = sh(
                        script: 'sc req validate --all --format=json',
                        returnStdout: true
                    ).trim()

                    def report = readJSON text: validationResult

                    if (report.status != 'compliant') {
                        error("Compliance validation failed: ${report.issues}")
                    }

                    // Archive compliance report
                    writeFile file: 'compliance-report.json', text: validationResult
                    archiveArtifacts artifacts: 'compliance-report.json'
                }
            }
        }

        stage('Generate Evidence') {
            when {
                branch 'main'
            }
            steps {
                sh '''
                    sc evidence generate --framework=iso13485
                    sc audit prepare --output=audit-package.zip
                '''
                archiveArtifacts artifacts: 'audit-package.zip'
            }
        }
    }

    post {
        always {
            publishHTML([
                allowMissing: false,
                alwaysLinkToLastBuild: true,
                keepAll: true,
                reportDir: 'reports',
                reportFiles: 'compliance-report.html',
                reportName: 'Compliance Report'
            ])
        }
    }
}

GitLab CI Integration

# .gitlab-ci.yml
stages:
  - validate
  - report
  - deploy

variables:
  SUPERNAL_API_KEY: $SUPERNAL_API_KEY

before_script:
  - npm install -g supernal-coding

validate-compliance:
  stage: validate
  script:
    - sc req validate --all --framework=iso13485
    - sc compliance check --critical
  artifacts:
    reports:
      junit: compliance-results.xml
    paths:
      - compliance-report.json
  only:
    - merge_requests
    - main

generate-compliance-report:
  stage: report
  script:
    - sc compliance report --format=pdf --output=compliance-report.pdf
    - sc evidence generate --framework=iso13485
  artifacts:
    paths:
      - compliance-report.pdf
      - evidence/
    expire_in: 30 days
  only:
    - main

deploy-with-compliance:
  stage: deploy
  script:
    - sc compliance verify --required-score=90
    - echo "Deploying application..."
    - ./deploy.sh
  only:
    - main
  when: manual

API Integration Examples

Node.js Express Integration

// server.ts
import express from 'express';
import { SupernalCoding } from '@supernal-coding/node-sdk';

const app = express();
const sc = new SupernalCoding({
  apiKey: process.env.SUPERNAL_API_KEY,
  framework: 'iso13485',
});

// Middleware for compliance validation
app.use('/api/requirements', async (req, res, next) => {
  try {
    const complianceStatus = await sc.getComplianceStatus();
    if (complianceStatus.score < 80) {
      return res.status(400).json({
        error: 'Compliance score too low',
        currentScore: complianceStatus.score,
        requiredScore: 80,
      });
    }
    next();
  } catch (error) {
    res.status(500).json({ error: 'Compliance check failed' });
  }
});

// Create requirement with validation
app.post('/api/requirements', async (req, res) => {
  try {
    const requirement = await sc.createRequirement(req.body);
    const validation = await sc.validateRequirement(requirement.id);

    res.json({
      requirement,
      validation,
      complianceImpact: validation.complianceImpact,
    });
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

// Real-time compliance monitoring (Aspirational - not yet implemented)
/* Aspirational - WebSocket server integration not yet implemented
const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 8080 });

wss.on('connection', (ws) => {
  // Subscribe to compliance events
  sc.onComplianceChange((event) => {
    ws.send(
      JSON.stringify({
        type: 'compliance_update',
        data: event,
      })
    );
  });

  // Subscribe to requirement updates
  sc.onRequirementUpdate((event) => {
    ws.send(
      JSON.stringify({
        type: 'requirement_update',
        data: event,
      })
    );
  });
});
*/

Python Flask Integration

# app.py
from flask import Flask, request, jsonify
from supernal_coding import SupernalCoding
import os

app = Flask(__name__)
sc = SupernalCoding(
    api_key=os.getenv('SUPERNAL_API_KEY'),
    framework='gdpr'
)

@app.before_request
def validate_compliance():
    """Validate compliance before processing requests"""
    if request.endpoint and request.endpoint.startswith('api.'):
        compliance = sc.get_compliance_status()
        if compliance['score'] < 85:
            return jsonify({
                'error': 'Compliance requirements not met',
                'current_score': compliance['score'],
                'required_score': 85
            }), 400

@app.route('/api/privacy/consent', methods=['POST'])
def handle_consent():
    """Handle privacy consent with GDPR compliance"""
    try:
        consent_data = request.json

        # Validate consent against GDPR requirements
        validation = sc.validate_consent(consent_data)
        if not validation['valid']:
            return jsonify({
                'error': 'Invalid consent',
                'issues': validation['issues']
            }), 400

        # Process consent
        result = sc.process_consent(consent_data)

        # Log for audit trail
        sc.audit_log({
            'action': 'consent_processed',
            'user_id': consent_data.get('user_id'),
            'consent_type': consent_data.get('type'),
            'timestamp': result['timestamp']
        })

        return jsonify(result)

    except Exception as e:
        return jsonify({'error': str(e)}), 500

@app.route('/api/compliance/report')
def compliance_report():
    """Generate compliance report"""
    report = sc.generate_report(
        framework='gdpr',
        include_evidence=True,
        format='json'
    )
    return jsonify(report)

Dashboard Integration Examples

React Dashboard Component

// ComplianceDashboard.tsx
import React, { useState, useEffect } from 'react';
import { SupernalDashboard } from '@supernal-coding/react';

interface ComplianceData {
  overallScore: number;
  frameworks: Array<{
    name: string;
    score: number;
    status: string;
  }>;
  requirements: {
    total: number;
    completed: number;
    pending: number;
  };
}

const ComplianceDashboard: React.FC = () => {
  const [complianceData, setComplianceData] = useState<ComplianceData | null>(
    null
  );
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const dashboard = new SupernalDashboard({
      apiKey: process.env.REACT_APP_SUPERNAL_API_KEY,
      framework: 'iso13485',
    });

    // Initial data load
    dashboard.getMetrics().then((data) => {
      setComplianceData(data);
      setLoading(false);
    });

    // Real-time updates
    dashboard.onUpdate((data) => {
      setComplianceData(data);
    });

    return () => dashboard.disconnect();
  }, []);

  if (loading) return <div>Loading compliance data...</div>;

  return (
    <div className="compliance-dashboard">
      <div className="score-card">
        <h2>Overall Compliance Score</h2>
        <div
          className={`score ${complianceData?.overallScore >= 90 ? 'good' : 'warning'}`}
        >
          {complianceData?.overallScore}%
        </div>
      </div>

      <div className="frameworks">
        <h3>Framework Status</h3>
        {complianceData?.frameworks.map((framework) => (
          <div key={framework.name} className="framework-card">
            <h4>{framework.name}</h4>
            <div className="score">{framework.score}%</div>
            <div className={`status ${framework.status}`}>
              {framework.status}
            </div>
          </div>
        ))}
      </div>

      <div className="requirements">
        <h3>Requirements Progress</h3>
        <div className="progress-bar">
          <div
            className="progress-fill"
            style={{
              width: `${(complianceData?.requirements.completed / complianceData?.requirements.total) * 100}%`,
            }}
          />
        </div>
        <div className="stats">
          <span>Completed: {complianceData?.requirements.completed}</span>
          <span>Pending: {complianceData?.requirements.pending}</span>
          <span>Total: {complianceData?.requirements.total}</span>
        </div>
      </div>
    </div>
  );
};

export default ComplianceDashboard;

WebSocket Integration Example

Real-time compliance monitoring using WebSocket connections for live updates and notifications.

Dashboard Integration Example

Complete dashboard integration with custom widgets and real-time compliance monitoring.

Webhook Integration Examples

Slack Notification Integration

// webhook-handlers/slack.ts
import { IncomingWebhook } from '@slack/webhook';

const webhook = new IncomingWebhook(process.env.SLACK_WEBHOOK_URL);

export async function handleComplianceAlert(event: any) {
  const message = {
    text: `🚨 Compliance Alert: ${event.framework}`,
    attachments: [
      {
        color: event.severity === 'critical' ? 'danger' : 'warning',
        fields: [
          {
            title: 'Framework',
            value: event.framework,
            short: true,
          },
          {
            title: 'Score',
            value: `${event.score}%`,
            short: true,
          },
          {
            title: 'Issue',
            value: event.description,
            short: false,
          },
        ],
      },
    ],
  };

  await webhook.send(message);
}

Microsoft Teams Integration

// webhook-handlers/teams.ts
import axios from 'axios';

export async function sendTeamsNotification(event: any) {
  const card = {
    '@type': 'MessageCard',
    '@context': 'http://schema.org/extensions',
    themeColor: event.severity === 'critical' ? 'FF0000' : 'FFA500',
    summary: `Compliance Update: ${event.framework}`,
    sections: [
      {
        activityTitle: `Compliance Status Change`,
        activitySubtitle: event.framework,
        facts: [
          {
            name: 'Current Score',
            value: `${event.score}%`,
          },
          {
            name: 'Previous Score',
            value: `${event.previousScore}%`,
          },
          {
            name: 'Change',
            value:
              event.score > event.previousScore ? '📈 Improved' : '📉 Declined',
          },
        ],
      },
    ],
    potentialAction: [
      {
        '@type': 'OpenUri',
        name: 'View Dashboard',
        targets: [
          {
            os: 'default',
            uri: `https://dashboard.supernal-coding.com/compliance/${event.framework}`,
          },
        ],
      },
    ],
  };

  await axios.post(process.env.TEAMS_WEBHOOK_URL, card);
}

Testing Integration Examples

Jest Testing Integration

// __tests__/compliance.test.ts
import { SupernalCoding } from '@supernal-coding/node-sdk';

describe('Compliance Integration', () => {
  let sc: SupernalCoding;

  beforeEach(() => {
    sc = new SupernalCoding({
      apiKey: process.env.TEST_SUPERNAL_API_KEY,
      framework: 'iso13485',
      environment: 'test',
    });
  });

  test('should validate requirement creation', async () => {
    const requirement = {
      title: 'User Authentication',
      description: 'Implement secure user authentication',
      framework: 'iso13485',
      category: 'security',
    };

    const result = await sc.createRequirement(requirement);
    expect(result.id).toBeDefined();
    expect(result.validationStatus).toBe('valid');
  });

  test('should maintain compliance score above threshold', async () => {
    const status = await sc.getComplianceStatus();
    expect(status.score).toBeGreaterThanOrEqual(85);
  });

  test('should generate valid audit trail', async () => {
    await sc.auditLog({
      action: 'test_action',
      userId: 'test-user',
      timestamp: new Date(),
    });

    const auditTrail = await sc.getAuditTrail({
      startDate: new Date(Date.now() - 3600000), // 1 hour ago
      endDate: new Date(),
    });

    expect(auditTrail.length).toBeGreaterThan(0);
    expect(auditTrail[0]).toHaveProperty('action');
    expect(auditTrail[0]).toHaveProperty('timestamp');
  });
});

Related Documentation

• Integration Overview - Main integration documentation
• API Reference - Complete API documentation
• CLI Commands - Command-line interface reference
• Dashboard Guide - Dashboard configuration

---

These integration examples provide practical guidance for incorporating Supernal Coding into existing development workflows and building custom compliance solutions.