@rankwrangler/http-client 0.10.0 → 0.11.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,14 @@ 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. Brand Analytics keyword `get`, `search`, and `history`
+remain separate from observed search results. Retryable `TIMEOUT` errors preserve retry hints.
 
 ## Types
 

package/dist/app-router.d.ts

@@ -324,7 +324,7 @@ export interface Product {
 		};
 	};
 }
-export interface ProductSearchProduct {
+export interface KeywordResultsProduct {
 	marketplaceId: string;
 	asin: string;
 	title: string | null;
@@ -348,12 +348,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 {
@@ -517,6 +517,14 @@ export declare const publicAppRouter: import("@trpc/server").TRPCBuiltRouter<{
 					};
 					meta: object;
 				}>;
+				results: import("@trpc/server").TRPCMutationProcedure<{
+					input: {
+						term: string;
+						refresh?: boolean | undefined;
+					};
+					output: KeywordResults;
+					meta: object;
+				}>;
 				history: import("@trpc/server").TRPCQueryProcedure<{
 					input: {
 						keyword: string;
@@ -601,12 +609,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.11.0",
     "description": "Typed tRPC client for RankWrangler",
     "repository": {
         "type": "git",