@adatechnology/user-contracts 0.1.0-rc.1

package/dist/index.d.cts

@@ -0,0 +1,395 @@
+import { z } from 'zod';
+
+/**
+ * Copyright (c) 2026 Ada Technology. All rights reserved.
+ *
+ * This source code is proprietary and confidential. Unauthorized copying,
+ * modification, distribution, or use of this file, via any medium, is
+ * strictly prohibited without prior written permission from Ada Technology.
+ */
+type UserProfile = {
+    readonly id: string;
+    readonly email: string;
+    readonly name: string;
+    readonly role: string;
+    readonly companyId?: string;
+    readonly isActive: boolean;
+    readonly lastSeenAt?: Date;
+};
+type UserSession = {
+    readonly accessToken: string;
+    readonly expiresInSeconds: number;
+    readonly refreshToken: string;
+    readonly refreshExpiresInSeconds: number;
+    readonly user: UserProfile;
+};
+type SessionStatus = 'unknown' | 'anonymous' | 'authenticated';
+type PaginatedResponse<T> = {
+    readonly data: readonly T[];
+    readonly pagination: {
+        readonly total: number;
+        readonly page: number;
+        readonly perPage: number;
+    };
+};
+type ListUsersParams = {
+    readonly page?: number;
+    readonly perPage?: number;
+    readonly companyId?: string;
+};
+
+/**
+ * Copyright (c) 2026 Ada Technology. All rights reserved.
+ *
+ * This source code is proprietary and confidential. Unauthorized copying,
+ * modification, distribution, or use of this file, via any medium, is
+ * strictly prohibited without prior written permission from Ada Technology.
+ */
+declare const USER_ERROR_CODE: {
+    readonly INVALID_CREDENTIALS: "USER_INVALID_CREDENTIALS";
+    readonly USER_NOT_FOUND: "USER_NOT_FOUND";
+    readonly EMAIL_ALREADY_EXISTS: "USER_EMAIL_ALREADY_EXISTS";
+    readonly NOT_AUTHENTICATED: "USER_NOT_AUTHENTICATED";
+    readonly RESET_TOKEN_INVALID: "USER_RESET_TOKEN_INVALID";
+    readonly RESET_TOKEN_EXPIRED: "USER_RESET_TOKEN_EXPIRED";
+    readonly RESET_TOKEN_ALREADY_USED: "USER_RESET_TOKEN_ALREADY_USED";
+    readonly WEAK_PASSWORD: "USER_WEAK_PASSWORD";
+    readonly PROVIDER_MISCONFIGURED: "USER_PROVIDER_MISCONFIGURED";
+    readonly PROVIDER_DISABLED: "USER_PROVIDER_DISABLED";
+    readonly CONFIG_MISSING: "USER_CONFIG_MISSING";
+};
+type UserErrorCode = (typeof USER_ERROR_CODE)[keyof typeof USER_ERROR_CODE];
+declare class UserError extends Error {
+    readonly statusCode: number;
+    readonly code: UserErrorCode;
+    readonly details?: unknown;
+    constructor(params: {
+        message: string;
+        statusCode: number;
+        code: UserErrorCode;
+        details?: unknown;
+    });
+}
+declare class InvalidCredentialsError extends UserError {
+    constructor();
+}
+declare class UserNotFoundError extends UserError {
+    constructor();
+}
+declare class EmailAlreadyExistsError extends UserError {
+    constructor();
+}
+declare class NotAuthenticatedError extends UserError {
+    constructor();
+}
+declare class ResetTokenInvalidError extends UserError {
+    constructor();
+}
+declare class ResetTokenExpiredError extends UserError {
+    constructor();
+}
+declare class ResetTokenAlreadyUsedError extends UserError {
+    constructor();
+}
+declare class WeakPasswordError extends UserError {
+    constructor();
+}
+declare class ProviderMisconfiguredError extends UserError {
+    constructor(details?: unknown);
+}
+declare class ProviderDisabledError extends UserError {
+    constructor();
+}
+declare class ConfigMissingError extends UserError {
+    constructor(field: string);
+}
+
+/**
+ * Copyright (c) 2026 Ada Technology. All rights reserved.
+ *
+ * This source code is proprietary and confidential. Unauthorized copying,
+ * modification, distribution, or use of this file, via any medium, is
+ * strictly prohibited without prior written permission from Ada Technology.
+ */
+
+declare const USER_EVENT: {
+    readonly USER_CREATED: "user.user.created";
+    readonly USER_UPDATED: "user.user.updated";
+    readonly LOGIN_SUCCEEDED: "user.login.succeeded";
+    readonly LOGIN_FAILED: "user.login.failed";
+    readonly PASSWORD_CHANGED: "user.password.changed";
+    readonly PASSWORD_RESET_REQUESTED: "user.password_reset.requested";
+    readonly PASSWORD_RESET_COMPLETED: "user.password_reset.completed";
+    readonly PROFILE_UPDATED: "user.profile.updated";
+};
+type UserEventType = (typeof USER_EVENT)[keyof typeof USER_EVENT];
+type BaseEvent = {
+    readonly companyId?: string;
+    readonly occurredAt: Date;
+};
+type UserCreatedEvent = BaseEvent & {
+    readonly type: typeof USER_EVENT.USER_CREATED;
+    readonly userId: string;
+    readonly email: string;
+};
+type UserUpdatedEvent = BaseEvent & {
+    readonly type: typeof USER_EVENT.USER_UPDATED;
+    readonly userId: string;
+    readonly user: UserProfile;
+};
+type LoginSucceededEvent = BaseEvent & {
+    readonly type: typeof USER_EVENT.LOGIN_SUCCEEDED;
+    readonly userId: string;
+    readonly email: string;
+    readonly ipAddress: string;
+};
+type LoginFailedEvent = BaseEvent & {
+    readonly type: typeof USER_EVENT.LOGIN_FAILED;
+    readonly email: string;
+    readonly ipAddress: string;
+    readonly reason: string;
+};
+type PasswordChangedEvent = BaseEvent & {
+    readonly type: typeof USER_EVENT.PASSWORD_CHANGED;
+    readonly userId: string;
+};
+type PasswordResetRequestedEvent = BaseEvent & {
+    readonly type: typeof USER_EVENT.PASSWORD_RESET_REQUESTED;
+    readonly email: string;
+    readonly resetUrl: string;
+};
+type PasswordResetCompletedEvent = BaseEvent & {
+    readonly type: typeof USER_EVENT.PASSWORD_RESET_COMPLETED;
+    readonly userId: string;
+    readonly email: string;
+};
+type ProfileUpdatedEvent = BaseEvent & {
+    readonly type: typeof USER_EVENT.PROFILE_UPDATED;
+    readonly userId: string;
+    readonly user: UserProfile;
+};
+type UserDomainEvent = UserCreatedEvent | UserUpdatedEvent | LoginSucceededEvent | LoginFailedEvent | PasswordChangedEvent | PasswordResetRequestedEvent | PasswordResetCompletedEvent | ProfileUpdatedEvent;
+type UserHooks = {
+    readonly onUserCreated?: (event: UserCreatedEvent) => Promise<void> | void;
+    readonly onUserUpdated?: (event: UserUpdatedEvent) => Promise<void> | void;
+    readonly onLoginSucceeded?: (event: LoginSucceededEvent) => Promise<void> | void;
+    readonly onLoginFailed?: (event: LoginFailedEvent) => Promise<void> | void;
+    readonly onPasswordChanged?: (event: PasswordChangedEvent) => Promise<void> | void;
+    readonly onPasswordResetRequested?: (event: PasswordResetRequestedEvent) => Promise<void> | void;
+    readonly onPasswordResetCompleted?: (event: PasswordResetCompletedEvent) => Promise<void> | void;
+    readonly onProfileUpdated?: (event: ProfileUpdatedEvent) => Promise<void> | void;
+};
+
+/**
+ * Copyright (c) 2026 Ada Technology. All rights reserved.
+ *
+ * This source code is proprietary and confidential. Unauthorized copying,
+ * modification, distribution, or use of this file, via any medium, is
+ * strictly prohibited without prior written permission from Ada Technology.
+ */
+
+declare const AUTH_PROVIDER_TYPE: {
+    readonly LOCAL: "local";
+    readonly OAUTH2: "oauth2";
+    readonly OIDC: "oidc";
+};
+type AuthProviderType = (typeof AUTH_PROVIDER_TYPE)[keyof typeof AUTH_PROVIDER_TYPE];
+type AuthProviderInterface<TCredentials = unknown> = {
+    readonly id: string;
+    readonly type: AuthProviderType;
+    authenticate(params: {
+        readonly credentials: TCredentials;
+        readonly ipAddress?: string;
+    }): Promise<UserSession>;
+};
+type AttributeMappingRule<TClaims extends Record<string, unknown>> = {
+    readonly from: keyof TClaims;
+} | {
+    readonly value: string;
+};
+type AttributeMapping<TClaims extends Record<string, unknown>> = {
+    readonly email: AttributeMappingRule<TClaims>;
+    readonly name?: AttributeMappingRule<TClaims>;
+    readonly role?: AttributeMappingRule<TClaims>;
+};
+/**
+ * `issue` devolve o token cru; `rotate`/`revoke` recebem o **sha256 hex** dele — o token cru nunca
+ * chega ao armazenamento, então um dump do Redis ou da tabela não vale sessão.
+ *
+ * `revokeAllForUser` é o que faz uma troca de senha realmente encerrar as sessões abertas. Sem ela,
+ * a sessão comprometida sobrevive à redefinição feita justamente para matá-la — por isso é
+ * obrigatória no contrato, e não uma capacidade opcional.
+ */
+type RefreshTokenStorePort = {
+    issue(params: {
+        readonly userId: string;
+        readonly expiresInSeconds: number;
+    }): Promise<string>;
+    rotate(params: {
+        readonly tokenHash: string;
+        readonly newExpiresInSeconds: number;
+    }): Promise<{
+        readonly token: string;
+        readonly userId: string;
+    } | null>;
+    revoke(params: {
+        readonly tokenHash: string;
+    }): Promise<void>;
+    revokeAllForUser(params: {
+        readonly userId: string;
+    }): Promise<void>;
+};
+type SendEmailParams = {
+    readonly to: string;
+    readonly subject: string;
+    readonly body: string;
+    readonly html?: string;
+};
+type DeliveryAttemptResult = {
+    readonly success: boolean;
+    readonly messageId?: string;
+    readonly error?: string;
+};
+type EmailDriverPort = {
+    readonly driver: string;
+    send(params: SendEmailParams): Promise<DeliveryAttemptResult>;
+};
+type ClockPort = {
+    now(): Date;
+};
+type LogMeta = Readonly<Record<string, unknown>>;
+/** Mesma forma do `LoggerPort` dos outros contratos do ecossistema — o host escreve um adapter só. */
+type LoggerPort = {
+    error(message: string, meta?: LogMeta): void;
+    warn(message: string, meta?: LogMeta): void;
+    info(message: string, meta?: LogMeta): void;
+    debug(message: string, meta?: LogMeta): void;
+};
+type TenancyConfig = {
+    readonly mode: 'single';
+    readonly defaultCompanyId: string;
+} | {
+    readonly mode: 'multi';
+};
+/**
+ * `issuer`/`audience` são opcionais, mas quando declarados valem na assinatura **e** na
+ * verificação: um token emitido para outra plateia é recusado. Um host que já emite JWT por conta
+ * própria (migração gradual, dois emissores sobre o mesmo segredo) precisa declarar os mesmos
+ * valores aqui, ou os dois lados não reconhecem o token um do outro.
+ */
+type AccessTokenConfig = {
+    readonly secret: string;
+    readonly expiresInSeconds?: number;
+    readonly issuer?: string;
+    readonly audience?: string;
+};
+type RefreshTokenConfig = {
+    readonly expiresInSeconds?: number;
+};
+type PasswordResetConfig = {
+    readonly resetUrlTemplate: string;
+    readonly tokenExpiresInSeconds?: number;
+};
+type KeycloakConfig = {
+    readonly realm: string;
+    readonly authServerUrl: string;
+    readonly clientId: string;
+    readonly clientSecret?: string;
+    readonly attributeMapping?: AttributeMapping<Record<string, unknown>>;
+};
+type UserModuleConfig = {
+    readonly tenancy: TenancyConfig;
+    readonly accessToken: AccessTokenConfig;
+    readonly refreshToken?: RefreshTokenConfig;
+    readonly passwordReset?: PasswordResetConfig;
+    readonly keycloak?: KeycloakConfig;
+};
+/**
+ * `keycloak` não entra aqui: a verificação de token é plumbing específico do módulo (ver
+ * `KeycloakVerifierPort` em `user-module`), não um contrato genérico reutilizável por outro host.
+ */
+type UserModuleProviders = {
+    readonly refreshTokenStore?: RefreshTokenStorePort;
+    readonly email?: EmailDriverPort;
+    readonly clock?: ClockPort;
+    readonly logger?: LoggerPort;
+};
+
+/**
+ * Copyright (c) 2026 Ada Technology. All rights reserved.
+ *
+ * This source code is proprietary and confidential. Unauthorized copying,
+ * modification, distribution, or use of this file, via any medium, is
+ * strictly prohibited without prior written permission from Ada Technology.
+ */
+
+declare const localCredentialsSchema: z.ZodObject<{
+    email: z.ZodString;
+    password: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    email: string;
+    password: string;
+}, {
+    email: string;
+    password: string;
+}>;
+type LocalCredentials = z.infer<typeof localCredentialsSchema>;
+declare const requestPasswordResetSchema: z.ZodObject<{
+    email: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    email: string;
+}, {
+    email: string;
+}>;
+type RequestPasswordResetInput = z.infer<typeof requestPasswordResetSchema>;
+declare const confirmPasswordResetSchema: z.ZodObject<{
+    token: z.ZodString;
+    newPassword: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    token: string;
+    newPassword: string;
+}, {
+    token: string;
+    newPassword: string;
+}>;
+type ConfirmPasswordResetInput = z.infer<typeof confirmPasswordResetSchema>;
+declare const updateProfileSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name?: string | undefined;
+}, {
+    name?: string | undefined;
+}>;
+type UpdateProfileInput = z.infer<typeof updateProfileSchema>;
+declare const createUserSchema: z.ZodObject<{
+    email: z.ZodString;
+    name: z.ZodString;
+    password: z.ZodString;
+    role: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    email: string;
+    password: string;
+    name: string;
+    role: string;
+}, {
+    email: string;
+    password: string;
+    name: string;
+    role: string;
+}>;
+type CreateUserInput = z.infer<typeof createUserSchema>;
+/**
+ * `accessToken`, não `code`/`state`: o módulo verifica localmente um token já emitido pelo
+ * Keycloak (`@adatechnology/auth-keycloak`, verificação via JWKS) — a troca do `code` da
+ * authorization code flow é responsabilidade do host/frontend, antes de chegar aqui.
+ */
+declare const keycloakCallbackSchema: z.ZodObject<{
+    accessToken: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    accessToken: string;
+}, {
+    accessToken: string;
+}>;
+type KeycloakCallbackInput = z.infer<typeof keycloakCallbackSchema>;
+
+export { AUTH_PROVIDER_TYPE, type AccessTokenConfig, type AttributeMapping, type AttributeMappingRule, type AuthProviderInterface, type AuthProviderType, type BaseEvent, type ClockPort, ConfigMissingError, type ConfirmPasswordResetInput, type CreateUserInput, type DeliveryAttemptResult, EmailAlreadyExistsError, type EmailDriverPort, InvalidCredentialsError, type KeycloakCallbackInput, type KeycloakConfig, type ListUsersParams, type LocalCredentials, type LogMeta, type LoggerPort, type LoginFailedEvent, type LoginSucceededEvent, NotAuthenticatedError, type PaginatedResponse, type PasswordChangedEvent, type PasswordResetCompletedEvent, type PasswordResetConfig, type PasswordResetRequestedEvent, type ProfileUpdatedEvent, ProviderDisabledError, ProviderMisconfiguredError, type RefreshTokenConfig, type RefreshTokenStorePort, type RequestPasswordResetInput, ResetTokenAlreadyUsedError, ResetTokenExpiredError, ResetTokenInvalidError, type SendEmailParams, type SessionStatus, type TenancyConfig, USER_ERROR_CODE, USER_EVENT, type UpdateProfileInput, type UserCreatedEvent, type UserDomainEvent, UserError, type UserErrorCode, type UserEventType, type UserHooks, type UserModuleConfig, type UserModuleProviders, UserNotFoundError, type UserProfile, type UserSession, type UserUpdatedEvent, WeakPasswordError, confirmPasswordResetSchema, createUserSchema, keycloakCallbackSchema, localCredentialsSchema, requestPasswordResetSchema, updateProfileSchema };