@schafevormfenster/rest-commons 0.1.1

package/dist/primitives/slug.schema.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+/**
+ * Zod schema for validating slug parameter in community slug endpoint.
+ * Checks for length between 2-150 characters and suspicious patterns.
+ * Enforces lowercase, no spaces, no special characters (only alphanumeric and hyphens).
+ */
+export declare const SlugSchema: z.ZodEffects<z.ZodString, string, string>;
+/**
+ * Zod schema that validates and transforms strings into slugs.
+ * Automatically converts input to URL-safe format.
+ *
+ * @example
+ * SlugSchemaWithTransform.parse("Hello World!") // "hello-world"
+ */
+export declare const SlugSchemaWithTransform: z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodEffects<z.ZodString, string, string>>;
+export type Slug = z.infer<typeof SlugSchema>;
+//# sourceMappingURL=slug.schema.d.ts.map

package/dist/primitives/slug.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug.schema.d.ts","sourceRoot":"","sources":["../../src/primitives/slug.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;GAIG;AACH,eAAO,MAAM,UAAU,2CAgBpB,CAAC;AAEJ;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,qGAGjB,CAAC;AAEpB,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC"}

package/dist/primitives/slug.schema.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { validateNoSuspiciousPatterns } from "../helpers/parameter-validation";
+import { slugify } from "../helpers/slugify";
+/**
+ * Zod schema for validating slug parameter in community slug endpoint.
+ * Checks for length between 2-150 characters and suspicious patterns.
+ * Enforces lowercase, no spaces, no special characters (only alphanumeric and hyphens).
+ */
+export const SlugSchema = z
+    .string()
+    .min(2, "Slug must be at least 2 characters long")
+    .max(150, "Slug must not exceed 150 characters")
+    .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "Slug must be lowercase, contain only alphanumeric characters and hyphens, and not start or end with a hyphen")
+    .refine((value) => {
+    validateNoSuspiciousPatterns(value, "slug");
+    return true;
+}, {
+    message: "Slug parameter contains suspicious patterns that are not allowed",
+});
+/**
+ * Zod schema that validates and transforms strings into slugs.
+ * Automatically converts input to URL-safe format.
+ *
+ * @example
+ * SlugSchemaWithTransform.parse("Hello World!") // "hello-world"
+ */
+export const SlugSchemaWithTransform = z
+    .string()
+    .transform(slugify)
+    .pipe(SlugSchema);

package/dist/primitives/uuid.schema.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+/**
+ * Zod schema for validating UUID v4 format.
+ * Follows RFC 4122 specification.
+ */
+export declare const UuidSchema: z.ZodString;
+export type Uuid = z.infer<typeof UuidSchema>;
+//# sourceMappingURL=uuid.schema.d.ts.map

package/dist/primitives/uuid.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.schema.d.ts","sourceRoot":"","sources":["../../src/primitives/uuid.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,UAAU,aAGqD,CAAC;AAE7E,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC"}

package/dist/primitives/uuid.schema.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+/**
+ * Zod schema for validating UUID v4 format.
+ * Follows RFC 4122 specification.
+ */
+export const UuidSchema = z
+    .string()
+    .uuid("Must be a valid UUID v4")
+    .describe("UUID v4 format (e.g., '550e8400-e29b-41d4-a716-446655440000')");

package/dist/primitives/wikidata-id.schema.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+/**
+ * Zod schema for validating Wikidata QID format.
+ * QIDs are unique identifiers for entities in Wikidata.
+ * Format: Q followed by one or more digits (e.g., "Q64" for Berlin)
+ */
+export declare const WikidataIdSchema: z.ZodString;
+export type WikidataId = z.infer<typeof WikidataIdSchema>;
+//# sourceMappingURL=wikidata-id.schema.d.ts.map

package/dist/primitives/wikidata-id.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wikidata-id.schema.d.ts","sourceRoot":"","sources":["../../src/primitives/wikidata-id.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,aAMkB,CAAC;AAEhD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/primitives/wikidata-id.schema.js

@@ -0,0 +1,10 @@
+import { z } from "zod";
+/**
+ * Zod schema for validating Wikidata QID format.
+ * QIDs are unique identifiers for entities in Wikidata.
+ * Format: Q followed by one or more digits (e.g., "Q64" for Berlin)
+ */
+export const WikidataIdSchema = z
+    .string()
+    .regex(/^Q[1-9]\d*$/, "Must be a valid Wikidata QID (e.g., 'Q64')")
+    .describe("Wikidata entity identifier (QID)");

package/dist/time/boundary-enforcement.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Helper function to clamp a timestamp to the allowed boundaries (-1w to +12m from now)
+ * Returns the clamped ISO8601 timestamp and a boolean indicating if clamping occurred
+ * All calculations are performed in UTC timezone
+ */
+export declare function clampToBoundaries(timestamp: string, fieldName: string, now?: Date): {
+    clamped: string;
+    wasClamped: boolean;
+    originalValue: string;
+};
+//# sourceMappingURL=boundary-enforcement.d.ts.map

package/dist/time/boundary-enforcement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary-enforcement.d.ts","sourceRoot":"","sources":["../../src/time/boundary-enforcement.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,IAAiB,GACrB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAyCjE"}

package/dist/time/boundary-enforcement.js

@@ -0,0 +1,43 @@
+import { getLogger } from "@schafevormfenster/logging";
+import dayjs from "dayjs";
+import utc from "dayjs/plugin/utc.js";
+dayjs.extend(utc);
+const log = getLogger("helpers.time.boundary-enforcement");
+/**
+ * Helper function to clamp a timestamp to the allowed boundaries (-1w to +12m from now)
+ * Returns the clamped ISO8601 timestamp and a boolean indicating if clamping occurred
+ * All calculations are performed in UTC timezone
+ */
+export function clampToBoundaries(timestamp, fieldName, now = new Date()) {
+    const timestampMs = new Date(timestamp).getTime();
+    // Calculate boundaries using Day.js in UTC
+    const minBoundaryMs = dayjs.utc(now).subtract(1, "week").valueOf();
+    const maxBoundaryMs = dayjs.utc(now).add(12, "month").valueOf();
+    let clampedMs = timestampMs;
+    let wasClamped = false;
+    if (timestampMs < minBoundaryMs) {
+        clampedMs = minBoundaryMs;
+        wasClamped = true;
+        log.warn({
+            field: fieldName,
+            originalValue: timestamp,
+            clampedValue: new Date(clampedMs).toISOString(),
+            boundary: "minimum (-1w)",
+        }, `Calendar update query ${fieldName} clamped to minimum boundary`);
+    }
+    else if (timestampMs > maxBoundaryMs) {
+        clampedMs = maxBoundaryMs;
+        wasClamped = true;
+        log.warn({
+            field: fieldName,
+            originalValue: timestamp,
+            clampedValue: new Date(clampedMs).toISOString(),
+            boundary: "maximum (+12m)",
+        }, `Calendar update query ${fieldName} clamped to maximum boundary`);
+    }
+    return {
+        clamped: new Date(clampedMs).toISOString(),
+        wasClamped,
+        originalValue: timestamp,
+    };
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Options for creating bounded schemas
+ */
+export interface BoundaryOptions {
+    /** Minimum allowed time (ISO8601 or relative from now) */
+    min?: string;
+    /** Maximum allowed time (ISO8601 or relative from now) */
+    max?: string;
+}
+/**
+ * Creates a flexible time schema with min/max boundaries
+ * @param options - Boundary configuration
+ * @returns Zod schema with boundary validation
+ * @example
+ * const schema = createBoundedFlexibleTimeSchema({ min: "1w", max: "1M" });
+ * schema.parse("3d"); // valid (between 1 week ago and 1 month in future)
+ * schema.parse("2M"); // throws error (exceeds max)
+ */
+export declare function createBoundedFlexibleTimeSchema(options?: BoundaryOptions): any;
+/**
+ * Creates a relative time schema with min/max boundaries
+ * @param options - Boundary configuration (relative times going backwards from now)
+ * @returns Zod schema with boundary validation
+ * @example
+ * const schema = createBoundedRelativeTimeSchema({ min: "1h", max: "30d" });
+ * schema.parse("3d"); // valid (3 days ago, between 1h and 30d ago)
+ * schema.parse("30m"); // throws error (too recent, less than 1h ago)
+ * schema.parse("60d"); // throws error (too old, more than 30d ago)
+ */
+export declare function createBoundedRelativeTimeSchema(options?: BoundaryOptions): any;
+//# sourceMappingURL=bounded-time.schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-time.schema.d.ts","sourceRoot":"","sources":["../../src/time/bounded-time.schema.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,GAAE,eAAoB,OAsC5E;AAED;;;;;;;;;GASG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,GAAE,eAAoB,OAqC5E"}

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

@@ -0,0 +1,77 @@
+import { FlexibleTimePastSchema } from "./flexible-time.schema";
+import { RelativeTimePastSchema } from "./relative-time.schema";
+import { parseRelativeTime } from "./time-helpers";
+/**
+ * Creates a flexible time schema with min/max boundaries
+ * @param options - Boundary configuration
+ * @returns Zod schema with boundary validation
+ * @example
+ * const schema = createBoundedFlexibleTimeSchema({ min: "1w", max: "1M" });
+ * schema.parse("3d"); // valid (between 1 week ago and 1 month in future)
+ * schema.parse("2M"); // throws error (exceeds max)
+ */
+export function createBoundedFlexibleTimeSchema(options = {}) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let schema = FlexibleTimePastSchema;
+    if (options.min) {
+        // Min is the oldest allowed time (furthest in the past)
+        // For relative times going backwards, larger values are older
+        const minTime = parseRelativeTime(options.min, new Date(), "past");
+        const minMs = new Date(minTime).getTime();
+        schema = schema.refine((value) => {
+            const valueMs = new Date(value).getTime();
+            return valueMs >= minMs;
+        }, {
+            message: `Time must be more recent than ${options.min} ago (minimum: ${minTime})`,
+        });
+    }
+    if (options.max) {
+        // Max is the newest allowed time (can be in future for flexible time)
+        const maxTime = parseRelativeTime(options.max, new Date(), "future");
+        const maxMs = new Date(maxTime).getTime();
+        schema = schema.refine((value) => {
+            const valueMs = new Date(value).getTime();
+            return valueMs <= maxMs;
+        }, {
+            message: `Time must be before ${options.max} in the future (maximum: ${maxTime})`,
+        });
+    }
+    return schema;
+}
+/**
+ * Creates a relative time schema with min/max boundaries
+ * @param options - Boundary configuration (relative times going backwards from now)
+ * @returns Zod schema with boundary validation
+ * @example
+ * const schema = createBoundedRelativeTimeSchema({ min: "1h", max: "30d" });
+ * schema.parse("3d"); // valid (3 days ago, between 1h and 30d ago)
+ * schema.parse("30m"); // throws error (too recent, less than 1h ago)
+ * schema.parse("60d"); // throws error (too old, more than 30d ago)
+ */
+export function createBoundedRelativeTimeSchema(options = {}) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let schema = RelativeTimePastSchema;
+    if (options.min) {
+        // Min is the most recent allowed (closest to now)
+        const minTime = parseRelativeTime(options.min, new Date(), "past");
+        const minMs = new Date(minTime).getTime();
+        schema = schema.refine((value) => {
+            const valueMs = new Date(value).getTime();
+            return valueMs <= minMs; // Value must be older (earlier) than min
+        }, {
+            message: `Time must be at least ${options.min} ago (more recent than ${minTime})`,
+        });
+    }
+    if (options.max) {
+        // Max is the oldest allowed (furthest from now)
+        const maxTime = parseRelativeTime(options.max, new Date(), "past");
+        const maxMs = new Date(maxTime).getTime();
+        schema = schema.refine((value) => {
+            const valueMs = new Date(value).getTime();
+            return valueMs >= maxMs; // Value must be newer (later) than max
+        }, {
+            message: `Time cannot be more than ${options.max} ago (older than ${maxTime})`,
+        });
+    }
+    return schema;
+}

package/dist/time/flexible-time-parser.d.ts

@@ -0,0 +1,12 @@
+import { FlexibleTime } from "./time-schemas";
+/**
+ * Parse a flexible time input (ISO 8601 or relative format) to ISO 8601 string
+ * Uses Zod schemas for validation instead of manual parsing
+ * All calculations are performed in UTC timezone
+ */
+export declare function parseFlexibleTime(input: FlexibleTime, baseTime?: Date): string;
+/**
+ * Create a flexible time parser with a specific base time (useful for testing)
+ */
+export declare function createFlexibleTimeParser(baseTime: Date): (input: FlexibleTime) => string;
+//# sourceMappingURL=flexible-time-parser.d.ts.map

package/dist/time/flexible-time-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flexible-time-parser.d.ts","sourceRoot":"","sources":["../../src/time/flexible-time-parser.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,YAAY,EACb,MAAM,gBAAgB,CAAC;AAKxB;;;;GAIG;AAEH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,YAAY,EACnB,QAAQ,GAAE,IAAiB,GAC1B,MAAM,CA2FR;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,IAAI,IAC7C,OAAO,YAAY,YAC5B"}

package/dist/time/flexible-time-parser.js

@@ -0,0 +1,94 @@
+import dayjs from "dayjs";
+import isoWeek from "dayjs/plugin/isoWeek.js";
+import utc from "dayjs/plugin/utc.js";
+import { ISO8601Schema } from "./iso8601.types";
+import { RelativeTimeSchema, FlexibleTimeSchema, } from "./time-schemas";
+dayjs.extend(isoWeek);
+dayjs.extend(utc);
+/**
+ * Parse a flexible time input (ISO 8601 or relative format) to ISO 8601 string
+ * Uses Zod schemas for validation instead of manual parsing
+ * All calculations are performed in UTC timezone
+ */
+// eslint-disable-next-line sonarjs/cognitive-complexity -- Complex time parsing logic requires multiple conditional branches
+export function parseFlexibleTime(input, baseTime = new Date()) {
+    // First, validate that input is a valid flexible time format
+    const flexibleResult = FlexibleTimeSchema.safeParse(input);
+    if (!flexibleResult.success) {
+        throw new Error(`Invalid time format: ${input}. Expected ISO 8601 date, 'now', 'today', 'tomorrow', 'yesterday', relative format (1s, 2m, 3h, 4d, 5w, -1d, -2w), or week notation (week-start, week-end, week-start+1w, week-end-2w)`);
+    }
+    // Try to parse as ISO 8601 first using Zod validation
+    const isoResult = ISO8601Schema.safeParse(input);
+    if (isoResult.success) {
+        return isoResult.data;
+    }
+    // Try to parse as relative time using Zod validation
+    const relativeResult = RelativeTimeSchema.safeParse(input);
+    if (relativeResult.success) {
+        // Check if it's week notation format
+        const weekMatch = input.match(/^week-(start|end)(([+-])\d+w)?$/);
+        if (weekMatch) {
+            const [, boundary, offsetPart] = weekMatch;
+            let weekOffset = 0;
+            // Parse offset if present (e.g., "+1w", "-2w")
+            if (offsetPart) {
+                const offsetMatch = offsetPart.match(/^([+-])(\d+)w$/);
+                if (offsetMatch) {
+                    const [, sign, amount] = offsetMatch;
+                    weekOffset = Number.parseInt(amount, 10);
+                    if (sign === "-") {
+                        weekOffset = -weekOffset;
+                    }
+                    // Zero offset is not allowed
+                    if (weekOffset === 0) {
+                        throw new Error(`Week offset cannot be zero: ${offsetPart}`);
+                    }
+                }
+            }
+            // Calculate week boundary based on type (in UTC)
+            return boundary === "start" ? dayjs.utc(baseTime).add(weekOffset, "week").startOf("isoWeek").toISOString() : dayjs.utc(baseTime).add(weekOffset, "week").endOf("isoWeek").endOf("day").toISOString();
+        }
+        // Handle literal values
+        if (input === "now") {
+            return baseTime.toISOString();
+        }
+        if (input === "today") {
+            return dayjs.utc(baseTime).startOf("day").toISOString();
+        }
+        // Map shortcuts to relative time format
+        let normalizedInput = input;
+        if (input === "tomorrow") {
+            normalizedInput = "1d";
+        }
+        else if (input === "yesterday") {
+            normalizedInput = "-1d";
+        }
+        // Extract the validated parts using regex (since Zod already validated the format)
+        const match = normalizedInput.match(/^(-?\d+)([smhdw])$/);
+        if (!match) {
+            throw new Error(`Invalid time format: ${input}`);
+        }
+        const [, amountString, unit] = match;
+        const amount = Number.parseInt(amountString, 10);
+        if (amount === 0) {
+            throw new Error(`Time amount cannot be zero: ${amount}`);
+        }
+        // Map unit to Day.js unit names
+        const unitMap = {
+            s: "second",
+            m: "minute",
+            h: "hour",
+            d: "day",
+            w: "week",
+        };
+        const dayjsUnit = unitMap[unit];
+        return dayjs.utc(baseTime).add(amount, dayjsUnit).toISOString();
+    }
+    throw new Error(`Invalid time format: ${input}. Expected ISO 8601 date, 'now', 'today', 'tomorrow', 'yesterday', relative format (1s, 2m, 3h, 4d, 5w, -1d, -2w), or week notation (week-start, week-end, week-start+1w, week-end-2w)`);
+}
+/**
+ * Create a flexible time parser with a specific base time (useful for testing)
+ */
+export function createFlexibleTimeParser(baseTime) {
+    return (input) => parseFlexibleTime(input, baseTime);
+}

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

@@ -0,0 +1,31 @@
+import { z } from "zod";
+/**
+ * Core validation schema for flexible time input
+ * Accepts either ISO8601 datetime or relative time expression
+ * Validates format but does not transform
+ */
+export declare const FlexibleTimeSchema: z.ZodUnion<[z.ZodString, z.ZodString]>;
+export type FlexibleTime = z.infer<typeof FlexibleTimeSchema>;
+/**
+ * Transformation schema that converts flexible time to ISO8601
+ * Direction: past (relative times subtract from current time)
+ * @example
+ * FlexibleTimePastSchema.parse("1d") // "2024-01-14T12:00:00.000Z"
+ * FlexibleTimePastSchema.parse("2024-01-15T12:00:00Z") // "2024-01-15T12:00:00.000Z"
+ */
+export declare const FlexibleTimePastSchema: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodString]>, string, string>;
+/**
+ * Transformation schema that converts flexible time to ISO8601
+ * Direction: future (relative times add to current time)
+ * @example
+ * FlexibleTimeFutureSchema.parse("1d") // "2024-01-16T12:00:00.000Z"
+ * FlexibleTimeFutureSchema.parse("2024-01-15T12:00:00Z") // "2024-01-15T12:00:00.000Z"
+ */
+export declare const FlexibleTimeFutureSchema: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodString]>, string, string>;
+/**
+ * Deprecated: Use FlexibleTimePastSchema instead
+ * @deprecated
+ */
+export declare const SinceParameterSchema: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodString]>, string, string>;
+export type SinceParameter = z.infer<typeof SinceParameterSchema>;
+//# sourceMappingURL=flexible-time.schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flexible-time.schema.d.ts","sourceRoot":"","sources":["../../src/time/flexible-time.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,wCAA+C,CAAC;AAE/E,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,sEAElC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,sEAEpC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,sEAAyB,CAAC;AAC3D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

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

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { ISO8601Schema } from "./iso8601.schema";
+import { RelativeTimeSchema } from "./relative-time.schema";
+import { parseFlexibleTime } from "./time-helpers";
+/**
+ * Core validation schema for flexible time input
+ * Accepts either ISO8601 datetime or relative time expression
+ * Validates format but does not transform
+ */
+export const FlexibleTimeSchema = z.union([ISO8601Schema, RelativeTimeSchema]);
+/**
+ * Transformation schema that converts flexible time to ISO8601
+ * Direction: past (relative times subtract from current time)
+ * @example
+ * FlexibleTimePastSchema.parse("1d") // "2024-01-14T12:00:00.000Z"
+ * FlexibleTimePastSchema.parse("2024-01-15T12:00:00Z") // "2024-01-15T12:00:00.000Z"
+ */
+export const FlexibleTimePastSchema = FlexibleTimeSchema.transform((value) => parseFlexibleTime(value, new Date(), "past"));
+/**
+ * Transformation schema that converts flexible time to ISO8601
+ * Direction: future (relative times add to current time)
+ * @example
+ * FlexibleTimeFutureSchema.parse("1d") // "2024-01-16T12:00:00.000Z"
+ * FlexibleTimeFutureSchema.parse("2024-01-15T12:00:00Z") // "2024-01-15T12:00:00.000Z"
+ */
+export const FlexibleTimeFutureSchema = FlexibleTimeSchema.transform((value) => parseFlexibleTime(value, new Date(), "future"));
+/**
+ * Deprecated: Use FlexibleTimePastSchema instead
+ * @deprecated
+ */
+export const SinceParameterSchema = FlexibleTimePastSchema;

package/dist/time/get-week-end.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Get the end of the week (Sunday at 23:59:59.999 UTC) for a given date
+ * Follows ISO 8601 standard where Sunday is the last day of the week
+ *
+ * @param date - The reference date
+ * @param weekOffset - Number of weeks to offset (positive = future, negative = past)
+ * @returns ISO 8601 string for Sunday 23:59:59.999 UTC
+ */
+export declare function getWeekEnd(date: Date, weekOffset?: number): string;
+//# sourceMappingURL=get-week-end.d.ts.map

package/dist/time/get-week-end.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-week-end.d.ts","sourceRoot":"","sources":["../../src/time/get-week-end.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,SAAI,GAAG,MAAM,CAsB7D"}

package/dist/time/get-week-end.js

@@ -0,0 +1,25 @@
+/**
+ * Get the end of the week (Sunday at 23:59:59.999 UTC) for a given date
+ * Follows ISO 8601 standard where Sunday is the last day of the week
+ *
+ * @param date - The reference date
+ * @param weekOffset - Number of weeks to offset (positive = future, negative = past)
+ * @returns ISO 8601 string for Sunday 23:59:59.999 UTC
+ */
+export function getWeekEnd(date, weekOffset = 0) {
+    const result = new Date(date);
+    // Get current day of week (0 = Sunday, 1 = Monday, ..., 6 = Saturday)
+    const dayOfWeek = result.getUTCDay();
+    // Calculate days to add to get to Sunday
+    // If Sunday (0), stay on same day; otherwise add (7 - dayOfWeek) days
+    const daysToSunday = dayOfWeek === 0 ? 0 : 7 - dayOfWeek;
+    // Set to Sunday of the current week
+    result.setUTCDate(result.getUTCDate() + daysToSunday);
+    // Apply week offset
+    if (weekOffset !== 0) {
+        result.setUTCDate(result.getUTCDate() + weekOffset * 7);
+    }
+    // Set to end of day (23:59:59.999)
+    result.setUTCHours(23, 59, 59, 999);
+    return result.toISOString();
+}

package/dist/time/get-week-start.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Get the start of the week (Monday at 00:00:00 UTC) for a given date
+ * Follows ISO 8601 standard where Monday is the first day of the week
+ *
+ * @param date - The reference date
+ * @param weekOffset - Number of weeks to offset (positive = future, negative = past)
+ * @returns ISO 8601 string for Monday 00:00:00 UTC
+ */
+export declare function getWeekStart(date: Date, weekOffset?: number): string;
+//# sourceMappingURL=get-week-start.d.ts.map

package/dist/time/get-week-start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-week-start.d.ts","sourceRoot":"","sources":["../../src/time/get-week-start.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,SAAI,GAAG,MAAM,CAsB/D"}

package/dist/time/get-week-start.js

@@ -0,0 +1,25 @@
+/**
+ * Get the start of the week (Monday at 00:00:00 UTC) for a given date
+ * Follows ISO 8601 standard where Monday is the first day of the week
+ *
+ * @param date - The reference date
+ * @param weekOffset - Number of weeks to offset (positive = future, negative = past)
+ * @returns ISO 8601 string for Monday 00:00:00 UTC
+ */
+export function getWeekStart(date, weekOffset = 0) {
+    const result = new Date(date);
+    // Get current day of week (0 = Sunday, 1 = Monday, ..., 6 = Saturday)
+    const dayOfWeek = result.getUTCDay();
+    // Calculate days to subtract to get to Monday
+    // If Sunday (0), go back 6 days; otherwise go back (dayOfWeek - 1) days
+    const daysToMonday = dayOfWeek === 0 ? 6 : dayOfWeek - 1;
+    // Set to Monday of the current week
+    result.setUTCDate(result.getUTCDate() - daysToMonday);
+    // Apply week offset
+    if (weekOffset !== 0) {
+        result.setUTCDate(result.getUTCDate() + weekOffset * 7);
+    }
+    // Set to start of day (00:00:00.000)
+    result.setUTCHours(0, 0, 0, 0);
+    return result.toISOString();
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Check if a string is a relative time expression
+ *
+ * @param value - String to check
+ * @returns true if it's a relative time expression
+ */
+export declare const isRelativeTime: (value: string) => boolean;
+//# sourceMappingURL=is-relative-time.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"is-relative-time.d.ts","sourceRoot":"","sources":["../../src/time/is-relative-time.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,OAE9C,CAAC"}

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

@@ -0,0 +1,9 @@
+/**
+ * Check if a string is a relative time expression
+ *
+ * @param value - String to check
+ * @returns true if it's a relative time expression
+ */
+export const isRelativeTime = (value) => {
+    return /^(\d+)[mhdwM]$/.test(value);
+};

package/dist/time/iso8601.schema.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+/**
+ * Core validation schema for ISO8601 datetime strings
+ * Validates format but does not transform
+ */
+export declare const ISO8601Schema: z.ZodString;
+export type ISO8601 = z.infer<typeof ISO8601Schema>;
+/**
+ * Core validation schema for ISO8601 date strings (YYYY-MM-DD)
+ * Validates format but does not transform
+ */
+export declare const ISO8601DateSchema: z.ZodString;
+export type ISO8601Date = z.infer<typeof ISO8601DateSchema>;
+//# sourceMappingURL=iso8601.schema.d.ts.map

package/dist/time/iso8601.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iso8601.schema.d.ts","sourceRoot":"","sources":["../../src/time/iso8601.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,aAAa,aAMvB,CAAC;AAEJ,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,aAM3B,CAAC;AAEJ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/time/iso8601.schema.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+/**
+ * Core validation schema for ISO8601 datetime strings
+ * Validates format but does not transform
+ */
+export const ISO8601Schema = z
+    .string()
+    .describe("Datetime in ISO8601 format")
+    .regex(/^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$/, "Must be a valid ISO8601 datetime (e.g., '2024-01-01T12:00:00Z')");
+/**
+ * Core validation schema for ISO8601 date strings (YYYY-MM-DD)
+ * Validates format but does not transform
+ */
+export const ISO8601DateSchema = z
+    .string()
+    .describe("Date in ISO8601 format")
+    .regex(/^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/, "Date must be in YYYY-MM-DD format with valid month (01-12) and day (01-31)");

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

@@ -0,0 +1,6 @@
+import { z } from "zod";
+export declare const ISO8601Schema: z.ZodEffects<z.ZodString, string, string>;
+export type ISO8601 = z.infer<typeof ISO8601Schema>;
+export declare const ISO8601DateSchema: z.ZodString;
+export type ISO8601Date = z.infer<typeof ISO8601DateSchema>;
+//# sourceMappingURL=iso8601.types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"iso8601.types.d.ts","sourceRoot":"","sources":["../../src/time/iso8601.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,aAAa,2CAMoB,CAAC;AAE/C,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAGpD,eAAO,MAAM,iBAAiB,aAM3B,CAAC;AACJ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/time/iso8601.types.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+export const ISO8601Schema = z
+    .string()
+    .describe("Datetime in ISO8601 format")
+    .regex(/^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$/)
+    .transform((v) => new Date(v).toISOString());
+// ensure valid month and valid day
+export const ISO8601DateSchema = z
+    .string()
+    .describe("Date in ISO8601 format")
+    .regex(/^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/, "Date must be in YYYY-MM-DD format with valid month (01-12) and day (01-31)");

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

@@ -0,0 +1,9 @@
+/**
+ * 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 declare const parseRelativeTime: (relativeTime: string) => string;
+//# sourceMappingURL=parse-relative-time.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parse-relative-time.d.ts","sourceRoot":"","sources":["../../src/time/parse-relative-time.ts"],"names":[],"mappings":"AAQA;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,cAAc,MAAM,KAAG,MAkCxD,CAAC"}