@hasura/promptql 1.0.0 → 2.0.0-alpha.1

package/README.md

@@ -1,196 +1,372 @@
-# PromptQL NodeJS SDK 
+# PromptQL TypeScript SDK
 
-A Node.js SDK for [PromptQL API](https://hasura.io/docs/promptql/promptql-apis/overview/).
+A TypeScript SDK for interacting with the [PromptQL API](https://promptql.hasura.io) by Hasura. PromptQL enables natural language querying of your data through an AI-powered interface.
 
-## Install
+## Features
 
-Run the following command:
+- **Type-safe API Client**: Fully typed TypeScript SDK with auto-generated types from GraphQL schema
+- **Thread Management**: Create, list, and manage conversation threads
+- **Real-time Streaming**: Subscribe to thread events with GraphQL subscriptions using RxJS observables
+- **Authentication**: Built-in authentication handling with service account tokens
+- **Query Planning**: Access to AI agent query plans and execution steps
+- **Artifact Support**: Handle modified artifacts from AI responses
+- **CLI Tool**: Command-line interface for quick interactions
+- **Flexible Configuration**: Support for custom base URLs, headers, and fetch implementations
 
-```sh
+## Requirements
+
+- Node.js >= 24
+- TypeScript >= 5.9.2
+
+## Installation
+
+```bash
 npm install @hasura/promptql
 ```
 
-## Get started
+Or with your preferred package manager:
+
+```bash
+# Yarn
+yarn add @hasura/promptql
 
-### Prerequisite
+# pnpm
+pnpm add @hasura/promptql
 
-- If you are new with PromptQL, follow [the quickstart guide of PromptQL](https://hasura.io/docs/promptql/quickstart/) to create a project.
-- Create a PromptQL API Key in project settings tab on [https://console.hasura.io](https://console.hasura.io).
-- Security headers and your Project API endpoint (version 1) or build version (version 2).
+# Bun
+bun add @hasura/promptql
+```
 
-### Use PromptQL SDK
+## Quick Start
 
-#### Create client
+### Getting Service Account Token
 
-Create the PromptQL client with required configurations:
+1. Visit your Hasura project console
+2. Navigate to Project Settings
+3. Go to Service Accounts section
+4. Create a new service account token with `Read Only` permission. Avoid using the `Admin` role. Hackers can modify your project metadata if the service account token is leaked.
+5. Copy the token and use it in your SDK configuration
 
-```ts
-import { createPromptQLClientV2 } from '@hasura/promptql';
+For more details, check the [Hasura documentation](https://hasura.io/docs/3.0/project-configuration/project-management/service-accounts/#how-to-create-service-account).
 
-const client = createPromptQLClientV2({
-    apiKey: '<your-promptql-api-key>',
-    ddn: {
-        headers: {
-            'Authorization': '<credential>'
-        }
-    },
-    // You can define a lazy function for the ddn options.
-    //
-    // ddn: () => {{ 
-    //     headers: {
-    //         'Authorization': '<credential>'
-    //     }
-    // }}  
+### Basic Usage
+
+#### Start a PromptQL thread
+
+```typescript
+import { PromptQLSdk } from '@hasura/promptql';
+
+// Initialize the SDK
+const sdk = new PromptQLSdk({
+  projectId: 'your-project-id',
+  serviceAccountToken: 'your-service-account-token',
 });
-```
 
-#### Run a Query
-
-```ts
-const runQuery = (text: string) => {
-    return client.query({
-        artifacts: [],
-        interactions: [
-            {
-                user_message: {
-                    text,
-                }
-            }
-        ],
-        ddn: {
-            // you can override the default ddn config, 
-            // for example, dynamic auth credentials
-            headers: {}
-        }
+// Start a new thread
+const thread = await sdk.startThread({
+  message: 'What are the top 10 customers by revenue?',
+});
+
+console.log('Thread ID:', thread.thread_id);
+
+// Stream events from the thread
+sdk.streamThreadEventsByThreadId(thread.thread_id).subscribe({
+  next: (events) => {
+    events.forEach(event => {
+      console.log('Event:', event);
     });
+  },
+  error: (err) => console.error('Error:', err),
+  complete: () => console.log('Interaction complete'),
+});
+```
 
-    return response.
-}
+#### Continue a Conversation
 
-runQuery('what can you do?').then((response) => {
-    console.log(response)
+```typescript
+// Send a follow-up message to an existing thread
+const result = await sdk.sendMessageToThread({
+  threadId: 'existing-thread-id',
+  message: 'Now show me their average order value',
 });
+
+// Stream the response
+sdk.streamThreadEventsByThreadId(result.thread_id, result.thread_event_id)
+  .subscribe({
+    next: (events) => console.log('New events:', events),
+  });
 ```
 
-## Reference
+#### Wait until the final response only
 
-### Version 2
+Use the `lastValueFrom` function to wrap the subscription.
 
-#### Natural Language
+```typescript
+import { PromptQLSdk } from '@hasura/promptql';
+import { lastValueFrom } from "rxjs";
 
-The API version 2 simplifies request parameters: 
-- The DDN URL is replaced by `build_version`. 
-- `llm`, `ai_primitives_llm`, and `system_instructions` are removed. 
+// Initialize the SDK
+const sdk = new PromptQLSdk({
+  projectId: 'your-project-id',
+  serviceAccountToken: 'your-service-account-token',
+});
 
-To use the API v2, you need to create a PromptQL Client v2:
+// Start a new thread
+const thread = await sdk.startThread({
+  message: 'What are the top 10 customers by revenue?',
+});
 
-```ts
-import { createPromptQLClientV2 } from '@hasura/promptql';
+console.log('Thread ID:', thread.thread_id);
 
-const client = createPromptQLClientV2({
-    apiKey: '<your-promptql-api-key>',
-    ddn: {
-        // build_version: '<your-build-version>',
-        headers: {
-            'Authorization': '<credential>'
-        }
-    },
+const events = await lastValueFrom(
+  sdk.streamThreadEventsByThreadId(
+     result.thread_id,
+  ),
+);
+
+events.forEach(event => {
+  console.log('Event:', event);
+});
+```
+
+#### Print new events only
+
+```typescript
+import { PromptQLSdk, diffThreadEvents } from '@hasura/promptql';
+import { pairwise, map } from 'rxjs';
+
+// Initialize the SDK
+const sdk = new PromptQLSdk({
+  projectId: 'your-project-id',
+  serviceAccountToken: 'your-service-account-token',
+});
+
+// Start a new thread
+const thread = await sdk.startThread({
+  message: 'What are the top 10 customers by revenue?',
+});
+
+console.log('Thread ID:', thread.thread_id);
+
+// Stream events from the thread
+sdk.streamThreadEventsByThreadId(thread.thread_id)
+  .pipe(
+    pairwise(),
+    map(([prev, curr]) => diffThreadEvents(prev, curr)),
+  )
+  .subscribe({
+  next: (events) => {
+    events.forEach(event => {
+      console.log('Event:', event);
+    });
+  },
+  error: (err) => console.error('Error:', err),
+  complete: () => console.log('Interaction complete'),
+});
+```
+
+### Listing Threads
+
+```typescript
+const threads = await sdk.getThreads({
+  limit: 20,
+  offset: 0,
+  order_by: [{ created_at: 'desc' }],
+  where: {
+    // Optional filters
+  },
+});
+
+threads.forEach(thread => {
+  console.log(`Thread ${thread.id}:`, thread.title);
 });
 ```
 
-##### Non-Streaming
+### Get a Specific Thread
+
+```typescript
+const thread = await sdk.getThreadById('thread-id');
+console.log('Thread:', thread);
+```
 
-```ts
-function query(
-    body: PromptQLQueryRequestV2,
-    queryOptions?: FetchOptions
-) => Promise<QueryResponse>
+## Event Handling
+
+### Basics
+
+The data structure of event data is the union of many event type. Each event type contains a different payload. You can go to the definition of `ThreadEventData` type to view the full data structure details. 
+
+The SDK also provides utility functions to parse different event types, for example, the following example catches and prints the query plan event and the final generated response:
+
+```typescript
+import {
+  getAgentPlanGenerationStartedEvent,
+  getAgentPlanStepGeneratedEvent,
+  getAgentGeneratedResponse,
+  getUserMessageEvent,
+} from '@hasura/promptql';
+
+sdk.streamThreadEventsByThreadId(threadId).subscribe({
+  next: (events) => {
+    events.forEach(event => {
+      // Check for plan generation start
+      const planStart = getAgentPlanGenerationStartedEvent(event.event_data);
+      if (planStart) {
+        console.log('Query Plan:\n');
+        return;
+      }
+
+      // Check for plan steps
+      const planStep = getAgentPlanStepGeneratedEvent(event.event_data);
+      if (planStep) {
+        console.log(`  - Step ${planStep.step_index}: ${planStep.step_title}\n`);
+        return;
+      }
+
+      // Check for final response
+      const response = getAgentGeneratedResponse(event.event_data);
+      if (response) {
+        const xmlRegex = /<\w+.*\/>/gm;
+        console.log('Response:', source.replaceAll(xmlRegex, response.response.message));
+        if (response.response.modified_artifacts) {
+          console.log('Artifacts:', response.response.modified_artifacts);
+        }
+        return;
+      }
+    });
+  },
+});
 ```
 
-##### Streaming
+### Handle XML tags in generated response message
+
+The generated message may contains XML tags. They represents custom UI elements that the markdown text doesn't support. You should parse or remove them if they aren't required.
 
-```ts
-function queryStream(
-    body: PromptQLQueryRequestV2, 
-    callback?: (data: QueryResponseChunk) => void | Promise<void>, 
-    queryOptions?: FetchOptions
-) Promise<Response>;
+Common XML tags are:
+
+- `<artifact type="table" identifier="last_5_products" />`: the identifier of the artifact block.
+- `<user_mention id="user_id" />`: mentioned user in the chat message.
+- `<user_group_mention id="group_id" />`: mentioned group in the chat message.
+- `<promptql_mention />`: represents a `@promptql` tag in the chat message.
+
+You can remove them using regular expressions or parse the message to XML elements for advanced format.
+
+```typescript
+const xmlRegex = /<\w+.*\/>/gm;
+console.log(source.replaceAll(xmlRegex, ""));
 ```
 
-#### Execute Program
+## Configuration Options
+
+```typescript
+interface PromptQLSdkOptions {
+  // Required: Project ID from PromptQL console
+  projectId: string;
+
+  // Required: Service account token for authentication
+  serviceAccountToken: string;
+
+  // Optional: Base URL of PromptQL data plane
+  // Default: 'https://promptql.ddn.hasura.app'
+  promptqlBaseUrl?: string;
+
+  // Optional: Custom authentication host (for self-hosted control plane)
+  authHost?: string;
+
+  // Optional: Custom fetch implementation
+  fetch?: typeof fetch;
+
+  // Optional: Additional headers for all requests
+  headers?: Record<string, string>;
 
-Execute a PromptQL program with your data.
+  // Optional: IANA timezone for time-based queries
+  // Default: Client's timezone
+  timezone?: string;
 
-```ts
-function executeProgram: (
-    body: PromptQLExecuteRequestV2,
-    executeOptions?: FetchOptions,
-) => Promise<PromptQlExecutionResult>
+  // Optional: DDN build ID
+  // Default: Applied build
+  buildId?: string;
+}
 ```
 
-### Version 1
+## API Reference
+
+### Class: `PromptQLSdk`
+
+#### Constructor
+
+```typescript
+new PromptQLSdk(options: PromptQLSdkOptions)
+```
 
-#### Natural Language
+#### Methods
 
-The [Natural Language Query API](https://hasura.io/docs/promptql/promptql-apis/natural-language-api/) allows you to interact with PromptQL directly, sending messages and receiving responses.
+##### `getThreads(variables)`
 
-##### Non-Streaming
+List threads with optional filtering and pagination.
 
-```ts
-function query(
-    body: PromptQLQueryRequestV1,
-    queryOptions?: FetchOptions
-) => Promise<QueryResponse>
+```typescript
+getThreads(variables: GetThreadsQueryVariables): Promise<ThreadFragment[]>
 ```
 
-##### Streaming
+##### `getThreadById(threadId)`
 
-The streaming response sends chunks of data in Server-Sent Events (SSE) format.
-If the callback isn't set the client returns the raw response and you need to handle the response manually.
+Get a specific thread by ID.
 
-```ts
-function queryStream(
-    body: PromptQLQueryRequestV1, 
-    callback?: (data: QueryResponseChunk) => void | Promise<void>, 
-    queryOptions?: FetchOptions
-) Promise<Response>;
+```typescript
+getThreadById(threadId: string): Promise<ThreadFragment | null | undefined>
 ```
 
-Example:
+##### `startThread(variables)`
 
-```ts
-client
-    .queryStream({
-        artifacts: [],
-        interactions: [
-            user_message: {
-                text: 'what can you do?',
-            }
-        ],
-    },
-    async (chunk) => {
-        console.log(chunk);
-    },
-);
+Start a new thread with a message.
+
+```typescript
+startThread(variables: StartThreadArguments): Promise<StartThreadOutput>
 ```
 
-#### Execute Program
+##### `sendMessageToThread(variables)`
 
-Execute a PromptQL program with your data.
+Send a message to an existing thread.
 
-```ts
-function executeProgram: (
-    body: PromptQLExecuteRequestV1,
-    executeOptions?: FetchOptions,
-) => Promise<PromptQlExecutionResult>
+```typescript
+sendMessageToThread(variables: SendMessageToThreadArguments): Promise<SendMessageToThreadOutput>
 ```
 
-## Development
+##### `subscribeThreadEventsByThreadId(threadId, threadEventId?)`
 
-### Generate types
+Subscribe to events from a thread. Continues indefinitely.
 
-Use the following command to update TypeScript types of PromptQL APIs from OpenAPI document.
+```typescript
+subscribeThreadEventsByThreadId(
+  threadId: string,
+  threadEventId?: string | null
+): Observable<ThreadEvent[]>
+```
 
-```bash
-npm run openapi:ts
+##### `streamThreadEventsByThreadId(threadId, threadEventId?)`
+
+Stream events from a thread. Automatically completes when interaction finishes.
+
+```typescript
+streamThreadEventsByThreadId(
+  threadId: string,
+  threadEventId?: string | null
+): Observable<ThreadEvent[]>
 ```
+
+## License
+
+Apache License 2.0 - see [LICENSE](LICENSE) file for details.
+
+## Links
+
+- [PromptQL Website](https://promptql.hasura.io)
+- [PromptQL Console](https://promptql.console.hasura.io)
+- [Hasura Documentation](https://hasura.io/docs)
+
+## Support
+
+For support, please:
+
+1. Check the [documentation](https://promptql.hasura.io)
+2. Join the [Hasura Discord community](https://discord.gg/hasura)

package/biome.json

@@ -0,0 +1,8 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.3.13/schema.json",
+	"root": false,
+	"files": {
+		"includes": ["**/*.ts", "**/*.gql", "!src/generated/*", "!dist/**/*"]
+	},
+	"extends": ["@hasura/biome-config/base"]
+}

package/package.json

@@ -1,55 +1,46 @@
 {
-  "name": "@hasura/promptql",
-  "description": "A Node.js SDK allows you to interact with PromptQL API",
-  "version": "1.0.0",
-  "license": "Apache-2.0",
-  "publishConfig": {
-    "access": "public"
-  },
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "author": "Hasura",
-  "homepage": "https://promptql.hasura.io",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/hasura/promptql-nodejs-sdk.git"
-  },
-  "bugs": {
-    "url": "https://github.com/hasura/promptql-nodejs-sdk/issues"
-  },
-  "keywords": [
-    "promptql",
-    "api",
-    "typescript"
-  ],
-  "scripts": {
-    "copy-files": "cp ./src/promptql.d.ts ./dist/promptql.d.ts",
-    "build": "tsc && vite build && npm run copy-files",
-    "release": "npm run test && changelogen --release --push && npm publish",
-    "lint": "biome check",
-    "lint:fix": "biome check --write",
-    "format": "biome format --write",
-    "test": "vitest --run",
-    "test:coverage": "vitest --coverage",
-    "prepublishOnly": "npm run build",
-    "openapi:ts": "openapi-typescript https://api.promptql.pro.hasura.io/openapi.json --export-type --root-types-no-schema-prefix --root-types -o ./src/promptql.d.ts"
-  },
-  "files": [
-    "dist/**/*"
-  ],
-  "dependencies": {
-    "@opentelemetry/api": "*"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "1.9.4",
-    "@types/node": "^25.0.10",
-    "@vitest/coverage-v8": "^4.0.18",
-    "changelogen": "^0.6.2",
-    "openapi-typescript": "^7.10.1",
-    "typescript": "^5.9.3",
-    "vite": "^7.3.1",
-    "vite-plugin-dts": "^4.5.4",
-    "vitest": "^4.0.18"
-  }
+	"name": "@hasura/promptql",
+	"description": "A Typescript SDK allows you to interact with PromptQL API",
+	"version": "2.0.0-alpha.1",
+	"license": "Apache-2.0",
+	"author": "Hasura",
+	"homepage": "https://promptql.hasura.io",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/hasura/promptql-typescript-sdk.git"
+	},
+	"bugs": {
+		"url": "https://github.com/hasura/promptql-typescript-sdk/issues"
+	},
+	"keywords": [
+		"promptql",
+		"api",
+		"typescript"
+	],
+	"main": "./dist/index.js",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+		"build": "tsup src/index.ts --format cjs,esm --dts",
+		"test": "bun test",
+		"lint": "biome check .",
+		"format": "biome check . --write",
+		"check-types": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@hasura/biome-config": "workspace:*",
+		"@hasura/typescript-config": "workspace:*",
+		"@types/bun": "latest",
+		"@types/node": "^25.1.0",
+		"tsup": "^8.5.1",
+		"typescript": "5.9.3"
+	},
+	"dependencies": {
+		"@apollo/client": "^4.1.3",
+		"@graphql-typed-document-node/core": "^3.2.0",
+		"graphql": "^16.12.0",
+		"graphql-ws": "^6.0.7",
+		"rxjs": "^7.8.2"
+	}
 }

package/src/auth/auth.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "bun:test";
+import { createPromptQLAuthTokenGenerator } from "./auth";
+
+describe("fetchPromptQLAuthToken", () => {
+  const promptqlProjectId = process.env.PROMPTQL_PROJECT_ID;
+  const serviceAccountToken = process.env.PROMPTQL_SERVICE_ACCOUNT_TOKEN;
+  if (!serviceAccountToken || !promptqlProjectId) {
+    return;
+  }
+
+  const fetchAuthToken = createPromptQLAuthTokenGenerator({
+    authHost: process.env.HASURA_AUTH_HOST,
+    projectId: promptqlProjectId,
+    promptqlGraphQLUrl: `${process.env.PROMPTQL_BASE_URL}/playground-v2-hge/v1/graphql`,
+    serviceAccountToken,
+  });
+
+  test("should fetch promptql jwt token successfully", async () => {
+    const token = await fetchAuthToken();
+    expect(token).toStartWith("eyJh");
+    const token2 = await fetchAuthToken();
+    expect(token).toEqual(token2);
+  });
+});