@dbx-tools/sdk-shared

Zod schemas plus inferred TypeScript types for the Databricks SDK shapes the rest of the @dbx-tools/* packages consume. Everything under ./generated/ is regenerated from upstream @databricks/sdk-experimental .d.ts declarations by scripts/codegen.ts; nothing in here is hand-maintained.

import {
  genieMessageSchema,
  genieAttachmentSchema,
  messageStatusSchema,
  type GenieMessage,
  type MessageStatus,
} from "@dbx-tools/sdk-shared";

// Parse / validate a wire payload.
const message = genieMessageSchema.parse(rawJson);

// Or just use the inferred type.
function format(m: GenieMessage): string {
  return `${m.status}: ${m.content}`;
}

The package has zero runtime dependency beyond zod itself. No WorkspaceClient, no node:*, no SDK runtime - importing it from a browser bundle is safe.

What's inside

The single dashboards input currently expands to 74 exported schemas + matching inferred types, covering the Genie and Lakeview SDK surfaces (conversations, messages, attachments, query results, suggested questions, dashboard schedules, subscriptions, etc.). The full list lives at ./generated/dashboards.zod.ts and the package barrel at ./generated/index.ts.

For each upstream type the generator emits two exports:

| Export | Shape | | ------------------ | ------------------------------------------- | | xxxSchema | z.ZodType<X> for runtime validation | | Xxx (type alias) | z.infer<typeof xxxSchema> for static use |

How codegen works

Each consumer package declares its own codegen.inputs in package.json:

{
  "name": "@dbx-tools/sdk-shared",
  "codegen": {
    "inputs": [
      "node_modules/@databricks/sdk-experimental/dist/apis/dashboards/model.d.ts"
    ]
  }
}

bun scripts/codegen.ts walks every package with a codegen field and, for each input:

1. Reads the upstream .d.ts.
2. Strips every import declaration and rewrites any type reference whose root identifier was introduced by one of those imports (sql.StatementResponse, ApiClient, ...) to unknown. The output is a pure data-shape surface; peer SDK runtime modules don't belong here.
3. Pipes the cleaned source into ts-to-zod to produce a <name>.zod.ts schema module.
4. Regenerates generated/index.ts as a barrel re-export of every schema module.

The whole generated/ tree is gitignored (generated/.gitignore holds *); the hand-tracked top-level ./index.ts re-exports it so the publish merge in scripts/release.ts picks up the standard package.default.json exports map without any per-package wiring.

// index.ts
export * from "./generated/index.js";

Regenerating

bun run prebuild         # runs codegen across every package with a codegen field
# or, just sdk-shared:
bun scripts/codegen.ts

Codegen refuses to write or delete any file inside generated/ that isn't already gitignored at the start of the run, so manually dropping a file into generated/ without updating the ignore aborts with a clear error instead of silently overwriting.

Adding a new SDK surface

Append the upstream .d.ts path to codegen.inputs and rerun codegen. Optionally append =<basename> to override the auto-derived file name:

{
  "codegen": {
    "inputs": [
      "node_modules/@databricks/sdk-experimental/dist/apis/dashboards/model.d.ts",
      "node_modules/@databricks/sdk-experimental/dist/apis/jobs/model.d.ts=jobs"
    ]
  }
}

That produces generated/dashboards.zod.ts and generated/jobs.zod.ts, both re-exported by generated/index.ts.

License

Apache-2.0