@evefrontier/dapp-kit 0.1.0

package/graphql/types.ts

@@ -0,0 +1,443 @@
+/**
+ * GraphQL response types for Sui object queries
+ */
+
+// ============================================================================
+// Base GraphQL Types
+// ============================================================================
+
+/** @category GraphQL */
+export interface GraphQLResponse<T = unknown> {
+  data?: T;
+  errors?: Array<{
+    message: string;
+  }>;
+}
+
+/** @category GraphQL */
+export interface PageInfo {
+  hasNextPage: boolean;
+  endCursor: string | null;
+}
+
+// ============================================================================
+// Move Object Types
+// ============================================================================
+
+/** @category GraphQL */
+export interface MoveObjectContents {
+  json?: Record<string, unknown>;
+  bcs?: string;
+  type?: {
+    repr: string;
+    layout?: string;
+  };
+}
+
+/** @category GraphQL */
+export interface DynamicFieldNode {
+  contents: {
+    json: Record<string, unknown>;
+    type: {
+      layout: string;
+    };
+  };
+  name: {
+    json: unknown;
+    type: {
+      repr: string;
+    };
+  };
+}
+
+/** @category GraphQL */
+export interface MoveObjectData {
+  contents: MoveObjectContents;
+  dynamicFields?: {
+    nodes: DynamicFieldNode[];
+  };
+}
+
+// ============================================================================
+// Object Response Types
+// ============================================================================
+
+/** @category GraphQL */
+export interface SuiObjectResponse {
+  address?: string;
+  version?: number;
+  digest?: string;
+  asMoveObject: MoveObjectData | null;
+}
+
+/** @category GraphQL */
+export interface GetObjectResponse {
+  object?: SuiObjectResponse;
+}
+
+// ============================================================================
+// GetObjectByAddress Response Types
+// ============================================================================
+
+/** @category GraphQL */
+export interface GetObjectByAddressResponse {
+  object?: {
+    address: string;
+    version: number;
+    digest: string;
+    asMoveObject: {
+      contents: {
+        type: {
+          repr: string;
+        };
+        bcs: string;
+      };
+    } | null;
+  };
+}
+
+// ============================================================================
+// Owner & Owned Objects Response Types
+// ============================================================================
+
+/** @category GraphQL */
+export interface OwnedObjectNode {
+  contents: {
+    bcs: string;
+  };
+  previousTransaction?: {
+    effects?: {
+      timestamp?: string;
+    };
+  };
+}
+
+/** @category GraphQL */
+export interface AddressOwner {
+  address: {
+    address: string;
+    objects: {
+      nodes: OwnedObjectNode[];
+    };
+  };
+}
+
+/** @category GraphQL */
+export interface GetObjectOwnerAndOwnedObjectsResponse {
+  object?: {
+    owner?: {
+      address?: AddressOwner["address"];
+    };
+  };
+}
+
+// ============================================================================
+// Owner & Owned Objects with JSON Response Types
+// ============================================================================
+
+/** @category GraphQL */
+export interface OwnedObjectNodeWithJson {
+  address: string;
+  contents: {
+    json: Record<string, unknown>;
+    bcs: string;
+  };
+  previousTransaction?: {
+    effects?: {
+      timestamp?: string;
+    };
+  };
+}
+
+/** @category GraphQL */
+export interface AddressOwnerWithJson {
+  address: {
+    address: string;
+    objects: {
+      nodes: OwnedObjectNodeWithJson[];
+    };
+  };
+}
+
+/** @category GraphQL */
+export interface GetObjectOwnerAndOwnedObjectsWithJsonResponse {
+  object?: {
+    owner?: {
+      address?: AddressOwnerWithJson["address"];
+    };
+  };
+}
+
+/** @category GraphQL */
+export interface GetObjectAndCharacterOwnerResponse {
+  object: {
+    asMoveObject: {
+      contents: {
+        json: Record<string, unknown>;
+        bcs: string;
+        type: {
+          repr: string;
+        };
+        extract?: {
+          asAddress?: {
+            asObject?: {
+              asMoveObject?: {
+                owner: {
+                  address: {
+                    objects: {
+                      nodes: [
+                        {
+                          contents: {
+                            authorizedObj: {
+                              asAddress: {
+                                asObject: {
+                                  asMoveObject: {
+                                    contents: {
+                                      json: RawCharacterData;
+                                    };
+                                  };
+                                };
+                              };
+                            };
+                          };
+                        },
+                      ];
+                    };
+                  };
+                };
+                contents?: {
+                  json: Record<string, unknown>;
+                };
+              };
+            };
+          };
+        } | null;
+        owner?: {
+          address?: {
+            address: string;
+            objects: {
+              nodes: Array<{
+                contents: {
+                  json: Record<string, unknown>;
+                  extract?: {
+                    asAddress?: {
+                      asObject?: {
+                        asMoveObject?: {
+                          contents?: {
+                            json: Record<string, unknown>;
+                          };
+                        };
+                      };
+                    };
+                  };
+                };
+              }>;
+            };
+          };
+        };
+      };
+      dynamicFields?: {
+        nodes: DynamicFieldNode[];
+      };
+    };
+  };
+}
+
+// ============================================================================
+// GetObjectWithJson Response Types
+// ============================================================================
+
+/** @category GraphQL */
+export interface GetObjectWithJsonResponse {
+  object?: {
+    address: string;
+    version: number;
+    digest: string;
+    asMoveObject: {
+      contents: {
+        type: {
+          repr: string;
+        };
+        json: Record<string, unknown>;
+        bcs: string;
+      };
+    } | null;
+  };
+}
+
+// ============================================================================
+// GetOwnedObjectsByType Response Types
+// ============================================================================
+
+/** @category GraphQL */
+export interface OwnedObjectAddressNode {
+  address: string;
+}
+
+/** @category GraphQL */
+export interface GetOwnedObjectsByTypeResponse {
+  address?: {
+    objects: {
+      nodes: OwnedObjectAddressNode[];
+    };
+  };
+}
+
+// ============================================================================
+// GetOwnedObjectsByPackage Response Types
+// ============================================================================
+
+/** @category GraphQL */
+export interface OwnedObjectFullNode {
+  address: string;
+  version: number;
+  asMoveObject: MoveObjectData | null;
+}
+
+/** @category GraphQL */
+export interface GetOwnedObjectsByPackageResponse {
+  objects: {
+    nodes: OwnedObjectFullNode[];
+  };
+}
+
+// ============================================================================
+// Singleton & Type-based Query Response Types
+// ============================================================================
+
+/** @category GraphQL */
+export interface GetSingletonObjectByTypeResponse {
+  objects: {
+    nodes: OwnedObjectAddressNode[];
+  };
+}
+
+/** @category GraphQL */
+export interface ObjectWithContentsNode {
+  address: string;
+  version: number;
+  asMoveObject: {
+    contents: {
+      json: Record<string, unknown>;
+      type: {
+        repr: string;
+      };
+    };
+  } | null;
+}
+
+/** @category GraphQL */
+export interface GetObjectsByTypeResponse {
+  objects: {
+    nodes: ObjectWithContentsNode[];
+    pageInfo: PageInfo;
+  };
+}
+
+// ============================================================================
+// EVE Frontier Specific Types
+// ============================================================================
+
+/**
+ * Raw Sui object data structure returned from the EVE Frontier package
+ *
+ * @category GraphQL
+ */
+export interface RawSuiObjectData {
+  id: string;
+  type_id: string;
+  extension: unknown;
+  inventory_keys?: string[];
+  key?: {
+    item_id: string;
+    tenant: string;
+  };
+  location?: {
+    location_hash: string;
+    structure_id: string;
+  };
+  metadata?: {
+    assembly_id: string;
+    description: string;
+    name: string;
+    url: string;
+  };
+  owner_cap_id?: string;
+  status?: {
+    assembly_id?: string;
+    item_id?: string;
+    status: {
+      "@variant": string;
+    };
+    type_id?: string;
+  };
+  /** Fuel data for Network Nodes */
+  fuel?: {
+    max_capacity: string;
+    burn_rate_in_ms: string;
+    type_id: string;
+    unit_volume: string;
+    quantity: string;
+    is_burning: boolean;
+    previous_cycle_elapsed_time: string;
+    burn_start_time: string;
+    last_updated: string;
+  };
+  /** Energy source data for Network Nodes */
+  energy_source?: {
+    max_energy_production: string;
+    current_energy_production: string;
+    total_reserved_energy: string;
+  };
+  /** Connected assembly IDs for Network Nodes */
+  connected_assembly_ids?: string[];
+}
+
+/**
+ * OwnerCap JSON structure - returned from Character OwnerCap query
+ * Contains the authorized_object_id which is the Character ID
+ *
+ * @category GraphQL
+ */
+export interface OwnerCapData {
+  authorized_object_id: string;
+  id: string;
+}
+
+/**
+ * Raw Character data structure from the EVE Frontier package
+ *
+ * @category GraphQL
+ */
+export interface RawCharacterData {
+  id: `0x${string}`;
+  key: {
+    item_id: string;
+    tenant: string;
+  };
+  tribe_id: number;
+  character_address: `0x${string}`;
+  metadata: {
+    assembly_id: `0x${string}`;
+    name: string;
+    description: string;
+    url: string;
+  };
+  owner_cap_id: `0x${string}`;
+  // Additional fields that may be present
+  [key: string]: unknown;
+}
+
+/**
+ * Processed character/owner information
+ *
+ * @category GraphQL
+ */
+export interface CharacterInfo {
+  id: string;
+  address: string;
+  name: string;
+  tribeId: number;
+  characterId: number;
+  _raw?: RawCharacterData;
+}

package/hooks/index.ts

@@ -0,0 +1,14 @@
+export { useConnection } from "./useConnection";
+export { useSmartObject } from "./useSmartObject";
+export { useNotification } from "./useNotification";
+export {
+  useSponsoredTransaction,
+  WalletSponsoredTransactionNotSupportedError,
+  WalletNotConnectedError,
+  WalletNoAccountSelectedError,
+} from "./useSponsoredTransaction";
+export type {
+  UseSponsoredTransactionError,
+  UseSponsoredTransactionArgs,
+  UseSponsoredTransactionMutationOptions,
+} from "./useSponsoredTransaction";

package/hooks/useConnection.ts

@@ -0,0 +1,58 @@
+import { useContext } from "react";
+import { VaultContext, VaultContextType } from "../providers/VaultProvider";
+
+/**
+ * Hook for managing wallet connection state in EVE Frontier dApps.
+ *
+ * Provides access to wallet connection status, current account information,
+ * and methods to connect/disconnect wallets. Automatically detects EVE Vault
+ * wallet availability.
+ *
+ * @category Hooks
+ * @returns Object containing wallet state and connection methods:
+ *   - `currentAccount` - The currently connected wallet account (or null)
+ *   - `walletAddress` - The connected wallet's address string
+ *   - `isConnected` - Boolean indicating connection status
+ *   - `hasEveVault` - Boolean indicating if EVE Vault wallet is available
+ *   - `handleConnect` - Function to initiate wallet connection
+ *   - `handleDisconnect` - Function to disconnect the wallet
+ * @throws {Error} If used outside of `EveFrontierProvider`
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { useConnection } from '@evefrontier/dapp-kit';
+ *
+ * const WalletButton = () => {
+ *   const { isConnected, walletAddress, handleConnect, handleDisconnect } = useConnection();
+ *
+ *   if (isConnected) {
+ *     return (
+ *       <div>
+ *         <p>Connected: {walletAddress}</p>
+ *         <button onClick={handleDisconnect}>Disconnect</button>
+ *       </div>
+ *     );
+ *   }
+ *
+ *   return <button onClick={handleConnect}>Connect Wallet</button>;
+ * };
+ * ```
+ *
+ * @example Check for EVE Vault
+ * ```tsx
+ * const { hasEveVault, handleConnect } = useConnection();
+ *
+ * return (
+ *   <button onClick={handleConnect} disabled={!hasEveVault}>
+ *     {hasEveVault ? 'Connect EVE Vault' : 'Please install EVE Vault'}
+ *   </button>
+ * );
+ * ```
+ */
+export function useConnection(): VaultContextType {
+  const context = useContext(VaultContext);
+  if (!context) {
+    throw new Error("useConnection must be used within an EveFrontierProvider");
+  }
+  return context;
+}

package/hooks/useNotification.ts

@@ -0,0 +1,80 @@
+import { useContext } from "react";
+import { NotificationContext, NotificationContextType } from "../providers/NotificationProvider";
+
+/**
+ * Hook for displaying user notifications in EVE Frontier dApps.
+ *
+ * Provides a simple notification system for displaying success, error, warning,
+ * and info messages to users. Commonly used after transaction completions
+ * or to display important status updates.
+ *
+ * @category Hooks
+ * @returns Object containing notification state and methods:
+ *   - `notify` - Function to trigger a notification
+ *   - `notification` - Current notification state object with:
+ *     - `isOpen` - Whether notification is visible
+ *     - `message` - The notification message
+ *     - `severity` - The notification type (success, error, warning, info)
+ *     - `txHash` - Optional transaction hash for linking
+ *     - `handleClose` - Function to close the notification
+ * @throws {Error} If used outside of `EveFrontierProvider`
+ *
+ * @example Basic notification
+ * ```tsx
+ * import { useNotification, Severity } from '@evefrontier/dapp-kit';
+ *
+ * const MyComponent = () => {
+ *   const { notify } = useNotification();
+ *
+ *   const showSuccess = () => {
+ *     notify({ type: Severity.Success, message: 'Operation completed!' });
+ *   };
+ *
+ *   return <button onClick={showSuccess}>Complete</button>;
+ * };
+ * ```
+ *
+ * @example Transaction notification with hash
+ * ```tsx
+ * const { notify } = useNotification();
+ *
+ * const handleTransaction = async () => {
+ *   try {
+ *     const result = await sendTransaction();
+ *     notify({
+ *       type: Severity.Success,
+ *       message: 'Transaction successful!',
+ *       txHash: result.digest
+ *     });
+ *   } catch (error) {
+ *     notify({
+ *       type: Severity.Error,
+ *       message: 'Transaction failed'
+ *     });
+ *   }
+ * };
+ * ```
+ *
+ * @example Displaying notification UI
+ * ```tsx
+ * const { notification } = useNotification();
+ *
+ * return (
+ *   <>
+ *     {notification.isOpen && (
+ *       <Alert severity={notification.severity} onClose={notification.handleClose}>
+ *         {notification.message}
+ *       </Alert>
+ *     )}
+ *   </>
+ * );
+ * ```
+ */
+export function useNotification(): NotificationContextType {
+  const context = useContext(NotificationContext);
+  if (!context) {
+    throw new Error("useNotification must be used within an EveFrontierProvider");
+  }
+  return context;
+}
+

package/hooks/useSmartObject.ts

@@ -0,0 +1,78 @@
+import { useContext } from "react";
+import {
+  SmartObjectContext,
+  SmartObjectContextType,
+} from "../providers/SmartObjectProvider";
+
+/**
+ * Hook for accessing smart assembly data from the Sui GraphQL Indexer.
+ *
+ * Provides reactive access to the currently selected smart assembly (Smart Storage Unit,
+ * Smart Turret, Smart Gate, Network Node, etc.) with automatic polling for updates.
+ * The assembly ID is determined from environment variables (`VITE_ITEM_ID`)
+ * or URL query parameters (`?itemId=` and `?tenant=`).
+ *
+ * @category Hooks
+ * @returns Object containing assembly state and methods:
+ *   - `assembly` - The transformed assembly data (or null if not loaded)
+ *   - `character` - The owner character information (or null)
+ *   - `selectedObjectId` - The current assembly's Sui object ID
+ *   - `loading` - Boolean indicating if data is being fetched
+ *   - `error` - Error message string (or null)
+ *   - `setSelectedObjectId` - Function to change the selected assembly
+ *   - `refetch` - Function to manually refresh assembly data
+ * @throws {Error} If used outside of `EveFrontierProvider`
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { useSmartObject } from '@evefrontier/dapp-kit';
+ *
+ * const AssemblyInfo = () => {
+ *   const { assembly, loading, error, refetch } = useSmartObject();
+ *
+ *   if (loading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error}</div>;
+ *   if (!assembly) return <div>No assembly found</div>;
+ *
+ *   return (
+ *     <div>
+ *       <h1>{assembly.name}</h1>
+ *       <p>Type: {assembly.type}</p>
+ *       <p>State: {assembly.state}</p>
+ *       <p>ID: {assembly.id}</p>
+ *       <button onClick={refetch}>Refresh</button>
+ *     </div>
+ *   );
+ * };
+ * ```
+ *
+ * @example Accessing owner character
+ * ```tsx
+ * const { assembly, character } = useSmartObject();
+ *
+ * return (
+ *   <div>
+ *     <p>Assembly: {assembly?.name}</p>
+ *     <p>Owner: {character?.name || 'Unknown'}</p>
+ *   </div>
+ * );
+ * ```
+ *
+ * @example Changing the selected assembly
+ * ```tsx
+ * const { setSelectedObjectId } = useSmartObject();
+ *
+ * const handleSelectAssembly = (newId: string) => {
+ *   setSelectedObjectId(newId);
+ * };
+ * ```
+ */
+export function useSmartObject(): SmartObjectContextType {
+  const context = useContext(SmartObjectContext);
+  if (!context) {
+    throw new Error(
+      "useSmartObject must be used within an EveFrontierProvider",
+    );
+  }
+  return context;
+}