@base44/superagent-native 0.0.1

package/README.md

@@ -0,0 +1,132 @@
+# @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:
+
+```sh
+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.
+
+## Web preview
+
+Run the mock web preview before connecting the package to the native app:
+
+```sh
+npm run preview:web -w @base44/superagent-native
+```
+
+It serves a Vite app on `http://localhost:5177/` and uses `react-native-web` to
+render the package source with mock agents, messages, markdown, media actions,
+and custom tool widgets.
+
+```tsx
+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:
+
+```ts
+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:
+
+```ts
+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, automated by the
+[`Publish superagent-native`](../../.github/workflows/publish-superagent-native.yml)
+workflow using [changesets](../../.changeset/README.md). Publishing authenticates
+via **npm Trusted Publishing (OIDC)** — there is no long-lived npm token; CI mints
+a short-lived credential at publish time.
+
+To ship a new version: include a changeset in your PR (`pnpm changeset`, pick
+`@base44/superagent-native`). On merge to `main` a "version packages" PR is
+opened; merging it builds and publishes the new version.
+
+> 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:
+
+```sh
+npm install @base44/superagent-native
+```