npm package: @podium-sdk/node-sdk
Description: TypeScript SDK for Podium API with namespace-style API and environment detection
Author: Podium
Latest version: 0.5.0

# Podium TypeScript SDK

Official TypeScript SDK for the Podium API.

## Installation

```bash
npm install @podiumcommerce/node-sdk
```

## Quick Start

```typescript
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:

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

Or set the `PODIUM_API_KEY` environment variable:

```bash
export PODIUM_API_KEY=podium_live_your-api-key
```

```typescript
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:

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

Or via environment variable:

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

### Custom Headers

Add headers to all requests:

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

## API Reference

### Products

```typescript
// 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)

```typescript
// 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

```typescript
// Create user
const user = await client.user.create({
  requestBody: {
    email: 'user@example.com',
    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

```typescript
// 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

```typescript
// 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

```typescript
// 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)

```typescript
// 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: 'customer@example.com',
    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

```typescript
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:

```typescript
// 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