@ai4b-team/fsaos-gateway-sdk 3.18.0 → 3.20.0

package/README.md

@@ -40,6 +40,7 @@ Rule of thumb: if the answer should differ depending on *who is asking* or *whic
 
 ### Session Management
 - `initSession()` — Initialize domain-scoped session via `GET /d/{hostname}/init`
+- `initializeFsaos()` — Canonical one-call domain session + tracking bootstrap
 - `clearSession()` — Clear cached session
 - `getSessionEntry()` — Get current session entry (or null)
 - `getAccessToken()` — Get current auth token (waits for first auth event)
@@ -49,6 +50,25 @@ Rule of thumb: if the answer should differ depending on *who is asking* or *whic
 ### Gateway Call
 - `gatewayCall(method, params)` — Core RPC dispatcher: `POST /d/{hostname}`
 
+### Public Page Forms
+- `submitForm(capabilityId, fields, options?)` — Submit through the public domain gateway to the form dataset bound to the current published page release. The browser supplies only the declared capability name, current page URL, and field values; it never receives a dataset identity or write credential. This works from the IIFE, ESM, or npm build.
+- `FormSubmissionError` — Includes the stable `fillId`, HTTP status, and error code so an uncertain submission can be retried without creating a second fill.
+
+```ts
+const receipt = await submitForm('hero-optin', { email });
+if (receipt.next) window.location.assign(receipt.next);
+```
+
+Plain HTML can use the same contract without loading the SDK:
+
+```html
+<form method="post" action="https://fsaos-mcp-gw-rust.fly.dev/d/launch.example.com/actions/hero-optin">
+  <input type="hidden" name="_page_path" value="/offer">
+  <input type="email" name="email" required>
+  <button type="submit">Continue</button>
+</form>
+```
+
 ### Shared Instances
 - `supabase` — Shared Supabase client instance
 - `queryClient` — Shared TanStack QueryClient instance
@@ -181,6 +201,26 @@ src/
   index.ts             — Barrel export
 ```
 
+## Application bootstrap
+
+Set the registered application configuration before importing the SDK, then
+initialize it once. Tracking starts by default; custom business events remain
+explicit.
+
+```ts
+window.__FSAOS_CONFIG__ = {
+  hostname: 'app.example.com',
+  gatewayUrl: 'https://fsaos-mcp-gw-rust.fly.dev',
+};
+
+const { initializeFsaos } = await import('@ai4b-team/fsaos-gateway-sdk');
+const fsaos = await initializeFsaos();
+```
+
+Use `initializeFsaos({ tracking: false })` when consent or product policy
+requires tracking to remain disabled. Published FSAOS IIFE pages call the same
+bootstrap automatically.
+
 ## Build
 
 ```bash