📦 Flinkk Inventory Library

A lightweight and modular TypeScript wrapper for interacting with Flinkk's external inventory service. This library enables client modules (like Admin Center) to securely configure and communicate with inventory endpoints by passing configuration directly at runtime — no environment variables are used.

🎯 Features

• 🔗 Centralized SDK: Consistent API layer for inventory service operations
• 🔐 Explicit Auth: Runtime configuration with no reliance on environment variables
• ⚙️ Configurable: Caller must pass both apiUrl and token explicitly when instantiating
• 🔁 Extensible: Designed for future support of inventory operations like stock updates, product sync
• 📝 Type-Safe: Full TypeScript support with comprehensive type definitions
• 🛡️ Robust Error Handling: Descriptive error messages and graceful failure handling

📦 Installation

Since this is an internal library, import it directly from the libs directory:

import { FlinkkInventoryAPI } from "@flinkk/inventory-api";

🚀 Quick Start

Basic Usage

import { FlinkkInventoryAPI } from "@flinkk/inventory-api";

// Create an instance with explicit configuration
const api = new FlinkkInventoryAPI({
  apiUrl: "https://inventory.example.com",
  token: "your-access-token",
});

// Verify the connection
try {
  const result = await api.verifyConnection();
} catch (error) {
  console.error("Connection failed:", error.message);
}

Using the Factory Function

import { createFlinkkInventoryAPI } from "@flinkk/inventory-api";

const api = createFlinkkInventoryAPI({
  apiUrl: "https://inventory.myapp.com",
  token: "abc123",
});

await api.verifyConnection();

📚 API Reference

Constructor

new FlinkkInventoryAPI(config)

Creates a new instance of the Flinkk Inventory API client.

Parameters:

• config (FlinkkInventoryAPIConfig): Configuration object
  • apiUrl (string, required): Base URL of the inventory service
  • token (string, required): Authentication token

Throws:

• Error if apiUrl is not provided
• Error if token is not provided

Methods

verifyConnection(): Promise<VerifyConnectionResponse>

Verifies the connection to the inventory service by making a GET request to /api/inventory/verify.

Returns:

• Promise<VerifyConnectionResponse>: Connection status and details

Example:

const result = await api.verifyConnection();
// {
//   status: "connected",
//   message: "Connection verified successfully",
//   timestamp: "2024-01-15T10:30:00Z",
//   version: "1.2.3"
// }

🔧 Configuration

FlinkkInventoryAPIConfig

interface FlinkkInventoryAPIConfig {
  apiUrl: string; // Base URL of the inventory service
  token: string; // Authentication token
}

Response Types

APIResponse

interface APIResponse<T = any> {
  success: boolean;
  data?: T;
  error?: string;
  message?: string;
}

VerifyConnectionResponse

interface VerifyConnectionResponse {
  status: "connected" | "disconnected";
  message: string;
  timestamp: string;
  version?: string;
}

🧪 Usage Examples

In React Components

import { useState, useEffect } from 'react';
import { FlinkkInventoryAPI } from '@flinkk/inventory-api';

function InventorySettings() {
  const [connectionStatus, setConnectionStatus] = useState<string>('checking');

  useEffect(() => {
    const checkConnection = async () => {
      try {
        const api = new FlinkkInventoryAPI({
          apiUrl: formData.inventoryUrl,
          token: formData.apiToken
        });

        const result = await api.verifyConnection();
        setConnectionStatus(result.status);
      } catch (error) {
        setConnectionStatus('error');
        console.error('Connection check failed:', error);
      }
    };

    checkConnection();
  }, [formData]);

  return (
    <div>
      <p>Connection Status: {connectionStatus}</p>
    </div>
  );
}

In Server-Side Functions

import { FlinkkInventoryAPI } from "@flinkk/inventory-api";

export async function validateInventoryConfig(apiUrl: string, token: string) {
  const api = new FlinkkInventoryAPI({ apiUrl, token });

  try {
    const result = await api.verifyConnection();
    return { valid: true, details: result };
  } catch (error) {
    return { valid: false, error: error.message };
  }
}

With React Query

import { useQuery } from "@tanstack/react-query";
import { FlinkkInventoryAPI } from "@flinkk/inventory-api";

function useInventoryConnection(apiUrl: string, token: string) {
  return useQuery({
    queryKey: ["inventory-connection", apiUrl, token],
    queryFn: async () => {
      const api = new FlinkkInventoryAPI({ apiUrl, token });
      return api.verifyConnection();
    },
    enabled: !!(apiUrl && token),
    retry: 2,
  });
}

🚨 Error Handling

The library provides descriptive error messages for common scenarios:

try {
  const api = new FlinkkInventoryAPI({
    apiUrl: "", // Empty URL
    token: "valid-token",
  });
} catch (error) {
  console.error(error.message); // "FlinkkInventoryAPI: apiUrl is required"
}

try {
  const api = new FlinkkInventoryAPI({
    apiUrl: "https://api.example.com",
    token: "invalid-token",
  });
  await api.verifyConnection();
} catch (error) {
  console.error(error.message); // "Inventory API error: 401 Unauthorized - Invalid token"
}

🔮 Future Enhancements

The library is designed to be extensible. Planned future methods include:

• syncStock(stockData) - Push stock levels per SKU
• getAvailability(productIds) - Pull availability by product/service
• listProducts() - Get product catalog
• bulkUpdateInventory() - Batch inventory updates

🧪 Testing

To test the library in your application:

1. Unit Tests: Test instantiation and error handling
2. Integration Tests: Test with actual inventory service endpoints
3. Mock Tests: Use with React Query or other data fetching libraries

Example test:

describe("FlinkkInventoryAPI", () => {
  it("should throw error when apiUrl is missing", () => {
    expect(() => {
      new FlinkkInventoryAPI({ apiUrl: "", token: "test" });
    }).toThrow("FlinkkInventoryAPI: apiUrl is required");
  });
});

📄 License

Internal Flinkk library - ISC License