Server Core Utilities
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 (statusand the parsedbodyare on the error) or a network errortimeout: no answer withinoptions.timeoutconfig: 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
keywhen 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.