@comapeo/core-react 10.0.0 → 11.0.0

package/dist/commonjs/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", { with: { "resolution-mode": "import" } }).MapShareState>;
+    createAndSend({ receiverDeviceId, mapId, }: import("../lib/map-shares-stores.js").CreateAndSendMapShareOptions): Promise<import("@comapeo/map-server", { with: { "resolution-mode": "import" } }).MapShareState>;
     cancel({ shareId }: import("../lib/map-shares-stores.js").CancelMapShareOptions): Promise<void>;
 };
 /**

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

@@ -123,6 +123,7 @@ export declare function useUpdateDocument<D extends WriteableDocumentType>({ doc
     projectId: string;
 }): FilteredMutationResult<UseMutationResult<Awaited<ReturnType<MapeoProjectApi[D]['update']>>, Error, {
     value: Omit<WriteableValue<D>, 'schemaName'>;
+    versionId: string;
 }>>;
 /**
  * Delete a document within a project.

package/dist/commonjs/hooks/documents.js

@@ -199,7 +199,6 @@ function useUpdateDocument({
 docType, projectId, }) {
     const queryClient = (0, react_query_1.useQueryClient)();
     const { data: projectApi } = (0, projects_js_1.useSingleProject)({ projectId });
-    // @ts-expect-error Not sure why TS complains here
     return (0, react_query_js_1.filterMutationResult)((0, react_query_1.useMutation)({
         ...(0, react_query_js_1.baseMutationOptions)(),
         mutationFn: async ({ versionId, value, }) => {

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

@@ -156,15 +156,25 @@ 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.
+ * Use `useManyReceivedMapShares` or `useSingleReceivedMapShare` to track
+ * download progress and final status.
  *
- * Throws if the share is not in `status="pending"` or if the download fails to
- * start (e.g. if the shareId if invalid).
+ * 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 {MapShareCanceledError} 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 {InvalidStatusTransitionError} If the share is not in a valid state
+ *   to start downloading (e.g. already downloading, completed, or declined).
  *
  * @example
  * ```tsx
  * function AcceptButton({ shareId }: { shareId: string }) {
- *   const { mutate: accept } = useAcceptMapShare()
+ *   const { mutate: accept } = useDownloadReceivedMapShare()
  *
  *   return <button onClick={() => accept({ shareId })}>Accept</button>
  * }
@@ -189,17 +199,25 @@ 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.
+ * 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 if the share is not with `status="pending"`
- * Throws if shareId is invalid
- * Throws if decline request fails (e.g. network error)
+ * @throws {MapShareCanceledError} 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 {InvalidStatusTransitionError} If the share is not in
+ *   `status='pending'` (e.g. already downloading, completed, or declined).
  *
  * @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 +247,15 @@ 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 {MapShareCanceledError} If the share is already known to be canceled.
+ * @throws {InvalidStatusTransitionError} If the share is not in
+ *   `status='downloading'` (e.g. still pending, already completed, or
+ *   declined).
  *
  * @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 +284,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 +292,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)
  *                    }

package/dist/commonjs/hooks/maps.js

@@ -182,15 +182,25 @@ 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.
+ * Use `useManyReceivedMapShares` or `useSingleReceivedMapShare` to track
+ * download progress and final status.
  *
- * Throws if the share is not in `status="pending"` or if the download fails to
- * start (e.g. if the shareId if invalid).
+ * 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 {MapShareCanceledError} 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 {InvalidStatusTransitionError} If the share is not in a valid state
+ *   to start downloading (e.g. already downloading, completed, or declined).
  *
  * @example
  * ```tsx
  * function AcceptButton({ shareId }: { shareId: string }) {
- *   const { mutate: accept } = useAcceptMapShare()
+ *   const { mutate: accept } = useDownloadReceivedMapShare()
  *
  *   return <button onClick={() => accept({ shareId })}>Accept</button>
  * }
@@ -207,17 +217,25 @@ function useDownloadReceivedMapShare() {
 }
 /**
  * Decline a map share that has been received. Notifies the sender that the
- * share was declined.
+ * 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 if the share is not with `status="pending"`
- * Throws if shareId is invalid
- * Throws if decline request fails (e.g. network error)
+ * @throws {MapShareCanceledError} 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 {InvalidStatusTransitionError} If the share is not in
+ *   `status='pending'` (e.g. already downloading, completed, or declined).
  *
  * @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 })}>
@@ -239,13 +257,15 @@ function useDeclineReceivedMapShare() {
 /**
  * Abort an in-progress map share download.
  *
- * Throws if the share is not in `status="downloading"`
- * Throws if shareId is invalid
+ * @throws {MapShareCanceledError} If the share is already known to be canceled.
+ * @throws {InvalidStatusTransitionError} If the share is not in
+ *   `status='downloading'` (e.g. still pending, already completed, or
+ *   declined).
  *
  * @example
  * ```tsx
  * function AbortButton({ shareId }: { shareId: string }) {
- *   const { mutate: abort } = useAbortMapShareDownload()
+ *   const { mutate: abort } = useAbortReceivedMapShareDownload()
  *
  *   return <button onClick={() => abort({ shareId })}>Cancel Download</button>
  * }
@@ -269,8 +289,6 @@ 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 }) {
@@ -279,7 +297,7 @@ 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)
  *                    }

package/dist/commonjs/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/commonjs/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useRemoveServerPeer = exports.useProjectSettings = exports.useProjectOwnRoleChangeListener = exports.useOwnRoleInProject = exports.useManyProjects = exports.useManyMembers = exports.useLeaveProject = exports.useImportProjectConfig = exports.useImportProjectCategories = exports.useIconUrl = exports.useDocumentCreatedBy = exports.useDisconnectSyncServers = exports.useDataSyncProgress = exports.useCreateProject = exports.useCreateBlob = exports.useConnectSyncServers = exports.useAttachmentUrl = exports.useAddServerPeer = exports.DeclineReason = exports.useSingleSentMapShare = exports.useCancelSentMapShare = exports.useSendMapShare = exports.useAbortReceivedMapShareDownload = exports.useDownloadReceivedMapShare = exports.useDeclineReceivedMapShare = exports.useSingleReceivedMapShare = exports.useManyReceivedMapShares = exports.useGetCustomMapInfo = exports.useRemoveCustomMapFile = exports.useImportCustomMapFile = exports.useMapStyleUrl = exports.useSingleInvite = exports.useSendInvite = exports.useRequestCancelInvite = exports.useRejectInvite = exports.useManyInvites = exports.useAcceptInvite = exports.useUpdateDocument = exports.useSingleDocByVersionId = exports.useSingleDocByDocId = exports.usePresetsSelection = exports.useManyDocs = exports.useDeleteDocument = exports.useCreateDocument = exports.useSetOwnDeviceInfo = exports.useSetIsArchiveDevice = exports.useOwnDeviceInfo = exports.useIsArchiveDevice = exports.useClientApi = exports.ComapeoCoreProvider = void 0;
-exports.isHTTPError = exports.HTTPError = exports.useExportZipFile = exports.useExportGeoJSON = exports.useChangeMemberRole = exports.useUpdateProjectSettings = exports.useSyncState = exports.useStopSync = exports.useStartSync = exports.useSingleProject = exports.useSingleMember = exports.useSetAutostopDataSyncTimeout = exports.useRemoveMember = void 0;
+exports.useManyProjects = exports.useManyMembers = exports.useLeaveProject = exports.useImportProjectConfig = exports.useImportProjectCategories = exports.useIconUrl = exports.useDocumentCreatedBy = exports.useDisconnectSyncServers = exports.useDataSyncProgress = exports.useCreateProject = exports.useCreateBlob = exports.useConnectSyncServers = exports.useAttachmentUrl = exports.useAddServerPeer = exports.InvalidStatusTransitionError = exports.MapShareCanceledError = exports.getErrorCode = exports.MapShareErrorCode = exports.DeclineReason = exports.useSingleSentMapShare = exports.useCancelSentMapShare = exports.useSendMapShare = exports.useAbortReceivedMapShareDownload = exports.useDownloadReceivedMapShare = exports.useDeclineReceivedMapShare = exports.useSingleReceivedMapShare = exports.useManyReceivedMapShares = exports.useGetCustomMapInfo = exports.useRemoveCustomMapFile = exports.useImportCustomMapFile = exports.useMapStyleUrl = exports.useSingleInvite = exports.useSendInvite = exports.useRequestCancelInvite = exports.useRejectInvite = exports.useManyInvites = exports.useAcceptInvite = exports.useUpdateDocument = exports.useSingleDocByVersionId = exports.useSingleDocByDocId = exports.usePresetsSelection = exports.useManyDocs = exports.useDeleteDocument = exports.useCreateDocument = exports.useSetOwnDeviceInfo = exports.useSetIsArchiveDevice = exports.useOwnDeviceInfo = exports.useIsArchiveDevice = exports.useClientApi = exports.ComapeoCoreProvider = void 0;
+exports.isHTTPError = exports.HTTPError = exports.useExportZipFile = exports.useExportGeoJSON = exports.useChangeMemberRole = exports.useUpdateProjectSettings = exports.useSyncState = exports.useStopSync = exports.useStartSync = exports.useSingleProject = exports.useSingleMember = exports.useSetAutostopDataSyncTimeout = exports.useRemoveMember = exports.useRemoveServerPeer = exports.useProjectSettings = exports.useProjectOwnRoleChangeListener = exports.useOwnRoleInProject = void 0;
 var ComapeoCore_js_1 = require("./contexts/ComapeoCore.js");
 Object.defineProperty(exports, "ComapeoCoreProvider", { enumerable: true, get: function () { return ComapeoCore_js_1.ComapeoCoreProvider; } });
 var client_js_1 = require("./hooks/client.js");
@@ -40,6 +40,10 @@ Object.defineProperty(exports, "useCancelSentMapShare", { enumerable: true, get:
 Object.defineProperty(exports, "useSingleSentMapShare", { enumerable: true, get: function () { return maps_js_1.useSingleSentMapShare; } });
 var map_shares_stores_js_1 = require("./lib/map-shares-stores.js");
 Object.defineProperty(exports, "DeclineReason", { enumerable: true, get: function () { return map_shares_stores_js_1.DeclineReason; } });
+Object.defineProperty(exports, "MapShareErrorCode", { enumerable: true, get: function () { return map_shares_stores_js_1.MapShareErrorCode; } });
+Object.defineProperty(exports, "getErrorCode", { enumerable: true, get: function () { return map_shares_stores_js_1.getErrorCode; } });
+Object.defineProperty(exports, "MapShareCanceledError", { enumerable: true, get: function () { return map_shares_stores_js_1.MapShareCanceledError; } });
+Object.defineProperty(exports, "InvalidStatusTransitionError", { enumerable: true, get: function () { return map_shares_stores_js_1.InvalidStatusTransitionError; } });
 var projects_js_1 = require("./hooks/projects.js");
 Object.defineProperty(exports, "useAddServerPeer", { enumerable: true, get: function () { return projects_js_1.useAddServerPeer; } });
 Object.defineProperty(exports, "useAttachmentUrl", { enumerable: true, get: function () { return projects_js_1.useAttachmentUrl; } });

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

@@ -9,6 +9,107 @@ export type ReceivedMapShareState = DistributedIntersection<Simplify<MapShare>,
 export type SentMapShareState = ServerMapShareState;
 export type ReceivedMapSharesStore = ReturnType<typeof createReceivedMapSharesStore>;
 export type SentMapSharesStore = ReturnType<typeof createSentMapSharesStore>;
+/**
+ * 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?"
+ *   }
+ * }
+ * ```
+ */
+export declare const MapShareErrorCode: {
+    /** Receiver: the sender canceled the share before the action could complete */
+    readonly MAP_SHARE_CANCELED: "MAP_SHARE_CANCELED";
+    /** Receiver/Sender: the action is not valid for the share's current status */
+    readonly INVALID_STATUS_TRANSITION: "INVALID_STATUS_TRANSITION";
+    /** Receiver/Sender: no map share with the given `shareId` exists in the store */
+    readonly MAP_SHARE_NOT_FOUND: "MAP_SHARE_NOT_FOUND";
+    /** Receiver: abort was called but no download is tracked for this share */
+    readonly DOWNLOAD_NOT_FOUND: "DOWNLOAD_NOT_FOUND";
+    /** Receiver: the download failed due to a network, disk, or server error */
+    readonly DOWNLOAD_ERROR: "DOWNLOAD_ERROR";
+    /** Receiver: could not connect to the sender to notify them of the decline */
+    readonly DECLINE_CANNOT_CONNECT: "DECLINE_CANNOT_CONNECT";
+    /** Sender: cancel failed because the share is already in a final state on the server */
+    readonly CANCEL_SHARE_NOT_CANCELABLE: "CANCEL_SHARE_NOT_CANCELABLE";
+    /** Receiver/Sender: fallback code when the original error has no specific code */
+    readonly 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
+ *   }
+ * }
+ * ```
+ */
+export declare function getErrorCode(error: unknown): string | undefined;
 /** Known reasons for declining a map share */
 export declare const DeclineReason: {
     /** User explicitly rejected the map share */
@@ -35,8 +136,6 @@ export type AbortMapShareOptions = {
 };
 /** 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 */
@@ -47,6 +146,24 @@ export type CancelMapShareOptions = {
     /** ID of the map share to cancel */
     shareId: string;
 };
+/**
+ * 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'`.
+ */
+export declare class MapShareCanceledError extends Error {
+    code: "MAP_SHARE_CANCELED";
+    constructor(shareId: string);
+}
+/**
+ * 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'`.
+ */
+export declare class InvalidStatusTransitionError extends Error {
+    code: "INVALID_STATUS_TRANSITION";
+    constructor(current: string, next: string);
+}
 /**
  * Store and actions for received map shares.
  */
@@ -73,7 +190,7 @@ export declare function createSentMapSharesStore({ clientApi, mapServerApi, }: {
     subscribe: (listener: () => void) => () => boolean;
     getSnapshot: () => ServerMapShareState[];
     actions: {
-        createAndSend({ projectId, receiverDeviceId, mapId, }: CreateAndSendMapShareOptions): Promise<ServerMapShareState>;
+        createAndSend({ receiverDeviceId, mapId, }: CreateAndSendMapShareOptions): Promise<ServerMapShareState>;
         cancel({ shareId }: CancelMapShareOptions): Promise<void>;
     };
 };

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 = [