@hashgraphonline/standards-agent-kit 0.2.136 → 0.2.138

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,8 +51,9 @@ 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) {
+function getHashLinkBlockId(
+  network: 'mainnet' | 'testnet',
+): { blockId: string; hashLink: string; template: string } {
   const config =
     network === 'mainnet'
       ? HASHLINK_BLOCK_CONFIG.mainnet
@@ -58,8 +64,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 +209,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 +353,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)'
           ),
@@ -523,173 +523,54 @@ 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 network = options.network || 'testnet';
-
-        const cdnUrl = jsonTopicId
-          ? `https://kiloscribe.com/api/inscription-cdn/${jsonTopicId}?network=${network}`
-          : null;
-
+        const ids = extractTopicIds(result.inscription, result.result);
+        const network = (options.network || 'testnet') as 'mainnet' | 'testnet';
         const fileStandard = params.fileStandard || '1';
-        const hrl = jsonTopicId ? `hcs://${fileStandard}/${jsonTopicId}` : null;
-        const standardType = fileStandard === '6' ? 'Dynamic' : 'Static';
-
-        if (!hrl) {
-          return createInscriptionError({
-            code: 'MISSING_TOPIC_ID',
-            details: 'Inscription completed but topic ID is missing',
-            suggestions: [
-              'Try the inscription again',
-              'Contact support if the issue persists',
-            ],
-          });
-        }
-
-        const inscriptionResponse = createInscriptionSuccess({
-          hrl,
-          topicId: jsonTopicId || imageTopicId || 'unknown',
-          standard: standardType as 'Static' | 'Dynamic',
-          cdnUrl: cdnUrl || undefined,
-          transactionId: (result.result as { transactionId?: string })
-            ?.transactionId,
+        const { hrl, topicId, cdnUrl } = buildInscriptionLinks(
+          ids,
+          network,
+          fileStandard
+        );
+
+        const txId = (result.result as InscriptionResult)?.transactionId ?? 'unknown';
+        return createInscriptionSuccess({
+          hrl: hrl || 'hcs://1/unknown',
+          topicId: topicId || 'unknown',
+          standard: fileStandard === '6' ? 'Dynamic' : 'Static',
+          cdnUrl,
+          transactionId: txId,
           metadata: {
             name: params.name,
             creator: params.creator,
             description: params.description,
             type: params.type,
-            attributes: params.attributes,
+            attributes: Array.isArray(params.attributes) ? params.attributes : [],
           },
         });
-
-        this.onEntityCreated?.({
-          entityId: jsonTopicId || imageTopicId || 'unknown',
-          entityName: params.name || 'Unnamed Inscription',
-          entityType: 'topicId',
-          transactionId: (result.result as { transactionId?: string })
-            ?.transactionId,
-        });
-
-        if (params.withHashLinkBlocks) {
-          try {
-            const blockData = await this.createHashLinkBlock(
-              inscriptionResponse,
-              inscriptionData.type === 'buffer'
-                ? inscriptionData.mimeType
-                : undefined
-            );
-
-            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,
-            });
-          }
-        }
-
-        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 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 standardType = fileStandard === '6' ? 'Dynamic' : 'Static';
-
-          if (hrl) {
-            const inscriptionResponse = createInscriptionSuccess({
-              hrl,
-              topicId: jsonTopicId || imageTopicId || 'unknown',
-              standard: standardType as 'Static' | 'Dynamic',
-              cdnUrl: cdnUrl || undefined,
-              transactionId: (result.result as { transactionId?: string })
-                ?.transactionId,
-              metadata: {
-                name: params.name,
-                creator: params.creator,
-                description: params.description,
-                type: params.type,
-                attributes: params.attributes,
-              },
-            });
-
-            this.onEntityCreated?.({
-              entityId: jsonTopicId || imageTopicId || 'unknown',
-              entityName: params.name || 'Unnamed Inscription',
-              entityType: 'topicId',
-              transactionId: (result.result as { transactionId?: string })
-                ?.transactionId,
-            });
-
-            if (params.withHashLinkBlocks) {
-              try {
-                const blockData = await this.createHashLinkBlock(
-                  inscriptionResponse,
-                  inscriptionData.type === 'buffer'
-                    ? inscriptionData.mimeType
-                    : undefined
-                );
-
-                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,
-                });
-              }
-            }
-
-            return inscriptionResponse;
-          }
-        }
-
-        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",
-          ],
+        const txId = (result.result as InscriptionResult)?.transactionId ?? 'unknown';
+        return createInscriptionPending({
+          transactionId: txId,
+          details:
+            'Successfully submitted Hashinal inscription. Waiting for network confirmation...'
         });
       } else {
         return createInscriptionError({
-          code: 'UNKNOWN_STATE',
-          details: 'Inscription completed but result state is unclear',
-          suggestions: [
-            'Check if the inscription was successful manually',
-            'Try the inscription again',
-          ],
+          code: 'UNEXPECTED_RESULT',
+          details: 'Received an unexpected inscription result state',
+          suggestions: ['Try again or verify network status']
         });
       }
     } catch (error) {
@@ -697,16 +578,7 @@ export class InscribeHashinalTool
         error instanceof Error
           ? error.message
           : 'Failed to inscribe Hashinal NFT';
-      return createInscriptionError({
-        code: 'INSCRIPTION_FAILED',
-        details: `Inscription failed: ${errorMessage}`,
-        suggestions: [
-          'Check network connectivity',
-          'Verify you have sufficient HBAR balance',
-          'Ensure content is accessible and valid',
-          'Try again in a moment',
-        ],
-      });
+      throw new Error(`Inscription failed: ${errorMessage}`);
     }
   }
 

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/types/tx-results.ts

@@ -0,0 +1,18 @@
+import type { TopicRegistrationResponse, RegistryOperationResponse, HCS6TopicRegistrationResponse, HCS6RegistryOperationResponse, HCS6CreateHashinalResponse } from '@hashgraphonline/standards-sdk';
+
+export interface WalletBytesResponse {
+  success: true;
+  transactionBytes: string;
+}
+
+export function isWalletBytesResponse(value: unknown): value is WalletBytesResponse {
+  return !!value && typeof (value as any).transactionBytes === 'string';
+}
+
+export type TopicRegistrationResult = TopicRegistrationResponse | WalletBytesResponse;
+export type RegistryOperationResult = RegistryOperationResponse | WalletBytesResponse;
+export type SubmitMessageResult = { success: true; transactionId?: string } | WalletBytesResponse;
+
+export type HCS6TopicRegistrationResult = HCS6TopicRegistrationResponse | WalletBytesResponse;
+export type HCS6RegistryOperationResult = HCS6RegistryOperationResponse | WalletBytesResponse;
+export type HCS6CreateHashinalResult = HCS6CreateHashinalResponse | WalletBytesResponse;

package/src/utils/CodedError.ts

@@ -0,0 +1,8 @@
+export class CodedError extends Error {
+  code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.code = code;
+    Object.setPrototypeOf(this, CodedError.prototype);
+  }
+}

package/src/utils/Encryption.ts

@@ -6,11 +6,9 @@
  */
 
 export function encryptMessage(message: string): string {
-    // TODO: Add encryption logic here if useEncryption flag is true.
     return message; // currently returns plaintext.
 }
 
 export function decryptMessage(encryptedMessage: string): string {
-    // TODO: Add decryption logic here.
     return encryptedMessage;
 }

package/src/utils/ensure-agent-has-hbar.ts

@@ -1,4 +1,4 @@
-import { Hbar, TransferTransaction, Client } from "@hashgraph/sdk";
+import { Hbar, TransferTransaction } from "@hashgraph/sdk";
 import { Logger, HCS10Client, HederaMirrorNode } from "@hashgraphonline/standards-sdk";
 
 export const MIN_REQUIRED_USD = 2.0;
@@ -58,10 +58,9 @@ export async function ensureAgentHasEnoughHbar(
                 )} HBAR from ${funder.accountId}`
               );
 
-              const fundTxResponse = await transferTx.execute(
-                baseClient.getClient() as Client
-              );
-              await fundTxResponse.getReceipt(baseClient.getClient() as Client);
+              const clientAny: any = baseClient.getClient();
+              const fundTxResponse = await transferTx.execute(clientAny);
+              await fundTxResponse.getReceipt(clientAny);
               logger.info(
                 `Successfully funded ${agentName} account ${accountId}.`
               );

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 };
+}