Akamai NetStorage HTTP API for Node.js

0.6.1 verified Tue Apr 21 auth: no javascript maintenance

This package provides an unofficial Node.js client for interacting with the Akamai NetStorage HTTP API. It is currently at version `0.6.1` and primarily focuses on maintenance, addressing dependency updates and security vulnerabilities rather than new feature development. The library differentiates itself by providing a seemingly more robust and actively maintained alternative to Akamai's official Node.js NetStorageKit, which the README notes as having "suspicious quality." It offers both stream-based 'Advanced' APIs for uploading and downloading files, and 'Basic' APIs for common file and directory operations like `du`, `dir`, `stat`, `delete`, `mkdir`, `rmdir`, `rename`, and `symlink`. It includes helpers like `fileExists` and provides explicit handling for HTTP response codes in error objects.

Common errors

error Error: Akamai API Error. Status: 409 Conflict ↓

cause Attempting to create a directory (`mkdir`) or symlink (`symlink`) where a file or directory with the same name already exists at the target path.

fix

Implement checks (e.g., using fileExists or stat) before creating resources, or specifically handle the err.code === 409 condition in your error callback.

error Error: read ECONNRESET ↓

cause A network connection reset occurred. This can happen due to an unstable network, Akamai rate limiting abruptly closing the connection, or an incorrect host configuration causing the server to reject the connection.

fix

Verify your network stability, ensure the host is correctly configured, and check Akamai's rate limit guidance. Consider implementing retry logic with back-off.

error Error: ETIMEDOUT (or similar timeout error) ↓

cause The HTTP request to Akamai NetStorage exceeded the configured `request.timeout` value before receiving a response. This could be due to network latency, large file transfers, or an unreachable host.

fix

Check network connectivity and the correctness of the configured host. For large files, consider increasing the request.timeout value in setConfig.

Warnings

breaking The core HTTP client library, 'request', which `akamai-http-api` depends on, is officially deprecated and no longer maintained. While this package updates its dependencies, continued reliance on 'request' could lead to future compatibility issues or unpatched security vulnerabilities in the underlying HTTP layer. ↓

fix Be aware of this underlying dependency risk. Monitor 'akamai-http-api' for potential migrations to a modern HTTP client, or consider alternatives if 'request' becomes a critical blocker for your security or compliance needs.

gotcha Multiple security vulnerabilities in the 'lodash' dependency have been patched. To ensure your application is secure, it is critical to use `akamai-http-api` version `0.6.1` or higher. ↓

fix Upgrade to `akamai-http-api@0.6.1` or newer. Regularly run `npm audit` to identify and mitigate any new security advisories.

gotcha Akamai NetStorage has a soft rate limit of approximately 15 operations per second. Exceeding this limit can result in 500 series HTTP errors being returned by NetStorage, which are not automatically retried or handled by this client. ↓

fix Implement client-side rate limiting, exponential back-off, or queueing mechanisms if your application performs a high volume of NetStorage operations.

gotcha Providing an incorrect `host` value in `setConfig` (e.g., a typo) will not immediately throw an error but will cause HTTP requests to hang until the connection timeout is reached (default 20 seconds). ↓

fix Double-check the `host` value against your Akamai NetStorage configuration. Utilize the `request.timeout` option within `setConfig` to adjust the timeout duration if needed.

deprecated The configuration for HTTP request timeouts was introduced and later standardized under a nested `request` object. Direct top-level `timeout` options might be ignored or behave inconsistently in newer versions. ↓

fix Always configure HTTP request timeouts using `akamai.setConfig({ request: { timeout: milliseconds } })`.

Install

npm install akamai-http-api

yarn add akamai-http-api

pnpm add akamai-http-api

Imports

akamai
wrong
```
const akamai = require('akamai-http-api');
```
correct
```
import akamai from 'akamai-http-api';
```
The library exports a single object containing all API methods. While the package documentation primarily uses CommonJS `require`, it can be imported as a default export in ESM environments.
setConfig
```
akamai.setConfig({ /* config */ });
```
Configuration is applied globally via a method on the imported `akamai` object and must be called before performing any API operations.
upload
```
akamai.upload(stream, '/path/to/remote', callback);
```
This is one of the 'Advanced' API methods for stream-based file uploads. Other methods like `download`, `dir`, `delete` are also accessed directly from the `akamai` object.

Quickstart

This quickstart demonstrates how to initialize the `akamai-http-api` client using configuration from environment variables and then perform a basic file upload to Akamai NetStorage via a readable stream. It includes local file creation and cleanup.

const akamai = require('akamai-http-api');
const fs = require('fs');
const path = require('path');

// Ensure these environment variables are set or provide direct values
akamai.setConfig({
  keyName: process.env.AKAMAI_KEY_NAME ?? 'your-akamai-keyname',
  key: process.env.AKAMAI_KEY ?? 'your-akamai-secret-key-long-string',
  host: process.env.AKAMAI_HOST ?? 'your-netstorage-hostname.akamaihd.net',
  ssl: true, // Recommended for production
  verbose: false,
  request: {
    timeout: 30000 // 30 seconds timeout (default is 20s)
  }
});

const localTempDir = './temp_akamai_uploads';
if (!fs.existsSync(localTempDir)) {
  fs.mkdirSync(localTempDir);
}
const localFilePath = path.join(localTempDir, 'example-upload.txt');
const remoteFilePath = '/12345/MyFolder/example-upload.txt'; // Replace 12345 with your CP code

// Create a dummy file for upload
fs.writeFileSync(localFilePath, 'Hello Akamai NetStorage from node-akamai-http-api!');
console.log(`Created local file: ${localFilePath}`);

const uploadStream = fs.createReadStream(localFilePath);

akamai.upload(uploadStream, remoteFilePath, function (err, data) {
  if (err) {
    console.error('Akamai upload failed:', err.message || err);
    // Clean up even on error
    fs.unlinkSync(localFilePath);
    fs.rmdirSync(localTempDir);
    return;
  }
  console.log('Akamai upload successful:', data);

  // Clean up the dummy file and directory
  fs.unlinkSync(localFilePath);
  fs.rmdirSync(localTempDir);
  console.log(`Cleaned up local file: ${localFilePath}`);
});