Required dependencies

npm install axios
npm install user@example.com

No native modules, no pod installs, no prebuild steps required. This is pure Node.js/TypeScript.

Project setup

1. Copy the source/ directory into your project, e.g. src/dots/.

2. Ensure your tsconfig.json includes the source directory and targets at least ES2017:

{
  "compilerOptions": {
    "target": "ES2017",
    "module": "commonjs",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

3. Set your DigitalOcean personal access token as an environment variable:

export DO_API_TOKEN="your-digitalocean-personal-access-token"

4. Import and instantiate the client from the copied source (or directly from the npm package — both work identically):

// Using the copied source
import { createApiClient } from './dots';

// Or using the npm package directly
import { createApiClient } from 'dots-wrapper';

const dots = createApiClient({ token: process.env.DO_API_TOKEN! });

5. For Express projects, create a singleton client module and import it wherever you need DigitalOcean API access.

Public API

createApiClient

function createApiClient(options: { token: string }): ApiClient;

The sole entry point. Pass your DigitalOcean personal access token. Returns a namespaced client object where each key corresponds to a resource module (e.g., dots.account, dots.droplet, dots.domain). Use this once at application startup and share the instance.

modules

const modules: Record<string, ResourceModule>;

The raw aggregation of all resource modules before they are bound to an API context. Useful if you need to inspect or extend individual modules without instantiating a full client, or when writing unit tests that mock specific modules.

getAccount (via dots.account.getAccount)

function getAccount(): Promise<AxiosResponse<{ account: Account }>>;

Fetches the DigitalOcean account associated with the provided token. Use this to verify token validity on startup, retrieve account-level rate-limit metadata, or display account status in a dashboard.

getAction / listActions (via dots.action)

function getAction(input: { action_id: number }): Promise<AxiosResponse<{ action: Action }>>;
function listActions(input: { page?: number; per_page?: number }): Promise<AxiosResponse<{ actions: Action[] }>>;

Retrieve a single action by ID or paginate through all account-level actions. Use after triggering asynchronous operations (e.g., Droplet power-off) to poll completion status.

Working examples

Scenario - Verify token and print account info

Create a startup check that confirms the API token is valid and logs basic account details.

import { createApiClient } from './dots'; // or 'dots-wrapper'

const dots = createApiClient({ token: process.env.DO_API_TOKEN! });

async function verifyAccount(): Promise<void> {
  const { data: { account } } = await dots.account.getAccount();
  console.log('Account email:', account.email);
  console.log('Droplet limit:', account.droplet_limit);
  console.log('Status:', account.status);
}

verifyAccount().catch(console.error);

Scenario - List and paginate through all actions

Poll recent infrastructure actions and filter for completed ones.

import { createApiClient } from './dots';

const dots = createApiClient({ token: process.env.DO_API_TOKEN! });

async function listCompletedActions(): Promise<void> {
  const { data: { actions } } = await dots.action.listActions({
    page: 1,
    per_page: 50,
  });

  const completed = actions.filter((a) => a.status === 'completed');
  console.log(`Completed actions (page 1): ${completed.length}`);

  for (const action of completed) {
    console.log(`[${action.type}] resource: ${action.resource_type}/${action.resource_id}`);
  }
}

listCompletedActions().catch(console.error);

Scenario - Express middleware exposing account status

Integrate the client into an Express route that returns account health.

import express from 'express';
import { createApiClient } from './dots';

const app = express();
const dots = createApiClient({ token: process.env.DO_API_TOKEN! });

app.get('/health/digitalocean', async (req, res) => {
  try {
    const { data: { account } } = await dots.account.getAccount();
    res.json({
      status: account.status,
      email: account.email,
      droplet_limit: account.droplet_limit,
    });
  } catch (err: any) {
    res.status(502).json({ error: 'DigitalOcean API unreachable', detail: err.message });
  }
});

app.listen(3000, () => console.log('Server on :3000'));

File walkthrough

• index.ts - Calls modules.common.createApiClient with all modules and exports the bound createApiClient factory and the raw modules object.
• modules.ts - Imports every resource module folder and re-exports them as a single aggregated object for the factory to consume.
• common/ - Contains createApiClient (the factory implementation) and createContext (builds the axios instance with token auth headers).
• account/ - Exports getAccount function and the Account TypeScript type.
• action/ - Exports getAction, listActions, and the Action type.
• app/ - Thirteen individual operation files covering the full App Platform API plus associated types.
• cdn-endpoint/ - Six operations for CDN endpoint lifecycle and cache purging.
• certificate/ - Four operations for certificate management.
• container-registry/ - Registry configuration and Docker credential helpers.
• customer/ - Billing and invoice retrieval operations.
• database/ - Managed database cluster operations and configuration.
• domain/ - Domain and DNS record CRUD.
• droplet/ - Core Droplet resource operations and actions.
• firewall/ - Firewall and rule set management.
• floating-ip/ - Floating IP address assignment.
• gen-ai/ - Generative AI product endpoints (newer API surface).
• image/ - Image listing and metadata updates.
• kubernetes/ - Cluster, node pool, and kubeconfig operations.
• load-balancer/ - Load balancer provisioning and rule management.
• monitoring/ - Alert policy CRUD and metrics queries.
• project/ - Project creation and resource grouping.
• region/ - Static list of available datacenter regions.
• size/ - Static list of available Droplet size slugs.
• snapshot/ - Snapshot listing and deletion.
• ssh-key/ - SSH public key CRUD.
• tag/ - Tag creation and resource tagging operations.
• types/ - Shared interfaces and enums used across multiple modules.
• volume/ - Block storage volume and attachment management.
• vpc/ - Virtual private cloud network operations.

Common pitfalls and fixes

• Missing DO_API_TOKEN at runtime: createApiClient will silently send an empty token and every request will return 401 — always assert process.env.DO_API_TOKEN is defined before constructing the client.
• esModuleInterop not enabled: axios uses a default export; without "esModuleInterop": true in tsconfig.json, imports break at runtime — add the flag.
• Strict null errors on data destructuring: DigitalOcean returns HTTP 204 for some delete operations with no body; destructuring data directly will throw — check response status before destructuring.
• Rate limiting (429): The DigitalOcean API enforces per-minute request limits; add exponential backoff around list/pagination calls rather than calling in tight loops.
• CJS vs ESM interop: If your project uses "module": "ESNext" with Node.js native ESM, axios 0.x (bundled peer) requires createRequire shims — pin axios to ^1.x or configure your bundler's interopRequireDefault.
• Pagination not automatic: List methods (listActions, listApps, etc.) do not auto-paginate — you must manually increment page and loop until the returned array length is less than per_page.

Vibe-coding prompt template

I have a DigitalOcean API wrapper located in `src/dots/` (copied from the
`user@example.com` npm package source). There is also a `USAGE.md` in the
same directory explaining the public API, real exports, and working examples.

Please help me integrate this wrapper into my existing project step by step:

1. Read `USAGE.md` and `src/dots/index.ts` to understand the public API.
2. Add a singleton `DotsClient` module that initialises `createApiClient`
   from `src/dots/index.ts` using the `DO_API_TOKEN` environment variable.
3. Wire the client into [describe your framework, e.g. Express / Fastify / Next.js API routes].
4. Implement the following specific operations using only exports visible in
   `USAGE.md`: [list your operations, e.g. list Droplets, get account info].
5. Add error handling for 401 (invalid token) and 429 (rate limit) responses.
6. Do not install additional packages beyond `axios` unless absolutely necessary.
7. Show the final file structure and any tsconfig changes required.

License and credit

See source/LICENSE if present in the copied source tree. The upstream project is published by pjpimentel under the MIT license (refer to the dots GitHub repository). Upstream npm package: user@example.com.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.