Getting Started - PosCam · Phoenix Framework

Quick Start

1

Install the package

npm install @poscam/use-camera

2

Get your API token

API tokens are currently available during the alpha phase for approved developers.

3

Import and use the hook

Import the useCamera hook and CameraState enum, then initialize with your session ID and auth token.

Camera States

The camera goes through several states during its lifecycle:

Loading

Initializing camera session and establishing connection.

Waiting

Camera session created, waiting for device to connect via QR code.

Connected

Camera is connected and ready to take pictures.

Closed

Session ended or camera disconnected.

API Reference

Hook

useCamera

React hook for managing remote camera sessions with real-time WebSocket communication.

Syntax

const camera: UseCameraReturn = useCamera(options: UseCameraOptions)

TypeScript Definitions

// Options interface
interface UseCameraOptions {
  sessionId: string;
  authToken: string;
  host?: string;
  useHttps?: boolean;
}

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

// Supporting types
enum CameraState {
  LOADING = "loading",
  WAITING = "waiting",
  CONNECTED = "connected",
  CLOSED = "closed",
  ERROR = "error",
}

interface CameraImage {
  id: string;
  url: string;
}

Parameters

Property	Type	Required	Description
sessionId	string	Required	Unique identifier for the camera session
authToken	string	Required	API authentication token from PosCam
host	string	Optional	Server hostname. Defaults to `"poscam.shop"`
useHttps	boolean	Optional	Use HTTPS/WSS protocols. Defaults to `true`

Returns

Property	Type	Description
cameraState	CameraState	Current camera connection state
qrCodeURL	string	URL of the QR code for camera connection
image	CameraImage \| undefined	Latest captured image with id and url
error	string \| null	Error message if something went wrong
initialize	() => Promise<void>	Initialize camera session and WebSocket connection
takePicture	() => void	Trigger photo capture on connected camera
disconnect	() => void	Disconnect WebSocket and cleanup resources
retry	() => Promise<void>	Retry connection after error or disconnect

Shopify POS UI Extension Example

import { useEffect, useState } from "react";
import {
  reactExtension,
  useApi,
  Navigator,
  Screen,
  Text,
  Image,
  Button,
  Banner,
  Section,
  Box,
  ScrollView,
} from "@shopify/ui-extensions-react/point-of-sale";
import { useCamera, CameraState } from "@poscam/use-camera";

const POSCAM_AUTH_TOKEN = "your-api-token-here";

export const CameraCapture = () => {
  const api = useApi();
  const [capturedImages, setCapturedImages] = useState([]);

  // Create session ID based on shop context
  const { shopId, locationId, userId } = api.session.currentSession;
  const sessionId = `${shopId}-${locationId}-${userId}`;

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

  // Initialize camera when modal opens
  useEffect(() => {
    initialize();

    return () => {
      disconnect();
    };
  }, []);

  // Handle new images
  useEffect(() => {
    if (image) {
      setCapturedImages((prev) => [...prev, image]);
    }
  }, [image]);

  const handleDone = () => {
    disconnect();
    api.navigation.dismiss();
  };

  const isLoading = cameraState === CameraState.LOADING;

  return (
    <Navigator>
      <Screen
        name="CameraCapture"
        title="Camera Capture"
        isLoading={isLoading}
        onNavigateBack={handleDone}
      >
        <ScrollView>
          <Section>
            <Button
              title="Take Picture"
              onPress={takePicture}
              disabled={cameraState !== CameraState.CONNECTED}
            />

            {cameraState === CameraState.CLOSED && (
              <Button title="Reconnect" onPress={retry} />
            )}

            <Button title="Done" onPress={handleDone} />
          </Section>

          {error && (
            <Banner status="critical" title="Camera Error">
              <Text>{error}</Text>
            </Banner>
          )}

          {cameraState === CameraState.WAITING && qrCodeURL && (
            <Section>
              <Text>Scan this QR code to connect your camera:</Text>
              <Box>
                <Image source={qrCodeURL} />
              </Box>
            </Section>
          )}

          {cameraState === CameraState.CONNECTED && (
            <Section>
              <Text>Camera connected! Ready to take pictures.</Text>
            </Section>
          )}

          {capturedImages.length > 0 && (
            <Section>
              <Text>Captured {capturedImages.length} image(s)</Text>
              {capturedImages.map((img, index) => (
                <Box key={img.id}>
                  <Image source={img.url} />
                </Box>
              ))}
            </Section>
          )}
        </ScrollView>
      </Screen>
    </Navigator>
  );
};

Resources

GitHub Repository

View source code, report issues, and contribute to the project.

NPM Package

Install the package and view detailed documentation.

Ready to Get Started?

You now have everything you need to integrate remote camera functionality into your React application.