SDK API Reference

import { NowAIKit } from 'nowaikit-sdk';

const kit = new NowAIKit({
  instance: 'your-instance.service-now.com',
  auth: {
    type: 'oauth',
    clientId: process.env.SN_CLIENT_ID,
    clientSecret: process.env.SN_CLIENT_SECRET,
    username: process.env.SN_USERNAME,
    password: process.env.SN_PASSWORD
  },
  timeout: 30000,
  retries: 3,
  proxy: 'http://proxy.corp.com:8080',
  debug: false
});

// Basic Auth
{ type: 'basic', username: string, password: string }

// OAuth 2.0 (Client Credentials + Password)
{ type: 'oauth', clientId: string, clientSecret: string, username: string, password: string }

// Token-based (SSO / OIDC)
{ type: 'token', accessToken: string }

// Query with filters
const incidents = await kit.incident.query({
  active: true,
  priority: 1,
  limit: 25,
  offset: 0,
  fields: ['number', 'short_description', 'state', 'assigned_to'],
  orderBy: '-sys_created_on',
  displayValue: true
});

// Returns: IncidentRecord[]

const incident = await kit.incident.get('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6');

// With field selection
const incident = await kit.incident.get('a1b2c3...d6', {
  fields: ['number', 'short_description', 'state'],
  displayValue: true
});

// Returns: IncidentRecord

const incident = await kit.incident.create({
  short_description: 'Email server unresponsive',
  description: 'Users reporting inability to send/receive emails since 09:00.',
  urgency: 1,
  impact: 1,
  category: 'email',
  assignment_group: 'IT Infrastructure'
});

console.log(incident.number);  // 'INC0012345'
console.log(incident.sys_id);  // 'a1b2c3d4...'

// Returns: IncidentRecord

const updated = await kit.incident.update('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6', {
  state: 6,              // Resolved
  close_code: 'Resolved',
  close_notes: 'Root cause identified and fixed. Email server restarted.'
});

// Returns: IncidentRecord (updated)

await kit.incident.delete('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6');
// No return value — throws NowAIKitError on failure

const results = await kit.fluent('incident')
  .where('active', true)
  .where('priority', '<=', 2)
  .orderByDesc('sys_created_on')
  .limit(25)
  .select('number', 'short_description', 'state');

// Aggregate query
const counts = await kit.fluent('incident')
  .where('active', true)
  .groupBy('category')
  .aggregate('COUNT');

// With OR conditions
const urgent = await kit.fluent('incident')
  .where('active', true)
  .orWhere('priority', 1)
  .orWhere('impact', 1)
  .select('number', 'short_description', 'priority', 'impact')
  .limit(50);

// Fetch data from 3 tables in one HTTP call
const results = await kit.batch([
  { id: 'incidents', method: 'GET', table: 'incident', query: { active: true, priority: 1 }, limit: 10 },
  { id: 'changes', method: 'GET', table: 'change_request', query: { state: 2 }, limit: 10 },
  { id: 'problems', method: 'GET', table: 'problem', query: { active: true }, limit: 10 }
]);

console.log(results.incidents);  // IncidentRecord[]
console.log(results.changes);    // ChangeRecord[]
console.log(results.problems);   // ProblemRecord[]

// Close multiple incidents in one request
const closeResults = await kit.batch([
  {
    id: 'close_1',
    method: 'PATCH',
    table: 'incident',
    sysId: 'a1b2c3d4...',
    body: { state: 7, close_code: 'Resolved', close_notes: 'Fixed via automated remediation' }
  },
  {
    id: 'close_2',
    method: 'PATCH',
    table: 'incident',
    sysId: 'b2c3d4e5...',
    body: { state: 7, close_code: 'Resolved', close_notes: 'Duplicate of INC0012345' }
  }
]);

// Check individual operation results
for (const [id, result] of Object.entries(closeResults)) {
  console.log(`${id}: ${result.success ? 'OK' : result.error}`);
}

import { NowAIKit, NowAIKitError } from 'nowaikit-sdk';

try {
  const incident = await kit.incident.get('invalid-sys-id');
} catch (error) {
  if (error instanceof NowAIKitError) {
    console.error(`Status: ${error.status}`);       // 404
    console.error(`Code: ${error.code}`);            // 'RECORD_NOT_FOUND'
    console.error(`Message: ${error.message}`);      // 'Record not found in incident table'
    console.error(`Instance: ${error.instance}`);    // 'your-instance.service-now.com'
    console.error(`RequestId: ${error.requestId}`);  // ServiceNow request correlation ID
  }
}

const kit = new NowAIKit({
  instance: 'your-instance.service-now.com',
  auth: { type: 'basic', username: 'admin', password: 'pass' },
  retries: 5,          // Retry up to 5 times
  retryDelay: 2000,    // Start with 2s delay (doubles each retry)
  timeout: 60000       // 60s timeout per request
});

import type {
  // Client
  NowAIKitConfig,
  AuthConfig,
  BasicAuth,
  OAuthAuth,
  TokenAuth,

  // Records
  ServiceNowRecord,
  IncidentRecord,
  ProblemRecord,
  ChangeRequestRecord,
  TaskRecord,
  CMDBCIRecord,
  UserRecord,
  GroupRecord,

  // Query
  QueryOptions,
  FluentQuery,
  AggregateResult,
  BatchOperation,
  BatchResult,

  // Errors
  NowAIKitError,
  ErrorCode,
} from 'nowaikit-sdk';

interface NowAIKitConfig {
  instance: string;
  auth: AuthConfig;
  timeout?: number;
  retries?: number;
  retryDelay?: number;
  proxy?: string;
  debug?: boolean;
  apiVersion?: string;
  maxConcurrent?: number;
}

interface ServiceNowRecord {
  sys_id: string;
  sys_created_on: string;
  sys_updated_on: string;
  sys_created_by: string;
  sys_updated_by: string;
  [key: string]: unknown;
}

interface IncidentRecord extends ServiceNowRecord {
  number: string;
  short_description: string;
  description: string;
  state: number;
  priority: number;
  urgency: number;
  impact: number;
  category: string;
  assigned_to: string;
  assignment_group: string;
  caller_id: string;
  resolved_at: string;
  closed_at: string;
  close_code: string;
  close_notes: string;
}

interface QueryOptions {
  limit?: number;
  offset?: number;
  fields?: string[];
  orderBy?: string;
  displayValue?: boolean;
  encodedQuery?: string;
  [key: string]: unknown;  // Field-value filters
}

interface NowAIKitError extends Error {
  status: number;
  code: ErrorCode;
  instance: string;
  requestId: string;
}

import { A2AClient } from 'nowaikit-sdk/a2a';

const a2a = new A2AClient(url: string, options?: A2AClientOptions);

// Discover the agent's capabilities
const agentCard = await a2a.discoverAgent();

// Send a task and get the result
const result = await a2a.sendTask(params: TaskSendParams);

// Send a task with SSE streaming
const stream = a2a.sendTaskStreaming(params: TaskSendParams);
for await (const event of stream) {
  console.log(event);
}

// Cancel a running task
await a2a.cancelTask(taskId: string);

// Get task status
const status = await a2a.getTask(taskId: string);

import { OAuthPKCE } from 'nowaikit-sdk/auth';

const auth = new OAuthPKCE({
  instance: 'your-instance.service-now.com',
  clientId: 'your-client-id',
  redirectUri: 'http://localhost:3000/callback',
  scopes: ['useraccount']
});

// Generate authorization URL with PKCE challenge
const { url, codeVerifier } = await auth.getAuthorizationUrl();

// Exchange code for tokens after redirect
const tokens = await auth.exchangeCode(code, codeVerifier);

// Refresh an expired token
const refreshed = await auth.refreshToken(tokens.refresh_token);

import { streamSSE } from 'nowaikit-sdk/stream';

const stream = streamSSE(url: string, options?: SSEOptions);

for await (const event of stream) {
  console.log(event.type, event.data);
}

import { SchemaCache } from 'nowaikit-sdk/cache';

const cache = new SchemaCache({ ttl: 3600000 }); // 1 hour TTL

// Get schema (fetches and caches on first call, returns cached on subsequent calls)
const schema = await cache.getSchema(kit, 'incident');

// Invalidate a specific table
cache.invalidate('incident');

// Clear all cached schemas
cache.clear();

import { NowAssistClient } from 'nowaikit-sdk/now-assist';

const assist = new NowAssistClient(kit);

// Generate a summary for a record
const summary = await assist.summarize('incident', sysId);

// Get resolution suggestions
const suggestions = await assist.suggestResolution('incident', sysId);

// Classify a record
const classification = await assist.classify('incident', sysId);

import type {
  NowConfig,
  FluentComponent,
  FluentPage,
  FluentTheme,
  FluentValidationResult,
  FluentBuildOptions,
  FluentInitOptions
} from 'nowaikit-sdk/fluent';