@rankwrangler/http-client 0.10.0 → 0.12.0

package/README.md

@@ -2,6 +2,9 @@
 
 Typed tRPC client for the RankWrangler public agent API.
 
+Unified search and `keyword.results` below describe prepared source changes. Database migration,
+package release, and production deployment are pending.
+
 ```bash
 npm install @rankwrangler/http-client
 ```
@@ -19,7 +22,11 @@ const product = await client.product.get.mutate({
     asin: 'B0DV53VS61',
 });
 
-const search = await client.product.search.mutate({
+const search = await client.product.search.query({
+    term: 'retro gardening shirt',
+});
+
+const observedResults = await client.keyword.results.mutate({
     term: 'retro gardening shirt',
 });
 
@@ -35,12 +42,13 @@ const keywords = await client.keyword.search.query({
 });
 ```
 
-The client is scoped to the public surface (`api.public.*`). It exposes Product
-`get/search/history` and keyword `get/search/history`; it does not expose Catalog, Operation,
-polling procedures. Product `get` and `history`, plus keyword reads, expose no refresh controls;
-Product search retains its separate search contract. Product `get` returns the provider-neutral
-current Product shape; Product `history` returns compact rank/price series. `NOT_FOUND` and retryable
-`TIMEOUT` errors are preserved from tRPC, with retry hints on temporary unavailability.
+The client is scoped to `api.public.*`. Product `search` reads the stored catalog and returns
+`{ items, nextCursor, coverage }` without provider calls. Its optional term, filters, and sorting
+screen compact Products with market metrics. `keyword.results` preserves dated external search
+evidence and can wait for collection under the existing 24-hour reuse policy.
+
+Product `get` returns the current Product. `getMany` returns basic listing data, and `history`
+returns compact rank and price series. Keyword `get` and `search` read the stored keyword directory, separately from observed search results. Retryable `TIMEOUT` errors preserve retry hints.
 
 ## Types
 
@@ -49,7 +57,7 @@ import type { PublicRouterInputs, PublicRouterOutputs } from '@rankwrangler/http
 
 type ProductGetInput = PublicRouterInputs['product']['get'];
 type ProductSearchOutput = PublicRouterOutputs['product']['search'];
-type KeywordHistoryOutput = PublicRouterOutputs['keyword']['history'];
+type KeywordSearchOutput = PublicRouterOutputs['keyword']['search'];
 ```
 
 When the public router changes, regenerate and build the declarations:

package/dist/app-router.d.ts

@@ -198,82 +198,6 @@ export interface ContextRequest {
 		host?: string;
 	};
 }
-declare const TOP_SEARCH_TERMS_REPORT_PERIODS: readonly [
-	"DAY",
-	"WEEK"
-];
-declare const TOP_SEARCH_TERMS_REFRESH_TRIGGERS: readonly [
-	"requested",
-	"automatic"
-];
-export type TopSearchTermsReportPeriod = (typeof TOP_SEARCH_TERMS_REPORT_PERIODS)[number];
-export type TopSearchTermsRefreshTrigger = (typeof TOP_SEARCH_TERMS_REFRESH_TRIGGERS)[number];
-export type SearchTermsTrendDelta = {
-	rankDelta: number | null;
-	clickShareDelta: number | null;
-	conversionShareDelta: number | null;
-};
-export type SearchTermsTrendDeltas = {
-	d1: SearchTermsTrendDelta;
-	d7: SearchTermsTrendDelta;
-	d30: SearchTermsTrendDelta;
-};
-export interface KeywordEvidence {
-	searchFrequencyRank: number;
-	clickShareTop3: number;
-	conversionShareTop3: number;
-	topRowsCount: number;
-	isMerchRelevant: boolean;
-	merchReason: string;
-}
-export interface KeywordCurrent {
-	keyword: string;
-	marketplaceId: string;
-	reportPeriod: TopSearchTermsReportPeriod;
-	dataStartDate: string;
-	dataEndDate: string;
-	observedDate: string;
-	fetchedAt: string;
-	trigger: TopSearchTermsRefreshTrigger;
-	evidence: KeywordEvidence;
-}
-export interface KeywordSearchItem extends KeywordEvidence {
-	keyword: string;
-	observedDate: string;
-	trigger: TopSearchTermsRefreshTrigger;
-}
-export interface KeywordSearchSummary {
-	marketplaceId: string;
-	reportPeriod: TopSearchTermsReportPeriod;
-	dataStartDate: string | null;
-	dataEndDate: string | null;
-	observedDate: string | null;
-	fetchedAt: string | null;
-	totalFiltered: number;
-}
-export interface KeywordSearchResponse {
-	status: "ready" | "empty";
-	items: KeywordSearchItem[];
-	nextCursor: number | null;
-	summary: KeywordSearchSummary;
-}
-export interface KeywordHistoryPoint {
-	observedDate: string;
-	searchFrequencyRank: number;
-	clickShareTop3: number;
-	conversionShareTop3: number;
-	trigger: TopSearchTermsRefreshTrigger;
-}
-export interface KeywordHistoryResponse {
-	keyword: string;
-	marketplaceId: string;
-	reportPeriod: TopSearchTermsReportPeriod;
-	rangeDays: number;
-	status: "ready" | "empty";
-	latestObservedDate: string | null;
-	points: KeywordHistoryPoint[];
-	deltas: SearchTermsTrendDeltas;
-}
 export type PublicCutoutThumbnail = {
 	status: "available";
 	url: string;
@@ -324,7 +248,7 @@ export interface Product {
 		};
 	};
 }
-export interface ProductSearchProduct {
+export interface KeywordResultsProduct {
 	marketplaceId: string;
 	asin: string;
 	title: string | null;
@@ -348,12 +272,12 @@ export interface ProductSearchProduct {
 	} | null;
 	boughtInPastMonth: number | null;
 }
-export interface ProductSearch {
+export interface KeywordResults {
 	keyword: string;
 	searchedAt: string;
 	results: Array<{
 		organicSearchPlacement: number;
-		product: ProductSearchProduct;
+		product: KeywordResultsProduct;
 	}>;
 }
 export interface BasicProduct {
@@ -505,42 +429,92 @@ export declare const publicAppRouter: import("@trpc/server").TRPCBuiltRouter<{
 				get: import("@trpc/server").TRPCQueryProcedure<{
 					input: {
 						keyword: string;
-						dataEndDate?: string | undefined;
-						dataStartDate?: string | undefined;
-						marketplaceId?: "ATVPDKIKX0DER" | undefined;
-						reportPeriod?: "DAY" | "WEEK" | undefined;
 					};
 					output: {
 						keyword: string;
-						status: "ready" | "empty";
-						current: KeywordCurrent | null;
+						data: {
+							createdAt: string;
+							lastCheckedAt: string | null;
+							nextCheckAt: string | null;
+							id: string;
+							queryId: string | null;
+							term: string;
+							status: "queued" | "scanning" | "upToDate" | "untracked";
+							untrackedReason: "notRelevant" | "noMerchFound" | "notScheduled" | null;
+							retryScheduled: boolean;
+							heat: string;
+							score: number | null;
+							sources: string[];
+							products: number;
+							merch: number;
+							intervalDays: number | null;
+						};
 					};
 					meta: object;
 				}>;
-				history: import("@trpc/server").TRPCQueryProcedure<{
+				results: import("@trpc/server").TRPCMutationProcedure<{
 					input: {
-						keyword: string;
-						marketplaceId?: "ATVPDKIKX0DER" | undefined;
-						rangeDays?: number | undefined;
-						reportPeriod?: "DAY" | "WEEK" | undefined;
+						term: string;
+						refresh?: boolean | undefined;
 					};
-					output: KeywordHistoryResponse;
+					output: KeywordResults;
 					meta: object;
 				}>;
 				search: import("@trpc/server").TRPCQueryProcedure<{
 					input: {
 						text: string;
-						cursor?: number | undefined;
+						state?: "all" | "queued" | "scanning" | "upToDate" | "untracked" | undefined;
+						sort?: "work" | "newest" | undefined;
 						limit?: number | undefined;
-						maxRank?: number | undefined;
-						merchOnly?: boolean | undefined;
-						minRank?: number | undefined;
-						dataEndDate?: string | undefined;
-						dataStartDate?: string | undefined;
-						marketplaceId?: "ATVPDKIKX0DER" | undefined;
-						reportPeriod?: "DAY" | "WEEK" | undefined;
+						heat?: "unrated" | "hot" | "warm" | "cold" | "all" | undefined;
+						cursor?: {
+							key: [
+								number,
+								number,
+								number,
+								number,
+								number,
+								number,
+								string
+							];
+							asOf: string;
+							trialTurn: boolean;
+							sort: "work" | "newest";
+						} | undefined;
+					};
+					output: {
+						items: {
+							createdAt: string;
+							lastCheckedAt: string | null;
+							nextCheckAt: string | null;
+							id: string;
+							queryId: string | null;
+							term: string;
+							status: "queued" | "scanning" | "upToDate" | "untracked";
+							untrackedReason: "notRelevant" | "noMerchFound" | "notScheduled" | null;
+							retryScheduled: boolean;
+							heat: string;
+							score: number | null;
+							sources: string[];
+							products: number;
+							merch: number;
+							intervalDays: number | null;
+						}[];
+						nextCursor: {
+							key: [
+								number,
+								number,
+								number,
+								number,
+								number,
+								number,
+								string
+							];
+							asOf: string;
+							trialTurn: boolean;
+							sort: "work" | "newest";
+						} | null;
 					};
-					output: KeywordSearchResponse;
 					meta: object;
 				}>;
 			}>>;
@@ -601,12 +575,106 @@ export declare const publicAppRouter: import("@trpc/server").TRPCBuiltRouter<{
 					output: PublicProductHistory;
 					meta: object;
 				}>;
-				search: import("@trpc/server").TRPCMutationProcedure<{
+				search: import("@trpc/server").TRPCQueryProcedure<{
 					input: {
-						term: string;
-						refresh?: boolean | undefined;
+						term?: string | undefined;
+						textFields?: "title" | "all" | undefined;
+						excludeWords?: string[] | undefined;
+						marketplaceIds?: string[] | undefined;
+						isMerchListing?: boolean | "unknown" | "all" | undefined;
+						amazonListingStatus?: "active" | "deleted" | "all" | undefined;
+						brands?: string[] | undefined;
+						excludeBrands?: string[] | undefined;
+						includeOfficialBrands?: boolean | undefined;
+						categoryIds?: number[] | undefined;
+						salesRank?: {
+							min?: number | undefined;
+							max?: number | undefined;
+						} | undefined;
+						price?: {
+							min?: number | undefined;
+							max?: number | undefined;
+						} | undefined;
+						monthlySold?: {
+							min?: number | undefined;
+							max?: number | undefined;
+						} | undefined;
+						firstAvailableAt?: {
+							after?: string | undefined;
+							before?: string | undefined;
+						} | undefined;
+						discoveredAt?: {
+							after?: string | undefined;
+							before?: string | undefined;
+						} | undefined;
+						updatedAt?: {
+							after?: string | undefined;
+							before?: string | undefined;
+						} | undefined;
+						facets?: {
+							facet: string;
+							name: string;
+						}[] | undefined;
+						sort?: "relevance" | "salesRankAsc" | "salesRankDesc" | "firstAvailableAtDesc" | "firstAvailableAtAsc" | "updatedAtAsc" | "updatedAtDesc" | "discoveredAtDesc" | "priceAsc" | "priceDesc" | "monthlySoldDesc" | undefined;
+						cursor?: string | null | undefined;
+						limit?: number | undefined;
+					};
+					output: {
+						coverage: {
+							keyword: string;
+							headCheckedAt: string | null;
+							exploration: {
+								source: "spapi";
+								pages: number;
+								observedAt: string | null;
+								budgetLimited: boolean;
+							} | null;
+						} | null;
+						items: {
+							marketplaceId: string;
+							asin: string;
+							title: string | null;
+							brand: string | null;
+							bullet1: string | null;
+							bullet2: string | null;
+							thumbnail: {
+								status: "available";
+								url: string;
+							} | {
+								status: "unavailable";
+								url?: undefined;
+							};
+							isMerchListing: boolean | null;
+							amazonListingStatus: AmazonListingStatus;
+							categoryId: number | null;
+							salesRank: number | null;
+							price: {
+								amountMinor: number;
+								currencyCode: string;
+							} | null;
+							firstAvailableAt: string | null;
+							discoveredAt: string;
+							updatedAt: string;
+							averages: {
+								last30Days: number | null;
+								last90Days: number | null;
+							};
+							demand: {
+								boughtInPastMonth: number | null;
+								salesRankDrops: {
+									last30Days: number | null;
+									last90Days: number | null;
+									last180Days: number | null;
+									last365Days: number | null;
+								};
+							};
+							facets: {
+								facet: string;
+								name: string;
+							}[];
+						}[];
+						nextCursor: string | null;
 					};
-					output: ProductSearch;
 					meta: object;
 				}>;
 			}>>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rankwrangler/http-client",
-    "version": "0.10.0",
+    "version": "0.12.0",
     "description": "Typed tRPC client for RankWrangler",
     "repository": {
         "type": "git",