@sincpro/mobile 0.3.1 → 0.4.1

package/dist/infrastructure/telemetry/tracing_facade.d.ts

@@ -0,0 +1,50 @@
+import type { Attributes, Span, SpanContext } from "@opentelemetry/api";
+import { bufferStats } from "./buffer_registry";
+import { initTelemetry } from "./init_telemetry";
+import { getTracer as _getTracer } from "./tracing/tracer";
+export declare function withSpan<T>(name: string, fn: (span: Span) => T | Promise<T>, opts?: {
+    attributes?: Attributes;
+    tracerName?: string;
+}): Promise<T>;
+export interface TraceOptions {
+    name?: string;
+    attributes?: Attributes;
+    tracerName?: string;
+}
+export declare function Trace(opts?: TraceOptions): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+export declare function TraceClass(tracerName: string): <T extends new (...args: never[]) => object>(target: T) => T;
+export declare const Tracing: {
+    /** Initializes telemetry (Loki + OTel). Call once at app startup. */
+    readonly init: typeof initTelemetry;
+    /** Wraps a block of code in a span. Handles start/end/error automatically. */
+    readonly withSpan: typeof withSpan;
+    /** Returns the active SpanContext ({ traceId, spanId }) or null if no span is active. */
+    readonly activeSpan: () => SpanContext | null;
+    /** Log suffix ready to append: " trace_id=xxx span_id=xxx" or "". */
+    readonly logSuffix: () => string;
+    /**
+     * Current size and drop pressure of the offline telemetry buffers.
+     * A rising `dropped` count means the device has been offline long enough
+     * to lose data. Surface it in health checks / dashboards.
+     */
+    readonly bufferStats: typeof bufferStats;
+    /** Direct access to the OTel tracer for advanced use cases. */
+    readonly getTracer: typeof _getTracer;
+    /**
+     * Method decorator — creates a span per invocation.
+     * @example
+     * class CheckoutUseCase {
+     *   \@Tracing.Trace()
+     *   async process(order: Order) { ... }
+     * }
+     */
+    readonly Trace: typeof Trace;
+    /**
+     * Class decorator — creates a span per public method and propagates context.
+     * Span name: `"<tracerName>.<methodName>"`.
+     * @example
+     * \@Tracing.TraceClass("checkout")
+     * class CheckoutUseCase { ... }
+     */
+    readonly TraceClass: typeof TraceClass;
+};

package/dist/infrastructure/telemetry/tracing_facade.js

@@ -0,0 +1,139 @@
+import { ROOT_CONTEXT as OTEL_ROOT, SpanStatusCode, trace } from "@opentelemetry/api";
+import { _getContextManager, PropagateContext, } from "../../infrastructure/context_manager/index";
+import { interceptClass } from "../../infrastructure/interceptor/intercept";
+import { bufferStats } from "./buffer_registry";
+import { OTEL_CTX_KEY } from "./context_keys";
+import { initTelemetry } from "./init_telemetry";
+import { activeTraceLabel, getActiveSpanContext } from "./tracing/active_span";
+import { getTracer as _getTracer } from "./tracing/tracer";
+import { tracingHooks } from "./tracing/tracing_hooks";
+// ---------------------------------------------------------------------------
+// withSpan — manual span block with automatic lifecycle
+// ---------------------------------------------------------------------------
+export async function withSpan(name, fn, opts) {
+    const manager = _getContextManager();
+    const frameworkCtx = manager.active();
+    const otelCtx = frameworkCtx.get(OTEL_CTX_KEY) ?? OTEL_ROOT;
+    const tracer = trace.getTracer(opts?.tracerName ?? "sincpro.mobile");
+    const span = tracer.startSpan(name, { attributes: opts?.attributes }, otelCtx);
+    const newOtelCtx = trace.setSpan(otelCtx, span);
+    manager.push(frameworkCtx.set(OTEL_CTX_KEY, newOtelCtx));
+    try {
+        const result = await Promise.resolve(fn(span));
+        span.setStatus({ code: SpanStatusCode.OK });
+        return result;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            span.recordException(error);
+        span.setStatus({ code: SpanStatusCode.ERROR, message: error?.message });
+        throw error;
+    }
+    finally {
+        span.end();
+        manager.pop();
+    }
+}
+export function Trace(opts) {
+    return function (target, propertyKey, descriptor) {
+        const original = descriptor.value;
+        const className = target.constructor.name ?? "";
+        descriptor.value = function (...args) {
+            const spanName = opts?.name ?? (className ? `${className}.${propertyKey}` : propertyKey);
+            const manager = _getContextManager();
+            const frameworkCtx = manager.active();
+            const otelCtx = frameworkCtx.get(OTEL_CTX_KEY) ?? OTEL_ROOT;
+            const tracer = trace.getTracer(opts?.tracerName ?? "sincpro.mobile");
+            const span = tracer.startSpan(spanName, { attributes: opts?.attributes }, otelCtx);
+            manager.push(frameworkCtx.set(OTEL_CTX_KEY, trace.setSpan(otelCtx, span)));
+            let result;
+            try {
+                result = original.apply(this, args);
+            }
+            catch (error) {
+                // Sync method threw before returning — record and clean up immediately.
+                if (error instanceof Error)
+                    span.recordException(error);
+                span.setStatus({ code: SpanStatusCode.ERROR, message: error?.message });
+                span.end();
+                manager.pop();
+                throw error;
+            }
+            if (result instanceof Promise) {
+                return result.then((value) => {
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    span.end();
+                    manager.pop();
+                    return value;
+                }, (error) => {
+                    if (error instanceof Error)
+                        span.recordException(error);
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: error?.message,
+                    });
+                    span.end();
+                    manager.pop();
+                    throw error;
+                });
+            }
+            // Sync success path.
+            span.setStatus({ code: SpanStatusCode.OK });
+            span.end();
+            manager.pop();
+            return result;
+        };
+        return descriptor;
+    };
+}
+// ---------------------------------------------------------------------------
+// @TraceClass — class decorator: PropagateContext + span per method
+// ---------------------------------------------------------------------------
+export function TraceClass(tracerName) {
+    return function (target) {
+        const traced = interceptClass(target, tracingHooks(tracerName));
+        return PropagateContext(traced);
+    };
+}
+// ---------------------------------------------------------------------------
+// Public facade
+// ---------------------------------------------------------------------------
+export const Tracing = {
+    /** Initializes telemetry (Loki + OTel). Call once at app startup. */
+    init: initTelemetry,
+    /** Wraps a block of code in a span. Handles start/end/error automatically. */
+    withSpan,
+    /** Returns the active SpanContext ({ traceId, spanId }) or null if no span is active. */
+    activeSpan() {
+        return getActiveSpanContext();
+    },
+    /** Log suffix ready to append: " trace_id=xxx span_id=xxx" or "". */
+    logSuffix() {
+        return activeTraceLabel();
+    },
+    /**
+     * Current size and drop pressure of the offline telemetry buffers.
+     * A rising `dropped` count means the device has been offline long enough
+     * to lose data. Surface it in health checks / dashboards.
+     */
+    bufferStats,
+    /** Direct access to the OTel tracer for advanced use cases. */
+    getTracer: _getTracer,
+    /**
+     * Method decorator — creates a span per invocation.
+     * @example
+     * class CheckoutUseCase {
+     *   \@Tracing.Trace()
+     *   async process(order: Order) { ... }
+     * }
+     */
+    Trace,
+    /**
+     * Class decorator — creates a span per public method and propagates context.
+     * Span name: `"<tracerName>.<methodName>"`.
+     * @example
+     * \@Tracing.TraceClass("checkout")
+     * class CheckoutUseCase { ... }
+     */
+    TraceClass,
+};

package/dist/infrastructure/telemetry/types.d.ts

@@ -0,0 +1,120 @@
+export type LokiAuth = {
+    type: "basic";
+    username: string;
+    password: string;
+} | {
+    type: "bearer";
+    token: string;
+};
+export interface LokiConfig {
+    /** Base URL of the Loki instance, e.g. "https://loki.myserver.com" */
+    endpoint: string;
+    /** Labels attached to every log stream (app, env, tenant, …) */
+    labels: Record<string, string>;
+    /**
+     * Standard auth shortcut (Basic / Bearer). For anything else use `headers`.
+     * Omit both for unauthenticated (internal/self-hosted) setups.
+     */
+    auth?: LokiAuth;
+    /**
+     * Arbitrary headers added to every Loki request — for gateways/proxies that
+     * authenticate with custom keys (e.g. `{ "api-key": "…" }`,
+     * `{ "sincpro-api-key": "…" }`, `{ "X-Scope-OrgID": "tenant-1" }`).
+     * Merged after `auth`, so an explicit `Authorization` here overrides `auth`.
+     */
+    headers?: Record<string, string>;
+}
+export interface OtlpConfig {
+    /** OTLP/HTTP collector base URL, e.g. "https://alloy.myserver.com" */
+    endpoint: string;
+    /** Optional headers (Authorization, X-Scope-OrgID, …) */
+    headers?: Record<string, string>;
+}
+export interface FlushConfig {
+    /**
+     * Background safety-net interval in minutes (≥15 → real OS background task).
+     * Set to 0 to disable the cron entirely and rely only on the production
+     * signal (and connectivity events, if enabled). Default 15.
+     */
+    backgroundIntervalMin?: number;
+    /**
+     * Subscribe to the app's InternetIsUp/Down events to drain the backlog the
+     * moment connectivity returns. Off by default — the framework does not
+     * require the app's connectivity cron. Default false.
+     */
+    onConnectivityEvents?: boolean;
+    /** HTTP send timeout in ms (fail fast instead of hanging). Default 4000. */
+    sendTimeoutMs?: number;
+    /** Coalescing window in ms for production-triggered flushes. Default 3000. */
+    debounceMs?: number;
+}
+export interface TelemetryConfig {
+    /**
+     * Name of this app/service as it appears in Grafana/Tempo/Jaeger.
+     * Becomes the OTel resource `service.name` attribute on every span.
+     * Without it, spans are grouped under `unknown_service`, making multi-app
+     * setups impossible to filter. Example: `"pos-mobile"`, `"warehouse-mobile"`.
+     */
+    serviceName?: string;
+    /**
+     * Semver of the deployed app. Becomes `service.version` on every span.
+     * Enables filtering by version in Grafana Tempo and alerting on regressions.
+     * Example: `"1.4.2"`.
+     */
+    serviceVersion?: string;
+    /**
+     * Deployment tier. Becomes `deployment.environment` on every span.
+     * Separates dev/staging/production traces in Grafana without label tricks.
+     * Example: `"production"`, `"staging"`, `"development"`.
+     */
+    deploymentEnvironment?: string;
+    /**
+     * Extra OTel resource attributes merged onto every span. Use for device,
+     * OS, tenant, or any dimension not covered above.
+     * Common keys (OTel semantic conventions):
+     *   `"device.model.name"` — e.g. "iPhone 16 Pro"
+     *   `"os.type"` — `Platform.OS` ("ios" | "android")
+     *   `"os.version"` — `String(Platform.Version)`
+     *   `"device.id"` — opaque installation ID
+     * Values must be strings (OTel resource attributes are always string here).
+     */
+    resourceAttributes?: Record<string, string>;
+    /** Omit to disable log shipping (e.g. traces-only setup). */
+    loki?: LokiConfig;
+    /** Omit to disable span flushing (e.g. logs-only setup). */
+    otlp?: OtlpConfig;
+    /** Delivery tuning — triggers, timeout, debounce. Sensible defaults if omitted. */
+    flush?: FlushConfig;
+}
+/**
+ * Snapshot of a bounded telemetry buffer.
+ *
+ * Telemetry is best-effort and bounded: when a device stays offline, the
+ * buffer fills and the oldest data is evicted. These numbers make that loss
+ * observable instead of silent. Business-critical data must NOT live here.
+ */
+export interface BufferStats {
+    /** Rows currently buffered. */
+    rows: number;
+    /** Lower-bound estimate of buffered payload text in bytes (sum of field lengths). */
+    approxBytes: number;
+    /**
+     * Rows EVICTED after being buffered, since process start. This is the buffer
+     * back-pressure indicator — a rising value means data was buffered then lost
+     * because the device stayed offline past the cap.
+     */
+    dropped: number;
+    /**
+     * Items refused at INGEST by head sampling (never buffered), since process
+     * start. Distinct from `dropped`: a healthy sampler shedding load under
+     * pressure raises this without signalling buffer distress. 0 for log buffers
+     * (logs are not head-sampled).
+     */
+    sampled: number;
+}
+export interface TelemetryBufferStats {
+    /** Log queue stats, or null when log shipping is disabled. */
+    logs: BufferStats | null;
+    /** Span queue stats, or null when tracing is disabled. */
+    spans: BufferStats | null;
+}

package/dist/infrastructure/telemetry/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ui/components/molecules/TimeZoneSelectorModal.js

@@ -4,7 +4,7 @@ import { Display } from "@sincpro/mobile-ui/Display";
 import { Form } from "@sincpro/mobile-ui/Form";
 import { useTheme } from "@sincpro/mobile-ui/theme";
 import { Typography } from "@sincpro/mobile-ui/Typography";
-import { useMemo, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { TextInput, TouchableOpacity, View } from "react-native";
 const TIMEZONES_LOCALES = {
     bolivia: { timezone: "America/La_Paz", locale: "es-BO" },
@@ -27,6 +27,12 @@ function TimeZoneSelectorModal({ visible, onClose, onSelect, currentTimezone, })
     const theme = useTheme();
     const [query, setQuery] = useState("");
     const [selectedTimezone, setSelectedTimezone] = useState(currentTimezone || null);
+    useEffect(() => {
+        if (visible) {
+            setQuery("");
+            setSelectedTimezone(currentTimezone || null);
+        }
+    }, [visible]);
     const timezoneList = useMemo(() => {
         return Object.values(TIMEZONES_LOCALES).map((tz) => ({
             ...tz,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sincpro/mobile",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Sincpro Mobile framework core: offline-first infra (DB, queue/events, cron), DDD patterns, adapters, AppShell and module-driven composition for React Native",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -27,6 +27,9 @@
   "author": "Gutierrez, Andres <andres.gutierrez@sincpro.com.bo>",
   "license": "MIT",
   "dependencies": {
+    "@opentelemetry/core": "^2.8.0",
+    "@opentelemetry/resources": "^2.8.0",
+    "@opentelemetry/sdk-trace-base": "^2.8.0",
     "async-mutex": "^0.5.0",
     "big.js": "^7.0.1",
     "dayjs": "^1.11.18",
@@ -36,6 +39,10 @@
     "uuid": "^13.0.0"
   },
   "peerDependencies": {
+    "@opentelemetry/api": ">=1.3.0 <1.10.0",
+    "@react-navigation/native": ">=7",
+    "@react-navigation/native-stack": ">=7",
+    "@sincpro/mobile-ui": "^0.7.2",
     "expo-background-task": "*",
     "expo-clipboard": "*",
     "expo-crypto": "*",
@@ -55,15 +62,16 @@
     "react-native-gesture-handler": "*",
     "react-native-keyboard-controller": "*",
     "react-native-safe-area-context": "*",
+    "react-native-screens": "*",
     "react-native-toast-message": "*",
     "react-native-view-shot": "*",
-    "react-native-webview": "*",
-    "@react-navigation/native": ">=7",
-    "@react-navigation/native-stack": ">=7",
-    "react-native-screens": "*",
-    "@sincpro/mobile-ui": "^0.7.1"
+    "react-native-webview": "*"
   },
   "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@react-navigation/native": "^7.0.0",
+    "@react-navigation/native-stack": "^7.0.0",
+    "@sincpro/mobile-ui": "^0.7.2",
     "@types/big.js": "^6.2.2",
     "@types/react": "~19.1.10",
     "@types/uuid": "^10.0.0",
@@ -94,16 +102,14 @@
     "react-native-keyboard-controller": "1.18.5",
     "react-native-reanimated": "~4.1.1",
     "react-native-safe-area-context": "~5.6.0",
+    "react-native-screens": "~4.25.2",
     "react-native-svg": "15.12.1",
     "react-native-toast-message": "^2.3.3",
     "react-native-view-shot": "^4.0.3",
     "react-native-webview": "13.15.0",
-    "@react-navigation/native": "^7.0.0",
-    "@react-navigation/native-stack": "^7.0.0",
-    "react-native-screens": "~4.25.2",
     "tsc-alias": "^1.8.17",
-    "typescript": "~5.9.2",
-    "@sincpro/mobile-ui": "^0.7.1"
+    "tsx": "^4.22.4",
+    "typescript": "~5.9.2"
   },
   "exports": {
     ".": "./dist/index.js",