@product-intelligence-hub/sdk-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Product Intelligence Hub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# @product-intelligence-hub/sdk-core
+
+Core SDK internals for Product Intelligence Hub. This package provides the base implementation used by platform-specific SDKs.
+
+## Overview
+
+This package is not intended for direct use. Instead, use one of the platform-specific SDKs:
+
+- [@product-intelligence-hub/sdk-web](../sdk-web/README.md) - Browser SDK
+- [@product-intelligence-hub/sdk-react-native](../sdk-react-native/README.md) - React Native SDK
+
+## Architecture
+
+```
+sdk-core/
+├── client.ts       # PIHClient base class
+├── identity.ts     # IdentityManager - user/anonymous ID management
+├── session.ts      # SessionManager - session tracking
+├── transport.ts    # Transport - HTTP communication
+├── queue.ts        # EventQueue - batching and retry logic
+├── errors.ts       # PIHError - error handling
+├── types.ts        # TypeScript interfaces
+└── utils.ts        # Utility functions
+```
+
+## Core Components
+
+### PIHClient
+
+Base client class that platform SDKs extend:
+
+```typescript
+import { PIHClient, StorageAdapter } from "@product-intelligence-hub/sdk-core";
+
+class MyPlatformClient extends PIHClient {
+  constructor(config: PIHConfig, storage: StorageAdapter) {
+    super(config, storage);
+  }
+
+  async initialize(): Promise<void> {
+    await super.initialize();
+    // Platform-specific initialization
+  }
+}
+```
+
+### StorageAdapter
+
+Interface for platform-specific storage:
+
+```typescript
+interface StorageAdapter {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+}
+```
+
+### IdentityManager
+
+Manages user identity:
+
+- Anonymous ID generation and persistence
+- User ID tracking after identify()
+- User traits storage
+
+### SessionManager
+
+Manages session lifecycle:
+
+- Session ID generation
+- Automatic session rotation on timeout
+- Session start/end callbacks
+
+### EventQueue
+
+Handles event batching:
+
+- Configurable flush interval and batch size
+- Automatic retry with exponential backoff
+- Persistent queue storage
+
+### Transport
+
+HTTP transport layer:
+
+- Track and identify endpoints
+- Retry logic
+- Error handling
+
+## Exports
+
+```typescript
+// Types
+export type {
+  PIHConfig,
+  AutocaptureConfig,
+  TrackEvent,
+  TrackOptions,
+  IdentifyPayload,
+  TrackResponse,
+  IdentifyResponse,
+  QueuedEvent,
+  StorageAdapter,
+  TransportOptions,
+  ClientState,
+} from "./types.js";
+
+// Errors
+export { PIHError } from "./errors.js";
+export type { PIHErrorCode } from "./errors.js";
+
+// Core classes
+export { PIHClient } from "./client.js";
+export { IdentityManager } from "./identity.js";
+export { SessionManager } from "./session.js";
+export { Transport } from "./transport.js";
+export { EventQueue } from "./queue.js";
+
+// Utilities
+export {
+  generateUUID,
+  getTimestamp,
+  dateToTimestamp,
+  getBackoffDelay,
+  STORAGE_PREFIX,
+  STORAGE_KEYS,
+  DEFAULTS,
+} from "./utils.js";
+```
+
+## Extending
+
+To create a new platform SDK:
+
+1. Create a storage adapter implementing `StorageAdapter`
+2. Extend `PIHClient` with platform-specific features
+3. Override `initialize()` for platform setup
+4. Add platform-specific tracking methods
+
+## Related
+
+- [SDK Spec](/docs/06_SDK_SPEC.md) - Full SDK specification

package/dist/client.d.ts

@@ -0,0 +1,91 @@
+import type { PIHConfig, TrackEvent, TrackOptions, StorageAdapter, TransportOptions } from "./types.js";
+import { IdentityManager } from "./identity.js";
+import { SessionManager } from "./session.js";
+import { Transport } from "./transport.js";
+import { EventQueue } from "./queue.js";
+/**
+ * Base PIH client class
+ * Platform-specific SDKs extend this class
+ */
+export declare class PIHClient {
+    protected config: PIHConfig;
+    protected storage: StorageAdapter | null;
+    protected identity: IdentityManager;
+    protected session: SessionManager;
+    protected transport: Transport;
+    protected queue: EventQueue;
+    protected initialized: boolean;
+    protected tenantId: string;
+    constructor(config: PIHConfig, storage?: StorageAdapter | null);
+    /**
+     * Initialize the client (load persisted state)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Set the tenant ID
+     */
+    setTenant(tenantId: string): void;
+    /**
+     * Identify the user
+     */
+    identify(userId: string, traits?: Record<string, unknown>): Promise<void>;
+    /**
+     * Set user traits without identifying
+     */
+    setUserTraits(traits: Record<string, unknown>): Promise<void>;
+    /**
+     * Track an event
+     */
+    track(eventName: string, properties?: Record<string, unknown>, options?: TrackOptions): Promise<void>;
+    /**
+     * Flush the event queue
+     */
+    flush(options?: TransportOptions): Promise<void>;
+    /**
+     * Reset identity (logout)
+     */
+    reset(): Promise<void>;
+    /**
+     * Enable/disable debug mode
+     */
+    setDebug(enabled: boolean): void;
+    /**
+     * Get the anonymous ID
+     */
+    getAnonymousId(): string;
+    /**
+     * Get the user ID
+     */
+    getUserId(): string | null;
+    /**
+     * Get the session ID
+     */
+    getSessionId(): string | null;
+    /**
+     * Get the queue length
+     */
+    getQueueLength(): number;
+    /**
+     * Destroy the client (cleanup)
+     */
+    destroy(): void;
+    /**
+     * Internal track method that doesn't require initialization
+     * Used for session events during initialization
+     */
+    protected trackInternal(eventName: string, properties?: Record<string, unknown>): void;
+    /**
+     * Create a track event
+     */
+    protected createEvent(eventName: string, properties?: Record<string, unknown>, options?: TrackOptions): TrackEvent;
+    /**
+     * Ensure client is initialized
+     */
+    protected ensureInitialized(): Promise<void>;
+    /**
+     * Validate configuration
+     */
+    protected validateConfig(config: PIHConfig): void;
+    protected log(...args: unknown[]): void;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EACV,YAAY,EACZ,cAAc,EACd,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxC;;;GAGG;AACH,qBAAa,SAAS;IACpB,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC;IAC5B,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAAQ;IAChD,SAAS,CAAC,QAAQ,EAAE,eAAe,CAAC;IACpC,SAAS,CAAC,OAAO,EAAE,cAAc,CAAC;IAClC,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC;IAC/B,SAAS,CAAC,KAAK,EAAE,UAAU,CAAC;IAC5B,SAAS,CAAC,WAAW,UAAS;IAC9B,SAAS,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEf,MAAM,EAAE,SAAS,EAAE,OAAO,GAAE,cAAc,GAAG,IAAW;IA+DpE;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAajC;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAMjC;;OAEG;IACG,QAAQ,CACZ,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,IAAI,CAAC;IA0BhB;;OAEG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnE;;OAEG;IACG,KAAK,CACT,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,IAAI,CAAC;IAuBhB;;OAEG;IACG,KAAK,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAQhC;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;OAEG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B;;OAEG;IACH,YAAY,IAAI,MAAM,GAAG,IAAI;IAI7B;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;OAEG;IACH,OAAO,IAAI,IAAI;IAKf;;;OAGG;IACH,SAAS,CAAC,aAAa,CACrB,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,IAAI;IAQP;;OAEG;IACH,SAAS,CAAC,WAAW,CACnB,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,OAAO,CAAC,EAAE,YAAY,GACrB,UAAU;IAsBb;;OAEG;cACa,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAMlD;;OAEG;IACH,SAAS,CAAC,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAkBjD,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;CAKxC"}

package/dist/client.js

@@ -0,0 +1,278 @@
+import { PIHError } from "./errors.js";
+import { IdentityManager } from "./identity.js";
+import { SessionManager } from "./session.js";
+import { Transport } from "./transport.js";
+import { EventQueue } from "./queue.js";
+import { generateUUID, getTimestamp, dateToTimestamp, DEFAULTS } from "./utils.js";
+/**
+ * Base PIH client class
+ * Platform-specific SDKs extend this class
+ */
+export class PIHClient {
+    config;
+    storage = null;
+    identity;
+    session;
+    transport;
+    queue;
+    initialized = false;
+    tenantId;
+    constructor(config, storage = null) {
+        this.validateConfig(config);
+        this.config = {
+            debug: false,
+            flushInterval: DEFAULTS.FLUSH_INTERVAL,
+            flushAt: DEFAULTS.FLUSH_AT,
+            maxQueueSize: DEFAULTS.MAX_QUEUE_SIZE,
+            sessionTimeout: DEFAULTS.SESSION_TIMEOUT,
+            ...config,
+        };
+        this.storage = storage;
+        this.tenantId = config.tenantId ?? "";
+        // Initialize identity manager
+        this.identity = new IdentityManager(storage, this.config.debug);
+        // Initialize session manager
+        this.session = new SessionManager(storage, this.config.sessionTimeout, {
+            onSessionStart: (sessionId) => {
+                this.log("Session started:", sessionId);
+                // Track session_started event
+                this.trackInternal("session_started", { session_id: sessionId });
+            },
+            onSessionEnd: (sessionId, duration) => {
+                this.log("Session ended:", sessionId, "duration:", duration);
+                // Track session_ended event
+                this.trackInternal("session_ended", {
+                    session_id: sessionId,
+                    duration_ms: duration,
+                });
+            },
+        }, this.config.debug);
+        // Initialize transport
+        this.transport = new Transport({
+            apiUrl: this.config.apiUrl,
+            apiKey: this.config.apiKey,
+            tenantId: this.tenantId,
+            debug: this.config.debug,
+        });
+        // Initialize queue
+        this.queue = new EventQueue({
+            flushAt: this.config.flushAt,
+            flushInterval: this.config.flushInterval,
+            maxQueueSize: this.config.maxQueueSize,
+            storage,
+            transport: this.transport,
+            onError: (error, events) => {
+                this.config.onError?.(error);
+                this.log("Queue error:", error.message, "events:", events.length);
+            },
+            debug: this.config.debug,
+        });
+    }
+    /**
+     * Initialize the client (load persisted state)
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        await Promise.all([
+            this.identity.initialize(),
+            this.session.initialize(),
+            this.queue.initialize(),
+        ]);
+        this.initialized = true;
+        this.log("Client initialized");
+    }
+    /**
+     * Set the tenant ID
+     */
+    setTenant(tenantId) {
+        this.tenantId = tenantId;
+        this.transport.setTenantId(tenantId);
+        this.log("Tenant set:", tenantId);
+    }
+    /**
+     * Identify the user
+     */
+    async identify(userId, traits) {
+        await this.ensureInitialized();
+        await this.identity.setUserId(userId);
+        if (traits) {
+            await this.identity.setUserTraits(traits);
+        }
+        // Send identify call to server
+        try {
+            await this.transport.sendIdentify({
+                project_id: this.config.projectId,
+                environment: this.config.environment,
+                tenant_id: this.tenantId,
+                anonymous_id: this.identity.getAnonymousId(),
+                user_id: userId,
+                traits,
+                timestamp: getTimestamp(),
+            });
+        }
+        catch (error) {
+            const pihError = PIHError.fromUnknown(error);
+            this.config.onError?.(pihError);
+            this.log("Identify error:", pihError.message);
+        }
+    }
+    /**
+     * Set user traits without identifying
+     */
+    async setUserTraits(traits) {
+        await this.ensureInitialized();
+        await this.identity.setUserTraits(traits);
+    }
+    /**
+     * Track an event
+     */
+    async track(eventName, properties, options) {
+        await this.ensureInitialized();
+        const event = this.createEvent(eventName, properties, options);
+        // Touch session to update last activity
+        this.session.touch();
+        if (options?.immediate) {
+            // Send immediately, bypassing queue
+            try {
+                await this.transport.sendEvents([event]);
+            }
+            catch (error) {
+                const pihError = PIHError.fromUnknown(error);
+                this.config.onError?.(pihError);
+                this.log("Immediate track error:", pihError.message);
+            }
+        }
+        else {
+            // Add to queue
+            await this.queue.enqueue(event);
+        }
+    }
+    /**
+     * Flush the event queue
+     */
+    async flush(options) {
+        await this.ensureInitialized();
+        await this.queue.flush(options);
+    }
+    /**
+     * Reset identity (logout)
+     */
+    async reset() {
+        await this.ensureInitialized();
+        // End current session
+        this.session.forceEndSession();
+        // Reset identity
+        await this.identity.reset();
+        this.log("Client reset");
+    }
+    /**
+     * Enable/disable debug mode
+     */
+    setDebug(enabled) {
+        this.config.debug = enabled;
+        this.identity.setDebug(enabled);
+        this.session.setDebug(enabled);
+        this.transport.setDebug(enabled);
+        this.queue.setDebug(enabled);
+    }
+    /**
+     * Get the anonymous ID
+     */
+    getAnonymousId() {
+        return this.identity.getAnonymousId();
+    }
+    /**
+     * Get the user ID
+     */
+    getUserId() {
+        return this.identity.getUserId();
+    }
+    /**
+     * Get the session ID
+     */
+    getSessionId() {
+        return this.session.getCurrentSessionId();
+    }
+    /**
+     * Get the queue length
+     */
+    getQueueLength() {
+        return this.queue.getQueueLength();
+    }
+    /**
+     * Destroy the client (cleanup)
+     */
+    destroy() {
+        this.queue.destroy();
+        this.log("Client destroyed");
+    }
+    /**
+     * Internal track method that doesn't require initialization
+     * Used for session events during initialization
+     */
+    trackInternal(eventName, properties) {
+        const event = this.createEvent(eventName, properties);
+        // Fire and forget - don't await
+        this.queue.enqueue(event).catch((error) => {
+            this.log("Internal track error:", error);
+        });
+    }
+    /**
+     * Create a track event
+     */
+    createEvent(eventName, properties, options) {
+        const timestamp = options?.timestamp
+            ? dateToTimestamp(options.timestamp)
+            : getTimestamp();
+        return {
+            event_id: generateUUID(),
+            timestamp,
+            project_id: this.config.projectId,
+            environment: this.config.environment,
+            tenant_id: this.tenantId,
+            event_name: eventName,
+            anonymous_id: this.identity.getAnonymousId(),
+            user_id: this.identity.getUserId(),
+            session_id: this.session.getSessionId(),
+            platform: this.config.platform,
+            app_version: this.config.appVersion ?? null,
+            properties: properties ?? {},
+            user_traits: this.identity.getUserTraits(),
+        };
+    }
+    /**
+     * Ensure client is initialized
+     */
+    async ensureInitialized() {
+        if (!this.initialized) {
+            await this.initialize();
+        }
+    }
+    /**
+     * Validate configuration
+     */
+    validateConfig(config) {
+        if (!config.apiUrl) {
+            throw PIHError.invalidConfig("apiUrl is required");
+        }
+        if (!config.apiKey) {
+            throw PIHError.invalidConfig("apiKey is required");
+        }
+        if (!config.projectId) {
+            throw PIHError.invalidConfig("projectId is required");
+        }
+        if (!config.environment) {
+            throw PIHError.invalidConfig("environment is required");
+        }
+        if (!config.platform) {
+            throw PIHError.invalidConfig("platform is required");
+        }
+    }
+    log(...args) {
+        if (this.config.debug) {
+            console.log("[PIH Client]", ...args);
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Error codes for PIH SDK errors
+ */
+export type PIHErrorCode = "NETWORK_ERROR" | "INVALID_CONFIG" | "QUEUE_FULL" | "RATE_LIMITED" | "INVALID_PAYLOAD" | "STORAGE_ERROR" | "SESSION_ERROR" | "UNKNOWN_ERROR";
+/**
+ * Custom error class for PIH SDK
+ */
+export declare class PIHError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: PIHErrorCode;
+    /** Additional error details */
+    readonly details?: unknown;
+    constructor(message: string, code: PIHErrorCode, details?: unknown);
+    /**
+     * Create a network error
+     */
+    static networkError(message: string, details?: unknown): PIHError;
+    /**
+     * Create an invalid config error
+     */
+    static invalidConfig(message: string, details?: unknown): PIHError;
+    /**
+     * Create a queue full error
+     */
+    static queueFull(message: string, details?: unknown): PIHError;
+    /**
+     * Create a rate limited error
+     */
+    static rateLimited(message: string, details?: unknown): PIHError;
+    /**
+     * Create an invalid payload error
+     */
+    static invalidPayload(message: string, details?: unknown): PIHError;
+    /**
+     * Create a storage error
+     */
+    static storageError(message: string, details?: unknown): PIHError;
+    /**
+     * Create a session error
+     */
+    static sessionError(message: string, details?: unknown): PIHError;
+    /**
+     * Convert unknown error to PIHError
+     */
+    static fromUnknown(error: unknown): PIHError;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,eAAe,GACf,gBAAgB,GAChB,YAAY,GACZ,cAAc,GACd,iBAAiB,GACjB,eAAe,GACf,eAAe,GACf,eAAe,CAAC;AAEpB;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,2CAA2C;IAC3C,SAAgB,IAAI,EAAE,YAAY,CAAC;IACnC,+BAA+B;IAC/B,SAAgB,OAAO,CAAC,EAAE,OAAO,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,OAAO;IAYlE;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ;IAIjE;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ;IAIlE;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ;IAI9D;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ;IAIhE;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ;IAInE;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ;IAIjE;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ;IAIjE;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ;CAS7C"}

package/dist/errors.js

@@ -0,0 +1,74 @@
+/**
+ * Custom error class for PIH SDK
+ */
+export class PIHError extends Error {
+    /** Error code for programmatic handling */
+    code;
+    /** Additional error details */
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.name = "PIHError";
+        this.code = code;
+        this.details = details;
+        // Maintains proper stack trace for where error was thrown (V8 only)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, PIHError);
+        }
+    }
+    /**
+     * Create a network error
+     */
+    static networkError(message, details) {
+        return new PIHError(message, "NETWORK_ERROR", details);
+    }
+    /**
+     * Create an invalid config error
+     */
+    static invalidConfig(message, details) {
+        return new PIHError(message, "INVALID_CONFIG", details);
+    }
+    /**
+     * Create a queue full error
+     */
+    static queueFull(message, details) {
+        return new PIHError(message, "QUEUE_FULL", details);
+    }
+    /**
+     * Create a rate limited error
+     */
+    static rateLimited(message, details) {
+        return new PIHError(message, "RATE_LIMITED", details);
+    }
+    /**
+     * Create an invalid payload error
+     */
+    static invalidPayload(message, details) {
+        return new PIHError(message, "INVALID_PAYLOAD", details);
+    }
+    /**
+     * Create a storage error
+     */
+    static storageError(message, details) {
+        return new PIHError(message, "STORAGE_ERROR", details);
+    }
+    /**
+     * Create a session error
+     */
+    static sessionError(message, details) {
+        return new PIHError(message, "SESSION_ERROR", details);
+    }
+    /**
+     * Convert unknown error to PIHError
+     */
+    static fromUnknown(error) {
+        if (error instanceof PIHError) {
+            return error;
+        }
+        if (error instanceof Error) {
+            return new PIHError(error.message, "UNKNOWN_ERROR", error);
+        }
+        return new PIHError(String(error), "UNKNOWN_ERROR", error);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAaA;;GAEG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,2CAA2C;IAC3B,IAAI,CAAe;IACnC,+BAA+B;IACf,OAAO,CAAW;IAElC,YAAY,OAAe,EAAE,IAAkB,EAAE,OAAiB;QAChE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QAEvB,oEAAoE;QACpE,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,OAAe,EAAE,OAAiB;QACpD,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,CAAC,CAAC;IACzD,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,OAAe,EAAE,OAAiB;QACrD,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,gBAAgB,EAAE,OAAO,CAAC,CAAC;IAC1D,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,OAAe,EAAE,OAAiB;QACjD,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,OAAe,EAAE,OAAiB;QACnD,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,CAAC;IACxD,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,OAAe,EAAE,OAAiB;QACtD,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,CAAC,CAAC;IAC3D,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,OAAe,EAAE,OAAiB;QACpD,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,CAAC,CAAC;IACzD,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,OAAe,EAAE,OAAiB;QACpD,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,CAAC,CAAC;IACzD,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,KAAc;QAC/B,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,CAAC,CAAC;QAC7D,CAAC;QACD,OAAO,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,eAAe,EAAE,KAAK,CAAC,CAAC;IAC7D,CAAC;CACF"}