@absolutejs/sync-capacitor 0.2.0 → 0.3.0

package/AbsoluteSyncCapacitor.podspec

@@ -0,0 +1,13 @@
+Pod::Spec.new do |s|
+  s.name = 'AbsoluteSyncCapacitor'
+  s.version = '0.3.0'
+  s.summary = 'Durable foreground and background Sync for AbsoluteJS Capacitor apps.'
+  s.license = 'Apache-2.0'
+  s.homepage = 'https://github.com/absolutejs/sync-adapters'
+  s.author = 'Alex Kahn'
+  s.source = { :git => 'https://github.com/absolutejs/sync-adapters.git', :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.ios.deployment_target = '15.0'
+  s.dependency 'Capacitor'
+  s.dependency 'AbsoluteDevicesCapacitor'
+end

package/Package.swift

@@ -0,0 +1,27 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "AbsoluteSyncCapacitor",
+    platforms: [.iOS(.v15)],
+    products: [.library(name: "AbsoluteSyncCapacitor", targets: ["AbsoluteSyncCapacitor"])],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0"),
+        // Both plugins are direct app dependencies. Resolving the sibling npm
+        // package keeps SwiftPM on the same installed devices-capacitor build
+        // that Capacitor discovered, instead of treating a monorepo subfolder
+        // as a nonexistent root Swift package.
+        .package(name: "AbsoluteDevicesCapacitor", path: "../devices-capacitor")
+    ],
+    targets: [
+        .target(
+            name: "AbsoluteSyncCapacitor",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "AbsoluteDevicesCapacitor", package: "AbsoluteDevicesCapacitor")
+            ],
+            path: "ios/Sources/AbsoluteSyncCapacitor",
+            linkerSettings: [.linkedLibrary("sqlite3")]
+        )
+    ]
+)

package/README.md

@@ -42,6 +42,48 @@ issuer, public client ID, and subject. Signing out locks that partition by
 removing it from the active runtime; it does not silently destroy offline data.
 Signing back in as the same verified principal unlocks the same partition.
 
+## Managed native background Sync
+
+AbsoluteJS also configures `AbsoluteBackgroundSync` when the application uses
+both `@absolutejs/auth` and `@absolutejs/sync`. The native worker is deliberately
+finite: Android WorkManager or iOS `BGProcessingTask` wakes it, it refreshes a
+short-lived access token, pushes a bounded durable outbox batch, pulls the
+foreground client's persisted collection descriptors, commits the response to
+the same SQLite database, and exits. Foreground/resume Sync remains the
+correctness path because neither operating system guarantees when background
+work will run.
+
+The worker does not run application JavaScript and does not expose Capacitor
+APIs to a background WebView. Its credential and network boundary is fixed:
+
+- the OAuth refresh token is read from the shared native Keychain/Keystore
+  vault and sent only to the issuer-advertised HTTPS token endpoint;
+- the resulting bearer token, mutation arguments, and collection parameters
+  are sent only to the configured same-origin AbsoluteJS endpoint;
+- redirects fail closed, and response bodies are bounded before parsing;
+- a rotated refresh token is written back to the vault, while returned Sync
+  data is written only to the principal's SQLite partition.
+
+Direct Capacitor applications can configure the worker after resolving a
+verified principal:
+
+```ts
+import { configureCapacitorBackgroundSync } from '@absolutejs/sync-capacitor';
+
+await configureCapacitorBackgroundSync({
+	issuer: 'https://app.example.com',
+	clientId: 'mobile-public-client',
+	endpoint: 'https://app.example.com/__absolute/sync/background',
+	namespace: authenticatedPrincipalNamespace
+});
+```
+
+Call `AbsoluteBackgroundSync.clear()` on sign-out. On iOS, register
+`AbsoluteBackgroundSyncPlugin.registerBackgroundTask()` during application
+launch and list `<bundle-id>.absolutejs.background-sync` in
+`BGTaskSchedulerPermittedIdentifiers`; the AbsoluteJS mobile CLI owns those
+generated regions. Android scheduling is registered by the plugin.
+
 ## Platform notes
 
 - Native Android and iOS use SQLCipher through
@@ -51,6 +93,10 @@ Signing back in as the same verified principal unlocks the same partition.
   `@absolutejs/sync/client`; they do not need the plugin's WASM/web component.
 - The adapter serializes transactions so an app cannot overlap two explicit
   transactions on the same Capacitor connection.
+- The native iOS worker currently targets the SQLite plugin's default Documents
+  location. Applications that override `CapacitorSQLite.iosDatabaseLocation`
+  must keep foreground and background database locations aligned before
+  enabling managed background Sync.
 
 ## License
 

package/android/build.gradle

@@ -0,0 +1,30 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+}
+
+buildscript {
+    repositories { google(); mavenCentral() }
+    dependencies { classpath 'com.android.tools.build:gradle:8.7.2' }
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    namespace "js.absolute.sync"
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 35
+    defaultConfig {
+        minSdk project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
+        targetSdk project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 35
+        versionCode 1
+        versionName "0.3.0"
+    }
+}
+
+repositories { google(); mavenCentral() }
+
+dependencies {
+    implementation project(':capacitor-android')
+    implementation project(':absolutejs-devices-capacitor')
+    implementation 'androidx.work:work-runtime:2.10.1'
+    testImplementation "junit:junit:$junitVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.INTERNET" />
+</manifest>

package/android/src/main/java/js/absolute/sync/AbsoluteBackgroundSyncConfig.java

@@ -0,0 +1,61 @@
+package js.absolute.sync;
+
+import android.content.Context;
+import android.content.SharedPreferences;
+import java.net.URI;
+import org.json.JSONException;
+import org.json.JSONObject;
+
+final class AbsoluteBackgroundSyncConfig {
+    static final String PREFERENCES = "absolutejs-background-sync";
+    static final String CONFIG = "config";
+    static final String WORK_NAME = "absolutejs-background-sync";
+    static final String REFRESH_KEY = "absolutejs.auth.oidc.refresh";
+    final String endpoint, issuer, clientId, namespace, databaseName;
+    final int intervalMinutes, maxMutations, maxPulls, maxAttempts;
+
+    AbsoluteBackgroundSyncConfig(JSONObject value) throws Exception {
+        endpoint = requireUrl(value, "endpoint", false);
+        issuer = requireUrl(value, "issuer", true);
+		if (!sameOrigin(new URI(endpoint), new URI(issuer))) throw new IllegalArgumentException("endpoint must use the Auth issuer origin.");
+        clientId = requireText(value, "clientId");
+        namespace = requireText(value, "namespace");
+        databaseName = value.optString("databaseName", "absolutejs-sync-local-v1");
+		if (!databaseName.matches("[A-Za-z0-9._-]{1,128}")) throw new IllegalArgumentException("databaseName is invalid.");
+        intervalMinutes = bounded(value.optInt("intervalMinutes", 15), 15, 1440, "intervalMinutes");
+        maxMutations = bounded(value.optInt("maxMutations", 50), 0, 100, "maxMutations");
+        maxPulls = bounded(value.optInt("maxPulls", 50), 0, 100, "maxPulls");
+        maxAttempts = bounded(value.optInt("maxAttempts", 5), 1, 100, "maxAttempts");
+    }
+	private static boolean sameOrigin(URI left, URI right) {
+		int leftPort = left.getPort() == -1 ? ("https".equals(left.getScheme()) ? 443 : 80) : left.getPort();
+		int rightPort = right.getPort() == -1 ? ("https".equals(right.getScheme()) ? 443 : 80) : right.getPort();
+		return left.getScheme().equals(right.getScheme()) && left.getHost().equalsIgnoreCase(right.getHost()) && leftPort == rightPort;
+	}
+    private static int bounded(int value, int min, int max, String name) {
+        if (value < min || value > max) throw new IllegalArgumentException(name + " is out of range.");
+        return value;
+    }
+    private static String requireText(JSONObject value, String name) throws JSONException {
+        String text = value.getString(name).trim();
+        if (text.isEmpty() || text.length() > 2048) throw new IllegalArgumentException(name + " is invalid.");
+        return text;
+    }
+    private static String requireUrl(JSONObject value, String name, boolean originOnly) throws Exception {
+        URI uri = new URI(requireText(value, name));
+        boolean loopback = "http".equals(uri.getScheme()) && ("localhost".equals(uri.getHost()) || "127.0.0.1".equals(uri.getHost()) || "::1".equals(uri.getHost()));
+        if (!"https".equals(uri.getScheme()) && !loopback) throw new IllegalArgumentException(name + " must use HTTPS.");
+        if (uri.getUserInfo() != null || uri.getFragment() != null) throw new IllegalArgumentException(name + " is invalid.");
+        if (originOnly && ((uri.getPath() != null && !uri.getPath().isEmpty() && !"/".equals(uri.getPath())) || uri.getQuery() != null)) throw new IllegalArgumentException(name + " must be an origin.");
+        return uri.toString();
+    }
+    JSONObject json() throws JSONException {
+        return new JSONObject().put("endpoint", endpoint).put("issuer", issuer).put("clientId", clientId).put("namespace", namespace).put("databaseName", databaseName).put("intervalMinutes", intervalMinutes).put("maxMutations", maxMutations).put("maxPulls", maxPulls).put("maxAttempts", maxAttempts);
+    }
+    static AbsoluteBackgroundSyncConfig load(Context context) throws Exception {
+        String encoded = preferences(context).getString(CONFIG, null);
+        return encoded == null ? null : new AbsoluteBackgroundSyncConfig(new JSONObject(encoded));
+    }
+    void save(Context context) throws JSONException { preferences(context).edit().putString(CONFIG, json().toString()).apply(); }
+    static SharedPreferences preferences(Context context) { return context.getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE); }
+}

package/android/src/main/java/js/absolute/sync/AbsoluteBackgroundSyncEngine.java

@@ -0,0 +1,95 @@
+package js.absolute.sync;
+
+import android.content.ContentValues;
+import android.content.Context;
+import android.database.Cursor;
+import android.database.sqlite.SQLiteDatabase;
+import com.getcapacitor.JSObject;
+import java.io.ByteArrayOutputStream;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.net.HttpURLConnection;
+import java.net.URI;
+import java.net.URL;
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import js.absolute.devices.AbsoluteSecureStorageVault;
+import org.json.JSONArray;
+import org.json.JSONObject;
+
+final class AbsoluteBackgroundSyncEngine {
+    static final class NoSession extends Exception {}
+    private static final int MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+    private static final String RUNNING="running", LAST_RUN="lastRunAt", LAST_ERROR="lastError", LAST_ACK="lastAcknowledged", LAST_PULL="lastPulled";
+    private static final class Mutation { final String id; final int attempts; Mutation(String i,int a){id=i;attempts=a;} }
+    private static final class Batch { final JSONObject request=new JSONObject(); final Map<String,Mutation> mutations=new LinkedHashMap<>(); final Map<String,JSONObject> pulls=new LinkedHashMap<>(); }
+
+    static JSObject status(Context context){
+        android.content.SharedPreferences p=AbsoluteBackgroundSyncConfig.preferences(context); JSObject v=new JSObject();
+        v.put("configured",p.contains(AbsoluteBackgroundSyncConfig.CONFIG)); v.put(RUNNING,p.getBoolean(RUNNING,false));
+        if(p.contains(LAST_RUN))v.put(LAST_RUN,p.getLong(LAST_RUN,0)); if(p.contains(LAST_ERROR))v.put(LAST_ERROR,p.getString(LAST_ERROR,null));
+        if(p.contains(LAST_ACK))v.put(LAST_ACK,p.getInt(LAST_ACK,0)); if(p.contains(LAST_PULL))v.put(LAST_PULL,p.getInt(LAST_PULL,0)); return v;
+    }
+    static void recordError(Context c,Exception e){AbsoluteBackgroundSyncConfig.preferences(c).edit().putBoolean(RUNNING,false).putString(LAST_ERROR,e.getMessage()==null?e.getClass().getSimpleName():e.getMessage()).apply();}
+    static void run(Context context,AbsoluteBackgroundSyncConfig config)throws Exception{
+        AbsoluteBackgroundSyncConfig.preferences(context).edit().putBoolean(RUNNING,true).remove(LAST_ERROR).apply();
+        try{
+            String access=refresh(context,config); SQLiteDatabase db=SQLiteDatabase.openDatabase(context.getDatabasePath(config.databaseName+"SQLite.db").getPath(),null,SQLiteDatabase.OPEN_READWRITE);
+            try{db.execSQL("PRAGMA busy_timeout=5000"); Batch batch=prepare(db,config); JSONObject response=request(config.endpoint,"POST",batch.request.toString().getBytes(StandardCharsets.UTF_8),"application/json","Bearer "+access,config.issuer); int[] counts=settle(db,config,batch,response);
+                AbsoluteBackgroundSyncConfig.preferences(context).edit().putBoolean(RUNNING,false).putLong(LAST_RUN,System.currentTimeMillis()).putInt(LAST_ACK,counts[0]).putInt(LAST_PULL,counts[1]).remove(LAST_ERROR).apply();
+            }finally{db.close();}
+        }catch(NoSession e){AbsoluteBackgroundSyncConfig.preferences(context).edit().putBoolean(RUNNING,false).remove(LAST_ERROR).apply();throw e;}
+        catch(Exception e){recordError(context,e);throw e;}
+    }
+    private static String refresh(Context context,AbsoluteBackgroundSyncConfig config)throws Exception{
+        String lease=AbsoluteSecureStorageVault.acquireLease(AbsoluteBackgroundSyncConfig.REFRESH_KEY,120000);if(lease==null)throw new IllegalStateException("Credential refresh is already running.");
+        try{
+            String refresh=AbsoluteSecureStorageVault.get(context,AbsoluteBackgroundSyncConfig.REFRESH_KEY);if(refresh==null)throw new NoSession();
+            JSONObject discovery=request(config.issuer.replaceAll("/$","")+"/.well-known/openid-configuration","GET",null,null,null,config.issuer,false); String tokenEndpoint=discovery.getString("token_endpoint");
+            String body=form("client_id",config.clientId)+"&"+form("grant_type","refresh_token")+"&"+form("refresh_token",refresh)+"&"+form("resource",config.issuer);
+            JSONObject tokens=request(tokenEndpoint,"POST",body.getBytes(StandardCharsets.UTF_8),"application/x-www-form-urlencoded",null,config.issuer,true);
+            if(!AbsoluteSecureStorageVault.setIfLease(context,AbsoluteBackgroundSyncConfig.REFRESH_KEY,tokens.getString("refresh_token"),lease))throw new NoSession();return tokens.getString("access_token");
+        }finally{AbsoluteSecureStorageVault.releaseLease(AbsoluteBackgroundSyncConfig.REFRESH_KEY,lease);}
+    }
+    private static String form(String n,String v)throws Exception{return URLEncoder.encode(n,"UTF-8")+"="+URLEncoder.encode(v,"UTF-8");}
+
+    private static Batch prepare(SQLiteDatabase db,AbsoluteBackgroundSyncConfig config)throws Exception{
+        Batch b=new Batch(); JSONArray mutations=new JSONArray(),pulls=new JSONArray(); long now=System.currentTimeMillis(); db.beginTransaction();
+        try{
+            try(Cursor c=db.rawQuery("SELECT operation_id,record_json FROM absolute_sync_mutations WHERE namespace=? ORDER BY created_at,operation_id",new String[]{config.namespace})){
+                while(c.moveToNext()&&mutations.length()<config.maxMutations){String id=c.getString(0);JSONObject r=new JSONObject(c.getString(1));if("dead-letter".equals(r.optString("state"))||r.optLong("nextAttemptAt",0)>now)continue;int attempts=r.optInt("attempts",0)+1;r.put("attempts",attempts).remove("nextAttemptAt");updateMutation(db,config.namespace,id,r);JSONObject m=new JSONObject().put("operationId",id).put("name",r.getString("name"));if(r.has("args"))m.put("args",r.get("args"));mutations.put(m);b.mutations.put(id,new Mutation(id,attempts));}
+            }
+            try(Cursor c=db.rawQuery("SELECT collection_key,record_json FROM absolute_sync_collections WHERE namespace=? ORDER BY collection_key",new String[]{config.namespace})){
+                while(c.moveToNext()&&pulls.length()<config.maxPulls){String key=c.getString(0);JSONObject r=new JSONObject(c.getString(1));String collection=r.optString("collection");if(collection.isEmpty())continue;JSONObject p=new JSONObject().put("id",key).put("collection",collection);if(r.has("params"))p.put("params",r.get("params"));if("id".equals(r.optString("headlessKey"))){if(r.has("cursor"))p.put("since",r.get("cursor"));else if(r.optInt("version",0)>0)p.put("since",r.getInt("version"));}pulls.put(p);b.pulls.put(key,r);}
+            }
+            db.setTransactionSuccessful();
+        }finally{db.endTransaction();}
+        b.request.put("version",1).put("mutations",mutations).put("pulls",pulls);return b;
+    }
+    private static int[] settle(SQLiteDatabase db,AbsoluteBackgroundSyncConfig config,Batch b,JSONObject response)throws Exception{
+        if(response.getInt("version")!=1)throw new IllegalStateException("Unsupported Headless Sync response.");Map<String,JSONObject> mutationResults=index(response.getJSONArray("mutations"),"operationId"),pullResults=index(response.getJSONArray("pulls"),"id");int ack=0,pulled=0;db.beginTransaction();
+        try{
+            for(Mutation sent:b.mutations.values()){JSONObject current=record(db,"absolute_sync_mutations","operation_id",config.namespace,sent.id);if(current==null||current.optInt("attempts",-1)!=sent.attempts)continue;JSONObject outcome=mutationResults.get(sent.id);if(outcome!=null&&"ack".equals(outcome.optString("status"))){db.delete("absolute_sync_mutations","namespace=? AND operation_id=?",new String[]{config.namespace,sent.id});ack++;continue;}JSONObject rejection=outcome==null?new JSONObject().put("kind","retryable").put("message","Missing mutation response."):outcome.getJSONObject("rejection");current.put("lastError",rejection.optString("message","Mutation rejected.")).put("rejection",rejection);if(!"retryable".equals(rejection.optString("kind"))||sent.attempts>=config.maxAttempts)current.put("state","dead-letter").put("deadLetteredAt",System.currentTimeMillis()).remove("nextAttemptAt");else current.put("state","pending").put("nextAttemptAt",System.currentTimeMillis()+Math.max(0,rejection.optLong("retryAfterMs",Math.min(30000,500L<<Math.min(20,sent.attempts-1)))));updateMutation(db,config.namespace,sent.id,current);}
+            for(Map.Entry<String,JSONObject> requested:b.pulls.entrySet()){JSONObject result=pullResults.get(requested.getKey());if(result==null||"error".equals(result.optString("type")))continue;JSONObject current=record(db,"absolute_sync_collections","collection_key",config.namespace,requested.getKey());if(!same(current,requested.getValue()))continue;ContentValues values=new ContentValues();values.put("record_json",applyPull(current,result).toString());db.update("absolute_sync_collections",values,"namespace=? AND collection_key=?",new String[]{config.namespace,requested.getKey()});pulled++;}
+            db.setTransactionSuccessful();
+        }finally{db.endTransaction();}return new int[]{ack,pulled};
+    }
+    private static JSONObject applyPull(JSONObject current,JSONObject result)throws Exception{JSONObject next=new JSONObject(current.toString());if("snapshot".equals(result.getString("type")))next.put("rows",result.getJSONArray("rows"));else{Map<String,JSONObject> rows=new LinkedHashMap<>();JSONArray existing=current.getJSONArray("rows");for(int i=0;i<existing.length();i++){JSONObject row=existing.getJSONObject(i);rows.put(key(row),row);}remove(rows,result.getJSONArray("removed"));set(rows,result.getJSONArray("changed"));set(rows,result.getJSONArray("added"));next.put("rows",new JSONArray(rows.values()));}return next.put("version",result.getInt("version")).put("cursor",result.getString("cursor"));}
+    private static String key(JSONObject row)throws Exception{Object id=row.get("id");if(!(id instanceof String)&&!(id instanceof Number))throw new IllegalStateException("Background Sync row requires id.");return id.getClass().getName()+":"+id;}
+    private static void set(Map<String,JSONObject> rows,JSONArray values)throws Exception{for(int i=0;i<values.length();i++){JSONObject row=values.getJSONObject(i);rows.put(key(row),row);}}
+    private static void remove(Map<String,JSONObject> rows,JSONArray values)throws Exception{for(int i=0;i<values.length();i++)rows.remove(key(values.getJSONObject(i)));}
+    private static boolean same(JSONObject a,JSONObject b){return a!=null&&a.optInt("version")==b.optInt("version")&&a.optString("cursor").equals(b.optString("cursor"));}
+    private static Map<String,JSONObject> index(JSONArray values,String field)throws Exception{Map<String,JSONObject> result=new HashMap<>();for(int i=0;i<values.length();i++){JSONObject value=values.getJSONObject(i);result.put(value.getString(field),value);}return result;}
+    private static JSONObject record(SQLiteDatabase db,String table,String field,String namespace,String id)throws Exception{try(Cursor c=db.rawQuery("SELECT record_json FROM "+table+" WHERE namespace=? AND "+field+"=? LIMIT 1",new String[]{namespace,id})){return c.moveToFirst()?new JSONObject(c.getString(0)):null;}}
+    private static void updateMutation(SQLiteDatabase db,String namespace,String id,JSONObject record){ContentValues values=new ContentValues();values.put("record_json",record.toString());db.update("absolute_sync_mutations",values,"namespace=? AND operation_id=?",new String[]{namespace,id});}
+
+    private static JSONObject request(String address,String method,byte[] body,String type,String auth,String trustedOrigin)throws Exception{return request(address,method,body,type,auth,trustedOrigin,false);}
+    private static JSONObject request(String address,String method,byte[] body,String type,String auth,String trustedOrigin,boolean advertisedTokenEndpoint)throws Exception{
+        if(body!=null&&body.length>MAX_RESPONSE_BYTES)throw new IllegalStateException("Background request is too large.");URI target=new URI(address);if(advertisedTokenEndpoint){boolean loopback="http".equals(target.getScheme())&&("localhost".equalsIgnoreCase(target.getHost())||"127.0.0.1".equals(target.getHost())||"::1".equals(target.getHost()));if((!"https".equals(target.getScheme())&&!loopback)||target.getUserInfo()!=null||target.getFragment()!=null)throw new SecurityException("OIDC advertised an unsafe token endpoint.");}else if(!sameOrigin(target,new URI(trustedOrigin)))throw new SecurityException("Background request left the Auth issuer origin.");HttpURLConnection c=(HttpURLConnection)new URL(address).openConnection();c.setConnectTimeout(10000);c.setReadTimeout(20000);c.setRequestMethod(method);c.setRequestProperty("Accept","application/json");c.setInstanceFollowRedirects(false);if(auth!=null)c.setRequestProperty("Authorization",auth);if(body!=null){c.setDoOutput(true);c.setFixedLengthStreamingMode(body.length);c.setRequestProperty("Content-Type",type);try(OutputStream output=c.getOutputStream()){output.write(body);}}int status=c.getResponseCode();InputStream input=status>=200&&status<300?c.getInputStream():c.getErrorStream();byte[] bytes=read(input);c.disconnect();if(status<200||status>=300)throw new IllegalStateException("Background request failed with HTTP "+status+".");return new JSONObject(new String(bytes,StandardCharsets.UTF_8));
+    }
+    private static boolean sameOrigin(URI a,URI b){int ap=a.getPort()<0?("https".equals(a.getScheme())?443:80):a.getPort(),bp=b.getPort()<0?("https".equals(b.getScheme())?443:80):b.getPort();return a.getScheme().equals(b.getScheme())&&a.getHost().equalsIgnoreCase(b.getHost())&&ap==bp;}
+    private static byte[] read(InputStream input)throws Exception{if(input==null)return new byte[0];ByteArrayOutputStream out=new ByteArrayOutputStream();byte[] buffer=new byte[8192];int count,total=0;while((count=input.read(buffer))!=-1){total+=count;if(total>MAX_RESPONSE_BYTES)throw new IllegalStateException("Background response is too large.");out.write(buffer,0,count);}input.close();return out.toByteArray();}
+}

package/android/src/main/java/js/absolute/sync/AbsoluteBackgroundSyncPlugin.java

@@ -0,0 +1,49 @@
+package js.absolute.sync;
+
+import androidx.work.Constraints;
+import androidx.work.ExistingPeriodicWorkPolicy;
+import androidx.work.NetworkType;
+import androidx.work.PeriodicWorkRequest;
+import androidx.work.WorkManager;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+import java.util.concurrent.TimeUnit;
+
+@CapacitorPlugin(name = "AbsoluteBackgroundSync")
+public class AbsoluteBackgroundSyncPlugin extends Plugin {
+    private Constraints networkConstraint() { return new Constraints.Builder().setRequiredNetworkType(NetworkType.CONNECTED).build(); }
+    private void schedule(AbsoluteBackgroundSyncConfig config) {
+        PeriodicWorkRequest request = new PeriodicWorkRequest.Builder(AbsoluteBackgroundSyncWorker.class, config.intervalMinutes, TimeUnit.MINUTES).setConstraints(networkConstraint()).build();
+        WorkManager.getInstance(getContext()).enqueueUniquePeriodicWork(AbsoluteBackgroundSyncConfig.WORK_NAME, ExistingPeriodicWorkPolicy.UPDATE, request);
+    }
+    @PluginMethod public void configure(PluginCall call) {
+        try {
+            AbsoluteBackgroundSyncConfig config = new AbsoluteBackgroundSyncConfig(call.getData());
+            config.save(getContext());
+            schedule(config);
+            call.resolve();
+        } catch (Exception error) { call.reject("Invalid background Sync configuration.", "INVALID_ARGUMENT", error); }
+    }
+    @PluginMethod public void clear(PluginCall call) {
+        WorkManager.getInstance(getContext()).cancelUniqueWork(AbsoluteBackgroundSyncConfig.WORK_NAME);
+        AbsoluteBackgroundSyncConfig.preferences(getContext()).edit().clear().apply();
+        call.resolve();
+    }
+    @PluginMethod public void runNow(PluginCall call) {
+        new Thread(() -> {
+            try {
+                AbsoluteBackgroundSyncConfig config = AbsoluteBackgroundSyncConfig.load(getContext());
+                if (config != null) AbsoluteBackgroundSyncEngine.run(getContext(), config);
+                call.resolve(AbsoluteBackgroundSyncEngine.status(getContext()));
+            } catch (AbsoluteBackgroundSyncEngine.NoSession error) {
+                call.resolve(AbsoluteBackgroundSyncEngine.status(getContext()));
+            } catch (Exception error) {
+                AbsoluteBackgroundSyncEngine.recordError(getContext(), error);
+                call.reject("Background Sync failed.", "SYNC_FAILURE", error);
+            }
+        }, "absolutejs-background-sync-manual").start();
+    }
+    @PluginMethod public void status(PluginCall call) { call.resolve(AbsoluteBackgroundSyncEngine.status(getContext())); }
+}

package/android/src/main/java/js/absolute/sync/AbsoluteBackgroundSyncWorker.java

@@ -0,0 +1,23 @@
+package js.absolute.sync;
+
+import android.content.Context;
+import androidx.annotation.NonNull;
+import androidx.work.Worker;
+import androidx.work.WorkerParameters;
+
+public final class AbsoluteBackgroundSyncWorker extends Worker {
+    public AbsoluteBackgroundSyncWorker(@NonNull Context context, @NonNull WorkerParameters parameters) { super(context, parameters); }
+    @NonNull @Override public Result doWork() {
+        try {
+            AbsoluteBackgroundSyncConfig config = AbsoluteBackgroundSyncConfig.load(getApplicationContext());
+            if (config == null) return Result.success();
+            AbsoluteBackgroundSyncEngine.run(getApplicationContext(), config);
+            return Result.success();
+        } catch (AbsoluteBackgroundSyncEngine.NoSession error) {
+            return Result.success();
+        } catch (Exception error) {
+            AbsoluteBackgroundSyncEngine.recordError(getApplicationContext(), error);
+            return Result.retry();
+        }
+    }
+}

package/dist/index.d.ts

@@ -2,6 +2,34 @@ import { type SQLiteDBConnection } from '@capacitor-community/sqlite';
 import type { SyncLocalStore } from '@absolutejs/sync/client';
 import type { DeviceLifecycleCapability, DeviceNetworkCapability, DeviceSubscription } from '@absolutejs/devices';
 import type { SyncClient } from '@absolutejs/sync/client';
+export type CapacitorBackgroundSyncConfig = {
+    endpoint: string;
+    issuer: string;
+    clientId: string;
+    namespace: string;
+    databaseName?: string;
+    intervalMinutes?: number;
+    maxMutations?: number;
+    maxPulls?: number;
+    maxAttempts?: number;
+};
+export type CapacitorBackgroundSyncStatus = {
+    configured: boolean;
+    running: boolean;
+    lastRunAt?: number;
+    lastError?: string;
+    lastAcknowledged?: number;
+    lastPulled?: number;
+};
+export type AbsoluteBackgroundSyncPlugin = {
+    configure(options: CapacitorBackgroundSyncConfig): Promise<void>;
+    clear(): Promise<void>;
+    runNow(): Promise<CapacitorBackgroundSyncStatus>;
+    status(): Promise<CapacitorBackgroundSyncStatus>;
+};
+export declare const AbsoluteBackgroundSync: AbsoluteBackgroundSyncPlugin;
+/** Configure the managed scheduler. Auth credentials remain in the native vault. */
+export declare const configureCapacitorBackgroundSync: (options: CapacitorBackgroundSyncConfig, plugin?: AbsoluteBackgroundSyncPlugin) => Promise<void>;
 export type CapacitorSyncSqliteConnection = Pick<SQLiteDBConnection, 'beginTransaction' | 'commitTransaction' | 'execute' | 'open' | 'query' | 'rollbackTransaction' | 'run'>;
 export type CapacitorSyncSqliteFactory = () => CapacitorSyncSqliteConnection | Promise<CapacitorSyncSqliteConnection>;
 export type CapacitorSyncLocalStoreOptions = {

package/dist/index.js

@@ -3,6 +3,9 @@ import {
   CapacitorSQLite,
   SQLiteConnection
 } from "@capacitor-community/sqlite";
+import { registerPlugin } from "@capacitor/core";
+var AbsoluteBackgroundSync = registerPlugin("AbsoluteBackgroundSync");
+var configureCapacitorBackgroundSync = (options, plugin = AbsoluteBackgroundSync) => plugin.configure(options);
 var SCHEMA = `
 CREATE TABLE IF NOT EXISTS absolute_sync_metadata (
   namespace TEXT PRIMARY KEY NOT NULL,
@@ -194,8 +197,10 @@ var installCapacitorSyncLifecycle = async ({
 };
 export {
   installCapacitorSyncLifecycle,
-  createCapacitorSyncLocalStore
+  createCapacitorSyncLocalStore,
+  configureCapacitorBackgroundSync,
+  AbsoluteBackgroundSync
 };
 
-//# debugId=9D6EB7498C1CD6F664756E2164756E21
+//# debugId=1D548F4E3CBABDF264756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../src/index.ts"],
   "sourcesContent": [
-    "import {\n\tCapacitorSQLite,\n\tSQLiteConnection,\n\ttype SQLiteDBConnection\n} from '@capacitor-community/sqlite';\nimport type {\n\tLocalCollectionRecord,\n\tLocalMutationRecord,\n\tSyncLocalStore,\n\tSyncLocalStoreMode,\n\tSyncLocalTransaction\n} from '@absolutejs/sync/client';\nimport type {\n\tDeviceLifecycleCapability,\n\tDeviceNetworkCapability,\n\tDeviceSubscription\n} from '@absolutejs/devices';\nimport type { SyncClient } from '@absolutejs/sync/client';\n\nexport type CapacitorSyncSqliteConnection = Pick<\n\tSQLiteDBConnection,\n\t| 'beginTransaction'\n\t| 'commitTransaction'\n\t| 'execute'\n\t| 'open'\n\t| 'query'\n\t| 'rollbackTransaction'\n\t| 'run'\n>;\n\nexport type CapacitorSyncSqliteFactory = () =>\n\t| CapacitorSyncSqliteConnection\n\t| Promise<CapacitorSyncSqliteConnection>;\n\nexport type CapacitorSyncLocalStoreOptions = {\n\t/** Defaults to `absolutejs-sync-local-v1`. */\n\tdatabaseName?: string;\n\t/** Injection seam for tests and custom SQLCipher provisioning. */\n\tconnection?: CapacitorSyncSqliteFactory;\n};\n\nconst SCHEMA = `\nCREATE TABLE IF NOT EXISTS absolute_sync_metadata (\n  namespace TEXT PRIMARY KEY NOT NULL,\n  installation_id TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS absolute_sync_collections (\n  namespace TEXT NOT NULL,\n  collection_key TEXT NOT NULL,\n  record_json TEXT NOT NULL,\n  PRIMARY KEY (namespace, collection_key)\n);\nCREATE TABLE IF NOT EXISTS absolute_sync_mutations (\n  namespace TEXT NOT NULL,\n  operation_id TEXT NOT NULL,\n  created_at INTEGER NOT NULL,\n  record_json TEXT NOT NULL,\n  PRIMARY KEY (namespace, operation_id)\n);\nCREATE INDEX IF NOT EXISTS absolute_sync_mutations_order\n  ON absolute_sync_mutations (namespace, created_at, operation_id);\n`;\n\ntype SqliteRow = Record<string, unknown>;\n\nconst firstString = (rows: SqliteRow[] | undefined, field: string) => {\n\tconst value = rows?.[0]?.[field];\n\treturn typeof value === 'string' ? value : undefined;\n};\n\nconst parseRecord = <T>(value: unknown, label: string): T | undefined => {\n\tif (value === undefined) return undefined;\n\tif (typeof value !== 'string')\n\t\tthrow new Error(\n\t\t\t`Capacitor Sync SQLite returned invalid ${label} JSON.`\n\t\t);\n\ttry {\n\t\treturn JSON.parse(value) as T;\n\t} catch (cause) {\n\t\tthrow new Error(\n\t\t\t`Capacitor Sync SQLite could not parse ${label} JSON.`,\n\t\t\t{\n\t\t\t\tcause\n\t\t\t}\n\t\t);\n\t}\n};\n\nconst defaultConnection = async (\n\tdatabaseName: string\n): Promise<CapacitorSyncSqliteConnection> => {\n\tconst sqlite = new SQLiteConnection(CapacitorSQLite);\n\tconst existing = await sqlite.isConnection(databaseName, false);\n\tconst connection = existing.result\n\t\t? await sqlite.retrieveConnection(databaseName, false)\n\t\t: await sqlite.createConnection(\n\t\t\t\tdatabaseName,\n\t\t\t\tfalse,\n\t\t\t\t'no-encryption',\n\t\t\t\t1,\n\t\t\t\tfalse\n\t\t\t);\n\tawait connection.open();\n\treturn connection;\n};\n\nconst requireNamespace = (namespace: string) => {\n\tif (namespace.length === 0)\n\t\tthrow new Error('Sync local-store namespace must not be empty');\n};\n\n/**\n * Native SQLite implementation of Sync's principal-partitioned atomic cache\n * and mutation outbox. All calls are serialized because a Capacitor database\n * connection owns one explicit transaction at a time.\n */\nexport const createCapacitorSyncLocalStore = ({\n\tdatabaseName = 'absolutejs-sync-local-v1',\n\tconnection: createConnection = () => defaultConnection(databaseName)\n}: CapacitorSyncLocalStoreOptions = {}): SyncLocalStore => {\n\tif (databaseName.length === 0)\n\t\tthrow new TypeError('Capacitor Sync databaseName cannot be empty.');\n\tlet connectionPromise: Promise<CapacitorSyncSqliteConnection> | undefined;\n\tconst connection = () => {\n\t\tconnectionPromise ??= Promise.resolve(createConnection()).then(\n\t\t\tasync (database) => {\n\t\t\t\tawait database.execute(SCHEMA);\n\t\t\t\treturn database;\n\t\t\t}\n\t\t);\n\t\treturn connectionPromise;\n\t};\n\tlet tail = Promise.resolve();\n\tconst locked = async <R>(run: () => Promise<R>): Promise<R> => {\n\t\tlet release!: () => void;\n\t\tconst previous = tail;\n\t\ttail = new Promise<void>((resolve) => {\n\t\t\trelease = resolve;\n\t\t});\n\t\tawait previous;\n\t\ttry {\n\t\t\treturn await run();\n\t\t} finally {\n\t\t\trelease();\n\t\t}\n\t};\n\n\tconst transaction = async <R>(\n\t\tnamespace: string,\n\t\tmode: SyncLocalStoreMode,\n\t\trun: (tx: SyncLocalTransaction) => Promise<R>\n\t): Promise<R> => {\n\t\trequireNamespace(namespace);\n\t\treturn locked(async () => {\n\t\t\tconst database = await connection();\n\t\t\tawait database.beginTransaction();\n\t\t\tconst writable = () => {\n\t\t\t\tif (mode !== 'readwrite')\n\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t'Cannot write in a readonly Sync local transaction'\n\t\t\t\t\t);\n\t\t\t};\n\t\t\tconst tx: SyncLocalTransaction = {\n\t\t\t\tgetInstallationId: async () =>\n\t\t\t\t\tfirstString(\n\t\t\t\t\t\t(\n\t\t\t\t\t\t\tawait database.query(\n\t\t\t\t\t\t\t\t'SELECT installation_id FROM absolute_sync_metadata WHERE namespace = ? LIMIT 1',\n\t\t\t\t\t\t\t\t[namespace]\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t).values,\n\t\t\t\t\t\t'installation_id'\n\t\t\t\t\t),\n\t\t\t\tsetInstallationId: async (installationId) => {\n\t\t\t\t\twritable();\n\t\t\t\t\tif (installationId.length === 0)\n\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\t'Sync installation id must not be empty'\n\t\t\t\t\t\t);\n\t\t\t\t\tawait database.run(\n\t\t\t\t\t\t'INSERT INTO absolute_sync_metadata (namespace, installation_id) VALUES (?, ?) ON CONFLICT(namespace) DO UPDATE SET installation_id = excluded.installation_id',\n\t\t\t\t\t\t[namespace, installationId],\n\t\t\t\t\t\tfalse\n\t\t\t\t\t);\n\t\t\t\t},\n\t\t\t\tgetCollection: async <T>(key: string) =>\n\t\t\t\t\tparseRecord<LocalCollectionRecord<T>>(\n\t\t\t\t\t\t(\n\t\t\t\t\t\t\tawait database.query(\n\t\t\t\t\t\t\t\t'SELECT record_json FROM absolute_sync_collections WHERE namespace = ? AND collection_key = ? LIMIT 1',\n\t\t\t\t\t\t\t\t[namespace, key]\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t).values?.[0]?.record_json,\n\t\t\t\t\t\t'collection'\n\t\t\t\t\t),\n\t\t\t\tputCollection: async (key, record) => {\n\t\t\t\t\twritable();\n\t\t\t\t\tawait database.run(\n\t\t\t\t\t\t'INSERT INTO absolute_sync_collections (namespace, collection_key, record_json) VALUES (?, ?, ?) ON CONFLICT(namespace, collection_key) DO UPDATE SET record_json = excluded.record_json',\n\t\t\t\t\t\t[namespace, key, JSON.stringify(record)],\n\t\t\t\t\t\tfalse\n\t\t\t\t\t);\n\t\t\t\t},\n\t\t\t\tdeleteCollection: async (key) => {\n\t\t\t\t\twritable();\n\t\t\t\t\tawait database.run(\n\t\t\t\t\t\t'DELETE FROM absolute_sync_collections WHERE namespace = ? AND collection_key = ?',\n\t\t\t\t\t\t[namespace, key],\n\t\t\t\t\t\tfalse\n\t\t\t\t\t);\n\t\t\t\t},\n\t\t\t\tlistMutations: async () => {\n\t\t\t\t\tconst rows = (\n\t\t\t\t\t\tawait database.query(\n\t\t\t\t\t\t\t'SELECT record_json FROM absolute_sync_mutations WHERE namespace = ? ORDER BY created_at ASC, operation_id ASC',\n\t\t\t\t\t\t\t[namespace]\n\t\t\t\t\t\t)\n\t\t\t\t\t).values;\n\t\t\t\t\treturn (rows ?? [])\n\t\t\t\t\t\t.map((row) =>\n\t\t\t\t\t\t\tparseRecord<LocalMutationRecord>(\n\t\t\t\t\t\t\t\trow.record_json,\n\t\t\t\t\t\t\t\t'mutation'\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t)\n\t\t\t\t\t\t.filter(\n\t\t\t\t\t\t\t(record): record is LocalMutationRecord =>\n\t\t\t\t\t\t\t\trecord !== undefined\n\t\t\t\t\t\t);\n\t\t\t\t},\n\t\t\t\tgetMutation: async (operationId) =>\n\t\t\t\t\tparseRecord<LocalMutationRecord>(\n\t\t\t\t\t\t(\n\t\t\t\t\t\t\tawait database.query(\n\t\t\t\t\t\t\t\t'SELECT record_json FROM absolute_sync_mutations WHERE namespace = ? AND operation_id = ? LIMIT 1',\n\t\t\t\t\t\t\t\t[namespace, operationId]\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t).values?.[0]?.record_json,\n\t\t\t\t\t\t'mutation'\n\t\t\t\t\t),\n\t\t\t\tputMutation: async (record) => {\n\t\t\t\t\twritable();\n\t\t\t\t\tawait database.run(\n\t\t\t\t\t\t'INSERT INTO absolute_sync_mutations (namespace, operation_id, created_at, record_json) VALUES (?, ?, ?, ?) ON CONFLICT(namespace, operation_id) DO UPDATE SET created_at = excluded.created_at, record_json = excluded.record_json',\n\t\t\t\t\t\t[\n\t\t\t\t\t\t\tnamespace,\n\t\t\t\t\t\t\trecord.operationId,\n\t\t\t\t\t\t\trecord.createdAt,\n\t\t\t\t\t\t\tJSON.stringify(record)\n\t\t\t\t\t\t],\n\t\t\t\t\t\tfalse\n\t\t\t\t\t);\n\t\t\t\t},\n\t\t\t\tdeleteMutation: async (operationId) => {\n\t\t\t\t\twritable();\n\t\t\t\t\tawait database.run(\n\t\t\t\t\t\t'DELETE FROM absolute_sync_mutations WHERE namespace = ? AND operation_id = ?',\n\t\t\t\t\t\t[namespace, operationId],\n\t\t\t\t\t\tfalse\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t};\n\t\t\ttry {\n\t\t\t\tconst result = await run(tx);\n\t\t\t\tawait database.commitTransaction();\n\t\t\t\treturn result;\n\t\t\t} catch (error) {\n\t\t\t\ttry {\n\t\t\t\t\tawait database.rollbackTransaction();\n\t\t\t\t} catch (rollbackError) {\n\t\t\t\t\tthrow new AggregateError(\n\t\t\t\t\t\t[error, rollbackError],\n\t\t\t\t\t\t'Capacitor Sync SQLite transaction and rollback both failed'\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t});\n\t};\n\n\treturn {\n\t\ttransaction,\n\t\tdeleteNamespace: async (namespace) => {\n\t\t\trequireNamespace(namespace);\n\t\t\tawait locked(async () => {\n\t\t\t\tconst database = await connection();\n\t\t\t\tawait database.beginTransaction();\n\t\t\t\ttry {\n\t\t\t\t\tfor (const table of [\n\t\t\t\t\t\t'absolute_sync_metadata',\n\t\t\t\t\t\t'absolute_sync_collections',\n\t\t\t\t\t\t'absolute_sync_mutations'\n\t\t\t\t\t])\n\t\t\t\t\t\tawait database.run(\n\t\t\t\t\t\t\t`DELETE FROM ${table} WHERE namespace = ?`,\n\t\t\t\t\t\t\t[namespace],\n\t\t\t\t\t\t\tfalse\n\t\t\t\t\t\t);\n\t\t\t\t\tawait database.commitTransaction();\n\t\t\t\t} catch (error) {\n\t\t\t\t\tawait database.rollbackTransaction();\n\t\t\t\t\tthrow error;\n\t\t\t\t}\n\t\t\t});\n\t\t}\n\t};\n};\n\nexport type CapacitorSyncLifecycleOptions = {\n\tclient: Pick<SyncClient, 'reconnect'> & Partial<Pick<SyncClient, 'flush'>>;\n\tlifecycle: DeviceLifecycleCapability;\n\tnetwork: DeviceNetworkCapability;\n\t/** Finite outbox budget after a wake-up. Defaults to 10 seconds. */\n\tflushTimeoutMs?: number;\n\t/** Lifecycle flush failures are observable without becoming unhandled. */\n\tonError?: (error: unknown) => void;\n};\n\n/** Refreshes the socket/ticket and runs a bounded outbox flush after wake-up. */\nexport const installCapacitorSyncLifecycle = async ({\n\tclient,\n\tlifecycle,\n\tnetwork,\n\tflushTimeoutMs = 10_000,\n\tonError\n}: CapacitorSyncLifecycleOptions): Promise<DeviceSubscription> => {\n\tif (!Number.isFinite(flushTimeoutMs) || flushTimeoutMs < 0)\n\t\tthrow new TypeError(\n\t\t\t'Capacitor Sync flushTimeoutMs must be a non-negative number.'\n\t\t);\n\tconst wake = () => {\n\t\tclient.reconnect();\n\t\tvoid client\n\t\t\t.flush?.({ timeoutMs: flushTimeoutMs })\n\t\t\t.catch((error) => onError?.(error));\n\t};\n\tconst removers = await Promise.all([\n\t\tlifecycle.onResume?.(wake) ?? (() => undefined),\n\t\tnetwork.onChange((status) => {\n\t\t\tif (status.connected) wake();\n\t\t})\n\t]);\n\tlet active = true;\n\treturn async () => {\n\t\tif (!active) return;\n\t\tactive = false;\n\t\tawait Promise.all(removers.map((remove) => remove()));\n\t};\n};\n"
+    "import {\n\tCapacitorSQLite,\n\tSQLiteConnection,\n\ttype SQLiteDBConnection\n} from '@capacitor-community/sqlite';\nimport type {\n\tLocalCollectionRecord,\n\tLocalMutationRecord,\n\tSyncLocalStore,\n\tSyncLocalStoreMode,\n\tSyncLocalTransaction\n} from '@absolutejs/sync/client';\nimport type {\n\tDeviceLifecycleCapability,\n\tDeviceNetworkCapability,\n\tDeviceSubscription\n} from '@absolutejs/devices';\nimport type { SyncClient } from '@absolutejs/sync/client';\nimport { registerPlugin } from '@capacitor/core';\n\nexport type CapacitorBackgroundSyncConfig = {\n\tendpoint: string;\n\tissuer: string;\n\tclientId: string;\n\tnamespace: string;\n\tdatabaseName?: string;\n\tintervalMinutes?: number;\n\tmaxMutations?: number;\n\tmaxPulls?: number;\n\tmaxAttempts?: number;\n};\n\nexport type CapacitorBackgroundSyncStatus = {\n\tconfigured: boolean;\n\trunning: boolean;\n\tlastRunAt?: number;\n\tlastError?: string;\n\tlastAcknowledged?: number;\n\tlastPulled?: number;\n};\n\nexport type AbsoluteBackgroundSyncPlugin = {\n\tconfigure(options: CapacitorBackgroundSyncConfig): Promise<void>;\n\tclear(): Promise<void>;\n\trunNow(): Promise<CapacitorBackgroundSyncStatus>;\n\tstatus(): Promise<CapacitorBackgroundSyncStatus>;\n};\n\nexport const AbsoluteBackgroundSync =\n\tregisterPlugin<AbsoluteBackgroundSyncPlugin>('AbsoluteBackgroundSync');\n\n/** Configure the managed scheduler. Auth credentials remain in the native vault. */\nexport const configureCapacitorBackgroundSync = (\n\toptions: CapacitorBackgroundSyncConfig,\n\tplugin: AbsoluteBackgroundSyncPlugin = AbsoluteBackgroundSync\n) => plugin.configure(options);\n\nexport type CapacitorSyncSqliteConnection = Pick<\n\tSQLiteDBConnection,\n\t| 'beginTransaction'\n\t| 'commitTransaction'\n\t| 'execute'\n\t| 'open'\n\t| 'query'\n\t| 'rollbackTransaction'\n\t| 'run'\n>;\n\nexport type CapacitorSyncSqliteFactory = () =>\n\t| CapacitorSyncSqliteConnection\n\t| Promise<CapacitorSyncSqliteConnection>;\n\nexport type CapacitorSyncLocalStoreOptions = {\n\t/** Defaults to `absolutejs-sync-local-v1`. */\n\tdatabaseName?: string;\n\t/** Injection seam for tests and custom SQLCipher provisioning. */\n\tconnection?: CapacitorSyncSqliteFactory;\n};\n\nconst SCHEMA = `\nCREATE TABLE IF NOT EXISTS absolute_sync_metadata (\n  namespace TEXT PRIMARY KEY NOT NULL,\n  installation_id TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS absolute_sync_collections (\n  namespace TEXT NOT NULL,\n  collection_key TEXT NOT NULL,\n  record_json TEXT NOT NULL,\n  PRIMARY KEY (namespace, collection_key)\n);\nCREATE TABLE IF NOT EXISTS absolute_sync_mutations (\n  namespace TEXT NOT NULL,\n  operation_id TEXT NOT NULL,\n  created_at INTEGER NOT NULL,\n  record_json TEXT NOT NULL,\n  PRIMARY KEY (namespace, operation_id)\n);\nCREATE INDEX IF NOT EXISTS absolute_sync_mutations_order\n  ON absolute_sync_mutations (namespace, created_at, operation_id);\n`;\n\ntype SqliteRow = Record<string, unknown>;\n\nconst firstString = (rows: SqliteRow[] | undefined, field: string) => {\n\tconst value = rows?.[0]?.[field];\n\treturn typeof value === 'string' ? value : undefined;\n};\n\nconst parseRecord = <T>(value: unknown, label: string): T | undefined => {\n\tif (value === undefined) return undefined;\n\tif (typeof value !== 'string')\n\t\tthrow new Error(\n\t\t\t`Capacitor Sync SQLite returned invalid ${label} JSON.`\n\t\t);\n\ttry {\n\t\treturn JSON.parse(value) as T;\n\t} catch (cause) {\n\t\tthrow new Error(\n\t\t\t`Capacitor Sync SQLite could not parse ${label} JSON.`,\n\t\t\t{\n\t\t\t\tcause\n\t\t\t}\n\t\t);\n\t}\n};\n\nconst defaultConnection = async (\n\tdatabaseName: string\n): Promise<CapacitorSyncSqliteConnection> => {\n\tconst sqlite = new SQLiteConnection(CapacitorSQLite);\n\tconst existing = await sqlite.isConnection(databaseName, false);\n\tconst connection = existing.result\n\t\t? await sqlite.retrieveConnection(databaseName, false)\n\t\t: await sqlite.createConnection(\n\t\t\t\tdatabaseName,\n\t\t\t\tfalse,\n\t\t\t\t'no-encryption',\n\t\t\t\t1,\n\t\t\t\tfalse\n\t\t\t);\n\tawait connection.open();\n\treturn connection;\n};\n\nconst requireNamespace = (namespace: string) => {\n\tif (namespace.length === 0)\n\t\tthrow new Error('Sync local-store namespace must not be empty');\n};\n\n/**\n * Native SQLite implementation of Sync's principal-partitioned atomic cache\n * and mutation outbox. All calls are serialized because a Capacitor database\n * connection owns one explicit transaction at a time.\n */\nexport const createCapacitorSyncLocalStore = ({\n\tdatabaseName = 'absolutejs-sync-local-v1',\n\tconnection: createConnection = () => defaultConnection(databaseName)\n}: CapacitorSyncLocalStoreOptions = {}): SyncLocalStore => {\n\tif (databaseName.length === 0)\n\t\tthrow new TypeError('Capacitor Sync databaseName cannot be empty.');\n\tlet connectionPromise: Promise<CapacitorSyncSqliteConnection> | undefined;\n\tconst connection = () => {\n\t\tconnectionPromise ??= Promise.resolve(createConnection()).then(\n\t\t\tasync (database) => {\n\t\t\t\tawait database.execute(SCHEMA);\n\t\t\t\treturn database;\n\t\t\t}\n\t\t);\n\t\treturn connectionPromise;\n\t};\n\tlet tail = Promise.resolve();\n\tconst locked = async <R>(run: () => Promise<R>): Promise<R> => {\n\t\tlet release!: () => void;\n\t\tconst previous = tail;\n\t\ttail = new Promise<void>((resolve) => {\n\t\t\trelease = resolve;\n\t\t});\n\t\tawait previous;\n\t\ttry {\n\t\t\treturn await run();\n\t\t} finally {\n\t\t\trelease();\n\t\t}\n\t};\n\n\tconst transaction = async <R>(\n\t\tnamespace: string,\n\t\tmode: SyncLocalStoreMode,\n\t\trun: (tx: SyncLocalTransaction) => Promise<R>\n\t): Promise<R> => {\n\t\trequireNamespace(namespace);\n\t\treturn locked(async () => {\n\t\t\tconst database = await connection();\n\t\t\tawait database.beginTransaction();\n\t\t\tconst writable = () => {\n\t\t\t\tif (mode !== 'readwrite')\n\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t'Cannot write in a readonly Sync local transaction'\n\t\t\t\t\t);\n\t\t\t};\n\t\t\tconst tx: SyncLocalTransaction = {\n\t\t\t\tgetInstallationId: async () =>\n\t\t\t\t\tfirstString(\n\t\t\t\t\t\t(\n\t\t\t\t\t\t\tawait database.query(\n\t\t\t\t\t\t\t\t'SELECT installation_id FROM absolute_sync_metadata WHERE namespace = ? LIMIT 1',\n\t\t\t\t\t\t\t\t[namespace]\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t).values,\n\t\t\t\t\t\t'installation_id'\n\t\t\t\t\t),\n\t\t\t\tsetInstallationId: async (installationId) => {\n\t\t\t\t\twritable();\n\t\t\t\t\tif (installationId.length === 0)\n\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\t'Sync installation id must not be empty'\n\t\t\t\t\t\t);\n\t\t\t\t\tawait database.run(\n\t\t\t\t\t\t'INSERT INTO absolute_sync_metadata (namespace, installation_id) VALUES (?, ?) ON CONFLICT(namespace) DO UPDATE SET installation_id = excluded.installation_id',\n\t\t\t\t\t\t[namespace, installationId],\n\t\t\t\t\t\tfalse\n\t\t\t\t\t);\n\t\t\t\t},\n\t\t\t\tgetCollection: async <T>(key: string) =>\n\t\t\t\t\tparseRecord<LocalCollectionRecord<T>>(\n\t\t\t\t\t\t(\n\t\t\t\t\t\t\tawait database.query(\n\t\t\t\t\t\t\t\t'SELECT record_json FROM absolute_sync_collections WHERE namespace = ? AND collection_key = ? LIMIT 1',\n\t\t\t\t\t\t\t\t[namespace, key]\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t).values?.[0]?.record_json,\n\t\t\t\t\t\t'collection'\n\t\t\t\t\t),\n\t\t\t\tputCollection: async (key, record) => {\n\t\t\t\t\twritable();\n\t\t\t\t\tawait database.run(\n\t\t\t\t\t\t'INSERT INTO absolute_sync_collections (namespace, collection_key, record_json) VALUES (?, ?, ?) ON CONFLICT(namespace, collection_key) DO UPDATE SET record_json = excluded.record_json',\n\t\t\t\t\t\t[namespace, key, JSON.stringify(record)],\n\t\t\t\t\t\tfalse\n\t\t\t\t\t);\n\t\t\t\t},\n\t\t\t\tdeleteCollection: async (key) => {\n\t\t\t\t\twritable();\n\t\t\t\t\tawait database.run(\n\t\t\t\t\t\t'DELETE FROM absolute_sync_collections WHERE namespace = ? AND collection_key = ?',\n\t\t\t\t\t\t[namespace, key],\n\t\t\t\t\t\tfalse\n\t\t\t\t\t);\n\t\t\t\t},\n\t\t\t\tlistMutations: async () => {\n\t\t\t\t\tconst rows = (\n\t\t\t\t\t\tawait database.query(\n\t\t\t\t\t\t\t'SELECT record_json FROM absolute_sync_mutations WHERE namespace = ? ORDER BY created_at ASC, operation_id ASC',\n\t\t\t\t\t\t\t[namespace]\n\t\t\t\t\t\t)\n\t\t\t\t\t).values;\n\t\t\t\t\treturn (rows ?? [])\n\t\t\t\t\t\t.map((row) =>\n\t\t\t\t\t\t\tparseRecord<LocalMutationRecord>(\n\t\t\t\t\t\t\t\trow.record_json,\n\t\t\t\t\t\t\t\t'mutation'\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t)\n\t\t\t\t\t\t.filter(\n\t\t\t\t\t\t\t(record): record is LocalMutationRecord =>\n\t\t\t\t\t\t\t\trecord !== undefined\n\t\t\t\t\t\t);\n\t\t\t\t},\n\t\t\t\tgetMutation: async (operationId) =>\n\t\t\t\t\tparseRecord<LocalMutationRecord>(\n\t\t\t\t\t\t(\n\t\t\t\t\t\t\tawait database.query(\n\t\t\t\t\t\t\t\t'SELECT record_json FROM absolute_sync_mutations WHERE namespace = ? AND operation_id = ? LIMIT 1',\n\t\t\t\t\t\t\t\t[namespace, operationId]\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t).values?.[0]?.record_json,\n\t\t\t\t\t\t'mutation'\n\t\t\t\t\t),\n\t\t\t\tputMutation: async (record) => {\n\t\t\t\t\twritable();\n\t\t\t\t\tawait database.run(\n\t\t\t\t\t\t'INSERT INTO absolute_sync_mutations (namespace, operation_id, created_at, record_json) VALUES (?, ?, ?, ?) ON CONFLICT(namespace, operation_id) DO UPDATE SET created_at = excluded.created_at, record_json = excluded.record_json',\n\t\t\t\t\t\t[\n\t\t\t\t\t\t\tnamespace,\n\t\t\t\t\t\t\trecord.operationId,\n\t\t\t\t\t\t\trecord.createdAt,\n\t\t\t\t\t\t\tJSON.stringify(record)\n\t\t\t\t\t\t],\n\t\t\t\t\t\tfalse\n\t\t\t\t\t);\n\t\t\t\t},\n\t\t\t\tdeleteMutation: async (operationId) => {\n\t\t\t\t\twritable();\n\t\t\t\t\tawait database.run(\n\t\t\t\t\t\t'DELETE FROM absolute_sync_mutations WHERE namespace = ? AND operation_id = ?',\n\t\t\t\t\t\t[namespace, operationId],\n\t\t\t\t\t\tfalse\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t};\n\t\t\ttry {\n\t\t\t\tconst result = await run(tx);\n\t\t\t\tawait database.commitTransaction();\n\t\t\t\treturn result;\n\t\t\t} catch (error) {\n\t\t\t\ttry {\n\t\t\t\t\tawait database.rollbackTransaction();\n\t\t\t\t} catch (rollbackError) {\n\t\t\t\t\tthrow new AggregateError(\n\t\t\t\t\t\t[error, rollbackError],\n\t\t\t\t\t\t'Capacitor Sync SQLite transaction and rollback both failed'\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t});\n\t};\n\n\treturn {\n\t\ttransaction,\n\t\tdeleteNamespace: async (namespace) => {\n\t\t\trequireNamespace(namespace);\n\t\t\tawait locked(async () => {\n\t\t\t\tconst database = await connection();\n\t\t\t\tawait database.beginTransaction();\n\t\t\t\ttry {\n\t\t\t\t\tfor (const table of [\n\t\t\t\t\t\t'absolute_sync_metadata',\n\t\t\t\t\t\t'absolute_sync_collections',\n\t\t\t\t\t\t'absolute_sync_mutations'\n\t\t\t\t\t])\n\t\t\t\t\t\tawait database.run(\n\t\t\t\t\t\t\t`DELETE FROM ${table} WHERE namespace = ?`,\n\t\t\t\t\t\t\t[namespace],\n\t\t\t\t\t\t\tfalse\n\t\t\t\t\t\t);\n\t\t\t\t\tawait database.commitTransaction();\n\t\t\t\t} catch (error) {\n\t\t\t\t\tawait database.rollbackTransaction();\n\t\t\t\t\tthrow error;\n\t\t\t\t}\n\t\t\t});\n\t\t}\n\t};\n};\n\nexport type CapacitorSyncLifecycleOptions = {\n\tclient: Pick<SyncClient, 'reconnect'> & Partial<Pick<SyncClient, 'flush'>>;\n\tlifecycle: DeviceLifecycleCapability;\n\tnetwork: DeviceNetworkCapability;\n\t/** Finite outbox budget after a wake-up. Defaults to 10 seconds. */\n\tflushTimeoutMs?: number;\n\t/** Lifecycle flush failures are observable without becoming unhandled. */\n\tonError?: (error: unknown) => void;\n};\n\n/** Refreshes the socket/ticket and runs a bounded outbox flush after wake-up. */\nexport const installCapacitorSyncLifecycle = async ({\n\tclient,\n\tlifecycle,\n\tnetwork,\n\tflushTimeoutMs = 10_000,\n\tonError\n}: CapacitorSyncLifecycleOptions): Promise<DeviceSubscription> => {\n\tif (!Number.isFinite(flushTimeoutMs) || flushTimeoutMs < 0)\n\t\tthrow new TypeError(\n\t\t\t'Capacitor Sync flushTimeoutMs must be a non-negative number.'\n\t\t);\n\tconst wake = () => {\n\t\tclient.reconnect();\n\t\tvoid client\n\t\t\t.flush?.({ timeoutMs: flushTimeoutMs })\n\t\t\t.catch((error) => onError?.(error));\n\t};\n\tconst removers = await Promise.all([\n\t\tlifecycle.onResume?.(wake) ?? (() => undefined),\n\t\tnetwork.onChange((status) => {\n\t\t\tif (status.connected) wake();\n\t\t})\n\t]);\n\tlet active = true;\n\treturn async () => {\n\t\tif (!active) return;\n\t\tactive = false;\n\t\tawait Promise.all(removers.map((remove) => remove()));\n\t};\n};\n"
   ],
-  "mappings": ";AAAA;AAAA;AAAA;AAAA;AAyCA,IAAM,SAAS;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAwBf,IAAM,cAAc,CAAC,MAA+B,UAAkB;AAAA,EACrE,MAAM,QAAQ,OAAO,KAAK;AAAA,EAC1B,OAAO,OAAO,UAAU,WAAW,QAAQ;AAAA;AAG5C,IAAM,cAAc,CAAI,OAAgB,UAAiC;AAAA,EACxE,IAAI,UAAU;AAAA,IAAW;AAAA,EACzB,IAAI,OAAO,UAAU;AAAA,IACpB,MAAM,IAAI,MACT,0CAA0C,aAC3C;AAAA,EACD,IAAI;AAAA,IACH,OAAO,KAAK,MAAM,KAAK;AAAA,IACtB,OAAO,OAAO;AAAA,IACf,MAAM,IAAI,MACT,yCAAyC,eACzC;AAAA,MACC;AAAA,IACD,CACD;AAAA;AAAA;AAIF,IAAM,oBAAoB,OACzB,iBAC4C;AAAA,EAC5C,MAAM,SAAS,IAAI,iBAAiB,eAAe;AAAA,EACnD,MAAM,WAAW,MAAM,OAAO,aAAa,cAAc,KAAK;AAAA,EAC9D,MAAM,aAAa,SAAS,SACzB,MAAM,OAAO,mBAAmB,cAAc,KAAK,IACnD,MAAM,OAAO,iBACb,cACA,OACA,iBACA,GACA,KACD;AAAA,EACF,MAAM,WAAW,KAAK;AAAA,EACtB,OAAO;AAAA;AAGR,IAAM,mBAAmB,CAAC,cAAsB;AAAA,EAC/C,IAAI,UAAU,WAAW;AAAA,IACxB,MAAM,IAAI,MAAM,8CAA8C;AAAA;AAQzD,IAAM,gCAAgC;AAAA,EAC5C,eAAe;AAAA,EACf,YAAY,mBAAmB,MAAM,kBAAkB,YAAY;AAAA,IAChC,CAAC,MAAsB;AAAA,EAC1D,IAAI,aAAa,WAAW;AAAA,IAC3B,MAAM,IAAI,UAAU,8CAA8C;AAAA,EACnE,IAAI;AAAA,EACJ,MAAM,aAAa,MAAM;AAAA,IACxB,sBAAsB,QAAQ,QAAQ,iBAAiB,CAAC,EAAE,KACzD,OAAO,aAAa;AAAA,MACnB,MAAM,SAAS,QAAQ,MAAM;AAAA,MAC7B,OAAO;AAAA,KAET;AAAA,IACA,OAAO;AAAA;AAAA,EAER,IAAI,OAAO,QAAQ,QAAQ;AAAA,EAC3B,MAAM,SAAS,OAAU,QAAsC;AAAA,IAC9D,IAAI;AAAA,IACJ,MAAM,WAAW;AAAA,IACjB,OAAO,IAAI,QAAc,CAAC,YAAY;AAAA,MACrC,UAAU;AAAA,KACV;AAAA,IACD,MAAM;AAAA,IACN,IAAI;AAAA,MACH,OAAO,MAAM,IAAI;AAAA,cAChB;AAAA,MACD,QAAQ;AAAA;AAAA;AAAA,EAIV,MAAM,cAAc,OACnB,WACA,MACA,QACgB;AAAA,IAChB,iBAAiB,SAAS;AAAA,IAC1B,OAAO,OAAO,YAAY;AAAA,MACzB,MAAM,WAAW,MAAM,WAAW;AAAA,MAClC,MAAM,SAAS,iBAAiB;AAAA,MAChC,MAAM,WAAW,MAAM;AAAA,QACtB,IAAI,SAAS;AAAA,UACZ,MAAM,IAAI,MACT,mDACD;AAAA;AAAA,MAEF,MAAM,KAA2B;AAAA,QAChC,mBAAmB,YAClB,aAEE,MAAM,SAAS,MACd,kFACA,CAAC,SAAS,CACX,GACC,QACF,iBACD;AAAA,QACD,mBAAmB,OAAO,mBAAmB;AAAA,UAC5C,SAAS;AAAA,UACT,IAAI,eAAe,WAAW;AAAA,YAC7B,MAAM,IAAI,MACT,wCACD;AAAA,UACD,MAAM,SAAS,IACd,iKACA,CAAC,WAAW,cAAc,GAC1B,KACD;AAAA;AAAA,QAED,eAAe,OAAU,QACxB,aAEE,MAAM,SAAS,MACd,wGACA,CAAC,WAAW,GAAG,CAChB,GACC,SAAS,IAAI,aACf,YACD;AAAA,QACD,eAAe,OAAO,KAAK,WAAW;AAAA,UACrC,SAAS;AAAA,UACT,MAAM,SAAS,IACd,2LACA,CAAC,WAAW,KAAK,KAAK,UAAU,MAAM,CAAC,GACvC,KACD;AAAA;AAAA,QAED,kBAAkB,OAAO,QAAQ;AAAA,UAChC,SAAS;AAAA,UACT,MAAM,SAAS,IACd,oFACA,CAAC,WAAW,GAAG,GACf,KACD;AAAA;AAAA,QAED,eAAe,YAAY;AAAA,UAC1B,MAAM,QACL,MAAM,SAAS,MACd,iHACA,CAAC,SAAS,CACX,GACC;AAAA,UACF,QAAQ,QAAQ,CAAC,GACf,IAAI,CAAC,QACL,YACC,IAAI,aACJ,UACD,CACD,EACC,OACA,CAAC,WACA,WAAW,SACb;AAAA;AAAA,QAEF,aAAa,OAAO,gBACnB,aAEE,MAAM,SAAS,MACd,oGACA,CAAC,WAAW,WAAW,CACxB,GACC,SAAS,IAAI,aACf,UACD;AAAA,QACD,aAAa,OAAO,WAAW;AAAA,UAC9B,SAAS;AAAA,UACT,MAAM,SAAS,IACd,sOACA;AAAA,YACC;AAAA,YACA,OAAO;AAAA,YACP,OAAO;AAAA,YACP,KAAK,UAAU,MAAM;AAAA,UACtB,GACA,KACD;AAAA;AAAA,QAED,gBAAgB,OAAO,gBAAgB;AAAA,UACtC,SAAS;AAAA,UACT,MAAM,SAAS,IACd,gFACA,CAAC,WAAW,WAAW,GACvB,KACD;AAAA;AAAA,MAEF;AAAA,MACA,IAAI;AAAA,QACH,MAAM,SAAS,MAAM,IAAI,EAAE;AAAA,QAC3B,MAAM,SAAS,kBAAkB;AAAA,QACjC,OAAO;AAAA,QACN,OAAO,OAAO;AAAA,QACf,IAAI;AAAA,UACH,MAAM,SAAS,oBAAoB;AAAA,UAClC,OAAO,eAAe;AAAA,UACvB,MAAM,IAAI,eACT,CAAC,OAAO,aAAa,GACrB,4DACD;AAAA;AAAA,QAED,MAAM;AAAA;AAAA,KAEP;AAAA;AAAA,EAGF,OAAO;AAAA,IACN;AAAA,IACA,iBAAiB,OAAO,cAAc;AAAA,MACrC,iBAAiB,SAAS;AAAA,MAC1B,MAAM,OAAO,YAAY;AAAA,QACxB,MAAM,WAAW,MAAM,WAAW;AAAA,QAClC,MAAM,SAAS,iBAAiB;AAAA,QAChC,IAAI;AAAA,UACH,WAAW,SAAS;AAAA,YACnB;AAAA,YACA;AAAA,YACA;AAAA,UACD;AAAA,YACC,MAAM,SAAS,IACd,eAAe,6BACf,CAAC,SAAS,GACV,KACD;AAAA,UACD,MAAM,SAAS,kBAAkB;AAAA,UAChC,OAAO,OAAO;AAAA,UACf,MAAM,SAAS,oBAAoB;AAAA,UACnC,MAAM;AAAA;AAAA,OAEP;AAAA;AAAA,EAEH;AAAA;AAcM,IAAM,gCAAgC;AAAA,EAC5C;AAAA,EACA;AAAA,EACA;AAAA,EACA,iBAAiB;AAAA,EACjB;AAAA,MACiE;AAAA,EACjE,IAAI,CAAC,OAAO,SAAS,cAAc,KAAK,iBAAiB;AAAA,IACxD,MAAM,IAAI,UACT,8DACD;AAAA,EACD,MAAM,OAAO,MAAM;AAAA,IAClB,OAAO,UAAU;AAAA,IACZ,OACH,QAAQ,EAAE,WAAW,eAAe,CAAC,EACrC,MAAM,CAAC,UAAU,UAAU,KAAK,CAAC;AAAA;AAAA,EAEpC,MAAM,WAAW,MAAM,QAAQ,IAAI;AAAA,IAClC,UAAU,WAAW,IAAI,MAAM,MAAG;AAAA,MAAG;AAAA;AAAA,IACrC,QAAQ,SAAS,CAAC,WAAW;AAAA,MAC5B,IAAI,OAAO;AAAA,QAAW,KAAK;AAAA,KAC3B;AAAA,EACF,CAAC;AAAA,EACD,IAAI,SAAS;AAAA,EACb,OAAO,YAAY;AAAA,IAClB,IAAI,CAAC;AAAA,MAAQ;AAAA,IACb,SAAS;AAAA,IACT,MAAM,QAAQ,IAAI,SAAS,IAAI,CAAC,WAAW,OAAO,CAAC,CAAC;AAAA;AAAA;",
-  "debugId": "9D6EB7498C1CD6F664756E2164756E21",
+  "mappings": "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",
+  "debugId": "1D548F4E3CBABDF264756E2164756E21",
   "names": []
 }

package/ios/Sources/AbsoluteSyncCapacitor/AbsoluteBackgroundSyncEngine.swift

@@ -0,0 +1,143 @@
+import AbsoluteDevicesCapacitor
+import Foundation
+import SQLite3
+
+private let SQLITE_TRANSIENT = unsafeBitCast(-1, to: sqlite3_destructor_type.self)
+
+private final class NoRedirect: NSObject, URLSessionTaskDelegate {
+    func urlSession(_ session: URLSession, task: URLSessionTask, willPerformHTTPRedirection response: HTTPURLResponse, newRequest request: URLRequest, completionHandler: @escaping (URLRequest?) -> Void) { completionHandler(nil) }
+}
+
+private struct NativeMutation { let id: String; let attempts: Int }
+private struct NativeBatch { let body: [String: Any]; let mutations: [String: NativeMutation]; let pulls: [String: [String: Any]] }
+
+enum AbsoluteBackgroundSyncEngine {
+    private static let refreshKey = "absolutejs.auth.oidc.refresh"
+    private static let maxResponse = 5 * 1024 * 1024
+
+    static func record(_ error: Error) {
+        let defaults = AbsoluteBackgroundSyncPlugin.defaults
+        defaults.set(false, forKey: "absolutejs.background-sync.running")
+        defaults.set(error.localizedDescription, forKey: "absolutejs.background-sync.lastError")
+    }
+    static func run() async throws {
+        guard let config = try AbsoluteBackgroundSyncPlugin.configuration() else { return }
+        let defaults = AbsoluteBackgroundSyncPlugin.defaults
+        defaults.set(true, forKey: "absolutejs.background-sync.running"); defaults.removeObject(forKey: "absolutejs.background-sync.lastError")
+        let access = try await refreshAccess(config)
+        let documents = try FileManager.default.url(for: .documentDirectory, in: .userDomainMask, appropriateFor: nil, create: false)
+        var handle: OpaquePointer?
+        guard sqlite3_open_v2(documents.appendingPathComponent("\(config.databaseName)SQLite.db").path, &handle, SQLITE_OPEN_READWRITE | SQLITE_OPEN_FULLMUTEX, nil) == SQLITE_OK, let db = handle else { throw SyncNativeError.invalidResponse("Unable to open Sync database.") }
+        defer { sqlite3_close(db) }
+        sqlite3_busy_timeout(db, 5_000)
+        let batch = try prepare(db, config)
+        let response = try await jsonRequest(config.endpoint, method: "POST", body: batch.body, bearer: access, issuer: config.issuer)
+        let counts = try settle(db, config, batch, response)
+        defaults.set(false, forKey: "absolutejs.background-sync.running"); defaults.set(Date().timeIntervalSince1970 * 1000, forKey: "absolutejs.background-sync.lastRunAt")
+        defaults.set(counts.0, forKey: "absolutejs.background-sync.lastAcknowledged"); defaults.set(counts.1, forKey: "absolutejs.background-sync.lastPulled")
+    }
+
+    private static func refreshAccess(_ config: AbsoluteBackgroundSyncConfiguration) async throws -> String {
+        guard let lease = AbsoluteSecureStorageVault.acquireLease(refreshKey, ttlMilliseconds: 120_000) else { throw SyncNativeError.invalidResponse("Credential refresh is already running.") }
+        defer { AbsoluteSecureStorageVault.releaseLease(refreshKey, leaseId: lease) }
+        guard let refresh = try AbsoluteSecureStorageVault.get(refreshKey) else {
+            AbsoluteBackgroundSyncPlugin.defaults.set(false, forKey: "absolutejs.background-sync.running")
+            throw SyncNativeError.noSession
+        }
+        let discoveryURL = config.issuer.appendingPathComponent(".well-known/openid-configuration")
+        let discovery = try await jsonRequest(discoveryURL, method: "GET", body: nil, bearer: nil, issuer: config.issuer)
+        guard let endpointValue = discovery["token_endpoint"] as? String, let endpoint = URL(string: endpointValue) else { throw SyncNativeError.invalidResponse("OIDC discovery has no token endpoint.") }
+        let form = ["client_id": config.clientId, "grant_type": "refresh_token", "refresh_token": refresh, "resource": config.issuer.absoluteString]
+            .map { key, value in "\(encode(key))=\(encode(value))" }.joined(separator: "&").data(using: .utf8)!
+        let tokens = try await jsonRequest(endpoint, method: "POST", rawBody: form, contentType: "application/x-www-form-urlencoded", bearer: nil, issuer: config.issuer, advertisedTokenEndpoint: true)
+        guard let replacement = tokens["refresh_token"] as? String, !replacement.isEmpty,
+              let access = tokens["access_token"] as? String else { throw SyncNativeError.invalidResponse("OIDC token response is malformed.") }
+        guard try AbsoluteSecureStorageVault.setIfLease(refreshKey, value: replacement, leaseId: lease) else {
+            AbsoluteBackgroundSyncPlugin.defaults.set(false, forKey: "absolutejs.background-sync.running")
+            throw SyncNativeError.noSession
+        }
+        return access
+    }
+    private static func encode(_ value: String) -> String { value.addingPercentEncoding(withAllowedCharacters: .alphanumerics) ?? "" }
+
+    private static func prepare(_ db: OpaquePointer, _ config: AbsoluteBackgroundSyncConfiguration) throws -> NativeBatch {
+        try execute(db, "BEGIN IMMEDIATE")
+        do {
+            var mutations: [[String: Any]] = [], mutationMap: [String: NativeMutation] = [:]
+            for row in try rows(db, "SELECT operation_id,record_json FROM absolute_sync_mutations WHERE namespace=? ORDER BY created_at,operation_id", [config.namespace]) where mutations.count < config.maxMutations {
+                let id = row[0], record = try object(row[1]); let now = Date().timeIntervalSince1970 * 1000
+                if record["state"] as? String == "dead-letter" || (record["nextAttemptAt"] as? NSNumber)?.doubleValue ?? 0 > now { continue }
+                let attempts = ((record["attempts"] as? NSNumber)?.intValue ?? 0) + 1; var next = record; next["attempts"] = attempts; next.removeValue(forKey: "nextAttemptAt")
+                try updateRecord(db, "absolute_sync_mutations", "operation_id", config.namespace, id, next)
+				guard let name = record["name"] as? String else { throw SyncNativeError.invalidResponse("Local mutation has no name.") }
+                var mutation: [String: Any] = ["operationId": id, "name": name]; if let args = record["args"] { mutation["args"] = args }
+                mutations.append(mutation); mutationMap[id] = NativeMutation(id: id, attempts: attempts)
+            }
+            var pulls: [[String: Any]] = [], pullMap: [String: [String: Any]] = [:]
+            for row in try rows(db, "SELECT collection_key,record_json FROM absolute_sync_collections WHERE namespace=? ORDER BY collection_key", [config.namespace]) where pulls.count < config.maxPulls {
+                let key = row[0], record = try object(row[1]); guard let collection = record["collection"] as? String, !collection.isEmpty else { continue }
+                var pull: [String: Any] = ["id": key, "collection": collection]; if let params = record["params"] { pull["params"] = params }
+                if record["headlessKey"] as? String == "id" { if let cursor = record["cursor"] { pull["since"] = cursor } else if ((record["version"] as? NSNumber)?.intValue ?? 0) > 0 { pull["since"] = record["version"] } }
+                pulls.append(pull); pullMap[key] = record
+            }
+            try execute(db, "COMMIT")
+            return NativeBatch(body: ["version": 1, "mutations": mutations, "pulls": pulls], mutations: mutationMap, pulls: pullMap)
+        } catch { try? execute(db, "ROLLBACK"); throw error }
+    }
+
+    private static func settle(_ db: OpaquePointer, _ config: AbsoluteBackgroundSyncConfiguration, _ batch: NativeBatch, _ response: [String: Any]) throws -> (Int, Int) {
+        guard (response["version"] as? NSNumber)?.intValue == 1 else { throw SyncNativeError.invalidResponse("Unsupported Headless Sync response.") }
+        let mutationResults = index(response["mutations"], "operationId"), pullResults = index(response["pulls"], "id")
+        var acknowledged = 0, pulled = 0; try execute(db, "BEGIN IMMEDIATE")
+        do {
+            for sent in batch.mutations.values {
+                guard var current = try record(db, "absolute_sync_mutations", "operation_id", config.namespace, sent.id), (current["attempts"] as? NSNumber)?.intValue == sent.attempts else { continue }
+                if mutationResults[sent.id]?["status"] as? String == "ack" { try execute(db, "DELETE FROM absolute_sync_mutations WHERE namespace=? AND operation_id=?", [config.namespace, sent.id]); acknowledged += 1; continue }
+                let rejection = mutationResults[sent.id]?["rejection"] as? [String: Any] ?? ["kind": "retryable", "message": "Missing mutation response."]
+                current["lastError"] = rejection["message"]; current["rejection"] = rejection
+                if rejection["kind"] as? String != "retryable" || sent.attempts >= config.maxAttempts { current["state"] = "dead-letter"; current["deadLetteredAt"] = Date().timeIntervalSince1970 * 1000; current.removeValue(forKey: "nextAttemptAt") }
+                else { let hint = (rejection["retryAfterMs"] as? NSNumber)?.doubleValue ?? min(30_000, 500 * pow(2, Double(max(0, sent.attempts - 1)))); current["state"] = "pending"; current["nextAttemptAt"] = Date().timeIntervalSince1970 * 1000 + max(0, hint) }
+                try updateRecord(db, "absolute_sync_mutations", "operation_id", config.namespace, sent.id, current)
+            }
+            for (key, baseline) in batch.pulls {
+                guard let result = pullResults[key], result["type"] as? String != "error", let current = try record(db, "absolute_sync_collections", "collection_key", config.namespace, key), same(current, baseline) else { continue }
+                try updateRecord(db, "absolute_sync_collections", "collection_key", config.namespace, key, try applyPull(current, result)); pulled += 1
+            }
+            try execute(db, "COMMIT"); return (acknowledged, pulled)
+        } catch { try? execute(db, "ROLLBACK"); throw error }
+    }
+
+    private static func applyPull(_ current: [String: Any], _ result: [String: Any]) throws -> [String: Any] {
+        var next = current
+        if result["type"] as? String == "snapshot" { next["rows"] = result["rows"] }
+        else {
+            var keyed: [String: [String: Any]] = [:]; for row in current["rows"] as? [[String: Any]] ?? [] { keyed[try key(row)] = row }
+            for row in result["removed"] as? [[String: Any]] ?? [] { keyed.removeValue(forKey: try key(row)) }
+            for row in (result["changed"] as? [[String: Any]] ?? []) + (result["added"] as? [[String: Any]] ?? []) { keyed[try key(row)] = row }
+            next["rows"] = Array(keyed.values)
+        }
+        next["version"] = result["version"]; next["cursor"] = result["cursor"]; return next
+    }
+    private static func key(_ row: [String: Any]) throws -> String { guard let id = row["id"], id is String || id is NSNumber else { throw SyncNativeError.invalidResponse("Background Sync row requires id.") }; return "\(type(of: id)):\(id)" }
+    private static func same(_ a: [String: Any], _ b: [String: Any]) -> Bool { ((a["version"] as? NSNumber)?.intValue ?? 0) == ((b["version"] as? NSNumber)?.intValue ?? 0) && (a["cursor"] as? String ?? "") == (b["cursor"] as? String ?? "") }
+    private static func index(_ value: Any?, _ field: String) -> [String: [String: Any]] { var result: [String: [String: Any]] = [:]; for item in value as? [[String: Any]] ?? [] { if let key = item[field] as? String { result[key] = item } }; return result }
+
+    private static func object(_ json: String) throws -> [String: Any] { guard let value = try JSONSerialization.jsonObject(with: Data(json.utf8)) as? [String: Any] else { throw SyncNativeError.invalidResponse("Invalid local Sync record.") }; return value }
+    private static func record(_ db: OpaquePointer, _ table: String, _ field: String, _ namespace: String, _ id: String) throws -> [String: Any]? { guard let value = try rows(db, "SELECT record_json FROM \(table) WHERE namespace=? AND \(field)=? LIMIT 1", [namespace,id]).first?.first else { return nil }; return try object(value) }
+    private static func updateRecord(_ db: OpaquePointer, _ table: String, _ field: String, _ namespace: String, _ id: String, _ value: [String: Any]) throws { let json = String(data: try JSONSerialization.data(withJSONObject: value), encoding: .utf8)!; try execute(db, "UPDATE \(table) SET record_json=? WHERE namespace=? AND \(field)=?", [json,namespace,id]) }
+    private static func rows(_ db: OpaquePointer, _ sql: String, _ bindings: [String]) throws -> [[String]] { var statement: OpaquePointer?; guard sqlite3_prepare_v2(db,sql,-1,&statement,nil)==SQLITE_OK else { throw SyncNativeError.invalidResponse("SQLite prepare failed.") }; defer{sqlite3_finalize(statement)}; for (i,value) in bindings.enumerated(){sqlite3_bind_text(statement,Int32(i+1),(value as NSString).utf8String,-1,SQLITE_TRANSIENT)}; var output:[[String]]=[]; while sqlite3_step(statement)==SQLITE_ROW { output.append((0..<sqlite3_column_count(statement)).map{String(cString:sqlite3_column_text(statement,$0))}) }; return output }
+    private static func execute(_ db: OpaquePointer, _ sql: String, _ bindings: [String] = []) throws { var statement: OpaquePointer?; guard sqlite3_prepare_v2(db,sql,-1,&statement,nil)==SQLITE_OK else { throw SyncNativeError.invalidResponse("SQLite prepare failed.") }; defer{sqlite3_finalize(statement)}; for(i,value)in bindings.enumerated(){sqlite3_bind_text(statement,Int32(i+1),(value as NSString).utf8String,-1,SQLITE_TRANSIENT)}; guard sqlite3_step(statement)==SQLITE_DONE else { throw SyncNativeError.invalidResponse("SQLite write failed.") } }
+
+    private static func jsonRequest(_ url: URL, method: String, body: [String: Any]?, bearer: String?, issuer: URL) async throws -> [String: Any] { try await jsonRequest(url, method: method, rawBody: body.map{try! JSONSerialization.data(withJSONObject:$0)}, contentType: body == nil ? nil : "application/json", bearer: bearer, issuer: issuer) }
+    private static func jsonRequest(_ url: URL, method: String, rawBody: Data?, contentType: String?, bearer: String?, issuer: URL, advertisedTokenEndpoint: Bool = false) async throws -> [String: Any] {
+        guard (rawBody?.count ?? 0) <= maxResponse else { throw SyncNativeError.invalidResponse("Background request is too large.") }
+        if advertisedTokenEndpoint {
+            let loopback = url.scheme == "http" && ["localhost", "127.0.0.1", "::1"].contains(url.host?.lowercased() ?? "")
+            guard (url.scheme == "https" || loopback), url.user == nil, url.password == nil, url.fragment == nil else { throw SyncNativeError.invalidResponse("OIDC advertised an unsafe token endpoint.") }
+        } else {
+            guard AbsoluteBackgroundSyncConfiguration.origin(url)==AbsoluteBackgroundSyncConfiguration.origin(issuer) else { throw SyncNativeError.invalidResponse("Background request left the Auth issuer origin.") }
+        }
+        var request=URLRequest(url:url);request.httpMethod=method;request.httpBody=rawBody;request.timeoutInterval=20;request.setValue("application/json",forHTTPHeaderField:"Accept");if let contentType{request.setValue(contentType,forHTTPHeaderField:"Content-Type")};if let bearer{request.setValue("Bearer \(bearer)",forHTTPHeaderField:"Authorization")}
+        let session=URLSession(configuration:.ephemeral,delegate:NoRedirect(),delegateQueue:nil);let(data,response)=try await session.data(for:request);guard data.count<=maxResponse,let http=response as? HTTPURLResponse,(200..<300).contains(http.statusCode),let value=try JSONSerialization.jsonObject(with:data)as?[String:Any]else{throw SyncNativeError.invalidResponse("Background request failed.")};return value
+    }
+}

package/ios/Sources/AbsoluteSyncCapacitor/AbsoluteBackgroundSyncPlugin.swift

@@ -0,0 +1,98 @@
+import BackgroundTasks
+import Capacitor
+import Foundation
+
+private let taskSuffix = ".absolutejs.background-sync"
+
+struct AbsoluteBackgroundSyncConfiguration: Codable {
+    let endpoint: URL
+    let issuer: URL
+    let clientId: String
+    let namespace: String
+    let databaseName: String
+    let intervalMinutes: Int
+    let maxMutations: Int
+    let maxPulls: Int
+    let maxAttempts: Int
+
+    init(call: CAPPluginCall) throws {
+        guard let endpointValue = call.getString("endpoint"), let endpoint = URL(string: endpointValue),
+              let issuerValue = call.getString("issuer"), let issuer = URL(string: issuerValue),
+              let clientId = call.getString("clientId"), !clientId.isEmpty,
+              let namespace = call.getString("namespace"), !namespace.isEmpty else { throw SyncNativeError.invalidConfiguration }
+        guard Self.origin(endpoint) == Self.origin(issuer), endpoint.user == nil, endpoint.password == nil,
+              issuer.path.isEmpty || issuer.path == "/", issuer.query == nil, issuer.fragment == nil else { throw SyncNativeError.invalidConfiguration }
+		let loopback = issuer.scheme == "http" && ["localhost", "127.0.0.1", "::1"].contains(issuer.host?.lowercased() ?? "")
+		guard issuer.scheme == "https" || loopback else { throw SyncNativeError.invalidConfiguration }
+        let databaseName = call.getString("databaseName") ?? "absolutejs-sync-local-v1"
+        guard databaseName.range(of: "^[A-Za-z0-9._-]{1,128}$", options: .regularExpression) != nil else { throw SyncNativeError.invalidConfiguration }
+        let interval = call.getInt("intervalMinutes") ?? 15
+        let mutationLimit = call.getInt("maxMutations") ?? 50
+        let pullLimit = call.getInt("maxPulls") ?? 50
+        let attemptLimit = call.getInt("maxAttempts") ?? 5
+        guard interval >= 15 && interval <= 1440, mutationLimit >= 0 && mutationLimit <= 100, pullLimit >= 0 && pullLimit <= 100, attemptLimit >= 1 && attemptLimit <= 100 else { throw SyncNativeError.invalidConfiguration }
+        self.endpoint = endpoint; self.issuer = issuer; self.clientId = clientId; self.namespace = namespace
+        self.databaseName = databaseName; intervalMinutes = interval; maxMutations = mutationLimit; maxPulls = pullLimit; maxAttempts = attemptLimit
+    }
+
+    static func origin(_ url: URL) -> String {
+        let port = url.port ?? (url.scheme == "https" ? 443 : 80)
+        return "\(url.scheme ?? "")://\(url.host?.lowercased() ?? ""):\(port)"
+    }
+}
+
+enum SyncNativeError: Error { case invalidConfiguration, noSession, invalidResponse(String) }
+
+@objc(AbsoluteBackgroundSyncPlugin)
+public class AbsoluteBackgroundSyncPlugin: CAPPlugin, CAPBridgedPlugin {
+    public let identifier = "AbsoluteBackgroundSyncPlugin"
+    public let jsName = "AbsoluteBackgroundSync"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "configure", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "clear", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "runNow", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "status", returnType: CAPPluginReturnPromise),
+    ]
+    static var taskIdentifier: String { "\(Bundle.main.bundleIdentifier ?? "absolutejs.app")\(taskSuffix)" }
+    static let defaults = UserDefaults.standard
+    static let configKey = "absolutejs.background-sync.config"
+
+    /** AbsoluteJS inserts this call in AppDelegate before launch completes. */
+    @objc public static func registerBackgroundTask() {
+        BGTaskScheduler.shared.register(forTaskWithIdentifier: taskIdentifier, using: nil) { task in
+            guard let processing = task as? BGProcessingTask else { task.setTaskCompleted(success: false); return }
+            let work = Task {
+                do { try await AbsoluteBackgroundSyncEngine.run(); schedule(); processing.setTaskCompleted(success: true) }
+                catch SyncNativeError.noSession { processing.setTaskCompleted(success: true) }
+                catch { AbsoluteBackgroundSyncEngine.record(error); schedule(); processing.setTaskCompleted(success: false) }
+            }
+            processing.expirationHandler = { work.cancel() }
+        }
+    }
+
+    static func configuration() throws -> AbsoluteBackgroundSyncConfiguration? {
+        guard let data = defaults.data(forKey: configKey) else { return nil }
+        return try JSONDecoder().decode(AbsoluteBackgroundSyncConfiguration.self, from: data)
+    }
+    static func schedule() {
+        guard let config = try? configuration() else { return }
+        let request = BGProcessingTaskRequest(identifier: taskIdentifier)
+        request.requiresNetworkConnectivity = true
+        request.earliestBeginDate = Date(timeIntervalSinceNow: TimeInterval(config.intervalMinutes * 60))
+        try? BGTaskScheduler.shared.submit(request)
+    }
+    static func statusValue() -> [String: Any] {
+        var value: [String: Any] = ["configured": defaults.data(forKey: configKey) != nil, "running": defaults.bool(forKey: "absolutejs.background-sync.running")]
+        for key in ["lastRunAt", "lastAcknowledged", "lastPulled"] where defaults.object(forKey: "absolutejs.background-sync.\(key)") != nil { value[key] = defaults.object(forKey: "absolutejs.background-sync.\(key)")! }
+        if let error = defaults.string(forKey: "absolutejs.background-sync.lastError") { value["lastError"] = error }
+        return value
+    }
+
+    @objc func configure(_ call: CAPPluginCall) {
+        do { let config = try AbsoluteBackgroundSyncConfiguration(call: call); Self.defaults.set(try JSONEncoder().encode(config), forKey: Self.configKey); Self.schedule(); call.resolve() }
+        catch { call.reject("Invalid background Sync configuration.", "INVALID_ARGUMENT", error) }
+    }
+    @objc func clear(_ call: CAPPluginCall) { BGTaskScheduler.shared.cancel(taskRequestWithIdentifier: Self.taskIdentifier); Self.defaults.removeObject(forKey: Self.configKey); call.resolve() }
+    @objc func runNow(_ call: CAPPluginCall) { Task { do { try await AbsoluteBackgroundSyncEngine.run(); call.resolve(Self.statusValue()) } catch SyncNativeError.noSession { Self.defaults.set(false, forKey: "absolutejs.background-sync.running"); call.resolve(Self.statusValue()) } catch { AbsoluteBackgroundSyncEngine.record(error); call.reject("Background Sync failed.", "SYNC_FAILURE", error) } } }
+    @objc func status(_ call: CAPPluginCall) { call.resolve(Self.statusValue()) }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@absolutejs/sync-capacitor",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Transactional Capacitor SQLite local store and native lifecycle adapter for @absolutejs/sync",
 	"repository": {
 		"type": "git",
@@ -29,20 +29,24 @@
 		"mobile"
 	],
 	"scripts": {
-		"build": "rm -rf dist && bun build src/index.ts --outdir dist --sourcemap --target=browser --external @absolutejs/sync --external @absolutejs/devices --external @capacitor-community/sqlite && tsc --project tsconfig.build.json",
+		"build": "rm -rf dist && bun build src/index.ts --outdir dist --sourcemap --target=browser --external @absolutejs/sync --external @absolutejs/devices --external @capacitor/core --external @capacitor-community/sqlite && tsc --project tsconfig.build.json",
 		"test": "bun test",
 		"typecheck": "tsc --noEmit",
 		"format": "prettier --write \"./**/*.{ts,json,md}\"",
 		"release": "bun run format && bun run typecheck && bun test && bun run build && npm publish"
 	},
 	"peerDependencies": {
-		"@absolutejs/devices": ">=0.0.2 <0.1.0",
-		"@absolutejs/sync": ">=2.22.0 <3",
+		"@absolutejs/devices": ">=0.0.3 <0.1.0",
+		"@absolutejs/devices-capacitor": ">=0.1.3 <0.2.0",
+		"@absolutejs/sync": ">=2.23.0 <3",
+		"@capacitor/core": ">=8 <9",
 		"@capacitor-community/sqlite": ">=8.1.1 <9"
 	},
 	"devDependencies": {
-		"@absolutejs/devices": "0.0.2",
-		"@absolutejs/sync": "2.22.0",
+		"@absolutejs/devices": "0.0.3",
+		"@absolutejs/devices-capacitor": "0.1.3",
+		"@absolutejs/sync": "2.23.0",
+		"@capacitor/core": "8.5.0",
 		"@capacitor-community/sqlite": "8.1.1",
 		"@types/bun": "1.3.14",
 		"prettier": "3.5.3",
@@ -56,8 +60,21 @@
 		}
 	},
 	"files": [
+		"android/src/main/",
+		"android/build.gradle",
 		"dist",
+		"ios/Sources/",
+		"Package.swift",
+		"AbsoluteSyncCapacitor.podspec",
 		"LICENSE",
 		"README.md"
-	]
+	],
+	"capacitor": {
+		"android": {
+			"src": "android"
+		},
+		"ios": {
+			"src": "ios"
+		}
+	}
 }