@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

import { useMemo } from 'react';
import {
  SuperagentHomeScreen,
  createSuperagentNativeClient,
  createSuperagentSocketClient,
} from '@base44/superagent-native';

export function SuperagentRoute() {
  const apiClient = useMemo(
    () => createSuperagentNativeClient({ apiBaseUrl, appId, getAuthToken }),
    [apiBaseUrl, appId],
  );

  const realtimeClient = useMemo(
    () => createSuperagentSocketClient({ socket: userAppsSocket }),
    [userAppsSocket],
  );

  return (
    <SuperagentHomeScreen
      agents={agents}
      apiClient={apiClient}
      messagesByAgentId={messagesByAgentId}
      onCreateAgent={createAgent}
      onOpenAgent={(agentId) => console.log(agentId)}
      onPickFiles={pickAndUploadFiles}
      onStartVoiceInput={recordAndTranscribe}
      onTakePhoto={takePhotoAndUpload}
      onSendMessage={({ agentId, fileUrls, message }) => sendMessage(agentId, message, fileUrls)}
      realtimeClient={realtimeClient}
      toolRenderers={{
        ask_for_approval: ApprovalToolWidget,
      }}
    />
  );
}

The consuming app should create userAppsSocket with its own Socket.IO/native dependency setup. Match the web socket contract:

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

Media callbacks are implemented by the consuming native app:

async function recordAndTranscribe() {
  return transcribedText;
}

async function takePhotoAndUpload() {
  return {
    kind: 'image',
    mimeType: 'image/jpeg',
    name: 'photo.jpg',
    previewUri: localCameraUri,
    url: uploadedHttpsUrl,
  };
}

url must be an uploaded http or https URL because it is sent as file_urls on the user message. Use previewUri for local camera/file URIs.

Assistant messages render with the built-in native markdown renderer by default. Pass renderMarkdown to replace it, or toolRenderers to render custom native widgets for specific tool call names.

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