shogun-core 5.2.0 → 5.2.1

package/dist/types/gundb/errors.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Error classes for Gun and Auth
+ */
+/**
+ * Base error for Gun
+ */
+export declare class GunError extends Error {
+    constructor(message: string);
+}
+/**
+ * Generic authentication error
+ */
+export declare class AuthError extends GunError {
+    constructor(message: string);
+}
+/**
+ * Invalid credentials error
+ */
+export declare class InvalidCredentials extends AuthError {
+    constructor(message?: string);
+}
+/**
+ * User already exists error
+ */
+export declare class UserExists extends AuthError {
+    constructor(message?: string);
+}
+/**
+ * Timeout error
+ */
+export declare class TimeoutError extends GunError {
+    constructor(message?: string);
+}
+/**
+ * Multiple authentication error
+ */
+export declare class MultipleAuthError extends AuthError {
+    constructor(message?: string);
+}
+/** Base error related to the network. */
+export declare class NetworkError extends GunError {
+}

package/dist/types/gundb/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./db";
+export * from "./types";
+export * from "./api";

package/dist/types/gundb/rxjs.d.ts

@@ -0,0 +1,110 @@
+import { Observable } from "rxjs";
+import { IGunInstance, IGunUserInstance } from "gun";
+/**
+ * RxJS Integration for GunDB
+ * Provides reactive programming capabilities for GunDB data
+ */
+export declare class RxJS {
+    private readonly gun;
+    private readonly user;
+    /**
+     * Initialize GunRxJS with a GunDB instance
+     * @param gun - GunDB instance
+     */
+    constructor(gun: IGunInstance<any>);
+    /**
+     * Get the current user
+     * @returns The current user
+     */
+    getUser(): IGunUserInstance<any>;
+    /**
+     * Get the current user's public key
+     * @returns The current user's public key
+     */
+    getUserPub(): string | undefined;
+    /**
+     * Observe a Gun node for changes
+     * @param path - Path to observe (can be a string or a Gun chain)
+     * @returns Observable that emits whenever the node changes
+     */
+    observe<T>(path: string | any): Observable<T>;
+    /**
+     * Match data based on Gun's '.map()' and convert to Observable
+     * @param path - Path to the collection
+     * @param matchFn - Optional function to filter results
+     * @returns Observable array of matched items
+     */
+    match<T>(path: string | any, matchFn?: (data: any) => boolean): Observable<T[]>;
+    /**
+     * Put data and return an Observable
+     * @param path - Path where to put the data
+     * @param data - Data to put
+     * @returns Observable that completes when the put is acknowledged
+     */
+    put<T>(path: string | any, data?: T): Observable<T>;
+    /**
+     * Backward-compatible overload that accepts optional callback like tests expect
+     */
+    putCompat<T extends Partial<any> & Record<string, any>>(data: T, callback?: (ack: any) => void): Observable<T>;
+    /**
+     * Set data on a node and return an Observable
+     * @param path - Path to the collection
+     * @param data - Data to set
+     * @returns Observable that completes when the set is acknowledged
+     */
+    set<T>(path: string | any, data?: T): Observable<T>;
+    setCompat<T>(data: T, callback?: (ack: any) => void): Observable<T>;
+    /**
+     * Get data once and return as Observable
+     * @param path - Path to get data from
+     * @returns Observable that emits the data once
+     */
+    once<T>(path?: string | any): Observable<T>;
+    /**
+     * Compute derived values from gun data
+     * @param sources - Array of paths or observables to compute from
+     * @param computeFn - Function that computes a new value from the sources
+     * @returns Observable of computed values
+     */
+    compute<T, R>(sources: Array<string | Observable<any>>, computeFn: (...values: T[]) => R): Observable<R>;
+    /**
+     * User put data and return an Observable (for authenticated users)
+     * @param path - Path where to put the data
+     * @param data - Data to put
+     * @returns Observable that completes when the put is acknowledged
+     */
+    userPut<T extends Partial<any> & Record<string, any>>(dataOrPath: string | T, maybeData?: T, callback?: (ack: any) => void): Observable<T>;
+    /**
+     * User set data and return an Observable (for authenticated users)
+     * @param dataOrPath - Data to set or path where to set the data
+     * @param maybeData - Data to set (if first parameter is path)
+     * @param callback - Optional callback function
+     * @returns Observable that completes when the set is acknowledged
+     */
+    userSet<T extends Partial<any> & Record<string, any>>(dataOrPath: string | T, maybeData?: T, callback?: (ack: any) => void): Observable<T>;
+    /**
+     * User once data and return an Observable (for authenticated users)
+     * @param path - Optional path to get data from
+     * @param callback - Optional callback function
+     * @returns Observable that emits the data once
+     */
+    userOnce<T>(path?: string, callback?: (ack: any) => void): Observable<T>;
+    /**
+     * Get user data
+     * @param path - Path to get data from
+     * @returns Observable that emits the data once
+     */
+    userGet<T>(path: string): Observable<T>;
+    /**
+     * Observe user data
+     * @param path - Path to observe in user space
+     * @returns Observable that emits whenever the user data changes
+     */
+    observeUser<T>(path?: string): Observable<T>;
+    /**
+     * Remove Gun metadata from an object
+     * @param obj - Object to clean
+     * @returns Cleaned object without Gun metadata
+     */
+    private removeGunMeta;
+}

package/dist/types/gundb/types.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Type definitions for GunDB to replace 'any' usage
+ */
+export type GunType = (config?: any) => IGunInstance<any>;
+export type SEAType = any;
+export type GunUser = IGunUserInstance<any>;
+export type UserInfo = {
+    pub: string;
+    epub?: string;
+    alias?: string;
+    user?: GunUser;
+    timestamp?: number;
+};
+export type AuthCallback = (user: GunUser) => void;
+export type AuthResult = {
+    success: boolean;
+    userPub?: string;
+    error?: string;
+    ack?: any;
+    sea?: {
+        pub: string;
+        priv: string;
+        epub: string;
+        epriv: string;
+    };
+};
+export type GunData = any;
+export type GunNode = any;
+export type GunCallback = any;
+export type GunDataCallback = any;
+export type GunMapCallback = any;
+export interface UsernameLookupResult {
+    pub?: string;
+    userPub?: string;
+    username?: string;
+    source: string;
+    immutable: boolean;
+    hash?: string;
+    [key: string]: any;
+}
+export interface UserMetadata {
+    username: string;
+    pub: string;
+    createdAt: number;
+    lastLogin: number;
+}
+export interface MappingData {
+    username: string;
+    userPub: string;
+    createdAt: number;
+}
+export interface SecurityData {
+    questions: string;
+    hint: string;
+}
+export interface FrozenData {
+    data: any;
+    timestamp: number;
+    description: string;
+    metadata: Record<string, any>;
+}
+export interface FrozenSpaceOptions {
+    namespace?: string;
+    path?: string;
+    description?: string;
+    metadata?: Record<string, any>;
+}
+export interface ConnectivityTestResult {
+    peers: {
+        [peer: string]: {
+            connected: boolean;
+            status: string;
+        };
+    };
+    gunInstance: boolean;
+    userInstance: boolean;
+    canWrite: boolean;
+    canRead: boolean;
+    testWriteResult?: any;
+    testReadResult?: any;
+}
+export interface LoginResult {
+    success: boolean;
+    userPub?: string;
+    username?: string;
+    error?: string;
+}
+export interface SignupResult {
+    success: boolean;
+    userPub?: string;
+    username?: string;
+    message?: string;
+    error?: string;
+    sea?: {
+        pub: string;
+        priv: string;
+        epub: string;
+        epriv: string;
+    };
+}
+export interface PostAuthResult {
+    success: boolean;
+    userPub?: string;
+    username?: string;
+    error?: string;
+}
+export interface PasswordHintResult {
+    success: boolean;
+    hint?: string;
+    error?: string;
+}
+export interface P256Keys {
+    pub: string;
+    priv: string;
+    epub: string;
+    epriv: string;
+}
+export interface Secp256k1Keys {
+    pub: string;
+    priv: string;
+    address: string;
+}
+export interface DeriveResult {
+    p256?: P256Keys;
+    secp256k1Bitcoin?: Secp256k1Keys;
+    secp256k1Ethereum?: Secp256k1Keys;
+}
+export interface FrozenSpaceResult {
+    hash: string;
+    fullPath: string;
+    data: FrozenData;
+}
+export interface VerificationResult {
+    verified: boolean;
+    frozenData?: FrozenData;
+    error?: string;
+}
+export interface SessionRestorationResult {
+    success: boolean;
+    userPub?: string;
+    error?: string;
+}
+export interface UserExistenceResult {
+    exists: boolean;
+    userPub?: string;
+    error?: string;
+}
+export interface UserCreationResult {
+    success: boolean;
+    pub?: string;
+    error?: string;
+}
+export type EventData = any;
+export type EventListener = (data: EventData) => void;
+export interface GunOperationResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Improved type definitions to reduce 'any' usage while maintaining GunDB compatibility
+ */
+import type { IGunUserInstance, IGunInstance, ISEAPair } from "gun/types";
+export interface GunAckCallback {
+    (ack: {
+        err?: string;
+        ok?: number;
+        pub?: string;
+    }): void;
+}
+export interface TypedGunOperationResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    ack?: {
+        err?: string;
+        ok?: number;
+        pub?: string;
+    };
+}
+export interface TypedAuthCallback {
+    (user: IGunUserInstance<any>): void;
+}
+export interface TypedAuthResult {
+    success: boolean;
+    userPub?: string;
+    username?: string;
+    error?: string;
+    ack?: {
+        err?: string;
+        ok?: number;
+        pub?: string;
+        sea?: ISEAPair;
+    };
+    sea?: ISEAPair;
+}
+export interface TypedGunConfig {
+    peers?: string[];
+    localStorage?: boolean;
+    radisk?: boolean;
+    file?: string;
+    uuid?: () => string;
+    [key: string]: unknown;
+}
+export interface TypedEventData {
+    type: string;
+    data: unknown;
+    timestamp: number;
+    source?: string;
+}
+export type GunPath = string | string[];
+export interface PathOperation<T = unknown> {
+    path: GunPath;
+    data?: T;
+    callback?: GunAckCallback;
+}
+export interface TypedRxJSObservable<T = unknown> {
+    subscribe: (observer: {
+        next: (value: T) => void;
+        error?: (error: Error) => void;
+        complete?: () => void;
+    }) => {
+        unsubscribe: () => void;
+    };
+}
+export interface TypedPluginConfig {
+    name: string;
+    version: string;
+    enabled: boolean;
+    config?: Record<string, unknown>;
+}
+export interface TypedStorageData {
+    key: string;
+    value: unknown;
+    timestamp: number;
+    ttl?: number;
+}
+export interface TypedGunError extends Error {
+    code?: string;
+    type: "GUN_ERROR" | "AUTH_ERROR" | "NETWORK_ERROR" | "VALIDATION_ERROR";
+    context?: Record<string, unknown>;
+}
+export type GunOperation = "get" | "put" | "set" | "remove" | "once" | "on" | "off";
+export type GunAuthMethod = "password" | "pair" | "webauthn" | "web3" | "nostr" | "zkproof";
+export interface TypedGunWrapper<T = Record<string, unknown>> {
+    gun: IGunInstance<any>;
+    user: IGunUserInstance | null;
+    get(path: GunPath): Promise<T>;
+    put(path: GunPath, data: T): Promise<TypedGunOperationResult<T>>;
+    set(path: GunPath, data: T): Promise<TypedGunOperationResult<T>>;
+    remove(path: GunPath): Promise<TypedGunOperationResult>;
+    getUserData(path: string): Promise<T>;
+    putUserData(path: string, data: T): Promise<void>;
+    login(username: string, password: string): Promise<TypedAuthResult>;
+    signUp(username: string, password: string): Promise<TypedAuthResult>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,16 @@
+import { ShogunCore } from "./core";
+import { IGunUserInstance, IGunInstance, GunDataEventData, GunPeerEventData, DeriveOptions } from "./gundb/db";
+import { RxJS, crypto, derive, GunErrors, DataBase } from "./gundb/db";
+import { SimpleGunAPI, QuickStart, quickStart, createSimpleAPI, TypedGunOperationResult, TypedAuthResult, AutoQuickStart, autoQuickStart } from "./gundb";
+import { SEA } from "./gundb/db";
+import Gun from "./gundb/db";
+export * from "./utils/errorHandler";
+export * from "./plugins";
+export * from "./interfaces/shogun";
+export * from "./config/simplified-config";
+export type * from "./interfaces/plugin";
+export type { IGunUserInstance, IGunInstance, GunDataEventData, GunPeerEventData, DeriveOptions, TypedGunOperationResult, TypedAuthResult, };
+export { Gun, ShogunCore, SEA, RxJS, crypto, derive, GunErrors, DataBase, SimpleGunAPI, QuickStart, quickStart, createSimpleAPI, AutoQuickStart, autoQuickStart, };
+export { generateSeedPhrase, validateSeedPhrase, mnemonicToSeed, seedToPassword, deriveCredentialsFromMnemonic, formatSeedPhrase, normalizeSeedPhrase, } from "./utils/seedPhrase";
+export * from "./crypto";
+export { CryptoIdentityManager } from "./managers/CryptoIdentityManager";

package/dist/types/interfaces/common.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Base event interface
+ */
+export interface BaseEvent {
+    type: string;
+    data: Record<string, unknown>;
+    timestamp: number;
+}
+/**
+ * Base configuration interface
+ */
+export interface BaseConfig {
+    timeout?: number;
+    maxRetries?: number;
+    retryDelay?: number;
+}
+/**
+ * Base cache entry interface
+ */
+export interface BaseCacheEntry<T = unknown> {
+    timestamp: number;
+    data?: T;
+}
+/**
+ * Base operation result
+ */
+export interface BaseResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Base authentication result
+ */
+export interface BaseAuthResult extends BaseResult {
+    username?: string;
+    password?: string;
+}
+/**
+ * Common log levels
+ */
+export type LogLevel = "info" | "error" | "debug" | "warn";
+/**
+ * Base log message
+ */
+export interface BaseLogMessage {
+    timestamp: string;
+    level: LogLevel;
+    message: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Base device info
+ */
+export interface BaseDeviceInfo {
+    deviceId: string;
+    timestamp: number;
+    name: string;
+    platform: string;
+    lastUsed?: number;
+}
+/**
+ * Base backup options
+ */
+export interface BaseBackupOptions {
+    encryptionPassword?: string;
+    includeHistory?: boolean;
+}
+/**
+ * Base import options
+ */
+export interface BaseImportOptions {
+    decryptionPassword?: string;
+    validateData?: boolean;
+    overwriteExisting?: boolean;
+}
+/**
+ * Basic error information
+ */
+export interface ErrorInfo {
+    message: string;
+    code?: string;
+    name?: string;
+    stack?: string;
+    [key: string]: unknown;
+}

package/dist/types/interfaces/events.d.ts

@@ -0,0 +1,131 @@
+import { EventEmitter } from "../utils/eventEmitter";
+/**
+ * Interface representing authentication event data
+ * @interface AuthEventData
+ * @property {string} [userPub] - The user's public key (optional)
+ * @property {string} [username] - Optional username
+ * @property {"password" | "webauthn" | "web3" | "nostr" | "zkproof" | "pair" } method - Authentication method used
+ * @property {string} [provider] - Optional provider name
+ */
+export interface AuthEventData {
+    userPub?: string;
+    username?: string;
+    method: "password" | "webauthn" | "web3" | "nostr" | "zkproof" | "pair";
+    provider?: string;
+}
+/**
+ * Interface representing wallet event data
+ * @interface WalletEventData
+ * @property {string} address - The wallet address
+ * @property {string} [path] - Optional derivation path
+ */
+export interface WalletEventData {
+    address: string;
+    path?: string;
+}
+/**
+ * Interface representing error event data
+ * @interface ErrorEventData
+ * @property {string} action - Error action/code
+ * @property {string} message - Error message
+ * @property {string} type - Error type
+ * @property {unknown} [details] - Optional additional error details
+ */
+export interface ErrorEventData {
+    action: string;
+    message: string;
+    type: string;
+    details?: unknown;
+}
+/**
+ * Interface representing Gun data operation event data
+ * @interface GunDataEventData
+ * @property {string} path - The path where the operation occurred
+ * @property {any} [data] - The data involved in the operation
+ * @property {boolean} success - Whether the operation was successful
+ * @property {string} [error] - Error message if operation failed
+ * @property {number} timestamp - Timestamp of the operation
+ */
+export interface GunDataEventData {
+    path: string;
+    data?: any;
+    success: boolean;
+    error?: string;
+    timestamp: number;
+}
+/**
+ * Interface representing Gun peer event data
+ * @interface GunPeerEventData
+ * @property {string} peer - The peer URL
+ * @property {string} action - The action performed (add, remove, connect, disconnect)
+ * @property {number} timestamp - Timestamp of the event
+ */
+export interface GunPeerEventData {
+    peer: string;
+    action: "add" | "remove" | "connect" | "disconnect";
+    timestamp: number;
+}
+/**
+ * Type defining all available Shogun event listeners
+ */
+export type ShogunEventMap = {
+    "auth:login": AuthEventData;
+    "auth:logout": void;
+    "auth:signup": AuthEventData;
+    "auth:username_changed": {
+        oldUsername?: string;
+        newUsername?: string;
+        userPub?: string;
+    };
+    "wallet:created": WalletEventData;
+    "gun:put": GunDataEventData;
+    "gun:get": GunDataEventData;
+    "gun:set": GunDataEventData;
+    "gun:remove": GunDataEventData;
+    "gun:peer:add": GunPeerEventData;
+    "gun:peer:remove": GunPeerEventData;
+    "gun:peer:connect": GunPeerEventData;
+    "gun:peer:disconnect": GunPeerEventData;
+    "plugin:registered": {
+        name: string;
+        version?: string;
+        category?: string;
+    };
+    "plugin:unregistered": {
+        name: string;
+    };
+    debug: {
+        action: string;
+        [key: string]: any;
+    };
+    error: ErrorEventData;
+};
+/**
+ * Extended EventEmitter class with typed events for Shogun
+ * @class ShogunEventEmitter
+ * @extends EventEmitter
+ */
+export declare class ShogunEventEmitter extends EventEmitter<ShogunEventMap> {
+    /**
+     * Emit a typed Shogun event
+     * @template K - Event key type
+     * @param {K} event - Event name
+     * @param {ShogunEventMap[K]} data - Event data
+     * @returns {boolean} - Returns true if the event had listeners, false otherwise
+     */
+    emit<K extends keyof ShogunEventMap>(event: K, data?: ShogunEventMap[K] extends void ? never : ShogunEventMap[K]): boolean;
+    /**
+     * Register a listener for a typed Shogun event
+     * @template K - Event key type
+     * @param {K} event - Event name
+     * @param {(data: ShogunEventMap[K]) => void} listener - Event listener function
+     */
+    on<K extends keyof ShogunEventMap>(event: K, listener: ShogunEventMap[K] extends void ? () => void : (data: ShogunEventMap[K]) => void): void;
+    /**
+     * Remove a listener for a typed Shogun event
+     * @template K - Event key type
+     * @param {K} event - Event name
+     * @param {(data: ShogunEventMap[K]) => void} listener - Event listener function to remove
+     */
+    off<K extends keyof ShogunEventMap>(event: K, listener: ShogunEventMap[K] extends void ? () => void : (data: ShogunEventMap[K]) => void): void;
+}