Kit de desenvolvimento (SDK TypeScript)

cliente tipado gerado dos próprios documentos openapi do erp ele monta os cabeçalhos, devolve objetos com campos nomeados e traduz a recusa por permissão num erro que dá para tratar fica em sdk/ no repositório do projeto, com a saída versionada — um integrador em rede restrita não precisa rodar o gerador, e a revisão enxerga num diff o que mudou no contrato além disso é publicado no registro privado (nexus) como @erp/integration sdk, para que runtimes de personalização o consumam por npm install (é assim que o low code faas o usa) as duas formas coexistem a saída continua versionada no repo e distribuída pelo nexus instalar para desenvolver o próprio sdk (a partir do repositório) cd sdk/typescript npm install npm run typecheck para consumir de outro projeto (via nexus), aponte o escopo @erp para o registro privado no npmrc e instale o pacote \# npmrc do projeto consumidor \# @erp\ registry=https //nexus centralit io/repository/npm private/ npm install @erp/integration sdk a publicação roda o build antes (prepublishonly), emitindo dist/ (javascript + tipos); o pacote entrega só dist/ primeira chamada cada seção é um pacote gerado independente, com a sua própria classe configuration monte a configuração a partir da seção que você vai chamar import { configuration, partnercontrollerapi } from " /generated/registry"; import { erpconfiguration } from " /src/client"; const config = new configuration( erpconfiguration({ baseurl "https //erp exemplo gov br", appkey process env erp app key!, tenantid process env erp tenant id!, }), ); const parceiros = await new partnercontrollerapi(config) partnercontrollerfindall({ pageable { page 0, size 20 } }); os dois cabeçalhos são anexados automaticamente coleções exigem pageable — não é opcional o cliente gerado recusa a chamada sem ele em vez de arbitrar um tamanho de página, e o compilador acusa antes de você rodar este exemplo em particular é ilustrativo partnercontrollerfindall está hoje entre as leituras sem escopo declarado , logo fechada para chave de integração consulte o catálogo de operações docid 825w6ivxqiy 5f88z8ubi antes de escolher a operação por onde começar achar um parceiro pelo cnpj o identificador que um sistema externo tem em mãos é o documento fiscal , nunca o uuid interno do erp por isso existe uma busca direta — antes dela, a única saída era paginar o cadastro inteiro e comparar do lado do integrador import { configuration, partnercontrollerapi } from " /generated/registry"; const api = new partnercontrollerapi(config); try { const parceiro = await api partnercontrollerfindbytaxid({ taxid "16653547000126" }); console log(parceiro id, parceiro name); } catch (e) { // 404 = esse documento não está cadastrado é uma resposta, não uma falha // é exatamente o que responder à pergunta "essa empresa já existe aqui?" } a pontuação é irrelevante — 16 653 547/0001 26 e 16653547000126 chegam ao mesmo parceiro, porque o documento é normalizado do mesmo jeito na gravação e na consulta filtrar uma lista por texto as listagens aceitam um termo livre em q , aplicado aos campos que a tela correspondente mostra (nome, razão social, documento, número do documento, conforme o recurso) const achados = await api partnercontrollerfindall({ q "fixtu", pageable { page 0, size 20 }, }); query continua valendo vários recursos publicaram esse termo como query antes de q existir, e nenhum cliente gerado contra o nome antigo precisa mudar os dois nomes são aceitos e apontam para o mesmo filtro quando os dois chegam, q vence termo em branco significa sem filtro — não "casar string vazia" tratar a recusa por permissão import { erpconfiguration, erpforbiddenerror } from " /src/client"; try { await new partnercontrollerapi(config) partnercontrollerfindall({ pageable { page 0, size 20 } }); } catch (erro) { if (erro instanceof erpforbiddenerror) { // a chave é válida; ela é que não abre esta operação // repetir não resolve — ver docs/dev/02 autenticacao md console error(erro message); return; } throw erro; // rede, indisponibilidade, erro de negócio } erpforbiddenerror nomeia, na própria mensagem, as três causas possíveis de 403, porque cada uma pede uma ação diferente chamar outra área a mesma configuração serve para qualquer seção — só a classe configuration vem de cada uma import { configuration as financeconfig, financialdocumentcontrollerapi } from " /generated/finance"; import { configuration as salesconfig, salesordercontrollerapi } from " /generated/sales"; const params = erpconfiguration({ baseurl, appkey, tenantid }); const titulos = await new financialdocumentcontrollerapi(new financeconfig(params)) financialdocumentcontrollerfindall({ pageable { page 0, size 20 } }); const pedidos = await new salesordercontrollerapi(new salesconfig(params)) salesordercontrollerfindall({ pageable { page 0, size 20 } }); por que os métodos têm nome longo partnercontrollerfindall, e não findall o nome curto não está disponível dezenas de controllers têm um findall, e deixar o gerador desempatar produzia ordinais posicionais (findall6) que mudavam sempre que alguém acrescentava um controller em qualquer lugar do produto um método que se renomeia por mudança alheia quebra o seu código sem motivo regerar quando o contrato mudar a saída fica versionada no repositório , por dois motivos um integrador em rede restrita não deveria precisar rodar um gerador, e a revisão precisa enxergar num diff o que mudou no contrato entre duas versões node sdk/generate mjs base https //erp exemplo gov br \\ \ key $erp app key \\ \ tenant $erp tenant id para conferir se o kit commitado ainda corresponde ao contrato — útil em ci node sdk/generate mjs check base key tenant o modo check compara os documentos, regenera para um diretório temporário e compara a saída arquivo a arquivo , e confere o catálogo de operações docid 825w6ivxqiy 5f88z8ubi assim uma troca de versão do gerador ou uma edição à mão sob generated/ também são pegas nunca edite nada sob typescript/generated — é sobrescrito a parte escrita à mão é typescript/src, e ela é propositalmente pequena cada método, um a um a referência do sdk typescript docid 3hov7fpn3qwzvzf8ncgm5 lista, por operação, a classe que você instancia, os parâmetros tipados (com obrigatoriedade), o tipo de retorno e uma chamada mínima — derivados do próprio cliente gerado, então não divergem do que você importa use a quando souber o que quer fazer (isso está no catálogo de operações docid 825w6ivxqiy 5f88z8ubi ) e precisar de como chamar em typescript outras linguagens só typescript é gerado hoje o contrato é openapi padrão, então gerar cliente para outra linguagem é executar o mesmo gerador com outro alvo — a qualidade da saída varia por linguagem, e por isso preferimos uma revisada de fato a cinco não lidas