Amura.Hub.Plugin 1.6.0

Amura Hub Plugin SDK

Amura.Hub.Plugin fornece o Plugin SDK e os contratos compartilhados usados para criar plugins de integração do Amura Hub. Esse pacote segue a versão AmuraHubPluginVersion em Version.props. A linha do SDK segue SemVer estrito: o primeiro breaking release saindo de 0.x sobe para 1.0.0, e o fluxo de release nao aceita saltos arbitrarios de major.

Instalação

dotnet add package Amura.Hub.Plugin

O que o pacote inclui

• Contratos seguros do SDK 1.0 como IIntegrationPlugin, PluginExecutionContext, IPluginOutboundClient e handlers especializados
• Tipos para schema de configuração declarativa
• Definições de integração e alvos de saída declarativos (OutboundTargets)
• DTOs, eventos, serviços de aplicação e contratos de integração consumidos pelos plugins
• Modelos de domínio compartilhados usados pelo runtime e pelos plugins

Modelo de plugin

• O código-fonte dos plugins costuma viver no repositório ~/Projetos/HubPlugins (https://github.com/amura-sistemas/hub-plugins.git).
• O artefato do plugin é distribuído como uma DLL acompanhada de plugin.json
• config.schema.json é opcional e descreve apenas a configuração específica por cliente do plugin
• O host mantém uma configuração global por systemName, visível apenas no painel admin, com BaseUri e Variables
• O plugin pode declarar defaults globais em GlobalConfigurationDefaults e globalConfigurationDefaults
• O host injeta automaticamente na configuração por cliente os campos comuns integrateOrders, publicationType e publishCategories
• O plugin nao registra endpoints HTTP nem workers no host
• Em config.schema.json, secret e password sao aceitos como equivalentes para campos sensiveis; secret continua sendo a forma canonica
• Toda saída externa deve passar por IPluginOutboundClient, usando targetName + relativePath
• O manifesto pode declarar settingsSectionName e outboundTargets para allowlist, auth e timeout
• O plugin é executado pelo Amura.Hub.PluginRunner em processo separado, via gRPC sobre IPC local: Unix domain socket no Linux/macOS e named pipe no Windows
• O pacote NuGet inclui analyzer buildTransitive, falhando o build do plugin quando APIs proibidas forem usadas
• Chaves sensíveis nao sao expostas ao plugin por IPluginSettingsAccessor; o host injeta autenticação quando necessário
• O runtime do host recarrega automaticamente alterações em artefatos de plugin visíveis no storage configurado, sem exigir restart da API

Configuração

• Escopo global do plugin:
  • BaseUri
  • Variables:{name}
• Defaults globais:
  • podem ser declarados em IntegrationDefinition.GlobalConfigurationDefaults
  • podem ser declarados no manifesto plugin.json com globalConfigurationDefaults
  • sao persistidos automaticamente pelo host quando ainda nao existe configuração global salva
• Escopo por cliente:
  • integrateOrders com default true
  • publicationType com default withVariations
  • publishCategories com default false
  • campos específicos declarados pelo plugin em config.schema.json ou IntegrationDefinition
• O host continua aceitando aliases legados persistidos, mas esconde essas duplicatas da UI do cliente.
• O host ainda injeta aliases legados UserAgent e Endpoints:{name} para compatibilidade de runtime.
• ConfigurationFieldType.Secret é o tipo interno canônico; o SDK tambem aceita password na leitura do schema para compatibilidade.

Versionamento

• AmuraHubPluginVersion acompanha tags sdk-vX.Y.Z do repositório host.
• A release local do SDK aceita apenas o próximo passo SemVer direto da última tag; em 0.x, o primeiro breaking release é 1.0.0.

Referências

• Guia do Plugin SDK: https://github.com/amura-sistemas/HubIntegracao/blob/main/docs/plugins/sdk.md
• Schema de configuração: https://github.com/amura-sistemas/HubIntegracao/blob/main/docs/plugins/configuration-schema.md