@poscam/use-camera

A React hook for camera functionality for use with PosCam. This hook provides everything a developer needs to integrate remote camera capabilities into a react (or even react native) application. Originally built for use with Shopify POS UI Extensions, useCamera aims to be easy to use in any application!

Installation

npm install @poscam/use-camera

Peer Dependencies

• react ^18.0.0
• phoenix ^1.7.0

Authentication

Before using the camera hook, you need to obtain an API token from the PosCam application. API tokens can be created through the user settings page and are required for all API requests.

// Example: Getting a token and using it with the hookconstapiToken="your-api-token-here";// Obtained from PosCam user settingsconstsessionId="unique-session-identifier";// Your application's session ID

Usage

import{useCamera,CameraState,CameraImage}from"@poscam/use-camera";functionCameraComponent({ sessionId, authToken }: {sessionId: string,authToken: string}){const{
cameraState,
qrCodeURL,
image,
error,
initialize,
disconnect,
retry,
takePicture,}=useCamera({
sessionId,
authToken,});// Initialize camera on mountuseEffect(()=>{initialize();},[initialize]);if(cameraState===CameraState.LOADING)return<div>Loading...</div>;if(cameraState===CameraState.ERROR)return<div>Error: {error}</div>;return(<div><p>Status: {cameraState}</p>{qrCodeURL&&<imgsrc={qrCodeURL}alt="QR Code"/>}{image&&<imgsrc={image.url}alt="Latest capture"/>}<buttononClick={retry}>Retry</button><buttononClick={disconnect}>Disconnect</button>{cameraState===CameraState.CONNECTED&&(<buttononClick={takePicture}>TakePicture</button>)}</div>);}

API

useCamera(options)

Parameters

interfaceUseCameraOptions{sessionId: string;// Unique session identifierauthToken: string;// API authentication tokenhost?: string;// Default: "poscam.shop"useHttps?: boolean;// Default: true}

Returns

interfaceUseCameraReturn{cameraState: CameraState;qrCodeURL: string;image: CameraImage|undefined;error: string|null;initialize: ()=>Promise<void>;disconnect: ()=>void;retry: ()=>Promise<void>;takePicture: ()=>void;}

Image Structure

interfaceCameraImage{id: string;// Unique identifier for the imageurl: string;// URL to access the image}

Camera States

enumCameraState{LOADING="loading",// Initializing camera sessionWAITING="waiting",// Waiting for camera connectionCONNECTED="connected",// Camera is connected and readyCLOSED="closed",// Camera session has been closedERROR="error",// An error occurred}

State Flow:

• LOADING → WAITING → CONNECTED → CLOSED (normal flow)
• LOADING → ERROR (on initialization failure)
• Any state → ERROR (on WebSocket errors)

Functions

initialize()

Initializes the camera session and WebSocket connection. Creates a new camera with QR code and establishes real-time communication. Sets cameraState to LOADING during initialization, then to the server's state on success or ERROR on failure.

disconnect()

Manually disconnects the WebSocket connection and cleans up resources.

retry()

Disconnects and re-initializes the camera session. Useful for recovering from errors. Clears any previous error state and attempts a fresh connection.

takePicture()

Triggers a picture capture command that is broadcast to all connected camera devices via WebSocket. This function:

• Only works when cameraState is CameraState.CONNECTED

Usage Example:

const{ takePicture, cameraState }=useCamera({sessionId: "your-session-id",authToken: "your-api-token"});// Check if camera is connected before taking pictureif(cameraState===CameraState.CONNECTED){takePicture();}

Note: This function sends a command to trigger photo capture. The actual photo capturing and image processing happens on the camera device side (browser with camera access).

License

MIT