@base44/superagent-native

React Native entrypoint for the Superagent mobile experience.

This package is intentionally native-only. It does not import the web Superagent implementation from frontend/; the mobile app should provide shell concerns such as auth, API clients, analytics, and external navigation through props.

Build

Build the package before consuming or packing it:

npm run build -w @base44/superagent-native

The build emits CommonJS, ES module, and TypeScript declaration files under lib/. The package main, module, types, and react-native entries all resolve to that built output, while source stays pointed at src/index.ts for the Bob build pipeline.

Usage

SuperagentHomeScreen is a self-contained shell: it runs the Superagent runtime internally (agents, channels, connectors, automations, secrets, files, the REST + realtime clients, and every mutation handler) via useSuperagentRuntime, plus the attachment picker. The host passes only what the package cannot produce itself — the auth-backed session, the signed-in user, the build environment, native adapters, and app-shell navigation wiring:

import { useMemo } from 'react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import {
  SuperagentHomeScreen,
  type SuperagentSessionConfig,
  type SuperagentShellAdapters,
} from '@base44/superagent-native';
import { io } from 'socket.io-client';

// The host owns this lifecycle. Reuse the same client for every native navigation root.
const queryClient = new QueryClient();

export function SuperagentRoute() {
  // Build both objects in useMemo — their identity feeds runtime effects.
  const session = useMemo<SuperagentSessionConfig>(
    () => ({
      baseUrl,
      cacheScope: activeWorkspaceId ?? 'personal',
      getAccessToken,
      getHeaders,
      queryClient,
      webUrl,
    }),
    [activeWorkspaceId, baseUrl, webUrl],
  );

  const adapters = useMemo<SuperagentShellAdapters>(
    () => ({
      alert: (title, message) => Alert.alert(title, message),
      confirm: showConfirmDialog,
      openUrl: (url) => Linking.openURL(url),
      createRealtimeSocket: ({ appId, baseUrl, token }) =>
        io(baseUrl, {
          path: '/ws-user-apps/socket.io/',
          query: { app_id: appId, token },
          transports: ['websocket'],
        }),
      liveVoiceAudio,                        // native audio module
      attachments: { pickNativeMedia, isCancel }, // folds in the file/photo/camera picker
      // …subscribeToAppResume / subscribeToDeepLinks / share / pickSandboxFiles …
    }),
    [],
  );

  return (
    <QueryClientProvider client={queryClient}>
      <SuperagentHomeScreen
        session={session}
        user={me}                       // the /me object; the runtime derives id/name/avatar from it
        environment="production"        // 'local' | 'preview' | 'production'
        adapters={adapters}
        navigationMode="external"
        onOpenAgent={(agentId) => pushConversationScreen(agentId)}
        onActiveAgentChange={(agent) => setNativeTitle(agent?.name)}
        onRouteChange={(route) => setTabsVisible(route.name === 'home')}
        onViewPlans={openBillingModal}
      />
    </QueryClientProvider>
  );
}

The createRealtimeSocket adapter creates the socket with the host's own Socket.IO/native setup. Match the web socket contract:

io(wsBaseUrl, {
  path: '/ws-user-apps/socket.io/',
  query: { app_id: appId, token: runtimeAuthToken },
  transports: ['websocket'],
});

Attachment picking is provided through adapters.attachments: the host supplies pickNativeMedia(mode) (returning the picked native media items) and an isCancel(error) predicate, and the package handles the upload and renders the upload-status modal itself. Omit adapters.attachments to hide the composer's file/photo/camera affordances.

const adapters: SuperagentShellAdapters = {
  // …runtime adapters…
  attachments: {
    async pickNativeMedia(mode) {
      // mode: 'files' | 'photos' | 'camera'
      return [{ name: 'photo.jpg', mimeType: 'image/jpeg', uri: localCameraUri }];
    },
    isCancel: (error) => isPickerCancelError(error),
  },
};

Assistant messages render with the built-in native markdown renderer and the package's own tool-call widgets. Both live inside the shell now — the runtime and view are internal, so hosts no longer wire markdown/tool renderers through props.

Publishing

This package is published publicly to npm (registry.npmjs.org) under the @base44 org by the Publish superagent-native workflow. Publishing authenticates via npm Trusted Publishing (OIDC) — there is no long-lived npm token; CI mints a short-lived credential at publish time.

Auto-bump on merge, nothing written to git: you don't touch the version. On every merge to main that changes packages/superagent-native/**, the workflow reads the latest published version from npm, increments the patch, and publishes that — without committing or pushing anything back to the repo. npm is the source of truth for the version; the version field in this package.json is cosmetic and is not used by the publish.

First-time setup only: the package must exist on npm before OIDC works, so the very first version is published manually (pnpm --filter @base44/superagent-native publish --access public), after which the trusted publisher is configured on npmjs.com and all later releases are token-free. See the workflow file header for the exact trusted-publisher values.

Consumers just install it — no registry config needed, it's public:

npm install @base44/superagent-native