@huloglobal/vendure-plugin-visitor-analytics 0.6.0 → 0.8.0

package/dist/recommendations.controller.d.ts

@@ -0,0 +1,72 @@
+import { RequestContext } from '@vendure/core';
+import { RecommendationsService } from './recommendations.service';
+/**
+ * Public + admin API for the co-view recommendations feature.
+ *
+ * The `also-viewed`, `personal` and `trending` endpoints are safe to
+ * hit from the storefront directly — they return only product ids +
+ * scores, no PII. Restricting them to Vendure admin would break the
+ * primary use case (rendering a recs rail on the product page).
+ */
+export declare class RecommendationsController {
+    private readonly service;
+    constructor(service: RecommendationsService);
+    /**
+     * "Customers who viewed X also viewed…"
+     *   /ees/recommendations/also-viewed?productId=42&channelId=1&limit=10
+     */
+    alsoViewed(pRaw?: string, chRaw?: string, lRaw?: string): Promise<{
+        error: string;
+        productId?: undefined;
+        items?: undefined;
+    } | {
+        productId: number;
+        items: {
+            productId: number;
+            score: number;
+        }[];
+        error?: undefined;
+    }>;
+    /**
+     * Personalised recs for a returning visitor:
+     *   /ees/recommendations/personal?visitorId=abc&channelId=1&limit=10
+     *
+     * Storefronts should send the current `ees_vid` cookie value —
+     * the same one the ingest endpoint issues.
+     */
+    personal(vRaw?: string, chRaw?: string, lRaw?: string): Promise<{
+        error: string;
+        visitorId?: undefined;
+        items?: undefined;
+    } | {
+        visitorId: string;
+        items: {
+            productId: number;
+            score: number;
+        }[];
+        error?: undefined;
+    }>;
+    /**
+     * Most-viewed products in the window:
+     *   /ees/recommendations/trending?channelId=1&hours=24&limit=10
+     */
+    trending(chRaw?: string, hRaw?: string, lRaw?: string): Promise<{
+        channelId: number;
+        hours: number;
+        items: {
+            productId: number;
+            views: number;
+        }[];
+    }>;
+    /**
+     * Admin-only: manually kick the aggregation cron. Normally runs
+     * nightly, but this is useful for smoke-testing after a data
+     * backfill, or for pushing a big spike through immediately.
+     */
+    aggregateNow(ctx: RequestContext, hRaw?: string): Promise<{
+        pairs: number;
+        ok: boolean;
+        hours: number;
+    }>;
+}
+//# sourceMappingURL=recommendations.controller.d.ts.map

package/dist/recommendations.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendations.controller.d.ts","sourceRoot":"","sources":["../src/recommendations.controller.ts"],"names":[],"mappings":"AACA,OAAO,EAAO,cAAc,EAAqB,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAEnE;;;;;;;GAOG;AACH,qBACa,yBAAyB;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,sBAAsB;IAE5D;;;OAGG;IAEG,UAAU,CACQ,IAAI,CAAC,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM;;;;;;;;;;;;IAUrC;;;;;;OAMG;IAEG,QAAQ,CACU,IAAI,CAAC,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM;;;;;;;;;;;;IAUrC;;;OAGG;IAEG,QAAQ,CACU,KAAK,CAAC,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,MAAM;;;;;;;;IASrC;;;;OAIG;IAGG,YAAY,CAAQ,GAAG,EAAE,cAAc,EAAkB,IAAI,CAAC,EAAE,MAAM;;;;;CAK/E"}

package/dist/recommendations.controller.js

@@ -0,0 +1,123 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecommendationsController = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@vendure/core");
+const recommendations_service_1 = require("./recommendations.service");
+/**
+ * Public + admin API for the co-view recommendations feature.
+ *
+ * The `also-viewed`, `personal` and `trending` endpoints are safe to
+ * hit from the storefront directly — they return only product ids +
+ * scores, no PII. Restricting them to Vendure admin would break the
+ * primary use case (rendering a recs rail on the product page).
+ */
+let RecommendationsController = class RecommendationsController {
+    constructor(service) {
+        this.service = service;
+    }
+    /**
+     * "Customers who viewed X also viewed…"
+     *   /ees/recommendations/also-viewed?productId=42&channelId=1&limit=10
+     */
+    async alsoViewed(pRaw, chRaw, lRaw) {
+        const productId = parseInt(pRaw || '0', 10);
+        if (!productId)
+            return { error: 'productId-required' };
+        const channelId = parseInt(chRaw || '1', 10) || 1;
+        const limit = parseInt(lRaw || '10', 10) || 10;
+        const items = await this.service.alsoViewed(productId, channelId, limit);
+        return { productId, items };
+    }
+    /**
+     * Personalised recs for a returning visitor:
+     *   /ees/recommendations/personal?visitorId=abc&channelId=1&limit=10
+     *
+     * Storefronts should send the current `ees_vid` cookie value —
+     * the same one the ingest endpoint issues.
+     */
+    async personal(vRaw, chRaw, lRaw) {
+        const visitorId = String(vRaw || '').trim();
+        if (!visitorId)
+            return { error: 'visitorId-required' };
+        const channelId = parseInt(chRaw || '1', 10) || 1;
+        const limit = parseInt(lRaw || '10', 10) || 10;
+        const items = await this.service.personalRecommendations(visitorId, channelId, limit);
+        return { visitorId, items };
+    }
+    /**
+     * Most-viewed products in the window:
+     *   /ees/recommendations/trending?channelId=1&hours=24&limit=10
+     */
+    async trending(chRaw, hRaw, lRaw) {
+        const channelId = parseInt(chRaw || '1', 10) || 1;
+        const hours = Math.min(Math.max(1, parseInt(hRaw || '24', 10) || 24), 24 * 30);
+        const limit = parseInt(lRaw || '10', 10) || 10;
+        const items = await this.service.trending(channelId, hours, limit);
+        return { channelId, hours, items };
+    }
+    /**
+     * Admin-only: manually kick the aggregation cron. Normally runs
+     * nightly, but this is useful for smoke-testing after a data
+     * backfill, or for pushing a big spike through immediately.
+     */
+    async aggregateNow(ctx, hRaw) {
+        const hours = Math.min(Math.max(1, parseInt(hRaw || '24', 10) || 24), 24 * 30);
+        const result = await this.service.aggregateCoViews(hours);
+        return { ok: true, hours, ...result };
+    }
+};
+exports.RecommendationsController = RecommendationsController;
+__decorate([
+    (0, common_1.Get)('recommendations/also-viewed'),
+    __param(0, (0, common_1.Query)('productId')),
+    __param(1, (0, common_1.Query)('channelId')),
+    __param(2, (0, common_1.Query)('limit')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, String]),
+    __metadata("design:returntype", Promise)
+], RecommendationsController.prototype, "alsoViewed", null);
+__decorate([
+    (0, common_1.Get)('recommendations/personal'),
+    __param(0, (0, common_1.Query)('visitorId')),
+    __param(1, (0, common_1.Query)('channelId')),
+    __param(2, (0, common_1.Query)('limit')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, String]),
+    __metadata("design:returntype", Promise)
+], RecommendationsController.prototype, "personal", null);
+__decorate([
+    (0, common_1.Get)('recommendations/trending'),
+    __param(0, (0, common_1.Query)('channelId')),
+    __param(1, (0, common_1.Query)('hours')),
+    __param(2, (0, common_1.Query)('limit')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, String]),
+    __metadata("design:returntype", Promise)
+], RecommendationsController.prototype, "trending", null);
+__decorate([
+    (0, common_1.Get)('recommendations/aggregate-now'),
+    (0, core_1.Allow)(core_1.Permission.SuperAdmin),
+    __param(0, (0, core_1.Ctx)()),
+    __param(1, (0, common_1.Query)('hours')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [core_1.RequestContext, String]),
+    __metadata("design:returntype", Promise)
+], RecommendationsController.prototype, "aggregateNow", null);
+exports.RecommendationsController = RecommendationsController = __decorate([
+    (0, common_1.Controller)('ees'),
+    __metadata("design:paramtypes", [recommendations_service_1.RecommendationsService])
+], RecommendationsController);
+//# sourceMappingURL=recommendations.controller.js.map

package/dist/recommendations.controller.js.map

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

package/dist/recommendations.service.d.ts

@@ -0,0 +1,62 @@
+import { TransactionalConnection } from '@vendure/core';
+/**
+ * Product recommendations driven by observed co-viewing behaviour.
+ *
+ * The scanner walks recent `product_view` custom events grouped by
+ * session, extracts every ordered pair, and increments a counter per
+ * `(productIdA, productIdB, channelId)` triple. We denormalise both
+ * directions (`A → B` AND `B → A`) so read-side lookups are one
+ * indexed scan.
+ *
+ * "Also viewed" is far simpler than "also bought" — you need orders
+ * data for the latter, and small stores don't have enough of it for
+ * useful signals. Co-views come from every browsing session, so a
+ * store with 1k daily visitors gets useful recs from day one.
+ */
+export declare class RecommendationsService {
+    private connection;
+    constructor(connection: TransactionalConnection);
+    /**
+     * Rebuild the co-view aggregate from `visitor_event`. Idempotent
+     * per (A, B, channelId) — repeated calls over the same window
+     * accumulate, so schedule this as a nightly cron with a rolling
+     * lookback (e.g. last 24h) rather than a full-history rescan.
+     *
+     * Returns the number of pair-triples updated. Uses a bounded
+     * ordered-pair extractor (max 20 events per session) so a single
+     * bot session can't skew the table.
+     */
+    aggregateCoViews(sinceHours?: number): Promise<{
+        pairs: number;
+    }>;
+    /**
+     * Read side: "customers who viewed X also viewed Y" for one
+     * product, ordered by co-view score, capped at `limit`. Returns
+     * bare product ids so the storefront can hydrate names / images
+     * from its usual product-fetch path.
+     */
+    alsoViewed(productId: number, channelId?: number, limit?: number): Promise<Array<{
+        productId: number;
+        score: number;
+    }>>;
+    /**
+     * Personalised recommendations for a returning visitor: look at
+     * the last N products they viewed, and rank co-viewed products by
+     * combined score across those seed products (excluding the seeds
+     * themselves).
+     */
+    personalRecommendations(visitorId: string, channelId?: number, limit?: number): Promise<Array<{
+        productId: number;
+        score: number;
+    }>>;
+    /**
+     * "Trending now" — most-viewed products in the last N hours.
+     * Useful for a homepage rail; uses `product_view` events, so it
+     * reflects real interest, not just search-console clicks.
+     */
+    trending(channelId?: number, sinceHours?: number, limit?: number): Promise<Array<{
+        productId: number;
+        views: number;
+    }>>;
+}
+//# sourceMappingURL=recommendations.service.d.ts.map

package/dist/recommendations.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendations.service.d.ts","sourceRoot":"","sources":["../src/recommendations.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAIxD;;;;;;;;;;;;;GAaG;AACH,qBACa,sBAAsB;IACnB,OAAO,CAAC,UAAU;gBAAV,UAAU,EAAE,uBAAuB;IAEvD;;;;;;;;;OASG;IACG,gBAAgB,CAAC,UAAU,SAAK,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAyDnE;;;;;OAKG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,SAAI,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC1E,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IAYH;;;;;OAKG;IACG,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,SAAI,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QACvF,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IA+BH;;;;OAIG;IACG,QAAQ,CAAC,SAAS,SAAI,EAAE,UAAU,SAAK,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QACtE,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CAmBN"}

package/dist/recommendations.service.js

@@ -0,0 +1,167 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecommendationsService = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@vendure/core");
+const loggerCtx = 'HuloRecommendationsService';
+/**
+ * Product recommendations driven by observed co-viewing behaviour.
+ *
+ * The scanner walks recent `product_view` custom events grouped by
+ * session, extracts every ordered pair, and increments a counter per
+ * `(productIdA, productIdB, channelId)` triple. We denormalise both
+ * directions (`A → B` AND `B → A`) so read-side lookups are one
+ * indexed scan.
+ *
+ * "Also viewed" is far simpler than "also bought" — you need orders
+ * data for the latter, and small stores don't have enough of it for
+ * useful signals. Co-views come from every browsing session, so a
+ * store with 1k daily visitors gets useful recs from day one.
+ */
+let RecommendationsService = class RecommendationsService {
+    constructor(connection) {
+        this.connection = connection;
+    }
+    /**
+     * Rebuild the co-view aggregate from `visitor_event`. Idempotent
+     * per (A, B, channelId) — repeated calls over the same window
+     * accumulate, so schedule this as a nightly cron with a rolling
+     * lookback (e.g. last 24h) rather than a full-history rescan.
+     *
+     * Returns the number of pair-triples updated. Uses a bounded
+     * ordered-pair extractor (max 20 events per session) so a single
+     * bot session can't skew the table.
+     */
+    async aggregateCoViews(sinceHours = 24) {
+        const conn = this.connection.rawConnection;
+        const since = new Date(Date.now() - sinceHours * 3600000);
+        // Extract every session's product-view sequence within the
+        // window. Bounded to 20 events per session to keep pathological
+        // sessions from blowing up the table.
+        const sessions = await conn.query(`SELECT
+                sessionId,
+                channelId,
+                GROUP_CONCAT(
+                    SUBSTRING_INDEX(SUBSTRING_INDEX(meta, '"productId":', -1), ',', 1)
+                    ORDER BY createdAt
+                    SEPARATOR ','
+                ) AS ids
+             FROM visitor_event
+             WHERE type = 'event'
+               AND meta LIKE '%"eventType":"product_view"%'
+               AND createdAt >= ?
+             GROUP BY sessionId, channelId
+             HAVING COUNT(*) BETWEEN 2 AND 20`, [since]);
+        let pairs = 0;
+        for (const s of sessions) {
+            const rawIds = String(s.ids || '')
+                .split(',')
+                .map((x) => parseInt(x.replace(/[^0-9]/g, ''), 10))
+                .filter((n) => Number.isFinite(n) && n > 0);
+            if (rawIds.length < 2)
+                continue;
+            const uniq = Array.from(new Set(rawIds));
+            if (uniq.length < 2)
+                continue;
+            for (let i = 0; i < uniq.length; i++) {
+                for (let j = 0; j < uniq.length; j++) {
+                    if (i === j)
+                        continue;
+                    const a = uniq[i];
+                    const b = uniq[j];
+                    // Upsert-with-increment via ON DUPLICATE KEY UPDATE.
+                    await conn.query(`INSERT INTO product_co_view
+                           (productIdA, productIdB, channelId, viewsTogether, lastUpdated)
+                         VALUES (?, ?, ?, 1, NOW(3))
+                         ON DUPLICATE KEY UPDATE
+                           viewsTogether = viewsTogether + 1,
+                           lastUpdated = NOW(3)`, [a, b, s.channelId || 1]);
+                    pairs += 1;
+                }
+            }
+        }
+        common_1.Logger.log(`Co-view aggregation: ${sessions.length} sessions, ${pairs} pair updates`, loggerCtx);
+        return { pairs };
+    }
+    /**
+     * Read side: "customers who viewed X also viewed Y" for one
+     * product, ordered by co-view score, capped at `limit`. Returns
+     * bare product ids so the storefront can hydrate names / images
+     * from its usual product-fetch path.
+     */
+    async alsoViewed(productId, channelId = 1, limit = 10) {
+        const rows = await this.connection.rawConnection.query(`SELECT productIdB AS productId, viewsTogether AS score
+             FROM product_co_view
+             WHERE productIdA = ? AND channelId = ?
+             ORDER BY viewsTogether DESC, lastUpdated DESC
+             LIMIT ?`, [productId, channelId, Math.min(Math.max(1, limit), 50)]);
+        return rows.map(r => ({ productId: Number(r.productId), score: Number(r.score) }));
+    }
+    /**
+     * Personalised recommendations for a returning visitor: look at
+     * the last N products they viewed, and rank co-viewed products by
+     * combined score across those seed products (excluding the seeds
+     * themselves).
+     */
+    async personalRecommendations(visitorId, channelId = 1, limit = 10) {
+        const conn = this.connection.rawConnection;
+        const seeds = await conn.query(`SELECT DISTINCT
+                CAST(SUBSTRING_INDEX(SUBSTRING_INDEX(meta, '"productId":', -1), ',', 1) AS UNSIGNED) AS productId
+             FROM visitor_event
+             WHERE visitorId = ?
+               AND type = 'event'
+               AND meta LIKE '%"eventType":"product_view"%'
+               AND createdAt >= (NOW() - INTERVAL 30 DAY)
+             ORDER BY createdAt DESC
+             LIMIT 10`, [visitorId]);
+        const seedIds = seeds.map(s => Number(s.productId)).filter(n => n > 0);
+        if (!seedIds.length)
+            return [];
+        const placeholders = seedIds.map(() => '?').join(',');
+        const rows = await conn.query(`SELECT productIdB AS productId, SUM(viewsTogether) AS score
+             FROM product_co_view
+             WHERE productIdA IN (${placeholders})
+               AND channelId = ?
+               AND productIdB NOT IN (${placeholders})
+             GROUP BY productIdB
+             ORDER BY score DESC
+             LIMIT ?`, [...seedIds, channelId, ...seedIds, Math.min(Math.max(1, limit), 50)]);
+        return rows.map(r => ({ productId: Number(r.productId), score: Number(r.score) }));
+    }
+    /**
+     * "Trending now" — most-viewed products in the last N hours.
+     * Useful for a homepage rail; uses `product_view` events, so it
+     * reflects real interest, not just search-console clicks.
+     */
+    async trending(channelId = 1, sinceHours = 24, limit = 10) {
+        const since = new Date(Date.now() - sinceHours * 3600000);
+        const rows = await this.connection.rawConnection.query(`SELECT
+                CAST(SUBSTRING_INDEX(SUBSTRING_INDEX(meta, '"productId":', -1), ',', 1) AS UNSIGNED) AS productId,
+                COUNT(*) AS views
+             FROM visitor_event
+             WHERE type = 'event'
+               AND meta LIKE '%"eventType":"product_view"%'
+               AND channelId = ?
+               AND createdAt >= ?
+             GROUP BY productId
+             HAVING productId > 0
+             ORDER BY views DESC
+             LIMIT ?`, [channelId, since, Math.min(Math.max(1, limit), 50)]);
+        return rows.map(r => ({ productId: Number(r.productId), views: Number(r.views) }));
+    }
+};
+exports.RecommendationsService = RecommendationsService;
+exports.RecommendationsService = RecommendationsService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [core_1.TransactionalConnection])
+], RecommendationsService);
+//# sourceMappingURL=recommendations.service.js.map

package/dist/recommendations.service.js.map

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

package/dist/search-analytics.controller.d.ts

@@ -0,0 +1,36 @@
+import { RequestContext } from '@vendure/core';
+import { SearchAnalyticsService } from './search-analytics.service';
+/**
+ * Admin API for search analytics. The storefront just needs to fire
+ * `hulo.search(query, resultsCount)` for every executed search;
+ * everything else is aggregation over the resulting custom events.
+ */
+export declare class SearchAnalyticsController {
+    private readonly service;
+    constructor(service: SearchAnalyticsService);
+    top(ctx: RequestContext, dRaw?: string, chRaw?: string, lRaw?: string): Promise<{
+        days: number;
+        channelId: number;
+        items: {
+            query: string;
+            searches: number;
+            avgResults: number;
+        }[];
+    }>;
+    noResults(ctx: RequestContext, dRaw?: string, chRaw?: string, lRaw?: string): Promise<{
+        days: number;
+        channelId: number;
+        items: {
+            query: string;
+            searches: number;
+        }[];
+    }>;
+    conversion(ctx: RequestContext, dRaw?: string, chRaw?: string): Promise<{
+        sessionsSearched: number;
+        sessionsAdded: number;
+        conversion: number;
+        days: number;
+        channelId: number;
+    }>;
+}
+//# sourceMappingURL=search-analytics.controller.d.ts.map

package/dist/search-analytics.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-analytics.controller.d.ts","sourceRoot":"","sources":["../src/search-analytics.controller.ts"],"names":[],"mappings":"AACA,OAAO,EAAO,cAAc,EAAqB,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAEpE;;;;GAIG;AACH,qBACa,yBAAyB;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,sBAAsB;IAItD,GAAG,CACE,GAAG,EAAE,cAAc,EACX,IAAI,CAAC,EAAE,MAAM,EACR,KAAK,CAAC,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,MAAM;;;;;;;;;IAW3B,SAAS,CACJ,GAAG,EAAE,cAAc,EACX,IAAI,CAAC,EAAE,MAAM,EACR,KAAK,CAAC,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,MAAM;;;;;;;;IAW3B,UAAU,CACL,GAAG,EAAE,cAAc,EACX,IAAI,CAAC,EAAE,MAAM,EACR,KAAK,CAAC,EAAE,MAAM;;;;;;;CAOzC"}

package/dist/search-analytics.controller.js

@@ -0,0 +1,86 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchAnalyticsController = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@vendure/core");
+const search_analytics_service_1 = require("./search-analytics.service");
+/**
+ * Admin API for search analytics. The storefront just needs to fire
+ * `hulo.search(query, resultsCount)` for every executed search;
+ * everything else is aggregation over the resulting custom events.
+ */
+let SearchAnalyticsController = class SearchAnalyticsController {
+    constructor(service) {
+        this.service = service;
+    }
+    async top(ctx, dRaw, chRaw, lRaw) {
+        const days = Math.min(Math.max(1, parseInt(dRaw || '7', 10) || 7), 365);
+        const channelId = parseInt(chRaw || '1', 10) || 1;
+        const limit = parseInt(lRaw || '50', 10) || 50;
+        const rows = await this.service.topQueries(days, channelId, limit);
+        return { days, channelId, items: rows };
+    }
+    async noResults(ctx, dRaw, chRaw, lRaw) {
+        const days = Math.min(Math.max(1, parseInt(dRaw || '7', 10) || 7), 365);
+        const channelId = parseInt(chRaw || '1', 10) || 1;
+        const limit = parseInt(lRaw || '50', 10) || 50;
+        const rows = await this.service.zeroResultQueries(days, channelId, limit);
+        return { days, channelId, items: rows };
+    }
+    async conversion(ctx, dRaw, chRaw) {
+        const days = Math.min(Math.max(1, parseInt(dRaw || '7', 10) || 7), 365);
+        const channelId = parseInt(chRaw || '1', 10) || 1;
+        const summary = await this.service.searchToAddRate(days, channelId);
+        return { days, channelId, ...summary };
+    }
+};
+exports.SearchAnalyticsController = SearchAnalyticsController;
+__decorate([
+    (0, common_1.Get)('search-analytics/top'),
+    (0, core_1.Allow)(core_1.Permission.ReadCustomer),
+    __param(0, (0, core_1.Ctx)()),
+    __param(1, (0, common_1.Query)('days')),
+    __param(2, (0, common_1.Query)('channelId')),
+    __param(3, (0, common_1.Query)('limit')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [core_1.RequestContext, String, String, String]),
+    __metadata("design:returntype", Promise)
+], SearchAnalyticsController.prototype, "top", null);
+__decorate([
+    (0, common_1.Get)('search-analytics/no-results'),
+    (0, core_1.Allow)(core_1.Permission.ReadCustomer),
+    __param(0, (0, core_1.Ctx)()),
+    __param(1, (0, common_1.Query)('days')),
+    __param(2, (0, common_1.Query)('channelId')),
+    __param(3, (0, common_1.Query)('limit')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [core_1.RequestContext, String, String, String]),
+    __metadata("design:returntype", Promise)
+], SearchAnalyticsController.prototype, "noResults", null);
+__decorate([
+    (0, common_1.Get)('search-analytics/conversion'),
+    (0, core_1.Allow)(core_1.Permission.ReadCustomer),
+    __param(0, (0, core_1.Ctx)()),
+    __param(1, (0, common_1.Query)('days')),
+    __param(2, (0, common_1.Query)('channelId')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [core_1.RequestContext, String, String]),
+    __metadata("design:returntype", Promise)
+], SearchAnalyticsController.prototype, "conversion", null);
+exports.SearchAnalyticsController = SearchAnalyticsController = __decorate([
+    (0, common_1.Controller)('ees'),
+    __metadata("design:paramtypes", [search_analytics_service_1.SearchAnalyticsService])
+], SearchAnalyticsController);
+//# sourceMappingURL=search-analytics.controller.js.map

package/dist/search-analytics.controller.js.map

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

package/dist/search-analytics.service.d.ts

@@ -0,0 +1,36 @@
+import { TransactionalConnection } from '@vendure/core';
+/**
+ * Zero-schema-cost search analytics: reads back over the existing
+ * `visitor_event` table where the storefront has posted `type='event'`,
+ * `eventType='search'` custom events, and aggregates them per query
+ * string.
+ *
+ * The storefront just needs to fire:
+ *   hulo.search('rgb keyboard', 42)   // (query, resultsCount)
+ *
+ * Everything else lives in the read side.
+ */
+export declare class SearchAnalyticsService {
+    private connection;
+    constructor(connection: TransactionalConnection);
+    /** Top search queries in the window, by volume. */
+    topQueries(sinceDays?: number, channelId?: number, limit?: number): Promise<Array<{
+        query: string;
+        searches: number;
+        avgResults: number;
+    }>>;
+    /** Zero-result queries — catalogue-gap intel. */
+    zeroResultQueries(sinceDays?: number, channelId?: number, limit?: number): Promise<Array<{
+        query: string;
+        searches: number;
+    }>>;
+    /** Search-to-cart-add conversion — of sessions that searched, what
+     *  fraction went on to fire an add_to_cart. Coarse, but the direction
+     *  of movement is what matters for catalogue tuning. */
+    searchToAddRate(sinceDays?: number, channelId?: number): Promise<{
+        sessionsSearched: number;
+        sessionsAdded: number;
+        conversion: number;
+    }>;
+}
+//# sourceMappingURL=search-analytics.service.d.ts.map

package/dist/search-analytics.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-analytics.service.d.ts","sourceRoot":"","sources":["../src/search-analytics.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAExD;;;;;;;;;;GAUG;AACH,qBACa,sBAAsB;IACnB,OAAO,CAAC,UAAU;gBAAV,UAAU,EAAE,uBAAuB;IAEvD,mDAAmD;IAC7C,UAAU,CAAC,SAAS,SAAI,EAAE,SAAS,SAAI,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QACtE,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;IAyBH,iDAAiD;IAC3C,iBAAiB,CAAC,SAAS,SAAI,EAAE,SAAS,SAAI,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC7E,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IAqBH;;4DAEwD;IAClD,eAAe,CAAC,SAAS,SAAI,EAAE,SAAS,SAAI,GAAG,OAAO,CAAC;QACzD,gBAAgB,EAAE,MAAM,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;KACtB,CAAC;CA6BL"}