AiScribe Integration SDK

An event-driven SDK for integrating with AiScribe workspace sessions. The SDK automatically discovers new sessions, eliminating the need for webhook infrastructure.

Installation

npm install @aiscribe/integration-sdk

Quick Start

import { AiScribeClient } from "@aiscribe/integration-sdk"

const client = new AiScribeClient({
  apiKey: process.env.AISCRIBE_API_KEY!,
  apiUrl: "https://api.aiscribe.live/graphql",
})

const listener = client.createEventListener({
  workspaceIds: process.env.WORKSPACE_IDS?.split(","),
})

const subjectMap = new Map([
  [
    "123",
    {
      patientId: "987",
      name: "John Smith",
      allergies: ["peanuts"],
      vip: false,
    },
  ],
  [
    "456",
    { patientId: "654", name: "Sally Jenkins", allergies: [], vip: true },
  ],
])

listener.on("session-created", async (session) => {
  console.log(`📝 New session: ${session.sessionId}`)
  const match = subjectMap.get(session.subjectKey)
  const context = match ? JSON.stringify(match) : "{}"
  await session.updateContext(context)
})

listener.on("error", (error) => {
  console.error("❌ Error:", error)
})

listener.start()

process.on("SIGTERM", async () => {
  await listener.destroy()
  process.exit(0)
})

API Reference

AiScribeClient

Main client for creating event listeners.

Constructor

new AiScribeClient(config: AiScribeClientConfig)

Parameters:

• apiKey (string, required): Your AiScribe API key (must start with api_)
• apiUrl (string, optional): API endpoint URL (defaults to https://api.aiscribe.live/graphql)

Example:

const client = new AiScribeClient({
  apiKey: "api_xxxxxxxxxxxxx",
  apiUrl: "https://api.aiscribe.live/graphql", // optional
})

Methods

createEventListener(config?: EventListenerConfig)

Creates a new event listener that automatically discovers new sessions.

Parameters:

• config (optional): Configuration object
  • workspaceIds (string[], optional): Array of workspace UUIDs to monitor. If omitted, monitors all workspaces accessible with the API key.

Returns: EventListener

Example:

const listener = client.createEventListener({
  workspaceIds: ["workspace-uuid-1", "workspace-uuid-2"],
})

EventListener

Event emitter that automatically discovers new sessions.

Methods

start(): void

Starts the listener. Must be called to begin receiving session events.

Example:

listener.start()

stop(): void

Stops the listener.

Example:

listener.stop()

on(event: 'session-created', handler: (session: Session) => void | Promise<void>): this

Registers an event handler for session creation events.

Parameters:

• event (string): Event name ('session-created' or 'error')
• handler (function): Callback function that receives a Session object (for 'session-created') or Error (for 'error')

Example:

listener.on("session-created", async (session) => {
  console.log(`Session created: ${session.sessionId}`)
  await session.updateContext("Custom context data")
})

listener.on("error", (error) => {
  console.error("Error:", error)
})

destroy(): Promise<void>

Stops the listener and cleans up resources.

Example:

await listener.destroy()

Session

Represents a workspace session with methods to interact with it.

Properties

• sessionId (string): Unique session identifier
• workspaceId (string): Associated workspace ID
• subjectKey (string): Subject identifier for the session
• createdAt (string): ISO 8601 timestamp of creation
• updatedAt (string): ISO 8601 timestamp of last update
• envVars (Record<string, string>): Environment variables for the session

Methods

updateContext(context: string): Promise<void>

Updates the session context with custom data.

Parameters:

• context (string): The context data to associate with the session

Example:

await session.updateContext("User is a premium customer")

Authentication

The SDK uses API key authentication. To create an API key:

1. Log in to your AiScribe account
2. Navigate to Settings → API Keys
3. Click "Create New Key"
4. Save the key securely (it will only be shown once)

Use the API key in your SDK configuration:

const client = new AiScribeClient({
  apiKey: process.env.AISCRIBE_API_KEY!,
})

Security best practices:

• Store API keys in environment variables, never in code
• Use separate keys for development and production
• Revoke keys immediately if compromised
• Rotate keys periodically

Environment Variables

export AISCRIBE_API_KEY="api_xxxxxxxxxxxxx"     # required
export AISCRIBE_API_URL="https://api.aiscribe.live/graphql"  # optional
export WORKSPACE_IDS="uuid1,uuid2"              # optional

How It Works

The SDK automatically queries the GraphQL API for new sessions. It tracks the timestamp of the last check and queries for sessions created after that time, ensuring no sessions are missed using cursor-based pagination.

Local Development

Build and link the SDK, then run the demo:

cd ./integration-sdk
npm run build
npm link

# In your demo project directory
npm link @aiscribe/integration-sdk

# Run the demo
node dist/examples/basic-usage.js

Error Handling

The SDK emits errors through the event listener:

listener.on("error", (error) => {
  console.error("Polling error:", error)
})

Handle session update failures within your event handler:

listener.on("session-created", async (session) => {
  try {
    await session.updateContext("Context data")
  } catch (error) {
    console.error("Failed to update context:", error)
  }
})

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import type {
  AiScribeClientConfig,
  EventListenerConfig,
  SessionData,
} from "@aiscribe/integration-sdk"

License

MIT