User Onboarding Guide¶

Welcome to Helomatic! This comprehensive guide will walk you through every step of getting started, from account creation to your first successful API integration.

Onboarding Checklist¶

Track your progress through the onboarding process:

• Account Setup - Create and verify your account
• Authentication - Generate and test API credentials
• First API Call - Make your first successful request
• Choose Integration - Select your primary use case
• Setup Monitoring - Configure your first data source
• Test Webhooks - Receive real-time notifications
• Production Ready - Deploy to your production environment

Step 1: Account Creation¶

Registration Process¶

Create your account through our API or web interface:

graph LR
    A[Start Registration] --> B[Enter Details]
    B --> C[Submit Form]
    C --> D[Email Verification]
    D --> E[Account Activated]
    E --> F[API Access Ready]

    style A fill:#e3f2fd
    style F fill:#c8e6c9

API Registration:

curl -X POST \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your.email@company.com",
    "password": "SecurePassword123!",
    "name": "Your Full Name",
    "company": "Your Company Name",
    "role": "user",
    "acceptTerms": true,
    "enableMFA": false
  }'

Expected Response:

{
  "success": true,
  "data": {
    "user": {
      "id": "usr_1234567890",
      "email": "your.email@company.com", 
      "name": "Your Full Name",
      "company": "Your Company Name",
      "verified": false,
      "created_at": "2025-08-22T18:30:15.123Z"
    },
    "tokens": {
      "access_token": "eyJhbGciOiJIUzI1NiIs...",
      "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
      "expires_in": 3600,
      "token_type": "Bearer"
    }
  },
  "message": "Registration successful. Please verify your email."
}

Email Verification¶

1. Check your email for a verification message from Helomatic
2. Click the verification link in the email
3. Confirm verification by testing an authenticated endpoint

Test Verification:

curl -X GET \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/account/profile \
  -H "Authorization: Bearer <your_access_token>"

Account Security Setup¶

Enable Multi-Factor Authentication (Recommended):

curl -X POST \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/auth/mfa/enable \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "totp",
    "backup_codes": true
  }'

Step 2: Authentication Mastery¶

Understanding JWT Tokens¶

Helomatic uses JWT (JSON Web Tokens) with a two-token system:

graph TB
    A[User Login] --> B[Receive Token Pair]
    B --> C[Access Token<br/>1 hour lifetime]
    B --> D[Refresh Token<br/>30 day lifetime]

    C --> E[API Requests]
    E --> F{Token Valid?}
    F -->|Yes| G[Allow Request]
    F -->|No| H[Token Expired]

    H --> I[Use Refresh Token]
    I --> J[Get New Access Token]
    J --> E

    D --> K{Refresh Expired?}
    K -->|Yes| L[Re-authenticate]
    K -->|No| I

    style C fill:#81c784
    style D fill:#64b5f6
    style H fill:#ffab40
    style L fill:#e57373

Token Management Best Practices¶

Secure Storage:

// ✅ Good - Environment variables
const API_TOKEN = process.env.HELOMATIC_ACCESS_TOKEN;

// ✅ Good - Secure storage in web apps
const secureStorage = {
  setToken(token) {
    // Use secure, HttpOnly cookies or secure storage
    document.cookie = `helomatic_token=${token}; Secure; HttpOnly; SameSite=Strict`;
  }
};

// ❌ Bad - Never expose in client-side code
const API_TOKEN = "eyJhbGciOiJIUzI1NiIs..."; // Don't do this!

Automatic Token Refresh:

class HelomaticClient {
  constructor(accessToken, refreshToken) {
    this.accessToken = accessToken;
    this.refreshToken = refreshToken;
  }

  async makeRequest(endpoint, options = {}) {
    let response = await fetch(endpoint, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.accessToken}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });

    // Handle token expiration
    if (response.status === 401) {
      await this.refreshAccessToken();

      // Retry original request
      response = await fetch(endpoint, {
        ...options,
        headers: {
          'Authorization': `Bearer ${this.accessToken}`,
          'Content-Type': 'application/json',
          ...options.headers
        }
      });
    }

    return response.json();
  }

  async refreshAccessToken() {
    const response = await fetch('/api/auth/refresh', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ refresh_token: this.refreshToken })
    });

    const data = await response.json();
    this.accessToken = data.access_token;
  }
}

Step 3: Your First API Calls¶

Health Check (No Authentication)¶

Start with a simple health check to verify connectivity:

curl https://helomatic-api-prod.ernijs-ansons.workers.dev/health

Expected Response:

{
  "status": "healthy",
  "environment": "production",
  "timestamp": "2025-08-22T18:19:49.258Z",
  "version": "1.0.0"
}

System Status (No Authentication)¶

Get detailed system information:

curl https://helomatic-api-prod.ernijs-ansons.workers.dev/status

User Profile (Authenticated)¶

Test your authentication with a profile request:

curl -X GET \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/account/profile \
  -H "Authorization: Bearer <your_access_token>"

Debugging Authentication Issues¶

Common Issues and Solutions:

1. 401 Unauthorized

   # Check token format (must include 'Bearer ')
   curl -v -H "Authorization: Bearer <token>" <endpoint>
   
   # Verify token hasn't expired
   echo '<token>' | base64 -d | jq .exp
   

2. Token Format Errors

   // ✅ Correct format
   headers: { 'Authorization': 'Bearer ' + accessToken }
   
   // ❌ Common mistakes
   headers: { 'Authorization': accessToken }         // Missing 'Bearer'
   headers: { 'Bearer': accessToken }              // Wrong header name
   headers: { 'Authorization': 'Token ' + accessToken } // Wrong prefix
   

Step 4: Choose Your Integration Path¶

Select the path that best matches your use case:

curl -X POST \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/monitoring/sources \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Price Monitor",
    "url": "https://example-store.com/product/123",
    "schedule": "hourly",
    "extractors": [
      {
        "type": "css",
        "selector": ".price-current",
        "name": "current_price"
      },
      {
        "type": "css", 
        "selector": ".availability",
        "name": "in_stock"
      }
    ]
  }'

curl -X POST \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/ai/chat \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful customer service assistant for an e-commerce platform."
      },
      {
        "role": "user",
        "content": "How do I track my order?"
      }
    ],
    "task": "general",
    "options": {
      "temperature": 0.7,
      "max_tokens": 200
    }
  }'

curl -X POST \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/data/enrichment \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "company": "TechCorp Inc",
      "website": "techcorp.com",
      "email": "contact@techcorp.com"
    },
    "enrichmentType": "company_details",
    "includeConfidence": true
  }'

Step 5: Advanced Configuration¶

Setting Up Webhooks¶

Webhooks provide real-time notifications when events occur:

sequenceDiagram
    participant Helomatic
    participant Your_Server

    Note over Helomatic: Event occurs (price change, AI completion, etc.)

    Helomatic->>Your_Server: POST /webhook
    Note over Helomatic: Includes event data + signature

    Your_Server->>Your_Server: Verify signature
    Your_Server->>Your_Server: Process event
    Your_Server->>Helomatic: 200 OK

    alt Webhook fails
        Helomatic->>Your_Server: Retry after 1s
        Helomatic->>Your_Server: Retry after 5s  
        Helomatic->>Your_Server: Retry after 25s
    end

Webhook Endpoint Implementation:

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.raw({ type: 'application/json' }));

// Webhook signature verification
function verifySignature(rawBody, signature, secret) {
  const expectedSignature = 'sha256=' + 
    crypto.createHmac('sha256', secret)
          .update(rawBody)
          .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

app.post('/webhooks/helomatic', (req, res) => {
  const signature = req.headers['x-helomatic-signature'];
  const secret = process.env.HELOMATIC_WEBHOOK_SECRET;

  if (!verifySignature(req.body, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body.toString());

  // Process different event types
  switch (event.type) {
    case 'monitoring.data_changed':
      handleDataChange(event.data);
      break;
    case 'ai.completion_ready':
      handleAICompletion(event.data);
      break;
    case 'data.enrichment_complete':
      handleEnrichmentComplete(event.data);
      break;
    default:
      console.log('Unknown event type:', event.type);
  }

  res.status(200).send('OK');
});

function handleDataChange(data) {
  console.log('Data changed:', data);
  // Send notification, update database, etc.
}

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

from flask import Flask, request, abort
import hmac
import hashlib
import json

app = Flask(__name__)

def verify_signature(payload, signature, secret):
    expected_signature = 'sha256=' + hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected_signature)

@app.route('/webhooks/helomatic', methods=['POST'])
def helomatic_webhook():
    signature = request.headers.get('X-Helomatic-Signature')
    payload = request.get_data()
    secret = os.getenv('HELOMATIC_WEBHOOK_SECRET')

    if not verify_signature(payload, signature, secret):
        abort(401, 'Invalid signature')

    event = request.get_json()
    event_type = event.get('type')

    if event_type == 'monitoring.data_changed':
        handle_data_change(event['data'])
    elif event_type == 'ai.completion_ready':
        handle_ai_completion(event['data'])
    else:
        print(f'Unknown event type: {event_type}')

    return 'OK', 200

def handle_data_change(data):
    print(f'Data changed: {data}')
    # Process the data change event

if __name__ == '__main__':
    app.run(port=3000)

Environment Setup¶

Development Environment:

# .env file
HELOMATIC_API_URL=https://helomatic-api-prod.ernijs-ansons.workers.dev
HELOMATIC_ACCESS_TOKEN=your_access_token
HELOMATIC_REFRESH_TOKEN=your_refresh_token
HELOMATIC_WEBHOOK_SECRET=your_webhook_secret

# Webhook endpoint (use ngrok for local development)
WEBHOOK_URL=https://your-unique-id.ngrok.io/webhooks/helomatic

Production Checklist: - [ ] Use HTTPS for all webhook endpoints - [ ] Implement proper signature verification - [ ] Set up error handling and retries - [ ] Configure monitoring and alerting - [ ] Test failover scenarios

Step 6: Testing Your Integration¶

Integration Testing Script¶

Create a comprehensive test script:

// integration-test.js
const HelomaticClient = require('./helomatic-client');

async function runIntegrationTests() {
  const client = new HelomaticClient({
    apiUrl: process.env.HELOMATIC_API_URL,
    accessToken: process.env.HELOMATIC_ACCESS_TOKEN
  });

  console.log('🧪 Running Helomatic Integration Tests...\n');

  // Test 1: Health Check
  try {
    const health = await client.health();
    console.log('✅ Health Check:', health.status);
  } catch (error) {
    console.error('❌ Health Check Failed:', error.message);
    return;
  }

  // Test 2: Authentication
  try {
    const profile = await client.getProfile();
    console.log('✅ Authentication:', profile.user.email);
  } catch (error) {
    console.error('❌ Authentication Failed:', error.message);
    return;
  }

  // Test 3: Create Monitoring Source
  try {
    const source = await client.createMonitoringSource({
      name: 'Test Monitor',
      url: 'https://httpbin.org/json',
      schedule: 'daily',
      extractors: [{
        type: 'json',
        selector: '$.url',
        name: 'test_url'
      }]
    });
    console.log('✅ Monitoring Source Created:', source.id);

    // Clean up
    await client.deleteMonitoringSource(source.id);
  } catch (error) {
    console.error('❌ Monitoring Test Failed:', error.message);
  }

  // Test 4: AI Chat
  try {
    const response = await client.chat({
      messages: [
        { role: 'user', content: 'Hello, this is a test message.' }
      ],
      task: 'general'
    });
    console.log('✅ AI Chat:', response.response.content.substring(0, 50) + '...');
  } catch (error) {
    console.error('❌ AI Chat Failed:', error.message);
  }

  console.log('\n🎉 Integration tests completed!');
}

runIntegrationTests().catch(console.error);

Run the tests:

node integration-test.js

Load Testing¶

Test your integration under load:

# Install artillery for load testing
npm install -g artillery

# Create load test configuration
cat > load-test.yml << EOF
config:
  target: 'https://helomatic-api-prod.ernijs-ansons.workers.dev'
  phases:
    - duration: 60
      arrivalRate: 10
  defaults:
    headers:
      Authorization: 'Bearer YOUR_ACCESS_TOKEN'
      Content-Type: 'application/json'

scenarios:
  - name: 'Health Check Load Test'
    weight: 50
    flow:
      - get:
          url: '/health'

  - name: 'API Load Test'
    weight: 50
    flow:
      - get:
          url: '/api/monitoring/sources'
EOF

# Run load test
artillery run load-test.yml

Step 7: Production Deployment¶

Pre-Deployment Checklist¶

• Security Review
• API keys stored securely
• HTTPS enforced for all endpoints
• Webhook signature verification implemented

• Rate limiting handled gracefully

• Monitoring Setup

• Application performance monitoring
• Error tracking and alerting
• Webhook delivery monitoring

• Usage tracking and budgets

• Documentation

• Team onboarding documentation
• API integration documentation
• Troubleshooting guides
• Emergency contact procedures

Production Configuration¶

Environment Variables:

# Production .env
NODE_ENV=production
HELOMATIC_API_URL=https://helomatic-api-prod.ernijs-ansons.workers.dev
HELOMATIC_ACCESS_TOKEN=prod_access_token
HELOMATIC_REFRESH_TOKEN=prod_refresh_token
HELOMATIC_WEBHOOK_SECRET=secure_webhook_secret

# Monitoring
SENTRY_DSN=your_sentry_dsn
NEW_RELIC_LICENSE_KEY=your_newrelic_key

# Scaling
MAX_CONCURRENT_REQUESTS=100
RATE_LIMIT_BUFFER=0.8

Health Check Endpoint:

// Add health check for your integration
app.get('/health', (req, res) => {
  res.json({
    status: 'healthy',
    timestamp: new Date().toISOString(),
    helomatic: {
      connected: helomaticClient.isConnected(),
      last_request: helomaticClient.lastRequestTime,
      token_expires: helomaticClient.tokenExpiresAt
    }
  });
});

Monitoring and Alerting¶

Set up monitoring for: - API response times and error rates - Webhook delivery success rates - Token refresh patterns - Usage against rate limits - Business metrics (data changes, AI usage)

Alert Thresholds:

# Example monitoring configuration
alerts:
  - name: "Helomatic API Errors"
    condition: "error_rate > 5%"
    duration: "5m"
    action: "email_team"

  - name: "Rate Limit Approaching"
    condition: "usage_rate > 80%"
    duration: "1m" 
    action: "slack_notification"

  - name: "Webhook Failures"
    condition: "webhook_failure_rate > 10%"
    duration: "5m"
    action: "page_oncall"

Troubleshooting Common Issues¶

Authentication Problems¶

Issue: "Invalid token" errors

# Debug token format
echo $HELOMATIC_ACCESS_TOKEN | cut -d'.' -f2 | base64 -d | jq

# Check expiration
node -e "
  const token = process.env.HELOMATIC_ACCESS_TOKEN;
  const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64'));
  console.log('Expires:', new Date(payload.exp * 1000));
  console.log('Expired:', payload.exp < Date.now() / 1000);
"

Solution:

// Implement automatic token refresh
async function makeAuthenticatedRequest(endpoint, options) {
  let response = await fetch(endpoint, {
    ...options,
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      ...options.headers
    }
  });

  if (response.status === 401) {
    // Token expired, refresh it
    await refreshAccessToken();

    // Retry request with new token
    response = await fetch(endpoint, {
      ...options,
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        ...options.headers
      }
    });
  }

  return response;
}

Rate Limiting Issues¶

Issue: Hitting rate limits frequently

Solution: Implement exponential backoff

async function makeRequestWithBackoff(endpoint, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(endpoint, options);

    if (response.status !== 429) {
      return response;
    }

    // Rate limited, wait and retry
    const retryAfter = response.headers.get('X-Ratelimit-Retry-After');
    const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, attempt) * 1000;

    console.log(`Rate limited, waiting ${waitTime}ms before retry ${attempt + 1}`);
    await new Promise(resolve => setTimeout(resolve, waitTime));
  }

  throw new Error('Max retries exceeded');
}

Webhook Issues¶

Issue: Webhooks not being received

Debug Steps: 1. Verify webhook URL is publicly accessible

curl -X POST https://your-domain.com/webhooks/helomatic \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

1. Check webhook signature verification

   // Log signatures for debugging
   app.post('/webhooks/helomatic', (req, res) => {
     const signature = req.headers['x-helomatic-signature'];
     console.log('Received signature:', signature);
     console.log('Computed signature:', computeSignature(req.body));
     // ... rest of handler
   });
   

2. Test with webhook delivery tool

   # Use webhook.site for testing
   curl -X POST \
     https://helomatic-api-prod.ernijs-ansons.workers.dev/api/monitoring/sources \
     -d '{"webhookUrl": "https://webhook.site/your-unique-url"}'
   

Next Steps¶

Congratulations! You've successfully completed the Helomatic onboarding process. Here are your next steps:

Immediate Actions¶

1. Join our community - Discord Server
2. Follow our blog - Stay updated on new features
3. Set up monitoring - Track your integration health
4. Explore advanced features - Check out our feature documentation

Learning Resources¶

• API Reference - Complete endpoint documentation
• Security Guide - Best practices and compliance
• Integration Examples - Real-world code samples
• Troubleshooting Guide - Common issues and solutions

Support Channels¶

• 📧 Email: support@helomatic.com
• 💬 Live Chat: Available on our website
• 🐛 Bug Reports: GitHub Issues
• 📚 Documentation: docs.helomatic.com

🎉 Welcome to Helomatic! You're now ready to build amazing integrations. If you have any questions during your journey, our team is here to help.