Quick Start

const BASE = 'https://sandbox-api.matinee.ai/v1'

export async function call<T>(
  path: string,
  options: { idempotencyKey?: string; body?: unknown; method?: string } = {},
): Promise<T> {
  const response = await fetch(BASE + path, {
    method: options.method ?? (options.body ? 'POST' : 'GET'),
    headers: {
      Authorization: `Bearer ${process.env.MATINEE_API_KEY}`,
      'X-Organization-ID': process.env.MATINEE_ORG_ID!,
      'X-Environment': 'sandbox',
      'X-Request-ID': crypto.randomUUID(),
      'Content-Type': 'application/json',
      ...(options.idempotencyKey ? { 'Idempotency-Key': options.idempotencyKey } : {}),
    },
    body: options.body ? JSON.stringify(options.body) : undefined,
  })

  const payload = await response.json()
  if (!response.ok) throw new Error(`${payload.error.code} (${payload.meta.request_id})`)
  return payload.data as T
}

The headers are §4 of the specification; the { data, meta } envelope is §5. Success and failure both carry meta.request_id — log it, it is what support will ask for.

// 1–2. A customer, and somewhere to hold what they earn.
const customer = await call('/customers', {
  idempotencyKey: 'quick-start-customer',
  body: { external_id: 'user-0001', email: 'ada@example.com', country: 'GB' },
})
const wallet = await call('/wallets', {
  idempotencyKey: `wallet-${customer.id}`,
  body: { customer_id: customer.id, type: 'customer' },
})

// 3. The asset being earned. Created configured, then activated.
const points = await call('/assets', {
  idempotencyKey: 'quick-start-points',
  body: { name: 'Points', symbol: 'PTS', type: 'points', decimals: 0 },
})
await call(`/assets/${points.id}/activate`, { idempotencyKey: `activate-${points.id}` })

// 4. A programme with one rule: 10 points per completed signup. Rules attach
//    to a draft version and take effect when the version is published.
const programme = await call('/reward-programs', {
  idempotencyKey: 'quick-start-programme',
  body: { name: 'Getting started', asset_id: points.id },
})
await call('/reward-rules', {
  idempotencyKey: 'quick-start-rule',
  body: {
    program_id: programme.id,
    event_type: 'signup.completed',
    actions: [{ type: 'issue', asset_id: points.id, amount: { fixed: '10' } }],
  },
})
await call(`/reward-programs/${programme.id}/publish`, {
  idempotencyKey: `publish-${programme.id}-v1`,
})

// 5. The event. From here on, this is the only call your system makes.
await call('/events', {
  idempotencyKey: 'signup-user-0001',
  body: {
    type: 'signup.completed',
    external_event_id: 'signup-user-0001',
    customer_id: customer.id,
    occurred_at: new Date().toISOString(),
  },
})

// 6. The balance. Rewards are issued asynchronously, so poll or subscribe to
//    the reward.issued webhook rather than asserting on the very next read.
const balances = await call(`/wallets/${wallet.id}/balances`)

Events are deduplicated on organization, environment and external_event_id — sending the same event id twice returns the original result rather than issuing twice.