Podium TypeScript SDK

Official TypeScript SDK for the Podium API.

Installation

npm install @podiumcommerce/node-sdk

Quick Start

import { createPodiumClient } from '@podiumcommerce/node-sdk'

const client = createPodiumClient({
  apiKey: 'podium_live_your-api-key',
})

// List products
const products = await client.product.list({ page: 1 })

// Get a creator
const creator = await client.merchant.get({ creatorId: 'creator-id' })

Configuration

API Key

Provide your API key directly:

const client = createPodiumClient({
  apiKey: 'podium_live_your-api-key',
})

Or set the PODIUM_API_KEY environment variable:

export PODIUM_API_KEY=podium_live_your-api-key

const client = createPodiumClient()

Environment Detection

The SDK automatically routes to the correct environment based on your API key:

• podium_test_* → Staging API
• podium_live_* → Production API

Custom Base URL

Override the API URL for local development or custom deployments:

const client = createPodiumClient({
  apiKey: 'podium_test_your-api-key',
  baseUrl: 'http://localhost:3030/api/v1',
})

Or via environment variable:

export PODIUM_API_URL=http://localhost:3030/api/v1

Custom Headers

Add headers to all requests:

const client = createPodiumClient({
  apiKey: 'podium_live_your-api-key',
  defaultHeaders: {
    'X-Custom-Header': 'value',
  },
})

API Reference

Products

// List products
const products = await client.product.list({
  page: 1,
  limit: 20,
  categories: '1,2,3',
})

// Buy product
const order = await client.product.create({
  id: 'product-id',
  requestBody: {
    quantity: 2,
  },
})

Creators (Merchants)

// Get creator by ID
const creator = await client.merchant.get({
  creatorId: 'creator-id',
})

// List creator products
const products = await client.merchantProducts.list({
  creatorId: 'creator-id',
})

// Get creator orders
const orders = await client.merchantOrders.list({
  creatorId: 'creator-id',
})

Users

// Create user
const user = await client.user.create({
  requestBody: {
    email: '[email protected]',
    privyId: 'did:privy:xxx',
  },
})

// Get user orders
const orders = await client.userOrders.list({
  id: 'user-id',
})

// Create order for user
const order = await client.userOrder.create({
  id: 'user-id',
  requestBody: {
    productId: 'product-id',
    quantity: 1,
  },
})

NFTs

// Get NFT details
const nft = await client.nft.get({
  network: 'base',
  address: '0x1234...',
  tokenId: '42',
})

// List user NFTs
const nfts = await client.userNfTs.list({
  id: 'user-id',
})

Token Presales

// List presales
const presales = await client.tokenPresales.list()

// Get presale details
const presale = await client.tokenPresales.get({
  id: 'presale-id',
})

// Buy tokens
const purchase = await client.tokenPresales.buy({
  id: 'presale-id',
  requestBody: {
    amount: 100,
  },
})

Search

// Universal search
const results = await client.universalSearch.get({
  q: 'search query',
})

// Product search
const products = await client.search.search({
  query: 'product name',
})

Agentic Commerce (ACP)

// Get product feed for agents
const feed = await client.agentic.list({
  page: 1,
  limit: 20,
})

// Create checkout session
const session = await client.agentic.create({
  requestBody: {
    items: [{ id: 'product-id', quantity: 1 }],
  },
})

// Get checkout session
const state = await client.agentic.get({
  id: 'session-id',
})

// Update checkout session
const updated = await client.agentic.update({
  id: 'session-id',
  requestBody: {
    email: '[email protected]',
    shippingAddress: { ... },
  },
})

Available Namespaces

| Namespace | Description | |-----------|-------------| | product | Product listing and purchase | | merchant | Creator/merchant profiles | | merchantProducts | Creator product management | | merchantOrders | Creator order management | | merchantPayouts | Payout management | | user | User management | | userOrder | User order operations | | userOrders | User order listing | | userNfTs | User NFT operations | | userWallets | User wallet management | | nft | NFT details | | tokenPresales | Token presale operations | | campaigns | Campaign operations | | search | Product search | | universalSearch | Cross-entity search | | agentic | Agentic commerce (ACP) | | categories | Product categories | | discover | Discovery feed | | forYou | Personalized feed |

See the full list of 64+ namespaces in the generated type definitions.

Error Handling

import { ApiError } from '@podiumcommerce/node-sdk'

try {
  const products = await client.product.list({ page: 1 })
} catch (error) {
  if (error instanceof ApiError) {
    console.error(`API Error ${error.status}: ${error.message}`)
    console.error('Response:', error.body)
  }
}

TypeScript Support

The SDK is fully typed. Request parameters and responses have TypeScript definitions:

// Parameters are typed
const products = await client.product.list({
  page: 1,      // number
  limit: 10,    // number
  categories: '1,2', // string
})

// IDE autocomplete works
products.data    // typed array
products.total   // number

License

MIT