@karmalicious/karma-api-js

Official JavaScript/TypeScript SDK for the Karma Common API.

Installation

npm install @karmalicious/karma-api-js

Quick Start

import { createKarmaClient } from '@karmalicious/karma-api-js'

const client = createKarmaClient({
  apiKey: 'karma_live_your_api_key_here',
  locationId: 1234,
})

Surplus

Push surplus items from your POS in one call — the SDK handles item find-or-create, date resolution, and quantity upsert automatically.

Add surplus

const result = await client.surplus.add({
  item: {
    externalId: 'sku-pasta-bolognese',
    title: 'Pasta Bolognese',
    basePriceCents: 12900,
    category: 'FOOD',
    allergens: ['GLUTEN', 'MILK'],
  },
  quantity: 5,
  discountPercentage: 50,
  date: '2024-12-20',
})

console.log(result.surplusEntry.id) // surplus entry ID
console.log(result.item.created)    // true if item was newly created

List, update, delete

// All entries (all dates), includes externalId + status
const entries = await client.surplus.list()
const filtered = await client.surplus.list({ from: '2024-12-20', to: '2024-12-22' })

// Update quantity or discount
await client.surplus.update(88421, { ministock: 3 })
await client.surplus.update(88421, { ministock: 3, discountPercentage: 70 })

// Delete
await client.surplus.delete(88421)

Error Handling

import { KarmaError } from '@karmalicious/karma-api-js'

try {
  await client.surplus.add({ ... })
} catch (err) {
  if (err instanceof KarmaError) {
    console.error(err.status, err.code, err.message)
  }
}

Environments

const client = createKarmaClient({
  apiKey: 'karma_dev_...',
  locationId: 1234,
  baseUrl: 'https://common-api.development.karma.life',
})

See docs.karma.life for the full API reference.