@quipuscore/watson-core-capacitor 0.1.0 → 0.2.0

package/android/build.gradle

@@ -1,7 +1,7 @@
 ext {
     androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.0'
     junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
-    watsonCoreVersion = project.hasProperty('watsonCoreVersion') ? rootProject.ext.watsonCoreVersion : '0.1.0'
+    watsonCoreVersion = project.hasProperty('watsonCoreVersion') ? rootProject.ext.watsonCoreVersion : '0.2.0'
 }
 
 buildscript {

package/android/src/main/java/com/quipuscore/watson/core/CapacitorPermissionRequester.java

@@ -1,8 +1,10 @@
 package com.quipuscore.watson.core;
 
 import android.Manifest;
+import android.content.Context;
 
 import com.getcapacitor.PluginCall;
+import com.getcapacitor.util.PermissionHelper;
 
 import com.quipuscore.watson.core.PermissionRequester;
 import com.quipuscore.watson.core.PermissionResultCallback;
@@ -34,7 +36,7 @@ final class CapacitorPermissionRequester implements PermissionRequester {
 
     @Override
     public void requestPermissions(List<String> permissions, PermissionResultCallback onComplete) {
-        String[] aliases = aliasesFor(permissions);
+        String[] aliases = aliasesFor(plugin.getContext(), permissions);
         if (aliases.length == 0) {
             // Nothing this wrapper knows how to prompt for; let the core proceed and gate per collector.
             onComplete.onPermissionsResolved();
@@ -45,11 +47,16 @@ final class CapacitorPermissionRequester implements PermissionRequester {
 
     /**
      * Maps runtime permission strings to the aliases declared in {@link WatsonCorePlugin}. Unknown
-     * permissions are dropped (a new collector permission needs a new alias in the plugin).
+     * permissions are dropped (a new collector permission needs a new alias in the plugin), and so
+     * are permissions missing from the app manifest (e.g. removed with {@code tools:node="remove"}):
+     * Capacitor would reject such a prompt without ever calling back, stalling the prompt queue.
      */
-    private static String[] aliasesFor(List<String> permissions) {
+    private static String[] aliasesFor(Context context, List<String> permissions) {
         Set<String> aliases = new LinkedHashSet<>();
         for (String permission : permissions) {
+            if (!PermissionHelper.hasDefinedPermission(context, permission)) {
+                continue;
+            }
             if (Manifest.permission.READ_SMS.equals(permission)) {
                 aliases.add("sms");
             } else if (Manifest.permission.READ_CALENDAR.equals(permission)) {

package/android/src/main/java/com/quipuscore/watson/core/WatsonCorePlugin.java

@@ -15,10 +15,13 @@ import com.quipuscore.watson.core.CollectionCallback;
 import com.quipuscore.watson.core.CollectionResult;
 import com.quipuscore.watson.core.CollectorOutcome;
 import com.quipuscore.watson.core.PermissionResultCallback;
+import com.quipuscore.watson.core.WatsonRegistry;
 import com.quipuscore.watson.core.WatsonService;
 
-import org.json.JSONException;
+import org.json.JSONArray;
 
+import java.util.ArrayDeque;
+import java.util.ArrayList;
 import java.util.List;
 
 /**
@@ -32,6 +35,10 @@ import java.util.List;
  * collector modules at compile time: the strings are Android constants, and the dangerous permission
  * reaches the merged manifest through the collector artifact the developer installed. A new collector
  * with a new permission means adding its alias here.
+ *
+ * <p>Every failure reaches JS as a rejected Promise with a stable {@code code} (mirrored by
+ * {@code WatsonErrorCode} in TypeScript); nothing is allowed to escape a plugin method, where the
+ * Capacitor bridge would rethrow it and crash the app.
  */
 @CapacitorPlugin(
     name = "WatsonCore",
@@ -43,49 +50,68 @@ import java.util.List;
 )
 public class WatsonCorePlugin extends Plugin {
 
-    /** Held across the async Capacitor permission prompt so the core collection can resume. */
-    private PermissionResultCallback pendingPermissionCallback;
+    /** The {@code collectors} option is not an array of non-empty strings. */
+    static final String ERROR_INVALID_ARGUMENT = "WATSON_INVALID_ARGUMENT";
+    /** A collector id has no native module registered: package missing or not synced. */
+    static final String ERROR_COLLECTOR_NOT_INSTALLED = "WATSON_COLLECTOR_NOT_INSTALLED";
+    /** Any other native failure while starting the run. */
+    static final String ERROR_INTERNAL = "WATSON_INTERNAL";
+
+    /**
+     * Permission prompts waiting for their turn. Android shows one permission dialog at a time and
+     * answers a second simultaneous request with an empty result, so overlapping collections (e.g.
+     * {@code Promise.all}) are prompted strictly one after the other, each resuming its own run.
+     * Guarded by itself: prompts are queued from the plugin thread and resolved on the main thread.
+     */
+    private final ArrayDeque<PendingPrompt> queuedPrompts = new ArrayDeque<>();
+    private PendingPrompt activePrompt;
 
     @PluginMethod
     public void collect(PluginCall call) {
         final WatsonService service;
         try {
             service = buildService(call);
-        } catch (JSONException e) {
-            call.reject("Invalid 'collectors' argument", e);
+        } catch (WatsonCallException e) {
+            call.reject(e.getMessage(), e.code);
+            return;
+        } catch (Exception e) {
+            call.reject(messageOf(e), ERROR_INTERNAL, e);
             return;
         }
 
-        service.collect(new CollectionCallback() {
-            @Override
-            public void onSuccess(CollectionResult result) {
-                call.resolve(toJs(result));
-            }
+        try {
+            service.collect(new CollectionCallback() {
+                @Override
+                public void onSuccess(CollectionResult result) {
+                    call.resolve(toJs(result));
+                }
 
-            @Override
-            public void onError(Exception error) {
-                call.reject(error.getMessage(), error);
-            }
-        });
+                @Override
+                public void onError(Exception error) {
+                    call.reject(messageOf(error), error);
+                }
+            });
+        } catch (Exception e) {
+            call.reject(messageOf(e), ERROR_INTERNAL, e);
+        }
     }
 
     @PluginMethod
     public void getUngrantedPermissions(PluginCall call) {
-        final WatsonService service;
         try {
-            service = buildService(call);
-        } catch (JSONException e) {
-            call.reject("Invalid 'collectors' argument", e);
-            return;
-        }
-
-        JSArray permissions = new JSArray();
-        for (String permission : service.getUngrantedPermissions()) {
-            permissions.put(permission);
+            WatsonService service = buildService(call);
+            JSArray permissions = new JSArray();
+            for (String permission : service.getUngrantedPermissions()) {
+                permissions.put(permission);
+            }
+            JSObject ret = new JSObject();
+            ret.put("permissions", permissions);
+            call.resolve(ret);
+        } catch (WatsonCallException e) {
+            call.reject(e.getMessage(), e.code);
+        } catch (Exception e) {
+            call.reject(messageOf(e), ERROR_INTERNAL, e);
         }
-        JSObject ret = new JSObject();
-        ret.put("permissions", permissions);
-        call.resolve(ret);
     }
 
     /**
@@ -93,12 +119,9 @@ public class WatsonCorePlugin extends Plugin {
      * {@link #load()}) so every collector plugin has already registered its factory in the core's
      * registry by the time collection runs.
      */
-    private WatsonService buildService(PluginCall call) throws JSONException {
+    private WatsonService buildService(PluginCall call) throws WatsonCallException {
         WatsonService.Builder builder = new WatsonService.Builder(getContext());
-        JSArray ids = call.getArray("collectors", new JSArray());
-        List<String> idList = ids.toList();
-        for (String id : idList) {
-            // Resolves via the core's WatsonRegistry; throws if the matching module is not installed.
+        for (String id : collectorIds(call)) {
             builder.addCollector(id);
         }
         WatsonService service = builder
@@ -110,25 +133,95 @@ public class WatsonCorePlugin extends Plugin {
     }
 
     /**
-     * Fires the Capacitor permission prompt for {@code aliases} and remembers {@code onComplete} so
-     * {@link #handleWatsonPermissions(PluginCall)} can resume the parked collection. Called only by
-     * {@link CapacitorPermissionRequester}.
+     * The {@code collectors} option, validated: an array of non-empty strings, each with a native
+     * module registered in the core. Checked up front so a missing module becomes a clear rejection
+     * instead of an exception from the core's registry.
+     */
+    private static List<String> collectorIds(PluginCall call) throws WatsonCallException {
+        Object raw = call.getData().opt("collectors");
+        List<String> ids = new ArrayList<>();
+        if (raw == null) {
+            return ids;
+        }
+        if (!(raw instanceof JSONArray)) {
+            throw new WatsonCallException(ERROR_INVALID_ARGUMENT,
+                "'collectors' must be an array of collector ids.");
+        }
+        JSONArray array = (JSONArray) raw;
+        for (int i = 0; i < array.length(); i++) {
+            Object id = array.opt(i);
+            if (!(id instanceof String) || ((String) id).isEmpty()) {
+                throw new WatsonCallException(ERROR_INVALID_ARGUMENT,
+                    "'collectors' must contain only non-empty strings; item " + i + " is " + id + ".");
+            }
+            if (!WatsonRegistry.isRegistered((String) id)) {
+                throw new WatsonCallException(ERROR_COLLECTOR_NOT_INSTALLED,
+                    "No Watson collector is installed for id '" + id + "'. Install its Capacitor "
+                        + "package (@quipuscore/watson-" + id + "-capacitor) and run "
+                        + "`npx cap sync android`.");
+            }
+            ids.add((String) id);
+        }
+        return ids;
+    }
+
+    /**
+     * Queues the Capacitor permission prompt for {@code aliases}; {@code onComplete} resumes the parked
+     * collection once the user has answered. Called only by {@link CapacitorPermissionRequester}.
      */
     void promptForAliases(String[] aliases, PluginCall call, PermissionResultCallback onComplete) {
-        this.pendingPermissionCallback = onComplete;
-        requestPermissionForAliases(aliases, call, "handleWatsonPermissions");
+        PendingPrompt next = null;
+        synchronized (queuedPrompts) {
+            queuedPrompts.add(new PendingPrompt(aliases, call, onComplete));
+            if (activePrompt == null) {
+                activePrompt = queuedPrompts.poll();
+                next = activePrompt;
+            }
+        }
+        if (next != null) {
+            launch(next);
+        }
     }
 
     @PermissionCallback
     private void handleWatsonPermissions(PluginCall call) {
-        PermissionResultCallback callback = this.pendingPermissionCallback;
-        this.pendingPermissionCallback = null;
-        if (callback != null) {
+        // Only one prompt is ever in flight, so this result answers the active one; Capacitor's own
+        // saved-call queue is in the same order.
+        finishActivePrompt();
+    }
+
+    /** Resumes the run whose prompt just ended and opens the next queued prompt, if any. */
+    private void finishActivePrompt() {
+        PendingPrompt finished;
+        PendingPrompt next;
+        synchronized (queuedPrompts) {
+            finished = activePrompt;
+            activePrompt = queuedPrompts.poll();
+            next = activePrompt;
+        }
+        if (finished != null) {
             // The core re-reads live grant state per collector; no results are carried back here.
-            callback.onPermissionsResolved();
+            finished.onComplete.onPermissionsResolved();
+        }
+        if (next != null) {
+            launch(next);
+        }
+    }
+
+    private void launch(PendingPrompt prompt) {
+        try {
+            requestPermissionForAliases(prompt.aliases, prompt.call, "handleWatsonPermissions");
+        } catch (RuntimeException e) {
+            // The dialog never opened: let that run go on (the core gates what is still missing)
+            // and keep the queue moving rather than leaving every later prompt waiting.
+            finishActivePrompt();
         }
     }
 
+    private static String messageOf(Exception e) {
+        return e.getMessage() != null ? e.getMessage() : e.getClass().getSimpleName();
+    }
+
     private JSObject toJs(CollectionResult result) {
         JSObject res = new JSObject();
         res.put("data", result.getData());
@@ -153,4 +246,27 @@ public class WatsonCorePlugin extends Plugin {
         res.put("outcomes", outcomes);
         return res;
     }
+
+    /** One permission prompt waiting for its turn, with the run it resumes. */
+    private static final class PendingPrompt {
+        final String[] aliases;
+        final PluginCall call;
+        final PermissionResultCallback onComplete;
+
+        PendingPrompt(String[] aliases, PluginCall call, PermissionResultCallback onComplete) {
+            this.aliases = aliases;
+            this.call = call;
+            this.onComplete = onComplete;
+        }
+    }
+
+    /** A rejection with a stable code, raised before the native service is built. */
+    private static final class WatsonCallException extends Exception {
+        final String code;
+
+        WatsonCallException(String code, String message) {
+            super(message);
+            this.code = code;
+        }
+    }
 }

package/dist/esm/definitions.d.ts

@@ -25,6 +25,22 @@ export interface CollectionResult {
     /** Per-collector outcomes, including the ones that were skipped or failed. */
     outcomes: CollectorOutcome[];
 }
+/**
+ * Stable `code` of the errors the native plugin rejects with, so callers can branch on
+ * `error.code` instead of parsing messages.
+ */
+export declare const WatsonErrorCode: {
+    /** The `collectors` option is not an array of non-empty strings. */
+    readonly INVALID_ARGUMENT: "WATSON_INVALID_ARGUMENT";
+    /**
+     * A collector was added in JS but its native module is not in the running app: its package is not
+     * installed or `npx cap sync android` was not run.
+     */
+    readonly COLLECTOR_NOT_INSTALLED: "WATSON_COLLECTOR_NOT_INSTALLED";
+    /** Any other native failure while starting the run. */
+    readonly INTERNAL: "WATSON_INTERNAL";
+};
+export type WatsonErrorCode = (typeof WatsonErrorCode)[keyof typeof WatsonErrorCode];
 /**
  * Low-level bridge contract for the native `WatsonCore` plugin. Application code should use the
  * {@link WatsonService} class instead of calling this plugin directly.

package/dist/esm/definitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,mBAAmB,GACnB,+BAA+B,GAC/B,OAAO,CAAC;AAEZ,uFAAuF;AACvF,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,eAAe,CAAC;IACxB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,YAAY,EAAE,MAAM,CAAC;IACrB,+FAA+F;IAC/F,UAAU,EAAE,OAAO,CAAC;IACpB,8EAA8E;IAC9E,QAAQ,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8FAA8F;IAC9F,OAAO,CAAC,OAAO,EAAE;QAAE,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACtE,4FAA4F;IAC5F,uBAAuB,CAAC,OAAO,EAAE;QAAE,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CAChG"}
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,mBAAmB,GACnB,+BAA+B,GAC/B,OAAO,CAAC;AAEZ,uFAAuF;AACvF,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,eAAe,CAAC;IACxB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,YAAY,EAAE,MAAM,CAAC;IACrB,+FAA+F;IAC/F,UAAU,EAAE,OAAO,CAAC;IACpB,8EAA8E;IAC9E,QAAQ,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe;IAC1B,oEAAoE;;IAEpE;;;OAGG;;IAEH,uDAAuD;;CAE/C,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAErF;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8FAA8F;IAC9F,OAAO,CAAC,OAAO,EAAE;QAAE,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACtE,4FAA4F;IAC5F,uBAAuB,CAAC,OAAO,EAAE;QAAE,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CAChG"}

package/dist/esm/definitions.js

@@ -1,2 +1,16 @@
-export {};
+/**
+ * Stable `code` of the errors the native plugin rejects with, so callers can branch on
+ * `error.code` instead of parsing messages.
+ */
+export const WatsonErrorCode = {
+    /** The `collectors` option is not an array of non-empty strings. */
+    INVALID_ARGUMENT: 'WATSON_INVALID_ARGUMENT',
+    /**
+     * A collector was added in JS but its native module is not in the running app: its package is not
+     * installed or `npx cap sync android` was not run.
+     */
+    COLLECTOR_NOT_INSTALLED: 'WATSON_COLLECTOR_NOT_INSTALLED',
+    /** Any other native failure while starting the run. */
+    INTERNAL: 'WATSON_INTERNAL',
+};
 //# sourceMappingURL=definitions.js.map

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":""}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"AAkCA;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,oEAAoE;IACpE,gBAAgB,EAAE,yBAAyB;IAC3C;;;OAGG;IACH,uBAAuB,EAAE,gCAAgC;IACzD,uDAAuD;IACvD,QAAQ,EAAE,iBAAiB;CACnB,CAAC"}

package/dist/esm/service.d.ts

@@ -4,20 +4,29 @@ import type { CollectionResult } from './definitions';
  * JS-side orchestrator, mirroring the native `WatsonService`. It accumulates the ids of the
  * collectors you add and hands that list to the native `WatsonCore` plugin on {@link collect}.
  *
- * The always-on `device` baseline is added by the native core itself; you never add it here. The
- * single structural asymmetry with the native API is that `new WatsonService()` takes no `context`
- * — the native plugin injects it.
+ * The always-on `device` baseline is added by the native core itself; you never add it here.
+ * Differences with the native Android API: `new WatsonService()` takes no `context` (the plugin
+ * injects it); the permission prompt is always delivered by the plugin, so there is no
+ * `setActivity` / `handlePermissionResult` / custom requester; `collect()` always prompts for missing
+ * permissions (no `requestPermissionsIfNeeded = false` yet); collectors run with their default
+ * configuration (no SMS `FilterConfig` or custom calendar window yet); and errors arrive as a
+ * rejected Promise instead of `onError`.
  */
 export declare class WatsonService {
     private readonly collectorIds;
     /**
-     * Registers a collector to run. Explicit by design: a collector you don't add is not collected
-     * and does not pull its runtime permission. Adding the same id twice is a no-op.
+     * Registers a collector to run. Explicit by design: a collector you don't add is not collected.
+     * Its runtime permission, though, reaches the app manifest by installing its package, whether or
+     * not you add it. Adding the same id twice is a no-op.
      */
     addCollector(collector: WatsonCollector): void;
     /**
      * Runs every added collector natively and resolves with the compressed payload and the
      * per-collector outcomes. A denied or failing collector never aborts the others.
+     *
+     * Overlapping calls (e.g. `Promise.all`) are fine: their permission prompts are shown one after
+     * the other and each call resolves with its own result. Rejects with a `WatsonErrorCode`
+     * `code` when the run cannot start, e.g. `WATSON_COLLECTOR_NOT_INSTALLED`.
      */
     collect(): Promise<CollectionResult>;
     /** The runtime permissions required by the added collectors that are not granted yet. */

package/dist/esm/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGtD;;;;;;;GAOG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgB;IAE7C;;;OAGG;IACH,YAAY,CAAC,SAAS,EAAE,eAAe,GAAG,IAAI;IAS9C;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAIpC,yFAAyF;IACnF,uBAAuB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CAMnD"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGtD;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgB;IAE7C;;;;OAIG;IACH,YAAY,CAAC,SAAS,EAAE,eAAe,GAAG,IAAI;IAS9C;;;;;;;OAOG;IACH,OAAO,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAIpC,yFAAyF;IACnF,uBAAuB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CAMnD"}

package/dist/esm/service.js

@@ -3,17 +3,22 @@ import { WatsonCore } from './plugin';
  * JS-side orchestrator, mirroring the native `WatsonService`. It accumulates the ids of the
  * collectors you add and hands that list to the native `WatsonCore` plugin on {@link collect}.
  *
- * The always-on `device` baseline is added by the native core itself; you never add it here. The
- * single structural asymmetry with the native API is that `new WatsonService()` takes no `context`
- * — the native plugin injects it.
+ * The always-on `device` baseline is added by the native core itself; you never add it here.
+ * Differences with the native Android API: `new WatsonService()` takes no `context` (the plugin
+ * injects it); the permission prompt is always delivered by the plugin, so there is no
+ * `setActivity` / `handlePermissionResult` / custom requester; `collect()` always prompts for missing
+ * permissions (no `requestPermissionsIfNeeded = false` yet); collectors run with their default
+ * configuration (no SMS `FilterConfig` or custom calendar window yet); and errors arrive as a
+ * rejected Promise instead of `onError`.
  */
 export class WatsonService {
     constructor() {
         this.collectorIds = [];
     }
     /**
-     * Registers a collector to run. Explicit by design: a collector you don't add is not collected
-     * and does not pull its runtime permission. Adding the same id twice is a no-op.
+     * Registers a collector to run. Explicit by design: a collector you don't add is not collected.
+     * Its runtime permission, though, reaches the app manifest by installing its package, whether or
+     * not you add it. Adding the same id twice is a no-op.
      */
     addCollector(collector) {
         if (!collector || !collector.id) {
@@ -26,6 +31,10 @@ export class WatsonService {
     /**
      * Runs every added collector natively and resolves with the compressed payload and the
      * per-collector outcomes. A denied or failing collector never aborts the others.
+     *
+     * Overlapping calls (e.g. `Promise.all`) are fine: their permission prompts are shown one after
+     * the other and each call resolves with its own result. Rejects with a `WatsonErrorCode`
+     * `code` when the run cannot start, e.g. `WATSON_COLLECTOR_NOT_INSTALLED`.
      */
     collect() {
         return WatsonCore.collect({ collectors: this.collectorIds });

package/dist/esm/service.js.map

@@ -1 +1 @@
-{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,OAAO,aAAa;IAA1B;QACmB,iBAAY,GAAa,EAAE,CAAC;IA8B/C,CAAC;IA5BC;;;OAGG;IACH,YAAY,CAAC,SAA0B;QACrC,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QAC3E,CAAC;QACD,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YACnD,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,OAAO;QACL,OAAO,UAAU,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,yFAAyF;IACzF,KAAK,CAAC,uBAAuB;QAC3B,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,UAAU,CAAC,uBAAuB,CAAC;YAC/D,UAAU,EAAE,IAAI,CAAC,YAAY;SAC9B,CAAC,CAAC;QACH,OAAO,WAAW,CAAC;IACrB,CAAC;CACF"}
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,aAAa;IAA1B;QACmB,iBAAY,GAAa,EAAE,CAAC;IAmC/C,CAAC;IAjCC;;;;OAIG;IACH,YAAY,CAAC,SAA0B;QACrC,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QAC3E,CAAC;QACD,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YACnD,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,OAAO;QACL,OAAO,UAAU,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,yFAAyF;IACzF,KAAK,CAAC,uBAAuB;QAC3B,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,UAAU,CAAC,uBAAuB,CAAC;YAC/D,UAAU,EAAE,IAAI,CAAC,YAAY;SAC9B,CAAC,CAAC;QACH,OAAO,WAAW,CAAC;IACrB,CAAC;CACF"}

package/dist/esm/web.js

@@ -1,5 +1,5 @@
 import { WebPlugin } from '@capacitor/core';
-const MESSAGE = 'Watson is only available on Android and iOS.';
+const MESSAGE = 'Watson is only available on Android (iOS is not implemented yet).';
 export class WatsonCoreWeb extends WebPlugin {
     async collect() {
         throw this.unimplemented(MESSAGE);

package/dist/esm/web.js.map

@@ -1 +1 @@
-{"version":3,"file":"web.js","sourceRoot":"","sources":["../../src/web.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAI5C,MAAM,OAAO,GAAG,8CAA8C,CAAC;AAE/D,MAAM,OAAO,aAAc,SAAQ,SAAS;IAC1C,KAAK,CAAC,OAAO;QACX,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,uBAAuB;QAC3B,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;CACF"}
+{"version":3,"file":"web.js","sourceRoot":"","sources":["../../src/web.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAI5C,MAAM,OAAO,GAAG,mEAAmE,CAAC;AAEpF,MAAM,OAAO,aAAc,SAAQ,SAAS;IAC1C,KAAK,CAAC,OAAO;QACX,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,uBAAuB;QAC3B,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;CACF"}

package/dist/plugin.cjs.js

@@ -2,6 +2,22 @@
 
 var core = require('@capacitor/core');
 
+/**
+ * Stable `code` of the errors the native plugin rejects with, so callers can branch on
+ * `error.code` instead of parsing messages.
+ */
+const WatsonErrorCode = {
+    /** The `collectors` option is not an array of non-empty strings. */
+    INVALID_ARGUMENT: 'WATSON_INVALID_ARGUMENT',
+    /**
+     * A collector was added in JS but its native module is not in the running app: its package is not
+     * installed or `npx cap sync android` was not run.
+     */
+    COLLECTOR_NOT_INSTALLED: 'WATSON_COLLECTOR_NOT_INSTALLED',
+    /** Any other native failure while starting the run. */
+    INTERNAL: 'WATSON_INTERNAL',
+};
+
 /**
  * Base type for a collector descriptor.
  *
@@ -25,17 +41,22 @@ const WatsonCore = core.registerPlugin('WatsonCore', {
  * JS-side orchestrator, mirroring the native `WatsonService`. It accumulates the ids of the
  * collectors you add and hands that list to the native `WatsonCore` plugin on {@link collect}.
  *
- * The always-on `device` baseline is added by the native core itself; you never add it here. The
- * single structural asymmetry with the native API is that `new WatsonService()` takes no `context`
- * — the native plugin injects it.
+ * The always-on `device` baseline is added by the native core itself; you never add it here.
+ * Differences with the native Android API: `new WatsonService()` takes no `context` (the plugin
+ * injects it); the permission prompt is always delivered by the plugin, so there is no
+ * `setActivity` / `handlePermissionResult` / custom requester; `collect()` always prompts for missing
+ * permissions (no `requestPermissionsIfNeeded = false` yet); collectors run with their default
+ * configuration (no SMS `FilterConfig` or custom calendar window yet); and errors arrive as a
+ * rejected Promise instead of `onError`.
  */
 class WatsonService {
     constructor() {
         this.collectorIds = [];
     }
     /**
-     * Registers a collector to run. Explicit by design: a collector you don't add is not collected
-     * and does not pull its runtime permission. Adding the same id twice is a no-op.
+     * Registers a collector to run. Explicit by design: a collector you don't add is not collected.
+     * Its runtime permission, though, reaches the app manifest by installing its package, whether or
+     * not you add it. Adding the same id twice is a no-op.
      */
     addCollector(collector) {
         if (!collector || !collector.id) {
@@ -48,6 +69,10 @@ class WatsonService {
     /**
      * Runs every added collector natively and resolves with the compressed payload and the
      * per-collector outcomes. A denied or failing collector never aborts the others.
+     *
+     * Overlapping calls (e.g. `Promise.all`) are fine: their permission prompts are shown one after
+     * the other and each call resolves with its own result. Rejects with a `WatsonErrorCode`
+     * `code` when the run cannot start, e.g. `WATSON_COLLECTOR_NOT_INSTALLED`.
      */
     collect() {
         return WatsonCore.collect({ collectors: this.collectorIds });
@@ -61,7 +86,7 @@ class WatsonService {
     }
 }
 
-const MESSAGE = 'Watson is only available on Android and iOS.';
+const MESSAGE = 'Watson is only available on Android (iOS is not implemented yet).';
 class WatsonCoreWeb extends core.WebPlugin {
     async collect() {
         throw this.unimplemented(MESSAGE);
@@ -78,5 +103,6 @@ var web = /*#__PURE__*/Object.freeze({
 
 exports.WatsonCollector = WatsonCollector;
 exports.WatsonCore = WatsonCore;
+exports.WatsonErrorCode = WatsonErrorCode;
 exports.WatsonService = WatsonService;
 //# sourceMappingURL=plugin.cjs.js.map

package/dist/plugin.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.cjs.js","sources":["esm/collector.js","esm/plugin.js","esm/service.js","esm/web.js"],"sourcesContent":["/**\n * Base type for a collector descriptor.\n *\n * Collector packages (for example `@quipuscore/watson-sms-capacitor`) extend this with the stable `id` their\n * native module registered with the Watson core. A descriptor carries no logic: it only tells the\n * core, across the bridge, which registered collector to run. This mirrors the explicit-registration\n * model of the native SDK — a collector you never add is never collected.\n */\nexport class WatsonCollector {\n}\n//# sourceMappingURL=collector.js.map","import { registerPlugin } from '@capacitor/core';\n/**\n * The registered native `WatsonCore` plugin proxy. Exposed for advanced use; prefer the\n * {@link WatsonService} class, which mirrors the native API surface.\n */\nexport const WatsonCore = registerPlugin('WatsonCore', {\n    web: () => import('./web').then(m => new m.WatsonCoreWeb()),\n});\n//# sourceMappingURL=plugin.js.map","import { WatsonCore } from './plugin';\n/**\n * JS-side orchestrator, mirroring the native `WatsonService`. It accumulates the ids of the\n * collectors you add and hands that list to the native `WatsonCore` plugin on {@link collect}.\n *\n * The always-on `device` baseline is added by the native core itself; you never add it here. The\n * single structural asymmetry with the native API is that `new WatsonService()` takes no `context`\n * — the native plugin injects it.\n */\nexport class WatsonService {\n    constructor() {\n        this.collectorIds = [];\n    }\n    /**\n     * Registers a collector to run. Explicit by design: a collector you don't add is not collected\n     * and does not pull its runtime permission. Adding the same id twice is a no-op.\n     */\n    addCollector(collector) {\n        if (!collector || !collector.id) {\n            throw new Error('addCollector requires a collector with a non-empty id');\n        }\n        if (this.collectorIds.indexOf(collector.id) === -1) {\n            this.collectorIds.push(collector.id);\n        }\n    }\n    /**\n     * Runs every added collector natively and resolves with the compressed payload and the\n     * per-collector outcomes. A denied or failing collector never aborts the others.\n     */\n    collect() {\n        return WatsonCore.collect({ collectors: this.collectorIds });\n    }\n    /** The runtime permissions required by the added collectors that are not granted yet. */\n    async getUngrantedPermissions() {\n        const { permissions } = await WatsonCore.getUngrantedPermissions({\n            collectors: this.collectorIds,\n        });\n        return permissions;\n    }\n}\n//# sourceMappingURL=service.js.map","import { WebPlugin } from '@capacitor/core';\nconst MESSAGE = 'Watson is only available on Android and iOS.';\nexport class WatsonCoreWeb extends WebPlugin {\n    async collect() {\n        throw this.unimplemented(MESSAGE);\n    }\n    async getUngrantedPermissions() {\n        throw this.unimplemented(MESSAGE);\n    }\n}\n//# sourceMappingURL=web.js.map"],"names":["registerPlugin","WebPlugin"],"mappings":";;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAM,eAAe,CAAC;AAC7B;;ACRA;AACA;AACA;AACA;AACY,MAAC,UAAU,GAAGA,mBAAc,CAAC,YAAY,EAAE;AACvD,IAAI,GAAG,EAAE,MAAM,mDAAe,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,aAAa,EAAE,CAAC;AAC/D,CAAC;;ACND;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAM,aAAa,CAAC;AAC3B,IAAI,WAAW,GAAG;AAClB,QAAQ,IAAI,CAAC,YAAY,GAAG,EAAE;AAC9B,IAAI;AACJ;AACA;AACA;AACA;AACA,IAAI,YAAY,CAAC,SAAS,EAAE;AAC5B,QAAQ,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE;AACzC,YAAY,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC;AACpF,QAAQ;AACR,QAAQ,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE;AAC5D,YAAY,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;AAChD,QAAQ;AACR,IAAI;AACJ;AACA;AACA;AACA;AACA,IAAI,OAAO,GAAG;AACd,QAAQ,OAAO,UAAU,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC;AACpE,IAAI;AACJ;AACA,IAAI,MAAM,uBAAuB,GAAG;AACpC,QAAQ,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,UAAU,CAAC,uBAAuB,CAAC;AACzE,YAAY,UAAU,EAAE,IAAI,CAAC,YAAY;AACzC,SAAS,CAAC;AACV,QAAQ,OAAO,WAAW;AAC1B,IAAI;AACJ;;ACtCA,MAAM,OAAO,GAAG,8CAA8C;AACvD,MAAM,aAAa,SAASC,cAAS,CAAC;AAC7C,IAAI,MAAM,OAAO,GAAG;AACpB,QAAQ,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC;AACzC,IAAI;AACJ,IAAI,MAAM,uBAAuB,GAAG;AACpC,QAAQ,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC;AACzC,IAAI;AACJ;;;;;;;;;;;"}
+{"version":3,"file":"plugin.cjs.js","sources":["esm/definitions.js","esm/collector.js","esm/plugin.js","esm/service.js","esm/web.js"],"sourcesContent":["/**\n * Stable `code` of the errors the native plugin rejects with, so callers can branch on\n * `error.code` instead of parsing messages.\n */\nexport const WatsonErrorCode = {\n    /** The `collectors` option is not an array of non-empty strings. */\n    INVALID_ARGUMENT: 'WATSON_INVALID_ARGUMENT',\n    /**\n     * A collector was added in JS but its native module is not in the running app: its package is not\n     * installed or `npx cap sync android` was not run.\n     */\n    COLLECTOR_NOT_INSTALLED: 'WATSON_COLLECTOR_NOT_INSTALLED',\n    /** Any other native failure while starting the run. */\n    INTERNAL: 'WATSON_INTERNAL',\n};\n//# sourceMappingURL=definitions.js.map","/**\n * Base type for a collector descriptor.\n *\n * Collector packages (for example `@quipuscore/watson-sms-capacitor`) extend this with the stable `id` their\n * native module registered with the Watson core. A descriptor carries no logic: it only tells the\n * core, across the bridge, which registered collector to run. This mirrors the explicit-registration\n * model of the native SDK — a collector you never add is never collected.\n */\nexport class WatsonCollector {\n}\n//# sourceMappingURL=collector.js.map","import { registerPlugin } from '@capacitor/core';\n/**\n * The registered native `WatsonCore` plugin proxy. Exposed for advanced use; prefer the\n * {@link WatsonService} class, which mirrors the native API surface.\n */\nexport const WatsonCore = registerPlugin('WatsonCore', {\n    web: () => import('./web').then(m => new m.WatsonCoreWeb()),\n});\n//# sourceMappingURL=plugin.js.map","import { WatsonCore } from './plugin';\n/**\n * JS-side orchestrator, mirroring the native `WatsonService`. It accumulates the ids of the\n * collectors you add and hands that list to the native `WatsonCore` plugin on {@link collect}.\n *\n * The always-on `device` baseline is added by the native core itself; you never add it here.\n * Differences with the native Android API: `new WatsonService()` takes no `context` (the plugin\n * injects it); the permission prompt is always delivered by the plugin, so there is no\n * `setActivity` / `handlePermissionResult` / custom requester; `collect()` always prompts for missing\n * permissions (no `requestPermissionsIfNeeded = false` yet); collectors run with their default\n * configuration (no SMS `FilterConfig` or custom calendar window yet); and errors arrive as a\n * rejected Promise instead of `onError`.\n */\nexport class WatsonService {\n    constructor() {\n        this.collectorIds = [];\n    }\n    /**\n     * Registers a collector to run. Explicit by design: a collector you don't add is not collected.\n     * Its runtime permission, though, reaches the app manifest by installing its package, whether or\n     * not you add it. Adding the same id twice is a no-op.\n     */\n    addCollector(collector) {\n        if (!collector || !collector.id) {\n            throw new Error('addCollector requires a collector with a non-empty id');\n        }\n        if (this.collectorIds.indexOf(collector.id) === -1) {\n            this.collectorIds.push(collector.id);\n        }\n    }\n    /**\n     * Runs every added collector natively and resolves with the compressed payload and the\n     * per-collector outcomes. A denied or failing collector never aborts the others.\n     *\n     * Overlapping calls (e.g. `Promise.all`) are fine: their permission prompts are shown one after\n     * the other and each call resolves with its own result. Rejects with a `WatsonErrorCode`\n     * `code` when the run cannot start, e.g. `WATSON_COLLECTOR_NOT_INSTALLED`.\n     */\n    collect() {\n        return WatsonCore.collect({ collectors: this.collectorIds });\n    }\n    /** The runtime permissions required by the added collectors that are not granted yet. */\n    async getUngrantedPermissions() {\n        const { permissions } = await WatsonCore.getUngrantedPermissions({\n            collectors: this.collectorIds,\n        });\n        return permissions;\n    }\n}\n//# sourceMappingURL=service.js.map","import { WebPlugin } from '@capacitor/core';\nconst MESSAGE = 'Watson is only available on Android (iOS is not implemented yet).';\nexport class WatsonCoreWeb extends WebPlugin {\n    async collect() {\n        throw this.unimplemented(MESSAGE);\n    }\n    async getUngrantedPermissions() {\n        throw this.unimplemented(MESSAGE);\n    }\n}\n//# sourceMappingURL=web.js.map"],"names":["registerPlugin","WebPlugin"],"mappings":";;;;AAAA;AACA;AACA;AACA;AACY,MAAC,eAAe,GAAG;AAC/B;AACA,IAAI,gBAAgB,EAAE,yBAAyB;AAC/C;AACA;AACA;AACA;AACA,IAAI,uBAAuB,EAAE,gCAAgC;AAC7D;AACA,IAAI,QAAQ,EAAE,iBAAiB;AAC/B;;ACdA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAM,eAAe,CAAC;AAC7B;;ACRA;AACA;AACA;AACA;AACY,MAAC,UAAU,GAAGA,mBAAc,CAAC,YAAY,EAAE;AACvD,IAAI,GAAG,EAAE,MAAM,mDAAe,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,aAAa,EAAE,CAAC;AAC/D,CAAC;;ACND;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAM,aAAa,CAAC;AAC3B,IAAI,WAAW,GAAG;AAClB,QAAQ,IAAI,CAAC,YAAY,GAAG,EAAE;AAC9B,IAAI;AACJ;AACA;AACA;AACA;AACA;AACA,IAAI,YAAY,CAAC,SAAS,EAAE;AAC5B,QAAQ,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE;AACzC,YAAY,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC;AACpF,QAAQ;AACR,QAAQ,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE;AAC5D,YAAY,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;AAChD,QAAQ;AACR,IAAI;AACJ;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,IAAI,OAAO,GAAG;AACd,QAAQ,OAAO,UAAU,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC;AACpE,IAAI;AACJ;AACA,IAAI,MAAM,uBAAuB,GAAG;AACpC,QAAQ,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,UAAU,CAAC,uBAAuB,CAAC;AACzE,YAAY,UAAU,EAAE,IAAI,CAAC,YAAY;AACzC,SAAS,CAAC;AACV,QAAQ,OAAO,WAAW;AAC1B,IAAI;AACJ;;AC/CA,MAAM,OAAO,GAAG,mEAAmE;AAC5E,MAAM,aAAa,SAASC,cAAS,CAAC;AAC7C,IAAI,MAAM,OAAO,GAAG;AACpB,QAAQ,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC;AACzC,IAAI;AACJ,IAAI,MAAM,uBAAuB,GAAG;AACpC,QAAQ,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC;AACzC,IAAI;AACJ;;;;;;;;;;;;"}

package/dist/plugin.js

@@ -1,6 +1,22 @@
 var capacitorWatsonCore = (function (exports, core) {
     'use strict';
 
+    /**
+     * Stable `code` of the errors the native plugin rejects with, so callers can branch on
+     * `error.code` instead of parsing messages.
+     */
+    const WatsonErrorCode = {
+        /** The `collectors` option is not an array of non-empty strings. */
+        INVALID_ARGUMENT: 'WATSON_INVALID_ARGUMENT',
+        /**
+         * A collector was added in JS but its native module is not in the running app: its package is not
+         * installed or `npx cap sync android` was not run.
+         */
+        COLLECTOR_NOT_INSTALLED: 'WATSON_COLLECTOR_NOT_INSTALLED',
+        /** Any other native failure while starting the run. */
+        INTERNAL: 'WATSON_INTERNAL',
+    };
+
     /**
      * Base type for a collector descriptor.
      *
@@ -24,17 +40,22 @@ var capacitorWatsonCore = (function (exports, core) {
      * JS-side orchestrator, mirroring the native `WatsonService`. It accumulates the ids of the
      * collectors you add and hands that list to the native `WatsonCore` plugin on {@link collect}.
      *
-     * The always-on `device` baseline is added by the native core itself; you never add it here. The
-     * single structural asymmetry with the native API is that `new WatsonService()` takes no `context`
-     * — the native plugin injects it.
+     * The always-on `device` baseline is added by the native core itself; you never add it here.
+     * Differences with the native Android API: `new WatsonService()` takes no `context` (the plugin
+     * injects it); the permission prompt is always delivered by the plugin, so there is no
+     * `setActivity` / `handlePermissionResult` / custom requester; `collect()` always prompts for missing
+     * permissions (no `requestPermissionsIfNeeded = false` yet); collectors run with their default
+     * configuration (no SMS `FilterConfig` or custom calendar window yet); and errors arrive as a
+     * rejected Promise instead of `onError`.
      */
     class WatsonService {
         constructor() {
             this.collectorIds = [];
         }
         /**
-         * Registers a collector to run. Explicit by design: a collector you don't add is not collected
-         * and does not pull its runtime permission. Adding the same id twice is a no-op.
+         * Registers a collector to run. Explicit by design: a collector you don't add is not collected.
+         * Its runtime permission, though, reaches the app manifest by installing its package, whether or
+         * not you add it. Adding the same id twice is a no-op.
          */
         addCollector(collector) {
             if (!collector || !collector.id) {
@@ -47,6 +68,10 @@ var capacitorWatsonCore = (function (exports, core) {
         /**
          * Runs every added collector natively and resolves with the compressed payload and the
          * per-collector outcomes. A denied or failing collector never aborts the others.
+         *
+         * Overlapping calls (e.g. `Promise.all`) are fine: their permission prompts are shown one after
+         * the other and each call resolves with its own result. Rejects with a `WatsonErrorCode`
+         * `code` when the run cannot start, e.g. `WATSON_COLLECTOR_NOT_INSTALLED`.
          */
         collect() {
             return WatsonCore.collect({ collectors: this.collectorIds });
@@ -60,7 +85,7 @@ var capacitorWatsonCore = (function (exports, core) {
         }
     }
 
-    const MESSAGE = 'Watson is only available on Android and iOS.';
+    const MESSAGE = 'Watson is only available on Android (iOS is not implemented yet).';
     class WatsonCoreWeb extends core.WebPlugin {
         async collect() {
             throw this.unimplemented(MESSAGE);
@@ -77,6 +102,7 @@ var capacitorWatsonCore = (function (exports, core) {
 
     exports.WatsonCollector = WatsonCollector;
     exports.WatsonCore = WatsonCore;
+    exports.WatsonErrorCode = WatsonErrorCode;
     exports.WatsonService = WatsonService;
 
     return exports;

package/dist/plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.js","sources":["esm/collector.js","esm/plugin.js","esm/service.js","esm/web.js"],"sourcesContent":["/**\n * Base type for a collector descriptor.\n *\n * Collector packages (for example `@quipuscore/watson-sms-capacitor`) extend this with the stable `id` their\n * native module registered with the Watson core. A descriptor carries no logic: it only tells the\n * core, across the bridge, which registered collector to run. This mirrors the explicit-registration\n * model of the native SDK — a collector you never add is never collected.\n */\nexport class WatsonCollector {\n}\n//# sourceMappingURL=collector.js.map","import { registerPlugin } from '@capacitor/core';\n/**\n * The registered native `WatsonCore` plugin proxy. Exposed for advanced use; prefer the\n * {@link WatsonService} class, which mirrors the native API surface.\n */\nexport const WatsonCore = registerPlugin('WatsonCore', {\n    web: () => import('./web').then(m => new m.WatsonCoreWeb()),\n});\n//# sourceMappingURL=plugin.js.map","import { WatsonCore } from './plugin';\n/**\n * JS-side orchestrator, mirroring the native `WatsonService`. It accumulates the ids of the\n * collectors you add and hands that list to the native `WatsonCore` plugin on {@link collect}.\n *\n * The always-on `device` baseline is added by the native core itself; you never add it here. The\n * single structural asymmetry with the native API is that `new WatsonService()` takes no `context`\n * — the native plugin injects it.\n */\nexport class WatsonService {\n    constructor() {\n        this.collectorIds = [];\n    }\n    /**\n     * Registers a collector to run. Explicit by design: a collector you don't add is not collected\n     * and does not pull its runtime permission. Adding the same id twice is a no-op.\n     */\n    addCollector(collector) {\n        if (!collector || !collector.id) {\n            throw new Error('addCollector requires a collector with a non-empty id');\n        }\n        if (this.collectorIds.indexOf(collector.id) === -1) {\n            this.collectorIds.push(collector.id);\n        }\n    }\n    /**\n     * Runs every added collector natively and resolves with the compressed payload and the\n     * per-collector outcomes. A denied or failing collector never aborts the others.\n     */\n    collect() {\n        return WatsonCore.collect({ collectors: this.collectorIds });\n    }\n    /** The runtime permissions required by the added collectors that are not granted yet. */\n    async getUngrantedPermissions() {\n        const { permissions } = await WatsonCore.getUngrantedPermissions({\n            collectors: this.collectorIds,\n        });\n        return permissions;\n    }\n}\n//# sourceMappingURL=service.js.map","import { WebPlugin } from '@capacitor/core';\nconst MESSAGE = 'Watson is only available on Android and iOS.';\nexport class WatsonCoreWeb extends WebPlugin {\n    async collect() {\n        throw this.unimplemented(MESSAGE);\n    }\n    async getUngrantedPermissions() {\n        throw this.unimplemented(MESSAGE);\n    }\n}\n//# sourceMappingURL=web.js.map"],"names":["registerPlugin","WebPlugin"],"mappings":";;;IAAA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACO,MAAM,eAAe,CAAC;IAC7B;;ICRA;IACA;IACA;IACA;AACY,UAAC,UAAU,GAAGA,mBAAc,CAAC,YAAY,EAAE;IACvD,IAAI,GAAG,EAAE,MAAM,mDAAe,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,aAAa,EAAE,CAAC;IAC/D,CAAC;;ICND;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACO,MAAM,aAAa,CAAC;IAC3B,IAAI,WAAW,GAAG;IAClB,QAAQ,IAAI,CAAC,YAAY,GAAG,EAAE;IAC9B,IAAI;IACJ;IACA;IACA;IACA;IACA,IAAI,YAAY,CAAC,SAAS,EAAE;IAC5B,QAAQ,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE;IACzC,YAAY,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC;IACpF,QAAQ;IACR,QAAQ,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE;IAC5D,YAAY,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;IAChD,QAAQ;IACR,IAAI;IACJ;IACA;IACA;IACA;IACA,IAAI,OAAO,GAAG;IACd,QAAQ,OAAO,UAAU,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC;IACpE,IAAI;IACJ;IACA,IAAI,MAAM,uBAAuB,GAAG;IACpC,QAAQ,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,UAAU,CAAC,uBAAuB,CAAC;IACzE,YAAY,UAAU,EAAE,IAAI,CAAC,YAAY;IACzC,SAAS,CAAC;IACV,QAAQ,OAAO,WAAW;IAC1B,IAAI;IACJ;;ICtCA,MAAM,OAAO,GAAG,8CAA8C;IACvD,MAAM,aAAa,SAASC,cAAS,CAAC;IAC7C,IAAI,MAAM,OAAO,GAAG;IACpB,QAAQ,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC;IACzC,IAAI;IACJ,IAAI,MAAM,uBAAuB,GAAG;IACpC,QAAQ,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC;IACzC,IAAI;IACJ;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"plugin.js","sources":["esm/definitions.js","esm/collector.js","esm/plugin.js","esm/service.js","esm/web.js"],"sourcesContent":["/**\n * Stable `code` of the errors the native plugin rejects with, so callers can branch on\n * `error.code` instead of parsing messages.\n */\nexport const WatsonErrorCode = {\n    /** The `collectors` option is not an array of non-empty strings. */\n    INVALID_ARGUMENT: 'WATSON_INVALID_ARGUMENT',\n    /**\n     * A collector was added in JS but its native module is not in the running app: its package is not\n     * installed or `npx cap sync android` was not run.\n     */\n    COLLECTOR_NOT_INSTALLED: 'WATSON_COLLECTOR_NOT_INSTALLED',\n    /** Any other native failure while starting the run. */\n    INTERNAL: 'WATSON_INTERNAL',\n};\n//# sourceMappingURL=definitions.js.map","/**\n * Base type for a collector descriptor.\n *\n * Collector packages (for example `@quipuscore/watson-sms-capacitor`) extend this with the stable `id` their\n * native module registered with the Watson core. A descriptor carries no logic: it only tells the\n * core, across the bridge, which registered collector to run. This mirrors the explicit-registration\n * model of the native SDK — a collector you never add is never collected.\n */\nexport class WatsonCollector {\n}\n//# sourceMappingURL=collector.js.map","import { registerPlugin } from '@capacitor/core';\n/**\n * The registered native `WatsonCore` plugin proxy. Exposed for advanced use; prefer the\n * {@link WatsonService} class, which mirrors the native API surface.\n */\nexport const WatsonCore = registerPlugin('WatsonCore', {\n    web: () => import('./web').then(m => new m.WatsonCoreWeb()),\n});\n//# sourceMappingURL=plugin.js.map","import { WatsonCore } from './plugin';\n/**\n * JS-side orchestrator, mirroring the native `WatsonService`. It accumulates the ids of the\n * collectors you add and hands that list to the native `WatsonCore` plugin on {@link collect}.\n *\n * The always-on `device` baseline is added by the native core itself; you never add it here.\n * Differences with the native Android API: `new WatsonService()` takes no `context` (the plugin\n * injects it); the permission prompt is always delivered by the plugin, so there is no\n * `setActivity` / `handlePermissionResult` / custom requester; `collect()` always prompts for missing\n * permissions (no `requestPermissionsIfNeeded = false` yet); collectors run with their default\n * configuration (no SMS `FilterConfig` or custom calendar window yet); and errors arrive as a\n * rejected Promise instead of `onError`.\n */\nexport class WatsonService {\n    constructor() {\n        this.collectorIds = [];\n    }\n    /**\n     * Registers a collector to run. Explicit by design: a collector you don't add is not collected.\n     * Its runtime permission, though, reaches the app manifest by installing its package, whether or\n     * not you add it. Adding the same id twice is a no-op.\n     */\n    addCollector(collector) {\n        if (!collector || !collector.id) {\n            throw new Error('addCollector requires a collector with a non-empty id');\n        }\n        if (this.collectorIds.indexOf(collector.id) === -1) {\n            this.collectorIds.push(collector.id);\n        }\n    }\n    /**\n     * Runs every added collector natively and resolves with the compressed payload and the\n     * per-collector outcomes. A denied or failing collector never aborts the others.\n     *\n     * Overlapping calls (e.g. `Promise.all`) are fine: their permission prompts are shown one after\n     * the other and each call resolves with its own result. Rejects with a `WatsonErrorCode`\n     * `code` when the run cannot start, e.g. `WATSON_COLLECTOR_NOT_INSTALLED`.\n     */\n    collect() {\n        return WatsonCore.collect({ collectors: this.collectorIds });\n    }\n    /** The runtime permissions required by the added collectors that are not granted yet. */\n    async getUngrantedPermissions() {\n        const { permissions } = await WatsonCore.getUngrantedPermissions({\n            collectors: this.collectorIds,\n        });\n        return permissions;\n    }\n}\n//# sourceMappingURL=service.js.map","import { WebPlugin } from '@capacitor/core';\nconst MESSAGE = 'Watson is only available on Android (iOS is not implemented yet).';\nexport class WatsonCoreWeb extends WebPlugin {\n    async collect() {\n        throw this.unimplemented(MESSAGE);\n    }\n    async getUngrantedPermissions() {\n        throw this.unimplemented(MESSAGE);\n    }\n}\n//# sourceMappingURL=web.js.map"],"names":["registerPlugin","WebPlugin"],"mappings":";;;IAAA;IACA;IACA;IACA;AACY,UAAC,eAAe,GAAG;IAC/B;IACA,IAAI,gBAAgB,EAAE,yBAAyB;IAC/C;IACA;IACA;IACA;IACA,IAAI,uBAAuB,EAAE,gCAAgC;IAC7D;IACA,IAAI,QAAQ,EAAE,iBAAiB;IAC/B;;ICdA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACO,MAAM,eAAe,CAAC;IAC7B;;ICRA;IACA;IACA;IACA;AACY,UAAC,UAAU,GAAGA,mBAAc,CAAC,YAAY,EAAE;IACvD,IAAI,GAAG,EAAE,MAAM,mDAAe,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,aAAa,EAAE,CAAC;IAC/D,CAAC;;ICND;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACO,MAAM,aAAa,CAAC;IAC3B,IAAI,WAAW,GAAG;IAClB,QAAQ,IAAI,CAAC,YAAY,GAAG,EAAE;IAC9B,IAAI;IACJ;IACA;IACA;IACA;IACA;IACA,IAAI,YAAY,CAAC,SAAS,EAAE;IAC5B,QAAQ,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE;IACzC,YAAY,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC;IACpF,QAAQ;IACR,QAAQ,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE;IAC5D,YAAY,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;IAChD,QAAQ;IACR,IAAI;IACJ;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA,IAAI,OAAO,GAAG;IACd,QAAQ,OAAO,UAAU,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC;IACpE,IAAI;IACJ;IACA,IAAI,MAAM,uBAAuB,GAAG;IACpC,QAAQ,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,UAAU,CAAC,uBAAuB,CAAC;IACzE,YAAY,UAAU,EAAE,IAAI,CAAC,YAAY;IACzC,SAAS,CAAC;IACV,QAAQ,OAAO,WAAW;IAC1B,IAAI;IACJ;;IC/CA,MAAM,OAAO,GAAG,mEAAmE;IAC5E,MAAM,aAAa,SAASC,cAAS,CAAC;IAC7C,IAAI,MAAM,OAAO,GAAG;IACpB,QAAQ,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC;IACzC,IAAI;IACJ,IAAI,MAAM,uBAAuB,GAAG;IACpC,QAAQ,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC;IACzC,IAAI;IACJ;;;;;;;;;;;;;;;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quipuscore/watson-core-capacitor",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Capacitor wrapper for the Watson core SDK: orchestrator + always-on device baseline.",
   "license": "UNLICENSED",
   "main": "dist/plugin.cjs.js",