API của các gói

Đây là tài liệu tham chiếu cho các gói TypeScript. Nó không phải API HTTP và không định nghĩa tuyến phía máy chủ.

`@langdrift/sdk`

Điểm vào gốc xuất lại mọi mô-đun công khai của SDK. Các điểm vào chuyên biệt /schema, /mcp và /integrations cung cấp cùng các thành phần được xuất cho từng nhóm.

Kiểu giao thức

Hằng số lúc chạy:

ARTIFACT_TYPES
SCHEMA_VERSION

Kiểu công khai:

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

Lược đồ và kiểm tra

Các lược đồ được xuất lúc chạy là schemas, projectSchema, pillarSchemas và artifactPillars.

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

Các hàm này đồng bộ và trả về đối tượng gốc đã được kiểm tra. Chúng ném LangDriftError thay vì ép kiểu hay sao chép dữ liệu.

Đường dẫn an toàn, dự án và hiện vật

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 và artifactReferences cũng được xuất. Các kiểu liên quan là ParsedArtifact và DiscoveryOptions.

Tham chiếu và sự kiện

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 được xuất. recordId, createRecord và createDrift là đồng bộ.

Dữ liệu gửi và vận chuyển

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>

Các kiểu vận chuyển công khai là PayloadSource, PayloadEnvelope, PayloadTransport và TransportResult. TransportError là lỗi chỉ chứa trạng thái mà bộ điều hợp được truyền vào có thể ném để sendPayload phân loại.

Tích hợp và chẩn đoán

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

Gói còn xuất integrationCapabilities, RecordSourceAdapter, GitHubPullRequestEvent, GitHubPullRequestDetails, LangDriftError, Issue, Diagnostic và Logger.

`@langdrift/core`

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

Gói xuất SetupError cùng các kiểu SetupOptions, SetupFile, SetupPlan và SetupResult. runCli, mẫu và chi tiết nội bộ bộ tạo không được xuất từ gói.

planSetup kiểm tra và đọc mà không ghi. setupProject chỉ ghi các mục create an toàn sau kế hoạch không có xung đột, hoặc trả nguyên kế hoạch khi chạy thử.

Lỗi

Kiểm tra, đường dẫn, thông tin xác thực và vận chuyển của SDK dùng LangDriftError với code và issues: { path, message }[]. Lỗi riêng của thiết lập dùng SetupError với code, files và fields. Thiết lập cũng có thể đưa ra LangDriftError của SDK khi kiểm tra dự án hoặc đường dẫn thất bại.

Chỉ các hàm trả về Promise tường minh mới là bất đồng bộ. Không API nào trong các gói này tự ghi nhật ký, tra cứu từ xa, tải lên hoặc thử lại ngầm.