CrowTerminal TypeScript SDK

External Brain for AI Agents - Persistent memory for AI agents working with creators.

While your agent stores 10-50 lines of context, CrowTerminal stores 6 months of versioned history.

Installation

npm install crowterminal
# or
yarn add crowterminal
# or
pnpm add crowterminal

Quick Start

import { CrowTerminal } from 'crowterminal';

// Initialize with your API key
const client = new CrowTerminal('ct_your_api_key');

// Get memory for a creator
const skill = await client.memory.get('client_123');
console.log(`Niche: ${skill.primaryNiche}`);
console.log(`Engagement: ${skill.avgEngagement}%`);
console.log(`Best hooks: ${skill.hookPatterns?.join(', ')}`);

Self-Registration

Don't have an API key? Register programmatically:

import { CrowTerminal } from 'crowterminal';

// This creates a new API key and returns an initialized client
const { client, apiKey } = await CrowTerminal.register('MyBot', {
  agentDescription: 'Content optimization agent',
});
// API key is printed - save it!

Core Features

Memory Operations

// Get current skill
const skill = await client.memory.get('client_123');

// Get version history
const versions = await client.memory.getVersions('client_123', { limit: 10 });

// Compare versions
const diff = await client.memory.getDiff('client_123', 5, 10);

// Track a field over time
const pattern = await client.memory.getPattern('client_123', 'avgEngagement');
console.log(`Trend: ${pattern.trend}`); // increasing, decreasing, stable

Validate Before Changing (Prevent Mistakes)

const result = await client.memory.validate('client_123', [
  { field: 'hookPatterns', oldValue: ['POV'], newValue: ['tutorial'] },
]);

if (result.validation === 'blocked') {
  console.log("Don't make this change!");
  for (const warning of result.warnings) {
    console.log(`  - ${warning.message}`);
  }
}

Engagement Analysis (The Killer Feature)

const analysis = await client.memory.engagementAnalysis('client_123', {
  hookPatterns: ['confession'],
  contentStyle: 'casual',
  primaryNiche: 'fitness',
});

console.log(`Peak engagement: ${analysis.overallStats.peakEngagement}%`);
console.log(`Your similarity to top performers: ${analysis.overallStats.yourSimilarityToTop}`);

for (const rec of analysis.recommendations) {
  console.log(`Recommendation: ${rec}`);
}

Data Ingestion (Push Your Data)

Push platform data we can't access via API:

// Push retention data from TikTok Studio
await client.data.ingest({
  clientId: 'client_123',
  platform: 'TIKTOK',
  dataType: 'retention',
  videoId: 'video_456',
  data: {
    retentionCurve: [100, 95, 88, 75, 60, 45, 30],
    avgWatchTime: 12.5,
    completionRate: 0.3,
  },
});

// Push demographics
await client.data.ingest({
  clientId: 'client_123',
  platform: 'TIKTOK',
  dataType: 'demographics',
  data: {
    ageGroups: { '18-24': 45, '25-34': 35, '35-44': 15, '45+': 5 },
    genderSplit: { male: 40, female: 58, other: 2 },
    topCountries: ['BR', 'US', 'PT'],
  },
});

// Bulk ingest (up to 50 items)
await client.data.ingestBulk([
  { clientId: 'client_123', platform: 'TIKTOK', dataType: 'retention', data: {...} },
  { clientId: 'client_123', platform: 'TIKTOK', dataType: 'demographics', data: {...} },
]);

Intelligence (Read-Only)

// Get creator profile
const profile = await client.intelligence.getProfile('client_123');

// Get hook recommendations
const hooks = await client.intelligence.getHooks('client_123', { count: 5 });

// Get optimal posting times
const timing = await client.intelligence.getTiming('client_123');

// Get platform algorithm insights
const intel = await client.intelligence.getPlatformIntel(['TIKTOK', 'INSTAGRAM']);

Webhooks (Async Notifications)

// Register a webhook
const webhook = await client.webhooks.register({
  url: 'https://your-server.com/webhook',
  events: ['skill.updated', 'data.ingested'],
});
console.log(`Webhook ID: ${webhook.id}`);
console.log(`Secret (save this!): ${webhook.secret}`);

// List webhooks
const webhooks = await client.webhooks.list();

// Delete a webhook
await client.webhooks.delete('wh_xxx');

// Test a webhook
const test = await client.webhooks.test('https://your-server.com/webhook');

Service Status

// Check service health (no auth required)
const status = await client.status.get();
console.log(`Service status: ${status.status}`);
console.log(`Database: ${status.services.database.status}`);

// Simple ping
const pong = await client.status.ping();
console.log(pong.pong ? 'Service is up!' : 'Service is down');

Error Handling

import {
  CrowTerminal,
  AuthenticationError,
  RateLimitError,
  ResourceNotFoundError,
  ValidationError,
} from 'crowterminal';

const client = new CrowTerminal('ct_your_api_key');

try {
  const skill = await client.memory.get('client_123');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof ResourceNotFoundError) {
    console.log('Client not found');
  } else if (error instanceof ValidationError) {
    console.log('Validation failed:', error.details);
  }
}

Valid Data Types

TikTok

• retention, demographics, traffic_sources, watch_time
• audience_activity, follower_growth, video_performance
• sound_performance, hashtag_performance

Instagram

• retention, demographics, reach_sources, watch_time
• audience_activity, follower_growth, content_interactions
• story_metrics, reel_metrics

YouTube

• retention, demographics, traffic_sources, watch_time
• audience_activity, subscriber_growth, click_through_rate
• impression_sources, end_screen_performance

Webhook Events

| Event | Description | |-------|-------------| | skill.updated | Client skill was updated | | skill.version_created | New skill version created | | data.ingested | Data was ingested | | validation.blocked | Proposed change was blocked | | posting.completed | Content posted successfully | | posting.failed | Content posting failed |

Links

• Full Documentation
• MCP Manifest
• GitHub
• Contact

License

MIT