Skip to content

V- Modal AI: Visual Video / Image Search - Flutter Video SDK

Release Flutter SDK from 70f1bdc14b39d012a7a07f5b98caf9101102a395

vmodal-release-app015bf70a6478
diff --git a/.pubignore b/.pubignore
index 576aa84..e44bfe8 100644
--- a/.pubignore
+++ b/.pubignore
@@ -4,10 +4,13 @@
.idea/
build/
coverage/
+docs/todo/
docs/dev_plan.md
docs/dev_plan_step.md
+docs_sdk/
+docs.py
release/
tool/live_test.dart
+utils.py
SOURCE_MANIFEST.sha256
*.iml
-
diff --git a/RELEASE_METADATA b/RELEASE_METADATA
index 512f7df..a1cb915 100644
--- a/RELEASE_METADATA
+++ b/RELEASE_METADATA
@@ -1 +1 @@
-Source-vmx-api: 664ac242fe76e342423a4f79f8a9f1ee7c4a0b2c
+Source-vmx-api: 70f1bdc14b39d012a7a07f5b98caf9101102a395
diff --git a/SOURCE_MANIFEST.sha256 b/SOURCE_MANIFEST.sha256
index 2bc1e48..4e9cdb7 100644
--- a/SOURCE_MANIFEST.sha256
+++ b/SOURCE_MANIFEST.sha256
@@ -1,16 +1,17 @@
e789cd4d1bed8a78ec8014c5c5913e300f81b63ea56a56aacb0dfec3b5e7ce2b ./.flutter-version
fbbda2e7e29bbd860539a9ca18c478f3b02de140f25a872c19a6dbecd11bc94b ./.github/workflows/publish.yml
-b2dc1cfc58dcd93d62c8f4a1c05210c9f4a3e5b93e69541a40fcf8176cb5f2aa ./.pubignore
+1643ecc8f8b7aeb9d0571896b5d723a89d932be362df671e0d95a1f6214dd2ee ./.pubignore
44900e7c55f6cf8e5068d7a3f169fdf8590ae63bb20602ef67941b879e70582a ./CHANGELOG.md
37b7148216ac6090e36adfb699d642b8dd1e1b8ba99870e65e88733947a59fa6 ./LICENSE
fb7735dc843f246dbcce8225de0def3ff5dc2d0d1655c606eeffd920e356c162 ./README.md
-aec05c0f875eb9e5a4dac8fde5cb0c5a33f14865d92427b0f3f998c7e0d2214d ./RELEASE_METADATA
+df6c3d8637d6f84cc8ec1df005b5637e3918d96b62c7a5784ad7f2c59082c476 ./RELEASE_METADATA
def7e4f643adff5b01b877b6a7fa5b2381612b693c0bf06bd232ee0f7197d342 ./analysis_options.yaml
09a850ca6ebd5470138b7f20204d4dbe0fec89d268a205f14cf3bff0b99f365b ./build.sh
+4f18642680fb433554a5523d00bd99e0d650af340bcaebe628f59f63ac84e458 ./dartdoc_options.yaml
28c321f8798c0e803246c737e0b634c5f3ade930239bb6e5429098bb2b096d86 ./doc/manage_api_key.md
-6b0e2ac4bd31a2d29dd3d4c52cef54b96a9515338d3d105a1172b3189b780c9e ./doc/release.md
+cae6114908952cf81a908b7fcc8c0ba4ce3f866e9dbaf974303273f334e0e3f6 ./doc/release.md
13bacc486006b6b6ae11ae37b2cda0dddf588b8aa8e72c1b13e570b95f36aa59 ./doc/sdk_contract.md
-5c90a4437c33000865ee889e1e2afb875d3e1abc83e5d3150e867efe1240232c ./doc/sdk_doc.md
+37ba2dc3e0ebcc1441ee57b557f93dacd6a941a3549fe31bfbe06ccd14078fa3 ./doc/sdk_doc.md
da330cad4fc27776d249a5db97c1e20bf2cac015d0bbab73b781c0a9ec15b00f ./doc/search_app.md
e246ed229511a24a1ee7e98529c203ef90d1d352290ce8486caebe05683db3a0 ./env.sh
c5ce516b547327aab5b6fa27a523d4c76e66294ada3248b293c54b9595cd3a87 ./example/.metadata
@@ -79,20 +80,20 @@ c59d35f6e3b82291eff92d5c7d55d9efb18ef2375cdef091c282282930729cad ./example/pubs
ca703ea63f5117dea4c308af57be8ff3a65e95400862159b7e793a90dc4d3200 ./example/pubspec.yaml
f6bae8dec3f5ce5afd314198c9a107082d3172cfe0bc6e02efcbc528cabdac1a ./example/test/widget_test.dart
23756b83470b1f25f6a7e6b5a6270f123a5224e49fd8e2eda36001358951b688 ./install.sh
-4630bdec004652eae39bd30f1e864a5b6e5f27a7d98f866bdea192b4d65b4046 ./lib/src/adaptive_upload.dart
-05a8215a0f8d4d5ca26d8dfdf93d8c41b5785d84855459f979b079527f6232b3 ./lib/src/api_key_provider.dart
-af86f6d0d7c5f10f0df759b04790d0b0f495446916ce121b3ef68e4d86d4fd8a ./lib/src/client.dart
-cafa2529768e48a6b89f85a069e337eff7a5cf75103d6ac8623bdbb7a1088549 ./lib/src/collection_uploads.dart
-744ea1477f794e3a2f8f4b8f7e63fe5a84da6f027f5bf83c9780f81bce0fb09d ./lib/src/config.dart
-fcef63e72b69415a1090c376095f8f44977e26104ffaeccf3a82430f65dcd4ff ./lib/src/errors.dart
+7becacd31a8d134fa435b39cd819798d5fbf58f89b9f30c50362e2dcf757aaed ./lib/src/adaptive_upload.dart
+9464fff0c519a1ce70cddefb3e3eaa95d07b97ccdaf5b8381c01d7c88767ae83 ./lib/src/api_key_provider.dart
+3dc89b610de12cc138a2487308ad3eda10b6416fa0c621cd3b99602288f3bf9d ./lib/src/client.dart
+ef4f3226baaefde24d45c7b4d8e9592665d85e1abbdafae4c7e59c462fd42b7d ./lib/src/collection_uploads.dart
+70901be6310dccada51c7b0ad993c6d3d1d99f4223dfd6a7279c49eed67e3fd0 ./lib/src/config.dart
+873d969cfed5c725d34df0fd0c8769462b56992cf523710fcf741a81fa1bbcad ./lib/src/errors.dart
2ad9b4183bce96eacd91c5514de9231b1f0a4f269392726e174507cfa507981a ./lib/src/http.dart
-90310dad6e207dca0d6fd20598fecee615519b819d537cf26a5f3a152dc3ee84 ./lib/src/models.dart
-8b6a10c89a44568aed939d712b05b120f513e04e909ba141a4d55998afa9aaa5 ./lib/src/resources.dart
-28f1ad1be044eb3fbee9a9435c4905a8296ba1ded9a9508fda5436f0de7b93bf ./lib/src/routes.dart
-a3134f6fc8387589e96a345ea35d4c68240c7c1893ef5cd5926707e4168e5309 ./lib/src/transport.dart
-d2411f67f427c095c7d82718c23ddd114fa39221e43333bfd55ac8ece9e4c877 ./lib/src/upload.dart
+52d09295f014fc4f8f8ff1ad714a8be830729b7e29cd6aa5421678e58edd2f0e ./lib/src/models.dart
+ed22b7665e09c9f2f4158c225affe6527b7d3eb921db0ccdf06c01c8cf31db96 ./lib/src/resources.dart
+c96728e339d8a5e83d3731226af832f53545839401e41620eef3f432ac1969c4 ./lib/src/routes.dart
+f0e69d1016f82fbad2a96434129a54a0129f095a0e138cce555db37c8120023f ./lib/src/transport.dart
+d407a3846da3236f37c5dc6af6c231116cc4f23844f623eb22db5365c6616bb5 ./lib/src/upload.dart
732e7f2f942e1c427e19ee3bdb766053f625f69e87dcf770d969555dbc7a9881 ./lib/src/utils.dart
-dd2a40eaedcf0f194d5faf7abf398124506f9db206d418617a69b7361d6ec349 ./lib/vmodal_sdk_flutter.dart
+17f7649a89019dd0664fb4b18a5697fa52012e9c27e45afe0fc70aaa03626009 ./lib/vmodal_sdk_flutter.dart
72fff91181fd3e25fd9afd766930a67025205b61096fd35c55cbdd9a3178ecf0 ./pubspec.lock
2b969fbd1d82d89a5dc7822032ce9fe0df4bda625da969bc8e93c57e43fcf2c2 ./pubspec.yaml
a80b38547f5d9ca1874f60e71c648e3fc12ab5f7cb88d1bead6d5b863d3c0245 ./readme_assets/dev_homepage.jpg
@@ -103,17 +104,18 @@ d31d6bb36542a9022c62d2d9940b0efd07f60b1cdfb30e35f8be8b15a226c843 ./run.sh
be59599b9ba77d031e9b4bad7f8d5c59efd2687888c5b73be4fbea115902106b ./test/adaptive_upload_test.dart
002abcc5d95c0cf20375adefe4ee2472581a615e64f5726bf361dd5c679cdea7 ./test/auth_http_test.dart
ba941377f1ee717091dd30522609d028f32cd60df575564c75ab0228c2543d35 ./test/config_routes_test.dart
+40d6dacb3d168bd095586568df443b3dc8b31896a85b549799983af4dc09a366 ./test/docs_reference_test.dart
b1d3b70a6c9ecde707a9f139a3e7c5a2b4db808e9746db6ac6195c2205c9522e ./test/fakes.dart
0a1394c90829b91541aa01e9786e3195aae04fc49a7b92775dbf404bf2802107 ./test/fakes_test.dart
14368b598ece0ce9b2e249148a10a92f2c80e38427c077013a1515826f4365bd ./test/fixtures/routes_contract.json
fd2bad0ad87fbf2f15f7e9845b830db58408bb4c502c6ff105f39e4e7cce1905 ./test/multipart_upload_test.dart
-99d0c5cd5829e26f1784df9cc931752f343d8b9220f4879a2703895a3578afcb ./test/regression_manifest_test.dart
+eb72ddf861f09a8898442358138534d56fcd0266d5a2fddae51e2722dfaeaa47 ./test/regression_manifest_test.dart
ec2d3ab09457fdccf30fc338585b89cf466f5d8f7fc8ce5f6c0ae52357390277 ./test/resources_models_test.dart
f7e75763ceec4bfba6f116fff23efd357a7a7ee9f141237443cf42c2300268d9 ./test/shell_scripts_test.dart
79e3de3c03451cd9d62327430106edf861da6aeb97b546bbac2d93a0bcbbe3d3 ./test/transport_test.dart
c13557f89597f0be73f48dc8463aa7513e9e814c0e6a0ab871e441834687abb1 ./test/upload_test.dart
-9319eaabf033436eb893fa65017784eb456245036e67996dd1d01f21b1d65aac ./test/workflow_layout_test.dart
+5781ecdda41052a0a68b3d5a2f6a976a47f20cedd01b708e33f9af758bccbd6d ./test/workflow_layout_test.dart
406de1350b79662fcaf007cb0cacd7a6b71b83815dc7cd3c7b561fcfba5600a3 ./tool/check_route_sync.dart
d5f5f9246656a5c275c5ab5863dbf3945d8ef6b1c9042c9d1912cfafce93646f ./tool/flutter_checksums.txt
d09e2ee68e0e238b86e54a8248a0da92db81c953ce691628708bffd63fa3e737 ./tool/live_test.dart
-f753a50df460c24d80c5c27d9f41f9fe0e9b389641515d44bf66be2d604261bd ./tool/release_manifest.dart
+7b1e5574aaf77db0de5a52fd87809ce3b10389e16d2e83c9f7816964e6da689f ./tool/release_manifest.dart
diff --git a/dartdoc_options.yaml b/dartdoc_options.yaml
new file mode 100644
index 0000000..ab333b8
--- /dev/null
+++ b/dartdoc_options.yaml
@@ -0,0 +1,10 @@
+dartdoc:
+ include:
+ - vmodal_sdk_flutter
+ nodoc:
+ - lib/src/http.dart
+ - lib/src/routes.dart
+ errors:
+ - ambiguous-doc-reference
+ - broken-link
+ - unresolved-doc-reference
diff --git a/doc/release.md b/doc/release.md
index c7e9b2b..733cb81 100644
--- a/doc/release.md
+++ b/doc/release.md
@@ -15,14 +15,19 @@ are also disabled during this development mode. Optional pub.dev publication is
triggered only by the exported version tag and uses OIDC trusted publishing; no
long-lived pub token is stored.
-After the tested SDK source is published, the same workflow regenerates
-`docs_swagger`, validates its OpenAPI contract, and publishes the immutable site
-artifact to the `gh-pages` branch of the existing public repository
-`v-modal/vmodal_sdk_flutter`. The workflow pushes that branch directly, without
-opening a pull request, and configures GitHub Pages for branch-based (`legacy`)
-publishing. It verifies the recorded `GITHUB_SHA` at
-`https://v-modal.github.io/vmodal_sdk_flutter/`. The deployment depends on both
-the source publication and the current no-op secret-detection job.
+After the tested SDK source is published, the same workflow installs the pinned
+Flutter toolchain, regenerates `docs_sdk` from the public Dart library, and
+publishes the immutable class/method reference to the `gh-pages` branch of the
+existing public repository `v-modal/vmodal_sdk_flutter`. Generation removes
+only Dartdoc Implementation sections, validates required public symbols, and
+fails when backend hosts, route prefixes, or implementation-only types appear.
+The workflow pushes that branch directly, without opening a pull request, and
+configures GitHub Pages for branch-based (`legacy`) publishing. It verifies the
+recorded `GITHUB_SHA` at `https://v-modal.github.io/vmodal_sdk_flutter/`. The
+deployment depends on both source publication and the current no-op
+secret-detection job. The private monorepo maintainer handbook owns the local
+generation commands because the generator is intentionally absent from the
+standalone public package.
Multipart is excluded from production live claims until all five backend routes
are verified. A failed publication is fixed forward with a new version after the
diff --git a/doc/sdk_doc.md b/doc/sdk_doc.md
index d805d2f..c26ab73 100644
--- a/doc/sdk_doc.md
+++ b/doc/sdk_doc.md
@@ -1,5 +1,13 @@
# SDK guide
+The generated class and method reference is published at
+`https://v-modal.github.io/vmodal_sdk_flutter/` and is built from the public
+Dart declarations in `lib/vmodal_sdk_flutter.dart`. The monorepo release
+pipeline builds the Pages artifact in `docs_sdk/`; that generated tree is not
+part of the standalone package. Backend hosts, wire paths, and implementation
+bodies are intentionally excluded; mobile applications should use the typed
+resources described there.
+
Construct `VmodalClient` with an explicit `SdkConfig` and an app-owned
`ApiKeyProvider`. All ordinary operations are asynchronous. Gateway mode is the
default and sends only `Authorization: Bearer <key>` as caller identity.
@@ -20,4 +28,3 @@ and per-task cancellation. Multipart requires explicit opt-in and is experimenta
Flutter Web, login UI, key persistence, file picking, widget state management,
and background scheduling are outside the package. The first release supports
Flutter applications on Android and iOS.
-
diff --git a/lib/src/adaptive_upload.dart b/lib/src/adaptive_upload.dart
index e5ffeba..59e713c 100644
--- a/lib/src/adaptive_upload.dart
+++ b/lib/src/adaptive_upload.dart
@@ -2,13 +2,18 @@ import 'dart:math';
import 'errors.dart';
+/// Network family observed when choosing multipart settings.
enum UploadNetworkType { wifi, cellular, unknown }
+/// Approximate throughput category observed by the app.
enum UploadNetworkSpeed { slow, standard, fast, unknown }
+/// Memory capacity category supplied by the app.
enum UploadDeviceMemory { low, standard, high }
+/// Device and network conditions used by [AdaptiveUploadPolicy].
class UploadConditions {
+ /// Creates a conditions snapshot with conservative unknown-network defaults.
const UploadConditions({
this.networkType = UploadNetworkType.unknown,
this.networkSpeed = UploadNetworkSpeed.unknown,
@@ -20,7 +25,9 @@ class UploadConditions {
final UploadDeviceMemory deviceMemory;
}
+/// Resolved multipart settings for the current source and conditions.
class AdaptiveUploadPreset {
+ /// Creates an immutable preset.
const AdaptiveUploadPreset({
required this.name,
required this.partSizeBytes,
@@ -36,7 +43,11 @@ class AdaptiveUploadPreset {
final Duration partTimeout;
}
+/// Selects bounded multipart settings from source size and app observations.
abstract final class AdaptiveUploadPolicy {
+ /// Returns a deterministic preset for [sizeBytes] and [conditions].
+ ///
+ /// Throws [ValidationException] when [sizeBytes] is negative.
static AdaptiveUploadPreset select(
int sizeBytes,
UploadConditions conditions,
diff --git a/lib/src/api_key_provider.dart b/lib/src/api_key_provider.dart
index 1db8b4d..ac56b88 100644
--- a/lib/src/api_key_provider.dart
+++ b/lib/src/api_key_provider.dart
@@ -1,25 +1,38 @@
import 'errors.dart';
+/// Supplies the API key used immediately before each SDK request.
+///
+/// Implementations should return only an in-memory credential and throw
+/// [AuthException] when it is unavailable.
abstract interface class ApiKeyProvider {
+ /// Returns the current validated credential.
String current();
}
+/// In-memory credential provider supporting rotation and explicit clearing.
+///
+/// [close] permanently disables the provider. Values are redacted from
+/// [toString] and are never persisted by this class.
class MutableApiKeyProvider implements ApiKeyProvider {
+ /// Creates a provider after validating [initialKey].
MutableApiKeyProvider(String initialKey) : _key = strApiKey(initialKey);
String? _key;
bool _closed = false;
+ /// Replaces the active key, or throws [AuthException] after [close].
void rotate(String newKey) {
final valid = strApiKey(newKey);
if (_closed) throw const AuthException('API key is unavailable');
_key = valid;
}
+ /// Removes the current key without permanently closing the provider.
void clear() {
_key = null;
}
+ /// Clears the key and permanently disables [current] and [rotate].
void close() {
_closed = true;
clear();
@@ -38,6 +51,7 @@ class MutableApiKeyProvider implements ApiKeyProvider {
String toString() => 'MutableApiKeyProvider([REDACTED])';
}
+/// @nodoc
String strApiKey(String value) {
final key = value.trim();
if (key.isEmpty) throw const ValidationException('API key must not be blank');
diff --git a/lib/src/client.dart b/lib/src/client.dart
index 8221baa..ce47a77 100644
--- a/lib/src/client.dart
+++ b/lib/src/client.dart
@@ -6,9 +6,19 @@ import 'resources.dart';
import 'transport.dart';
import 'upload.dart';
+/// Version of the Dart SDK contract represented by this package.
const String vmodalSdkVersion = '1.0.0';
+/// Owns configuration, transports, and feature resources for one app session.
+///
+/// Reuse a client while the same identity is active. Call [close] when the
+/// identity changes or the app no longer needs the SDK; closing is idempotent.
class VmodalClient {
+ /// Creates a client from validated [config].
+ ///
+ /// Custom transports are primarily useful for testing and platform-specific
+ /// integrations. The client owns every supplied transport and closes it from
+ /// [close].
VmodalClient({
required this.config,
VmodalTransport? transport,
@@ -27,27 +37,62 @@ class VmodalClient {
images = ImagesResource(http);
}
+ /// Immutable configuration used by all resources.
final SdkConfig config;
+
+ /// Transport used for typed SDK operations.
final VmodalTransport transport;
+
+ /// Transport used after the SDK obtains permission to upload media bytes.
final SignedUploadTransport signedUploadTransport;
+
+ /// @nodoc
late final VmodalHttp http;
+
+ /// Authentication and identity operations.
late final AuthResource auth;
+
+ /// Multimodal search operations.
late final SearchesResource searches;
+
+ /// Collection management and upload operations.
late final CollectionsResource collections;
+
+ /// Index creation, status, and deletion operations.
late final IndexesResource indexes;
+
+ /// Usage and service-statistics operations.
late final AdminResource admin;
+
+ /// Advanced signed object-upload operations.
late final R2Resource r2;
+
+ /// Image lookup and download operations.
late final ImagesResource images;
+
+ /// Compatibility surface whose methods currently throw [FeatureDisabled].
final GDriveResource gdrive = GDriveResource();
+
+ /// Compatibility surface whose methods currently throw [FeatureDisabled].
final SqlResource sql = SqlResource();
bool _closed = false;
+ /// Checks service health and returns version/dependency information.
Future<HealthResponse> health({CancellationToken? cancellation}) =>
auth.health(cancellation: cancellation);
+ /// Returns `true` when an authenticated health request succeeds.
+ ///
+ /// Authentication, transport, and cancellation failures are surfaced as
+ /// typed [SdkException] subclasses.
Future<bool> authCheck({CancellationToken? cancellation}) =>
auth.authCheck(cancellation: cancellation);
+ /// Creates a client from the supported environment map.
+ ///
+ /// Unless [resolveIdentity] is false or a user ID is already configured, the
+ /// factory resolves the active profile and rebuilds the client with that
+ /// identity. A profile without a user ID throws [AuthException].
static Future<VmodalClient> fromEnvironment(
Map<String, String> env, {
VmodalTransport? transport,
@@ -83,6 +128,9 @@ class VmodalClient {
return client;
}
+ /// Creates a direct-mode client for controlled development integrations.
+ ///
+ /// Most mobile apps should use the default gateway configuration instead.
factory VmodalClient.unsafeDirect({
required String baseUrl,
required String userId,
@@ -111,6 +159,7 @@ class VmodalClient {
);
}
+ /// Closes both owned transports. Repeated calls have no effect.
Future<void> close() async {
if (_closed) return;
_closed = true;
diff --git a/lib/src/collection_uploads.dart b/lib/src/collection_uploads.dart
index b6f4255..319a3d7 100644
--- a/lib/src/collection_uploads.dart
+++ b/lib/src/collection_uploads.dart
@@ -13,7 +13,12 @@ import 'transport.dart';
import 'upload.dart';
import 'utils.dart';
+/// Controls signed and optional multipart video uploads.
+///
+/// Multipart mode is opt-in. When [adaptiveConditions] is supplied, the SDK
+/// derives bounded part and concurrency settings before validating the upload.
class VideoUploadOptions {
+ /// Creates upload options with single-upload behavior by default.
const VideoUploadOptions({
this.multipart = false,
this.multipartThresholdBytes = 100 * 1024 * 1024,
@@ -26,18 +31,37 @@ class VideoUploadOptions {
this.adaptiveConditions,
});
+ /// Enables experimental multipart upload behavior.
final bool multipart;
+
+ /// Source size at which callers may choose multipart behavior.
final int multipartThresholdBytes;
+
+ /// Requested bytes per multipart part.
final int partSizeBytes;
+
+ /// Maximum number of parts uploaded concurrently.
final int maxConcurrency;
+
+ /// Maximum attempts for one part.
final int maxPartAttempts;
+
+ /// Timeout applied to each part upload.
final Duration partTimeout;
+
+ /// Whether a compatible checkpoint can resume an earlier session.
final bool resume;
+
+ /// Optional checkpoint store; defaults to process-local memory.
final UploadSessionStore? sessionStore;
+
+ /// Optional device/network snapshot for adaptive preset selection.
final UploadConditions? adaptiveConditions;
+ /// Effective checkpoint store.
UploadSessionStore get store => sessionStore ?? UploadSessionStores.memory;
+ /// Returns options resolved for [size] using [adaptiveConditions].
VideoUploadOptions resolvedFor(int size) {
if (!multipart || adaptiveConditions == null) return this;
final preset = AdaptiveUploadPolicy.select(size, adaptiveConditions!);
@@ -49,6 +73,7 @@ class VideoUploadOptions {
);
}
+ /// Returns a copy with selected options replaced.
VideoUploadOptions copyWith({
bool? multipart,
int? multipartThresholdBytes,
@@ -72,6 +97,7 @@ class VideoUploadOptions {
adaptiveConditions: adaptiveConditions ?? this.adaptiveConditions,
);
+ /// Validates multipart constraints for a source of [size] bytes.
void validate(int size) {
if (!multipart) return;
if (partSizeBytes < 5 * 1024 * 1024) {
@@ -97,7 +123,12 @@ class VideoUploadOptions {
}
}
+/// Signed upload operations available on [CollectionsResource].
extension CollectionUploads on CollectionsResource {
+ /// Starts one video upload and returns immediately with an [UploadTask].
+ ///
+ /// Listen to [UploadTask.progress], await [UploadTask.result], or call
+ /// [UploadTask.cancel]. Multipart behavior is enabled only through [options].
UploadTask<VideoUploadResponse> videoUpload(
UploadSource source, {
required String collectionName,
@@ -125,6 +156,10 @@ extension CollectionUploads on CollectionsResource {
);
}
+ /// Starts an ordered bulk upload with aggregate progress.
+ ///
+ /// The result keeps input order. The first failure cancels remaining work
+ /// and completes [UploadTask.result] with that error.
UploadTask<VideoUploadBulkResponse> videoUploadBulk(
List<UploadSource> sources, {
required String collectionName,
diff --git a/lib/src/config.dart b/lib/src/config.dart
index 3a5c2f3..e2a8215 100644
--- a/lib/src/config.dart
+++ b/lib/src/config.dart
@@ -3,12 +3,23 @@ import 'dart:convert';
import 'api_key_provider.dart';
import 'errors.dart';
+/// @nodoc
const String publicGatewayUrlHash =
'aHR0cHM6Ly9zZWFyY2hhcGktdGVzdC52LW1vZGFsLmNvbQ==';
+
+/// @nodoc
final String publicGatewayUrl = utf8.decode(base64Decode(publicGatewayUrlHash));
+
+/// @nodoc
const String devGatewayUrl = 'http://127.0.0.1:3099';
+/// Immutable client configuration and credential-provider binding.
+///
+/// The constructor validates timeout, retry, mode, and base-address values.
+/// Supply either [token] or an [apiKeyProvider]; a provider is preferred when
+/// credentials can rotate during a mobile session.
class SdkConfig {
+ /// Creates and validates configuration with mobile-safe defaults.
SdkConfig({
String? baseUrl,
this.userId = '',
@@ -32,14 +43,31 @@ class SdkConfig {
_validateBase(normalizedBaseUrl);
}
+ /// Configured service origin. It is normalized internally before use.
final String baseUrl;
+
+ /// Optional known user identifier.
final String userId;
+
+ /// Optional tenant identifier supplied with direct integrations.
final String tenantId;
+
+ /// Optional user email supplied with direct integrations.
final String email;
+
+ /// Static API key used when [apiKeyProvider] is absent.
final String token;
+
+ /// Maximum duration for an SDK request.
final Duration timeout;
+
+ /// Connection mode, either `gateway` or `direct`.
final String mode;
+
+ /// Number of retries allowed for retryable SDK operations.
final int maxRetries;
+
+ /// Optional rotating credential source.
final ApiKeyProvider? apiKeyProvider;
String get normalizedMode {
@@ -53,11 +81,13 @@ class SdkConfig {
String get normalizedEmail => email.trim();
int get normalizedMaxRetries => maxRetries;
+ /// Returns the current validated API key without storing provider output.
String currentApiKey() {
final value = apiKeyProvider?.current() ?? token;
return value.trim().isEmpty ? '' : strApiKey(value);
}
+ /// Returns a new validated configuration with selected values replaced.
SdkConfig copyWith({
String? baseUrl,
String? userId,
@@ -80,6 +110,10 @@ class SdkConfig {
apiKeyProvider: apiKeyProvider ?? this.apiKeyProvider,
);
+ /// Builds configuration from the supported environment keys and overrides.
+ ///
+ /// A missing credential throws [ValidationException] unless
+ /// [apiKeyProvider] is supplied.
factory SdkConfig.fromEnvironment(
Map<String, String> env, {
String? baseUrl,
@@ -148,6 +182,7 @@ class SdkConfig {
'apiKeyProviderConfigured=${apiKeyProvider != null})';
}
+/// @nodoc
String strGatewayBaseUrl(String baseUrl, [String mode = '']) {
final base = baseUrl.trim().replaceFirst(RegExp(r'/+$'), '');
if (base.isEmpty || mode.trim().toLowerCase() != 'gateway') return base;
@@ -155,6 +190,7 @@ String strGatewayBaseUrl(String baseUrl, [String mode = '']) {
return base.endsWith(suffix) ? base : '$base$suffix';
}
+/// @nodoc
String strUsersBaseUrl(String baseUrl) {
final base = baseUrl.trim().replaceFirst(RegExp(r'/+$'), '');
const suffix = '/api/v1/proxy/search_api';
diff --git a/lib/src/errors.dart b/lib/src/errors.dart
index 997058c..962308e 100644
--- a/lib/src/errors.dart
+++ b/lib/src/errors.dart
@@ -1,4 +1,6 @@
+/// Base class for failures intentionally surfaced by the SDK.
class SdkException implements Exception {
+ /// Creates an immutable typed failure.
const SdkException(
this.message, {
this.statusCode = 0,
@@ -6,9 +8,16 @@ class SdkException implements Exception {
this.details,
});
+ /// Human-readable summary safe to show in diagnostic UI.
final String message;
+
+ /// Service status when available, otherwise zero.
final int statusCode;
+
+ /// Optional structured or textual response body.
final Object? body;
+
+ /// Optional local diagnostic details or cause.
final Object? details;
@override
@@ -18,6 +27,7 @@ class SdkException implements Exception {
}
}
+/// Credential or identity-resolution failure.
class AuthException extends SdkException {
const AuthException(
super.message, {
@@ -27,6 +37,7 @@ class AuthException extends SdkException {
});
}
+/// Valid service response that represents an unsuccessful operation.
class ApiException extends SdkException {
const ApiException(
super.message, {
@@ -36,6 +47,7 @@ class ApiException extends SdkException {
});
}
+/// Invalid caller input detected before or while preparing an operation.
class ValidationException extends SdkException {
const ValidationException(
super.message, {
@@ -45,15 +57,18 @@ class ValidationException extends SdkException {
});
}
+/// Compatibility method that is intentionally unavailable.
class FeatureDisabled extends SdkException {
const FeatureDisabled(super.message);
}
+/// Connectivity, timeout, stream, or lower-level transport failure.
class TransportException extends SdkException {
const TransportException([Object? cause])
: super('transport error', details: cause);
}
+/// Response or checkpoint exceeded an SDK safety limit.
class ResponseTooLarge extends SdkException {
const ResponseTooLarge(this.limitBytes, this.observedBytes)
: super('response exceeds the configured limit');
@@ -62,10 +77,12 @@ class ResponseTooLarge extends SdkException {
final int observedBytes;
}
+/// Structured response could not be decoded into the documented contract.
class MalformedResponse extends SdkException {
const MalformedResponse([super.message = 'malformed JSON response']);
}
+/// Operation stopped because its [CancellationToken] was canceled.
class OperationCanceled extends SdkException {
const OperationCanceled() : super('operation canceled');
}
diff --git a/lib/src/models.dart b/lib/src/models.dart
index 730f26c..95de986 100644
--- a/lib/src/models.dart
+++ b/lib/src/models.dart
@@ -1,16 +1,21 @@
import 'errors.dart';
import 'utils.dart';
+/// Base response retaining unmodeled service fields in [raw].
class JsonBackedResponse {
+ /// Creates a response backed by [raw].
const JsonBackedResponse([this.raw = const <String, Object?>{}]);
+ /// Complete decoded response, including extension fields unknown to the SDK.
final Map<String, Object?> raw;
}
+/// One untyped search result with forward-compatible [raw] data.
class SearchResultItem extends JsonBackedResponse {
const SearchResultItem(super.raw);
}
+/// Typed summary of one collection group.
class GroupItem extends JsonBackedResponse {
GroupItem(super.raw)
: userId = '${raw['user_id'] ?? ''}',
@@ -29,6 +34,7 @@ class GroupItem extends JsonBackedResponse {
final List<String> lancedbVersions;
final String? lastUpdated;
+ /// Highest numeric `vN` value in [lancedbVersions], when present.
int? get latestLancedbVersion {
int? latest;
for (final value in lancedbVersions) {
@@ -45,23 +51,32 @@ class GroupItem extends JsonBackedResponse {
}
}
+/// One item returned by a folder-upload operation.
class FolderUploadItem extends JsonBackedResponse {
const FolderUploadItem(super.raw);
}
+/// One asset associated with a collection.
class CollectionAsset extends JsonBackedResponse {
const CollectionAsset(super.raw);
}
+/// One indexation job with forward-compatible [raw] data.
class IndexationJobItem extends JsonBackedResponse {
const IndexationJobItem(super.raw);
}
+/// One user-statistics row with forward-compatible [raw] data.
class AdminUserStatItem extends JsonBackedResponse {
const AdminUserStatItem(super.raw);
}
+/// Parameters for a multimodal media search.
+///
+/// At least one of [queryText] or [imageQuery] must be nonblank. Defaults
+/// search common speech, visible-text, and image sources with union semantics.
class SearchRequest {
+ /// Creates a search request with mobile-oriented defaults.
const SearchRequest({
this.queryText = '',
this.queryMetadata,
@@ -96,12 +111,14 @@ class SearchRequest {
final double imageEmbScoreMin;
final int? versionLancedb;
+ /// Validates the required query input.
void validate() {
if (queryText.trim().isEmpty && (imageQuery?.trim().isEmpty ?? true)) {
throw const ValidationException('query_text or image_query is required');
}
}
+ /// Converts this request to its structured transport representation.
Map<String, Object?> toJson() => _withoutNull(<String, Object?>{
'query_text': queryText,
'query_metadata': queryMetadata,
@@ -121,7 +138,9 @@ class SearchRequest {
});
}
+/// Parameters for previewing or confirming collection deletion.
class DeleteCollectionRequest {
+ /// Creates a deletion request. [dryRun] and [confirm] default to `false`.
const DeleteCollectionRequest({
required this.groupName,
required this.mode,
@@ -136,11 +155,13 @@ class DeleteCollectionRequest {
final bool dryRun;
final bool confirm;
+ /// Validates required collection identifiers.
void validate() {
strRequired(groupName, 'group_name');
strRequired(mode, 'mode');
}
+ /// Converts this request to its structured transport representation.
Map<String, Object?> toJson() => <String, Object?>{
'group_name': groupName,
'mode': mode,
@@ -150,7 +171,9 @@ class DeleteCollectionRequest {
};
}
+/// Parameters for associating existing assets with a collection.
class CollectionAddAssetsRequest {
+ /// Creates an add-assets request.
const CollectionAddAssetsRequest({
required this.collectionId,
required this.assetIds,
@@ -165,6 +188,7 @@ class CollectionAddAssetsRequest {
final String groupName;
final String streamName;
+ /// Validates identifiers and requires at least one asset.
void validate() {
strRequired(collectionId, 'collection_id');
if (assetIds.isEmpty) {
@@ -174,6 +198,7 @@ class CollectionAddAssetsRequest {
strRequired(groupName, 'group_name');
}
+ /// Converts this request to its structured transport representation.
Map<String, Object?> toJson() => <String, Object?>{
'collection_id': collectionId,
'asset_ids': assetIds,
@@ -183,7 +208,9 @@ class CollectionAddAssetsRequest {
};
}
+/// Parameters for creating an indexation job.
class IndexationSubmitRequest {
+ /// Creates an indexation request with append and index-creation defaults.
const IndexationSubmitRequest({
required this.mode,
required this.groupName,
@@ -214,11 +241,13 @@ class IndexationSubmitRequest {
final bool reProcess;
final bool dryRun;
+ /// Validates required collection identifiers.
void validate() {
strRequired(mode, 'mode');
strRequired(groupName, 'group_name');
}
+ /// Converts this request to its structured transport representation.
Map<String, Object?> toJson() => _withoutNull(<String, Object?>{
'mode': mode,
'group_name': groupName,
@@ -236,7 +265,9 @@ class IndexationSubmitRequest {
});
}
+/// Parameters for previewing or confirming index deletion.
class IndexationDeleteRequest {
+ /// Creates an index deletion request.
const IndexationDeleteRequest({
required this.mode,
required this.groupName,
@@ -253,12 +284,14 @@ class IndexationDeleteRequest {
final bool dryRun;
final bool confirm;
+ /// Validates the required collection and version identifiers.
void validate() {
strRequired(mode, 'mode');
strRequired(groupName, 'group_name');
strRequired(version, 'version');
}
+ /// Converts this request to its structured transport representation.
Map<String, Object?> toJson() => _withoutNull(<String, Object?>{
'mode': mode,
'group_name': groupName,
@@ -269,7 +302,9 @@ class IndexationDeleteRequest {
});
}
+/// Stored-image selector used by image lookup helpers.
class ImageRecord {
+ /// Creates an image selector.
const ImageRecord({
this.mode = '',
this.groupName = '',
@@ -286,6 +321,9 @@ class ImageRecord {
final String frameId;
final String? userid;
+ /// Converts this selector to structured data.
+ ///
+ /// Set [includeIdentity] to `false` outside trusted direct integrations.
Map<String, Object?> toJson({bool includeIdentity = true}) =>
_withoutNull(<String, Object?>{
'mode': mode,
@@ -297,7 +335,9 @@ class ImageRecord {
});
}
+/// Stored-image selector for temporary URL lookup.
class ImageUrlRecord {
+ /// Creates an image URL selector.
const ImageUrlRecord({
this.mode = '',
this.groupName = '',
@@ -314,6 +354,7 @@ class ImageUrlRecord {
final String filename;
final String? tsUnix13digits;
+ /// Converts this selector to structured data.
Map<String, Object?> toJson() => _withoutNull(<String, Object?>{
'mode': mode,
'group_name': groupName,
@@ -324,6 +365,7 @@ class ImageUrlRecord {
});
}
+/// Service health, version, and dependency summary.
class HealthResponse extends JsonBackedResponse {
HealthResponse(super.raw)
: status = '${raw['status'] ?? ''}',
@@ -339,6 +381,7 @@ class HealthResponse extends JsonBackedResponse {
final Object? dependencies;
}
+/// Search results, counts, and execution timing.
class SearchResponse extends JsonBackedResponse {
SearchResponse(super.raw)
: data = raw['data'] is List
@@ -354,6 +397,7 @@ class SearchResponse extends JsonBackedResponse {
final double executionTimeMs;
}
+/// Typed collection-group listing.
class GroupsResponse extends JsonBackedResponse {
GroupsResponse(super.raw)
: data = objectList(raw['data']).map(GroupItem.new).toList(),
@@ -364,6 +408,7 @@ class GroupsResponse extends JsonBackedResponse {
final int total;
final double executionTimeMs;
+ /// Finds a group by trimmed name and optional mode.
GroupItem? findGroup(String groupName, {String? mode}) {
final name = groupName.trim();
for (final item in data) {
@@ -376,6 +421,7 @@ class GroupsResponse extends JsonBackedResponse {
}
}
+/// Temporary upload grant returned for a signed upload.
class ExternalUploadSignedUrlResponse extends JsonBackedResponse {
ExternalUploadSignedUrlResponse(super.raw)
: userId = '${raw['user_id'] ?? ''}',
@@ -391,6 +437,7 @@ class ExternalUploadSignedUrlResponse extends JsonBackedResponse {
final String method;
}
+/// Uploaded multipart part summary.
class MultipartPart extends JsonBackedResponse {
MultipartPart(super.raw)
: partNumber = intValue(raw['part_number']),
@@ -402,6 +449,7 @@ class MultipartPart extends JsonBackedResponse {
final int sizeBytes;
}
+/// Temporary upload grant for one multipart part.
class MultipartSignedPart extends JsonBackedResponse {
MultipartSignedPart(super.raw)
: partNumber = intValue(raw['part_number']),
@@ -417,6 +465,7 @@ class MultipartSignedPart extends JsonBackedResponse {
final Map<String, String> headers;
}
+/// Newly created multipart session and its resolved limits.
class MultipartCreateResponse extends JsonBackedResponse {
MultipartCreateResponse(super.raw)
: requestId = '${raw['request_id'] ?? ''}',
@@ -436,6 +485,7 @@ class MultipartCreateResponse extends JsonBackedResponse {
final String status;
}
+/// Temporary grants for a requested set of multipart parts.
class MultipartSignResponse extends JsonBackedResponse {
MultipartSignResponse(super.raw)
: parts = objectList(raw['parts']).map(MultipartSignedPart.new).toList(),
@@ -445,6 +495,7 @@ class MultipartSignResponse extends JsonBackedResponse {
final int expiresIn;
}
+/// Current multipart session status and accepted parts.
class MultipartStatusResponse extends JsonBackedResponse {
MultipartStatusResponse(super.raw)
: status = '${raw['status'] ?? 'uploading'}',
@@ -458,6 +509,7 @@ class MultipartStatusResponse extends JsonBackedResponse {
final int sizeBytes;
}
+/// Completed multipart object metadata.
class MultipartCompleteResponse extends JsonBackedResponse {
MultipartCompleteResponse(super.raw)
: status = '${raw['status'] ?? 'completed'}',
@@ -473,10 +525,12 @@ class MultipartCompleteResponse extends JsonBackedResponse {
final bool alreadyCompleted;
}
+/// Result of a basic collection upload.
class UploadResponse extends JsonBackedResponse {
const UploadResponse(super.raw);
}
+/// Detailed result of one signed video upload.
class VideoUploadResponse extends JsonBackedResponse {
VideoUploadResponse(super.raw)
: userId = '${raw['user_id'] ?? ''}',
@@ -516,6 +570,7 @@ class VideoUploadResponse extends JsonBackedResponse {
final String destPath;
}
+/// Ordered results for a bulk signed upload.
class VideoUploadBulkResponse extends JsonBackedResponse {
VideoUploadBulkResponse(super.raw)
: data = objectList(raw['data']).map(VideoUploadResponse.new).toList(),
@@ -525,26 +580,32 @@ class VideoUploadBulkResponse extends JsonBackedResponse {
final int total;
}
+/// Folder-upload compatibility response.
class FolderUploadResponse extends JsonBackedResponse {
const FolderUploadResponse(super.raw);
}
+/// Result of a metadata JSON Lines upload.
class MetadataParquetUploadResponse extends JsonBackedResponse {
const MetadataParquetUploadResponse(super.raw);
}
+/// Result of updating collection-item metadata.
class CollectionDescriptionUpdateResponse extends JsonBackedResponse {
const CollectionDescriptionUpdateResponse(super.raw);
}
+/// Result or preview of collection deletion.
class DeleteCollectionResponse extends JsonBackedResponse {
const DeleteCollectionResponse(super.raw);
}
+/// Result of associating assets with a collection.
class CollectionAddAssetsResponse extends JsonBackedResponse {
const CollectionAddAssetsResponse(super.raw);
}
+/// Indexation job rows and total count.
class IndexationJobsListResponse extends JsonBackedResponse {
IndexationJobsListResponse(super.raw)
: data = raw['data'] is List
@@ -556,6 +617,7 @@ class IndexationJobsListResponse extends JsonBackedResponse {
final int total;
}
+/// Identifier and initial state of a new indexation job.
class IndexationSubmitResponse extends JsonBackedResponse {
IndexationSubmitResponse(super.raw)
: jobId = '${raw['job_id'] ?? ''}',
@@ -565,6 +627,7 @@ class IndexationSubmitResponse extends JsonBackedResponse {
final String status;
}
+/// Identifier and current state of an indexation job.
class IndexationStatusResponse extends JsonBackedResponse {
IndexationStatusResponse(super.raw)
: jobId = '${raw['job_id'] ?? ''}',
@@ -574,12 +637,14 @@ class IndexationStatusResponse extends JsonBackedResponse {
final String status;
}
+/// Result of deleting index data.
class IndexationDeleteResponse extends JsonBackedResponse {
IndexationDeleteResponse(super.raw) : status = '${raw['status'] ?? ''}';
final String status;
}
+/// User-statistics rows and total count.
class AdminUserStatsResponse extends JsonBackedResponse {
AdminUserStatsResponse(super.raw)
: data = raw['data'] is List
@@ -591,6 +656,7 @@ class AdminUserStatsResponse extends JsonBackedResponse {
final int total;
}
+/// Identity and permissions resolved for the current credential.
class UserProfile extends JsonBackedResponse {
UserProfile(super.raw)
: userId = raw['user_id']?.toString(),
@@ -616,6 +682,7 @@ class UserProfile extends JsonBackedResponse {
final String type;
}
+/// Usage totals grouped by operation for one date.
class UsageUserDetail extends JsonBackedResponse {
UsageUserDetail(super.raw)
: date = '${raw['date'] ?? ''}',
@@ -631,6 +698,7 @@ class UsageUserDetail extends JsonBackedResponse {
final Map<String, int> endpoints;
}
+/// Cache, limiter, and related service configuration counters.
class CacheStats extends JsonBackedResponse {
CacheStats(super.raw)
: apikeyCacheSize = intValue(raw['apikey_cache_size']),
@@ -642,6 +710,7 @@ class CacheStats extends JsonBackedResponse {
final Map<String, Object?> config;
}
+/// Temporary object-upload grant for one file.
class PresignedUploadResponse extends JsonBackedResponse {
PresignedUploadResponse(super.raw)
: userId = '${raw['user_id'] ?? ''}',
@@ -657,6 +726,7 @@ class PresignedUploadResponse extends JsonBackedResponse {
final String method;
}
+/// One file and its temporary object-upload grant.
class PresignedFolderItem extends JsonBackedResponse {
PresignedFolderItem(super.raw)
: filename = '${raw['filename'] ?? ''}',
@@ -670,6 +740,7 @@ class PresignedFolderItem extends JsonBackedResponse {
final String method;
}
+/// Batch of temporary object-upload grants.
class PresignedFolderResponse extends JsonBackedResponse {
PresignedFolderResponse(super.raw)
: userId = '${raw['user_id'] ?? ''}',
@@ -681,6 +752,7 @@ class PresignedFolderResponse extends JsonBackedResponse {
final List<PresignedFolderItem> files;
}
+/// Temporary image location and lookup status.
class ImageUrlResponse extends JsonBackedResponse {
ImageUrlResponse(super.raw)
: found = raw['found'] == true,
@@ -696,18 +768,21 @@ class ImageUrlResponse extends JsonBackedResponse {
final String error;
}
+/// Raw per-record results for bulk image URL lookup.
class ImageUrlBulkResponse extends JsonBackedResponse {
ImageUrlBulkResponse(super.raw) : records = objectList(raw['records']);
final List<Map<String, Object?>> records;
}
+/// Raw per-record results for bulk image download.
class ImageGetBulkResponse extends JsonBackedResponse {
ImageGetBulkResponse(super.raw) : records = objectList(raw['records']);
final List<Map<String, Object?>> records;
}
+/// Base64-encoded image result.
class ImageResponse extends JsonBackedResponse {
ImageResponse(super.raw)
: found = raw['found'] == true,
@@ -717,6 +792,7 @@ class ImageResponse extends JsonBackedResponse {
final String imgBase64;
}
+/// Base64-encoded image result with its stored path.
class FullPathImageResponse extends JsonBackedResponse {
FullPathImageResponse(super.raw)
: found = raw['found'] == true,
@@ -728,6 +804,7 @@ class FullPathImageResponse extends JsonBackedResponse {
final String fullpath;
}
+/// Raw per-record base64 image results.
class ImageBulkResponse extends JsonBackedResponse {
ImageBulkResponse(super.raw) : records = objectList(raw['records']);
diff --git a/lib/src/resources.dart b/lib/src/resources.dart
index 494f6c7..5e76df5 100644
--- a/lib/src/resources.dart
+++ b/lib/src/resources.dart
@@ -8,11 +8,15 @@ import 'transport.dart';
import 'upload.dart';
import 'utils.dart';
+/// Authentication, identity, and service-health operations.
class AuthResource {
+ /// @nodoc
AuthResource(this.http);
+ /// @nodoc
final VmodalHttp http;
+ /// Returns service health metadata.
Future<HealthResponse> health({CancellationToken? cancellation}) async =>
HealthResponse(
await http.request(
@@ -22,11 +26,13 @@ class AuthResource {
),
);
+ /// Returns `true` when the authenticated health check completes.
Future<bool> authCheck({CancellationToken? cancellation}) async {
await health(cancellation: cancellation);
return true;
}
+ /// Resolves the profile associated with the current API key.
Future<UserProfile> me({CancellationToken? cancellation}) async =>
UserProfile(
await http.requestUsers(
@@ -37,11 +43,18 @@ class AuthResource {
);
}
+/// Multimodal media-search operations.
class SearchesResource {
+ /// @nodoc
SearchesResource(this.http);
+ /// @nodoc
final VmodalHttp http;
+ /// Validates [request] and returns matching media results.
+ ///
+ /// Use [CancellationToken.cancel] when the owning screen is disposed or a
+ /// newer query supersedes this one.
Future<SearchResponse> searchVideo(
SearchRequest request, {
CancellationToken? cancellation,
@@ -58,12 +71,18 @@ class SearchesResource {
}
}
+/// Collection discovery, mutation, and media-upload operations.
class CollectionsResource {
+ /// @nodoc
CollectionsResource(this.http, this.signedUploads);
+ /// @nodoc
final VmodalHttp http;
+
+ /// @nodoc
final SignedUploadTransport signedUploads;
+ /// Lists collections, optionally filtered by [mode].
Future<GroupsResponse> listGroups({
String? mode,
CancellationToken? cancellation,
@@ -76,6 +95,10 @@ class CollectionsResource {
),
);
+ /// Uploads a small file as one SDK request.
+ ///
+ /// Prefer [CollectionUploads.videoUpload] for signed uploads with progress
+ /// and cancellation.
Future<UploadResponse> uploadFile(
VmodalFilePart part, {
String groupName = '',
@@ -100,10 +123,12 @@ class CollectionsResource {
),
);
+ /// Always throws [FeatureDisabled] before any transport call.
Never uploadFolder() => throw const FeatureDisabled(
'folder upload is disabled on server (cannot scan remote PC/laptop)',
);
+ /// Uploads JSON Lines metadata and returns the accepted metadata result.
Future<MetadataParquetUploadResponse> uploadMetadataJsonl(
VmodalFilePart part, {
String mode = 'img_file',
@@ -144,6 +169,7 @@ class CollectionsResource {
return MetadataParquetUploadResponse(raw);
}
+ /// Adds existing [assetIds] to a collection after local validation.
Future<CollectionAddAssetsResponse> addAssets({
required String collectionId,
required List<String> assetIds,
@@ -174,6 +200,7 @@ class CollectionsResource {
);
}
+ /// Updates the description and/or tags for one collection item.
Future<CollectionDescriptionUpdateResponse> updateDescription({
required String groupName,
required String mode,
@@ -198,6 +225,10 @@ class CollectionsResource {
),
);
+ /// Deletes collection data according to [scope].
+ ///
+ /// Use [dryRun] to inspect the operation before setting [confirm] for a
+ /// destructive deletion.
Future<DeleteCollectionResponse> delete({
required String groupName,
required String mode,
@@ -224,25 +255,38 @@ class CollectionsResource {
);
}
+ /// Always throws [FeatureDisabled]; uploads create collections implicitly.
Never create() => throw const FeatureDisabled(
'no server endpoint; upload creates collection implicitly',
);
+
+ /// Always throws [FeatureDisabled]; collection editing is not available.
Never edit() => throw const FeatureDisabled(
'no server endpoint; upload creates collection implicitly',
);
+
+ /// Always throws [FeatureDisabled] before any transport call.
Never autoIndexGet() => throw const FeatureDisabled(
'collection auto_index is disabled on server',
);
+
+ /// Always throws [FeatureDisabled] before any transport call.
Never autoIndexSet() => throw const FeatureDisabled(
'collection auto_index is disabled on server',
);
}
+/// Index lifecycle operations for searchable collections.
class IndexesResource {
+ /// @nodoc
IndexesResource(this.http);
+ /// @nodoc
final VmodalHttp http;
+ /// Lists index jobs with optional filters.
+ ///
+ /// [limit] must be between 1 and 1000.
Future<IndexationJobsListResponse> jobsList({
String? status,
String? mode,
@@ -268,6 +312,7 @@ class IndexesResource {
);
}
+ /// Validates and starts an indexation job.
Future<IndexationSubmitResponse> createIndex(
IndexationSubmitRequest request, {
CancellationToken? cancellation,
@@ -283,6 +328,7 @@ class IndexesResource {
);
}
+ /// Returns the latest known state for [jobId].
Future<IndexationStatusResponse> indexStatus(
String jobId, {
CancellationToken? cancellation,
@@ -311,6 +357,7 @@ class IndexesResource {
}
}
+ /// Validates and deletes the selected index data.
Future<IndexationDeleteResponse> deleteIndex(
IndexationDeleteRequest request, {
CancellationToken? cancellation,
@@ -326,16 +373,21 @@ class IndexesResource {
);
}
+ /// Always throws [FeatureDisabled] before any transport call.
Never embeddingModels() => throw const FeatureDisabled(
'embedding models endpoint is disabled on server',
);
}
+/// Usage and operational-statistics queries for the active identity.
class AdminResource {
+ /// @nodoc
AdminResource(this.http);
+ /// @nodoc
final VmodalHttp http;
+ /// Returns user-level search statistics.
Future<AdminUserStatsResponse> userStats({
CancellationToken? cancellation,
}) async => AdminUserStatsResponse(
@@ -346,6 +398,7 @@ class AdminResource {
),
);
+ /// Returns usage for [date], or the service default period when blank.
Future<UsageUserDetail> usage({
String date = '',
CancellationToken? cancellation,
@@ -360,6 +413,7 @@ class AdminResource {
),
);
+ /// Returns current cache and limiter statistics.
Future<CacheStats> cacheStats({CancellationToken? cancellation}) async =>
CacheStats(
await http.requestUsers(
@@ -370,11 +424,15 @@ class AdminResource {
);
}
+/// Advanced signed object-upload preparation operations.
class R2Resource {
+ /// @nodoc
R2Resource(this.http);
+ /// @nodoc
final VmodalHttp http;
+ /// Creates a temporary upload grant for one file.
Future<PresignedUploadResponse> presignUploadFile({
required String mode,
required String groupName,
@@ -399,6 +457,7 @@ class R2Resource {
),
);
+ /// Creates temporary upload grants for all [filenames].
Future<PresignedFolderResponse> presignUploadFolderVideo({
required String mode,
required String groupName,
@@ -422,11 +481,15 @@ class R2Resource {
);
}
+/// Image-location and image-download operations.
class ImagesResource {
+ /// @nodoc
ImagesResource(this.http);
+ /// @nodoc
final VmodalHttp http;
+ /// Resolves a temporary URL for one stored image.
Future<ImageUrlResponse> getUrl({
required String mode,
required String groupName,
@@ -455,6 +518,9 @@ class ImagesResource {
),
);
+ /// Resolves image URLs for [records] in one call.
+ ///
+ /// Identity fields in records are ignored outside direct mode.
Future<ImageUrlBulkResponse> getUrlBulk(
List<Map<String, Object?>> records, {
String? userid,
@@ -484,6 +550,7 @@ class ImagesResource {
);
}
+ /// Downloads image bytes from a previously returned temporary URL.
Future<Uint8List> getImageFromUrl(
String urlPreSigned, {
String? userid,
@@ -500,6 +567,7 @@ class ImagesResource {
cancellation: cancellation,
);
+ /// Downloads several images represented by [urls].
Future<ImageGetBulkResponse> getImageBulkFromUrls(
List<String> urls, {
String? userid,
@@ -519,16 +587,22 @@ class ImagesResource {
);
}
+/// Disabled Google Drive compatibility surface.
class GDriveResource {
+ /// Always throws [FeatureDisabled] before any transport call.
Never privateAuthUrl() => throw const FeatureDisabled(
'private google drive auth endpoint is disabled on server',
);
+
+ /// Always throws [FeatureDisabled] before any transport call.
Never privateDownload() => throw const FeatureDisabled(
'private google drive download endpoint is disabled on server',
);
}
+/// Disabled SQL compatibility surface.
class SqlResource {
+ /// Always throws [FeatureDisabled] before any transport call.
Never query() =>
throw const FeatureDisabled('sql query endpoint is disabled on server');
}
diff --git a/lib/src/routes.dart b/lib/src/routes.dart
index a33d7a9..91fd34c 100644
--- a/lib/src/routes.dart
+++ b/lib/src/routes.dart
@@ -1,5 +1,6 @@
import 'errors.dart';
+/// @nodoc
enum RouteCategory {
active,
usersApi,
@@ -10,6 +11,7 @@ enum RouteCategory {
disabled,
}
+/// @nodoc
class RouteSpec {
const RouteSpec(
this.name,
@@ -26,6 +28,7 @@ class RouteSpec {
final String source;
}
+/// @nodoc
abstract final class Routes {
static const String prefix = '/api/external/v1';
static const String usersApiPrefix = '/api/v1';
diff --git a/lib/src/transport.dart b/lib/src/transport.dart
index b073061..bcac5ed 100644
--- a/lib/src/transport.dart
+++ b/lib/src/transport.dart
@@ -10,24 +10,41 @@ import 'config.dart';
import 'errors.dart';
import 'utils.dart';
-enum VmodalResponseMode { json, bytes }
+/// Expected response representation for a [VmodalRequest].
+enum VmodalResponseMode {
+ /// Decode a bounded structured response.
+ json,
+ /// Return bounded binary bytes.
+ bytes,
+}
+
+/// Cooperative cancellation signal shared with an in-flight operation.
class CancellationToken {
final Completer<void> _abort = Completer<void>();
+ /// Whether [cancel] has been called.
bool get isCanceled => _abort.isCompleted;
+
+ /// Completes once cancellation is requested.
Future<void> get whenCanceled => _abort.future;
+ /// Requests cancellation. Repeated calls have no effect.
void cancel() {
if (!_abort.isCompleted) _abort.complete();
}
+ /// Throws [OperationCanceled] after cancellation has been requested.
void throwIfCanceled() {
if (isCanceled) throw const OperationCanceled();
}
}
+/// Replayable file part used by multipart SDK operations.
class VmodalFilePart {
+ /// Creates a part backed by [opener].
+ ///
+ /// Names, content type, and non-negative [contentLength] are validated.
VmodalFilePart({
required this.fieldName,
required this.fileName,
@@ -43,6 +60,7 @@ class VmodalFilePart {
}
}
+ /// Creates a replayable part from an in-memory byte list.
factory VmodalFilePart.bytes({
required String fieldName,
required String fileName,
@@ -59,15 +77,26 @@ class VmodalFilePart {
);
}
+ /// Form field associated with the file.
final String fieldName;
+
+ /// File name reported to the service.
final String fileName;
+
+ /// Exact number of bytes produced by [open].
final int contentLength;
+
+ /// Media type for the part.
final String contentType;
final Stream<List<int>> Function() _opener;
+ /// Opens a fresh byte stream for this part.
Stream<List<int>> open() => _opener();
}
+/// Creates a replayable part from [file].
+///
+/// Throws [ValidationException] when the file does not exist.
VmodalFilePart filePart(String fieldName, File file, {String? contentType}) {
if (!file.existsSync()) {
throw const ValidationException('file must exist');
@@ -81,6 +110,7 @@ VmodalFilePart filePart(String fieldName, File file, {String? contentType}) {
);
}
+/// Creates a replayable part from a caller-provided stream factory.
VmodalFilePart streamPart({
required String fieldName,
required String fileName,
@@ -95,6 +125,7 @@ VmodalFilePart streamPart({
opener: opener,
);
+/// Infers a conservative media type from [name].
String guessContentType(String name) {
final ext = name.contains('.') ? name.split('.').last.toLowerCase() : '';
return switch (ext) {
@@ -107,7 +138,12 @@ String guessContentType(String name) {
};
}
+/// Transport-neutral request supplied to [VmodalTransport].
+///
+/// Applications normally use resource methods instead of constructing this
+/// type. Custom transport implementations can inspect its immutable fields.
class VmodalRequest {
+ /// Creates a request, assigning a fresh cancellation token when omitted.
VmodalRequest({
required this.method,
required this.uri,
@@ -140,7 +176,9 @@ class VmodalRequest {
'fileCount=${files.length})';
}
+/// Streaming transport response consumed by the SDK.
class VmodalResponse {
+ /// Creates a response with immutable status and metadata.
const VmodalResponse({
required this.statusCode,
required this.body,
@@ -160,9 +198,12 @@ class VmodalResponse {
'contentLength=$contentLength)';
}
+/// Pluggable request transport owned by [VmodalClient].
abstract interface class VmodalTransport {
+ /// Sends [request] and returns its streaming response.
Future<VmodalResponse> send(VmodalRequest request);
+ /// Releases transport resources. Implementations should be idempotent.
Future<void> close();
}
diff --git a/lib/src/upload.dart b/lib/src/upload.dart
index 3ecf7d7..678550a 100644
--- a/lib/src/upload.dart
+++ b/lib/src/upload.dart
@@ -9,7 +9,12 @@ import 'errors.dart';
import 'transport.dart';
import 'utils.dart';
+/// Replayable media source with a known byte length.
+///
+/// Multipart resume requires stable [sourceId] and [versionTag] values and a
+/// source that can reopen the requested ranges.
class UploadSource {
+ /// Creates a source from stream factories.
UploadSource({
required this.fileName,
required this.contentLength,
@@ -31,6 +36,7 @@ class UploadSource {
}
}
+ /// Creates a range-capable source from a local [file].
factory UploadSource.fromFile(File file, {String? contentType}) {
if (!file.existsSync()) {
throw const ValidationException('file must exist');
@@ -48,14 +54,27 @@ class UploadSource {
);
}
+ /// Name associated with the uploaded object.
final String fileName;
+
+ /// Exact source length in bytes.
final int contentLength;
+
+ /// Media type sent with the upload.
final String contentType;
+
+ /// Stable local identity used by resume checkpoints.
final String sourceId;
+
+ /// Version marker used to reject stale resume checkpoints.
final String versionTag;
final Stream<List<int>> Function() _opener;
final Stream<List<int>> Function(int offset)? _rangeOpener;
+ /// Opens a validated source range.
+ ///
+ /// Throws [ValidationException] for an invalid range and
+ /// [TransportException] if the source ends early.
Stream<List<int>> open({int offset = 0, int? length}) async* {
final wanted = length ?? contentLength - offset;
if (offset < 0 || wanted < 0 || offset + wanted > contentLength) {
@@ -89,25 +108,35 @@ class UploadSource {
}
}
+/// Monotonic upload progress snapshot.
class UploadProgress {
+ /// Creates a snapshot from uploaded and total byte counts.
const UploadProgress(this.uploadedBytes, this.totalBytes);
+ /// Bytes uploaded so far.
final int uploadedBytes;
+
+ /// Total bytes expected for the task.
final int totalBytes;
+ /// Integer percentage clamped to the inclusive range 0–100.
int get percent =>
totalBytes <= 0 ? 0 : ((uploadedBytes * 100) ~/ totalBytes).clamp(0, 100);
}
+/// Lifecycle state of an [UploadTask].
enum UploadTaskState { running, succeeded, failed, canceled }
+/// Work function used to create an [UploadTask].
typedef UploadRunner<T> =
Future<T> Function(
CancellationToken cancellation,
void Function(UploadProgress progress) emit,
);
+/// Running upload with result, progress, state, and cooperative cancellation.
class UploadTask<T> {
+ /// Starts [runner] immediately.
UploadTask.start(UploadRunner<T> runner) {
unawaited(_start(runner));
}
@@ -115,15 +144,25 @@ class UploadTask<T> {
final Completer<T> _result = Completer<T>();
final StreamController<UploadProgress> _progress =
StreamController<UploadProgress>.broadcast(sync: true);
+
+ /// Token passed to the running upload operation.
final CancellationToken cancellation = CancellationToken();
UploadTaskState _state = UploadTaskState.running;
int _lastBytes = 0;
+ /// Completes with the typed upload response or the task error.
Future<T> get result => _result.future;
+
+ /// Broadcast stream of monotonic progress updates.
Stream<UploadProgress> get progress => _progress.stream;
+
+ /// Current task state.
UploadTaskState get state => _state;
+
+ /// Whether cancellation won the terminal-state race.
bool get isCanceled => _state == UploadTaskState.canceled;
+ /// Requests cancellation and completes [result] with [OperationCanceled].
void cancel() {
if (_state != UploadTaskState.running) return;
_state = UploadTaskState.canceled;
@@ -157,7 +196,9 @@ class UploadTask<T> {
}
}
+/// Integrity and response metadata from a completed byte upload.
class SignedUploadResult {
+ /// Creates an immutable result.
const SignedUploadResult({
required this.statusCode,
this.etag = '',
@@ -169,7 +210,9 @@ class SignedUploadResult {
final String localMd5;
}
+/// Transport failure that retains partial-upload integrity information.
class SignedUploadFailure extends TransportException {
+ /// Creates a failure with the number of bytes already sent.
const SignedUploadFailure({
required this.sentBytes,
required this.localMd5,
@@ -180,7 +223,12 @@ class SignedUploadFailure extends TransportException {
final String localMd5;
}
+/// Pluggable transport for temporary signed media uploads.
abstract interface class SignedUploadTransport {
+ /// Uploads all or part of [source] and reports optional progress.
+ ///
+ /// Implementations must honor [cancellation] and must not attach app
+ /// credentials to the temporary upload destination.
Future<SignedUploadResult> upload({
required UploadSource source,
required Uri url,
@@ -193,10 +241,13 @@ abstract interface class SignedUploadTransport {
void Function(UploadProgress progress)? onProgress,
});
+ /// Releases transport resources. Implementations should be idempotent.
Future<void> close();
}
+/// `dart:io` implementation of [SignedUploadTransport].
class IoSignedUploadTransport implements SignedUploadTransport {
+ /// Creates a transport with [defaultTimeout].
IoSignedUploadTransport(this.defaultTimeout, {HttpClient? client})
: _client = client ?? HttpClient();
@@ -323,12 +374,19 @@ class IoSignedUploadTransport implements SignedUploadTransport {
}
}
+/// Stores resumable multipart-upload checkpoints.
abstract interface class UploadSessionStore {
+ /// Loads a checkpoint or returns `null` when absent.
Future<Map<String, Object?>?> load(String key);
+
+ /// Persists a checkpoint under [key].
Future<void> save(String key, Map<String, Object?> value);
+
+ /// Removes the checkpoint under [key].
Future<void> remove(String key);
}
+/// Process-local upload checkpoint store.
class MemoryUploadSessionStore implements UploadSessionStore {
final Map<String, Map<String, Object?>> _values =
<String, Map<String, Object?>>{};
@@ -350,7 +408,9 @@ class MemoryUploadSessionStore implements UploadSessionStore {
}
}
+/// File-backed upload checkpoint store with bounded, atomic JSON writes.
class FileUploadSessionStore implements UploadSessionStore {
+ /// Creates a store in [directory], creating it when necessary.
FileUploadSessionStore(this.directory) {
if (!directory.existsSync()) directory.createSync(recursive: true);
if (!directory.statSync().type.toString().contains('directory')) {
@@ -418,10 +478,13 @@ class FileUploadSessionStore implements UploadSessionStore {
File('${directory.path}/${sha256.convert(utf8.encode(key))}.json');
}
+/// Shared built-in upload checkpoint stores.
abstract final class UploadSessionStores {
+ /// Process-local store used when no explicit store is configured.
static final UploadSessionStore memory = MemoryUploadSessionStore();
}
+/// Calculates the MD5 digest for a validated range of [source].
Future<String> md5Hex(
UploadSource source, {
required int offset,
diff --git a/lib/vmodal_sdk_flutter.dart b/lib/vmodal_sdk_flutter.dart
index c9e15af..5da5602 100644
--- a/lib/vmodal_sdk_flutter.dart
+++ b/lib/vmodal_sdk_flutter.dart
@@ -1,4 +1,28 @@
-library;
+/// Typed Flutter client for uploading, indexing, and searching VModal media.
+///
+/// Create one [VmodalClient] for the active signed-in session and share its
+/// resource objects across the app. The SDK does not own login UI or persist
+/// credentials; supply the current key through [MutableApiKeyProvider] and
+/// close the client when the session ends.
+///
+/// ```dart
+/// final keys = MutableApiKeyProvider(runtimeApiKey);
+/// final vmodal = VmodalClient(config: SdkConfig(apiKeyProvider: keys));
+///
+/// final groups = await vmodal.collections.listGroups();
+/// final results = await vmodal.searches.searchVideo(
+/// const SearchRequest(queryText: 'a person entering the room'),
+/// );
+///
+/// await vmodal.close();
+/// keys.close();
+/// ```
+///
+/// Long-running calls accept a [CancellationToken]. Media uploads return an
+/// [UploadTask], whose [UploadTask.progress] stream is suitable for progress
+/// indicators and whose [UploadTask.cancel] method stops pending work.
+// ignore: unnecessary_library_name
+library vmodal_sdk_flutter;
export 'src/adaptive_upload.dart';
export 'src/api_key_provider.dart';
diff --git a/test/docs_reference_test.dart b/test/docs_reference_test.dart
new file mode 100644
index 0000000..ff89771
--- /dev/null
+++ b/test/docs_reference_test.dart
@@ -0,0 +1,134 @@
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:flutter_test/flutter_test.dart';
+
+final docsRoot = Directory('docs_sdk');
+final internalDocs = docsRoot.existsSync() && File('docs.py').existsSync();
+
+final requiredDocs = <String>[
+ 'index.html',
+ 'index.json',
+ 'vmodal_sdk_flutter/index.html',
+ 'vmodal_sdk_flutter/VmodalClient-class.html',
+ 'vmodal_sdk_flutter/VmodalClient/VmodalClient.html',
+ 'vmodal_sdk_flutter/VmodalClient/close.html',
+ 'vmodal_sdk_flutter/CollectionsResource/listGroups.html',
+ 'vmodal_sdk_flutter/CollectionUploads/videoUpload.html',
+ 'vmodal_sdk_flutter/UploadTask-class.html',
+];
+
+final forbiddenDocs = <String>[
+ 'swagger.yaml',
+ 'swagger-ui',
+ 'openapi:',
+ 'operationid',
+ 'x-flutter-sdk-method',
+ 'class="summary source-code"',
+ 'id="source"',
+ 'routes-class.html',
+ 'routespec',
+ 'routecategory',
+ 'publicgatewayurl',
+ 'publicgatewayurlhash',
+ 'devgatewayurl',
+ 'searchapi-test.v-modal.com',
+ '/api/v1',
+ '/api/external/v1',
+ '&#47;api&#47;v1',
+ '&#47;api&#47;external&#47;v1',
+ '&#x2f;api&#x2f;v1',
+ '&#x2f;api&#x2f;external&#x2f;v1',
+];
+
+Iterable<File> docsTextFiles() sync* {
+ const suffixes = <String>{
+ '.css',
+ '.html',
+ '.js',
+ '.json',
+ '.md',
+ '.svg',
+ '.txt',
+ '.xml',
+ };
+ for (final entity in docsRoot.listSync(recursive: true)) {
+ if (entity is File &&
+ suffixes.any((String suffix) => entity.path.endsWith(suffix))) {
+ yield entity;
+ }
+ }
+}
+
+void main() {
+ test('generated SDK reference contains required navigation and pages', () {
+ if (!internalDocs) return;
+ stdout.writeln('[docs] checking ${requiredDocs.length} required pages');
+ expect(docsRoot.existsSync(), isTrue);
+ for (final path in requiredDocs) {
+ expect(File('${docsRoot.path}/$path').existsSync(), isTrue, reason: path);
+ }
+ expect(File('${docsRoot.path}/index.json').lengthSync(), greaterThan(1000));
+ });
+
+ test('search inventory exposes representative public SDK symbols', () {
+ if (!internalDocs) return;
+ final rows =
+ jsonDecode(File('${docsRoot.path}/index.json').readAsStringSync())
+ as List<Object?>;
+ final names = rows
+ .cast<Map<String, Object?>>()
+ .map((Map<String, Object?> row) => '${row['qualifiedName']}')
+ .toSet();
+ const expected = <String>[
+ 'vmodal_sdk_flutter.VmodalClient',
+ 'vmodal_sdk_flutter.SearchesResource.searchVideo',
+ 'vmodal_sdk_flutter.CollectionUploads.videoUpload',
+ 'vmodal_sdk_flutter.UploadTask',
+ 'vmodal_sdk_flutter.SdkException',
+ ];
+ stdout.writeln('[docs] index entries=${rows.length}');
+ for (final name in expected) {
+ expect(names, contains(name), reason: name);
+ }
+ });
+
+ test('generated text contains no endpoints or implementation source', () {
+ if (!internalDocs) return;
+ var count = 0;
+ for (final file in docsTextFiles()) {
+ count++;
+ final text = utf8.decode(file.readAsBytesSync()).toLowerCase();
+ for (final value in forbiddenDocs) {
+ expect(text, isNot(contains(value)), reason: '${file.path}: $value');
+ }
+ }
+ stdout.writeln('[docs] endpoint-free text files checked=$count');
+ expect(count, greaterThan(100));
+ });
+
+ test('documentation commands use one deterministic Dartdoc pipeline', () {
+ if (!internalDocs) return;
+ final generator = File('docs.py').readAsStringSync();
+ expect(generator, contains('dart, "doc", "--validate-links"'));
+ expect(generator, contains('os_sanitize_dartdoc(site)'));
+ expect(generator, contains('os_compare_trees(dest, site)'));
+ expect(generator, isNot(contains('swagger_operations')));
+ expect(generator, isNot(contains('routes_contract.json')));
+ });
+
+ test('maintainer docs use SDK reference terminology', () {
+ if (!internalDocs) return;
+ for (final path in <String>[
+ 'README_PRIVATE.md',
+ 'docs/release.md',
+ 'docs/sdk_doc.md',
+ ]) {
+ final text = File(path).readAsStringSync().toLowerCase();
+ expect(text, isNot(contains('swagger')), reason: path);
+ expect(text, isNot(contains('openapi')), reason: path);
+ expect(text, isNot(contains('docs_swagger')), reason: path);
+ expect(text, contains('docs_sdk'), reason: path);
+ }
+ });
+}
diff --git a/test/regression_manifest_test.dart b/test/regression_manifest_test.dart
index 86543e1..d353891 100644
--- a/test/regression_manifest_test.dart
+++ b/test/regression_manifest_test.dart
@@ -44,6 +44,7 @@ void main() {
test('required implementation and release artifacts exist', () {
const files = <String>[
+ 'dartdoc_options.yaml',
'lib/vmodal_sdk_flutter.dart',
'lib/src/client.dart',
'lib/src/transport.dart',
@@ -73,6 +74,39 @@ void main() {
);
});
+ test('dartdoc exposes only the public library', () {
+ final text = File('dartdoc_options.yaml').readAsStringSync();
+ expect(text, contains('include:'));
+ expect(text, contains('- vmodal_sdk_flutter'));
+ expect(text, contains('nodoc:'));
+ expect(text, contains('- lib/src/http.dart'));
+ expect(text, contains('- lib/src/routes.dart'));
+ expect(text, contains('- ambiguous-doc-reference'));
+ expect(text, contains('- broken-link'));
+ expect(text, contains('- unresolved-doc-reference'));
+ final api = File('lib/vmodal_sdk_flutter.dart').readAsStringSync();
+ expect(
+ api,
+ contains(
+ "export 'src/routes.dart' show RouteCategory, RouteSpec, Routes;",
+ ),
+ reason: 'documentation exclusions must not remove runtime exports',
+ );
+ });
+
+ test('package publication excludes internal documentation artifacts', () {
+ final text = File('.pubignore').readAsStringSync();
+ for (final path in <String>[
+ 'docs/todo/',
+ 'docs_sdk/',
+ 'docs.py',
+ 'utils.py',
+ ]) {
+ expect(text, contains(path), reason: path);
+ }
+ expect(text, isNot(contains('dartdoc_options.yaml')));
+ });
+
test('default all suite remains offline', () {
final text = File('test.sh').readAsStringSync();
final body = RegExp(
@@ -99,6 +133,7 @@ void main() {
]);
expect(result.exitCode, 0, reason: '${result.stderr}');
expect(File('${dir.path}/pubspec.lock').existsSync(), isTrue);
+ expect(File('${dir.path}/dartdoc_options.yaml').existsSync(), isTrue);
for (final path in <String>[
'install.sh',
'build.sh',
@@ -120,6 +155,10 @@ void main() {
'example/ios/Flutter/ephemeral',
'example/ios/Runner/GeneratedPluginRegistrant.h',
'example/ios/Runner/GeneratedPluginRegistrant.m',
+ 'doc/todo/sdk_doc.md',
+ 'docs_sdk',
+ 'docs.py',
+ 'utils.py',
]) {
expect(
FileSystemEntity.typeSync('${dir.path}/$path'),
diff --git a/test/workflow_layout_test.dart b/test/workflow_layout_test.dart
index 7cfc513..123279f 100644
--- a/test/workflow_layout_test.dart
+++ b/test/workflow_layout_test.dart
@@ -22,16 +22,16 @@ final examplePubspec = File('example/pubspec.yaml').readAsStringSync();
void checkWorkflow(String main, String tagged) {
const releaseOnly =
- "if: \${{ github.event_name == 'workflow_dispatch' && !inputs.publish_docs_swagger_only && (inputs.publish_sdk_flutter || inputs.publish_pub_dev) }}";
+ "if: \${{ github.event_name == 'workflow_dispatch' && !inputs.publish_sdk_docs_only && (inputs.publish_sdk_flutter || inputs.publish_pub_dev) }}";
const publishDocs =
- "if: \${{ github.event_name == 'workflow_dispatch' && (inputs.publish_sdk_flutter || inputs.publish_pub_dev || inputs.publish_docs_swagger_only) }}";
+ "if: \${{ github.event_name == 'workflow_dispatch' && (inputs.publish_sdk_flutter || inputs.publish_pub_dev || inputs.publish_sdk_docs_only) }}";
const buildDocs =
- "if: \${{ always() && github.event_name == 'workflow_dispatch' && (inputs.publish_sdk_flutter || inputs.publish_pub_dev || inputs.publish_docs_swagger_only) && needs.secret_detection.result == 'success' && (inputs.publish_docs_swagger_only || needs.publish_sdk_flutter.result == 'success') }}";
+ "if: \${{ always() && github.event_name == 'workflow_dispatch' && (inputs.publish_sdk_flutter || inputs.publish_pub_dev || inputs.publish_sdk_docs_only) && needs.secret_detection.result == 'success' && (inputs.publish_sdk_docs_only || needs.publish_sdk_flutter.result == 'success') }}";
expect(main, contains('name: sdk_flutter_test_release'));
expect(main, contains('publish_sdk_flutter:'));
expect(main, contains('publish_pub_dev:'));
- expect(main, contains('publish_docs_swagger_only:'));
- expect(main, contains('description: Publish only the doc swagger'));
+ expect(main, contains('publish_sdk_docs_only:'));
+ expect(main, contains('description: Publish only the Flutter SDK reference'));
expect(main, contains('default: true'));
expect(main, contains('group: sdk_flutter_release_\${{ github.ref }}'));
expect(main, contains('WORKDIR: uinterface/sdk_flutter'));
@@ -51,7 +51,7 @@ void checkWorkflow(String main, String tagged) {
expect(
main,
contains(
- 'offline_test:\n if: \${{ !inputs.publish_docs_swagger_only }}\n runs-on: ubuntu-latest',
+ 'offline_test:\n if: \${{ !inputs.publish_sdk_docs_only }}\n runs-on: ubuntu-latest',
),
);
expect(
@@ -75,7 +75,7 @@ void checkWorkflow(String main, String tagged) {
expect(
main,
contains(
- 'if: \${{ !inputs.publish_docs_swagger_only && inputs.publish_pub_dev }}',
+ 'if: \${{ !inputs.publish_sdk_docs_only && inputs.publish_pub_dev }}',
),
);
expect(main, contains('environment: sdk-flutter-production'));
@@ -99,28 +99,42 @@ void checkWorkflow(String main, String tagged) {
expect(
main,
contains(
- 'if: \${{ !inputs.publish_docs_swagger_only && (inputs.publish_sdk_flutter || inputs.publish_pub_dev) }}',
+ 'if: \${{ !inputs.publish_sdk_docs_only && (inputs.publish_sdk_flutter || inputs.publish_pub_dev) }}',
),
);
expect(
main,
contains(
- 'swagger_docs_artifact:\n needs: [secret_detection, publish_sdk_flutter]\n $buildDocs',
+ 'sdk_docs_artifact:\n needs: [secret_detection, publish_sdk_flutter]\n $buildDocs',
),
);
expect(
main,
contains(
- 'publish_swagger_docs:\n needs: swagger_docs_artifact\n $publishDocs',
+ 'publish_sdk_docs:\n needs: sdk_docs_artifact\n $publishDocs',
),
);
expect(main, contains('python "\$WORKDIR/docs.py" generate'));
expect(main, contains('python "\$WORKDIR/docs.py" check'));
+ expect(main, contains('bash "\$WORKDIR/install.sh" install'));
expect(
main,
- contains('openapi-spec-validator "\$WORKDIR/docs_swagger/swagger.yaml"'),
+ contains('python -m pip install --disable-pip-version-check fire==0.7.1'),
);
- expect(main, contains('path: \${{ env.WORKDIR }}/docs_swagger'));
+ expect(main, contains('path: \${{ env.WORKDIR }}/docs_sdk'));
+ expect(
+ main,
+ contains('sdk-flutter-docs-\${{ github.run_id }}-\${{ github.sha }}'),
+ );
+ expect(main, contains('"\$WORKDIR/docs_sdk/index.html"'));
+ expect(main, contains('"\$WORKDIR/docs_sdk/index.json"'));
+ expect(
+ main,
+ contains('"\$WORKDIR/docs_sdk/vmodal_sdk_flutter/VmodalClient-class.html"'),
+ );
+ expect(main, isNot(contains('PyYAML')));
+ expect(main, isNot(contains('openapi-spec-validator')));
+ expect(main.toLowerCase(), isNot(contains('swagger')));
expect(main, contains('include-hidden-files: true'));
expect(main, contains('DOCS_REPOSITORY: v-modal/vmodal_sdk_flutter'));
expect(
@@ -134,6 +148,8 @@ void checkWorkflow(String main, String tagged) {
expect(main, contains('"\$DOCS_URL/RELEASE_SHA"'));
expect(main, contains('for attempt in {1..30}'));
expect(main, contains('https://pub.dev/api/packages/vmodal_sdk_flutter'));
+ expect(main, contains('dartdoc_options.yaml'));
+ expect(main, contains("--exclude='todo'"));
final actions = RegExp(
r'uses:\s+[^\s]+@([^\s]+)',
diff --git a/tool/release_manifest.dart b/tool/release_manifest.dart
index 3fc23ee..57592eb 100644
--- a/tool/release_manifest.dart
+++ b/tool/release_manifest.dart
@@ -82,6 +82,7 @@ Future<void> _export(Directory root, Directory destination) async {
'pubspec.yaml',
'pubspec.lock',
'analysis_options.yaml',
+ 'dartdoc_options.yaml',
'LICENSE',
'README.md',
'readme_assets',
@@ -121,6 +122,7 @@ Future<void> _export(Directory root, Directory destination) async {
await _copyDirectory(
Directory('${root.path}/$docs'),
Directory('${destination.path}/doc'),
+ excluded: const <String>{'todo'},
);
final publish = File('${root.path}/release/public_publish.yml').existsSync()
? File('${root.path}/release/public_publish.yml')
@@ -131,20 +133,29 @@ Future<void> _export(Directory root, Directory destination) async {
await _manifest(destination);
}
-Future<void> _copyDirectory(Directory source, Directory destination) async {
+Future<void> _copyDirectory(
+ Directory source,
+ Directory destination, {
+ Set<String> excluded = const <String>{},
+}) async {
await destination.create(recursive: true);
await for (final entity in source.list(recursive: false)) {
final name = entity.uri.pathSegments
.where((String value) => value.isNotEmpty)
.last;
- if (isGeneratedName(name) ||
+ if (excluded.contains(name) ||
+ isGeneratedName(name) ||
const <String>{'dev_plan.md', 'dev_plan_step.md'}.contains(name)) {
continue;
}
if (entity is File) {
await entity.copy('${destination.path}/$name');
} else if (entity is Directory) {
- await _copyDirectory(entity, Directory('${destination.path}/$name'));
+ await _copyDirectory(
+ entity,
+ Directory('${destination.path}/$name'),
+ excluded: excluded,
+ );
}
}
}