& so it begins

packages/logic/core/array.utils.ts

@@ -0,0 +1,7 @@
+export function chunk<T>(arr: T[], size: number): T[][] {
+	const result = [];
+	for (let i = 0; i < arr.length; i += size) {
+		result.push(arr.slice(i, i + size));
+	}
+	return result;
+}

packages/logic/core/data/countries.ts

@@ -0,0 +1,264 @@
+export const COUNTRIES = [
+  { id: "1", name: "Afghanistan", code: "AF" },
+  { id: "2", name: "Albania", code: "AL" },
+  { id: "3", name: "Algeria", code: "DZ" },
+  { id: "4", name: "American Samoa", code: "AS" },
+  { id: "5", name: "Andorra", code: "AD" },
+  { id: "6", name: "Angola", code: "AO" },
+  { id: "7", name: "Anguilla", code: "AI" },
+  { id: "8", name: "Antarctica", code: "AQ" },
+  { id: "9", name: "Antigua and Barbuda", code: "AG" },
+  { id: "10", name: "Argentina", code: "AR" },
+  { id: "11", name: "Armenia", code: "AM" },
+  { id: "12", name: "Aruba", code: "AW" },
+  { id: "13", name: "Australia", code: "AU" },
+  { id: "14", name: "Austria", code: "AT" },
+  { id: "15", name: "Azerbaijan", code: "AZ" },
+  { id: "16", name: "Bahamas", code: "BS" },
+  { id: "17", name: "Bahrain", code: "BH" },
+  { id: "18", name: "Bangladesh", code: "BD" },
+  { id: "19", name: "Barbados", code: "BB" },
+  { id: "20", name: "Belarus", code: "BY" },
+  { id: "21", name: "Belgium", code: "BE" },
+  { id: "22", name: "Belize", code: "BZ" },
+  { id: "23", name: "Benin", code: "BJ" },
+  { id: "24", name: "Bermuda", code: "BM" },
+  { id: "25", name: "Bhutan", code: "BT" },
+  { id: "26", name: "Bolivia", code: "BO" },
+  { id: "27", name: "Bosnia and Herzegovina", code: "BA" },
+  { id: "28", name: "Botswana", code: "BW" },
+  { id: "29", name: "Bouvet Island", code: "BV" },
+  { id: "30", name: "Brazil", code: "BR" },
+  { id: "31", name: "British Indian Ocean Territory", code: "IO" },
+  { id: "32", name: "British Virgin Islands", code: "VG" },
+  { id: "33", name: "Brunei", code: "BN" },
+  { id: "34", name: "Bulgaria", code: "BG" },
+  { id: "35", name: "Burkina Faso", code: "BF" },
+  { id: "36", name: "Burundi", code: "BI" },
+  { id: "37", name: "Cambodia", code: "KH" },
+  { id: "38", name: "Cameroon", code: "CM" },
+  { id: "39", name: "Canada", code: "CA" },
+  { id: "40", name: "Cape Verde", code: "CV" },
+  { id: "41", name: "Caribbean Netherlands", code: "BQ" },
+  { id: "42", name: "Cayman Islands", code: "KY" },
+  { id: "43", name: "Central African Republic", code: "CF" },
+  { id: "44", name: "Chad", code: "TD" },
+  { id: "45", name: "Chile", code: "CL" },
+  { id: "46", name: "China", code: "CN" },
+  { id: "47", name: "Christmas Island", code: "CX" },
+  { id: "48", name: "Cocos (Keeling) Islands", code: "CC" },
+  { id: "49", name: "Colombia", code: "CO" },
+  { id: "50", name: "Comoros", code: "KM" },
+  { id: "51", name: "Cook Islands", code: "CK" },
+  { id: "52", name: "Costa Rica", code: "CR" },
+  { id: "53", name: "Croatia", code: "HR" },
+  { id: "54", name: "Cuba", code: "CU" },
+  { id: "55", name: "Curaçao", code: "CW" },
+  { id: "56", name: "Cyprus", code: "CY" },
+  { id: "57", name: "Czechia", code: "CZ" },
+  { id: "58", name: "DR Congo", code: "CD" },
+  { id: "59", name: "Denmark", code: "DK" },
+  { id: "60", name: "Djibouti", code: "DJ" },
+  { id: "61", name: "Dominica", code: "DM" },
+  { id: "62", name: "Dominican Republic", code: "DO" },
+  { id: "63", name: "Ecuador", code: "EC" },
+  { id: "64", name: "Egypt", code: "EG" },
+  { id: "65", name: "El Salvador", code: "SV" },
+  { id: "66", name: "Equatorial Guinea", code: "GQ" },
+  { id: "67", name: "Eritrea", code: "ER" },
+  { id: "68", name: "Estonia", code: "EE" },
+  { id: "69", name: "Eswatini", code: "SZ" },
+  { id: "70", name: "Ethiopia", code: "ET" },
+  { id: "71", name: "Falkland Islands", code: "FK" },
+  { id: "72", name: "Faroe Islands", code: "FO" },
+  { id: "73", name: "Fiji", code: "FJ" },
+  { id: "74", name: "Finland", code: "FI" },
+  { id: "75", name: "France", code: "FR" },
+  { id: "76", name: "French Guiana", code: "GF" },
+  { id: "77", name: "French Polynesia", code: "PF" },
+  { id: "78", name: "French Southern and Antarctic Lands", code: "TF" },
+  { id: "79", name: "Gabon", code: "GA" },
+  { id: "80", name: "Gambia", code: "GM" },
+  { id: "81", name: "Georgia", code: "GE" },
+  { id: "82", name: "Germany", code: "DE" },
+  { id: "83", name: "Ghana", code: "GH" },
+  { id: "84", name: "Gibraltar", code: "GI" },
+  { id: "85", name: "Greece", code: "GR" },
+  { id: "86", name: "Greenland", code: "GL" },
+  { id: "87", name: "Grenada", code: "GD" },
+  { id: "88", name: "Guadeloupe", code: "GP" },
+  { id: "89", name: "Guam", code: "GU" },
+  { id: "90", name: "Guatemala", code: "GT" },
+  { id: "91", name: "Guernsey", code: "GG" },
+  { id: "92", name: "Guinea", code: "GN" },
+  { id: "93", name: "Guinea-Bissau", code: "GW" },
+  { id: "94", name: "Guyana", code: "GY" },
+  { id: "95", name: "Haiti", code: "HT" },
+  { id: "96", name: "Heard Island and McDonald Islands", code: "HM" },
+  { id: "97", name: "Honduras", code: "HN" },
+  { id: "98", name: "Hong Kong", code: "HK" },
+  { id: "99", name: "Hungary", code: "HU" },
+  { id: "100", name: "Iceland", code: "IS" },
+  { id: "101", name: "India", code: "IN" },
+  { id: "102", name: "Indonesia", code: "ID" },
+  { id: "103", name: "Iran", code: "IR" },
+  { id: "104", name: "Iraq", code: "IQ" },
+  { id: "105", name: "Ireland", code: "IE" },
+  { id: "106", name: "Isle of Man", code: "IM" },
+  { id: "107", name: "Israel", code: "IL" },
+  { id: "108", name: "Italy", code: "IT" },
+  { id: "109", name: "Ivory Coast", code: "CI" },
+  { id: "110", name: "Jamaica", code: "JM" },
+  { id: "111", name: "Japan", code: "JP" },
+  { id: "112", name: "Jersey", code: "JE" },
+  { id: "113", name: "Jordan", code: "JO" },
+  { id: "114", name: "Kazakhstan", code: "KZ" },
+  { id: "115", name: "Kenya", code: "KE" },
+  { id: "116", name: "Kiribati", code: "KI" },
+  { id: "117", name: "Kosovo", code: "XK" },
+  { id: "118", name: "Kuwait", code: "KW" },
+  { id: "119", name: "Kyrgyzstan", code: "KG" },
+  { id: "120", name: "Laos", code: "LA" },
+  { id: "121", name: "Latvia", code: "LV" },
+  { id: "122", name: "Lebanon", code: "LB" },
+  { id: "123", name: "Lesotho", code: "LS" },
+  { id: "124", name: "Liberia", code: "LR" },
+  { id: "125", name: "Libya", code: "LY" },
+  { id: "126", name: "Liechtenstein", code: "LI" },
+  { id: "127", name: "Lithuania", code: "LT" },
+  { id: "128", name: "Luxembourg", code: "LU" },
+  { id: "129", name: "Macau", code: "MO" },
+  { id: "130", name: "Madagascar", code: "MG" },
+  { id: "131", name: "Malawi", code: "MW" },
+  { id: "132", name: "Malaysia", code: "MY" },
+  { id: "133", name: "Maldives", code: "MV" },
+  { id: "134", name: "Mali", code: "ML" },
+  { id: "135", name: "Malta", code: "MT" },
+  { id: "136", name: "Marshall Islands", code: "MH" },
+  { id: "137", name: "Martinique", code: "MQ" },
+  { id: "138", name: "Mauritania", code: "MR" },
+  { id: "139", name: "Mauritius", code: "MU" },
+  { id: "140", name: "Mayotte", code: "YT" },
+  { id: "141", name: "Mexico", code: "MX" },
+  { id: "142", name: "Micronesia", code: "FM" },
+  { id: "143", name: "Moldova", code: "MD" },
+  { id: "144", name: "Monaco", code: "MC" },
+  { id: "145", name: "Mongolia", code: "MN" },
+  { id: "146", name: "Montenegro", code: "ME" },
+  { id: "147", name: "Montserrat", code: "MS" },
+  { id: "148", name: "Morocco", code: "MA" },
+  { id: "149", name: "Mozambique", code: "MZ" },
+  { id: "150", name: "Myanmar", code: "MM" },
+  { id: "151", name: "Namibia", code: "NA" },
+  { id: "152", name: "Nauru", code: "NR" },
+  { id: "153", name: "Nepal", code: "NP" },
+  { id: "154", name: "Netherlands", code: "NL" },
+  { id: "155", name: "New Caledonia", code: "NC" },
+  { id: "156", name: "New Zealand", code: "NZ" },
+  { id: "157", name: "Nicaragua", code: "NI" },
+  { id: "158", name: "Niger", code: "NE" },
+  { id: "159", name: "Nigeria", code: "NG" },
+  { id: "160", name: "Niue", code: "NU" },
+  { id: "161", name: "Norfolk Island", code: "NF" },
+  { id: "162", name: "North Korea", code: "KP" },
+  { id: "163", name: "North Macedonia", code: "MK" },
+  { id: "164", name: "Northern Mariana Islands", code: "MP" },
+  { id: "165", name: "Norway", code: "NO" },
+  { id: "166", name: "Oman", code: "OM" },
+  { id: "167", name: "Pakistan", code: "PK" },
+  { id: "168", name: "Palau", code: "PW" },
+  { id: "169", name: "Palestine", code: "PS" },
+  { id: "170", name: "Panama", code: "PA" },
+  { id: "171", name: "Papua New Guinea", code: "PG" },
+  { id: "172", name: "Paraguay", code: "PY" },
+  { id: "173", name: "Peru", code: "PE" },
+  { id: "174", name: "Philippines", code: "PH" },
+  { id: "175", name: "Pitcairn Islands", code: "PN" },
+  { id: "176", name: "Poland", code: "PL" },
+  { id: "177", name: "Portugal", code: "PT" },
+  { id: "178", name: "Puerto Rico", code: "PR" },
+  { id: "179", name: "Qatar", code: "QA" },
+  { id: "180", name: "Republic of the Congo", code: "CG" },
+  { id: "181", name: "Romania", code: "RO" },
+  { id: "182", name: "Russia", code: "RU" },
+  { id: "183", name: "Rwanda", code: "RW" },
+  { id: "184", name: "Réunion", code: "RE" },
+  { id: "185", name: "Saint Barthélemy", code: "BL" },
+  {
+    id: "186",
+    name: "Saint Helena, Ascension and Tristan da Cunha",
+    code: "SH",
+  },
+  { id: "187", name: "Saint Kitts and Nevis", code: "KN" },
+  { id: "188", name: "Saint Lucia", code: "LC" },
+  { id: "189", name: "Saint Martin", code: "MF" },
+  { id: "190", name: "Saint Pierre and Miquelon", code: "PM" },
+  { id: "191", name: "Saint Vincent and the Grenadines", code: "VC" },
+  { id: "192", name: "Samoa", code: "WS" },
+  { id: "193", name: "San Marino", code: "SM" },
+  { id: "194", name: "Saudi Arabia", code: "SA" },
+  { id: "195", name: "Senegal", code: "SN" },
+  { id: "196", name: "Serbia", code: "RS" },
+  { id: "197", name: "Seychelles", code: "SC" },
+  { id: "198", name: "Sierra Leone", code: "SL" },
+  { id: "199", name: "Singapore", code: "SG" },
+  { id: "200", name: "Sint Maarten", code: "SX" },
+  { id: "201", name: "Slovakia", code: "SK" },
+  { id: "202", name: "Slovenia", code: "SI" },
+  { id: "203", name: "Solomon Islands", code: "SB" },
+  { id: "204", name: "Somalia", code: "SO" },
+  { id: "205", name: "South Africa", code: "ZA" },
+  { id: "206", name: "South Georgia", code: "GS" },
+  { id: "207", name: "South Korea", code: "KR" },
+  { id: "208", name: "South Sudan", code: "SS" },
+  { id: "209", name: "Spain", code: "ES" },
+  { id: "210", name: "Sri Lanka", code: "LK" },
+  { id: "211", name: "Sudan", code: "SD" },
+  { id: "212", name: "Suriname", code: "SR" },
+  { id: "213", name: "Svalbard and Jan Mayen", code: "SJ" },
+  { id: "214", name: "Sweden", code: "SE" },
+  { id: "215", name: "Switzerland", code: "CH" },
+  { id: "216", name: "Syria", code: "SY" },
+  { id: "217", name: "São Tomé and Príncipe", code: "ST" },
+  { id: "218", name: "Taiwan", code: "TW" },
+  { id: "219", name: "Tajikistan", code: "TJ" },
+  { id: "220", name: "Tanzania", code: "TZ" },
+  { id: "221", name: "Thailand", code: "TH" },
+  { id: "222", name: "Timor-Leste", code: "TL" },
+  { id: "223", name: "Togo", code: "TG" },
+  { id: "224", name: "Tokelau", code: "TK" },
+  { id: "225", name: "Tonga", code: "TO" },
+  { id: "226", name: "Trinidad and Tobago", code: "TT" },
+  { id: "227", name: "Tunisia", code: "TN" },
+  { id: "228", name: "Turkey", code: "TR" },
+  { id: "229", name: "Turkmenistan", code: "TM" },
+  { id: "230", name: "Turks and Caicos Islands", code: "TC" },
+  { id: "231", name: "Tuvalu", code: "TV" },
+  { id: "232", name: "Uganda", code: "UG" },
+  { id: "233", name: "Ukraine", code: "UA" },
+  { id: "234", name: "United Arab Emirates", code: "AE" },
+  { id: "235", name: "United Kingdom", code: "GB" },
+  { id: "236", name: "United States", code: "US" },
+  { id: "237", name: "United States Minor Outlying Islands", code: "UM" },
+  { id: "238", name: "United States Virgin Islands", code: "VI" },
+  { id: "239", name: "Uruguay", code: "UY" },
+  { id: "240", name: "Uzbekistan", code: "UZ" },
+  { id: "241", name: "Vanuatu", code: "VU" },
+  { id: "242", name: "Vatican City", code: "VA" },
+  { id: "243", name: "Venezuela", code: "VE" },
+  { id: "244", name: "Vietnam", code: "VN" },
+  { id: "245", name: "Wallis and Futuna", code: "WF" },
+  { id: "246", name: "Western Sahara", code: "EH" },
+  { id: "247", name: "Yemen", code: "YE" },
+  { id: "248", name: "Zambia", code: "ZM" },
+  { id: "249", name: "Zimbabwe", code: "ZW" },
+  { id: "250", name: "Åland Islands", code: "AX" },
+];
+
+export const COUNTRIES_SELECT = COUNTRIES.map((c) => {
+  return {
+    id: c.id,
+    label: `${c.code} (${c.name})`,
+    value: c.name.toLowerCase(),
+  };
+});

packages/logic/core/date.utils.ts

@@ -0,0 +1,83 @@
+import type { CalendarDate } from "@internationalized/date";
+
+export function formatDuration(ms: number): string {
+	const seconds = Math.floor(ms / 1000);
+	if (seconds < 60) return `${seconds}s`;
+
+	const minutes = Math.floor(seconds / 60);
+	const remainingSeconds = seconds % 60;
+	return `${minutes}m ${remainingSeconds}s`;
+}
+
+export function formatDateTimeFromIsoString(isoString: string): string {
+	try {
+		const date = new Date(isoString);
+		return new Intl.DateTimeFormat("en-US", {
+			dateStyle: "medium",
+			timeStyle: "short",
+		}).format(date);
+	} catch (e) {
+		return "Invalid date";
+	}
+}
+
+export function getJustDateString(d: Date): string {
+	return d.toISOString().split("T")[0];
+}
+
+export function formatDateTime(dateTimeStr: string) {
+	const date = new Date(dateTimeStr);
+	return {
+		time: date.toLocaleTimeString("en-US", {
+			hour: "2-digit",
+			minute: "2-digit",
+			hour12: false,
+		}),
+		date: date.toLocaleDateString("en-US", {
+			weekday: "short",
+			day: "2-digit",
+			month: "short",
+		}),
+	};
+}
+
+export function formatDate(dateStr: string) {
+	return new Date(dateStr).toLocaleDateString("en-US", {
+		weekday: "short",
+		day: "2-digit",
+		month: "short",
+	});
+}
+
+export function isTimestampMoreThan1MinAgo(ts: string): boolean {
+	const lastPingedDate = new Date(ts);
+	const now = new Date();
+	const diff = now.getTime() - lastPingedDate.getTime();
+	return diff > 60000;
+}
+
+export function isTimestampOlderThan(ts: string, seconds: number): boolean {
+	const lastPingedDate = new Date(ts);
+	const now = new Date();
+	const diff = now.getTime() - lastPingedDate.getTime();
+	return diff > seconds * 1000;
+}
+
+export function makeDateStringISO(ds: string): string {
+	if (ds.includes("T")) {
+		return `${ds.split("T")[0]}T00:00:00.000Z`;
+	}
+	return `${ds}T00:00:00.000Z`;
+}
+
+export function parseCalDateToDateString(v: CalendarDate) {
+	let month: string | number = v.month;
+	if (month < 10) {
+		month = `0${month}`;
+	}
+	let day: string | number = v.day;
+	if (day < 10) {
+		day = `0${day}`;
+	}
+	return `${v.year}-${month}-${day}`;
+}

packages/logic/core/error.ts

@@ -0,0 +1,8 @@
+export type Err = {
+	code: string;
+	message: string;
+	description: string;
+	detail: string;
+	actionable?: boolean;
+	error?: any;
+};

packages/logic/core/flow.execution.context.ts

@@ -0,0 +1,5 @@
+export type FlowExecCtx = {
+    flowId: string;
+    userId?: string;
+    sessionId?: string;
+};

packages/logic/core/hash.utils.ts

@@ -0,0 +1,31 @@
+import { argon2id, hash as argonHash, verify as argonVerify } from "argon2";
+
+export async function hashString(target: string): Promise<string> {
+	const salt = Buffer.from(crypto.getRandomValues(new Uint8Array(16))).toString(
+		"hex",
+	);
+	const hash = await argonHash(target, {
+		type: argon2id,
+		salt: Buffer.from(salt, "hex"),
+		hashLength: 32,
+		timeCost: 3,
+		memoryCost: 65536,
+		parallelism: 1,
+	});
+	return hash;
+}
+
+export async function verifyHash({
+	hash,
+	target,
+}: {
+	hash: string;
+	target: string;
+}): Promise<boolean> {
+	try {
+		const isValid = await argonVerify(hash, `${target}`);
+		return isValid;
+	} catch (err) {
+		return false;
+	}
+}

packages/logic/core/hono.helpers.ts

@@ -0,0 +1,9 @@
+import type { Session, User } from "@/domains/user/data";
+import { FlowExecCtx } from "./flow.execution.context";
+import { Env } from "hono";
+
+export interface HonoContext extends Env {
+    Bindings: {
+        locals: { user: User; session: Session; fCtx: FlowExecCtx };
+    };
+}

packages/logic/core/pagination.utils.ts

@@ -0,0 +1,12 @@
+import * as v from "valibot";
+
+export const paginationModel = v.object({
+    cursor: v.optional(v.string()),
+    limit: v.pipe(v.number(), v.integer(), v.maxValue(100)),
+    asc: v.optional(v.boolean(), true),
+    totalItemCount: v.optional(v.pipe(v.number(), v.integer()), 0),
+    totalPages: v.pipe(v.number(), v.integer()),
+    page: v.pipe(v.number(), v.integer()),
+});
+
+export type PaginationModel = v.InferOutput<typeof paginationModel>;

packages/logic/core/rate.limiter.ts

@@ -0,0 +1,40 @@
+import { logger } from "@pkg/logger";
+
+export class RateLimiter {
+    private requestTimestamps: number[] = [];
+    private readonly callsPerMinute: number;
+
+    constructor(callsPerMinute: number = 60) {
+        this.callsPerMinute = Math.min(callsPerMinute, 60);
+    }
+
+    async checkRateLimit(): Promise<void> {
+        const currentTime = Date.now();
+        const oneMinuteAgo = currentTime - 60000; // 60 seconds in milliseconds
+
+        // Remove timestamps older than 1 minute
+        this.requestTimestamps = this.requestTimestamps.filter(
+            (timestamp) => timestamp > oneMinuteAgo,
+        );
+
+        // If we're approaching the limit, wait until we have capacity
+        if (this.requestTimestamps.length >= this.callsPerMinute) {
+            const oldestRequest = this.requestTimestamps[0];
+            const waitTime = oldestRequest + 60000 - currentTime;
+
+            if (waitTime > 0) {
+                logger.warn(
+                    `Rate limit approaching (${this.requestTimestamps.length} requests in last minute). Sleeping for ${waitTime}ms`,
+                );
+                await new Promise((resolve) => setTimeout(resolve, waitTime));
+                // After waiting, some timestamps may have expired
+                this.requestTimestamps = this.requestTimestamps.filter(
+                    (timestamp) => timestamp > Date.now() - 60000,
+                );
+            }
+        }
+
+        // Add current request to timestamps
+        this.requestTimestamps.push(Date.now());
+    }
+}

packages/logic/core/settings.ts

@@ -0,0 +1 @@
+export { getSetting, settings } from "@pkg/settings";

packages/logic/core/string.utils/index.ts

@@ -0,0 +1,106 @@
+import * as v from "valibot";
+
+export function capitalize(input: string, firstOfAllWords?: boolean): string {
+    // capitalize first letter of input
+    if (!firstOfAllWords) {
+        return input.charAt(0).toUpperCase() + input.slice(1);
+    }
+    let out = "";
+    for (const word of input.split(" ")) {
+        out += word.charAt(0).toUpperCase() + word.slice(1) + " ";
+    }
+    return out.slice(0, -1);
+}
+
+export function camelToSpacedPascal(input: string): string {
+    let result = "";
+    let previousChar = "";
+    for (const char of input) {
+        if (char === char.toUpperCase() && previousChar !== " ") {
+            result += " ";
+        }
+        result += char;
+        previousChar = char;
+    }
+    return result.charAt(0).toUpperCase() + result.slice(1);
+}
+
+export function snakeToCamel(input: string): string {
+    if (!input) {
+        return input;
+    }
+    // also account for numbers and kebab-case
+    const splits = input.split(/[-_]/);
+    let result = splits[0];
+    for (const split of splits.slice(1)) {
+        result += capitalize(split, true);
+    }
+    return result ?? "";
+}
+
+export function snakeToSpacedPascal(input: string): string {
+    return camelToSpacedPascal(snakeToCamel(input));
+}
+
+export function spacedPascalToSnake(input: string): string {
+    return input.split(" ").join("_").toLowerCase();
+}
+
+export function convertDashedLowerToTitleCase(input: string): string {
+    return input
+        .split("-")
+        .map(
+            (word) =>
+                word.charAt(0).toUpperCase() + word.slice(1).toLowerCase(),
+        )
+        .join(" "); // Join the words with a space
+}
+
+export function encodeCursor<T>(cursor: T): string {
+    try {
+        // Convert the object to a JSON string
+        const jsonString = JSON.stringify(cursor);
+        // Convert to UTF-8 bytes, then base64
+        return btoa(
+            encodeURIComponent(jsonString).replace(/%([0-9A-F]{2})/g, (_, p1) =>
+                String.fromCharCode(parseInt(p1, 16)),
+            ),
+        );
+    } catch (error) {
+        console.error("Error encoding cursor:", error);
+        throw new Error("Failed to encode cursor");
+    }
+}
+
+export function decodeCursor<T>(
+    cursor: string,
+    parser: v.BaseSchema<any, T, any>,
+) {
+    try {
+        // Decode base64 back to UTF-8 string
+        const decoded = decodeURIComponent(
+            Array.prototype.map
+                .call(atob(cursor), (c) => {
+                    return (
+                        "%" + ("00" + c.charCodeAt(0).toString(16)).slice(-2)
+                    );
+                })
+                .join(""),
+        );
+        // Parse back to object
+        const parsedData = JSON.parse(decoded);
+        const result = v.safeParse(parser, parsedData);
+        return result.success
+            ? { success: true, data: result.output as T }
+            : {
+                  success: false,
+                  error: new Error(
+                      result.issues.map((i) => i.message).join(", "),
+                  ),
+                  data: undefined,
+              };
+    } catch (error) {
+        console.error("Error decoding cursor:", error);
+        return { error: new Error("Failed to decode cursor"), data: undefined };
+    }
+}

packages/logic/core/string.utils/sequence.matcher.ts

@@ -0,0 +1,555 @@
+/**
+ * Similar to Python's difflib.SequenceMatcher
+ *
+ * A flexible class for comparing pairs of sequences of any type.
+ * Uses the Ratcliff-Obershelp algorithm with "gestalt pattern matching"
+ * to find the longest contiguous matching subsequences.
+ */
+
+export interface Match {
+	/** Starting position in sequence a */
+	a: number;
+	/** Starting position in sequence b */
+	b: number;
+	/** Length of the matching block */
+	size: number;
+}
+
+export type OpCode = "replace" | "delete" | "insert" | "equal";
+
+export interface OpCodeTuple {
+	/** Operation type */
+	tag: OpCode;
+	/** Start index in sequence a */
+	i1: number;
+	/** End index in sequence a */
+	i2: number;
+	/** Start index in sequence b */
+	j1: number;
+	/** End index in sequence b */
+	j2: number;
+}
+
+export type JunkFunction<T> = (element: T) => boolean;
+
+export class SequenceMatcher<T> {
+	private isjunk: JunkFunction<T> | null;
+	private a: T[];
+	private b: T[];
+	private autojunk: boolean;
+
+	// Cached data structures for sequence b
+	private bjunk: Set<T>;
+	private bpopular: Set<T>;
+	private b2j: Map<T, number[]>;
+
+	// Cached results
+	private fullbcount: Map<T, number> | null = null;
+	private matchingBlocks: Match[] | null = null;
+	private opcodes: OpCodeTuple[] | null = null;
+
+	constructor(
+		isjunk: JunkFunction<T> | null = null,
+		a: T[] = [],
+		b: T[] = [],
+		autojunk: boolean = true,
+	) {
+		this.isjunk = isjunk;
+		this.a = [];
+		this.b = [];
+		this.autojunk = autojunk;
+		this.bjunk = new Set();
+		this.bpopular = new Set();
+		this.b2j = new Map();
+
+		this.setSeqs(a, b);
+	}
+
+	/**
+	 * Set both sequences to be compared
+	 */
+	setSeqs(a: T[], b: T[]): void {
+		this.setSeq1(a);
+		this.setSeq2(b);
+	}
+
+	/**
+	 * Set the first sequence to be compared
+	 */
+	setSeq1(a: T[]): void {
+		if (a === this.a) return;
+		this.a = [...a];
+		this.matchingBlocks = null;
+		this.opcodes = null;
+	}
+
+	/**
+	 * Set the second sequence to be compared
+	 */
+	setSeq2(b: T[]): void {
+		if (b === this.b) return;
+		this.b = [...b];
+		this.matchingBlocks = null;
+		this.opcodes = null;
+		this.fullbcount = null;
+		this.chainB();
+	}
+
+	/**
+	 * Analyze sequence b and build lookup structures
+	 */
+	private chainB(): void {
+		const b = this.b;
+		this.bjunk = new Set();
+		this.bpopular = new Set();
+		this.b2j = new Map();
+
+		// Count occurrences of each element
+		const elementCounts = new Map<T, number>();
+		for (const element of b) {
+			elementCounts.set(element, (elementCounts.get(element) || 0) + 1);
+		}
+
+		// Determine junk and popular elements
+		const n = b.length;
+		const popularThreshold = Math.floor(n / 100) + 1; // > 1% of sequence
+
+		for (const [element, count] of elementCounts) {
+			if (this.isjunk && this.isjunk(element)) {
+				this.bjunk.add(element);
+			} else if (this.autojunk && n >= 200 && count > popularThreshold) {
+				this.bpopular.add(element);
+			}
+		}
+
+		// Build position mapping for non-junk, non-popular elements
+		for (let i = 0; i < b.length; i++) {
+			const element = b[i];
+			if (!this.bjunk.has(element) && !this.bpopular.has(element)) {
+				if (!this.b2j.has(element)) {
+					this.b2j.set(element, []);
+				}
+				this.b2j.get(element)!.push(i);
+			}
+		}
+	}
+
+	/**
+	 * Find the longest matching block in a[alo:ahi] and b[blo:bhi]
+	 */
+	findLongestMatch(
+		alo: number = 0,
+		ahi: number | null = null,
+		blo: number = 0,
+		bhi: number | null = null,
+	): Match {
+		if (ahi === null) ahi = this.a.length;
+		if (bhi === null) bhi = this.b.length;
+
+		let besti = alo;
+		let bestj = blo;
+		let bestsize = 0;
+
+		// Find all positions where a[i] appears in b
+		const j2len = new Map<number, number>();
+
+		for (let i = alo; i < ahi; i++) {
+			const element = this.a[i];
+			const positions = this.b2j.get(element) || [];
+			const newj2len = new Map<number, number>();
+
+			for (const j of positions) {
+				if (j < blo) continue;
+				if (j >= bhi) break;
+
+				const prevLen = j2len.get(j - 1) || 0;
+				const k = prevLen + 1;
+				newj2len.set(j, k);
+
+				if (k > bestsize) {
+					besti = i - k + 1;
+					bestj = j - k + 1;
+					bestsize = k;
+				}
+			}
+
+			j2len.clear();
+			for (const [key, value] of newj2len) {
+				j2len.set(key, value);
+			}
+		}
+
+		// Extend match with junk elements
+		while (
+			besti > alo &&
+			bestj > blo &&
+			!this.isBJunk(this.b[bestj - 1]) &&
+			this.elementsEqual(this.a[besti - 1], this.b[bestj - 1])
+		) {
+			besti--;
+			bestj--;
+			bestsize++;
+		}
+
+		while (
+			besti + bestsize < ahi &&
+			bestj + bestsize < bhi &&
+			!this.isBJunk(this.b[bestj + bestsize]) &&
+			this.elementsEqual(this.a[besti + bestsize], this.b[bestj + bestsize])
+		) {
+			bestsize++;
+		}
+
+		// Extend match with junk elements at the beginning
+		while (besti > alo && bestj > blo && this.isBJunk(this.b[bestj - 1])) {
+			besti--;
+			bestj--;
+			bestsize++;
+		}
+
+		// Extend match with junk elements at the end
+		while (
+			besti + bestsize < ahi &&
+			bestj + bestsize < bhi &&
+			this.isBJunk(this.b[bestj + bestsize])
+		) {
+			bestsize++;
+		}
+
+		return { a: besti, b: bestj, size: bestsize };
+	}
+
+	/**
+	 * Return list of non-overlapping matching blocks
+	 */
+	getMatchingBlocks(): Match[] {
+		if (this.matchingBlocks !== null) {
+			return this.matchingBlocks;
+		}
+
+		const matches: Match[] = [];
+		this.getMatchingBlocksRecursive(
+			0,
+			this.a.length,
+			0,
+			this.b.length,
+			matches,
+		);
+
+		// Add sentinel
+		matches.push({ a: this.a.length, b: this.b.length, size: 0 });
+
+		this.matchingBlocks = matches;
+		return matches;
+	}
+
+	/**
+	 * Recursively find matching blocks
+	 */
+	private getMatchingBlocksRecursive(
+		alo: number,
+		ahi: number,
+		blo: number,
+		bhi: number,
+		matches: Match[],
+	): void {
+		const match = this.findLongestMatch(alo, ahi, blo, bhi);
+
+		if (match.size > 0) {
+			// Recurse on the pieces before and after the match
+			if (alo < match.a && blo < match.b) {
+				this.getMatchingBlocksRecursive(
+					alo,
+					match.a,
+					blo,
+					match.b,
+					matches,
+				);
+			}
+
+			matches.push(match);
+
+			if (match.a + match.size < ahi && match.b + match.size < bhi) {
+				this.getMatchingBlocksRecursive(
+					match.a + match.size,
+					ahi,
+					match.b + match.size,
+					bhi,
+					matches,
+				);
+			}
+		}
+	}
+
+	/**
+	 * Return list of 5-tuples describing how to turn a into b
+	 */
+	getOpcodes(): OpCodeTuple[] {
+		if (this.opcodes !== null) {
+			return this.opcodes;
+		}
+
+		let i = 0;
+		let j = 0;
+		const opcodes: OpCodeTuple[] = [];
+
+		for (const match of this.getMatchingBlocks()) {
+			let tag: OpCode = "equal";
+
+			if (i < match.a && j < match.b) {
+				tag = "replace";
+			} else if (i < match.a) {
+				tag = "delete";
+			} else if (j < match.b) {
+				tag = "insert";
+			}
+
+			if (tag !== "equal") {
+				opcodes.push({
+					tag,
+					i1: i,
+					i2: match.a,
+					j1: j,
+					j2: match.b,
+				});
+			}
+
+			i = match.a + match.size;
+			j = match.b + match.size;
+
+			// Don't add the sentinel match
+			if (match.size > 0) {
+				opcodes.push({
+					tag: "equal",
+					i1: match.a,
+					i2: i,
+					j1: match.b,
+					j2: j,
+				});
+			}
+		}
+
+		this.opcodes = opcodes;
+		return opcodes;
+	}
+
+	/**
+	 * Return a measure of sequences' similarity (0.0-1.0)
+	 */
+	ratio(): number {
+		const matches = this.getMatchingBlocks()
+			.slice(0, -1) // Exclude sentinel
+			.reduce((sum, match) => sum + match.size, 0);
+
+		const total = this.a.length + this.b.length;
+		return total === 0 ? 1.0 : (2.0 * matches) / total;
+	}
+
+	/**
+	 * Return an upper bound on ratio() relatively quickly
+	 */
+	quickRatio(): number {
+		if (this.fullbcount === null) {
+			this.fullbcount = new Map();
+			for (const element of this.b) {
+				this.fullbcount.set(
+					element,
+					(this.fullbcount.get(element) || 0) + 1,
+				);
+			}
+		}
+
+		let matches = 0;
+		const tempCounts = new Map(this.fullbcount);
+
+		for (const element of this.a) {
+			const count = tempCounts.get(element);
+			if (count && count > 0) {
+				matches++;
+				tempCounts.set(element, count - 1);
+			}
+		}
+
+		const total = this.a.length + this.b.length;
+		return total === 0 ? 1.0 : (2.0 * matches) / total;
+	}
+
+	/**
+	 * Return an upper bound on ratio() very quickly
+	 */
+	realQuickRatio(): number {
+		const total = this.a.length + this.b.length;
+		return total === 0
+			? 1.0
+			: (2.0 * Math.min(this.a.length, this.b.length)) / total;
+	}
+
+	/**
+	 * Check if element is junk in sequence b
+	 */
+	private isBJunk(element: T): boolean {
+		return this.bjunk.has(element);
+	}
+
+	/**
+	 * Check if two elements are equal
+	 */
+	private elementsEqual(a: T, b: T): boolean {
+		return a === b;
+	}
+}
+
+/**
+ * Utility function to get close matches similar to Python's get_close_matches
+ */
+export function getCloseMatches<T>(
+	word: T[],
+	possibilities: T[][],
+	n: number = 3,
+	cutoff: number = 0.6,
+): T[][] {
+	if (n <= 0) {
+		throw new Error("n must be greater than 0");
+	}
+
+	const matches: Array<{ sequence: T[]; ratio: number }> = [];
+
+	for (const possibility of possibilities) {
+		const matcher = new SequenceMatcher(null, word, possibility);
+		const ratio = matcher.ratio();
+
+		if (ratio >= cutoff) {
+			matches.push({ sequence: possibility, ratio });
+		}
+	}
+
+	// Sort by ratio (descending) and take top n
+	matches.sort((a, b) => b.ratio - a.ratio);
+	return matches.slice(0, n).map((match) => match.sequence);
+}
+
+/**
+ * String-specific version of SequenceMatcher for character-by-character comparison.
+ * This class treats strings as sequences of characters while providing a string-friendly API.
+ */
+export class StringSequenceMatcher {
+	private matcher: SequenceMatcher<string>;
+
+	constructor(
+		isjunk: JunkFunction<string> | null = null,
+		a: string = "",
+		b: string = "",
+		autojunk: boolean = true,
+	) {
+		this.matcher = new SequenceMatcher(
+			isjunk,
+			Array.from(a),
+			Array.from(b),
+			autojunk,
+		);
+	}
+
+	/**
+	 * Set both sequences to be compared
+	 */
+	setSeqs(a: string, b: string): void {
+		this.matcher.setSeqs(Array.from(a), Array.from(b));
+	}
+
+	/**
+	 * Set the first sequence to be compared
+	 */
+	setSeq1(a: string): void {
+		this.matcher.setSeq1(Array.from(a));
+	}
+
+	/**
+	 * Set the second sequence to be compared
+	 */
+	setSeq2(b: string): void {
+		this.matcher.setSeq2(Array.from(b));
+	}
+
+	/**
+	 * Find the longest matching block in a[alo:ahi] and b[blo:bhi]
+	 */
+	findLongestMatch(
+		alo: number = 0,
+		ahi: number | null = null,
+		blo: number = 0,
+		bhi: number | null = null,
+	): Match {
+		return this.matcher.findLongestMatch(alo, ahi, blo, bhi);
+	}
+
+	/**
+	 * Return list of non-overlapping matching blocks
+	 */
+	getMatchingBlocks(): Match[] {
+		return this.matcher.getMatchingBlocks();
+	}
+
+	/**
+	 * Return list of 5-tuples describing how to turn a into b
+	 */
+	getOpcodes(): OpCodeTuple[] {
+		return this.matcher.getOpcodes();
+	}
+
+	/**
+	 * Return a measure of sequences' similarity (0.0-1.0)
+	 */
+	ratio(): number {
+		return this.matcher.ratio();
+	}
+
+	/**
+	 * Return an upper bound on ratio() relatively quickly
+	 */
+	quickRatio(): number {
+		return this.matcher.quickRatio();
+	}
+
+	/**
+	 * Return an upper bound on ratio() very quickly
+	 */
+	realQuickRatio(): number {
+		return this.matcher.realQuickRatio();
+	}
+}
+
+/**
+ * Utility function for string similarity
+ */
+export function getStringSimilarity(a: string, b: string): number {
+	const matcher = new StringSequenceMatcher(null, a, b);
+	return matcher.ratio();
+}
+
+/**
+ * Get close string matches
+ */
+export function getCloseStringMatches(
+	word: string,
+	possibilities: string[],
+	n: number = 3,
+	cutoff: number = 0.6,
+): string[] {
+	if (n <= 0) {
+		throw new Error("n must be greater than 0");
+	}
+
+	const matches: Array<{ string: string; ratio: number }> = [];
+
+	for (const possibility of possibilities) {
+		const ratio = getStringSimilarity(word, possibility);
+
+		if (ratio >= cutoff) {
+			matches.push({ string: possibility, ratio });
+		}
+	}
+
+	// Sort by ratio (descending) and take top n
+	matches.sort((a, b) => b.ratio - a.ratio);
+	return matches.slice(0, n).map((match) => match.string);
+}