@comapeo/core-react 1.0.1 → 2.0.0

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

@@ -0,0 +1,334 @@
+import type { BitmapOpts, SvgOpts } from '@comapeo/core/dist/icon-api.js' with { 'resolution-mode': 'import' };
+import type { BlobId } from '@comapeo/core/dist/types.js' with { 'resolution-mode': 'import' };
+/**
+ * Retrieve the project settings for a project.
+ *
+ * @param 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.js", { with: { "resolution-mode": "import" } }).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 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.js").ClientApi<import("@comapeo/core/dist/mapeo-project.js", { with: { "resolution-mode": "import" } }).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 opts.projectId Project public ID
+ * @param 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.js", { with: { "resolution-mode": "import" } }).MemberInfo;
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * Retrieve all members of a project.
+ *
+ * @param 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.js", { with: { "resolution-mode": "import" } }).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 opts.projectId Project public ID
+ * @param opts.iconId Icon ID of interest
+ * @param opts.mimeType MIME type of desired resource
+ * @param opts.pixelDensity Pixel density resource (only applicable when `mimeType` is `'image/png'`)
+ * @param opts.size Size of desired resource
+ *
+ * @example
+ * ```tsx
+ * function PngExample() {
+ *   const { data } = useIconUrl({
+ *     projectId: '...',
+ *     iconId: '...',
+ *     mimeType: 'image/png',
+ *     pixelDensity: 1,
+ *     size: 'medium'
+ *   })
+ * }
+ * ```
+ *
+ * ```tsx
+ * function SvgExample() {
+ *   const { data } = useIconUrl({
+ *     projectId: '...',
+ *     iconId: '...',
+ *     mimeType: 'image/svg',
+ *     size: 'medium'
+ *   })
+ * }
+ * ```
+ */
+export declare function useIconUrl({ projectId, iconId, ...mimeBasedOpts }: {
+    projectId: string;
+    iconId: string;
+} & (BitmapOpts | SvgOpts)): {
+    data: string;
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * Retrieve a URL that points to a desired blob resource.
+ *
+ * _TODO: Explain BlobId in more depth_
+ *
+ * @param opts.projectId Project public Id
+ * @param 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 opts.projectId Project public ID
+ * @param 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;
+};
+export declare function useAddServerPeer({ projectId }: {
+    projectId: string;
+}): {
+    mutate: import("@tanstack/react-query").UseMutateFunction<void, Error, {
+        baseUrl: string;
+        dangerouslyAllowInsecureConnections?: boolean;
+    }, unknown>;
+    reset: () => void;
+    status: "pending" | "error" | "success" | "idle";
+};
+/**
+ * Create a new project.
+ */
+export declare function useCreateProject(): {
+    mutate: import("@tanstack/react-query").UseMutateFunction<string, Error, {
+        name?: string;
+        configPath?: string;
+    } | undefined, unknown>;
+    reset: () => void;
+    status: "pending" | "error" | "success" | "idle";
+};
+/**
+ * Leave an existing project.
+ */
+export declare function useLeaveProject(): {
+    mutate: import("@tanstack/react-query").UseMutateFunction<void, Error, {
+        projectId: string;
+    }, unknown>;
+    reset: () => void;
+    status: "pending" | "error" | "success" | "idle";
+};
+/**
+ * Update the configuration of a project using an external file.
+ *
+ * @param opts.projectId Public ID of the project to apply changes to.
+ */
+export declare function useImportProjectConfig({ projectId }: {
+    projectId: string;
+}): {
+    mutate: import("@tanstack/react-query").UseMutateFunction<Error[], Error, {
+        configPath: string;
+    }, unknown>;
+    reset: () => void;
+    status: "pending" | "error" | "success" | "idle";
+};
+/**
+ * Update the settings of a project.
+ *
+ * @param opts.projectId Public ID of the project to apply changes to.
+ */
+export declare function useUpdateProjectSettings({ projectId }: {
+    projectId: string;
+}): {
+    mutate: import("@tanstack/react-query").UseMutateFunction<import("@comapeo/core/dist/mapeo-project.js", { with: { "resolution-mode": "import" } }).EditableProjectSettings, Error, {
+        name?: import("@comapeo/schema", { with: { "resolution-mode": "import" } }).ProjectSettings["name"];
+        configMetadata?: import("@comapeo/schema", { with: { "resolution-mode": "import" } }).ProjectSettings["configMetadata"];
+        defaultPresets?: import("@comapeo/schema", { with: { "resolution-mode": "import" } }).ProjectSettings["defaultPresets"];
+    }, unknown>;
+    reset: () => void;
+    status: "pending" | "error" | "success" | "idle";
+};
+/**
+ * Create a blob for a project.
+ *
+ * @param opts.projectId Public project ID of project to apply to changes to.
+ */
+export declare function useCreateBlob({ projectId }: {
+    projectId: string;
+}): {
+    mutate: import("@tanstack/react-query").UseMutateFunction<{
+        driveId: string;
+        name: string;
+        type: "photo" | "video" | "audio";
+        hash: string;
+    }, Error, {
+        original: string;
+        preview?: string;
+        thumbnail?: string;
+        metadata: import("@comapeo/core/dist/blob-api.js", { with: { "resolution-mode": "import" } }).Metadata;
+    }, unknown>;
+    reset: () => void;
+    status: "pending" | "error" | "success" | "idle";
+};

package/dist/commonjs/hooks/projects.js

@@ -0,0 +1,320 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useProjectSettings = useProjectSettings;
+exports.useSingleProject = useSingleProject;
+exports.useManyProjects = useManyProjects;
+exports.useSingleMember = useSingleMember;
+exports.useManyMembers = useManyMembers;
+exports.useIconUrl = useIconUrl;
+exports.useAttachmentUrl = useAttachmentUrl;
+exports.useDocumentCreatedBy = useDocumentCreatedBy;
+exports.useAddServerPeer = useAddServerPeer;
+exports.useCreateProject = useCreateProject;
+exports.useLeaveProject = useLeaveProject;
+exports.useImportProjectConfig = useImportProjectConfig;
+exports.useUpdateProjectSettings = useUpdateProjectSettings;
+exports.useCreateBlob = useCreateBlob;
+const react_query_1 = require("@tanstack/react-query");
+const projects_js_1 = require("../lib/react-query/projects.js");
+const client_js_1 = require("./client.js");
+/**
+ * Retrieve the project settings for a project.
+ *
+ * @param opts.projectId Project public ID
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useProjectSettings({ projectId: '...' })
+ *
+ *   console.log(data.name)
+ * }
+ * ```
+ */
+function useProjectSettings({ projectId }) {
+    const clientApi = (0, client_js_1.useClientApi)();
+    const { data: projectApi } = (0, react_query_1.useSuspenseQuery)((0, projects_js_1.projectByIdQueryOptions)({
+        projectId,
+        clientApi,
+    }));
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)((0, projects_js_1.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 opts.projectId Project public ID
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useSingleProject({ projectId: '...' })
+ * }
+ * ```
+ */
+function useSingleProject({ projectId }) {
+    const clientApi = (0, client_js_1.useClientApi)();
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)({
+        ...(0, projects_js_1.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))
+ * }
+ * ```
+ */
+function useManyProjects() {
+    const clientApi = (0, client_js_1.useClientApi)();
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)((0, projects_js_1.projectsQueryOptions)({
+        clientApi,
+    }));
+    return { data, error, isRefetching };
+}
+/**
+ * Retrieve a single member of a project.
+ *
+ * @param opts.projectId Project public ID
+ * @param opts.projectId Device ID of interest
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useSingleMember({ projectId: '...', deviceId: '...' })
+ *
+ *   console.log(data.role)
+ * }
+ * ```
+ */
+function useSingleMember({ projectId, deviceId, }) {
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)((0, projects_js_1.projectMemberByIdQueryOptions)({
+        projectApi,
+        projectId,
+        deviceId,
+    }));
+    return { data, error, isRefetching };
+}
+/**
+ * Retrieve all members of a project.
+ *
+ * @param opts.projectId Project public ID
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useManyMembers({ projectId: '...' })
+ *
+ *   console.log(data.role)
+ * }
+ * ```
+ */
+function useManyMembers({ projectId }) {
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)((0, projects_js_1.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 opts.projectId Project public ID
+ * @param opts.iconId Icon ID of interest
+ * @param opts.mimeType MIME type of desired resource
+ * @param opts.pixelDensity Pixel density resource (only applicable when `mimeType` is `'image/png'`)
+ * @param opts.size Size of desired resource
+ *
+ * @example
+ * ```tsx
+ * function PngExample() {
+ *   const { data } = useIconUrl({
+ *     projectId: '...',
+ *     iconId: '...',
+ *     mimeType: 'image/png',
+ *     pixelDensity: 1,
+ *     size: 'medium'
+ *   })
+ * }
+ * ```
+ *
+ * ```tsx
+ * function SvgExample() {
+ *   const { data } = useIconUrl({
+ *     projectId: '...',
+ *     iconId: '...',
+ *     mimeType: 'image/svg',
+ *     size: 'medium'
+ *   })
+ * }
+ * ```
+ */
+function useIconUrl({ projectId, iconId, ...mimeBasedOpts }) {
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)((0, projects_js_1.iconUrlQueryOptions)({
+        ...mimeBasedOpts,
+        projectApi,
+        projectId,
+        iconId,
+    }));
+    return { data, error, isRefetching };
+}
+/**
+ * Retrieve a URL that points to a desired blob resource.
+ *
+ * _TODO: Explain BlobId in more depth_
+ *
+ * @param opts.projectId Project public Id
+ * @param 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: '...',
+ *     }
+ *   })
+ * }
+ * ```
+ */
+function useAttachmentUrl({ projectId, blobId, }) {
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)((0, projects_js_1.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 opts.projectId Project public ID
+ * @param opts.originalVersionId Version ID of document
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useDocumentCreatedBy({
+ *     projectId: '...',
+ *     originalVersionId: '...',
+ *   })
+ * }
+ * ```
+ */
+function useDocumentCreatedBy({ projectId, originalVersionId, }) {
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)((0, projects_js_1.documentCreatedByQueryOptions)({ projectApi, projectId, originalVersionId }));
+    return { data, error, isRefetching };
+}
+function useAddServerPeer({ projectId }) {
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { mutate, reset, status } = (0, react_query_1.useMutation)((0, projects_js_1.addServerPeerMutationOptions)({ projectApi, projectId, queryClient }));
+    return { mutate, reset, status };
+}
+/**
+ * Create a new project.
+ */
+function useCreateProject() {
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const clientApi = (0, client_js_1.useClientApi)();
+    const { mutate, status, reset } = (0, react_query_1.useMutation)((0, projects_js_1.createProjectMutationOptions)({ clientApi, queryClient }));
+    return { mutate, reset, status };
+}
+/**
+ * Leave an existing project.
+ */
+function useLeaveProject() {
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const clientApi = (0, client_js_1.useClientApi)();
+    const { mutate, status, reset } = (0, react_query_1.useMutation)((0, projects_js_1.leaveProjectMutationOptions)({ clientApi, queryClient }));
+    return { mutate, reset, status };
+}
+/**
+ * Update the configuration of a project using an external file.
+ *
+ * @param opts.projectId Public ID of the project to apply changes to.
+ */
+function useImportProjectConfig({ projectId }) {
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { mutate, status, reset } = (0, react_query_1.useMutation)((0, projects_js_1.importProjectConfigMutationOptions)({ queryClient, projectApi, projectId }));
+    return { mutate, reset, status };
+}
+/**
+ * Update the settings of a project.
+ *
+ * @param opts.projectId Public ID of the project to apply changes to.
+ */
+function useUpdateProjectSettings({ projectId }) {
+    const queryClient = (0, react_query_1.useQueryClient)();
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { mutate, reset, status } = (0, react_query_1.useMutation)((0, projects_js_1.updateProjectSettingsMutationOptions)({ projectApi, queryClient }));
+    return { mutate, reset, status };
+}
+/**
+ * Create a blob for a project.
+ *
+ * @param opts.projectId Public project ID of project to apply to changes to.
+ */
+function useCreateBlob({ projectId }) {
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { mutate, reset, status } = (0, react_query_1.useMutation)((0, projects_js_1.createBlobMutationOptions)({ projectApi }));
+    return { mutate, reset, status };
+}

package/dist/commonjs/index.d.ts

@@ -0,0 +1,12 @@
+export { ClientApiContext, ClientApiProvider } from './contexts/ClientApi.js';
+export { useClientApi, useIsArchiveDevice, useOwnDeviceInfo, useSetIsArchiveDevice, useSetOwnDeviceInfo, } from './hooks/client.js';
+export { useCreateDocument, useDeleteDocument, useManyDocs, useSingleDocByDocId, useSingleDocByVersionId, useUpdateDocument, } from './hooks/documents.js';
+export { useAcceptInvite, useRejectInvite, useRequestCancelInvite, useSendInvite, } from './hooks/invites.js';
+export { useMapStyleUrl } from './hooks/maps.js';
+export { useAddServerPeer, useAttachmentUrl, useCreateBlob, useCreateProject, useDocumentCreatedBy, useIconUrl, useImportProjectConfig, useLeaveProject, useManyMembers, useManyProjects, useProjectSettings, useSingleMember, useSingleProject, useUpdateProjectSettings, } from './hooks/projects.js';
+export { getClientQueryKey, getDeviceInfoQueryKey, getIsArchiveDeviceQueryKey, } from './lib/react-query/client.js';
+export { getDocumentByDocIdQueryKey, getDocumentByVersionIdQueryKey, getDocumentsQueryKey, getManyDocumentsQueryKey, type WriteableDocument, type WriteableDocumentType, type WriteableValue, } from './lib/react-query/documents.js';
+export { getInvitesQueryKey, getPendingInvitesQueryKey, } from './lib/react-query/invites.js';
+export { getMapsQueryKey, getStyleJsonUrlQueryKey, } from './lib/react-query/maps.js';
+export { getAttachmentUrlQueryKey, getDocumentCreatedByQueryKey, getIconUrlQueryKey, getMemberByIdQueryKey, getMembersQueryKey, getProjectByIdQueryKey, getProjectRoleQueryKey, getProjectSettingsQueryKey, getProjectsQueryKey, } from './lib/react-query/projects.js';
+export { ROOT_QUERY_KEY } from './lib/react-query/shared.js';