@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