@plyaz/types 1.3.1 → 1.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "author": "Redeemer Pace",
   "license": "ISC",
   "description": "Provides shared TypeScript types and schema utilities for validation and parsing in the @playz ecosystem.",
@@ -105,7 +105,7 @@
   "scripts": {
     "build": "pnpm clean && pnpm build:js && pnpm build:types",
     "build:js": "tsup",
-    "build:types": "tsc src/index.ts --emitDeclarationOnly --outDir dist --declaration",
+    "build:types": "tsc -p tsconfig.build.json",
     "build:watch": "tsup --watch",
     "dev": "tsup --watch",
     "lint": "eslint ./src",

package/dist/api/index.d.ts

@@ -1 +0,0 @@
-export type * from './types';

package/dist/api/types.d.ts

@@ -1,84 +0,0 @@
-/**
- * Standard structure for API responses.
- * @template Data - The main payload/data returned by the API.
- * @template Meta - Optional metadata object extending the default {@link ApiResponseMeta}.
- */
-export interface ApiResponse<Data, Meta = Record<string, string>> {
-    /**
-     * The core data returned by the API.
-     */
-    readonly data: Data;
-    /**
-     * Optional metadata object containing request-related information.
-     */
-    readonly meta?: ApiResponseMeta & Meta;
-}
-/**
- * Metadata included in API responses.
- * @description Provides useful context such as timestamps, request tracking, and API versioning.
- */
-export interface ApiResponseMeta {
-    /**
-     * ISO timestamp indicating when the response was generated.
-     */
-    readonly timestamp: string;
-    /**
-     * Semantic version or release version of the API.
-     */
-    readonly version: string;
-    /**
-     * Unique identifier for tracing the API request.
-     */
-    readonly requestId: string;
-}
-/**
- * Generic structure for paginated API responses.
- * @template Item - The type of items in the paginated result.
- */
-export interface PaginatedResponse<Item> {
-    /**
-     * The current page's list of items.
-     */
-    readonly items: readonly Item[];
-    /**
-     * Total number of items across all pages.
-     */
-    readonly totalCount: number;
-    /**
-     * Number of items per page.
-     */
-    readonly pageSize: number;
-    /**
-     * Current page number (starting from 1).
-     */
-    readonly currentPage: number;
-    /**
-     * Total number of available pages.
-     */
-    readonly totalPages: number;
-    /**
-     * Indicates whether there is a next page.
-     */
-    readonly hasNextPage: boolean;
-    /**
-     * Indicates whether there is a previous page.
-     */
-    readonly hasPreviousPage: boolean;
-}
-/**
- * Parameters used to control pagination in API requests.
- */
-export interface PaginationParameters {
-    /**
-     * Page number to retrieve (starting from 1).
-     */
-    readonly page?: number;
-    /**
-     * Maximum number of items per page.
-     */
-    readonly limit?: number;
-    /**
-     * Optional cursor string for cursor-based pagination.
-     */
-    readonly cursor?: string;
-}

package/dist/auth/enums.d.ts

@@ -1,32 +0,0 @@
-/**
- * Enum representing the different roles a user can have within the system.
- * @description Roles are used to determine access levels, permissions, and user-specific experiences.
- */
-export declare const USER_ROLE: {
-    readonly Athlete: "athlete";
-    readonly Scout: "scout";
-    readonly Agent: "agent";
-    readonly Club: "club";
-    readonly Fan: "fan";
-    readonly Admin: "admin";
-    readonly SuperAdmin: "super.admin";
-};
-/**
- * Enum representing the current status of a user account.
- * @description Statuses are used to determine login availability, visibility, and user flow.
- */
-export declare const USER_STATUS: {
-    readonly Active: "active";
-    readonly Inactive: "inactive";
-    readonly Pending: "pending";
-    readonly Suspended: "suspended";
-    readonly Banned: "banned";
-};
-/**
- * Enum representing the supported authentication providers for user login.
- * @description Auth Providers allowed such as Email, Wallet, etc.
- */
-export declare const AUTH_PROVIDER: {
-    readonly Email: "email";
-    readonly Wallet: "wallet";
-};

package/dist/auth/index.d.ts

@@ -1,3 +0,0 @@
-export * from './enums';
-export type * from './schemas';
-export type * from './types';

package/dist/auth/schemas.d.ts

@@ -1,27 +0,0 @@
-import { z } from 'zod';
-/**
- * Zod schema for validating user login credentials.
- * @description Ensures the input object contains a valid email address and a password string.
- * @example
- * ```ts
- * LoginCredentialsSchema.parse({
- *   email: "user@example.com",
- *   password: ""
- * });
- * ```
- */
-export declare const loginCredentialsSchema: z.ZodObject<{
-    email: z.ZodString;
-    password: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    email?: string;
-    password?: string;
-}, {
-    email?: string;
-    password?: string;
-}>;
-/**
- * Type inferred from {@link loginCredentialsSchema}.
- * @description Represents the shape of validated login credentials input.
- */
-export type LoginCredentialsInput = z.infer<typeof loginCredentialsSchema>;

package/dist/auth/types.d.ts

@@ -1,34 +0,0 @@
-/**
- * Represents a simplified user model.
- * @description Typically used for identification purposes within auth or session logic.
- */
-export interface User {
-    /**
-     * Universally unique identifier (UUID) for the user.
-     * @example "f47ac10b-58cc-4372-a567-0e02b2c3d479"
-     */
-    readonly uuid: string;
-}
-/**
- * AuthToken Interface.
- * @description Represents an authentication token set returned after a successful login or refresh.
- */
-export interface AuthToken {
-    /**
-     * JWT or opaque access token used for authenticating API requests.
-     */
-    readonly accessToken: string;
-    /**
-     * Token used to obtain a new access token when the current one expires.
-     */
-    readonly refreshToken: string;
-    /**
-     * ISO timestamp indicating when the access token will expire.
-     * @example "2025-06-15T12:00:00Z"
-     */
-    readonly expiresAt: string;
-    /**
-     * Token type, typically "Bearer" for OAuth2-style tokens.
-     */
-    readonly tokenType: 'Bearer';
-}

package/dist/common/index.d.ts

@@ -1,2 +0,0 @@
-export type * from './types';
-export type * from 'type-fest';

package/dist/common/types.d.ts

@@ -1,22 +0,0 @@
-/**
- * A utility type used to create branded types for stronger type safety.
- * @description Branded types allow distinguishing between primitive types that share the same shape (e.g., two different string IDs), preventing accidental mixing of values that are technically the same base type.
- * @template T - The base type (e.g., `string`, `number`).
- * @template B - The unique brand label (typically a string literal).
- * @example
- * ```ts
- * type UserId = Brand<string, "UserID">;
- * type PostId = Brand<string, "PostID">;
- *
- * function getUser(id: UserId) { ... }
- * // getUser("abc") // ❌ Type error
- * ```
- */
-export type Brand<T, B> = T & {
-    readonly _brand: B;
-};
-/**
- * Branded `string` type representing a unique identifier.
- * @description This is used to avoid mixing generic strings with semantically significant IDs in function arguments and data structures.
- */
-export type ID = Brand<string, 'ID'>;

package/dist/entities/index.d.ts

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

package/dist/errors/enums.d.ts

@@ -1,33 +0,0 @@
-/**
- * Enum representing standardized error types used across the application.
- * @description These error types help classify different categories of errors such as validation issues and system-level failures.
- */
-export declare const ERROR_TYPE: {
-    readonly ValidationError: "validation.error";
-    readonly SchemaValidationError: "validation.schema.error";
-    readonly InternalError: "system.internal.error";
-    readonly ServiceUnavailable: "system.service.unavailable";
-    readonly TimeoutError: "system.timeout";
-    readonly RateLimitExceeded: "system.rate.limit.exceeded";
-};
-/**
- * Enum representing the severity level of an error.
- * @description This allows categorization of errors by their potential impact on the system or user.
- */
-export declare const ERROR_SEVERITY: {
-    readonly Low: "low";
-    readonly Medium: "medium";
-    readonly High: "high";
-    readonly Critical: "critical";
-};
-/**
- * Enum representing the category or origin of an error.
- * @description Useful for filtering or logging errors based on their source or nature.
- */
-export declare const ERROR_CATEGORY: {
-    readonly Client: "client";
-    readonly Server: "server";
-    readonly Network: "network";
-    readonly Blockchain: "blockchain";
-    readonly Validation: "validation";
-};

package/dist/errors/index.d.ts

@@ -1,2 +0,0 @@
-export * from './enums';
-export type * from './types';

package/dist/errors/types.d.ts

@@ -1,79 +0,0 @@
-/**
- * Represents the structure of an error response returned by the application.
- * @template ErrorDetails - The type of the `errors` array, defaults to `ErrorDetailsList`.
- */
-export interface ErrorResponse<ErrorDetails = ErrorDetailsList> {
-    /**
-     * HTTP status code (e.g., 400, 404, 500).
-     */
-    readonly statusCode: number;
-    /**
-     * Application-specific error code used for programmatic handling.
-     */
-    readonly errorCode: string;
-    /**
-     * Human-readable message describing the error.
-     */
-    readonly message: string;
-    /**
-     * Array of detailed errors, typically used for validation failures.
-     */
-    readonly errors: ErrorDetails;
-    /**
-     * Optional unique identifier for tracing the request across systems.
-     */
-    readonly correlationId?: string;
-    /**
-     * ISO 8601 timestamp indicating when the error occurred.
-     */
-    readonly timestamp: string;
-}
-/**
- * Additional context information about a validation error.
- * @template ValueGiven - Type of the value that caused the error.
- * @template AllowedValues - Type of acceptable values for the field.
- * @template Constraints - Type of any validation constraints.
- */
-export interface ErrorDetailContext<ValueGiven, AllowedValues, Constraints> {
-    /**
-     * The value that was provided and caused the error.
-     */
-    readonly valueGiven?: ValueGiven;
-    /**
-     * Acceptable values for the field, if applicable.
-     */
-    readonly allowedValues?: AllowedValues;
-    /**
-     * Validation constraints that were violated (e.g., min/max, regex).
-     */
-    readonly constraints?: Constraints;
-}
-/**
- * Represents a specific validation or business logic error related to a particular field.
- * @template ValueGiven - Type of the value that caused the error.
- * @template AllowedValues - Type of acceptable values for the field.
- * @template Constraints - Type of any validation constraints.
- */
-export interface ErrorDetail<ValueGiven, AllowedValues, Constraints> {
-    /**
-     * The name of the field that caused the error (optional).
-     */
-    readonly field?: string;
-    /**
-     * Human-readable error message for this specific field or rule.
-     */
-    readonly message: string;
-    /**
-     * Specific application-defined error code for this error.
-     */
-    readonly errorCode: string;
-    /**
-     * Additional context information about the error.
-     */
-    readonly context?: ErrorDetailContext<ValueGiven, AllowedValues, Constraints>;
-}
-/**
- * Error Details Array.
- * @description A flexible list of error details that can contain string, number, or boolean values along with structured allowed values and constraints.
- */
-export type ErrorDetailsList = readonly ErrorDetail<string | number | boolean, Record<string, string>, Record<string, string>>[];

package/dist/events/enums.d.ts

@@ -1,25 +0,0 @@
-/**
- * Enum representing the types of events in the application.
- */
-export declare const EVENT_TYPE: {
-    readonly AppInit: "app.init";
-};
-/**
- * Const representing the priority levels for events.
- */
-export declare const EVENT_PRIORITY: {
-    readonly Low: "low";
-    readonly Normal: "normal";
-    readonly High: "high";
-    readonly Critical: "critical";
-};
-/**
- * Const representing the status of an event.
- */
-export declare const EVENT_STATUS: {
-    readonly Pending: "pending";
-    readonly Processing: "processing";
-    readonly Completed: "completed";
-    readonly Failed: "failed";
-    readonly Retrying: "retrying";
-};

package/dist/events/index.d.ts

@@ -1,3 +0,0 @@
-export * from './enums';
-export type * from './payload';
-export type * from './types';

package/dist/events/payload.d.ts

@@ -1,6 +0,0 @@
-/**
- * User Payloads.
- */
-export interface UserUpdatePayload {
-    readonly uuid: string;
-}

package/dist/events/types.d.ts

@@ -1,136 +0,0 @@
-import type { EVENT_PRIORITY, EVENT_STATUS, EVENT_TYPE } from './enums';
-/**
- * Event Details.
- * @description Represents a typed event published and consumed via the event bus.
- * @template T - The payload type carried by the event.
- */
-export interface Event<T> {
-    /**
-     * Unique identifier for the event instance.
-     */
-    readonly id: string;
-    /**
-     * Type of the event, used to categorize behavior.
-     */
-    readonly type: typeof EVENT_TYPE;
-    /**
-     * Topic used for event routing and subscription.
-     */
-    readonly topic: string;
-    /**
-     * ISO timestamp of when the event was created.
-     */
-    readonly timestamp: string;
-    /**
-     * Payload data associated with the event.
-     */
-    readonly payload: T;
-    /**
-     * Origin or service that published the event.
-     */
-    readonly source: string;
-    /**
-     * Optional correlation ID used for tracing distributed flows.
-     */
-    readonly correlationId?: string;
-    /**
-     * Version number of the event structure or schema.
-     */
-    readonly version: number;
-    /**
-     * Priority level of the event.
-     */
-    readonly priority: typeof EVENT_PRIORITY;
-    /**
-     * Current processing status of the event.
-     */
-    readonly status: typeof EVENT_STATUS;
-    /**
-     * Optional metadata providing contextual details about the event.
-     */
-    readonly metadata?: EventMetadata;
-}
-/**
- * Additional contextual data for an event.
- * @description This is often populated with session/user data and retry tracking.
- */
-export interface EventMetadata {
-    /**
-     * Optional user identifier associated with the event.
-     */
-    readonly userId?: string;
-    /**
-     * Optional session identifier, typically from a browser or mobile session.
-     */
-    readonly sessionId?: string;
-    /**
-     * User-agent string from the origin of the event.
-     */
-    readonly userAgent?: string;
-    /**
-     * IP address of the origin that triggered the event.
-     */
-    readonly ipAddress?: string;
-    /**
-     * Current retry attempt count for the event.
-     */
-    readonly retryCount?: number;
-    /**
-     * Maximum allowed retries for this event.
-     */
-    readonly maxRetries?: number;
-    /**
-     * Additional metadata as key-value pairs.
-     */
-    readonly [key: string]: unknown;
-}
-/**
- * Event Handler.
- * @description A handler function that processes an event of type `T`.
- * @template T - The event payload type.
- */
-export type EventHandler<T = unknown> = (event: Event<T>) => void | Promise<void>;
-/**
- * Represents a subscription to a specific topic on the event bus.
- */
-export interface Subscription {
-    /**
-     * Unique ID for the subscription.
-     */
-    readonly id: string;
-    /**
-     * Topic the handler is subscribed to.
-     */
-    readonly topic: string;
-    /**
-     * Handler function to invoke when an event is published on the topic.
-     */
-    readonly handler: EventHandler;
-    /**
-     * Function to cancel the subscription.
-     */
-    readonly unsubscribe: () => void;
-}
-/**
- * Interface for a publish-subscribe event bus system.
- * @description Allows services to publish events and listen to specific topics.
- */
-export interface EventBus {
-    /**
-     * Publishes an event to all subscribed handlers for its topic.
-     * @param event - The event object to publish.
-     */
-    readonly publish: <T>(event: Event<T>) => Promise<void>;
-    /**
-     * Subscribes a handler function to a specific topic.
-     * @param topic - The topic to subscribe to.
-     * @param handler - The function to call when events are published to the topic.
-     * @returns A `Subscription` object for managing the listener.
-     */
-    readonly subscribe: <T>(topic: string, handler: EventHandler<T>) => Subscription;
-    /**
-     * Unsubscribes a handler by its subscription ID.
-     * @param subscriptionId - The unique ID of the subscription to remove.
-     */
-    readonly unsubscribe: (subscriptionId: string) => void;
-}

package/dist/features/cache/index.d.ts

@@ -1 +0,0 @@
-export type * from './types';

package/dist/features/cache/types.d.ts

@@ -1,142 +0,0 @@
-/**
- * Cache Types and Interfaces
- *
- * Type definitions for the caching layer.
- * This will be moved to @plyaz/core when the package structure is finalized.
- *
- * @fileoverview Cache type definitions
- * @version 1.0.0
- */
-/**
- * Cache entry structure that wraps cached data with metadata.
- */
-export interface CacheEntry<T = unknown> {
-    /** The cached data */
-    data: T;
-    /** When the entry expires (timestamp in milliseconds) */
-    expiresAt: number;
-    /** When the entry was created (timestamp in milliseconds) */
-    createdAt: number;
-    /** Optional metadata for the cache entry */
-    meta?: Record<string, unknown>;
-}
-/**
- * Cache statistics for monitoring and debugging.
- */
-export interface CacheStats {
-    /** Total number of cache hits */
-    hits: number;
-    /** Total number of cache misses */
-    misses: number;
-    /** Total number of set operations */
-    sets: number;
-    /** Total number of delete operations */
-    deletes: number;
-    /** Number of entries currently in cache */
-    size: number;
-    /** Cache hit ratio (hits / (hits + misses)) */
-    hitRatio?: number;
-}
-/**
- * Configuration for cache strategies.
- */
-export interface CacheConfig {
-    /** Whether caching is enabled */
-    isEnabled: boolean;
-    /** Default TTL in seconds */
-    ttl: number;
-    /** Cache strategy to use */
-    strategy: 'memory' | 'redis';
-    /** Redis-specific configuration */
-    redisConfig?: RedisCacheConfig;
-    /** Memory cache specific configuration */
-    memoryConfig?: {
-        /** Maximum number of entries to store */
-        maxSize?: number;
-        /** Maximum number of entries to store (alias for maxSize) */
-        maxEntries?: number;
-        /** Check for expired entries every N milliseconds */
-        cleanupInterval?: number;
-    };
-}
-/**
- * Configuration for memory cache strategy.
- */
-export interface MemoryCacheConfig {
-    /** Maximum number of entries to store (default: 1000) */
-    maxSize?: number;
-    /** Maximum number of entries to store (alias for maxSize) */
-    maxEntries?: number;
-    /** Check for expired entries every N milliseconds (default: 60000) */
-    cleanupInterval?: number;
-    /** Callback when entry is evicted */
-    onEvict?: (key: string, entry: CacheEntry) => void;
-}
-/**
- * Configuration for Redis cache strategy.
- */
-export interface RedisCacheConfig {
-    /** Redis connection URL */
-    url: string;
-    /** Redis password for authentication */
-    password?: string;
-    /** Redis database number */
-    db?: number;
-    /** Key prefix for Redis keys */
-    keyPrefix?: string;
-    /** Connection timeout in milliseconds */
-    connectTimeout?: number;
-    /** Command timeout in milliseconds */
-    commandTimeout?: number;
-}
-/**
- * Cache manager statistics interface.
- */
-export interface CacheManagerStats extends CacheStats {
-}
-/**
- * Interface that all cache strategies must implement.
- */
-export interface CacheStrategy {
-    /**
-     * Stores a cache entry.
-     *
-     * @param key - Cache key
-     * @param entry - Cache entry to store
-     * @returns Promise that resolves when entry is stored
-     */
-    set<T>(key: string, entry: CacheEntry<T>): Promise<void>;
-    /**
-     * Retrieves a cache entry.
-     *
-     * @param key - Cache key
-     * @returns Promise that resolves to cache entry or null if not found
-     */
-    get<T>(key: string): Promise<CacheEntry<T> | null>;
-    /**
-     * Removes a cache entry.
-     *
-     * @param key - Cache key to remove
-     * @returns Promise that resolves when entry is removed
-     */
-    delete(key: string): Promise<void>;
-    /**
-     * Clears all cache entries.
-     *
-     * @returns Promise that resolves when cache is cleared
-     */
-    clear(): Promise<void>;
-    /**
-     * Gets cache statistics.
-     *
-     * @returns Promise that resolves to cache statistics
-     */
-    getStats(): Promise<CacheStats>;
-    /**
-     * Disposes of the cache strategy and cleans up resources.
-     * Optional method for cleanup.
-     *
-     * @returns Promise that resolves when cleanup is complete
-     */
-    dispose?(): Promise<void>;
-}

package/dist/features/feature-flag/index.d.ts

@@ -1 +0,0 @@
-export type * from './types';