Node.js SDK

Official Node.js/TypeScript SDK for the Girard AI API.

Installation

npm install girardai
# or
yarn add girardai
# or
pnpm add girardai

Quick Start

import { Girard AI } from 'girardai';

const client = new Girard AI({ apiKey: 'your_api_key' });

// List workflows
const workflows = await client.workflows.list();
console.log(workflows.items);

// Execute a workflow
const result = await client.workflows.execute('wf_abc123', {
  input: 'Generate a product description',
  variables: { tone: 'professional' }
});

if (result.success) {
  console.log(result.output);
} else {
  console.error(result.error);
}

Configuration

const client = new Girard AI({
  apiKey: process.env.GIRARDAI_API_KEY!,
  baseUrl: 'https://www.girardai.com/api/v1', // optional
  timeout: 30000, // optional, in milliseconds
});

Workflows

List Workflows

const workflows = await client.workflows.list({ limit: 10 });

for (const workflow of workflows.items) {
  console.log(`${workflow.name} (${workflow.id})`);
}

// Pagination
if (workflows.hasMore) {
  const nextPage = await client.workflows.list({
    cursor: workflows.nextCursor
  });
}

Get a Workflow

const workflow = await client.workflows.get('wf_abc123');
console.log(workflow.name);

Create a Workflow

const workflow = await client.workflows.create({
  name: 'My Workflow',
  description: 'A workflow that generates content',
  aiModel: 'claude-sonnet-4-20250514',
});

Update a Workflow

const workflow = await client.workflows.update('wf_abc123', {
  name: 'Updated Name',
  isActive: false,
});

Delete a Workflow

await client.workflows.delete('wf_abc123');

Execute a Workflow

// Synchronous execution (waits for completion)
const result = await client.workflows.execute('wf_abc123', {
  input: 'Write a blog post about AI',
  variables: {
    topic: 'artificial intelligence',
    length: 'medium',
  },
});

if (result.success) {
  console.log('Output:', result.output);
  console.log('Tokens used:', result.tokensUsed);
  console.log('Duration:', result.durationMs, 'ms');
} else {
  console.error('Error:', result.error);
}

// Asynchronous execution (returns immediately)
const asyncResult = await client.workflows.execute('wf_abc123', {
  input: 'Generate content',
  wait: false,
});

console.log('Run ID:', asyncResult.runId);

Runs

Get a Run

const run = await client.runs.get('run_abc123');
console.log(run.status); // 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELED'

List Runs

const runs = await client.runs.list('wf_abc123', { limit: 20 });

for (const run of runs.items) {
  console.log(`${run.id}: ${run.status}`);
}

Error Handling

import {
  Girard AI,
  GirardAIError,
  AuthenticationError,
  RateLimitError,
  NotFoundError
} from 'girardai';

try {
  const result = await client.workflows.execute('wf_abc123', {
    input: 'Generate content',
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof NotFoundError) {
    console.error('Workflow not found');
  } else if (error instanceof GirardAIError) {
    console.error(`API Error: ${error.message} (${error.code})`);
  } else {
    throw error;
  }
}

TypeScript Types

All types are exported for use in your TypeScript projects:

import type {
  Workflow,
  WorkflowRun,
  ExecutionResult,
  StepResult,
  RunStatus,
  PaginatedList,
} from 'girardai';

Requirements

• Node.js 18.0.0 or higher
• TypeScript 5.0 or higher (for TypeScript users)

License

MIT