@comapeo/core-react 0.1.0

package/dist/hooks/documents.js

@@ -0,0 +1,124 @@
+import { useSuspenseQuery } from '@tanstack/react-query';
+import { documentByDocumentIdQueryOptions, documentByVersionIdQueryOptions, documentsQueryOptions, } from '../lib/react-query/documents';
+import { useSingleProject } from './projects';
+// TODO: Return type is not narrowed properly by `docType`
+/**
+ * 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
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectId Project public ID
+ * @param {DocumentType} opts.docType Document type of interest
+ * @param {string} opts.docId Document ID
+ * @param {Object} [opts.opts]
+ * @param {string} [opts.opts.lang] Language to translate the document into
+ *
+ * @example
+ * ```tsx
+ * function SingleDocumentByDocIdExample() {
+ *   const { data } = useSingleDocByDocId({
+ *     projectId: '...',
+ *     docType: 'observation',
+ *     docId: '...',
+ *   })
+ *
+ *   console.log(data.schemaName) // logs 'observation'
+ * }
+ * ```
+ */
+export function useSingleDocByDocId({ projectId, docType, docId, opts, }) {
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { data, error, isRefetching } = useSuspenseQuery(documentByDocumentIdQueryOptions({
+        projectApi,
+        projectId,
+        docType,
+        docId,
+        opts,
+    }));
+    return { data, error, isRefetching };
+}
+// TODO: Return type is not narrowed properly by `docType`
+/**
+ * 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.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectId Project public ID
+ * @param {DocumentType} opts.docType Document type of interest
+ * @param {string} opts.versionId Document's version ID
+ * @param {Object} [opts.opts]
+ * @param {string} [opts.opts.lang] Language to translate the document into
+ *
+ *  * @example
+ * ```tsx
+ * function SingleDocumentByVersionIdExample() {
+ *   const { data } = useSingleDocByVersionId({
+ *     projectId: '...',
+ *     docType: 'observation',
+ *     docId: '...',
+ *   })
+ *
+ *   console.log(data.schemaName) // logs 'observation'
+ * }
+ * ```
+ */
+export function useSingleDocByVersionId({ projectId, docType, versionId, opts, }) {
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { data, error, isRefetching } = useSuspenseQuery(documentByVersionIdQueryOptions({
+        projectApi,
+        projectId,
+        docType,
+        versionId,
+        opts,
+    }));
+    return { data, error, isRefetching };
+}
+// TODO: Return type is not narrowed properly by `docType`
+/**
+ * Retrieve all documents of a specific `docType`.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectId Project public ID
+ * @param {DocumentType} opts.docType Document type of interest
+ * @param {Object} [opts.opts]
+ * @param {boolean} [opts.opts.includeDeleted] Include documents that have been marked as deleted
+ * @param {string} [opts.opts.lang] Language to translate the documents into
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useManyDocs({
+ *     projectId: '...',
+ *     docType: 'observations',
+ *   })
+ * }
+ * ```
+ *
+ * ```tsx
+ * function useAllObservations(opts) {
+ *   return useManyDocs({
+ *     ...opts,
+ *     docType: 'observations',
+ *   })
+ * }
+ *
+ * function useAllPresets(opts) {
+ *   return useManyDocs({
+ *     ...opts,
+ *     docType: 'presets',
+ *   })
+ * }
+ * ```
+ */
+export function useManyDocs({ projectId, docType, opts, }) {
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { data, error, isRefetching } = useSuspenseQuery(documentsQueryOptions({
+        projectApi,
+        projectId,
+        docType,
+        opts,
+    }));
+    return { data, error, isRefetching };
+}

package/dist/hooks/maps.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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).
+ *
+ * @param {Object} opts
+ * @param {string} opts.refreshToken String to append to the returned value as a search param
+ *
+ * @example
+ * ```tsx
+ * function ExampleWithoutRefreshToken() {
+ *   const { data, isRefetching } = useMapStyleUrl()
+ *
+ *   console.log(data) // logs something like 'http://localhost:...'
+ * }
+ * ```
+ *
+ * ```tsx
+ * function ExampleWithRefreshToken() {
+ *   const [refreshToken] = useState('foo')
+ *   const { data } = useMapStyleUrl({ refreshToken })
+ *
+ *   console.log(data) // logs something like 'http://localhost:...?refresh_token=foo'
+ * }
+ * ```
+ */
+export declare function useMapStyleUrl({ refreshToken, }?: {
+    refreshToken?: string;
+}): {
+    data: string;
+    error: Error | null;
+    isRefetching: boolean;
+};

package/dist/hooks/maps.js

@@ -0,0 +1,35 @@
+import { useSuspenseQuery } from '@tanstack/react-query';
+import { mapStyleJsonUrlQueryOptions } from '../lib/react-query/maps';
+import { useClientApi } from './client';
+/**
+ * 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).
+ *
+ * @param {Object} opts
+ * @param {string} opts.refreshToken String to append to the returned value as a search param
+ *
+ * @example
+ * ```tsx
+ * function ExampleWithoutRefreshToken() {
+ *   const { data, isRefetching } = useMapStyleUrl()
+ *
+ *   console.log(data) // logs something like 'http://localhost:...'
+ * }
+ * ```
+ *
+ * ```tsx
+ * function ExampleWithRefreshToken() {
+ *   const [refreshToken] = useState('foo')
+ *   const { data } = useMapStyleUrl({ refreshToken })
+ *
+ *   console.log(data) // logs something like 'http://localhost:...?refresh_token=foo'
+ * }
+ * ```
+ */
+export function useMapStyleUrl({ refreshToken, } = {}) {
+    const clientApi = useClientApi();
+    const { data, error, isRefetching } = useSuspenseQuery(mapStyleJsonUrlQueryOptions({ clientApi, refreshToken }));
+    return { data, error, isRefetching };
+}

package/dist/hooks/projects.d.ts

@@ -0,0 +1,261 @@
+import type { BlobId } from '@comapeo/core/dist/types';
+import { iconUrlQueryOptions } from '../lib/react-query/projects';
+/**
+ * Retrieve the project settings for a project.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectId Project public ID
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useProjectSettings({ projectId: '...' })
+ *
+ *   console.log(data.name)
+ * }
+ * ```
+ */
+export declare function useProjectSettings({ projectId }: {
+    projectId: string;
+}): {
+    data: import("@comapeo/core/dist/mapeo-project").EditableProjectSettings;
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * 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.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectId Project public ID
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useSingleProject({ projectId: '...' })
+ * }
+ * ```
+ */
+export declare function useSingleProject({ projectId }: {
+    projectId: string;
+}): {
+    data: import("rpc-reflector/lib/types").ClientApi<import("@comapeo/core/dist/mapeo-project").MapeoProject>;
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * Retrieve project information for each project that exists.
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useManyProjects()
+ *
+ *   console.log(data.map(project => project.name))
+ * }
+ * ```
+ */
+export declare function useManyProjects(): {
+    data: (Pick<{
+        schemaName: "projectSettings";
+        name?: string | undefined;
+        defaultPresets?: {
+            point: string[];
+            area: string[];
+            vertex: string[];
+            line: string[];
+            relation: string[];
+        } | undefined;
+        configMetadata?: {
+            name: string;
+            buildDate: string;
+            importDate: string;
+            fileVersion: string;
+        } | undefined;
+    }, "name"> & {
+        projectId: string;
+        createdAt?: string | undefined;
+        updatedAt?: string | undefined;
+    })[];
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * Retrieve a single member of a project.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectId Project public ID
+ * @param {deviceId} opts.projectId Device ID of interest
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useSingleMember({ projectId: '...', deviceId: '...' })
+ *
+ *   console.log(data.role)
+ * }
+ * ```
+ */
+export declare function useSingleMember({ projectId, deviceId, }: {
+    projectId: string;
+    deviceId: string;
+}): {
+    data: import("@comapeo/core/dist/member-api").MemberInfo;
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * Retrieve all members of a project.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectId Project public ID
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useManyMembers({ projectId: '...' })
+ *
+ *   console.log(data.role)
+ * }
+ * ```
+ */
+export declare function useManyMembers({ projectId }: {
+    projectId: string;
+}): {
+    data: import("@comapeo/core/dist/member-api").MemberInfo[];
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * Retrieve a URL that points to icon resources served by the embedded HTTP server.
+ *
+ * _TODO: Explain bitmap opts vs svg opts_
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectId Project public ID
+ * @param {string} opts.iconId Icon ID of interest
+ * @param {BitmapOpts | SvgOpts} opts.opts Parameters related to the mime type of the icon of interest
+ *
+ * @example
+ * ```tsx
+ * function PngExample() {
+ *   const { data } = useIconUrl({
+ *     projectId: '...',
+ *     iconId: '...',
+ *     opts: {
+ *       mimeType: 'image/png',
+ *       pixelDensity: 1,
+ *       size: 'medium'
+ *     }
+ *   })
+ * }
+ * ```
+ *
+ * ```tsx
+ * function SvgExample() {
+ *   const { data } = useIconUrl({
+ *     projectId: '...',
+ *     iconId: '...',
+ *     opts: {
+ *       mimeType: 'image/svg',
+ *       size: 'medium'
+ *     }
+ *   })
+ * }
+ * ```
+ */
+export declare function useIconUrl({ projectId, iconId, opts, }: {
+    projectId: string;
+    iconId: string;
+    opts: Parameters<typeof iconUrlQueryOptions>[0]['opts'];
+}): {
+    data: string;
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * Retrieve a URL that points to a desired blob resource.
+ *
+ * _TODO: Explain BlobId in more depth_
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectId Project public Id
+ * @param {BlobId} opts.blobId Blob ID of the desired resource
+ *
+ * @example
+ * ```tsx
+ * function PhotoExample() {
+ *   const { data } = useAttachmentUrl({
+ *     projectId: '...',
+ *     blobId: {
+ *       type: 'photo',
+ *       variant: 'thumbnail',
+ *       name: '...',
+ *       driveId: '...',
+ *     }
+ *   })
+ * }
+ * ```
+ *
+ * ```tsx
+ * function AudioExample() {
+ *   const { data } = useAttachmentUrl({
+ *     projectId: '...',
+ *     blobId: {
+ *       type: 'audio',
+ *       variant: 'original',
+ *       name: '...',
+ *       driveId: '...',
+ *     }
+ *   })
+ * }
+ * ```
+ *
+ * ```tsx
+ * function VideoExample() {
+ *   const { data } = useAttachmentUrl({
+ *     projectId: '...',
+ *     blobId: {
+ *       type: 'video',
+ *       variant: 'original',
+ *       name: '...',
+ *       driveId: '...',
+ *     }
+ *   })
+ * }
+ * ```
+ */
+export declare function useAttachmentUrl({ projectId, blobId, }: {
+    projectId: string;
+    blobId: BlobId;
+}): {
+    data: string;
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * Retrieve the device ID that created a document.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectId Project public ID
+ * @param {string} opts.originalVersionId Version ID of document
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useDocumentCreatedBy({
+ *     projectId: '...',
+ *     originalVersionId: '...',
+ *   })
+ * }
+ * ```
+ */
+export declare function useDocumentCreatedBy({ projectId, originalVersionId, }: {
+    projectId: string;
+    originalVersionId: string;
+}): {
+    data: string;
+    error: Error | null;
+    isRefetching: boolean;
+};

package/dist/hooks/projects.js

@@ -0,0 +1,257 @@
+import { useSuspenseQuery } from '@tanstack/react-query';
+import { attachmentUrlQueryOptions, documentCreatedByQueryOptions, iconUrlQueryOptions, projectByIdQueryOptions, projectMemberByIdQueryOptions, projectMembersQueryOptions, projectSettingsQueryOptions, projectsQueryOptions, } from '../lib/react-query/projects';
+import { useClientApi } from './client';
+/**
+ * Retrieve the project settings for a project.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectId Project public ID
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useProjectSettings({ projectId: '...' })
+ *
+ *   console.log(data.name)
+ * }
+ * ```
+ */
+export function useProjectSettings({ projectId }) {
+    const clientApi = useClientApi();
+    const { data: projectApi } = useSuspenseQuery(projectByIdQueryOptions({
+        projectId,
+        clientApi,
+    }));
+    const { data, error, isRefetching } = useSuspenseQuery(projectSettingsQueryOptions({
+        projectApi,
+        projectId,
+    }));
+    return { data, error, isRefetching };
+}
+/**
+ * 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.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectId Project public ID
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useSingleProject({ projectId: '...' })
+ * }
+ * ```
+ */
+export function useSingleProject({ projectId }) {
+    const clientApi = useClientApi();
+    const { data, error, isRefetching } = useSuspenseQuery({
+        ...projectByIdQueryOptions({
+            clientApi,
+            projectId,
+        }),
+        // Keep project instances around indefinitely - shouldn't be a memory
+        // problem because these are only lightweight proxy objects, and project
+        // references are kept indefinitely on the backend anyway once they are
+        // accessed
+        staleTime: Infinity,
+        gcTime: Infinity,
+    });
+    return { data, error, isRefetching };
+}
+/**
+ * Retrieve project information for each project that exists.
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useManyProjects()
+ *
+ *   console.log(data.map(project => project.name))
+ * }
+ * ```
+ */
+export function useManyProjects() {
+    const clientApi = useClientApi();
+    const { data, error, isRefetching } = useSuspenseQuery(projectsQueryOptions({
+        clientApi,
+    }));
+    return { data, error, isRefetching };
+}
+/**
+ * Retrieve a single member of a project.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectId Project public ID
+ * @param {deviceId} opts.projectId Device ID of interest
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useSingleMember({ projectId: '...', deviceId: '...' })
+ *
+ *   console.log(data.role)
+ * }
+ * ```
+ */
+export function useSingleMember({ projectId, deviceId, }) {
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { data, error, isRefetching } = useSuspenseQuery(projectMemberByIdQueryOptions({
+        projectApi,
+        projectId,
+        deviceId,
+    }));
+    return { data, error, isRefetching };
+}
+/**
+ * Retrieve all members of a project.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectId Project public ID
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useManyMembers({ projectId: '...' })
+ *
+ *   console.log(data.role)
+ * }
+ * ```
+ */
+export function useManyMembers({ projectId }) {
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { data, error, isRefetching } = useSuspenseQuery(projectMembersQueryOptions({ projectApi, projectId }));
+    return { data, error, isRefetching };
+}
+/**
+ * Retrieve a URL that points to icon resources served by the embedded HTTP server.
+ *
+ * _TODO: Explain bitmap opts vs svg opts_
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectId Project public ID
+ * @param {string} opts.iconId Icon ID of interest
+ * @param {BitmapOpts | SvgOpts} opts.opts Parameters related to the mime type of the icon of interest
+ *
+ * @example
+ * ```tsx
+ * function PngExample() {
+ *   const { data } = useIconUrl({
+ *     projectId: '...',
+ *     iconId: '...',
+ *     opts: {
+ *       mimeType: 'image/png',
+ *       pixelDensity: 1,
+ *       size: 'medium'
+ *     }
+ *   })
+ * }
+ * ```
+ *
+ * ```tsx
+ * function SvgExample() {
+ *   const { data } = useIconUrl({
+ *     projectId: '...',
+ *     iconId: '...',
+ *     opts: {
+ *       mimeType: 'image/svg',
+ *       size: 'medium'
+ *     }
+ *   })
+ * }
+ * ```
+ */
+export function useIconUrl({ projectId, iconId, opts, }) {
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { data, error, isRefetching } = useSuspenseQuery(iconUrlQueryOptions({
+        projectApi,
+        projectId,
+        iconId,
+        opts,
+    }));
+    return { data, error, isRefetching };
+}
+/**
+ * Retrieve a URL that points to a desired blob resource.
+ *
+ * _TODO: Explain BlobId in more depth_
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectId Project public Id
+ * @param {BlobId} opts.blobId Blob ID of the desired resource
+ *
+ * @example
+ * ```tsx
+ * function PhotoExample() {
+ *   const { data } = useAttachmentUrl({
+ *     projectId: '...',
+ *     blobId: {
+ *       type: 'photo',
+ *       variant: 'thumbnail',
+ *       name: '...',
+ *       driveId: '...',
+ *     }
+ *   })
+ * }
+ * ```
+ *
+ * ```tsx
+ * function AudioExample() {
+ *   const { data } = useAttachmentUrl({
+ *     projectId: '...',
+ *     blobId: {
+ *       type: 'audio',
+ *       variant: 'original',
+ *       name: '...',
+ *       driveId: '...',
+ *     }
+ *   })
+ * }
+ * ```
+ *
+ * ```tsx
+ * function VideoExample() {
+ *   const { data } = useAttachmentUrl({
+ *     projectId: '...',
+ *     blobId: {
+ *       type: 'video',
+ *       variant: 'original',
+ *       name: '...',
+ *       driveId: '...',
+ *     }
+ *   })
+ * }
+ * ```
+ */
+export function useAttachmentUrl({ projectId, blobId, }) {
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { data, error, isRefetching } = useSuspenseQuery(attachmentUrlQueryOptions({
+        projectApi,
+        projectId,
+        blobId,
+    }));
+    return { data, error, isRefetching };
+}
+// TODO: Eventually remove in favor of this information being provided by the backend when retrieving documents
+/**
+ * Retrieve the device ID that created a document.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectId Project public ID
+ * @param {string} opts.originalVersionId Version ID of document
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useDocumentCreatedBy({
+ *     projectId: '...',
+ *     originalVersionId: '...',
+ *   })
+ * }
+ * ```
+ */
+export function useDocumentCreatedBy({ projectId, originalVersionId, }) {
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { data, error, isRefetching } = useSuspenseQuery(documentCreatedByQueryOptions({ projectApi, projectId, originalVersionId }));
+    return { data, error, isRefetching };
+}