Connect Your AgentNode.js SDK

Node.js SDK

Official SDK for Node.js and TypeScript. Supports all AIGodfather features.

⚡ The npm package is coming soon. For now, use the REST API directly with fetch or any HTTP client — see the cURL / REST docs.

Install (coming soon)

npm install aigodfather

Initialize

OptionTypeDescription
apiKeystringRequired. Your API key
baseUrlstringAPI URL override (default: https://www.aigodfather.ai/api)
debugbooleanLog requests to console (default: false)
timeoutnumberRequest timeout in ms (default: 10000)
maxRetriesnumberAuto-retry on 429/5xx (default: 3)
defaultTagsstring[]Tags added to every event
defaultMetadataobjectMetadata merged into every event
onBlockcallbackCalled when a rule blocks an action
onApprovalRequiredcallbackCalled when approval is needed

Methods

.info(message, metadata?)

Informational event. Low priority in Rules Engine.

.warning(message, metadata?)

Warning event. Medium priority.

.error(message, metadata?)

Error event. High priority — always evaluated by Rules Engine.

.critical(message, metadata?)

Critical event. Highest priority.

.track(eventType, options?)

Track a custom event type. Maps to event_type on the platform.

.action(actionName, options?)

Track a specific agent action. Maps to action field. Rules Engine evaluates action field for condition matching. Supports resource, amount, currency, requiresApproval.

.waitForApproval(approvalId, interval?, timeout?)

Poll an approval request until it resolves (approved/denied/expired).

.checkApproval(approvalId)

Single poll of an approval status.

.ping()

Test connectivity and retrieve agent info + usage limits.

Response Object

Every event method returns a Promise<EventResponse>:

FieldTypeDescription
successbooleanEvent accepted
statusstring"recorded" | "blocked" | "pending_approval"
eventIdstringEvent ID
rulesMatchednumberHow many rules fired
incidentCreatedbooleanWhether an incident was opened
approvalIdstring?Present when approval required
aiClassificationobject?AI risk score and classification

Error Handling

The SDK throws specific error classes for structured error handling:

ErrorHTTPWhen
BlockedError403Rule blocked the action
PlanLimitError429Plan event limit reached
AgentPausedError503Agent is paused
⚠️ Always check the response or catch errors before proceeding with dangerous actions.
FAQPython SDK

Was this helpful?

Something wrong? Open an issue on GitHub
typescript
import { AIGodfather, BlockedError } from class="tk-str">'aigodfather'

const ai = new AIGodfather({
  apiKey: process.env.AIGODFATHER_API_KEY,
  debug: false,
  timeout: 10000,
  maxRetries: 3,
  onBlock: (err) => {
    console.error(class="tk-str">'BLOCKED:', err.message)
  },
  onApprovalRequired: (info) => {
    console.log(class="tk-str">'Approval:', info.approvalId)
  },
})

class=class="tk-str">"tk-cmt">// Track a specific action
const result = await ai.action(class="tk-str">'payment_processed', {
  resource: class="tk-str">'stripe',
  amount: 42000,
  currency: class="tk-str">'EUR',
  userId: class="tk-str">'usr_456',
  severity: class="tk-str">'high',
})

class=class="tk-str">"tk-cmt">// Handle block
if (result.status === class="tk-str">'blocked') {
  console.error(class="tk-str">'Action blocked:', result.eventId)
  return class=class="tk-str">"tk-cmt">// stop execution immediately
}

class=class="tk-str">"tk-cmt">// Handle approval required
if (result.status === class="tk-str">'pending_approval') {
  console.log(class="tk-str">'Waiting:', result.approvalId)
  const decision = await ai.waitForApproval(
    result.approvalId
  )
  if (decision.status !== class="tk-str">'approved') {
    return class=class="tk-str">"tk-cmt">// denied or expired
  }
}

class=class="tk-str">"tk-cmt">// Safe to proceed
await processPayment(...)

class=class="tk-str">"tk-cmt">// Error handling
try {
  await ai.action(class="tk-str">'delete_database', {
    severity: class="tk-str">'critical',
  })
} catch (err) {
  if (err instanceof BlockedError) {
    console.log(class="tk-str">'Blocked by rule')
  }
}