Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
11.5 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-or-later

import {Config} from '@app/api/Config';
import {getContentMessage} from '@app/api/content_i18n/ContentI18n';
import {getLegalUrls} from '@app/api/instance/LegalUrls';
import {getInstanceProductName} from '@app/api/instance/ProductName';
import {
	assertValidReportFlowLibrary,
	buildReportFlowVariant,
	type ReportFlowInstance,
	type ReportFlowLibrary,
	type ReportFlowVariant,
	type ReportFlowVariantScreen,
} from '@app/api/report/flows/ReportFlowCompiler';
import {REPORT_FLOWS} from '@app/api/report/flows/ReportFlowDefinitions';
import {
	REPORT_FLOW_NOTICES,
	REPORT_FLOW_SCREENS,
	type ReportFlowCopyKey,
	type ReportFlowLinkId,
	type ReportFlowOutcomeDef,
} from '@app/api/report/flows/ReportFlowScreens';
import {getLegacyCategory, type ReportReasonKey} from '@app/api/report/flows/ReportReasonCatalog';
import {isStringArray, parseJsonArray} from '@app/api/utils/JsonBoundaryUtils';
import type {LocaleCode} from '@fluxer/constants/src/Locales';
import {InvalidReportFlowAnswersError} from '@fluxer/errors/src/domains/moderation/InvalidReportFlowAnswersError';
import {ReportFlowOutdatedError} from '@fluxer/errors/src/domains/moderation/ReportFlowOutdatedError';
import {parseAcceptLanguage} from '@fluxer/i18n/src/locale/resolution/AcceptLanguageNegotiation';
import {isObjectLike} from '@fluxer/record_utils/src/RecordGuards';
import type {
	ReportFlowOutcome,
	ReportFlowResponse,
	ReportFlowScreen,
	ReportFlowSurface,
	ReportFlowTargetType,
} from '@fluxer/schema/src/domains/report/ReportFlowSchemas';

export interface ReportFlowStepRecord {
	screen_id: string;
	option_id?: string;
	item_ids?: Array<string>;
}

interface ReportFlowStepInput {
	screen_id: string;
	option_id?: string | undefined;
	item_ids?: ReadonlyArray<string> | undefined;
}

interface ResolvedReportFlowAnswers {
	reason: ReportReasonKey;
	legacyCategory: string;
	steps: Array<ReportFlowStepRecord>;
	stepsJson: string;
	currentRevisionHash: string;
	isCurrentRevision: boolean;
}

interface ReportFlowAnswersDescription {
	revision_hash: string;
	surface: string;
	locale: string | null;
	steps: Array<{
		screen_id: string;
		screen_title: string;
		option_id: string | null;
		option_label: string | null;
		items: Array<{id: string; label: string}>;
	}>;
}

const REPORT_FLOW_LIBRARY: ReportFlowLibrary = {
	flows: REPORT_FLOWS,
	screens: REPORT_FLOW_SCREENS,
	notices: REPORT_FLOW_NOTICES,
};

const CRISIS_LINES_URL = 'https://befrienders.org';
const COPYRIGHT_HELP_URL = 'https://fluxer.com/help/copyright';
const ADMIN_LOCALE = 'en-US';

assertValidReportFlowLibrary(REPORT_FLOW_LIBRARY);

const variantCache = new Map<string, ReportFlowVariant>();
const responseCache = new Map<string, ReportFlowResponse>();

function getReportFlowInstance(guidelinesUrl: string | null): ReportFlowInstance {
	return {selfHosted: Config.instance.selfHosted, guidelinesLinked: guidelinesUrl !== null};
}

function getLinkUrl(link: ReportFlowLinkId, guidelinesUrl: string | null): string | null {
	switch (link) {
		case 'copyright':
			return COPYRIGHT_HELP_URL;
		case 'crisis_lines':
			return CRISIS_LINES_URL;
		case 'guidelines':
			return guidelinesUrl;
	}
}

function getReportFlowVariant(
	target: ReportFlowTargetType,
	surface: ReportFlowSurface,
	instance: ReportFlowInstance,
): ReportFlowVariant {
	const cacheKey = `${target}:${surface}:${instance.selfHosted}:${instance.guidelinesLinked}`;
	const cached = variantCache.get(cacheKey);
	if (cached) {
		return cached;
	}
	const variant = buildReportFlowVariant(REPORT_FLOW_LIBRARY, target, surface, instance);
	variantCache.set(cacheKey, variant);
	return variant;
}

export function resolveReportFlowLocale(raw: string | null | undefined): LocaleCode {
	return parseAcceptLanguage(raw);
}

function renderCopy(key: ReportFlowCopyKey, locale: string): string {
	return getContentMessage(key, locale, {product_name: getInstanceProductName()});
}

function renderOutcome(outcome: ReportFlowOutcomeDef, guidelinesUrl: string | null): ReportFlowOutcome {
	return {
		type: outcome.type,
		screen_id: outcome.type === 'screen' ? outcome.screenId : null,
		reason: outcome.type === 'submit' ? outcome.reason : null,
		notice_id: outcome.type === 'end' ? (outcome.noticeId ?? null) : null,
		url: outcome.type === 'link' ? getLinkUrl(outcome.link, guidelinesUrl) : null,
	};
}

function renderScreen(screen: ReportFlowVariantScreen, locale: string, guidelinesUrl: string | null): ReportFlowScreen {
	const {def} = screen;
	return {
		id: def.id,
		title: renderCopy(def.title, locale),
		subtitle: screen.subtitle ? renderCopy(screen.subtitle, locale) : null,
		urgent: def.urgent === true,
		options: screen.options.map((option) => ({
			id: option.id,
			label: renderCopy(option.label, locale),
			outcome: renderOutcome(option.outcome, guidelinesUrl),
		})),
		options_heading: null,
		checklist: def.checklist
			? {
					items: def.checklist.items.map((item) => ({
						id: item.id,
						label: renderCopy(item.label, locale),
						description: item.description ? renderCopy(item.description, locale) : null,
					})),
					min_checked: def.checklist.minChecked,
					outcome: renderOutcome(def.checklist.outcome, guidelinesUrl),
				}
			: null,
		next_screen_id: def.nextScreenId ?? null,
	};
}

export function getReportFlowResponse(
	target: ReportFlowTargetType,
	surface: ReportFlowSurface,
	rawLocale: string | null | undefined,
): ReportFlowResponse {
	const {guidelinesUrl} = getLegalUrls();
	const instance = getReportFlowInstance(guidelinesUrl);
	const variant = getReportFlowVariant(target, surface, instance);
	const locale = resolveReportFlowLocale(rawLocale);
	const cacheKey = [
		target,
		surface,
		locale,
		instance.selfHosted,
		guidelinesUrl ?? '',
		getInstanceProductName(),
		Config.endpoints.webApp,
	].join('\u0000');
	const cached = responseCache.get(cacheKey);
	if (cached) {
		return cached;
	}
	const response: ReportFlowResponse = {
		target_type: target,
		surface,
		revision_hash: variant.revisionHash,
		locale,
		start_screen_id: variant.startScreenId,
		guidelines_url: guidelinesUrl,
		screens: [...variant.screens.values()].map((screen) => renderScreen(screen, locale, guidelinesUrl)),
		notices: variant.notices.map((notice) => ({
			id: notice.id,
			title: renderCopy(notice.title, locale),
			body: renderCopy(notice.body, locale),
		})),
	};
	responseCache.set(cacheKey, response);
	return response;
}

function findInvalidStep(
	variant: ReportFlowVariant,
	steps: ReadonlyArray<ReportFlowStepInput>,
): {invalidStep: number} | {reason: ReportReasonKey; steps: Array<ReportFlowStepRecord>} {
	let expectedScreenId: string | null = variant.startScreenId;
	let finalReason: ReportReasonKey | null = null;
	let itemReason: ReportReasonKey | null = null;
	const records: Array<ReportFlowStepRecord> = [];
	for (let index = 0; index < steps.length; index++) {
		const step = steps[index];
		if (expectedScreenId === null || step.screen_id !== expectedScreenId) {
			return {invalidStep: index};
		}
		const screen = variant.screens.get(expectedScreenId);
		if (!screen) {
			return {invalidStep: index};
		}
		let outcome: ReportFlowOutcomeDef;
		if (screen.kind === 'choice') {
			const option =
				step.option_id !== undefined && step.item_ids === undefined
					? screen.options.find((candidate) => candidate.id === step.option_id)
					: undefined;
			if (!option) {
				return {invalidStep: index};
			}
			outcome = option.outcome;
			records.push({screen_id: step.screen_id, option_id: option.id});
		} else if (screen.kind === 'checklist' && screen.def.checklist) {
			const {items, minChecked} = screen.def.checklist;
			const chosen = new Set(step.item_ids ?? []);
			const known = items.filter((item) => chosen.has(item.id));
			if (
				step.option_id !== undefined ||
				step.item_ids === undefined ||
				chosen.size !== step.item_ids.length ||
				known.length !== chosen.size ||
				known.length < minChecked
			) {
				return {invalidStep: index};
			}
			itemReason ??= known.find((item) => item.reason !== undefined)?.reason ?? null;
			outcome = screen.def.checklist.outcome;
			records.push({screen_id: step.screen_id, item_ids: known.map((item) => item.id)});
		} else {
			if (step.option_id !== undefined || step.item_ids !== undefined || screen.def.nextScreenId === undefined) {
				return {invalidStep: index};
			}
			outcome = {type: 'screen', screenId: screen.def.nextScreenId};
			records.push({screen_id: step.screen_id});
		}
		if (outcome.type === 'screen') {
			expectedScreenId = outcome.screenId;
		} else if (outcome.type === 'submit') {
			expectedScreenId = null;
			finalReason = outcome.reason;
		} else {
			return {invalidStep: index};
		}
	}
	if (finalReason === null) {
		return {invalidStep: Math.max(steps.length - 1, 0)};
	}
	return {reason: itemReason ?? finalReason, steps: records};
}

export function resolveReportFlowAnswers(params: {
	target: ReportFlowTargetType;
	surface: ReportFlowSurface;
	revisionHash: string;
	steps: ReadonlyArray<ReportFlowStepInput>;
}): ResolvedReportFlowAnswers {
	const variant = getReportFlowVariant(
		params.target,
		params.surface,
		getReportFlowInstance(getLegalUrls().guidelinesUrl),
	);
	const isCurrentRevision = params.revisionHash === variant.revisionHash;
	const result = findInvalidStep(variant, params.steps);
	if ('invalidStep' in result) {
		if (isCurrentRevision) {
			throw new InvalidReportFlowAnswersError(result.invalidStep);
		}
		throw new ReportFlowOutdatedError();
	}
	return {
		reason: result.reason,
		legacyCategory: getLegacyCategory(result.reason, params.target),
		steps: result.steps,
		stepsJson: JSON.stringify(result.steps),
		currentRevisionHash: variant.revisionHash,
		isCurrentRevision,
	};
}

export function parseReportFlowSteps(json: string | null | undefined): Array<ReportFlowStepRecord> | null {
	if (!json) {
		return null;
	}
	const parsed = parseJsonArray(json);
	if (!parsed) {
		return null;
	}
	const steps: Array<ReportFlowStepRecord> = [];
	for (const entry of parsed) {
		if (!isObjectLike(entry)) {
			return null;
		}
		const {screen_id, option_id, item_ids} = entry;
		if (
			typeof screen_id !== 'string' ||
			(option_id !== undefined && typeof option_id !== 'string') ||
			(item_ids !== undefined && !isStringArray(item_ids))
		) {
			return null;
		}
		steps.push({
			screen_id,
			...(option_id !== undefined ? {option_id} : {}),
			...(item_ids !== undefined ? {item_ids} : {}),
		});
	}
	return steps;
}

export function describeReportFlowAnswers(params: {
	revisionHash: string;
	surface: string;
	locale: string | null;
	steps: ReadonlyArray<ReportFlowStepRecord>;
}): ReportFlowAnswersDescription {
	const screenDefs = new Map(REPORT_FLOW_LIBRARY.screens.map((screen) => [screen.id, screen]));
	return {
		revision_hash: params.revisionHash,
		surface: params.surface,
		locale: params.locale,
		steps: params.steps.map((step) => {
			const screen = screenDefs.get(step.screen_id);
			const option =
				step.option_id === undefined
					? undefined
					: screen?.options?.find((candidate) => candidate.id === step.option_id);
			const screenTitle = screen ? renderCopy(screen.title, ADMIN_LOCALE) : step.screen_id;
			let optionLabel: string | null = null;
			if (step.option_id !== undefined) {
				optionLabel = option ? renderCopy(option.label, ADMIN_LOCALE) : step.option_id;
			}
			return {
				screen_id: step.screen_id,
				screen_title: screenTitle,
				option_id: step.option_id ?? null,
				option_label: optionLabel,
				items: (step.item_ids ?? []).map((itemId) => {
					const item = screen?.checklist?.items.find((candidate) => candidate.id === itemId);
					return {id: itemId, label: item ? renderCopy(item.label, ADMIN_LOCALE) : itemId};
				}),
			};
		}),
	};
}