@databricks/zerobus-ingest-sdk 0.0.1 → 0.1.1

package/build.rs

@@ -0,0 +1,5 @@
+extern crate napi_build;
+
+fn main() {
+    napi_build::setup();
+}

package/package.json

@@ -1,11 +1,93 @@
 {
   "name": "@databricks/zerobus-ingest-sdk",
-  "version": "0.0.1",
-  "description": "",
+  "version": "0.1.1",
+  "description": "TypeScript/Node.js SDK for streaming data ingestion into Databricks Delta tables using Zerobus",
   "main": "index.js",
+  "types": "index.d.ts",
+  "keywords": [
+    "databricks",
+    "delta",
+    "streaming",
+    "ingestion",
+    "zerobus",
+    "typescript",
+    "rust"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/databricks/zerobus-sdk-ts.git"
+  },
+  "license": "Databricks License",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE",
+    "src/",
+    "utils/",
+    "schemas/",
+    "Cargo.toml",
+    "Cargo.lock",
+    "build.rs",
+    "*.node"
+  ],
+  "napi": {
+    "name": "zerobus-ingest-sdk",
+    "triples": {
+      "defaults": true,
+      "additional": [
+        "x86_64-unknown-linux-musl",
+        "aarch64-unknown-linux-gnu",
+        "aarch64-apple-darwin",
+        "aarch64-unknown-linux-musl"
+      ]
+    }
+  },
+  "engines": {
+    "node": ">= 16"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "artifacts": "napi artifacts",
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "build:proto": "mkdir -p examples/generated && pbjs -t static-module -w commonjs -o examples/generated/air_quality.js schemas/air_quality.proto && pbts -o examples/generated/air_quality.d.ts examples/generated/air_quality.js && protoc --descriptor_set_out=schemas/air_quality_descriptor.pb --include_imports schemas/air_quality.proto",
+    "prepublishOnly": "napi prepublish -t npm",
+    "test": "tsx --test test/unit.test.ts test/integration.test.ts",
+    "test:unit": "tsx --test test/unit.test.ts",
+    "test:integration": "tsx --test test/integration.test.ts",
+    "universal": "napi universal",
+    "version": "napi version",
+    "example:json": "tsx examples/json.ts",
+    "example:proto": "tsx examples/proto.ts",
+    "example:parallel": "tsx examples/parallel_streams.ts"
+  },
+  "peerDependencies": {
+    "protobufjs": "^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "protobufjs": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.0",
+    "@types/node": "^20.0.0",
+    "dotenv": "^17.2.3",
+    "protobufjs": "^7.5.4",
+    "protobufjs-cli": "^2.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.3.0"
+  },
+  "overrides": {
+    "glob": "^10.0.0"
   },
-  "author": "",
-  "license": "Apache-2.0"
+  "optionalDependencies": {
+    "@databricks/zerobus-ingest-sdk-win32-x64-msvc": "0.1.1",
+    "@databricks/zerobus-ingest-sdk-darwin-x64": "0.1.1",
+    "@databricks/zerobus-ingest-sdk-linux-x64-gnu": "0.1.1",
+    "@databricks/zerobus-ingest-sdk-linux-x64-musl": "0.1.1",
+    "@databricks/zerobus-ingest-sdk-linux-arm64-gnu": "0.1.1",
+    "@databricks/zerobus-ingest-sdk-darwin-arm64": "0.1.1",
+    "@databricks/zerobus-ingest-sdk-linux-arm64-musl": "0.1.1"
+  }
 }

package/schemas/air_quality.proto

@@ -0,0 +1,10 @@
+syntax = "proto2";
+
+package examples;
+
+// Example message representing air quality sensor data
+message AirQuality {
+    optional string device_name = 1;
+    optional int32 temp = 2;
+    optional int64 humidity = 3;
+}

package/src/headers_provider.ts

@@ -0,0 +1,82 @@
+/**
+ * Interface for providing custom headers to Zerobus streams.
+ *
+ * Implement this interface to use custom authentication beyond OAuth,
+ * such as Personal Access Tokens (PAT) or custom auth tokens.
+ */
+export interface HeadersProvider {
+    /**
+     * Returns headers as array of [name, value] tuples.
+     *
+     * Required headers:
+     * - ["authorization", "Bearer <token>"]
+     * - ["x-databricks-zerobus-table-name", "<table_name>"]
+     *
+     * @returns Promise resolving to array of header name-value pairs
+     */
+    getHeaders(): Promise<Array<[string, string]>>;
+}
+
+/**
+ * OAuth 2.0 Client Credentials headers provider.
+ *
+ * **IMPORTANT: DO NOT instantiate this class directly.**
+ *
+ * OAuth authentication is handled automatically by the Rust SDK when you call
+ * `createStream()` with clientId and clientSecret parameters (without providing
+ * a headers_provider).
+ *
+ * This class exists for:
+ * 1. Documentation purposes - showing the HeadersProvider pattern
+ * 2. API consistency with other Zerobus SDKs (Python, Java, Rust)
+ *
+ * **How to use OAuth authentication:**
+ * ```typescript
+ * // OAuth is the default - just pass clientId and clientSecret
+ * const stream = await sdk.createStream(
+ *     tableProperties,
+ *     clientId,      // OAuth client ID
+ *     clientSecret,  // OAuth client secret
+ *     options
+ *     // No headers_provider parameter = OAuth authentication
+ * );
+ * ```
+ *
+ * **How to use custom authentication (PAT, etc.):**
+ * ```typescript
+ * class CustomHeadersProvider implements HeadersProvider {
+ *     async getHeaders() {
+ *         return [
+ *             ["authorization", `Bearer ${myToken}`],
+ *             ["x-databricks-zerobus-table-name", tableName]
+ *         ];
+ *     }
+ * }
+ *
+ * const provider = new CustomHeadersProvider();
+ * const stream = await sdk.createStream(
+ *     tableProperties,
+ *     '', // ignored
+ *     '', // ignored
+ *     options,
+ *     { getHeadersCallback: provider.getHeaders.bind(provider) }
+ * );
+ * ```
+ */
+export class OAuthHeadersProvider implements HeadersProvider {
+    constructor(
+        private clientId: string,
+        private clientSecret: string,
+        private tableName: string,
+        private workspaceUrl: string
+    ) {}
+
+    async getHeaders(): Promise<Array<[string, string]>> {
+        throw new Error(
+            'OAuthHeadersProvider should not be instantiated directly. ' +
+            'OAuth authentication is handled internally by the Rust SDK. ' +
+            'To use OAuth: call createStream(tableProperties, clientId, clientSecret, options) without the headers_provider parameter. ' +
+            'To use custom authentication: implement the HeadersProvider interface.'
+        );
+    }
+}