lindoai

@lindo/sdk

TypeScript SDK for the Lindo API. Provides typed methods and interfaces for interacting with AI agents, workflows, workspace management, and analytics.

Installation

npm install @lindo/sdk
# or
yarn add @lindo/sdk
# or
pnpm add @lindo/sdk

Quick Start

import { LindoClient } from '@lindo/sdk';

const client = new LindoClient({
  apiKey: 'your-api-key',
});

// Run an agent
const result = await client.agents.run({
  agent_id: 'my-agent',
  input: { prompt: 'Hello!' },
});

// Start a workflow
const workflow = await client.workflows.start({
  workflow_name: 'publish-page',
  params: { page_id: 'page-123' },
});

// Get workspace credits
const credits = await client.workspace.getCredits();

// Get analytics
const analytics = await client.analytics.getWorkspace({
  from: '2024-01-01',
  to: '2024-01-31',
});

Configuration

const client = new LindoClient({
  apiKey: 'your-api-key',        // Required
  baseUrl: 'https://api.lindo.ai', // Optional, defaults to https://api.lindo.ai
  timeout: 30000,                  // Optional, defaults to 30000ms
});

API Reference

Agents

Run AI agents with custom inputs.

// Run an agent
const result = await client.agents.run({
  agent_id: 'my-agent',
  input: { prompt: 'Hello!' },
  stream: false, // Optional: enable streaming
});

console.log(result.success);      // boolean
console.log(result.output);       // Agent output
console.log(result.credits_used); // Credits consumed

Workflows

Manage long-running workflows.

// Start a workflow
const workflow = await client.workflows.start({
  workflow_name: 'publish-page',
  params: { page_id: 'page-123' },
});
console.log(workflow.instance_id); // Workflow instance ID

// Start multiple workflows in batch
const batch = await client.workflows.batchStart({
  workflow_name: 'publish-page',
  items: [
    { params: { page_id: 'page-1' } },
    { params: { page_id: 'page-2' } },
  ],
});

// Get workflow status
const status = await client.workflows.getStatus('instance-123');
console.log(status.status); // 'queued' | 'running' | 'paused' | 'completed' | 'failed' | 'terminated'

// Pause a workflow
await client.workflows.pause('instance-123');

// Resume a workflow
await client.workflows.resume('instance-123');

// Terminate a workflow
await client.workflows.terminate('instance-123');

Workspace

Manage workspace resources.

// Get credit balance
const credits = await client.workspace.getCredits();
console.log(credits.balance);    // Current balance
console.log(credits.allocated);  // Total allocated
console.log(credits.used);       // Total used

Analytics

Access workspace and website analytics.

// Get workspace analytics
const workspaceAnalytics = await client.analytics.getWorkspace({
  from: '2024-01-01', // Optional
  to: '2024-01-31',   // Optional
});
console.log(workspaceAnalytics.total_views);
console.log(workspaceAnalytics.unique_visitors);

// Get website analytics
const websiteAnalytics = await client.analytics.getWebsite({
  from: '2024-01-01',
  to: '2024-01-31',
});
console.log(websiteAnalytics.top_pages);

Error Handling

The SDK provides typed error classes for common error scenarios:

import {
  LindoClient,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
  ValidationError,
  ServerError,
} from '@lindo/sdk';

try {
  const result = await client.agents.run({
    agent_id: 'my-agent',
    input: {},
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid or expired API key (401)
    console.error('Please check your API key');
  } else if (error instanceof RateLimitError) {
    // Too many requests (429)
    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof NotFoundError) {
    // Resource not found (404)
    console.error('Agent not found');
  } else if (error instanceof ValidationError) {
    // Invalid request (400)
    console.error('Validation errors:', error.errors);
  } else if (error instanceof ServerError) {
    // Server error (5xx)
    console.error('Server error, please try again later');
  }
}

Error Classes

Error Class	HTTP Status	Description
AuthenticationError	401	Invalid or expired API key
ForbiddenError	403	Insufficient permissions
NotFoundError	404	Resource not found
ValidationError	400	Invalid request parameters
RateLimitError	429	Too many requests
ServerError	5xx	Internal server error
NetworkError	-	Network connection failed
TimeoutError	-	Request timed out

Types

The SDK exports TypeScript interfaces for all request and response types:

import type {
  // Agent types
  AgentRunRequest,
  AgentRunResponse,
  
  // Workflow types
  WorkflowStartRequest,
  WorkflowStartResponse,
  WorkflowBatchStartRequest,
  WorkflowBatchStartResponse,
  WorkflowStatus,
  WorkflowStatusType,
  WorkflowActionResponse,
  
  // Workspace types
  WorkspaceCredits,
  
  // Analytics types
  AnalyticsQuery,
  WorkspaceAnalytics,
  WebsiteAnalytics,
} from '@lindo/sdk';

Module Formats

The SDK supports both CommonJS and ESM:

// ESM
import { LindoClient } from '@lindo/sdk';

// CommonJS
const { LindoClient } = require('@lindo/sdk');

Development

# Build the package
pnpm build

# Run type checking
pnpm typecheck

# Run tests
pnpm test

License

MIT