Skill: n8n-workflow-conventions

Every n8n → service call uses an explicit typed payload. Define these in src/workflows/types.ts. Never rely on implicit n8n node output shapes.

// src/workflows/types.ts

export interface AudioIngestPayload {
  readonly sessionId: string;       // client-generated stable UUID
  readonly telegramFileId?: string; // set when source is Telegram voice message
  readonly uploadUrl?: string;      // set when source is direct upload
  readonly durationSeconds: number;
  readonly mimeType: string;
}

export interface TranscriptionRequestPayload {
  readonly sessionId: string;
  readonly filePath: string;
  readonly mimeType: string;
}

export interface ExtractionRequestPayload {
  readonly sessionId: string;
  readonly transcript: string;
  readonly transcribedAt: string;   // ISO 8601
}

export interface DeliveryRequestPayload {
  readonly correlationId: string;
  readonly chatId: string;
  readonly kind: string;
  readonly text: string;
  readonly replyMarkup?: unknown;   // validated inside delivery adapter
}

Validate all incoming n8n payloads with Zod (or equivalent) at the service boundary. Reject and log invalid payloads immediately.

Workflow structure conventions

Naming

• Workflow names: kebab-case, prefixed by domain. E.g. audio-ingest, daily-briefing, decision-prompt.
• Node names: sentence case, action-oriented. E.g. Receive voice upload, Call transcription, Send Telegram message.

Error branches

• Every HTTP call node must have an error branch.
• Error branches log the failure (node name, error message, sessionId or correlationId) and send a Telegram error notice to the user.
• Never silently swallow errors in a workflow.

Retries

• Configure automatic retries on HTTP call nodes for transient failures (network, 5xx).
• Use exponential backoff. Set a maximum of 3 retries.
• Mark a workflow run as failed after max retries are exhausted — do not retry indefinitely.

Idempotency

• Pass sessionId or correlationId through every node.
• Service endpoints must be idempotent for the same ID — repeated calls return the same result without creating duplicates.
• Store processed IDs in a lightweight store (e.g. Redis, SQLite) to detect and skip duplicates.

Webhook endpoint conventions

Webhook handlers in the TypeScript service follow this pattern:

// src/workflows/handlers/audioIngestHandler.ts

import { z } from 'zod';
import type { Request, Response } from 'express';

const AudioIngestPayloadSchema = z.object({
  sessionId: z.string().uuid(),
  telegramFileId: z.string().optional(),
  uploadUrl: z.string().url().optional(),
  durationSeconds: z.number().positive().max(600),
  mimeType: z.string(),
});

export async function audioIngestHandler(req: Request, res: Response): Promise<void> {
  const parsed = AudioIngestPayloadSchema.safeParse(req.body);
  if (!parsed.success) {
    res.status(400).json({ error: 'Invalid payload', details: parsed.error.flatten() });
    return;
  }
  // hand off to domain service — no business logic here
}

• Handlers are thin. Validate → hand off → respond.
• Always return a structured JSON response, even for errors.
• Log sessionId / correlationId on entry and on success / failure.

Environment variables

All secrets and configuration values come from environment variables. Validate them at startup, not lazily.

// src/config.ts

import { z } from 'zod';

const EnvSchema = z.object({
  TELEGRAM_BOT_TOKEN: z.string().min(1),
  TELEGRAM_CHAT_ID: z.string().min(1),
  N8N_WEBHOOK_SECRET: z.string().min(32),
  TRANSCRIPTION_BACKEND: z.enum(['local', 'openai']),
  MAX_AUDIO_DURATION_SECONDS: z.coerce.number().positive().default(600),
});

export const config = EnvSchema.parse(process.env);

Never read process.env outside of src/config.ts.

Testing checklist

• All webhook handlers reject invalid payloads with a 400 and a reason.
• All payload schemas are tested with valid, invalid, and boundary-value inputs.
• sessionId / correlationId is present on every structured log entry in handlers.
• Service endpoints are tested for idempotent behavior on duplicate IDs.
• Config validation is tested with missing and malformed environment variables.
• No business logic lives in n8n workflow nodes — only in TypeScript service functions.