LinkO'Star

Changelog

Changes that may impact integrators. For the full backend git log, check the repository. This page only lists items integrators may need to act on.

Breaking-change notice SLA

  • Path / method removal or rename: at least 30 days' notice + one release of parallel availability.
  • Response key removal or type change: at least 14 days' notice.
  • Response key addition: no notice — integrators must ignore unknown keys.
  • New required query param / header: 14 days' notice plus a default-value compatibility window.
  • All notices: this page + email or Slack to known supplier contacts.

2026-06-20 — Supplier OAuth + Permission Sync (V8~V13)

  • feat (V8): Activation outbound to sdx-web. On device activation LinkOStar now POSTs to sdx-web's /api/m2m/billing/activation to debit the credit ledger. device_activation_event grew sync_status /synced_at / last_attempt_at / sync_error columns. Ops can track via GET /platform/activation-events?syncStatus=PENDING|SYNCED|FAILED|REJECTED_BALANCE. No integrator action — the billing model now has a single SSOT.
  • feat (V9): supplier-opaque metadata + provisioning two-mode. (a) hub_claim_code.metadata + hub_instance.metadata JSON slots — supplier attaches owner/space/spot ids on claim code creation and reads them back on hub fetch. (b) Provisioning step configJson contract for external_submit_url /external_headers / track_state_in_linkostar. When the mobile app POSTs straight to the supplier, LinkOStar is bypassed. The default LinkOStar submit endpoint (/tenant/hubs/{uuid}/provisioning/steps/{stepId}/submit) still works. (c) Optional device_instance.hub_uuidmapping column — customers that don't maintain the mapping keep it NULL.
  • feat (V10): Supplier OAuth client (Authorization Code + PKCE). LinkOStar app users can link their accounts to a supplier identity. POST /app/supplier-link/authorize → external browser (RFC 8252) → GET /auth/supplier-link/callback → tokens kept server-side (AES-GCM) → GET /app/supplier-links/{id}/access-token returns a refresh-aware bearer. n:1 model (user × supplier × sub) — one user can connect multiple accounts of the same supplier. See Supplier OAuth.
  • feat (V11): Five new fields on supplier_oauth_config — permission_query_url · permission_webhook_url · hub_registration_url · device_registration_url · registration_shared_secret. All optional. Each opens a corresponding sync channel.
  • feat (V12): LinkOStar → supplier registration outbox. New hub / device events are POSTed to the supplier with HMAC-SHA256 (X-LinkOStar-Signature: sha256=<hex>) and an idempotency header. Failures retry with backoff; 4xx is DEAD. The supplier only has to implement a receiver and verify the signature.
  • feat (V13, potentially breaking): Supplier-SSOT permission sync. When a supplier registers permission_query_url, /app/hubs · /app/devices responses are filteredby the supplier's permission view. Suppliers without a registered config are unaffected. Cache invalidation via POST /webhook/supplier-permission/{supplierUuid}(HMAC-signed). Permissions: OWNER > OPERATOR > VIEWER. Integrator action: confirm whether your supplier registers permission_query_url. If not, LinkOStar-SSOT semantics continue.
  • feat (V13): GET /app/bundle-catalog added — PUBLISHED bundle listing with per-viewer requiresSupplierLink / currentUserLinked flags. A catalog entry is visible even when the hub instance is hidden by supplier-SSOT — the link entry point.
  • feat (Flutter): new Link step in the provisioning flow + a Connected Services settings screen. external_submit_url calls now carry the supplier-issued Bearer automatically.
  • Ops note: LINKOSTAR_CRYPTO_SECRET (32-byte base64) env is now required in production — without it, every token / client_secret is encrypted with the dev fallback key. See Supplier OAuth for the first-supplier registration runbook.

2026-06-04

  • fix: the HubTokenAuthenticationFilter hub-bearer check now compares bytes directly. Rows that stored a trailing zero-pad byte under one Hibernate/MySQL combination were 401-ing on every request. No integrator action — hub-agent telemetry and refresh just work again.
  • feat: ProvisioningStep gained an INFO type — a read-only acknowledge step (title + description + Next button). The existing four types remain compatible.
  • feat: the hub-agent BLE service UUID changed from 00001801-... to 6d18c51f-0440-4e48-bbee-aa908ce6d0ef(LinkOStar custom). Hubs running hub-os ≤ v0.1.5 are not discoverable by the updated mobile scan; re-flash to v0.1.6+ to recover.
  • feat: the hub-agent telemetry / reconcile / self-update loops now run regardless of MQTT being enabled. Setting mqtt.enabled: falsepreviously silenced telemetry as well; that regression is fixed in v0.1.5.

2026-06-01

  • revert: /dashboard/stats removed. Cross-resource aggregation belongs in the supplier BFF, not in LinkOStar — see the 4-tile dashboard example in Integration Guide.

2026-05-31

  • feat: POST /v1/hubs/{uuid}/telemetrynow accepts the hub-agent's flat reported-state shape directly. The previous {payloadJson: ...} envelope still works.
  • feat: GET /tenant/hubs now returns hubTypeand macAddress. All previous keys remain.

Versioning

  • Backend: rolling deploy. master push = production deploy. No semver tags.
  • Hub-agent: vMAJOR.MINOR.PATCH tags (e.g. v0.1.5).
  • Hub-OS: hub-os-vMAJOR.MINOR.PATCH tags. Auto-bakes the latest hub-agent.
  • OpenAPI spec: no version number. Updates are reflected in the spec immediately and announced on this page.