Skip to main content
Ask your AI

Server Core Utilities

Server Source code Package

Server core utilities are Node.js-specific functions designed for server-side walkerOS implementations. These utilities handle server communication, cryptographic hashing, and other backend operations.

Installation​

Import server utilities from the @walkeros/server-core package:

import { sendServer, getHashServer } from '@walkeros/server-core';

Server communication​

sendServer​

sendServer(url: string, data?: SendDataValue, options?: SendServerOptions): Promise<SendResponse> sends HTTP requests with the global fetch. It resolves { data } for a 2xx answer, with the body parsed as JSON where it parses, and throws a StepError otherwise (see Error handling).

// Simple POST request
const response = await sendServer('https://api.example.com/events', {
  name: 'page view',
  data: { url: '/home' },
});

// With custom options
const response = await sendServer(url, data, {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer token',
    'Content-Type': 'application/json',
  },
  timeout: 10000, // 10 seconds
});

console.log('Response body:', response.data);

SendServerOptions​

interface SendServerOptions {
  headers?: Record<string, string>; // Custom HTTP headers
  method?: string; // HTTP method (default: 'POST')
  timeout?: number; // Request timeout in milliseconds (default: 5000)
}

Headers merge into the default Content-Type: application/json; charset=utf-8. A GET or HEAD request sends no body.

SendResponse​

interface SendResponse {
  data?: unknown; // Response body, parsed as JSON where it parses
}

Cryptographic operations​

getHashServer​

getHashServer(str: string, length?: number, options?: { algorithm?: 'sha256' | 'md5'; key?: string }): Promise<string> generates hex hashes using the Node.js crypto module. The algorithm defaults to sha256; pass { algorithm: 'md5' } for an MD5 digest. With key, the hash is an HMAC and cannot be recomputed without that key.

// Full SHA-256 hash
await getHashServer('user123@example.com');
// Returns the full 64-character hash

// Shortened hash
await getHashServer('user123@example.com', 16);
// Returns '865c4dd20427a134'

// HMAC with a secret key
await getHashServer('user123@example.com', 16, { key: process.env.HASH_KEY });

Error handling​

sendServer throws a StepError from @walkeros/core when a request does not succeed. Its code says why:

  • transport: a non-2xx answer (status and the parsed body are on the error) or a network error
  • timeout: no answer within options.timeout
  • config: the URL is not a valid absolute URL

The body stays on the error, never in its message.

import { StepError } from '@walkeros/core';

try {
  const response = await sendServer(url, data, { timeout: 5000 });
  console.log('Success:', response.data);
} catch (error) {
  if (error instanceof StepError) {
    console.error('Send failed:', error.code, error.status);
  }
}

Inside a destination, let the error propagate: the collector reports the failed push (see Failure lines).

Connection reuse​

Node's built-in fetch keeps connections open and reuses them for requests to the same host.

Security notes​

  • Use HTTPS URLs in production for encrypted transmission.
  • Store sensitive credentials in environment variables.
  • Set reasonable timeouts to prevent hanging requests.
  • Pass a secret key when hashing sensitive data.
// Good security practices
const apiKey = process.env.ANALYTICS_API_KEY;
const keyedHash = await getHashServer(userData, undefined, {
  key: process.env.HASH_KEY,
});

await sendServer('https://secure-api.example.com/events', data, {
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  timeout: 5000,
});

Integration with Core​

Server utilities combine with Core Utilities:

import { getMappingValue, anonymizeIP } from '@walkeros/core';
import { sendServer, getHashServer } from '@walkeros/server-core';

// collector: the running collector, from startFlow or a step's context
async function processServerSideEvent(rawEvent, clientIP, collector) {
  // Use core utilities for data processing
  const processedData = await getMappingValue(rawEvent, mappingConfig, {
    collector,
  });
  const safeIP = anonymizeIP(clientIP);

  // Use server utilities for transmission
  const sessionId = await getHashServer(`${safeIP}${userAgent}`, 16, {
    key: process.env.HASH_KEY,
  });

  return await sendServer(endpoint, {
    ...processedData,
    sessionId,
    ip: safeIP,
  });
}

For platform-agnostic utilities, see Core Utilities.

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)