ble

type ActionTLV struct {
	// Type is the Action Type byte — 0x05 (AirDrop), 0x10 (Nearby
	// Info), etc. Stored as an int rather than byte so JSON renders
	// as a plain integer.
	Type int `json:"type"`
	// TypeHex is the operator-facing form of Type — uppercase,
	// always 2 chars, no 0x prefix ("05", "10"). Matches every
	// public reference's format.
	TypeHex string `json:"type_hex"`
	// Name is the canonical name for the action type, or
	// "Unknown" when the type isn't in our catalog. The walker
	// still records and returns unknown types so operators can
	// flag novel signatures.
	Name string `json:"name"`
	// Length is the declared payload length in bytes (the L byte
	// of the TLV).
	Length int `json:"length"`
	// Hex is the operator-facing hex rendering of Value — always
	// uppercase, no separators.
	Hex string `json:"hex"`
	// Value is the raw payload bytes.
	Value []byte `json:"-"`
	// Fields carries documented-action-type field decodes, keyed
	// by short snake_case names. Nil for unknown types or for
	// types whose body we don't dissect further.
	Fields map[string]any `json:"fields,omitempty"`
	// DecodeWarning is non-empty when the per-type decoder hit a
	// recoverable shape issue (e.g. payload shorter than the
	// documented minimum for that action). The TLV is still
	// returned so the operator can see the raw bytes; the warning
	// flags that Fields may be partial or missing.
	DecodeWarning string `json:"decode_warning,omitempty"`
}

type Continuity struct {
	// TLVs is the ordered list of action-type entries pulled from
	// the payload. May be empty when the payload is empty after
	// prefix-stripping (legal but unusual — an empty 0x004C
	// manufacturer record).
	TLVs []ActionTLV `json:"tlvs"`
	// Count is len(TLVs) — surfaced for callers that consume the
	// JSON directly without needing to compute it.
	Count int `json:"count"`
	// StrippedPrefix records what the parser stripped from the
	// front of the input before walking ("none", "manufacturer",
	// "ad_structure"). Useful to confirm the parser interpreted
	// the input as the operator expected.
	StrippedPrefix string `json:"stripped_prefix"`
}

type Eddystone struct {
	// FrameType is the frame-type byte at offset 0 of the
	// service-data payload.
	FrameType int `json:"frame_type"`
	// FrameTypeHex is the operator-facing hex form ("00", "10",
	// "20", "30").
	FrameTypeHex string `json:"frame_type_hex"`
	// FrameName is the canonical name ("UID", "URL", "TLM",
	// "EID") or "Unknown" for out-of-catalog types.
	FrameName string `json:"frame_name"`
	// Fields carries the decoded per-frame-type fields. Nil for
	// unknown types or when DecodeWarning is set.
	Fields map[string]any `json:"fields,omitempty"`
	// Hex is the operator-facing hex rendering of the full
	// service-data payload (including the frame-type byte).
	Hex string `json:"hex"`
	// DecodeWarning is non-empty when the payload is shorter than
	// the documented minimum for its frame type. The frame type
	// and raw hex are still surfaced.
	DecodeWarning string `json:"decode_warning,omitempty"`
}

type EddystoneEncodeRequest struct {
	Kind    string `json:"kind"`
	TxPower int    `json:"tx_power_dbm,omitempty"`

	URL string `json:"url,omitempty"`

	Namespace string `json:"namespace,omitempty"`
	Instance  string `json:"instance,omitempty"`

	BatteryMV    int     `json:"battery_mv,omitempty"`
	TemperatureC float64 `json:"temperature_c,omitempty"`
	AdvCount     int     `json:"adv_count,omitempty"`
	Uptime100ms  int     `json:"uptime_100ms,omitempty"`

	EphemeralID string `json:"ephemeral_id,omitempty"`

	// Wrap controls the framing of the returned bytes:
	//   "" / "frame" — the bare Eddystone frame (starts with the
	//                   frame-type byte); the default.
	//   "uuid"        — prefixed with the 0xAA 0xFE service UUID.
	//   "ad"          — the full BLE Service-Data AD structure
	//                   (length, 0x16, 0xAA, 0xFE, frame) ready to drop
	//                   into an advertising payload.
	Wrap string `json:"wrap,omitempty"`
}

type EddystoneFrameType byte

type GAPAdvertisement struct {
	// Records is the ordered list of decoded records.
	Records []GAPRecord `json:"records"`
	// Count is len(Records).
	Count int `json:"count"`
	// Warnings collects non-fatal observations (zero-length
	// terminator hit, trailing bytes after final record, etc.).
	Warnings []string `json:"warnings,omitempty"`
}

type GAPRecord struct {
	// Length is the declared record length byte (size of AD
	// type + data; doesn't count the length byte itself).
	Length int `json:"length"`
	// ADType is the 1-byte AD type identifier.
	ADType int `json:"ad_type"`
	// ADTypeHex is the operator-facing form ("01", "FF").
	ADTypeHex string `json:"ad_type_hex"`
	// Name is the documented Bluetooth SIG name for the AD type,
	// or "Unknown" when the type isn't in our table.
	Name string `json:"name"`
	// DataHex is the operator-facing hex rendering of the data
	// portion (the bytes after the AD type, length = Length-1).
	DataHex string `json:"data_hex"`
	// Decoded is the per-AD-type structured field decode.
	// Populated for the documented types we dissect (Flags,
	// Service UUID lists, Local Name, TX Power, Service Data,
	// Manufacturer Data, Appearance). nil for types we leave as
	// raw hex.
	Decoded map[string]any `json:"decoded,omitempty"`
}