@comapeo/core-react 1.0.1 → 2.0.0

package/dist/commonjs/contexts/ClientApi.d.ts

@@ -0,0 +1,14 @@
+import type { MapeoClientApi } from '@comapeo/ipc' with { 'resolution-mode': 'import' };
+import { type ReactNode } from 'react';
+export declare const ClientApiContext: import("react").Context<import("@comapeo/ipc/dist/client.js", { with: { "resolution-mode": "import" } }).MapeoClientApi | null>;
+/**
+ * Create a context provider that holds a CoMapeo API client instance.
+ *
+ * @param 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.js", { with: { "resolution-mode": "import" } }).MapeoClientApi | null>>;

package/dist/commonjs/contexts/ClientApi.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientApiContext = void 0;
+exports.ClientApiProvider = ClientApiProvider;
+const react_1 = require("react");
+exports.ClientApiContext = (0, react_1.createContext)(null);
+/**
+ * Create a context provider that holds a CoMapeo API client instance.
+ *
+ * @param opts
+ * @param {ReactNode} opts.children React children node
+ * @param {MapeoClientApi} opts.clientApi Client API instance
+ */
+function ClientApiProvider({ children, clientApi, }) {
+    return (0, react_1.createElement)(exports.ClientApiContext.Provider, { value: clientApi }, children);
+}

package/dist/commonjs/hooks/client.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Access a client API instance. If a ClientApiContext provider is not
+ * set up, it will throw an error.
+ *
+ * @returns 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.js", { with: { "resolution-mode": "import" } }).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.js", { with: { "resolution-mode": "import" } }).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;
+};
+/**
+ * Update the device info for the current device.
+ */
+export declare function useSetOwnDeviceInfo(): {
+    mutate: import("@tanstack/react-query").UseMutateFunction<void, Error, {
+        name: string;
+        deviceType: import("@comapeo/schema", { with: { "resolution-mode": "import" } }).DeviceInfo["deviceType"];
+    }, unknown>;
+    reset: () => void;
+    status: "pending" | "error" | "success" | "idle";
+};
+/**
+ * Set or unset the current device as an archive device.
+ */
+export declare function useSetIsArchiveDevice(): {
+    mutate: import("@tanstack/react-query").UseMutateFunction<void, Error, {
+        isArchiveDevice: boolean;
+    }, unknown>;
+    reset: () => void;
+    status: "pending" | "error" | "success" | "idle";
+};

package/dist/commonjs/hooks/client.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useClientApi = useClientApi;
+exports.useOwnDeviceInfo = useOwnDeviceInfo;
+exports.useIsArchiveDevice = useIsArchiveDevice;
+exports.useSetOwnDeviceInfo = useSetOwnDeviceInfo;
+exports.useSetIsArchiveDevice = useSetIsArchiveDevice;
+const react_query_1 = require("@tanstack/react-query");
+const react_1 = require("react");
+const ClientApi_js_1 = require("../contexts/ClientApi.js");
+const client_js_1 = require("../lib/react-query/client.js");
+/**
+ * Access a client API instance. If a ClientApiContext provider is not
+ * set up, it will throw an error.
+ *
+ * @returns 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.
+ * }
+ * ```
+ *
+ */
+function useClientApi() {
+    const clientApi = (0, react_1.useContext)(ClientApi_js_1.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()
+ * }
+ * ```
+ */
+function useOwnDeviceInfo() {
+    const clientApi = useClientApi();
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)((0, client_js_1.deviceInfoQueryOptions)({ clientApi }));
+    return { data, error, isRefetching };
+}
+/**
+ * Retrieve whether the current device is an archive device or not.
+ *
+ * @example
+ * ```tsx
+ * function IsArchiveDeviceExample() {
+ *   const { data } = useIsArchiveDevice()
+ * }
+ * ```
+ */
+function useIsArchiveDevice() {
+    const clientApi = useClientApi();
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)((0, client_js_1.isArchiveDeviceQueryOptions)({ clientApi }));
+    return { data, error, isRefetching };
+}
+/**
+ * Update the device info for the current device.
+ */
+function useSetOwnDeviceInfo() {
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const clientApi = useClientApi();
+    const { mutate, status, reset } = (0, react_query_1.useMutation)((0, client_js_1.setOwnDeviceInfoMutationOptions)({ clientApi, queryClient }));
+    return { mutate, reset, status };
+}
+/**
+ * Set or unset the current device as an archive device.
+ */
+function useSetIsArchiveDevice() {
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const clientApi = useClientApi();
+    const { mutate, status, reset } = (0, react_query_1.useMutation)((0, client_js_1.setIsArchiveDeviceMutationOptions)({ clientApi, queryClient }));
+    return { mutate, reset, status };
+}

package/dist/{hooks → commonjs/hooks}/documents.d.ts

@@ -1,5 +1,5 @@
-import type { MapeoDoc } from '@comapeo/schema';
-import { type DocumentType } from '../lib/react-query/documents';
+import type { MapeoDoc } from '@comapeo/schema' with { 'resolution-mode': 'import' };
+import { type WriteableDocumentType } from '../lib/react-query/documents.js';
 type ReadHookResult<D> = {
     data: D;
     error: Error | null;
@@ -28,7 +28,7 @@ type ReadHookResult<D> = {
  * }
  * ```
  */
-export declare function useSingleDocByDocId<D extends DocumentType>({ projectId, docType, docId, lang, }: {
+export declare function useSingleDocByDocId<D extends WriteableDocumentType>({ projectId, docType, docId, lang, }: {
     projectId: string;
     docType: D;
     docId: string;
@@ -59,7 +59,7 @@ export declare function useSingleDocByDocId<D extends DocumentType>({ projectId,
  * }
  * ```
  */
-export declare function useSingleDocByVersionId<D extends DocumentType>({ projectId, docType, versionId, lang, }: {
+export declare function useSingleDocByVersionId<D extends WriteableDocumentType>({ projectId, docType, versionId, lang, }: {
     projectId: string;
     docType: D;
     versionId: string;
@@ -101,7 +101,7 @@ export declare function useSingleDocByVersionId<D extends DocumentType>({ projec
  * }
  * ```
  */
-export declare function useManyDocs<D extends DocumentType>({ projectId, docType, includeDeleted, lang, }: {
+export declare function useManyDocs<D extends WriteableDocumentType>({ projectId, docType, includeDeleted, lang, }: {
     projectId: string;
     docType: D;
     includeDeleted?: boolean;
@@ -109,4 +109,59 @@ export declare function useManyDocs<D extends DocumentType>({ projectId, docType
 }): ReadHookResult<Extract<MapeoDoc, {
     schemaName: D;
 }>>;
+/**
+ * Create a document for a project.
+ *
+ * @param opts.docType Document type to create.
+ * @param opts.projectId Public ID of project to create document for.
+ */
+export declare function useCreateDocument<D extends WriteableDocumentType>({ docType, projectId, }: {
+    docType: D;
+    projectId: string;
+}): {
+    mutate: import("@tanstack/react-query").UseMutateFunction<import("../lib/react-query/documents.js").WriteableDocument<D> & {
+        forks: Array<string>;
+    }, Error, {
+        value: Omit<import("../lib/react-query/documents.js").WriteableValue<D>, "schemaName">;
+    }, unknown>;
+    reset: () => void;
+    status: "pending" | "error" | "success" | "idle";
+};
+/**
+ * Update a document within a project.
+ *
+ * @param opts.docType Document type to update.
+ * @param opts.projectId Public ID of project document belongs to.
+ */
+export declare function useUpdateDocument<D extends WriteableDocumentType>({ docType, projectId, }: {
+    docType: D;
+    projectId: string;
+}): {
+    mutate: import("@tanstack/react-query").UseMutateFunction<import("../lib/react-query/documents.js").WriteableDocument<D> & {
+        forks: Array<string>;
+    }, Error, {
+        versionId: string;
+        value: Omit<import("../lib/react-query/documents.js").WriteableValue<D>, "schemaName">;
+    }, unknown>;
+    reset: () => void;
+    status: "pending" | "error" | "success" | "idle";
+};
+/**
+ * Delete a document within a project.
+ *
+ * @param opts.docType Document type to delete.
+ * @param opts.projectId Public ID of project document belongs to.
+ */
+export declare function useDeleteDocument<D extends WriteableDocumentType>({ docType, projectId, }: {
+    docType: D;
+    projectId: string;
+}): {
+    mutate: import("@tanstack/react-query").UseMutateFunction<import("../lib/react-query/documents.js").WriteableDocument<D> & {
+        forks: Array<string>;
+    }, Error, {
+        docId: string;
+    }, unknown>;
+    reset: () => void;
+    status: "pending" | "error" | "success" | "idle";
+};
 export {};

package/dist/commonjs/hooks/documents.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSingleDocByDocId = useSingleDocByDocId;
+exports.useSingleDocByVersionId = useSingleDocByVersionId;
+exports.useManyDocs = useManyDocs;
+exports.useCreateDocument = useCreateDocument;
+exports.useUpdateDocument = useUpdateDocument;
+exports.useDeleteDocument = useDeleteDocument;
+const react_query_1 = require("@tanstack/react-query");
+const documents_js_1 = require("../lib/react-query/documents.js");
+const projects_js_1 = require("./projects.js");
+/**
+ * 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 opts.projectId Project public ID
+ * @param opts.docType Document type of interest
+ * @param opts.docId Document ID
+ * @param 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'
+ * }
+ * ```
+ */
+function useSingleDocByDocId({ projectId, docType, docId, lang, }) {
+    const { data: projectApi } = (0, projects_js_1.useSingleProject)({ projectId });
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)((0, documents_js_1.documentByDocumentIdQueryOptions)({
+        projectApi,
+        projectId,
+        docType,
+        docId,
+        lang,
+    }));
+    return {
+        // @ts-expect-error - TS does not handle dependent types, so this will not
+        // be narrowed properly within the function body. See for example
+        // https://github.com/microsoft/TypeScript/issues/33014#event-15134418011
+        data,
+        error,
+        isRefetching,
+    };
+}
+/**
+ * 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 opts.projectId Project public ID
+ * @param opts.docType Document type of interest
+ * @param opts.versionId Document's version ID
+ * @param 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'
+ * }
+ * ```
+ */
+function useSingleDocByVersionId({ projectId, docType, versionId, lang, }) {
+    const { data: projectApi } = (0, projects_js_1.useSingleProject)({ projectId });
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)((0, documents_js_1.documentByVersionIdQueryOptions)({
+        projectApi,
+        projectId,
+        docType,
+        versionId,
+        lang,
+    }));
+    return {
+        // @ts-expect-error - TS does not handle dependent types, see above
+        data,
+        error,
+        isRefetching,
+    };
+}
+/**
+ * Retrieve all documents of a specific `docType`.
+ *
+ * @param opts.projectId Project public ID
+ * @param opts.docType Document type of interest
+ * @param opts.includeDeleted Include documents that have been marked as deleted
+ * @param 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',
+ *   })
+ * }
+ * ```
+ */
+function useManyDocs({ projectId, docType, includeDeleted, lang, }) {
+    const { data: projectApi } = (0, projects_js_1.useSingleProject)({ projectId });
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)((0, documents_js_1.documentsQueryOptions)({
+        projectApi,
+        projectId,
+        docType,
+        includeDeleted,
+        lang,
+    }));
+    return {
+        // @ts-expect-error - TS does not handle dependent types, see above
+        data,
+        error,
+        isRefetching,
+    };
+}
+/**
+ * Create a document for a project.
+ *
+ * @param opts.docType Document type to create.
+ * @param opts.projectId Public ID of project to create document for.
+ */
+function useCreateDocument({ docType, projectId, }) {
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const { data: projectApi } = (0, projects_js_1.useSingleProject)({ projectId });
+    const { mutate, reset, status } = (0, react_query_1.useMutation)((0, documents_js_1.createDocumentMutationOptions)({
+        docType,
+        projectApi,
+        projectId,
+        queryClient,
+    }));
+    return { mutate, reset, status };
+}
+/**
+ * Update a document within a project.
+ *
+ * @param opts.docType Document type to update.
+ * @param opts.projectId Public ID of project document belongs to.
+ */
+function useUpdateDocument({ docType, projectId, }) {
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const { data: projectApi } = (0, projects_js_1.useSingleProject)({ projectId });
+    const { mutate, reset, status } = (0, react_query_1.useMutation)((0, documents_js_1.updateDocumentMutationOptions)({
+        docType,
+        projectApi,
+        projectId,
+        queryClient,
+    }));
+    return { mutate, reset, status };
+}
+/**
+ * Delete a document within a project.
+ *
+ * @param opts.docType Document type to delete.
+ * @param opts.projectId Public ID of project document belongs to.
+ */
+function useDeleteDocument({ docType, projectId, }) {
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const { data: projectApi } = (0, projects_js_1.useSingleProject)({ projectId });
+    const { mutate, reset, status } = (0, react_query_1.useMutation)((0, documents_js_1.deleteDocumentMutationOptions)({
+        docType,
+        projectApi,
+        projectId,
+        queryClient,
+    }));
+    return { mutate, reset, status };
+}

package/dist/commonjs/hooks/invites.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Accept an invite that has been received.
+ */
+export declare function useAcceptInvite(): {
+    mutate: import("@tanstack/react-query").UseMutateFunction<string, Error, {
+        inviteId: string;
+    }, unknown>;
+    reset: () => void;
+    status: "pending" | "error" | "success" | "idle";
+};
+/**
+ * Reject an invite that has been received.
+ */
+export declare function useRejectInvite(): {
+    mutate: import("@tanstack/react-query").UseMutateFunction<void, Error, {
+        inviteId: string;
+    }, unknown>;
+    reset: () => void;
+    status: "pending" | "error" | "success" | "idle";
+};
+/**
+ * Send an invite for a project.
+ *
+ * @param opts.projectId Public ID of project to send the invite on behalf of.
+ */
+export declare function useSendInvite({ projectId }: {
+    projectId: string;
+}): {
+    mutate: import("@tanstack/react-query").UseMutateFunction<"ACCEPT" | "REJECT" | "ALREADY", Error, {
+        deviceId: string;
+        roleDescription?: string;
+        roleId: import("@comapeo/core/dist/roles.js", { with: { "resolution-mode": "import" } }).RoleIdForNewInvite;
+        roleName?: string;
+    }, unknown>;
+    reset: () => void;
+    status: "pending" | "error" | "success" | "idle";
+};
+/**
+ * Request a cancellation of an invite sent to another device.
+ *
+ * @param opts.projectId Public ID of project to request the invite cancellation for.
+ */
+export declare function useRequestCancelInvite({ projectId }: {
+    projectId: string;
+}): {
+    mutate: import("@tanstack/react-query").UseMutateFunction<void, Error, {
+        deviceId: string;
+    }, unknown>;
+    reset: () => void;
+    status: "pending" | "error" | "success" | "idle";
+};

package/dist/commonjs/hooks/invites.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useAcceptInvite = useAcceptInvite;
+exports.useRejectInvite = useRejectInvite;
+exports.useSendInvite = useSendInvite;
+exports.useRequestCancelInvite = useRequestCancelInvite;
+const react_query_1 = require("@tanstack/react-query");
+const invites_js_1 = require("../lib/react-query/invites.js");
+const client_js_1 = require("./client.js");
+const projects_js_1 = require("./projects.js");
+/**
+ * Accept an invite that has been received.
+ */
+function useAcceptInvite() {
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const clientApi = (0, client_js_1.useClientApi)();
+    const { mutate, status, reset } = (0, react_query_1.useMutation)((0, invites_js_1.acceptInviteMutationOptions)({ clientApi, queryClient }));
+    return { mutate, reset, status };
+}
+/**
+ * Reject an invite that has been received.
+ */
+function useRejectInvite() {
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const clientApi = (0, client_js_1.useClientApi)();
+    const { mutate, status, reset } = (0, react_query_1.useMutation)((0, invites_js_1.rejectInviteMutationOptions)({ clientApi, queryClient }));
+    return { mutate, reset, status };
+}
+/**
+ * Send an invite for a project.
+ *
+ * @param opts.projectId Public ID of project to send the invite on behalf of.
+ */
+function useSendInvite({ projectId }) {
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const { data: projectApi } = (0, projects_js_1.useSingleProject)({ projectId });
+    const { mutate, status, reset } = (0, react_query_1.useMutation)((0, invites_js_1.sendInviteMutationOptions)({ projectApi, projectId, queryClient }));
+    return { mutate, reset, status };
+}
+/**
+ * Request a cancellation of an invite sent to another device.
+ *
+ * @param opts.projectId Public ID of project to request the invite cancellation for.
+ */
+function useRequestCancelInvite({ projectId }) {
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const { data: projectApi } = (0, projects_js_1.useSingleProject)({ projectId });
+    const { mutate, status, reset } = (0, react_query_1.useMutation)((0, invites_js_1.requestCancelInviteMutationOptions)({ projectApi, queryClient }));
+    return { mutate, reset, status };
+}

package/dist/commonjs/hooks/maps.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useMapStyleUrl = useMapStyleUrl;
+const react_query_1 = require("@tanstack/react-query");
+const maps_js_1 = require("../lib/react-query/maps.js");
+const client_js_1 = require("./client.js");
+/**
+ * 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 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'
+ * }
+ * ```
+ */
+function useMapStyleUrl({ refreshToken, } = {}) {
+    const clientApi = (0, client_js_1.useClientApi)();
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)((0, maps_js_1.mapStyleJsonUrlQueryOptions)({ clientApi, refreshToken }));
+    return { data, error, isRefetching };
+}