@schafevormfenster/rest-commons 0.1.1

package/src/primitives/international-zip.schema.test.ts

@@ -0,0 +1,212 @@
+import { describe, it, expect } from "vitest";
+
+import {
+  InternationalZipSchema,
+  ZipSchemaByCountry,
+  getZipSchemaForCountry,
+} from "./international-zip.schema";
+
+describe("InternationalZipSchema", () => {
+  it("should accept various international postal code formats", () => {
+    expect(InternationalZipSchema.parse("12345")).toBe("12345");
+    expect(InternationalZipSchema.parse("12-345")).toBe("12-345");
+    expect(InternationalZipSchema.parse("1234 AB")).toBe("1234 AB");
+    expect(InternationalZipSchema.parse("SW1A 1AA")).toBe("SW1A 1AA");
+  });
+
+  it("should reject codes that are too short", () => {
+    expect(() => InternationalZipSchema.parse("12")).toThrow(
+      "Postal code must be at least 3 characters long"
+    );
+  });
+
+  it("should reject codes that are too long", () => {
+    expect(() => InternationalZipSchema.parse("1234567890123")).toThrow(
+      "Postal code must not exceed 12 characters"
+    );
+  });
+
+  it("should reject codes with invalid characters", () => {
+    expect(() => InternationalZipSchema.parse("12345@")).toThrow(
+      "Postal code must contain only alphanumeric characters, spaces, and hyphens"
+    );
+    expect(() => InternationalZipSchema.parse("ABC.DEF")).toThrow(
+      "Postal code must contain only alphanumeric characters, spaces, and hyphens"
+    );
+  });
+});
+
+// Central European Countries (Priority)
+describe("ZipSchemaByCountry.DE (Germany)", () => {
+  it("should accept valid German postal codes", () => {
+    expect(ZipSchemaByCountry.DE.parse("12345")).toBe("12345");
+    expect(ZipSchemaByCountry.DE.parse("80331")).toBe("80331"); // Munich
+    expect(ZipSchemaByCountry.DE.parse("10115")).toBe("10115"); // Berlin
+  });
+
+  it("should reject invalid German postal codes", () => {
+    expect(() => ZipSchemaByCountry.DE.parse("1234")).toThrow();
+    expect(() => ZipSchemaByCountry.DE.parse("123456")).toThrow();
+    expect(() => ZipSchemaByCountry.DE.parse("ABCDE")).toThrow();
+  });
+});
+
+describe("ZipSchemaByCountry.PL (Poland)", () => {
+  it("should accept valid Polish postal codes", () => {
+    expect(ZipSchemaByCountry.PL.parse("00-001")).toBe("00-001"); // Warsaw
+    expect(ZipSchemaByCountry.PL.parse("30-001")).toBe("30-001"); // Krakow
+    expect(ZipSchemaByCountry.PL.parse("80-001")).toBe("80-001"); // Gdansk
+  });
+
+  it("should reject invalid Polish postal codes", () => {
+    expect(() => ZipSchemaByCountry.PL.parse("12345")).toThrow();
+    expect(() => ZipSchemaByCountry.PL.parse("1-234")).toThrow();
+    expect(() => ZipSchemaByCountry.PL.parse("123-45")).toThrow();
+  });
+});
+
+describe("ZipSchemaByCountry.FR (France)", () => {
+  it("should accept valid French postal codes", () => {
+    expect(ZipSchemaByCountry.FR.parse("75001")).toBe("75001"); // Paris
+    expect(ZipSchemaByCountry.FR.parse("69001")).toBe("69001"); // Lyon
+    expect(ZipSchemaByCountry.FR.parse("13001")).toBe("13001"); // Marseille
+  });
+
+  it("should reject invalid French postal codes", () => {
+    expect(() => ZipSchemaByCountry.FR.parse("1234")).toThrow();
+    expect(() => ZipSchemaByCountry.FR.parse("123456")).toThrow();
+  });
+});
+
+describe("ZipSchemaByCountry.AT (Austria)", () => {
+  it("should accept valid Austrian postal codes", () => {
+    expect(ZipSchemaByCountry.AT.parse("1010")).toBe("1010"); // Vienna
+    expect(ZipSchemaByCountry.AT.parse("5020")).toBe("5020"); // Salzburg
+    expect(ZipSchemaByCountry.AT.parse("6020")).toBe("6020"); // Innsbruck
+  });
+
+  it("should reject invalid Austrian postal codes", () => {
+    expect(() => ZipSchemaByCountry.AT.parse("123")).toThrow();
+    expect(() => ZipSchemaByCountry.AT.parse("12345")).toThrow();
+  });
+});
+
+describe("ZipSchemaByCountry.NL (Netherlands)", () => {
+  it("should accept valid Dutch postal codes", () => {
+    expect(ZipSchemaByCountry.NL.parse("1012 AB")).toBe("1012 AB"); // Amsterdam
+    expect(ZipSchemaByCountry.NL.parse("1012AB")).toBe("1012AB");
+    expect(ZipSchemaByCountry.NL.parse("3011 AB")).toBe("3011 AB"); // Rotterdam
+  });
+
+  it("should reject invalid Dutch postal codes", () => {
+    expect(() => ZipSchemaByCountry.NL.parse("12345")).toThrow();
+    expect(() => ZipSchemaByCountry.NL.parse("ABCD EF")).toThrow();
+  });
+});
+
+// Other European Countries
+describe("ZipSchemaByCountry.CH (Switzerland)", () => {
+  it("should accept valid Swiss postal codes", () => {
+    expect(ZipSchemaByCountry.CH.parse("8001")).toBe("8001"); // Zurich
+    expect(ZipSchemaByCountry.CH.parse("1200")).toBe("1200"); // Geneva
+  });
+
+  it("should reject invalid Swiss postal codes", () => {
+    expect(() => ZipSchemaByCountry.CH.parse("123")).toThrow();
+    expect(() => ZipSchemaByCountry.CH.parse("12345")).toThrow();
+  });
+});
+
+describe("ZipSchemaByCountry.IT (Italy)", () => {
+  it("should accept valid Italian CAP codes", () => {
+    expect(ZipSchemaByCountry.IT.parse("00100")).toBe("00100"); // Rome
+    expect(ZipSchemaByCountry.IT.parse("20121")).toBe("20121"); // Milan
+  });
+
+  it("should reject invalid Italian CAP codes", () => {
+    expect(() => ZipSchemaByCountry.IT.parse("1234")).toThrow();
+    expect(() => ZipSchemaByCountry.IT.parse("123456")).toThrow();
+  });
+});
+
+describe("ZipSchemaByCountry.ES (Spain)", () => {
+  it("should accept valid Spanish postal codes", () => {
+    expect(ZipSchemaByCountry.ES.parse("28001")).toBe("28001"); // Madrid
+    expect(ZipSchemaByCountry.ES.parse("08001")).toBe("08001"); // Barcelona
+  });
+
+  it("should reject invalid Spanish postal codes", () => {
+    expect(() => ZipSchemaByCountry.ES.parse("1234")).toThrow();
+    expect(() => ZipSchemaByCountry.ES.parse("123456")).toThrow();
+  });
+});
+
+describe("ZipSchemaByCountry.BE (Belgium)", () => {
+  it("should accept valid Belgian postal codes", () => {
+    expect(ZipSchemaByCountry.BE.parse("1000")).toBe("1000"); // Brussels
+    expect(ZipSchemaByCountry.BE.parse("2000")).toBe("2000"); // Antwerp
+  });
+
+  it("should reject invalid Belgian postal codes", () => {
+    expect(() => ZipSchemaByCountry.BE.parse("123")).toThrow();
+    expect(() => ZipSchemaByCountry.BE.parse("12345")).toThrow();
+  });
+});
+
+describe("ZipSchemaByCountry.CZ (Czech Republic)", () => {
+  it("should accept valid Czech postal codes", () => {
+    expect(ZipSchemaByCountry.CZ.parse("110 00")).toBe("110 00"); // Prague
+    expect(ZipSchemaByCountry.CZ.parse("11000")).toBe("11000");
+    expect(ZipSchemaByCountry.CZ.parse("602 00")).toBe("602 00"); // Brno
+  });
+
+  it("should reject invalid Czech postal codes", () => {
+    expect(() => ZipSchemaByCountry.CZ.parse("123456")).toThrow();
+    expect(() => ZipSchemaByCountry.CZ.parse("1234")).toThrow();
+    expect(() => ZipSchemaByCountry.CZ.parse("12 345")).toThrow();
+  });
+});
+
+describe("ZipSchemaByCountry.UK (United Kingdom)", () => {
+  it("should accept valid UK postcodes", () => {
+    expect(ZipSchemaByCountry.UK.parse("SW1A 1AA")).toBe("SW1A 1AA");
+    expect(ZipSchemaByCountry.UK.parse("SW1A1AA")).toBe("SW1A1AA");
+    expect(ZipSchemaByCountry.UK.parse("M1 1AA")).toBe("M1 1AA");
+    expect(ZipSchemaByCountry.UK.parse("EC1A 1BB")).toBe("EC1A 1BB");
+  });
+
+  it("should reject invalid UK postcodes", () => {
+    expect(() => ZipSchemaByCountry.UK.parse("12345")).toThrow();
+    expect(() => ZipSchemaByCountry.UK.parse("AAA")).toThrow();
+  });
+});
+
+describe("getZipSchemaForCountry", () => {
+  it("should return correct schema for Central European countries", () => {
+    expect(getZipSchemaForCountry("DE")).toBe(ZipSchemaByCountry.DE);
+    expect(getZipSchemaForCountry("de")).toBe(ZipSchemaByCountry.DE);
+    expect(getZipSchemaForCountry("PL")).toBe(ZipSchemaByCountry.PL);
+    expect(getZipSchemaForCountry("FR")).toBe(ZipSchemaByCountry.FR);
+    expect(getZipSchemaForCountry("AT")).toBe(ZipSchemaByCountry.AT);
+    expect(getZipSchemaForCountry("NL")).toBe(ZipSchemaByCountry.NL);
+  });
+
+  it("should return InternationalZipSchema for unknown countries", () => {
+    expect(getZipSchemaForCountry("XX")).toBe(InternationalZipSchema);
+    expect(getZipSchemaForCountry("ZZ")).toBe(InternationalZipSchema);
+  });
+
+  it("should validate postal codes using returned schema", () => {
+    const deSchema = getZipSchemaForCountry("DE");
+    expect(deSchema.parse("12345")).toBe("12345");
+    expect(() => deSchema.parse("ABCDE")).toThrow();
+
+    const plSchema = getZipSchemaForCountry("PL");
+    expect(plSchema.parse("00-001")).toBe("00-001");
+    expect(() => plSchema.parse("12345")).toThrow();
+
+    const unknownSchema = getZipSchemaForCountry("XX");
+    expect(unknownSchema.parse("12345")).toBe("12345");
+    expect(unknownSchema.parse("ABCDE")).toBe("ABCDE");
+  });
+});

package/src/primitives/international-zip.schema.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+
+/**
+ * Zod schema for validating international postal/ZIP codes.
+ * Focuses on Central European formats with support for other common formats.
+ * - Germany: 12345
+ * - Poland: 12-345
+ * - France: 12345
+ * - Austria: 1234
+ * - Netherlands: 1234 AB
+ * - And more
+ */
+export const InternationalZipSchema = z
+  .string()
+  .min(3, "Postal code must be at least 3 characters long")
+  .max(12, "Postal code must not exceed 12 characters")
+  .regex(
+    /^[A-Z0-9\s-]+$/i,
+    "Postal code must contain only alphanumeric characters, spaces, and hyphens"
+  )
+  .describe("International postal/ZIP code");
+
+/**
+ * Country-specific ZIP code schemas for stricter validation.
+ * Focuses on Central European countries (DE, PL, FR, AT, NL) with additional support for common formats.
+ */
+export const ZipSchemaByCountry = {
+  /**
+   * Germany PLZ: 12345 (5 digits)
+   * Most important for Central Europe
+   */
+  DE: z.string().regex(/^\d{5}$/, "Must be a valid German postal code (12345)"),
+  
+  /**
+   * Poland kod pocztowy: 12-345 (2 digits, hyphen, 3 digits)
+   * Most important for Central Europe
+   */
+  PL: z.string().regex(/^\d{2}-\d{3}$/, "Must be a valid Polish postal code (12-345)"),
+  
+  /**
+   * France code postal: 12345 (5 digits)
+   * Most important for Central Europe
+   */
+  FR: z.string().regex(/^\d{5}$/, "Must be a valid French postal code (12345)"),
+  
+  /**
+   * Austria PLZ: 1234 (4 digits)
+   * Most important for Central Europe
+   */
+  AT: z.string().regex(/^\d{4}$/, "Must be a valid Austrian postal code (1234)"),
+  
+  /**
+   * Netherlands postcode: 1234 AB (4 digits, space, 2 letters)
+   * Most important for Central Europe
+   */
+  NL: z.string().regex(/^\d{4}\s?[A-Z]{2}$/i, "Must be a valid Dutch postal code (1234 AB)"),
+  
+  /**
+   * Switzerland PLZ: 1234 (4 digits)
+   */
+  CH: z.string().regex(/^\d{4}$/, "Must be a valid Swiss postal code (1234)"),
+  
+  /**
+   * Italy CAP: 12345 (5 digits)
+   */
+  IT: z.string().regex(/^\d{5}$/, "Must be a valid Italian CAP (12345)"),
+  
+  /**
+   * Spain código postal: 12345 (5 digits)
+   */
+  ES: z.string().regex(/^\d{5}$/, "Must be a valid Spanish postal code (12345)"),
+  
+  /**
+   * Belgium postcode: 1234 (4 digits)
+   */
+  BE: z.string().regex(/^\d{4}$/, "Must be a valid Belgian postal code (1234)"),
+  
+  /**
+   * Czech Republic PSČ: 123 45 (3 digits, space, 2 digits)
+   */
+  CZ: z.string().regex(/^\d{3}\s?\d{2}$/, "Must be a valid Czech postal code (123 45)"),
+  
+  /**
+   * UK postcode: SW1A 1AA
+   */
+  UK: z.string().regex(
+    /^[A-Z]{1,2}\d[A-Z\d]?\s?\d[A-Z]{2}$/i,
+    "Must be a valid UK postcode (SW1A 1AA)"
+  ),
+} as const;
+
+export type InternationalZip = z.infer<typeof InternationalZipSchema>;
+export type CountryCode = keyof typeof ZipSchemaByCountry;
+
+/**
+ * Helper function to get the appropriate ZIP schema for a country
+ * @param countryCode - Two-letter ISO country code
+ * @returns Zod schema for the country's postal code format, or InternationalZipSchema as fallback
+ */
+export function getZipSchemaForCountry(countryCode: string): z.ZodString {
+  const upperCode = countryCode.toUpperCase() as CountryCode;
+  return ZipSchemaByCountry[upperCode] || InternationalZipSchema;
+}

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

@@ -0,0 +1,77 @@
+import { describe, it, expect } from "vitest";
+
+import { LatitudeSchema } from "./latitude.schema";
+
+describe("LatitudeSchema", () => {
+  it("should accept valid latitude values", () => {
+    expect(LatitudeSchema.parse(0)).toBe(0);
+    expect(LatitudeSchema.parse(45)).toBe(45);
+    expect(LatitudeSchema.parse(-45)).toBe(-45);
+    expect(LatitudeSchema.parse(52.52)).toBe(52.52); // Berlin
+    expect(LatitudeSchema.parse(40.7128)).toBe(40.7128); // New York
+  });
+
+  it("should accept boundary values", () => {
+    expect(LatitudeSchema.parse(90)).toBe(90); // North Pole
+    expect(LatitudeSchema.parse(-90)).toBe(-90); // South Pole
+  });
+
+  it("should reject values above 90", () => {
+    expect(() => LatitudeSchema.parse(90.1)).toThrow(
+      "Latitude must be less than or equal to 90"
+    );
+    expect(() => LatitudeSchema.parse(100)).toThrow(
+      "Latitude must be less than or equal to 90"
+    );
+    expect(() => LatitudeSchema.parse(180)).toThrow(
+      "Latitude must be less than or equal to 90"
+    );
+  });
+
+  it("should reject values below -90", () => {
+    expect(() => LatitudeSchema.parse(-90.1)).toThrow(
+      "Latitude must be greater than or equal to -90"
+    );
+    expect(() => LatitudeSchema.parse(-100)).toThrow(
+      "Latitude must be greater than or equal to -90"
+    );
+    expect(() => LatitudeSchema.parse(-180)).toThrow(
+      "Latitude must be greater than or equal to -90"
+    );
+  });
+
+  it("should reject non-numeric values", () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(() => LatitudeSchema.parse("45" as any)).toThrow();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, unicorn/no-null
+    expect(() => LatitudeSchema.parse(null as any)).toThrow();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(() => LatitudeSchema.parse(undefined as any)).toThrow();
+  });
+
+  it("should accept values with up to 8 decimal places", () => {
+    expect(LatitudeSchema.parse(52.52)).toBe(52.52); // 2 decimal places
+    expect(LatitudeSchema.parse(40.7128)).toBe(40.7128); // 4 decimal places
+    expect(LatitudeSchema.parse(52.520_008)).toBe(52.520_008); // 6 decimal places
+    expect(LatitudeSchema.parse(52.520_008_07)).toBe(52.520_008_07); // 8 decimal places
+  });
+
+  it("should reject values with more than 8 decimal places", () => {
+    expect(() => LatitudeSchema.parse(52.520_008_071)).toThrow(
+      "Latitude must have at most 8 decimal places"
+    );
+    expect(() => LatitudeSchema.parse(40.712_812_345_678)).toThrow(
+      "Latitude must have at most 8 decimal places"
+    );
+  });
+
+  it("should handle scientific notation correctly", () => {
+    // Small numbers with few actual decimal places should pass
+    expect(LatitudeSchema.parse(1.23e-4)).toBe(1.23e-4); // 0.000123 = 6 decimals
+    
+    // Numbers with more than 8 decimal places should fail
+    expect(() => LatitudeSchema.parse(1.234_567_89e-1)).toThrow(
+      "Latitude must have at most 8 decimal places"
+    );
+  });
+});

package/src/primitives/latitude.schema.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+
+import { hasValidDecimalPrecision } from "./coordinate-precision";
+
+/**
+ * Zod schema for validating latitude coordinates.
+ * Latitude must be a number between -90 and 90 degrees inclusive.
+ * Maximum precision is 8 decimal places (~1.1mm accuracy).
+ */
+export const LatitudeSchema = z
+  .number()
+  .min(-90, "Latitude must be greater than or equal to -90")
+  .max(90, "Latitude must be less than or equal to 90")
+  .refine(
+    (value) => hasValidDecimalPrecision(value, 8),
+    { message: "Latitude must have at most 8 decimal places" }
+  )
+  .describe("Latitude coordinate in degrees");
+
+export type Latitude = z.infer<typeof LatitudeSchema>;

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

@@ -0,0 +1,21 @@
+import { describe, it, expect } from "vitest";
+
+import { LocationSchema } from "./location.schema";
+
+describe("LocationSchema", () => {
+  it("should accept valid location strings", () => {
+    expect(LocationSchema.parse("Berlin")).toBe("Berlin");
+    expect(LocationSchema.parse("New York, NY")).toBe("New York, NY");
+    expect(LocationSchema.parse("123 Main Street, Anytown")).toBe("123 Main Street, Anytown");
+  });
+
+  it("should reject strings shorter than 2 characters", () => {
+    expect(() => LocationSchema.parse("a")).toThrow("Location must be at least 2 characters long");
+  });
+
+  it("should reject strings with suspicious patterns", () => {
+    expect(() => LocationSchema.parse("<script>alert(1)</script>")).toThrow(
+      "Parameter 'location' contains suspicious patterns: html.script_tag"
+    );
+  });
+});

package/src/primitives/location.schema.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+import { validateNoSuspiciousPatterns } from "../helpers/parameter-validation";
+
+/**
+ * Zod schema for validating location parameter in findbyaddress endpoint.
+ * Checks for minimum length and suspicious patterns.
+ */
+export const LocationSchema = z
+  .string()
+  .min(2, "Location must be at least 2 characters long")
+  .refine(
+    (value) => {
+      validateNoSuspiciousPatterns(value, "location");
+      return true;
+    },
+    {
+      message: "Location parameter contains suspicious patterns that are not allowed",
+    }
+  );
+
+export type Location = z.infer<typeof LocationSchema>;

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

@@ -0,0 +1,77 @@
+import { describe, it, expect } from "vitest";
+
+import { LongitudeSchema } from "./longitude.schema";
+
+describe("LongitudeSchema", () => {
+  it("should accept valid longitude values", () => {
+    expect(LongitudeSchema.parse(0)).toBe(0);
+    expect(LongitudeSchema.parse(90)).toBe(90);
+    expect(LongitudeSchema.parse(-90)).toBe(-90);
+    expect(LongitudeSchema.parse(13.405)).toBe(13.405); // Berlin
+    expect(LongitudeSchema.parse(-74.006)).toBe(-74.006); // New York
+  });
+
+  it("should accept boundary values", () => {
+    expect(LongitudeSchema.parse(180)).toBe(180); // International Date Line
+    expect(LongitudeSchema.parse(-180)).toBe(-180); // International Date Line
+  });
+
+  it("should reject values above 180", () => {
+    expect(() => LongitudeSchema.parse(180.1)).toThrow(
+      "Longitude must be less than or equal to 180"
+    );
+    expect(() => LongitudeSchema.parse(200)).toThrow(
+      "Longitude must be less than or equal to 180"
+    );
+    expect(() => LongitudeSchema.parse(360)).toThrow(
+      "Longitude must be less than or equal to 180"
+    );
+  });
+
+  it("should reject values below -180", () => {
+    expect(() => LongitudeSchema.parse(-180.1)).toThrow(
+      "Longitude must be greater than or equal to -180"
+    );
+    expect(() => LongitudeSchema.parse(-200)).toThrow(
+      "Longitude must be greater than or equal to -180"
+    );
+    expect(() => LongitudeSchema.parse(-360)).toThrow(
+      "Longitude must be greater than or equal to -180"
+    );
+  });
+
+  it("should reject non-numeric values", () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(() => LongitudeSchema.parse("45" as any)).toThrow();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, unicorn/no-null
+    expect(() => LongitudeSchema.parse(null as any)).toThrow();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(() => LongitudeSchema.parse(undefined as any)).toThrow();
+  });
+
+  it("should accept values with up to 8 decimal places", () => {
+    expect(LongitudeSchema.parse(13.405)).toBe(13.405); // 3 decimal places
+    expect(LongitudeSchema.parse(-74.006)).toBe(-74.006); // 3 decimal places
+    expect(LongitudeSchema.parse(151.2093)).toBe(151.2093); // 4 decimal places
+    expect(LongitudeSchema.parse(13.405_000_01)).toBe(13.405_000_01); // 8 decimal places
+  });
+
+  it("should reject values with more than 8 decimal places", () => {
+    expect(() => LongitudeSchema.parse(13.405_000_012)).toThrow(
+      "Longitude must have at most 8 decimal places"
+    );
+    expect(() => LongitudeSchema.parse(-74.006_123_456_789)).toThrow(
+      "Longitude must have at most 8 decimal places"
+    );
+  });
+
+  it("should handle scientific notation correctly", () => {
+    // Small numbers with few actual decimal places should pass
+    expect(LongitudeSchema.parse(1.23e-4)).toBe(1.23e-4); // 0.000123 = 6 decimals
+    
+    // Numbers with more than 8 decimal places should fail
+    expect(() => LongitudeSchema.parse(1.234_567_89e-1)).toThrow(
+      "Longitude must have at most 8 decimal places"
+    );
+  });
+});

package/src/primitives/longitude.schema.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+
+import { hasValidDecimalPrecision } from "./coordinate-precision";
+
+/**
+ * Zod schema for validating longitude coordinates.
+ * Longitude must be a number between -180 and 180 degrees inclusive.
+ * Maximum precision is 8 decimal places (~1.1mm accuracy).
+ */
+export const LongitudeSchema = z
+  .number()
+  .min(-180, "Longitude must be greater than or equal to -180")
+  .max(180, "Longitude must be less than or equal to 180")
+  .refine(
+    (value) => hasValidDecimalPrecision(value, 8),
+    { message: "Longitude must have at most 8 decimal places" }
+  )
+  .describe("Longitude coordinate in degrees");
+
+export type Longitude = z.infer<typeof LongitudeSchema>;

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

@@ -0,0 +1,32 @@
+import { describe, it, expect } from "vitest";
+
+import { NumericIdSchema } from "./numeric-id.schema";
+
+describe("NumericIdSchema", () => {
+  it("should accept valid numeric ID strings", () => {
+    expect(NumericIdSchema.parse("123")).toBe("123");
+    expect(NumericIdSchema.parse("1234567890")).toBe("1234567890");
+    expect(NumericIdSchema.parse("12345678901234567890")).toBe("12345678901234567890");
+  });
+
+  it("should reject strings shorter than 3 characters", () => {
+    expect(() => NumericIdSchema.parse("12")).toThrow("ID must be at least 3 characters long");
+  });
+
+  it("should reject strings longer than 20 characters", () => {
+    expect(() => NumericIdSchema.parse("123456789012345678901")).toThrow("ID must not exceed 20 characters");
+  });
+
+  it("should reject non-numeric strings", () => {
+    expect(() => NumericIdSchema.parse("123abc")).toThrow("ID must contain only numeric characters");
+    expect(() => NumericIdSchema.parse("abc123")).toThrow("ID must contain only numeric characters");
+    expect(() => NumericIdSchema.parse("12-34")).toThrow("ID must contain only numeric characters");
+  });
+
+  it("should reject numeric strings with suspicious patterns", () => {
+    // This test ensures regex validation happens first for non-numeric characters
+    expect(() => NumericIdSchema.parse("123<script>")).toThrow(
+      "ID must contain only numeric characters"
+    );
+  });
+});

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

@@ -0,0 +1,13 @@
+import { z } from "zod";
+
+/**
+ * Zod schema for validating ID parameter in community ID endpoint.
+ * Checks that ID contains only numbers and is between 3-20 characters long.
+ */
+export const NumericIdSchema = z
+  .string()
+  .min(3, "ID must be at least 3 characters long")
+  .max(20, "ID must not exceed 20 characters")
+  .regex(/^\d+$/, "ID must contain only numeric characters");
+
+export type NumericId = z.infer<typeof NumericIdSchema>;