@comapeo/core-react 10.0.1 → 11.0.1

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/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/commonjs/hooks/maps.js

@@ -163,6 +163,9 @@ 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 }) {
@@ -175,22 +178,35 @@ function useManyReceivedMapShares() {
 function useSingleReceivedMapShare({ shareId }) {
     const mapShare = (0, MapShares_js_1.useReceivedMapSharesState)((0, react_1.useCallback)((shares) => shares.find((s) => s.shareId === shareId), [shareId]));
     if (!mapShare) {
-        throw new Error(`Map share with id ${shareId} not found`);
+        throw new errors_js_1.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>
  * }
@@ -207,17 +223,28 @@ 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 })}>
@@ -239,13 +266,20 @@ 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>
  * }
@@ -269,8 +303,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 +311,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)
  *                    }
@@ -308,6 +340,12 @@ 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
@@ -333,7 +371,8 @@ 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/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>;
     };
 };