@plyaz/types 1.46.0 → 1.46.2

package/dist/core/frontend/types.d.ts

@@ -12,6 +12,7 @@ import type { CoreBaseDomainServiceConfig } from '../domain';
 import type { CoreBaseServiceConfig, CoreBaseMapperInstance, CoreBaseValidatorInstance } from '../domain';
 import type { CoreDomainServiceInstance, CoreObservabilityConfig, CoreServiceEntry } from '../init';
 import type { PackageErrorLike } from '../../errors';
+import type { DevtoolsConfig } from '../../devtools';
 /**
  * Base store interface for frontend services.
  *
@@ -1102,6 +1103,8 @@ export interface CorePlyazConfig {
     observability?: CoreObservabilityConfig;
     /** Enable verbose logging */
     verbose?: boolean;
+    /** DevTools configuration */
+    devtools?: DevtoolsConfig;
 }
 /**
  * Interface for services that can provide feature flags.

package/dist/core/init/index.d.ts

@@ -2,4 +2,4 @@
  * Core Init Types
  * Service registry and initialization type definitions
  */
-export type { CoreDomainServiceInstance, CoreServiceInitConfig, CoreServiceCreateOptions, CoreInitializableDomainService, CoreServiceEntry, CoreServiceRegistryConfig, CoreExtractServiceConfig, CoreExtractServiceInstance, CoreFeatureFlagInitConfig, CoreErrorHandlerInitConfig, CoreCacheConfig, CoreStorageConfig, CoreNotificationConfig, CoreObservabilityConfig, CoreStreamConfig, CoreInitOptionsBase, CoreServicesResultBase, } from './types';
+export type { CoreDomainServiceInstance, CoreServiceInitConfig, CoreServiceCreateOptions, CoreInitializableDomainService, CoreServiceEntry, CoreServiceRegistryConfig, CoreExtractServiceConfig, CoreExtractServiceInstance, CoreFeatureFlagInitConfig, CoreErrorHandlerInitConfig, CoreCacheConfig, CoreStorageConfig, CoreNotificationConfig, CoreObservabilityConfig, CoreStreamConfig, CoreInitOptionsBase, CoreServicesResultBase, CoreNestJsMiddlewareConfig, CoreNestJsRateLimitConfig, CoreNestJsValidationConfig, CoreNestJsSwaggerConfig, } from './types';

package/dist/core/init/types.d.ts

@@ -787,6 +787,142 @@ export interface CoreStreamConfig {
         maxConnections?: number;
     };
 }
+/**
+ * Rate limiting configuration for NestJS
+ */
+export interface CoreNestJsRateLimitConfig {
+    /** Time window in seconds (default: 60) */
+    ttl?: number;
+    /** Max requests per window (default: 100) */
+    limit?: number;
+    /** Skip rate limiting for certain paths */
+    skipIf?: (request: unknown) => boolean;
+}
+/**
+ * Validation pipe configuration for NestJS
+ */
+export interface CoreNestJsValidationConfig {
+    /** Strip properties not in DTO (default: true) */
+    whitelist?: boolean;
+    /** Throw on non-whitelisted properties (default: false) */
+    forbidNonWhitelisted?: boolean;
+    /** Transform payloads to DTO instances (default: true) */
+    transform?: boolean;
+    /** Disable error messages (default: false) */
+    disableErrorMessages?: boolean;
+}
+/**
+ * Swagger/OpenAPI configuration for NestJS
+ */
+export interface CoreNestJsSwaggerConfig {
+    /** Enable Swagger (default: false in production) */
+    enabled?: boolean;
+    /** Swagger path (default: '/api/docs') */
+    path?: string;
+    /** API title */
+    title?: string;
+    /** API description */
+    description?: string;
+    /** API version */
+    version?: string;
+    /** Bearer auth enabled */
+    bearerAuth?: boolean;
+}
+/**
+ * NestJS middleware and configuration options.
+ * Applied during app bootstrap via configureNestApp().
+ *
+ * @example
+ * ```typescript
+ * await Core.initialize({
+ *   nestjs: {
+ *     compression: true,
+ *     helmet: true,
+ *     rateLimit: { ttl: 60, limit: 100 },
+ *     validation: { whitelist: true, transform: true },
+ *     bodyLimit: '10mb',
+ *     timeout: 30000,
+ *     rawBody: true,
+ *     swagger: { enabled: true, path: '/api/docs' },
+ *   },
+ * });
+ * ```
+ */
+export interface CoreNestJsMiddlewareConfig {
+    /**
+     * Enable response compression (default: true in production).
+     * Uses compression middleware for gzip/brotli.
+     */
+    compression?: boolean;
+    /**
+     * Enable Helmet security headers (default: true).
+     * Adds XSS protection, content security policy, etc.
+     */
+    helmet?: boolean | Record<string, unknown>;
+    /**
+     * Rate limiting configuration.
+     * Set to false to disable, true for defaults, or object for custom config.
+     */
+    rateLimit?: boolean | CoreNestJsRateLimitConfig;
+    /**
+     * Global validation pipe configuration.
+     * Enables class-validator for DTO validation.
+     */
+    validation?: boolean | CoreNestJsValidationConfig;
+    /**
+     * Maximum request body size (default: '10mb').
+     * Accepts string like '1mb', '10kb', or number in bytes.
+     */
+    bodyLimit?: string | number;
+    /**
+     * Request timeout in milliseconds (default: 30000).
+     * Set to 0 to disable timeout.
+     */
+    timeout?: number;
+    /**
+     * Enable raw body parsing for webhooks (default: false).
+     * Required for signature verification (Stripe, GitHub, etc.).
+     * When enabled, raw body is available on request.rawBody.
+     */
+    rawBody?: boolean | {
+        paths?: string[];
+    };
+    /**
+     * Swagger/OpenAPI documentation configuration.
+     * Set to false to disable, true for defaults, or object for custom config.
+     */
+    swagger?: boolean | CoreNestJsSwaggerConfig;
+    /**
+     * CORS configuration override.
+     * By default, uses app-level CORS. Set here to override.
+     */
+    cors?: boolean | {
+        origin?: string | string[] | boolean;
+        credentials?: boolean;
+        methods?: string[];
+        allowedHeaders?: string[];
+    };
+    /**
+     * Global prefix for all routes (default: 'api').
+     * Set to false to disable prefix.
+     */
+    globalPrefix?: string | false;
+    /**
+     * Routes to exclude from global prefix.
+     * @example ['health', 'metrics', 'webhooks/*']
+     */
+    excludeFromPrefix?: string[];
+    /**
+     * Enable graceful shutdown handling (default: true).
+     * Registers SIGTERM/SIGINT handlers for clean shutdown.
+     */
+    gracefulShutdown?: boolean;
+    /**
+     * Shutdown timeout in milliseconds (default: 10000).
+     * Time to wait for graceful shutdown before force exit.
+     */
+    shutdownTimeout?: number;
+}
 /**
  * Base core initialization options
  * Extended by @plyaz/core's CoreInitOptions with specific types
@@ -848,6 +984,12 @@ export interface CoreInitOptionsBase<TDb = unknown, TApi = unknown, TStorage = u
     featureFlags?: CoreFeatureFlagInitConfig;
     /** Domain services to auto-initialize */
     services?: CoreServiceEntry[];
+    /**
+     * NestJS-specific middleware and configuration.
+     * Applied during app bootstrap via configureNestApp().
+     * Only used when runtime is 'nestjs'.
+     */
+    nestjs?: CoreNestJsMiddlewareConfig;
 }
 /**
  * Core services result from initialization

package/dist/devtools/index.cjs

@@ -0,0 +1,4 @@
+'use strict';
+
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/devtools/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}

package/dist/devtools/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * DevTools Types Module
+ *
+ * @module devtools
+ */
+export type * from './types';

package/dist/devtools/index.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/devtools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/devtools/types.d.ts

@@ -0,0 +1,238 @@
+/**
+ * DevTools Types
+ *
+ * Type definitions for PlyazDevtools configuration and state.
+ * These types are used by @plyaz/core/devtools.
+ *
+ * @module devtools
+ */
+import type { ComponentType, ReactNode } from 'react';
+import type { CorePlyazConfig } from '../core';
+/**
+ * Available devtools tab identifiers
+ */
+export type DevtoolsTab = 'stores' | 'actions' | 'api' | 'streaming' | 'security' | 'compliance' | 'accessibility' | 'services' | 'errors' | 'events' | 'uploads' | 'observability' | 'config' | 'storage' | 'playground' | 'runner' | 'flags' | 'mocking' | 'explorer' | 'ssr' | 'routes' | 'i18n' | 'react' | 'console' | 'shortcuts';
+/**
+ * Tab group configuration
+ */
+export interface TabGroupConfig {
+    /** Group identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Short name for compact displays */
+    shortName: string;
+    /** Icon (emoji or component) */
+    icon: string;
+    /** Color theme for the group */
+    color: string;
+    /** Tabs in this group */
+    tabs: DevtoolsTab[];
+    /** Description for tooltips */
+    description?: string;
+}
+/**
+ * Tab plugin definition for custom tabs
+ */
+export interface TabPlugin {
+    /** Unique identifier for the tab */
+    id: string;
+    /** Tab metadata */
+    metadata: {
+        /** Full display name */
+        name: string;
+        /** Short name for compact displays */
+        shortName: string;
+        /** Icon (emoji or component) */
+        icon: ReactNode;
+        /** Group to place this tab in */
+        group?: string;
+        /** Keywords for search */
+        keywords?: string[];
+        /** Description for tooltips/search */
+        description?: string;
+    };
+    /** Tab component */
+    component: ComponentType;
+    /** Optional lifecycle hooks */
+    onMount?: () => void;
+    onUnmount?: () => void;
+    /** Required adapters for this tab to work */
+    requiredAdapters?: string[];
+}
+/**
+ * Keyboard shortcut configuration
+ */
+export interface ShortcutConfig {
+    /** Shortcut key combination (e.g., 'Ctrl+K') */
+    key: string;
+    /** Action identifier */
+    action: string;
+    /** Description for help */
+    description?: string;
+    /** Whether this shortcut is enabled */
+    enabled?: boolean;
+}
+/**
+ * Storage adapter interface for custom storage implementations
+ */
+export interface DevtoolsStorageAdapter {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Core adapter configuration for @plyaz/core integration
+ */
+export interface CoreAdapterConfig {
+    /** Hook to check if core is ready */
+    useReady?: () => boolean;
+    /** Hook to get core context */
+    useContext?: () => unknown;
+    /** Hook to get event manager */
+    useEvents?: () => unknown;
+}
+/**
+ * Store adapter configuration for @plyaz/store integration
+ */
+export interface StoreAdapterConfig {
+    /** Hook to get root store */
+    useRootStore?: () => unknown;
+    /** Hook to get errors */
+    useErrors?: () => unknown[];
+    /** Hook to check stream connection */
+    useStreamConnected?: () => boolean;
+    /** Hook to get stream messages */
+    useStreamMessages?: () => unknown[];
+    /** Custom store hooks */
+    [key: string]: (() => unknown) | undefined;
+}
+/**
+ * App config adapter for accessing application configuration
+ */
+export interface ConfigAdapterConfig {
+    /** Get frontend configuration */
+    getFrontendConfig?: () => unknown;
+    /** Get environment variables */
+    getEnv?: () => Record<string, unknown>;
+    /** Get feature flags */
+    getFeatureFlags?: () => Record<string, boolean>;
+}
+/**
+ * Package export configuration for ExplorerTab
+ */
+export interface PackageExport {
+    name: string;
+    displayName: string;
+    color: string;
+    exports: Record<string, unknown>;
+}
+/**
+ * App-specific configuration passed to devtools
+ * This allows devtools to work generically across different Plyaz apps
+ *
+ * @template TConfig - The frontend config type (defaults to CorePlyazConfig)
+ */
+export interface DevtoolsAppConfig<TConfig = CorePlyazConfig> {
+    /** Frontend configuration object (from app's plyaz.frontend.ts) */
+    frontendConfig?: TConfig;
+    /** Package exports for ExplorerTab */
+    packageExports?: PackageExport[];
+}
+/**
+ * Main DevTools configuration interface
+ */
+export interface DevtoolsConfig {
+    /** Whether devtools is enabled */
+    enabled?: boolean;
+    /** Panel position */
+    position?: 'bottom' | 'left' | 'right';
+    /** Default panel height (in pixels) */
+    defaultHeight?: number;
+    /** Default panel width (in pixels, for left/right positions) */
+    defaultWidth?: number;
+    /** Color theme */
+    theme?: 'dark' | 'light';
+    /** Tab configuration */
+    tabs?: {
+        /** Which tabs to enable (use ['*'] for all) */
+        enabled?: string[];
+        /** Which tabs to explicitly disable */
+        disabled?: string[];
+        /** Custom tab groups configuration */
+        groups?: TabGroupConfig[];
+        /** Default pinned/favorite tabs */
+        favorites?: string[];
+        /** Custom tabs to register */
+        custom?: TabPlugin[];
+        /** Default active tab */
+        defaultTab?: DevtoolsTab;
+    };
+    /** Storage configuration */
+    storage?: {
+        /** Storage adapter type or custom implementation */
+        adapter?: 'indexeddb' | 'memory' | DevtoolsStorageAdapter;
+        /** How many days to retain data */
+        retentionDays?: number;
+        /** Maximum items to store per category */
+        maxItems?: number;
+    };
+    /** Keyboard shortcuts configuration */
+    shortcuts?: {
+        /** Toggle devtools shortcut */
+        toggle?: string;
+        /** Open search shortcut */
+        search?: string;
+        /** Close shortcut */
+        close?: string;
+        /** Custom shortcuts */
+        custom?: ShortcutConfig[];
+    };
+    /** Adapter configuration for external dependencies */
+    adapters?: {
+        core?: CoreAdapterConfig;
+        store?: StoreAdapterConfig;
+        config?: ConfigAdapterConfig;
+    };
+    /** App-specific configuration (env, frontendConfig, etc.) */
+    appConfig?: DevtoolsAppConfig<CorePlyazConfig>;
+    /** Security configuration */
+    security?: {
+        /** Read-only mode (disable mutations) */
+        readOnly?: boolean;
+        /** Keys to mask in display (e.g., tokens, passwords) */
+        sensitiveKeys?: string[];
+    };
+    /** Event hooks */
+    hooks?: {
+        onOpen?: () => void;
+        onClose?: () => void;
+        onTabChange?: (tab: string) => void;
+        onError?: (error: Error) => void;
+    };
+}
+/**
+ * Date range filter for data queries
+ */
+export interface DateRange {
+    start: number;
+    end: number;
+    label: string;
+}
+/**
+ * Devtools settings persisted to storage
+ */
+export interface DevtoolsSettings {
+    isOpen: boolean;
+    activeTab: DevtoolsTab;
+    position: 'bottom' | 'left' | 'right';
+    height: number;
+    width: number;
+    theme: 'dark' | 'light';
+    maxMessages: number;
+    hideHeartbeats: boolean;
+    pinnedTabs: DevtoolsTab[];
+    recentTabs: DevtoolsTab[];
+    collapsedGroups: Record<string, boolean>;
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './auth';
 export type * from './common';
 export * from './core';
+export type * from './devtools';
 export type * from './store';
 export type * from './entities';
 export * from './errors';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.46.0",
+  "version": "1.46.2",
   "author": "Redeemer Pace",
   "license": "ISC",
   "description": "Provides shared TypeScript types and schema utilities for validation and parsing in the @playz ecosystem.",
@@ -205,6 +205,11 @@
       "import": "./dist/db/index.js",
       "require": "./dist/db/index.cjs"
     },
+    "./devtools": {
+      "types": "./dist/devtools/index.d.ts",
+      "import": "./dist/devtools/index.js",
+      "require": "./dist/devtools/index.cjs"
+    },
     "./user": {
       "types": "./dist/user/index.d.ts",
       "import": "./dist/user/index.js",