@comapeo/core-react 8.0.0 → 9.0.0

package/dist/esm/hooks/maps.js

@@ -1,6 +1,11 @@
-import { useSuspenseQuery } from '@tanstack/react-query';
-import { mapStyleJsonUrlQueryOptions } from '../lib/react-query/maps.js';
-import { useClientApi } from './client.js';
+import { CUSTOM_MAP_ID } from '@comapeo/map-server/constants.js';
+import { errors } from '@comapeo/map-server/errors.js';
+import { useMutation, useQuery, useQueryClient, useSuspenseQuery, } from '@tanstack/react-query';
+import { useCallback } from 'react';
+import { useMapServerApi } from '../contexts/MapServer.js';
+import { useReceivedMapSharesActions, useReceivedMapSharesState, useSentMapSharesActions, useSentMapSharesState, } from '../contexts/MapShares.js';
+import { mapImportMutationOptions, mapInfoQueryOptions, mapRemoveMutationOptions, mapSharesMutationOptions, mapStyleJsonUrlQueryOptions, } from '../lib/react-query/maps.js';
+import { filterMutationResult } from '../lib/react-query/mutation-result.js';
 /**
  * Get a URL that points to a StyleJSON resource served by the embedded HTTP server.
  *
@@ -27,8 +32,249 @@ import { useClientApi } from './client.js';
  * }
  * ```
  */
-export function useMapStyleUrl({ refreshToken, } = {}) {
-    const clientApi = useClientApi();
-    const { data, error, isRefetching } = useSuspenseQuery(mapStyleJsonUrlQueryOptions({ clientApi, refreshToken }));
+export function useMapStyleUrl() {
+    const mapServerApi = useMapServerApi();
+    const { data, error, isRefetching } = useSuspenseQuery(mapStyleJsonUrlQueryOptions({ mapServerApi }));
     return { data, error, isRefetching };
 }
+/**
+ * Import a custom SMP map file, replacing any existing custom map. The mutation
+ * resolves once the file is successfully uploaded and processed by the server.
+ *
+ * @example
+ * ```tsx
+ * function MapImportExample() {
+ *   const { mutate: importMap } = useImportCustomMapFile()
+ *
+ * }
+ * ```
+ */
+export function useImportCustomMapFile() {
+    const mapServerApi = useMapServerApi();
+    const queryClient = useQueryClient();
+    const options = mapImportMutationOptions({ mapServerApi, queryClient });
+    const result = useMutation(options);
+    return filterMutationResult(result);
+}
+export function useRemoveCustomMapFile() {
+    const mapServerApi = useMapServerApi();
+    const queryClient = useQueryClient();
+    const options = mapRemoveMutationOptions({ mapServerApi, queryClient });
+    const result = useMutation(options);
+    return filterMutationResult(result);
+}
+export function useGetCustomMapInfo() {
+    const mapServerApi = useMapServerApi();
+    const { data, error, isRefetching } = useQuery(mapInfoQueryOptions({ mapServerApi, mapId: CUSTOM_MAP_ID }));
+    return { data, error, isRefetching };
+}
+// ============================================
+// RECEIVER HOOKS
+// ============================================
+/**
+ * Get all map shares that the device has received. Automatically updates when
+ * new shares arrive or share states change.
+ *
+ * IMPORTANT: This hook will not trigger a re-render when download progress
+ * updates, only when the status changes. This is to avoid excessive re-renders
+ * during downloads. Use `useSingleReceivedMapShare` to get real-time updates on
+ * a specific share, including download progress.
+ *
+ * @example
+ * ```tsx
+ * function MapSharesList() {
+ *   const shares = useManyReceivedMapShares()
+ *
+ *   return shares.map(share => (
+ *     <div key={share.shareId}>
+ *       {share.mapName} from {share.senderDeviceName} - {share.state}
+ *     </div>
+ *   ))
+ * }
+ * ```
+ */
+export function useManyReceivedMapShares() {
+    return useReceivedMapSharesState();
+}
+/**
+ * Get a single received map share based on its shareId.
+ *
+ * @param opts.shareId ID of the map share
+ *
+ * @example
+ * ```tsx
+ * function MapShareDetail({ shareId }: { shareId: string }) {
+ *   const share = useSingleReceivedMapShare({ shareId })
+ *
+ *   return <div>{share.mapName} - {share.state}</div>
+ * }
+ * ```
+ */
+export function useSingleReceivedMapShare({ shareId }) {
+    const mapShare = useReceivedMapSharesState(useCallback((shares) => shares.find((s) => s.shareId === shareId), [shareId]));
+    if (!mapShare) {
+        throw new Error(`Map share with id ${shareId} not found`);
+    }
+    return mapShare;
+}
+/**
+ * Accept and download a map share that has been received. The mutate promise
+ * resolves once the map _starts_ downloading, before it finishes downloading.
+ * Use `useManyMapShares` or `useSingleMapShare` to track download progress.
+ *
+ * Throws if the share is not in `status="pending"` or if the download fails to
+ * start (e.g. if the shareId if invalid).
+ *
+ * @example
+ * ```tsx
+ * function AcceptButton({ shareId }: { shareId: string }) {
+ *   const { mutate: accept } = useAcceptMapShare()
+ *
+ *   return <button onClick={() => accept({ shareId })}>Accept</button>
+ * }
+ * ```
+ */
+export function useDownloadReceivedMapShare() {
+    const { download } = useReceivedMapSharesActions();
+    const options = mapSharesMutationOptions({ action: download });
+    const result = useMutation(options);
+    return filterMutationResult(result);
+}
+/**
+ * Decline a map share that has been received. Notifies the sender that the
+ * share was declined.
+ *
+ * Throws if the share is not with `status="pending"`
+ * Throws if shareId is invalid
+ * Throws if decline request fails (e.g. network error)
+ *
+ * @example
+ * ```tsx
+ * import { DeclineReason } from '@comapeo/core-react'
+ * function DeclineButton({ shareId }: { shareId: string }) {
+ *   const { mutate: decline } = useDeclineMapShare()
+ *
+ *   return (
+ *     <button onClick={() => decline({ shareId, reason: DeclineReason.user_rejected })}>
+ *       Decline
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export function useDeclineReceivedMapShare() {
+    const { decline } = useReceivedMapSharesActions();
+    const options = mapSharesMutationOptions({ action: decline });
+    const result = useMutation(options);
+    return filterMutationResult(result);
+}
+/**
+ * Abort an in-progress map share download.
+ *
+ * Throws if the share is not in `status="downloading"`
+ * Throws if shareId is invalid
+ *
+ * @example
+ * ```tsx
+ * function AbortButton({ shareId }: { shareId: string }) {
+ *   const { mutate: abort } = useAbortMapShareDownload()
+ *
+ *   return <button onClick={() => abort({ shareId })}>Cancel Download</button>
+ * }
+ * ```
+ */
+export function useAbortReceivedMapShareDownload() {
+    const { abort } = useReceivedMapSharesActions();
+    const options = mapSharesMutationOptions({ action: abort });
+    const result = useMutation(options);
+    return filterMutationResult(result);
+}
+// ============================================
+// SENDER HOOKS
+// ============================================
+/**
+ * Share a map with a device. The mutation resolves immediately after sending
+ * the share offer, without waiting for the recipient to accept or reject. The
+ * mutation resolves with the created map share object, including its ID, which
+ * can be used to track the share status with `useSingleSentMapShare`.
+ *
+ * @param opts.projectId Public ID of project for sending the map share: you can only send map shares to users on the same project
+ *
+ * @example
+ * ```tsx
+ * function SendMapButton({ projectId, deviceId }: { projectId: string; deviceId: string }) {
+ *   const { mutate: send } = useSendMapShare({ projectId }, {
+ *     onSuccess: (mapShare) => {
+ *  	   console.log('Share sent with id', mapShare.shareId)
+ *     }
+ *   })
+ *
+ *   return (
+ *     <button onClick={() => send({ receiverDeviceId: deviceId, mapId: 'custom' })}>
+ *       Send Map
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export function useSendMapShare({ projectId }) {
+    const { createAndSend } = useSentMapSharesActions();
+    const options = mapSharesMutationOptions({ action: createAndSend, projectId });
+    const result = useMutation(options);
+    return filterMutationResult(result);
+}
+/**
+ * Cancel a map share that was previously sent. If the recipient has not yet
+ * started downloading the share, they will not be notified until they attempt
+ * to accept the share and begin downloading it. If they are already downloading
+ * the share, the download will be canceled before completion. If the download
+ * is already complete, this action will throw an error.
+ *
+ * @param opts.projectId Public ID of project to request the map share cancellation for.
+ *
+ * @example
+ * ```tsx
+ * function CancelShareButton({ projectId, shareId }: { projectId: string; shareId: string }) {
+ *   const { mutate: cancel } = useRequestCancelMapShare({ projectId })
+ *
+ *   return <button onClick={() => cancel({ shareId })}>Cancel Share</button>
+ * }
+ * ```
+ */
+export function useCancelSentMapShare() {
+    const { cancel } = useSentMapSharesActions();
+    const options = mapSharesMutationOptions({ action: cancel });
+    const result = useMutation(options);
+    return filterMutationResult(result);
+}
+/**
+ * Track the status and progress of a sent map share. Returns the current state
+ * of the share, updated in real-time. When the recipient starts downloading, or
+ * if they decline the share, then the returned share will update.
+ *
+ * Throws if no share with the specified ID is found.
+ *
+ * @param opts.shareId ID of the sent map share
+ *
+ * @example
+ * ```tsx
+ * function SentShareStatus({ shareId }: { shareId: string }) {
+ *   const mapShare = useSingleSentMapShare({ shareId })
+ *
+ *   return (<div>
+ * 		<div>Share status: {mapShare.status}</div>
+ *    {mapShare.status === 'pending' && <div>Waiting for recipient to accept...</div>}
+ *   	{mapShare.status === 'downloading' && (<div>Download in progress: {mapShare.downloadProgress}%</div>)}
+ *   	{mapShare.status === 'declined' && <div>Share was declined by recipient</div>}
+ * 	  {mapShare.status === 'canceled' && <div>Share was canceled</div>}
+ *   </div>)
+ * }
+ * ```
+ */
+export function useSingleSentMapShare({ shareId, }) {
+    const mapShare = useSentMapSharesState(useCallback((shares) => shares.find((s) => s.shareId === shareId), [shareId]));
+    if (!mapShare) {
+        throw new errors.MAP_SHARE_NOT_FOUND(`Sent map share with id ${shareId} not found`);
+    }
+    return mapShare;
+}

package/dist/esm/index.d.ts

@@ -1,8 +1,11 @@
-export { ClientApiProvider } from './contexts/ClientApi.js';
+export { ComapeoCoreProvider } from './contexts/ComapeoCore.js';
 export { useClientApi, useIsArchiveDevice, useOwnDeviceInfo, useSetIsArchiveDevice, useSetOwnDeviceInfo, } from './hooks/client.js';
 export { useCreateDocument, useDeleteDocument, useManyDocs, usePresetsSelection, useSingleDocByDocId, useSingleDocByVersionId, useUpdateDocument, } from './hooks/documents.js';
 export { useAcceptInvite, useManyInvites, useRejectInvite, useRequestCancelInvite, useSendInvite, useSingleInvite, } from './hooks/invites.js';
-export { useMapStyleUrl } from './hooks/maps.js';
+export { useMapStyleUrl, useImportCustomMapFile, useRemoveCustomMapFile, useGetCustomMapInfo, useManyReceivedMapShares, useSingleReceivedMapShare, useDeclineReceivedMapShare, useDownloadReceivedMapShare, useAbortReceivedMapShareDownload, useSendMapShare, useCancelSentMapShare, useSingleSentMapShare, } from './hooks/maps.js';
+export type { SentMapShareState, ReceivedMapShareState, AbortMapShareOptions, CancelMapShareOptions, DeclineMapShareOptions, DownloadMapShareOptions, CreateAndSendMapShareOptions, } from './lib/map-shares-stores.js';
+export { DeclineReason } from './lib/map-shares-stores.js';
 export { useAddServerPeer, useAttachmentUrl, useConnectSyncServers, useCreateBlob, useCreateProject, useDataSyncProgress, useDisconnectSyncServers, useDocumentCreatedBy, useIconUrl, useImportProjectCategories, useImportProjectConfig, useLeaveProject, useManyMembers, useManyProjects, useOwnRoleInProject, useProjectOwnRoleChangeListener, useProjectSettings, useRemoveServerPeer, useRemoveMember, useSetAutostopDataSyncTimeout, useSingleMember, useSingleProject, useStartSync, useStopSync, useSyncState, useUpdateProjectSettings, useChangeMemberRole, useExportGeoJSON, useExportZipFile, } from './hooks/projects.js';
 export { type SyncState } from './lib/sync.js';
 export { type WriteableDocument, type WriteableDocumentType, type WriteableValue, } from './lib/types.js';
+export { HTTPError, isHTTPError } from './lib/http.js';

package/dist/esm/index.js

@@ -1,6 +1,8 @@
-export { ClientApiProvider } from './contexts/ClientApi.js';
+export { ComapeoCoreProvider } from './contexts/ComapeoCore.js';
 export { useClientApi, useIsArchiveDevice, useOwnDeviceInfo, useSetIsArchiveDevice, useSetOwnDeviceInfo, } from './hooks/client.js';
 export { useCreateDocument, useDeleteDocument, useManyDocs, usePresetsSelection, useSingleDocByDocId, useSingleDocByVersionId, useUpdateDocument, } from './hooks/documents.js';
 export { useAcceptInvite, useManyInvites, useRejectInvite, useRequestCancelInvite, useSendInvite, useSingleInvite, } from './hooks/invites.js';
-export { useMapStyleUrl } from './hooks/maps.js';
+export { useMapStyleUrl, useImportCustomMapFile, useRemoveCustomMapFile, useGetCustomMapInfo, useManyReceivedMapShares, useSingleReceivedMapShare, useDeclineReceivedMapShare, useDownloadReceivedMapShare, useAbortReceivedMapShareDownload, useSendMapShare, useCancelSentMapShare, useSingleSentMapShare, } from './hooks/maps.js';
+export { DeclineReason } from './lib/map-shares-stores.js';
 export { useAddServerPeer, useAttachmentUrl, useConnectSyncServers, useCreateBlob, useCreateProject, useDataSyncProgress, useDisconnectSyncServers, useDocumentCreatedBy, useIconUrl, useImportProjectCategories, useImportProjectConfig, useLeaveProject, useManyMembers, useManyProjects, useOwnRoleInProject, useProjectOwnRoleChangeListener, useProjectSettings, useRemoveServerPeer, useRemoveMember, useSetAutostopDataSyncTimeout, useSingleMember, useSingleProject, useStartSync, useStopSync, useSyncState, useUpdateProjectSettings, useChangeMemberRole, useExportGeoJSON, useExportZipFile, } from './hooks/projects.js';
+export { HTTPError, isHTTPError } from './lib/http.js';

package/dist/esm/lib/http.d.ts

@@ -0,0 +1,45 @@
+import type { JsonValue } from 'type-fest';
+type HttpInit = RequestInit & {
+    json?: JsonValue;
+};
+type ResponsePromise = Promise<Response> & {
+    json<T = unknown>(): Promise<T>;
+    text(): Promise<string>;
+};
+type Input = string | URL;
+/**
+ * http - A minimal fetch wrapper to reduce some boilerplate.
+ *
+ * @example
+ * ```js
+ *   import { createHttp } from './http.js'
+ *   const http = createHttp(myCustomFetch)
+ *
+ *   const data = await http.get('https://api.example.com/items').json()
+ *   await http.post('https://api.example.com/items', { json: { name: 'foo' } }).json()
+ * ```
+ */
+declare function createHttp(fetchFn?: (input: string | URL, init?: RequestInit) => Promise<Response>): Record<"head" | "get" | "post" | "put" | "patch" | "delete", (input: Input, options?: HttpInit) => ResponsePromise>;
+type HTTPErrorObject = {
+    message?: string;
+    code?: string;
+    [key: string]: unknown;
+};
+/**
+ * HTTPError - Custom error class to represent HTTP errors with additional context.
+ */
+declare class HTTPError extends Error {
+    readonly response: Response;
+    readonly status: number;
+    readonly code: string;
+    [key: string]: unknown;
+    constructor(response: Response, { method, url, ...body }: {
+        method: string;
+        url: string;
+    } & HTTPErrorObject);
+}
+/**
+ * Type guard to check if an error is an instance of HTTPError.
+ */
+declare function isHTTPError(error: unknown): error is HTTPError;
+export { createHttp, HTTPError, isHTTPError };

package/dist/esm/lib/http.js

@@ -0,0 +1,98 @@
+const requestMethods = [
+    'get',
+    'post',
+    'put',
+    'patch',
+    'head',
+    'delete',
+];
+/**
+ * http - A minimal fetch wrapper to reduce some boilerplate.
+ *
+ * @example
+ * ```js
+ *   import { createHttp } from './http.js'
+ *   const http = createHttp(myCustomFetch)
+ *
+ *   const data = await http.get('https://api.example.com/items').json()
+ *   await http.post('https://api.example.com/items', { json: { name: 'foo' } }).json()
+ * ```
+ */
+function createHttp(fetchFn = globalThis.fetch) {
+    const alias = (method) => (input, options = {}) => {
+        const { json, headers, ...rest } = options;
+        const h = new Headers(headers);
+        if (json !== undefined) {
+            rest.body = JSON.stringify(json);
+            if (!h.has('content-type'))
+                h.set('content-type', 'application/json');
+        }
+        if (!h.has('accept'))
+            h.set('accept', 'application/json');
+        const responsePromise = fetchFn(input, {
+            ...rest,
+            method,
+            headers: h,
+        }).then((response) => {
+            if (!response.ok)
+                throw new HTTPError(response, { method, url: input.toString() });
+            return response;
+        });
+        responsePromise.json = () => responsePromise
+            .catch((e) => {
+            // For http errors, parse the body as json to get the error details, but rethrow other errors (e.g. network errors)
+            if (isHTTPError(e))
+                return e.response;
+            throw e;
+        })
+            .then(async (r) => {
+            if (r.status === 204)
+                return '';
+            const text = await r.text();
+            const parsed = text === '' ? '' : JSON.parse(text);
+            if (r.ok)
+                return parsed;
+            throw new HTTPError(r, {
+                method: options.method ?? 'GET',
+                url: input.toString(),
+                ...parsed,
+            });
+        });
+        responsePromise.text = () => responsePromise.then((r) => r.text());
+        return responsePromise;
+    };
+    const http = {};
+    for (const method of requestMethods) {
+        http[method] = alias(upperCase(method));
+    }
+    return http;
+}
+/**
+ * HTTPError - Custom error class to represent HTTP errors with additional context.
+ */
+class HTTPError extends Error {
+    response;
+    status;
+    code = 'UNKNOWN_ERROR';
+    constructor(response, { method, url, ...body }) {
+        const status = response.status || 500;
+        const message = body.message || `Request failed with ${status}: ${method} ${url}`;
+        super(message);
+        Object.assign(this, body);
+        // override status in body with status from response
+        this.status = status;
+        this.name = 'HTTPError';
+        this.response = response;
+    }
+}
+/**
+ * Type guard to check if an error is an instance of HTTPError.
+ */
+function isHTTPError(error) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return error instanceof HTTPError || error?.name === HTTPError.name;
+}
+export { createHttp, HTTPError, isHTTPError };
+function upperCase(str) {
+    return str.toUpperCase();
+}

package/dist/esm/lib/map-shares-stores.d.ts

@@ -0,0 +1,80 @@
+import type { MapShare } from '@comapeo/core';
+import type { MapeoClientApi } from '@comapeo/ipc';
+import { type MapShareState as ServerMapShareState } from '@comapeo/map-server';
+import { type QueryClient } from '@tanstack/react-query';
+import type { Simplify } from 'type-fest';
+import type { MapServerApi } from '../contexts/MapServer.js';
+type DistributedIntersection<T, U> = U extends unknown ? Simplify<T & U> : never;
+export type ReceivedMapShareState = DistributedIntersection<Simplify<MapShare>, ServerMapShareState>;
+export type SentMapShareState = ServerMapShareState;
+export type ReceivedMapSharesStore = ReturnType<typeof createReceivedMapSharesStore>;
+export type SentMapSharesStore = ReturnType<typeof createSentMapSharesStore>;
+/** Known reasons for declining a map share */
+export declare const DeclineReason: {
+    /** User explicitly rejected the map share */
+    readonly user_rejected: "user_rejected";
+    /** Device storage is full */
+    readonly storage_full: "storage_full";
+};
+/** Options for downloading a received map share */
+export type DownloadMapShareOptions = {
+    /** ID of the map share to download */
+    shareId: string;
+};
+/** Options for declining a received map share */
+export type DeclineMapShareOptions = {
+    /** ID of the map share to decline */
+    shareId: string;
+    /** Reason for declining (e.g., 'user_rejected', 'storage_full') */
+    reason: (typeof DeclineReason)[keyof typeof DeclineReason] | (string & {});
+};
+/** Options for aborting an in-progress map share download */
+export type AbortMapShareOptions = {
+    /** ID of the map share download to abort */
+    shareId: string;
+};
+/** Options for creating and sending a map share */
+export type CreateAndSendMapShareOptions = {
+    /** Public ID of the project to send the share on behalf of */
+    projectId: string;
+    /** Device ID of the recipient */
+    receiverDeviceId: string;
+    /** ID of the map to share - not needed until we support multiple maps */
+    mapId?: string;
+};
+/** Options for canceling a sent map share */
+export type CancelMapShareOptions = {
+    /** ID of the map share to cancel */
+    shareId: string;
+};
+/**
+ * Store and actions for received map shares.
+ */
+export declare function createReceivedMapSharesStore({ clientApi, mapServerApi, queryClient, }: {
+    clientApi: MapeoClientApi;
+    mapServerApi: MapServerApi;
+    queryClient: QueryClient;
+}): {
+    subscribe: (listener: () => void) => () => boolean;
+    getSnapshot: () => ReceivedMapShareState[];
+    actions: {
+        download({ shareId }: DownloadMapShareOptions): Promise<void>;
+        decline({ shareId, reason }: DeclineMapShareOptions): Promise<void>;
+        abort({ shareId }: AbortMapShareOptions): Promise<void>;
+    };
+};
+/**
+ * Store and actions for sent map share.
+ */
+export declare function createSentMapSharesStore({ clientApi, mapServerApi, }: {
+    clientApi: MapeoClientApi;
+    mapServerApi: MapServerApi;
+}): {
+    subscribe: (listener: () => void) => () => boolean;
+    getSnapshot: () => ServerMapShareState[];
+    actions: {
+        createAndSend({ projectId, receiverDeviceId, mapId, }: CreateAndSendMapShareOptions): Promise<ServerMapShareState>;
+        cancel({ shareId }: CancelMapShareOptions): Promise<void>;
+    };
+};
+export {};