@lukso/transaction-decoder 1.0.1-dev.0f1bea5

package/src/decoder/registry.ts

@@ -0,0 +1,322 @@
+import type { Hex } from 'viem'
+import type { DecoderPlugin, Info, SchemaPlugin } from './types'
+
+/**
+ * Plugin metadata for registry
+ */
+export interface PluginMetadata {
+  name: string
+  plugin: DecoderPlugin
+  priority?: number
+  required?: boolean // Cannot be overridden, always runs first
+  description?: string
+  version?: string
+  usesAsync?: boolean // Whether this plugin performs async operations
+}
+
+/**
+ * Schema plugin metadata
+ */
+export interface SchemaPluginMetadata {
+  name: string
+  plugin: SchemaPlugin
+  priority?: number
+  required?: boolean // Cannot be overridden, always runs first
+  description?: string
+  version?: string
+}
+
+/**
+ * Global plugin registry for auto-registration
+ */
+class PluginRegistry {
+  private plugins: Map<string, PluginMetadata> = new Map()
+  private schemaPlugins: Map<string, SchemaPluginMetadata> = new Map()
+
+  /**
+   * Register a decoder plugin
+   * @param name - Unique plugin name
+   * @param plugin - Plugin instance
+   * @param options - Registration options
+   */
+  register(
+    name: string,
+    plugin: DecoderPlugin,
+    options?: {
+      priority?: number
+      required?: boolean
+      override?: boolean
+      description?: string
+      version?: string
+      usesAsync?: boolean
+    }
+  ): void {
+    const {
+      override = false,
+      priority = 0,
+      required = false,
+      description,
+      version,
+      usesAsync = false,
+    } = options || {}
+
+    const existing = this.plugins.get(name)
+
+    if (existing) {
+      if (existing.required) {
+        console.error(
+          `Plugin "${name}" is marked as required and cannot be overridden.`
+        )
+        return
+      }
+      if (!override) {
+        console.warn(
+          `Plugin "${name}" is already registered. Use override: true to replace.`
+        )
+        return
+      }
+    }
+
+    this.plugins.set(name, {
+      name,
+      plugin: Object.freeze(plugin),
+      priority,
+      required,
+      description,
+      version,
+      usesAsync,
+    })
+  }
+
+  /**
+   * Register a schema plugin
+   * @param name - Unique plugin name
+   * @param plugin - Schema plugin instance
+   * @param options - Registration options
+   */
+  registerSchema(
+    name: string,
+    plugin: SchemaPlugin,
+    options?: {
+      priority?: number
+      required?: boolean
+      override?: boolean
+      description?: string
+      version?: string
+    }
+  ): void {
+    const {
+      override = false,
+      priority = 0,
+      required = false,
+      description,
+      version,
+    } = options || {}
+
+    const existing = this.schemaPlugins.get(name)
+
+    if (existing) {
+      if (existing.required) {
+        console.error(
+          `Schema plugin "${name}" is marked as required and cannot be overridden.`
+        )
+        return
+      }
+      if (!override) {
+        console.warn(
+          `Schema plugin "${name}" is already registered. Use override: true to replace.`
+        )
+        return
+      }
+    }
+
+    this.schemaPlugins.set(name, {
+      name,
+      plugin: Object.freeze(plugin),
+      priority,
+      required,
+      description,
+      version,
+    })
+  }
+
+  /**
+   * Unregister a plugin
+   */
+  unregister(name: string): boolean {
+    return this.plugins.delete(name)
+  }
+
+  /**
+   * Get all registered decoder plugins (excluding overridden ones)
+   * @param options - Filter options
+   */
+  async getAll(options?: {
+    excludeNames?: string[]
+    syncOnly?: boolean
+  }): Promise<DecoderPlugin[]> {
+    const { excludeNames = [], syncOnly = false } = options || {}
+    const exclude = new Set(excludeNames)
+    let plugins = Array.from(this.plugins.values())
+
+    // Filter by syncOnly if requested
+    if (syncOnly) {
+      plugins = plugins.filter((meta) => !meta.usesAsync)
+    }
+
+    // Check if any required plugins are being excluded
+    for (const name of exclude) {
+      const plugin = this.plugins.get(name)
+      if (plugin?.required) {
+        console.warn(
+          `Warning: Plugin "${name}" is required and cannot be excluded. It will run first.`
+        )
+      }
+    }
+
+    // Separate required and optional plugins
+    return plugins
+      .sort((a, b) => (b.priority || 0) - (a.priority || 0))
+      .map(({ plugin }) => plugin)
+  }
+
+  /**
+   * Get all schema plugins (excluding overridden ones)
+   * @param excludeNames - Plugin names to exclude
+   */
+  getAllSchema(excludeNames?: string[]): SchemaPlugin[] {
+    const exclude = new Set(excludeNames || [])
+    const plugins = Array.from(this.schemaPlugins.values())
+
+    // Check if any required plugins are being excluded
+    for (const name of exclude) {
+      const plugin = this.schemaPlugins.get(name)
+      if (plugin?.required) {
+        console.warn(
+          `Warning: Schema plugin "${name}" is required and cannot be excluded. It will run first.`
+        )
+      }
+    }
+
+    // Separate required and optional plugins
+    const required = plugins
+      .filter((meta) => meta.required)
+      .sort((a, b) => (b.priority || 0) - (a.priority || 0))
+
+    const optional = plugins
+      .filter((meta) => !meta.required && !exclude.has(meta.name))
+      .sort((a, b) => (b.priority || 0) - (a.priority || 0))
+
+    // Required plugins always come first, then optional ones
+    return [...required, ...optional].map((meta) => meta.plugin)
+  }
+
+  /**
+   * Get a specific plugin by name
+   */
+  async get(name: string): Promise<DecoderPlugin | undefined> {
+    const meta = this.plugins.get(name)
+    return meta?.plugin
+  }
+
+  /**
+   * Get plugin metadata
+   */
+  getMetadata(name: string): PluginMetadata | undefined {
+    return this.plugins.get(name)
+  }
+
+  /**
+   * Get schema plugin metadata
+   */
+  getSchemaMetadata(name: string): SchemaPluginMetadata | undefined {
+    return this.schemaPlugins.get(name)
+  }
+
+  /**
+   * Check if a plugin is registered
+   */
+  has(name: string): boolean {
+    return this.plugins.has(name)
+  }
+
+  /**
+   * Clear all plugins
+   */
+  clear(): void {
+    this.plugins.clear()
+    this.schemaPlugins.clear()
+  }
+
+  /**
+   * Get the number of registered plugins
+   */
+  get size(): number {
+    return this.plugins.size + this.schemaPlugins.size
+  }
+
+  /**
+   * List all registered plugins with metadata
+   */
+  list(): { plugins: PluginMetadata[]; schemaPlugins: SchemaPluginMetadata[] } {
+    return {
+      plugins: Array.from(this.plugins.values()),
+      schemaPlugins: Array.from(this.schemaPlugins.values()),
+    }
+  }
+}
+
+// Freeze the PluginRegistry prototype to prevent modifications
+Object.freeze(PluginRegistry.prototype)
+Object.freeze(PluginRegistry)
+
+// Global singleton instance
+export const pluginRegistry = new PluginRegistry()
+
+// Convenience function for plugin authors
+export function registerPlugin(
+  name: string,
+  plugin: DecoderPlugin,
+  options?: {
+    priority?: number
+    required?: boolean
+    override?: boolean
+    description?: string
+    version?: string
+    usesAsync?: boolean
+  }
+): void {
+  pluginRegistry.register(name, plugin, options)
+}
+
+// Convenience function for schema plugin authors
+export function registerSchemaPlugin(
+  name: string,
+  plugin: SchemaPlugin,
+  options?: {
+    priority?: number
+    required?: boolean
+    override?: boolean
+    description?: string
+    version?: string
+  }
+): void {
+  pluginRegistry.registerSchema(name, plugin, options)
+}
+
+// Helper to create a named schema plugin
+export function createNamedSchemaPlugin(
+  name: string,
+  plugin: (key: Hex, value: Hex) => Promise<Info | undefined>
+): SchemaPlugin {
+  const namedPlugin = Object.assign(plugin, { name })
+  return namedPlugin as SchemaPlugin
+}
+
+// Helper to create a named decoder plugin
+export function createNamedPlugin(
+  name: string,
+  plugin: Omit<DecoderPlugin, 'name'>
+): DecoderPlugin {
+  return { ...plugin, name }
+}

package/src/decoder/singleGQL.ts

@@ -0,0 +1,293 @@
+import request, { gql } from 'graphql-request'
+import { type Address, type Chain, getAddress } from 'viem'
+import { lukso } from 'viem/chains'
+import type { EnhancedInfo } from '../types'
+import { getWSClient } from './graphqlWS'
+
+/**
+ * Get controllers from a set of profile addresses
+ */
+const singleProfileControllersGql = gql`
+  query MyQuery($profileAddress: String = "") {
+    Profile_by_pk(id: $profileAddress) {
+      controllers {
+        address
+        tags
+        permissions
+      }
+    }
+  }
+`
+
+/**
+ * Get a single profile from it's address
+ */
+const singleProfileGql = gql`
+  query MyQuery($profileAddress: String = "") {
+    Profile_by_pk(id: $profileAddress) {
+      fullName
+      id
+      name
+      tags
+      description
+      links {
+        title
+        url
+      }
+      profileImages(
+        where: { error: { _is_null: true } }
+        order_by: { width: asc }
+      ) {
+        width
+        src
+        verified
+      }
+      backgroundImages(
+        where: { error: { _is_null: true } }
+        order_by: { width: asc }
+      ) {
+        width
+        src
+        verified
+      }
+      avatars(where: { error: { _is_null: true } }, order_by: { width: asc }) {
+        width
+        src
+        verified
+      }
+      followed {
+        follower {
+          id
+          name
+        }
+      }
+      followed_aggregate {
+        aggregate {
+          count
+        }
+      }
+      following_aggregate {
+        aggregate {
+          count
+        }
+      }
+      following {
+        followee {
+          id
+          name
+        }
+      }
+      controllers {
+        address
+        tags
+        permissions
+      }
+    }
+  }
+`
+
+/**
+ * Subscribe to a single profile by it's address
+ */
+const singleProfileGqlSub = gql`
+  subscription MyQuery($profileAddress: String = "") {
+    Profile_by_pk(id: $profileAddress) {
+      fullName
+      id
+      name
+      tags
+      description
+      links {
+        title
+        url
+      }
+      profileImages(
+        where: { error: { _is_null: true } }
+        order_by: { width: asc }
+      ) {
+        width
+        src
+        verified
+      }
+      backgroundImages(
+        where: { error: { _is_null: true } }
+        order_by: { width: asc }
+      ) {
+        width
+        src
+        verified
+      }
+      avatars(where: { error: { _is_null: true } }, order_by: { width: asc }) {
+        width
+        src
+        verified
+      }
+      followed {
+        follower {
+          id
+          name
+        }
+      }
+      followed_aggregate {
+        aggregate {
+          count
+        }
+      }
+      following_aggregate {
+        aggregate {
+          count
+        }
+      }
+      following {
+        followee {
+          id
+          name
+        }
+      }
+      controllers {
+        address
+        tags
+        permissions
+      }
+    }
+  }
+`
+
+export type SubscribeResponse = {
+  data: {
+    Profile_by_pk: Record<string, unknown>
+  }
+}
+
+/**
+ * Subscribe to profile by it's address
+ *
+ * @param chain which chain to use
+ * @param address the address of the profile
+ * @param profile callback to receive the profile data
+ * @returns
+ */
+export function subscribeToProfile(
+  chain: Chain,
+  address: Address,
+  profile?: (data: EnhancedInfo) => void
+) {
+  const wsClient = getWSClient(chain)
+  let current = undefined as EnhancedInfo | undefined
+  return wsClient.subscribe(
+    {
+      query: singleProfileGqlSub,
+      variables: { profileAddress: address.toLowerCase() },
+    },
+    {
+      next: async (data: SubscribeResponse) => {
+        const { data: response } = data
+        const { Profile_by_pk: prof } = response as {
+          Profile_by_pk: Record<string, unknown>
+        }
+        const {
+          id,
+          backgroundImages,
+          profileImages,
+          avatars,
+          links,
+          tags,
+          controllers,
+          ...rest
+        } = prof || {}
+        if (!id) {
+          console.error('Profile not found')
+          return
+        }
+        const result = {
+          address: getAddress(id as string),
+          backgroundImage: backgroundImages || [],
+          profileImage: profileImages || [],
+          avatar: avatars || [],
+          tags: tags || [],
+          links: links || [],
+          ...rest,
+        } as EnhancedInfo
+        if (!current || JSON.stringify(current) !== JSON.stringify(result)) {
+          profile?.(result)
+          current = result
+        }
+      },
+      error: (err: unknown) => {
+        console.error('Subscription error:', err)
+      },
+      complete: () => {},
+    }
+  )
+}
+
+/**
+ * Fetch the controllers for a profile address
+ *
+ * @param chain which chain to use
+ * @param address which profile to fetch
+ * @returns a list of controller addresses
+ */
+export async function fetchProfileControllers(
+  chain: Chain,
+  address: Address
+): Promise<`0x${string}`[]> {
+  const response: {
+    Profile_by_pk: {
+      controllers?: { address: `0x${string}`; tags: string[] }[]
+    }
+  } = await request(
+    chain.id === lukso.id
+      ? 'https://envio.lukso-mainnet.universal.tech/v1/graphql'
+      : 'https://envio.lukso-testnet.universal.tech/v1/graphql',
+    singleProfileControllersGql,
+    {
+      profileAddress: address.toLowerCase(),
+    }
+  )
+  const { Profile_by_pk: { controllers = [] } = {} } = response
+  return controllers
+    .filter((c) => !c.tags?.includes('ISRECOVERY'))
+    .map((C) => C.address)
+}
+
+export async function fetchProfile(
+  chain: Chain,
+  address: Address
+): Promise<EnhancedInfo> {
+  const response: {
+    Profile_by_pk: Record<string, unknown>
+  } = await request(
+    chain.id === lukso.id
+      ? 'https://envio.lukso-mainnet.universal.tech/v1/graphql'
+      : 'https://envio.lukso-testnet.universal.tech/v1/graphql',
+    singleProfileGql,
+    {
+      profileAddress: address.toLowerCase(),
+    }
+  )
+  const { Profile_by_pk: profile } = response
+  const {
+    id,
+    backgroundImages,
+    profileImages,
+    avatars,
+    links,
+    tags,
+    controllers,
+    ...rest
+  } = profile || {}
+  if (!id) {
+    throw new Error('Profile not found')
+  }
+  return {
+    address: getAddress(id as string),
+    backgroundImage: backgroundImages || [],
+    profileImage: profileImages || [],
+    avatar: avatars || [],
+    tags: tags || [],
+    links: links || [],
+    ...rest,
+    __gqltype: 'Profile',
+  } as EnhancedInfo
+}