@mindmakr/gs-websdk/docs/DEVOPS_GUIDE.md

Web SDK for Guru SaaS System - Complete JavaScript/TypeScript SDK for building applications with dynamic schema management

# 🚀 DevOps Guide

Complete guide for building, testing, and publishing the Guru SaaS Web SDK to npm.

## 📋 Table of Contents

- [Prerequisites](#prerequisites)
- [Development Setup](#development-setup)
- [Building the SDK](#building-the-sdk)
- [Testing](#testing)
- [Publishing to NPM](#publishing-to-npm)
- [CI/CD Pipeline](#cicd-pipeline)
- [Troubleshooting](#troubleshooting)

## 📋 Prerequisites

### Required Software
- **Node.js 18+** and npm
- **Git** with push access to the repository
- **NPM account** with publish permissions to `@mindmakr` organization
- **Docker** (for running backend services during testing)

### Environment Setup
```bash
# Verify Node.js version
node --version  # Should be 18+

# Verify npm login
npm whoami  # Should show your npm username

# Verify git configuration
git config --global user.name
git config --global user.email
```

### NPM Organization Access
Ensure you have publish permissions to the `@mindmakr` organization:
```bash
npm org ls mindmakr

# If you don't have access, request it from organization owner
# npm org set mindmakr <username> developer
```

### NPM Authentication
```bash
# Login to npm
npm login

# Verify authentication
npm whoami

# Check organization membership
npm org ls mindmakr

# Test publish permissions (dry run)
npm publish --dry-run
```

## 🔧 Development Setup

### 1. Clone and Setup
```bash
# Clone repository
git clone https://github.com/mindmakr/guru-saas.git
cd guru-saas/gs-websdk

# Install dependencies
npm install

# Start development mode
npm run dev  # Watches for changes and rebuilds
```

### 2. Backend Services Setup
For integration testing, you need backend services running:

```bash
# In the root directory (guru-saas/)
cd ..
npm install
npm run dev  # Starts all backend services

# Verify services are running
curl http://localhost:4000/health    # Auth Service
curl http://localhost:5010/health    # Schema Service
curl http://localhost:4001/health    # AI Service
curl http://localhost:5020/health    # Notification Service
```

## 🏗️ Building the SDK

### Development Build
```bash
# Clean build
rm -rf dist
npm run build

# Verify build output
ls -la dist/
# Should contain: index.js, index.d.ts, *.map files, and service modules
```

### Build Output Structure
```
dist/
├── index.js          # Main SDK bundle
├── index.d.ts        # TypeScript definitions
├── index.js.map      # Source map
├── core/             # Core modules
├── services/         # Service modules
├── types/            # Type definitions
└── utils/            # Utility modules
```

### Documentation Build
```bash
# Build TypeScript API documentation
npm run build:docs

# Serve documentation locally
npm run docs:serve
# Opens http://localhost:8080
```

## 🧪 Testing

### Test Prerequisites
Ensure backend services are running before testing:

```bash
# Check service health
npm run test:health
```

### Test Suites
```bash
# Unit tests only
npm test

# Full integration tests (requires backend)
npm run test:integration

# Specific service tests
npm run test:integration:auth
npm run test:integration:schema
npm run test:integration:ai
npm run test:integration:notification

# Coverage report
npm run test:coverage
```

### Test Validation
```bash
# Validate API alignment with backend
npm run validate

# Run comprehensive test suite
npm run test:run
```

## 📦 Publishing to NPM

### Pre-Publication Checklist

- [ ] All tests pass (`npm test`)
- [ ] Integration tests pass (`npm run test:integration`)
- [ ] API alignment is 100% (`npm run validate`)
- [ ] Build succeeds without errors (`npm run build`)
- [ ] Documentation is up to date
- [ ] Version number follows semantic versioning
- [ ] Git working directory is clean
- [ ] NPM authentication is valid (`npm whoami`)

### Option 1: Automated Release (Recommended)

#### Using Release Scripts
```bash
# Patch release (1.0.0 -> 1.0.1)
npm run release:patch

# Minor release (1.0.0 -> 1.1.0)
npm run release:minor

# Major release (1.0.0 -> 2.0.0)
npm run release:major

# Specific version
npm run release 1.2.3
```

The release script automatically:
- Runs all tests
- Updates version in package.json
- Builds the SDK
- Publishes to NPM
- Creates git tag
- Pushes to repository

#### Using GitHub Actions
1. **Create a release tag:**
   ```bash
   git tag sdk-v1.0.0
   git push origin sdk-v1.0.0
   ```

2. **GitHub Actions will automatically:**
   - Run all tests
   - Build the SDK
   - Publish to NPM
   - Create GitHub release

### Option 2: Manual Release

#### Step-by-Step Process

1. **Prepare for release:**
   ```bash
   # Ensure clean git state
   git status
   git pull origin main
   
   # Run full test suite
   npm test
   npm run test:integration
   npm run validate
   ```

2. **Update version:**
   ```bash
   # Semantic versioning
   npm version patch   # Bug fixes
   npm version minor   # New features
   npm version major   # Breaking changes
   ```

3. **Build and test:**
   ```bash
   npm run build
   npm test
   ```

4. **Publish to NPM:**
   ```bash
   # Dry run first to check what will be published
   npm publish --dry-run

   # Publish to npm (public access for scoped packages)
   npm publish --access public

   # Verify publication
   npm view @mindmakr/gs-websdk
   ```

5. **Create git tag and push:**
   ```bash
   git add .
   git commit -m "Release v$(node -p "require('./package.json').version")"
   git tag sdk-v$(node -p "require('./package.json').version")
   git push origin main --tags
   ```

### Post-Release Verification

```bash
# Verify NPM publication
npm view @mindmakr/gs-websdk

# Check package details
npm view @mindmakr/gs-websdk version
npm view @mindmakr/gs-websdk dist-tags
npm view @mindmakr/gs-websdk files

# Test installation in a new project
mkdir test-install && cd test-install
npm init -y
npm install @mindmakr/gs-websdk

# Test basic import
node -e "console.log(require('@mindmakr/gs-websdk'))"

# Test TypeScript definitions
echo "import { GuruSaaS } from '@mindmakr/gs-websdk';" > test.ts
npx tsc --noEmit test.ts
```

## 📦 Using the Published Package

### For Frontend Developers

Once published, developers can install and use the SDK:

```bash
# Install the SDK
npm install @mindmakr/gs-websdk

# Or with yarn
yarn add @mindmakr/gs-websdk

# Or with pnpm
pnpm add @mindmakr/gs-websdk
```

#### Configuration for Different Environments

**Development (Direct Service Access):**
```typescript
const client = new GuruSaaS({
  authUrl: 'http://localhost:4000',
  globalDataUrl: 'http://localhost:5010',
  aiServiceUrl: 'http://localhost:4001',
  notificationUrl: 'http://localhost:5020',
  debug: true
});
```

**Production (Reverse Proxy):**
```typescript
const client = new GuruSaaS({
  baseUrl: 'https://api.yourdomain.com',
  debug: false
});
```

### Package Information
```bash
# View package information
npm info @mindmakr/gs-websdk

# View all versions
npm view @mindmakr/gs-websdk versions --json

# View latest version
npm view @mindmakr/gs-websdk version

# View package dependencies
npm view @mindmakr/gs-websdk dependencies
```

### CDN Usage
The package is also available via CDN:

```html
<!-- Latest version -->
<script src="https://unpkg.com/@mindmakr/gs-websdk@latest/dist/index.js"></script>

<!-- Specific version -->
<script src="https://unpkg.com/@mindmakr/gs-websdk@1.0.1/dist/index.js"></script>

<!-- With integrity check -->
<script src="https://unpkg.com/@mindmakr/gs-websdk@1.0.1/dist/index.js"
        integrity="sha384-..."
        crossorigin="anonymous"></script>
```

## 🔄 CI/CD Pipeline

### GitHub Actions Workflow

The repository includes automated workflows for:

1. **Continuous Integration**
   - Runs on every push and PR
   - Executes all tests
   - Validates build process

2. **Release Automation**
   - Triggered by version tags
   - Publishes to NPM
   - Creates GitHub releases

### Manual CI Trigger
```bash
# Go to GitHub Actions tab
# Select "Release SDK" workflow
# Click "Run workflow"
# Enter version number (e.g., 1.0.0)
```

### Environment Variables
Required for CI/CD:
- `NPM_TOKEN` - NPM authentication token
- `GITHUB_TOKEN` - GitHub access token (automatically provided)

## 🚨 Troubleshooting

### Common Issues

#### Build Failures
```bash
# Clear cache and rebuild
rm -rf dist node_modules
npm install
npm run build
```

#### Test Failures
```bash
# Ensure backend services are running
cd .. && npm run dev

# Check individual service health
curl http://localhost:4000/health
curl http://localhost:5010/health
curl http://localhost:4001/health
curl http://localhost:5020/health

# Run tests with debug output
DEBUG_TESTS=true npm run test:integration
```

#### NPM Publish Errors
```bash
# Check authentication
npm whoami

# Re-login if needed
npm logout
npm login

# Check package name availability
npm view @mindmakr/gs-websdk

# Verify organization permissions
npm org ls mindmakr
```

#### Version Conflicts
```bash
# Reset version if needed
git checkout package.json
npm version patch --no-git-tag-version
```

### Debug Mode
Enable detailed logging during build/release:

```bash
# Set debug environment
export DEBUG=*
npm run build

# Or for specific operations
DEBUG=sdk:* npm run release:patch
```

## 📊 Release Metrics

### Success Criteria
- ✅ 100% test coverage maintained
- ✅ 100% API alignment verified
- ✅ Zero build warnings/errors
- ✅ Documentation updated
- ✅ Semantic versioning followed

### Monitoring
- NPM download statistics: `npm view @mindmakr/gs-websdk`
- GitHub release metrics
- Issue reports and feedback
- Performance benchmarks

## 🔗 Resources

### Documentation
- [Developer Guide](./DEVELOPER_GUIDE.md)
- [API Reference](./API_REFERENCE.md)
- [Examples](./EXAMPLES.md)

### Tools
- [NPM Package](https://www.npmjs.com/package/@mindmakr/gs-websdk)
- [GitHub Repository](https://github.com/mindmakr/guru-saas)
- [GitHub Actions](https://github.com/mindmakr/guru-saas/actions)

### Support
- [GitHub Issues](https://github.com/mindmakr/guru-saas/issues)
- [Discussions](https://github.com/mindmakr/guru-saas/discussions)

---

**🎉 Ready to release?** Follow the automated release process for the most reliable results!