@perkamo/sdk

Server-side JavaScript and TypeScript client for the Perkamo API.

Use this package from trusted backend code. Do not bundle server API keys into browser, mobile, or embedded widget code.

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

npm install @perkamo/sdk

Quick Start

import { createPerkamoClient } from "@perkamo/sdk";

const perkamo = createPerkamoClient({
  apiKey: () => process.env.PERKAMO_SECRET_KEY,
});

const result = await perkamo.emit(
  "customer_123",
  "purchase.completed",
  {
    order_id: "order_1092",
    amount: 12900,
    currency: "CZK",
  },
  { txId: "order_1092" },
);
// result: EventIngestResponse — delta, wallet_state, level, unlocked, …

API

createPerkamoClient(options): PerkamoClient

Only apiKey is required for a normal hosted API integration. Advanced transport options are optional.

| Option | Type | Description | | ----------- | ------------------------------------------- | --------------------------------------- | | apiKey | string \| () => string \| Promise<string> | Server API key — never in browser code | | baseUrl | string | Optional custom API endpoint override | | fetch | typeof fetch | Custom fetch for tests or edge runtimes | | timeoutMs | number | Optional timeout override; default none |

The client defaults to the hosted Perkamo API. Set baseUrl only for a custom, staging or private endpoint.

client.identify(userId, traits?): Promise<IdentifyResponse>

Creates or updates trusted customer traits through POST /v1/identify.

import type { PerkamoCustomerTraits } from "@perkamo/sdk";

const optionalLocale: string | undefined = undefined;
const traits: PerkamoCustomerTraits = {
  email: "[email protected]",
  name: "Customer Test",
  crm_id: "crm_123",
  locale: optionalLocale,
};

await perkamo.identify("customer_123", traits);

Use your application's stable user id as the Perkamo customer id. Put only non-secret customer facts your application is allowed to share in traits. Undefined object properties in traits are omitted by JSON serialization. Remove undefined values from arrays before sending customer traits. Perkamo Console uses common identity traits such as e-mail, name, phone, external id, customer id and CRM id for customer display and operator search.

client.emit(userId, event, context?, options?): Promise<EventIngestResponse>

Sends one activity event to POST /v1/events. Auto-generates a transaction ID when options.txId is omitted.

client.batch(events): Promise<BatchIngestResponse>

Sends up to 100 events in one request to POST /v1/events:batch. Each event requires an explicit transaction_id.

client.customer(userId): Promise<PerkamoCustomer>

Reads the current server-authoritative customer from GET /v1/customer/{userId}.

client.program(): Promise<PerkamoProgram>

Reads the active Space program blueprint, metrics and usage summary from GET /v1/program. Use it for customer-admin tooling that needs the configured wallets, earning rules, rewards, perks, achievements and plan usage.

client.eventCatalog(): Promise<PerkamoProgramEvent[]>

Returns program().blueprint.earningRules. Use this when your backend or admin UI needs to list configured event keys and labels without hardcoding them. Rewards in the catalog use either a fixed amount or a context formula such as {{product_price}} * 10.

client.subscribeCustomer(userId, streamToken, onCustomer, onError?): CustomerSubscription

Preview helper for the planned customer SSE stream flow. Do not treat this as a stable v1 server API contract yet; the stable v1 public HTTP API is backend-first. When customer streams are enabled for an integration, they require a short-lived stream token returned by your backend after it calls Perkamo. Never pass server API keys to browser subscriptions.

PerkamoApiError

Thrown on non-2xx responses. Has status, body, requestId, retryAfter and rateLimit properties when the API or edge gateway returns those headers.

import { PerkamoApiError } from "@perkamo/sdk";

try {
  await perkamo.emit("user", "event");
} catch (err) {
  if (err instanceof PerkamoApiError) {
    console.error(err.status, err.requestId, err.retryAfter, err.body);
  }
}

Reserved context fields

The SDK rejects context keys that Perkamo computes server-side: xp, wallet, wallets, rewards, level, perks, achievements. Use event context only for business facts (order ID, amount, category).

Security

Server API keys belong only in your backend or secret manager — never in browser, mobile, or embedded widget code. Browser-token key metadata and allowed request origins are separate from customer-site CSP, but client-safe browser routes and customer stream token verification are preview work rather than stable v1 API surface.

The SDK automatically signs mutating API requests with x-perkamo-timestamp and x-perkamo-signature, binding the method, path and raw JSON body to the server API key.