@jmlq/auth 0.0.1-alpha.1

package/dist/tests/infrastructure/services/jwt-token-service.spec.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const jwt_token_service_1 = require("../../../src/infrastructure/services/jwt-token.service");
+describe("JwtTokenService", () => {
+    let config;
+    let jwtGenerator;
+    let jwtVerifier;
+    let jwtValidator;
+    let service;
+    beforeEach(() => {
+        // ⚠️ Rellena/ajusta según tu definición real de IAuthConfig["info"]
+        config = {
+            accessTokenSecret: "access-secret",
+            refreshTokenSecret: "refresh-secret",
+            accessTokenExpirationMs: 15 * 60 * 1000,
+            refreshTokenExpirationMs: 7 * 24 * 60 * 60 * 1000,
+            issuer: "test-issuer",
+            audience: "test-audience",
+            appName: "test-app",
+        };
+        jwtGenerator = {
+            generateAccessToken: jest.fn(),
+            generateRefreshToken: jest.fn(),
+        };
+        jwtVerifier = {
+            verifyAccessToken: jest.fn(),
+            verifyRefreshToken: jest.fn(),
+            getTokenExpiration: jest.fn(),
+        };
+        jwtValidator = {
+            validateTokenInput: jest.fn(),
+        };
+        service = new jwt_token_service_1.JwtTokenService(config, jwtGenerator, jwtVerifier, jwtValidator);
+    });
+    describe("generateAccessToken", () => {
+        it("debería delegar en JwtTokenGenerator.generateAccessToken y retornar el token", async () => {
+            const props = {
+                userId: "user-123",
+            };
+            const expectedToken = "access.token.value";
+            jwtGenerator.generateAccessToken.mockResolvedValue(expectedToken);
+            const result = await service.generateAccessToken(props);
+            expect(jwtGenerator.generateAccessToken).toHaveBeenCalledTimes(1);
+            expect(jwtGenerator.generateAccessToken).toHaveBeenCalledWith(props);
+            expect(result).toBe(expectedToken);
+        });
+    });
+    describe("generateRefreshToken", () => {
+        it("debería delegar en JwtTokenGenerator.generateRefreshToken y retornar el token", async () => {
+            const props = {
+                userId: "user-123",
+            };
+            const expectedToken = "refresh.token.value";
+            jwtGenerator.generateRefreshToken.mockResolvedValue(expectedToken);
+            const result = await service.generateRefreshToken(props);
+            expect(jwtGenerator.generateRefreshToken).toHaveBeenCalledTimes(1);
+            expect(jwtGenerator.generateRefreshToken).toHaveBeenCalledWith(props);
+            expect(result).toBe(expectedToken);
+        });
+    });
+    describe("verifyAccessToken", () => {
+        it("debería validar el token y delegar en JwtTokenVerifier.verifyAccessToken", async () => {
+            const token = "access.token.value";
+            const payload = {
+                sub: "user-123",
+                roles: [
+                    {
+                        role: "user",
+                    },
+                ],
+                customClaims: {},
+                jti: "unique-jwt-id",
+                iss: "test-issuer",
+                aud: "test-audience",
+                iat: Date.now() / 1000,
+                exp: (Date.now() + 1000) / 1000,
+            };
+            jwtVerifier.verifyAccessToken.mockResolvedValue(payload);
+            const result = await service.verifyAccessToken(token);
+            // Primero se valida la entrada
+            expect(jwtValidator.validateTokenInput).toHaveBeenCalledTimes(1);
+            expect(jwtValidator.validateTokenInput).toHaveBeenCalledWith(token);
+            // Luego se delega al verificador con el token y la config
+            expect(jwtVerifier.verifyAccessToken).toHaveBeenCalledTimes(1);
+            expect(jwtVerifier.verifyAccessToken).toHaveBeenCalledWith(token, config);
+            expect(result).toBe(payload);
+        });
+        it("debería propagar el error si validateTokenInput lanza una excepción", async () => {
+            const token = "invalid.token";
+            jwtValidator.validateTokenInput.mockImplementation(() => {
+                throw new Error("Invalid token format");
+            });
+            await expect(service.verifyAccessToken(token)).rejects.toThrow("Invalid token format");
+            // Si falla la validación, no debería llamar al verificador
+            expect(jwtVerifier.verifyAccessToken).not.toHaveBeenCalled();
+        });
+    });
+    describe("verifyRefreshToken", () => {
+        it("debería validar el token y delegar en JwtTokenVerifier.verifyRefreshToken", async () => {
+            const token = "refresh.token.value";
+            const payload = {
+                sub: "user-123",
+                roles: [
+                    {
+                        role: "user",
+                    },
+                ],
+                customClaims: {},
+                jti: "unique-jwt-id",
+                iss: "test-issuer",
+                aud: "test-audience",
+                iat: Date.now() / 1000,
+                exp: (Date.now() + 1000) / 1000,
+            };
+            jwtVerifier.verifyRefreshToken.mockResolvedValue(payload);
+            const result = await service.verifyRefreshToken(token);
+            expect(jwtValidator.validateTokenInput).toHaveBeenCalledTimes(1);
+            expect(jwtValidator.validateTokenInput).toHaveBeenCalledWith(token);
+            expect(jwtVerifier.verifyRefreshToken).toHaveBeenCalledTimes(1);
+            expect(jwtVerifier.verifyRefreshToken).toHaveBeenCalledWith(token, config);
+            expect(result).toBe(payload);
+        });
+    });
+    describe("getTokenExpiration", () => {
+        it("debería validar el token y delegar en JwtTokenVerifier.getTokenExpiration", async () => {
+            const token = "any.token.value";
+            const expectedDate = new Date(Date.now() + 10000);
+            jwtVerifier.getTokenExpiration.mockResolvedValue(expectedDate);
+            const result = await service.getTokenExpiration(token);
+            expect(jwtValidator.validateTokenInput).toHaveBeenCalledTimes(1);
+            expect(jwtValidator.validateTokenInput).toHaveBeenCalledWith(token);
+            expect(jwtVerifier.getTokenExpiration).toHaveBeenCalledTimes(1);
+            expect(jwtVerifier.getTokenExpiration).toHaveBeenCalledWith(token);
+            expect(result).toBe(expectedDate);
+        });
+        it("debería propagar el error si validateTokenInput lanza una excepción", async () => {
+            const token = "invalid.token";
+            jwtValidator.validateTokenInput.mockImplementation(() => {
+                throw new Error("Invalid token");
+            });
+            await expect(service.getTokenExpiration(token)).rejects.toThrow("Invalid token");
+            expect(jwtVerifier.getTokenExpiration).not.toHaveBeenCalled();
+        });
+    });
+});

package/dist/tests/infrastructure/services/token-session.service.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/infrastructure/services/token-session.service.spec.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const domain_1 = require("../../../src/domain");
+const token_session_service_1 = require("../../../src/infrastructure/services/token-session.service");
+const shared_1 = require("../../../src/shared");
+describe("TokenSessionService", () => {
+    let tokenService;
+    let userRepository;
+    let credentialRepository;
+    const accessTokenExpiration = "15m";
+    const refreshTokenExpiration = "7d";
+    const accessSecret = "access-secret";
+    const refreshSecret = "refresh-secret";
+    const algorithm = "HS256";
+    const makeService = () => new token_session_service_1.TokenSessionService(tokenService, userRepository, credentialRepository, algorithm, accessTokenExpiration, refreshTokenExpiration, accessSecret, refreshSecret);
+    beforeEach(() => {
+        tokenService = {
+            generateAccessToken: jest.fn(),
+            generateRefreshToken: jest.fn(),
+            verifyAccessToken: jest.fn(),
+            verifyRefreshToken: jest.fn(),
+            getTokenExpiration: jest.fn(),
+        };
+        userRepository = {
+            findById: jest.fn(),
+        };
+        credentialRepository = {
+            save: jest.fn(),
+            findByUserId: jest.fn(),
+            findByRefreshToken: jest.fn(),
+            update: jest.fn(),
+            delete: jest.fn(),
+            deleteByRefreshToken: jest.fn(),
+        };
+        jest.restoreAllMocks();
+    });
+    // ────────────────────────────────────────────────
+    // Constructor
+    // ────────────────────────────────────────────────
+    it("debería lanzar JwtSecretError si faltan los secretos", () => {
+        expect(() => new token_session_service_1.TokenSessionService(tokenService, userRepository, credentialRepository, algorithm, accessTokenExpiration, refreshTokenExpiration, undefined, // accessTokenSecret
+        undefined // refreshTokenSecret
+        )).toThrow(domain_1.JwtSecretError);
+    });
+    it("debería lanzar error si la configuración de expiración es inválida", () => {
+        const spy = jest
+            .spyOn(shared_1.TimeParser, "parseToMilliseconds")
+            .mockImplementation(() => {
+            throw new Error("Formato inválido");
+        });
+        expect(() => new token_session_service_1.TokenSessionService(tokenService, userRepository, credentialRepository, algorithm, "invalid", // access
+        "invalid", // refresh
+        accessSecret, refreshSecret)).toThrow("Invalid token expiration configuration");
+        spy.mockRestore();
+    });
+    // ────────────────────────────────────────────────
+    // createSession
+    // ────────────────────────────────────────────────
+    describe("createSession", () => {
+        it("debería generar access y refresh tokens, guardar la credencial y retornarla", async () => {
+            const service = makeService();
+            const mockUserId = "user-123";
+            const mockEmail = "user@example.com";
+            const mockRolesPublic = [{ role: "user" }];
+            const user = {
+                id: { toString: () => mockUserId },
+                email: { toString: () => mockEmail },
+                roles: [
+                    {
+                        getValuePublic: () => mockRolesPublic[0],
+                    },
+                ],
+            };
+            tokenService.generateAccessToken.mockResolvedValue("access-token");
+            tokenService.generateRefreshToken.mockResolvedValue("refresh-token");
+            const result = await service.createSession(user);
+            // Debe generar tokens con los datos del usuario
+            expect(tokenService.generateAccessToken).toHaveBeenCalledTimes(1);
+            expect(tokenService.generateAccessToken).toHaveBeenCalledWith(expect.objectContaining({
+                user: {
+                    id: mockUserId,
+                    email: mockEmail,
+                    roles: mockRolesPublic,
+                },
+                expiresIn: accessTokenExpiration,
+            }));
+            expect(tokenService.generateRefreshToken).toHaveBeenCalledTimes(1);
+            expect(tokenService.generateRefreshToken).toHaveBeenCalledWith(expect.objectContaining({
+                user: {
+                    id: mockUserId,
+                    email: mockEmail,
+                    roles: mockRolesPublic,
+                },
+                expiresIn: refreshTokenExpiration,
+            }));
+            // Debe guardar la credencial
+            expect(credentialRepository.save).toHaveBeenCalledTimes(1);
+            const savedCredential = credentialRepository.save.mock
+                .calls[0][0];
+            // La credencial retornada debe ser la misma que se guardó
+            expect(result).toBe(savedCredential);
+            expect(savedCredential).toBeInstanceOf(domain_1.Credential);
+        });
+    });
+    // ────────────────────────────────────────────────
+    // refreshSession
+    // ────────────────────────────────────────────────
+    describe("refreshSession", () => {
+        const refreshToken = "refresh-token";
+        it("debería lanzar InvalidOrExpiredRefreshTokenError si no existe credencial para el refresh token", async () => {
+            const service = makeService();
+            credentialRepository.findByRefreshToken.mockResolvedValue(null);
+            await expect(service.refreshSession(refreshToken)).rejects.toThrow(domain_1.InvalidOrExpiredRefreshTokenError);
+            expect(credentialRepository.findByRefreshToken).toHaveBeenCalledWith(refreshToken);
+        });
+        it("debería lanzar InvalidOrExpiredRefreshTokenError si verifyRefreshToken falla", async () => {
+            const service = makeService();
+            credentialRepository.findByRefreshToken.mockResolvedValue({});
+            tokenService.verifyRefreshToken.mockRejectedValue(new Error("expired"));
+            await expect(service.refreshSession(refreshToken)).rejects.toThrow(domain_1.InvalidOrExpiredRefreshTokenError);
+        });
+        it("debería lanzar UserNotFoundError si el usuario no existe", async () => {
+            const service = makeService();
+            credentialRepository.findByRefreshToken.mockResolvedValue({});
+            const payload = {
+                sub: "user-123",
+                iss: "test",
+                aud: "test",
+                iat: Date.now() / 1000,
+                exp: (Date.now() + 1000) / 1000,
+                roles: [],
+                customClaims: {},
+                jti: "id",
+            };
+            tokenService.verifyRefreshToken.mockResolvedValue(payload);
+            userRepository.findById.mockResolvedValue(null);
+            await expect(service.refreshSession(refreshToken)).rejects.toThrow(domain_1.UserNotFoundError);
+            expect(userRepository.findById).toHaveBeenCalledWith(expect.any(domain_1.Id) // se instancia con payload.sub
+            );
+        });
+        it("debería lanzar UserDisabledError si el usuario está deshabilitado", async () => {
+            const service = makeService();
+            credentialRepository.findByRefreshToken.mockResolvedValue({});
+            const payload = {
+                sub: "user-123",
+                iss: "test",
+                aud: "test",
+                iat: Date.now() / 1000,
+                exp: (Date.now() + 1000) / 1000,
+                roles: [],
+                customClaims: {},
+                jti: "id",
+            };
+            tokenService.verifyRefreshToken.mockResolvedValue(payload);
+            const user = {
+                canLogin: jest.fn().mockReturnValue(false),
+            };
+            userRepository.findById.mockResolvedValue(user);
+            await expect(service.refreshSession(refreshToken)).rejects.toThrow(domain_1.UserDisabledError);
+        });
+        it("debería crear una nueva sesión, eliminar la credencial anterior y retornar la nueva", async () => {
+            const service = makeService();
+            // Existe una credencial asociada al refresh token
+            credentialRepository.findByRefreshToken.mockResolvedValue({});
+            const payload = {
+                sub: "user-123",
+                iss: "test",
+                aud: "test",
+                iat: Date.now() / 1000,
+                exp: (Date.now() + 1000) / 1000,
+                roles: [],
+                customClaims: {},
+                jti: "id",
+            };
+            tokenService.verifyRefreshToken.mockResolvedValue(payload);
+            const user = {
+                id: { toString: () => "user-123" },
+                email: { toString: () => "user@example.com" },
+                roles: [
+                    {
+                        getValuePublic: () => ({ role: "user" }),
+                    },
+                ],
+                canLogin: jest.fn().mockReturnValue(true),
+            };
+            userRepository.findById.mockResolvedValue(user);
+            tokenService.generateAccessToken.mockResolvedValue("new-access");
+            tokenService.generateRefreshToken.mockResolvedValue("new-refresh");
+            const result = await service.refreshSession(refreshToken);
+            // Debe haber creado y guardado una nueva credencial
+            expect(credentialRepository.save).toHaveBeenCalledTimes(1);
+            const savedCredential = credentialRepository.save.mock
+                .calls[0][0];
+            expect(result).toBe(savedCredential);
+            expect(savedCredential).toBeInstanceOf(domain_1.Credential);
+            // Debe eliminar la credencial vieja asociada al refresh token
+            expect(credentialRepository.deleteByRefreshToken).toHaveBeenCalledWith(refreshToken);
+        });
+    });
+    // ────────────────────────────────────────────────
+    // validateSession
+    // ────────────────────────────────────────────────
+    describe("validateSession", () => {
+        it("debería retornar el usuario cuando el token es válido y el usuario puede iniciar sesión", async () => {
+            const service = makeService();
+            const payload = {
+                sub: "user-123",
+                iss: "test",
+                aud: "test",
+                iat: Date.now() / 1000,
+                exp: (Date.now() + 1000) / 1000,
+                roles: [],
+                customClaims: {},
+                jti: "id",
+            };
+            tokenService.verifyAccessToken.mockResolvedValue(payload);
+            const user = {
+                canLogin: jest.fn().mockReturnValue(true),
+            };
+            userRepository.findById.mockResolvedValue(user);
+            const result = await service.validateSession("access-token");
+            expect(tokenService.verifyAccessToken).toHaveBeenCalledWith("access-token");
+            expect(userRepository.findById).toHaveBeenCalledWith(expect.any(domain_1.Id));
+            expect(result).toBe(user);
+        });
+        it("debería retornar null si verifyAccessToken lanza error", async () => {
+            const service = makeService();
+            tokenService.verifyAccessToken.mockRejectedValue(new Error("invalid"));
+            const result = await service.validateSession("invalid-token");
+            expect(result).toBeNull();
+        });
+        it("debería retornar null si el usuario no existe o no puede iniciar sesión", async () => {
+            const service = makeService();
+            const payload = {
+                sub: "user-123",
+                iss: "test",
+                aud: "test",
+                iat: Date.now() / 1000,
+                exp: (Date.now() + 1000) / 1000,
+                roles: [],
+                customClaims: {},
+                jti: "id",
+            };
+            tokenService.verifyAccessToken.mockResolvedValue(payload);
+            // Caso usuario no existe
+            userRepository.findById.mockResolvedValueOnce(null);
+            const result1 = await service.validateSession("access-token");
+            expect(result1).toBeNull();
+            // Caso usuario existe pero no puede iniciar sesión
+            const user = {
+                canLogin: jest.fn().mockReturnValue(false),
+            };
+            userRepository.findById.mockResolvedValueOnce(user);
+            const result2 = await service.validateSession("access-token");
+            expect(result2).toBeNull();
+        });
+    });
+    // ────────────────────────────────────────────────
+    // revokeSession
+    // ────────────────────────────────────────────────
+    describe("revokeSession", () => {
+        it("debería eliminar la credencial asociada al refresh token", async () => {
+            const service = makeService();
+            const refreshToken = "refresh-token";
+            await service.revokeSession(refreshToken);
+            expect(credentialRepository.deleteByRefreshToken).toHaveBeenCalledWith(refreshToken);
+        });
+    });
+});

package/dist/tests/shared/constants/jwt-algorithms.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/shared/constants/jwt-algorithms.spec.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const shared_1 = require("src/shared");
+describe("algorithms constant", () => {
+    it("define las tres categorías principales", () => {
+        expect(Object.keys(shared_1.algorithms)).toEqual(["hmac", "rsa", "ecdsa"]);
+    });
+    it("cada categoría contiene tres algoritmos esperados", () => {
+        expect(Object.keys(shared_1.algorithms.hmac)).toEqual(["HS256", "HS384", "HS512"]);
+        expect(Object.keys(shared_1.algorithms.rsa)).toEqual(["RS256", "RS384", "RS512"]);
+        expect(Object.keys(shared_1.algorithms.ecdsa)).toEqual(["ES256", "ES384", "ES512"]);
+    });
+    it("los valores coinciden exactamente con sus claves (autodescriptivos)", () => {
+        for (const [family, algos] of Object.entries(shared_1.algorithms)) {
+            for (const [key, value] of Object.entries(algos)) {
+                expect(value).toBe(key);
+            }
+        }
+    });
+    it("no debe contener valores nulos o indefinidos", () => {
+        for (const family of Object.values(shared_1.algorithms)) {
+            for (const value of Object.values(family)) {
+                expect(value).toBeTruthy();
+            }
+        }
+    });
+});

package/dist/tests/shared/encoders/base64-url-encoder.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/shared/encoders/base64-url-encoder.spec.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const shared_1 = require("../../../src/shared");
+describe("Base64UrlEncoder", () => {
+    const enc = new shared_1.Base64UrlEncoder();
+    describe("encode", () => {
+        it.each([
+            ["", ""],
+            ["f", "Zg"],
+            ["fo", "Zm8"],
+            ["foo", "Zm9v"],
+            ["foob", "Zm9vYg"],
+            ["fooba", "Zm9vYmE"],
+            ["foobar", "Zm9vYmFy"],
+            ["hello", "aGVsbG8"],
+            ["mañana", "bWHDsWFuYQ"], // UTF-8
+            ["🔥", "8J-UpQ"], // incluye '-'
+            ["😺", "8J-Yug"], // incluye '-'
+            ["00?", "MDA_"], // incluye '_'
+        ])('encode("%s") → "%s"', (plain, expected) => {
+            expect(enc.encode(plain)).toBe(expected);
+        });
+        it("no contiene +, / ni = (URL-safe y sin padding)", () => {
+            const out = enc.encode("texto con símbolos: ~✓🔥/+/=");
+            expect(out).not.toMatch(/[+/=]/);
+        });
+    });
+    describe("decode", () => {
+        it.each([
+            ["", ""],
+            ["Zg", "f"], // sin padding (==)
+            ["Zm8", "fo"], // sin padding (=)
+            ["Zm9v", "foo"], // sin padding
+            ["Zm9vYg", "foob"],
+            ["Zm9vYmE", "fooba"],
+            ["Zm9vYmFy", "foobar"],
+            ["aGVsbG8", "hello"],
+            ["bWHDsWFuYQ", "mañana"], // UTF-8
+            ["8J-UpQ", "🔥"], // con '-'
+            ["MDA_", "00?"], // con '_'
+        ])('decode("%s") → "%s"', (b64url, expected) => {
+            expect(enc.decode(b64url)).toBe(expected);
+        });
+        it("acepta también Base64 “estándar” con padding", () => {
+            // Aunque la clase es URL-safe, su decode soporta base64 estándar.
+            expect(enc.decode("aGVsbG8=")).toBe("hello");
+            expect(enc.decode("Zm8=")).toBe("fo");
+            expect(enc.decode("Zg==")).toBe("f");
+        });
+        it("reconstituye padding correcto cuando falta", () => {
+            // length % 4 === 2 → agrega "=="
+            expect(enc.decode("Zg")).toBe("f");
+            // length % 4 === 3 → agrega "="
+            expect(enc.decode("Zm8")).toBe("fo");
+        });
+    });
+    describe("round-trip", () => {
+        it.each([
+            "",
+            "hola",
+            "The quick brown fox jumps over the lazy dog.",
+            "mañana será otro día",
+            "🔥😺 ~ ✓ / + _",
+        ])('decode(encode(x)) === x para "%s"', (plain) => {
+            const encoded = enc.encode(plain);
+            const decoded = enc.decode(encoded);
+            expect(decoded).toBe(plain);
+        });
+    });
+});

package/dist/tests/shared/utils/time-parser.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/shared/utils/time-parser.spec.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// tests/shared/TimeParser.spec.ts
+const time_parser_1 = require("../../../src/shared/utils/time-parser");
+describe("TimeParser", () => {
+    describe("parseToMilliseconds", () => {
+        it.each([
+            ["30s", 30000],
+            ["1m", 60000],
+            ["15m", 900000],
+            ["1h", 3600000],
+            ["2h", 7200000],
+            ["1d", 86400000],
+            ["3d", 259200000],
+        ])("convierte %s a %d ms", (input, expected) => {
+            expect(time_parser_1.TimeParser.parseToMilliseconds(input)).toBe(expected);
+        });
+        it("ignora espacios y mayúsculas/minúsculas", () => {
+            expect(time_parser_1.TimeParser.parseToMilliseconds("  2H ")).toBe(7200000);
+            expect(time_parser_1.TimeParser.parseToMilliseconds("  45S")).toBe(45000);
+        });
+        it("lanza si no es string o es falsy", () => {
+            expect(() => time_parser_1.TimeParser.parseToMilliseconds("")).toThrow(/must be a string/i);
+            // Solo espacios
+            expect(() => time_parser_1.TimeParser.parseToMilliseconds("   ")).toThrow(/invalid time format/i);
+        });
+        it("lanza si el formato no coincide con número+unidad", () => {
+            for (const bad of ["15", "m15", "1 h", "1w", "1mh", "-5m"]) {
+                expect(() => time_parser_1.TimeParser.parseToMilliseconds(bad)).toThrow(/invalid time format/i);
+            }
+        });
+        it("lanza si el valor es 0 (o no positivo)", () => {
+            expect(() => time_parser_1.TimeParser.parseToMilliseconds("0m")).toThrow(/invalid time value/i);
+            expect(() => time_parser_1.TimeParser.parseToMilliseconds("000s")).toThrow(/invalid time value/i);
+        });
+        it("acepta ceros a la izquierda válidos (01h -> 1h)", () => {
+            expect(time_parser_1.TimeParser.parseToMilliseconds("01h")).toBe(3600000);
+        });
+    });
+    describe("isValidTimeString", () => {
+        it.each(["30s", "1m", "2h", "7d", "  2H  "])("devuelve true para %s", (input) => {
+            expect(time_parser_1.TimeParser.isValidTimeString(input)).toBe(true);
+        });
+        it.each(["", "   ", "1", "m15", "1 h", "1w", "0m", "-5m"])("devuelve false para %s", (input) => {
+            expect(time_parser_1.TimeParser.isValidTimeString(input)).toBe(false);
+        });
+    });
+    describe("getSupportedUnits", () => {
+        it("devuelve las unidades soportadas en orden estable", () => {
+            const units = time_parser_1.TimeParser.getSupportedUnits();
+            expect(units).toEqual(["s", "m", "h", "d"]);
+            expect(new Set(units)).toEqual(new Set(["s", "m", "h", "d"]));
+        });
+    });
+    describe("formatMilliseconds", () => {
+        it.each([
+            [1000, "1s"],
+            [3000, "3s"],
+            [60000, "1m"],
+            [120000, "2m"],
+            [180000, "3m"],
+            [3600000, "1h"],
+            [7200000, "2h"],
+            [86400000, "1d"],
+            [172800000, "2d"],
+        ])("formatea %d como %s", (ms, expected) => {
+            expect(time_parser_1.TimeParser.formatMilliseconds(ms)).toBe(expected);
+        });
+        it("elige la unidad más grande divisible exactamente (90_000 -> 90s, no 1.5m)", () => {
+            expect(time_parser_1.TimeParser.formatMilliseconds(90000)).toBe("90s");
+        });
+        it('cuando no es divisible exacto por 1000, devuelve "Xms"', () => {
+            expect(time_parser_1.TimeParser.formatMilliseconds(1501)).toBe("1501ms");
+            expect(time_parser_1.TimeParser.formatMilliseconds(65001)).toBe("65001ms");
+        });
+        it('0ms retorna "0ms"', () => {
+            expect(time_parser_1.TimeParser.formatMilliseconds(0)).toBe("0ms");
+        });
+    });
+});

package/dist/utils/index.d.ts

@@ -0,0 +1 @@
+export * from "./time-parser";

package/dist/utils/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./time-parser"), exports);

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

@@ -0,0 +1,28 @@
+export declare class TimeParser {
+    private static readonly TIME_UNITS;
+    private static readonly TIME_PATTERN;
+    /**
+     * Convierte una cadena de tiempo (ej: "15m", "1h", "7d") a milisegundos
+     * @param timeString - Cadena de tiempo en formato número + unidad
+     * @returns Tiempo en milisegundos
+     * @throws Error si el formato es inválido
+     */
+    static parseToMilliseconds(timeString: string): number;
+    /**
+     * Valida si una cadena de tiempo tiene el formato correcto
+     * @param timeString - Cadena de tiempo a validar
+     * @returns true si es válida, false en caso contrario
+     */
+    static isValidTimeString(timeString: string): boolean;
+    /**
+     * Obtiene las unidades de tiempo soportadas
+     * @returns Array con las unidades soportadas
+     */
+    static getSupportedUnits(): string[];
+    /**
+     * Convierte milisegundos a formato legible
+     * @param milliseconds - Tiempo en milisegundos
+     * @returns Cadena de tiempo legible
+     */
+    static formatMilliseconds(milliseconds: number): string;
+}