@hashgraphonline/standards-agent-kit 0.2.131 → 0.2.134

package/src/tools/inscriber/RetrieveInscriptionTool.ts

@@ -15,6 +15,26 @@ const retrieveInscriptionSchema = z.object({
     .describe('API key for inscription service'),
 });
 
+/**
+ * Type definition for inscription retrieval result
+ */
+interface InscriptionRetrievalResult {
+  inscriptionId?: string;
+  transactionId: string;
+  topicId?: string;
+  status?: string;
+  holderId?: string;
+  metadata?: unknown;
+  tags?: unknown;
+  mode?: string;
+  chunks?: unknown;
+  createdAt?: string;
+  completedAt?: string;
+  fileUrl?: string;
+  mimeType?: string;
+  fileSize?: number;
+}
+
 
 /**
  * Tool for retrieving inscriptions
@@ -30,7 +50,7 @@ export class RetrieveInscriptionTool extends BaseInscriberQueryTool<typeof retri
   protected async executeQuery(
     params: z.infer<typeof retrieveInscriptionSchema>,
     _runManager?: CallbackManagerForToolRun
-  ): Promise<unknown> {
+  ): Promise<InscriptionRetrievalResult> {
     const result = await this.inscriberBuilder.retrieveInscription(
       params.transactionId,
       {
@@ -39,21 +59,23 @@ export class RetrieveInscriptionTool extends BaseInscriberQueryTool<typeof retri
       }
     );
 
+    const typedResult = result as unknown as Record<string, unknown>;
+
     return {
-      inscriptionId: (result as any).inscriptionId,
-      transactionId: result.transactionId,
-      topicId: (result as any).topic_id,
-      status: result.status,
-      holderId: (result as any).holderId,
+      inscriptionId: typedResult.inscriptionId as string | undefined,
+      transactionId: result.transactionId || 'unknown',
+      topicId: typedResult.topic_id as string | undefined,
+      status: result.status || 'unknown',
+      holderId: typedResult.holderId as string | undefined,
       metadata: result.metadata,
-      tags: (result as any).tags,
+      tags: typedResult.tags,
       mode: result.mode,
-      chunks: (result as any).chunks,
-      createdAt: (result as any).createdAt,
-      completedAt: (result as any).completed || (result as any).completedAt,
+      chunks: typedResult.chunks,
+      createdAt: typedResult.createdAt as string | undefined,
+      completedAt: (typedResult.completed || typedResult.completedAt) as string | undefined,
       fileUrl: result.fileUrl,
-      mimeType: (result as any).mimeType,
-      fileSize: (result as any).fileSize,
+      mimeType: typedResult.mimeType as string | undefined,
+      fileSize: typedResult.fileSize as number | undefined,
     };
   }
 }

package/src/tools/inscriber/base-inscriber-tools.ts

@@ -60,22 +60,11 @@ export abstract class BaseInscriberTransactionTool<
     input: InscriptionInput,
     options: InscriptionOptions
   ): Promise<QuoteResult> {
-    const operatorId = this.inscriberBuilder['hederaKit'].signer.getAccountId().toString();
-    const operatorPrivateKey = this.inscriberBuilder['hederaKit'].signer?.getOperatorPrivateKey()
-      ? this.inscriberBuilder['hederaKit'].signer.getOperatorPrivateKey().toStringRaw()
-      : '';
-
     const network = this.inscriberBuilder['hederaKit'].client.network;
     const networkType = network.toString().includes('mainnet')
       ? 'mainnet'
       : 'testnet';
 
-    const clientConfig = {
-      accountId: operatorId,
-      privateKey: operatorPrivateKey,
-      network: networkType as 'mainnet' | 'testnet',
-    };
-
     const quoteOptions = {
       ...options,
       quoteOnly: true,
@@ -83,7 +72,7 @@ export abstract class BaseInscriberTransactionTool<
     };
 
     const result = await this.inscriberBuilder.inscribe(input, quoteOptions);
-    
+
     if (!result.quote || result.confirmed) {
       throw new Error('Failed to generate quote - unexpected response type');
     }
@@ -136,22 +125,11 @@ export abstract class BaseInscriberQueryTool<
     input: InscriptionInput,
     options: InscriptionOptions
   ): Promise<QuoteResult> {
-    const operatorId = this.inscriberBuilder['hederaKit'].signer.getAccountId().toString();
-    const operatorPrivateKey = this.inscriberBuilder['hederaKit'].signer?.getOperatorPrivateKey()
-      ? this.inscriberBuilder['hederaKit'].signer.getOperatorPrivateKey().toStringRaw()
-      : '';
-
     const network = this.inscriberBuilder['hederaKit'].client.network;
     const networkType = network.toString().includes('mainnet')
       ? 'mainnet'
       : 'testnet';
 
-    const clientConfig = {
-      accountId: operatorId,
-      privateKey: operatorPrivateKey,
-      network: networkType as 'mainnet' | 'testnet',
-    };
-
     const quoteOptions = {
       ...options,
       quoteOnly: true,
@@ -159,7 +137,7 @@ export abstract class BaseInscriberQueryTool<
     };
 
     const result = await this.inscriberBuilder.inscribe(input, quoteOptions);
-    
+
     if (!result.quote || result.confirmed) {
       throw new Error('Failed to generate quote - unexpected response type');
     }

package/src/types/content-resolver.ts

@@ -1,11 +1,11 @@
 /**
  * Content Resolver Types
- * 
+ *
  * Re-export types from standards-sdk for content resolution.
  */
 
-export type { 
+export type {
   ContentResolverInterface,
   ReferenceResolutionResult,
-  ContentStoreInterface 
+  ContentStoreInterface
 } from '@hashgraphonline/standards-sdk';

package/src/types/inscription-response.ts

@@ -0,0 +1,234 @@
+/**
+ * Structured response interface for inscription tools
+ * Provides a consistent, user-friendly format for inscription results
+ */
+
+export interface InscriptionSuccessResponse {
+  success: true;
+  type: 'inscription';
+  title: string;
+  message: string;
+  inscription: {
+    /** The HRL (Hashinal Reference Link) for minting - e.g., "hcs://1/0.0.123456" */
+    hrl: string;
+    /** Topic ID where the inscription was stored */
+    topicId: string;
+    /** Type of Hashinal - Static (HCS-5) or Dynamic (HCS-6) */
+    standard: 'Static' | 'Dynamic';
+    /** CDN URL for direct access to the inscribed content */
+    cdnUrl?: string;
+    /** Transaction ID of the inscription */
+    transactionId?: string;
+  };
+  metadata: {
+    /** Name/title of the inscribed content */
+    name?: string;
+    /** Creator of the content */
+    creator?: string;
+    /** Description of the content */
+    description?: string;
+    /** Content type (image, text, etc.) */
+    type?: string;
+    /** Additional attributes */
+    attributes?: Array<{ trait_type: string; value: string | number }>;
+  };
+  nextSteps: {
+    /** Primary action the user should take next */
+    primary: string;
+    /** Additional context or options */
+    context?: string;
+    /** Specific metadata value to use for minting */
+    mintingMetadata: string;
+  };
+  /** HashLink block data (only present when withHashLinkBlocks=true) */
+  hashLinkBlock?: {
+    /** Block topic ID on HCS */
+    blockId: string;
+    /** HashLink reference to the block */
+    hashLink: string;
+    /** Template topic ID */
+    template: string;
+    /** Block attributes for rendering */
+    attributes: BlockAttributes;
+  };
+}
+
+export interface InscriptionQuoteResponse {
+  success: true;
+  type: 'quote';
+  title: string;
+  message: string;
+  quote: {
+    /** Total cost in HBAR */
+    totalCostHbar: string;
+    /** When the quote expires */
+    validUntil: string;
+    /** Cost breakdown details */
+    breakdown?: CostBreakdown;
+  };
+  content: {
+    /** Name of the content to be inscribed */
+    name?: string;
+    /** Creator of the content */
+    creator?: string;
+    /** Type of content */
+    type?: string;
+  };
+}
+
+export interface InscriptionErrorResponse {
+  success: false;
+  type: 'error';
+  title: string;
+  message: string;
+  error: {
+    /** Error code for programmatic handling */
+    code: string;
+    /** Detailed error message */
+    details: string;
+    /** Suggestions for fixing the error */
+    suggestions?: string[];
+  };
+}
+
+export type InscriptionResponse =
+  | InscriptionSuccessResponse
+  | InscriptionQuoteResponse
+  | InscriptionErrorResponse;
+
+/**
+ * Helper function to create a successful inscription response
+ */
+export function createInscriptionSuccess(params: {
+  hrl: string;
+  topicId: string;
+  standard: 'Static' | 'Dynamic';
+  cdnUrl?: string;
+  transactionId?: string;
+  metadata: {
+    name?: string;
+    creator?: string;
+    description?: string;
+    type?: string;
+    attributes?: Array<{ trait_type: string; value: string | number }>;
+  };
+}): InscriptionSuccessResponse {
+  const { hrl, topicId, standard, cdnUrl, transactionId, metadata } = params;
+
+  return {
+    success: true,
+    type: 'inscription',
+    title: `${standard} Hashinal Inscription Complete`,
+    message: `Successfully inscribed "${
+      metadata.name || 'your content'
+    }" as a ${standard} Hashinal. The content is now ready for NFT minting.`,
+    inscription: {
+      hrl,
+      topicId,
+      standard,
+      cdnUrl,
+      transactionId,
+    },
+    metadata,
+    nextSteps: {
+      primary: 'Use the HRL below as metadata when minting your NFT',
+      context:
+        'The HRL (Hedera Resource Locator) is the standardized way to reference your inscribed content in NFT metadata.',
+      mintingMetadata: hrl,
+    },
+  };
+}
+
+/**
+ * Block attributes for HashLink rendering
+ */
+interface BlockAttributes {
+  /** Display name */
+  name?: string;
+  /** Description text */
+  description?: string;
+  /** Image URL */
+  image?: string;
+  /** Content type */
+  contentType?: string;
+  /** Size in bytes */
+  size?: number;
+  /** Custom metadata */
+  metadata?: Record<string, string | number | boolean>;
+}
+
+/**
+ * Transfer details in cost breakdown
+ */
+interface TransferDetails {
+  to: string;
+  amount: string;
+  description: string;
+}
+
+/**
+ * Cost breakdown details for inscription quote
+ */
+interface CostBreakdown {
+  transfers: TransferDetails[];
+  baseFee?: number;
+  sizeFee?: number;
+  networkFee?: number;
+  serviceFee?: number;
+  totalFee?: number;
+  currency?: string;
+}
+
+/**
+ * Helper function to create a quote response
+ */
+export function createInscriptionQuote(params: {
+  totalCostHbar: string;
+  validUntil: string;
+  breakdown?: CostBreakdown;
+  content: {
+    name?: string;
+    creator?: string;
+    type?: string;
+  };
+}): InscriptionQuoteResponse {
+  const { totalCostHbar, validUntil, breakdown, content } = params;
+
+  return {
+    success: true,
+    type: 'quote',
+    title: 'Inscription Cost Quote',
+    message: `Estimated cost to inscribe "${
+      content.name || 'your content'
+    }" is ${totalCostHbar} HBAR.`,
+    quote: {
+      totalCostHbar,
+      validUntil,
+      breakdown,
+    },
+    content,
+  };
+}
+
+/**
+ * Helper function to create an error response
+ */
+export function createInscriptionError(params: {
+  code: string;
+  details: string;
+  suggestions?: string[];
+}): InscriptionErrorResponse {
+  const { code, details, suggestions } = params;
+
+  return {
+    success: false,
+    type: 'error',
+    title: 'Inscription Failed',
+    message: `Unable to complete inscription: ${details}`,
+    error: {
+      code,
+      details,
+      suggestions,
+    },
+  };
+}

package/src/utils/Encryption.ts

@@ -1,4 +1,4 @@
-// src/utils/Encryption.ts
+
 /**
  * Placeholder for encryption functionality.
  * Currently, encryption is disabled. The useEncryption flag is false by default.

package/src/utils/HederaClient.ts

@@ -1,9 +1,8 @@
-// src/utils/HederaClient.ts
+
 import { Client, AccountId, PrivateKey, TopicMessage, TopicMessageQuery } from '@hashgraph/sdk';
 import * as dotenv from 'dotenv';
 import { HCS10Message } from '../hcs10/types';
 
-// Load environment variables from .env file
 dotenv.config();
 
 /**

package/src/utils/metadata-defaults.ts

@@ -9,11 +9,22 @@ export function generateDefaultMetadata(params: {
   fileName?: string;
   mimeType?: string;
   operatorAccount: string;
-}) {
+}): {
+  name: string;
+  creator: string;
+  description: string;
+  type: string;
+  image: string;
+} {
   const defaultName = params.fileName?.replace(/\.[^/.]+$/, '') || 'Hashinal NFT';
-  const defaultType = params.mimeType?.startsWith('image/') ? 'image' : 
-                      params.mimeType?.startsWith('video/') ? 'video' :
-                      params.mimeType?.startsWith('audio/') ? 'audio' : 'media';
+  let defaultType = 'media';
+  if (params.mimeType?.startsWith('image/')) {
+    defaultType = 'image';
+  } else if (params.mimeType?.startsWith('video/')) {
+    defaultType = 'video';
+  } else if (params.mimeType?.startsWith('audio/')) {
+    defaultType = 'audio';
+  }
 
   return {
     name: params.name || defaultName,

package/src/utils/state-tools.ts

@@ -125,8 +125,7 @@ export async function createAgent(
       client,
     };
   } catch (error) {
-    console.log('error', error, baseClient);
-    logger.error(`Error creating ${agentName} agent:`, error);
+    logger.error(`Error creating ${agentName} agent:`, error, { baseClient });
     return null;
   }
 }

package/src/validation/content-ref-schemas.ts

@@ -5,7 +5,7 @@ import { z } from 'zod';
  */
 export const contentRefSchema = z
   .string()
-  .regex(/^content-ref:[a-fA-F0-9]{64}$/, 'Content reference must be in format "content-ref:[64-char hex]"')
+  .regex(/^content-ref:[a-zA-Z0-9_-]+$/, 'Content reference must be in format "content-ref:[alphanumeric-id]"')
   .describe('Content reference in format "content-ref:[id]"');
 
 /**
@@ -15,6 +15,6 @@ export function validateContentRef(input: string): string {
   try {
     return contentRefSchema.parse(input);
   } catch (error) {
-    throw new Error(`Invalid content reference format. Expected "content-ref:[64-character-hash]" but got "${input}"`);
+    throw new Error(`Invalid content reference format. Expected "content-ref:[alphanumeric-id]" but got "${input}"`);
   }
 }

package/src/validation/hip412-schemas.ts

@@ -39,7 +39,7 @@ export const hip412MetadataSchema = z.object({
 /**
  * Validates metadata against HIP-412 standard
  */
-export function validateHIP412Metadata(metadata: any): z.infer<typeof hip412MetadataSchema> {
+export function validateHIP412Metadata(metadata: unknown): z.infer<typeof hip412MetadataSchema> {
   try {
     return hip412MetadataSchema.parse(metadata);
   } catch (error) {