Configuração

Todo app Kazzle tem um kazzle.config.ts na raiz do projeto. O arquivo exporta uma definição de app: o mesmo contrato que Kazzle usa para apps publicados e conectores integrados.

Início rápido

import { defineApp } from '@kazzle/app';

export default defineApp({
  schemaVersion: 1,
  name: 'My App',
  subtitle: 'A short catalog description',
  description: { type: 'markdown', path: 'README.md' },
  maxInstallations: 1,
  setup: { type: 'none' },
  launch: { type: 'component', component: 'web' },
  components: [{ name: 'web', type: 'ui', path: '.' }],
  tools: [],
  skills: [],
});

defineApp valida a definição e fornece autocompletar do TypeScript. Campos não suportados ou com erros de digitação falham na validação em vez de serem ignorados.

Campos de definição

Campo	Tipo	Obrigatório	Descrição
`schemaVersion`	`1`	sim	Versão do contrato de definição.
`name`	`string`	sim	Nome de exibição no catálogo e página de detalhes.
`subtitle`	`string`	sim	Descrição de catálogo em uma linha.
`description`	`{ type: 'markdown', path: string }`	sim	Markdown incluído no app, geralmente `README.md`.
`version`	`string`	não	Versão do publicador exibida com o app instalado.
`icon`	`string`	não	Caminho do ícone relativo à raiz do app.
`accentColor`	cor hex	não	Cor de destaque da marca.
`maxInstallations`	`number \| null`	sim	Máximo de instalações por Space; `null` permite qualquer número.
`setup`	objeto setup	sim	Como uma instalação é configurada.
`launch`	objeto launch	sim	O que abre após a instalação.
`components`	component[]	sim	Componentes de UI e processo.
`tools`	tool source[]	sim	Fontes que compilam em ferramentas de IA chamáveis.
`skills`	skill[]	sim	Instruções carregadas quando relevantes.
`kazzleAuth`	`'optional' \| 'required'`	não	Se a superfície de inicialização requer identidade Kazzle.
`webhookUrl`	URL	não	Recebe webhooks do ciclo de vida da instalação.
`appLogin`	`boolean`	não	Ativa o login de usuário final do próprio app.

Setup

Um app escolhe exatamente um fluxo de setup.

setup: { type: 'none' }

Use none quando a instalação não precisa de autorização externa.

setup: {
  type: 'oauth',
  version: '2.0',
  metadata: {
    type: 'endpoints',
    authorizationUrl: 'https://provider.example.com/oauth/authorize',
    tokenUrl: 'https://provider.example.com/oauth/token',
  },
  scopes: ['account.read'],
  pkce: 'required',
  authorizationParams: {},
  fields: [],
}

Use oauth para OAuth 1.0a ou OAuth 2.0. As credenciais do cliente OAuth são configuradas de forma privada quando o app é publicado; elas nunca aparecem na definição.

setup: {
  type: 'form',
  labelField: 'accountUrl',
  fields: [
    { key: 'accountUrl', label: 'Account URL', kind: 'url', required: true, secret: false },
    { key: 'apiKey', label: 'API key', kind: 'password', required: true, secret: true },
  ],
}

Campos de formulário suportam text, password, url, hostname, email e select. labelField pode referenciar um campo não secreto para distinguir múltiplas instalações.

Launch

launch: { type: 'none' }
launch: { type: 'component', component: 'web' }
launch: { type: 'url', url: 'https://example.com', target: 'external' }

Um alvo de componente deve nomear um componente na mesma definição. Alvos de URL escolhem embedded ou external explicitamente.

Componentes

Cada componente tem um name único, um type de ui ou process e um path de origem. Um app pode ter no máximo um componente de UI.

components: [{
  name: 'server',
  type: 'process',
  path: './server',
  runtime: {
    dev: { command: 'bun run dev' },
    prod: { command: 'bun run start', build: 'bun run build' },
  },
}]

env pode selecionar uma coleção de segredos e ambiente para um componente. Componentes de processo também podem declarar execução persistente ou acionada e gatilhos de agendamento ou webhook nomeados.

Ferramentas e skills

Ferramentas e skills são independentes. Ferramentas definem operações chamáveis; skills explicam quando e como usá-las.

tools: [
  { name: 'app-tools', type: 'file', path: './tools.ts' },
  {
    name: 'stripe',
    type: 'connection_actions',
    actions: ['customers.list', 'invoices.list'],
  },
],
skills: [
  { name: 'billing', source: { type: 'file', path: './skills/billing/SKILL.md' } },
  { name: 'review', source: { type: 'inline', instructions: 'Confirm before write actions.' } },
]

Ações de conexão requerem uma instalação quando chamadas. Elas são emitidas pelo conversor de app do sistema Kazzle; apps publicados definem ferramentas chamáveis em arquivos. Skills permanecem separadas e podem ser carregadas apenas quando relevantes.

Começar

Construir

Usuários e dados

Publicar

Usar o Kazzle

Segurança

Referência

Configuração

Configuração

Início rápido

Campos de definição

Setup

Launch

Componentes

Ferramentas e skills

​Configuração

​Início rápido

​Campos de definição

​Setup

​Launch

​Componentes

​Ferramentas e skills

Configuração

Início rápido

Campos de definição

Setup

Launch

Componentes

Ferramentas e skills