@attlaz/client 1.104.0 → 1.106.0

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

@@ -0,0 +1,20 @@
+import { ApiRecord } from '../../Model/ApiRecord.js';
+/**
+ * One page of a crawl — `pulse.crawl_job_page`.
+ *
+ * A worker takes pages by claiming them, which is what `status` and `claimedAt` record: a claimed
+ * page is nobody else's to fetch until its owner finishes or its lease expires.
+ */
+export type CrawlJobPageStatus = 'pending' | 'running' | 'complete' | 'failed';
+export declare class CrawlJobPage {
+    id: string;
+    crawlJobId: string;
+    url: string;
+    status: CrawlJobPageStatus;
+    /** When a worker took this page; its lease runs from here. */
+    claimedAt: Date | null;
+    /** How many times it has been claimed — a page released by an expired lease is retried. */
+    attempts: number;
+    constructor(id: string, crawlJobId: string, url: string);
+    static parse(raw: ApiRecord): CrawlJobPage;
+}

package/dist/MarketPulse/Model/CrawlJobPage.js

@@ -0,0 +1,22 @@
+export class CrawlJobPage {
+    id;
+    crawlJobId;
+    url;
+    status = 'pending';
+    /** When a worker took this page; its lease runs from here. */
+    claimedAt = null;
+    /** How many times it has been claimed — a page released by an expired lease is retried. */
+    attempts = 0;
+    constructor(id, crawlJobId, url) {
+        this.id = id;
+        this.crawlJobId = crawlJobId;
+        this.url = url;
+    }
+    static parse(raw) {
+        const page = new CrawlJobPage(raw.id, raw.crawl_job_id ?? raw.crawl_job ?? '', raw.url ?? '');
+        page.status = (raw.status ?? 'pending');
+        page.claimedAt = raw.claimed_at === undefined || raw.claimed_at === null ? null : new Date(raw.claimed_at);
+        page.attempts = Number(raw.attempts ?? 0);
+        return page;
+    }
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Whether a vendor product is purchasable. Three states rather than a nullable boolean, because
+ * "we don't know" is a different fact from "it is out of stock" — most crawlers never report stock.
+ *
+ * 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 StockStatus = 'in_stock' | 'out_of_stock' | 'unknown';
+/**
+ * Read `stock_status` from an API record. An unrecognised or absent value is `unknown`, never
+ * `out_of_stock` — guessing the latter would make a consumer hide a product that is probably on sale.
+ */
+export declare const parseStockStatus: (status: unknown) => StockStatus;
+/**
+ * Convert a scraper's own boolean reading of stock into a status. Separate from parseStockStatus:
+ * that one reads the wire, this one is for callers holding a `boolean | null` of their own, where
+ * null genuinely means the source did not say.
+ */
+export declare const stockStatusFromBoolean: (inStock: boolean | null) => StockStatus;

package/dist/MarketPulse/Model/StockStatus.js

@@ -0,0 +1,21 @@
+/**
+ * Read `stock_status` from an API record. An unrecognised or absent value is `unknown`, never
+ * `out_of_stock` — guessing the latter would make a consumer hide a product that is probably on sale.
+ */
+export const parseStockStatus = (status) => {
+    if (status === 'in_stock' || status === 'out_of_stock' || status === 'unknown') {
+        return status;
+    }
+    return 'unknown';
+};
+/**
+ * Convert a scraper's own boolean reading of stock into a status. Separate from parseStockStatus:
+ * that one reads the wire, this one is for callers holding a `boolean | null` of their own, where
+ * null genuinely means the source did not say.
+ */
+export const stockStatusFromBoolean = (inStock) => {
+    if (inStock === null) {
+        return 'unknown';
+    }
+    return inStock ? 'in_stock' : 'out_of_stock';
+};

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

@@ -1,3 +1,4 @@
+import { StockStatus } from './StockStatus.js';
 import { ApiRecord } from '../../Model/ApiRecord.js';
 /**
  * A competitor's product as tracked by Market Pulse — the `/pulse/vendors/:vendorId/products`
@@ -17,7 +18,7 @@ export declare class VendorProduct {
     price: number | null;
     originalPrice: number | null;
     shippingCost: number | null;
-    isInStock: boolean | null;
+    stockStatus: StockStatus;
     properties: Record<string, unknown> | null;
     createdAt: Date | null;
     updatedAt: Date | null;

package/dist/MarketPulse/Model/VendorProduct.js

@@ -1,3 +1,4 @@
+import { parseStockStatus } from './StockStatus.js';
 /**
  * A competitor's product as tracked by Market Pulse — the `/pulse/vendors/:vendorId/products`
  * resource. `identifier` is the product's stable id on the competitor's site (the upsert key).
@@ -16,7 +17,7 @@ export class VendorProduct {
     price = null;
     originalPrice = null;
     shippingCost = null;
-    isInStock = null;
+    stockStatus = 'unknown';
     properties = null;
     createdAt = null;
     updatedAt = null;
@@ -46,7 +47,7 @@ export class VendorProduct {
         product.price = toNumber(raw.price);
         product.originalPrice = toNumber(raw.original_price);
         product.shippingCost = toNumber(raw.shipping_cost);
-        product.isInStock = typeof raw.is_in_stock === 'boolean' ? raw.is_in_stock : null;
+        product.stockStatus = parseStockStatus(raw.stock_status);
         product.properties = raw.properties ?? null;
         product.createdAt = raw.created_at ? new Date(raw.created_at) : null;
         product.updatedAt = raw.updated_at ? new Date(raw.updated_at) : null;

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

@@ -1,3 +1,4 @@
+import { StockStatus } from './StockStatus.js';
 import { ApiRecord } from '../../Model/ApiRecord.js';
 /**
  * One recorded price point of a competitor product — the `/pulse/vendor-products/:id/price-history`
@@ -10,7 +11,7 @@ export declare class VendorProductPriceHistoryEntry {
     price: number | null;
     originalPrice: number | null;
     shippingCost: number | null;
-    isInStock: boolean | null;
+    stockStatus: StockStatus;
     isPromotion: boolean | null;
     recordedAt: Date | null;
     constructor(id: string, vendorProductId: string);

package/dist/MarketPulse/Model/VendorProductPriceHistoryEntry.js

@@ -1,3 +1,4 @@
+import { parseStockStatus } from './StockStatus.js';
 /**
  * One recorded price point of a competitor product — the `/pulse/vendor-products/:id/price-history`
  * resource. Written when a crawl finds a price that differs from the last recorded one, so the
@@ -9,7 +10,7 @@ export class VendorProductPriceHistoryEntry {
     price = null;
     originalPrice = null;
     shippingCost = null;
-    isInStock = null;
+    stockStatus = 'unknown';
     isPromotion = null;
     recordedAt = null;
     constructor(id, vendorProductId) {
@@ -21,7 +22,7 @@ export class VendorProductPriceHistoryEntry {
         entry.price = toNumber(raw.price);
         entry.originalPrice = toNumber(raw.original_price);
         entry.shippingCost = toNumber(raw.shipping_cost);
-        entry.isInStock = typeof raw.is_in_stock === 'boolean' ? raw.is_in_stock : null;
+        entry.stockStatus = parseStockStatus(raw.stock_status);
         entry.isPromotion = typeof raw.is_promotion === 'boolean' ? raw.is_promotion : null;
         entry.recordedAt = raw.recorded_at ? new Date(raw.recorded_at) : null;
         return entry;

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

@@ -1,6 +1,7 @@
 import { CatalogId } from '../../Catalog/Model/CatalogId.js';
 import { CursorPagination } from '../../Model/Pagination/CursorPagination.js';
 import { CrawlJob, CrawlJobStatus } from '../Model/CrawlJob.js';
+import { CrawlJobPage } from '../Model/CrawlJobPage.js';
 import { CollectionResult } from '../../Model/Result/CollectionResult.js';
 import { Endpoint } from '../../Service/Endpoint.js';
 /**
@@ -32,6 +33,16 @@ export declare class CrawlJobEndpoint extends Endpoint {
     markPagesParsed(crawlJobId: string, urls: string[]): Promise<void>;
     /** Mark pages as failed (terminal, e.g. blocked/unfetchable). */
     markPagesFailed(crawlJobId: string, urls: string[]): Promise<void>;
+    /**
+     * Atomically take up to `limit` of this crawl's pending pages to work on.
+     *
+     * Concurrent workers get disjoint sets, so a page is never fetched twice. An empty array means
+     * there is nothing left to do — that is how a worker knows to stop, not an error.
+     *
+     * Claiming starts a lease: finish the pages (mark them parsed or failed) or they are handed back
+     * to another worker once the lease expires.
+     */
+    claimPages(crawlJobId: string, limit: number): Promise<CrawlJobPage[]>;
     /** @param suffix a literal trailing segment, e.g. `/pages/crawled` — not caller data. */
     private postUrls;
 }

package/dist/MarketPulse/Service/CrawlJobEndpoint.js

@@ -1,6 +1,7 @@
 import { path } from '../../Http/Data/Path.js';
 import { QueryString } from '../../Http/Data/QueryString.js';
 import { CrawlJob } from '../Model/CrawlJob.js';
+import { CrawlJobPage } from '../Model/CrawlJobPage.js';
 import { Endpoint } from '../../Service/Endpoint.js';
 /**
  * Market Pulse crawl jobs — `/pulse/crawl-jobs`. Mirrors the PHP client's MarketPulse\CrawlJobEndpoint.
@@ -64,6 +65,19 @@ export class CrawlJobEndpoint extends Endpoint {
     async markPagesFailed(crawlJobId, urls) {
         await this.postUrls(crawlJobId, '/pages/failed', urls);
     }
+    /**
+     * Atomically take up to `limit` of this crawl's pending pages to work on.
+     *
+     * Concurrent workers get disjoint sets, so a page is never fetched twice. An empty array means
+     * there is nothing left to do — that is how a worker knows to stop, not an error.
+     *
+     * Claiming starts a lease: finish the pages (mark them parsed or failed) or they are handed back
+     * to another worker once the lease expires.
+     */
+    async claimPages(crawlJobId, limit) {
+        const result = await this.requestCollection(path('/pulse/crawl-jobs/:crawlJobId', { crawlJobId }) + '/pages/claim', CrawlJobPage.parse, { limit }, 'POST');
+        return result.getData();
+    }
     /** @param suffix a literal trailing segment, e.g. `/pages/crawled` — not caller data. */
     async postUrls(crawlJobId, suffix, urls) {
         if (urls.length === 0) {

package/dist/MarketPulse/Service/VendorProductEndpoint.js

@@ -62,7 +62,7 @@ export class VendorProductEndpoint extends Endpoint {
             price: product.price,
             originalPrice: product.originalPrice,
             shippingCost: product.shippingCost,
-            isInStock: product.isInStock,
+            stockStatus: product.stockStatus,
             properties: product.properties,
         };
         const result = await this.requestObject(path('/pulse/vendors/:vendorId/products', { vendorId: product.vendorId }), body, VendorProduct.parse, 'POST');
@@ -76,7 +76,7 @@ export class VendorProductEndpoint extends Endpoint {
             { op: 'add', path: 'original_price', value: product.originalPrice },
             { op: 'add', path: 'brand', value: product.brand },
             { op: 'add', path: 'shipping_cost', value: product.shippingCost },
-            { op: 'add', path: 'is_in_stock', value: product.isInStock },
+            { op: 'add', path: 'stock_status', value: product.stockStatus },
             { op: 'add', path: 'url', value: product.url },
             { op: 'add', path: 'gtin', value: product.gtin },
             { op: 'add', path: 'image', value: product.image },

package/dist/index.d.ts

@@ -82,8 +82,10 @@ export { ResultError } from './Model/Result/ResultError.js';
 export { StorageInformation } from './Model/Storage/StorageInformation.js';
 export { StorageType } from './Model/Storage/StorageType.js';
 export { VendorProduct } from './MarketPulse/Model/VendorProduct.js';
+export { StockStatus, parseStockStatus, stockStatusFromBoolean } from './MarketPulse/Model/StockStatus.js';
 export { VendorProductEndpoint } from './MarketPulse/Service/VendorProductEndpoint.js';
 export { CrawlJob, CrawlJobStatus } from './MarketPulse/Model/CrawlJob.js';
+export { CrawlJobPage, CrawlJobPageStatus } from './MarketPulse/Model/CrawlJobPage.js';
 export { CrawlJobEndpoint } from './MarketPulse/Service/CrawlJobEndpoint.js';
 export { VendorProductPriceHistoryEntry } from './MarketPulse/Model/VendorProductPriceHistoryEntry.js';
 export { Catalog } from './Catalog/Model/Catalog.js';

package/dist/index.js

@@ -68,8 +68,10 @@ export { ResultError } from './Model/Result/ResultError.js';
 export { StorageInformation } from './Model/Storage/StorageInformation.js';
 export { StorageType } from './Model/Storage/StorageType.js';
 export { VendorProduct } from './MarketPulse/Model/VendorProduct.js';
+export { parseStockStatus, stockStatusFromBoolean } from './MarketPulse/Model/StockStatus.js';
 export { VendorProductEndpoint } from './MarketPulse/Service/VendorProductEndpoint.js';
 export { CrawlJob } from './MarketPulse/Model/CrawlJob.js';
+export { CrawlJobPage } from './MarketPulse/Model/CrawlJobPage.js';
 export { CrawlJobEndpoint } from './MarketPulse/Service/CrawlJobEndpoint.js';
 export { VendorProductPriceHistoryEntry } from './MarketPulse/Model/VendorProductPriceHistoryEntry.js';
 export { Catalog } from './Catalog/Model/Catalog.js';

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.103.0";
+export declare const VERSION = "1.105.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "1.103.0";
+export const VERSION = "1.105.0";

package/package.json

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