@usagekit/providers 0.9.0 → 0.9.1

package/dist/dataforseo/descriptor.js

@@ -113,8 +113,15 @@ export const descriptor = {
         },
         free("serp.google.organic.tasks_ready", "Google organic SERP, tasks ready", "GET", "/v3/serp/google/organic/tasks_ready"),
         free("serp.google.organic.task_get.advanced", "Google organic SERP, task get advanced", "GET", "/v3/serp/google/organic/task_get/advanced/:id"),
-        ...labs.map(([name, label]) => live(`dataforseo_labs.google.${name}.live`, label, `/v3/dataforseo_labs/google/${name}/live`, ["itemCount", "clickstream"])),
-        ...backlinks.map(([name, label]) => live(`backlinks.${name}.live`, label, `/v3/backlinks/${name}/live`, ["itemCount"])),
+        ...labs.map(([name, label]) => live(`dataforseo_labs.google.${name}.live`, label, `/v3/dataforseo_labs/google/${name}/live`, [
+            "itemCount",
+            "clickstream",
+            ...(name === "historical_rank_overview" ? ["dateFrom", "dateTo"] : []),
+        ])),
+        ...backlinks.map(([name, label]) => live(`backlinks.${name}.live`, label, `/v3/backlinks/${name}/live`, [
+            "itemCount",
+            ...(name === "history" ? ["dateFrom", "dateTo"] : []),
+        ])),
         free("appendix.user_data", "User data (balance, limits, prices)", "GET", "/v3/appendix/user_data"),
         free("dataforseo_labs.status", "Labs status", "GET", "/v3/dataforseo_labs/status"),
     ],

package/dist/dataforseo/extractors.js

@@ -1,5 +1,6 @@
 import { addQuantity, formatQuantity } from "@usagekit/core";
 import { descriptor } from "./descriptor.js";
+import { historyWindowOptions } from "./history-window.js";
 import { listEstimate } from "../prices.js";
 import { pointer } from "../pointer.js";
 import { decimalQuantity, moneyFromDollars, requestsMeasured } from "../receipts.js";
@@ -253,6 +254,7 @@ export const extractors = {
             return {};
         const task = first, options = {};
         const keys = operation.optionKeys ?? [];
+        Object.assign(options, historyWindowOptions(operation.id, task));
         if (operation.billable) {
             const fields = operation.requestPricing;
             const unlisted = !fields ||
@@ -304,9 +306,8 @@ export const extractors = {
                         task.limit === undefined
                             ? operation.requestPricing?.priceFields.limit?.defaultCount
                             : task.limit
-                    : // Summary returns one row. History has no documented request count.
+                    : // Summary returns one row; explicit history dates were bounded above.
                         // https://docs.dataforseo.com/v3/backlinks/summary/live/
-                        // https://docs.dataforseo.com/v3/backlinks/history/live/
                         operation.id === "backlinks.summary.live"
                             ? 1
                             : undefined;

package/dist/dataforseo/history-window.d.ts

@@ -0,0 +1,5 @@
+/** Both history APIs return at most one item per month. Include partial boundary months.
+ * https://docs.dataforseo.com/v3/backlinks-history-live/
+ * https://docs.dataforseo.com/v3/dataforseo_labs-google-historical_rank_overview-live/
+ */
+export declare function historyWindowOptions(operation: string, task: Readonly<Record<string, unknown>>): Record<string, string>;

package/dist/dataforseo/history-window.js

@@ -0,0 +1,36 @@
+const historyOperations = new Set([
+    "backlinks.history.live",
+    "dataforseo_labs.google.historical_rank_overview.live",
+]);
+function validDate(value) {
+    if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    const date = new Date(`${value}T00:00:00Z`);
+    return Number.isFinite(date.getTime()) && date.toISOString().slice(0, 10) === value;
+}
+/** Both history APIs return at most one item per month. Include partial boundary months.
+ * https://docs.dataforseo.com/v3/backlinks-history-live/
+ * https://docs.dataforseo.com/v3/dataforseo_labs-google-historical_rank_overview-live/
+ */
+export function historyWindowOptions(operation, task) {
+    if (!historyOperations.has(operation))
+        return {};
+    const from = task.date_from;
+    const to = task.date_to;
+    const options = {};
+    if (validDate(from))
+        options.dateFrom = from;
+    else if (from !== undefined)
+        options.pricingUnknown = "true";
+    if (validDate(to))
+        options.dateTo = to;
+    else if (to !== undefined)
+        options.pricingUnknown = "true";
+    if (!validDate(from) || !validDate(to))
+        return options;
+    if (from > to)
+        return { ...options, pricingUnknown: "true" };
+    const monthIndex = (date) => Number(date.slice(0, 4)) * 12 + Number(date.slice(5, 7));
+    options.itemCount = String(monthIndex(to) - monthIndex(from) + 1);
+    return options;
+}

package/dist/dataforseo/request-pricing.js

@@ -7,7 +7,7 @@ export const requestPricing = {
     // Request field inventory: https://docs.dataforseo.com/v3/backlinks/backlinks/live/
     "backlinks.backlinks.live": {
         source: "https://docs.dataforseo.com/v3/backlinks/backlinks/live/",
-        formula: "2.4 + 0.0036 * rowCount cents; summary one row, backlinks limit, history count unknown",
+        formula: "2.4 + 0.0036 * rowCount cents; summary one row, backlinks limit, history inclusive month bound with explicit dates",
         priceFields: {
             limit: {
                 formula: "(base + per-item * limit); documented default, 1..1000; zero unknown",
@@ -32,13 +32,13 @@ export const requestPricing = {
     // Request field inventory: https://docs.dataforseo.com/v3/backlinks/history/live/
     "backlinks.history.live": {
         source: "https://docs.dataforseo.com/v3/backlinks/history/live/",
-        formula: "2.4 + 0.0036 * rowCount cents; summary one row, backlinks limit, history count unknown",
+        formula: "2.4 + 0.0036 * rowCount cents; history inclusive month bound with explicit dates",
         priceFields: {
             date_from: {
-                formula: "changes returned row count; count not derivable from the request",
+                formula: "inclusive first calendar month; both dates required to bound item count",
             },
             date_to: {
-                formula: "changes returned row count; count not derivable from the request",
+                formula: "inclusive last calendar month; both dates required to bound item count",
             },
         },
         neutralFields: ["target", "rank_scale", "tag"],
@@ -46,7 +46,7 @@ export const requestPricing = {
     // Request field inventory: https://docs.dataforseo.com/v3/backlinks/summary/live/
     "backlinks.summary.live": {
         source: "https://docs.dataforseo.com/v3/backlinks/summary/live/",
-        formula: "2.4 + 0.0036 * rowCount cents; summary one row, backlinks limit, history count unknown",
+        formula: "2.4 + 0.0036 * rowCount cents; summary one row, backlinks limit, history inclusive month bound with explicit dates",
         priceFields: {},
         neutralFields: [
             "target",
@@ -63,7 +63,7 @@ export const requestPricing = {
     // Request field inventory: https://docs.dataforseo.com/v3/dataforseo_labs/google/domain_rank_overview/live/
     "dataforseo_labs.google.domain_rank_overview.live": {
         source: "https://docs.dataforseo.com/v3/dataforseo_labs/google/domain_rank_overview/live/",
-        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count unknown; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
+        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count requires explicit date bounds; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
         priceFields: {
             limit: {
                 formula: "(base + per-item * limit); documented default, 1..1000; zero unknown",
@@ -84,16 +84,16 @@ export const requestPricing = {
     // Request field inventory: https://docs.dataforseo.com/v3/dataforseo_labs/google/historical_rank_overview/live/
     "dataforseo_labs.google.historical_rank_overview.live": {
         source: "https://docs.dataforseo.com/v3/dataforseo_labs/google/historical_rank_overview/live/",
-        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count unknown; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
+        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count requires explicit date bounds; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
         priceFields: {
             include_clickstream_data: {
                 formula: "true doubles entire request charge",
             },
             date_from: {
-                formula: "changes returned row count; count not derivable from the request",
+                formula: "inclusive first calendar month; both dates required to bound item count",
             },
             date_to: {
-                formula: "changes returned row count; count not derivable from the request",
+                formula: "inclusive last calendar month; both dates required to bound item count",
             },
         },
         neutralFields: [
@@ -110,7 +110,7 @@ export const requestPricing = {
     // Request field inventory: https://docs.dataforseo.com/v3/dataforseo_labs/google/keyword_ideas/live/
     "dataforseo_labs.google.keyword_ideas.live": {
         source: "https://docs.dataforseo.com/v3/dataforseo_labs/google/keyword_ideas/live/",
-        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count unknown; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
+        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count requires explicit date bounds; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
         priceFields: {
             include_clickstream_data: {
                 formula: "true doubles entire request charge",
@@ -142,7 +142,7 @@ export const requestPricing = {
     // Request field inventory: https://docs.dataforseo.com/v3/dataforseo_labs/google/keyword_overview/live/
     "dataforseo_labs.google.keyword_overview.live": {
         source: "https://docs.dataforseo.com/v3/dataforseo_labs/google/keyword_overview/live/",
-        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count unknown; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
+        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count requires explicit date bounds; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
         priceFields: {
             keywords: {
                 formula: "base + 0.012 cents * keywords.length; clickstream doubles total",
@@ -163,7 +163,7 @@ export const requestPricing = {
     // Request field inventory: https://docs.dataforseo.com/v3/dataforseo_labs/google/keyword_suggestions/live/
     "dataforseo_labs.google.keyword_suggestions.live": {
         source: "https://docs.dataforseo.com/v3/dataforseo_labs/google/keyword_suggestions/live/",
-        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count unknown; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
+        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count requires explicit date bounds; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
         priceFields: {
             include_seed_keyword: {
                 formula: "false neutral; true unknown because extra item count is unconfirmed",
@@ -199,7 +199,7 @@ export const requestPricing = {
     // Request field inventory: https://docs.dataforseo.com/v3/dataforseo_labs/google/ranked_keywords/live/
     "dataforseo_labs.google.ranked_keywords.live": {
         source: "https://docs.dataforseo.com/v3/dataforseo_labs/google/ranked_keywords/live/",
-        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count unknown; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
+        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count requires explicit date bounds; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
         priceFields: {
             include_clickstream_data: {
                 formula: "true doubles entire request charge",
@@ -228,7 +228,7 @@ export const requestPricing = {
     // Request field inventory: https://docs.dataforseo.com/v3/dataforseo_labs/google/related_keywords/live/
     "dataforseo_labs.google.related_keywords.live": {
         source: "https://docs.dataforseo.com/v3/dataforseo_labs/google/related_keywords/live/",
-        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count unknown; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
+        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count requires explicit date bounds; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
         priceFields: {
             include_seed_keyword: {
                 formula: "false neutral; true unknown because extra item count is unconfirmed",
@@ -261,7 +261,7 @@ export const requestPricing = {
     // Request field inventory: https://docs.dataforseo.com/v3/dataforseo_labs/google/relevant_pages/live/
     "dataforseo_labs.google.relevant_pages.live": {
         source: "https://docs.dataforseo.com/v3/dataforseo_labs/google/relevant_pages/live/",
-        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count unknown; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
+        formula: "(base + perItem * itemCount) * (clickstream ? 2 : 1); historical count requires explicit date bounds; ordinary base 1.2, perItem 0.012 cents; historical base 12, perItem 0.12 cents",
         priceFields: {
             include_clickstream_data: {
                 formula: "true doubles entire request charge",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usagekit/providers",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Provider descriptors, catalog, price tables, extractors, fixtures and probes.",
@@ -31,7 +31,7 @@
     "prepack": "node ../../scripts/package-license.mjs"
   },
   "dependencies": {
-    "@usagekit/core": "0.9.0"
+    "@usagekit/core": "0.9.1"
   },
   "peerDependencies": {
     "vitest": ">=5.0.1 <6",