SDK 2.0.0 / PROTOCOLO V1
Titan Architect SDK V2
Bibliotecas e ferramentas para plugins PHP e TypeScript, compatíveis com o protocolo v1 do host Titan. A versão 2 é do kit de desenvolvimento, não do protocolo nem do formato FEX. Não exige migração do núcleo, atualização de APKs, alteração de workers ou acesso ao código proprietário.
O que mudou
- Projetos iniciais genéricos, sem dependência do MDM, sem serviços externos e sem solicitar permissões.
MockCoreem PHP e TypeScript para registrar fixtures locais e testar dependências, permissões declaradas, concessões do host e permissões do ator. Todos os conjuntos começam sem acesso.TypedClientTypeScript com mapa de operações e decoder obrigatório para validar resultados em execução.- Rejeição de identificadores de operação inválidos antes do transporte JSON.
- CLI e FEX herdados da distribuição v1: gerar, testar, validar, assinar, verificar e inspecionar.
- Projetos compatíveis com o preview e os comandos da extensão Titan Architect Studio. Configure o Studio para esta pasta do SDK.
Comece
Extraia o ZIP. Use PHP 8.2+, Python 3 e Composer para PHP, ou Node.js 22+ e npm para TypeScript. Execute da pasta que contém titanArchitect-sdk:
php titanArchitect-sdk/tools/titan-sdk.php doctor php
php titanArchitect-sdk/tools/titan-sdk.php init php empresa.ola ./ola
(cd ola && composer install && composer test)
php titanArchitect-sdk/tools/titan-sdk.php validate ola
Para TypeScript:
php titanArchitect-sdk/tools/titan-sdk.php init typescript empresa.ola-web ./ola-web
(cd ola-web && npm install && npm test)
php titanArchitect-sdk/tools/titan-sdk.php validate ola-web
O gerador usa dependências locais do SDK extraído. Não pressupõe que os pacotes estejam publicados no npm ou Packagist.
Mock local e autorização
O mock não autentica usuários reais. demo.greeting, demo.read e empresa.demo abaixo são fixtures fictícias, não operações do Titan operacional.
import { MockCore } from '@zerotrusted/forge-sdk';
const core = new MockCore();
core.register('demo.greeting', 'demo.read', 'empresa.demo', () => ({ message: 'Olá, Titan!' }));
const manifest = {
id: 'empresa.exemplo', version: '1.0.0', runtime: 'typescript' as const,
entrypoint: 'dist/plugin.js', apiVersion: 1 as const,
dependencies: ['empresa.demo'], permissions: ['demo.read'], events: []
};
const client = core.client(manifest, ['demo.read'], ['demo.read']);
console.log(await client.call('demo.greeting'));
// core.client(manifest).call('demo.greeting') rejeita com forbidden.
PHP fornece Forge\Development\MockCore com os mesmos métodos register, client e calls. Use o autoload Composer para carregar a classe. O histórico local registra apenas operação e sucesso/negação; não armazena payloads.
Produção e compatibilidade
Continue usando Client.call, manifestos com apiVersion: 1, mensagens JSON com version: 1 e o FEX assinado existente. O host real fornece o canal autenticado. Nunca passe credenciais do banco ou confie em permissões enviadas pelo próprio plugin.
O SDK não oferece isolamento de SO, supervisor PHP/Node, instalação automática nem credenciais de homologação. O Studio renderiza apenas a interface HTML/CSS/JS local. Homologação de instalação continua necessária antes de executar código externo.
Leia docs/MIGRACAO-V2.md, docs/CLI.md e docs/CONTRATOS.md. Os exemplos de integração em examples/php e examples/typescript continuam disponíveis para consultar o contrato de distribuição Android; não são o ponto de partida obrigatório.
Migracao
- Mantenha uma cópia do projeto e do SDK anterior. Teste a atualização em homologação.
- Troque a dependência local PHP
zerotrusted/forge-sdkpara2.0.0e o repositório path paraphp/desta distribuição. No TypeScript, a dependênciafile:deve apontar paratypescript/desta distribuição. - Reinstale as dependências e execute os testes do plugin. Compile TypeScript antes da validação.
- Mantenha
apiVersion: 1,Client.call(...), IDs de operação, permissões e dependências existentes. Não altere o manifesto paraapiVersion: 2. - Identificadores inválidos de operação passam a falhar antes de acessar o transporte. Corrija o chamador; operações válidas do protocolo v1 permanecem compatíveis.
MockCoreé opcional e destinado a testes locais. Ele não concede acesso nem acompanha a identidade do usuário em produção.- Configure o SDK V2 nas configurações de usuário do Studio. Valide, gere o FEX e confira assinatura e permissões antes de entregar para homologação.
Rollback: restaure a dependência e o caminho para o SDK anterior e reinstale o lockfile preservado. O SDK V2 não aplica migrações de banco nem substitui serviços do Titan.