# Signal Stock reviews · 0.1.0

Save `signal-trade-stock-sync.mjs` on your trusted server. It is a dependency-free Node client. Create a separate **Stock reviews** connection in Signal Trade and first use `getTradeApiAccount` to confirm the dealership and exact scope.

`stock_review:read` reads the private review queue, cost position, evidence and decision history. `stock_review:manage` also records decisions and prepares their owned follow-up tasks. Existing Stock, finance, CRM, deal and advert keys receive no new review access.

## Read a vehicle and record a reviewed decision

```js
import {randomUUID} from 'node:crypto';
import {getStockReview,saveStockReview} from './signal-trade-stock-sync.mjs';

const connection={apiKey:process.env.SIGNAL_TRADE_API_KEY};
const vehicleId='YOUR_SAVED_STOCK_ID';
const current=await getStockReview({...connection,vehicleId});
const body={
  operationId:randomUUID(),
  expected:current.review.expected,
  decision:'keep',
  reason:'Recorded asking price retained after reviewing the current costs.',
  nextReviewDate:'YOUR_FUTURE_YYYY_MM_DD',
  ownerUserId:current.review.assignees[0].userId,
};
// Persist body in your transactional private storage BEFORE sending.
// Store the original operation receipt separately from the current review.
const saved=await saveStockReview({...connection,vehicleId,body});
console.log(saved.operation.id,saved.operation.result.recordedAt);
```

The reviewer must be a currently eligible principal, manager or the buyer who owns this Stock record. Choose the intended reviewer from the returned `assignees`; the first item above is only a code example. A next review date is required and must be in the future. Unknown costs keep complete totals blank and do not establish a gross contribution.

`change_price` additionally requires `newAskingPrice:{amountPence,vatBasis,vatRateBasisPoints}`. Amounts are integer pence; choose a usable explicit VAT basis/rate. This updates the internal asking price and prepares the related Signal advert as a draft for a fresh price review. It does not publish an advert. `disposal_plan` additionally requires a supported `disposalRoute`; it records an intention and does not record a sale or pay an auction house.

Optional evidence is either `{kind:'manual',reference,observedAt,note?}` or `{kind:'saved_valuation',valuationId}`. Manual observations remain manual. Signal resolves an authorized saved valuation and keeps its qualification and freshness; this permission does not grant a third-party provider licence.

## Recovery and current records

Persist the exact request, including its `operationId` and `expected`, before sending. After a lost reply or restart, retry that same body with the original key. Do not refresh its versions, change its decision or create a new operation ID. Signal returns the original receipt with `replayed:true` and separately returns the current review. The current review can be newer than the receipt. On a confirmed conflict, retain the draft and deliberately read/review the current facts before preparing a new request.

`listStockReviews` accepts `q`, `site`, `filter:'due'|'all'`, `limit:1..100` and an opaque `cursor`. Keep filters/page size unchanged through the page chain; a changed day or queue can require a deliberate fresh read. Record history accepts `historyLimit:1..50` and `historyCursor`. Reads do not create tasks or decisions.

`reconcileStockReviews` accepts an exact saved `{operationId,vehicleIds}` containing 1 to 25 distinct IDs. It creates or reopens one owned task only when a review is due. It never completes a decision. The scheduled Signal worker also rotates bounded Stock pages in the background. Tasks can become due at 31, 46, 61 and 91 days, on the chosen date, or after recorded asking-price/cost facts change.

These dedicated keys do not read the general Stock change feed or manage webhooks. If a separate authorized Stock integration receives `stock.vehicle.updated`, reload the review using this review key; the notice itself is a small invalidation, not review history. Perform a periodic full review queue read to reconcile missed notices.

`stock_price_reviews.csv` in the private accounting export contains non-additive frozen review facts and any associated later actual outcome/completed sale. It is planning evidence, not extra invoice totals, payments, revenue or realised profit. Free reasons, notes, references and staff details are excluded from that CSV.