@xdelivered/emberflow 0.2.0

package/src/nodes/requireAuth.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest';
+import { createDefaultRegistry } from './index';
+import { isHttpError } from '../engine';
+
+describe('requireAuth node', () => {
+  it('is registered with type requireAuth', () => {
+    expect(createDefaultRegistry().get('requireAuth').definition.type).toBe('requireAuth');
+  });
+
+  it('returns { user } for a valid bearer token', async () => {
+    const impl = createDefaultRegistry().get('requireAuth').implementation;
+    const ctx = {
+      input: { headers: { authorization: 'Bearer good' } },
+      config: { scheme: 'bearer', secretRef: 'T' },
+      secrets: { T: 'good' },
+      vars: {},
+      safeMode: false,
+      runInput: {},
+      log: () => {},
+    } as never;
+    expect(await impl(ctx)).toEqual({ user: { scheme: 'bearer' } });
+  });
+
+  it('throws HttpError 401 for a missing/wrong token', async () => {
+    const impl = createDefaultRegistry().get('requireAuth').implementation;
+    const ctx = {
+      input: { headers: {} },
+      config: { scheme: 'bearer', secretRef: 'T' },
+      secrets: { T: 'good' },
+      vars: {},
+      safeMode: false,
+      runInput: {},
+      log: () => {},
+    } as never;
+    try {
+      await impl(ctx);
+      expect.unreachable();
+    } catch (e) {
+      expect(isHttpError(e) && e.status).toBe(401);
+    }
+  });
+
+  it('throws HttpError 500 when the secret is unset (fail closed)', async () => {
+    const impl = createDefaultRegistry().get('requireAuth').implementation;
+    const ctx = {
+      input: { headers: { authorization: 'Bearer x' } },
+      config: { scheme: 'bearer', secretRef: 'T' },
+      secrets: {},
+      vars: {},
+      safeMode: false,
+      runInput: {},
+      log: () => {},
+    } as never;
+    try {
+      await impl(ctx);
+      expect.unreachable();
+    } catch (e) {
+      expect(isHttpError(e) && e.status).toBe(500);
+    }
+  });
+
+  it('supports the apiKey scheme with a custom header', async () => {
+    const impl = createDefaultRegistry().get('requireAuth').implementation;
+    const ctx = {
+      input: { headers: { 'x-svc-key': 'k' } },
+      config: { scheme: 'apiKey', secretRef: 'K', header: 'x-svc-key' },
+      secrets: { K: 'k' },
+      vars: {},
+      safeMode: false,
+      runInput: {},
+      log: () => {},
+    } as never;
+    expect(await impl(ctx)).toEqual({ user: { scheme: 'apiKey' } });
+  });
+});

package/src/nodes/requireAuth.ts

@@ -0,0 +1,55 @@
+import type { NodeRegistry } from '../engine';
+import { createDefaultVerifierRegistry, enforceAuth } from '../engine';
+import type { AuthPolicy } from '../engine';
+
+/**
+ * Explicit in-flow auth check. Config carries the AuthPolicy fields (scheme,
+ * secretRef, verify?, header?). Reads the request off ctx.input (the
+ * operation's incoming { headers, ... }) and the secret off ctx.secrets,
+ * then reuses the same enforceAuth() the HTTP handler runs before the
+ * operation body (server/httpOperations.ts via server/auth/enforce.ts) so
+ * there is a single verify code path.
+ *
+ * Browser-safe: uses only src/engine (no server/ import), since src/nodes is
+ * bundled into the studio browser build (src/store/builderStore.ts). Custom
+ * verifiers registered server-side via project.registerVerifiers are a
+ * server-enforcement concern; this node only has the default bearer/apiKey
+ * verifiers (unless policy.verify happens to name one of those).
+ *
+ * Pure-read: throws HttpError(401/500) on failure, otherwise returns
+ * { user } for downstream nodes to see. No side effects, so no
+ * `effects: 'mutation'`.
+ */
+export function registerRequireAuthNode(registry: NodeRegistry): void {
+  registry.register(
+    {
+      type: 'requireAuth',
+      label: 'Require Auth',
+      description:
+        'Verifies the incoming request against an auth policy (bearer/apiKey shared-secret, or a named custom verifier) and attaches { user } for downstream nodes. Throws HttpError(401) on failure, HttpError(500) if misconfigured.',
+      simpleDescription: 'Checks the request is authorized before continuing',
+      category: 'http',
+      traceKind: 'compute',
+      tags: ['http', 'auth'],
+      configSchema: {
+        fields: [
+          { name: 'scheme', type: 'string' },
+          { name: 'secretRef', type: 'string' },
+          { name: 'verify', type: 'string' },
+          { name: 'header', type: 'string' },
+        ],
+      },
+      outputSchema: {
+        fields: [{ name: 'user', type: 'object' }],
+      },
+    },
+    async (ctx) => {
+      const policy = ctx.config as unknown as AuthPolicy;
+      const input = (ctx.input ?? {}) as { headers?: Record<string, unknown> };
+      const request = { headers: input.headers ?? {} };
+      const verifiers = createDefaultVerifierRegistry();
+      const { user } = enforceAuth({ policy, request, secrets: ctx.secrets, verifiers });
+      return { user };
+    },
+  );
+}

package/src/nodes/response.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { createDefaultRegistry } from './index';
+
+describe('Response node', () => {
+  it('is registered with type Response', () => {
+    expect(createDefaultRegistry().get('Response').definition.type).toBe('Response');
+  });
+
+  it('passes { status, body } through, defaulting status to 200', async () => {
+    const impl = createDefaultRegistry().get('Response').implementation;
+    const ctx = {
+      input: { body: { ok: true } },
+      config: {},
+      secrets: {},
+      vars: {},
+      safeMode: false,
+      runInput: {},
+      log: () => {},
+    } as never;
+    expect(await impl(ctx)).toEqual({ status: 200, body: { ok: true } });
+
+    const ctx2 = {
+      input: { status: 201, body: { id: 1 } },
+      config: {},
+      secrets: {},
+      vars: {},
+      safeMode: false,
+      runInput: {},
+      log: () => {},
+    } as never;
+    expect(await impl(ctx2)).toEqual({ status: 201, body: { id: 1 } });
+  });
+});

package/src/nodes/response.ts

@@ -0,0 +1,39 @@
+import type { NodeRegistry } from '../engine';
+
+/**
+ * Terminal node for an HTTP operation: its input `{ status, body }` becomes
+ * the HTTP response `extractResponse` (server/operationResult.ts) maps onto
+ * the wire. `status` defaults to 200 when the input omits it. Pure — no
+ * side effects, so no `effects: 'mutation'` declaration.
+ */
+export function registerResponseNodes(registry: NodeRegistry): void {
+  registry.register(
+    {
+      type: 'Response',
+      label: 'Response',
+      description:
+        'Terminal node for an HTTP operation: its input { status, body } becomes the HTTP response. Omit status to default to 200.',
+      simpleDescription: 'Shapes the HTTP response for this operation',
+      category: 'http',
+      traceKind: 'compute',
+      tags: ['http'],
+      inputSchema: {
+        fields: [
+          { name: 'status', type: 'number' },
+          { name: 'body', type: 'object' },
+        ],
+      },
+      outputSchema: {
+        fields: [
+          { name: 'status', type: 'number' },
+          { name: 'body', type: 'object' },
+        ],
+      },
+    },
+    async (ctx) => {
+      const input = (ctx.input ?? {}) as { status?: unknown; body?: unknown };
+      const status = typeof input.status === 'number' ? input.status : 200;
+      return { status, body: input.body };
+    },
+  );
+}

package/src/nodes/traceDetail.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import { createDefaultRegistry } from './index';
+
+/**
+ * traceDetail is a STATIC, honest descriptor of the concrete call each db/http/llm
+ * node makes — the "what it calls" line in the runbook trace-badge hover card.
+ * These assertions prove honesty (real table names, HTTP verbs, provider/model)
+ * without pinning brittle exact strings.
+ */
+describe('node traceDetail annotations', () => {
+  const registry = createDefaultRegistry();
+  const detail = (type: string): string | undefined => registry.get(type).definition.traceDetail;
+
+  it('every db/http/llm node carries a non-empty traceDetail; compute nodes carry none', () => {
+    for (const def of registry.list()) {
+      if (def.traceKind === 'db' || def.traceKind === 'http' || def.traceKind === 'llm') {
+        expect(def.traceDetail, `${def.type} should have traceDetail`).toBeTruthy();
+        expect(def.traceDetail!.trim().length).toBeGreaterThan(0);
+      }
+      if (def.traceKind === 'compute') {
+        expect(def.traceDetail, `${def.type} (compute) should have no traceDetail`).toBeUndefined();
+      }
+    }
+  });
+
+  it('http nodes name the HTTP verb and endpoint', () => {
+    // Real anomaly service.
+    expect(detail('DetectLastPoint')).toMatch(/POST/);
+    expect(detail('DetectLastPoint')).toMatch(/timeseries\/last\/detect/);
+
+    // Open-Meteo public API.
+    expect(detail('GeocodeCity')).toMatch(/open-meteo\.com/);
+
+    // Simulated senders name the endpoint they represent AND flag the simulation.
+    expect(detail('EvNotify')).toMatch(/ntfy\.sh/);
+    expect(detail('EvNotify')).toMatch(/SIMULATED/i);
+  });
+
+});

package/src/nodes/weather.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+import { buildAdvisory, classifyWeather, describeWeatherCode } from './weather';
+import { createDefaultRegistry } from './index';
+import { createWeatherFlow } from '../flows/weather-flow';
+import { validateFlow } from '../engine';
+
+describe('weather advisory logic', () => {
+  it('maps weather codes to descriptions', () => {
+    expect(describeWeatherCode(0)).toBe('clear sky');
+    expect(describeWeatherCode(63)).toBe('rain');
+    expect(describeWeatherCode(1234)).toContain('unknown');
+  });
+
+  it('advises umbrella on high rain chance and warmth on cold', () => {
+    const advisory = buildAdvisory({
+      place: 'Belfast', temperatureC: 3, windKmh: 35, weatherCode: 61,
+      maxC: 6, minC: 1, rainChancePct: 80,
+    });
+    expect(advisory.advice).toContain('umbrella');
+    expect(advisory.advice).toContain('wind');
+    expect(advisory.advice).toContain('warm');
+    expect(advisory.headline).toBe('Belfast: 3°C, light rain');
+  });
+
+  it('gives the all-clear on mild conditions', () => {
+    const advisory = buildAdvisory({
+      place: 'Nice', temperatureC: 21, windKmh: 8, weatherCode: 0,
+      maxC: 24, minC: 16, rainChancePct: 5,
+    });
+    expect(advisory.advice).toBe('no precautions needed');
+  });
+});
+
+describe('classifyWeather severity', () => {
+  it('flags severe on gale-strength wind (≥ 40 km/h)', () => {
+    const result = classifyWeather(45, 10);
+    expect(result.severity).toBe('severe');
+    expect(result.reason).toContain('wind');
+  });
+
+  it('flags severe on high rain chance (≥ 70%)', () => {
+    const result = classifyWeather(12, 85);
+    expect(result.severity).toBe('severe');
+    expect(result.reason).toContain('rain');
+  });
+
+  it('grades calm conditions as mild', () => {
+    expect(classifyWeather(15, 20).severity).toBe('mild');
+    // Boundaries are exclusive below the thresholds.
+    expect(classifyWeather(39, 69).severity).toBe('mild');
+  });
+});
+
+describe('weather flow', () => {
+  it('registers the weather nodes alongside the login set', () => {
+    const types = createDefaultRegistry(0).list().map((d) => d.type);
+    expect(types).toEqual(
+      expect.arrayContaining(['GeocodeCity', 'FetchForecast', 'SummarizeConditions', 'Result', 'ValidateCredentials']),
+    );
+  });
+
+  it('validates cleanly against the default registry', () => {
+    expect(validateFlow(createWeatherFlow(), createDefaultRegistry(0))).toEqual([]);
+  });
+});

package/src/nodes/weather.ts

@@ -0,0 +1,306 @@
+import type { NodeRegistry } from '../engine';
+
+const WEATHER_CODES: Record<number, string> = {
+  0: 'clear sky',
+  1: 'mainly clear',
+  2: 'partly cloudy',
+  3: 'overcast',
+  45: 'fog',
+  48: 'rime fog',
+  51: 'light drizzle',
+  53: 'drizzle',
+  55: 'dense drizzle',
+  61: 'light rain',
+  63: 'rain',
+  65: 'heavy rain',
+  71: 'light snow',
+  73: 'snow',
+  75: 'heavy snow',
+  80: 'rain showers',
+  81: 'rain showers',
+  82: 'violent rain showers',
+  95: 'thunderstorm',
+  96: 'thunderstorm with hail',
+  99: 'thunderstorm with heavy hail',
+};
+
+export function describeWeatherCode(code: number): string {
+  return WEATHER_CODES[code] ?? `unknown conditions (code ${code})`;
+}
+
+export interface AdvisoryInput {
+  place: string;
+  temperatureC: number;
+  windKmh: number;
+  weatherCode: number;
+  maxC: number;
+  minC: number;
+  rainChancePct: number;
+}
+
+export function buildAdvisory(input: AdvisoryInput) {
+  const condition = describeWeatherCode(input.weatherCode);
+  const advice: string[] = [];
+  if (input.rainChancePct >= 50) advice.push('take an umbrella');
+  if (input.windKmh >= 30) advice.push('expect strong wind');
+  if (input.temperatureC <= 5) advice.push('dress warm');
+  if (input.temperatureC >= 28) advice.push('stay hydrated');
+  if (advice.length === 0) advice.push('no precautions needed');
+
+  return {
+    place: input.place,
+    temperatureC: input.temperatureC,
+    condition,
+    headline: `${input.place}: ${Math.round(input.temperatureC)}°C, ${condition}`,
+    range: `${Math.round(input.minC)}–${Math.round(input.maxC)}°C today, ${Math.round(input.rainChancePct)}% rain chance`,
+    advice: advice.join('; '),
+  };
+}
+
+export type WeatherSeverity = 'severe' | 'mild';
+
+/**
+ * Pure severity rule: severe when wind is at gale strength (≥ 40 km/h) or rain
+ * is likely (≥ 70% chance), otherwise mild.
+ */
+export function classifyWeather(windKmh: number, rainChancePct: number): {
+  severity: WeatherSeverity;
+  reason: string;
+} {
+  if (windKmh >= 40) {
+    return { severity: 'severe', reason: `high winds at ${Math.round(windKmh)} km/h` };
+  }
+  if (rainChancePct >= 70) {
+    return { severity: 'severe', reason: `${Math.round(rainChancePct)}% chance of rain` };
+  }
+  return {
+    severity: 'mild',
+    reason: `winds ${Math.round(windKmh)} km/h, ${Math.round(rainChancePct)}% rain chance`,
+  };
+}
+
+/**
+ * Real-infrastructure nodes backed by the Open-Meteo public APIs
+ * (keyless, CORS-enabled): geocoding + weather forecast.
+ */
+export function registerWeatherNodes(registry: NodeRegistry): void {
+  registry.register(
+    {
+      type: 'GeocodeCity',
+      label: 'Geocode City',
+      description: 'Resolves a city name to coordinates via the Open-Meteo geocoding API.',
+      category: 'http',
+      traceKind: 'http',
+      traceDetail: 'GET https://geocoding-api.open-meteo.com/v1/search?name={city}&count=1',
+      // city is input-drivable (e.g. from an Input node); config is the fallback.
+      inputSchema: {
+        fields: [{ name: 'city', type: 'string' }],
+      },
+      configSchema: {
+        fields: [{ name: 'city', type: 'string', required: true }],
+      },
+      outputSchema: {
+        fields: [
+          { name: 'place', type: 'string' },
+          { name: 'country', type: 'string' },
+          { name: 'latitude', type: 'number' },
+          { name: 'longitude', type: 'number' },
+        ],
+      },
+    },
+    async (ctx) => {
+      const city = String(ctx.input.city ?? '');
+      if (!city) throw new Error('No city configured');
+      const url = `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(city)}&count=1`;
+      ctx.log('info', `GET ${url}`);
+      const response = await fetch(url);
+      if (!response.ok) throw new Error(`Geocoding failed: HTTP ${response.status}`);
+      const data = (await response.json()) as {
+        results?: Array<{ name: string; country: string; latitude: number; longitude: number }>;
+      };
+      const hit = data.results?.[0];
+      if (!hit) throw new Error(`No location found for "${city}"`);
+      ctx.log('info', `Resolved ${hit.name}, ${hit.country} → ${hit.latitude}, ${hit.longitude}`);
+      return {
+        place: hit.name,
+        country: hit.country,
+        latitude: hit.latitude,
+        longitude: hit.longitude,
+      };
+    },
+  );
+
+  registry.register(
+    {
+      type: 'FetchForecast',
+      label: 'Fetch Forecast',
+      description: 'Fetches live current conditions and today’s outlook from the Open-Meteo forecast API.',
+      category: 'http',
+      traceKind: 'http',
+      traceDetail:
+        'GET https://api.open-meteo.com/v1/forecast?latitude&longitude&current=temperature_2m,wind_speed_10m,weather_code&daily=…&forecast_days=1',
+      inputSchema: {
+        fields: [
+          { name: 'latitude', type: 'number', required: true },
+          { name: 'longitude', type: 'number', required: true },
+        ],
+      },
+      outputSchema: {
+        fields: [
+          { name: 'temperatureC', type: 'number' },
+          { name: 'windKmh', type: 'number' },
+          { name: 'weatherCode', type: 'number' },
+          { name: 'maxC', type: 'number' },
+          { name: 'minC', type: 'number' },
+          { name: 'rainChancePct', type: 'number' },
+        ],
+      },
+    },
+    async (ctx) => {
+      const latitude = Number(ctx.input.latitude);
+      const longitude = Number(ctx.input.longitude);
+      if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) {
+        throw new Error('latitude/longitude missing or not numbers');
+      }
+      const url =
+        `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}` +
+        '&current=temperature_2m,wind_speed_10m,weather_code' +
+        '&daily=temperature_2m_max,temperature_2m_min,precipitation_probability_max' +
+        '&timezone=auto&forecast_days=1';
+      ctx.log('info', `GET ${url}`);
+      const response = await fetch(url);
+      if (!response.ok) throw new Error(`Forecast failed: HTTP ${response.status}`);
+      const data = (await response.json()) as {
+        current: { temperature_2m: number; wind_speed_10m: number; weather_code: number };
+        daily: {
+          temperature_2m_max: number[];
+          temperature_2m_min: number[];
+          precipitation_probability_max: Array<number | null>;
+        };
+      };
+      const output = {
+        temperatureC: data.current.temperature_2m,
+        windKmh: data.current.wind_speed_10m,
+        weatherCode: data.current.weather_code,
+        maxC: data.daily.temperature_2m_max[0],
+        minC: data.daily.temperature_2m_min[0],
+        rainChancePct: data.daily.precipitation_probability_max[0] ?? 0,
+      };
+      ctx.log('info', `Now ${output.temperatureC}°C, wind ${output.windKmh} km/h, code ${output.weatherCode}`);
+      return output;
+    },
+  );
+
+  registry.register(
+    {
+      type: 'SummarizeConditions',
+      label: 'Summarize Conditions',
+      description: 'Turns raw forecast numbers into a readable weather advisory.',
+      category: 'logic',
+      traceKind: 'compute',
+      inputSchema: {
+        fields: [
+          { name: 'place', type: 'string', required: true },
+          { name: 'temperatureC', type: 'number', required: true },
+          { name: 'windKmh', type: 'number', required: true },
+          { name: 'weatherCode', type: 'number', required: true },
+          { name: 'maxC', type: 'number' },
+          { name: 'minC', type: 'number' },
+          { name: 'rainChancePct', type: 'number' },
+        ],
+      },
+      outputSchema: {
+        fields: [
+          { name: 'headline', type: 'string' },
+          { name: 'range', type: 'string' },
+          { name: 'advice', type: 'string' },
+          { name: 'place', type: 'string' },
+          { name: 'temperatureC', type: 'number' },
+          { name: 'condition', type: 'string' },
+        ],
+      },
+    },
+    async (ctx) => {
+      const advisory = buildAdvisory({
+        place: String(ctx.input.place ?? 'Unknown'),
+        temperatureC: Number(ctx.input.temperatureC),
+        windKmh: Number(ctx.input.windKmh),
+        weatherCode: Number(ctx.input.weatherCode),
+        maxC: Number(ctx.input.maxC ?? ctx.input.temperatureC),
+        minC: Number(ctx.input.minC ?? ctx.input.temperatureC),
+        rainChancePct: Number(ctx.input.rainChancePct ?? 0),
+      });
+      ctx.log('info', advisory.headline);
+      ctx.log('info', `Advice: ${advisory.advice}`);
+      return advisory;
+    },
+  );
+
+  registry.register(
+    {
+      type: 'ClassifyWeather',
+      label: 'Classify Weather',
+      description: 'Grades conditions as severe or mild from wind and rain thresholds.',
+      category: 'logic',
+      traceKind: 'compute',
+      tags: ['branching'],
+      inputSchema: {
+        fields: [
+          { name: 'windKmh', type: 'number', required: true },
+          { name: 'rainChancePct', type: 'number', required: true },
+          // Optional passthrough so fan-out consumers (e.g. a Collect
+          // gathering one verdict per city) keep the place name attached.
+          { name: 'place', type: 'string' },
+        ],
+      },
+      outputSchema: {
+        fields: [
+          { name: 'severity', type: 'enum', enumValues: ['severe', 'mild'] },
+          { name: 'reason', type: 'string' },
+          { name: 'place', type: 'string' },
+        ],
+      },
+    },
+    async (ctx) => {
+      const { severity, reason } = classifyWeather(
+        Number(ctx.input.windKmh),
+        Number(ctx.input.rainChancePct),
+      );
+      ctx.log('info', `Severity ${severity}: ${reason}`);
+      return {
+        severity,
+        reason,
+        ...(ctx.input.place !== undefined ? { place: ctx.input.place } : {}),
+      };
+    },
+  );
+
+  registry.register(
+    {
+      type: 'ComposeAlert',
+      label: 'Compose Alert',
+      description: 'Formats a severe-weather alert line for a place.',
+      category: 'logic',
+      traceKind: 'compute',
+      inputSchema: {
+        fields: [
+          { name: 'place', type: 'string', required: true },
+          { name: 'reason', type: 'string', required: true },
+        ],
+      },
+      outputSchema: {
+        fields: [
+          { name: 'alert', type: 'string' },
+          { name: 'place', type: 'string' },
+        ],
+      },
+    },
+    async (ctx) => {
+      const place = String(ctx.input.place ?? 'the area');
+      const reason = String(ctx.input.reason ?? 'conditions worsening');
+      const alert = `⚠ Weather alert for ${place}: ${reason}`;
+      ctx.log('info', alert);
+      return { alert, place };
+    },
+  );
+}