@meago/core 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,417 @@
+/** URL compose từ constant — cả FE lẫn tài liệu API dùng chung một nguồn. */
+declare const API_VERSION = "/api/v1";
+declare const API_CONTROLLERS: {
+    readonly AUTH: "auth";
+    readonly USERS: "users";
+    readonly ROLES: "roles";
+    readonly STORIES: "stories";
+};
+declare const API_ACTIONS: {
+    readonly LOGIN: "login";
+    readonly REGISTER: "register";
+    readonly REFRESH: "refresh";
+    readonly LOGOUT: "logout";
+    readonly LOGOUT_ALL: "logout-all";
+    readonly ME: "me";
+};
+/**
+ * Permission string "resource:action" — nguồn chân lý duy nhất,
+ * BE dùng trong @RequirePermissions, FE dùng trong PermissionGuard/usePermission,
+ * seed script dùng để tạo bảng permissions.
+ */
+declare const PERMISSIONS: {
+    readonly USER: {
+        readonly READ: "user:read";
+        readonly MANAGE: "user:manage";
+    };
+    readonly ROLE: {
+        readonly READ: "role:read";
+        readonly MANAGE: "role:manage";
+    };
+    readonly STORY: {
+        readonly CREATE: "story:create";
+        readonly READ: "story:read";
+        readonly MANAGE: "story:manage";
+    };
+};
+
+declare const index$b_API_ACTIONS: typeof API_ACTIONS;
+declare const index$b_API_CONTROLLERS: typeof API_CONTROLLERS;
+declare const index$b_API_VERSION: typeof API_VERSION;
+declare const index$b_PERMISSIONS: typeof PERMISSIONS;
+declare namespace index$b {
+  export { index$b_API_ACTIONS as API_ACTIONS, index$b_API_CONTROLLERS as API_CONTROLLERS, index$b_API_VERSION as API_VERSION, index$b_PERMISSIONS as PERMISSIONS };
+}
+
+/** Trạng thái user — mirror EUserStatus của MeagoServer (user.entity.ts) */
+declare enum EUserStatus {
+    ACTIVE = "active",
+    BLOCKED = "blocked"
+}
+declare enum ESortDir {
+    ASC = "ASC",
+    DESC = "DESC"
+}
+
+type index$a_ESortDir = ESortDir;
+declare const index$a_ESortDir: typeof ESortDir;
+type index$a_EUserStatus = EUserStatus;
+declare const index$a_EUserStatus: typeof EUserStatus;
+declare namespace index$a {
+  export { index$a_ESortDir as ESortDir, index$a_EUserStatus as EUserStatus };
+}
+
+interface ILoginDto {
+    email: string;
+    password: string;
+}
+interface IRegisterDto extends ILoginDto {
+    displayName: string;
+}
+interface ITokenResponse {
+    accessToken: string;
+    expiresIn?: number;
+}
+/** Minimal interoperable access JWT payload. */
+interface IJwtPayload {
+    sub: string;
+    sid: string;
+    jti: string;
+    iss: string;
+    aud: string | string[];
+    iat: number;
+    exp: number;
+    email?: string;
+}
+
+type index$9_IJwtPayload = IJwtPayload;
+type index$9_ILoginDto = ILoginDto;
+type index$9_IRegisterDto = IRegisterDto;
+type index$9_ITokenResponse = ITokenResponse;
+declare namespace index$9 {
+  export type { index$9_IJwtPayload as IJwtPayload, index$9_ILoginDto as ILoginDto, index$9_IRegisterDto as IRegisterDto, index$9_ITokenResponse as ITokenResponse };
+}
+
+interface IBaseResponse<T> {
+    statusCode: number;
+    message: string;
+    data: T;
+    timestamp: string;
+}
+interface IErrorResponse<TDetails = unknown> {
+    statusCode: number;
+    error: string;
+    message: string | string[];
+    path: string;
+    timestamp: string;
+    code?: string;
+    details?: TDetails;
+}
+interface IPaginatedResult<T> {
+    items: T[];
+    totalItems: number;
+    page: number;
+    limit: number;
+    totalPages?: number;
+    hasNextPage?: boolean;
+    hasPreviousPage?: boolean;
+}
+interface IBaseQuery<TSortBy extends string = string> {
+    page?: number;
+    limit?: number;
+    sortBy?: TSortBy;
+    sortDir?: ESortDir | 'ASC' | 'DESC';
+    search?: string;
+}
+interface IBaseModel {
+    id: string;
+    version: number;
+    createdAt: string;
+    updatedAt: string | null;
+}
+interface ITrackingModel extends IBaseModel {
+    createdBy: string | null;
+    updatedBy: string | null;
+}
+
+type index$8_IBaseModel = IBaseModel;
+type index$8_IBaseQuery<TSortBy extends string = string> = IBaseQuery<TSortBy>;
+type index$8_IBaseResponse<T> = IBaseResponse<T>;
+type index$8_IErrorResponse<TDetails = unknown> = IErrorResponse<TDetails>;
+type index$8_IPaginatedResult<T> = IPaginatedResult<T>;
+type index$8_ITrackingModel = ITrackingModel;
+declare namespace index$8 {
+  export type { index$8_IBaseModel as IBaseModel, index$8_IBaseQuery as IBaseQuery, index$8_IBaseResponse as IBaseResponse, index$8_IErrorResponse as IErrorResponse, index$8_IPaginatedResult as IPaginatedResult, index$8_ITrackingModel as ITrackingModel };
+}
+
+/** User trả về từ GET /auth/me — kèm tập permission đã resolve. */
+interface ICurrentUser {
+    id: string;
+    email: string;
+    displayName: string;
+    status: EUserStatus | string;
+    permissions: string[];
+}
+interface IUser extends IBaseModel {
+    email: string;
+    displayName: string;
+    status: EUserStatus | string;
+}
+interface IPermission extends IBaseModel {
+    name: string;
+    description?: string | null;
+}
+interface IRole extends IBaseModel {
+    name: string;
+    description?: string | null;
+    permissions: IPermission[];
+}
+
+type index$7_ICurrentUser = ICurrentUser;
+type index$7_IPermission = IPermission;
+type index$7_IRole = IRole;
+type index$7_IUser = IUser;
+declare namespace index$7 {
+  export type { index$7_ICurrentUser as ICurrentUser, index$7_IPermission as IPermission, index$7_IRole as IRole, index$7_IUser as IUser };
+}
+
+interface ResponseMeta {
+    statusCode?: number;
+    message?: string;
+    timestamp?: string;
+}
+declare function createSuccessResponse<T>(data: T, meta?: ResponseMeta): IBaseResponse<T>;
+interface ErrorResponseInput<TDetails = unknown> extends Omit<ResponseMeta, 'message'> {
+    error: string;
+    message: string | string[];
+    path: string;
+    code?: string;
+    details?: TDetails;
+}
+declare function createErrorResponse<TDetails = unknown>(input: ErrorResponseInput<TDetails>): IErrorResponse<TDetails>;
+declare function joinApiPath(...parts: ReadonlyArray<string | number | null | undefined>): string;
+
+type index$6_ErrorResponseInput<TDetails = unknown> = ErrorResponseInput<TDetails>;
+type index$6_ResponseMeta = ResponseMeta;
+declare const index$6_createErrorResponse: typeof createErrorResponse;
+declare const index$6_createSuccessResponse: typeof createSuccessResponse;
+declare const index$6_joinApiPath: typeof joinApiPath;
+declare namespace index$6 {
+  export { type index$6_ErrorResponseInput as ErrorResponseInput, type index$6_ResponseMeta as ResponseMeta, index$6_createErrorResponse as createErrorResponse, index$6_createSuccessResponse as createSuccessResponse, index$6_joinApiPath as joinApiPath };
+}
+
+declare const AuthMode: {
+    readonly JWT: "jwt";
+    readonly SESSION: "session";
+};
+type AuthMode = (typeof AuthMode)[keyof typeof AuthMode];
+interface AuthPrincipal<TAttributes extends Record<string, unknown> = Record<string, unknown>> {
+    subjectId: string;
+    sessionId: string;
+    email?: string;
+    permissions?: readonly string[];
+    attributes?: Readonly<TAttributes>;
+}
+interface AuthIdentity<TAttributes extends Record<string, unknown> = Record<string, unknown>> {
+    subjectId: string;
+    email?: string;
+    attributes?: Readonly<TAttributes>;
+}
+interface AuthContext {
+    ip?: string;
+    userAgent?: string;
+    deviceId?: string;
+    deviceName?: string;
+}
+type AuthCredential = Readonly<{
+    kind: 'bearer';
+    token: string;
+}> | Readonly<{
+    kind: 'refresh';
+    token: string;
+}> | Readonly<{
+    kind: 'session';
+    sessionId: string;
+}>;
+type AuthResult = Readonly<{
+    mode: 'jwt';
+    principal: AuthPrincipal;
+    accessToken: string;
+    accessExpiresAt: Date;
+    refreshToken?: string;
+    refreshExpiresAt?: Date;
+}> | Readonly<{
+    mode: 'session';
+    principal: AuthPrincipal;
+    sessionId: string;
+    expiresAt: Date;
+}>;
+interface AuthStrategy {
+    signIn(identity: AuthIdentity, context: AuthContext): Promise<AuthResult>;
+    authenticate(credential: AuthCredential, context: AuthContext): Promise<AuthPrincipal | null>;
+    renew(credential: AuthCredential, context: AuthContext): Promise<AuthResult>;
+    signOut(credential: AuthCredential, context: AuthContext): Promise<void>;
+    revokeAll(subjectId: string): Promise<void>;
+}
+interface SessionRecord<TData extends Record<string, unknown> = Record<string, unknown>> {
+    id: string;
+    subjectId: string;
+    createdAt: Date;
+    expiresAt: Date;
+    absoluteExpiresAt: Date;
+    lastSeenAt: Date;
+    revokedAt: Date | null;
+    context?: AuthContext;
+    data?: Readonly<TData>;
+}
+interface SessionStore<TData extends Record<string, unknown> = Record<string, unknown>> {
+    create(session: SessionRecord<TData>): Promise<void>;
+    findById(id: string): Promise<SessionRecord<TData> | null>;
+    touch(id: string, lastSeenAt: Date, expiresAt: Date): Promise<boolean>;
+    rotate(currentId: string, successor: SessionRecord<TData>): Promise<boolean>;
+    revoke(id: string, revokedAt: Date): Promise<void>;
+    revokeAll(subjectId: string, revokedAt: Date): Promise<void>;
+}
+
+type index$5_AuthContext = AuthContext;
+type index$5_AuthCredential = AuthCredential;
+type index$5_AuthIdentity<TAttributes extends Record<string, unknown> = Record<string, unknown>> = AuthIdentity<TAttributes>;
+type index$5_AuthMode = AuthMode;
+type index$5_AuthPrincipal<TAttributes extends Record<string, unknown> = Record<string, unknown>> = AuthPrincipal<TAttributes>;
+type index$5_AuthResult = AuthResult;
+type index$5_AuthStrategy = AuthStrategy;
+type index$5_SessionRecord<TData extends Record<string, unknown> = Record<string, unknown>> = SessionRecord<TData>;
+type index$5_SessionStore<TData extends Record<string, unknown> = Record<string, unknown>> = SessionStore<TData>;
+declare namespace index$5 {
+  export type { index$5_AuthContext as AuthContext, index$5_AuthCredential as AuthCredential, index$5_AuthIdentity as AuthIdentity, index$5_AuthMode as AuthMode, index$5_AuthPrincipal as AuthPrincipal, index$5_AuthResult as AuthResult, index$5_AuthStrategy as AuthStrategy, index$5_SessionRecord as SessionRecord, index$5_SessionStore as SessionStore };
+}
+
+declare const CoreErrorCode: {
+    readonly VALIDATION: "VALIDATION";
+    readonly UNAUTHENTICATED: "UNAUTHENTICATED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly CONFLICT: "CONFLICT";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly UNAVAILABLE: "UNAVAILABLE";
+    readonly INTERNAL: "INTERNAL";
+};
+type CoreErrorCode = (typeof CoreErrorCode)[keyof typeof CoreErrorCode];
+interface CoreErrorOptions<TDetails = unknown> {
+    code: CoreErrorCode | (string & {});
+    message: string;
+    details?: TDetails;
+    cause?: unknown;
+}
+/** Transport-neutral error; an outer adapter maps it to HTTP or another protocol. */
+declare class CoreError<TDetails = unknown> extends Error {
+    readonly code: CoreErrorCode | (string & {});
+    readonly details?: TDetails;
+    readonly cause?: unknown;
+    constructor(options: CoreErrorOptions<TDetails>);
+}
+declare function isCoreError(error: unknown): error is CoreError;
+
+type index$4_CoreError<TDetails = unknown> = CoreError<TDetails>;
+declare const index$4_CoreError: typeof CoreError;
+type index$4_CoreErrorCode = CoreErrorCode;
+type index$4_CoreErrorOptions<TDetails = unknown> = CoreErrorOptions<TDetails>;
+declare const index$4_isCoreError: typeof isCoreError;
+declare namespace index$4 {
+  export { index$4_CoreError as CoreError, type index$4_CoreErrorCode as CoreErrorCode, type index$4_CoreErrorOptions as CoreErrorOptions, index$4_isCoreError as isCoreError };
+}
+
+interface PaginationInput {
+    page?: number;
+    limit?: number;
+}
+interface PaginationPolicy {
+    defaultPage?: number;
+    defaultLimit?: number;
+    maxLimit?: number;
+}
+interface NormalizedPagination {
+    page: number;
+    limit: number;
+}
+declare function normalizePagination(input: PaginationInput, policy?: PaginationPolicy): NormalizedPagination;
+declare function getPaginationOffset(pagination: NormalizedPagination): number;
+declare function createPaginatedResult<T>(items: T[], totalItems: number, pagination: NormalizedPagination): IPaginatedResult<T>;
+
+type index$3_NormalizedPagination = NormalizedPagination;
+type index$3_PaginationInput = PaginationInput;
+type index$3_PaginationPolicy = PaginationPolicy;
+declare const index$3_createPaginatedResult: typeof createPaginatedResult;
+declare const index$3_getPaginationOffset: typeof getPaginationOffset;
+declare const index$3_normalizePagination: typeof normalizePagination;
+declare namespace index$3 {
+  export { type index$3_NormalizedPagination as NormalizedPagination, type index$3_PaginationInput as PaginationInput, type index$3_PaginationPolicy as PaginationPolicy, index$3_createPaginatedResult as createPaginatedResult, index$3_getPaginationOffset as getPaginationOffset, index$3_normalizePagination as normalizePagination };
+}
+
+type PermissionCollection = ReadonlySet<string> | readonly string[];
+declare function hasAllPermissions(granted: PermissionCollection, required: readonly string[]): boolean;
+declare function hasAnyPermission(granted: PermissionCollection, required: readonly string[]): boolean;
+
+type index$2_PermissionCollection = PermissionCollection;
+declare const index$2_hasAllPermissions: typeof hasAllPermissions;
+declare const index$2_hasAnyPermission: typeof hasAnyPermission;
+declare namespace index$2 {
+  export { type index$2_PermissionCollection as PermissionCollection, index$2_hasAllPermissions as hasAllPermissions, index$2_hasAnyPermission as hasAnyPermission };
+}
+
+interface Clock {
+    now(): Date;
+}
+interface IdGenerator {
+    generate(): string;
+}
+interface Hasher {
+    hash(value: string): Promise<string> | string;
+    verify?(value: string, hash: string): Promise<boolean> | boolean;
+}
+interface TransactionRunner<TContext = unknown> {
+    run<T>(work: (context: TContext) => Promise<T>): Promise<T>;
+}
+declare const systemClock: Clock;
+
+type index$1_Clock = Clock;
+type index$1_Hasher = Hasher;
+type index$1_IdGenerator = IdGenerator;
+type index$1_TransactionRunner<TContext = unknown> = TransactionRunner<TContext>;
+declare const index$1_systemClock: typeof systemClock;
+declare namespace index$1 {
+  export { type index$1_Clock as Clock, type index$1_Hasher as Hasher, type index$1_IdGenerator as IdGenerator, type index$1_TransactionRunner as TransactionRunner, index$1_systemClock as systemClock };
+}
+
+type Result<T, E> = Readonly<{
+    ok: true;
+    value: T;
+}> | Readonly<{
+    ok: false;
+    error: E;
+}>;
+declare function ok<T>(value: T): Result<T, never>;
+declare function err<E>(error: E): Result<never, E>;
+declare function isOk<T, E>(result: Result<T, E>): result is Readonly<{
+    ok: true;
+    value: T;
+}>;
+declare function isErr<T, E>(result: Result<T, E>): result is Readonly<{
+    ok: false;
+    error: E;
+}>;
+declare function unwrapResult<T, E>(result: Result<T, E>): T;
+declare function mapResult<T, U, E>(result: Result<T, E>, mapper: (value: T) => U): Result<U, E>;
+
+type index_Result<T, E> = Result<T, E>;
+declare const index_err: typeof err;
+declare const index_isErr: typeof isErr;
+declare const index_isOk: typeof isOk;
+declare const index_mapResult: typeof mapResult;
+declare const index_ok: typeof ok;
+declare const index_unwrapResult: typeof unwrapResult;
+declare namespace index {
+  export { type index_Result as Result, index_err as err, index_isErr as isErr, index_isOk as isOk, index_mapResult as mapResult, index_ok as ok, index_unwrapResult as unwrapResult };
+}
+
+export { API_ACTIONS, API_CONTROLLERS, API_VERSION, type AuthContext, type AuthCredential, type AuthIdentity, AuthMode, type AuthPrincipal, type AuthResult, type AuthStrategy, type Clock, CoreError, CoreErrorCode, type CoreErrorOptions, ESortDir, EUserStatus, type ErrorResponseInput, type Hasher, type IBaseModel, type IBaseQuery, type IBaseResponse, type ICurrentUser, type IErrorResponse, type IJwtPayload, type ILoginDto, type IPaginatedResult, type IPermission, type IRegisterDto, type IRole, type ITokenResponse, type ITrackingModel, type IUser, type IdGenerator, index$6 as MeagoApi, index$5 as MeagoAuth, index$b as MeagoConstants, index$9 as MeagoDto, index$a as MeagoEnums, index$4 as MeagoErrors, index$8 as MeagoInterfacesCommon, index$7 as MeagoInterfacesModels, index$3 as MeagoPagination, index$2 as MeagoPermissions, index$1 as MeagoPorts, index as MeagoResult, type NormalizedPagination, PERMISSIONS, type PaginationInput, type PaginationPolicy, type PermissionCollection, type ResponseMeta, type Result, type SessionRecord, type SessionStore, type TransactionRunner, createErrorResponse, createPaginatedResult, createSuccessResponse, err, getPaginationOffset, hasAllPermissions, hasAnyPermission, isCoreError, isErr, isOk, joinApiPath, mapResult, normalizePagination, ok, systemClock, unwrapResult };