@altimateai/dbt-integration

A comprehensive TypeScript library that provides a unified integration layer for dbt (data build tool) projects. Supports multiple dbt deployment strategies including dbt Core, dbt Cloud, dbt Fusion, and command-line execution.

Features

• Multiple Integration Strategies: Support for dbt Core (Python bridge), dbt Cloud API, dbt Fusion, and CLI-based execution
• Unified Interface: Framework-agnostic DBTFacade interface for all dbt operations
• Manifest Parsing: Complete parsing of dbt manifests including models, sources, tests, macros, exposures, and metrics
• Dependency Graph: Build and analyze dbt project dependency graphs and lineage
• Python Integration: Direct Python bridge integration with dbt-core
• Type Safety: Full TypeScript support with comprehensive type definitions

Installation

npm install @altimateai/dbt-integration
# or
yarn add @altimateai/dbt-integration

Requirements: Node.js 18+

Setup

yarn install

Commands

Build

• yarn build - Build the library (CJS, ESM, and TypeScript declarations)
• yarn dev - Build in watch mode

Testing

• yarn test - Run Jest test suite
• yarn test:watch - Run tests in watch mode
• yarn test:coverage - Generate test coverage report
• yarn test:integration - Run integration tests

Code Quality

• yarn lint - Run ESLint
• yarn lint:fix - Fix ESLint issues
• yarn format - Format code with Prettier
• yarn format:check - Check code formatting
• yarn typecheck - Run TypeScript type checking

Publishing

1. Update version in package.json
2. Build the library: yarn build
3. Publish to npm: npm publish

Releases normally publish automatically via .github/workflows/publish.yml when a GitHub release is published. If that event is dropped — a GitHub Actions incident did exactly this to the mcp-engine's v0.7.0 release — the same publish can be started by hand rather than re-cutting the release:

gh workflow run publish.yml --ref main -f ref=v0.3.14                   # publish that tag
gh workflow run publish.yml --ref main -f ref=v0.3.14 -f dry_run=true   # validate without publishing

--ref picks the copy of the workflow that runs, so keep it on main: a tag cut before this trigger existed has no workflow_dispatch. -f ref= picks what to publish.

Inputs: ref (tag/ref to publish from, defaults to the ref the run was started on), dist_tag (defaults to latest, or beta for a prerelease version), and dry_run. The version published is always the one in package.json at that ref, never the tag name, and the workflow refuses to run if that version is already on npm — so bump package.json before tagging.

The library is configured with:

• TypeScript for type safety
• tsup for bundling
• Jest for testing
• ESLint and Prettier for code quality
• Husky for git hooks
• Commitlint for conventional commits
• MSW for API mocking in tests

Commit Convention

This project uses Conventional Commits. Valid commit types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, etc)
• refactor: Code refactoring
• perf: Performance improvements
• test: Test changes
• build: Build system changes
• ci: CI/CD changes
• chore: Other changes
• revert: Revert previous commit

License

MIT