@linked.cm/capacitor 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,116 @@
1
+ import { App as NativeApp } from '@capacitor/app';
2
+ import { Capacitor } from '@capacitor/core';
3
+ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
4
+ import { effectiveMinimumVersion, useMandatoryNativeUpdate, } from './useMandatoryNativeUpdate.js';
5
+ import { isMaintenanceApplicable, } from '../utils/releaseStatus.js';
6
+ /**
7
+ * Headless release gate. Status loading never delays application rendering;
8
+ * consumers decide how to present maintenance and mandatory-update states.
9
+ */
10
+ export function useReleaseGate({ loadStatus, fallbackMinimumVersion, iosAppStoreId, androidPackageName, }) {
11
+ const capacitorPlatform = Capacitor.getPlatform();
12
+ const platform = capacitorPlatform === 'ios' || capacitorPlatform === 'android'
13
+ ? capacitorPlatform
14
+ : 'web';
15
+ const isNative = platform !== 'web';
16
+ const [releaseStatus, setReleaseStatus] = useState();
17
+ const [statusSettled, setStatusSettled] = useState(false);
18
+ // Ignore stale async status results after a newer refresh/unmount.
19
+ const loadSequence = useRef(0);
20
+ // Keep the latest loader without re-subscribing the effect every render.
21
+ const loadStatusRef = useRef(loadStatus);
22
+ loadStatusRef.current = loadStatus;
23
+ const nativeUpdate = useMandatoryNativeUpdate({
24
+ minimumVersion: releaseStatus === null || releaseStatus === void 0 ? void 0 : releaseStatus.minimumVersion,
25
+ fallbackMinimumVersion,
26
+ iosAppStoreId,
27
+ androidPackageName,
28
+ });
29
+ const refresh = useCallback(async () => {
30
+ const sequence = ++loadSequence.current;
31
+ setStatusSettled(false);
32
+ try {
33
+ const next = await loadStatusRef.current();
34
+ if (sequence === loadSequence.current)
35
+ setReleaseStatus(next);
36
+ }
37
+ catch (error) {
38
+ console.warn('Unable to load release status; using safe fallback:', error);
39
+ }
40
+ finally {
41
+ if (sequence === loadSequence.current)
42
+ setStatusSettled(true);
43
+ }
44
+ }, []);
45
+ useEffect(() => {
46
+ void refresh();
47
+ if (!isNative)
48
+ return;
49
+ let disposed = false;
50
+ let removeListener;
51
+ void NativeApp.addListener('appStateChange', ({ isActive }) => {
52
+ if (isActive)
53
+ void refresh();
54
+ })
55
+ .then((handle) => {
56
+ if (disposed)
57
+ void handle.remove();
58
+ else
59
+ removeListener = handle.remove;
60
+ })
61
+ .catch((error) => {
62
+ console.error('Unable to register the release status listener:', error);
63
+ });
64
+ return () => {
65
+ disposed = true;
66
+ loadSequence.current += 1;
67
+ if (removeListener)
68
+ void removeListener();
69
+ };
70
+ }, [isNative, refresh]);
71
+ const state = useMemo(() => {
72
+ if (releaseStatus && isMaintenanceApplicable(releaseStatus, platform)) {
73
+ return {
74
+ status: 'maintenance',
75
+ ...(releaseStatus.maintenanceMessage
76
+ ? { message: releaseStatus.maintenanceMessage }
77
+ : {}),
78
+ };
79
+ }
80
+ if (!isNative || nativeUpdate.state.status === 'not-native') {
81
+ return { status: 'supported' };
82
+ }
83
+ if (nativeUpdate.state.status === 'error') {
84
+ return {
85
+ status: 'error',
86
+ minimumVersion: nativeUpdate.state.minimumVersion,
87
+ error: nativeUpdate.state.error,
88
+ };
89
+ }
90
+ return nativeUpdate.state;
91
+ }, [isNative, nativeUpdate.state, platform, releaseStatus]);
92
+ const retryCheck = useCallback(async () => {
93
+ await refresh();
94
+ await nativeUpdate.retryCheck();
95
+ }, [nativeUpdate.retryCheck, refresh]);
96
+ const expectedMinimum = effectiveMinimumVersion(fallbackMinimumVersion, releaseStatus === null || releaseStatus === void 0 ? void 0 : releaseStatus.minimumVersion);
97
+ // Pause OTA until status has settled and the native check used the same
98
+ // effective minimum; otherwise a fast App.getInfo() can enable OTA before
99
+ // the server minimum arrives or while a previous minimum is still showing.
100
+ const otaEnabled = !isNative ||
101
+ (statusSettled &&
102
+ nativeUpdate.state.status === 'supported' &&
103
+ nativeUpdate.state.minimumVersion === expectedMinimum);
104
+ return useMemo(() => ({
105
+ state,
106
+ store: platform === 'ios'
107
+ ? 'App Store'
108
+ : platform === 'android'
109
+ ? 'Google Play'
110
+ : undefined,
111
+ otaEnabled,
112
+ requestUpdate: nativeUpdate.requestUpdate,
113
+ retryCheck,
114
+ }), [nativeUpdate.requestUpdate, otaEnabled, platform, retryCheck, state]);
115
+ }
116
+ //# sourceMappingURL=useReleaseGate.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"useReleaseGate.js","sourceRoot":"","sources":["../../../src/hooks/useReleaseGate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,IAAI,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC1E,OAAO,EACL,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,uBAAuB,GAGxB,MAAM,2BAA2B,CAAC;AAkCnC;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,EAC7B,UAAU,EACV,sBAAsB,EACtB,aAAa,EACb,kBAAkB,GACI;IACtB,MAAM,iBAAiB,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC;IAClD,MAAM,QAAQ,GACZ,iBAAiB,KAAK,KAAK,IAAI,iBAAiB,KAAK,SAAS;QAC5D,CAAC,CAAC,iBAAiB;QACnB,CAAC,CAAC,KAAK,CAAC;IACZ,MAAM,QAAQ,GAAG,QAAQ,KAAK,KAAK,CAAC;IACpC,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC,GAAG,QAAQ,EAAiB,CAAC;IACpE,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC1D,mEAAmE;IACnE,MAAM,YAAY,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAC/B,yEAAyE;IACzE,MAAM,aAAa,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IACzC,aAAa,CAAC,OAAO,GAAG,UAAU,CAAC;IACnC,MAAM,YAAY,GAAG,wBAAwB,CAAC;QAC5C,cAAc,EAAE,aAAa,aAAb,aAAa,uBAAb,aAAa,CAAE,cAAc;QAC7C,sBAAsB;QACtB,aAAa;QACb,kBAAkB;KACnB,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,IAAI,EAAE;QACrC,MAAM,QAAQ,GAAG,EAAE,YAAY,CAAC,OAAO,CAAC;QACxC,gBAAgB,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,OAAO,EAAE,CAAC;YAC3C,IAAI,QAAQ,KAAK,YAAY,CAAC,OAAO;gBAAE,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAChE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC,qDAAqD,EAAE,KAAK,CAAC,CAAC;QAC7E,CAAC;gBAAS,CAAC;YACT,IAAI,QAAQ,KAAK,YAAY,CAAC,OAAO;gBAAE,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAChE,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,SAAS,CAAC,GAAG,EAAE;QACb,KAAK,OAAO,EAAE,CAAC;QACf,IAAI,CAAC,QAAQ;YAAE,OAAO;QACtB,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,IAAI,cAAiD,CAAC;QACtD,KAAK,SAAS,CAAC,WAAW,CAAC,gBAAgB,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE;YAC5D,IAAI,QAAQ;gBAAE,KAAK,OAAO,EAAE,CAAC;QAC/B,CAAC,CAAC;aACC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;YACf,IAAI,QAAQ;gBAAE,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC;;gBAC9B,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC;QACtC,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACf,OAAO,CAAC,KAAK,CAAC,iDAAiD,EAAE,KAAK,CAAC,CAAC;QAC1E,CAAC,CAAC,CAAC;QACL,OAAO,GAAG,EAAE;YACV,QAAQ,GAAG,IAAI,CAAC;YAChB,YAAY,CAAC,OAAO,IAAI,CAAC,CAAC;YAC1B,IAAI,cAAc;gBAAE,KAAK,cAAc,EAAE,CAAC;QAC5C,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;IAExB,MAAM,KAAK,GAAG,OAAO,CAAmB,GAAG,EAAE;QAC3C,IAAI,aAAa,IAAI,uBAAuB,CAAC,aAAa,EAAE,QAAQ,CAAC,EAAE,CAAC;YACtE,OAAO;gBACL,MAAM,EAAE,aAAa;gBACrB,GAAG,CAAC,aAAa,CAAC,kBAAkB;oBAClC,CAAC,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,kBAAkB,EAAE;oBAC/C,CAAC,CAAC,EAAE,CAAC;aACR,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,QAAQ,IAAI,YAAY,CAAC,KAAK,CAAC,MAAM,KAAK,YAAY,EAAE,CAAC;YAC5D,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QACjC,CAAC;QACD,IAAI,YAAY,CAAC,KAAK,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;YAC1C,OAAO;gBACL,MAAM,EAAE,OAAO;gBACf,cAAc,EAAE,YAAY,CAAC,KAAK,CAAC,cAAc;gBACjD,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,KAAK;aAChC,CAAC;QACJ,CAAC;QACD,OAAO,YAAY,CAAC,KAAK,CAAC;IAC5B,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC;IAE5D,MAAM,UAAU,GAAG,WAAW,CAAC,KAAK,IAAI,EAAE;QACxC,MAAM,OAAO,EAAE,CAAC;QAChB,MAAM,YAAY,CAAC,UAAU,EAAE,CAAC;IAClC,CAAC,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;IAEvC,MAAM,eAAe,GAAG,uBAAuB,CAC7C,sBAAsB,EACtB,aAAa,aAAb,aAAa,uBAAb,aAAa,CAAE,cAAc,CAC9B,CAAC;IACF,wEAAwE;IACxE,0EAA0E;IAC1E,2EAA2E;IAC3E,MAAM,UAAU,GACd,CAAC,QAAQ;QACT,CAAC,aAAa;YACZ,YAAY,CAAC,KAAK,CAAC,MAAM,KAAK,WAAW;YACzC,YAAY,CAAC,KAAK,CAAC,cAAc,KAAK,eAAe,CAAC,CAAC;IAE3D,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,CAAC;QACL,KAAK;QACL,KAAK,EACH,QAAQ,KAAK,KAAK;YAChB,CAAC,CAAE,WAAqB;YACxB,CAAC,CAAC,QAAQ,KAAK,SAAS;gBACtB,CAAC,CAAE,aAAuB;gBAC1B,CAAC,CAAC,SAAS;QACjB,UAAU;QACV,aAAa,EAAE,YAAY,CAAC,aAAa;QACzC,UAAU;KACX,CAAC,EACF,CAAC,YAAY,CAAC,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,CAAC,CACtE,CAAC;AACJ,CAAC","sourcesContent":["import { App as NativeApp } from '@capacitor/app';\nimport { Capacitor } from '@capacitor/core';\nimport { useCallback, useEffect, useMemo, useRef, useState } from 'react';\nimport {\n effectiveMinimumVersion,\n useMandatoryNativeUpdate,\n} from './useMandatoryNativeUpdate.js';\nimport {\n isMaintenanceApplicable,\n type ReleaseStatus,\n type RuntimePlatform,\n} from '../utils/releaseStatus.js';\n\nexport type ReleaseGateState =\n | { status: 'checking' }\n | { status: 'maintenance'; message?: string }\n | {\n status: 'supported';\n currentVersion?: string;\n }\n | {\n status: 'required';\n platform: 'ios' | 'android';\n currentVersion: string;\n minimumVersion: string;\n updating: boolean;\n error?: string;\n }\n | { status: 'error'; minimumVersion: string; error: string };\n\nexport type UseReleaseGateOptions = {\n loadStatus: () => Promise<ReleaseStatus>;\n fallbackMinimumVersion: string;\n iosAppStoreId?: string;\n androidPackageName?: string;\n};\n\nexport type ReleaseGateResult = {\n state: ReleaseGateState;\n store?: 'App Store' | 'Google Play';\n otaEnabled: boolean;\n requestUpdate: () => Promise<void>;\n retryCheck: () => Promise<void>;\n};\n\n/**\n * Headless release gate. Status loading never delays application rendering;\n * consumers decide how to present maintenance and mandatory-update states.\n */\nexport function useReleaseGate({\n loadStatus,\n fallbackMinimumVersion,\n iosAppStoreId,\n androidPackageName,\n}: UseReleaseGateOptions): ReleaseGateResult {\n const capacitorPlatform = Capacitor.getPlatform();\n const platform: RuntimePlatform =\n capacitorPlatform === 'ios' || capacitorPlatform === 'android'\n ? capacitorPlatform\n : 'web';\n const isNative = platform !== 'web';\n const [releaseStatus, setReleaseStatus] = useState<ReleaseStatus>();\n const [statusSettled, setStatusSettled] = useState(false);\n // Ignore stale async status results after a newer refresh/unmount.\n const loadSequence = useRef(0);\n // Keep the latest loader without re-subscribing the effect every render.\n const loadStatusRef = useRef(loadStatus);\n loadStatusRef.current = loadStatus;\n const nativeUpdate = useMandatoryNativeUpdate({\n minimumVersion: releaseStatus?.minimumVersion,\n fallbackMinimumVersion,\n iosAppStoreId,\n androidPackageName,\n });\n\n const refresh = useCallback(async () => {\n const sequence = ++loadSequence.current;\n setStatusSettled(false);\n try {\n const next = await loadStatusRef.current();\n if (sequence === loadSequence.current) setReleaseStatus(next);\n } catch (error) {\n console.warn('Unable to load release status; using safe fallback:', error);\n } finally {\n if (sequence === loadSequence.current) setStatusSettled(true);\n }\n }, []);\n\n useEffect(() => {\n void refresh();\n if (!isNative) return;\n let disposed = false;\n let removeListener: (() => Promise<void>) | undefined;\n void NativeApp.addListener('appStateChange', ({ isActive }) => {\n if (isActive) void refresh();\n })\n .then((handle) => {\n if (disposed) void handle.remove();\n else removeListener = handle.remove;\n })\n .catch((error) => {\n console.error('Unable to register the release status listener:', error);\n });\n return () => {\n disposed = true;\n loadSequence.current += 1;\n if (removeListener) void removeListener();\n };\n }, [isNative, refresh]);\n\n const state = useMemo<ReleaseGateState>(() => {\n if (releaseStatus && isMaintenanceApplicable(releaseStatus, platform)) {\n return {\n status: 'maintenance',\n ...(releaseStatus.maintenanceMessage\n ? { message: releaseStatus.maintenanceMessage }\n : {}),\n };\n }\n if (!isNative || nativeUpdate.state.status === 'not-native') {\n return { status: 'supported' };\n }\n if (nativeUpdate.state.status === 'error') {\n return {\n status: 'error',\n minimumVersion: nativeUpdate.state.minimumVersion,\n error: nativeUpdate.state.error,\n };\n }\n return nativeUpdate.state;\n }, [isNative, nativeUpdate.state, platform, releaseStatus]);\n\n const retryCheck = useCallback(async () => {\n await refresh();\n await nativeUpdate.retryCheck();\n }, [nativeUpdate.retryCheck, refresh]);\n\n const expectedMinimum = effectiveMinimumVersion(\n fallbackMinimumVersion,\n releaseStatus?.minimumVersion\n );\n // Pause OTA until status has settled and the native check used the same\n // effective minimum; otherwise a fast App.getInfo() can enable OTA before\n // the server minimum arrives or while a previous minimum is still showing.\n const otaEnabled =\n !isNative ||\n (statusSettled &&\n nativeUpdate.state.status === 'supported' &&\n nativeUpdate.state.minimumVersion === expectedMinimum);\n\n return useMemo(\n () => ({\n state,\n store:\n platform === 'ios'\n ? ('App Store' as const)\n : platform === 'android'\n ? ('Google Play' as const)\n : undefined,\n otaEnabled,\n requestUpdate: nativeUpdate.requestUpdate,\n retryCheck,\n }),\n [nativeUpdate.requestUpdate, otaEnabled, platform, retryCheck, state]\n );\n}\n\n"]}
@@ -11,3 +11,8 @@ import './components/SignInWithWhatsapp.js';
11
11
  import './hooks/useCapacitor.js';
12
12
  import './hooks/useAutomaticUpdates.js';
13
13
  import './hooks/useNativeAppUpdate.js';
14
+ import './hooks/useMandatoryNativeUpdate.js';
15
+ import './hooks/useReleaseGate.js';
16
+ import './utils/releaseStatus.js';
17
+ import './utils/releaseStatusCache.js';
18
+ import './utils/releaseStatusClient.js';
package/lib/esm/index.js CHANGED
@@ -13,4 +13,9 @@ import './components/SignInWithWhatsapp.js';
13
13
  import './hooks/useCapacitor.js';
14
14
  import './hooks/useAutomaticUpdates.js';
15
15
  import './hooks/useNativeAppUpdate.js';
16
+ import './hooks/useMandatoryNativeUpdate.js';
17
+ import './hooks/useReleaseGate.js';
18
+ import './utils/releaseStatus.js';
19
+ import './utils/releaseStatusCache.js';
20
+ import './utils/releaseStatusClient.js';
16
21
  //# sourceMappingURL=index.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,CAAC;AACpB,cAAc,6BAA6B,CAAC;AAC5C,OAAO,oCAAoC,CAAC;AAE5C,cAAc;AACd,OAAO,mBAAmB,CAAC;AAE3B,iBAAiB;AACjB,OAAO,iCAAiC,CAAC;AACzC,OAAO,0CAA0C,CAAC;AAClD,OAAO,uCAAuC,CAAC;AAC/C,OAAO,wCAAwC,CAAC;AAChD,OAAO,mCAAmC,CAAC;AAC3C,OAAO,oCAAoC,CAAC;AAC5C,OAAO,yBAAyB,CAAC;AACjC,OAAO,gCAAgC,CAAC;AACxC,OAAO,+BAA+B,CAAC","sourcesContent":["import './types.js';\nexport * from './auth/SocialLoginClient.js';\nimport './ontologies/capacitor.register.js';\n\n//SHAPES FIRST\nimport './shapes/index.js';\n\n//THEN COMPONENTS\nimport './components/LocationEnabler.js';\nimport './components/SigninWithFacebookButton.js';\nimport './components/SigninWithAppleButton.js';\nimport './components/SigninWithGoogleButton.js';\nimport './components/SafeAreaContainer.js';\nimport './components/SignInWithWhatsapp.js';\nimport './hooks/useCapacitor.js';\nimport './hooks/useAutomaticUpdates.js';\nimport './hooks/useNativeAppUpdate.js';\n"]}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,CAAC;AACpB,cAAc,6BAA6B,CAAC;AAC5C,OAAO,oCAAoC,CAAC;AAE5C,cAAc;AACd,OAAO,mBAAmB,CAAC;AAE3B,iBAAiB;AACjB,OAAO,iCAAiC,CAAC;AACzC,OAAO,0CAA0C,CAAC;AAClD,OAAO,uCAAuC,CAAC;AAC/C,OAAO,wCAAwC,CAAC;AAChD,OAAO,mCAAmC,CAAC;AAC3C,OAAO,oCAAoC,CAAC;AAC5C,OAAO,yBAAyB,CAAC;AACjC,OAAO,gCAAgC,CAAC;AACxC,OAAO,+BAA+B,CAAC;AACvC,OAAO,qCAAqC,CAAC;AAC7C,OAAO,2BAA2B,CAAC;AACnC,OAAO,0BAA0B,CAAC;AAClC,OAAO,+BAA+B,CAAC;AACvC,OAAO,gCAAgC,CAAC","sourcesContent":["import './types.js';\nexport * from './auth/SocialLoginClient.js';\nimport './ontologies/capacitor.register.js';\n\n//SHAPES FIRST\nimport './shapes/index.js';\n\n//THEN COMPONENTS\nimport './components/LocationEnabler.js';\nimport './components/SigninWithFacebookButton.js';\nimport './components/SigninWithAppleButton.js';\nimport './components/SigninWithGoogleButton.js';\nimport './components/SafeAreaContainer.js';\nimport './components/SignInWithWhatsapp.js';\nimport './hooks/useCapacitor.js';\nimport './hooks/useAutomaticUpdates.js';\nimport './hooks/useNativeAppUpdate.js';\nimport './hooks/useMandatoryNativeUpdate.js';\nimport './hooks/useReleaseGate.js';\nimport './utils/releaseStatus.js';\nimport './utils/releaseStatusCache.js';\nimport './utils/releaseStatusClient.js';\n"]}
@@ -0,0 +1,34 @@
1
+ export type MaintenancePlatform = 'all' | 'web' | 'ios' | 'android' | 'native';
2
+ export type RuntimePlatform = 'web' | 'ios' | 'android';
3
+ export type ReleaseStatus = {
4
+ minimumVersion: string;
5
+ maintenanceMode: boolean;
6
+ maintenancePlatform: MaintenancePlatform;
7
+ maintenanceMessage?: string;
8
+ };
9
+ export declare const MAINTENANCE_PLATFORMS: readonly MaintenancePlatform[];
10
+ export declare function isStableReleaseVersion(value: unknown): value is string;
11
+ export declare function isMaintenancePlatform(value: unknown): value is MaintenancePlatform;
12
+ export declare function assertStableReleaseVersion(value: unknown): string;
13
+ export declare function normalizeReleaseStatus(input: unknown, options?: {
14
+ defaultMinimumVersion?: string;
15
+ }): ReleaseStatus;
16
+ export declare function tryNormalizeReleaseStatus(input: unknown, options?: {
17
+ defaultMinimumVersion?: string;
18
+ }): {
19
+ ok: true;
20
+ value: ReleaseStatus;
21
+ } | {
22
+ ok: false;
23
+ error: string;
24
+ };
25
+ export declare function pickReleaseStatus(config: {
26
+ minimumVersion?: unknown;
27
+ maintenanceMode?: unknown;
28
+ maintenancePlatform?: unknown;
29
+ maintenanceMessage?: unknown;
30
+ }, options?: {
31
+ defaultMinimumVersion?: string;
32
+ }): ReleaseStatus;
33
+ export declare function toStatusResponse(status: ReleaseStatus): ReleaseStatus;
34
+ export declare function isMaintenanceApplicable(status: Pick<ReleaseStatus, 'maintenanceMode' | 'maintenancePlatform'>, platform: RuntimePlatform): boolean;
@@ -0,0 +1,81 @@
1
+ export const MAINTENANCE_PLATFORMS = [
2
+ 'all',
3
+ 'web',
4
+ 'ios',
5
+ 'android',
6
+ 'native',
7
+ ];
8
+ const STABLE_VERSION = /^\d+\.\d+\.\d+$/;
9
+ export function isStableReleaseVersion(value) {
10
+ return typeof value === 'string' && STABLE_VERSION.test(value.trim());
11
+ }
12
+ export function isMaintenancePlatform(value) {
13
+ return (typeof value === 'string' &&
14
+ MAINTENANCE_PLATFORMS.includes(value));
15
+ }
16
+ export function assertStableReleaseVersion(value) {
17
+ if (!isStableReleaseVersion(value)) {
18
+ throw new Error('minimumVersion must use stable X.Y.Z format');
19
+ }
20
+ return value.trim();
21
+ }
22
+ export function normalizeReleaseStatus(input, options = {}) {
23
+ var _a, _b;
24
+ if (!input || typeof input !== 'object' || Array.isArray(input)) {
25
+ throw new Error('Release status must be an object');
26
+ }
27
+ const raw = input;
28
+ // Only an omitted minimum may use the compiled fallback. null/invalid values
29
+ // must fail so callers can retain their last valid snapshot.
30
+ const minimumVersion = assertStableReleaseVersion(raw.minimumVersion === undefined
31
+ ? options.defaultMinimumVersion
32
+ : raw.minimumVersion);
33
+ const maintenanceMode = (_a = raw.maintenanceMode) !== null && _a !== void 0 ? _a : false;
34
+ if (typeof maintenanceMode !== 'boolean') {
35
+ throw new Error('maintenanceMode must be a boolean');
36
+ }
37
+ const maintenancePlatform = (_b = raw.maintenancePlatform) !== null && _b !== void 0 ? _b : 'all';
38
+ if (!isMaintenancePlatform(maintenancePlatform)) {
39
+ throw new Error(`maintenancePlatform must be one of: ${MAINTENANCE_PLATFORMS.join(', ')}`);
40
+ }
41
+ let maintenanceMessage;
42
+ if (raw.maintenanceMessage !== undefined) {
43
+ if (typeof raw.maintenanceMessage !== 'string') {
44
+ throw new Error('maintenanceMessage must be a string when provided');
45
+ }
46
+ maintenanceMessage = raw.maintenanceMessage.trim() || undefined;
47
+ }
48
+ return {
49
+ minimumVersion,
50
+ maintenanceMode,
51
+ maintenancePlatform,
52
+ ...(maintenanceMessage ? { maintenanceMessage } : {}),
53
+ };
54
+ }
55
+ export function tryNormalizeReleaseStatus(input, options = {}) {
56
+ try {
57
+ return { ok: true, value: normalizeReleaseStatus(input, options) };
58
+ }
59
+ catch (error) {
60
+ return {
61
+ ok: false,
62
+ error: error instanceof Error ? error.message : String(error),
63
+ };
64
+ }
65
+ }
66
+ export function pickReleaseStatus(config, options = {}) {
67
+ return normalizeReleaseStatus(config, options);
68
+ }
69
+ export function toStatusResponse(status) {
70
+ return normalizeReleaseStatus(status);
71
+ }
72
+ export function isMaintenanceApplicable(status, platform) {
73
+ if (!status.maintenanceMode)
74
+ return false;
75
+ if (status.maintenancePlatform === 'all')
76
+ return true;
77
+ if (status.maintenancePlatform === 'native')
78
+ return platform !== 'web';
79
+ return status.maintenancePlatform === platform;
80
+ }
81
+ //# sourceMappingURL=releaseStatus.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"releaseStatus.js","sourceRoot":"","sources":["../../../src/utils/releaseStatus.ts"],"names":[],"mappings":"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","sourcesContent":["export type MaintenancePlatform =\n | 'all'\n | 'web'\n | 'ios'\n | 'android'\n | 'native';\n\nexport type RuntimePlatform = 'web' | 'ios' | 'android';\n\nexport type ReleaseStatus = {\n minimumVersion: string;\n maintenanceMode: boolean;\n maintenancePlatform: MaintenancePlatform;\n maintenanceMessage?: string;\n};\n\nexport const MAINTENANCE_PLATFORMS: readonly MaintenancePlatform[] = [\n 'all',\n 'web',\n 'ios',\n 'android',\n 'native',\n] as const;\n\nconst STABLE_VERSION = /^\\d+\\.\\d+\\.\\d+$/;\n\nexport function isStableReleaseVersion(value: unknown): value is string {\n return typeof value === 'string' && STABLE_VERSION.test(value.trim());\n}\n\nexport function isMaintenancePlatform(\n value: unknown\n): value is MaintenancePlatform {\n return (\n typeof value === 'string' &&\n (MAINTENANCE_PLATFORMS as readonly string[]).includes(value)\n );\n}\n\nexport function assertStableReleaseVersion(value: unknown): string {\n if (!isStableReleaseVersion(value)) {\n throw new Error('minimumVersion must use stable X.Y.Z format');\n }\n return value.trim();\n}\n\nexport function normalizeReleaseStatus(\n input: unknown,\n options: { defaultMinimumVersion?: string } = {}\n): ReleaseStatus {\n if (!input || typeof input !== 'object' || Array.isArray(input)) {\n throw new Error('Release status must be an object');\n }\n const raw = input as Record<string, unknown>;\n // Only an omitted minimum may use the compiled fallback. null/invalid values\n // must fail so callers can retain their last valid snapshot.\n const minimumVersion = assertStableReleaseVersion(\n raw.minimumVersion === undefined\n ? options.defaultMinimumVersion\n : raw.minimumVersion\n );\n const maintenanceMode = raw.maintenanceMode ?? false;\n if (typeof maintenanceMode !== 'boolean') {\n throw new Error('maintenanceMode must be a boolean');\n }\n const maintenancePlatform = raw.maintenancePlatform ?? 'all';\n if (\n !isMaintenancePlatform(maintenancePlatform)\n ) {\n throw new Error(\n `maintenancePlatform must be one of: ${MAINTENANCE_PLATFORMS.join(', ')}`\n );\n }\n let maintenanceMessage: string | undefined;\n if (raw.maintenanceMessage !== undefined) {\n if (typeof raw.maintenanceMessage !== 'string') {\n throw new Error('maintenanceMessage must be a string when provided');\n }\n maintenanceMessage = raw.maintenanceMessage.trim() || undefined;\n }\n return {\n minimumVersion,\n maintenanceMode,\n maintenancePlatform,\n ...(maintenanceMessage ? { maintenanceMessage } : {}),\n };\n}\n\nexport function tryNormalizeReleaseStatus(\n input: unknown,\n options: { defaultMinimumVersion?: string } = {}\n): { ok: true; value: ReleaseStatus } | { ok: false; error: string } {\n try {\n return { ok: true, value: normalizeReleaseStatus(input, options) };\n } catch (error) {\n return {\n ok: false,\n error: error instanceof Error ? error.message : String(error),\n };\n }\n}\n\nexport function pickReleaseStatus(\n config: {\n minimumVersion?: unknown;\n maintenanceMode?: unknown;\n maintenancePlatform?: unknown;\n maintenanceMessage?: unknown;\n },\n options: { defaultMinimumVersion?: string } = {}\n): ReleaseStatus {\n return normalizeReleaseStatus(config, options);\n}\n\nexport function toStatusResponse(status: ReleaseStatus): ReleaseStatus {\n return normalizeReleaseStatus(status);\n}\n\nexport function isMaintenanceApplicable(\n status: Pick<ReleaseStatus, 'maintenanceMode' | 'maintenancePlatform'>,\n platform: RuntimePlatform\n): boolean {\n if (!status.maintenanceMode) return false;\n if (status.maintenancePlatform === 'all') return true;\n if (status.maintenancePlatform === 'native') return platform !== 'web';\n return status.maintenancePlatform === platform;\n}\n\n"]}
@@ -0,0 +1,31 @@
1
+ import { type ReleaseStatus } from './releaseStatus.js';
2
+ export declare const RELEASE_STATUS_REFRESH_MS = 60000;
3
+ export type ReadReleaseStatus = () => unknown;
4
+ /** Keeps serving the last valid snapshot when its injected source fails. */
5
+ export declare class ReleaseStatusCache {
6
+ private snapshot;
7
+ private timer?;
8
+ private readonly readStatus;
9
+ private readonly refreshMs;
10
+ private readonly log;
11
+ constructor(options: {
12
+ initialStatus: ReleaseStatus;
13
+ readStatus: ReadReleaseStatus;
14
+ refreshMs?: number;
15
+ log?: (message: string, error?: unknown) => void;
16
+ });
17
+ load(): ReleaseStatus;
18
+ start(): void;
19
+ stop(): void;
20
+ getStatus(): ReleaseStatus;
21
+ private refresh;
22
+ }
23
+ type StatusHttpResponse = {
24
+ setHeader(name: string, value: string): void;
25
+ status(code: number): {
26
+ json(body: ReleaseStatus): unknown;
27
+ };
28
+ };
29
+ /** Framework-light HTTP adapter; applications still own route registration. */
30
+ export declare function createReleaseStatusHandler(cache: ReleaseStatusCache): (_request: unknown, response: StatusHttpResponse) => void;
31
+ export {};
@@ -0,0 +1,48 @@
1
+ import { normalizeReleaseStatus, } from './releaseStatus.js';
2
+ export const RELEASE_STATUS_REFRESH_MS = 60000;
3
+ /** Keeps serving the last valid snapshot when its injected source fails. */
4
+ export class ReleaseStatusCache {
5
+ constructor(options) {
6
+ var _a, _b;
7
+ this.snapshot = normalizeReleaseStatus(options.initialStatus);
8
+ this.readStatus = options.readStatus;
9
+ this.refreshMs = (_a = options.refreshMs) !== null && _a !== void 0 ? _a : RELEASE_STATUS_REFRESH_MS;
10
+ this.log = (_b = options.log) !== null && _b !== void 0 ? _b : console.warn;
11
+ }
12
+ load() {
13
+ this.refresh('startup');
14
+ return this.getStatus();
15
+ }
16
+ start() {
17
+ if (this.timer)
18
+ return;
19
+ this.timer = setInterval(() => this.refresh('refresh'), this.refreshMs);
20
+ if (typeof this.timer.unref === 'function')
21
+ this.timer.unref();
22
+ }
23
+ stop() {
24
+ if (!this.timer)
25
+ return;
26
+ clearInterval(this.timer);
27
+ this.timer = undefined;
28
+ }
29
+ getStatus() {
30
+ return { ...this.snapshot };
31
+ }
32
+ refresh(reason) {
33
+ try {
34
+ this.snapshot = normalizeReleaseStatus(this.readStatus());
35
+ }
36
+ catch (error) {
37
+ this.log(`releaseStatusCache: ${reason} retained last valid snapshot`, error);
38
+ }
39
+ }
40
+ }
41
+ /** Framework-light HTTP adapter; applications still own route registration. */
42
+ export function createReleaseStatusHandler(cache) {
43
+ return (_request, response) => {
44
+ response.setHeader('Cache-Control', 'no-store');
45
+ response.status(200).json(cache.getStatus());
46
+ };
47
+ }
48
+ //# sourceMappingURL=releaseStatusCache.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"releaseStatusCache.js","sourceRoot":"","sources":["../../../src/utils/releaseStatusCache.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,GAEvB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,CAAC,MAAM,yBAAyB,GAAG,KAAM,CAAC;AAIhD,4EAA4E;AAC5E,MAAM,OAAO,kBAAkB;IAO7B,YAAY,OAKX;;QACC,IAAI,CAAC,QAAQ,GAAG,sBAAsB,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QAC9D,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,SAAS,GAAG,MAAA,OAAO,CAAC,SAAS,mCAAI,yBAAyB,CAAC;QAChE,IAAI,CAAC,GAAG,GAAG,MAAA,OAAO,CAAC,GAAG,mCAAI,OAAO,CAAC,IAAI,CAAC;IACzC,CAAC;IAED,IAAI;QACF,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACxB,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC;IAC1B,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO;QACvB,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACxE,IAAI,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,KAAK,UAAU;YAAE,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACjE,CAAC;IAED,IAAI;QACF,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO;QACxB,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;IACzB,CAAC;IAED,SAAS;QACP,OAAO,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;IAC9B,CAAC;IAEO,OAAO,CAAC,MAA6B;QAC3C,IAAI,CAAC;YACH,IAAI,CAAC,QAAQ,GAAG,sBAAsB,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QAC5D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,GAAG,CACN,uBAAuB,MAAM,+BAA+B,EAC5D,KAAK,CACN,CAAC;QACJ,CAAC;IACH,CAAC;CACF;AAOD,+EAA+E;AAC/E,MAAM,UAAU,0BAA0B,CAAC,KAAyB;IAClE,OAAO,CAAC,QAAiB,EAAE,QAA4B,EAAQ,EAAE;QAC/D,QAAQ,CAAC,SAAS,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;QAChD,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;IAC/C,CAAC,CAAC;AACJ,CAAC","sourcesContent":["import {\n normalizeReleaseStatus,\n type ReleaseStatus,\n} from './releaseStatus.js';\n\nexport const RELEASE_STATUS_REFRESH_MS = 60_000;\n\nexport type ReadReleaseStatus = () => unknown;\n\n/** Keeps serving the last valid snapshot when its injected source fails. */\nexport class ReleaseStatusCache {\n private snapshot: ReleaseStatus;\n private timer?: ReturnType<typeof setInterval>;\n private readonly readStatus: ReadReleaseStatus;\n private readonly refreshMs: number;\n private readonly log: (message: string, error?: unknown) => void;\n\n constructor(options: {\n initialStatus: ReleaseStatus;\n readStatus: ReadReleaseStatus;\n refreshMs?: number;\n log?: (message: string, error?: unknown) => void;\n }) {\n this.snapshot = normalizeReleaseStatus(options.initialStatus);\n this.readStatus = options.readStatus;\n this.refreshMs = options.refreshMs ?? RELEASE_STATUS_REFRESH_MS;\n this.log = options.log ?? console.warn;\n }\n\n load(): ReleaseStatus {\n this.refresh('startup');\n return this.getStatus();\n }\n\n start(): void {\n if (this.timer) return;\n this.timer = setInterval(() => this.refresh('refresh'), this.refreshMs);\n if (typeof this.timer.unref === 'function') this.timer.unref();\n }\n\n stop(): void {\n if (!this.timer) return;\n clearInterval(this.timer);\n this.timer = undefined;\n }\n\n getStatus(): ReleaseStatus {\n return { ...this.snapshot };\n }\n\n private refresh(reason: 'startup' | 'refresh'): void {\n try {\n this.snapshot = normalizeReleaseStatus(this.readStatus());\n } catch (error) {\n this.log(\n `releaseStatusCache: ${reason} retained last valid snapshot`,\n error\n );\n }\n }\n}\n\ntype StatusHttpResponse = {\n setHeader(name: string, value: string): void;\n status(code: number): { json(body: ReleaseStatus): unknown };\n};\n\n/** Framework-light HTTP adapter; applications still own route registration. */\nexport function createReleaseStatusHandler(cache: ReleaseStatusCache) {\n return (_request: unknown, response: StatusHttpResponse): void => {\n response.setHeader('Cache-Control', 'no-store');\n response.status(200).json(cache.getStatus());\n };\n}\n\n"]}
@@ -0,0 +1,16 @@
1
+ import { type ReleaseStatus } from './releaseStatus.js';
2
+ export type ReleaseStatusClientOptions = {
3
+ url: string | (() => string);
4
+ headers?: HeadersInit | (() => HeadersInit);
5
+ timeoutMs?: number;
6
+ fetch?: typeof fetch;
7
+ };
8
+ /** Deduplicates concurrent loads and falls back to the last valid response. */
9
+ export declare class ReleaseStatusClient {
10
+ private lastValid?;
11
+ private inFlight?;
12
+ private readonly options;
13
+ constructor(options: ReleaseStatusClientOptions);
14
+ load(): Promise<ReleaseStatus>;
15
+ private request;
16
+ }
@@ -0,0 +1,46 @@
1
+ import { normalizeReleaseStatus, } from './releaseStatus.js';
2
+ /** Deduplicates concurrent loads and falls back to the last valid response. */
3
+ export class ReleaseStatusClient {
4
+ constructor(options) {
5
+ this.options = options;
6
+ }
7
+ load() {
8
+ if (this.inFlight)
9
+ return this.inFlight;
10
+ this.inFlight = this.request().finally(() => {
11
+ this.inFlight = undefined;
12
+ });
13
+ return this.inFlight;
14
+ }
15
+ async request() {
16
+ var _a, _b;
17
+ const controller = new AbortController();
18
+ const timeout = setTimeout(() => controller.abort(), (_a = this.options.timeoutMs) !== null && _a !== void 0 ? _a : 8000);
19
+ try {
20
+ const request = (_b = this.options.fetch) !== null && _b !== void 0 ? _b : fetch;
21
+ const response = await request(typeof this.options.url === 'function'
22
+ ? this.options.url()
23
+ : this.options.url, {
24
+ cache: 'no-store',
25
+ headers: typeof this.options.headers === 'function'
26
+ ? this.options.headers()
27
+ : this.options.headers,
28
+ signal: controller.signal,
29
+ });
30
+ if (!response.ok) {
31
+ throw new Error(`Status request failed: ${response.status}`);
32
+ }
33
+ this.lastValid = normalizeReleaseStatus(await response.json());
34
+ return this.lastValid;
35
+ }
36
+ catch (error) {
37
+ if (this.lastValid)
38
+ return this.lastValid;
39
+ throw error;
40
+ }
41
+ finally {
42
+ clearTimeout(timeout);
43
+ }
44
+ }
45
+ }
46
+ //# sourceMappingURL=releaseStatusClient.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"releaseStatusClient.js","sourceRoot":"","sources":["../../../src/utils/releaseStatusClient.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,GAEvB,MAAM,oBAAoB,CAAC;AAS5B,+EAA+E;AAC/E,MAAM,OAAO,mBAAmB;IAK9B,YAAY,OAAmC;QAC7C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,IAAI;QACF,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC,QAAQ,CAAC;QACxC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YAC1C,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC;QAC5B,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAEO,KAAK,CAAC,OAAO;;QACnB,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,UAAU,CACxB,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EACxB,MAAA,IAAI,CAAC,OAAO,CAAC,SAAS,mCAAI,IAAK,CAChC,CAAC;QACF,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAA,IAAI,CAAC,OAAO,CAAC,KAAK,mCAAI,KAAK,CAAC;YAC5C,MAAM,QAAQ,GAAG,MAAM,OAAO,CAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,KAAK,UAAU;gBACpC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE;gBACpB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EACpB;gBACE,KAAK,EAAE,UAAU;gBACjB,OAAO,EACL,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,KAAK,UAAU;oBACxC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE;oBACxB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO;gBAC1B,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CACF,CAAC;YACF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CAAC,0BAA0B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;YAC/D,CAAC;YACD,IAAI,CAAC,SAAS,GAAG,sBAAsB,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;YAC/D,OAAO,IAAI,CAAC,SAAS,CAAC;QACxB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,IAAI,CAAC,SAAS;gBAAE,OAAO,IAAI,CAAC,SAAS,CAAC;YAC1C,MAAM,KAAK,CAAC;QACd,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;CACF","sourcesContent":["import {\n normalizeReleaseStatus,\n type ReleaseStatus,\n} from './releaseStatus.js';\n\nexport type ReleaseStatusClientOptions = {\n url: string | (() => string);\n headers?: HeadersInit | (() => HeadersInit);\n timeoutMs?: number;\n fetch?: typeof fetch;\n};\n\n/** Deduplicates concurrent loads and falls back to the last valid response. */\nexport class ReleaseStatusClient {\n private lastValid?: ReleaseStatus;\n private inFlight?: Promise<ReleaseStatus>;\n private readonly options: ReleaseStatusClientOptions;\n\n constructor(options: ReleaseStatusClientOptions) {\n this.options = options;\n }\n\n load(): Promise<ReleaseStatus> {\n if (this.inFlight) return this.inFlight;\n this.inFlight = this.request().finally(() => {\n this.inFlight = undefined;\n });\n return this.inFlight;\n }\n\n private async request(): Promise<ReleaseStatus> {\n const controller = new AbortController();\n const timeout = setTimeout(\n () => controller.abort(),\n this.options.timeoutMs ?? 8_000\n );\n try {\n const request = this.options.fetch ?? fetch;\n const response = await request(\n typeof this.options.url === 'function'\n ? this.options.url()\n : this.options.url,\n {\n cache: 'no-store',\n headers:\n typeof this.options.headers === 'function'\n ? this.options.headers()\n : this.options.headers,\n signal: controller.signal,\n }\n );\n if (!response.ok) {\n throw new Error(`Status request failed: ${response.status}`);\n }\n this.lastValid = normalizeReleaseStatus(await response.json());\n return this.lastValid;\n } catch (error) {\n if (this.lastValid) return this.lastValid;\n throw error;\n } finally {\n clearTimeout(timeout);\n }\n }\n}\n\n"]}
package/package.json CHANGED
@@ -10,7 +10,7 @@
10
10
  "type": "git",
11
11
  "url": "git+ssh://git@github.com/linked-cm/capacitor.git"
12
12
  },
13
- "version": "1.0.0",
13
+ "version": "1.1.0",
14
14
  "linked": {
15
15
  "kind": "library"
16
16
  },
@@ -27,7 +27,7 @@
27
27
  "license": "ISC",
28
28
  "scripts": {
29
29
  "start": "linked dev",
30
- "test": "npm run build && node --test tests/*.test.mjs",
30
+ "test": "npm run build && node --test tests/*.test.mjs && vitest run --config vitest.config.ts",
31
31
  "build": "linked build"
32
32
  },
33
33
  "keywords": [
@@ -81,15 +81,19 @@
81
81
  "@capgo/capacitor-updater": "^7.4.0",
82
82
  "@changesets/changelog-github": "^0.5.2",
83
83
  "@changesets/cli": "^2.29.8",
84
+ "@testing-library/dom": "10.4.2",
85
+ "@testing-library/react": "16.3.3",
84
86
  "@tolgee/react": "^5.33.0",
85
87
  "@types/node": "^20.12.7",
86
88
  "@types/react": "^19.3.0",
87
89
  "@types/react-dom": "^19.3.0",
88
90
  "capacitor-plugin-safe-area": "^4.0.3",
91
+ "happy-dom": "20.14.6",
89
92
  "react": "^19.3.1",
90
93
  "react-dom": "^19.3.1",
91
94
  "typescript": "^5.7.3",
92
- "typescript-plugin-css-modules": "^5.1.0"
95
+ "typescript-plugin-css-modules": "^5.1.0",
96
+ "vitest": "2.1.9"
93
97
  },
94
98
  "peerDependencies": {
95
99
  "react": "^18.2.0 || ^19.0.0",
package/readme.md CHANGED
@@ -18,6 +18,11 @@ The location term `LocationUpdateAction` (a `schema:UpdateAction`) lives at `htt
18
18
  | `@linked.cm/capacitor/hooks/useCapacitor` | `CapacitorProvider` for deep links and native token storage |
19
19
  | `@linked.cm/capacitor/hooks/useAutomaticUpdates` | OTA bundle updates and a maintenance check |
20
20
  | `@linked.cm/capacitor/hooks/useNativeAppUpdate` | Store update prompt on iOS and Android |
21
+ | `@linked.cm/capacitor/hooks/useMandatoryNativeUpdate` | App-supplied minimum-version enforcement for installed iOS and Android binaries |
22
+ | `@linked.cm/capacitor/hooks/useReleaseGate` | Non-blocking maintenance, installed-binary, and OTA coordination |
23
+ | `@linked.cm/capacitor/utils/releaseStatus` | Shared release-status contract and validation |
24
+ | `@linked.cm/capacitor/utils/releaseStatusCache` | Last-valid server cache and framework-light status handler |
25
+ | `@linked.cm/capacitor/utils/releaseStatusClient` | Deduplicated, validated status client with last-valid fallback |
21
26
  | `@linked.cm/capacitor/shapes/LocationUpdateAction` | `LocationUpdateAction.updateUserLocation` |
22
27
  | `@linked.cm/capacitor/shapes/index` | Registers the location shape without loading the components |
23
28
  | `@linked.cm/capacitor/utils/helper` | `normalizeTelephone` and `replaceLocalhostWithSiteRoot` |
@@ -56,3 +61,95 @@ WhatsApp sign-in asks the backend to send a code, then validates it. `generateOT
56
61
  `LocationEnabler` requests the device position only when the switch turns on, then calls `LocationUpdateAction.updateUserLocation`. Turning the switch off clears `enabledLocationServices` on the current account.
57
62
 
58
63
  `useAutomaticUpdates` runs on iOS and Android. It confirms the current bundle, checks the native store version, polls `{SITE_ROOT}/__health`, and downloads a newer bundle when the server is up. `IOS_APP_STORE_ID` is the numeric store id used when opening the store.
64
+
65
+ `__health` maintenance inside `useAutomaticUpdates` is a legacy server-up
66
+ signal for Capgo OTA timing. Release-status maintenance from `/status` is a
67
+ separate product policy overlay owned by `useReleaseGate`. Apps that adopt the
68
+ release gate should treat `/status` as the source of truth for maintenance UI
69
+ and keep `__health` only as OTA infrastructure probing.
70
+
71
+ Apps that enforce their own minimum installed-binary version can pause OTA
72
+ without delaying application rendering:
73
+
74
+ ```ts
75
+ import { useAutomaticUpdates } from '@linked.cm/capacitor/hooks/useAutomaticUpdates';
76
+ import { useMandatoryNativeUpdate } from '@linked.cm/capacitor/hooks/useMandatoryNativeUpdate';
77
+
78
+ const nativeUpdate = useMandatoryNativeUpdate({
79
+ minimumVersion: status?.minimumVersion,
80
+ fallbackMinimumVersion: COMPILED_MINIMUM_NATIVE_VERSION,
81
+ iosAppStoreId: process.env.IOS_APP_STORE_ID,
82
+ androidPackageName: process.env.APP_ID,
83
+ });
84
+
85
+ useAutomaticUpdates({
86
+ enabled:
87
+ nativeUpdate.state.status === 'not-native' ||
88
+ nativeUpdate.state.status === 'supported',
89
+ checkNativeStoreVersion: false,
90
+ });
91
+ ```
92
+
93
+ While disabled, automatic updates still call `notifyAppReady()` to prevent a
94
+ working Capgo bundle from rolling back, but skip channel, health, store, and OTA
95
+ work. Both options default to the previous behavior for existing callers.
96
+
97
+ For a complete release gate, applications inject their own status loader while
98
+ the package owns the reusable lifecycle and native checks. `loadStatus` must
99
+ return an already-normalized `ReleaseStatus` (for example via
100
+ `ReleaseStatusClient` or `normalizeReleaseStatus`); the gate does not
101
+ re-validate that object.
102
+
103
+ ```ts
104
+ import { useAutomaticUpdates } from '@linked.cm/capacitor/hooks/useAutomaticUpdates';
105
+ import { useReleaseGate } from '@linked.cm/capacitor/hooks/useReleaseGate';
106
+ import { ReleaseStatusClient } from '@linked.cm/capacitor/utils/releaseStatusClient';
107
+
108
+ const statusClient = new ReleaseStatusClient({
109
+ url: () => `${API_ROOT}/status`,
110
+ headers: () => ({ 'X-App-Version': APP_VERSION }),
111
+ });
112
+
113
+ const gate = useReleaseGate({
114
+ loadStatus: () => statusClient.load(),
115
+ fallbackMinimumVersion: COMPILED_MINIMUM_NATIVE_VERSION,
116
+ iosAppStoreId: IOS_APP_STORE_ID,
117
+ androidPackageName: APP_ID,
118
+ });
119
+
120
+ useAutomaticUpdates({
121
+ enabled: gate.otaEnabled,
122
+ checkNativeStoreVersion: false,
123
+ });
124
+ ```
125
+
126
+ The app renders immediately and decides how to present `gate.state`. Web uses
127
+ maintenance only; iOS and Android also enforce the installed store-binary
128
+ version. On native, `gate.otaEnabled` stays false until status has settled and
129
+ the installed binary is confirmed against the exact effective minimum. On web
130
+ it stays true because `useAutomaticUpdates` does not run there.
131
+
132
+ On the server, inject application-owned storage into the cache. The package
133
+ does not own configuration files, locks, authorization, or route registration:
134
+
135
+ ```ts
136
+ import {
137
+ createReleaseStatusHandler,
138
+ ReleaseStatusCache,
139
+ } from '@linked.cm/capacitor/utils/releaseStatusCache';
140
+
141
+ const cache = new ReleaseStatusCache({
142
+ initialStatus: SAFE_COMPILED_STATUS,
143
+ readStatus: () => readReleaseStatusFromApplicationConfig(),
144
+ });
145
+ cache.load();
146
+ cache.start();
147
+ server.get('/status', createReleaseStatusHandler(cache));
148
+ // later, during provider/server dispose:
149
+ cache.stop();
150
+ ```
151
+
152
+ The cache refreshes every minute by default and retains its last valid snapshot
153
+ when reading or validation fails. The handler returns validated release fields
154
+ with `Cache-Control: no-store`. Call `load()` before serving `/status`, keep
155
+ `start()` running while the process is up, and `stop()` on dispose.