@incodetech/core 2.1.1 → 2.2.0-rc.0

package/dist/{geolocationManager-CF6-NizA.esm.js → geolocationManager-Bv9MSVNr.esm.js}

@@ -1,7 +1,6 @@
-import { n as eventModuleNames, s as createManagerInstrumentation } from "./events-1wxZ97yf.esm.js";
-import { l as createManager, s as createActor } from "./xstate.esm-nY3M5UYm.esm.js";
-import { t as geolocationMachine } from "./geolocationStateMachine-CD2XJs1b.esm.js";
-
+import { n as eventModuleNames, o as createManagerInstrumentation } from "./events-CxfNJVZW.esm.js";
+import { c as createManager, o as createActor } from "./xstate.esm-Cf4e0Cfd.esm.js";
+import { t as geolocationMachine } from "./geolocationStateMachine-BxD6JK1M.esm.js";
 //#region ../infra/src/providers/browser/BrowserGeolocationProvider.ts
 var BrowserGeolocationProvider = class {
 	getCurrentPosition() {
@@ -9,11 +8,10 @@ var BrowserGeolocationProvider = class {
 			navigator.geolocation.getCurrentPosition((pos) => resolve({
 				latitude: pos.coords.latitude,
 				longitude: pos.coords.longitude
-			}), reject);
+			}), (err) => reject(Object.assign(new Error(err.message), { code: err.code })));
 		});
 	}
 };
-
 //#endregion
 //#region src/modules/geolocation/geolocationActor.ts
 function createGeolocationActor(options) {
@@ -23,7 +21,6 @@ function createGeolocationActor(options) {
 		geolocation
 	} }).start();
 }
-
 //#endregion
 //#region src/modules/geolocation/geolocationManager.ts
 /**
@@ -35,11 +32,17 @@ function createGeolocationActor(options) {
 * Source of truth: Geolocation Figma file → Tracked Events canvas
 * (`https://www.figma.com/design/xg1t3GnUS95A4bLrM3lyOG/Geolocation---Latest-Design?node-id=2652-17008`).
 *
-* Deferred Figma screens that have no state-machine counterpart yet:
-* `Geolocation.error.locationUnavailable` and `Geolocation.error.noNetwork`.
-* Both kinds of failure currently collapse into `permissionDenied`
-* (`requestPosition` `onError`) or `locationAcquired` with `location: null`
-* (`submitPosition` `onError`), so the machine cannot distinguish them today.
+* Failure mapping: a device-level failure (`requestPosition` `onError`) splits
+* by `GeolocationPositionError.code` — a real permission denial (code 1) routes
+* to `permissionDenied` (device-specific "enable location" instructions), while
+* a transient failure (position unavailable / timeout, e.g. the browser's
+* `kCLErrorLocationUnknown`) routes to the attempt-limited `error` state so the
+* user can retry. A backend submit failure (`submitPosition` `onError`) splits
+* by cause: a connectivity error routes to `noNetwork`
+* (`Geolocation.error.noNetwork`), while a server-side rejection routes to the
+* same attempt-limited `error` state (`Geolocation.error`). The deferred Figma
+* sub-screen `Geolocation.error.locationUnavailable` shares the `Geolocation.error`
+* screen name for now rather than emitting a distinct one.
 */
 function getGeolocationScreenName(snapshot) {
 	const { value } = snapshot;
@@ -51,6 +54,8 @@ function getGeolocationScreenName(snapshot) {
 		case "locationAcquired":
 		case "finished": return "Geolocation.continue";
 		case "permissionDenied": return "Geolocation.allowLocation";
+		case "error": return "Geolocation.error";
+		case "noNetwork": return "Geolocation.error.noNetwork";
 		default: return;
 	}
 }
@@ -69,25 +74,49 @@ function mapState(snapshot) {
 		deviceType: context.deviceType,
 		canSkip: context.config.allowUserToSkipGeolocation === true
 	};
+	if (typedSnapshot.matches("error")) return {
+		status: "error",
+		attemptsRemaining: context.attemptsRemaining,
+		canSkip: context.config.allowUserToSkipGeolocation === true
+	};
+	if (typedSnapshot.matches("noNetwork")) return { status: "noNetwork" };
 	if (typedSnapshot.matches("finished")) return { status: "finished" };
+	if (typedSnapshot.matches("closed")) return { status: "closed" };
 	return { status: "idle" };
 }
 function createApi({ actor, trackElementClicked }) {
 	return {
+		/**
+		* Initiates the browser geolocation permission request.
+		* Transitions from 'idle' to 'requestingLocation'.
+		*/
 		request() {
 			trackElementClicked?.("request");
 			actor.send({ type: "REQUEST" });
 		},
+		/**
+		* Confirms the acquired location and completes the module.
+		* Should be called when state is 'locationAcquired'.
+		*/
 		continue() {
 			trackElementClicked?.("continue");
 			actor.send({ type: "CONTINUE" });
 		},
+		/**
+		* Skips geolocation when the user has denied permission.
+		* Only works when `config.allowUserToSkipGeolocation` is true.
+		*/
 		skip() {
 			trackElementClicked?.("skip");
 			actor.send({ type: "SKIP" });
 		},
-		reset() {
-			actor.send({ type: "RESET" });
+		retry() {
+			trackElementClicked?.("retry");
+			actor.send({ type: "RETRY" });
+		},
+		quit() {
+			trackElementClicked?.("quit");
+			actor.send({ type: "QUIT" });
 		}
 	};
 }
@@ -117,6 +146,5 @@ function createGeolocationManagerFromActor(actor) {
 		instrumentation: createManagerInstrumentation(eventModuleNames.geolocation, { getEventScreenName: getGeolocationScreenName })
 	});
 }
-
 //#endregion
-export { createGeolocationManagerFromActor as n, createGeolocationManager as t };
+export { createGeolocationManagerFromActor as n, createGeolocationManager as t };

package/dist/geolocationManager-Cz744E5S.d.ts

@@ -0,0 +1,506 @@
+import { A as StateMachine, C as StateValue, D as PromiseActorLogic, a as ActorRefFromLogic, b as RequiredActorOptions, c as AnyEventObject, g as IsNotNever, h as InputFrom, i as ActorRefFrom, k as MachineSnapshot, m as GetConcreteByKey, o as AnyActorLogic, p as EventObject, r as ActorRef, s as AnyActorRef, u as ConditionalRequired, v as MetaObject, w as Values, x as RequiredLogicInput, y as NonReducibleUnknown } from "./spawn-D9jgw9pW.js";
+import "./StateMachine-EDpYWy0i.js";
+import { t as Manager } from "./Manager-CQQ99QOI.js";
+import "./Actor-iTq7YY48.js";
+//#region ../infra/src/capabilities/IGeolocationCapability.d.ts
+type GeolocationCoords = {
+  latitude: number;
+  longitude: number;
+};
+type IGeolocationCapability = {
+  getCurrentPosition(): Promise<GeolocationCoords>;
+};
+//#endregion
+//#region src/modules/geolocation/types.d.ts
+/**
+ * Configuration options for the Geolocation module.
+ *
+ * @example
+ * ```typescript
+ * const config: GeolocationConfig = {
+ *   allowUserToSkipGeolocation: true,
+ * };
+ * ```
+ */
+type GeolocationConfig = {
+  /**
+   * Whether the user is allowed to skip geolocation capture.
+   * When true, a skip button is shown on the permission-denied screen.
+   * Backend field name from flow/workflow configuration.
+   * @default false
+   */
+  allowUserToSkipGeolocation?: boolean;
+  /**
+   * Maximum number of backend submit attempts before the error screen stops
+   * offering "Try again" and falls back to skip/quit.
+   * @default 3
+   */
+  maxAttempts?: number;
+};
+type AddGeolocationParams = {
+  latitude: number;
+  longitude: number;
+};
+//#endregion
+//#region src/modules/geolocation/geolocationStateMachine.d.ts
+type GeolocationDeviceType = 'ios' | 'android' | 'desktop';
+type GeolocationContext = {
+  config: GeolocationConfig;
+  geolocation: IGeolocationCapability;
+  coords: AddGeolocationParams | undefined;
+  location: string | null | undefined;
+  deviceType: GeolocationDeviceType;
+  attemptsRemaining: number;
+};
+type GeolocationInput = {
+  config: GeolocationConfig;
+  geolocation: IGeolocationCapability;
+};
+declare const geolocationMachine: StateMachine<GeolocationContext, {
+  type: "REQUEST";
+} | {
+  type: "CONTINUE";
+} | {
+  type: "SKIP";
+} | {
+  type: "RETRY";
+} | {
+  type: "QUIT";
+}, {
+  [x: string]: ActorRefFromLogic<PromiseActorLogic<AddGeolocationParams, {
+    geolocation: IGeolocationCapability;
+  }, EventObject>> | ActorRefFromLogic<PromiseActorLogic<{
+    location: string | null;
+  }, AddGeolocationParams, EventObject>> | undefined;
+}, Values<{
+  requestPosition: {
+    src: "requestPosition";
+    logic: PromiseActorLogic<AddGeolocationParams, {
+      geolocation: IGeolocationCapability;
+    }, EventObject>;
+    id: string | undefined;
+  };
+  submitPosition: {
+    src: "submitPosition";
+    logic: PromiseActorLogic<{
+      location: string | null;
+    }, AddGeolocationParams, EventObject>;
+    id: string | undefined;
+  };
+}>, Values<{
+  setCoords: {
+    type: "setCoords";
+    params: NonReducibleUnknown;
+  };
+  setLocation: {
+    type: "setLocation";
+    params: NonReducibleUnknown;
+  };
+  setDeviceType: {
+    type: "setDeviceType";
+    params: NonReducibleUnknown;
+  };
+  decrementAttemptsRemaining: {
+    type: "decrementAttemptsRemaining";
+    params: NonReducibleUnknown;
+  };
+}>, Values<{
+  canSkip: {
+    type: "canSkip";
+    params: unknown;
+  };
+  hasAttemptsRemaining: {
+    type: "hasAttemptsRemaining";
+    params: unknown;
+  };
+  isNetworkError: {
+    type: "isNetworkError";
+    params: unknown;
+  };
+  isPermissionDenied: {
+    type: "isPermissionDenied";
+    params: unknown;
+  };
+}>, never, "error" | "idle" | "closed" | "finished" | "requestingLocation" | "submitting" | "permissionDenied" | "locationAcquired" | "noNetwork", string, GeolocationInput, NonReducibleUnknown, EventObject, MetaObject, {
+  readonly id: "geolocation";
+  readonly initial: "idle";
+  readonly context: ({ input }: {
+    spawn: {
+      <TSrc extends "requestPosition" | "submitPosition">(logic: TSrc, ...[options]: ({
+        src: "requestPosition";
+        logic: PromiseActorLogic<AddGeolocationParams, {
+          geolocation: IGeolocationCapability;
+        }, EventObject>;
+        id: string | undefined;
+      } extends (infer T) ? T extends {
+        src: "requestPosition";
+        logic: PromiseActorLogic<AddGeolocationParams, {
+          geolocation: IGeolocationCapability;
+        }, EventObject>;
+        id: string | undefined;
+      } ? T extends {
+        src: TSrc;
+      } ? ConditionalRequired<[options?: ({
+        id?: T["id"] | undefined;
+        systemId?: string;
+        input?: InputFrom<T["logic"]> | undefined;
+        syncSnapshot?: boolean;
+      } & { [K in RequiredActorOptions<T>]: unknown; }) | undefined], IsNotNever<RequiredActorOptions<T>>> : never : never : never) | ({
+        src: "submitPosition";
+        logic: PromiseActorLogic<{
+          location: string | null;
+        }, AddGeolocationParams, EventObject>;
+        id: string | undefined;
+      } extends (infer T_1) ? T_1 extends {
+        src: "submitPosition";
+        logic: PromiseActorLogic<{
+          location: string | null;
+        }, AddGeolocationParams, EventObject>;
+        id: string | undefined;
+      } ? T_1 extends {
+        src: TSrc;
+      } ? ConditionalRequired<[options?: ({
+        id?: T_1["id"] | undefined;
+        systemId?: string;
+        input?: InputFrom<T_1["logic"]> | undefined;
+        syncSnapshot?: boolean;
+      } & { [K_1 in RequiredActorOptions<T_1>]: unknown; }) | undefined], IsNotNever<RequiredActorOptions<T_1>>> : never : never : never)): ActorRefFromLogic<GetConcreteByKey<Values<{
+        requestPosition: {
+          src: "requestPosition";
+          logic: PromiseActorLogic<AddGeolocationParams, {
+            geolocation: IGeolocationCapability;
+          }, EventObject>;
+          id: string | undefined;
+        };
+        submitPosition: {
+          src: "submitPosition";
+          logic: PromiseActorLogic<{
+            location: string | null;
+          }, AddGeolocationParams, EventObject>;
+          id: string | undefined;
+        };
+      }>, "src", TSrc>["logic"]>;
+      <TLogic extends AnyActorLogic>(src: TLogic, ...[options]: ConditionalRequired<[options?: ({
+        id?: never;
+        systemId?: string;
+        input?: InputFrom<TLogic> | undefined;
+        syncSnapshot?: boolean;
+      } & { [K in RequiredLogicInput<TLogic>]: unknown; }) | undefined], IsNotNever<RequiredLogicInput<TLogic>>>): ActorRefFromLogic<TLogic>;
+    };
+    input: GeolocationInput;
+    self: ActorRef<MachineSnapshot<GeolocationContext, {
+      type: "REQUEST";
+    } | {
+      type: "CONTINUE";
+    } | {
+      type: "SKIP";
+    } | {
+      type: "RETRY";
+    } | {
+      type: "QUIT";
+    }, Record<string, AnyActorRef | undefined>, StateValue, string, unknown, any, any>, {
+      type: "REQUEST";
+    } | {
+      type: "CONTINUE";
+    } | {
+      type: "SKIP";
+    } | {
+      type: "RETRY";
+    } | {
+      type: "QUIT";
+    }, AnyEventObject>;
+  }) => {
+    config: GeolocationConfig;
+    geolocation: IGeolocationCapability;
+    coords: undefined;
+    location: undefined;
+    deviceType: GeolocationDeviceType;
+    attemptsRemaining: number;
+  };
+  readonly states: {
+    readonly idle: {
+      readonly on: {
+        readonly REQUEST: {
+          readonly target: "requestingLocation";
+        };
+      };
+    };
+    readonly requestingLocation: {
+      readonly invoke: {
+        readonly id: "requestPosition";
+        readonly src: "requestPosition";
+        readonly input: ({ context }: {
+          context: GeolocationContext;
+          event: {
+            type: "REQUEST";
+          } | {
+            type: "CONTINUE";
+          } | {
+            type: "SKIP";
+          } | {
+            type: "RETRY";
+          } | {
+            type: "QUIT";
+          };
+          self: ActorRef<MachineSnapshot<GeolocationContext, {
+            type: "REQUEST";
+          } | {
+            type: "CONTINUE";
+          } | {
+            type: "SKIP";
+          } | {
+            type: "RETRY";
+          } | {
+            type: "QUIT";
+          }, Record<string, AnyActorRef>, StateValue, string, unknown, any, any>, {
+            type: "REQUEST";
+          } | {
+            type: "CONTINUE";
+          } | {
+            type: "SKIP";
+          } | {
+            type: "RETRY";
+          } | {
+            type: "QUIT";
+          }, AnyEventObject>;
+        }) => {
+          geolocation: IGeolocationCapability;
+        };
+        readonly onDone: {
+          readonly target: "submitting";
+          readonly actions: "setCoords";
+        };
+        readonly onError: readonly [{
+          readonly target: "permissionDenied";
+          readonly guard: "isPermissionDenied";
+          readonly actions: "setDeviceType";
+        }, {
+          readonly target: "error";
+          readonly actions: "decrementAttemptsRemaining";
+        }];
+      };
+    };
+    readonly submitting: {
+      readonly invoke: {
+        readonly id: "submitPosition";
+        readonly src: "submitPosition";
+        readonly input: ({ context }: {
+          context: GeolocationContext;
+          event: {
+            type: "REQUEST";
+          } | {
+            type: "CONTINUE";
+          } | {
+            type: "SKIP";
+          } | {
+            type: "RETRY";
+          } | {
+            type: "QUIT";
+          };
+          self: ActorRef<MachineSnapshot<GeolocationContext, {
+            type: "REQUEST";
+          } | {
+            type: "CONTINUE";
+          } | {
+            type: "SKIP";
+          } | {
+            type: "RETRY";
+          } | {
+            type: "QUIT";
+          }, Record<string, AnyActorRef>, StateValue, string, unknown, any, any>, {
+            type: "REQUEST";
+          } | {
+            type: "CONTINUE";
+          } | {
+            type: "SKIP";
+          } | {
+            type: "RETRY";
+          } | {
+            type: "QUIT";
+          }, AnyEventObject>;
+        }) => {
+          latitude: number;
+          longitude: number;
+        };
+        readonly onDone: {
+          readonly target: "locationAcquired";
+          readonly actions: "setLocation";
+        };
+        readonly onError: readonly [{
+          readonly target: "noNetwork";
+          readonly guard: "isNetworkError";
+        }, {
+          readonly target: "error";
+          readonly actions: "decrementAttemptsRemaining";
+        }];
+      };
+    };
+    readonly noNetwork: {};
+    readonly error: {
+      readonly on: {
+        readonly RETRY: {
+          readonly target: "idle";
+          readonly guard: "hasAttemptsRemaining";
+        };
+        readonly SKIP: {
+          readonly target: "finished";
+          readonly guard: "canSkip";
+        };
+        readonly QUIT: {
+          readonly target: "closed";
+        };
+      };
+    };
+    readonly locationAcquired: {
+      readonly on: {
+        readonly CONTINUE: {
+          readonly target: "finished";
+        };
+      };
+    };
+    readonly permissionDenied: {
+      readonly on: {
+        readonly SKIP: {
+          readonly target: "finished";
+          readonly guard: "canSkip";
+        };
+      };
+    };
+    readonly closed: {
+      readonly type: "final";
+    };
+    readonly finished: {
+      readonly type: "final";
+    };
+  };
+}>;
+type GeolocationMachine = typeof geolocationMachine;
+//#endregion
+//#region src/modules/geolocation/geolocationActor.d.ts
+type CreateGeolocationActorOptions = {
+  config: GeolocationConfig;
+  geolocation?: IGeolocationCapability;
+};
+type GeolocationActor = ActorRefFrom<GeolocationMachine>;
+//#endregion
+//#region src/modules/geolocation/geolocationManager.d.ts
+/** Geolocation manager is in initial state, waiting for `request()` to be called */
+type GeolocationIdleState = {
+  status: 'idle';
+};
+/** Browser geolocation permission prompt is active */
+type GeolocationRequestingState = {
+  status: 'requestingLocation';
+};
+/** Coordinates are being submitted to the backend */
+type GeolocationSubmittingState = {
+  status: 'submitting';
+};
+/**
+ * Location successfully acquired — call `continue()` to proceed
+ * @property location - Location name returned from backend, or null
+ */
+type GeolocationAcquiredState = {
+  status: 'locationAcquired';
+  location: string | null;
+};
+type GeolocationErrorState = {
+  status: 'error';
+  attemptsRemaining: number;
+  canSkip: boolean;
+};
+/**
+ * A backend request failed due to lost connectivity (device offline/network
+ * error) = the user refreshes once the connection returns.
+ */
+type GeolocationNoNetworkState = {
+  status: 'noNetwork';
+};
+/**
+ * User denied geolocation permission — shows device-specific instructions
+ * @property deviceType - Used by UI to render the correct instruction panel
+ * @property canSkip - Whether the skip button should be shown
+ */
+type GeolocationPermissionDeniedState = {
+  status: 'permissionDenied';
+  deviceType: GeolocationDeviceType;
+  canSkip: boolean;
+};
+/** Geolocation flow completed successfully */
+type GeolocationFinishedState = {
+  status: 'finished';
+};
+type GeolocationClosedState = {
+  status: 'closed';
+};
+/**
+ * Union of all possible geolocation manager states.
+ *
+ * @example
+ * ```typescript
+ * const state = geolocationManager.getState();
+ * if (state.status === 'locationAcquired') {
+ *   console.log(state.location);
+ * }
+ * if (state.status === 'permissionDenied') {
+ *   console.log(state.deviceType); // 'ios' | 'android' | 'desktop'
+ * }
+ * ```
+ */
+type GeolocationState = GeolocationIdleState | GeolocationRequestingState | GeolocationSubmittingState | GeolocationAcquiredState | GeolocationErrorState | GeolocationNoNetworkState | GeolocationPermissionDeniedState | GeolocationFinishedState | GeolocationClosedState;
+/**
+ * Creates a geolocation manager for headless or UI-driven usage.
+ *
+ * @example Headless usage
+ * ```typescript
+ * const manager = createGeolocationManager({ config: { allowUserToSkipGeolocation: true } });
+ * manager.subscribe((state) => console.log(state.status));
+ * manager.request();
+ * ```
+ */
+declare function createGeolocationManager(options: CreateGeolocationActorOptions): Manager<GeolocationState> & {
+  /**
+   * Initiates the browser geolocation permission request.
+   * Transitions from 'idle' to 'requestingLocation'.
+   */
+  request(): void;
+  /**
+   * Confirms the acquired location and completes the module.
+   * Should be called when state is 'locationAcquired'.
+   */
+  continue(): void;
+  /**
+   * Skips geolocation when the user has denied permission.
+   * Only works when `config.allowUserToSkipGeolocation` is true.
+   */
+  skip(): void;
+  retry(): void;
+  quit(): void;
+};
+/**
+ * Creates a geolocation manager from a pre-built actor.
+ * Use this when overriding the machine via `.provide()` for custom backends
+ * or for story-isolation testing.
+ */
+declare function createGeolocationManagerFromActor(actor: GeolocationActor): Manager<GeolocationState> & {
+  /**
+   * Initiates the browser geolocation permission request.
+   * Transitions from 'idle' to 'requestingLocation'.
+   */
+  request(): void;
+  /**
+   * Confirms the acquired location and completes the module.
+   * Should be called when state is 'locationAcquired'.
+   */
+  continue(): void;
+  /**
+   * Skips geolocation when the user has denied permission.
+   * Only works when `config.allowUserToSkipGeolocation` is true.
+   */
+  skip(): void;
+  retry(): void;
+  quit(): void;
+};
+type GeolocationManager = ReturnType<typeof createGeolocationManager>;
+//#endregion
+export { GeolocationActor as a, createGeolocationManagerFromActor as i, GeolocationState as n, geolocationMachine as o, createGeolocationManager as r, GeolocationConfig as s, GeolocationManager as t };