@hashgraphonline/standards-agent-kit 0.2.131 → 0.2.134

package/dist/es/tools/inscriber/InscribeHashinalTool.d.ts

@@ -1,62 +1,12 @@
 import { z } from 'zod';
 import { BaseInscriberQueryTool } from './base-inscriber-tools';
 import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+import { InscriptionResponse } from '../../types/inscription-response';
+import { FormValidatable } from '../../interfaces/FormValidatable';
 /**
  * Schema for inscribing Hashinal NFT
  */
-declare const inscribeHashinalSchema: z.ZodObject<{
-    url: z.ZodOptional<z.ZodString>;
-    contentRef: z.ZodOptional<z.ZodString>;
-    base64Data: z.ZodOptional<z.ZodString>;
-    fileName: z.ZodOptional<z.ZodString>;
-    mimeType: z.ZodOptional<z.ZodString>;
-    name: z.ZodOptional<z.ZodString>;
-    creator: z.ZodOptional<z.ZodString>;
-    description: z.ZodOptional<z.ZodString>;
-    type: z.ZodOptional<z.ZodString>;
-    attributes: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        trait_type: z.ZodString;
-        value: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
-    }, "strip", z.ZodTypeAny, {
-        value: string | number;
-        trait_type: string;
-    }, {
-        value: string | number;
-        trait_type: string;
-    }>, "many">>;
-    properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    jsonFileURL: z.ZodOptional<z.ZodString>;
-    fileStandard: z.ZodDefault<z.ZodOptional<z.ZodEnum<["1", "6"]>>>;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    chunkSize: z.ZodOptional<z.ZodNumber>;
-    waitForConfirmation: z.ZodOptional<z.ZodBoolean>;
-    timeoutMs: z.ZodOptional<z.ZodNumber>;
-    apiKey: z.ZodOptional<z.ZodString>;
-    quoteOnly: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-}, "strip", z.ZodTypeAny, {
-    quoteOnly: boolean;
-    fileStandard: "1" | "6";
-    url?: string | undefined;
-    type?: string | undefined;
-    name?: string | undefined;
-    description?: string | undefined;
-    tags?: string[] | undefined;
-    creator?: string | undefined;
-    properties?: Record<string, unknown> | undefined;
-    mimeType?: string | undefined;
-    chunkSize?: number | undefined;
-    waitForConfirmation?: boolean | undefined;
-    timeoutMs?: number | undefined;
-    apiKey?: string | undefined;
-    fileName?: string | undefined;
-    base64Data?: string | undefined;
-    attributes?: {
-        value: string | number;
-        trait_type: string;
-    }[] | undefined;
-    contentRef?: string | undefined;
-    jsonFileURL?: string | undefined;
-}, {
+declare const inscribeHashinalSchema: import('../..').ZodSchemaWithRender<{
     url?: string | undefined;
     type?: string | undefined;
     name?: string | undefined;
@@ -68,7 +18,6 @@ declare const inscribeHashinalSchema: z.ZodObject<{
     chunkSize?: number | undefined;
     waitForConfirmation?: boolean | undefined;
     timeoutMs?: number | undefined;
-    apiKey?: string | undefined;
     quoteOnly?: boolean | undefined;
     fileName?: string | undefined;
     base64Data?: string | undefined;
@@ -79,91 +28,92 @@ declare const inscribeHashinalSchema: z.ZodObject<{
     contentRef?: string | undefined;
     jsonFileURL?: string | undefined;
     fileStandard?: "1" | "6" | undefined;
+    withHashLinkBlocks?: boolean | undefined;
+    renderForm?: boolean | undefined;
 }>;
 /**
  * Tool for inscribing Hashinal NFTs
  */
-export declare class InscribeHashinalTool extends BaseInscriberQueryTool<typeof inscribeHashinalSchema> {
+export declare class InscribeHashinalTool extends BaseInscriberQueryTool implements FormValidatable {
     name: string;
     description: string;
-    get specificInputSchema(): z.ZodObject<{
-        url: z.ZodOptional<z.ZodString>;
-        contentRef: z.ZodOptional<z.ZodString>;
-        base64Data: z.ZodOptional<z.ZodString>;
-        fileName: z.ZodOptional<z.ZodString>;
-        mimeType: z.ZodOptional<z.ZodString>;
-        name: z.ZodOptional<z.ZodString>;
-        creator: z.ZodOptional<z.ZodString>;
-        description: z.ZodOptional<z.ZodString>;
-        type: z.ZodOptional<z.ZodString>;
-        attributes: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            trait_type: z.ZodString;
-            value: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
-        }, "strip", z.ZodTypeAny, {
-            value: string | number;
-            trait_type: string;
-        }, {
-            value: string | number;
-            trait_type: string;
-        }>, "many">>;
-        properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        jsonFileURL: z.ZodOptional<z.ZodString>;
-        fileStandard: z.ZodDefault<z.ZodOptional<z.ZodEnum<["1", "6"]>>>;
-        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        chunkSize: z.ZodOptional<z.ZodNumber>;
-        waitForConfirmation: z.ZodOptional<z.ZodBoolean>;
-        timeoutMs: z.ZodOptional<z.ZodNumber>;
-        apiKey: z.ZodOptional<z.ZodString>;
-        quoteOnly: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    }, "strip", z.ZodTypeAny, {
-        quoteOnly: boolean;
-        fileStandard: "1" | "6";
-        url?: string | undefined;
-        type?: string | undefined;
-        name?: string | undefined;
-        description?: string | undefined;
-        tags?: string[] | undefined;
-        creator?: string | undefined;
-        properties?: Record<string, unknown> | undefined;
-        mimeType?: string | undefined;
-        chunkSize?: number | undefined;
-        waitForConfirmation?: boolean | undefined;
-        timeoutMs?: number | undefined;
-        apiKey?: string | undefined;
-        fileName?: string | undefined;
-        base64Data?: string | undefined;
-        attributes?: {
-            value: string | number;
-            trait_type: string;
-        }[] | undefined;
-        contentRef?: string | undefined;
-        jsonFileURL?: string | undefined;
-    }, {
-        url?: string | undefined;
-        type?: string | undefined;
-        name?: string | undefined;
-        description?: string | undefined;
-        tags?: string[] | undefined;
-        creator?: string | undefined;
-        properties?: Record<string, unknown> | undefined;
-        mimeType?: string | undefined;
-        chunkSize?: number | undefined;
-        waitForConfirmation?: boolean | undefined;
-        timeoutMs?: number | undefined;
-        apiKey?: string | undefined;
-        quoteOnly?: boolean | undefined;
-        fileName?: string | undefined;
-        base64Data?: string | undefined;
-        attributes?: {
-            value: string | number;
-            trait_type: string;
-        }[] | undefined;
-        contentRef?: string | undefined;
-        jsonFileURL?: string | undefined;
-        fileStandard?: "1" | "6" | undefined;
-    }>;
-    protected executeQuery(params: z.infer<typeof inscribeHashinalSchema>, _runManager?: CallbackManagerForToolRun): Promise<unknown>;
+    get specificInputSchema(): z.ZodObject<z.ZodRawShape>;
+    private _schemaWithRenderConfig?;
+    get schema(): z.ZodObject<z.ZodRawShape>;
+    /**
+     * Implementation of FormValidatable interface
+     * Determines if a form should be generated for the given input
+     */
+    shouldGenerateForm(input: unknown): boolean;
+    /**
+     * Implementation of FormValidatable interface
+     * Returns the focused schema for form generation
+     */
+    getFormSchema(): z.ZodObject<z.ZodRawShape>;
+    /**
+     * Implementation of FormValidatable interface
+     * Validates metadata quality and provides detailed feedback
+     */
+    validateMetadataQuality(input: unknown): {
+        needsForm: boolean;
+        reason: string;
+    };
+    protected executeQuery(params: z.infer<typeof inscribeHashinalSchema>, _runManager?: CallbackManagerForToolRun): Promise<InscriptionResponse>;
+    /**
+     * Creates HashLink block configuration for Hashinal inscriptions.
+     * Automatically detects network and selects appropriate block ID configuration.
+     * Uses testnet block as fallback for unknown networks or undeployed mainnet blocks.
+     *
+     * @param response The inscription response containing metadata and network information
+     * @param _mimeType Optional MIME type (currently unused, preserved for compatibility)
+     * @returns HCS12BlockResult with network-specific block configuration
+     *
+     * @example
+     * ```typescript
+     * // Testnet usage (automatic detection from client)
+     * const testnetClient = Client.forTestnet();
+     * const tool = new InscribeHashinalTool(testnetClient);
+     * const block = await tool.createHashLinkBlock(inscriptionResponse);
+     * console.log(block.blockId);   // '0.0.6617393'
+     * console.log(block.hashLink);  // 'hcs://12/0.0.6617393'
+     *
+     * // Mainnet usage (automatic detection from client)
+     * const mainnetClient = Client.forMainnet();
+     * const tool = new InscribeHashinalTool(mainnetClient);
+     * const block = await tool.createHashLinkBlock(inscriptionResponse);
+     * console.log(block.blockId);   // Network-specific mainnet block ID
+     *
+     * // HashLink Block Response Structure:
+     * {
+     *   blockId: string;        // Hedera account ID format (e.g., '0.0.6617393')
+     *   hashLink: string;       // HCS-12 URL format: 'hcs://12/{blockId}'
+     *   template: string;       // Block template reference matching blockId
+     *   attributes: {           // Metadata for client-side processing
+     *     name: string;         // Content display name
+     *     creator: string;      // Creator account ID
+     *     topicId: string;      // HCS topic containing the inscription
+     *     hrl: string;          // Hedera Resource Locator
+     *     network: string;      // Network type: 'testnet' | 'mainnet'
+     *   }
+     * }
+     *
+     * // Render function usage in HashLink blocks:
+     * // The block's JavaScript render function receives this structure
+     * // and can access network-specific resources through attributes.network
+     * ```
+     */
+    private createHashLinkBlock;
     private resolveContent;
     private handleDirectContent;
+    /**
+     * Implementation of FormValidatable interface
+     * Returns essential fields that should always be shown in forms
+     */
+    getEssentialFields(): string[];
+    /**
+     * Implementation of FormValidatable interface
+     * Determines if a field value should be considered empty for this tool
+     */
+    isFieldEmpty(fieldName: string, value: unknown): boolean;
 }
 export {};

package/dist/es/tools/inscriber/RetrieveInscriptionTool.d.ts

@@ -14,6 +14,25 @@ declare const retrieveInscriptionSchema: z.ZodObject<{
     transactionId: string;
     apiKey?: string | undefined;
 }>;
+/**
+ * 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,6 +49,6 @@ export declare class RetrieveInscriptionTool extends BaseInscriberQueryTool<type
         transactionId: string;
         apiKey?: string | undefined;
     }>;
-    protected executeQuery(params: z.infer<typeof retrieveInscriptionSchema>, _runManager?: CallbackManagerForToolRun): Promise<unknown>;
+    protected executeQuery(params: z.infer<typeof retrieveInscriptionSchema>, _runManager?: CallbackManagerForToolRun): Promise<InscriptionRetrievalResult>;
 }
 export {};

package/dist/es/types/inscription-response.d.ts

@@ -0,0 +1,172 @@
+/**
+ * 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 declare 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;
+/**
+ * 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 declare function createInscriptionQuote(params: {
+    totalCostHbar: string;
+    validUntil: string;
+    breakdown?: CostBreakdown;
+    content: {
+        name?: string;
+        creator?: string;
+        type?: string;
+    };
+}): InscriptionQuoteResponse;
+/**
+ * Helper function to create an error response
+ */
+export declare function createInscriptionError(params: {
+    code: string;
+    details: string;
+    suggestions?: string[];
+}): InscriptionErrorResponse;
+export {};

package/dist/es/validation/hip412-schemas.d.ts

@@ -122,4 +122,4 @@ export declare const hip412MetadataSchema: z.ZodObject<{
 /**
  * Validates metadata against HIP-412 standard
  */
-export declare function validateHIP412Metadata(metadata: any): z.infer<typeof hip412MetadataSchema>;
+export declare function validateHIP412Metadata(metadata: unknown): z.infer<typeof hip412MetadataSchema>;

package/dist/umd/builders/hcs10/hcs10-builder.d.ts

@@ -87,8 +87,6 @@ export declare class HCS10Builder extends BaseServiceBuilder {
     private standardClient;
     private stateManager;
     private executeResult?;
-    private useEncryption;
-    private guardedRegistryBaseUrl;
     private network;
     private sdkLogger;
     constructor(hederaKit: HederaAgentKit, stateManager?: IStateManager, options?: {

package/dist/umd/builders/inscriber/inscriber-builder.d.ts

@@ -1,20 +1,14 @@
 import { BaseServiceBuilder, HederaAgentKit } from 'hedera-agent-kit';
 import { InscriptionInput, InscriptionOptions, InscriptionResponse, RetrievedInscriptionResult } from '@hashgraphonline/standards-sdk';
+import { InscriptionSDK } from '@kiloscribe/inscription-sdk';
 /**
- * Type definition for DAppSigner since we don't have the actual package
+ * Type definition for DAppSigner interface compatible with inscription SDK
  */
 interface DAppSigner {
     getAccountId(): {
         toString(): string;
     };
-}
-/**
- * Type definition for InscriptionSDK since we don't have the actual package
- */
-interface InscriptionSDK {
-    inscribeAndExecute(request: any, config: any): Promise<any>;
-    inscribe(request: any, signer: any): Promise<any>;
-    waitForInscription(txId: string, maxAttempts: number, intervalMs: number, checkCompletion: boolean, progressCallback?: Function): Promise<any>;
+    [key: string]: unknown;
 }
 /**
  * Builder for Inscription operations
@@ -25,7 +19,7 @@ export declare class InscriberBuilder extends BaseServiceBuilder {
     /**
      * Get or create Inscription SDK - temporarily returns null since we don't have the actual SDK
      */
-    protected getInscriptionSDK(options: InscriptionOptions): Promise<InscriptionSDK | null>;
+    protected getInscriptionSDK(_options: InscriptionOptions): Promise<InscriptionSDK | null>;
     /**
      * Inscribe content using server-side authentication
      */

package/dist/umd/index.d.ts

@@ -2,6 +2,8 @@ export * from './tools';
 export * from './state';
 export * from './init';
 export * from './plugins';
+export * from './lib';
+export * from './interfaces';
 export { HCS10Builder, HCS2Builder, HCS6Builder, InscriberBuilder } from './builders';
 export type { ExecuteResult } from './builders';
 export { HCS10Client } from './hcs10';

package/dist/umd/interfaces/FormValidatable.d.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+/**
+ * Interface for tools that can provide custom form validation logic
+ */
+export interface FormValidatable {
+    /**
+     * Determines if a form should be generated for the given input
+     * @param input The input data to validate
+     * @returns true if a form should be generated, false if the tool can execute
+     */
+    shouldGenerateForm(input: unknown): boolean;
+    /**
+     * Returns the schema to use for form generation
+     * This allows tools to provide a focused schema for forms
+     * @returns The schema to use for generating forms
+     */
+    getFormSchema(): z.ZodSchema;
+    /**
+     * Optional method to validate metadata quality and provide detailed feedback
+     * @param input The input data to analyze
+     * @returns Object indicating if form is needed and the reason
+     */
+    validateMetadataQuality?(input: unknown): {
+        needsForm: boolean;
+        reason: string;
+    };
+    /**
+     * Optional method to define which fields are essential for this tool
+     * Essential fields are always shown in forms even if marked as optional
+     * @returns Array of field names that are essential for user experience
+     */
+    getEssentialFields?(): string[];
+    /**
+     * Optional method to determine if a field value should be considered empty
+     * Allows tools to define custom empty logic for their specific data types
+     * @param fieldName The name of the field
+     * @param value The value to check
+     * @returns true if the field should be considered empty
+     */
+    isFieldEmpty?(fieldName: string, value: unknown): boolean;
+}
+/**
+ * Type guard to check if a tool implements FormValidatable
+ */
+export declare function isFormValidatable(tool: unknown): tool is FormValidatable;

package/dist/umd/interfaces/index.d.ts

@@ -0,0 +1 @@
+export * from './FormValidatable';

package/dist/umd/lib/index.d.ts

@@ -0,0 +1 @@
+export * from './zod-render';

package/dist/umd/lib/zod-render/config-extractor.d.ts

@@ -0,0 +1,50 @@
+import { ZodType } from 'zod';
+import { RenderConfigSchema, ExtractedRenderConfig, FieldMetadata, FormFieldType } from './types';
+/**
+ * Type definition for field config map entries
+ */
+interface FieldConfigMapEntry {
+    renderConfig: RenderConfigSchema;
+    metadata: FieldMetadata;
+    path: string[];
+}
+/**
+ * Type definition for simple field configuration
+ */
+interface SimpleFieldConfig {
+    name: string;
+    type: FormFieldType;
+    label: string;
+    required: boolean;
+    placeholder?: string;
+    options?: Array<{
+        value: unknown;
+        label: string;
+    }>;
+}
+/**
+ * Extracts render configurations from a Zod schema and all nested schemas
+ */
+export declare function extractRenderConfigs(schema: ZodType<unknown>): ExtractedRenderConfig;
+/**
+ * Generates field ordering metadata for complex forms
+ */
+export declare function generateFieldOrdering(schema: ZodType<unknown>): {
+    sections: Record<string, {
+        title: string;
+        fields: string[];
+        order: number;
+    }>;
+    fieldOrder: string[];
+};
+/**
+ * Creates a field configuration map for form builders
+ */
+export declare function createFieldConfigMap(schema: ZodType<unknown>): Record<string, FieldConfigMapEntry>;
+/**
+ * Creates a simplified configuration for basic form rendering
+ */
+export declare function createSimpleConfig(schema: ZodType<unknown>): {
+    fields: Array<SimpleFieldConfig>;
+};
+export {};

package/dist/umd/lib/zod-render/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types';
+export * from './schema-extension';
+export * from './config-extractor';
+export { extendZodSchema, hasRenderConfig, getRenderConfig, renderConfigs } from './schema-extension';
+export { extractRenderConfigs, generateFieldOrdering, createFieldConfigMap, createSimpleConfig } from './config-extractor';
+export type { FormFieldType, RenderContext, RenderFunction, RenderConfigSchema, ZodSchemaWithRender, FormGenerationOptions, ValidationError, FormState, FormActions, UseFormReturn, ComponentRegistry, FieldComponentProps, SelectOption, FileUploadResult, FieldMetadata, ExtractedRenderConfig } from './types';