Summer store skill for AI agents

npx -y summer-engine@latest skills install summer-store --agent claude-code

extends Node
## A shop for Summer items, paid in Sparks. Summer shows its own purchase
## sheet; the game never sees money and never grants an item itself.

signal shelf_changed(rows: Array)          # [{name, sparks, offer_id}]
signal checkouts_changed(busy: bool, rows: Array)
signal status(text: String)

var store: SummerClientStore
var items: SummerClientItems

## Main calls this right after Summer.initialize succeeds: a child's _ready
## runs before that, while Summer.client is still null.
func start() -> void:
	store = Summer.client.store
	items = Summer.client.items
	# Connect before reading retained statuses; a normal (not deferred)
	# connection is how the SDK knows a result was delivered.
	store.checkout_status_changed.connect(func(_status: SummerCheckoutStatus) -> void: _render_checkouts())
	items.refreshed.connect(_on_items_changed)
	items.item_replaced.connect(func(_change: SummerInventoryChange) -> void: _on_items_changed())
	items.item_removed.connect(func(_change: SummerInventoryChange) -> void: _on_items_changed())
	_render_checkouts()

## Opening the shop screen.
func open() -> void:
	var readiness := store.check_browse_readiness()
	if not readiness.ok:
		status.emit("The shop is not available here.")   # hide the shop button
		return
	var page := store.list_items(50)
	var listed: SummerResult = await page.get_result_or_completed_signal()
	if not listed.ok:
		status.emit("The shop could not load.")
		return
	var rows := []
	for item in page.items:
		if item.price != null and item.price.offer_id != "":
			rows.append({"name": item.name, "sparks": item.price.sparks_amount, "offer_id": item.price.offer_id})
	shelf_changed.emit(rows)
	if items.check_refresh_readiness().ok:
		items.refresh()

## The Buy button. One call is one purchase: never call it again to retry.
func buy(offer_id: String) -> void:
	if not store.check_checkout_readiness().ok:
		status.emit("Purchases are not available here.")
		return
	if store.has_pending_checkouts():
		return
	var lines: Array[SummerCheckoutLine] = [SummerCheckoutLine.create(offer_id, 1)]
	var operation := store.request_checkout(lines)
	_render_checkouts()
	await operation.get_result_or_completed_signal()
	_render_checkouts(operation)

func _render_checkouts(operation: SummerCheckoutOperation = null) -> void:
	var view := SummerCheckoutObservation.capture(store, operation)
	var rows := []
	for checkout in view.statuses:
		rows.append({"id": checkout.request_id, "state": checkout.state, "error": checkout.error_code})
	checkouts_changed.emit(view.has_pending_checkouts(), rows)
	if view.submission_failure != null:
		status.emit("The purchase did not start: %s" % view.submission_failure.code)

## Ownership comes only from the inventory, never from a checkout result.
func owns(definition_id: String) -> bool:
	return items.is_projection_loaded() and items.has_owned_definition(definition_id)

func _on_items_changed() -> void:
	status.emit("Inventory updated.")

		"equip":
			_equip(request, str(command.get("definition", "")))

## A player asks to wear a hat. The authority reads that Session's inventory
## itself; a client saying "I own it" proves nothing.
func _equip(request: SummerNetworkCommandRequest, definition_id: String) -> void:
	var session := request.get_session()
	var read := Summer.authority.items.inventory_for_session(session)
	var result: SummerResult = await read.get_result_or_completed_signal()
	if not result.ok:
		request.refuse(&"inventory_unavailable")   # retryable: try again later
		return
	for item in read.items:
		if item.is_owned() and item.get_definition_id() == definition_id:
			var hats: Dictionary = match_doc.get("hats", {})
			hats[session.player.user_id] = definition_id
			match_doc["hats"] = hats
			match_group.reset(Game.pack(match_doc))
			request.accept({}, Game.pack({"equipped": definition_id}))
			return
	request.refuse(&"not_owned")

{
  "schema": "summer.local-fixture.v1",
  "fixture_id": "courtyard",
  "fixture_version": 1,
  "seed": 1,
  "world_definition": "world.json",
  "service_outcomes": [],
  "catalog_item_templates": ["hat"],
  "personas": [
    {"persona_id": "alice", "display_name": "Alice", "participant_role": "player", "eligible_for_outcome": true, "session_lifetime": "match_bound"},
    {"persona_id": "bob", "display_name": "Bob", "participant_role": "player", "eligible_for_outcome": true, "session_lifetime": "match_bound"}
  ]
}