@schafevormfenster/rest-commons 0.1.1

package/src/primitives/slug.schema.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from "vitest";
+
+import { SlugSchema, SlugSchemaWithTransform } from "./slug.schema";
+
+describe("SlugSchema", () => {
+  it("should accept valid slug strings", () => {
+    expect(SlugSchema.parse("my-community")).toBe("my-community");
+    expect(SlugSchema.parse("test-123")).toBe("test-123");
+    expect(SlugSchema.parse("abc-def-ghi")).toBe("abc-def-ghi");
+  });
+
+  it("should accept single hyphen-separated words", () => {
+    expect(SlugSchema.parse("ab")).toBe("ab");
+    expect(SlugSchema.parse("test-slug")).toBe("test-slug");
+  });
+
+  it("should reject strings shorter than 2 characters", () => {
+    expect(() => SlugSchema.parse("a")).toThrow("Slug must be at least 2 characters long");
+  });
+
+  it("should reject strings longer than 150 characters", () => {
+    expect(() => SlugSchema.parse("a".repeat(151))).toThrow("Slug must not exceed 150 characters");
+  });
+
+  it("should reject uppercase letters", () => {
+    expect(() => SlugSchema.parse("My-Community")).toThrow(
+      "Slug must be lowercase, contain only alphanumeric characters and hyphens"
+    );
+    expect(() => SlugSchema.parse("TEST")).toThrow(
+      "Slug must be lowercase, contain only alphanumeric characters and hyphens"
+    );
+  });
+
+  it("should reject spaces", () => {
+    expect(() => SlugSchema.parse("my community")).toThrow(
+      "Slug must be lowercase, contain only alphanumeric characters and hyphens"
+    );
+    expect(() => SlugSchema.parse("test slug")).toThrow(
+      "Slug must be lowercase, contain only alphanumeric characters and hyphens"
+    );
+  });
+
+  it("should reject special characters", () => {
+    expect(() => SlugSchema.parse("my_community")).toThrow(
+      "Slug must be lowercase, contain only alphanumeric characters and hyphens"
+    );
+    expect(() => SlugSchema.parse("test.slug")).toThrow(
+      "Slug must be lowercase, contain only alphanumeric characters and hyphens"
+    );
+    expect(() => SlugSchema.parse("test@slug")).toThrow(
+      "Slug must be lowercase, contain only alphanumeric characters and hyphens"
+    );
+  });
+
+  it("should reject slugs starting or ending with hyphen", () => {
+    expect(() => SlugSchema.parse("-my-community")).toThrow(
+      "Slug must be lowercase, contain only alphanumeric characters and hyphens"
+    );
+    expect(() => SlugSchema.parse("my-community-")).toThrow(
+      "Slug must be lowercase, contain only alphanumeric characters and hyphens"
+    );
+  });
+
+  it("should reject consecutive hyphens", () => {
+    expect(() => SlugSchema.parse("my--community")).toThrow(
+      "Slug must be lowercase, contain only alphanumeric characters and hyphens"
+    );
+  });
+
+  it("should reject strings with suspicious patterns", () => {
+    expect(() => SlugSchema.parse("community<script>")).toThrow();
+  });
+});
+
+describe("SlugSchemaWithTransform", () => {
+  it("should transform and validate strings into slugs", () => {
+    expect(SlugSchemaWithTransform.parse("Hello World")).toBe("hello-world");
+    expect(SlugSchemaWithTransform.parse("My Community")).toBe("my-community");
+    expect(SlugSchemaWithTransform.parse("Berlin, Germany")).toBe("berlin-germany");
+  });
+
+  it("should handle German umlauts", () => {
+    expect(SlugSchemaWithTransform.parse("Café in München")).toBe("cafe-in-muenchen");
+    expect(SlugSchemaWithTransform.parse("Äpfel und Öl")).toBe("aepfel-und-oel");
+  });
+
+  it("should handle already valid slugs", () => {
+    expect(SlugSchemaWithTransform.parse("my-community")).toBe("my-community");
+    expect(SlugSchemaWithTransform.parse("test-slug")).toBe("test-slug");
+  });
+
+  it("should reject slugs that become too short after transformation", () => {
+    expect(() => SlugSchemaWithTransform.parse("!")).toThrow();
+  });
+
+  it("should reject slugs that become too long after transformation", () => {
+    expect(() => SlugSchemaWithTransform.parse("a".repeat(151))).toThrow(
+      "Slug must not exceed 150 characters"
+    );
+  });
+});

package/src/primitives/slug.schema.ts

@@ -0,0 +1,41 @@
+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);
+
+export type Slug = z.infer<typeof SlugSchema>;

package/src/primitives/uuid.schema.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+
+import { UuidSchema } from "./uuid.schema";
+
+describe("UuidSchema", () => {
+  it("should accept valid UUID v4 strings", () => {
+    expect(UuidSchema.parse("550e8400-e29b-41d4-a716-446655440000")).toBe(
+      "550e8400-e29b-41d4-a716-446655440000"
+    );
+    expect(UuidSchema.parse("6ba7b810-9dad-11d1-80b4-00c04fd430c8")).toBe(
+      "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
+    );
+    expect(UuidSchema.parse("00000000-0000-0000-0000-000000000000")).toBe(
+      "00000000-0000-0000-0000-000000000000"
+    );
+  });
+
+  it("should accept UUIDs in uppercase", () => {
+    expect(UuidSchema.parse("550E8400-E29B-41D4-A716-446655440000")).toBe(
+      "550E8400-E29B-41D4-A716-446655440000"
+    );
+  });
+
+  it("should reject invalid UUID formats", () => {
+    expect(() => UuidSchema.parse("not-a-uuid")).toThrow("Must be a valid UUID v4");
+    expect(() => UuidSchema.parse("550e8400-e29b-41d4-a716")).toThrow("Must be a valid UUID v4");
+    expect(() => UuidSchema.parse("550e8400e29b41d4a716446655440000")).toThrow("Must be a valid UUID v4");
+    expect(() => UuidSchema.parse("")).toThrow("Must be a valid UUID v4");
+  });
+
+  it("should reject UUIDs with invalid characters", () => {
+    expect(() => UuidSchema.parse("550e8400-e29b-41d4-a716-44665544000g")).toThrow(
+      "Must be a valid UUID v4"
+    );
+  });
+
+  it("should reject non-string values", () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(() => UuidSchema.parse(123 as any)).toThrow();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, unicorn/no-null
+    expect(() => UuidSchema.parse(null as any)).toThrow();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(() => UuidSchema.parse(undefined as any)).toThrow();
+  });
+});

package/src/primitives/uuid.schema.ts

@@ -0,0 +1,12 @@
+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')");
+
+export type Uuid = z.infer<typeof UuidSchema>;

package/src/primitives/wikidata-id.schema.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+
+import { WikidataIdSchema } from "./wikidata-id.schema";
+
+describe("WikidataIdSchema", () => {
+  it("should accept valid Wikidata QIDs", () => {
+    expect(WikidataIdSchema.parse("Q1")).toBe("Q1"); // Universe
+    expect(WikidataIdSchema.parse("Q64")).toBe("Q64"); // Berlin
+    expect(WikidataIdSchema.parse("Q60")).toBe("Q60"); // New York
+    expect(WikidataIdSchema.parse("Q123456789")).toBe("Q123456789");
+  });
+
+  it("should reject QIDs starting with Q0", () => {
+    expect(() => WikidataIdSchema.parse("Q0")).toThrow("Must be a valid Wikidata QID (e.g., 'Q64')");
+    expect(() => WikidataIdSchema.parse("Q01")).toThrow("Must be a valid Wikidata QID (e.g., 'Q64')");
+    expect(() => WikidataIdSchema.parse("Q012")).toThrow("Must be a valid Wikidata QID (e.g., 'Q64')");
+  });
+
+  it("should reject QIDs without the Q prefix", () => {
+    expect(() => WikidataIdSchema.parse("64")).toThrow("Must be a valid Wikidata QID (e.g., 'Q64')");
+    expect(() => WikidataIdSchema.parse("1")).toThrow("Must be a valid Wikidata QID (e.g., 'Q64')");
+  });
+
+  it("should reject lowercase q", () => {
+    expect(() => WikidataIdSchema.parse("q64")).toThrow("Must be a valid Wikidata QID (e.g., 'Q64')");
+    expect(() => WikidataIdSchema.parse("q1")).toThrow("Must be a valid Wikidata QID (e.g., 'Q64')");
+  });
+
+  it("should reject QIDs with non-numeric characters", () => {
+    expect(() => WikidataIdSchema.parse("Q64a")).toThrow("Must be a valid Wikidata QID (e.g., 'Q64')");
+    expect(() => WikidataIdSchema.parse("Qabc")).toThrow("Must be a valid Wikidata QID (e.g., 'Q64')");
+    expect(() => WikidataIdSchema.parse("Q6-4")).toThrow("Must be a valid Wikidata QID (e.g., 'Q64')");
+  });
+
+  it("should reject empty Q", () => {
+    expect(() => WikidataIdSchema.parse("Q")).toThrow("Must be a valid Wikidata QID (e.g., 'Q64')");
+  });
+
+  it("should reject empty strings", () => {
+    expect(() => WikidataIdSchema.parse("")).toThrow("Must be a valid Wikidata QID (e.g., 'Q64')");
+  });
+
+  it("should reject non-string values", () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(() => WikidataIdSchema.parse(64 as any)).toThrow();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, unicorn/no-null
+    expect(() => WikidataIdSchema.parse(null as any)).toThrow();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(() => WikidataIdSchema.parse(undefined as any)).toThrow();
+  });
+});

package/src/primitives/wikidata-id.schema.ts

@@ -0,0 +1,16 @@
+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)");
+
+export type WikidataId = z.infer<typeof WikidataIdSchema>;

package/src/time/README.md

@@ -0,0 +1,220 @@
+# Time Schema Architecture
+
+This document describes the unified time schema architecture for flexible and type-safe time handling.
+
+## Overview
+
+The time schema module provides a comprehensive, composable set of Zod schemas for handling time inputs in various formats. It supports:
+
+- **ISO8601 timestamps**: Standard datetime strings
+- **Relative times**: Human-readable time expressions like "1d", "3h", "30m"
+- **Flexible times**: Either ISO8601 or relative time
+- **Bounded times**: Min/max constraints on time values
+- **Direction-aware**: Parse relative times as past or future
+
+## Core Schemas
+
+### Validation-Only Schemas
+
+These schemas validate format but don't transform the value:
+
+```typescript
+import { ISO8601Schema } from './iso8601.schema';
+import { RelativeTimeSchema } from './relative-time.schema';
+import { FlexibleTimeSchema } from './flexible-time.schema';
+
+// Validates ISO8601 format
+ISO8601Schema.parse("2024-01-15T12:00:00Z"); // ✓ returns same string
+
+// Validates relative time format  
+RelativeTimeSchema.parse("1d"); // ✓ returns "1d"
+
+// Validates either format
+FlexibleTimeSchema.parse("2024-01-15T12:00:00Z"); // ✓
+FlexibleTimeSchema.parse("3h"); // ✓
+```
+
+### Transformation Schemas
+
+These schemas validate AND transform to ISO8601:
+
+```typescript
+import { 
+  RelativeTimePastSchema,
+  RelativeTimeFutureSchema,
+} from './relative-time.schema';
+import {
+  FlexibleTimePastSchema,
+  FlexibleTimeFutureSchema,
+} from './flexible-time.schema';
+
+// Transform relative time to ISO8601 (subtracting from now)
+RelativeTimePastSchema.parse("1d");
+// → "2024-01-14T12:00:00.000Z" (if now is 2024-01-15T12:00:00Z)
+
+// Transform relative time to ISO8601 (adding to now)
+RelativeTimeFutureSchema.parse("2h");
+// → "2024-01-15T14:00:00.000Z"
+
+// Transform flexible time (past direction for relatives)
+FlexibleTimePastSchema.parse("1d"); // → "2024-01-14T12:00:00.000Z"
+FlexibleTimePastSchema.parse("2024-01-15T12:00:00Z"); // → "2024-01-15T12:00:00.000Z"
+```
+
+## Bounded Schemas
+
+Create schemas with min/max time boundaries:
+
+### Flexible Time with Boundaries
+
+```typescript
+import { createBoundedFlexibleTimeSchema } from './bounded-time.schema';
+
+// Accept times between 1 week ago and 1 month in future
+const schema = createBoundedFlexibleTimeSchema({
+  min: "1w",  // Oldest allowed: 1 week ago
+  max: "1M",  // Newest allowed: 1 month in future
+});
+
+schema.parse("3d"); // ✓ (3 days ago, within range)
+schema.parse("2w"); // ✗ (too old, more than 1w ago)
+schema.parse("2024-01-20T12:00:00Z"); // ✓ (if within range)
+```
+
+### Relative Time with Boundaries
+
+```typescript
+import { createBoundedRelativeTimeSchema } from './bounded-time.schema';
+
+// Accept relative times between 1 hour and 30 days ago
+const schema = createBoundedRelativeTimeSchema({
+  min: "1h",  // Most recent: 1 hour ago
+  max: "30d", // Oldest: 30 days ago
+});
+
+schema.parse("3d"); // ✓ (3 days ago, within range)
+schema.parse("30m"); // ✗ (too recent, less than 1h ago)
+schema.parse("60d"); // ✗ (too old, more than 30d ago)
+```
+
+## Helper Functions
+
+### parseRelativeTime
+
+Parse relative time expression to ISO8601:
+
+```typescript
+import { parseRelativeTime } from './time-helpers';
+
+// Parse relative to a specific date
+const base = new Date("2024-01-15T12:00:00Z");
+
+parseRelativeTime("1d", base, "past");
+// → "2024-01-14T12:00:00.000Z"
+
+parseRelativeTime("2h", base, "future");
+// → "2024-01-15T14:00:00.000Z"
+```
+
+### parseFlexibleTime
+
+Parse flexible time (ISO8601 or relative) to ISO8601:
+
+```typescript
+import { parseFlexibleTime } from './time-helpers';
+
+parseFlexibleTime("2024-01-15T12:00:00Z");
+// → "2024-01-15T12:00:00.000Z"
+
+parseFlexibleTime("1d", new Date(), "past");
+// → ISO8601 string for 1 day ago
+```
+
+## Usage Examples
+
+### API Query Parameter
+
+```typescript
+import { FlexibleTimePastSchema } from './flexible-time.schema';
+
+const QuerySchema = z.object({
+  since: FlexibleTimePastSchema.describe("Start time for query"),
+  until: FlexibleTimePastSchema.optional(),
+});
+
+// Accepts both:
+// ?since=2024-01-15T12:00:00Z
+// ?since=3d (3 days ago)
+```
+
+### Bounded Time Range
+
+```typescript
+import { createBoundedFlexibleTimeSchema } from './bounded-time.schema';
+
+const UpdateQuerySchema = z.object({
+  updatedAfter: createBoundedFlexibleTimeSchema({
+    min: "1w",  // Max 1 week in the past
+    max: "0h",  // Up to now
+  }),
+});
+```
+
+### Log Retention Filter
+
+```typescript
+import { createBoundedRelativeTimeSchema } from './bounded-time.schema';
+
+const LogQuerySchema = z.object({
+  since: createBoundedRelativeTimeSchema({
+    min: "1h",   // At least 1 hour ago
+    max: "90d",  // At most 90 days ago
+  }),
+});
+```
+
+## Type Definitions
+
+```typescript
+// Core types
+type ISO8601 = string;           // ISO8601 datetime string
+type RelativeTime = string;      // e.g., "1d", "3h", "30m"
+type FlexibleTime = ISO8601 | RelativeTime;
+
+// Boundary options
+interface BoundaryOptions {
+  min?: string;         // Minimum allowed time (relative or ISO)
+  max?: string;         // Maximum allowed time (relative or ISO)
+}
+}
+```
+
+## Time Units
+
+Supported time units in relative time expressions:
+
+- `m`: minutes (e.g., "30m" = 30 minutes)
+- `h`: hours (e.g., "2h" = 2 hours)
+- `d`: days (e.g., "3d" = 3 days)
+- `w`: weeks (e.g., "1w" = 1 week)
+- `M`: months (e.g., "2M" = 2 months, using calendar months)
+
+## Best Practices
+
+1. **Use transformation schemas for API inputs**: They automatically convert to ISO8601
+2. **Use bounded schemas for security**: Prevent excessive historical or future queries
+3. **Prefer FlexibleTime for user inputs**: Allows both absolute and relative times
+4. **Use RelativeTime for time-based rules**: When only relative expressions make sense
+5. **Add clear error messages**: Help users understand time constraints
+6. **Import from atomic files**: More efficient bundling and clearer dependencies
+
+## Dependencies
+
+- **dayjs**: Lightweight date manipulation library
+- **zod**: TypeScript-first schema validation
+
+## See Also
+
+- `flexible-time-parser.ts`: Advanced parser with week notation support
+- `boundary-enforcement.ts`: Helper for clamping times to boundaries
+- `iso8601.types.ts`: Legacy ISO8601 schema (deprecated)

package/src/time/boundary-enforcement.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from "vitest";
+
+import { clampToBoundaries } from "./boundary-enforcement";
+
+describe("clampToBoundaries", () => {
+  const now = new Date("2024-01-15T12:00:00.000Z");
+
+  describe("within boundaries", () => {
+    it("should not clamp timestamp within boundaries (-1w to +12m)", () => {
+      const timestamp = "2024-01-10T12:00:00.000Z"; // 5 days ago
+      const result = clampToBoundaries(timestamp, "testField", now);
+
+      expect(result.clamped).toBe(timestamp);
+      expect(result.wasClamped).toBe(false);
+      expect(result.originalValue).toBe(timestamp);
+    });
+
+    it("should not clamp timestamp at minimum boundary (-1w)", () => {
+      const timestamp = "2024-01-08T12:00:00.000Z"; // Exactly 1 week ago
+      const result = clampToBoundaries(timestamp, "testField", now);
+
+      expect(result.clamped).toBe(timestamp);
+      expect(result.wasClamped).toBe(false);
+    });
+
+    it("should not clamp timestamp at maximum boundary (+12m)", () => {
+      const timestamp = "2025-01-15T12:00:00.000Z"; // Exactly 12 months in future
+      const result = clampToBoundaries(timestamp, "testField", now);
+
+      expect(result.clamped).toBe(timestamp);
+      expect(result.wasClamped).toBe(false);
+    });
+
+    it("should not clamp timestamp at current time", () => {
+      const timestamp = now.toISOString();
+      const result = clampToBoundaries(timestamp, "testField", now);
+
+      expect(result.clamped).toBe(timestamp);
+      expect(result.wasClamped).toBe(false);
+    });
+  });
+
+  describe("minimum boundary clamping", () => {
+    it("should clamp timestamp before minimum boundary (-1w)", () => {
+      const timestamp = "2024-01-01T12:00:00.000Z"; // 2 weeks ago
+      const result = clampToBoundaries(timestamp, "testField", now);
+
+      expect(result.wasClamped).toBe(true);
+      expect(result.originalValue).toBe(timestamp);
+      expect(new Date(result.clamped).getTime()).toBeGreaterThan(
+        new Date(timestamp).getTime()
+      );
+      expect(result.clamped).toBe("2024-01-08T12:00:00.000Z"); // Clamped to 1 week ago
+    });
+
+    it("should clamp very old timestamp to minimum boundary", () => {
+      const timestamp = "2020-01-01T12:00:00.000Z"; // Years ago
+      const result = clampToBoundaries(timestamp, "testField", now);
+
+      expect(result.wasClamped).toBe(true);
+      expect(result.clamped).toBe("2024-01-08T12:00:00.000Z");
+    });
+  });
+
+  describe("maximum boundary clamping", () => {
+    it("should clamp timestamp after maximum boundary (+12m)", () => {
+      const timestamp = "2025-02-15T12:00:00.000Z"; // 13 months in future
+      const result = clampToBoundaries(timestamp, "testField", now);
+
+      expect(result.wasClamped).toBe(true);
+      expect(result.originalValue).toBe(timestamp);
+      expect(new Date(result.clamped).getTime()).toBeLessThan(
+        new Date(timestamp).getTime()
+      );
+      expect(result.clamped).toBe("2025-01-15T12:00:00.000Z"); // Clamped to 12 months ahead
+    });
+
+    it("should clamp far future timestamp to maximum boundary", () => {
+      const timestamp = "2030-01-01T12:00:00.000Z"; // Years in future
+      const result = clampToBoundaries(timestamp, "testField", now);
+
+      expect(result.wasClamped).toBe(true);
+      expect(result.clamped).toBe("2025-01-15T12:00:00.000Z");
+    });
+  });
+
+  describe("default parameters", () => {
+    it("should use current time when 'now' is not provided", () => {
+      const timestamp = "2024-01-10T12:00:00.000Z";
+      const result = clampToBoundaries(timestamp, "testField");
+
+      expect(result).toHaveProperty("clamped");
+      expect(result).toHaveProperty("wasClamped");
+      expect(result).toHaveProperty("originalValue");
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle timestamps with milliseconds", () => {
+      const timestamp = "2024-01-10T12:00:00.123Z";
+      const result = clampToBoundaries(timestamp, "testField", now);
+
+      expect(result.wasClamped).toBe(false);
+      expect(result.clamped).toBe(timestamp);
+    });
+
+    it("should handle timestamps in different formats", () => {
+      const timestamp = "2024-01-10T12:00:00+00:00";
+      const result = clampToBoundaries(timestamp, "testField", now);
+
+      expect(result.wasClamped).toBe(false);
+      expect(new Date(result.clamped).getTime()).toBe(
+        new Date(timestamp).getTime()
+      );
+    });
+  });
+
+  describe("field name parameter", () => {
+    it("should accept any field name for logging purposes", () => {
+      const timestamp = "2024-01-01T12:00:00.000Z";
+      const result = clampToBoundaries(
+        timestamp,
+        "customFieldName",
+        now
+      );
+
+      expect(result.wasClamped).toBe(true);
+    });
+  });
+});

package/src/time/boundary-enforcement.ts

@@ -0,0 +1,59 @@
+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: string,
+  fieldName: string,
+  now: Date = new Date()
+): { clamped: string; wasClamped: boolean; originalValue: string } {
+  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,
+  };
+}