@meago/core 0.2.0

package/README.md

@@ -0,0 +1,65 @@
+# @meago/core
+
+Core TypeScript dùng chung cho MeagoServer, MeagoClient và các dự án Meago tiếp theo. Package cung cấp contract ổn định cùng các primitive nền tảng, không phụ thuộc NestJS, React, TypeORM, Redis hoặc domain nghiệp vụ cụ thể.
+
+## Phạm vi
+
+- Response, error và pagination contract.
+- Auth contract dùng chung cho JWT và stateful session.
+- Result và transport-neutral error.
+- Permission helpers.
+- Clock, ID, hash và transaction ports.
+- API path và response factory.
+
+Framework adapter thuộc package hoặc layer khác. Không đưa controller, entity, guard hay React hook vào package này.
+
+## Ví dụ
+
+```ts
+import {
+  AuthMode,
+  normalizePagination,
+  ok,
+  type AuthPrincipal,
+  type Result,
+} from '@meago/core';
+
+const pagination = normalizePagination({ page: 1, limit: 200 }, { maxLimit: 100 });
+const principal: AuthPrincipal = { subjectId: 'user-id', sessionId: 'session-id' };
+const result: Result<string, Error> = ok(`${principal.subjectId}:${AuthMode.SESSION}`);
+```
+
+## Phát triển
+
+```bash
+npm install
+npm run verify
+```
+
+`verify` chạy strict type-check, build ESM/CJS/declaration, smoke test và kiểm tra nội dung tarball.
+
+## Dùng local
+
+```bash
+npm install ../MeagoLibrary
+```
+
+Consumer chỉ import từ `@meago/core`, không import `@meago/core/dist/...`.
+
+## Phát hành
+
+1. Chạy `npm run verify`.
+2. Cập nhật `CHANGELOG.md`.
+3. Tăng version theo semver.
+4. Chạy `npm publish` hoặc `npm run pub`.
+5. Nâng cùng version ở Server và Client, sau đó chạy test của cả hai repo.
+
+Package đang cấu hình `access: restricted`; registry/account deploy phải hỗ trợ scoped private package. Đổi sang `public` nếu chủ đích phát hành công khai.
+
+## Compatibility
+
+- Patch: không đổi public contract hoặc behavior.
+- Minor: thêm export hoặc field optional.
+- Major: xóa/đổi export, thêm field required hoặc đổi semantics.
+- Entity database không phải contract và không được export từ library.
+

package/dist/index.d.mts

@@ -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 };