API.md

Functions

• ClientApiProvider
• useClientApi
• useOwnDeviceInfo
• useIsArchiveDevice
• useSetOwnDeviceInfo
• useSetIsArchiveDevice
• useProjectSettings
• useSingleProject
• useManyProjects
• useSingleMember
• useManyMembers
• useIconUrl
• useAttachmentUrl
• useDocumentCreatedBy
• useAddServerPeer
• useCreateProject
• useLeaveProject
• useImportProjectConfig
• useUpdateProjectSettings
• useCreateBlob
• useSingleDocByDocId
• useSingleDocByVersionId
• useManyDocs
• useCreateDocument
• useUpdateDocument
• useDeleteDocument
• useAcceptInvite
• useRejectInvite
• useSendInvite
• useRequestCancelInvite
• useMapStyleUrl

ClientApiProvider

Create a context provider that holds a CoMapeo API client instance.

Function	Type
ClientApiProvider	({ children, clientApi, }: { children: ReactNode; clientApi: MapeoClientApi; }) => FunctionComponentElement<ProviderProps<MapeoClientApi or null>>

Parameters:

• opts.children: React children node
• opts.clientApi: Client API instance

useClientApi

Access a client API instance. If a ClientApiContext provider is not set up, it will throw an error.

Function	Type
useClientApi	() => MapeoClientApi

Examples:

function ClientExample() {
  return (
    // Creation of clientApi omitted for brevity
    <ClientApiContext.Provider clientApi={clientApi}>
      <ComponentThatUsesClient />
    </ClientApiContext.Provider>
  )
}

function ComponentThatUsesClient() {
  const clientApi = useClientApi()

  // Rest omitted for brevity.
}

useOwnDeviceInfo

Retrieve info about the current device.

Function	Type
useOwnDeviceInfo	() => { data: { deviceId: string; deviceType: "device_type_unspecified" or "mobile" or "tablet" or "desktop" or "selfHostedServer" or "UNRECOGNIZED"; } and Partial<DeviceInfoParam>; error: Error or null; isRefetching: boolean; }

Examples:

function DeviceInfoExample() {
  const { data } = useDeviceInfo()
}

useIsArchiveDevice

Retrieve whether the current device is an archive device or not.

Function	Type
useIsArchiveDevice	() => { data: boolean; error: Error or null; isRefetching: boolean; }

Examples:

function IsArchiveDeviceExample() {
  const { data } = useIsArchiveDevice()
}

useSetOwnDeviceInfo

Update the device info for the current device.

Function	Type
useSetOwnDeviceInfo	() => { mutate: UseMutateFunction<void, Error, { name: string; deviceType: "device_type_unspecified" or "mobile" or "tablet" or "desktop" or "selfHostedServer" or "UNRECOGNIZED"; }, unknown>; reset: () => void; status: "pending" or ... 2 more ... or "idle"; }

useSetIsArchiveDevice

Set or unset the current device as an archive device.

Function	Type
useSetIsArchiveDevice	() => { mutate: UseMutateFunction<void, Error, { isArchiveDevice: boolean; }, unknown>; reset: () => void; status: "pending" or "error" or "success" or "idle"; }

useProjectSettings

Retrieve the project settings for a project.

Function	Type
useProjectSettings	({ projectId }: { projectId: string; }) => { data: EditableProjectSettings; error: Error or null; isRefetching: boolean; }

Parameters:

• opts.projectId: Project public ID

Examples:

function BasicExample() {
  const { data } = useProjectSettings({ projectId: '...' })

  console.log(data.name)
}

useSingleProject

Retrieve a project API instance for a project.

This is mostly used internally by the other hooks and should only be used if certain project APIs are not exposed via the hooks.

Function	Type
useSingleProject	({ projectId }: { projectId: string; }) => { data: ClientApi<MapeoProject>; error: Error or null; isRefetching: boolean; }

Parameters:

• opts.projectId: Project public ID

Examples:

function BasicExample() {
  const { data } = useSingleProject({ projectId: '...' })
}

useManyProjects

Retrieve project information for each project that exists.

Function	Type
useManyProjects	() => { data: (Pick<{ schemaName: "projectSettings"; name?: string or undefined; defaultPresets?: { point: string[]; area: string[]; vertex: string[]; line: string[]; relation: string[]; } or undefined; configMetadata?: { ...; } or undefined; }, "name"> and { ...; })[]; error: Error or null; isRefetching: boolean; }

Examples:

function BasicExample() {
  const { data } = useManyProjects()

  console.log(data.map(project => project.name))
}

useSingleMember

Retrieve a single member of a project.

Function	Type
useSingleMember	({ projectId, deviceId, }: { projectId: string; deviceId: string; }) => { data: MemberInfo; error: Error or null; isRefetching: boolean; }

Parameters:

• opts.projectId: Project public ID
• opts.projectId: Device ID of interest

Examples:

function BasicExample() {
  const { data } = useSingleMember({ projectId: '...', deviceId: '...' })

  console.log(data.role)
}

useManyMembers

Retrieve all members of a project.

Function	Type
useManyMembers	({ projectId }: { projectId: string; }) => { data: MemberInfo[]; error: Error or null; isRefetching: boolean; }

Parameters:

• opts.projectId: Project public ID

Examples:

function BasicExample() {
  const { data } = useManyMembers({ projectId: '...' })

  console.log(data.role)
}

useIconUrl

Retrieve a URL that points to icon resources served by the embedded HTTP server.

TODO: Explain bitmap opts vs svg opts

Function	Type
useIconUrl	({ projectId, iconId, ...mimeBasedOpts }: { projectId: string; iconId: string; } and (BitmapOpts or SvgOpts)) => { data: string; error: Error or null; isRefetching: boolean; }

Parameters:

• opts.projectId: Project public ID
• opts.iconId: Icon ID of interest
• opts.mimeType: MIME type of desired resource
• opts.pixelDensity: Pixel density resource (only applicable when mimeType is 'image/png')
• opts.size: Size of desired resource

Examples:

function PngExample() {
  const { data } = useIconUrl({
    projectId: '...',
    iconId: '...',
    mimeType: 'image/png',
    pixelDensity: 1,
    size: 'medium'
  })
}

function SvgExample() {
  const { data } = useIconUrl({
    projectId: '...',
    iconId: '...',
    mimeType: 'image/svg',
    size: 'medium'
  })
}

useAttachmentUrl

Retrieve a URL that points to a desired blob resource.

TODO: Explain BlobId in more depth

Function	Type
useAttachmentUrl	({ projectId, blobId, }: { projectId: string; blobId: BlobId; }) => { data: string; error: Error or null; isRefetching: boolean; }

Parameters:

• opts.projectId: Project public Id
• opts.blobId: Blob ID of the desired resource

Examples:

function PhotoExample() {
  const { data } = useAttachmentUrl({
    projectId: '...',
    blobId: {
      type: 'photo',
      variant: 'thumbnail',
      name: '...',
      driveId: '...',
    }
  })
}

function AudioExample() {
  const { data } = useAttachmentUrl({
    projectId: '...',
    blobId: {
      type: 'audio',
      variant: 'original',
      name: '...',
      driveId: '...',
    }
  })
}

function VideoExample() {
  const { data } = useAttachmentUrl({
    projectId: '...',
    blobId: {
      type: 'video',
      variant: 'original',
      name: '...',
      driveId: '...',
    }
  })
}

useDocumentCreatedBy

Retrieve the device ID that created a document.

Function	Type
useDocumentCreatedBy	({ projectId, originalVersionId, }: { projectId: string; originalVersionId: string; }) => { data: string; error: Error or null; isRefetching: boolean; }

Parameters:

• opts.projectId: Project public ID
• opts.originalVersionId: Version ID of document

Examples:

function BasicExample() {
  const { data } = useDocumentCreatedBy({
    projectId: '...',
    originalVersionId: '...',
  })
}

useAddServerPeer

Function	Type
useAddServerPeer	({ projectId }: { projectId: string; }) => { mutate: UseMutateFunction<void, Error, { baseUrl: string; dangerouslyAllowInsecureConnections?: boolean or undefined; }, unknown>; reset: () => void; status: "pending" or ... 2 more ... or "idle"; }

useCreateProject

Create a new project.

Function	Type
useCreateProject	() => { mutate: UseMutateFunction<string, Error, { name?: string or undefined; configPath?: string or undefined; } or undefined, unknown>; reset: () => void; status: "pending" or ... 2 more ... or "idle"; }

useLeaveProject

Leave an existing project.

Function	Type
useLeaveProject	() => { mutate: UseMutateFunction<void, Error, { projectId: string; }, unknown>; reset: () => void; status: "pending" or "error" or "success" or "idle"; }

useImportProjectConfig

Update the configuration of a project using an external file.

Function	Type
useImportProjectConfig	({ projectId }: { projectId: string; }) => { mutate: UseMutateFunction<Error[], Error, { configPath: string; }, unknown>; reset: () => void; status: "pending" or "error" or "success" or "idle"; }

Parameters:

• opts.projectId: Public ID of the project to apply changes to.

useUpdateProjectSettings

Update the settings of a project.

Function	Type
useUpdateProjectSettings	({ projectId }: { projectId: string; }) => { mutate: UseMutateFunction<EditableProjectSettings, Error, { name?: string or undefined; configMetadata?: { name: string; buildDate: string; importDate: string; fileVersion: string; } or undefined; defaultPresets?: { ...; } or undefined; }, unknown>; reset: () => void; status...

Parameters:

• opts.projectId: Public ID of the project to apply changes to.

useCreateBlob

Create a blob for a project.

Function	Type
useCreateBlob	({ projectId }: { projectId: string; }) => { mutate: UseMutateFunction<{ driveId: string; name: string; type: "audio" or "video" or "photo"; hash: string; }, Error, { original: string; preview?: string or undefined; thumbnail?: string or undefined; metadata: Metadata; }, unknown>; reset: () => void; status: "pending" or ...

Parameters:

• opts.projectId: Public project ID of project to apply to changes to.

useSingleDocByDocId

Retrieve a single document from the database based on the document's document ID.

Triggers the closest error boundary if the document cannot be found

Function	Type
useSingleDocByDocId	<D extends WriteableDocumentType>({ projectId, docType, docId, lang, }: { projectId: string; docType: D; docId: string; lang?: string or undefined; }) => ReadHookResult<Extract<{ schemaName: "deviceInfo"; name: string; deviceType: "device_type_unspecified" or ... 4 more ... or "UNRECOGNIZED"; ... 7 more ...; deleted: b...

Parameters:

• opts.projectId: Project public ID
• opts.docType: Document type of interest
• opts.docId: Document ID
• opts.lang: Language to translate the document into

Examples:

function SingleDocumentByDocIdExample() {
  const { data } = useSingleDocByDocId({
    projectId: '...',
    docType: 'observation',
    docId: '...',
  })

  console.log(data.schemaName) // logs 'observation'
}

useSingleDocByVersionId

Retrieve a single document from the database based on the document's version ID.

Triggers the closest error boundary if the document cannot be found.

Function	Type
useSingleDocByVersionId	<D extends WriteableDocumentType>({ projectId, docType, versionId, lang, }: { projectId: string; docType: D; versionId: string; lang?: string or undefined; }) => ReadHookResult<Extract<{ schemaName: "deviceInfo"; name: string; deviceType: "device_type_unspecified" or ... 4 more ... or "UNRECOGNIZED"; ... 7 more ...; de...

Parameters:

• opts.projectId: Project public ID

• opts.docType: Document type of interest

• opts.versionId: Document's version ID

• opts.lang: Language to translate the document into

Examples:

function SingleDocumentByVersionIdExample() {
  const { data } = useSingleDocByVersionId({
    projectId: '...',
    docType: 'observation',
    docId: '...',
  })

  console.log(data.schemaName) // logs 'observation'
}

useManyDocs

Retrieve all documents of a specific docType.

Function	Type
useManyDocs	<D extends WriteableDocumentType>({ projectId, docType, includeDeleted, lang, }: { projectId: string; docType: D; includeDeleted?: boolean or undefined; lang?: string or undefined; }) => ReadHookResult<(Extract<{ schemaName: "deviceInfo"; name: string; deviceType: "device_type_unspecified" or ... 4 more ... or "UNRECOGN...

Parameters:

• opts.projectId: Project public ID
• opts.docType: Document type of interest
• opts.includeDeleted: Include documents that have been marked as deleted
• opts.lang: Language to translate the documents into

Examples:

function BasicExample() {
  const { data } = useManyDocs({
    projectId: '...',
    docType: 'observations',
  })
}

function useAllObservations(opts) {
  return useManyDocs({
    ...opts,
    docType: 'observations',
  })
}

function useAllPresets(opts) {
  return useManyDocs({
    ...opts,
    docType: 'presets',
  })
}

useCreateDocument

Create a document for a project.

Function	Type
useCreateDocument	<D extends WriteableDocumentType>({ docType, projectId, }: { docType: D; projectId: string; }) => { mutate: UseMutateFunction<WriteableDocument<D> and { forks: string[]; }, Error, { value: Omit<WriteableValue<D>, "schemaName">; }, unknown>; reset: () => void; status: "pending" or ... 2 more ... or "idle"; }

Parameters:

• opts.docType: Document type to create.
• opts.projectId: Public ID of project to create document for.

useUpdateDocument

Update a document within a project.

Function	Type
useUpdateDocument	<D extends WriteableDocumentType>({ docType, projectId, }: { docType: D; projectId: string; }) => { mutate: UseMutateFunction<WriteableDocument<D> and { forks: string[]; }, Error, { versionId: string; value: Omit<...>; }, unknown>; reset: () => void; status: "pending" or ... 2 more ... or "idle"; }

Parameters:

• opts.docType: Document type to update.
• opts.projectId: Public ID of project document belongs to.

useDeleteDocument

Delete a document within a project.

Function	Type
useDeleteDocument	<D extends WriteableDocumentType>({ docType, projectId, }: { docType: D; projectId: string; }) => { mutate: UseMutateFunction<WriteableDocument<D> and { forks: string[]; }, Error, { docId: string; }, unknown>; reset: () => void; status: "pending" or ... 2 more ... or "idle"; }

Parameters:

• opts.docType: Document type to delete.
• opts.projectId: Public ID of project document belongs to.

useAcceptInvite

Accept an invite that has been received.

Function	Type
useAcceptInvite	() => { mutate: UseMutateFunction<string, Error, { inviteId: string; }, unknown>; reset: () => void; status: "pending" or "error" or "success" or "idle"; }

useRejectInvite

Reject an invite that has been received.

Function	Type
useRejectInvite	() => { mutate: UseMutateFunction<void, Error, { inviteId: string; }, unknown>; reset: () => void; status: "pending" or "error" or "success" or "idle"; }

useSendInvite

Send an invite for a project.

Function	Type
useSendInvite	({ projectId }: { projectId: string; }) => { mutate: UseMutateFunction<"ACCEPT" or "REJECT" or "ALREADY", Error, { deviceId: string; roleDescription?: string or undefined; roleId: "f7c150f5a3a9a855" or "012fd2d431c0bf60" or "9e6d29263cba36c9"; roleName?: string or undefined; }, unknown>; reset: () => void; status: "pendin...

Parameters:

• opts.projectId: Public ID of project to send the invite on behalf of.

useRequestCancelInvite

Request a cancellation of an invite sent to another device.

Function	Type
useRequestCancelInvite	({ projectId }: { projectId: string; }) => { mutate: UseMutateFunction<void, Error, { deviceId: string; }, unknown>; reset: () => void; status: "pending" or "error" or "success" or "idle"; }

Parameters:

• opts.projectId: Public ID of project to request the invite cancellation for.

useMapStyleUrl

Get a URL that points to a StyleJSON resource served by the embedded HTTP server.

If opts.refreshToken is specified, it will be appended to the returned URL as a search param. This is useful for forcing cache busting due to hidden internal details by consuming components (e.g. map component from MapLibre).

Function	Type
useMapStyleUrl	({ refreshToken, }?: { refreshToken?: string or undefined; }) => { data: string; error: Error or null; isRefetching: boolean; }

Parameters:

• opts.refreshToken: String to append to the returned value as a search param

Examples:

function ExampleWithoutRefreshToken() {
  const { data, isRefetching } = useMapStyleUrl()

  console.log(data) // logs something like 'http://localhost:...'
}

function ExampleWithRefreshToken() {
  const [refreshToken] = useState('foo')
  const { data } = useMapStyleUrl({ refreshToken })

  console.log(data) // logs something like 'http://localhost:...?refresh_token=foo'
}

Constants

• ClientApiContext

ClientApiContext

Constant	Type
ClientApiContext	Context<MapeoClientApi or null>