@proveanything/smartlinks 1.8.11 → 1.8.12

package/dist/api/index.d.ts

@@ -32,3 +32,4 @@ export { order } from "./order";
 export { app } from "./appObjects";
 export { attestations } from "./attestations";
 export { containers } from "./containers";
+export { loyalty } from "./loyalty";

package/dist/api/index.js

@@ -35,3 +35,4 @@ export { order } from "./order";
 export { app } from "./appObjects";
 export { attestations } from "./attestations";
 export { containers } from "./containers";
+export { loyalty } from "./loyalty";

package/dist/api/loyalty.d.ts

@@ -0,0 +1,65 @@
+import type { LoyaltyScheme, LoyaltyMember, LoyaltyTransaction, LoyaltyEarningRule, LoyaltySchemeWithMembership, LoyaltyTransactionResult, LoyaltyPaginationParams, LoyaltyPaginatedResult, CreateLoyaltySchemeBody, UpdateLoyaltySchemeBody, CreateLoyaltyEarningRuleBody, UpdateLoyaltyEarningRuleBody, RecordLoyaltyTransactionBody } from "../types/loyalty";
+export declare namespace loyalty {
+    function list(collectionId: string, params?: {
+        includeDeleted?: boolean;
+    }): Promise<LoyaltyScheme[]>;
+    function get(collectionId: string, schemeId: string): Promise<LoyaltyScheme>;
+    function create(collectionId: string, body: CreateLoyaltySchemeBody): Promise<LoyaltyScheme>;
+    function update(collectionId: string, schemeId: string, body: UpdateLoyaltySchemeBody): Promise<LoyaltyScheme>;
+    function remove(collectionId: string, schemeId: string): Promise<LoyaltyScheme>;
+    function listEarningRules(collectionId: string, schemeId: string): Promise<LoyaltyEarningRule[]>;
+    function getEarningRule(collectionId: string, schemeId: string, ruleId: string): Promise<LoyaltyEarningRule>;
+    function createEarningRule(collectionId: string, schemeId: string, body: CreateLoyaltyEarningRuleBody): Promise<LoyaltyEarningRule>;
+    function updateEarningRule(collectionId: string, schemeId: string, ruleId: string, body: UpdateLoyaltyEarningRuleBody): Promise<LoyaltyEarningRule>;
+    function removeEarningRule(collectionId: string, schemeId: string, ruleId: string): Promise<LoyaltyEarningRule>;
+    function listMembers(collectionId: string, schemeId: string, params?: LoyaltyPaginationParams): Promise<LoyaltyPaginatedResult<LoyaltyMember>>;
+    function getMember(collectionId: string, schemeId: string, contactId: string): Promise<LoyaltyMember>;
+    /**
+     * Manually award or deduct points for a contact.
+     *
+     * - `points` must be a non-zero integer
+     * - Positive = award, negative = deduct
+     * - Deducting below zero returns HTTP 422 `INSUFFICIENT_BALANCE`
+     * - Supply `idempotencyKey` to safely retry without double-crediting
+     *
+     * Points earned via interaction events are awarded automatically by the
+     * server — this endpoint is for manual adjustments and admin overrides.
+     */
+    function recordTransaction(collectionId: string, schemeId: string, contactId: string, body: RecordLoyaltyTransactionBody): Promise<LoyaltyTransactionResult>;
+    function getMemberHistory(collectionId: string, schemeId: string, contactId: string, params?: LoyaltyPaginationParams): Promise<LoyaltyPaginatedResult<LoyaltyTransaction>>;
+    /**
+     * List active schemes for a collection. No authentication required.
+     */
+    function publicList(collectionId: string): Promise<LoyaltyScheme[]>;
+    /**
+     * Get a single active scheme. No authentication required.
+     */
+    function publicGet(collectionId: string, schemeId: string): Promise<LoyaltyScheme>;
+    /**
+     * List active earning rules for a scheme — useful for showing "how to earn"
+     * in a loyalty UI. No authentication required.
+     */
+    function publicListEarningRules(collectionId: string, schemeId: string): Promise<LoyaltyEarningRule[]>;
+    /**
+     * Get all active schemes with the caller's membership embedded in each.
+     *
+     * This is the primary entry point for a loyalty widget — one call gives
+     * you everything needed to render a user's loyalty status across all
+     * programs in a collection.
+     *
+     * - Authenticated: `member` is populated with balance + lifetimePoints
+     *   (or null if not yet enrolled in that scheme)
+     * - Unauthenticated: `member` is null on all schemes
+     */
+    function publicGetMe(collectionId: string): Promise<LoyaltySchemeWithMembership[]>;
+    /**
+     * Get the authenticated caller's membership (balance + lifetimePoints)
+     * on a specific scheme. Requires authentication.
+     */
+    function publicGetMine(collectionId: string, schemeId: string): Promise<LoyaltyMember>;
+    /**
+     * Get the authenticated caller's transaction history on a specific scheme.
+     * Ordered newest first. Requires authentication.
+     */
+    function publicGetMineHistory(collectionId: string, schemeId: string, params?: LoyaltyPaginationParams): Promise<LoyaltyPaginatedResult<LoyaltyTransaction>>;
+}

package/dist/api/loyalty.js

@@ -0,0 +1,139 @@
+// src/api/loyalty.ts
+import { request, post, patch, del } from "../http";
+function encodeQuery(params) {
+    const q = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined)
+            q.set(k, String(v));
+    }
+    const s = q.toString();
+    return s ? `?${s}` : "";
+}
+export var loyalty;
+(function (loyalty) {
+    // ── Admin — Schemes ───────────────────────────────────────────────────────────
+    async function list(collectionId, params = {}) {
+        return request(`/admin/collection/${encodeURIComponent(collectionId)}/loyaltyScheme${encodeQuery(params)}`);
+    }
+    loyalty.list = list;
+    async function get(collectionId, schemeId) {
+        return request(`/admin/collection/${encodeURIComponent(collectionId)}/loyaltyScheme/${encodeURIComponent(schemeId)}`);
+    }
+    loyalty.get = get;
+    async function create(collectionId, body) {
+        return post(`/admin/collection/${encodeURIComponent(collectionId)}/loyaltyScheme`, body);
+    }
+    loyalty.create = create;
+    async function update(collectionId, schemeId, body) {
+        return patch(`/admin/collection/${encodeURIComponent(collectionId)}/loyaltyScheme/${encodeURIComponent(schemeId)}`, body);
+    }
+    loyalty.update = update;
+    async function remove(collectionId, schemeId) {
+        return del(`/admin/collection/${encodeURIComponent(collectionId)}/loyaltyScheme/${encodeURIComponent(schemeId)}`);
+    }
+    loyalty.remove = remove;
+    // ── Admin — Earning Rules ─────────────────────────────────────────────────────
+    async function listEarningRules(collectionId, schemeId) {
+        return request(`/admin/collection/${encodeURIComponent(collectionId)}/loyaltyScheme/${encodeURIComponent(schemeId)}/earningRule`);
+    }
+    loyalty.listEarningRules = listEarningRules;
+    async function getEarningRule(collectionId, schemeId, ruleId) {
+        return request(`/admin/collection/${encodeURIComponent(collectionId)}/loyaltyScheme/${encodeURIComponent(schemeId)}/earningRule/${encodeURIComponent(ruleId)}`);
+    }
+    loyalty.getEarningRule = getEarningRule;
+    async function createEarningRule(collectionId, schemeId, body) {
+        return post(`/admin/collection/${encodeURIComponent(collectionId)}/loyaltyScheme/${encodeURIComponent(schemeId)}/earningRule`, body);
+    }
+    loyalty.createEarningRule = createEarningRule;
+    async function updateEarningRule(collectionId, schemeId, ruleId, body) {
+        return patch(`/admin/collection/${encodeURIComponent(collectionId)}/loyaltyScheme/${encodeURIComponent(schemeId)}/earningRule/${encodeURIComponent(ruleId)}`, body);
+    }
+    loyalty.updateEarningRule = updateEarningRule;
+    async function removeEarningRule(collectionId, schemeId, ruleId) {
+        return del(`/admin/collection/${encodeURIComponent(collectionId)}/loyaltyScheme/${encodeURIComponent(schemeId)}/earningRule/${encodeURIComponent(ruleId)}`);
+    }
+    loyalty.removeEarningRule = removeEarningRule;
+    // ── Admin — Members ───────────────────────────────────────────────────────────
+    async function listMembers(collectionId, schemeId, params = {}) {
+        return request(`/admin/collection/${encodeURIComponent(collectionId)}/loyaltyScheme/${encodeURIComponent(schemeId)}/member${encodeQuery(params)}`);
+    }
+    loyalty.listMembers = listMembers;
+    async function getMember(collectionId, schemeId, contactId) {
+        return request(`/admin/collection/${encodeURIComponent(collectionId)}/loyaltyScheme/${encodeURIComponent(schemeId)}/member/${encodeURIComponent(contactId)}`);
+    }
+    loyalty.getMember = getMember;
+    // ── Admin — Transactions ──────────────────────────────────────────────────────
+    /**
+     * Manually award or deduct points for a contact.
+     *
+     * - `points` must be a non-zero integer
+     * - Positive = award, negative = deduct
+     * - Deducting below zero returns HTTP 422 `INSUFFICIENT_BALANCE`
+     * - Supply `idempotencyKey` to safely retry without double-crediting
+     *
+     * Points earned via interaction events are awarded automatically by the
+     * server — this endpoint is for manual adjustments and admin overrides.
+     */
+    async function recordTransaction(collectionId, schemeId, contactId, body) {
+        return post(`/admin/collection/${encodeURIComponent(collectionId)}/loyaltyScheme/${encodeURIComponent(schemeId)}/member/${encodeURIComponent(contactId)}/transaction`, body);
+    }
+    loyalty.recordTransaction = recordTransaction;
+    async function getMemberHistory(collectionId, schemeId, contactId, params = {}) {
+        return request(`/admin/collection/${encodeURIComponent(collectionId)}/loyaltyScheme/${encodeURIComponent(schemeId)}/member/${encodeURIComponent(contactId)}/history${encodeQuery(params)}`);
+    }
+    loyalty.getMemberHistory = getMemberHistory;
+    // ── Public ────────────────────────────────────────────────────────────────────
+    /**
+     * List active schemes for a collection. No authentication required.
+     */
+    async function publicList(collectionId) {
+        return request(`/public/collection/${encodeURIComponent(collectionId)}/loyaltyScheme`);
+    }
+    loyalty.publicList = publicList;
+    /**
+     * Get a single active scheme. No authentication required.
+     */
+    async function publicGet(collectionId, schemeId) {
+        return request(`/public/collection/${encodeURIComponent(collectionId)}/loyaltyScheme/${encodeURIComponent(schemeId)}`);
+    }
+    loyalty.publicGet = publicGet;
+    /**
+     * List active earning rules for a scheme — useful for showing "how to earn"
+     * in a loyalty UI. No authentication required.
+     */
+    async function publicListEarningRules(collectionId, schemeId) {
+        return request(`/public/collection/${encodeURIComponent(collectionId)}/loyaltyScheme/${encodeURIComponent(schemeId)}/earningRule`);
+    }
+    loyalty.publicListEarningRules = publicListEarningRules;
+    /**
+     * Get all active schemes with the caller's membership embedded in each.
+     *
+     * This is the primary entry point for a loyalty widget — one call gives
+     * you everything needed to render a user's loyalty status across all
+     * programs in a collection.
+     *
+     * - Authenticated: `member` is populated with balance + lifetimePoints
+     *   (or null if not yet enrolled in that scheme)
+     * - Unauthenticated: `member` is null on all schemes
+     */
+    async function publicGetMe(collectionId) {
+        return request(`/public/collection/${encodeURIComponent(collectionId)}/loyaltyScheme/me`);
+    }
+    loyalty.publicGetMe = publicGetMe;
+    /**
+     * Get the authenticated caller's membership (balance + lifetimePoints)
+     * on a specific scheme. Requires authentication.
+     */
+    async function publicGetMine(collectionId, schemeId) {
+        return request(`/public/collection/${encodeURIComponent(collectionId)}/loyaltyScheme/${encodeURIComponent(schemeId)}/member/me`);
+    }
+    loyalty.publicGetMine = publicGetMine;
+    /**
+     * Get the authenticated caller's transaction history on a specific scheme.
+     * Ordered newest first. Requires authentication.
+     */
+    async function publicGetMineHistory(collectionId, schemeId, params = {}) {
+        return request(`/public/collection/${encodeURIComponent(collectionId)}/loyaltyScheme/${encodeURIComponent(schemeId)}/member/me/history${encodeQuery(params)}`);
+    }
+    loyalty.publicGetMineHistory = publicGetMineHistory;
+})(loyalty || (loyalty = {}));

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.8.11  |  Generated: 2026-03-19T19:58:44.820Z
+Version: 1.8.12  |  Generated: 2026-03-22T11:27:19.142Z
 
 This is a concise summary of all available API functions and types.
 
@@ -26,6 +26,7 @@ For detailed guides on specific features:
 - **[App Objects: Cases, Threads & Records](app-objects.md)** - Generic app-scoped building blocks for support cases, discussions, bookings, registrations, and more
 - **[Communications](comms.md)** - Transactional sends, multi-channel broadcasts, consent management, push registration, and analytics
 - **[Interactions & Event Tracking](interactions.md)** - Log user events, count outcomes, query history, and define interaction types with permissions
+- **[Loyalty: Points, Members & Earning Rules](loyalty.md)** - Loyalty schemes, automatic point earning via interaction rules, member balances, transaction history, and manual adjustments
 - **[Deep Link Discovery](deep-link-discovery.md)** - Registering and discovering navigable app states for portal menus and AI orchestration
 - **[AI-Native App Manifests](manifests.md)** - How AI workflows discover, configure, and import apps via structured manifests and prose guides
 - **[AI Guide Template](ai-guide-template.md)** - A sample for an app on how to build an AI setup guide
@@ -79,6 +80,7 @@ The Smartlinks SDK is organized into the following namespaces:
 
 — Analytics & Events —
 - **interactions** - Log and analyze interactions/outcomes; aggregates and actor lists; interaction definition CRUD. → [Guide](interactions.md)
+- **loyalty** - Loyalty programmes: schemes, earning rules tied to interactions, member balances, transaction ledger, and manual adjustments. → [Guide](loyalty.md)
 
 — Automation —
 - **journeys** - Configure automated flows triggered by events or schedules; steps, rules; full CRUD.
@@ -4861,6 +4863,174 @@ interface LocationSearchResponse {
 
 **LocationPayload** = `Omit<`
 
+### loyalty
+
+**LoyaltyScheme** (interface)
+```typescript
+interface LoyaltyScheme {
+  id: string
+  orgId: string
+  collectionId: string
+  name: string
+  type: string
+  active: boolean
+  createdAt: string // ISO
+  updatedAt: string // ISO
+  deletedAt: string | null // ISO
+  data: DataBlock
+  owner?: DataBlock
+  admin?: DataBlock
+}
+```
+
+**LoyaltyMember** (interface)
+```typescript
+interface LoyaltyMember {
+  id: string
+  orgId: string
+  collectionId: string
+  schemeId: string
+  contactId: string
+  userId: string | null
+  balance: number
+  lifetimePoints: number
+  createdAt: string // ISO
+  updatedAt: string // ISO
+  data: DataBlock
+  owner?: DataBlock
+  admin?: DataBlock
+}
+```
+
+**LoyaltyTransaction** (interface)
+```typescript
+interface LoyaltyTransaction {
+  id: string
+  orgId: string
+  collectionId: string
+  schemeId: string
+  memberId: string
+  points: number
+  reason: string | null
+  idempotencyKey: string | null
+  metadata: DataBlock
+  createdAt: string // ISO
+}
+```
+
+**LoyaltyEarningRule** (interface)
+```typescript
+interface LoyaltyEarningRule {
+  id: string
+  orgId: string
+  collectionId: string
+  schemeId: string
+  interactionId: string
+  points: number
+  * Key-value conditions matched against the interaction event before awarding.
+  * Supports top-level event fields (outcome, scope, status, eventType, etc.)
+  * and dot-path into metadata (e.g. `"metadata.tier": "gold"`).
+  * Empty object = always fires for any event on this interaction.
+  conditions: Record<string, string>
+  maxPerContact: number | null
+  cooldownHours: number | null
+  active: boolean
+  createdAt: string // ISO
+  updatedAt: string // ISO
+  data: DataBlock
+}
+```
+
+**LoyaltyTransactionResult** (interface)
+```typescript
+interface LoyaltyTransactionResult {
+  member: LoyaltyMember
+  transaction: LoyaltyTransaction
+}
+```
+
+**LoyaltyPaginationParams** (interface)
+```typescript
+interface LoyaltyPaginationParams {
+  limit?: number  // default 50, max 200
+  offset?: number
+}
+```
+
+**LoyaltyPaginatedResult<T>** (interface)
+```typescript
+interface LoyaltyPaginatedResult<T> {
+  items: T[]
+  limit: number
+  offset: number
+}
+```
+
+**CreateLoyaltySchemeBody** (interface)
+```typescript
+interface CreateLoyaltySchemeBody {
+  name: string
+  type: string
+  active?: boolean
+  data?: DataBlock
+  owner?: DataBlock
+  admin?: DataBlock
+}
+```
+
+**UpdateLoyaltySchemeBody** (interface)
+```typescript
+interface UpdateLoyaltySchemeBody {
+  name?: string
+  type?: string
+  active?: boolean
+  data?: DataBlock
+  owner?: DataBlock
+  admin?: DataBlock
+}
+```
+
+**CreateLoyaltyEarningRuleBody** (interface)
+```typescript
+interface CreateLoyaltyEarningRuleBody {
+  interactionId: string
+  points: number
+  conditions?: Record<string, string>
+  maxPerContact?: number | null
+  cooldownHours?: number | null
+  active?: boolean
+  data?: DataBlock
+}
+```
+
+**UpdateLoyaltyEarningRuleBody** (interface)
+```typescript
+interface UpdateLoyaltyEarningRuleBody {
+  points?: number
+  conditions?: Record<string, string>
+  maxPerContact?: number | null
+  cooldownHours?: number | null
+  active?: boolean
+  data?: DataBlock
+}
+```
+
+**RecordLoyaltyTransactionBody** (interface)
+```typescript
+interface RecordLoyaltyTransactionBody {
+  points: number
+  reason?: string
+  * Optional caller-supplied key scoped to the scheme.
+  * If a transaction with this key already exists the server returns 409.
+  * Use to safely retry without double-crediting points.
+  idempotencyKey?: string
+  metadata?: DataBlock
+  userId?: string
+}
+```
+
+**DataBlock** = `Record<string, unknown>`
+
 ### nfc
 
 **NfcTagInfo** (interface)
@@ -7064,6 +7234,89 @@ Public: Fetch a global location by ID GET /public/location/:locationId
     locationId: string) → `Promise<Location>`
 Public: Fetch a location for a collection; returns either a collection-owned or global fallback GET /public/collection/:collectionId/location/:locationId
 
+### loyalty
+
+Loyalty programmes built on top of collections. Configure schemes and earning rules; contacts earn points automatically via interaction events. See the [Loyalty guide](loyalty.md) for the full walkthrough.
+
+**list**(collectionId: string,
+    params: { includeDeleted?: boolean } = {}) → `Promise<LoyaltyScheme[]>`
+
+**get**(collectionId: string,
+    schemeId: string) → `Promise<LoyaltyScheme>`
+
+**create**(collectionId: string,
+    body: CreateLoyaltySchemeBody) → `Promise<LoyaltyScheme>`
+
+**update**(collectionId: string,
+    schemeId: string,
+    body: UpdateLoyaltySchemeBody) → `Promise<LoyaltyScheme>`
+
+**remove**(collectionId: string,
+    schemeId: string) → `Promise<LoyaltyScheme>`
+
+**listEarningRules**(collectionId: string,
+    schemeId: string) → `Promise<LoyaltyEarningRule[]>`
+
+**getEarningRule**(collectionId: string,
+    schemeId: string,
+    ruleId: string) → `Promise<LoyaltyEarningRule>`
+
+**createEarningRule**(collectionId: string,
+    schemeId: string,
+    body: CreateLoyaltyEarningRuleBody) → `Promise<LoyaltyEarningRule>`
+
+**updateEarningRule**(collectionId: string,
+    schemeId: string,
+    ruleId: string,
+    body: UpdateLoyaltyEarningRuleBody) → `Promise<LoyaltyEarningRule>`
+
+**removeEarningRule**(collectionId: string,
+    schemeId: string,
+    ruleId: string) → `Promise<LoyaltyEarningRule>`
+
+**listMembers**(collectionId: string,
+    schemeId: string,
+    params: LoyaltyPaginationParams = {}) → `Promise<LoyaltyPaginatedResult<LoyaltyMember>>`
+
+**getMember**(collectionId: string,
+    schemeId: string,
+    contactId: string) → `Promise<LoyaltyMember>`
+
+**recordTransaction**(collectionId: string,
+    schemeId: string,
+    contactId: string,
+    body: RecordLoyaltyTransactionBody) → `Promise<LoyaltyTransactionResult>`
+Manually award or deduct points for a contact. - `points` must be a non-zero integer - Positive = award, negative = deduct - Deducting below zero returns HTTP 422 `INSUFFICIENT_BALANCE` - Supply `idempotencyKey` to safely retry without double-crediting Points earned via interaction events are awarded automatically by the server — this endpoint is for manual adjustments and admin overrides.
+
+**getMemberHistory**(collectionId: string,
+    schemeId: string,
+    contactId: string,
+    params: LoyaltyPaginationParams = {}) → `Promise<LoyaltyPaginatedResult<LoyaltyTransaction>>`
+Manually award or deduct points for a contact. - `points` must be a non-zero integer - Positive = award, negative = deduct - Deducting below zero returns HTTP 422 `INSUFFICIENT_BALANCE` - Supply `idempotencyKey` to safely retry without double-crediting Points earned via interaction events are awarded automatically by the server — this endpoint is for manual adjustments and admin overrides.
+
+**publicList**(collectionId: string) → `Promise<LoyaltyScheme[]>`
+List active schemes for a collection. No authentication required.
+
+**publicGet**(collectionId: string,
+    schemeId: string) → `Promise<LoyaltyScheme>`
+Get a single active scheme. No authentication required.
+
+**publicListEarningRules**(collectionId: string,
+    schemeId: string) → `Promise<LoyaltyEarningRule[]>`
+List active earning rules for a scheme — useful for showing "how to earn" in a loyalty UI. No authentication required.
+
+**publicGetMe**(collectionId: string) → `Promise<LoyaltySchemeWithMembership[]>`
+Get all active schemes with the caller's membership embedded in each. This is the primary entry point for a loyalty widget — one call gives you everything needed to render a user's loyalty status across all programs in a collection. - Authenticated: `member` is populated with balance + lifetimePoints (or null if not yet enrolled in that scheme) - Unauthenticated: `member` is null on all schemes
+
+**publicGetMine**(collectionId: string,
+    schemeId: string) → `Promise<LoyaltyMember>`
+Get the authenticated caller's membership (balance + lifetimePoints) on a specific scheme. Requires authentication.
+
+**publicGetMineHistory**(collectionId: string,
+    schemeId: string,
+    params: LoyaltyPaginationParams = {}) → `Promise<LoyaltyPaginatedResult<LoyaltyTransaction>>`
+Get the authenticated caller's transaction history on a specific scheme. Ordered newest first. Requires authentication.
+
 ### models
 
 **list**(collectionId: string, params?: AIModelListParams) → `Promise<AIModelListResponse>`