AssetFlux TypeScript SDK

Server-side TypeScript/Node.js SDK for AssetFlux. Fetch asset manifests, resolve CDN URLs, and manage gradual rollouts in your Node.js applications, SSR frameworks, or build pipelines.

Getting Started

1. Install

npm install @assetflux.io/sdk

2. Initialize

import { AssetFlux } from '@assetflux.io/sdk';

const result = await AssetFlux.init({
  projectId: 'af_your_project_id',
  apiKey: 'afk_your_sdk_key',
});

console.log(`Environment: ${result.environment}`);

3. Access the Manifest

const manifest = AssetFlux.getManifest();

for (const asset of manifest.assets) {
  console.log(`${asset.key}: ${asset.cdnUrl}`);
}

Usage

Get Manifest and Assets

const manifest = AssetFlux.getManifest();
const asset = manifest?.assets.find(a => a.key === 'home.hero.banner');

if (asset) {
  console.log(asset.cdnUrl);      // CDN URL for the active version
  console.log(asset.version.id);  // Version identifier
  console.log(asset.rollout);     // { percentage: 100 }
}

Force Refresh

const updated = await AssetFlux.refreshManifest();
console.log(`Refreshed: ${updated.assets.length} assets`);

Cache Statistics

const stats = AssetFlux.getManifestCacheStats();
console.log(stats);
// { hasCachedManifest: true, isExpired: false, ttlRemaining: 285000, assetCount: 12, ... }

Rollout Assignment

// Check if current device is in a rollout
const inRollout = AssetFlux.isInRollout(50); // 50% rollout
console.log(`In rollout: ${inRollout}`);

// Get full rollout details
const assignment = AssetFlux.getRolloutAssignment(25);
console.log(assignment);
// { identifier: '...', bucket: 42, isInRollout: false }

// Check specific asset rollout
const assetInRollout = AssetFlux.isAssetInRollout('home.hero.banner');

User-Based Rollout

await AssetFlux.init({
  projectId: 'af_...',
  apiKey: 'afk_...',
  config: {
    identifierType: 'user',
  },
});

// After user login
AssetFlux.setUserId('user_12345');

Custom HTTP Client

import { AssetFluxSDK, HttpClient } from '@assetflux.io/sdk';

const customClient: HttpClient = {
  async get(url, options) {
    const res = await myHttpLib.get(url, { headers: options?.headers });
    return { status: res.statusCode, data: res.body };
  },
};

const sdk = new AssetFluxSDK(customClient);
await sdk.init({ projectId: 'af_...', apiKey: 'afk_...' });

Configuration

await AssetFlux.init({
  projectId: 'af_...',
  apiKey: 'afk_...',
  config: {
    baseUrl: 'https://api.assetflux.io',   // API base URL
    cacheTTL: 300_000,                       // 5 minutes
    timeout: 10_000,                         // 10 seconds
    retryAttempts: 3,
    fallbackBehavior: 'cache',               // 'cache' | 'bundled' | 'error'
    identifierType: 'device',                // 'device' | 'user' | 'custom'
    backgroundRefresh: true,
    refreshInterval: 900_000,                // 15 minutes
    cacheDirectory: '/tmp/assetflux-cache',  // disk cache location
    debug: false,
  },
});

| Option | Type | Default | Description | |--------|------|---------|-------------| | baseUrl | string | https://api.assetflux.io | API base URL | | cacheTTL | number | 300000 (5m) | Manifest cache TTL in ms | | timeout | number | 10000 (10s) | Network request timeout in ms | | retryAttempts | number | 3 | Max retry attempts with exponential backoff | | fallbackBehavior | string | cache | Behavior when offline: cache, bundled, or error | | identifierType | string | device | Identifier for rollout: device, user, or custom | | backgroundRefresh | boolean | true | Enable background manifest refresh | | refreshInterval | number | 900000 (15m) | Background refresh interval in ms | | cacheDirectory | string? | OS default | Directory for disk-based manifest cache | | debug | boolean | false | Enable debug logging |

Requirements

• Node.js >= 18.0

Documentation

Full documentation is available at docs.assetflux.io/typescript.

License

BSD 3-Clause. See LICENSE for details.