SDKs & Examples

Get started quickly with the official stemp Node.js/TypeScript SDK.

Installation

npm install @stemp/node

GitHub: github.com/stempapp/stemp-node

Quick Start

import { Stemp } from '@stemp/node'

const stemp = new Stemp({
  apiKey: 'sk_live_abc123...',
})

Available Namespaces

The SDK organizes functionality into namespaces:

Namespace	Description
`stemp.templates`	Create and manage loyalty card templates
`stemp.users`	Manage end users
`stemp.walletPasses`	Create and manage wallet passes
`stemp.stamps`	Stamp card operations (add, remove, reset)
`stemp.points`	Points operations (coming soon)
`stemp.webhooks`	Webhook endpoint management
`stemp.notifications`	Send push notifications to pass holders
`stemp.apiKeys`	Manage API keys
`stemp.organizations`	Organization management
`stemp.apps`	App management

Examples

import { Stemp } from '@stemp/node'

const stemp = new Stemp({ apiKey: process.env.STEMP_API_KEY! })

// List templates
const templates = await stemp.templates.list()

// Create a user
const user = await stemp.users.create({
  email: 'jane@example.com',
  name: 'Jane Doe',
})

// Create a wallet pass
const pass = await stemp.walletPasses.create('tpl_abc123', {
  userId: user.id,
})

// Add a stamp
await stemp.stamps.add(pass.id)

Advanced Usage

For lower-level access, you can instantiate the generated API classes directly:

import { createClient, createConfig } from '@stemp/node'

const config = createConfig({
  apiKey: 'sk_live_abc123...',
})
const client = createClient(config)

Webhook Verification

Node.js (Express)

import express from 'express'
import { createHmac } from 'crypto'

const app = express()
app.use(express.raw({ type: 'application/json' }))

const WEBHOOK_SECRET = process.env.STEMP_WEBHOOK_SECRET!

app.post('/webhooks/stemp', (req, res) => {
  const signature = req.headers['x-stemp-signature'] as string
  const payload = req.body.toString()

  const expected = `sha256=${createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex')}`

  if (signature !== expected) {
    return res.status(401).send('Invalid signature')
  }

  const event = JSON.parse(payload)

  switch (event.type) {
    case 'stamp.reward_triggered':
      console.log('Reward earned:', event.data)
      break
    case 'pass.installed':
      console.log('Pass installed:', event.data)
      break
  }

  res.sendStatus(200)
})

Integration Recipes

POS Stamp Card Flow

A typical point-of-sale integration for a stamp card program:

import { Stemp } from '@stemp/node'

const stemp = new Stemp({ apiKey: process.env.STEMP_API_KEY! })

async function handlePurchase(qrCode: string) {
  // 1. Look up the wallet pass by QR code
  const pass = await stemp.walletPasses.getByQrCode(qrCode)

  // 2. Add a stamp
  const stampState = await stemp.stamps.add(pass.id)

  // 3. Return the current state to the POS display
  return {
    customerName: pass.user.name,
    stamps: `${stampState.currentStamps}/${stampState.maxStampsSnapshot}`,
    timesCompleted: stampState.timesCompleted,
  }
}

SDKs & Examples

On this page