@perkamo/sdk-core

Runtime-independent event types, response types, and helpers for Perkamo SDKs.

Use this package for shared TypeScript types and input helpers. Most integrations should install @perkamo/sdk, which re-exports these utilities and adds the API client.

Full SDK documentation: https://www.perkamo.com/docs/v1/sdk

npm install @perkamo/sdk-core

Exports

Types

• PerkamoContextValue / PerkamoEventContext / PerkamoEventInput
• PerkamoCustomerTraitValue / PerkamoCustomerTraits / PerkamoIdentifyInput
• EventIngestResponse / BatchIngestResponse
• PerkamoCustomer / PerkamoLevel / PerkamoUnlockedPerk / PerkamoCustomerFlags
• PerkamoProgram / PerkamoProgramBlueprint / PerkamoProgramEvent
• IdentifyResponse / RedeemRewardResponse
• PerkamoApiError — error class with status, body, requestId, retryAfter and rateLimit metadata

Helpers

• assertSafeEventInput(input) — validates fields and rejects server-authoritative context keys
• createTransactionId(prefix?) — generates a tx_<uuid> idempotency key
• canonicalJson(value) — deterministic JSON for comparison and logging

Example

import { assertSafeEventInput, createTransactionId } from "@perkamo/sdk-core";

const input = {
  user_id: "customer_123",
  event: "purchase.completed",
  transaction_id: createTransactionId(),
  context: { order_id: "order_1092" },
  occurred_at: new Date().toISOString(),
};

assertSafeEventInput(input);

Program earning rule rewards may expose a fixed amount or a safe arithmetic formula such as {{product_price}} * 10. Formula inputs come from event context and are evaluated server-side by Perkamo.