@attlaz/client 1.107.0 → 1.109.0

package/dist/Client.d.ts

@@ -35,6 +35,7 @@ import { ProductMatchEndpoint } from './MarketPulse/Service/ProductMatchEndpoint
 import { PulseCatalogProductEndpoint } from './MarketPulse/Service/PulseCatalogProductEndpoint.js';
 import { PriceAlertEndpoint } from './MarketPulse/Service/PriceAlertEndpoint.js';
 import { PricingEndpoint } from './MarketPulse/Service/PricingEndpoint.js';
+import { OpportunityEndpoint } from './MarketPulse/Service/OpportunityEndpoint.js';
 import { ProductGroupEndpoint } from './MarketPulse/Service/ProductGroupEndpoint.js';
 import { CatalogProductEndpoint } from './Catalog/Service/CatalogProductEndpoint.js';
 import { GenerateContentEndpoint } from './DataEnrichment/Service/GenerateContentEndpoint.js';
@@ -147,6 +148,7 @@ export declare class Client {
     getCatalogProductEndpoint(): CatalogProductEndpoint;
     getPriceAlertEndpoint(): PriceAlertEndpoint;
     getPricingEndpoint(): PricingEndpoint;
+    getOpportunityEndpoint(): OpportunityEndpoint;
     getProductGroupEndpoint(): ProductGroupEndpoint;
     getGenerateContentEndpoint(): GenerateContentEndpoint;
     getCompetitorEndpoint(): CompetitorEndpoint;

package/dist/Client.js

@@ -35,6 +35,7 @@ import { ProductMatchEndpoint } from './MarketPulse/Service/ProductMatchEndpoint
 import { PulseCatalogProductEndpoint } from './MarketPulse/Service/PulseCatalogProductEndpoint.js';
 import { PriceAlertEndpoint } from './MarketPulse/Service/PriceAlertEndpoint.js';
 import { PricingEndpoint } from './MarketPulse/Service/PricingEndpoint.js';
+import { OpportunityEndpoint } from './MarketPulse/Service/OpportunityEndpoint.js';
 import { ProductGroupEndpoint } from './MarketPulse/Service/ProductGroupEndpoint.js';
 import { CatalogProductEndpoint } from './Catalog/Service/CatalogProductEndpoint.js';
 import { GenerateContentEndpoint } from './DataEnrichment/Service/GenerateContentEndpoint.js';
@@ -105,6 +106,7 @@ export class Client {
         PulseCatalogProductEndpoint,
         PriceAlertEndpoint,
         PricingEndpoint,
+        OpportunityEndpoint,
         ProductGroupEndpoint,
         CatalogProductEndpoint,
         GenerateContentEndpoint,
@@ -339,6 +341,9 @@ export class Client {
     getPricingEndpoint() {
         return this.getEndpoint('pricing', this.Store.PricingEndpoint);
     }
+    getOpportunityEndpoint() {
+        return this.getEndpoint('opportunity', this.Store.OpportunityEndpoint);
+    }
     getProductGroupEndpoint() {
         return this.getEndpoint('product-group', this.Store.ProductGroupEndpoint);
     }

package/dist/MarketPulse/Model/CrawlJob.d.ts

@@ -12,6 +12,11 @@ export declare class CrawlJob {
     requestedAt: Date | null;
     startedAt: Date | null;
     finishedAt: Date | null;
+    /**
+     * This crawl looked at only part of the catalogue, so it is excluded from the delisting window:
+     * it never looked for most products, so its silence about them proves nothing.
+     */
+    isPartial: boolean;
     /** Progress (populated by list endpoints): total pages and how many have been processed. */
     total: number;
     processed: number;

package/dist/MarketPulse/Model/CrawlJob.js

@@ -10,6 +10,11 @@ export class CrawlJob {
     requestedAt;
     startedAt;
     finishedAt;
+    /**
+     * This crawl looked at only part of the catalogue, so it is excluded from the delisting window:
+     * it never looked for most products, so its silence about them proves nothing.
+     */
+    isPartial = false;
     /** Progress (populated by list endpoints): total pages and how many have been processed. */
     total = 0;
     processed = 0;
@@ -27,6 +32,7 @@ export class CrawlJob {
         job.requestedAt = raw.requested_at ? new Date(raw.requested_at) : null;
         job.startedAt = raw.started_at ? new Date(raw.started_at) : null;
         job.finishedAt = raw.finished_at ? new Date(raw.finished_at) : null;
+        job.isPartial = raw.is_partial === true;
         job.total = Number(raw.total ?? 0);
         job.processed = Number(raw.processed ?? 0);
         return job;

package/dist/MarketPulse/Model/ProductOpportunity.d.ts

@@ -0,0 +1,41 @@
+import { ApiRecord } from '../../Model/ApiRecord.js';
+/**
+ * What the detection engine found wrong with a product's price.
+ *
+ * Duplicated from apps-lib rather than imported, per the client's enum-duplication convention: the
+ * client must not depend on a server package.
+ */
+export type OpportunityType = 'OVERPRICED_WITH_ROOM' | 'NEEDLESSLY_CHEAP' | 'UNCOMPETITIVE' | 'JUST_CHANGED';
+/**
+ * One detected pricing opportunity on one catalog product — the `/pulse/…/opportunities` resource.
+ *
+ * A derived cache, not history: every recompute delete-and-replaces the whole catalog, so a product
+ * that stops qualifying simply stops appearing. A product can hold two of these, because
+ * `JUST_CHANGED` co-occurs with one of the price types — which is why `id` is the (product, type)
+ * pair rather than the product id.
+ *
+ * The reference price throughout is the **median** of the product's matched, in-stock competitors,
+ * never the average. `NEEDLESSLY_CHEAP` is the one type judged against the cheapest rival instead.
+ */
+export declare class ProductOpportunity {
+    id: string;
+    catalogProductId: string;
+    type: OpportunityType;
+    /** Money at stake. Ranks the worklist within one type; not comparable across types. */
+    score: number;
+    priceVsMedianPct: number | null;
+    marginPct: number | null;
+    medianCompetitorPrice: number | null;
+    competitorCount: number;
+    computedAt: Date | null;
+    /** Which threshold set produced this row, so rows from an older configuration are identifiable. */
+    configVersion: number;
+    productName: string;
+    productImage: string | null;
+    productBrand: string | null;
+    ownPrice: number;
+    /** The product's own currency. Never assume one — see DECISIONS.md (2026-08-08). */
+    currency: string | null;
+    constructor(id: string, catalogProductId: string, type: OpportunityType);
+    static parse(raw: ApiRecord): ProductOpportunity;
+}

package/dist/MarketPulse/Model/ProductOpportunity.js

@@ -0,0 +1,53 @@
+/**
+ * One detected pricing opportunity on one catalog product — the `/pulse/…/opportunities` resource.
+ *
+ * A derived cache, not history: every recompute delete-and-replaces the whole catalog, so a product
+ * that stops qualifying simply stops appearing. A product can hold two of these, because
+ * `JUST_CHANGED` co-occurs with one of the price types — which is why `id` is the (product, type)
+ * pair rather than the product id.
+ *
+ * The reference price throughout is the **median** of the product's matched, in-stock competitors,
+ * never the average. `NEEDLESSLY_CHEAP` is the one type judged against the cheapest rival instead.
+ */
+export class ProductOpportunity {
+    id;
+    catalogProductId;
+    type;
+    /** Money at stake. Ranks the worklist within one type; not comparable across types. */
+    score = 0;
+    priceVsMedianPct = null;
+    marginPct = null;
+    medianCompetitorPrice = null;
+    competitorCount = 0;
+    computedAt = null;
+    /** Which threshold set produced this row, so rows from an older configuration are identifiable. */
+    configVersion = 0;
+    // The own product, carried on the row so a worklist renders without a call per product.
+    productName = '';
+    productImage = null;
+    productBrand = null;
+    ownPrice = 0;
+    /** The product's own currency. Never assume one — see DECISIONS.md (2026-08-08). */
+    currency = null;
+    constructor(id, catalogProductId, type) {
+        this.id = id;
+        this.catalogProductId = catalogProductId;
+        this.type = type;
+    }
+    static parse(raw) {
+        const opportunity = new ProductOpportunity(raw.id, raw.catalog_product, raw.type);
+        opportunity.score = Number(raw.score ?? 0);
+        opportunity.priceVsMedianPct = raw.price_vs_median_pct === null || raw.price_vs_median_pct === undefined ? null : Number(raw.price_vs_median_pct);
+        opportunity.marginPct = raw.margin_pct === null || raw.margin_pct === undefined ? null : Number(raw.margin_pct);
+        opportunity.medianCompetitorPrice = raw.median_competitor_price === null || raw.median_competitor_price === undefined ? null : Number(raw.median_competitor_price);
+        opportunity.competitorCount = Number(raw.competitor_count ?? 0);
+        opportunity.computedAt = raw.computed_at ? new Date(raw.computed_at) : null;
+        opportunity.configVersion = Number(raw.config_version ?? 0);
+        opportunity.productName = raw.product_name ?? '';
+        opportunity.productImage = raw.product_image ?? null;
+        opportunity.productBrand = raw.product_brand ?? null;
+        opportunity.ownPrice = Number(raw.own_price ?? 0);
+        opportunity.currency = raw.currency ?? null;
+        return opportunity;
+    }
+}

package/dist/MarketPulse/Service/CrawlJobEndpoint.d.ts

@@ -10,8 +10,14 @@ import { Endpoint } from '../../Service/Endpoint.js';
  * post-crawl processing (price history, product matching, price-index snapshots).
  */
 export declare class CrawlJobEndpoint extends Endpoint {
-    /** Create a new (pending) crawl job for a vendor. */
-    create(vendorId: string): Promise<CrawlJob>;
+    /**
+     * Create a new (pending) crawl job for a vendor.
+     *
+     * @param isPartial This crawl will deliberately look at only part of the catalogue. Such a crawl
+     *        is excluded from the delisting window: it never looked for most products, so its
+     *        silence about them is not evidence they are gone.
+     */
+    create(vendorId: string, isPartial?: boolean): Promise<CrawlJob>;
     /** Update a crawl job's status ('started', 'finished', 'cancelled'). */
     updateStatus(crawlJobId: string, status: CrawlJobStatus): Promise<CrawlJob>;
     /** A vendor's crawl jobs (newest first), each with progress (`total` / `processed`). */

package/dist/MarketPulse/Service/CrawlJobEndpoint.js

@@ -9,9 +9,15 @@ import { Endpoint } from '../../Service/Endpoint.js';
  * post-crawl processing (price history, product matching, price-index snapshots).
  */
 export class CrawlJobEndpoint extends Endpoint {
-    /** Create a new (pending) crawl job for a vendor. */
-    async create(vendorId) {
-        const result = await this.requestObject('/pulse/crawl-jobs', { vendor: vendorId }, CrawlJob.parse, 'POST');
+    /**
+     * Create a new (pending) crawl job for a vendor.
+     *
+     * @param isPartial This crawl will deliberately look at only part of the catalogue. Such a crawl
+     *        is excluded from the delisting window: it never looked for most products, so its
+     *        silence about them is not evidence they are gone.
+     */
+    async create(vendorId, isPartial = false) {
+        const result = await this.requestObject('/pulse/crawl-jobs', { vendor: vendorId, isPartial }, CrawlJob.parse, 'POST');
         const job = result.getData();
         if (job === null) {
             throw new Error('Unable to create crawl job: empty response');

package/dist/MarketPulse/Service/OpportunityEndpoint.d.ts

@@ -0,0 +1,17 @@
+import { CatalogId } from '../../Catalog/Model/CatalogId.js';
+import { CursorPagination } from '../../Model/Pagination/CursorPagination.js';
+import { CollectionResult } from '../../Model/Result/CollectionResult.js';
+import { Endpoint } from '../../Service/Endpoint.js';
+import { OpportunityType, ProductOpportunity } from '../Model/ProductOpportunity.js';
+/**
+ * The pricing opportunity worklist — `/pulse/catalogs/:catalogId/opportunities`.
+ */
+export declare class OpportunityEndpoint extends Endpoint {
+    /**
+     * Opportunities in a catalog, ranked by money at stake.
+     *
+     * Pass a `type`: the score means something different per type, so an unfiltered read interleaves
+     * four scales into one order. Unfiltered is an overview of what exists, not a ranked worklist.
+     */
+    getOpportunities(catalogId: CatalogId | string, pagination?: CursorPagination | null, type?: OpportunityType | null): Promise<CollectionResult<ProductOpportunity>>;
+}

package/dist/MarketPulse/Service/OpportunityEndpoint.js

@@ -0,0 +1,23 @@
+import { path } from '../../Http/Data/Path.js';
+import { QueryString } from '../../Http/Data/QueryString.js';
+import { Endpoint } from '../../Service/Endpoint.js';
+import { ProductOpportunity } from '../Model/ProductOpportunity.js';
+/**
+ * The pricing opportunity worklist — `/pulse/catalogs/:catalogId/opportunities`.
+ */
+export class OpportunityEndpoint extends Endpoint {
+    /**
+     * Opportunities in a catalog, ranked by money at stake.
+     *
+     * Pass a `type`: the score means something different per type, so an unfiltered read interleaves
+     * four scales into one order. Unfiltered is an overview of what exists, not a ranked worklist.
+     */
+    async getOpportunities(catalogId, pagination = null, type = null) {
+        const queryString = new QueryString(path('/pulse/catalogs/:catalogId/opportunities', { catalogId: catalogId.toString() }));
+        if (type !== null) {
+            queryString.set('type', type);
+        }
+        queryString.addPagination(pagination);
+        return await this.requestCollection(queryString, ProductOpportunity.parse);
+    }
+}

package/dist/Service/AdapterConnectionEndpoint.d.ts

@@ -16,8 +16,8 @@ export declare class AdapterConnectionEndpoint extends Endpoint {
      * it is a partial update. A configuration the API does not let a client set (a provider token)
      * is untouched rather than cleared.
      *
-     * Needs an API that serves the PATCH route; it is also still registered as POST for clients
-     * released before the verb changed.
+     * Needs an API that serves the PATCH route. The POST alias this once relied on has since been
+     * removed from Core-Api, so a client older than 1.104.0 can no longer write this at all.
      */
     saveConnectionConfiguration(connectionId: string, configuration: AdapterConnectionConfigurationValue[]): Promise<boolean>;
     getConnectionEvents(connectionId: string, pagination: CursorPagination): Promise<CollectionResult<AdapterConnectionEvent>>;

package/dist/Service/AdapterConnectionEndpoint.js

@@ -84,8 +84,8 @@ export class AdapterConnectionEndpoint extends Endpoint {
      * it is a partial update. A configuration the API does not let a client set (a provider token)
      * is untouched rather than cleared.
      *
-     * Needs an API that serves the PATCH route; it is also still registered as POST for clients
-     * released before the verb changed.
+     * Needs an API that serves the PATCH route. The POST alias this once relied on has since been
+     * removed from Core-Api, so a client older than 1.104.0 can no longer write this at all.
      */
     async saveConnectionConfiguration(connectionId, configuration) {
         try {

package/dist/index.d.ts

@@ -122,6 +122,8 @@ export { PricingRule } from './MarketPulse/Model/PricingRule.js';
 export { PriceSuggestion, PriceSuggestionStatus } from './MarketPulse/Model/PriceSuggestion.js';
 export { PricingRuleData } from './MarketPulse/Model/PricingRuleData.js';
 export { PricingEndpoint } from './MarketPulse/Service/PricingEndpoint.js';
+export { ProductOpportunity, OpportunityType } from './MarketPulse/Model/ProductOpportunity.js';
+export { OpportunityEndpoint } from './MarketPulse/Service/OpportunityEndpoint.js';
 export { ProductGroup, ProductGroupType } from './MarketPulse/Model/ProductGroup.js';
 export { ProductGroupData } from './MarketPulse/Model/ProductGroupData.js';
 export { ProductGroupEndpoint } from './MarketPulse/Service/ProductGroupEndpoint.js';

package/dist/index.js

@@ -99,6 +99,8 @@ export { PriceAlertEndpoint } from './MarketPulse/Service/PriceAlertEndpoint.js'
 export { PricingRule } from './MarketPulse/Model/PricingRule.js';
 export { PriceSuggestion } from './MarketPulse/Model/PriceSuggestion.js';
 export { PricingEndpoint } from './MarketPulse/Service/PricingEndpoint.js';
+export { ProductOpportunity } from './MarketPulse/Model/ProductOpportunity.js';
+export { OpportunityEndpoint } from './MarketPulse/Service/OpportunityEndpoint.js';
 export { ProductGroup } from './MarketPulse/Model/ProductGroup.js';
 export { ProductGroupEndpoint } from './MarketPulse/Service/ProductGroupEndpoint.js';
 export { CatalogProduct } from './Catalog/Model/CatalogProduct.js';

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.107.0";
+export declare const VERSION = "1.108.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "1.107.0";
+export const VERSION = "1.108.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attlaz/client",
-  "version": "1.107.0",
+  "version": "1.109.0",
   "description": "Javascript Client to access Attlaz API",
   "types": "./dist/index.d.ts",
   "main": "./dist/index.js",