@webpieces/http-api 0.2.16 → 0.2.21

package/src/PlatformHeadersExtension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlatformHeadersExtension.js","sourceRoot":"","sources":["../../../../../packages/http/http-api/src/PlatformHeadersExtension.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAa,wBAAwB;IAMjC,YAAY,OAAyB;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,UAAU;QACN,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;CACJ;AAjBD,4DAiBC","sourcesContent":["import { PlatformHeader } from './PlatformHeader';\n\n/**\n * PlatformHeadersExtension - Extension that contributes platform headers to the framework.\n *\n * This is a DI-level extension (not an app-level Plugin).\n * Multiple modules can bind PlatformHeadersExtension instances, and the framework\n * collects them via Inversify @multiInject.\n *\n * Two-level plugin system:\n * 1. **Extensions** (DI-level): Contribute specific capabilities to framework\n *    - Examples: PlatformHeadersExtension, BodyContentExtension, EntityLookupExtension\n *    - Pattern: Bound via multiInject, consumed by framework\n *    - Java equivalent: Multibinder<AddPlatformHeaders>, Multibinder<BodyContentBinder>\n *\n * 2. **Plugins** (App-level): Provide complete features with modules + routes\n *    - Examples: HibernatePlugin, JacksonPlugin, Auth0Plugin\n *    - Pattern: Implements getGuiceModules() + getRouteModules()\n *    - Java equivalent: Plugin interface with getGuiceModules() + getRouteModules()\n *\n * Usage:\n * ```typescript\n * // In WebpiecesModule\n * const coreExtension = new PlatformHeadersExtension([\n *     WebpiecesCoreHeaders.REQUEST_ID,\n *     WebpiecesCoreHeaders.CORRELATION_ID,\n * ]);\n * bind(HEADER_TYPES.PlatformHeadersExtension).toConstantValue(coreExtension);\n *\n * // In CompanyModule\n * const companyExtension = new PlatformHeadersExtension([\n *     CompanyHeaders.TENANT_ID,\n *     CompanyHeaders.API_VERSION,\n * ]);\n * bind(HEADER_TYPES.PlatformHeadersExtension).toConstantValue(companyExtension);\n *\n * // Framework collects all extensions\n * constructor(@multiInject(HEADER_TYPES.PlatformHeadersExtension) extensions: PlatformHeadersExtension[]) {}\n * ```\n */\nexport class PlatformHeadersExtension {\n    /**\n     * The set of platform headers contributed by this extension.\n     */\n    readonly headers: PlatformHeader[];\n\n    constructor(headers: PlatformHeader[]) {\n        this.headers = headers;\n    }\n\n    /**\n     * Get all headers from this extension.\n     * @returns Array of platform headers\n     */\n    getHeaders(): PlatformHeader[] {\n        return this.headers;\n    }\n}\n"]}

package/src/datetime.d.ts

@@ -0,0 +1,284 @@
+/**
+ * Date/Time DTOs and Utilities for JSON serialization (inspired by Java Time / JSR-310)
+ *
+ * DTOs are simple interfaces - just data, no logic!
+ * Utilities provide conversion logic.
+ *
+ * Design Philosophy:
+ * - DTOs are plain objects with { value: string } - perfect for JSON.stringify/parse
+ * - Utilities contain ALL conversion logic (no business logic in DTOs)
+ * - Store as ISO-8601 strings (human-readable, unambiguous, sortable)
+ * - Always use UTC for timestamps (avoid timezone confusion)
+ *
+ * References:
+ * - Java Time API (JSR-310): https://docs.oracle.com/javase/8/docs/api/java/time/package-summary.html
+ * - ISO-8601: https://www.iso.org/iso-8601-date-and-time-format.html
+ * - REST API Best Practices: https://www.moesif.com/blog/technical/timestamp/manage-datetime-timestamp-timezones-in-api/
+ */
+/**
+ * InstantDto - Represents an absolute point in time (UTC).
+ *
+ * Equivalent to Java's java.time.Instant or JavaScript's Date.
+ *
+ * **Use cases:**
+ * - Timestamps (createdAt, updatedAt, lastModified)
+ * - Audit logs
+ * - Event timestamps
+ * - Any absolute point in time
+ *
+ * **JSON format:** ISO-8601 string with UTC timezone (Z suffix)
+ * - Example: "2024-12-03T14:30:00.000Z"
+ *
+ * @example
+ * ```typescript
+ * const now = InstantUtil.now();
+ * const json = JSON.stringify({ timestamp: now });
+ * // {"timestamp":{"value":"2024-12-03T14:30:00.000Z"}}
+ *
+ * const parsed = JSON.parse(json);
+ * const date = InstantUtil.toDate(parsed.timestamp);
+ * ```
+ */
+export interface InstantDto {
+    /**
+     * ISO-8601 string in UTC with Z suffix.
+     * Example: "2024-12-03T14:30:00.000Z"
+     */
+    value: string;
+}
+/**
+ * DateDto - Represents a date without time or timezone (e.g., 2024-12-03).
+ *
+ * Equivalent to Java's java.time.LocalDate.
+ *
+ * **Use cases:**
+ * - Birth dates
+ * - Holidays
+ * - Calendar dates
+ * - Any date where time/timezone is irrelevant
+ *
+ * **JSON format:** ISO-8601 date string (YYYY-MM-DD)
+ * - Example: "2024-12-03"
+ *
+ * @example
+ * ```typescript
+ * const christmas = DateUtil.of(2024, 12, 25);
+ * const json = JSON.stringify({ birthDate: christmas });
+ * // {"birthDate":{"value":"2024-12-25"}}
+ * ```
+ */
+export interface DateDto {
+    /**
+     * ISO-8601 date string (YYYY-MM-DD).
+     * Example: "2024-12-03"
+     */
+    value: string;
+}
+/**
+ * TimeDto - Represents a time without date or timezone (e.g., 14:30:00.123).
+ *
+ * Equivalent to Java's java.time.LocalTime.
+ *
+ * **Use cases:**
+ * - Opening/closing hours (e.g., "Store opens at 09:00")
+ * - Recurring event times (e.g., "Daily standup at 10:00")
+ * - Alarm times
+ * - Precise timing measurements
+ * - Any time where date/timezone is irrelevant
+ *
+ * **JSON format:** ISO-8601 time string with milliseconds (HH:mm:ss.SSS)
+ * - Example: "14:30:00.123"
+ *
+ * @example
+ * ```typescript
+ * const lunch = TimeUtil.of(12, 30, 0, 500);
+ * const json = JSON.stringify({ openingTime: lunch });
+ * // {"openingTime":{"value":"12:30:00.500"}}
+ * ```
+ */
+export interface TimeDto {
+    /**
+     * ISO-8601 time string with milliseconds (HH:mm:ss.SSS).
+     * Example: "14:30:00.123"
+     */
+    value: string;
+}
+/**
+ * DateTimeDto - Represents a date and time without timezone (e.g., 2024-12-03T14:30:00.123).
+ *
+ * Equivalent to Java's java.time.LocalDateTime.
+ *
+ * **⚠️ WARNING: Use with caution!**
+ * "LocalDateTime does not have a time zone, so if you use JSON to send date/time info,
+ * you might get in trouble if the client interprets the lack of time zone as default UTC
+ * (or its own time zone)."
+ *
+ * **Use cases:**
+ * - Appointment times (when timezone is implied by context)
+ * - Event dates/times (when all participants are in same timezone)
+ * - **Prefer InstantDto for most use cases to avoid timezone confusion!**
+ *
+ * **JSON format:** ISO-8601 datetime string without timezone (milliseconds optional)
+ * - Example: "2024-12-03T14:30:00" or "2024-12-03T14:30:00.123"
+ *
+ * @example
+ * ```typescript
+ * const meeting = DateTimeUtil.of(2024, 12, 3, 14, 30, 0, 500);
+ * const json = JSON.stringify({ appointmentTime: meeting });
+ * // {"appointmentTime":{"value":"2024-12-03T14:30:00.500"}}
+ * ```
+ */
+export interface DateTimeDto {
+    /**
+     * ISO-8601 datetime string without timezone (YYYY-MM-DDTHH:mm:ss or YYYY-MM-DDTHH:mm:ss.SSS).
+     * Example: "2024-12-03T14:30:00" or "2024-12-03T14:30:00.123"
+     */
+    value: string;
+}
+/**
+ * InstantUtil - Utility for converting InstantDto to/from various formats.
+ *
+ * All methods are static - this is a pure utility class with no state.
+ *
+ * **Why UTC?** "It's recommended to convert all dates to UTC before storing.
+ * Don't use local timezone. Otherwise, you'll be pulling your hair out when
+ * your database is deployed in high availability designs across multiple data
+ * centers across multiple timezones."
+ * - Source: https://www.moesif.com/blog/technical/timestamp/manage-datetime-timestamp-timezones-in-api/
+ */
+export declare class InstantUtil {
+    /**
+     * Create InstantDto representing the current moment (UTC).
+     */
+    static now(): InstantDto;
+    /**
+     * Create InstantDto from JavaScript Date object.
+     */
+    static fromDate(date: Date): InstantDto;
+    /**
+     * Create InstantDto from ISO-8601 string.
+     * @param iso - ISO-8601 string (e.g., "2024-12-03T14:30:00.000Z")
+     */
+    static fromString(iso: string): InstantDto;
+    /**
+     * Create InstantDto from epoch milliseconds.
+     * @param millis - Milliseconds since Unix epoch (January 1, 1970, 00:00:00 UTC)
+     */
+    static fromEpochMillis(millis: number): InstantDto;
+    /**
+     * Convert InstantDto to JavaScript Date object.
+     */
+    static toDate(instant: InstantDto): Date;
+    /**
+     * Get ISO-8601 string representation.
+     */
+    static toString(instant: InstantDto): string;
+    /**
+     * Get epoch milliseconds (Unix timestamp).
+     */
+    static toEpochMillis(instant: InstantDto): number;
+}
+/**
+ * DateUtil - Utility for converting DateDto to/from various formats.
+ *
+ * All methods are static - this is a pure utility class with no state.
+ *
+ * **Note:** DateDto represents a date in the abstract sense, not tied to any timezone.
+ * December 25th is Christmas regardless of what timezone you're in.
+ */
+export declare class DateUtil {
+    /**
+     * Create DateDto from year, month, day.
+     * @param year - Full year (e.g., 2024)
+     * @param month - Month (1-12, where 1 = January)
+     * @param day - Day of month (1-31)
+     */
+    static of(year: number, month: number, day: number): DateDto;
+    /**
+     * Create DateDto from JavaScript Date object.
+     * Uses the local timezone's date.
+     */
+    static fromDate(date: Date): DateDto;
+    /**
+     * Create DateDto from ISO-8601 date string.
+     * @param iso - ISO-8601 date string (e.g., "2024-12-03")
+     */
+    static fromString(iso: string): DateDto;
+    /**
+     * Convert DateDto to JavaScript Date object (at midnight local time).
+     */
+    static toDate(dateDto: DateDto): Date;
+    /**
+     * Get ISO-8601 date string.
+     */
+    static toString(dateDto: DateDto): string;
+}
+/**
+ * TimeUtil - Utility for converting TimeDto to/from various formats.
+ *
+ * All methods are static - this is a pure utility class with no state.
+ */
+export declare class TimeUtil {
+    /**
+     * Create TimeDto from hour, minute, second, and optional milliseconds.
+     * @param hour - Hour (0-23)
+     * @param minute - Minute (0-59)
+     * @param second - Second (0-59)
+     * @param millis - Milliseconds (0-999), optional
+     */
+    static of(hour: number, minute: number, second: number, millis?: number): TimeDto;
+    /**
+     * Create TimeDto from JavaScript Date object.
+     * Uses the local timezone's time.
+     * Includes milliseconds.
+     */
+    static fromDate(date: Date): TimeDto;
+    /**
+     * Create TimeDto from ISO-8601 time string.
+     * @param iso - ISO-8601 time string (e.g., "14:30:00" or "14:30:00.123")
+     */
+    static fromString(iso: string): TimeDto;
+    /**
+     * Get ISO-8601 time string.
+     */
+    static toString(timeDto: TimeDto): string;
+}
+/**
+ * DateTimeUtil - Utility for converting DateTimeDto to/from various formats.
+ *
+ * All methods are static - this is a pure utility class with no state.
+ *
+ * **⚠️ WARNING:** Prefer InstantDto for most use cases to avoid timezone confusion!
+ */
+export declare class DateTimeUtil {
+    /**
+     * Create DateTimeDto from components.
+     * @param year - Full year (e.g., 2024)
+     * @param month - Month (1-12, where 1 = January)
+     * @param day - Day of month (1-31)
+     * @param hour - Hour (0-23)
+     * @param minute - Minute (0-59)
+     * @param second - Second (0-59)
+     * @param millis - Milliseconds (0-999), optional
+     */
+    static of(year: number, month: number, day: number, hour: number, minute: number, second: number, millis?: number): DateTimeDto;
+    /**
+     * Create DateTimeDto from JavaScript Date object.
+     * Uses the local timezone's date/time.
+     * Includes milliseconds.
+     */
+    static fromDate(date: Date): DateTimeDto;
+    /**
+     * Create DateTimeDto from ISO-8601 datetime string.
+     * @param iso - ISO-8601 datetime string (e.g., "2024-12-03T14:30:00" or "2024-12-03T14:30:00.123")
+     */
+    static fromString(iso: string): DateTimeDto;
+    /**
+     * Convert DateTimeDto to JavaScript Date object (interprets as local timezone).
+     */
+    static toDate(dateTime: DateTimeDto): Date;
+    /**
+     * Get ISO-8601 datetime string.
+     */
+    static toString(dateTime: DateTimeDto): string;
+}

package/src/datetime.js

@@ -0,0 +1,270 @@
+"use strict";
+/**
+ * Date/Time DTOs and Utilities for JSON serialization (inspired by Java Time / JSR-310)
+ *
+ * DTOs are simple interfaces - just data, no logic!
+ * Utilities provide conversion logic.
+ *
+ * Design Philosophy:
+ * - DTOs are plain objects with { value: string } - perfect for JSON.stringify/parse
+ * - Utilities contain ALL conversion logic (no business logic in DTOs)
+ * - Store as ISO-8601 strings (human-readable, unambiguous, sortable)
+ * - Always use UTC for timestamps (avoid timezone confusion)
+ *
+ * References:
+ * - Java Time API (JSR-310): https://docs.oracle.com/javase/8/docs/api/java/time/package-summary.html
+ * - ISO-8601: https://www.iso.org/iso-8601-date-and-time-format.html
+ * - REST API Best Practices: https://www.moesif.com/blog/technical/timestamp/manage-datetime-timestamp-timezones-in-api/
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DateTimeUtil = exports.TimeUtil = exports.DateUtil = exports.InstantUtil = void 0;
+// ============================================================
+// Utilities - All conversion logic lives here
+// ============================================================
+/**
+ * InstantUtil - Utility for converting InstantDto to/from various formats.
+ *
+ * All methods are static - this is a pure utility class with no state.
+ *
+ * **Why UTC?** "It's recommended to convert all dates to UTC before storing.
+ * Don't use local timezone. Otherwise, you'll be pulling your hair out when
+ * your database is deployed in high availability designs across multiple data
+ * centers across multiple timezones."
+ * - Source: https://www.moesif.com/blog/technical/timestamp/manage-datetime-timestamp-timezones-in-api/
+ */
+class InstantUtil {
+    /**
+     * Create InstantDto representing the current moment (UTC).
+     */
+    static now() {
+        return { value: new Date().toISOString() };
+    }
+    /**
+     * Create InstantDto from JavaScript Date object.
+     */
+    static fromDate(date) {
+        return { value: date.toISOString() };
+    }
+    /**
+     * Create InstantDto from ISO-8601 string.
+     * @param iso - ISO-8601 string (e.g., "2024-12-03T14:30:00.000Z")
+     */
+    static fromString(iso) {
+        // Validate by parsing
+        const date = new Date(iso);
+        if (isNaN(date.getTime())) {
+            throw new Error(`Invalid ISO-8601 string: ${iso}`);
+        }
+        return { value: date.toISOString() };
+    }
+    /**
+     * Create InstantDto from epoch milliseconds.
+     * @param millis - Milliseconds since Unix epoch (January 1, 1970, 00:00:00 UTC)
+     */
+    static fromEpochMillis(millis) {
+        return { value: new Date(millis).toISOString() };
+    }
+    /**
+     * Convert InstantDto to JavaScript Date object.
+     */
+    static toDate(instant) {
+        return new Date(instant.value);
+    }
+    /**
+     * Get ISO-8601 string representation.
+     */
+    static toString(instant) {
+        return instant.value;
+    }
+    /**
+     * Get epoch milliseconds (Unix timestamp).
+     */
+    static toEpochMillis(instant) {
+        return new Date(instant.value).getTime();
+    }
+}
+exports.InstantUtil = InstantUtil;
+/**
+ * DateUtil - Utility for converting DateDto to/from various formats.
+ *
+ * All methods are static - this is a pure utility class with no state.
+ *
+ * **Note:** DateDto represents a date in the abstract sense, not tied to any timezone.
+ * December 25th is Christmas regardless of what timezone you're in.
+ */
+class DateUtil {
+    /**
+     * Create DateDto from year, month, day.
+     * @param year - Full year (e.g., 2024)
+     * @param month - Month (1-12, where 1 = January)
+     * @param day - Day of month (1-31)
+     */
+    static of(year, month, day) {
+        const monthStr = month.toString().padStart(2, '0');
+        const dayStr = day.toString().padStart(2, '0');
+        return { value: `${year}-${monthStr}-${dayStr}` };
+    }
+    /**
+     * Create DateDto from JavaScript Date object.
+     * Uses the local timezone's date.
+     */
+    static fromDate(date) {
+        const year = date.getFullYear();
+        const month = (date.getMonth() + 1).toString().padStart(2, '0');
+        const day = date.getDate().toString().padStart(2, '0');
+        return { value: `${year}-${month}-${day}` };
+    }
+    /**
+     * Create DateDto from ISO-8601 date string.
+     * @param iso - ISO-8601 date string (e.g., "2024-12-03")
+     */
+    static fromString(iso) {
+        // Validate format: YYYY-MM-DD
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(iso)) {
+            throw new Error(`Invalid date format: ${iso}. Expected YYYY-MM-DD`);
+        }
+        return { value: iso };
+    }
+    /**
+     * Convert DateDto to JavaScript Date object (at midnight local time).
+     */
+    static toDate(dateDto) {
+        return new Date(dateDto.value + 'T00:00:00');
+    }
+    /**
+     * Get ISO-8601 date string.
+     */
+    static toString(dateDto) {
+        return dateDto.value;
+    }
+}
+exports.DateUtil = DateUtil;
+/**
+ * TimeUtil - Utility for converting TimeDto to/from various formats.
+ *
+ * All methods are static - this is a pure utility class with no state.
+ */
+class TimeUtil {
+    /**
+     * Create TimeDto from hour, minute, second, and optional milliseconds.
+     * @param hour - Hour (0-23)
+     * @param minute - Minute (0-59)
+     * @param second - Second (0-59)
+     * @param millis - Milliseconds (0-999), optional
+     */
+    static of(hour, minute, second, millis) {
+        const hourStr = hour.toString().padStart(2, '0');
+        const minuteStr = minute.toString().padStart(2, '0');
+        const secondStr = second.toString().padStart(2, '0');
+        if (millis !== undefined) {
+            const millisStr = millis.toString().padStart(3, '0');
+            return { value: `${hourStr}:${minuteStr}:${secondStr}.${millisStr}` };
+        }
+        return { value: `${hourStr}:${minuteStr}:${secondStr}` };
+    }
+    /**
+     * Create TimeDto from JavaScript Date object.
+     * Uses the local timezone's time.
+     * Includes milliseconds.
+     */
+    static fromDate(date) {
+        const hour = date.getHours().toString().padStart(2, '0');
+        const minute = date.getMinutes().toString().padStart(2, '0');
+        const second = date.getSeconds().toString().padStart(2, '0');
+        const millis = date.getMilliseconds().toString().padStart(3, '0');
+        return { value: `${hour}:${minute}:${second}.${millis}` };
+    }
+    /**
+     * Create TimeDto from ISO-8601 time string.
+     * @param iso - ISO-8601 time string (e.g., "14:30:00" or "14:30:00.123")
+     */
+    static fromString(iso) {
+        // Validate format: HH:mm:ss or HH:mm:ss.SSS
+        if (!/^\d{2}:\d{2}:\d{2}(\.\d{3})?$/.test(iso)) {
+            throw new Error(`Invalid time format: ${iso}. Expected HH:mm:ss or HH:mm:ss.SSS`);
+        }
+        return { value: iso };
+    }
+    /**
+     * Get ISO-8601 time string.
+     */
+    static toString(timeDto) {
+        return timeDto.value;
+    }
+}
+exports.TimeUtil = TimeUtil;
+/**
+ * DateTimeUtil - Utility for converting DateTimeDto to/from various formats.
+ *
+ * All methods are static - this is a pure utility class with no state.
+ *
+ * **⚠️ WARNING:** Prefer InstantDto for most use cases to avoid timezone confusion!
+ */
+class DateTimeUtil {
+    /**
+     * Create DateTimeDto from components.
+     * @param year - Full year (e.g., 2024)
+     * @param month - Month (1-12, where 1 = January)
+     * @param day - Day of month (1-31)
+     * @param hour - Hour (0-23)
+     * @param minute - Minute (0-59)
+     * @param second - Second (0-59)
+     * @param millis - Milliseconds (0-999), optional
+     */
+    static of(year, month, day, hour, minute, second, millis) {
+        const monthStr = month.toString().padStart(2, '0');
+        const dayStr = day.toString().padStart(2, '0');
+        const hourStr = hour.toString().padStart(2, '0');
+        const minuteStr = minute.toString().padStart(2, '0');
+        const secondStr = second.toString().padStart(2, '0');
+        if (millis !== undefined) {
+            const millisStr = millis.toString().padStart(3, '0');
+            return {
+                value: `${year}-${monthStr}-${dayStr}T${hourStr}:${minuteStr}:${secondStr}.${millisStr}`,
+            };
+        }
+        return {
+            value: `${year}-${monthStr}-${dayStr}T${hourStr}:${minuteStr}:${secondStr}`,
+        };
+    }
+    /**
+     * Create DateTimeDto from JavaScript Date object.
+     * Uses the local timezone's date/time.
+     * Includes milliseconds.
+     */
+    static fromDate(date) {
+        const year = date.getFullYear();
+        const month = (date.getMonth() + 1).toString().padStart(2, '0');
+        const day = date.getDate().toString().padStart(2, '0');
+        const hour = date.getHours().toString().padStart(2, '0');
+        const minute = date.getMinutes().toString().padStart(2, '0');
+        const second = date.getSeconds().toString().padStart(2, '0');
+        const millis = date.getMilliseconds().toString().padStart(3, '0');
+        return { value: `${year}-${month}-${day}T${hour}:${minute}:${second}.${millis}` };
+    }
+    /**
+     * Create DateTimeDto from ISO-8601 datetime string.
+     * @param iso - ISO-8601 datetime string (e.g., "2024-12-03T14:30:00" or "2024-12-03T14:30:00.123")
+     */
+    static fromString(iso) {
+        // Validate format: YYYY-MM-DDTHH:mm:ss or YYYY-MM-DDTHH:mm:ss.SSS
+        if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?$/.test(iso)) {
+            throw new Error(`Invalid datetime format: ${iso}. Expected YYYY-MM-DDTHH:mm:ss or YYYY-MM-DDTHH:mm:ss.SSS`);
+        }
+        return { value: iso };
+    }
+    /**
+     * Convert DateTimeDto to JavaScript Date object (interprets as local timezone).
+     */
+    static toDate(dateTime) {
+        return new Date(dateTime.value);
+    }
+    /**
+     * Get ISO-8601 datetime string.
+     */
+    static toString(dateTime) {
+        return dateTime.value;
+    }
+}
+exports.DateTimeUtil = DateTimeUtil;
+//# sourceMappingURL=datetime.js.map

package/src/datetime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"datetime.js","sourceRoot":"","sources":["../../../../../packages/http/http-api/src/datetime.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Date/Time DTOs and Utilities for JSON serialization (inspired by Java Time / JSR-310)\n *\n * DTOs are simple interfaces - just data, no logic!\n * Utilities provide conversion logic.\n *\n * Design Philosophy:\n * - DTOs are plain objects with { value: string } - perfect for JSON.stringify/parse\n * - Utilities contain ALL conversion logic (no business logic in DTOs)\n * - Store as ISO-8601 strings (human-readable, unambiguous, sortable)\n * - Always use UTC for timestamps (avoid timezone confusion)\n *\n * References:\n * - Java Time API (JSR-310): https://docs.oracle.com/javase/8/docs/api/java/time/package-summary.html\n * - ISO-8601: https://www.iso.org/iso-8601-date-and-time-format.html\n * - REST API Best Practices: https://www.moesif.com/blog/technical/timestamp/manage-datetime-timestamp-timezones-in-api/\n */\n\n// ============================================================\n// DTOs (Data Transfer Objects) - Pure data, no logic\n// ============================================================\n\n/**\n * InstantDto - Represents an absolute point in time (UTC).\n *\n * Equivalent to Java's java.time.Instant or JavaScript's Date.\n *\n * **Use cases:**\n * - Timestamps (createdAt, updatedAt, lastModified)\n * - Audit logs\n * - Event timestamps\n * - Any absolute point in time\n *\n * **JSON format:** ISO-8601 string with UTC timezone (Z suffix)\n * - Example: \"2024-12-03T14:30:00.000Z\"\n *\n * @example\n * ```typescript\n * const now = InstantUtil.now();\n * const json = JSON.stringify({ timestamp: now });\n * // {\"timestamp\":{\"value\":\"2024-12-03T14:30:00.000Z\"}}\n *\n * const parsed = JSON.parse(json);\n * const date = InstantUtil.toDate(parsed.timestamp);\n * ```\n */\nexport interface InstantDto {\n    /**\n     * ISO-8601 string in UTC with Z suffix.\n     * Example: \"2024-12-03T14:30:00.000Z\"\n     */\n    value: string;\n}\n\n/**\n * DateDto - Represents a date without time or timezone (e.g., 2024-12-03).\n *\n * Equivalent to Java's java.time.LocalDate.\n *\n * **Use cases:**\n * - Birth dates\n * - Holidays\n * - Calendar dates\n * - Any date where time/timezone is irrelevant\n *\n * **JSON format:** ISO-8601 date string (YYYY-MM-DD)\n * - Example: \"2024-12-03\"\n *\n * @example\n * ```typescript\n * const christmas = DateUtil.of(2024, 12, 25);\n * const json = JSON.stringify({ birthDate: christmas });\n * // {\"birthDate\":{\"value\":\"2024-12-25\"}}\n * ```\n */\nexport interface DateDto {\n    /**\n     * ISO-8601 date string (YYYY-MM-DD).\n     * Example: \"2024-12-03\"\n     */\n    value: string;\n}\n\n/**\n * TimeDto - Represents a time without date or timezone (e.g., 14:30:00.123).\n *\n * Equivalent to Java's java.time.LocalTime.\n *\n * **Use cases:**\n * - Opening/closing hours (e.g., \"Store opens at 09:00\")\n * - Recurring event times (e.g., \"Daily standup at 10:00\")\n * - Alarm times\n * - Precise timing measurements\n * - Any time where date/timezone is irrelevant\n *\n * **JSON format:** ISO-8601 time string with milliseconds (HH:mm:ss.SSS)\n * - Example: \"14:30:00.123\"\n *\n * @example\n * ```typescript\n * const lunch = TimeUtil.of(12, 30, 0, 500);\n * const json = JSON.stringify({ openingTime: lunch });\n * // {\"openingTime\":{\"value\":\"12:30:00.500\"}}\n * ```\n */\nexport interface TimeDto {\n    /**\n     * ISO-8601 time string with milliseconds (HH:mm:ss.SSS).\n     * Example: \"14:30:00.123\"\n     */\n    value: string;\n}\n\n/**\n * DateTimeDto - Represents a date and time without timezone (e.g., 2024-12-03T14:30:00.123).\n *\n * Equivalent to Java's java.time.LocalDateTime.\n *\n * **⚠️ WARNING: Use with caution!**\n * \"LocalDateTime does not have a time zone, so if you use JSON to send date/time info,\n * you might get in trouble if the client interprets the lack of time zone as default UTC\n * (or its own time zone).\"\n *\n * **Use cases:**\n * - Appointment times (when timezone is implied by context)\n * - Event dates/times (when all participants are in same timezone)\n * - **Prefer InstantDto for most use cases to avoid timezone confusion!**\n *\n * **JSON format:** ISO-8601 datetime string without timezone (milliseconds optional)\n * - Example: \"2024-12-03T14:30:00\" or \"2024-12-03T14:30:00.123\"\n *\n * @example\n * ```typescript\n * const meeting = DateTimeUtil.of(2024, 12, 3, 14, 30, 0, 500);\n * const json = JSON.stringify({ appointmentTime: meeting });\n * // {\"appointmentTime\":{\"value\":\"2024-12-03T14:30:00.500\"}}\n * ```\n */\nexport interface DateTimeDto {\n    /**\n     * ISO-8601 datetime string without timezone (YYYY-MM-DDTHH:mm:ss or YYYY-MM-DDTHH:mm:ss.SSS).\n     * Example: \"2024-12-03T14:30:00\" or \"2024-12-03T14:30:00.123\"\n     */\n    value: string;\n}\n\n// ============================================================\n// Utilities - All conversion logic lives here\n// ============================================================\n\n/**\n * InstantUtil - Utility for converting InstantDto to/from various formats.\n *\n * All methods are static - this is a pure utility class with no state.\n *\n * **Why UTC?** \"It's recommended to convert all dates to UTC before storing.\n * Don't use local timezone. Otherwise, you'll be pulling your hair out when\n * your database is deployed in high availability designs across multiple data\n * centers across multiple timezones.\"\n * - Source: https://www.moesif.com/blog/technical/timestamp/manage-datetime-timestamp-timezones-in-api/\n */\nexport class InstantUtil {\n    /**\n     * Create InstantDto representing the current moment (UTC).\n     */\n    static now(): InstantDto {\n        return { value: new Date().toISOString() };\n    }\n\n    /**\n     * Create InstantDto from JavaScript Date object.\n     */\n    static fromDate(date: Date): InstantDto {\n        return { value: date.toISOString() };\n    }\n\n    /**\n     * Create InstantDto from ISO-8601 string.\n     * @param iso - ISO-8601 string (e.g., \"2024-12-03T14:30:00.000Z\")\n     */\n    static fromString(iso: string): InstantDto {\n        // Validate by parsing\n        const date = new Date(iso);\n        if (isNaN(date.getTime())) {\n            throw new Error(`Invalid ISO-8601 string: ${iso}`);\n        }\n        return { value: date.toISOString() };\n    }\n\n    /**\n     * Create InstantDto from epoch milliseconds.\n     * @param millis - Milliseconds since Unix epoch (January 1, 1970, 00:00:00 UTC)\n     */\n    static fromEpochMillis(millis: number): InstantDto {\n        return { value: new Date(millis).toISOString() };\n    }\n\n    /**\n     * Convert InstantDto to JavaScript Date object.\n     */\n    static toDate(instant: InstantDto): Date {\n        return new Date(instant.value);\n    }\n\n    /**\n     * Get ISO-8601 string representation.\n     */\n    static toString(instant: InstantDto): string {\n        return instant.value;\n    }\n\n    /**\n     * Get epoch milliseconds (Unix timestamp).\n     */\n    static toEpochMillis(instant: InstantDto): number {\n        return new Date(instant.value).getTime();\n    }\n}\n\n/**\n * DateUtil - Utility for converting DateDto to/from various formats.\n *\n * All methods are static - this is a pure utility class with no state.\n *\n * **Note:** DateDto represents a date in the abstract sense, not tied to any timezone.\n * December 25th is Christmas regardless of what timezone you're in.\n */\nexport class DateUtil {\n    /**\n     * Create DateDto from year, month, day.\n     * @param year - Full year (e.g., 2024)\n     * @param month - Month (1-12, where 1 = January)\n     * @param day - Day of month (1-31)\n     */\n    static of(year: number, month: number, day: number): DateDto {\n        const monthStr = month.toString().padStart(2, '0');\n        const dayStr = day.toString().padStart(2, '0');\n        return { value: `${year}-${monthStr}-${dayStr}` };\n    }\n\n    /**\n     * Create DateDto from JavaScript Date object.\n     * Uses the local timezone's date.\n     */\n    static fromDate(date: Date): DateDto {\n        const year = date.getFullYear();\n        const month = (date.getMonth() + 1).toString().padStart(2, '0');\n        const day = date.getDate().toString().padStart(2, '0');\n        return { value: `${year}-${month}-${day}` };\n    }\n\n    /**\n     * Create DateDto from ISO-8601 date string.\n     * @param iso - ISO-8601 date string (e.g., \"2024-12-03\")\n     */\n    static fromString(iso: string): DateDto {\n        // Validate format: YYYY-MM-DD\n        if (!/^\\d{4}-\\d{2}-\\d{2}$/.test(iso)) {\n            throw new Error(`Invalid date format: ${iso}. Expected YYYY-MM-DD`);\n        }\n        return { value: iso };\n    }\n\n    /**\n     * Convert DateDto to JavaScript Date object (at midnight local time).\n     */\n    static toDate(dateDto: DateDto): Date {\n        return new Date(dateDto.value + 'T00:00:00');\n    }\n\n    /**\n     * Get ISO-8601 date string.\n     */\n    static toString(dateDto: DateDto): string {\n        return dateDto.value;\n    }\n}\n\n/**\n * TimeUtil - Utility for converting TimeDto to/from various formats.\n *\n * All methods are static - this is a pure utility class with no state.\n */\nexport class TimeUtil {\n    /**\n     * Create TimeDto from hour, minute, second, and optional milliseconds.\n     * @param hour - Hour (0-23)\n     * @param minute - Minute (0-59)\n     * @param second - Second (0-59)\n     * @param millis - Milliseconds (0-999), optional\n     */\n    static of(hour: number, minute: number, second: number, millis?: number): TimeDto {\n        const hourStr = hour.toString().padStart(2, '0');\n        const minuteStr = minute.toString().padStart(2, '0');\n        const secondStr = second.toString().padStart(2, '0');\n\n        if (millis !== undefined) {\n            const millisStr = millis.toString().padStart(3, '0');\n            return { value: `${hourStr}:${minuteStr}:${secondStr}.${millisStr}` };\n        }\n\n        return { value: `${hourStr}:${minuteStr}:${secondStr}` };\n    }\n\n    /**\n     * Create TimeDto from JavaScript Date object.\n     * Uses the local timezone's time.\n     * Includes milliseconds.\n     */\n    static fromDate(date: Date): TimeDto {\n        const hour = date.getHours().toString().padStart(2, '0');\n        const minute = date.getMinutes().toString().padStart(2, '0');\n        const second = date.getSeconds().toString().padStart(2, '0');\n        const millis = date.getMilliseconds().toString().padStart(3, '0');\n        return { value: `${hour}:${minute}:${second}.${millis}` };\n    }\n\n    /**\n     * Create TimeDto from ISO-8601 time string.\n     * @param iso - ISO-8601 time string (e.g., \"14:30:00\" or \"14:30:00.123\")\n     */\n    static fromString(iso: string): TimeDto {\n        // Validate format: HH:mm:ss or HH:mm:ss.SSS\n        if (!/^\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?$/.test(iso)) {\n            throw new Error(`Invalid time format: ${iso}. Expected HH:mm:ss or HH:mm:ss.SSS`);\n        }\n        return { value: iso };\n    }\n\n    /**\n     * Get ISO-8601 time string.\n     */\n    static toString(timeDto: TimeDto): string {\n        return timeDto.value;\n    }\n}\n\n/**\n * DateTimeUtil - Utility for converting DateTimeDto to/from various formats.\n *\n * All methods are static - this is a pure utility class with no state.\n *\n * **⚠️ WARNING:** Prefer InstantDto for most use cases to avoid timezone confusion!\n */\nexport class DateTimeUtil {\n    /**\n     * Create DateTimeDto from components.\n     * @param year - Full year (e.g., 2024)\n     * @param month - Month (1-12, where 1 = January)\n     * @param day - Day of month (1-31)\n     * @param hour - Hour (0-23)\n     * @param minute - Minute (0-59)\n     * @param second - Second (0-59)\n     * @param millis - Milliseconds (0-999), optional\n     */\n    static of(\n        year: number,\n        month: number,\n        day: number,\n        hour: number,\n        minute: number,\n        second: number,\n        millis?: number,\n    ): DateTimeDto {\n        const monthStr = month.toString().padStart(2, '0');\n        const dayStr = day.toString().padStart(2, '0');\n        const hourStr = hour.toString().padStart(2, '0');\n        const minuteStr = minute.toString().padStart(2, '0');\n        const secondStr = second.toString().padStart(2, '0');\n\n        if (millis !== undefined) {\n            const millisStr = millis.toString().padStart(3, '0');\n            return {\n                value: `${year}-${monthStr}-${dayStr}T${hourStr}:${minuteStr}:${secondStr}.${millisStr}`,\n            };\n        }\n\n        return {\n            value: `${year}-${monthStr}-${dayStr}T${hourStr}:${minuteStr}:${secondStr}`,\n        };\n    }\n\n    /**\n     * Create DateTimeDto from JavaScript Date object.\n     * Uses the local timezone's date/time.\n     * Includes milliseconds.\n     */\n    static fromDate(date: Date): DateTimeDto {\n        const year = date.getFullYear();\n        const month = (date.getMonth() + 1).toString().padStart(2, '0');\n        const day = date.getDate().toString().padStart(2, '0');\n        const hour = date.getHours().toString().padStart(2, '0');\n        const minute = date.getMinutes().toString().padStart(2, '0');\n        const second = date.getSeconds().toString().padStart(2, '0');\n        const millis = date.getMilliseconds().toString().padStart(3, '0');\n        return { value: `${year}-${month}-${day}T${hour}:${minute}:${second}.${millis}` };\n    }\n\n    /**\n     * Create DateTimeDto from ISO-8601 datetime string.\n     * @param iso - ISO-8601 datetime string (e.g., \"2024-12-03T14:30:00\" or \"2024-12-03T14:30:00.123\")\n     */\n    static fromString(iso: string): DateTimeDto {\n        // Validate format: YYYY-MM-DDTHH:mm:ss or YYYY-MM-DDTHH:mm:ss.SSS\n        if (!/^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?$/.test(iso)) {\n            throw new Error(\n                `Invalid datetime format: ${iso}. Expected YYYY-MM-DDTHH:mm:ss or YYYY-MM-DDTHH:mm:ss.SSS`,\n            );\n        }\n        return { value: iso };\n    }\n\n    /**\n     * Convert DateTimeDto to JavaScript Date object (interprets as local timezone).\n     */\n    static toDate(dateTime: DateTimeDto): Date {\n        return new Date(dateTime.value);\n    }\n\n    /**\n     * Get ISO-8601 datetime string.\n     */\n    static toString(dateTime: DateTimeDto): string {\n        return dateTime.value;\n    }\n}\n"]}

package/src/index.d.ts

@@ -19,3 +19,9 @@
 export { ApiInterface, Get, Post, Put, Delete, Patch, Path, getRoutes, isApiInterface, RouteMetadata, METADATA_KEYS, } from './decorators';
 export { ValidateImplementation } from './validators';
 export { ProtocolError, HttpError, HttpNotFoundError, EndpointNotFoundError, HttpBadRequestError, HttpUnauthorizedError, HttpForbiddenError, HttpTimeoutError, HttpBadGatewayError, HttpGatewayTimeoutError, HttpInternalServerError, HttpVendorError, HttpUserError, ENTITY_NOT_FOUND, WRONG_LOGIN_TYPE, WRONG_LOGIN, NOT_APPROVED, EMAIL_NOT_CONFIRMED, WRONG_DOMAIN, WRONG_COMPANY, NO_REG_CODE, } from './errors';
+export { InstantDto, DateDto, TimeDto, DateTimeDto, InstantUtil, DateUtil, TimeUtil, DateTimeUtil, } from './datetime';
+export { PlatformHeader } from './PlatformHeader';
+export { PlatformHeadersExtension } from './PlatformHeadersExtension';
+export { HeaderMethods, ContextReader } from './HeaderMethods';
+export { HEADER_TYPES } from './HeaderTypes';
+export { LogApiCall } from './LogApiCall';

package/src/index.js

@@ -18,7 +18,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NO_REG_CODE = exports.WRONG_COMPANY = exports.WRONG_DOMAIN = exports.EMAIL_NOT_CONFIRMED = exports.NOT_APPROVED = exports.WRONG_LOGIN = exports.WRONG_LOGIN_TYPE = exports.ENTITY_NOT_FOUND = exports.HttpUserError = exports.HttpVendorError = exports.HttpInternalServerError = exports.HttpGatewayTimeoutError = exports.HttpBadGatewayError = exports.HttpTimeoutError = exports.HttpForbiddenError = exports.HttpUnauthorizedError = exports.HttpBadRequestError = exports.EndpointNotFoundError = exports.HttpNotFoundError = exports.HttpError = exports.ProtocolError = exports.METADATA_KEYS = exports.RouteMetadata = exports.isApiInterface = exports.getRoutes = exports.Path = exports.Patch = exports.Delete = exports.Put = exports.Post = exports.Get = exports.ApiInterface = void 0;
+exports.LogApiCall = exports.HEADER_TYPES = exports.HeaderMethods = exports.PlatformHeadersExtension = exports.PlatformHeader = exports.DateTimeUtil = exports.TimeUtil = exports.DateUtil = exports.InstantUtil = exports.NO_REG_CODE = exports.WRONG_COMPANY = exports.WRONG_DOMAIN = exports.EMAIL_NOT_CONFIRMED = exports.NOT_APPROVED = exports.WRONG_LOGIN = exports.WRONG_LOGIN_TYPE = exports.ENTITY_NOT_FOUND = exports.HttpUserError = exports.HttpVendorError = exports.HttpInternalServerError = exports.HttpGatewayTimeoutError = exports.HttpBadGatewayError = exports.HttpTimeoutError = exports.HttpForbiddenError = exports.HttpUnauthorizedError = exports.HttpBadRequestError = exports.EndpointNotFoundError = exports.HttpNotFoundError = exports.HttpError = exports.ProtocolError = exports.METADATA_KEYS = exports.RouteMetadata = exports.isApiInterface = exports.getRoutes = exports.Path = exports.Patch = exports.Delete = exports.Put = exports.Post = exports.Get = exports.ApiInterface = void 0;
 // API definition decorators
 var decorators_1 = require("./decorators");
 Object.defineProperty(exports, "ApiInterface", { enumerable: true, get: function () { return decorators_1.ApiInterface; } });
@@ -56,4 +56,22 @@ Object.defineProperty(exports, "EMAIL_NOT_CONFIRMED", { enumerable: true, get: f
 Object.defineProperty(exports, "WRONG_DOMAIN", { enumerable: true, get: function () { return errors_1.WRONG_DOMAIN; } });
 Object.defineProperty(exports, "WRONG_COMPANY", { enumerable: true, get: function () { return errors_1.WRONG_COMPANY; } });
 Object.defineProperty(exports, "NO_REG_CODE", { enumerable: true, get: function () { return errors_1.NO_REG_CODE; } });
+// Date/Time DTOs and Utilities (inspired by Java Time / JSR-310)
+var datetime_1 = require("./datetime");
+Object.defineProperty(exports, "InstantUtil", { enumerable: true, get: function () { return datetime_1.InstantUtil; } });
+Object.defineProperty(exports, "DateUtil", { enumerable: true, get: function () { return datetime_1.DateUtil; } });
+Object.defineProperty(exports, "TimeUtil", { enumerable: true, get: function () { return datetime_1.TimeUtil; } });
+Object.defineProperty(exports, "DateTimeUtil", { enumerable: true, get: function () { return datetime_1.DateTimeUtil; } });
+// Platform Headers
+var PlatformHeader_1 = require("./PlatformHeader");
+Object.defineProperty(exports, "PlatformHeader", { enumerable: true, get: function () { return PlatformHeader_1.PlatformHeader; } });
+var PlatformHeadersExtension_1 = require("./PlatformHeadersExtension");
+Object.defineProperty(exports, "PlatformHeadersExtension", { enumerable: true, get: function () { return PlatformHeadersExtension_1.PlatformHeadersExtension; } });
+var HeaderMethods_1 = require("./HeaderMethods");
+Object.defineProperty(exports, "HeaderMethods", { enumerable: true, get: function () { return HeaderMethods_1.HeaderMethods; } });
+var HeaderTypes_1 = require("./HeaderTypes");
+Object.defineProperty(exports, "HEADER_TYPES", { enumerable: true, get: function () { return HeaderTypes_1.HEADER_TYPES; } });
+// Logging
+var LogApiCall_1 = require("./LogApiCall");
+Object.defineProperty(exports, "LogApiCall", { enumerable: true, get: function () { return LogApiCall_1.LogApiCall; } });
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/http/http-api/src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAEH,4BAA4B;AAC5B,2CAYsB;AAXlB,0GAAA,YAAY,OAAA;AACZ,iGAAA,GAAG,OAAA;AACH,kGAAA,IAAI,OAAA;AACJ,iGAAA,GAAG,OAAA;AACH,oGAAA,MAAM,OAAA;AACN,mGAAA,KAAK,OAAA;AACL,kGAAA,IAAI,OAAA;AACJ,uGAAA,SAAS,OAAA;AACT,4GAAA,cAAc,OAAA;AACd,2GAAA,aAAa,OAAA;AACb,2GAAA,aAAa,OAAA;AAMjB,cAAc;AACd,mCAuBkB;AAtBd,uGAAA,aAAa,OAAA;AACb,mGAAA,SAAS,OAAA;AACT,2GAAA,iBAAiB,OAAA;AACjB,+GAAA,qBAAqB,OAAA;AACrB,6GAAA,mBAAmB,OAAA;AACnB,+GAAA,qBAAqB,OAAA;AACrB,4GAAA,kBAAkB,OAAA;AAClB,0GAAA,gBAAgB,OAAA;AAChB,6GAAA,mBAAmB,OAAA;AACnB,iHAAA,uBAAuB,OAAA;AACvB,iHAAA,uBAAuB,OAAA;AACvB,yGAAA,eAAe,OAAA;AACf,uGAAA,aAAa,OAAA;AACb,0BAA0B;AAC1B,0GAAA,gBAAgB,OAAA;AAChB,0GAAA,gBAAgB,OAAA;AAChB,qGAAA,WAAW,OAAA;AACX,sGAAA,YAAY,OAAA;AACZ,6GAAA,mBAAmB,OAAA;AACnB,sGAAA,YAAY,OAAA;AACZ,uGAAA,aAAa,OAAA;AACb,qGAAA,WAAW,OAAA","sourcesContent":["/**\n * @webpieces/http-api\n *\n * Core HTTP API definition package.\n * Contains decorators and utilities for defining HTTP APIs.\n *\n * This package is used by:\n * - @webpieces/http-routing (server-side): Routes HTTP requests to controllers\n * - @webpieces/http-client (client-side): Generates HTTP clients from API definitions\n *\n * Architecture:\n * ```\n * http-api (defines the contract)\n *    ↑\n *    ├── http-routing (server: contract → handlers)\n *    └── http-client (client: contract → HTTP requests)\n * ```\n */\n\n// API definition decorators\nexport {\n    ApiInterface,\n    Get,\n    Post,\n    Put,\n    Delete,\n    Patch,\n    Path,\n    getRoutes,\n    isApiInterface,\n    RouteMetadata,\n    METADATA_KEYS,\n} from './decorators';\n\n// Type validators\nexport { ValidateImplementation } from './validators';\n\n// HTTP errors\nexport {\n    ProtocolError,\n    HttpError,\n    HttpNotFoundError,\n    EndpointNotFoundError,\n    HttpBadRequestError,\n    HttpUnauthorizedError,\n    HttpForbiddenError,\n    HttpTimeoutError,\n    HttpBadGatewayError,\n    HttpGatewayTimeoutError,\n    HttpInternalServerError,\n    HttpVendorError,\n    HttpUserError,\n    // Error subtype constants\n    ENTITY_NOT_FOUND,\n    WRONG_LOGIN_TYPE,\n    WRONG_LOGIN,\n    NOT_APPROVED,\n    EMAIL_NOT_CONFIRMED,\n    WRONG_DOMAIN,\n    WRONG_COMPANY,\n    NO_REG_CODE,\n} from './errors';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/http/http-api/src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAEH,4BAA4B;AAC5B,2CAYsB;AAXlB,0GAAA,YAAY,OAAA;AACZ,iGAAA,GAAG,OAAA;AACH,kGAAA,IAAI,OAAA;AACJ,iGAAA,GAAG,OAAA;AACH,oGAAA,MAAM,OAAA;AACN,mGAAA,KAAK,OAAA;AACL,kGAAA,IAAI,OAAA;AACJ,uGAAA,SAAS,OAAA;AACT,4GAAA,cAAc,OAAA;AACd,2GAAA,aAAa,OAAA;AACb,2GAAA,aAAa,OAAA;AAMjB,cAAc;AACd,mCAuBkB;AAtBd,uGAAA,aAAa,OAAA;AACb,mGAAA,SAAS,OAAA;AACT,2GAAA,iBAAiB,OAAA;AACjB,+GAAA,qBAAqB,OAAA;AACrB,6GAAA,mBAAmB,OAAA;AACnB,+GAAA,qBAAqB,OAAA;AACrB,4GAAA,kBAAkB,OAAA;AAClB,0GAAA,gBAAgB,OAAA;AAChB,6GAAA,mBAAmB,OAAA;AACnB,iHAAA,uBAAuB,OAAA;AACvB,iHAAA,uBAAuB,OAAA;AACvB,yGAAA,eAAe,OAAA;AACf,uGAAA,aAAa,OAAA;AACb,0BAA0B;AAC1B,0GAAA,gBAAgB,OAAA;AAChB,0GAAA,gBAAgB,OAAA;AAChB,qGAAA,WAAW,OAAA;AACX,sGAAA,YAAY,OAAA;AACZ,6GAAA,mBAAmB,OAAA;AACnB,sGAAA,YAAY,OAAA;AACZ,uGAAA,aAAa,OAAA;AACb,qGAAA,WAAW,OAAA;AAGf,iEAAiE;AACjE,uCASoB;AAJhB,uGAAA,WAAW,OAAA;AACX,oGAAA,QAAQ,OAAA;AACR,oGAAA,QAAQ,OAAA;AACR,wGAAA,YAAY,OAAA;AAGhB,mBAAmB;AACnB,mDAAkD;AAAzC,gHAAA,cAAc,OAAA;AACvB,uEAAsE;AAA7D,oIAAA,wBAAwB,OAAA;AACjC,iDAA+D;AAAtD,8GAAA,aAAa,OAAA;AACtB,6CAA6C;AAApC,2GAAA,YAAY,OAAA;AAErB,UAAU;AACV,2CAA0C;AAAjC,wGAAA,UAAU,OAAA","sourcesContent":["/**\n * @webpieces/http-api\n *\n * Core HTTP API definition package.\n * Contains decorators and utilities for defining HTTP APIs.\n *\n * This package is used by:\n * - @webpieces/http-routing (server-side): Routes HTTP requests to controllers\n * - @webpieces/http-client (client-side): Generates HTTP clients from API definitions\n *\n * Architecture:\n * ```\n * http-api (defines the contract)\n *    ↑\n *    ├── http-routing (server: contract → handlers)\n *    └── http-client (client: contract → HTTP requests)\n * ```\n */\n\n// API definition decorators\nexport {\n    ApiInterface,\n    Get,\n    Post,\n    Put,\n    Delete,\n    Patch,\n    Path,\n    getRoutes,\n    isApiInterface,\n    RouteMetadata,\n    METADATA_KEYS,\n} from './decorators';\n\n// Type validators\nexport { ValidateImplementation } from './validators';\n\n// HTTP errors\nexport {\n    ProtocolError,\n    HttpError,\n    HttpNotFoundError,\n    EndpointNotFoundError,\n    HttpBadRequestError,\n    HttpUnauthorizedError,\n    HttpForbiddenError,\n    HttpTimeoutError,\n    HttpBadGatewayError,\n    HttpGatewayTimeoutError,\n    HttpInternalServerError,\n    HttpVendorError,\n    HttpUserError,\n    // Error subtype constants\n    ENTITY_NOT_FOUND,\n    WRONG_LOGIN_TYPE,\n    WRONG_LOGIN,\n    NOT_APPROVED,\n    EMAIL_NOT_CONFIRMED,\n    WRONG_DOMAIN,\n    WRONG_COMPANY,\n    NO_REG_CODE,\n} from './errors';\n\n// Date/Time DTOs and Utilities (inspired by Java Time / JSR-310)\nexport {\n    InstantDto,\n    DateDto,\n    TimeDto,\n    DateTimeDto,\n    InstantUtil,\n    DateUtil,\n    TimeUtil,\n    DateTimeUtil,\n} from './datetime';\n\n// Platform Headers\nexport { PlatformHeader } from './PlatformHeader';\nexport { PlatformHeadersExtension } from './PlatformHeadersExtension';\nexport { HeaderMethods, ContextReader } from './HeaderMethods';\nexport { HEADER_TYPES } from './HeaderTypes';\n\n// Logging\nexport { LogApiCall } from './LogApiCall';\n"]}