@comapeo/core-react 10.0.0 → 11.0.0

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/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/esm/hooks/documents.js

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

package/dist/esm/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/esm/hooks/maps.js

@@ -168,15 +168,25 @@ export 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>
  * }
@@ -193,17 +203,25 @@ export 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 })}>
@@ -225,13 +243,15 @@ 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 {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>
  * }
@@ -255,8 +275,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 +283,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)
  *                    }

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';

package/dist/esm/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/esm/lib/map-shares-stores.js

@@ -8,6 +8,118 @@ import { invalidateMapQueries } from './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?"
+ *   }
+ * }
+ * ```
+ */
+export const 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
+ *   }
+ * }
+ * ```
+ */
+export 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 */
 export const DeclineReason = {
     /** User explicitly rejected the map share */
@@ -15,6 +127,30 @@ export const 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'`.
+ */
+export class MapShareCanceledError extends Error {
+    code = 'MAP_SHARE_CANCELED';
+    constructor(shareId) {
+        super(`Map share ${shareId} has been canceled by the sender`);
+        this.name = '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'`.
+ */
+export class InvalidStatusTransitionError extends Error {
+    code = 'INVALID_STATUS_TRANSITION';
+    constructor(current, next) {
+        super(`Invalid status transition from ${current} to ${next}`);
+        this.name = '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
@@ -135,6 +271,13 @@ export function createReceivedMapSharesStore({ clientApi, mapServerApi, queryCli
     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
@@ -176,22 +319,39 @@ export function createReceivedMapSharesStore({ clientApi, mapServerApi, queryCli
         },
         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 = ensureError(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);
@@ -221,15 +381,14 @@ export function createReceivedMapSharesStore({ clientApi, mapServerApi, queryCli
 export function createSentMapSharesStore({ clientApi, mapServerApi, }) {
     const { subscribe, getSnapshot, update, add, handleError, monitor } = createMapSharesStore({ mapServerApi });
     const actions = {
-        async createAndSend({ projectId, receiverDeviceId, mapId = CUSTOM_MAP_ID, }) {
+        async createAndSend({ receiverDeviceId, mapId = 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`);
@@ -271,7 +430,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 = [