@managesome/knotr-toolkit 0.1.1 → 0.8.5

package/dist/constants/socket.js

@@ -0,0 +1,204 @@
+// ============================================
+// Socket Constants - Event names and room helpers
+// ============================================
+/**
+ * Server-to-Client Socket.IO events
+ * Events emitted from server to clients
+ */
+export const SOCKET_EVENTS = {
+    // Connection events
+    CONNECTED: 'connected',
+    DISCONNECTED: 'disconnected',
+    ERROR: 'error',
+    // Account events
+    ACCOUNT_UPDATED: 'account:updated',
+    ACCOUNT_SUSPENDED: 'account:suspended',
+    ACCOUNT_DELETED: 'account:deleted',
+    // Profile events
+    PROFILE_UPDATED: 'profile:updated',
+    PROFILE_APPROVED: 'profile:approved',
+    PROFILE_REJECTED: 'profile:rejected',
+    PROFILE_HOLD: 'profile:hold',
+    PROFILE_VIEW: 'profile:view',
+    // Match events
+    INTEREST_RECEIVED: 'interest:received',
+    INTEREST_ACCEPTED: 'interest:accepted',
+    INTEREST_DECLINED: 'interest:declined',
+    INTEREST_EXPIRED: 'interest:expired',
+    INTEREST_WITHDRAWN: 'interest:withdrawn',
+    MATCH_CREATED: 'match:created',
+    MATCH_ENDED: 'match:ended',
+    MATCH_SUCCESS: 'match:success',
+    // Chat events
+    CHAT_CREATED: 'chat:created',
+    CHAT_UPDATED: 'chat:updated',
+    CHAT_CLOSED: 'chat:closed',
+    MESSAGE_RECEIVED: 'message:received',
+    MESSAGE_READ: 'message:read',
+    MESSAGE_DELETED: 'message:deleted',
+    TYPING_START: 'typing:start',
+    TYPING_STOP: 'typing:stop',
+    // Notification events
+    NOTIFICATION_NEW: 'notification:new',
+    NOTIFICATION_READ: 'notification:read',
+    // Verification events
+    VERIFICATION_SUBMITTED: 'verification:submitted',
+    VERIFICATION_APPROVED: 'verification:approved',
+    VERIFICATION_REJECTED: 'verification:rejected',
+    // Subscription events
+    SUBSCRIPTION_CREATED: 'subscription:created',
+    SUBSCRIPTION_RENEWED: 'subscription:renewed',
+    SUBSCRIPTION_CANCELLED: 'subscription:cancelled',
+    SUBSCRIPTION_EXPIRED: 'subscription:expired',
+    // Moderation events
+    FLAG_RECEIVED: 'flag:received',
+    ACTION_TAKEN: 'action:taken',
+    WARNING_ISSUED: 'warning:issued',
+    // Company/TMC events
+    COMPANY_UPDATED: 'company:updated',
+    COMPANY_APPROVED: 'company:approved',
+    MEMBER_ADDED: 'member:added',
+    MEMBER_REMOVED: 'member:removed',
+    // Marketplace events
+    PROPOSAL_RECEIVED: 'proposal:received',
+    PROPOSAL_ACCEPTED: 'proposal:accepted',
+    PROPOSAL_DECLINED: 'proposal:declined',
+    CONTRACT_CREATED: 'contract:created',
+    CONTRACT_UPDATED: 'contract:updated',
+    MILESTONE_COMPLETED: 'milestone:completed',
+    MILESTONE_APPROVED: 'milestone:approved',
+    DISPUTE_OPENED: 'dispute:opened',
+    DISPUTE_RESOLVED: 'dispute:resolved',
+    PAYMENT_RECEIVED: 'payment:received',
+    PAYOUT_SENT: 'payout:sent',
+};
+/**
+ * Client-to-Server Socket.IO events
+ * Events sent from clients to server
+ */
+export const CLIENT_EVENTS = {
+    // Connection
+    AUTHENTICATE: 'authenticate',
+    PING: 'ping',
+    // Presence
+    JOIN_ROOM: 'room:join',
+    LEAVE_ROOM: 'room:leave',
+    SET_STATUS: 'status:set',
+    SET_PRESENCE: 'presence:set',
+    GET_PRESENCE: 'presence:get',
+    // Chat
+    SEND_MESSAGE: 'message:send',
+    MARK_READ: 'message:read',
+    START_TYPING: 'typing:start',
+    STOP_TYPING: 'typing:stop',
+    DELETE_MESSAGE: 'message:delete',
+    JOIN_CHAT: 'chat:join',
+    LEAVE_CHAT: 'chat:leave',
+    // Account
+    JOIN_ACCOUNT: 'account:join',
+    LEAVE_ACCOUNT: 'account:leave',
+    // Notifications
+    MARK_NOTIFICATION_READ: 'notification:read',
+    MARK_ALL_NOTIFICATIONS_READ: 'notification:readAll',
+};
+// ============================================
+// Room Helpers - Generate room names for Socket.IO
+// ============================================
+/**
+ * Get the room name for a specific user.
+ * Used for sending events to a specific user across all their devices.
+ *
+ * @param userId - User's account ID
+ * @returns Room name
+ *
+ * @example
+ * ```typescript
+ * const room = getUserRoom("usr_abc123");
+ * io.to(room).emit("notification:new", payload);
+ * ```
+ */
+export function getUserRoom(userId) {
+    return `user:${userId}`;
+}
+/**
+ * Get the room name for all users of an account.
+ * Useful for family accounts with multiple profiles.
+ *
+ * @param accountId - Account ID
+ * @returns Room name
+ */
+export function getAccountRoom(accountId) {
+    return `account:${accountId}`;
+}
+/**
+ * Get the room name for a chat.
+ * Both participants join this room for real-time messaging.
+ *
+ * @param chatId - Chat ID
+ * @returns Room name
+ */
+export function getChatRoom(chatId) {
+    return `chat:${chatId}`;
+}
+/**
+ * Get the room name for a match.
+ * Both matched users join for match-related events.
+ *
+ * @param matchId - Match ID
+ * @returns Room name
+ */
+export function getMatchRoom(matchId) {
+    return `match:${matchId}`;
+}
+/**
+ * Get the room name for a company.
+ * All team members join for company events.
+ *
+ * @param companyId - Company ID
+ * @returns Room name
+ */
+export function getCompanyRoom(companyId) {
+    return `company:${companyId}`;
+}
+/**
+ * Get the room name for marketplace contract.
+ * All parties join for contract updates.
+ *
+ * @param contractId - Contract ID
+ * @returns Room name
+ */
+export function getContractRoom(contractId) {
+    return `contract:${contractId}`;
+}
+/**
+ * Get the room name for admins.
+ * Used for internal dashboard real-time updates.
+ *
+ * @param scope - Admin scope (e.g., "moderation", "support", "all")
+ * @returns Room name
+ */
+export function getAdminRoom(scope = 'all') {
+    return `admin:${scope}`;
+}
+/**
+ * Get the room name for a dispute.
+ * All parties and assigned admins join.
+ *
+ * @param disputeId - Dispute ID
+ * @returns Room name
+ */
+export function getDisputeRoom(disputeId) {
+    return `dispute:${disputeId}`;
+}
+// ============================================
+// Room function aliases for backward compatibility
+// ============================================
+/** @deprecated Use getUserRoom instead */
+export const userRoom = getUserRoom;
+/** @deprecated Use getAccountRoom instead */
+export const accountRoom = getAccountRoom;
+/** @deprecated Use getChatRoom instead */
+export const chatRoom = getChatRoom;
+/** @deprecated Use getMatchRoom instead */
+export const matchRoom = getMatchRoom;
+//# sourceMappingURL=socket.js.map

package/dist/constants/socket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.js","sourceRoot":"","sources":["../../src/constants/socket.ts"],"names":[],"mappings":"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"}

package/dist/helpers/ApiError.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Standard API error codes used across all services
+ */
+export type ApiErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'CONFLICT' | 'VALIDATION_ERROR' | 'RATE_LIMIT_EXCEEDED' | 'INTERNAL_ERROR' | 'SERVICE_UNAVAILABLE' | 'TIMEOUT' | 'PAYMENT_REQUIRED' | 'UNPROCESSABLE_ENTITY';
+/**
+ * Error details for validation errors
+ */
+export interface ValidationErrorDetail {
+    field: string;
+    message: string;
+    code?: string;
+}
+/**
+ * Custom error class for API errors with status codes and error codes.
+ * Extends the native Error class with additional properties for HTTP responses.
+ *
+ * @example
+ * ```typescript
+ * throw new ApiError(404, "User not found", "NOT_FOUND");
+ *
+ * throw new ApiError(400, "Validation failed", "VALIDATION_ERROR", [
+ *   { field: "email", message: "Invalid email format" }
+ * ]);
+ * ```
+ */
+export declare class ApiError extends Error {
+    /**
+     * HTTP status code (e.g., 400, 401, 404, 500)
+     */
+    readonly statusCode: number;
+    /**
+     * Machine-readable error code for client handling
+     */
+    readonly code: ApiErrorCode;
+    /**
+     * Whether this error is operational (expected) vs programming error
+     * Operational errors are safe to expose to clients
+     */
+    readonly isOperational: boolean;
+    /**
+     * Additional error details (e.g., validation errors)
+     */
+    readonly details?: ValidationErrorDetail[];
+    /**
+     * Timestamp when the error occurred
+     */
+    readonly timestamp: Date;
+    constructor(statusCode: number, message: string, code?: ApiErrorCode, details?: ValidationErrorDetail[], isOperational?: boolean);
+    /**
+     * Convert error to JSON for API responses
+     */
+    toJSON(): {
+        success: boolean;
+        error: {
+            code: ApiErrorCode;
+            message: string;
+            details: ValidationErrorDetail[] | undefined;
+            timestamp: string;
+        };
+    };
+    static badRequest(message: string, details?: ValidationErrorDetail[]): ApiError;
+    static unauthorized(message?: string): ApiError;
+    static forbidden(message?: string): ApiError;
+    static notFound(resource?: string): ApiError;
+    static conflict(message: string): ApiError;
+    static validationError(details: ValidationErrorDetail[]): ApiError;
+    static rateLimitExceeded(message?: string): ApiError;
+    static internalError(message?: string): ApiError;
+    static serviceUnavailable(message?: string): ApiError;
+    static timeout(message?: string): ApiError;
+    static paymentRequired(message?: string): ApiError;
+    static unprocessableEntity(message: string, details?: ValidationErrorDetail[]): ApiError;
+}
+//# sourceMappingURL=ApiError.d.ts.map

package/dist/helpers/ApiError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiError.d.ts","sourceRoot":"","sources":["../../src/helpers/ApiError.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,aAAa,GACb,cAAc,GACd,WAAW,GACX,WAAW,GACX,UAAU,GACV,kBAAkB,GAClB,qBAAqB,GACrB,gBAAgB,GAChB,qBAAqB,GACrB,SAAS,GACT,kBAAkB,GAClB,sBAAsB,CAAC;AAE3B;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC;;OAEG;IACH,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC;;OAEG;IACH,SAAgB,IAAI,EAAE,YAAY,CAAC;IAEnC;;;OAGG;IACH,SAAgB,aAAa,EAAE,OAAO,CAAC;IAEvC;;OAEG;IACH,SAAgB,OAAO,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAElD;;OAEG;IACH,SAAgB,SAAS,EAAE,IAAI,CAAC;gBAG9B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,YAA+B,EACrC,OAAO,CAAC,EAAE,qBAAqB,EAAE,EACjC,aAAa,GAAE,OAAc;IAgB/B;;OAEG;IACH,MAAM;;;;;;;;;IAgBN,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,EAAE,GAAG,QAAQ;IAI/E,MAAM,CAAC,YAAY,CAAC,OAAO,GAAE,MAAuB,GAAG,QAAQ;IAI/D,MAAM,CAAC,SAAS,CAAC,OAAO,GAAE,MAAoB,GAAG,QAAQ;IAIzD,MAAM,CAAC,QAAQ,CAAC,QAAQ,GAAE,MAAmB,GAAG,QAAQ;IAIxD,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ;IAI1C,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,qBAAqB,EAAE,GAAG,QAAQ;IAIlE,MAAM,CAAC,iBAAiB,CAAC,OAAO,GAAE,MAA8B,GAAG,QAAQ;IAI3E,MAAM,CAAC,aAAa,CAAC,OAAO,GAAE,MAAgC,GAAG,QAAQ;IAIzE,MAAM,CAAC,kBAAkB,CAAC,OAAO,GAAE,MAA0C,GAAG,QAAQ;IAIxF,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,MAA0B,GAAG,QAAQ;IAI7D,MAAM,CAAC,eAAe,CAAC,OAAO,GAAE,MAA2B,GAAG,QAAQ;IAItE,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,EAAE,GAAG,QAAQ;CAGzF"}

package/dist/helpers/ApiError.js

@@ -0,0 +1,105 @@
+// ============================================
+// ApiError - Custom error class for API errors
+// ============================================
+/**
+ * Custom error class for API errors with status codes and error codes.
+ * Extends the native Error class with additional properties for HTTP responses.
+ *
+ * @example
+ * ```typescript
+ * throw new ApiError(404, "User not found", "NOT_FOUND");
+ *
+ * throw new ApiError(400, "Validation failed", "VALIDATION_ERROR", [
+ *   { field: "email", message: "Invalid email format" }
+ * ]);
+ * ```
+ */
+export class ApiError extends Error {
+    /**
+     * HTTP status code (e.g., 400, 401, 404, 500)
+     */
+    statusCode;
+    /**
+     * Machine-readable error code for client handling
+     */
+    code;
+    /**
+     * Whether this error is operational (expected) vs programming error
+     * Operational errors are safe to expose to clients
+     */
+    isOperational;
+    /**
+     * Additional error details (e.g., validation errors)
+     */
+    details;
+    /**
+     * Timestamp when the error occurred
+     */
+    timestamp;
+    constructor(statusCode, message, code = 'INTERNAL_ERROR', details, isOperational = true) {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+        this.isOperational = isOperational;
+        this.details = details;
+        this.timestamp = new Date();
+        // Maintains proper stack trace for where error was thrown
+        Error.captureStackTrace(this, this.constructor);
+        // Set the prototype explicitly for instanceof checks
+        Object.setPrototypeOf(this, ApiError.prototype);
+    }
+    /**
+     * Convert error to JSON for API responses
+     */
+    toJSON() {
+        return {
+            success: false,
+            error: {
+                code: this.code,
+                message: this.message,
+                details: this.details,
+                timestamp: this.timestamp.toISOString(),
+            },
+        };
+    }
+    // ============================================
+    // Static factory methods for common errors
+    // ============================================
+    static badRequest(message, details) {
+        return new ApiError(400, message, 'BAD_REQUEST', details);
+    }
+    static unauthorized(message = 'Unauthorized') {
+        return new ApiError(401, message, 'UNAUTHORIZED');
+    }
+    static forbidden(message = 'Forbidden') {
+        return new ApiError(403, message, 'FORBIDDEN');
+    }
+    static notFound(resource = 'Resource') {
+        return new ApiError(404, `${resource} not found`, 'NOT_FOUND');
+    }
+    static conflict(message) {
+        return new ApiError(409, message, 'CONFLICT');
+    }
+    static validationError(details) {
+        return new ApiError(400, 'Validation failed', 'VALIDATION_ERROR', details);
+    }
+    static rateLimitExceeded(message = 'Rate limit exceeded') {
+        return new ApiError(429, message, 'RATE_LIMIT_EXCEEDED');
+    }
+    static internalError(message = 'Internal server error') {
+        return new ApiError(500, message, 'INTERNAL_ERROR', undefined, false);
+    }
+    static serviceUnavailable(message = 'Service temporarily unavailable') {
+        return new ApiError(503, message, 'SERVICE_UNAVAILABLE');
+    }
+    static timeout(message = 'Request timeout') {
+        return new ApiError(504, message, 'TIMEOUT');
+    }
+    static paymentRequired(message = 'Payment required') {
+        return new ApiError(402, message, 'PAYMENT_REQUIRED');
+    }
+    static unprocessableEntity(message, details) {
+        return new ApiError(422, message, 'UNPROCESSABLE_ENTITY', details);
+    }
+}
+//# sourceMappingURL=ApiError.js.map

package/dist/helpers/ApiError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiError.js","sourceRoot":"","sources":["../../src/helpers/ApiError.ts"],"names":[],"mappings":"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"}

package/dist/helpers/asyncHandler.d.ts

@@ -0,0 +1,42 @@
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
+/**
+ * Async handler function type
+ */
+type AsyncRequestHandler = (req: Request, res: Response, next: NextFunction) => Promise<unknown>;
+/**
+ * Wraps an async Express route handler to automatically catch errors
+ * and pass them to the next() error handler.
+ *
+ * This eliminates the need for try-catch blocks in every route handler.
+ *
+ * @example
+ * ```typescript
+ * router.get('/users/:id', asyncHandler(async (req, res) => {
+ *   const user = await User.findById(req.params.id);
+ *   if (!user) throw ApiError.notFound('User');
+ *   res.json(user);
+ * }));
+ * ```
+ *
+ * @param fn - Async function to wrap
+ * @returns Express RequestHandler that catches errors
+ */
+export declare function asyncHandler(fn: AsyncRequestHandler): RequestHandler;
+/**
+ * Type-safe async handler with typed request body/params/query
+ *
+ * @example
+ * ```typescript
+ * interface CreateUserBody { name: string; email: string; }
+ *
+ * router.post('/users', typedAsyncHandler<{}, CreateUserBody>(async (req, res) => {
+ *   const { name, email } = req.body;
+ *   // TypeScript knows body has name and email
+ *   const user = await User.create({ name, email });
+ *   res.json(user);
+ * }));
+ * ```
+ */
+export declare function typedAsyncHandler<TParams = Record<string, string>, TBody = unknown, TQuery = Record<string, string>>(fn: (req: Request<TParams, unknown, TBody, TQuery>, res: Response, next: NextFunction) => Promise<unknown>): RequestHandler<TParams, unknown, TBody, TQuery>;
+export {};
+//# sourceMappingURL=asyncHandler.d.ts.map

package/dist/helpers/asyncHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asyncHandler.d.ts","sourceRoot":"","sources":["../../src/helpers/asyncHandler.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE/E;;GAEG;AACH,KAAK,mBAAmB,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEjG;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,mBAAmB,GAAG,cAAc,CAIpE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClH,EAAE,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,GACzG,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,CAIjD"}

package/dist/helpers/asyncHandler.js

@@ -0,0 +1,47 @@
+// ============================================
+// asyncHandler - Express async wrapper
+// ============================================
+/**
+ * Wraps an async Express route handler to automatically catch errors
+ * and pass them to the next() error handler.
+ *
+ * This eliminates the need for try-catch blocks in every route handler.
+ *
+ * @example
+ * ```typescript
+ * router.get('/users/:id', asyncHandler(async (req, res) => {
+ *   const user = await User.findById(req.params.id);
+ *   if (!user) throw ApiError.notFound('User');
+ *   res.json(user);
+ * }));
+ * ```
+ *
+ * @param fn - Async function to wrap
+ * @returns Express RequestHandler that catches errors
+ */
+export function asyncHandler(fn) {
+    return (req, res, next) => {
+        Promise.resolve(fn(req, res, next)).catch(next);
+    };
+}
+/**
+ * Type-safe async handler with typed request body/params/query
+ *
+ * @example
+ * ```typescript
+ * interface CreateUserBody { name: string; email: string; }
+ *
+ * router.post('/users', typedAsyncHandler<{}, CreateUserBody>(async (req, res) => {
+ *   const { name, email } = req.body;
+ *   // TypeScript knows body has name and email
+ *   const user = await User.create({ name, email });
+ *   res.json(user);
+ * }));
+ * ```
+ */
+export function typedAsyncHandler(fn) {
+    return (req, res, next) => {
+        Promise.resolve(fn(req, res, next)).catch(next);
+    };
+}
+//# sourceMappingURL=asyncHandler.js.map

package/dist/helpers/asyncHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asyncHandler.js","sourceRoot":"","sources":["../../src/helpers/asyncHandler.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,uCAAuC;AACvC,+CAA+C;AAS/C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAAC,EAAuB;IAClD,OAAO,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAQ,EAAE;QAC/D,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClD,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAC/B,EAA0G;IAE1G,OAAO,CAAC,GAA6C,EAAE,GAAa,EAAE,IAAkB,EAAQ,EAAE;QAChG,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClD,CAAC,CAAC;AACJ,CAAC"}

package/dist/helpers/id-generator.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Generate a unique ID suitable for database primary keys.
+ * Uses nanoid with 21 characters (default) for high collision resistance.
+ *
+ * Collision probability: 1 in 10^18 after generating 1 billion IDs
+ *
+ * @param size - Length of the ID (default: 21)
+ * @returns Unique URL-safe ID
+ *
+ * @example
+ * ```typescript
+ * const userId = generateId(); // "V1StGXR8_Z5jdHi6B-myT"
+ * const shorterId = generateId(16); // "V1StGXR8_Z5jdHi6"
+ * ```
+ */
+export declare function generateId(size?: number): string;
+/**
+ * Generate a shorter, more readable ID.
+ * Uses a reduced alphabet (no ambiguous characters) for better readability.
+ *
+ * Best for: display IDs, reference numbers, shareable links
+ *
+ * @param size - Length of the ID (default: 12)
+ * @returns Short readable ID
+ *
+ * @example
+ * ```typescript
+ * const refId = generateShortId(); // "Xk9Qm2ZpNrTv"
+ * const tinyId = generateShortId(8); // "Xk9Qm2Zp"
+ * ```
+ */
+export declare function generateShortId(size?: number): string;
+/**
+ * Generate a numeric code (OTP, verification codes).
+ *
+ * @param length - Length of the code (default: 6)
+ * @returns Numeric string
+ *
+ * @example
+ * ```typescript
+ * const otp = generateNumericCode(); // "847291"
+ * const pin = generateNumericCode(4); // "8472"
+ * ```
+ */
+export declare function generateNumericCode(length?: number): string;
+/**
+ * Generate an alphanumeric code (promo codes, invite codes).
+ * Uses uppercase letters and numbers, no ambiguous characters.
+ *
+ * @param length - Length of the code (default: 8)
+ * @returns Alphanumeric string
+ *
+ * @example
+ * ```typescript
+ * const promoCode = generateAlphanumericCode(); // "XKQM2ZPN"
+ * const inviteCode = generateAlphanumericCode(6); // "XKQM2Z"
+ * ```
+ */
+export declare function generateAlphanumericCode(length?: number): string;
+/**
+ * Generate a prefixed ID for better identification.
+ *
+ * @param prefix - Prefix to add (e.g., "usr", "prf", "mtc")
+ * @param size - Length of the random part (default: 16)
+ * @returns Prefixed ID
+ *
+ * @example
+ * ```typescript
+ * const userId = generatePrefixedId("usr"); // "usr_V1StGXR8_Z5jdHi6"
+ * const profileId = generatePrefixedId("prf", 12); // "prf_V1StGXR8_Z5j"
+ * ```
+ */
+export declare function generatePrefixedId(prefix: string, size?: number): string;
+/**
+ * ID prefixes for different entity types
+ */
+export declare const ID_PREFIXES: {
+    readonly ACCOUNT: "acc";
+    readonly PROFILE: "prf";
+    readonly MATCH: "mtc";
+    readonly INTEREST: "int";
+    readonly CHAT: "cht";
+    readonly MESSAGE: "msg";
+    readonly COMPANY: "cmp";
+    readonly SUBSCRIPTION: "sub";
+    readonly PAYMENT: "pay";
+    readonly VERIFICATION: "vrf";
+    readonly FLAG: "flg";
+    readonly ADMIN: "adm";
+    readonly LISTING: "lst";
+    readonly PROPOSAL: "prp";
+    readonly CONTRACT: "ctr";
+    readonly MILESTONE: "mls";
+    readonly DISPUTE: "dsp";
+    readonly NOTIFICATION: "ntf";
+};
+export type IdPrefix = (typeof ID_PREFIXES)[keyof typeof ID_PREFIXES];
+//# sourceMappingURL=id-generator.d.ts.map

package/dist/helpers/id-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-generator.d.ts","sourceRoot":"","sources":["../../src/helpers/id-generator.ts"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAE,MAAW,GAAG,MAAM,CAEpD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,MAAW,GAAG,MAAM,CAEzD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,GAAE,MAAU,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,GAAE,MAAU,GAAG,MAAM,CAEnE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,MAAW,GAAG,MAAM,CAE5E;AAED;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;CAmBd,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC"}