Guide

Getting started

Everything you need to go from install to your first upload.

Install

npm install ts-netstorageapi-akamai

Node.js 18 or newer. Types are included; no @types package is needed.

Configure

import Netstorage from "ts-netstorageapi-akamai";

const ns = new Netstorage({
  hostname: "example-nsu.akamaihd.net", // NetStorage HTTP API hostname
  keyName: "upload-user",               // upload account key name
  key: process.env.NETSTORAGE_KEY!,     // upload account key
  cpCode: "123456",                     // your CP code
  ssl: true,                            // https; defaults to false (http)
  proxy: "http://proxy.internal:3128",  // optional
});

Option	Type	Description
`hostname`	string	The HTTP API hostname of your NetStorage upload account, e.g. `example-nsu.akamaihd.net`.
`keyName`	string	The key name (upload account) used to sign requests.
`key`	string	The HTTP API key. Read it from an environment variable or a secret store; never commit it.
`cpCode`	string	Your CP code. Every NetStorage path starts with it, e.g. `/123456/images/logo.png`.
`ssl`	boolean	Use https when `true`. Defaults to `false`.
`proxy`	string	Optional `http://` or `https://` proxy URL. Requests are tunnelled with CONNECT.

The hostname is your storage group's [prefix]-nsu.akamaihd.net domain, and the key name and key come from the HTTP API settings of an upload account in Akamai Control Center. New to this? Read NetStorage basics first.

Importing

import Netstorage from "ts-netstorageapi-akamai";

const Netstorage = require("ts-netstorageapi-akamai").default;

import pkg from "ts-netstorageapi-akamai";
const Netstorage = pkg.default;

Promises and callbacks

Every method comes in two forms. Callbacks receive (err, response, body), where response is Node's http.IncomingMessage; promise methods end in Async and resolve with the body.

const { du } = await ns.duAsync("/123456");

ns.du("/123456", (err, res, body) => {
  if (err) throw err;
  console.log(res?.statusCode, body?.du["du-info"][0].bytes);
});

Responses and errors

XML responses are parsed: the root element's attributes become attribs, and each child element becomes a list of its attributes, e.g. body.stat.file[0].name. All values are strings.
Plain-text bodies are returned as { message }. An empty 200 upload response becomes { message: "Request Processed." }.
HTTP errors do not throw. Network errors, invalid arguments and local file errors reject the promise (or reach err), but a 403 or 404 resolves with the parsed error body, as in Akamai's own client. Use the callback form when you need the status code.
A connection that drops before the response is complete reports an ECONNRESET error.

ns.stat("/123456/maybe.txt", (err, res, body) => {
  if (err) throw err;            // network or argument error
  if (res?.statusCode === 404) { /* not found */ }
});

Try the response shapes in the XML explorer.

Proxy

const ns = new Netstorage({ ...config, proxy: "http://user:pass@proxy.internal:3128" });

Requests go through the proxy with CONNECT, for both ssl: true and ssl: false. The proxy library is only loaded when a proxy is set.

TypeScript

import Netstorage, { AkamaiConfig, DirResponse, DirResponseFile, StatResponse } from "ts-netstorageapi-akamai";

const files: DirResponseFile[] = (await ns.dirAsync("/123456")).stat.file;

Every type is listed in the API reference.

Node support

Node.js 18, 20, 22 and 24 are tested in CI. The package is CommonJS and works with require() and import.