@perkamo/sdk-core 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.0 - 2026-06-02
+
+### Added
+
+- Initial public SDK core package for shared Perkamo event and profile types.
+- Added `PerkamoApiError`, event ingest response types, batch response types,
+  wallet delta types, profile state types, identify response types and reward
+  redemption response types.
+- Added `canonicalJson` for stable JSON serialization of SDK payload facts.
+- Added `createTransactionId` for secure transaction ID generation.
+- Added `assertSafeEventInput` to validate required event fields and reject
+  reserved context keys that Perkamo computes server-side.
+
+### Security
+
+- Rejects client-authored computed fields such as `xp`, `wallet`, `wallets`,
+  `rewards`, `level`, `perks` and `achievements` in event context.

package/README.md

@@ -0,0 +1,39 @@
+# `@perkamo/sdk-core`
+
+Runtime-independent event types, response types, and helpers for Perkamo SDKs.
+
+See the full customer developer guide in
+[`../../docs/sdk-api.md`](../../docs/sdk-api.md).
+
+## Exports
+
+### Types
+
+- `PerkamoContextValue` / `PerkamoEventContext` / `PerkamoEventInput`
+- `EventIngestResponse` / `BatchIngestResponse`
+- `PerkamoProfile` / `PerkamoLevel` / `PerkamoUnlockedPerk` / `PerkamoProfileFlags`
+- `IdentifyResponse` / `RedeemRewardResponse`
+- `PerkamoApiError` — error class with `status: number` and `body: unknown`
+
+### 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
+
+```ts
+import { assertSafeEventInput, createTransactionId } from "@perkamo/sdk-core";
+
+const input = {
+  tenant: "commerce-test",
+  user_id: "customer_123",
+  event: "purchase.completed",
+  transaction_id: createTransactionId(),
+  context: { order_id: "order_1092" },
+  occurred_at: new Date().toISOString(),
+};
+
+assertSafeEventInput(input);
+```

package/dist/index.d.ts

@@ -0,0 +1,132 @@
+export type PerkamoContextValue = string | number | boolean | null | PerkamoContextValue[] | {
+    [key: string]: PerkamoContextValue;
+};
+export type PerkamoEventContext = Record<string, PerkamoContextValue>;
+export type PerkamoEventInput = {
+    tenant: string;
+    user_id: string;
+    event: string;
+    transaction_id: string;
+    context?: PerkamoEventContext;
+    occurred_at?: string;
+};
+export type WalletDelta = {
+    wallet: string;
+    amount: number;
+};
+export type PerkamoLevel = {
+    wallet: string;
+    level: number;
+    current: number;
+    currentLevelAt: number;
+    nextLevelAt: number | null;
+    progress: number;
+};
+export type PerkamoLevelProgress = {
+    point_name: string;
+    into_level: number;
+    to_next: number;
+    ratio: number;
+    current_level_floor: number;
+    next_level_at: number | null;
+};
+export type PerkamoUnlocked = {
+    type: string;
+    key: string;
+    name: string;
+};
+export type EventIngestResponse = {
+    applied: boolean;
+    duplicate: boolean;
+    delta: WalletDelta[];
+    leveled_up: boolean;
+    unlocked: PerkamoUnlocked[];
+    wallet_state: Record<string, number>;
+    level: PerkamoLevel | null;
+};
+export type BatchIngestResponse = {
+    results: EventIngestResponse[];
+};
+export type PerkamoUnlockedPerk = {
+    key: string;
+    unlocked_at: string;
+    metadata: Record<string, unknown>;
+};
+export type PerkamoNextPerk = {
+    key: string;
+    name: string;
+    description: string;
+    trigger?: Record<string, unknown>;
+    card?: {
+        title: string;
+        description: string;
+        animation: string;
+    };
+};
+export type PerkamoAchievements = {
+    completed: Array<{
+        key: string;
+        name: string;
+    }>;
+    in_progress: Array<{
+        key: string;
+        name: string;
+        current: number;
+        target: number;
+    }>;
+    unlocked: Array<{
+        key: string;
+        cycle: number;
+    }>;
+};
+export type PerkamoProfileFlags = {
+    levels: Record<string, boolean>;
+    has_level_at_least: Record<string, boolean>;
+    perks: Record<string, boolean>;
+};
+export type PerkamoProfile = {
+    user_id: string;
+    traits?: Record<string, unknown>;
+    wallets: Record<string, number>;
+    level: PerkamoLevel;
+    progress?: PerkamoLevelProgress;
+    perks: PerkamoUnlockedPerk[];
+    next_perks: PerkamoNextPerk[];
+    achievements: PerkamoAchievements;
+    flags: PerkamoProfileFlags;
+};
+export type IdentifyResponse = {
+    identified: boolean;
+    user_id: string;
+    registration_event: EventIngestResponse | null;
+    profile: {
+        tenant: string;
+        user_id: string;
+    };
+};
+export type RedeemRewardResponse = {
+    redeemed: boolean;
+    duplicate: boolean;
+    reward: {
+        key: string;
+        name: string;
+        description: string;
+        cost: {
+            wallet: string;
+            amount: number;
+        };
+    };
+    delta: WalletDelta[];
+    effect: Record<string, unknown>;
+    wallet_state: Record<string, number>;
+    level: PerkamoLevel | null;
+};
+export declare class PerkamoApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown);
+}
+export declare function canonicalJson(value: PerkamoContextValue): string;
+export declare function createTransactionId(prefix?: string): string;
+export declare function assertSafeEventInput(input: PerkamoEventInput): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,67 @@
+// ─── Error ───────────────────────────────────────────────────────────────────
+export class PerkamoApiError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        const message = body != null && typeof body === "object" && "message" in body
+            ? String(body.message)
+            : `HTTP ${status}`;
+        super(`Perkamo API error: ${message}`);
+        this.name = "PerkamoApiError";
+        this.status = status;
+        this.body = body;
+    }
+}
+// ─── Signing helpers ─────────────────────────────────────────────────────────
+const reservedContextKeys = new Set([
+    "xp",
+    "wallet",
+    "wallets",
+    "rewards",
+    "level",
+    "perks",
+    "achievements",
+]);
+function stableEntries(value) {
+    return Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+}
+export function canonicalJson(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+    }
+    return `{${stableEntries(value)
+        .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`)
+        .join(",")}}`;
+}
+export function createTransactionId(prefix = "tx") {
+    if (!globalThis.crypto?.randomUUID) {
+        throw new Error("Secure randomUUID support is required to create transaction IDs");
+    }
+    return `${prefix}_${globalThis.crypto.randomUUID()}`;
+}
+export function assertSafeEventInput(input) {
+    const required = [
+        ["tenant", input.tenant, 128],
+        ["user_id", input.user_id, 256],
+        ["event", input.event, 128],
+        ["transaction_id", input.transaction_id, 256],
+    ];
+    for (const [field, value, maxLen] of required) {
+        if (!value || typeof value !== "string") {
+            throw new Error(`Perkamo event field '${field}' is required and must be a string`);
+        }
+        if (value.length > maxLen) {
+            throw new Error(`Perkamo event field '${field}' exceeds max length of ${maxLen} characters`);
+        }
+    }
+    for (const key of Object.keys(input.context ?? {})) {
+        if (reservedContextKeys.has(key.toLowerCase())) {
+            throw new Error(`Refusing to send reserved Perkamo context field '${key}' from the SDK — ` +
+                `Perkamo computes this value server-side from your rules`);
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@perkamo/sdk-core",
+  "version": "0.1.0",
+  "description": "Runtime-independent types and security helpers for Perkamo SDKs.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "format": "prettier --write src",
+    "format:check": "prettier --check src"
+  },
+  "devDependencies": {
+    "vitest": "4.1.7"
+  }
+}