TypeScript SDK

The official TypeScript SDK for the Ned AI API.

Installation

npm install @ned-ai/sdk

Quick Start

import { NedClient } from '@ned-ai/sdk';

const ned = new NedClient({
  apiKey: process.env.NED_API_KEY
});

// Get today's sales
const sales = await ned.analytics.getSalesContext({ period: 'today' });
console.log(`Revenue: $${sales.summary.total_revenue}`);

Configuration

Options

const ned = new NedClient({
  // Required: Your API key
  apiKey: 'ned_live_xxxxx',

  // Optional: Custom base URL (default: https://api.meetned.com)
  baseUrl: 'https://api.meetned.com',

  // Optional: Request timeout in ms (default: 30000)
  timeout: 30000
});

Environment Variables

We recommend storing your API key in environment variables:

# .env
NED_API_KEY=ned_live_your_key_here

const ned = new NedClient({
  apiKey: process.env.NED_API_KEY!
});

Analytics

Get Sales Context

const sales = await ned.analytics.getSalesContext({
  period: 'last_7_days' // optional, default: 'today'
});

console.log(sales.summary.total_revenue);
console.log(sales.summary.total_orders);
console.log(sales.comparison.revenue_change);

Get Daily Sales

const daily = await ned.analytics.getDailySales({
  period: 'last_7_days'
});

for (const day of daily.days) {
  console.log(`${day.date}: $${day.revenue}`);
}

Get Forecast (Growth tier)

const forecast = await ned.analytics.getForecast({
  period: 'last_30_days'
});

console.log(`30-day projection: $${forecast.summary.projected_30_day_revenue}`);

Get Profitability

const profit = await ned.analytics.getProfitability({
  period: 'this_month',
  view_type: 'summary' // or 'detailed'
});

console.log(`Gross margin: ${profit.summary.gross_margin}%`);

Get Product Profitability

const products = await ned.analytics.getProductProfitability({
  period: 'this_month',
  limit: 10,
  sort: 'profit'
});

for (const product of products.products) {
  console.log(`${product.title}: $${product.gross_profit}`);
}

Get Customer Summary

const customers = await ned.analytics.getCustomerSummary({
  period: 'this_month'
});

console.log(`New customers: ${customers.summary.new_customers}`);
console.log(`Average LTV: $${customers.summary.average_ltv}`);

Get Customer Segments

const segments = await ned.analytics.getCustomerSegments({
  period: 'last_90_days'
});

for (const segment of segments.segments) {
  console.log(`${segment.label}: ${segment.customer_count} customers`);
}

Get Marketing Metrics

const marketing = await ned.analytics.getMarketingMetrics({
  period: 'last_30_days'
});

console.log(`MER: ${marketing.metrics.mer}`);
console.log(`CAC: $${marketing.metrics.cac}`);
console.log(`ROAS: ${marketing.metrics.roas}`);

Get Ad Performance

const ads = await ned.analytics.getAdPerformance({
  period: 'last_7_days',
  channel: 'meta',
  limit: 10
});

for (const ad of ads.ads) {
  console.log(`${ad.ad_name}: ROAS ${ad.roas}`);
}

Error Handling

The SDK throws typed errors for different scenarios:

import { NedClient, NedError, AuthenticationError, RateLimitError } from '@ned-ai/sdk';

try {
  const sales = await ned.analytics.getSalesContext();
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof NedError) {
    console.error(`API error: ${error.message}`);
  }
}

Error Types

Error	Description
AuthenticationError	Invalid, expired, or revoked API key (401)
ForbiddenError	Feature not available on your tier (403)
RateLimitError	Too many requests (429)
ValidationError	Invalid parameters (400)
NedError	General API error

TypeScript Types

All responses are fully typed:

import type {
  SalesContext,
  ProfitabilitySummary,
  CustomerSegments,
  MarketingMetrics
} from '@ned-ai/sdk';

const sales: SalesContext = await ned.analytics.getSalesContext();

Examples

Dashboard Integration

async function getDashboardData() {
  const ned = new NedClient({ apiKey: process.env.NED_API_KEY! });

  const [sales, profit, marketing] = await Promise.all([
    ned.analytics.getSalesContext({ period: 'today' }),
    ned.analytics.getProfitability({ period: 'this_month' }),
    ned.analytics.getMarketingMetrics({ period: 'last_30_days' })
  ]);

  return {
    todayRevenue: sales.summary.total_revenue,
    monthlyProfit: profit.summary.gross_profit,
    mer: marketing.metrics.mer
  };
}

Scheduled Reports

import { NedClient } from '@ned-ai/sdk';

async function generateWeeklyReport() {
  const ned = new NedClient({ apiKey: process.env.NED_API_KEY! });

  const sales = await ned.analytics.getDailySales({ period: 'last_7_days' });
  const totalRevenue = sales.days.reduce((sum, day) => sum + day.revenue, 0);

  return {
    period: 'Last 7 Days',
    totalRevenue,
    averageDaily: totalRevenue / 7,
    days: sales.days
  };
}