@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 hook
const apiToken = "your-api-token-here"; // Obtained from PosCam user settings
const sessionId = "unique-session-identifier"; // Your application's session ID

Usage

import { useCamera, CameraState, CameraImage } from "@poscam/use-camera";

function CameraComponent({ sessionId, authToken }: { sessionId: string, authToken: string }) {
  const {
    cameraState,
    qrCodeURL,
    image,
    error,
    initialize,
    disconnect,
    retry,
    takePicture,
  } = useCamera({
    sessionId,
    authToken,
  });

  // Initialize camera on mount
  useEffect(() => {
    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 && <img src={qrCodeURL} alt="QR Code" />}
      {image && <img src={image.url} alt="Latest capture" />}
      <button onClick={retry}>Retry</button>
      <button onClick={disconnect}>Disconnect</button>
      {cameraState === CameraState.CONNECTED && (
        <button onClick={takePicture}>Take Picture</button>
      )}
    </div>
  );
}

API

useCamera(options)

Parameters

interface UseCameraOptions {
  sessionId: string;       // Unique session identifier
  authToken: string;       // API authentication token
  host?: string;           // Default: "poscam.shop"
  useHttps?: boolean;      // Default: true
}

Returns

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

Image Structure

interface CameraImage {
  id: string;    // Unique identifier for the image
  url: string;   // URL to access the image
}

Camera States

enum CameraState {
  LOADING = "loading",     // Initializing camera session
  WAITING = "waiting",     // Waiting for camera connection
  CONNECTED = "connected", // Camera is connected and ready
  CLOSED = "closed",       // Camera session has been closed
  ERROR = "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 picture
if (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