@hashgraphonline/standards-agent-kit 0.2.135 → 0.2.137

package/src/tools/inscriber/InscribeHashinalTool.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 import { z } from 'zod';
 import { BaseInscriberQueryTool } from './base-inscriber-tools';
 import {
@@ -6,6 +5,7 @@ import {
   InscriptionInput,
   ContentResolverRegistry,
   Logger,
+  InscriptionResult,
 } from '@hashgraphonline/standards-sdk';
 import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
 import { validateHIP412Metadata } from '../../validation/hip412-schemas';
@@ -19,9 +19,14 @@ import {
   createInscriptionSuccess,
   createInscriptionQuote,
   createInscriptionError,
+  createInscriptionPending,
   InscriptionResponse,
 } from '../../types/inscription-response';
 import { FormValidatable } from '../../interfaces/FormValidatable';
+import {
+  extractTopicIds,
+  buildInscriptionLinks,
+} from '../../utils/inscription-utils';
 
 /**
  * Network-specific Hashinal block configuration for HashLink blocks
@@ -46,7 +51,6 @@ const HASHLINK_BLOCK_CONFIG = {
  * @param network The network type to get configuration for
  * @returns Network-specific block configuration with blockId, hashLink, and template
  */
-// @ts-ignore - keep untyped to satisfy mixed parser while using runtime narrowing
 function getHashLinkBlockId(network) {
   const config =
     network === 'mainnet'
@@ -58,8 +62,6 @@ function getHashLinkBlockId(network) {
   return config;
 }
 
-// Note: Using inline return type annotations to avoid parser issues with interface declarations
-
 /**
  * Schema for inscribing Hashinal NFT
  */
@@ -205,7 +207,6 @@ export class InscribeHashinalTool
   description =
     'Tool for inscribing Hashinal NFTs. CRITICAL: When user provides content (url/contentRef/base64Data), call with ONLY the content parameters - DO NOT auto-generate name, description, creator, or attributes. A form will be automatically shown to collect metadata from the user. Only include metadata parameters if the user explicitly provided them in their message.';
 
-  // Declare entity resolution preferences to preserve user-specified literal fields
   getEntityResolutionPreferences(): Record<string, string> {
     return {
       name: 'literal',
@@ -350,20 +351,17 @@ export class InscribeHashinalTool
                 .describe('Trait name (e.g., "Rarity", "Color", "Style")'),
               value: z
                 .union([z.string(), z.number()])
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 .describe('Trait value (e.g., "Epic", "Blue", 85)'),
             })
           )
         )
           .withRender(renderConfigs.array('NFT Attributes', 'Attribute'))
           .optional()
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
           .describe('Collectible traits and characteristics.'),
 
         type: z
           .string()
           .optional()
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
           .describe(
             'Category or genre of the NFT (e.g., "Digital Art", "Photography", "Collectible Card)'
           ),
@@ -379,35 +377,6 @@ export class InscribeHashinalTool
     return focusedSchema as unknown as z.ZodObject<z.ZodRawShape>;
   }
 
-  /**
-   * Implementation of FormValidatable interface
-   * Validates metadata quality and provides detailed feedback
-   */
-  validateMetadataQuality(input: unknown): {
-    needsForm: boolean;
-    reason: string;
-  } {
-    const inputObj = input as Record<string, unknown>;
-    const hasRequiredMetadata = !!(
-      inputObj.name &&
-      inputObj.description &&
-      inputObj.creator
-    );
-
-    if (!hasRequiredMetadata) {
-      return {
-        needsForm: true,
-        reason:
-          'Missing essential metadata (name, description, creator) for NFT creation',
-      };
-    }
-
-    return {
-      needsForm: false,
-      reason: 'All required metadata fields present',
-    };
-  }
-
   protected async executeQuery(
     params: z.infer<typeof inscribeHashinalSchema>,
     _runManager?: CallbackManagerForToolRun
@@ -552,28 +521,26 @@ export class InscribeHashinalTool
         });
 
         result = await Promise.race([
-          this.inscriberBuilder.inscribe(inscriptionData, options),
+          this.inscriberBuilder.inscribeAuto
+            ? this.inscriberBuilder.inscribeAuto(inscriptionData, options)
+            : this.inscriberBuilder.inscribe(inscriptionData, options),
           timeoutPromise,
         ]);
       } else {
-        result = await this.inscriberBuilder.inscribe(inscriptionData, options);
+        result = this.inscriberBuilder.inscribeAuto
+          ? await this.inscriberBuilder.inscribeAuto(inscriptionData, options)
+          : await this.inscriberBuilder.inscribe(inscriptionData, options);
       }
 
       if (result.confirmed && !result.quote) {
-        const imageTopicId = (
-          result.inscription as { topic_id?: string; jsonTopicId?: string }
-        )?.topic_id;
-        const jsonTopicId = (
-          result.inscription as { topic_id?: string; jsonTopicId?: string }
-        )?.jsonTopicId;
+        const ids = extractTopicIds(result.inscription, result.result);
         const network = options.network || 'testnet';
-
-        const cdnUrl = jsonTopicId
-          ? `https://kiloscribe.com/api/inscription-cdn/${jsonTopicId}?network=${network}`
-          : null;
-
         const fileStandard = params.fileStandard || '1';
-        const hrl = jsonTopicId ? `hcs://${fileStandard}/${jsonTopicId}` : null;
+        const { hrl, cdnUrl, topicId } = buildInscriptionLinks(
+          ids,
+          network,
+          fileStandard
+        );
         const standardType = fileStandard === '6' ? 'Dynamic' : 'Static';
 
         if (!hrl) {
@@ -589,11 +556,10 @@ export class InscribeHashinalTool
 
         const inscriptionResponse = createInscriptionSuccess({
           hrl,
-          topicId: jsonTopicId || imageTopicId || 'unknown',
+          topicId: topicId || 'unknown',
           standard: standardType as 'Static' | 'Dynamic',
           cdnUrl: cdnUrl || undefined,
-          transactionId: (result.result as { transactionId?: string })
-            ?.transactionId,
+          transactionId: (result.result as InscriptionResult)?.transactionId,
           metadata: {
             name: params.name,
             creator: params.creator,
@@ -604,11 +570,10 @@ export class InscribeHashinalTool
         });
 
         this.onEntityCreated?.({
-          entityId: jsonTopicId || imageTopicId || 'unknown',
+          entityId: topicId || 'unknown',
           entityName: params.name || 'Unnamed Inscription',
-          entityType: 'topic',
-          transactionId: (result.result as { transactionId?: string })
-            ?.transactionId,
+          entityType: 'topicId',
+          transactionId: (result.result as InscriptionResult)?.transactionId,
         });
 
         if (params.withHashLinkBlocks) {
@@ -622,7 +587,6 @@ export class InscribeHashinalTool
 
             inscriptionResponse.hashLinkBlock = blockData;
           } catch (blockError) {
-            // Log error but don't fail the inscription
             const logger = new Logger({ module: 'InscribeHashinalTool' });
             logger.error('Failed to create HashLink block', {
               error: blockError,
@@ -632,32 +596,24 @@ export class InscribeHashinalTool
 
         return inscriptionResponse;
       } else if (!result.quote && !result.confirmed) {
-        const imageTopicId = (
-          result.inscription as { topic_id?: string; jsonTopicId?: string }
-        )?.topic_id;
-        const jsonTopicId = (
-          result.inscription as { topic_id?: string; jsonTopicId?: string }
-        )?.jsonTopicId;
-
-        if (jsonTopicId || imageTopicId) {
+        const ids = extractTopicIds(result.inscription, result.result);
+        if (ids.jsonTopicId || ids.topicId) {
           const network = options.network || 'testnet';
-          const cdnUrl = jsonTopicId
-            ? `https://kiloscribe.com/api/inscription-cdn/${jsonTopicId}?network=${network}`
-            : null;
-
           const fileStandard = params.fileStandard || '1';
-          const hrl = jsonTopicId
-            ? `hcs://${fileStandard}/${jsonTopicId}`
-            : null;
+          const { hrl, cdnUrl, topicId } = buildInscriptionLinks(
+            ids,
+            network,
+            fileStandard
+          );
           const standardType = fileStandard === '6' ? 'Dynamic' : 'Static';
 
           if (hrl) {
             const inscriptionResponse = createInscriptionSuccess({
               hrl,
-              topicId: jsonTopicId || imageTopicId || 'unknown',
+              topicId: topicId || 'unknown',
               standard: standardType as 'Static' | 'Dynamic',
               cdnUrl: cdnUrl || undefined,
-              transactionId: (result.result as { transactionId?: string })
+              transactionId: (result.result as InscriptionResult)
                 ?.transactionId,
               metadata: {
                 name: params.name,
@@ -669,10 +625,10 @@ export class InscribeHashinalTool
             });
 
             this.onEntityCreated?.({
-              entityId: jsonTopicId || imageTopicId || 'unknown',
+              entityId: topicId || 'unknown',
               entityName: params.name || 'Unnamed Inscription',
-              entityType: 'topic',
-              transactionId: (result.result as { transactionId?: string })
+              entityType: 'topicId',
+              transactionId: (result.result as InscriptionResult)
                 ?.transactionId,
             });
 
@@ -687,7 +643,6 @@ export class InscribeHashinalTool
 
                 inscriptionResponse.hashLinkBlock = blockData;
               } catch (blockError) {
-                // Log error but don't fail the inscription
                 const logger = new Logger({ module: 'InscribeHashinalTool' });
                 logger.error('Failed to create HashLink block', {
                   error: blockError,
@@ -700,17 +655,14 @@ export class InscribeHashinalTool
         }
 
         const transactionId =
-          (result.result as { transactionId?: string })?.transactionId ||
-          'unknown';
-        return createInscriptionError({
-          code: 'INSCRIPTION_PENDING',
-          details: `Inscription submitted but not yet confirmed. Transaction ID: ${transactionId}`,
-          suggestions: [
-            'Wait a few moments for confirmation',
-            'Check the transaction status on a Hedera explorer',
-            "Try the inscription again if it doesn't confirm within 5 minutes",
-          ],
+          (result.result as InscriptionResult)?.transactionId || 'unknown';
+        const pending = createInscriptionPending({
+          transactionId,
         });
+        return {
+          ...pending,
+          metadata: { transactionId },
+        } as unknown as InscriptionResponse;
       } else {
         return createInscriptionError({
           code: 'UNKNOWN_STATE',

package/src/tools/inscriber/RetrieveInscriptionTool.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { BaseInscriberQueryTool } from './base-inscriber-tools';
 import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+import type { RetrievedInscriptionResult } from '@hashgraphonline/standards-sdk';
 
 /**
  * Schema for retrieving inscription
@@ -51,7 +52,7 @@ export class RetrieveInscriptionTool extends BaseInscriberQueryTool<typeof retri
     params: z.infer<typeof retrieveInscriptionSchema>,
     _runManager?: CallbackManagerForToolRun
   ): Promise<InscriptionRetrievalResult> {
-    const result = await this.inscriberBuilder.retrieveInscription(
+    const result: RetrievedInscriptionResult = await this.inscriberBuilder.retrieveInscription(
       params.transactionId,
       {
         apiKey: params.apiKey,
@@ -59,23 +60,21 @@ export class RetrieveInscriptionTool extends BaseInscriberQueryTool<typeof retri
       }
     );
 
-    const typedResult = result as unknown as Record<string, unknown>;
-
     return {
-      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,
+      inscriptionId: (result as unknown as { inscriptionId?: string }).inscriptionId,
+      transactionId: (result as unknown as { transactionId?: string }).transactionId || 'unknown',
+      topicId: (result as unknown as { topic_id?: string; topicId?: string }).topic_id || (result as unknown as { topicId?: string }).topicId,
+      status: (result as unknown as { status?: string }).status || 'unknown',
+      holderId: (result as unknown as { holderId?: string }).holderId,
       metadata: result.metadata,
-      tags: typedResult.tags,
-      mode: result.mode,
-      chunks: typedResult.chunks,
-      createdAt: typedResult.createdAt as string | undefined,
-      completedAt: (typedResult.completed || typedResult.completedAt) as string | undefined,
-      fileUrl: result.fileUrl,
-      mimeType: typedResult.mimeType as string | undefined,
-      fileSize: typedResult.fileSize as number | undefined,
+      tags: (result as unknown as { tags?: unknown }).tags,
+      mode: (result as unknown as { mode?: string }).mode,
+      chunks: (result as unknown as { chunks?: unknown }).chunks,
+      createdAt: (result as unknown as { createdAt?: string }).createdAt,
+      completedAt: (result as unknown as { completed?: string; completedAt?: string }).completed || (result as unknown as { completedAt?: string }).completedAt,
+      fileUrl: (result as unknown as { fileUrl?: string }).fileUrl,
+      mimeType: (result as unknown as { mimeType?: string }).mimeType,
+      fileSize: (result as unknown as { fileSize?: number }).fileSize,
     };
   }
 }

package/src/types/inscription-response.ts

@@ -232,3 +232,30 @@ export function createInscriptionError(params: {
     },
   };
 }
+
+/**
+ * Helper for pending inscription state (submitted but not yet confirmed)
+ */
+export function createInscriptionPending(params: {
+  transactionId: string;
+  details?: string;
+  suggestions?: string[];
+}): InscriptionErrorResponse {
+  const { transactionId, details, suggestions } = params;
+  const d = details || `Inscription submitted but not yet confirmed. Transaction ID: ${transactionId}`;
+  return {
+    success: false,
+    type: 'error',
+    title: 'Inscription Submitted (Pending)',
+    message: d,
+    error: {
+      code: 'INSCRIPTION_PENDING',
+      details: d,
+      suggestions: suggestions || [
+        'Wait a few moments for confirmation',
+        'Check the transaction status on a Hedera explorer',
+        "Try the inscription again if it doesn't confirm within 5 minutes",
+      ],
+    },
+  };
+}

package/src/utils/inscription-utils.ts

@@ -0,0 +1,53 @@
+export type NetworkType = 'mainnet' | 'testnet';
+
+export interface TopicIds {
+  jsonTopicId?: string;
+  topicId?: string;
+}
+
+function getStringProp(obj: unknown, key: string): string | undefined {
+  if (!obj || typeof obj !== 'object') return undefined;
+  const val = (obj as Record<string, unknown>)[key];
+  return typeof val === 'string' && val.trim() ? val : undefined;
+}
+
+/**
+ * Extract topic ids from an inscription and/or result object without using any.
+ * - Prefers jsonTopicId when present (for CDN linking)
+ * - Collects topic_id/topicId from either inscription or result
+ */
+export function extractTopicIds(
+  inscription: unknown,
+  result?: unknown
+): TopicIds {
+  const jsonTopicId = getStringProp(inscription, 'jsonTopicId');
+
+  const imageTopicId =
+    getStringProp(inscription, 'topic_id') ||
+    getStringProp(inscription, 'topicId') ||
+    getStringProp(result, 'topicId') ||
+    getStringProp(result, 'topic_id');
+
+  return {
+    jsonTopicId: jsonTopicId,
+    topicId: imageTopicId,
+  };
+}
+
+/**
+ * Build HRL/CDN URLs from extracted topic ids.
+ * - HRL prefers jsonTopicId, falls back to topicId
+ * - CDN URL only provided when jsonTopicId is present
+ */
+export function buildInscriptionLinks(
+  ids: TopicIds,
+  network: NetworkType,
+  fileStandard: string = '1'
+): { hrl?: string; cdnUrl?: string; topicId?: string } {
+  const chosen = ids.jsonTopicId || ids.topicId;
+  const hrl = chosen ? `hcs://${fileStandard}/${chosen}` : undefined;
+  const cdnUrl = ids.jsonTopicId
+    ? `https://kiloscribe.com/api/inscription-cdn/${ids.jsonTopicId}?network=${network}`
+    : undefined;
+  return { hrl, cdnUrl, topicId: chosen };
+}