Headless Mode

Headless mode enables server-side and CLI execution of RowOps pipelines without a browser environment. This page describes the invocation model, license modes, and operational constraints.

Headless execution is implemented and actively used, but evolving.

---

Invocation Model

Initialization

import { initHeadless } from '@rowops/headless';

await initHeadless({
  projectId: "proj_123",
  secretKey: "sk_live_...",
  endpoint: "https://api.rowops.dev/api/license/verify",
  licenseMode: "strict",
});

import { initHeadless } from '@rowops/headless';

await initHeadless({
  projectId: "proj_123",
  entitlementToken: process.env.ROWOPS_ENTITLEMENT_TOKEN!,
  licenseMode: "strict",
});

Required Parameters

Parameter	Description
projectId	Project identifier from dashboard
secretKey	Secret API key (required unless entitlementToken is provided)

Optional Parameters

Parameter	Default	Description
endpoint	https://api.rowops.dev/api/license/verify	License verification endpoint (full URL)
licenseMode	strict	License enforcement behavior
entitlementToken	undefined	Signed token for offline verification (skips network exchange)
wasmPath	undefined	Explicit WASM path override (Node/containers)
wasmBytes	undefined	Explicit WASM bytes (edge/serverless)
fileAdapter	undefined	File adapter for cache + WASM resolution

Use wasmBytes with a custom fileAdapter in edge/serverless environments to avoid filesystem resolution.

Authentication Flow

1. If entitlementToken is provided, verify it locally using the public key
2. Otherwise, validate secret key format and call /api/license/verify
3. Tier and feature limits derived from the verified token
4. Processing engine initialized with tier gate configuration

---

License Modes

Strict Mode (Default)

licenseMode: 'strict'

• Verified entitlements required before pipeline execution
• Invalid or expired token falls back to Free tier
• Network exchange required only when entitlementToken is not provided

Demo Mode

licenseMode: 'demo'

• Skips license verification
• 100-row limit enforced
• Watermark applied to exports
• Suitable for testing and development

Network Dependencies

Required (Strict Mode)

Endpoint	Purpose
/api/license/verify	License and tier verification (when using secretKey)

Optional

Endpoint	Purpose
Sync targets	User-configured delivery endpoints
Webhook endpoints	Event notification delivery

Network-Free Usage

Provide a signed entitlementToken to run in strict mode without network access. Demo mode remains available with a 100-row limit and watermarking.

---

Observed Behavior

Design Intent

The pipeline aims to produce deterministic results given identical inputs, schema, and configuration. This supports replay scenarios where the same file can be re-processed to yield the same results.

Fail-Closed on Errors

In tested paths:

• Masking failures throw MaskingFailedError and halt execution
• Transform failures throw TransformFailedError and halt execution
• No partial results are produced on failure

Constraints

• Row-filtering transforms are explicitly disallowed in headless mode
• Determinism and fail-closed behavior are not asserted as universal guarantees across all modules and configurations
• Some operations may behave differently than browser mode

---

What Headless Mode Does Not Provide

• UI components: No React components or visual interface
• Domain locking: Secret keys are not domain-restricted
• Session management: No user sessions or authentication state
• Browser APIs: No DOM or browser-specific APIs
• Guaranteed determinism: Determinism is a design goal, not a verified property

---

Error Handling

Initialization Errors

Error	Cause
Invalid secret key format	Key does not start with sk_
License verification failed	Network error or invalid credentials
Engine initialization failed	Configuration error

Pipeline Errors

Error Type	Behavior
MaskingFailedError	Pipeline halts, no fallback
TransformFailedError	Pipeline halts, no fallback
Validation errors	Rows marked invalid, pipeline continues
Parse errors	Pipeline halts with parse error