@sincpro/mobile 0.4.3 → 1.0.0

package/dist/infrastructure/database/connector.d.ts

@@ -3,6 +3,8 @@ export declare const DB_NAME = "distribution.db";
 export declare function getDatabase(): Promise<SQLiteDatabase>;
 export declare function getDatabaseSync(): SQLiteDatabase;
 export declare const DBCursor: {
+    inTransaction(): boolean;
+    transaction<T>(work: () => Promise<T>): Promise<T>;
     mutateDatabase(query: string, ...params: SQLiteVariadicBindParams): Promise<SQLiteRunResult>;
     getFirstAsync<T>(query: string, ...params: SQLiteVariadicBindParams): Promise<T | null>;
     getAllAsync<T>(query: string, ...params: SQLiteVariadicBindParams): Promise<T[]>;

package/dist/infrastructure/database/connector.js

@@ -3,6 +3,7 @@ import { Mutex } from "async-mutex";
 import { openDatabaseAsync, openDatabaseSync, } from "expo-sqlite";
 export const DB_NAME = "distribution.db";
 let dbInstance = null;
+let currentTx = null;
 const dbLock = new Mutex();
 // Telemetry/queue tables are excluded from query logging: logging their
 // mutations would feed the log pipeline its own writes — and a failing
@@ -45,12 +46,33 @@ export function getDatabaseSync() {
     return dbInstance;
 }
 async function withDB(fn) {
+    if (currentTx)
+        return fn(currentTx);
     return dbLock.runExclusive(async () => fn(await getDatabase()));
 }
 function withDBSync(fn) {
     return fn(getDatabaseSync());
 }
 export const DBCursor = {
+    inTransaction() {
+        return currentTx !== null;
+    },
+    async transaction(work) {
+        return dbLock.runExclusive(async () => {
+            const db = await getDatabase();
+            let result;
+            await db.withTransactionAsync(async () => {
+                currentTx = db;
+                try {
+                    result = await work();
+                }
+                finally {
+                    currentTx = null;
+                }
+            });
+            return result;
+        });
+    },
     async mutateDatabase(query, ...params) {
         const safeQuery = `${query.trim()};`;
         return withDB(async (db) => {

package/dist/infrastructure/database/index.d.ts

@@ -1,2 +1,3 @@
 export { DB_NAME, DBCursor } from "./connector";
 export { mapped, resolveEntity } from "./mapped";
+export { addColumnIfMissing, addColumnIfMissingSync } from "./schema";

package/dist/infrastructure/database/index.js

@@ -1,2 +1,3 @@
 export { DB_NAME, DBCursor } from "./connector";
 export { mapped, resolveEntity } from "./mapped";
+export { addColumnIfMissing, addColumnIfMissingSync } from "./schema";

package/dist/infrastructure/database/schema.d.ts

@@ -0,0 +1,9 @@
+export declare function assertSqlIdentifier(name: string): void;
+export declare function addColumnStatement(table: string, column: string, definition: string): string;
+export declare function tableColumns(table: string): Promise<string[]>;
+export declare function tableColumnsSync(table: string): string[];
+export declare function addColumnIfMissing(table: string, column: string, definition: string): Promise<void>;
+export declare function addColumnIfMissingSync(table: string, column: string, definition: string): void;
+export declare function appliedMigrationNames(): Promise<Set<string>>;
+export declare function markMigrationApplied(name: string): Promise<void>;
+export declare function forgetMigrations(names: readonly string[]): Promise<void>;

package/dist/infrastructure/database/schema.js

@@ -0,0 +1,61 @@
+import { DBCursor } from "../../infrastructure/database/connector";
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const DEFINITION = /^[A-Za-z0-9_ ()'",.{}-]+$/;
+const LEDGER = "schema_migrations";
+export function assertSqlIdentifier(name) {
+    if (!IDENTIFIER.test(name))
+        throw new Error(`invalid SQL identifier: ${name}`);
+}
+export function addColumnStatement(table, column, definition) {
+    assertSqlIdentifier(table);
+    assertSqlIdentifier(column);
+    if (!DEFINITION.test(definition))
+        throw new Error(`invalid column definition: ${definition}`);
+    return `ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`;
+}
+export async function tableColumns(table) {
+    assertSqlIdentifier(table);
+    const rows = await DBCursor.getAllAsync(`PRAGMA table_info(${table})`);
+    return rows.map((row) => row.name);
+}
+export function tableColumnsSync(table) {
+    assertSqlIdentifier(table);
+    const rows = DBCursor.getAllSync(`PRAGMA table_info(${table})`);
+    return rows.map((row) => row.name);
+}
+export async function addColumnIfMissing(table, column, definition) {
+    const existing = await tableColumns(table);
+    if (existing.includes(column))
+        return;
+    await DBCursor.execAsync(addColumnStatement(table, column, definition));
+}
+export function addColumnIfMissingSync(table, column, definition) {
+    const existing = tableColumnsSync(table);
+    if (existing.includes(column))
+        return;
+    DBCursor.mutateDatabaseSync(addColumnStatement(table, column, definition));
+}
+export async function appliedMigrationNames() {
+    await ensureLedger();
+    const rows = await DBCursor.getAllAsync(`SELECT name FROM ${LEDGER}`);
+    return new Set(rows.map((row) => row.name));
+}
+export async function markMigrationApplied(name) {
+    await ensureLedger();
+    await DBCursor.mutateDatabase(`INSERT OR IGNORE INTO ${LEDGER} (name) VALUES (?)`, name);
+}
+export async function forgetMigrations(names) {
+    await ensureLedger();
+    if (names.length === 0)
+        return;
+    const marks = names.map(() => "?").join(", ");
+    await DBCursor.mutateDatabase(`DELETE FROM ${LEDGER} WHERE name IN (${marks})`, ...names);
+}
+async function ensureLedger() {
+    await DBCursor.execAsync(`
+    CREATE TABLE IF NOT EXISTS ${LEDGER} (
+      name TEXT PRIMARY KEY NOT NULL,
+      applied_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    )
+  `);
+}

package/dist/infrastructure/database/utils.d.ts

@@ -1,3 +1,5 @@
+import { isEntityId, momentOf } from "@sincpro/client-framework";
+export { isEntityId, momentOf };
 /**
  * Constructs a SQL placeholder string and corresponding values for use in a query based on the provided field and data.
  *

package/dist/infrastructure/database/utils.js

@@ -1,6 +1,7 @@
+import { isEntityId, momentOf, newEntityId } from "@sincpro/client-framework";
 import { convertToArray } from "../../tools/utils/collections";
 import * as Crypto from "expo-crypto";
-import { v7 as uuidv7 } from "uuid";
+export { isEntityId, momentOf };
 /**
  * Constructs a SQL placeholder string and corresponding values for use in a query based on the provided field and data.
  *
@@ -28,8 +29,15 @@ export function getPlaceholders(field, data) {
     }
     return [`${field} IN (${placeholders})`, values];
 }
-export function generateUUID() {
-    return uuidv7({
-        random: Crypto.getRandomBytes(16),
+function ensureRandom() {
+    if (typeof globalThis.crypto?.getRandomValues === "function")
+        return;
+    Object.defineProperty(globalThis, "crypto", {
+        value: { getRandomValues: Crypto.getRandomValues },
+        configurable: true,
     });
 }
+export function generateUUID() {
+    ensureRandom();
+    return newEntityId();
+}

package/dist/infrastructure/event_chain.d.ts

@@ -0,0 +1,6 @@
+import { type Chain } from "../domain/events/chain";
+export declare const EVENT_CHAIN_KEY: import("./context_manager/context_key").ContextKey<Chain>;
+export declare function openChain(active: Chain | undefined): Chain;
+export declare function currentChain(): Chain | undefined;
+export declare function runWithChain<T>(chain: Chain, fn: () => T): T;
+export declare function traceparent(): string | null;

package/dist/infrastructure/event_chain.js

@@ -0,0 +1,25 @@
+import { generateUUID } from "../infrastructure/database/utils";
+import { getActiveSpanContext } from "../infrastructure/telemetry/tracing/active_span";
+import { createContextKey } from "./context_manager/context_key";
+import { getActiveContext, getContext, runWithContext } from "./context_manager/index";
+export const EVENT_CHAIN_KEY = createContextKey("sincpro.event.chain");
+export function openChain(active) {
+    const executionId = generateUUID();
+    if (!active) {
+        return { causationId: executionId, correlationId: executionId };
+    }
+    return { causationId: executionId, correlationId: active.correlationId };
+}
+export function currentChain() {
+    return getContext(EVENT_CHAIN_KEY);
+}
+export function runWithChain(chain, fn) {
+    return runWithContext(getActiveContext().set(EVENT_CHAIN_KEY, chain), fn);
+}
+export function traceparent() {
+    const span = getActiveSpanContext();
+    if (!span)
+        return null;
+    const flags = span.traceFlags.toString(16).padStart(2, "0");
+    return `00-${span.traceId}-${span.spanId}-${flags}`;
+}

package/dist/infrastructure/interceptor/intercept.d.ts

@@ -41,6 +41,10 @@ export declare function interceptClass<T extends new (...args: never[]) => objec
  * function's `.name` (or `"anonymous"` if unnamed).
  */
 export declare function interceptFunction<T extends (...args: never[]) => unknown>(fn: T, hooks: InterceptorHooks): T;
+export type InstanceInterceptOptions = {
+    /** Method names for which the proxy returns the raw function. */
+    skip?: (methodName: string) => boolean;
+};
 /**
  * Wraps a single live instance via Proxy without touching the class prototype.
  * Use for singletons exported directly (e.g. `dbCursor`, `distributionWorkflows`).
@@ -52,6 +56,7 @@ export declare function interceptFunction<T extends (...args: never[]) => unknow
  *
  * Hooks contract: `before` fires before the call; `after` fires on success with
  * the resolved value; `onError` fires on throw or rejection — the error is always
- * re-thrown after `onError` completes.
+ * re-thrown after `onError` completes. `skip` leaves a method unwrapped — a `_`
+ * helper must not open a span.
  */
-export declare function interceptInstance<T extends object>(instance: T, hooks: InterceptorHooks): T;
+export declare function interceptInstance<T extends object>(instance: T, hooks: InterceptorHooks, options?: InstanceInterceptOptions): T;

package/dist/infrastructure/interceptor/intercept.js

@@ -96,9 +96,10 @@ export function interceptFunction(fn, hooks) {
  *
  * Hooks contract: `before` fires before the call; `after` fires on success with
  * the resolved value; `onError` fires on throw or rejection — the error is always
- * re-thrown after `onError` completes.
+ * re-thrown after `onError` completes. `skip` leaves a method unwrapped — a `_`
+ * helper must not open a span.
  */
-export function interceptInstance(instance, hooks) {
+export function interceptInstance(instance, hooks, options) {
     const className = instance.constructor?.name ?? "Object";
     return new Proxy(instance, {
         get(target, prop, receiver) {
@@ -106,6 +107,8 @@ export function interceptInstance(instance, hooks) {
             if (typeof value !== "function" || typeof prop === "symbol") {
                 return value;
             }
+            if (options?.skip?.(prop))
+                return value;
             return wrap(value, className, prop, hooks).bind(target);
         },
     });

package/dist/infrastructure/telemetry/tracing/tracing_hooks.d.ts

@@ -1,10 +1,13 @@
-import type { InterceptorHooks } from "../../interceptor/intercept";
+import type { InterceptorHooks } from "../../../infrastructure/interceptor/intercept";
 /**
- * Returns InterceptorHooks that record an OTel span for every intercepted
- * method call. Parent-child relationships are maintained through the framework
- * StackContextManager: the OTel context (with the active span) is stored as a
- * value inside our Context, pushed in `before` and popped in `after`/`onError`.
+ * A span per intercepted call. The active span lives in the framework context,
+ * so a nested call — an application service running a feature — is a child of
+ * the same trace.
  *
- * @param tracerName - instrumentation scope name, e.g. "sincpro.mobile.checkout"
+ * Tracing is optional. No provider, a missing SDK, or an exporter that throws:
+ * the hooks swallow it and the use case runs. `before` only records a push it
+ * actually made, so `after` never pops a context it did not push.
+ *
+ * @param tracerName - instrumentation scope, e.g. "sincpro.mobile.checkout"
  */
 export declare function tracingHooks(tracerName: string): InterceptorHooks;

package/dist/infrastructure/telemetry/tracing/tracing_hooks.js

@@ -1,59 +1,85 @@
 import { ROOT_CONTEXT as OTEL_ROOT, SpanStatusCode, trace } from "@opentelemetry/api";
-import { _getContextManager } from "../../context_manager/index";
-import { OTEL_CTX_KEY } from "../context_keys";
+import { _getContextManager } from "../../../infrastructure/context_manager";
+import { EVENT_CHAIN_KEY, openChain } from "../../../infrastructure/event_chain";
+import { OTEL_CTX_KEY } from "../../../infrastructure/telemetry/context_keys";
 const _spanMap = new WeakMap();
 // Tracks whether `before` successfully pushed a context entry for this call.
 // Guards `after`/`onError` against popping a context they never pushed.
 const _pushedMap = new WeakSet();
 /**
- * Returns InterceptorHooks that record an OTel span for every intercepted
- * method call. Parent-child relationships are maintained through the framework
- * StackContextManager: the OTel context (with the active span) is stored as a
- * value inside our Context, pushed in `before` and popped in `after`/`onError`.
+ * A span per intercepted call. The active span lives in the framework context,
+ * so a nested call — an application service running a feature — is a child of
+ * the same trace.
  *
- * @param tracerName - instrumentation scope name, e.g. "sincpro.mobile.checkout"
+ * Tracing is optional. No provider, a missing SDK, or an exporter that throws:
+ * the hooks swallow it and the use case runs. `before` only records a push it
+ * actually made, so `after` never pops a context it did not push.
+ *
+ * @param tracerName - instrumentation scope, e.g. "sincpro.mobile.checkout"
  */
 export function tracingHooks(tracerName) {
     return {
         before(call) {
             const manager = _getContextManager();
-            const frameworkCtx = manager.active();
-            // Read the OTel context carried inside our framework context.
-            // Falls back to OTel ROOT if tracing has not been initialized yet.
-            const otelCtx = frameworkCtx.get(OTEL_CTX_KEY) ?? OTEL_ROOT;
-            const spanName = call.className
-                ? `${call.className}.${call.methodName}`
-                : call.methodName;
-            const span = trace.getTracer(tracerName).startSpan(spanName, undefined, otelCtx);
-            _spanMap.set(call, span);
-            // Store the updated OTel context (now containing this span) back into
-            // the framework context and push it onto the stack so nested calls see
-            // this span as their parent.
-            const newOtelCtx = trace.setSpan(otelCtx, span);
-            manager.push(frameworkCtx.set(OTEL_CTX_KEY, newOtelCtx));
+            let ctx = manager.active();
+            ctx = ctx.set(EVENT_CHAIN_KEY, openChain(ctx.get(EVENT_CHAIN_KEY)));
+            try {
+                const otelCtx = ctx.get(OTEL_CTX_KEY) ?? OTEL_ROOT;
+                const spanName = call.className
+                    ? `${call.className}.${call.methodName}`
+                    : call.methodName;
+                const span = trace.getTracer(tracerName).startSpan(spanName, undefined, otelCtx);
+                _spanMap.set(call, span);
+                ctx = ctx.set(OTEL_CTX_KEY, trace.setSpan(otelCtx, span));
+            }
+            catch {
+                _spanMap.delete(call);
+            }
+            manager.push(ctx);
             _pushedMap.add(call);
         },
         after(call) {
             const span = _spanMap.get(call);
-            if (!span)
-                return;
             _spanMap.delete(call);
-            span.setStatus({ code: SpanStatusCode.OK });
-            span.end();
-            if (_pushedMap.delete(call))
-                _getContextManager().pop();
+            try {
+                span?.setStatus({ code: SpanStatusCode.OK });
+                span?.end();
+            }
+            catch {
+                // The use case already finished. A failing exporter does not change that.
+            }
+            finally {
+                pop(call);
+            }
         },
         onError(call, error) {
             const span = _spanMap.get(call);
-            if (!span)
-                return;
             _spanMap.delete(call);
-            if (error instanceof Error)
-                span.recordException(error);
-            span.setStatus({ code: SpanStatusCode.ERROR, message: error?.message });
-            span.end();
-            if (_pushedMap.delete(call))
-                _getContextManager().pop();
+            try {
+                if (error instanceof Error)
+                    span?.recordException(error);
+                span?.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : undefined,
+                });
+                span?.end();
+            }
+            catch {
+                // Same as `after`: the business error is the one that propagates.
+            }
+            finally {
+                pop(call);
+            }
         },
     };
 }
+function pop(call) {
+    if (!_pushedMap.delete(call))
+        return;
+    try {
+        _getContextManager().pop();
+    }
+    catch {
+        // The stack was already cleared. Nothing of this call is left on it.
+    }
+}

package/dist/infrastructure/ui/UIEventBus.d.ts

@@ -3,7 +3,9 @@ declare class UIEventBusImpl {
     private emitter;
     private subscriptions;
     private handlerIdCounter;
-    on<T = unknown>(event: string, handler: Handler<T>): () => void;
+    on<T = unknown>(event: string, handler: Handler<T>, options?: {
+        debounce?: boolean;
+    }): () => void;
     off<T = unknown>(event: string, handler: Handler<T>): void;
     emit<T = unknown>(event: string, payload?: T): void;
     clear(): void;

package/dist/infrastructure/ui/UIEventBus.js

@@ -4,7 +4,14 @@ class UIEventBusImpl {
     emitter = mitt();
     subscriptions = new Map();
     handlerIdCounter = 0;
-    on(event, handler) {
+    on(event, handler, options) {
+        if (options?.debounce === false) {
+            const direct = handler;
+            this.emitter.on(event, direct);
+            return () => {
+                this.emitter.off(event, direct);
+            };
+        }
         const handlerId = `${event}_${++this.handlerIdCounter}`;
         const wrappedHandler = (payload) => {
             const sub = this.subscriptions.get(handlerId);

package/dist/infrastructure/ui/activity.d.ts

@@ -0,0 +1,37 @@
+import { type LabelText } from "../../domain/events/label";
+export declare const ACTIVITY_EVENT = "ui.activity";
+export declare const ACTIVITY_SETTING_EVENT = "ui.activity.setting";
+export type ActivityChannel = "queue" | "cron" | "device";
+export type ActivityStatus = "running" | "succeeded" | "failed" | "idle";
+export interface ActivityFact {
+    id: string;
+    channel: ActivityChannel;
+    name: string;
+    label: LabelText;
+    detail?: LabelText;
+    status: ActivityStatus;
+    ui: boolean;
+    variant?: "success" | "danger" | "info";
+}
+export interface ActivityState {
+    running: ActivityFact[];
+    failure?: ActivityFact;
+    notices: ActivityFact[];
+}
+export interface ActivitySettingChange {
+    channel: ActivityChannel;
+    enabled: boolean;
+}
+export declare const emptyActivity: ActivityState;
+export declare function declaresUi(source: object): boolean;
+export declare function publishActivity(fact: Omit<ActivityFact, "id">): ActivityFact;
+export declare function notifyDevice(input: {
+    name: string;
+    title: LabelText;
+    message: LabelText;
+    variant: "success" | "danger" | "info";
+}): void;
+export declare function loadActivityEnabled(): Promise<Record<ActivityChannel, boolean>>;
+export declare function setActivityEnabled(channel: ActivityChannel, enabled: boolean): Promise<void>;
+export declare function activityVisible(fact: ActivityFact, enabled: Record<ActivityChannel, boolean>, all?: boolean): boolean;
+export declare function applyActivity(state: ActivityState, fact: ActivityFact): ActivityState;

package/dist/infrastructure/ui/activity.js

@@ -0,0 +1,84 @@
+import { SettingsRepository } from "../../adapters/repositories/setting.repository";
+import { textOf } from "../../domain/events/label";
+import { ECommonSetting } from "../../domain/settings";
+import { UIEventBus } from "./UIEventBus";
+export const ACTIVITY_EVENT = "ui.activity";
+export const ACTIVITY_SETTING_EVENT = "ui.activity.setting";
+export const emptyActivity = { running: [], notices: [] };
+const SETTING_KEY = {
+    queue: ECommonSetting.UI_QUEUE,
+    cron: ECommonSetting.UI_CRON,
+    device: ECommonSetting.UI_DEVICE,
+};
+let sequence = 0;
+export function declaresUi(source) {
+    return source.constructor.ui === true;
+}
+export function publishActivity(fact) {
+    const full = { ...fact, id: `${fact.channel}:${fact.name}:${++sequence}` };
+    UIEventBus.emit(ACTIVITY_EVENT, full);
+    return full;
+}
+export function notifyDevice(input) {
+    publishActivity({
+        channel: "device",
+        name: input.name,
+        label: input.title,
+        detail: input.message,
+        status: input.variant === "danger" ? "failed" : "succeeded",
+        variant: input.variant,
+        ui: true,
+    });
+}
+export async function loadActivityEnabled() {
+    const enabled = {
+        queue: true,
+        cron: true,
+        device: true,
+    };
+    for (const channel of Object.keys(SETTING_KEY)) {
+        try {
+            const value = await SettingsRepository.getSettingByName(SETTING_KEY[channel]);
+            if (value === false)
+                enabled[channel] = false;
+        }
+        catch {
+            return enabled;
+        }
+    }
+    return enabled;
+}
+export async function setActivityEnabled(channel, enabled) {
+    await SettingsRepository.saveOneSetting(SETTING_KEY[channel], enabled);
+    const change = { channel, enabled };
+    UIEventBus.emit(ACTIVITY_SETTING_EVENT, change);
+}
+export function activityVisible(fact, enabled, all = false) {
+    if (all)
+        return true;
+    if (!fact.ui)
+        return false;
+    if (!enabled[fact.channel])
+        return false;
+    if (fact.channel !== "device" && textOf(fact.label).length === 0)
+        return false;
+    return true;
+}
+export function applyActivity(state, fact) {
+    if (fact.channel === "device") {
+        return { ...state, notices: [...state.notices, fact].slice(-8) };
+    }
+    const running = state.running.filter((item) => item.channel !== fact.channel || item.name !== fact.name);
+    const sameFailure = state.failure?.channel === fact.channel && state.failure.name === fact.name;
+    if (fact.status === "running") {
+        return { ...state, running: [...running, fact], failure: undefined };
+    }
+    if (fact.status === "failed") {
+        return { ...state, running, failure: fact };
+    }
+    return {
+        ...state,
+        running,
+        failure: sameFailure ? undefined : state.failure,
+    };
+}

package/dist/infrastructure/workers/CronWorker.d.ts

@@ -1,8 +1,9 @@
+import { type LabelText } from "../../domain/events/label";
 export type CronJob = () => Promise<void>;
 export interface CronWorkerOpts {
     requiresAuth?: boolean;
-    label?: string;
-    showToast?: boolean;
+    label?: LabelText;
+    ui?: boolean;
 }
 export declare class CronWorker {
     readonly taskName: string;
@@ -13,8 +14,8 @@ export declare class CronWorker {
     private isExecuting;
     private registrationError?;
     readonly requiresAuth: boolean;
-    label?: string;
-    private showToast;
+    label?: LabelText;
+    private ui;
     constructor(taskName: string, job: CronJob, intervalMin?: number, opts?: CronWorkerOpts);
     configure(opts: Partial<CronWorkerOpts>): void;
     /**
@@ -42,6 +43,7 @@ export declare class CronWorker {
     getLastError(): Error | undefined;
     private createIntervalJob;
     private runWithEvents;
+    private publish;
     /**
      * Waits for current job execution to complete (if any).
      * Timeout after 10 seconds to prevent infinite wait.