@zerogpu/expo-android-sdk 0.1.2 → 0.2.0-dev.202609221223.gb39bc09

package/README.md

@@ -68,9 +68,30 @@ await start('zgpu-sdk-…', {
   baseUrl: 'https://devices.zerogpu.ai', // default
   env: 'production',                     // default
   enableTelemetry: true,                 // default
+  customParams: { cust_param1: 'placement_home' }, // operator macros, see below
 });
 ```
 
+### Custom params (operator macros)
+
+Three opaque slots — `cust_param1`, `cust_param2`, `cust_param3` — attached to every task the
+device serves, so you can segment your ZeroGPU earnings by your own dimensions (placement, cohort,
+campaign). ZeroGPU stores and counts them and never interprets them.
+
+```ts
+import { setCustomParams } from '@zerogpu/expo-android-sdk';
+
+// Replaces the whole set (a slot you leave out is cleared); `{}` clears all.
+// Applies from the next task — no restart. Safe to call before start().
+await setCustomParams({ cust_param1: 'placement_settings', cust_param2: 'cohort_b' });
+```
+
+A slot takes **just a value** — the slot name is the key — so send `{ cust_param1: '1231231313' }`,
+never `{ cust_param1: 'user-id=1231231313' }`. Letters, digits, `.`, `_` and `-` only; anything else
+is dropped with a logcat warning. Values are truncated to 128 characters and unknown keys are
+dropped. **Never put PII** (emails, phone numbers, names) in a slot — email-shaped values are
+dropped with a logcat warning.
+
 ## Verifying it works
 
 Run the app on an `arm64-v8a` phone or an `x86_64` emulator (Android 8.0+), then

package/android/build.gradle

@@ -4,7 +4,7 @@ apply plugin: 'com.android.library'
 apply plugin: 'kotlin-android'
 
 group = 'ai.zerogpu.expo'
-version = '0.1.0'
+version = '0.2.0'
 
 def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
 apply from: expoModulesCorePlugin

package/android/src/main/java/ai/zerogpu/expo/ZeroGpuAndroidSdkModule.kt

@@ -17,6 +17,10 @@ class ZeroGpuAndroidSdkModule : Module() {
   // null == not started.
   private var sdk: ZeroGpuSdk? = null
 
+  // Outlives stop()/start() so macros set before start (or between runs) apply
+  // to the next instance.
+  private var customParams: Map<String, String> = emptyMap()
+
   override fun definition() = ModuleDefinition {
     // Must match requireNativeModule('ZeroGpuAndroidSdk') on the JS side.
     Name("ZeroGpuAndroidSdk")
@@ -27,15 +31,23 @@ class ZeroGpuAndroidSdkModule : Module() {
       val appCtx = appContext.reactContext?.applicationContext
         ?: throw Exceptions.ReactContextLost()
 
+      (options?.get("customParams") as? Map<*, *>)?.let { customParams = toStringMap(it) }
+
       sdk = ZeroGpuSdk(
         context = appCtx,
         operatorKey = operatorKey,
         baseUrl = (options?.get("baseUrl") as? String) ?: DEFAULT_BASE_URL,
         env = (options?.get("env") as? String) ?: DEFAULT_ENV,
         enableTelemetry = (options?.get("enableTelemetry") as? Boolean) ?: true,
+        customParams = customParams,
       ).also { it.start() }
     }
 
+    AsyncFunction("setCustomParams") { params: Map<String, Any?> ->
+      customParams = toStringMap(params)
+      sdk?.setCustomParams(customParams)
+    }
+
     AsyncFunction("stop") {
       sdk?.stop()
       sdk = null // drop the dead instance; a later start() builds a fresh one
@@ -48,6 +60,20 @@ class ZeroGpuAndroidSdkModule : Module() {
     }
   }
 
+  // JS numbers/booleans are coerced like the server does; nested values are
+  // dropped here rather than stringified into a slot.
+  private fun toStringMap(raw: Map<*, *>): Map<String, String> =
+    raw.entries.mapNotNull { (k, v) ->
+      val key = k as? String ?: return@mapNotNull null
+      val value = when (v) {
+        is String -> v
+        is Boolean -> v.toString()
+        is Number -> if (v.toDouble() % 1.0 == 0.0) v.toLong().toString() else v.toString()
+        else -> return@mapNotNull null
+      }
+      key to value
+    }.toMap()
+
   private companion object {
     const val DEFAULT_BASE_URL = "https://devices.zerogpu.ai"
     const val DEFAULT_ENV = "production"

package/build/ZeroGpuAndroidSdkModule.d.ts

@@ -1,4 +1,4 @@
-import type { ZeroGpuOptions } from './types';
+import type { CustomParams, ZeroGpuOptions } from './types';
 /**
  * Native-module contract. Backed by the Android implementation
  * (`ai.zerogpu.expo.ZeroGpuAndroidSdkModule`) and a no-op iOS stub, so both
@@ -7,7 +7,7 @@ import type { ZeroGpuOptions } from './types';
 export interface ZeroGpuAndroidSdkNativeModule {
     start(operatorKey: string, options?: ZeroGpuOptions): Promise<void>;
     stop(): Promise<void>;
+    setCustomParams(customParams: CustomParams): Promise<void>;
 }
 declare const _default: ZeroGpuAndroidSdkNativeModule;
 export default _default;
-//# sourceMappingURL=ZeroGpuAndroidSdkModule.d.ts.map

package/build/ZeroGpuAndroidSdkModule.js

@@ -1,4 +1,3 @@
 import { requireNativeModule } from 'expo-modules-core';
 // The name must match `Name(...)` in the native module definitions.
 export default requireNativeModule('ZeroGpuAndroidSdk');
-//# sourceMappingURL=ZeroGpuAndroidSdkModule.js.map

package/build/index.d.ts

@@ -1,5 +1,5 @@
-import type { ZeroGpuOptions } from './types';
-export type { ZeroGpuOptions } from './types';
+import type { CustomParams, ZeroGpuOptions } from './types';
+export type { CustomParams, ZeroGpuOptions } from './types';
 /**
  * Start the ZeroGPU node. The device registers with the ZeroGPU backend using the
  * operator key, downloads its assigned model(s), and serves on-device inference
@@ -9,7 +9,8 @@ export type { ZeroGpuOptions } from './types';
  * resolves without doing anything — the SDK is Android-only.
  *
  * @param operatorKey Your operator key from the ZeroGPU dashboard (`zgpu-sdk-…`).
- * @param options Optional base URL / environment / telemetry overrides.
+ * @param options Optional base URL / environment / telemetry overrides and
+ *   initial `customParams`.
  */
 export declare function start(operatorKey: string, options?: ZeroGpuOptions): Promise<void>;
 /**
@@ -17,4 +18,9 @@ export declare function start(operatorKey: string, options?: ZeroGpuOptions): Pr
  * SDK down. A subsequent {@link start} spins up a fresh instance. No-op on iOS.
  */
 export declare function stop(): Promise<void>;
-//# sourceMappingURL=index.d.ts.map
+/**
+ * Replace the operator macros on the running node; `{}` clears them. Applies
+ * from the next task the device serves — no re-register. Values set before
+ * {@link start} are kept and used when it starts. No-op on iOS.
+ */
+export declare function setCustomParams(customParams: CustomParams): Promise<void>;

package/build/index.js

@@ -8,7 +8,8 @@ import ZeroGpuAndroidSdkModule from './ZeroGpuAndroidSdkModule';
  * resolves without doing anything — the SDK is Android-only.
  *
  * @param operatorKey Your operator key from the ZeroGPU dashboard (`zgpu-sdk-…`).
- * @param options Optional base URL / environment / telemetry overrides.
+ * @param options Optional base URL / environment / telemetry overrides and
+ *   initial `customParams`.
  */
 export function start(operatorKey, options) {
     return ZeroGpuAndroidSdkModule.start(operatorKey, options);
@@ -20,4 +21,11 @@ export function start(operatorKey, options) {
 export function stop() {
     return ZeroGpuAndroidSdkModule.stop();
 }
-//# sourceMappingURL=index.js.map
+/**
+ * Replace the operator macros on the running node; `{}` clears them. Applies
+ * from the next task the device serves — no re-register. Values set before
+ * {@link start} are kept and used when it starts. No-op on iOS.
+ */
+export function setCustomParams(customParams) {
+    return ZeroGpuAndroidSdkModule.setCustomParams(customParams);
+}

package/build/types.d.ts

@@ -9,5 +9,19 @@ export type ZeroGpuOptions = {
     env?: string;
     /** Whether the SDK reports anonymous telemetry. Defaults to `true`. */
     enableTelemetry?: boolean;
+    /** Operator macros attached to every task this device serves. See {@link CustomParams}. */
+    customParams?: CustomParams;
+};
+/**
+ * Operator-defined macros: opaque values (placement, cohort, campaign…) that
+ * ZeroGPU stores and counts per request and never interprets, so you can
+ * segment your earnings by them. A slot takes just a value (letters, digits,
+ * `.` `_` `-`), never a nested parameter like `user-id=123`, which is dropped.
+ * Values are truncated to 128 characters; unset or empty slots are omitted. Never put PII (emails, phone numbers, names) in a
+ * slot — email-shaped values are dropped with a logcat warning.
+ */
+export type CustomParams = {
+    cust_param1?: string;
+    cust_param2?: string;
+    cust_param3?: string;
 };
-//# sourceMappingURL=types.d.ts.map

package/build/types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types.js.map

package/ios/ZeroGpuAndroidSdkModule.swift

@@ -13,5 +13,9 @@ public class ZeroGpuAndroidSdkModule: Module {
     AsyncFunction("stop") {
       // No-op on iOS.
     }
+
+    AsyncFunction("setCustomParams") { (_ customParams: [String: Any]) in
+      // No-op on iOS.
+    }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerogpu/expo-android-sdk",
-  "version": "0.1.2",
+  "version": "0.2.0-dev.202609221223.gb39bc09",
   "description": "Expo/React Native module that runs a ZeroGPU on-device inference node on Android by wrapping the native ai.zerogpu:android-sdk AAR.",
   "main": "build/index.js",
   "types": "build/index.d.ts",

package/build/ZeroGpuAndroidSdkModule.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ZeroGpuAndroidSdkModule.d.ts","sourceRoot":"","sources":["../src/ZeroGpuAndroidSdkModule.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;;AAGD,wBAAuF"}

package/build/ZeroGpuAndroidSdkModule.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ZeroGpuAndroidSdkModule.js","sourceRoot":"","sources":["../src/ZeroGpuAndroidSdkModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAcxD,oEAAoE;AACpE,eAAe,mBAAmB,CAAgC,mBAAmB,CAAC,CAAC","sourcesContent":["import { requireNativeModule } from 'expo-modules-core';\n\nimport type { ZeroGpuOptions } from './types';\n\n/**\n * Native-module contract. Backed by the Android implementation\n * (`ai.zerogpu.expo.ZeroGpuAndroidSdkModule`) and a no-op iOS stub, so both\n * methods resolve on every platform.\n */\nexport interface ZeroGpuAndroidSdkNativeModule {\n  start(operatorKey: string, options?: ZeroGpuOptions): Promise<void>;\n  stop(): Promise<void>;\n}\n\n// The name must match `Name(...)` in the native module definitions.\nexport default requireNativeModule<ZeroGpuAndroidSdkNativeModule>('ZeroGpuAndroidSdk');\n"]}

package/build/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAElF;AAED;;;GAGG;AACH,wBAAgB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAEpC"}

package/build/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,uBAAuB,MAAM,2BAA2B,CAAC;AAKhE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,KAAK,CAAC,WAAmB,EAAE,OAAwB;IACjE,OAAO,uBAAuB,CAAC,KAAK,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AAC7D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,IAAI;IAClB,OAAO,uBAAuB,CAAC,IAAI,EAAE,CAAC;AACxC,CAAC","sourcesContent":["import ZeroGpuAndroidSdkModule from './ZeroGpuAndroidSdkModule';\nimport type { ZeroGpuOptions } from './types';\n\nexport type { ZeroGpuOptions } from './types';\n\n/**\n * Start the ZeroGPU node. The device registers with the ZeroGPU backend using the\n * operator key, downloads its assigned model(s), and serves on-device inference\n * while the app is foregrounded (the native SDK manages the socket lifecycle).\n *\n * Idempotent: calling `start` again while already running is a no-op. On iOS this\n * resolves without doing anything — the SDK is Android-only.\n *\n * @param operatorKey Your operator key from the ZeroGPU dashboard (`zgpu-sdk-…`).\n * @param options Optional base URL / environment / telemetry overrides.\n */\nexport function start(operatorKey: string, options?: ZeroGpuOptions): Promise<void> {\n  return ZeroGpuAndroidSdkModule.start(operatorKey, options);\n}\n\n/**\n * Stop the ZeroGPU node: close the socket, release model adapters, and shut the\n * SDK down. A subsequent {@link start} spins up a fresh instance. No-op on iOS.\n */\nexport function stop(): Promise<void> {\n  return ZeroGpuAndroidSdkModule.stop();\n}\n"]}

package/build/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC"}

package/build/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Optional overrides for {@link start}. All fields default to production values\n * inside the native SDK, so a typical caller only passes the operator key.\n */\nexport type ZeroGpuOptions = {\n  /** Device-registration base URL. Defaults to `https://devices.zerogpu.ai`. */\n  baseUrl?: string;\n  /** Environment name. Defaults to `production`. */\n  env?: string;\n  /** Whether the SDK reports anonymous telemetry. Defaults to `true`. */\n  enableTelemetry?: boolean;\n};\n"]}