@chipmobilesdk/rn-camera 0.2.0 → 0.3.0

package/src/core/sessionMachine.ts

@@ -1,111 +1,104 @@
-/**
- * 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;
-	}
-}
+/**
+ * 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

@@ -1,92 +1,94 @@
-/**
- * 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;
-}
+/**
+ * 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.
+ */
+
+import { COMMON_PATTERNS, PATH_PATTERN, SdkError, redactPatterns } from '@chipmobilesdk/rn-core';
+
+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',
+]);
+
+/** The package's error; an `SdkError` (`@chipmobilesdk/rn-core`) with `pkg: 'rn-camera'`. */
+export class CameraError extends SdkError<CameraErrorCode> {
+	constructor(code: CameraErrorCode, message?: string) {
+		super('rn-camera', code, { message, retryable: RECOVERABLE.has(code) });
+		this.name = 'CameraError';
+	}
+
+	/** @deprecated Use `retryable`, the name every SDK package shares. */
+	get recoverable(): boolean {
+		return this.retryable;
+	}
+}
+
+export function isCameraError(value: unknown): value is CameraError {
+	return value instanceof CameraError;
+}
+
+/**
+ * rn-core's shared patterns (URLs, including file URIs; JWTs; e-mail addresses;
+ * UUIDs; base64-ish payload runs) plus POSIX and Windows paths.
+ */
+const PATTERNS = [...COMMON_PATTERNS, PATH_PATTERN];
+
+const REDACTED = '[redacted]';
+const SENSITIVE_KEYS = new Set(['uri', 'path', 'destination', 'file', 'data', 'base64']);
+
+function redactString(value: string): string {
+	return redactPatterns(value, PATTERNS);
+}
+
+/**
+ * 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.retryable };
+	}
+	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;
+}

package/src/diagnostics/logger.ts

@@ -1,31 +1,47 @@
-/**
- * Optional consumer-supplied logger (research R4).
- *
- * The default is no logging at all, so FR-038 holds whether or not a consumer
- * opts in. Event bodies carry codes and states only — never file paths, never
- * image data — so an opted-in logger still cannot leak an image path.
- */
-
-export type CameraLogEventType =
-	| 'session'
-	| 'permission'
-	| 'capture'
-	| 'capability'
-	| 'cleanup';
-
-export interface CameraLogEvent {
-	readonly type: CameraLogEventType;
-	readonly code: string;
-	readonly recoverable?: boolean;
-}
-
-export interface CameraLogger {
-	log(event: CameraLogEvent): void;
-}
-
-/** No-op logger used when the consumer supplies none. */
-export const silentLogger: CameraLogger = {
-	log() {
-		// Intentionally empty: logging is opt-in.
-	},
-};
+/**
+ * Optional consumer-supplied logger (research R4).
+ *
+ * The default is no logging at all, so FR-038 holds whether or not a consumer
+ * opts in. Event bodies carry codes and states only — never file paths, never
+ * image data — so an opted-in logger still cannot leak an image path.
+ */
+
+import { createDiagnosticChannel } from '@chipmobilesdk/rn-core';
+
+export type CameraLogEventType = 'session' | 'permission' | 'capture' | 'capability' | 'cleanup';
+
+export interface CameraLogEvent {
+	readonly type: CameraLogEventType;
+	readonly code: string;
+	readonly recoverable?: boolean | undefined;
+}
+
+export interface CameraLogger {
+	log(event: CameraLogEvent): void;
+}
+
+const channel = createDiagnosticChannel('rn-camera');
+
+/**
+ * Every event also reaches the app's SDK sinks (`installSdkSink`, CORE-08), as
+ * `<type>.<code>`: the same code-and-state body, so nothing new can leak.
+ */
+export function withSdkSinks(logger: CameraLogger): CameraLogger {
+	return {
+		log(event) {
+			channel.emit(
+				`${event.type}.${event.code}`,
+				event.code === 'listener-threw' ? 'error' : event.recoverable === false ? 'warn' : 'info',
+				event.recoverable === undefined ? undefined : { retryable: event.recoverable },
+			);
+			logger.log(event);
+		},
+	};
+}
+
+/** No-op logger used when the consumer supplies none. */
+export const silentLogger: CameraLogger = {
+	log() {
+		// Intentionally empty: logging is opt-in.
+	},
+};