@smartico/public-api 0.0.419 → 0.0.421

package/src/WSAPI/WSAPIUser.ts

@@ -2,7 +2,6 @@ import { CoreUtils } from '../Core';
 import { ECacheContext, OCache } from '../OCache';
 import {
 	TActivityLog,
-	TActivityLogEntry,
 	TLevel,
 	TLevelCurrent,
 	TSegmentCheckResult,
@@ -514,15 +513,16 @@ export class WSAPIUser extends WSAPIBase {
 	}
 
 	/**
-	 * Returns the user's unified balance-change history — every points, gems, and
-	 * diamonds transaction within the requested time window, ordered newest-first.
-	 * Use to power an "Activity" / "History" tab showing wins, claims, purchases,
-	 * level-up rewards, and operator adjustments.
+	 * Returns the user's activity history within the requested time window,
+	 * ordered newest-first. Today that is primarily wallet changes (points /
+	 * gems / diamonds); when the server starts returning richer activity rows
+	 * (missions, badges, levels, …), the same method surfaces them via optional
+	 * fields on {@link TActivityLog} — no separate call, same wire CID.
 	 *
-	 * The returned shape is the same regardless of currency type — `type` (see
-	 * {@link UserBalanceType}) distinguishes points / gems / diamonds and
-	 * `source_type_id` (see {@link PointChangeSourceType}) names the originating
-	 * event.
+	 * Existing wallet fields (`type`, `amount`, `balance`, `source_type_id`, …)
+	 * stay stable. Clients that only read those keep working; clients that want
+	 * the fuller feed can also read `activity_type_id`, `meta`,
+	 * `source_entity_*`, and `is_wallet_entry` when present.
 	 *
 	 * @remarks
 	 * **Preconditions**
@@ -535,13 +535,18 @@ export class WSAPIUser extends WSAPIBase {
 	 * `from` by 50 between calls. Both `startTimeSeconds` and `endTimeSeconds`
 	 * are epoch seconds bounding the window the server scans.
 	 *
+	 * **Filtering** — optional server-side filters:
+	 * - `types` — {@link ActivityLogActivities} / `type_id` values (e.g. Points=3, Gems=1)
+	 * - `src_types` — {@link PointChangeSourceType} / `source_type_id` values
+	 * Omit both for an unfiltered window.
+	 *
 	 * **Subscription model (`onUpdate`)**
 	 * The callback fires when the user's `ach_points_balance`,
 	 * `ach_gems_balance`, or `ach_diamonds_balance` changes (i.e. whenever a
 	 * wallet event lands). The pushed payload is a FIXED re-fetch of the
 	 * **last 10 minutes / first 50 entries** — it does NOT honor the original
-	 * call's `startTimeSeconds` / `endTimeSeconds` / `from` / `to`. Consumers
-	 * maintaining a long historical view must re-call `getActivityLog` with
+	 * call's `startTimeSeconds` / `endTimeSeconds` / `from` / `to` / filters.
+	 * Consumers maintaining a long historical view must re-call `getActivityLog` with
 	 * their own params after receiving an `onUpdate` notification.
 	 *
 	 * **Refresh**
@@ -565,6 +570,8 @@ export class WSAPIUser extends WSAPIBase {
 	 *     endTimeSeconds:   now,
 	 *     from: 0,
 	 *     to:   50,
+	 *     types: [1], // Gems only (ActivityLogActivities.Gems)
+	 *     src_types: [11], // Tournament wins only (PointChangeSourceType.Tournament)
 	 *     onUpdate: (refreshed) => {
 	 *         console.log('[smartico] wallet changed — refreshed payload is last 10 min / 50 entries:', refreshed.length, 'rows');
 	 *         // If the consumer is showing a full 30-day view, re-call getActivityLog with the original params here.
@@ -582,6 +589,8 @@ export class WSAPIUser extends WSAPIBase {
 		endTimeSeconds,
 		from,
 		to,
+		types,
+		src_types,
 		onUpdate,
 	}: {
 		/** Window start in epoch seconds. */
@@ -592,30 +601,41 @@ export class WSAPIUser extends WSAPIBase {
 		from: number;
 		/** Pagination ceiling (exclusive); server caps `to - from` at 50. */
 		to: number;
+		/** Optional — filter by {@link ActivityLogActivities} / `type_id`. */
+		types?: number[];
+		/** Optional — filter by {@link PointChangeSourceType} / `source_type_id`. */
+		src_types?: number[];
 		/** Optional push callback; payload is a fixed 10-min / 50-entry refresh on every wallet change (see Subscription model). */
 		onUpdate?: (data: TActivityLog[]) => void;
 	}): Promise<TActivityLog[]> {
 
-		const cacheKey = `${onUpdateContextKey.ActivityLog}:${startTimeSeconds}:${endTimeSeconds}:${from}:${to}`;
+		const cacheKey = `${onUpdateContextKey.ActivityLog}:${startTimeSeconds}:${endTimeSeconds}:${from}:${to}:${types?.join(',') ?? ''}:${src_types?.join(',') ?? ''}`;
 
 		if (typeof onUpdate === 'function') {
 			this.onUpdateCallback.set(onUpdateContextKey.ActivityLog, onUpdate);
 			// Remember the requested window so a push refresh re-fetches THIS window
 			// and writes the matching composite cache key (see notifyActivityLogUpdate).
-			this.activityLogOnUpdateParams = { startTimeSeconds, endTimeSeconds, from, to };
+			this.activityLogOnUpdateParams = { startTimeSeconds, endTimeSeconds, from, to, types, src_types };
 		}
 
 		return await OCache.use(
 			cacheKey,
 			ECacheContext.WSAPI,
-			() => this.api.getActivityLogT(this.userExtId, startTimeSeconds, endTimeSeconds, from, to),
+			() => this.api.getActivityLogT(this.userExtId, startTimeSeconds, endTimeSeconds, from, to, types, src_types),
 			CACHE_DATA_SEC,
 		);
 	}
 
 	/** @hidden Last window passed to `getActivityLog` with an `onUpdate`, so a push
 	 * refresh re-fetches the same window and updates its matching composite cache key. */
-	private activityLogOnUpdateParams: { startTimeSeconds: number; endTimeSeconds: number; from: number; to: number } | undefined;
+	private activityLogOnUpdateParams: {
+		startTimeSeconds: number;
+		endTimeSeconds: number;
+		from: number;
+		to: number;
+		types?: number[];
+		src_types?: number[];
+	} | undefined;
 
 	protected async notifyActivityLogUpdate() {
 		const params = this.activityLogOnUpdateParams;
@@ -630,8 +650,10 @@ export class WSAPIUser extends WSAPIBase {
 			params.endTimeSeconds,
 			params.from,
 			params.to,
+			params.types,
+			params.src_types,
 		);
-		const cacheKey = `${onUpdateContextKey.ActivityLog}:${params.startTimeSeconds}:${params.endTimeSeconds}:${params.from}:${params.to}`;
+		const cacheKey = `${onUpdateContextKey.ActivityLog}:${params.startTimeSeconds}:${params.endTimeSeconds}:${params.from}:${params.to}:${params.types?.join(',') ?? ''}:${params.src_types?.join(',') ?? ''}`;
 
 		OCache.set(cacheKey, payload, ECacheContext.WSAPI);
 
@@ -640,43 +662,4 @@ export class WSAPIUser extends WSAPIBase {
 			onUpdate(payload);
 		}
 	}
-
-	/**
-	 * Returns the full activity log (v2) — wallet changes **and** non-wallet
-	 * activities (missions, badges, levels, tournaments, avatars, …).
-	 *
-	 * **Backwards compatibility**: existing integrations should keep using
-	 * {@link getActivityLog}, which returns wallet-only {@link TActivityLog}
-	 * rows with the original field contract unchanged.
-	 *
-	 * **Pagination** — same `from` / `to` offset model as {@link getActivityLog}
-	 * (server caps a single response at 50 entries).
-	 *
-	 * **Filtering** — pass `types` with {@link ActivityLogActivities} values to
-	 * request a server-side subset (e.g. missions only). Omit for all activity types.
-	 *
-	 * @returns Array of {@link TActivityLogEntry} ordered newest-first.
-	 */
-	public async getActivityLogV2({
-		startTimeSeconds,
-		endTimeSeconds,
-		from,
-		to,
-		types,
-	}: {
-		startTimeSeconds: number;
-		endTimeSeconds: number;
-		from: number;
-		to: number;
-		types?: number[];
-	}): Promise<TActivityLogEntry[]> {
-		const cacheKey = `${onUpdateContextKey.ActivityLogV2}:${startTimeSeconds}:${endTimeSeconds}:${from}:${to}:${types?.join(',') ?? ''}`;
-
-		return await OCache.use(
-			cacheKey,
-			ECacheContext.WSAPI,
-			() => this.api.getActivityLogV2T(this.userExtId, startTimeSeconds, endTimeSeconds, from, to, types),
-			CACHE_DATA_SEC,
-		);
-	}
 }

package/docs/api/interfaces/GemsDiamondsLog.md

@@ -1,45 +0,0 @@
-# Interface: GemsDiamondsLog
-
-## Properties
-
-### create\_date
-
-> **create\_date**: `number`
-
-Epoch timestamp in SECONDS (not ms — unlike most SDK timestamps).
-
-***
-
-### user\_ext\_id
-
-> **user\_ext\_id**: `string`
-
-***
-
-### crm\_brand\_id
-
-> **crm\_brand\_id**: `number`
-
-***
-
-### type
-
-> **type**: [`UserBalanceType`](../enumerations/UserBalanceType.md)
-
-***
-
-### amount
-
-> **amount**: `number`
-
-***
-
-### balance
-
-> **balance**: `number`
-
-***
-
-### source\_type\_id
-
-> **source\_type\_id**: [`PointChangeSourceType`](../enumerations/PointChangeSourceType.md)

package/docs/api/interfaces/PointsLog.md

@@ -1,45 +0,0 @@
-# Interface: PointsLog
-
-## Properties
-
-### create\_date
-
-> **create\_date**: `number`
-
-Epoch timestamp in SECONDS (not ms — unlike most SDK timestamps).
-
-***
-
-### user\_ext\_id
-
-> **user\_ext\_id**: `string`
-
-***
-
-### crm\_brand\_id
-
-> **crm\_brand\_id**: `number`
-
-***
-
-### points\_collected
-
-> **points\_collected**: `number`
-
-***
-
-### user\_points\_ever
-
-> **user\_points\_ever**: `number`
-
-***
-
-### user\_points\_balance
-
-> **user\_points\_balance**: `number`
-
-***
-
-### source\_type\_id
-
-> **source\_type\_id**: [`PointChangeSourceType`](../enumerations/PointChangeSourceType.md)

package/docs/api/interfaces/TActivityLogEntry.md

@@ -1,100 +0,0 @@
-# Interface: TActivityLogEntry
-
-Full activity-log row returned by [WSAPIUser.getActivityLogV2](../classes/WSAPIUser.md#getactivitylogv2).
-Includes wallet changes and non-wallet activities (missions, badges, levels, …).
-
-## Properties
-
-### create\_date
-
-> **create\_date**: `number`
-
-***
-
-### user\_ext\_id
-
-> **user\_ext\_id**: `string`
-
-***
-
-### crm\_brand\_id
-
-> **crm\_brand\_id**: `number`
-
-***
-
-### type
-
-> **type**: [`UserBalanceType`](../enumerations/UserBalanceType.md)
-
-***
-
-### amount
-
-> **amount**: `number`
-
-***
-
-### balance
-
-> **balance**: `number`
-
-***
-
-### total\_ever?
-
-> `optional` **total\_ever?**: `number`
-
-***
-
-### source\_type\_id
-
-> **source\_type\_id**: [`PointChangeSourceType`](../enumerations/PointChangeSourceType.md)
-
-***
-
-### activity\_type\_id?
-
-> `optional` **activity\_type\_id?**: [`ActivityLogActivities`](../enumerations/ActivityLogActivities.md)
-
-***
-
-### context\_value\_1?
-
-> `optional` **context\_value\_1?**: `number`
-
-***
-
-### meta?
-
-> `optional` **meta?**: [`ActivityLogMeta`](ActivityLogMeta.md)
-
-***
-
-### source\_entity\_name?
-
-> `optional` **source\_entity\_name?**: `string`
-
-***
-
-### source\_entity\_id?
-
-> `optional` **source\_entity\_id?**: `number`
-
-***
-
-### source\_reference\_id?
-
-> `optional` **source\_reference\_id?**: `number`
-
-***
-
-### source\_root\_id?
-
-> `optional` **source\_root\_id?**: `number`
-
-***
-
-### is\_wallet\_entry
-
-> **is\_wallet\_entry**: `boolean`

package/docs/api/type-aliases/ActivityLogEntry.md

@@ -1,3 +0,0 @@
-# Type Alias: ActivityLogEntry
-
-> **ActivityLogEntry** = [`PointsLog`](../interfaces/PointsLog.md) \| [`GemsDiamondsLog`](../interfaces/GemsDiamondsLog.md)

package/docs/capabilities/getActivityLogV2.md

@@ -1,62 +0,0 @@
-# getActivityLogV2 — API (TActivityLogEntry)
-
-> Returns the full activity log (v2) — wallet changes **and** non-wallet activities (missions, badges, levels, tournaments, avatars, …).
-> Import: `import { TActivityLogEntry } from '@smartico/public-api'`
-> Search terms: getActivityLogV2, user, TActivityLogEntry, UserBalanceType, PointChangeSourceType, ActivityLogActivities, ActivityLogMeta
-
-## Signature
-```ts
-_smartico.api.getActivityLogV2({
-		startTimeSeconds,
-		endTimeSeconds,
-		from,
-		to,
-		types,
-	}: {
-		startTimeSeconds: number;
-		endTimeSeconds: number;
-		from: number;
-		to: number;
-		types?: number[];
-	}): Promise<TActivityLogEntry[]>
-```
-
-## Parameters
-_None._
-
-## Returns — `Promise<TActivityLogEntry[]>`
-Array of `TActivityLogEntry`. Each item:
-- `create_date` (number)
-- `user_ext_id` (string)
-- `crm_brand_id` (number)
-- `type` (UserBalanceType)
-- `amount` (number)
-- `balance` (number)
-- `total_ever` (number)
-- `source_type_id` (PointChangeSourceType)
-- `activity_type_id` (ActivityLogActivities)
-- `context_value_1` (number)
-- `meta` (ActivityLogMeta)
-  - `name` (string)
-  - `image_url` (string)
-  - `position` (number)
-  - `user_points_balance_before` (number)
-  - `points_requested` (number)
-  - `user_points_ever` (number)
-- `source_entity_name` (string)
-- `source_entity_id` (number)
-- `source_reference_id` (number)
-- `source_root_id` (number)
-- `is_wallet_entry` (boolean)
-
-## Behavioral contract
-See the [UI guide](../ui/user/UIGuide_getActivityLogV2.md) if present.
-
-## Errors
-See this method's TSDoc / the mutation pages for `err_code` handling.
-
-## Related
-- `getActivityLog`
-- `TActivityLog`
-- `ActivityLogActivities`
-- `TActivityLogEntry`