feat: Add map sharing API by gmaclennan · Pull Request #143 · digidem/comapeo-core-react

gmaclennan · 2025-11-25T17:03:09Z

Map Sharing Hooks

Adds React hooks for sharing maps between devices. The API separates receiver and sender functionality.

Receiver Hooks

useManyReceivedMapShares() - List all received map shares. Updates when shares arrive or status changes (but not during download progress updates).
useSingleReceivedMapShare({ shareId }) - Get a specific received share with real-time updates including download progress.
useDownloadReceivedMapShare() - Accept and start downloading a share. Resolves when download starts, not when complete.
useDeclineReceivedMapShare() - Decline a pending share. Notifies the sender.
useAbortReceivedMapShareDownload() - Cancel an in-progress download.

Sender Hooks

useSendMapShare({ projectId }) - Send a map to another device. Resolves immediately with the share object (doesn't wait for recipient response).
useSingleSentMapShare({ shareId }) - Track a sent share's status in real-time (pending, downloading, declined, canceled).
useCancelSentMapShare() - Cancel a sent share before the recipient completes the download.

Example Usage

// Receiving a map share
function ReceivedShareScreen({ shareId }: { shareId: string }) {
  const share = useSingleReceivedMapShare({ shareId })
  const { mutate: download } = useDownloadReceivedMapShare()
  const { mutate: decline } = useDeclineReceivedMapShare()

  if (share.status === 'downloading') {
    return <div>Downloading: {share.downloadProgress}%</div>
  }

  return (
    <div>
      <div>{share.mapName} from {share.senderDeviceName}</div>
      <button onClick={() => download({ shareId })}>Accept</button>
      <button onClick={() => decline({ shareId, reason: 'user_rejected' })}>Decline</button>
    </div>
  )
}

// Sending a map share
function SendMapScreen({ projectId, deviceId }: { projectId: string; deviceId: string }) {
  const [shareId, setShareId] = useState<string | null>(null)
  const { mutate: send } = useSendMapShare({ projectId })

  const handleSend = () => {
    send(
      { receiverDeviceId: deviceId, mapId: 'custom' },
      { onSuccess: (share) => setShareId(share.shareId) }
    )
  }

  if (shareId) {
    return <SentShareStatus shareId={shareId} />
  }

  return <button onClick={handleSend}>Send Map</button>
}

function SentShareStatus({ shareId }: { shareId: string }) {
  const share = useSingleSentMapShare({ shareId })

  return (
    <div>
      {share.status === 'pending' && <div>Waiting for recipient...</div>}
      {share.status === 'downloading' && <div>Recipient downloading: {share.downloadProgress}%</div>}
      {share.status === 'completed' && <div>Map shared successfully</div>}
      {share.status === 'declined' && <div>Recipient declined</div>}
    </div>
  )
}

gmaclennan · 2025-11-25T17:38:56Z

I think maybe the useSendMapShare() API needs work - let me know @ErikSin & @cimigree how you are planning to implement this from the sender's side and we can maybe adjust this API so it works for that.

ErikSin

There are a few event emitters/listeners needed.

The ui is designed to constantly be listening in the background and notify the user when a map has been shared. So there needs to be some listener function that invalidates the useManyMapShares function when a map get shared that lives at the top of the app
Similar to invites, the person receiving the map needs to also listen in the background for when the person sending the map has cancelled sending the map. This has to be listener because it can happen at any time during the process.
As mentioned in the comments, if we want to show progress of the map being downloaded, the map sharing function needs to be an event emitter. As it is now, there is no way to show the progress in the ui as it an async function that will just return one object when resolved at the end.

src/hooks/maps.ts

src/lib/react-query/maps.ts

cimigree

I agree with what Erik said. Thanks for the thorough review, Erik. I added a few things that I noticed as well.

src/lib/react-query/maps.ts

src/hooks/maps.ts

src/lib/react-query/maps.ts

cimigree · 2025-12-09T19:08:31Z

Hi, @gmaclennan
I tried using the tgz file but found a few issues that I think need code changes in the PR before they are ready to really use.

The map share hooks (useSendMapShare, useRequestCancelMapShare, useManyMapShares, useSingleMapShare, useAcceptMapShare, useRejectMapShare) exist in src/hooks/maps.ts but aren't exported from src/index.ts - only useMapStyleUrl is exported. Could you add them to the main index exports?
Missing useSetUpInvitesListeners: This hooks seems to have disappeared? And that is causing a crash. I can't remember why that is and what I should do about it. It's not in any changes in here...
Naming correction: The tgz file I have still has the old useRequestCancelInvite name.
Once these are fixed, could you generate an updated tgz? For now, I'm importing the hooks directly from dist/esm/hooks/maps.js with a @ts-expect-error comment to test the UI. Thanks! Or please advise if there is anything I should be doing differently.

achou11 · 2025-12-09T19:16:21Z

@cimigree

1. The map share hooks (useSendMapShare, useRequestCancelMapShare, useManyMapShares, useSingleMapShare, useAcceptMapShare, useRejectMapShare) exist in src/hooks/maps.ts but aren't exported from src/index.ts - only useMapStyleUrl is exported. Could you add them to the main index exports?

I can update this branch to export those hooks!

2. Missing useSetUpInvitesListeners: This hooks seems to have disappeared? And that is causing a crash. I can't remember why that is and what I should do about it. It's not in any changes in here...

Yes this is branch is based off of main, which includes the changes from #141 . You no longer need to use that hook as it's done automatically when setting up the api client provider.

3. Naming correction: The tgz file I have still has the old useRequestCancelInvite name.
   Once these are fixed, could you generate an updated tgz? For now, I'm importing the hooks directly from dist/esm/hooks/maps.js with a @ts-expect-error comment to test the UI. Thanks! Or please advise if there is anything I should be doing differently.

Can fix this for you. ~~Also worth noting that Gregor included instructions about generating the tarball yourself in the PR description, if you want to take it into your own hands.~~ EDIT: Think I was confusing this for a different conversation I was having with Erik where I instructed him on how to generate it. In a nutshell:

Clone this branch
Run npm pack
Use the generated tarball file based on the instructions Gregor wrote in the PR description

achou11 · 2025-12-09T19:23:00Z

@cimigree Updated the package exports via 371e486.

Shared a tarball with you on Slack, but if you need/prefer to generate your own, you can follow the steps I outlined in my previous comment

gmaclennan · 2025-12-10T18:11:04Z

I didn't catch this today until now, but thank you @achou11 for responding to these questions. I think @cimigree you have what you need for now, but let me know otherwise.

gmaclennan · 2025-12-10T18:15:28Z

I will try and re-visit this API tomorrow now that I've got further into the implementation. We will actually need two similar APIs I think for managing the map shares from the sender side and from the receiver side. They are subtly different and I think this current API design maybe conflates the two. It could be possible to make this current API design work for both I guess - I'll look into this.

gmaclennan · 2025-12-11T14:53:36Z

@cimigree & @ErikSin : So after implementing this, I realize there is a slight confusion with this API with the distinction between sent map shares and received map shares, which I imagine you have encountered when you are implementing this? For the API we have a couple of options:

We keep the current API, but add a discriminator on the MapShare objects, so that you can filter by it to get only sent or received map shares as needed.
We have separate APIs for sent and received map shares, e.g. useSentMapShares() and useReceivedMapShares().

Which do you think would be preferable to work with? I am thinking (2) is better because you there would never be a use-case for reading both sent and received map shares at the same time, and it would complicate the effects (e.g. showing the share offer screen) when the value updates.

* main: chore: update deps and actions (#148)

awana-lockfile-bot · 2026-02-11T17:47:28Z

`package-lock.json` changes

Summary

Status	Count
	57
	85

Click to toggle table visibility

Name	Previous	Current
`@acemir/cssom`	-	0.9.31
`@asamuzakjp/css-color`	-	4.1.2
`@asamuzakjp/dom-selector`	-	6.7.8
`@asamuzakjp/nwsapi`	-	2.3.9
`@augment-vir/common`	-	26.4.0
`@babel/code-frame`	7.27.1	7.29.0
`@babel/compat-data`	7.28.5	7.29.0
`@babel/core`	7.28.5	7.29.0
`@babel/generator`	7.28.5	7.29.1
`@babel/helper-compilation-targets`	7.27.2	7.28.6
`@babel/helper-module-imports`	7.27.1	7.28.6
`@babel/helper-module-transforms`	7.28.3	7.28.6
`@babel/helpers`	7.28.4	7.28.6
`@babel/parser`	7.28.5	7.29.0
`@babel/template`	7.27.2	7.28.6
`@babel/traverse`	7.28.5	7.29.0
`@babel/types`	7.28.5	7.29.0
`@comapeo/core`	5.2.1	5.4.0
`@comapeo/map-server`	-	1.0.0-pre.6
`@csstools/color-helpers`	-	6.0.1
`@csstools/css-calc`	-	3.0.1
`@csstools/css-color-parser`	-	4.0.1
`@csstools/css-parser-algorithms`	-	4.0.0
`@csstools/css-syntax-patches-for-csstree`	-	1.0.27
`@csstools/css-tokenizer`	-	4.0.0
`@emnapi/core`	1.5.0	1.8.1
`@emnapi/runtime`	1.5.0	1.8.1
`@esbuild/aix-ppc64`	0.25.12	0.27.3
`@esbuild/android-arm`	0.25.12	0.27.3
`@esbuild/android-arm64`	0.25.12	0.27.3
`@esbuild/android-x64`	0.25.12	0.27.3
`@esbuild/darwin-arm64`	0.25.12	0.27.3
`@esbuild/darwin-x64`	0.25.12	0.27.3
`@esbuild/freebsd-arm64`	0.25.12	0.27.3
`@esbuild/freebsd-x64`	0.25.12	0.27.3
`@esbuild/linux-arm`	0.25.12	0.27.3
`@esbuild/linux-arm64`	0.25.12	0.27.3
`@esbuild/linux-ia32`	0.25.12	0.27.3
`@esbuild/linux-loong64`	0.25.12	0.27.3
`@esbuild/linux-mips64el`	0.25.12	0.27.3
`@esbuild/linux-ppc64`	0.25.12	0.27.3
`@esbuild/linux-riscv64`	0.25.12	0.27.3
`@esbuild/linux-s390x`	0.25.12	0.27.3
`@esbuild/linux-x64`	0.25.12	0.27.3
`@esbuild/netbsd-arm64`	0.25.12	0.27.3
`@esbuild/netbsd-x64`	0.25.12	0.27.3
`@esbuild/openbsd-arm64`	0.25.12	0.27.3
`@esbuild/openbsd-x64`	0.25.12	0.27.3
`@esbuild/openharmony-arm64`	0.25.12	0.27.3
`@esbuild/sunos-x64`	0.25.12	0.27.3
`@esbuild/win32-arm64`	0.25.12	0.27.3
`@esbuild/win32-ia32`	0.25.12	0.27.3
`@esbuild/win32-x64`	0.25.12	0.27.3
`@eslint-community/eslint-utils`	4.9.0	4.9.1
`@eslint/core`	1.0.0	1.1.0
`@exodus/bytes`	-	1.13.0
`@fastify/forwarded`	-	3.0.1
`@fastify/proxy-addr`	-	5.1.0
`@jridgewell/source-map`	-	0.3.11
`@pinojs/redact`	-	0.4.0
`@rollup/rollup-android-arm-eabi`	4.53.3	4.57.1
`@rollup/rollup-android-arm64`	4.53.3	4.57.1
`@rollup/rollup-darwin-arm64`	4.53.3	4.57.1
`@rollup/rollup-darwin-x64`	4.53.3	4.57.1
`@rollup/rollup-freebsd-arm64`	4.53.3	4.57.1
`@rollup/rollup-freebsd-x64`	4.53.3	4.57.1
`@rollup/rollup-linux-arm-gnueabihf`	4.53.3	4.57.1
`@rollup/rollup-linux-arm-musleabihf`	4.53.3	4.57.1
`@rollup/rollup-linux-arm64-gnu`	4.53.3	4.57.1
`@rollup/rollup-linux-arm64-musl`	4.53.3	4.57.1
`@rollup/rollup-linux-loong64-gnu`	4.53.3	4.57.1
`@rollup/rollup-linux-loong64-musl`	-	4.57.1
`@rollup/rollup-linux-ppc64-gnu`	4.53.3	4.57.1
`@rollup/rollup-linux-ppc64-musl`	-	4.57.1
`@rollup/rollup-linux-riscv64-gnu`	4.53.3	4.57.1
`@rollup/rollup-linux-riscv64-musl`	4.53.3	4.57.1
`@rollup/rollup-linux-s390x-gnu`	4.53.3	4.57.1
`@rollup/rollup-linux-x64-gnu`	4.53.3	4.57.1
`@rollup/rollup-linux-x64-musl`	4.53.3	4.57.1
`@rollup/rollup-openbsd-x64`	-	4.57.1
`@rollup/rollup-openharmony-arm64`	4.53.3	4.57.1
`@rollup/rollup-win32-arm64-msvc`	4.53.3	4.57.1
`@rollup/rollup-win32-ia32-msvc`	4.53.3	4.57.1
`@rollup/rollup-win32-x64-gnu`	4.53.3	4.57.1
`@rollup/rollup-win32-x64-msvc`	4.53.3	4.57.1
`@standard-schema/spec`	1.0.0	1.1.0
`@types/jsdom`	-	27.0.0
`@types/tough-cookie`	-	4.0.5
`@typescript-eslint/scope-manager`	8.49.0	8.55.0
`@typescript-eslint/types`	8.49.0	8.55.0
`@typescript-eslint/visitor-keys`	8.49.0	8.55.0
`agent-base`	-	7.1.4
`ansi-escapes`	7.2.0	7.3.0
`baseline-browser-mapping`	2.9.7	2.9.19
`bidi-js`	-	1.0.3
`browser-or-node`	-	2.1.1
`buffer-from`	-	1.1.2
`caniuse-lite`	1.0.30001760	1.0.30001769
`chai`	6.2.1	6.2.2
`commander`	14.0.2	14.0.3
`cssstyle`	-	5.3.7
`data-urls`	-	7.0.0
`decimal.js`	-	10.6.0
`electron-to-chromium`	1.5.267	1.5.286
`ensure-error`	4.0.0	5.0.0
`esbuild`	0.25.12	0.27.3
`eventsource-client`	-	1.2.0
`eventsource-parser`	-	3.0.6
`html-encoding-sniffer`	-	6.0.0
`http-proxy-agent`	-	7.0.2
`https-proxy-agent`	-	7.0.6
`is-potential-custom-element-name`	-	1.0.1
`itty-router`	-	5.0.22
`jsdom`	-	28.0.0
`ky`	1.10.0	1.14.3
`p-mutex`	-	0.1.0
`parse5`	-	8.0.0
`rollup`	4.53.3	4.57.1
`run-time-assertions`	-	1.5.2
`saxes`	-	6.0.0
`secret-stream-http`	-	1.0.1
`semver`	7.7.2	7.7.4
`source-map-support`	-	0.5.21
`symbol-tree`	-	3.2.4
`terser`	-	5.46.0
`tldts-core`	-	7.0.23
`tldts`	-	7.0.23
`tough-cookie`	-	6.0.0
`tr46`	-	6.0.0
`ts-api-utils`	2.1.0	2.4.0
`type-fest`	4.41.0	5.4.3
`typebox`	-	1.0.79
`typed-event-target`	-	3.4.0
`uint8array-extras`	-	1.5.0
`update-browserslist-db`	1.2.2	1.2.3
`vite`	7.2.7	7.3.1
`w3c-xmlserializer`	-	5.0.0
`webidl-conversions`	-	8.0.1
`whatwg-url`	-	16.0.0
`xml-name-validator`	-	5.0.0
`xmlchars`	-	2.2.0
`zod`	4.1.13	4.3.6

socket-security · 2026-02-11T17:48:00Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Package	Quality	Maintenance
@types/jsdom@27.0.0
@comapeo/map-server@1.0.0-pre.6
@comapeo/core@5.2.1 ⏵ 5.4.0	⁺¹	^-1
uint8array-extras@1.5.0
eventsource-client@1.2.0
ensure-error@5.0.0
ky@1.10.0 ⏵ 1.14.3	⁺¹	⁺¹
jsdom@28.0.0
type-fest@5.1.0 ⏵ 5.4.3	⁺¹

View full report

gmaclennan · 2026-02-11T18:25:43Z

I've updated the PR description with the completed API. This is now ready for review.

gmaclennan · 2026-02-11T18:56:00Z

@achou11 there are a couple more hooks tests still pending (download progress related) and I think maybe I can delete the unit tests for the stores, which are now testing an implementation detail, once I verify that the hooks tests are covering the same things (I created the stores tests first so I could fix bugs before writing the hooks). I added a helper filterResult to reduce some boilerplate but I might update that to a more generic pick(result, keys). I didn't use that helper for any existing hooks - you can do that in a separate PR if you like.
What do you think about exporting a general provider CoMapeoCoreProvider that combines all the providers into one (including tanstack query) ?

socket-security · 2026-02-13T13:35:08Z

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

View full report

gmaclennan · 2026-02-13T18:47:49Z

The latest changes may/should address the react native Request compatibility issues by removing ky and using a simpler wrapper for reducing fetch boiler plate. 0430f7a also adds hooks for importing, deleting and getting map info about the custom map. These replace the hooks currently in the mobile app code.

cimigree · 2026-02-13T21:31:38Z

The latest changes may/should address the react native Request compatibility issues by removing ky and using a simpler wrapper for reducing fetch boiler plate. 0430f7a also adds hooks for importing, deleting and getting map info about the custom map. These replace the hooks currently in the mobile app code.

So sorry but it doesn't seem to be working or I need more guidance on how to use.
digidem/comapeo-mobile#1693 (comment)

feat: Add stubbed map sharing API

0825b6b

gmaclennan self-assigned this Nov 25, 2025

ErikSin reviewed Nov 26, 2025

View reviewed changes

cimigree requested changes Nov 26, 2025

View reviewed changes

src/lib/react-query/maps.ts Outdated Show resolved Hide resolved

src/hooks/maps.ts Show resolved Hide resolved

src/lib/react-query/maps.ts Outdated Show resolved Hide resolved

src/lib/react-query/maps.ts Outdated Show resolved Hide resolved

gmaclennan added 5 commits December 1, 2025 18:00

fix naming & jsdoc for useRequestCancelMapShare

26b4e28

fix MapShare type

7ee3fbd

Return shareId from accept map share mutation.

69a1cea

increase timeout for sendMapShare stub

a024869

Add reason to reject response

1af841d

gmaclennan mentioned this pull request Dec 3, 2025

Create map share API in @comapeo/core-react digidem/comapeo-core#1187

Closed

gmaclennan linked an issue Dec 3, 2025 that may be closed by this pull request

Create map share API in @comapeo/core-react digidem/comapeo-core#1187

Closed

gmaclennan mentioned this pull request Dec 3, 2025

Hook up stubbed map share API to backend #147

Open

ErikSin mentioned this pull request Dec 9, 2025

feat: adds waiting for map share accept digidem/comapeo-mobile#1621

Closed

add other map hooks to package exports

371e486

gmaclennan added 9 commits January 27, 2026 22:07

initial integration with map-server (WIP)

5111aa4

MapServerContext impl

9e9fe6d

WIP received map shares store

8a01ddd

add map shares stores

c8a5746

wrap providers in single provider

586e92d

cleanup and fix

6d346ad

finish up implementation

aab58d0

add hooks tests

9ab5364

Merge branch 'main' into feat/map-sharing

4e0e989

* main: chore: update deps and actions (#148)

update package-lock

ace042e

gmaclennan added 2 commits February 11, 2026 18:00

update readme and docs

0a2b962

fix useMapStyleUrl test & types

536f3a5

gmaclennan changed the title ~~feat: Add stubbed map sharing API~~ feat: Add map sharing API Feb 11, 2026

gmaclennan added 2 commits February 11, 2026 18:29

fix types and lint errors

0eaaf91

fix linting errors

66e0746

gmaclennan requested a review from achou11 February 11, 2026 18:30

gmaclennan added 7 commits February 11, 2026 22:17

update to latest map-server

6e140d3

add download progress tests

a71b9e4

add additional tests for error paths

df658b0

fix dependencies

6e5f63e

fix: map style json URL should use 'default' not 'custom'

b5c84d4

feat: map import, delete & info hooks

0430f7a

support expo File for map import

0a6bf97

gmaclennan added 2 commits February 13, 2026 18:44

remove expo-file-system dep

cec8afa

don't use ky at runtime for expo compat

22f6d95

gmaclennan mentioned this pull request Feb 13, 2026

feat: waiting map accept digidem/comapeo-mobile#1693

Draft

gmaclennan added 5 commits February 16, 2026 16:39

fix: use uppercase method names for requests

fdb2443

fix: don't use suspense for map info query

1a3d354

parse json for response errors

fe3d245

consistent HTTPErrors

ac30cbd

fix: expo/fetch only accepts string not URL as input

bbcf530

Conversation

gmaclennan commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Map Sharing Hooks

Receiver Hooks

Sender Hooks

Example Usage

Uh oh!

gmaclennan commented Nov 25, 2025

Uh oh!

ErikSin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cimigree left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cimigree commented Dec 9, 2025

Uh oh!

achou11 commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

achou11 commented Dec 9, 2025

Uh oh!

gmaclennan commented Dec 10, 2025

Uh oh!

gmaclennan commented Dec 10, 2025

Uh oh!

gmaclennan commented Dec 11, 2025

Uh oh!

awana-lockfile-bot bot commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

package-lock.json changes

Summary

Uh oh!

socket-security bot commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gmaclennan commented Feb 11, 2026

Uh oh!

gmaclennan commented Feb 11, 2026

Uh oh!

socket-security bot commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gmaclennan commented Feb 13, 2026

Uh oh!

cimigree commented Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

gmaclennan commented Nov 25, 2025 •

edited

Loading

achou11 commented Dec 9, 2025 •

edited

Loading

awana-lockfile-bot bot commented Feb 11, 2026 •

edited

Loading

`package-lock.json` changes

socket-security bot commented Feb 11, 2026 •

edited

Loading

socket-security bot commented Feb 13, 2026 •

edited

Loading