Skip to content

configuration.md

Latest commit

 

History

History
272 lines (205 loc) · 5.51 KB

configuration.md

File metadata and controls

272 lines (205 loc) · 5.51 KB

Configuration Guide

Learn how to configure the Unitag API client for your needs.

Basic Configuration

The minimal configuration requires only an API key:

import { UnitagApi } from "unitag-api-client";

const api = new UnitagApi({
  apiKey: "your-api-key",
});

Configuration Options

Full Configuration Interface

interface UnitagApiConfig {
  apiKey: string; // Required: Your Unitag API key
  sandbox?: boolean; // Optional: Use sandbox environment (default: false)
  baseUrl?: string; // Optional: Custom API base URL
  timeout?: number; // Optional: Request timeout in milliseconds (default: 30000)
}

Environment Selection

Sandbox Environment

Use the sandbox for development and testing:

const api = new UnitagApi({
  apiKey: "your-sandbox-key",
  sandbox: true,
});

Sandbox Characteristics:

  • Base URL: https://api-v2.sandbox.unitag.io
  • 1,000 API calls per day
  • QR codes deleted after 6 months
  • QR codes return 404 when scanned

Production Environment

Use production for live applications:

const api = new UnitagApi({
  apiKey: "your-production-key",
  sandbox: false, // or omit, as false is default
});

Production Characteristics:

  • Base URL: https://api-v2.unitag.io
  • 1,000,000 API calls per day
  • Permanent QR codes
  • Fully functional scanning

Custom Base URL

If you're using a self-hosted Unitag instance or a custom endpoint:

const api = new UnitagApi({
  apiKey: "your-api-key",
  baseUrl: "https://custom-unitag.example.com",
});

Note: When baseUrl is provided, the sandbox option is ignored.

Request Timeout

Set a custom timeout for API requests (in milliseconds):

const api = new UnitagApi({
  apiKey: "your-api-key",
  timeout: 60000, // 60 seconds
});

Default: 30,000ms (30 seconds)

Use cases for custom timeout:

  • Batch operations: Increase timeout
  • Quick operations: Decrease timeout
  • Slow networks: Increase timeout

Environment-Based Configuration

Using Environment Variables

const api = new UnitagApi({
  apiKey: process.env.UNITAG_API_KEY!,
  sandbox: process.env.NODE_ENV !== "production",
  timeout: parseInt(process.env.UNITAG_TIMEOUT || "30000"),
});

Configuration Factory

Create a configuration factory for different environments:

// config/unitag.ts
export function createUnitagClient(
  env: "development" | "staging" | "production"
) {
  const configs = {
    development: {
      apiKey: process.env.UNITAG_DEV_KEY!,
      sandbox: true,
      timeout: 60000,
    },
    staging: {
      apiKey: process.env.UNITAG_STAGING_KEY!,
      sandbox: true,
      timeout: 45000,
    },
    production: {
      apiKey: process.env.UNITAG_PROD_KEY!,
      sandbox: false,
      timeout: 30000,
    },
  };

  return new UnitagApi(configs[env]);
}

// Usage
const api = createUnitagClient(process.env.NODE_ENV || "development");

Multiple Instances

You can create multiple client instances with different configurations:

// Sandbox client for testing
const sandboxApi = new UnitagApi({
  apiKey: process.env.SANDBOX_KEY!,
  sandbox: true,
});

// Production client
const productionApi = new UnitagApi({
  apiKey: process.env.PRODUCTION_KEY!,
  sandbox: false,
});

// Use different instances
const testQR = await sandboxApi.createQRCode({...});
const liveQR = await productionApi.createQRCode({...});

Validation

The client validates configuration on initialization:

API Key Validation

try {
  const api = new UnitagApi({
    apiKey: "", // Invalid: empty string
  });
} catch (error) {
  // Throws UnitagConfigurationError
  console.error("Invalid configuration:", error.message);
}

Valid API Key Format

  • Must be a non-empty string
  • Should be 32+ characters (typical Unitag key length)
  • Use isValidApiKey() utility to check:
import { isValidApiKey } from "unitag-api-client";

if (!isValidApiKey(apiKey)) {
  throw new Error("Invalid API key format");
}

Best Practices

1. Never Hardcode API Keys

❌ Bad:

const api = new UnitagApi({
  apiKey: "uk_1234567890abcdef",
});

✅ Good:

const api = new UnitagApi({
  apiKey: process.env.UNITAG_API_KEY!,
});

2. Use Different Keys for Different Environments

const api = new UnitagApi({
  apiKey:
    process.env.NODE_ENV === "production"
      ? process.env.UNITAG_PROD_KEY!
      : process.env.UNITAG_DEV_KEY!,
  sandbox: process.env.NODE_ENV !== "production",
});

3. Implement Timeout Based on Use Case

// For batch operations
const batchApi = new UnitagApi({
  apiKey: process.env.UNITAG_API_KEY!,
  timeout: 120000, // 2 minutes
});

// For real-time operations
const realtimeApi = new UnitagApi({
  apiKey: process.env.UNITAG_API_KEY!,
  timeout: 5000, // 5 seconds
});

4. Create a Singleton Instance

// lib/unitag.ts
let apiInstance: UnitagApi | null = null;

export function getUnitagApi(): UnitagApi {
  if (!apiInstance) {
    apiInstance = new UnitagApi({
      apiKey: process.env.UNITAG_API_KEY!,
      sandbox: process.env.NODE_ENV !== "production",
    });
  }
  return apiInstance;
}

// Usage throughout your app
import { getUnitagApi } from "./lib/unitag";
const api = getUnitagApi();

See Also