パッケージ API

これは TypeScript パッケージのリファレンスです。 HTTP API ではなく、バックエンドのルートも定義しません。

`@langdrift/sdk`

ルートのエントリーポイントは、SDK のすべての公開モジュールを再エクスポートします。専用の /schema、/mcp、/integrations エントリーポイントも、それぞれの領域で同じエクスポートを提供します。

プロトコルの型

実行時定数：

ARTIFACT_TYPES
SCHEMA_VERSION

公開型：

ArtifactType、DocumentType、Pillar
JsonValue と JsonObject
ArtifactRef と ActorRef
Project、ArtifactMetadata、RecordEvent、DriftEvent

スキーマと検証

実行時のスキーマエクスポートは schemas、projectSchema、pillarSchemas、artifactPillars です。

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

これらは同期関数で、検証した元のオブジェクトを返します。データを型変換したりコピーしたりせず、問題がある場合は LangDriftError を送出します。

安全なパス、プロジェクト、成果物

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、artifactReferences もエクスポートされます。関連する型は ParsedArtifact と DiscoveryOptions です。

参照とイベント

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 がエクスポートされます。 recordId、createRecord、createDrift は同期関数です。

ペイロードと転送

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>

公開される転送の型は PayloadSource、PayloadEnvelope、PayloadTransport、TransportResult です。 TransportError は、注入したアダプターが送出できるステータスのみのエラーで、sendPayload が分類します。

連携と診断

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

パッケージは integrationCapabilities、RecordSourceAdapter、GitHubPullRequestEvent、GitHubPullRequestDetails、LangDriftError、Issue、Diagnostic、Logger もエクスポートします。

`@langdrift/core`

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

パッケージは SetupError と、SetupOptions、SetupFile、SetupPlan、SetupResult の型をエクスポートします。 runCli、テンプレート、生成処理の内部実装はエクスポートされません。

planSetup は書き込まずに検証と読み取りを行います。 setupProject は、競合のない計画が得られた後、安全な create 項目だけを書き込みます。ドライランでは計画を変更せずに返します。

エラー

SDK の検証、パス、認証情報、転送では、code と issues: { path, message }[] を持つ LangDriftError を使います。セットアップ固有の失敗では、code、files、fields を持つ SetupError を使います。プロジェクトやパスの検証に失敗した場合、セットアップから SDK の LangDriftError が返ることもあります。

非同期なのは、明示的に Promise を返す関数だけです。これらのパッケージには、暗黙のログ記録、リモート検索、アップロード、再試行を行う API はありません。