@comapeo/core-react 10.0.1 → 11.0.1

package/dist/commonjs/lib/map-shares-stores.js

@@ -3,7 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DeclineReason = void 0;
+exports.InvalidStatusTransitionError = exports.MapShareCanceledError = exports.DeclineReason = exports.MapShareErrorCode = void 0;
+exports.getErrorCode = getErrorCode;
 exports.createReceivedMapSharesStore = createReceivedMapSharesStore;
 exports.createSentMapSharesStore = createSentMapSharesStore;
 const constants_js_1 = require("@comapeo/map-server/constants.js");
@@ -16,6 +17,118 @@ const react_query_js_1 = require("./react-query.js");
 // functions - if the documentation comments are added inline for the store
 // actions, they do not show for the mutate() function in hooks.
 // ============================================
+/**
+ * Error codes for map share operations. Use with {@link getErrorCode} to safely
+ * check the error code of an unknown error thrown by a map share mutation, or
+ * to check the `error.code` on a share in `status='error'`.
+ *
+ * ## Receiver errors
+ *
+ * **Mutation errors** (thrown by receiver hooks, check via
+ * `getErrorCode(mutation.error)`):
+ * - `MAP_SHARE_CANCELED` — the sender canceled the share
+ * - `INVALID_STATUS_TRANSITION` — the action is not valid for the share's
+ *   current status (e.g. declining a share that is already downloading)
+ * - `MAP_SHARE_NOT_FOUND` — no share with the given `shareId` exists
+ * - `DOWNLOAD_NOT_FOUND` — abort was called but no download is tracked for
+ *   this share
+ *
+ * **Share state errors** (on received `share.error.code` when
+ * `share.status === 'error'`):
+ * - `DOWNLOAD_ERROR` — the download failed (network, disk, or server error)
+ * - `DECLINE_CANNOT_CONNECT` — the decline was accepted locally but the sender
+ *   could not be reached to notify them
+ *
+ * ## Sender errors
+ *
+ * **Mutation errors** (thrown by sender hooks, check via
+ * `getErrorCode(mutation.error)`):
+ * - `INVALID_STATUS_TRANSITION` — the action is not valid for the share's
+ *   current status (e.g. canceling a share that is already canceled)
+ * - `MAP_SHARE_NOT_FOUND` — no share with the given `shareId` exists
+ *
+ * **Share state errors** (on sent `share.error.code` when
+ * `share.status === 'error'`):
+ * - `CANCEL_SHARE_NOT_CANCELABLE` — the cancel request reached the server but
+ *   the share is already in a final state (e.g. completed or declined)
+ *
+ * ## Common
+ *
+ * - `UNKNOWN_ERROR` — fallback when the original error has no specific code.
+ *   Can appear as both a mutation error and a share state error for either
+ *   sender or receiver.
+ *
+ * @example
+ * ```tsx
+ * import { getErrorCode, MapShareErrorCode } from '@comapeo/core-react'
+ *
+ * // Receiver: checking a mutation error
+ * const decline = useDeclineReceivedMapShare()
+ * // ... after mutation fails:
+ * if (getErrorCode(decline.error) === MapShareErrorCode.MAP_SHARE_CANCELED) {
+ *   // Show "this share was canceled by the sender"
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Receiver: checking a share state error
+ * const share = useSingleReceivedMapShare({ shareId })
+ * if (share.status === 'error') {
+ *   if (share.error.code === MapShareErrorCode.DOWNLOAD_ERROR) {
+ *     // Show "download failed, try again?"
+ *   }
+ * }
+ * ```
+ */
+exports.MapShareErrorCode = {
+    // --- Receiver mutation errors (thrown by receiver actions) ---
+    /** Receiver: the sender canceled the share before the action could complete */
+    MAP_SHARE_CANCELED: 'MAP_SHARE_CANCELED',
+    /** Receiver/Sender: the action is not valid for the share's current status */
+    INVALID_STATUS_TRANSITION: 'INVALID_STATUS_TRANSITION',
+    /** Receiver/Sender: no map share with the given `shareId` exists in the store */
+    MAP_SHARE_NOT_FOUND: 'MAP_SHARE_NOT_FOUND',
+    /** Receiver: abort was called but no download is tracked for this share */
+    DOWNLOAD_NOT_FOUND: 'DOWNLOAD_NOT_FOUND',
+    // --- Receiver share state errors (in share.error.code) ---
+    /** Receiver: the download failed due to a network, disk, or server error */
+    DOWNLOAD_ERROR: 'DOWNLOAD_ERROR',
+    /** Receiver: could not connect to the sender to notify them of the decline */
+    DECLINE_CANNOT_CONNECT: 'DECLINE_CANNOT_CONNECT',
+    // --- Sender share state errors (in share.error.code) ---
+    /** Sender: cancel failed because the share is already in a final state on the server */
+    CANCEL_SHARE_NOT_CANCELABLE: 'CANCEL_SHARE_NOT_CANCELABLE',
+    // --- Common ---
+    /** Receiver/Sender: fallback code when the original error has no specific code */
+    UNKNOWN_ERROR: 'UNKNOWN_ERROR',
+};
+/**
+ * Safely extract the `code` property from an unknown error. Returns `undefined`
+ * if the value is not an Error or has no string `code` property.
+ *
+ * @example
+ * ```tsx
+ * import { getErrorCode, MapShareErrorCode } from '@comapeo/core-react'
+ *
+ * try {
+ *   await decline.mutateAsync({ shareId, reason: 'user_rejected' })
+ * } catch (e) {
+ *   const code = getErrorCode(e)
+ *   if (code === MapShareErrorCode.MAP_SHARE_CANCELED) {
+ *     // handle cancellation
+ *   }
+ * }
+ * ```
+ */
+function getErrorCode(error) {
+    if (error instanceof Error &&
+        'code' in error &&
+        typeof error.code === 'string') {
+        return error.code;
+    }
+    return undefined;
+}
 /** Known reasons for declining a map share */
 exports.DeclineReason = {
     /** User explicitly rejected the map share */
@@ -23,6 +136,32 @@ exports.DeclineReason = {
     /** Device storage is full */
     storage_full: 'storage_full',
 };
+/**
+ * Thrown when a receiver action (download, decline, or abort) is attempted on a
+ * map share that has been canceled by the sender. Has `code: 'MAP_SHARE_CANCELED'`.
+ */
+class MapShareCanceledError extends Error {
+    code = 'MAP_SHARE_CANCELED';
+    constructor(shareId) {
+        super(`Map share ${shareId} has been canceled by the sender`);
+        this.name = 'MapShareCanceledError';
+    }
+}
+exports.MapShareCanceledError = MapShareCanceledError;
+/**
+ * Thrown when an action is attempted on a map share whose current status does
+ * not allow the requested transition (e.g. declining a share that is already
+ * downloading, or aborting a share that is still pending).
+ * Has `code: 'INVALID_STATUS_TRANSITION'`.
+ */
+class InvalidStatusTransitionError extends Error {
+    code = 'INVALID_STATUS_TRANSITION';
+    constructor(current, next) {
+        super(`Invalid status transition from ${current} to ${next}`);
+        this.name = 'InvalidStatusTransitionError';
+    }
+}
+exports.InvalidStatusTransitionError = InvalidStatusTransitionError;
 /**
  * This is like a mini zustand store. Keeping the map shares in an external
  * store avoids unnecessary re-renders of the entire app when map shares are
@@ -143,6 +282,13 @@ function createReceivedMapSharesStore({ clientApi, mapServerApi, queryClient, })
     const actions = {
         async download({ shareId }) {
             const mapShare = get(shareId);
+            // This path should be be impossible, because the map share only receives
+            // status updates from the receiver after the download starts, but adding
+            // for completeness, and the edge-case of the receiving trying to
+            // download() a second time.
+            if (mapShare.status === 'canceled') {
+                throw new MapShareCanceledError(shareId);
+            }
             update(shareId, { status: 'downloading', bytesDownloaded: 0 });
             try {
                 const downloadIdPromise = mapServerApi
@@ -184,22 +330,39 @@ function createReceivedMapSharesStore({ clientApi, mapServerApi, queryClient, })
         },
         async decline({ shareId, reason }) {
             const mapShare = get(shareId);
-            update(shareId, { status: 'declined', reason });
+            if (mapShare.status === 'canceled') {
+                throw new MapShareCanceledError(shareId);
+            }
+            if (mapShare.status !== 'pending') {
+                throw new InvalidStatusTransitionError(mapShare.status, 'declined');
+            }
             try {
-                await mapServerApi.post(`mapShares/${shareId}/decline`, {
+                await mapServerApi
+                    .post(`mapShares/${shareId}/decline`, {
                     json: {
                         senderDeviceId: mapShare.senderDeviceId,
                         mapShareUrls: mapShare.mapShareUrls,
                         reason,
                     },
-                });
+                })
+                    .json();
+                update(shareId, { status: 'declined', reason });
             }
             catch (e) {
+                const error = (0, ensure_error_1.default)(e);
+                if ('code' in error && error.code === 'MAP_SHARE_CANCELED') {
+                    update(shareId, { status: 'canceled' });
+                    throw new MapShareCanceledError(shareId);
+                }
                 handleError(shareId, e);
                 throw e;
             }
         },
         async abort({ shareId }) {
+            const mapShare = get(shareId);
+            if (mapShare.status === 'canceled') {
+                throw new MapShareCanceledError(shareId);
+            }
             update(shareId, { status: 'aborted' });
             try {
                 const downloadId = await downloads.get(shareId);
@@ -229,15 +392,14 @@ function createReceivedMapSharesStore({ clientApi, mapServerApi, queryClient, })
 function createSentMapSharesStore({ clientApi, mapServerApi, }) {
     const { subscribe, getSnapshot, update, add, handleError, monitor } = createMapSharesStore({ mapServerApi });
     const actions = {
-        async createAndSend({ projectId, receiverDeviceId, mapId = constants_js_1.CUSTOM_MAP_ID, }) {
+        async createAndSend({ receiverDeviceId, mapId = constants_js_1.CUSTOM_MAP_ID, }) {
             const mapShare = await mapServerApi
                 .post('mapShares', {
                 json: { receiverDeviceId, mapId },
             })
                 .json();
             try {
-                const project = await clientApi.getProject(projectId);
-                await project.$sendMapShare(mapShare);
+                await clientApi.sendMapShare(mapShare);
             }
             catch (e) {
                 await mapServerApi.post(`mapShares/${mapShare.shareId}/cancel`);
@@ -279,7 +441,7 @@ const allowedStatusTransitions = {
  */
 function assertValidStatusTransition(current, next) {
     if (!allowedStatusTransitions[current].includes(next)) {
-        throw new Error(`Invalid status transition from ${current} to ${next}`);
+        throw new InvalidStatusTransitionError(current, next);
     }
 }
 const finalStatuses = [

package/dist/commonjs/lib/react-query.js

@@ -23,7 +23,7 @@ exports.getDocumentsQueryKey = getDocumentsQueryKey;
 exports.getManyDocumentsQueryKey = getManyDocumentsQueryKey;
 exports.getDocumentByDocIdQueryKey = getDocumentByDocIdQueryKey;
 exports.getDocumentByVersionIdQueryKey = getDocumentByVersionIdQueryKey;
-const map_server_1 = require("@comapeo/map-server");
+const constants_js_1 = require("@comapeo/map-server/constants.js");
 // #region Shared
 const ROOT_QUERY_KEY = '@comapeo/core-react';
 // Since the API is running locally, queries should run regardless of network
@@ -103,7 +103,7 @@ async function invalidateMapQueries(queryClient, { mapId }) {
             queryKey: getMapQueryKey({ mapId }),
         }),
         queryClient.invalidateQueries({
-            queryKey: getMapQueryKey({ mapId: map_server_1.DEFAULT_MAP_ID }),
+            queryKey: getMapQueryKey({ mapId: constants_js_1.DEFAULT_MAP_ID }),
         }),
     ]);
 }

package/dist/esm/contexts/MapShares.d.ts

@@ -42,7 +42,7 @@ export declare function useReceivedMapSharesState<T>(selector: (state: Array<Rec
  * @internal
  */
 export declare function useSentMapSharesActions(): {
-    createAndSend({ projectId, receiverDeviceId, mapId, }: import("../lib/map-shares-stores.js").CreateAndSendMapShareOptions): Promise<import("@comapeo/map-server").MapShareState>;
+    createAndSend({ receiverDeviceId, mapId, }: import("../lib/map-shares-stores.js").CreateAndSendMapShareOptions): Promise<import("@comapeo/map-server").MapShareState>;
     cancel({ shareId }: import("../lib/map-shares-stores.js").CancelMapShareOptions): Promise<void>;
 };
 /**

package/dist/esm/hooks/maps.d.ts

@@ -141,6 +141,9 @@ export declare function useManyReceivedMapShares(): ReceivedMapShareState[];
  *
  * @param opts.shareId ID of the map share
  *
+ * @throws An error with code `'MAP_SHARE_NOT_FOUND'` if no received share
+ *   with the given `shareId` exists.
+ *
  * @example
  * ```tsx
  * function MapShareDetail({ shareId }: { shareId: string }) {
@@ -156,15 +159,28 @@ export declare function useSingleReceivedMapShare({ shareId }: {
 /**
  * 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).
+ * Use `useManyReceivedMapShares` or `useSingleReceivedMapShare` to track
+ * download progress and final status.
+ *
+ * If the sender canceled the share before the receiver calls this, the
+ * mutation will still resolve (the download starts), but the share status will
+ * end up as `'canceled'` rather than `'completed'`. This is the only way the
+ * receiver discovers that a share has been canceled — check `share.status`
+ * after the download settles.
+ *
+ * @throws An error with code `'MAP_SHARE_CANCELED'` if the share is already
+ *   known to be canceled (i.e. `status` is `'canceled'` in the store, e.g.
+ *   after a previous download attempt discovered the cancellation).
+ * @throws An error with code `'INVALID_STATUS_TRANSITION'` if the share is
+ *   not in a valid state to start downloading (e.g. already downloading,
+ *   completed, or declined).
+ * @throws An error with code `'MAP_SHARE_NOT_FOUND'` if no share with the
+ *   given `shareId` exists in the store.
  *
  * @example
  * ```tsx
  * function AcceptButton({ shareId }: { shareId: string }) {
- *   const { mutate: accept } = useAcceptMapShare()
+ *   const { mutate: accept } = useDownloadReceivedMapShare()
  *
  *   return <button onClick={() => accept({ shareId })}>Accept</button>
  * }
@@ -189,17 +205,28 @@ export declare function useDownloadReceivedMapShare(): Pick<import("@tanstack/re
 }, "error" | "status" | "mutate" | "reset" | "mutateAsync">;
 /**
  * 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)
+ * share was declined. The share status is only updated to `'declined'` after
+ * the server confirms the decline — there is no optimistic update.
+ *
+ * If the sender canceled the share before the decline reaches the server, the
+ * share status will transition to `'canceled'` (not `'error'`) and the
+ * mutation will throw a `MapShareCanceledError`.
+ *
+ * @throws An error with code `'MAP_SHARE_CANCELED'` if the share is already
+ *   known to be canceled, or if the server reports that the sender canceled
+ *   the share while the decline was in flight. In both cases `share.status`
+ *   will be `'canceled'`.
+ * @throws An error with code `'INVALID_STATUS_TRANSITION'` if the share is
+ *   not in `status='pending'` (e.g. already downloading, completed, or
+ *   declined).
+ * @throws An error with code `'MAP_SHARE_NOT_FOUND'` if no share with the
+ *   given `shareId` exists in the store.
  *
  * @example
  * ```tsx
  * import { DeclineReason } from '@comapeo/core-react'
  * function DeclineButton({ shareId }: { shareId: string }) {
- *   const { mutate: decline } = useDeclineMapShare()
+ *   const { mutate: decline } = useDeclineReceivedMapShare()
  *
  *   return (
  *     <button onClick={() => decline({ shareId, reason: DeclineReason.user_rejected })}>
@@ -229,13 +256,20 @@ export declare function useDeclineReceivedMapShare(): Pick<import("@tanstack/rea
 /**
  * Abort an in-progress map share download.
  *
- * Throws if the share is not in `status="downloading"`
- * Throws if shareId is invalid
+ * @throws An error with code `'MAP_SHARE_CANCELED'` if the share is already
+ *   known to be canceled.
+ * @throws An error with code `'INVALID_STATUS_TRANSITION'` if the share is
+ *   not in `status='downloading'` (e.g. still pending, already completed, or
+ *   declined).
+ * @throws An error with code `'MAP_SHARE_NOT_FOUND'` if no share with the
+ *   given `shareId` exists in the store.
+ * @throws An error with code `'DOWNLOAD_NOT_FOUND'` if no download is
+ *   currently tracked for this share (e.g. the download was never started).
  *
  * @example
  * ```tsx
  * function AbortButton({ shareId }: { shareId: string }) {
- *   const { mutate: abort } = useAbortMapShareDownload()
+ *   const { mutate: abort } = useAbortReceivedMapShareDownload()
  *
  *   return <button onClick={() => abort({ shareId })}>Cancel Download</button>
  * }
@@ -264,8 +298,6 @@ export declare function useAbortReceivedMapShareDownload(): Pick<import("@tansta
  * 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 }) {
@@ -274,7 +306,7 @@ export declare function useAbortReceivedMapShareDownload(): Pick<import("@tansta
  *	return (
  *		<button
  *			onClick={() =>
- *				send({ projectId, receiverDeviceId: deviceId, mapId: 'custom' }, {
+ *				send({ receiverDeviceId: deviceId, mapId: 'custom' }, {
  *                    onSuccess: (mapShare) => {
  *                        console.log('Share sent with id', mapShare.shareId)
  *                    }
@@ -311,6 +343,12 @@ export declare function useSendMapShare(): Pick<import("@tanstack/react-query").
  * the share, the download will be canceled before completion. If the download
  * is already complete, this action will throw an error.
  *
+ * @throws An error with code `'INVALID_STATUS_TRANSITION'` if the share is
+ *   not in `status='pending'` or `status='downloading'` (e.g. already
+ *   completed, canceled, aborted, or declined).
+ * @throws An error with code `'MAP_SHARE_NOT_FOUND'` if no share with the
+ *   given `shareId` exists in the store.
+ *
  * @param opts.projectId Public ID of project to request the map share cancellation for.
  *
  * @example
@@ -344,7 +382,8 @@ export declare function useCancelSentMapShare(): Pick<import("@tanstack/react-qu
  * 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.
+ * @throws An error with code `'MAP_SHARE_NOT_FOUND'` if no sent share with
+ *   the given `shareId` exists in the store.
  *
  * @param opts.shareId ID of the sent map share
  *

package/dist/esm/hooks/maps.js

@@ -149,6 +149,9 @@ export function useManyReceivedMapShares() {
  *
  * @param opts.shareId ID of the map share
  *
+ * @throws An error with code `'MAP_SHARE_NOT_FOUND'` if no received share
+ *   with the given `shareId` exists.
+ *
  * @example
  * ```tsx
  * function MapShareDetail({ shareId }: { shareId: string }) {
@@ -161,22 +164,35 @@ export function useManyReceivedMapShares() {
 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`);
+        throw new errors.MAP_SHARE_NOT_FOUND(`Received 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).
+ * Use `useManyReceivedMapShares` or `useSingleReceivedMapShare` to track
+ * download progress and final status.
+ *
+ * If the sender canceled the share before the receiver calls this, the
+ * mutation will still resolve (the download starts), but the share status will
+ * end up as `'canceled'` rather than `'completed'`. This is the only way the
+ * receiver discovers that a share has been canceled — check `share.status`
+ * after the download settles.
+ *
+ * @throws An error with code `'MAP_SHARE_CANCELED'` if the share is already
+ *   known to be canceled (i.e. `status` is `'canceled'` in the store, e.g.
+ *   after a previous download attempt discovered the cancellation).
+ * @throws An error with code `'INVALID_STATUS_TRANSITION'` if the share is
+ *   not in a valid state to start downloading (e.g. already downloading,
+ *   completed, or declined).
+ * @throws An error with code `'MAP_SHARE_NOT_FOUND'` if no share with the
+ *   given `shareId` exists in the store.
  *
  * @example
  * ```tsx
  * function AcceptButton({ shareId }: { shareId: string }) {
- *   const { mutate: accept } = useAcceptMapShare()
+ *   const { mutate: accept } = useDownloadReceivedMapShare()
  *
  *   return <button onClick={() => accept({ shareId })}>Accept</button>
  * }
@@ -193,17 +209,28 @@ export function useDownloadReceivedMapShare() {
 }
 /**
  * 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)
+ * share was declined. The share status is only updated to `'declined'` after
+ * the server confirms the decline — there is no optimistic update.
+ *
+ * If the sender canceled the share before the decline reaches the server, the
+ * share status will transition to `'canceled'` (not `'error'`) and the
+ * mutation will throw a `MapShareCanceledError`.
+ *
+ * @throws An error with code `'MAP_SHARE_CANCELED'` if the share is already
+ *   known to be canceled, or if the server reports that the sender canceled
+ *   the share while the decline was in flight. In both cases `share.status`
+ *   will be `'canceled'`.
+ * @throws An error with code `'INVALID_STATUS_TRANSITION'` if the share is
+ *   not in `status='pending'` (e.g. already downloading, completed, or
+ *   declined).
+ * @throws An error with code `'MAP_SHARE_NOT_FOUND'` if no share with the
+ *   given `shareId` exists in the store.
  *
  * @example
  * ```tsx
  * import { DeclineReason } from '@comapeo/core-react'
  * function DeclineButton({ shareId }: { shareId: string }) {
- *   const { mutate: decline } = useDeclineMapShare()
+ *   const { mutate: decline } = useDeclineReceivedMapShare()
  *
  *   return (
  *     <button onClick={() => decline({ shareId, reason: DeclineReason.user_rejected })}>
@@ -225,13 +252,20 @@ export function useDeclineReceivedMapShare() {
 /**
  * Abort an in-progress map share download.
  *
- * Throws if the share is not in `status="downloading"`
- * Throws if shareId is invalid
+ * @throws An error with code `'MAP_SHARE_CANCELED'` if the share is already
+ *   known to be canceled.
+ * @throws An error with code `'INVALID_STATUS_TRANSITION'` if the share is
+ *   not in `status='downloading'` (e.g. still pending, already completed, or
+ *   declined).
+ * @throws An error with code `'MAP_SHARE_NOT_FOUND'` if no share with the
+ *   given `shareId` exists in the store.
+ * @throws An error with code `'DOWNLOAD_NOT_FOUND'` if no download is
+ *   currently tracked for this share (e.g. the download was never started).
  *
  * @example
  * ```tsx
  * function AbortButton({ shareId }: { shareId: string }) {
- *   const { mutate: abort } = useAbortMapShareDownload()
+ *   const { mutate: abort } = useAbortReceivedMapShareDownload()
  *
  *   return <button onClick={() => abort({ shareId })}>Cancel Download</button>
  * }
@@ -255,8 +289,6 @@ export function useAbortReceivedMapShareDownload() {
  * 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 }) {
@@ -265,7 +297,7 @@ export function useAbortReceivedMapShareDownload() {
  *	return (
  *		<button
  *			onClick={() =>
- *				send({ projectId, receiverDeviceId: deviceId, mapId: 'custom' }, {
+ *				send({ receiverDeviceId: deviceId, mapId: 'custom' }, {
  *                    onSuccess: (mapShare) => {
  *                        console.log('Share sent with id', mapShare.shareId)
  *                    }
@@ -294,6 +326,12 @@ export function useSendMapShare() {
  * the share, the download will be canceled before completion. If the download
  * is already complete, this action will throw an error.
  *
+ * @throws An error with code `'INVALID_STATUS_TRANSITION'` if the share is
+ *   not in `status='pending'` or `status='downloading'` (e.g. already
+ *   completed, canceled, aborted, or declined).
+ * @throws An error with code `'MAP_SHARE_NOT_FOUND'` if no share with the
+ *   given `shareId` exists in the store.
+ *
  * @param opts.projectId Public ID of project to request the map share cancellation for.
  *
  * @example
@@ -319,7 +357,8 @@ export function useCancelSentMapShare() {
  * 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.
+ * @throws An error with code `'MAP_SHARE_NOT_FOUND'` if no sent share with
+ *   the given `shareId` exists in the store.
  *
  * @param opts.shareId ID of the sent map share
  *

package/dist/esm/index.d.ts

@@ -4,7 +4,7 @@ export { useCreateDocument, useDeleteDocument, useManyDocs, usePresetsSelection,
 export { useAcceptInvite, useManyInvites, useRejectInvite, useRequestCancelInvite, useSendInvite, useSingleInvite, } from './hooks/invites.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 { DeclineReason, MapShareErrorCode, getErrorCode, MapShareCanceledError, InvalidStatusTransitionError, } 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, WriteableDocumentType, WriteableValue, } from './lib/types.js';

package/dist/esm/index.js

@@ -3,6 +3,6 @@ export { useClientApi, useIsArchiveDevice, useOwnDeviceInfo, useSetIsArchiveDevi
 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, useImportCustomMapFile, useRemoveCustomMapFile, useGetCustomMapInfo, useManyReceivedMapShares, useSingleReceivedMapShare, useDeclineReceivedMapShare, useDownloadReceivedMapShare, useAbortReceivedMapShareDownload, useSendMapShare, useCancelSentMapShare, useSingleSentMapShare, } from './hooks/maps.js';
-export { DeclineReason } from './lib/map-shares-stores.js';
+export { DeclineReason, MapShareErrorCode, getErrorCode, MapShareCanceledError, InvalidStatusTransitionError, } 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';