Generic Inventory SDK

Small JavaScript SDK for a REST-style inventory backend. It wraps common inventory, movement, quote comparison, medicine batch, spreadsheet sync, purchase record, and product catalog endpoints behind a single fetch-based client.

This repository contains only SDK source and examples. It does not include runtime databases, spreadsheet exports, credentials, service-account files, uploaded images, operational records, or deployment state.

Install

git clone <your-repo-url>
cd generic-inventory-sdk

The package can also be copied directly into another Node.js project by using src/index.js.

Requirements

• Node.js 18 or newer
• Or any runtime with a standards-compatible fetch

If your runtime does not provide fetch, pass one explicitly:

import { createInventorySDK } from "./src/index.js";

const sdk = createInventorySDK({
  baseUrl: "http://127.0.0.1:8780",
  fetch: yourFetchImplementation
});

Quick Start

import { createInventorySDK } from "./src/index.js";

const sdk = createInventorySDK({
  baseUrl: "http://127.0.0.1:8780"
});

const health = await sdk.health();
console.log(health);

Examples

Dashboard

const dashboard = await sdk.getDashboard();
console.log(dashboard);

Items

const items = await sdk.getItems();
console.log(items);

Create a Stock Movement

const movement = await sdk.createMovement({
  item_id: "ITEM-001",
  date: "2026-05-12",
  movement_type: "in",
  quantity: 12,
  unit: "piece",
  purpose: "restock",
  note: "SDK smoke test"
});

console.log(movement);

Spreadsheet Sync

await sdk.syncSpreadsheet();
await sdk.writebackMovementsToSpreadsheet();

Price Comparison

const compare = await sdk.comparePrices({
  keyword: "cleaning bag",
  itemId: "CLN-001"
});

console.log(compare);

API Surface

System

• health()
• getDashboard()

Items

• getItems()
• getItem(itemId)
• createItem(payload)
• updateItem(itemId, payload)
• deleteItem(itemId)

Stock Movements

• getMovements()
• createMovement(payload)
• updateMovement(movementId, payload)
• deleteMovement(movementId)

Quotes

• getQuotes()
• getQuoteAnalysis()
• createQuote(payload)
• updateQuote(quoteId, payload)
• deleteQuote(quoteId)
• comparePrices({ keyword, itemId })

Medicine Batches

• getMedicineBatches()
• createMedicineBatch(payload)
• updateMedicineBatch(batchId, payload)
• deleteMedicineBatch(batchId)

Spreadsheet Bridge

• getSpreadsheetStatus()
• syncSpreadsheet()
• writebackMovementsToSpreadsheet()

Compatibility helpers are also exported for existing spreadsheet-backed endpoints:

• getGoogleSheetStatus()
• syncGoogleSheet()
• writebackMovementsToGoogleSheet()

Purchase Records

• getPurchaseItems()
• createPurchaseItem(payload)
• updatePurchaseItem(purchaseId, payload)
• deletePurchaseItem(purchaseId)
• getPurchaseCandidates(purchaseId)
• uploadPurchaseImage(payload)
• extractPurchaseImage(payload)

Product Catalog

• getStandardProducts()
• createStandardProduct(payload)
• updateStandardProduct(productId, payload)
• deleteStandardProduct(productId)
• getStandardProductDetail(productId)
• createProductGrouping(payload)
• splitProductGrouping(payload)
• createProductAlias(payload)

Error Handling

Failed requests throw an Error with:

• error.message
• error.status
• error.payload

try {
  await sdk.getItems();
} catch (error) {
  console.error(error.message);
  console.error(error.status);
  console.error(error.payload);
}

Security Notes

• Keep credentials, spreadsheet service-account files, uploaded purchase images, and runtime databases outside the repository.
• The default baseUrl is localhost. Configure deployment URLs from your own environment rather than committing them.
• Treat spreadsheet sync endpoints as privileged operations in production.

Future Work

• TypeScript declarations
• npm publishing
• Browser bundle
• Retry, timeout, and logger options
• Auth middleware hooks
• Webhook/event helpers