@dbx-tools/databricks-zerobus 0.1.9

package/README.md

@@ -0,0 +1,55 @@
+# @dbx-tools/node-databricks-zerobus
+
+Region-aware Zerobus ingest helpers for Databricks workspaces.
+
+Import this package when Node code needs to create a Zerobus SDK client and open
+an ingest stream without hand-building the region-specific Zerobus endpoint.
+
+Key features:
+
+- Databricks workspace URL/id discovery through
+  [`@dbx-tools/node-databricks`](../databricks).
+- Cloud/region-aware Zerobus endpoint construction.
+- Credential lookup with Zerobus-prefixed env vars and Databricks client-id
+  fallbacks.
+- Thin wrapper around the Zerobus SDK so callers can still use SDK-native stream
+  methods after setup.
+
+## Create A Zerobus SDK Client
+
+```ts
+import { zerobus } from "@dbx-tools/node-databricks-zerobus";
+
+const sdk = await zerobus.createSdk();
+```
+
+`createSdk()` resolves the current Databricks workspace URL/id, detects its cloud
+region through [`@dbx-tools/node-databricks`](../databricks), and constructs the
+Zerobus endpoint for that region.
+
+## Open An Ingest Stream
+
+```ts
+const stream = await zerobus.createStream(sdk, "main.default.events");
+
+await stream.ingestRecord({
+  id: crypto.randomUUID(),
+  event_type: "clicked",
+  created_at: new Date().toISOString(),
+});
+```
+
+`createStream()` reads `ZEROBUS_DATABRICKS_CLIENT_ID` /
+`ZEROBUS_DATABRICKS_CLIENT_SECRET`, falling back to unprefixed
+`DATABRICKS_CLIENT_ID` / `DATABRICKS_CLIENT_SECRET`. Use the prefixed variables
+when the app uses separate credentials for Zerobus ingestion.
+
+This package does not model records or topics. It only resolves the correct SDK
+client and stream endpoint, then leaves ingestion semantics to Zerobus.
+
+## Module
+
+- `zerobus` - `createSdk()` and `createStream()`.
+
+This package has no AppKit dependency. Workspace and cloud detection are
+delegated to [`@dbx-tools/node-databricks`](../databricks).

package/index.ts

@@ -0,0 +1,5 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as zerobus from "./src/zerobus";

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@dbx-tools/databricks-zerobus",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "workspaces/node/databricks-zerobus"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@databricks/zerobus-ingest-sdk": "^1.1.0",
+    "@dbx-tools/databricks": "0.1.9",
+    "@dbx-tools/shared-core": "0.1.9"
+  },
+  "main": "index.ts",
+  "license": "UNLICENSED",
+  "version": "0.1.9",
+  "types": "index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./package.json": "./package.json"
+  },
+  "dbxToolsConfig": {
+    "tags": [
+      "node"
+    ]
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  }
+}

package/src/zerobus.ts

@@ -0,0 +1,59 @@
+import {
+  ZerobusSdk,
+  type RecordType,
+  type StreamConfigurationOptions,
+  type TableProperties,
+  type ZerobusStream,
+} from "@databricks/zerobus-ingest-sdk";
+import { workspace, cloud } from "@dbx-tools/databricks";
+
+export async function createSdk(): Promise<ZerobusSdk> {
+  const workspaceUrl = await workspace.getWorkspaceUrl();
+  if (!workspaceUrl) {
+    throw new Error("Workspace URL not found");
+  }
+  const workspaceId = await workspace.getWorkspaceId();
+  if (!workspaceId) {
+    throw new Error(`Workspace ID not found: workspaceUrl=${workspaceUrl.toString()}`);
+  }
+  const location = await cloud.resolveCloudLocation(workspaceUrl.toString());
+  if (!location) {
+    throw new Error(`Workspace location not found: workspaceUrl=${workspaceUrl.toString()}`);
+  }
+  const domain =
+    location.provider === cloud.CloudProvider.Azure
+      ? "azuredatabricks.net"
+      : "cloud.databricks.com";
+  const zerobusEndpoint = `https://${workspaceId}.zerobus.${location.region}.${domain}`;
+  return new ZerobusSdk(zerobusEndpoint, workspaceUrl.toString());
+}
+
+export async function createStream(
+  sdk: ZerobusSdk,
+  table: TableProperties | string,
+  options?: StreamConfigurationOptions,
+): Promise<ZerobusStream> {
+  function resolveVariable(name: string): string {
+    for (const candidate of [`ZEROBUS_${name}`, name]) {
+      const value = process.env[candidate];
+      if (value) {
+        return value;
+      }
+    }
+    throw new Error(`Variable ${name} not found`);
+  }
+  const streamTableProperties = typeof table === "string" ? { tableName: table } : table;
+  const streamClientId = resolveVariable("DATABRICKS_CLIENT_ID");
+  const streamClientSecret = resolveVariable("DATABRICKS_CLIENT_SECRET");
+  const streamOptions = {
+    recovery: true,
+    recordType: 0 as RecordType, // RecordType.Json (const enum, can't be referenced under verbatimModuleSyntax)
+    ...options,
+  };
+  return await sdk.createStream(
+    streamTableProperties,
+    streamClientId,
+    streamClientSecret,
+    streamOptions,
+  );
+}

package/tsconfig.json

@@ -0,0 +1,41 @@
+// ~~ Generated by projen. To modify, edit .projenrc.js and run "pnpm exec projen".
+{
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib",
+    "alwaysStrict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "lib": [
+      "ES2022"
+    ],
+    "module": "ESNext",
+    "noEmitOnError": false,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "strictPropertyInitialization": true,
+    "stripInternal": true,
+    "target": "ES2022",
+    "types": [
+      "node"
+    ],
+    "moduleResolution": "bundler",
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}