SDKs

Official TypeScript/JavaScript SDKs for building on WhaleTools. Zero dependencies, fully typed, tree-shakeable.

Quick Install

# API Client (REST)
npm install @neowhale/api-client

# Storefront SDK (React hooks)
npm install @neowhale/storefront

# Telemetry SDK (observability)
npm install @neowhale/telemetry

# All packages
npm install @neowhale/api-client @neowhale/storefront @neowhale/telemetry

@neowhale/api-client

npm

Typed REST client — zero dependencies, full API coverage

$ npm install @neowhale/api-client

import { WhaleClient } from '@neowhale/api-client';

const whale = new WhaleClient({
  apiKey: 'wk_live_...',
  storeId: 'your-store-id',
});

// List products
const products = await whale.products.list('store-id');

// Create an order
const order = await whale.orders.create('store-id', {
  customer_id: '...',
  line_items: [{ product_id: '...', quantity: 1 }],
});

// Chat with AI agent
// (SSE streaming — use the REST API directly)

@neowhale/storefront

npm

React hooks for headless commerce — cart, auth, products, analytics

$ npm install @neowhale/storefront

import { WhaleProvider, useProducts, useCart } from '@neowhale/storefront';

function App() {
  return (
    <WhaleProvider storeId="your-store-id" apiKey="wk_live_...">
      <Shop />
    </WhaleProvider>
  );
}

function Shop() {
  const { products, loading } = useProducts();
  const { cart, addItem } = useCart();

  return (
    <div>
      {products.map(p => (
        <button key={p.id} onClick={() => addItem(p.id, 1)}>
          {p.name} — ${p.price}
        </button>
      ))}
      <p>Cart: {cart.item_count} items</p>
    </div>
  );
}

@neowhale/telemetry

npm

Observability SDK — errors, events, Web Vitals, AI call tracing

$ npm install @neowhale/telemetry

import { WhaleTelemetry } from '@neowhale/telemetry';

const telemetry = new WhaleTelemetry({
  storeId: 'your-store-id',
  apiKey: 'wk_live_...',
  environment: 'production',
});

// Auto-captures unhandled errors
// Manual error capture
telemetry.captureError(new Error('Something went wrong'));

// Custom events
telemetry.trackEvent('checkout_completed', {
  order_id: '...',
  total: 49.99,
});

// AI call tracing
telemetry.traceAICall({
  model: 'claude-sonnet-4-6',
  input_tokens: 150,
  output_tokens: 320,
  duration_ms: 1200,
});

API Client Resources

The API client provides typed methods across 31 namespaces covering 200+ REST resources. Every method returns typed responses with full IntelliSense support.

Namespace	Methods	Description
products	list, get, create, update, delete	Catalog management
orders	list, get, create, update	Order management
customers	list, get, create, update	CRM
inventory	list, get, adjust, transfer	Stock levels
locations	list, get, create, update, delete	Store locations
analytics	sales, dailySales, weeklySales, traffic, funnel, attribution, inventory, customers, products	Business analytics
categories	list, get, create, update, delete	Product categories
agents	list, get, create, update, delete, conversations, messages, usage	AI agents
webhooks	list, get, create, update, delete, deliveries, test	Event subscriptions
generate	image, voice, text, video, removeBackground	AI content generation
loyalty	list, get, create, update, rewards.list, transactions.list	Loyalty programs
coupons	list, get, create, update, delete	Coupon codes
deals	list, get, create, update, delete	Discounts and deals
emailTemplates	list, get, create, update, delete	Email templates
suppliers	list, get, create, update, delete	Supplier management
purchaseOrders	list, get, create, update	Purchase orders
invoices	list, get, create, update	Invoicing
segments	list, get, create, update, delete	Customer segments
reviews	list, get, create, update, delete	Product reviews
metaAds	campaigns, adSets, ads, audiences, leads	Meta/Facebook Ads
googleAds	campaigns, adGroups, ads, keywords, audiences	Google Ads
fulfillment	list, get, create, updateStatus, addTracking	Order fulfillment
tax	list, get, create, update, delete, calculate	Tax rates
affiliates	list, get, create, update, conversions, payouts	Affiliate program
qrCodes	list, get, create, update, scans, analytics	QR codes
pipeline	stages, createStage, listDeals, getDeal, createDeal, updateDeal, moveDeal, summary	Sales pipeline
wholesale	listPricing, setPricing, deletePricing, listApplications, reviewApplication, listCustomers	Wholesale B2B
embeddings	create, search, index, delete, stats	Vector embeddings
enrichment	enrich, listProfiles, getProfile	Customer enrichment
teamMembers	list, get, create, update, delete	Team management
teamInvites	list, create, delete	Team invitations

Error Handling

import { WhaleClient, WhaleApiError } from '@neowhale/api-client';

const whale = new WhaleClient({ apiKey: 'wk_live_...' });

try {
  const product = await whale.products.get('store-id', 'product-id');
} catch (err) {
  if (err instanceof WhaleApiError) {
    console.log(err.status);     // 404
    console.log(err.type);       // "not_found_error"
    console.log(err.message);    // "Product not found"
    console.log(err.requestId);  // "req_abc123"
  }
}