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.
  • MockCore em 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.
  • TypedClient TypeScript 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

  1. Mantenha uma cópia do projeto e do SDK anterior. Teste a atualização em homologação.
  2. Troque a dependência local PHP zerotrusted/forge-sdk para 2.0.0 e o repositório path para php/ desta distribuição. No TypeScript, a dependência file: deve apontar para typescript/ desta distribuição.
  3. Reinstale as dependências e execute os testes do plugin. Compile TypeScript antes da validação.
  4. Mantenha apiVersion: 1, Client.call(...), IDs de operação, permissões e dependências existentes. Não altere o manifesto para apiVersion: 2.
  5. 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.
  6. MockCore é opcional e destinado a testes locais. Ele não concede acesso nem acompanha a identidade do usuário em produção.
  7. 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.

Baixar SDK V2 SHA-256

Prepare primeiro seu ambiente Linux, WSL2 ou Remote SSH.