@schafevormfenster/rest-commons 0.1.1

package/dist/time/parse-relative-time.js

@@ -0,0 +1,36 @@
+import { getLogger } from "@schafevormfenster/logging";
+import dayjs from "dayjs";
+import utc from "dayjs/plugin/utc.js";
+dayjs.extend(utc);
+const log = getLogger("rest.helpers.relative-time-parser");
+/**
+ * Helper function to convert relative time expressions to ISO8601 timestamps
+ * All calculations are performed in UTC timezone
+ *
+ * @param relativeTime - Relative time expression like "1d", "3h", "30m"
+ * @returns ISO8601 timestamp string
+ */
+export const parseRelativeTime = (relativeTime) => {
+    const relativePattern = /^(\d+)([mhdwM])$/;
+    const match = relativePattern.exec(relativeTime);
+    if (!match) {
+        log.error({ relativeTime, error: `Invalid relative time format: ${relativeTime}` }, `Invalid relative time format: ${relativeTime}`);
+        throw new Error(`Invalid relative time format: ${relativeTime}`);
+    }
+    const [, amount, unit] = match;
+    const numberAmount = Number.parseInt(amount, 10);
+    // Map unit to Day.js unit names
+    const unitMap = {
+        m: "minute",
+        h: "hour",
+        d: "day",
+        w: "week",
+        M: "month",
+    };
+    const dayjsUnit = unitMap[unit];
+    if (!dayjsUnit) {
+        log.error({ unit, error: `Invalid time unit: ${unit}` }, `Invalid time unit: ${unit}`);
+        throw new Error(`Invalid time unit: ${unit}`);
+    }
+    return dayjs.utc().subtract(numberAmount, dayjsUnit).toISOString();
+};

package/dist/time/relative-time.schema.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+/**
+ * Core validation schema for relative time expressions
+ * Supports: "1m" (minute), "2h" (hour), "3d" (day), "1w" (week), "2M" (month)
+ * Validates format but does not transform
+ */
+export declare const RelativeTimeSchema: z.ZodString;
+export type RelativeTime = z.infer<typeof RelativeTimeSchema>;
+/**
+ * Transformation schema that converts relative time to ISO8601
+ * Direction: past (subtracts from current time)
+ * @example
+ * RelativeTimePastSchema.parse("1d") // "2024-01-14T12:00:00.000Z" (if now is 2024-01-15T12:00:00Z)
+ */
+export declare const RelativeTimePastSchema: z.ZodEffects<z.ZodString, string, string>;
+/**
+ * Transformation schema that converts relative time to ISO8601
+ * Direction: future (adds to current time)
+ * @example
+ * RelativeTimeFutureSchema.parse("1d") // "2024-01-16T12:00:00.000Z" (if now is 2024-01-15T12:00:00Z)
+ */
+export declare const RelativeTimeFutureSchema: z.ZodEffects<z.ZodString, string, string>;
+//# sourceMappingURL=relative-time.schema.d.ts.map

package/dist/time/relative-time.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relative-time.schema.d.ts","sourceRoot":"","sources":["../../src/time/relative-time.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,aAM5B,CAAC;AAEJ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,2CAElC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,2CAEpC,CAAC"}

package/dist/time/relative-time.schema.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { parseRelativeTime } from "./time-helpers";
+/**
+ * Core validation schema for relative time expressions
+ * Supports: "1m" (minute), "2h" (hour), "3d" (day), "1w" (week), "2M" (month)
+ * Validates format but does not transform
+ */
+export const RelativeTimeSchema = z
+    .string()
+    .describe("Relative time expression")
+    .regex(/^(\d+)([mhdwM])$/, "Must be a relative time expression (e.g., '1d', '3h', '30m', '1w', '2M')");
+/**
+ * Transformation schema that converts relative time to ISO8601
+ * Direction: past (subtracts from current time)
+ * @example
+ * RelativeTimePastSchema.parse("1d") // "2024-01-14T12:00:00.000Z" (if now is 2024-01-15T12:00:00Z)
+ */
+export const RelativeTimePastSchema = RelativeTimeSchema.transform((value) => parseRelativeTime(value, new Date(), "past"));
+/**
+ * Transformation schema that converts relative time to ISO8601
+ * Direction: future (adds to current time)
+ * @example
+ * RelativeTimeFutureSchema.parse("1d") // "2024-01-16T12:00:00.000Z" (if now is 2024-01-15T12:00:00Z)
+ */
+export const RelativeTimeFutureSchema = RelativeTimeSchema.transform((value) => parseRelativeTime(value, new Date(), "future"));

package/dist/time/since-parameter.schema.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+/**
+ * Schema that accepts either ISO8601 timestamps or relative time expressions
+ * All calculations are performed in UTC timezone
+ */
+export declare const SinceParameterSchema: z.ZodEffects<z.ZodString, string, string>;
+export type SinceParameter = z.infer<typeof SinceParameterSchema>;
+//# sourceMappingURL=since-parameter.schema.d.ts.map

package/dist/time/since-parameter.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"since-parameter.schema.d.ts","sourceRoot":"","sources":["../../src/time/since-parameter.schema.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;GAGG;AACH,eAAO,MAAM,oBAAoB,2CAwD7B,CAAC;AAEL,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/time/since-parameter.schema.js

@@ -0,0 +1,56 @@
+import dayjs from "dayjs";
+import utc from "dayjs/plugin/utc.js";
+import { z } from "zod";
+dayjs.extend(utc);
+/**
+ * Schema that accepts either ISO8601 timestamps or relative time expressions
+ * All calculations are performed in UTC timezone
+ */
+export const SinceParameterSchema = z
+    .string()
+    .describe("Timestamp in ISO8601 format or relative time expression")
+    .transform((value, context) => {
+    // Try to parse as ISO8601 first
+    const iso8601Pattern = /^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$/;
+    if (iso8601Pattern.test(value)) {
+        try {
+            return new Date(value).toISOString();
+        }
+        catch {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "Invalid ISO8601 timestamp format",
+            });
+            return z.NEVER;
+        }
+    }
+    // Try to parse as relative time
+    const relativePattern = /^(\d+)([mhdwM])$/;
+    const match = relativePattern.exec(value);
+    if (!match) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Must be either ISO8601 timestamp or relative time expression (e.g., '1d', '3h', '30m')",
+        });
+        return z.NEVER;
+    }
+    const [, amount, unit] = match;
+    const numberAmount = Number.parseInt(amount, 10);
+    // Map unit to Day.js unit names
+    const unitMap = {
+        m: "minute",
+        h: "hour",
+        d: "day",
+        w: "week",
+        M: "month",
+    };
+    const dayjsUnit = unitMap[unit];
+    if (!dayjsUnit) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Invalid time unit. Use 'm' (minutes), 'h' (hours), 'd' (days), 'w' (weeks), or 'M' (months)",
+        });
+        return z.NEVER;
+    }
+    return dayjs.utc().subtract(numberAmount, dayjsUnit).toISOString();
+});

package/dist/time/time-helpers.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Helper function to parse relative time and calculate the datetime
+ * All calculations are performed in UTC timezone
+ * @param relativeTime - Relative time string like "1d", "3h", "30m"
+ * @param from - Base datetime to calculate from (defaults to now)
+ * @param direction - Whether to subtract (past) or add (future)
+ * @returns ISO8601 datetime string
+ */
+export declare function parseRelativeTime(relativeTime: string, from?: Date, direction?: "past" | "future"): string;
+/**
+ * Helper function to parse flexible time (ISO8601 or relative) to ISO8601
+ * All calculations are performed in UTC timezone
+ * @param flexibleTime - ISO8601 string or relative time expression
+ * @param from - Base datetime for relative time calculations (defaults to now)
+ * @param direction - Whether relative times are past or future (defaults to past)
+ * @returns ISO8601 datetime string
+ */
+export declare function parseFlexibleTime(flexibleTime: string, from?: Date, direction?: "past" | "future"): string;
+//# sourceMappingURL=time-helpers.d.ts.map

package/dist/time/time-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-helpers.d.ts","sourceRoot":"","sources":["../../src/time/time-helpers.ts"],"names":[],"mappings":"AAQA;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,IAAI,GAAE,IAAiB,EACvB,SAAS,GAAE,MAAM,GAAG,QAAiB,GACpC,MAAM,CA2BR;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,IAAI,GAAE,IAAiB,EACvB,SAAS,GAAE,MAAM,GAAG,QAAiB,GACpC,MAAM,CAgBR"}

package/dist/time/time-helpers.js

@@ -0,0 +1,56 @@
+import dayjs from "dayjs";
+import utc from "dayjs/plugin/utc.js";
+import { ISO8601Schema } from "./iso8601.schema";
+import { RelativeTimeSchema } from "./relative-time.schema";
+dayjs.extend(utc);
+/**
+ * Helper function to parse relative time and calculate the datetime
+ * All calculations are performed in UTC timezone
+ * @param relativeTime - Relative time string like "1d", "3h", "30m"
+ * @param from - Base datetime to calculate from (defaults to now)
+ * @param direction - Whether to subtract (past) or add (future)
+ * @returns ISO8601 datetime string
+ */
+export function parseRelativeTime(relativeTime, from = new Date(), direction = "past") {
+    const match = relativeTime.match(/^(\d+)([mhdwM])$/);
+    if (!match) {
+        throw new Error(`Invalid relative time format: ${relativeTime}. Expected format like '1d', '3h', '30m'`);
+    }
+    const [, amount, unit] = match;
+    const numberAmount = Number.parseInt(amount, 10);
+    // Map unit to Day.js unit names
+    const unitMap = {
+        m: "minute",
+        h: "hour",
+        d: "day",
+        w: "week",
+        M: "month",
+    };
+    const dayjsUnit = unitMap[unit];
+    if (!dayjsUnit) {
+        throw new Error(`Invalid time unit: ${unit}`);
+    }
+    const operation = direction === "past" ? "subtract" : "add";
+    return dayjs.utc(from)[operation](numberAmount, dayjsUnit).toISOString();
+}
+/**
+ * Helper function to parse flexible time (ISO8601 or relative) to ISO8601
+ * All calculations are performed in UTC timezone
+ * @param flexibleTime - ISO8601 string or relative time expression
+ * @param from - Base datetime for relative time calculations (defaults to now)
+ * @param direction - Whether relative times are past or future (defaults to past)
+ * @returns ISO8601 datetime string
+ */
+export function parseFlexibleTime(flexibleTime, from = new Date(), direction = "past") {
+    // Try to parse as ISO8601 first
+    const isoResult = ISO8601Schema.safeParse(flexibleTime);
+    if (isoResult.success) {
+        return new Date(flexibleTime).toISOString();
+    }
+    // Try to parse as relative time
+    const relativeResult = RelativeTimeSchema.safeParse(flexibleTime);
+    if (relativeResult.success) {
+        return parseRelativeTime(flexibleTime, from, direction);
+    }
+    throw new Error(`Invalid flexible time format: ${flexibleTime}. Expected ISO8601 datetime or relative time expression`);
+}

package/dist/time/time-schemas.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+export type TimeUnit = "s" | "m" | "h" | "d" | "w";
+export interface RelativeTimeConfig {
+    amount: number;
+    unit: TimeUnit;
+}
+export declare const RelativeTimeSchema: z.ZodUnion<[z.ZodLiteral<"now">, z.ZodLiteral<"today">, z.ZodLiteral<"tomorrow">, z.ZodLiteral<"yesterday">, z.ZodString, z.ZodString]>;
+/**
+ * Flexible time schema that accepts either ISO 8601 dates or relative time formats
+ *
+ * Supports:
+ * - ISO 8601 dates: "2024-01-01T12:00:00Z"
+ * - Literals: "now" (current datetime), "today" (current day at 00:00:00), "tomorrow" (next day), "yesterday" (previous day)
+ * - Relative future times: "30s", "5m", "2h", "3d", "1w" (positive = future)
+ * - Relative past times: "-1d" (yesterday), "-2w" (2 weeks ago) (negative = past)
+ * - Week notation: "week-start" (Monday 00:00:00), "week-end" (Sunday 23:59:59), "week-start+1w" (next week start), "week-end-2w" (end of 2 weeks ago)
+ */
+export declare const FlexibleTimeSchema: z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodUnion<[z.ZodLiteral<"now">, z.ZodLiteral<"today">, z.ZodLiteral<"tomorrow">, z.ZodLiteral<"yesterday">, z.ZodString, z.ZodString]>]>;
+export type FlexibleTime = z.infer<typeof FlexibleTimeSchema>;
+//# sourceMappingURL=time-schemas.d.ts.map

package/dist/time/time-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-schemas.d.ts","sourceRoot":"","sources":["../../src/time/time-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,MAAM,MAAM,QAAQ,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEnD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,eAAO,MAAM,kBAAkB,yIAiB7B,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,kMAA+C,CAAC;AAC/E,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/time/time-schemas.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { ISO8601Schema } from "./iso8601.types";
+export const RelativeTimeSchema = z.union([
+    z.literal("now"),
+    z.literal("today"),
+    z.literal("tomorrow"),
+    z.literal("yesterday"),
+    z
+        .string()
+        .regex(/^(-?\d+)([smhdw])$/, "Invalid relative time format. Use format like '1m' (1 min future), '2h' (2 hours future), '3d' (3 days future), '-1d' (1 day past), '-2w' (2 weeks past)"),
+    z
+        .string()
+        .regex(/^week-(start|end)(([+-])\d+w)?$/, "Invalid week notation format. Use format like 'week-start', 'week-end', 'week-start+1w', 'week-end-2w'"),
+]);
+/**
+ * Flexible time schema that accepts either ISO 8601 dates or relative time formats
+ *
+ * Supports:
+ * - ISO 8601 dates: "2024-01-01T12:00:00Z"
+ * - Literals: "now" (current datetime), "today" (current day at 00:00:00), "tomorrow" (next day), "yesterday" (previous day)
+ * - Relative future times: "30s", "5m", "2h", "3d", "1w" (positive = future)
+ * - Relative past times: "-1d" (yesterday), "-2w" (2 weeks ago) (negative = past)
+ * - Week notation: "week-start" (Monday 00:00:00), "week-end" (Sunday 23:59:59), "week-start+1w" (next week start), "week-end-2w" (end of 2 weeks ago)
+ */
+export const FlexibleTimeSchema = z.union([ISO8601Schema, RelativeTimeSchema]);

package/dist/time/timezone.types.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+/**
+ * Formatted as an IANA Time Zone Database name, e.g. "Europe/Zurich"
+ */
+export declare const IanaTimezone: z.ZodString;
+/**
+ * Common time standards like UTC, GMT, etc.
+ */
+export declare const TimeStandard: z.ZodString;
+/**
+ * Timezone that can be either an IANA timezone or a time standard
+ */
+export declare const Timezone: z.ZodUnion<[z.ZodString, z.ZodString]>;
+export type IanaTimezone = z.infer<typeof IanaTimezone>;
+export type TimeStandard = z.infer<typeof TimeStandard>;
+export type Timezone = z.infer<typeof Timezone>;
+//# sourceMappingURL=timezone.types.d.ts.map

package/dist/time/timezone.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timezone.types.d.ts","sourceRoot":"","sources":["../../src/time/timezone.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,eAAO,MAAM,YAAY,aAA+C,CAAC;AAEzE;;GAEG;AACH,eAAO,MAAM,YAAY,aAE8B,CAAC;AAExD;;GAEG;AACH,eAAO,MAAM,QAAQ,wCAAwC,CAAC;AAE9D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AACxD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AACxD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC"}

package/dist/time/timezone.types.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+/**
+ * Formatted as an IANA Time Zone Database name, e.g. "Europe/Zurich"
+ */
+export const IanaTimezone = z.string().regex(/^[A-Za-z_]+\/[A-Za-z_]+$/);
+/**
+ * Common time standards like UTC, GMT, etc.
+ */
+export const TimeStandard = z
+    .string()
+    .regex(/^(UTC|GMT|EST|CST|MST|PST|EDT|CDT|MDT|PDT)$/);
+/**
+ * Timezone that can be either an IANA timezone or a time standard
+ */
+export const Timezone = z.union([IanaTimezone, TimeStandard]);

package/dist/validation/zod-error-handler.d.ts

@@ -0,0 +1,3 @@
+import { TsRestResponse } from "@ts-rest/serverless";
+export declare function handleZodError(error: unknown): Promise<TsRestResponse>;
+//# sourceMappingURL=zod-error-handler.d.ts.map

package/dist/validation/zod-error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-error-handler.d.ts","sourceRoot":"","sources":["../../src/validation/zod-error-handler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AA0GrD,wBAAsB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CAqI5E"}

package/dist/validation/zod-error-handler.js

@@ -0,0 +1,189 @@
+import { getLogger } from "@schafevormfenster/logging";
+import { TsRestResponse } from "@ts-rest/serverless";
+import { ZodError } from "zod";
+const log = getLogger("api.validation.zod");
+/**
+ * Extract a meaningful error summary from ZodError
+ * Simplified version to reduce cognitive complexity
+ */
+function getZodErrorSummary(error) {
+    if (!error.issues || error.issues.length === 0) {
+        return "Validation error: Validation failed";
+    }
+    // Check for union errors
+    const unionIssue = error.issues.find((issue) => issue.code === "invalid_union" &&
+        "unionErrors" in issue &&
+        Array.isArray(issue.unionErrors));
+    if (unionIssue && "unionErrors" in unionIssue) {
+        const errors = extractUnionErrors(unionIssue.unionErrors);
+        if (errors.length > 0) {
+            return formatErrorSummary(errors.slice(0, 3).join("; "));
+        }
+    }
+    // Fallback to first issue
+    const firstIssue = error.issues[0];
+    const path = firstIssue.path.length > 0 ? firstIssue.path.join(".") : "input";
+    return formatErrorSummary(`${firstIssue.message} at ${path}`);
+}
+/**
+ * Extract non-discriminator errors from union branches
+ * Simplified to reduce cognitive complexity
+ */
+function extractUnionErrors(unionErrors) {
+    const errors = [];
+    for (const unionError of unionErrors) {
+        if (!(unionError instanceof ZodError) || unionError.issues.length === 0) {
+            continue;
+        }
+        const relevantIssues = unionError.issues.filter((subIssue) => subIssue.code !== "invalid_literal" &&
+            subIssue.code !== "invalid_union");
+        for (const subIssue of relevantIssues) {
+            const path = subIssue.path.length > 0 ? subIssue.path.join(".") : "input";
+            errors.push(`${subIssue.message} (${path})`);
+        }
+    }
+    return errors;
+}
+/**
+ * Format error summary with consistent prefix
+ */
+function formatErrorSummary(summary) {
+    return summary.toLowerCase().startsWith("validation error")
+        ? summary
+        : `Validation error: ${summary}`;
+}
+/**
+ * Check if error is likely a response validation error (from ts-rest)
+ * Response validation errors typically have statusCode property set by ts-rest
+ */
+function isResponseValidationError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "statusCode" in error &&
+        error.statusCode === 500);
+}
+/**
+ * Safely extract and truncate request body for logging
+ * Following defensive logging guidelines - never assume payload structure
+ */
+function getSafePayloadExcerpt(payload) {
+    if (!payload) {
+        return undefined;
+    }
+    try {
+        const jsonString = JSON.stringify(payload);
+        // Truncate to 500 characters to avoid excessive log size
+        return jsonString.slice(0, 500);
+    }
+    catch {
+        // If JSON.stringify fails (circular references, etc.), fall back to type check
+        return `[Unable to serialize: ${typeof payload}]`;
+    }
+}
+export async function handleZodError(error) {
+    // JSON parsing errors (SyntaxError from malformed JSON)
+    if (error instanceof SyntaxError) {
+        const jsonError = {
+            status: 400,
+            error: `Invalid JSON: ${error.message}`,
+            trace: error,
+        };
+        log.error({ error: jsonError }, "JSON parsing error occurred");
+        return new TsRestResponse(JSON.stringify(jsonError), {
+            status: 400,
+            headers: {
+                "Content-Type": "application/json",
+            },
+        });
+    }
+    // Input validation errors (ZodError from request validation)
+    if (error instanceof ZodError) {
+        const errorSummary = getZodErrorSummary(error);
+        const zodError = {
+            status: 400,
+            error: errorSummary,
+            trace: error,
+        };
+        // Note: Direct ZodError typically doesn't have request body access
+        // Request body is available in ts-rest wrapper errors (handled below)
+        log.error({ error: zodError }, "Input validation error occurred");
+        return new TsRestResponse(JSON.stringify(zodError), {
+            status: 400,
+            headers: {
+                "Content-Type": "application/json",
+            },
+        });
+    }
+    // Response validation errors (statusCode 500 from ts-rest)
+    if (isResponseValidationError(error)) {
+        const errorObject = error;
+        let errorMessage = "Response validation failed";
+        // Extract meaningful error from ZodError cause if available
+        if (errorObject.cause instanceof ZodError) {
+            errorMessage = `Response validation failed: ${getZodErrorSummary(errorObject.cause)}`;
+        }
+        const responseError = {
+            status: 500,
+            error: errorMessage,
+            trace: error,
+        };
+        log.error({ error: responseError }, "Response validation error occurred");
+        return new TsRestResponse(JSON.stringify(responseError), {
+            status: 500,
+            headers: {
+                "Content-Type": "application/json",
+            },
+        });
+    }
+    // Input validation errors with statusCode 400 (from ts-rest request validation)
+    if (typeof error === "object" &&
+        error !== null &&
+        "statusCode" in error &&
+        error.statusCode === 400) {
+        const errorObject = error;
+        let errorMessage = "Validation Error";
+        // Extract meaningful error from ZodError cause or bodyError if available
+        if (errorObject.cause instanceof ZodError) {
+            errorMessage = getZodErrorSummary(errorObject.cause);
+        }
+        else if (errorObject.bodyError instanceof ZodError) {
+            errorMessage = getZodErrorSummary(errorObject.bodyError);
+        }
+        // Extract request body for debugging if available
+        const requestBody = errorObject.body && "body" in errorObject.body ? errorObject.body.body : undefined;
+        // Get safe truncated payload excerpt for logging
+        const payloadExcerpt = getSafePayloadExcerpt(requestBody);
+        const zodError = {
+            status: 400,
+            error: errorMessage,
+            trace: {
+                ...error,
+                requestBody, // Include the actual request body for debugging
+            },
+        };
+        // Enhanced logging with sanitized payload excerpt
+        log.error({
+            error: zodError,
+            payloadExcerpt, // Truncated, safe payload snapshot
+        }, "Input validation error occurred");
+        return new TsRestResponse(JSON.stringify(zodError), {
+            status: 400,
+            headers: {
+                "Content-Type": "application/json",
+            },
+        });
+    }
+    // Unknown errors
+    const unknownError = {
+        status: 500,
+        error: "Internal Server Error",
+        trace: error,
+    };
+    log.error({ error: unknownError }, "An unknown error occurred");
+    return new TsRestResponse(JSON.stringify(unknownError), {
+        status: 500,
+        headers: {
+            "Content-Type": "application/json",
+        },
+    });
+}

package/dist/validation/zod-utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Extracts a clean, user-friendly error message from Zod validation errors.
+ * Returns the first validation error message instead of the full error object.
+ *
+ * @param error - The error from Zod validation
+ * @returns Clean error message string
+ */
+export declare function extractZodErrorMessage(error: unknown): string;
+//# sourceMappingURL=zod-utils.d.ts.map

package/dist/validation/zod-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-utils.d.ts","sourceRoot":"","sources":["../../src/validation/zod-utils.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAgB7D"}

package/dist/validation/zod-utils.js

@@ -0,0 +1,23 @@
+import { ZodError } from "zod";
+/**
+ * Extracts a clean, user-friendly error message from Zod validation errors.
+ * Returns the first validation error message instead of the full error object.
+ *
+ * @param error - The error from Zod validation
+ * @returns Clean error message string
+ */
+export function extractZodErrorMessage(error) {
+    if (error instanceof ZodError) {
+        // Get the first error message from Zod validation
+        const firstError = error.errors[0];
+        if (firstError?.message && firstError.message.trim() !== "") {
+            return firstError.message;
+        }
+        // If ZodError has no useful message, return default instead of falling through to Error branch
+        return "Schema validation failed";
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return "Schema validation failed";
+}

package/eslint.config.mjs

@@ -0,0 +1,16 @@
+import baseConfig from "@schafevormfenster/eslint-config";
+import vitestConfig from "@schafevormfenster/eslint-config/vitest";
+
+export default [
+  ...baseConfig,
+  ...vitestConfig,
+  {
+    ignores: ["dist/**", "node_modules/**", "bin/**"],
+  },
+  {
+    rules: {
+      "import/no-unresolved": "off", // TypeScript handles this
+      "import/named": "off", // TypeScript handles type exports
+    },
+  },
+];

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@schafevormfenster/rest-commons",
+  "version": "0.1.1",
+  "description": "Centralized authority for REST standards and schemas - XSD schemas, parsing functions, and coding instructions",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "setup-rest-commons": "./bin/setup.js"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.3",
+    "@typescript-eslint/eslint-plugin": "^8.51.0",
+    "@typescript-eslint/parser": "^8.51.0",
+    "eslint": "^9.39.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16",
+    "@schafevormfenster/eslint-config": "0.0.7"
+  },
+  "dependencies": {
+    "dayjs": "^1.11.19",
+    "slugify": "^1.6.6",
+    "zod": "^3.25.76",
+    "@schafevormfenster/logging": "0.1.0",
+    "@schafevormfenster/security": "0.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint",
+    "test": "TZ=UTC vitest run",
+    "test:watch": "TZ=UTC vitest",
+    "build": "tsc",
+    "check": "pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run build"
+  }
+}

package/src/api-schemas/error.schema.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from "vitest";
+
+import { ApiErrorSchema, ApiErrorConstructor } from "./error.schema";
+
+describe("ApiErrorSchema", () => {
+  it("validates error shape for 4xx/5xx", () => {
+    const parsed = ApiErrorSchema.parse({ status: 404, error: "Not Found" });
+    expect(parsed.status).toBe(404);
+    expect(parsed.error).toMatch(/not found/i);
+  });
+
+  it("rejects non-error status codes", () => {
+    expect(() => ApiErrorSchema.parse({ status: 200, error: "ok" })).toThrow();
+    expect(() =>
+      ApiErrorSchema.parse({ status: 600, error: "invalid" })
+    ).toThrow();
+  });
+});
+
+describe("ApiError class", () => {
+  it("sets status and name", () => {
+    const error = new ApiErrorConstructor(418, "I'm a teapot");
+    expect(error.status).toBe(418);
+    expect(error.message).toMatch(/i'm a teapot/i);
+    expect(error.name).toBe("ApiError");
+  });
+});