@craftthingy-digital-innovation/cty-offline-outbox-sync-web 1.0.0

package/LICENSE

@@ -0,0 +1,38 @@
+Public-Source Corporate Royalty License (PSCRL)
+
+Copyright (c) 2026 Alif Nurhidayat (alifnurhidayatwork@gmail.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction for non-commercial, personal, educational,
+research, and open-source public use, subject to the following conditions:
+
+1. NON-COMMERCIAL & PUBLIC USE
+The Software is completely free to use, modify, and distribute for individuals,
+educational institutions, personal research, testing, and non-commercial open-source
+projects.
+
+2. CORPORATE & COMMERCIAL BUSINESS USE
+Any use of the Software by for-profit companies, corporations, commercial applications,
+SaaS (Software as a Service) platforms, or for any revenue-generating activity
+requires a commercial licensing agreement. 
+
+By using this Software for commercial or corporate purposes, you agree to:
+a. Pay a royalty fee of 1% (one percent) of the gross monthly revenue generated by
+   any product, service, or platform that incorporates or uses this Software.
+b. Startups or businesses with gross annual revenues of less than $10,000 USD (or equivalent)
+   are exempt from royalties until they exceed this threshold.
+c. Provide quarterly reporting of gross revenues generated to the copyright holder.
+
+3. CONTACT & CUSTOM LICENSING
+For royalty payments, reporting, custom enterprise flat-rate licenses, or general inquiries,
+contact the copyright holder directly at:
+alifnurhidayatwork@gmail.com
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# @craftthingy-digital-innovation/cty-offline-outbox-sync-web
+
+Bilingual documentation: [Bahasa Indonesia](#bahasa-indonesia) | [English](#english)
+
+---
+
+## Bahasa Indonesia
+
+Library client-side Javascript untuk menangani pengiriman data otomatis (auto-save) dengan kemampuan penyimpanan lokal sementara (`localStorage` outbox) dan pencobaan ulang otomatis (`auto-retry`) berkala jika koneksi terputus.
+
+Sangat berguna untuk aplikasi web yang membutuhkan persistensi tinggi (seperti spreadsheet, form panjang, CRM) agar terhindar dari kehilangan data saat jaringan buruk.
+
+### Instalasi
+```bash
+npm install @craftthingy-digital-innovation/cty-offline-outbox-sync-web
+```
+
+### Cara Penggunaan
+```javascript
+import { OfflineOutbox } from '@craftthingy-digital-innovation/cty-offline-outbox-sync-web';
+
+const outbox = new OfflineOutbox({
+  storageKey: 'paspor_offline_queue', // Kunci localStorage
+  retryInterval: 6000, // Waktu tunggu coba kembali (6 detik)
+  onSync: async (item) => {
+    // Jalankan pengiriman data asinkron Anda ke server
+    const response = await fetch('/api/save', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(item.postData)
+    });
+    return await response.json();
+  }
+});
+
+// Masukkan perubahan data ke outbox (akan di-merge otomatis jika UUID sama)
+outbox.enqueue('row-uuid-123', { nama_pemohon: 'Alif Nurhidayat' });
+
+// Dengarkan perubahan status sinkronisasi untuk update UI badge
+outbox.on('status-change', ({ pendingCount, online }) => {
+  if (!online) {
+    updateStatusUI(`Koneksi terputus. Menyimpan lokal... (${pendingCount} tertunda)`);
+  } else if (pendingCount > 0) {
+    updateStatusUI(`Menyinkronkan... (${pendingCount} perubahan)`);
+  } else {
+    updateStatusUI('Semua data tersimpan otomatis');
+  }
+});
+```
+
+---
+
+## English
+
+A client-side JavaScript library to handle automatic form submissions (auto-save) with local cache fallback (`localStorage` outbox) and periodic auto-retry capabilities when connections are disrupted.
+
+Extremely useful for sheets, databases, long forms, or CRMs to prevent data loss on unstable networks.
+
+### Installation
+```bash
+npm install @craftthingy-digital-innovation/cty-offline-outbox-sync-web
+```
+
+### Usage
+```javascript
+import { OfflineOutbox } from '@craftthingy-digital-innovation/cty-offline-outbox-sync-web';
+
+const outbox = new OfflineOutbox({
+  storageKey: 'paspor_offline_queue', // Key in localStorage
+  retryInterval: 6000, // Retry interval (6 seconds)
+  onSync: async (item) => {
+    // Execute your async API save request
+    const response = await fetch('/api/save', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(item.postData)
+    });
+    return await response.json();
+  }
+});
+
+// Enqueue changes (automatically merged if same UUID is modified)
+outbox.enqueue('row-uuid-123', { nama_pemohon: 'Alif Nurhidayat' });
+
+// Listen for status changes to update your UI indicators
+outbox.on('status-change', ({ pendingCount, online }) => {
+  if (!online) {
+    updateStatusUI(`Connection offline. Saved locally (${pendingCount} pending)`);
+  } else if (pendingCount > 0) {
+    updateStatusUI(`Syncing... (${pendingCount} changes)`);
+  } else {
+    updateStatusUI('All data saved automatically');
+  }
+});
+```

package/dist/cty-offline-outbox-sync.es.js

@@ -0,0 +1,85 @@
+class i extends EventTarget {
+  constructor(t = {}) {
+    super(), this.storageKey = t.storageKey || "cty_offline_outbox_queue", this.retryInterval = t.retryInterval || 6e3, this.onSync = t.onSync || null, this.queue = JSON.parse(localStorage.getItem(this.storageKey) || "[]"), this.isProcessing = !1, typeof window < "u" && (window.addEventListener("online", () => {
+      this.dispatchEvent(new CustomEvent("network-status-change", { detail: { online: !0 } })), this.processQueue();
+    }), window.addEventListener("offline", () => {
+      this.dispatchEvent(new CustomEvent("network-status-change", { detail: { online: !1 } }));
+    }));
+  }
+  /**
+   * Enqueues data for submission. Deduplicates by uuid.
+   * @param {string} uuid Unique identifier for the row/entity
+   * @param {object} postData Fields and values to update
+   */
+  enqueue(t, e) {
+    const s = this.queue.findIndex((n) => n.uuid === t);
+    s !== -1 ? (Object.assign(this.queue[s].postData, e), this.queue[s].timestamp = Date.now()) : this.queue.push({
+      uuid: t,
+      postData: e,
+      timestamp: Date.now(),
+      attempts: 0
+    }), this.save(), this.notifyStatus(), this.processQueue();
+  }
+  /**
+   * Saves the queue to local storage
+   */
+  save() {
+    localStorage.setItem(this.storageKey, JSON.stringify(this.queue));
+  }
+  /**
+   * Dispatches status update events
+   */
+  notifyStatus(t = !1) {
+    const e = typeof navigator < "u" ? navigator.onLine : !0;
+    this.dispatchEvent(new CustomEvent("status-change", {
+      detail: {
+        pendingCount: this.queue.length,
+        online: e && !t,
+        queue: [...this.queue]
+      }
+    }));
+  }
+  /**
+   * Processes the first item in the queue recursively
+   */
+  async processQueue() {
+    if (this.isProcessing || this.queue.length === 0) return;
+    if (!(typeof navigator < "u" ? navigator.onLine : !0)) {
+      this.notifyStatus(!0);
+      return;
+    }
+    this.isProcessing = !0;
+    const e = this.queue[0];
+    this.dispatchEvent(new CustomEvent("sync-start", { detail: { item: e } }));
+    try {
+      if (typeof this.onSync != "function")
+        throw new Error("onSync callback is not registered or not a function.");
+      const s = await this.onSync(e);
+      this.queue.shift(), this.save(), this.dispatchEvent(new CustomEvent("sync-success", { detail: { item: e, result: s } })), this.isProcessing = !1, this.notifyStatus(), this.processQueue();
+    } catch (s) {
+      console.warn("Outbox sync failed, will retry:", s), e.attempts++, this.save(), this.dispatchEvent(new CustomEvent("sync-failure", { detail: { item: e, error: s } })), this.isProcessing = !1, this.notifyStatus(!0), setTimeout(() => this.processQueue(), this.retryInterval);
+    }
+  }
+  /**
+   * Clear all pending items in the queue
+   */
+  clear() {
+    this.queue = [], this.save(), this.notifyStatus();
+  }
+  /**
+   * Get all queued items
+   */
+  getQueue() {
+    return [...this.queue];
+  }
+  /**
+   * Callback binder helper
+   */
+  on(t, e) {
+    this.addEventListener(t, (s) => e(s.detail));
+  }
+}
+typeof window < "u" && (window.OfflineOutbox = i);
+export {
+  i as OfflineOutbox
+};

package/dist/cty-offline-outbox-sync.umd.js

@@ -0,0 +1 @@
+(function(n,i){typeof exports=="object"&&typeof module<"u"?i(exports):typeof define=="function"&&define.amd?define(["exports"],i):(n=typeof globalThis<"u"?globalThis:n||self,i(n.OfflineOutbox={}))})(this,function(n){"use strict";class i extends EventTarget{constructor(t={}){super(),this.storageKey=t.storageKey||"cty_offline_outbox_queue",this.retryInterval=t.retryInterval||6e3,this.onSync=t.onSync||null,this.queue=JSON.parse(localStorage.getItem(this.storageKey)||"[]"),this.isProcessing=!1,typeof window<"u"&&(window.addEventListener("online",()=>{this.dispatchEvent(new CustomEvent("network-status-change",{detail:{online:!0}})),this.processQueue()}),window.addEventListener("offline",()=>{this.dispatchEvent(new CustomEvent("network-status-change",{detail:{online:!1}}))}))}enqueue(t,e){const s=this.queue.findIndex(o=>o.uuid===t);s!==-1?(Object.assign(this.queue[s].postData,e),this.queue[s].timestamp=Date.now()):this.queue.push({uuid:t,postData:e,timestamp:Date.now(),attempts:0}),this.save(),this.notifyStatus(),this.processQueue()}save(){localStorage.setItem(this.storageKey,JSON.stringify(this.queue))}notifyStatus(t=!1){const e=typeof navigator<"u"?navigator.onLine:!0;this.dispatchEvent(new CustomEvent("status-change",{detail:{pendingCount:this.queue.length,online:e&&!t,queue:[...this.queue]}}))}async processQueue(){if(this.isProcessing||this.queue.length===0)return;if(!(typeof navigator<"u"?navigator.onLine:!0)){this.notifyStatus(!0);return}this.isProcessing=!0;const e=this.queue[0];this.dispatchEvent(new CustomEvent("sync-start",{detail:{item:e}}));try{if(typeof this.onSync!="function")throw new Error("onSync callback is not registered or not a function.");const s=await this.onSync(e);this.queue.shift(),this.save(),this.dispatchEvent(new CustomEvent("sync-success",{detail:{item:e,result:s}})),this.isProcessing=!1,this.notifyStatus(),this.processQueue()}catch(s){console.warn("Outbox sync failed, will retry:",s),e.attempts++,this.save(),this.dispatchEvent(new CustomEvent("sync-failure",{detail:{item:e,error:s}})),this.isProcessing=!1,this.notifyStatus(!0),setTimeout(()=>this.processQueue(),this.retryInterval)}}clear(){this.queue=[],this.save(),this.notifyStatus()}getQueue(){return[...this.queue]}on(t,e){this.addEventListener(t,s=>e(s.detail))}}typeof window<"u"&&(window.OfflineOutbox=i),n.OfflineOutbox=i,Object.defineProperty(n,Symbol.toStringTag,{value:"Module"})});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@craftthingy-digital-innovation/cty-offline-outbox-sync-web",
+  "version": "1.0.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CraftThingy-Digital-Innovation/cty-offline-outbox-sync-web.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CraftThingy-Digital-Innovation/cty-offline-outbox-sync-web/issues"
+  },
+  "homepage": "https://github.com/CraftThingy-Digital-Innovation/cty-offline-outbox-sync-web#readme",
+  "main": "./dist/cty-offline-outbox-sync.umd.js",
+  "module": "./dist/cty-offline-outbox-sync.es.js",
+  "exports": {
+    ".": {
+      "import": "./dist/cty-offline-outbox-sync.es.js",
+      "require": "./dist/cty-offline-outbox-sync.umd.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "vite": "^5.2.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,153 @@
+/**
+ * cty-offline-outbox-sync-web
+ * Offline Outbox Auto-Retry Manager
+ * Public-Source Corporate Royalty License (PSCRL)
+ * Copyright (c) 2026 CraftThingy Digital Innovation & Alif Nurhidayat
+ */
+
+export class OfflineOutbox extends EventTarget {
+  constructor(options = {}) {
+    super();
+    this.storageKey = options.storageKey || 'cty_offline_outbox_queue';
+    this.retryInterval = options.retryInterval || 6000;
+    this.onSync = options.onSync || null; // Async function (item) => Promise<any>
+    
+    this.queue = JSON.parse(localStorage.getItem(this.storageKey) || '[]');
+    this.isProcessing = false;
+
+    // Listen to network status changes automatically
+    if (typeof window !== 'undefined') {
+      window.addEventListener('online', () => {
+        this.dispatchEvent(new CustomEvent('network-status-change', { detail: { online: true } }));
+        this.processQueue();
+      });
+      window.addEventListener('offline', () => {
+        this.dispatchEvent(new CustomEvent('network-status-change', { detail: { online: false } }));
+      });
+    }
+  }
+
+  /**
+   * Enqueues data for submission. Deduplicates by uuid.
+   * @param {string} uuid Unique identifier for the row/entity
+   * @param {object} postData Fields and values to update
+   */
+  enqueue(uuid, postData) {
+    const existingIdx = this.queue.findIndex(item => item.uuid === uuid);
+    
+    if (existingIdx !== -1) {
+      // Merge updates
+      Object.assign(this.queue[existingIdx].postData, postData);
+      this.queue[existingIdx].timestamp = Date.now();
+    } else {
+      this.queue.push({
+        uuid: uuid,
+        postData: postData,
+        timestamp: Date.now(),
+        attempts: 0
+      });
+    }
+
+    this.save();
+    this.notifyStatus();
+    this.processQueue();
+  }
+
+  /**
+   * Saves the queue to local storage
+   */
+  save() {
+    localStorage.setItem(this.storageKey, JSON.stringify(this.queue));
+  }
+
+  /**
+   * Dispatches status update events
+   */
+  notifyStatus(isOfflineError = false) {
+    const online = typeof navigator !== 'undefined' ? navigator.onLine : true;
+    this.dispatchEvent(new CustomEvent('status-change', {
+      detail: {
+        pendingCount: this.queue.length,
+        online: online && !isOfflineError,
+        queue: [...this.queue]
+      }
+    }));
+  }
+
+  /**
+   * Processes the first item in the queue recursively
+   */
+  async processQueue() {
+    if (this.isProcessing || this.queue.length === 0) return;
+    
+    const online = typeof navigator !== 'undefined' ? navigator.onLine : true;
+    if (!online) {
+      this.notifyStatus(true);
+      return;
+    }
+
+    this.isProcessing = true;
+    const item = this.queue[0];
+    
+    this.dispatchEvent(new CustomEvent('sync-start', { detail: { item } }));
+
+    try {
+      if (typeof this.onSync !== 'function') {
+        throw new Error("onSync callback is not registered or not a function.");
+      }
+
+      const result = await this.onSync(item);
+      
+      // Success! Remove from outbox
+      this.queue.shift();
+      this.save();
+
+      this.dispatchEvent(new CustomEvent('sync-success', { detail: { item, result } }));
+      
+      this.isProcessing = false;
+      this.notifyStatus();
+      
+      // Recursively process next item
+      this.processQueue();
+    } catch (err) {
+      console.warn("Outbox sync failed, will retry:", err);
+      item.attempts++;
+      this.save();
+
+      this.dispatchEvent(new CustomEvent('sync-failure', { detail: { item, error: err } }));
+      
+      this.isProcessing = false;
+      this.notifyStatus(true);
+
+      // Retry after configured delay
+      setTimeout(() => this.processQueue(), this.retryInterval);
+    }
+  }
+
+  /**
+   * Clear all pending items in the queue
+   */
+  clear() {
+    this.queue = [];
+    this.save();
+    this.notifyStatus();
+  }
+
+  /**
+   * Get all queued items
+   */
+  getQueue() {
+    return [...this.queue];
+  }
+
+  /**
+   * Callback binder helper
+   */
+  on(event, callback) {
+    this.addEventListener(event, (e) => callback(e.detail));
+  }
+}
+
+if (typeof window !== 'undefined') {
+  window.OfflineOutbox = OfflineOutbox;
+}