@devorash/core 0.1.0

package/dist/utils/index.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Utility functions for Devora SDKs
+ * @module @devorash/core/utils
+ */
+import type { DevoraResponse, ImpersonationScope, LogEvent, SDKInfo } from "../types/index.js";
+/**
+ * Create a successful SDK response
+ */
+export declare function createSuccessResponse<T>(data: T): DevoraResponse<T>;
+/**
+ * Create an error SDK response
+ */
+export declare function createErrorResponse(error: string, errorCode?: string): DevoraResponse<never>;
+/**
+ * Extract URL parameters.
+ */
+export declare function extractUrlParams(url: string): Record<string, string | undefined>;
+/**
+ * Clean impersonation parameters from URL
+ * Handles both absolute and relative URLs
+ */
+export declare function cleanImpersonationParams(url: string): string;
+/**
+ * Match a path pattern against an actual path
+ * Supports :param patterns (e.g., /impersonate/:id)
+ */
+export declare function matchPath(pattern: string, path: string): {
+    match: boolean;
+    params: Record<string, string>;
+};
+/**
+ * Extract path parameters from a matched route
+ */
+export declare function extractPathParams(pattern: string, path: string): Record<string, string>;
+/**
+ * Check if a scope allows write operations
+ */
+export declare function scopeAllowsWrite(scope: ImpersonationScope): boolean;
+/**
+ * Get human-readable scope description
+ */
+export declare function getScopeDescription(scope: ImpersonationScope): string;
+/**
+ * Create a log event
+ */
+export declare function createLogEvent(type: LogEvent["type"], sessionId: string, options?: Partial<Omit<LogEvent, "type" | "sessionId" | "timestamp">>): LogEvent;
+/**
+ * Create SDK info object
+ */
+export declare function createSDKInfo(name: string, type: SDKInfo["type"], runtime?: SDKInfo["runtime"]): SDKInfo;
+/**
+ * Log levels in order of severity (lower = more verbose)
+ */
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    SILENT = 4
+}
+/**
+ * Logger configuration options
+ */
+export interface LoggerConfig {
+    /** Minimum log level to output (default: WARN in production, DEBUG in development) */
+    level?: LogLevel;
+    /** Custom prefix for log messages (default: "Devora") */
+    prefix?: string;
+    /** Enable/disable logging entirely (overrides level) */
+    enabled?: boolean;
+    /** Include timestamp in log messages */
+    includeTimestamp?: boolean;
+    /** Custom log handler (for testing or custom logging backends) */
+    handler?: LogHandler;
+}
+/**
+ * Custom log handler interface
+ */
+export interface LogHandler {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+/**
+ * Logger instance interface
+ */
+export interface Logger {
+    debug: (...args: unknown[]) => void;
+    log: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    setLevel: (level: LogLevel) => void;
+    setEnabled: (enabled: boolean) => void;
+    isEnabled: () => boolean;
+    getLevel: () => LogLevel;
+}
+/**
+ * Configure the global logger settings.
+ * Call this once at your application's entry point.
+ *
+ * @example
+ * ```typescript
+ * import { configureLogger, LogLevel } from "@devorash/core"
+ *
+ * // Enable verbose logging in development
+ * configureLogger({
+ *   level: LogLevel.DEBUG,
+ *   enabled: true,
+ *   includeTimestamp: true,
+ * })
+ *
+ * // Disable all logging in production
+ * configureLogger({
+ *   enabled: false,
+ * })
+ * ```
+ */
+export declare function configureLogger(config: Partial<LoggerConfig>): void;
+/**
+ * Get the current global logger configuration
+ */
+export declare function getLoggerConfig(): LoggerConfig;
+/**
+ * Reset logger configuration to defaults
+ */
+export declare function resetLoggerConfig(): void;
+/**
+ * Create a logger instance with the given options.
+ *
+ * @param prefix - Prefix for log messages (e.g., "Devora SDK", "Devora React")
+ * @param enabled - Override to enable/disable this specific logger
+ * @returns Logger instance
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger("MyComponent")
+ * logger.debug("Initializing...")
+ * logger.info("Ready")
+ * logger.warn("Something unexpected happened")
+ * logger.error("Failed!", error)
+ * ```
+ */
+export declare function createLogger(prefix?: string, enabled?: boolean): Logger;
+/**
+ * Validate API key format
+ */
+export declare function validateApiKeyFormat(apiKey: string): {
+    valid: boolean;
+    type?: "server" | "client";
+};
+/**
+ * Validate organization ID format
+ */
+export declare function validateOrgIdFormat(orgId: string): boolean;
+/**
+ * Get header value from headers object (handles array values and case-insensitive lookup)
+ */
+export declare function getHeaderValue(headers: Record<string, string | string[] | undefined>, key: string): string | undefined;
+/**
+ * Get HTTP status code from Devora error code
+ */
+export declare function getErrorStatusCode(errorCode?: string): number;
+/**
+ * Simple rate limiter for SDK API calls
+ */
+export declare class RateLimiter {
+    private maxRequests;
+    private windowMs;
+    private requests;
+    constructor(maxRequests?: number, windowMs?: number);
+    /**
+     * Check if a request is allowed
+     */
+    isAllowed(): boolean;
+    /**
+     * Get remaining requests in current window
+     */
+    getRemaining(): number;
+    /**
+     * Reset the rate limiter
+     */
+    reset(): void;
+    /**
+     * Wait until a request is allowed
+     * Uses iterative approach to avoid stack overflow under sustained load
+     */
+    waitForSlot(): Promise<void>;
+}
+/**
+ * Safely parse JSON
+ */
+export declare function safeJsonParse<T>(json: string, fallback: T): T;
+/**
+ * Safely stringify JSON
+ */
+export declare function safeJsonStringify(value: unknown): string;
+/**
+ * Deep freeze an object (make immutable)
+ */
+export declare function deepFreeze<T extends object>(obj: T): Readonly<T>;
+/**
+ * Create a deferred promise
+ */
+export declare function createDeferred<T>(): {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (reason?: unknown) => void;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

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