refactor(ads-client): housekeeping - sort fields/methods, add UniFFI defaults, split docs, add Client in HttpCache

components/ads-client/README.md

@@ -44,4 +44,10 @@ cargo test -p ads-client-integration-tests --test mars test_contract_image_stagi
 
 ## Usage
 
-Please refer to `./docs/usage.md` for information on using the component.
+Please refer to `./docs/usage.md` for the API reference and type documentation.
+
+Language-specific guides with code examples:
+
+- [Swift](./docs/usage-swift.md)
+- [Kotlin](./docs/usage-kotlin.md)
+- [JavaScript](./docs/usage-javascript.md)

components/ads-client/docs/usage-javascript.md

@@ -0,0 +1,77 @@
+# Mozilla Ads Client — JavaScript Usage Guide
+
+This guide covers JavaScript-specific examples for using the Mozilla Ads Client (MAC) via UniFFI bindings. For the full API reference and type documentation, see [usage.md](./usage.md).
+
+---
+
+## Creating a Client
+
+```javascript
+const client = MozAdsClientBuilder()
+    .environment(MozAdsEnvironment.Prod)
+    .cacheConfig(cache)
+    .telemetry(telemetry)
+    .build();
+```
+
+---
+
+## Implementing Telemetry
+
+```javascript
+class AdsClientTelemetry {
+    recordBuildCacheError(label, value) {
+        // Bind to your telemetry system
+    }
+
+    recordClientError(label, value) {
+        // Bind to your telemetry system
+    }
+
+    recordClientOperationTotal(label) {
+        // Bind to your telemetry system
+    }
+
+    recordDeserializationError(label, value) {
+        // Bind to your telemetry system
+    }
+
+    recordHttpCacheOutcome(label, value) {
+        // Bind to your telemetry system
+    }
+}
+```
+
+---
+
+## Configuring the Cache
+
+```javascript
+const cache = MozAdsCacheConfig({
+    dbPath: "/tmp/ads_cache.sqlite",
+    defaultCacheTtlSeconds: 600,   // 10 min
+    maxSizeMib: 20                 // 20 MiB
+});
+
+const telemetry = new AdsClientTelemetry();
+
+const client = MozAdsClientBuilder()
+    .environment(MozAdsEnvironment.Prod)
+    .cacheConfig(cache)
+    .telemetry(telemetry)
+    .build();
+```
+
+---
+
+## Per-Request Cache Policy Override
+
+```javascript
+// Always fetch from network but only cache for 60 seconds
+const options = MozAdsRequestOptions({
+    cachePolicy: MozAdsRequestCachePolicy({ mode: MozAdsCacheMode.NetworkFirst, ttlSeconds: 60 })
+});
+
+// Use it when requesting ads
+const placements = client.requestImageAds(configs, options);
+```

components/ads-client/docs/usage-kotlin.md

@@ -0,0 +1,80 @@
+# Mozilla Ads Client — Kotlin Usage Guide
+
+This guide covers Kotlin-specific examples for using the Mozilla Ads Client (MAC) via UniFFI bindings. For the full API reference and type documentation, see [usage.md](./usage.md).
+
+---
+
+## Creating a Client
+
+```kotlin
+val client = MozAdsClientBuilder()
+    .environment(MozAdsEnvironment.PROD)
+    .cacheConfig(cache)
+    .telemetry(telemetry)
+    .build()
+```
+
+---
+
+## Implementing Telemetry
+
+```kotlin
+import mozilla.appservices.adsclient.MozAdsTelemetry
+import org.mozilla.appservices.ads_client.GleanMetrics.AdsClient
+
+class AdsClientTelemetry : MozAdsTelemetry {
+    override fun recordBuildCacheError(label: String, value: String) {
+        AdsClient.buildCacheError[label].set(value)
+    }
+
+    override fun recordClientError(label: String, value: String) {
+        AdsClient.clientError[label].set(value)
+    }
+
+    override fun recordClientOperationTotal(label: String) {
+        AdsClient.clientOperationTotal[label].add()
+    }
+
+    override fun recordDeserializationError(label: String, value: String) {
+        AdsClient.deserializationError[label].set(value)
+    }
+
+    override fun recordHttpCacheOutcome(label: String, value: String) {
+        AdsClient.httpCacheOutcome[label].set(value)
+    }
+}
+```
+
+---
+
+## Configuring the Cache
+
+```kotlin
+val cache = MozAdsCacheConfig(
+    dbPath = "/tmp/ads_cache.sqlite",
+    defaultCacheTtlSeconds = 600L,   // 10 min
+    maxSizeMib = 20L                 // 20 MiB
+)
+
+val telemetry = AdsClientTelemetry()
+
+val client = MozAdsClientBuilder()
+    .environment(MozAdsEnvironment.PROD)
+    .cacheConfig(cache)
+    .telemetry(telemetry)
+    .build()
+```
+
+---
+
+## Per-Request Cache Policy Override
+
+```kotlin
+// Always fetch from network but only cache for 60 seconds
+val options = MozAdsRequestOptions(
+    cachePolicy = MozAdsRequestCachePolicy(mode = MozAdsCacheMode.NETWORK_FIRST, ttlSeconds = 60L)
+)
+
+// Use it when requesting ads
+val placements = client.requestImageAds(configs, options = options)
+```

components/ads-client/docs/usage-swift.md

@@ -0,0 +1,80 @@
+# Mozilla Ads Client — Swift Usage Guide
+
+This guide covers Swift-specific examples for using the Mozilla Ads Client (MAC) via UniFFI bindings. For the full API reference and type documentation, see [usage.md](./usage.md).
+
+---
+
+## Creating a Client
+
+```swift
+let client = MozAdsClientBuilder()
+    .environment(environment: .prod)
+    .cacheConfig(cacheConfig: cache)
+    .telemetry(telemetry: telemetry)
+    .build()
+```
+
+---
+
+## Implementing Telemetry
+
+```swift
+import MozillaRustComponents
+import Glean
+
+public final class AdsClientTelemetry: MozAdsTelemetry {
+    public func recordBuildCacheError(label: String, value: String) {
+        AdsClientMetrics.buildCacheError[label].set(value)
+    }
+
+    public func recordClientError(label: String, value: String) {
+        AdsClientMetrics.clientError[label].set(value)
+    }
+
+    public func recordClientOperationTotal(label: String) {
+        AdsClientMetrics.clientOperationTotal[label].add()
+    }
+
+    public func recordDeserializationError(label: String, value: String) {
+        AdsClientMetrics.deserializationError[label].set(value)
+    }
+
+    public func recordHttpCacheOutcome(label: String, value: String) {
+        AdsClientMetrics.httpCacheOutcome[label].set(value)
+    }
+}
+```
+
+---
+
+## Configuring the Cache
+
+```swift
+let cache = MozAdsCacheConfig(
+    dbPath: "/tmp/ads_cache.sqlite",
+    defaultCacheTtlSeconds: 600,   // 10 min
+    maxSizeMib: 20                 // 20 MiB
+)
+
+let telemetry = AdsClientTelemetry()
+
+let client = MozAdsClientBuilder()
+    .environment(environment: .prod)
+    .cacheConfig(cacheConfig: cache)
+    .telemetry(telemetry: telemetry)
+    .build()
+```
+
+---
+
+## Per-Request Cache Policy Override
+
+```swift
+// Always fetch from network but only cache for 60 seconds
+let options = MozAdsRequestOptions(
+    cachePolicy: MozAdsRequestCachePolicy(mode: .networkFirst, ttlSeconds: 60)
+)
+
+// Use it when requesting ads
+let placements = client.requestImageAds(configs, options: options)
+```