API dos pacotes

Esta é uma referência dos pacotes TypeScript. Não é uma API HTTP e não define rotas de backend.

`@langdrift/sdk`

O ponto de entrada raiz reexporta todos os módulos públicos do SDK. Os pontos de entrada dedicados /schema, /mcp e /integrations expõem as mesmas exportações para essas áreas.

Tipos do protocolo

Constantes de execução:

ARTIFACT_TYPES
SCHEMA_VERSION

Tipos públicos:

ArtifactType, DocumentType e Pillar
JsonValue e JsonObject
ArtifactRef e ActorRef
Project, ArtifactMetadata, RecordEvent e DriftEvent

Esquemas e validação

As exportações de esquemas em tempo de execução são schemas, projectSchema, pillarSchemas e artifactPillars.

validateProject(input: unknown): Project
validateArtifact(input: unknown): ArtifactMetadata
validateRecord(input: unknown): RecordEvent
validateDrift(input: unknown): DriftEvent

Essas funções são síncronas e retornam o objeto original validado. Elas lançam LangDriftError em vez de converter ou copiar dados.

Caminhos seguros, projetos e artefatos

findRepositoryRoot(start?: string): Promise<string>
resolveSafePath(root: string, relative: string): Promise<string>
readProjectFile(
  root: string,
  relative: string,
  maxBytes?: number
): Promise<string>
loadProject(root: string): Promise<Project>
parseArtifact(text: string, artifactPath: string): ParsedArtifact
discoverArtifacts(
  root: string,
  options?: DiscoveryOptions
): Promise<ParsedArtifact[]>

MAX_ARTIFACT_BYTES, artifactLocations e artifactReferences também são exportados. Os tipos relacionados são ParsedArtifact e DiscoveryOptions.

Referências e eventos

resolveReferences(
  root: string,
  artifacts: ParsedArtifact[],
  knownReferences?: ArtifactRef[]
): Promise<ReferenceResolution>
 
recordId(
  integration: string,
  sourceId: string,
  eventId: string
): string
 
createRecord(
  input: Omit<RecordEvent, 'type' | 'schema_version'>
): RecordEvent
 
createDrift(
  input: Omit<DriftEvent, 'type' | 'schema_version'>
): DriftEvent

ReferenceResolution é exportado. recordId, createRecord e createDrift são síncronos.

Payloads e transporte

createPayload(
  project: Project,
  input: ParsedArtifact | RecordEvent | DriftEvent,
  source?: PayloadSource
): PayloadEnvelope
 
resolveCredential(
  reference: string,
  environment?: Readonly<Record<string, string | undefined>>
): string
 
sendPayload(
  project: Project,
  artifact: ParsedArtifact | RecordEvent | DriftEvent,
  transport: PayloadTransport,
  options: {
    credentialRef: string
    environment?: Readonly<Record<string, string | undefined>>
    source?: PayloadSource
  }
): Promise<TransportResult>

Os tipos públicos de transporte são PayloadSource, PayloadEnvelope, PayloadTransport e TransportResult. TransportError é o erro que contém apenas status que um adaptador injetado pode lançar para classificação por sendPayload.

Integrações e diagnósticos

recordFromGitHubPullRequest(
  event: GitHubPullRequestEvent,
  references?: ArtifactRef[],
  details?: GitHubPullRequestDetails
): RecordEvent
 
reportError(error: unknown, logger: Logger): void

O pacote também exporta integrationCapabilities, RecordSourceAdapter, GitHubPullRequestEvent, GitHubPullRequestDetails, LangDriftError, Issue, Diagnostic e Logger.

`@langdrift/core`

planSetup(options?: SetupOptions): Promise<SetupPlan>
setupProject(options?: SetupOptions): Promise<SetupResult>

O pacote exporta SetupError e os tipos SetupOptions, SetupFile, SetupPlan e SetupResult. runCli, templates e detalhes internos do gerador não são exportações do pacote.

planSetup valida e lê sem gravar. setupProject grava apenas entradas create seguras após um plano sem conflitos, ou retorna o plano inalterado em uma simulação.

Erros

Validação, caminhos, credenciais e transporte do SDK usam LangDriftError com code e issues: { path, message }[]. Falhas específicas da configuração usam SetupError com code, files e fields. A configuração também pode apresentar um LangDriftError do SDK quando a validação de projeto ou caminho falha.

Somente as funções que retornam explicitamente Promise são assíncronas. Nenhuma API desses pacotes faz registro de logs implícito, consulta remota, envio ou nova tentativa.