Client packages (npm)

Sync Server is plain HTTP, and every guide on this site shows the raw requests. These packages save you writing the same client code again. Both are published under the @imaps scope on npm and ship ESM with TypeScript types. The sign-in client is MIT licensed; the chat is International Mapping software under the licence in the package.

Package	What it does	Docs
@imaps/sync-server-auth	Browser sign-in (popup or redirect), token persistence, authenticated fetch, ArcGIS and MapLibre wiring. Zero dependencies.	Authenticating a browser app
@imaps/ai-chat	An AI assistant with MCP tools, as a React component, <imaps-ai-chat> element, or a MapLibre / ArcGIS widget. Points at a base’s MCP endpoint.	MCP for LLM clients

The packages are currently pre-release (0.0.x-alpha). Install with the alpha dist-tag or pin an exact version; APIs can still change between alphas, and the guides say which version they document.

Install

With a bundler:

npm i @imaps/sync-server-auth
npm i @imaps/ai-chat

Without one, both ship <script>-tag builds that load straight from the npm CDN:

<script src="https://cdn.jsdelivr.net/npm/@imaps/sync-server-auth@alpha/dist/sync-server-auth.iife.js"
        data-server="https://sync.example.com"></script>
<script src="https://cdn.jsdelivr.net/npm/@imaps/ai-chat@alpha/dist/ai-chat.iife.js"></script>

Use the plain dist/ file paths on jsDelivr or unpkg (not /+esm); the builds only use relative imports, so their sibling entry points resolve without a bundler.

How they fit together

One sign-in, then hand the token to everything else: your own fetch calls against the feature service or records API, a map SDK’s request hook, the realtime WebSocket, and the chat’s MCP server entry.

import { createSyncAuth } from '@imaps/sync-server-auth';

const server = 'https://sync.example.com';
const auth = createSyncAuth({ server });
await auth.ensureSignedIn();

const res = await auth.fetch(`${server}/api/v0/bases/appXXXXXXXX/tables/Locations/records?limit=50`);
const ws = new WebSocket(`${server.replace('https', 'wss')}/api/v0/realtime`, [`bearer.${auth.token}`]);
const chatServers = [{ name: 'sync', url: `${server}/api/v0/bases/appXXXXXXXX/mcp`, bearerToken: auth.token }];

@imaps/sync-server-auth

Sign users in from any browser stack and get a short-lived app token. Entry points:

Import	Use when
@imaps/sync-server-auth	Any app; auto-wires the ArcGIS SDK when it is loaded from the CDN
@imaps/sync-server-auth/arcgis	@arcgis/core from npm — registers with IdentityManager and a request interceptor
@imaps/sync-server-auth/maplibre	MapLibre / Mapbox GL — transformRequest and refreshSource built in

import { createSyncAuth } from '@imaps/sync-server-auth/maplibre';

const auth = createSyncAuth({ server: 'https://sync.example.com' });
const map = new maplibregl.Map({ container, style, transformRequest: auth.transformRequest });
signInButton.onclick = () => auth.signIn(); // popup; falls back to redirect if blocked

The full walkthrough, including React / Vue / Svelte bindings, the ArcGIS Maps SDK, the redirect flow and a protocol appendix for doing it without the package, is Authenticating a browser app.

@imaps/ai-chat

A provider-agnostic assistant (Anthropic or OpenAI, bring your own key) whose tools are MCP servers. Give it a base’s MCP endpoint and the caller’s token, and the model can list tables, query features and — with write access — edit, attributed to that person.

<imaps-ai-chat
  servers='[{"name":"sync","url":"https://sync.example.com/api/v0/bases/appXXXXXXXX/mcp","bearerToken":"…"}]'>
</imaps-ai-chat>
<script type="module">import '@imaps/ai-chat/element';</script>

// Beside a MapLibre map, as a control, with the same servers
import { AiChatControl } from '@imaps/ai-chat/maplibre';
map.addControl(new AiChatControl({ chat: { servers: [{ name: 'sync', url: mcpUrl, bearerToken: auth.token }] } }));

@imaps/ai-chat/feature-service adds in-process describe_service / describe_layer / query_features tools over any FeatureServer URL, with no @arcgis/core. Entry points for React, the ArcGIS Expand widget, theming, key storage and the deployment policy are in the package README on npm.