@chipmobilesdk/rn-camera 0.1.0

package/src/core/captureController.ts

@@ -0,0 +1,118 @@
+/**
+ * Capture guards, single-flight enforcement, and metadata assembly
+ * (FR-020..FR-026b).
+ *
+ * The single-flight guard rejects rather than queues or coalesces. A queue
+ * turns a double-tapped shutter into two photos the user never asked for, and
+ * coalescing hides a deliberate second capture behind an accidental one — so a
+ * fast, explicit `captureInProgress` error is the only option that lets the app
+ * decide (clarification session 2026-07-26).
+ */
+
+import {
+	known,
+	unavailable,
+	type CameraPosition,
+	type CapabilityProfile,
+	type CapturedImage,
+	type CaptureRequest,
+	type FlashMode,
+	type Maybe,
+	type SessionStatus,
+} from '../config/types';
+import { CameraError } from '../diagnostics/errors';
+import type { CameraEngine } from '../native/cameraEngine';
+import { assertSupported, supportsFlashMode, supportsPosition } from './capabilities';
+import { canCapture } from './sessionMachine';
+
+export const DEFAULT_QUALITY = 0.9;
+
+export function clampQuality(quality: number | undefined): number {
+	if (quality === undefined || Number.isNaN(quality)) {
+		return DEFAULT_QUALITY;
+	}
+	return Math.min(1, Math.max(0, quality));
+}
+
+export function clampMaxDimension(maxDimension: number | undefined): Maybe<number> {
+	if (maxDimension === undefined || !Number.isFinite(maxDimension) || maxDimension <= 0) {
+		return unavailable();
+	}
+	return known(Math.floor(maxDimension));
+}
+
+export interface CaptureContext {
+	readonly engine: CameraEngine;
+	readonly sessionStatus: SessionStatus;
+	readonly permissionGranted: boolean;
+	readonly capabilities: CapabilityProfile | null;
+	readonly cameraPosition: CameraPosition;
+	readonly flashMode: FlashMode;
+}
+
+/**
+ * Validates a capture request against permission, readiness, and capability.
+ * Throws before any artifact could be created, so a rejected capture never
+ * leaves a file behind (FR-020).
+ */
+export function assertCaptureAllowed(context: CaptureContext, request: CaptureRequest): void {
+	if (!context.permissionGranted) {
+		throw new CameraError('permissionDenied', 'Camera permission is not granted');
+	}
+	if (!canCapture(context.sessionStatus)) {
+		throw new CameraError('notReady', `Camera is not ready (session: ${context.sessionStatus})`);
+	}
+	const flashMode = request.flashMode ?? context.flashMode;
+	assertSupported(supportsFlashMode(context.capabilities, flashMode), `flash mode "${flashMode}"`);
+
+	const position = request.cameraPosition ?? context.cameraPosition;
+	assertSupported(supportsPosition(context.capabilities, position), `${position} camera`);
+}
+
+/**
+ * Normalizes whatever the engine returned into the published contract, filling
+ * in effective hint values and marking undeterminable fields explicitly
+ * unavailable rather than guessing them (FR-022, FR-023).
+ */
+export function finalizeResult(
+	raw: CapturedImage,
+	request: CaptureRequest,
+	context: CaptureContext,
+): CapturedImage {
+	const ownership = request.destination ? 'appOwned' : 'packageTemporary';
+	return {
+		...raw,
+		ownership,
+		cameraPosition: raw.cameraPosition ?? request.cameraPosition ?? context.cameraPosition,
+		timestamp: raw.timestamp ?? Date.now(),
+		effectiveQuality: raw.effectiveQuality ?? clampQuality(request.quality),
+		effectiveMaxDimension: raw.effectiveMaxDimension ?? clampMaxDimension(request.maxDimension),
+		fileSize: raw.fileSize ?? unavailable(),
+		orientation: raw.orientation ?? unavailable(),
+	};
+}
+
+/**
+ * Serializes captures. Holding the in-flight promise rather than a boolean
+ * means the guard cannot be defeated by two synchronous calls in the same tick.
+ */
+export class SingleFlight {
+	private inFlight: Promise<CapturedImage> | null = null;
+
+	get busy(): boolean {
+		return this.inFlight !== null;
+	}
+
+	async run(operation: () => Promise<CapturedImage>): Promise<CapturedImage> {
+		if (this.inFlight) {
+			throw new CameraError('captureInProgress', 'A capture is already in progress');
+		}
+		const promise = operation();
+		this.inFlight = promise;
+		try {
+			return await promise;
+		} finally {
+			this.inFlight = null;
+		}
+	}
+}

package/src/core/controller.ts

@@ -0,0 +1,385 @@
+/**
+ * Camera controller — the object consuming apps actually drive.
+ *
+ * It owns observable state and orchestrates the three ports (engine,
+ * permissions, artifact store). All I/O lives here; the decisions live in
+ * `sessionMachine` and `captureController`, which stay pure so they can be
+ * tested without a camera.
+ */
+
+import {
+	type CameraPermissionState,
+	type CameraPosition,
+	type CameraState,
+	type CapabilityProfile,
+	type CapturedImage,
+	type CaptureRequest,
+	type FlashMode,
+	type StartOptions,
+} from '../config/types';
+import { CameraError, isCameraError } from '../diagnostics/errors';
+import { silentLogger, type CameraLogger } from '../diagnostics/logger';
+import type { CameraEngine } from '../native/cameraEngine';
+import type { PermissionPort } from '../permissions/permissionPort';
+import type { ArtifactStore } from '../storage/artifactStore';
+import { EMPTY_CAPABILITIES, assertSupported, supportsTorch } from './capabilities';
+import {
+	SingleFlight,
+	assertCaptureAllowed,
+	finalizeResult,
+	type CaptureContext,
+} from './captureController';
+import { canStart, initialSession, sessionReducer, type SessionSnapshot } from './sessionMachine';
+
+/** 24 hours (FR-029). */
+export const DEFAULT_TEMPORARY_TTL_MS = 24 * 60 * 60 * 1000;
+
+export type AppStatus = 'active' | 'background';
+
+export interface CameraControllerOptions {
+	readonly engine?: CameraEngine;
+	readonly permissions?: PermissionPort;
+	readonly store?: ArtifactStore;
+	readonly logger?: CameraLogger;
+	readonly temporaryTtlMs?: number;
+	/**
+	 * App foreground/background source. Defaults to React Native `AppState`.
+	 * Injectable so lifecycle rules are testable without an app (FR-015).
+	 */
+	readonly subscribeToAppState?: (listener: (status: AppStatus) => void) => () => void;
+	/** Set false to skip the initialization sweep (tests). Defaults to true. */
+	readonly sweepOnInit?: boolean;
+}
+
+export interface CameraController {
+	readonly state: CameraState;
+	subscribe(listener: (state: CameraState) => void): () => void;
+
+	getPermission(): Promise<CameraPermissionState>;
+	requestPermission(): Promise<CameraPermissionState>;
+
+	start(options?: StartOptions): Promise<void>;
+	pause(): Promise<void>;
+	resume(): Promise<void>;
+	stop(): Promise<void>;
+
+	capture(request?: CaptureRequest): Promise<CapturedImage>;
+	cleanup(image: CapturedImage | string): Promise<void>;
+
+	getCapabilities(): Promise<CapabilityProfile>;
+	setFlashMode(mode: FlashMode): void;
+	setTorch(enabled: boolean): Promise<void>;
+
+	/** Marks the preview surface mounted, enabling foreground auto-restart. */
+	setSurfaceMounted(mounted: boolean): void;
+	/** Releases ports, listeners, and the camera. Safe to call twice. */
+	dispose(): Promise<void>;
+}
+
+function defaultAppStateSubscribe(listener: (status: AppStatus) => void): () => void {
+	// Lazy require so importing the package outside React Native (for example in
+	// a Node-based test runner) does not pull in the RN runtime.
+	const { AppState } = require('react-native');
+	const subscription = AppState.addEventListener('change', (next: string) => {
+		listener(next === 'active' ? 'active' : 'background');
+	});
+	return () => subscription.remove();
+}
+
+export function createCameraController(
+	options: CameraControllerOptions = {},
+): CameraController {
+	if (!options.engine || !options.permissions) {
+		throw new CameraError(
+			'unsupportedCapability',
+			'createCameraController requires `engine` and `permissions` ports. Use the ' +
+				'default adapters, or createTestCamera() in tests.',
+		);
+	}
+
+	// Bound after the guard so the closures below see non-optional ports.
+	const engine: CameraEngine = options.engine;
+	const permissions: PermissionPort = options.permissions;
+	const store = options.store;
+	const logger = options.logger ?? silentLogger;
+	const ttlMs = options.temporaryTtlMs ?? DEFAULT_TEMPORARY_TTL_MS;
+
+	let session: SessionSnapshot = initialSession;
+	let permission: CameraPermissionState = 'undetermined';
+	let capabilities: CapabilityProfile | null = null;
+	let cameraPosition: CameraPosition = 'back';
+	let flashMode: FlashMode = 'off';
+	let torchEnabled = false;
+	let surfaceMounted = false;
+	let disposed = false;
+
+	const capture = new SingleFlight();
+	const listeners = new Set<(state: CameraState) => void>();
+
+	function snapshot(): CameraState {
+		return {
+			session: session.status,
+			permission,
+			capabilities,
+			cameraPosition,
+			flashMode,
+			torchEnabled,
+			capturing: capture.busy,
+			error: session.error
+				? {
+						code: session.error.code,
+						recoverable: session.error.recoverable,
+						message: session.error.message,
+				  }
+				: null,
+		};
+	}
+
+	let current = snapshot();
+
+	function emit(): void {
+		current = snapshot();
+		for (const listener of listeners) {
+			listener(current);
+		}
+	}
+
+	function dispatch(event: Parameters<typeof sessionReducer>[1]): void {
+		const next = sessionReducer(session, event);
+		if (next !== session) {
+			session = next;
+			logger.log({
+				type: 'session',
+				code: session.status,
+				recoverable: session.error?.recoverable,
+			});
+			emit();
+		}
+	}
+
+	/** Torch must never survive leaving the active state (FR-034b). */
+	async function forceTorchOff(): Promise<void> {
+		if (!torchEnabled) {
+			return;
+		}
+		torchEnabled = false;
+		try {
+			await engine.setTorch(false);
+		} catch {
+			// Torch-off is best effort; the session is going away regardless.
+		}
+		emit();
+	}
+
+	async function releaseCamera(): Promise<void> {
+		await forceTorchOff();
+		dispatch({ type: 'STOP' });
+		try {
+			await engine.stop();
+			dispatch({ type: 'STOPPED' });
+		} catch (error) {
+			dispatch({ type: 'FAIL', code: isCameraError(error) ? error.code : 'captureFailed' });
+		}
+	}
+
+	const unsubscribePermission = permissions.subscribe(next => {
+		permission = next;
+		logger.log({ type: 'permission', code: next });
+		emit();
+		// A revocation while running must tear the session down, not leave a
+		// frozen preview on screen (FR-007).
+		if (next !== 'granted' && session.status !== 'idle' && session.status !== 'stopped') {
+			releaseCamera().catch(() => undefined);
+		}
+	});
+
+	const unsubscribeAppState = (options.subscribeToAppState ?? defaultAppStateSubscribe)(
+		status => {
+			if (status === 'background') {
+				dispatch({ type: 'BACKGROUND' });
+				releaseCamera().catch(() => undefined);
+			} else {
+				dispatch({ type: 'FOREGROUND', surfaceMounted });
+				if (surfaceMounted && session.status === 'starting') {
+					startEngine().catch(() => undefined);
+				}
+			}
+		},
+	);
+
+	async function startEngine(startOptions: StartOptions = {}): Promise<void> {
+		try {
+			await engine.start({ cameraPosition: startOptions.cameraPosition ?? cameraPosition });
+			dispatch({ type: 'STARTED' });
+		} catch (error) {
+			dispatch({ type: 'FAIL', code: isCameraError(error) ? error.code : 'cameraUnavailable' });
+		}
+	}
+
+	// FR-029: sweep our own temp directory once per process, asynchronously, so
+	// it can never add latency to the capture path or the preview start.
+	if (store && options.sweepOnInit !== false) {
+		store
+			.sweep(ttlMs)
+			.then(removed => {
+				if (removed > 0) {
+					logger.log({ type: 'cleanup', code: `swept:${removed}` });
+				}
+			})
+			.catch(() => {
+				// A failed sweep must never block startup.
+			});
+	}
+
+	const controller: CameraController = {
+		get state() {
+			return current;
+		},
+
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+
+		async getPermission() {
+			permission = await permissions.getStatus();
+			emit();
+			return permission;
+		},
+
+		async requestPermission() {
+			permission = 'requesting';
+			emit();
+			permission = await permissions.request();
+			emit();
+			return permission;
+		},
+
+		async start(startOptions: StartOptions = {}) {
+			if (permission !== 'granted') {
+				dispatch({ type: 'FAIL', code: 'permissionDenied' });
+				throw new CameraError('permissionDenied', 'Camera permission is not granted');
+			}
+			if (!canStart(session.status)) {
+				throw new CameraError('sessionConflict', `Session already ${session.status}`);
+			}
+			if (startOptions.cameraPosition) {
+				cameraPosition = startOptions.cameraPosition;
+			}
+			dispatch({ type: 'START' });
+			await startEngine(startOptions);
+			if (session.error) {
+				throw session.error;
+			}
+		},
+
+		async pause() {
+			await forceTorchOff();
+			dispatch({ type: 'PAUSE' });
+		},
+
+		async resume() {
+			dispatch({ type: 'RESUME' });
+			if (session.status === 'starting') {
+				await startEngine();
+			}
+		},
+
+		async stop() {
+			await releaseCamera();
+		},
+
+		async capture(request: CaptureRequest = {}) {
+			const context: CaptureContext = {
+				engine,
+				sessionStatus: session.status,
+				permissionGranted: permission === 'granted',
+				capabilities,
+				cameraPosition,
+				flashMode,
+			};
+			// Guards run before the single-flight slot is taken so a rejected
+			// request cannot block a subsequent legal one.
+			assertCaptureAllowed(context, request);
+
+			const result = await capture.run(async () => {
+				emit();
+				const raw = await engine.capture({
+					...request,
+					flashMode: request.flashMode ?? flashMode,
+					cameraPosition: request.cameraPosition ?? cameraPosition,
+				});
+				return finalizeResult(raw, request, context);
+			});
+			logger.log({ type: 'capture', code: 'succeeded' });
+			emit();
+			return result;
+		},
+
+		async cleanup(image: CapturedImage | string) {
+			const uri = typeof image === 'string' ? image : image.uri;
+			if (!store) {
+				return;
+			}
+			// Refuse anything we did not create rather than deleting an arbitrary
+			// path, which also covers every appOwned artifact (FR-026b, FR-028).
+			if (!store.owns(uri)) {
+				logger.log({ type: 'cleanup', code: 'refused-not-owned' });
+				return;
+			}
+			await store.remove(uri);
+			logger.log({ type: 'cleanup', code: 'removed' });
+		},
+
+		async getCapabilities() {
+			try {
+				capabilities = await engine.getCapabilities();
+			} catch {
+				capabilities = EMPTY_CAPABILITIES;
+			}
+			logger.log({
+				type: 'capability',
+				code: capabilities.hasCameraHardware ? 'available' : 'no-hardware',
+			});
+			emit();
+			return capabilities;
+		},
+
+		setFlashMode(mode: FlashMode) {
+			assertSupported(
+				mode === 'off' || capabilities?.hasFlash === true,
+				`flash mode "${mode}"`,
+			);
+			flashMode = mode;
+			emit();
+		},
+
+		async setTorch(enabled: boolean) {
+			if (enabled) {
+				assertSupported(supportsTorch(capabilities), 'torch');
+			}
+			await engine.setTorch(enabled);
+			torchEnabled = enabled;
+			emit();
+		},
+
+		setSurfaceMounted(mounted: boolean) {
+			surfaceMounted = mounted;
+		},
+
+		async dispose() {
+			if (disposed) {
+				return;
+			}
+			disposed = true;
+			unsubscribePermission();
+			unsubscribeAppState();
+			await releaseCamera();
+			listeners.clear();
+		},
+	};
+
+	return controller;
+}

package/src/core/sessionMachine.ts

@@ -0,0 +1,111 @@
+/**
+ * Session lifecycle state machine (FR-014..FR-019).
+ *
+ * Pure and synchronous: it decides what a transition means, the controller
+ * performs the I/O. That split is what makes every lifecycle rule in
+ * `data-model.md` section 2 testable without a camera.
+ *
+ * Backgrounding STOPS rather than pauses. Both operating systems can reclaim
+ * the camera anyway, and holding it risks leaving the OS camera indicator lit
+ * after the app is no longer in front of the user (FR-015).
+ */
+
+import type { SessionStatus } from '../config/types';
+import { CameraError, type CameraErrorCode } from '../diagnostics/errors';
+
+export type SessionEvent =
+	| { readonly type: 'START' }
+	| { readonly type: 'STARTED' }
+	| { readonly type: 'PAUSE' }
+	| { readonly type: 'RESUME' }
+	| { readonly type: 'STOP' }
+	| { readonly type: 'STOPPED' }
+	| { readonly type: 'BACKGROUND' }
+	| { readonly type: 'FOREGROUND'; readonly surfaceMounted: boolean }
+	| { readonly type: 'FAIL'; readonly code: CameraErrorCode }
+	| { readonly type: 'START_TIMEOUT' };
+
+export interface SessionSnapshot {
+	readonly status: SessionStatus;
+	readonly error: CameraError | null;
+}
+
+export const initialSession: SessionSnapshot = { status: 'idle', error: null };
+
+/** Statuses from which a fresh start is allowed (FR-019). */
+const STARTABLE: ReadonlySet<SessionStatus> = new Set<SessionStatus>([
+	'idle',
+	'stopped',
+	'error',
+]);
+
+export function canStart(status: SessionStatus): boolean {
+	return STARTABLE.has(status);
+}
+
+/** Capture is only ever legal from a fully active session (FR-020). */
+export function canCapture(status: SessionStatus): boolean {
+	return status === 'active';
+}
+
+function fail(code: CameraErrorCode): SessionSnapshot {
+	return { status: 'error', error: new CameraError(code) };
+}
+
+export function sessionReducer(
+	snapshot: SessionSnapshot,
+	event: SessionEvent,
+): SessionSnapshot {
+	const { status } = snapshot;
+
+	switch (event.type) {
+		case 'START':
+			if (!canStart(status)) {
+				// Refuse rather than silently stealing the camera from the surface
+				// that already holds it (FR-019).
+				return { status, error: new CameraError('sessionConflict') };
+			}
+			return { status: 'starting', error: null };
+
+		case 'STARTED':
+			return status === 'starting' ? { status: 'active', error: null } : snapshot;
+
+		case 'START_TIMEOUT':
+			// Never sit in `starting` forever when frames stop arriving.
+			return status === 'starting' ? fail('captureFailed') : snapshot;
+
+		case 'PAUSE':
+			return status === 'active' ? { status: 'paused', error: null } : snapshot;
+
+		case 'RESUME':
+			return status === 'paused' ? { status: 'starting', error: null } : snapshot;
+
+		case 'STOP':
+			if (status === 'stopped' || status === 'idle') {
+				return snapshot;
+			}
+			return { status: 'stopping', error: snapshot.error };
+
+		case 'STOPPED':
+			return { status: 'stopped', error: null };
+
+		case 'BACKGROUND':
+			// Release, do not hold (FR-015).
+			if (status === 'active' || status === 'paused' || status === 'starting') {
+				return { status: 'stopping', error: null };
+			}
+			return snapshot;
+
+		case 'FOREGROUND':
+			if (event.surfaceMounted && (status === 'stopped' || status === 'idle')) {
+				return { status: 'starting', error: null };
+			}
+			return snapshot;
+
+		case 'FAIL':
+			return fail(event.code);
+
+		default:
+			return snapshot;
+	}
+}

package/src/diagnostics/errors.ts

@@ -0,0 +1,92 @@
+/**
+ * Typed error taxonomy (FR-044) and redaction helper (FR-038).
+ *
+ * The taxonomy exists so consuming apps can branch on `code` and `recoverable`
+ * instead of string-matching messages. Messages never carry file paths or image
+ * payloads — `redact` is applied before any value reaches a log sink.
+ */
+
+export type CameraErrorCode =
+	| 'permissionDenied'
+	| 'cameraUnavailable'
+	| 'cameraBlocked'
+	| 'cameraInUse'
+	| 'sessionConflict'
+	| 'notReady'
+	| 'captureInProgress'
+	| 'captureFailed'
+	| 'storageFailure'
+	| 'unsupportedCapability'
+	| 'interrupted';
+
+/** Codes the app may retry; everything else ends the session. */
+const RECOVERABLE: ReadonlySet<CameraErrorCode> = new Set<CameraErrorCode>([
+	'permissionDenied',
+	'cameraInUse',
+	'sessionConflict',
+	'notReady',
+	'captureInProgress',
+	'captureFailed',
+	'storageFailure',
+	'unsupportedCapability',
+	'interrupted',
+]);
+
+export class CameraError extends Error {
+	readonly code: CameraErrorCode;
+	readonly recoverable: boolean;
+
+	constructor(code: CameraErrorCode, message?: string) {
+		super(message ?? code);
+		this.name = 'CameraError';
+		this.code = code;
+		this.recoverable = RECOVERABLE.has(code);
+		Object.setPrototypeOf(this, CameraError.prototype);
+	}
+}
+
+export function isCameraError(value: unknown): value is CameraError {
+	return value instanceof CameraError;
+}
+
+/** Matches anything path-like: file URIs, POSIX paths, and Windows paths. */
+const PATH_PATTERN =
+	/(?:[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s"']+)|(?:[a-zA-Z]:[\\/][^\s"']+)|(?:\/[^\s"']*\/[^\s"']*)/g;
+/** Matches base64-ish runs long enough to be an encoded image payload. */
+const PAYLOAD_PATTERN = /[A-Za-z0-9+/=]{64,}/g;
+
+const REDACTED = '[redacted]';
+const SENSITIVE_KEYS = new Set(['uri', 'path', 'destination', 'file', 'data', 'base64']);
+
+function redactString(value: string): string {
+	return value.replace(PATH_PATTERN, REDACTED).replace(PAYLOAD_PATTERN, REDACTED);
+}
+
+/**
+ * Strips paths and payload-shaped strings from a value before logging (FR-038).
+ * Recurses through plain objects and arrays; known-sensitive keys are dropped
+ * wholesale rather than pattern-matched, since a bare filename has no separator
+ * for the path pattern to catch.
+ */
+export function redact(value: unknown): unknown {
+	if (typeof value === 'string') {
+		return redactString(value);
+	}
+	if (Array.isArray(value)) {
+		return value.map(redact);
+	}
+	if (value instanceof CameraError) {
+		return { code: value.code, recoverable: value.recoverable };
+	}
+	if (value instanceof Error) {
+		return { name: value.name, message: redactString(value.message) };
+	}
+	if (value && typeof value === 'object') {
+		const out: Record<string, unknown> = {};
+		for (const [key, item] of Object.entries(value)) {
+			out[key] = SENSITIVE_KEYS.has(key) ? REDACTED : redact(item);
+		}
+		return out;
+	}
+	return value;
+}