Google Immersive Product API

# Integrate HasData Google Immersive Product API

## Task

Add the requested detailed product, retailer offer, variant or review research workflow using HasData Google Immersive Product API.
Inspect project instructions, the server-side runtime, existing HTTP client, and tests first.
Follow the project's conventions and preserve unrelated code. No new SDK is required.
Implement only the requested workflow. If it is unclear, ask which product and workflow are needed and whether a current immersive product token is already available.
Keep the integration as REST API calls; do not replace it with an MCP connection or a custom Google scraper.

## References

Read the endpoint documentation before implementing:

- Product details, seller expansion and pagination: https://docs.hasdata.com/apis/google-serp/immersive-product.md
- Product search and token source: https://docs.hasdata.com/apis/google-serp/shopping.md
- Error handling: https://docs.hasdata.com/api-codes.md
- Documentation index: https://docs.hasdata.com/llms.txt
- Full documentation (fallback): https://docs.hasdata.com/llms-full.txt

Start with the endpoint reference. Use `llms.txt` to find additional pages.
Use `llms-full.txt` only when needed; extract relevant sections instead of loading everything into context.
If a `.md` reference is unavailable, try its HTML URL without `.md`.
If it is still unavailable, ask for the missing documentation rather than guessing.

## Optional agent skill

If the official `hasdata` skill is already available, use its relevant guidance.
Otherwise, if this agent supports skills, ask before installing it in this project:

```sh
npx skills add hasdata/agent-skills --skill hasdata
```

Run from the project directory and select the coding agent in use.
The `hasdata-cli` skill is not required. If installation is declined or unsupported, continue with the docs.
Flag conflicts between skill guidance and current API docs rather than guessing.


## Implementation

- Use `GET https://api.hasdata.com/scrape/google/immersive-product` with required `pageToken`. Accept the exact `immersiveProductPageToken` returned by a supported product result; a product ID or merchant URL is not a substitute.
- If no valid token is available, explain that a Google Shopping search is a separate request. Obtain a current token only within the agreed workflow and request budget. Do not copy an abbreviated documentation token or assume an old token stays valid.
- Keep opaque tokens unchanged and preserve large product identifiers as strings. Use the existing HTTP client to encode parameters; do not decode or construct product tokens.
- Read `productResults`, with nested `stores`, `aboutTheProduct`, `userReviews`, `variants`, `topInsights` and `videos` when present. Optional sections may be absent. `topInsights` is an array in the current response, not a single object.
- By default, only a selection of seller offers is returned. Use documented `moreStores` only when requested. For requested seller pagination, pass `productResults.storesNextPageToken` as `nextPageToken` while retaining the same product token. Stop on missing or repeated tokens; do not promise every seller.
- Read offer `price`, `extractedPrice`, `shipping`, `shippingExtracted`, `total` and `extractedTotal` only when present. Missing shipping is unknown, not automatically zero. Google-displayed totals are not guaranteed final checkout costs.
- Validate seller offer title, pack size, quantity, condition and currency before price comparison. A Google product group can contain different sizes or packs. Product matching, unit-price normalization, historical tracking and alerts belong to the application.
- Preserve variant groups and options. `available` describes an option exposed by Google, not verified retailer inventory. Use a returned variant `immersiveProductPageToken` for a separate lookup only when requested; do not assume every combination exists.
- Keep aggregate product ratings distinct from seller ratings and individual review ratings. Retain source and original review text; complete review history is not guaranteed. Sentiment, topic extraction and summaries belong to the application.
- Treat specifications and Google’s existing review insights as extracted source material, not independently verified claims or newly generated HasData analysis. Video records contain metadata and links, not transcripts or content reuse rights.
- Validate any returned API link against the exact `https://api.hasdata.com` origin and intended path before sending the key. Merchant, Google, image and video URLs must never receive API credentials.
- Handle timeouts and documented errors before reading data. Keep requests server-side. If no suitable runtime exists, discuss options before changing the architecture.

## Credentials

- Implement the integration and mocked tests without requiring a live API key.
- Read `HASDATA_API_KEY` from the project's existing environment or secret store and send it as `x-api-key`.
- If the key is missing before live verification, ask the user to configure it from https://app.hasdata.com/api-keys.
- Never ask the user to paste the key into chat. Check only that it is configured, without printing its value.
- Never put the key in browser code, logs, or version control. Add only a placeholder to the project's example configuration.
- If using a local `.env` file, make sure it is gitignored.
- Send the key only to `https://api.hasdata.com`. Never forward it to documentation, Google, retailer links, media links, or redirects to another origin.


## Verification

- Add mocked tests for missing and malformed tokens, unchanged token encoding, optional product sections, seller pagination limits, repeated tokens, missing shipping, mixed pack sizes and currencies, variant context, distinct rating scopes, source links, empty results and errors. Include a usage example and run local checks.
- With a configured key and explicit user approval, including approval already given for this task, make one live verification request with agreed inputs. A successful Google Immersive Product API request consumes 5 credits.
- Use an agreed current token. If obtaining one needs a Shopping search, request approval for that extra request or use approval already given; it adds 10 credits when successful. Do not automatically fetch additional sellers or variants.
- Validate the HTTP status, documented API status, and response structure. An empty result set can be valid.
- Do not automatically repeat paid requests to obtain a nonempty response.
- Report changed files, setup commands, and test results. State separately whether live verification passed, failed, or was skipped.
- Ask before deploying.