FoxNose TypeScript SDK

Official TypeScript client for FoxNose Management and Flux APIs. Async-only, type-safe, with zero dependencies.

Version:LatestLicense:Apache 2.0

Overview

The FoxNose TypeScript SDK provides a convenient way to interact with FoxNose APIs from your Node.js applications. It includes two main clients:

ManagementClient — For administrative operations: managing folders, components, resources, roles, and API keys
FluxClient — For content delivery: fetching published resources, searching content, and accessing localized data

Features

Type-safe — Full TypeScript interfaces for all API responses
Async-only — Built on native fetch (Node 18+)
Automatic retries — Exponential backoff with jitter and Retry-After support
Four auth strategies — Anonymous, JWT, Simple key, and Secure (ECDSA P-256)
Zero dependencies — Uses only Node.js built-in modules
Dual output — ESM and CommonJS builds with full .d.ts declarations

Installation

npm install @foxnose/sdk
# or
pnpm add @foxnose/sdk

Quick Start

Management Client

import { ManagementClient, SimpleKeyAuth } from '@foxnose/sdk';

const client = new ManagementClient({
  baseUrl: 'https://api.foxnose.net',
  environmentKey: 'your-environment-key',
  auth: new SimpleKeyAuth('YOUR_PUBLIC_KEY', 'YOUR_SECRET_KEY'),
});

// List folders
const folders = await client.listFolders();
console.log(folders.results);

// Create a resource
const resource = await client.createResource('my-folder-key', {
  data: { title: 'Hello World' },
});

client.close();

Flux Client

import { FluxClient, SimpleKeyAuth } from '@foxnose/sdk';

const client = new FluxClient({
  baseUrl: 'https://your-env.fxns.io',
  apiPrefix: 'content',
  auth: new SimpleKeyAuth('YOUR_PUBLIC_KEY', 'YOUR_SECRET_KEY'),
});

// List resources
const resources = await client.listResources('articles');

// Vector search
const results = await client.search('articles', {
  search_mode: 'vector',
  vector_search: {
    query: 'how to build AI applications',
    top_k: 5,
  },
});

client.close();

Authentication

The SDK supports four authentication strategies:

Strategy	Use case
`SimpleKeyAuth`	Development and Flux API access
`SecureKeyAuth`	Production — ECDSA P-256 signed requests
`JWTAuth`	Server-side apps with user tokens
`AnonymousAuth`	Unauthenticated endpoints

import { SimpleKeyAuth, SecureKeyAuth, JWTAuth, AnonymousAuth } from '@foxnose/sdk';

// Simple key pair
const simple = new SimpleKeyAuth('public-key', 'secret-key');

// ECDSA P-256 signature
const secure = new SecureKeyAuth('public-key', 'base64-der-private-key');

// JWT token
const jwt = JWTAuth.fromStaticToken('your-access-token');

// No authentication
const anon = new AnonymousAuth();

Batch Operations

Efficiently upsert multiple resources with concurrency control:

const items = [
  { external_id: 'article-1', payload: { data: { title: 'First' } } },
  { external_id: 'article-2', payload: { data: { title: 'Second' } } },
];

const result = await client.batchUpsertResources('folder-key', items, {
  maxConcurrency: 5,
  onProgress: (completed, total) => console.log(`${completed}/${total}`),
});

console.log(`OK: ${result.succeeded.length}, Failed: ${result.failed.length}`);

Error Handling

All API errors are thrown as typed exceptions:

import { FoxnoseAPIError, FoxnoseTransportError } from '@foxnose/sdk';

try {
  await client.getResource('folder', 'nonexistent-key');
} catch (err) {
  if (err instanceof FoxnoseAPIError) {
    console.error(err.statusCode);  // 404
    console.error(err.errorCode);   // "not_found"
  } else if (err instanceof FoxnoseTransportError) {
    console.error('Network error:', err.message);
  }
}

Resources

GitHub Repository — Source code and issues
npm Package — Package downloads
Management API Reference — API documentation
Flux API Reference — Content delivery API docs