Skip to main content

Installation

Install and configure the Mappa SDK in your Node.js or TypeScript project.

Requirements​

  • Node.js 18 or later
  • TypeScript 4.7+ (recommended but optional)

The SDK uses native fetch, AbortController, and crypto APIs available in Node.js 18+. It also works with:

  • Bun (all versions)
  • Deno with Node compatibility mode

Package managers​

Install using your preferred package manager:

npm
npm install @mappa-ai/mappa-node
yarn
yarn add @mappa-ai/mappa-node
pnpm
pnpm add @mappa-ai/mappa-node
bun
bun add @mappa-ai/mappa-node

Basic setup​

1. Get your API key​

Obtain an API key from the Mappa Dashboard.

2. Store your API key securely​

Never commit API keys to version control. Use environment variables:

.env
MAPPA_API_KEY=your_api_key_here

Add .env to your .gitignore:

.gitignore
.env
Security Best Practices
  • Never expose API keys in client-side code - Only use keys in server-side environments
  • Use environment variables - Never hardcode keys in your source code
  • Rotate keys periodically - Regularly generate new keys and revoke old ones
  • Use separate keys for development and production - Keep environments isolated
  • Restrict key permissions - Use team settings to limit key capabilities if available
Authentication Headers

When using the REST API directly (not the SDK), include your API key in the Mappa-Api-Key header:

curl https://api.mappa.ai/v1/credits \
  -H "Mappa-Api-Key: YOUR_API_KEY"

3. Create the client​

index.ts
import { Mappa } from "@mappa-ai/mappa-node";

const mappa = new Mappa({
  apiKey: process.env.MAPPA_API_KEY!,
});

Configuration options​

The SDK accepts comprehensive configuration through MappaClientOptions:

import { Mappa } from "@mappa-ai/mappa-node";

const mappa = new Mappa({
  // Required: Your API key
  apiKey: process.env.MAPPA_API_KEY!,

  // Optional: API base URL (default: "https://api.mappa.ai")
  baseUrl: "https://api.mappa.ai",

  // Optional: Request timeout in milliseconds (default: 30000)
  timeoutMs: 30_000,

  // Optional: Maximum retry attempts for failed requests (default: 2)
  maxRetries: 2,

  // Optional: Custom headers for all requests
  defaultHeaders: {
    "X-App-Name": "my-app",
    "X-App-Version": "1.0.0",
  },

  // Optional: Custom User-Agent header
  userAgent: "MyApp/1.0.0",

  // Optional: Custom fetch implementation
  fetch: customFetch,

  // Optional: Telemetry hooks for logging/monitoring
  telemetry: {
    onRequest: ({ method, url, requestId }) => {
      console.log(`→ ${method} ${url} [${requestId}]`);
    },
    onResponse: ({ status, url, durationMs, requestId }) => {
      console.log(`← ${status} ${url} (${durationMs}ms) [${requestId}]`);
    },
    onError: ({ url, requestId, error }) => {
      console.error(`✗ ${url} [${requestId}]`, error);
    },
  },
});

Configuration reference​

OptionTypeDefaultDescription
apiKeystringRequiredYour Mappa API key
baseUrlstring"https://api.mappa.ai"API base URL
timeoutMsnumber30000Request timeout (per HTTP attempt)
maxRetriesnumber2Max retry attempts for retryable requests
defaultHeadersRecord<string, string>{}Custom headers for all requests
userAgentstringAuto-generatedCustom User-Agent header
fetchtypeof fetchNative fetchCustom fetch implementation
telemetryTelemetryundefinedHooks for request/response/error events

Environment-Specific configuration​

Development​

const mappa = new Mappa({
  apiKey: process.env.MAPPA_API_KEY!,
  timeoutMs: 60_000, // Longer timeout for debugging
  maxRetries: 0, // Disable retries to see errors immediately
  telemetry: {
    onRequest: (ctx) => console.log("Request:", ctx),
    onError: (ctx) => console.error("Error:", ctx),
  },
});

Production​

const mappa = new Mappa({
  apiKey: process.env.MAPPA_API_KEY!,
  maxRetries: 3, // More aggressive retries
  defaultHeaders: {
    "X-Service-Name": process.env.SERVICE_NAME!,
  },
  telemetry: {
    onRequest: ({ method, url, requestId }) => {
      logger.info({ method, url, requestId }, "API request");
    },
    onResponse: ({ status, durationMs, requestId }) => {
      logger.info({ status, durationMs, requestId }, "API response");
    },
    onError: ({ error, requestId }) => {
      logger.error({ error, requestId }, "API error");
    },
  },
});

Derived clients​

Create a new client with modified configuration using withOptions():

const defaultMappa = new Mappa({
  apiKey: process.env.MAPPA_API_KEY!,
  maxRetries: 2,
});

// Client with retries disabled for specific operations
const mappaNoRetry = defaultMappa.withOptions({
  maxRetries: 0,
});

// Client with longer timeout
const mappaLongTimeout = defaultMappa.withOptions({
  timeoutMs: 120_000,
});

This is useful for:

  • Disabling retries for non-idempotent operations
  • Extending timeouts for specific requests
  • Adding custom headers for certain operations

Module formats​

The SDK supports both ESM and CommonJS:

index.ts
import { Mappa } from "@mappa-ai/mappa-node";

const mappa = new Mappa({
  apiKey: process.env.MAPPA_API_KEY!,
});

CommonJS​

index.js
const { Mappa } = require("@mappa-ai/mappa-node");

const mappa = new Mappa({
  apiKey: process.env.MAPPA_API_KEY,
});

TypeScript configuration​

The SDK includes complete type definitions. For the best experience:

tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Troubleshooting​

"Cannot find module" error​

Ensure you're using Node.js 18+ with native fetch support:

node --version  # Should be >= 18.0.0

If using an older Node.js version, upgrade to Node.js 18 or later.

TypeScript errors​

If you encounter type errors, ensure your TypeScript version is 4.7+:

npm list typescript

Update if needed:

npm install -D typescript@latest

Fetch not available​

The SDK requires native fetch. This is available in:

  • Node.js 18+
  • Bun (all versions)
  • Deno (with --node-compat flag)

If using a runtime without fetch, consider upgrading to a modern runtime.

Next steps​