@adcp/sdk 6.7.0 → 6.8.0

package/skills/build-seller-agent/specialisms/sales-non-guaranteed.md

@@ -2,38 +2,16 @@
 
 Companion to [`../SKILL.md`](../SKILL.md). The SKILL.md baseline applies; this file covers only the deltas for `sales-non-guaranteed`.
 
-Storyboard: `media_buy_non_guaranteed`. The specialism hinges on `bid_price` and `update_media_buy`, neither of which the baseline example shows.
+Storyboard: `sales_non_guaranteed`. The specialism hinges on `bid_price` and `update_media_buy`, neither of which the baseline example shows.
 
-**Forecast surface**: `'spend'` (the default). Programmatic forward forecast — points at ascending budget levels show how impressions and clicks scale with spend. This is the planning surface every non-guaranteed buyer expects. Project your forecaster's spend curves directly onto `Product.forecast` points where each point is `{ budget: { mid }, metrics: { impressions: { low, mid, high }, clicks: { mid } } }`. See [Delivery Forecasts § Budget Curve](https://adcontextprotocol.org/docs/media-buy/product-discovery/media-products#budget-curve) for the canonical worked example.
+**Fork target**: [`examples/hello_seller_adapter_non_guaranteed.ts`](../../../examples/hello_seller_adapter_non_guaranteed.ts) is the worked, passing reference adapter for this specialism. CI gates strict tsc + storyboard pass + upstream-traffic façade.
 
-Packages on `create_media_buy` carry `bid_price`. Validate it against the product's `floor_price`:
+The adapter demonstrates the auction-mode deltas vs `sales-guaranteed`:
 
-```typescript
-createMediaBuy: async (params, ctx) => {
-  for (const pkg of params.packages ?? []) {
-    const product = PRODUCTS.find((p) => p.product_id === pkg.product_id);
-    const floor = product?.pricing_options[0].floor_price;
-    if (floor && pkg.bid_price != null && pkg.bid_price < floor) {
-      return adcpError('INVALID_REQUEST', {
-        message: `bid_price ${pkg.bid_price} below floor_price ${floor}`,
-      });
-    }
-  }
-  return {
-    media_buy_id: `mb_${randomUUID()}`,
-    status: 'active' as const,   // instant — no IO
-    packages: /* ... */,
-  };
-},
+- **Sync confirmation** — `createMediaBuy` returns `media_buy_id` immediately with `status: 'active'` (or `pending_creatives` until creatives attach). No `ctx.handoffToTask`, no IO poll, no task envelope. Auction inventory clears at request time.
+- **Floor pricing** — `pricing_options[].fixed_price` projected from upstream `min_cpm`; `min_spend` and `target_cpm` flow through to the wire when the upstream sets them. Reject `bid_price` below `floor_price` with `INVALID_REQUEST`.
+- **Spend-only forecast** — `forecast_range_unit: 'spend'`; no `availability` unit because non-guaranteed inventory isn't pre-committed. See [Delivery Forecasts § Budget Curve](https://adcontextprotocol.org/docs/media-buy/product-discovery/media-products#budget-curve) for the wire shape.
+- **Pacing propagation** — `even` / `asap` / `front_loaded` forwarded to upstream order; reflected in delivery curve. Validate raw input — reject typos rather than silently passing them through.
+- **`update_media_buy`** — bid/budget changes apply in-flight without re-issuing the order. `valid_actions` on an active non-guaranteed buy should include `pause`, `update_bid`, `get_delivery`; the framework auto-populates this when `status: 'active'`.
 
-updateMediaBuy: async (params, ctx) => {
-  const existing = await ctx.store.get('media_buys', params.media_buy_id);
-  if (!existing) return adcpError('NOT_FOUND', { message: `Media buy ${params.media_buy_id} not found` });
-  // Apply bid/budget updates from params.packages
-  const updated = { ...existing, packages: /* merged */ };
-  await ctx.store.put('media_buys', params.media_buy_id, updated);
-  return updated;
-},
-```
-
-`valid_actions` on an active non-guaranteed buy should include `pause`, `update_bid`, `get_delivery`. The framework auto-populates this when `createMediaBuy`/`updateMediaBuy` return with `status: 'active'`.
+Auction mode is the deletion-fork of the guaranteed sibling. If your backend has HITL approval, fork [`hello_seller_adapter_guaranteed.ts`](../../../examples/hello_seller_adapter_guaranteed.ts) instead. Replace the `// SWAP:` markers with calls to your real backend.