@hashgraphonline/standards-agent-kit 0.2.127 → 0.2.129

package/src/utils/content-resolver.ts

@@ -0,0 +1,87 @@
+import { ContentResolverRegistry } from '@hashgraphonline/standards-sdk';
+
+export interface ContentResolutionResult {
+  buffer: Buffer;
+  mimeType?: string;
+  fileName?: string;
+  wasReference?: boolean;
+}
+
+/**
+ * Resolves content from various input formats (content-ref, base64, plain text)
+ */
+export async function resolveContent(
+  input: string,
+  providedMimeType?: string,
+  providedFileName?: string
+): Promise<ContentResolutionResult> {
+  const trimmedInput = input.trim();
+
+  const resolver = ContentResolverRegistry.getResolver();
+
+  if (!resolver) {
+    return handleDirectContent(
+      trimmedInput,
+      providedMimeType,
+      providedFileName
+    );
+  }
+
+  const referenceId = resolver.extractReferenceId(trimmedInput);
+
+  if (referenceId) {
+    try {
+      const resolution = await resolver.resolveReference(referenceId);
+
+      return {
+        buffer: resolution.content,
+        mimeType: resolution.metadata?.mimeType || providedMimeType,
+        fileName: resolution.metadata?.fileName || providedFileName,
+        wasReference: true,
+      };
+    } catch (error) {
+      const errorMsg =
+        error instanceof Error
+          ? error.message
+          : 'Unknown error resolving reference';
+      throw new Error(`Reference resolution failed: ${errorMsg}`);
+    }
+  }
+
+  return handleDirectContent(trimmedInput, providedMimeType, providedFileName);
+}
+
+/**
+ * Handles direct content (base64 or plain text)
+ */
+function handleDirectContent(
+  input: string,
+  providedMimeType?: string,
+  providedFileName?: string
+): ContentResolutionResult {
+  const isValidBase64 = /^[A-Za-z0-9+/]*={0,2}$/.test(input);
+
+  if (isValidBase64) {
+    try {
+      const buffer = Buffer.from(input, 'base64');
+      return {
+        buffer,
+        mimeType: providedMimeType,
+        fileName: providedFileName,
+        wasReference: false,
+      };
+    } catch (error) {
+      throw new Error(
+        'Failed to decode base64 data. Please ensure the data is properly encoded.'
+      );
+    }
+  }
+
+  const buffer = Buffer.from(input, 'utf8');
+  return {
+    buffer,
+    mimeType: providedMimeType || 'text/plain',
+    fileName: providedFileName,
+    wasReference: false,
+  };
+}

package/src/utils/metadata-defaults.ts

@@ -0,0 +1,25 @@
+/**
+ * Generates default metadata for NFT inscription
+ */
+export function generateDefaultMetadata(params: {
+  name?: string;
+  creator?: string;
+  description?: string;
+  type?: string;
+  fileName?: string;
+  mimeType?: string;
+  operatorAccount: 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';
+
+  return {
+    name: params.name || defaultName,
+    creator: params.creator || params.operatorAccount,
+    description: params.description || `${defaultType.charAt(0).toUpperCase() + defaultType.slice(1)} NFT inscribed as Hashinal`,
+    type: params.type || defaultType,
+    image: '',
+  };
+}

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

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+
+/**
+ * Validates content reference format
+ */
+export const contentRefSchema = z
+  .string()
+  .regex(/^content-ref:[a-fA-F0-9]{64}$/, 'Content reference must be in format "content-ref:[64-char hex]"')
+  .describe('Content reference in format "content-ref:[id]"');
+
+/**
+ * Validates content reference or returns error for dumber models
+ */
+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}"`);
+  }
+}

package/src/validation/hip412-schemas.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+
+/**
+ * HIP-412 file schema for multi-file NFTs
+ */
+export const hip412FileSchema = z.object({
+  uri: z.string().describe('URI of the file'),
+  checksum: z.string().optional().describe('SHA-256 checksum of the file'),
+  is_default_file: z.boolean().optional().describe('Whether this is the default file'),
+  type: z.string().describe('MIME type of the file'),
+});
+
+/**
+ * HIP-412 attribute schema for NFT traits
+ */
+export const hip412AttributeSchema = z.object({
+  trait_type: z.string().describe('The trait type'),
+  value: z.union([z.string(), z.number()]).describe('The trait value'),
+  display_type: z.string().optional().describe('Display type for the attribute'),
+});
+
+/**
+ * HIP-412 compliant metadata schema for Hedera NFTs
+ */
+export const hip412MetadataSchema = z.object({
+  name: z.string().describe('Token name (required by HIP-412)'),
+  description: z.string().describe('Human readable description (required by HIP-412)'),
+  image: z.string().describe('Preview image URI (required by HIP-412)'),
+  type: z.string().describe('MIME type (required by HIP-412)'),
+  creator: z.string().optional().describe('Creator name or comma-separated names'),
+  creatorDID: z.string().optional().describe('Decentralized identifier for creator'),
+  checksum: z.string().optional().describe('SHA-256 checksum of the image'),
+  format: z.string().optional().default('HIP412@2.0.0').describe('Metadata format version'),
+  files: z.array(hip412FileSchema).optional().describe('Array of files for multi-file NFTs'),
+  attributes: z.array(hip412AttributeSchema).optional().describe('NFT attributes/traits'),
+  properties: z.record(z.unknown()).optional().describe('Additional properties'),
+});
+
+/**
+ * Validates metadata against HIP-412 standard
+ */
+export function validateHIP412Metadata(metadata: any): z.infer<typeof hip412MetadataSchema> {
+  try {
+    return hip412MetadataSchema.parse(metadata);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      const issues = error.errors.map(err => `${err.path.join('.')}: ${err.message}`).join('; ');
+      throw new Error(`HIP-412 metadata validation failed: ${issues}`);
+    }
+    throw error;
+  }
+}