soroq_sdk

soroq_sdk is the pure Dart client layer for Soroq.

Use it when you want to talk to the Soroq control plane from Dart without pulling in any platform plugin code.

What It Includes

  • typed request and response models for app, release, patch, patch-check, boot report, and patch-health flows
  • a small SoroqControlPlaneClient for the hosted control-plane endpoints
  • bundle and manifest download helpers
  • a config-patch helper that downloads a Soroq bundle and returns the JSON payload from artifact.bin
  • pure Dart data structures for bundled metadata and runtime events

Native runtime bridging lives in the sibling soroq_flutter package so this package can stay portable across Flutter and non-Flutter Dart code.

If you are onboarding a Flutter app to the public Soroq alpha, start with:

That public flow includes soroq patch config for JSON config OTA payloads in addition to Android asset patches.

Installation

dependencies:
  soroq_sdk: ^0.1.4

Quick Start

import 'package:soroq_sdk/soroq_sdk.dart';

Future<void> main() async {
  final client = SoroqControlPlaneClient(
    baseUrl: Uri.parse('https://api.example.com'),
  );

  final patchCheck = await client.patchCheck(
    const SoroqPatchCheckRequest(
      appId: 'com.example.app',
      runtimeId: 'runtime-fingerprint',
      currentPatchNumber: 0,
    ),
  );

  if (patchCheck.patchAvailable) {
    print('Patch available: ${patchCheck.patch?.id}');
  }

  final configPatch = await client.fetchConfigPatch(
    const SoroqPatchCheckRequest(
      appId: 'com.example.app',
      runtimeId: 'runtime-fingerprint',
      currentPatchNumber: 0,
    ),
  );
  if (configPatch != null) {
    print('Config OTA payload: ${configPatch.config}');
  }
}

Typical Flow

  1. Build or compute the app runtime identity in your host app.
  2. Call patchCheck(...) to ask the control plane whether a newer patch is available for that runtime.
  3. For config OTA, call fetchConfigPatch(...) to check, download, extract, verify the signed manifest when trust keys are configured, and parse the JSON payload in one step. The helper sends a config-kind patch-check so newer asset patches do not hide unapplied config patches.
  4. For lower-level integrations, download the signed manifest and bundle from the returned URLs.
  5. After the runtime applies or rejects a patch, report the result with reportBoot(...).
  6. Inspect rollout health with patchHealth(...) when you need operator-side visibility.
  7. Use listApps(...), listReleases(...), and listPatches(...) when you are building a dashboard or operator tool.

API Surface

  • SoroqControlPlaneClient
    • listApps(...)
    • app(...)
    • listReleases(...)
    • release(...)
    • listPatches(...)
    • patch(...)
    • patchCheck(...)
    • fetchConfigPatch(...)
    • downloadConfigPatch(...)
    • reportBoot(...)
    • patchHealth(...)
    • downloadPatchBundle(...)
    • downloadPatchManifest(...)
  • extractPatchBundleArtifact(...) for low-level bundle inspection
  • wire models for apps, releases, patches, patch descriptors, activation modes, patch kinds, config patches, bundled metadata, and runtime events

Status

This package is part of the current Soroq Android public alpha. The core control-plane protocol is real and already used by the companion Flutter runtime/plugin, but the overall product is still evolving toward a more polished Shorebird-style developer workflow. For public users, describe the current lane as Android asset/config OTA with patch-check, boot-report, patch-health, and rollback support; broader code-push parity remains a separate runtime-managed research track.

Published Consumer Proof

Repository maintainers can verify the package handoff from the repository root after publishing:

make package-post-publish-proof

That target checks pub.dev versions, dependency alignment, and archive freshness, then creates clean Dart and Flutter consumers that install from pub.dev, import the public APIs, run Flutter analysis, build an Android debug APK, and finish the non-device public-alpha readiness proof.

Because it installs from pub.dev and finishes the public-alpha readiness proof, it requires network access to pub.dev and the hosted Soroq public-alpha services after both packages are published.

Libraries

soroq_sdk