@comapeo/core-react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
+
+## 0.1.0 (2024-12-12)
+
+### Features
+
+- initial implementation of many tanstack-query queries ([8a6aed7](https://github.com/digidem/comapeo-core-react/commit/8a6aed78f646c0f536551ac4a0423ff5d7780b33))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Digital Democracy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# @comapeo/core-react
+
+React wrapper for working with [`@comapeo/core`](https://github.com/digidem/comapeo-core)
+
+## Installation
+
+```sh
+npm install @comapeo/core-react
+```
+
+## API Documentation
+
+Still a work in progress. Currently lives in [`docs/API.md`](./docs/API.md).
+
+## Contributing
+
+See contributing docs in [`docs/CONTRIBUTING.md`](./docs/CONTRIBUTING.md)
+
+## License
+
+[MIT](./LICENSE)

package/dist/contexts/ClientApi.d.ts

@@ -0,0 +1,14 @@
+import type { MapeoClientApi } from '@comapeo/ipc';
+import { type ReactNode } from 'react';
+export declare const ClientApiContext: import("react").Context<import("@comapeo/ipc/dist/client").MapeoClientApi | null>;
+/**
+ * Create a context provider that holds a CoMapeo API client instance.
+ *
+ * @param {Object} opts
+ * @param {ReactNode} opts.children React children node
+ * @param {MapeoClientApi} opts.clientApi Client API instance
+ */
+export declare function ClientApiProvider({ children, clientApi, }: {
+    children: ReactNode;
+    clientApi: MapeoClientApi;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<import("@comapeo/ipc/dist/client").MapeoClientApi | null>>;

package/dist/contexts/ClientApi.js

@@ -0,0 +1,12 @@
+import { createContext, createElement } from 'react';
+export const ClientApiContext = createContext(null);
+/**
+ * Create a context provider that holds a CoMapeo API client instance.
+ *
+ * @param {Object} opts
+ * @param {ReactNode} opts.children React children node
+ * @param {MapeoClientApi} opts.clientApi Client API instance
+ */
+export function ClientApiProvider({ children, clientApi, }) {
+    return createElement(ClientApiContext.Provider, { value: clientApi }, children);
+}

package/dist/hooks/client.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Access a client API instance. If a ClientApiContext provider is not
+ * set up, it will throw an error.
+ *
+ * @returns {import('@comapeo/ipc').MapeoClientApi} Client API instance
+ *
+ * @example
+ * ```tsx
+ * 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.
+ * }
+ * ```
+ *
+ */
+export declare function useClientApi(): import("@comapeo/ipc/dist/client").MapeoClientApi;
+/**
+ * Retrieve info about the current device.
+ *
+ * @example
+ * ```tsx
+ * function DeviceInfoExample() {
+ *   const { data } = useDeviceInfo()
+ * }
+ * ```
+ */
+export declare function useOwnDeviceInfo(): {
+    data: {
+        deviceId: string;
+        deviceType: "device_type_unspecified" | "mobile" | "tablet" | "desktop" | "selfHostedServer" | "UNRECOGNIZED";
+    } & Partial<import("@comapeo/core/dist/schema/client").DeviceInfoParam>;
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * Retrieve whether the current device is an archive device or not.
+ *
+ * @example
+ * ```tsx
+ * function IsArchiveDeviceExample() {
+ *   const { data } = useIsArchiveDevice()
+ * }
+ * ```
+ */
+export declare function useIsArchiveDevice(): {
+    data: boolean;
+    error: Error | null;
+    isRefetching: boolean;
+};

package/dist/hooks/client.js

@@ -0,0 +1,66 @@
+import { useSuspenseQuery } from '@tanstack/react-query';
+import { useContext } from 'react';
+import { ClientApiContext } from '../contexts/ClientApi';
+import { deviceInfoQueryOptions, isArchiveDeviceQueryOptions, } from '../lib/react-query/client';
+/**
+ * Access a client API instance. If a ClientApiContext provider is not
+ * set up, it will throw an error.
+ *
+ * @returns {import('@comapeo/ipc').MapeoClientApi} Client API instance
+ *
+ * @example
+ * ```tsx
+ * 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.
+ * }
+ * ```
+ *
+ */
+export function useClientApi() {
+    const clientApi = useContext(ClientApiContext);
+    if (!clientApi) {
+        throw new Error('No client API set. Make sure you set up the ClientApiContext provider properly');
+    }
+    return clientApi;
+}
+/**
+ * Retrieve info about the current device.
+ *
+ * @example
+ * ```tsx
+ * function DeviceInfoExample() {
+ *   const { data } = useDeviceInfo()
+ * }
+ * ```
+ */
+export function useOwnDeviceInfo() {
+    const clientApi = useClientApi();
+    const { data, error, isRefetching } = useSuspenseQuery(deviceInfoQueryOptions({ clientApi }));
+    return { data, error, isRefetching };
+}
+/**
+ * Retrieve whether the current device is an archive device or not.
+ *
+ * @example
+ * ```tsx
+ * function IsArchiveDeviceExample() {
+ *   const { data } = useIsArchiveDevice()
+ * }
+ * ```
+ */
+export function useIsArchiveDevice() {
+    const clientApi = useClientApi();
+    const { data, error, isRefetching } = useSuspenseQuery(isArchiveDeviceQueryOptions({ clientApi }));
+    return { data, error, isRefetching };
+}

package/dist/hooks/documents.d.ts

@@ -0,0 +1,475 @@
+import { documentByDocumentIdQueryOptions, documentByVersionIdQueryOptions, documentsQueryOptions, type DocumentType } from '../lib/react-query/documents';
+/**
+ * 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 declare function useSingleDocByDocId<D extends DocumentType>({ projectId, docType, docId, opts, }: {
+    projectId: string;
+    docType: D;
+    docId: string;
+    opts?: Parameters<typeof documentByDocumentIdQueryOptions>[0]['opts'];
+}): {
+    data: ({
+        schemaName: "track";
+        locations: import("@comapeo/schema/dist/schema/track").Position[];
+        observationRefs: {
+            docId: string;
+            versionId: string;
+        }[];
+        tags: {
+            [k: string]: boolean | number | string | null | (boolean | number | string | null)[];
+        };
+        docId: string;
+        versionId: string;
+        originalVersionId: string;
+        createdAt: string;
+        updatedAt: string;
+        links: string[];
+        deleted: boolean;
+    } & {
+        forks: string[];
+    }) | ({
+        schemaName: "remoteDetectionAlert";
+        detectionDateStart: string;
+        detectionDateEnd: string;
+        sourceId: string;
+        metadata: {
+            [k: string]: boolean | number | string | null | (boolean | number | string | null)[];
+        };
+        geometry: import("@comapeo/schema/dist/schema/remoteDetectionAlert").Geometry;
+        docId: string;
+        versionId: string;
+        originalVersionId: string;
+        createdAt: string;
+        updatedAt: string;
+        links: string[];
+        deleted: boolean;
+    } & {
+        forks: string[];
+    }) | ({
+        schemaName: "preset";
+        name: string;
+        geometry: ("point" | "vertex" | "line" | "area" | "relation")[];
+        tags: import("@comapeo/schema/dist/schema/preset").Tags;
+        addTags: import("@comapeo/schema/dist/schema/preset").Tags1;
+        removeTags: import("@comapeo/schema/dist/schema/preset").Tags2;
+        fieldRefs: {
+            docId: string;
+            versionId: string;
+        }[];
+        iconRef?: {
+            docId: string;
+            versionId: string;
+        } | undefined;
+        terms: string[];
+        color?: string | undefined;
+        docId: string;
+        versionId: string;
+        originalVersionId: string;
+        createdAt: string;
+        updatedAt: string;
+        links: string[];
+        deleted: boolean;
+    } & {
+        forks: string[];
+    }) | ({
+        schemaName: "observation";
+        lat?: number | undefined;
+        lon?: number | undefined;
+        attachments: {
+            driveDiscoveryId: string;
+            name: string;
+            type: "attachment_type_unspecified" | "photo" | "video" | "audio" | "UNRECOGNIZED";
+            hash: string;
+        }[];
+        tags: {
+            [k: string]: boolean | number | string | null | (boolean | number | string | null)[];
+        };
+        metadata?: {
+            manualLocation?: boolean;
+            position?: import("@comapeo/schema/dist/schema/observation").Position;
+            lastSavedPosition?: import("@comapeo/schema/dist/schema/observation").Position;
+            positionProvider?: {
+                gpsAvailable?: boolean;
+                passiveAvailable?: boolean;
+                locationServicesEnabled: boolean;
+                networkAvailable?: boolean;
+            };
+        } | undefined;
+        presetRef?: {
+            docId: string;
+            versionId: string;
+        } | undefined;
+        docId: string;
+        versionId: string;
+        originalVersionId: string;
+        createdAt: string;
+        updatedAt: string;
+        links: string[];
+        deleted: boolean;
+    } & {
+        forks: string[];
+    }) | ({
+        schemaName: "field";
+        tagKey: string;
+        type: "type_unspecified" | "text" | "number" | "selectOne" | "selectMultiple" | "UNRECOGNIZED";
+        label: string;
+        appearance?: ("appearance_unspecified" | "singleline" | "multiline" | "UNRECOGNIZED") | undefined;
+        snakeCase?: boolean | undefined;
+        options?: {
+            label: string;
+            value: string | boolean | number | null;
+        }[] | undefined;
+        universal?: boolean | undefined;
+        placeholder?: string | undefined;
+        helperText?: string | undefined;
+        docId: string;
+        versionId: string;
+        originalVersionId: string;
+        createdAt: string;
+        updatedAt: string;
+        links: string[];
+        deleted: boolean;
+    } & {
+        forks: string[];
+    });
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * 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 declare function useSingleDocByVersionId<D extends DocumentType>({ projectId, docType, versionId, opts, }: {
+    projectId: string;
+    docType: D;
+    versionId: string;
+    opts?: Parameters<typeof documentByVersionIdQueryOptions>[0]['opts'];
+}): {
+    data: {
+        schemaName: "track";
+        locations: import("@comapeo/schema/dist/schema/track").Position[];
+        observationRefs: {
+            docId: string;
+            versionId: string;
+        }[];
+        tags: {
+            [k: string]: boolean | number | string | null | (boolean | number | string | null)[];
+        };
+        docId: string;
+        versionId: string;
+        originalVersionId: string;
+        createdAt: string;
+        updatedAt: string;
+        links: string[];
+        deleted: boolean;
+    } | {
+        schemaName: "remoteDetectionAlert";
+        detectionDateStart: string;
+        detectionDateEnd: string;
+        sourceId: string;
+        metadata: {
+            [k: string]: boolean | number | string | null | (boolean | number | string | null)[];
+        };
+        geometry: import("@comapeo/schema/dist/schema/remoteDetectionAlert").Geometry;
+        docId: string;
+        versionId: string;
+        originalVersionId: string;
+        createdAt: string;
+        updatedAt: string;
+        links: string[];
+        deleted: boolean;
+    } | {
+        schemaName: "preset";
+        name: string;
+        geometry: ("point" | "vertex" | "line" | "area" | "relation")[];
+        tags: import("@comapeo/schema/dist/schema/preset").Tags;
+        addTags: import("@comapeo/schema/dist/schema/preset").Tags1;
+        removeTags: import("@comapeo/schema/dist/schema/preset").Tags2;
+        fieldRefs: {
+            docId: string;
+            versionId: string;
+        }[];
+        iconRef?: {
+            docId: string;
+            versionId: string;
+        } | undefined;
+        terms: string[];
+        color?: string | undefined;
+        docId: string;
+        versionId: string;
+        originalVersionId: string;
+        createdAt: string;
+        updatedAt: string;
+        links: string[];
+        deleted: boolean;
+    } | {
+        schemaName: "observation";
+        lat?: number | undefined;
+        lon?: number | undefined;
+        attachments: {
+            driveDiscoveryId: string;
+            name: string;
+            type: "attachment_type_unspecified" | "photo" | "video" | "audio" | "UNRECOGNIZED";
+            hash: string;
+        }[];
+        tags: {
+            [k: string]: boolean | number | string | null | (boolean | number | string | null)[];
+        };
+        metadata?: {
+            manualLocation?: boolean;
+            position?: import("@comapeo/schema/dist/schema/observation").Position;
+            lastSavedPosition?: import("@comapeo/schema/dist/schema/observation").Position;
+            positionProvider?: {
+                gpsAvailable?: boolean;
+                passiveAvailable?: boolean;
+                locationServicesEnabled: boolean;
+                networkAvailable?: boolean;
+            };
+        } | undefined;
+        presetRef?: {
+            docId: string;
+            versionId: string;
+        } | undefined;
+        docId: string;
+        versionId: string;
+        originalVersionId: string;
+        createdAt: string;
+        updatedAt: string;
+        links: string[];
+        deleted: boolean;
+    } | {
+        schemaName: "field";
+        tagKey: string;
+        type: "type_unspecified" | "text" | "number" | "selectOne" | "selectMultiple" | "UNRECOGNIZED";
+        label: string;
+        appearance?: ("appearance_unspecified" | "singleline" | "multiline" | "UNRECOGNIZED") | undefined;
+        snakeCase?: boolean | undefined;
+        options?: {
+            label: string;
+            value: string | boolean | number | null;
+        }[] | undefined;
+        universal?: boolean | undefined;
+        placeholder?: string | undefined;
+        helperText?: string | undefined;
+        docId: string;
+        versionId: string;
+        originalVersionId: string;
+        createdAt: string;
+        updatedAt: string;
+        links: string[];
+        deleted: boolean;
+    };
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * 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 declare function useManyDocs<D extends DocumentType>({ projectId, docType, opts, }: {
+    projectId: string;
+    docType: D;
+    opts?: Parameters<typeof documentsQueryOptions>[0]['opts'];
+}): {
+    data: ({
+        schemaName: "track";
+        locations: import("@comapeo/schema/dist/schema/track").Position[];
+        observationRefs: {
+            docId: string;
+            versionId: string;
+        }[];
+        tags: {
+            [k: string]: boolean | number | string | null | (boolean | number | string | null)[];
+        };
+        docId: string;
+        versionId: string;
+        originalVersionId: string;
+        createdAt: string;
+        updatedAt: string;
+        links: string[];
+        deleted: boolean;
+    } & {
+        forks: string[];
+    })[] | ({
+        schemaName: "remoteDetectionAlert";
+        detectionDateStart: string;
+        detectionDateEnd: string;
+        sourceId: string;
+        metadata: {
+            [k: string]: boolean | number | string | null | (boolean | number | string | null)[];
+        };
+        geometry: import("@comapeo/schema/dist/schema/remoteDetectionAlert").Geometry;
+        docId: string;
+        versionId: string;
+        originalVersionId: string;
+        createdAt: string;
+        updatedAt: string;
+        links: string[];
+        deleted: boolean;
+    } & {
+        forks: string[];
+    })[] | ({
+        schemaName: "preset";
+        name: string;
+        geometry: ("point" | "vertex" | "line" | "area" | "relation")[];
+        tags: import("@comapeo/schema/dist/schema/preset").Tags;
+        addTags: import("@comapeo/schema/dist/schema/preset").Tags1;
+        removeTags: import("@comapeo/schema/dist/schema/preset").Tags2;
+        fieldRefs: {
+            docId: string;
+            versionId: string;
+        }[];
+        iconRef?: {
+            docId: string;
+            versionId: string;
+        } | undefined;
+        terms: string[];
+        color?: string | undefined;
+        docId: string;
+        versionId: string;
+        originalVersionId: string;
+        createdAt: string;
+        updatedAt: string;
+        links: string[];
+        deleted: boolean;
+    } & {
+        forks: string[];
+    })[] | ({
+        schemaName: "observation";
+        lat?: number | undefined;
+        lon?: number | undefined;
+        attachments: {
+            driveDiscoveryId: string;
+            name: string;
+            type: "attachment_type_unspecified" | "photo" | "video" | "audio" | "UNRECOGNIZED";
+            hash: string;
+        }[];
+        tags: {
+            [k: string]: boolean | number | string | null | (boolean | number | string | null)[];
+        };
+        metadata?: {
+            manualLocation?: boolean;
+            position?: import("@comapeo/schema/dist/schema/observation").Position;
+            lastSavedPosition?: import("@comapeo/schema/dist/schema/observation").Position;
+            positionProvider?: {
+                gpsAvailable?: boolean;
+                passiveAvailable?: boolean;
+                locationServicesEnabled: boolean;
+                networkAvailable?: boolean;
+            };
+        } | undefined;
+        presetRef?: {
+            docId: string;
+            versionId: string;
+        } | undefined;
+        docId: string;
+        versionId: string;
+        originalVersionId: string;
+        createdAt: string;
+        updatedAt: string;
+        links: string[];
+        deleted: boolean;
+    } & {
+        forks: string[];
+    })[] | ({
+        schemaName: "field";
+        tagKey: string;
+        type: "type_unspecified" | "text" | "number" | "selectOne" | "selectMultiple" | "UNRECOGNIZED";
+        label: string;
+        appearance?: ("appearance_unspecified" | "singleline" | "multiline" | "UNRECOGNIZED") | undefined;
+        snakeCase?: boolean | undefined;
+        options?: {
+            label: string;
+            value: string | boolean | number | null;
+        }[] | undefined;
+        universal?: boolean | undefined;
+        placeholder?: string | undefined;
+        helperText?: string | undefined;
+        docId: string;
+        versionId: string;
+        originalVersionId: string;
+        createdAt: string;
+        updatedAt: string;
+        links: string[];
+        deleted: boolean;
+    } & {
+        forks: string[];
+    })[];
+    error: Error | null;
+    isRefetching: boolean;
+};