frontier-os-app-builder 1.1.0 → 1.2.0

package/references/sdk/events.md

@@ -0,0 +1,212 @@
+# Events Module
+
+**Trigger keywords:** event, meetup, gathering, calendar, schedule, room, booking, reserve, reservation, space, venue, location, conference, meeting, coworking
+
+Access via `sdk.getEvents()`. Manage events, locations (event spaces and rooms), and room bookings.
+
+---
+
+## Methods
+
+```typescript
+listEvents(payload?: ListEventsParams): Promise<PaginatedResponse<Event>>
+```
+List active events with optional filters (search, type, location, date range). Permission: `events:listEvents`
+
+```typescript
+createEvent(payload: CreateEventRequest): Promise<Event>
+```
+Create a new event. Permission: `events:createEvent`
+
+```typescript
+addEventHost(payload: { eventId: number; email: string }): Promise<Event>
+```
+Add a co-host to an event. Only the primary host can add co-hosts, and only to upcoming events. Permission: `events:addEventHost`
+
+```typescript
+listLocations(payload?: ListLocationsParams): Promise<Location[]>
+```
+List available locations. Returns an array (not paginated). Optional `locationType` filter. Permission: `events:listLocations`
+
+```typescript
+listRoomBookings(payload?: ListRoomBookingsParams): Promise<PaginatedResponse<RoomBooking>>
+```
+List approved room bookings with optional filters. Permission: `events:listRoomBookings`
+
+```typescript
+createRoomBooking(payload: CreateRoomBookingRequest): Promise<RoomBooking>
+```
+Create a room booking. Location must be of type `'room'`. Permission: `events:createRoomBooking`
+
+```typescript
+getCryptoDepositPreflight(payload: { eventId: number }): Promise<DepositPreflight>
+```
+Preflight an event's FND security deposit. Host only, read-only. Returns the spender plus candidate ERC-20 tokens (iFND first, then FND) with on-chain decimals and base-unit amounts so you can approve the allowance BEFORE placing the deposit. Throws if not authenticated, not the host, or no deposit is required. Permission: `events:getCryptoDepositPreflight`
+
+```typescript
+placeCryptoDeposit(payload: { eventId: number }): Promise<DepositResult>
+```
+Place the FND security deposit. The backend `transferFrom`s the stablecoin from the member's smart account into treasury; the member must first approve the allowance to the preflight `spender` via `getWallet().approveERC20(token.address, spender, BigInt(token.baseUnits))`. Returns `status: 'secured'` (`reference` is the tx hash) or `'awaiting_payment'` (read `statusReason`, fix, retry). Host only. Permission: `events:placeCryptoDeposit`
+
+**Canonical 3-step deposit flow** (host only):
+```typescript
+// 1. Preflight — discover the spender + candidate tokens (iFND first, then FND)
+const { spender, tokens } = await sdk.getEvents().getCryptoDepositPreflight({ eventId: 42 });
+const token = tokens[0]; // prefer iFND; fall back to tokens[1] (FND) if the member lacks iFND
+// 2. Approve the allowance to the spender (on-chain; the member confirms in the wallet)
+await sdk.getWallet().approveERC20(token.address, spender, BigInt(token.baseUnits));
+// 3. Place the deposit — the backend transferFroms it into treasury
+const result = await sdk.getEvents().placeCryptoDeposit({ eventId: 42 });
+```
+
+---
+
+## Types
+
+```typescript
+type EventType = 'public' | 'members_plus_one' | 'members_only' | 'community_only';
+type EventService = 'luma' | 'private' | 'test';
+type ReviewStatus = 'not_required' | 'approved' | 'rejected' | 'pending';
+type EventStatus = 'active' | 'suspended' | 'archived';
+type LocationType = 'event_space' | 'room';
+
+// Compact deposit status on the Event payload (host UI gating). 7 values.
+type DepositStatus = 'not_required' | 'required' | 'pending' | 'secured' | 'released' | 'withheld' | 'failed';
+
+// Raw status returned by placeCryptoDeposit. 6 values — has 'awaiting_payment' + 'grant', lacks 'not_required'/'required'/'pending'.
+type CryptoDepositStatus = 'secured' | 'awaiting_payment' | 'grant' | 'released' | 'withheld' | 'failed';
+
+interface Event {
+  id: number;
+  name: string;
+  description: string;
+  eventType: EventType;
+  eventService: EventService;
+  host: string;
+  community: number | null;
+  startsAt: string;
+  endsAt: string;
+  coverImage: string | null;
+  eventId: string;
+  location: string;
+  locationName: string;
+  displayLocation: string;
+  url: string;
+  additionalHosts: string[];
+  color: string;
+  reviewStatus: ReviewStatus;
+  status: EventStatus;
+  isHost?: boolean;                 // True iff the requesting user is this event's host (the user the deposit endpoints authorize)
+  deposit?: EventDeposit | null;    // Read-only security-deposit summary, null when no deposit row
+}
+
+interface ListEventsParams {
+  search?: string;
+  eventType?: EventType;
+  locationType?: LocationType;
+  locationId?: string;
+  date?: string;          // YYYY-MM-DD
+  startDate?: string;     // YYYY-MM-DD
+  endDate?: string;       // YYYY-MM-DD
+  page?: number;
+}
+
+interface CreateEventRequest {
+  name: string;
+  eventType: EventType;
+  startsAt: string;       // ISO 8601
+  endsAt: string;         // ISO 8601
+  location: string;       // readable_id slug
+  description?: string;
+  coverImage?: string;    // Base64 data URI
+  additionalHosts?: string[];
+  color?: string;         // Hex color code
+}
+
+interface Location {
+  id: number;
+  owner: number | null;
+  readableId: string;
+  name: string;
+  maxCapacity: number;
+  description: string;
+  directions: string;
+  locationType: LocationType;
+  warmupBuffer: string;    // e.g. "00:10:00"
+  cooldownBuffer: string;  // e.g. "00:15:00"
+  openBooking: boolean;
+  floorLocation: string;
+}
+
+interface ListLocationsParams {
+  locationType?: LocationType;
+}
+
+interface RoomBooking {
+  id: number;
+  startsAt: string;
+  endsAt: string;
+  location: string;
+}
+
+interface ListRoomBookingsParams {
+  locationId?: string;
+  date?: string;          // YYYY-MM-DD
+  startDate?: string;     // YYYY-MM-DD
+  endDate?: string;       // YYYY-MM-DD
+  page?: number;
+}
+
+interface CreateRoomBookingRequest {
+  startsAt: string;       // ISO 8601
+  endsAt: string;         // ISO 8601
+  location: string;       // readable_id (must be room type)
+}
+
+interface EventDeposit {
+  status: DepositStatus;
+  amount: number;         // snapshotted deposit amount in `currency` (e.g. 400 for the FND rail)
+  currency: string;       // e.g. "usd"
+}
+
+interface DepositPreflightToken {
+  key: string;            // e.g. "ifnd_token" or "fnd_token"
+  address: string;        // ERC-20 contract to approve the allowance on
+  decimals: number;       // on-chain token decimals (read from the contract, never assumed)
+  baseUnits: string;      // deposit amount in this token's base units, as a decimal string (wrap in BigInt() for approveERC20)
+}
+
+interface DepositPreflight {
+  spender: string;        // address to approve the allowance to (treasury) — never hardcode it
+  network: string;        // e.g. "base" (prod) or "base_sepolia" (sandbox)
+  amount: string;         // deposit amount in `currency`, as a decimal string (e.g. "400.00")
+  currency: string;       // e.g. "usd"
+  tokens: DepositPreflightToken[];  // candidate tokens in preference order: iFND first, then FND
+}
+
+interface DepositResult {
+  provider: 'crypto';     // always 'crypto' on this rail
+  status: CryptoDepositStatus;
+  amount: string;         // deposit amount in `currency`, as a decimal string
+  currency: string;       // e.g. "usd"
+  reference: string;      // on-chain tx hash when secured; empty otherwise
+  statusReason: string;   // human-readable reason when not secured (e.g. insufficient iFND/FND allowance or balance)
+}
+```
+
+> **Deposit notes:** `DepositStatus` (7 values, carried on the `Event` payload) DIFFERS from `CryptoDepositStatus` (6 values, returned by `placeCryptoDeposit` — it adds `awaiting_payment` + `grant` and drops `not_required`/`required`/`pending`). `DepositPreflightToken.baseUnits` is a decimal STRING — wrap it via `BigInt()` for `approveERC20`. Never hardcode `spender` or token addresses, and read on-chain `decimals` rather than assuming 6.
+
+---
+
+## Permissions (8)
+
+| Permission | Description |
+|---|---|
+| `events:listEvents` | List events with optional filters (paginated) |
+| `events:createEvent` | Create a new event |
+| `events:addEventHost` | Add a co-host to an event |
+| `events:listLocations` | List available locations (event spaces and rooms) |
+| `events:listRoomBookings` | List room bookings (paginated) |
+| `events:createRoomBooking` | Create a room booking |
+| `events:getCryptoDepositPreflight` | Preflight an event's FND security deposit (spender, candidate tokens, amounts) before approving the allowance |
+| `events:placeCryptoDeposit` | Place an event's FND security deposit (backend transferFrom from the member's smart account) |

package/references/sdk/init.md

@@ -0,0 +1,126 @@
+# SDK Initialization & Core Protocol
+
+Frontier SDK v0.24.0 — `@frontiertower/frontier-sdk`
+
+Import paths:
+- `@frontiertower/frontier-sdk` -- main SDK class and access modules
+- `@frontiertower/frontier-sdk/ui-utils` -- detection and standalone helpers
+
+The package **root** also exports the bigint token-amount helpers `parseAmount`, `formatAmount`, `FND_DECIMALS`, and `InvalidAmountError` (from `@frontiertower/frontier-sdk`, **not** `/ui-utils`) — the canonical bridge for displaying and parsing the now-`bigint` FND amounts. See [`token-amount.md`](./token-amount.md).
+
+---
+
+## Class: `FrontierSDK`
+
+```typescript
+import { FrontierSDK } from '@frontiertower/frontier-sdk';
+```
+
+### Constructor
+
+```typescript
+const sdk = new FrontierSDK();
+```
+
+On construction the SDK:
+1. Instantiates all ten access modules (wallet, storage, chain, user, partnerships, thirdParty, communities, events, offices, navigation).
+2. Registers a `window.addEventListener('message', ...)` listener that routes `SDKResponse` messages from `window.parent`.
+3. Sends an `{ type: 'app:ready', payload: null }` postMessage to `window.parent` to notify the host that the app iframe is ready.
+
+### `destroy(): void`
+
+Call when the app is being torn down. Removes the message event listener, calls `this.navigation.destroy()` to clean up deep-link listeners, and clears all pending request promises.
+
+### Internal: `request(type: string, payload?: any): Promise<any>`
+
+Used by all access classes. Sends an `SDKRequest` via `window.parent.postMessage` and returns a promise that resolves/rejects when the host responds. Requests time out after **30 000 ms**.
+
+## PostMessage Protocol Types
+
+```typescript
+interface SDKRequest {
+  type: string;        // e.g. 'wallet:getBalance'
+  requestId: string;   // `${Date.now()}-${incrementingId}`
+  payload?: any;
+}
+
+interface SDKResponse {
+  type: 'response' | 'error';
+  requestId: string;
+  result?: any;
+  error?: string;
+}
+```
+
+## Module Getters
+
+| Getter | Returns | Module |
+|---|---|---|
+| `sdk.getWallet()` | `WalletAccess` | Wallet |
+| `sdk.getStorage()` | `StorageAccess` | Storage |
+| `sdk.getChain()` | `ChainAccess` | Chain |
+| `sdk.getUser()` | `UserAccess` | User |
+| `sdk.getPartnerships()` | `PartnershipsAccess` | Partnerships |
+| `sdk.getThirdParty()` | `ThirdPartyAccess` | Third-Party |
+| `sdk.getCommunities()` | `CommunitiesAccess` | Communities |
+| `sdk.getEvents()` | `EventsAccess` | Events |
+| `sdk.getOffices()` | `OfficesAccess` | Offices |
+| `sdk.getNavigation()` | `NavigationAccess` | Navigation |
+
+---
+
+## Security
+
+### Allowed Origins
+
+The SDK defines three allowed Frontier Wallet origins. Apps should only accept messages from these:
+
+| Environment | Origin |
+|---|---|
+| Development | `http://localhost:5173` |
+| Sandbox | `https://sandbox.os.frontiertower.io` |
+| Production | `https://os.frontiertower.io` |
+
+### Access Controls Verification
+
+The `user:getVerifiedAccessControls` method provides a tamper-proof way to verify user access. The flow:
+
+1. The PWA host relays a `SignedAccessControls` envelope from the Frontier API server.
+2. The SDK decodes the Base64 payload, computes its SHA-256 hash, and verifies the ECDSA secp256k1 signature against a hardcoded public key for the current environment stage.
+3. If the signature is valid, the decoded `AccessControlsPayload` is returned.
+4. If invalid, the method throws -- the app should deny access.
+
+Supported stages and their public keys (uncompressed secp256k1, hex):
+
+| Stage(s) | Key |
+|---|---|
+| `test` | `04aab6c393...` (test-only key) |
+| `development`, `local`, `sandbox`, `staging` | `04dc3ab0e1...` (shared dev/sandbox key) |
+| `production` | `045d1a0f9c...` (production key) |
+
+**Rule: Always use `getVerifiedAccessControls()` for access-gating decisions.** Do not trust unsigned user data from other SDK methods for gating features, content, or permissions.
+
+### PostMessage Security
+
+- The SDK sends requests to `window.parent` with `'*'` as the target origin.
+- The SDK only processes responses where `event.source === window.parent`.
+- Requests auto-expire after 30 seconds.
+
+---
+
+## Wildcard Permissions
+
+Each module supports a wildcard permission that grants access to all methods in that module:
+
+| Wildcard | Grants |
+|---|---|
+| `wallet:*` | All wallet permissions |
+| `storage:*` | All storage permissions |
+| `chain:*` | All chain permissions |
+| `user:*` | All user permissions |
+| `partnerships:*` | All partnerships permissions |
+| `thirdParty:*` | All third-party permissions |
+| `communities:*` | All communities permissions |
+| `events:*` | All events permissions |
+| `offices:*` | All offices permissions |
+| `navigation:*` | All navigation permissions |

package/references/sdk/navigation.md

@@ -0,0 +1,49 @@
+# Navigation Module
+
+**Trigger keywords:** navigate, deep link, deeplink, open app, app link, cross-app, redirect, launch app, inter-app
+
+Access via `sdk.getNavigation()`. App-to-app deep linking. Allows apps to navigate to other Frontier OS apps and receive incoming deep link data.
+
+---
+
+## Methods
+
+```typescript
+openApp(appId: string, options?: NavigationOpenAppOptions): Promise<void>
+```
+Navigate the host to another app in the Frontier OS ecosystem. `appId` is the target app ID from the Frontier app registry. `options.path` provides an optional deep link path for the target app. `options.params` provides optional key-value params for the target app. Permission: `navigation:openApp`
+
+```typescript
+close(): Promise<void>
+```
+Close the current app and return to the previous screen. Permission: `navigation:close`
+
+```typescript
+onDeepLink(callback: (data: DeepLinkData) => void): () => void
+```
+Register a callback for incoming deep link data. Called when this app was opened via another app's `openApp()` call. Returns an unsubscribe function. No permission required (passive listener).
+
+---
+
+## Types
+
+```typescript
+interface NavigationOpenAppOptions {
+  path?: string;
+  params?: Record<string, string>;
+}
+
+interface DeepLinkData {
+  path?: string;
+  params?: Record<string, string>;
+}
+```
+
+---
+
+## Permissions (2)
+
+| Permission | Description |
+|---|---|
+| `navigation:openApp` | Navigate to another app |
+| `navigation:close` | Close current app |

package/references/sdk/offices.md

@@ -0,0 +1,76 @@
+# Offices Module
+
+**Trigger keywords:** office, access pass, building, door, entry, visitor, check-in, checkin, physical access, facility
+
+Access via `sdk.getOffices()`. Manage office access passes for membership contracts.
+
+All endpoints require authentication, an active subscription, and manager status on the membership contract's organization (or superuser).
+
+---
+
+## Methods
+
+```typescript
+createAccessPass(payload: CreateAccessPassRequest): Promise<AccessPass>
+```
+Create an access pass for a membership contract. Auto-creates an inactive account if the user does not exist. Each user can only have one active pass per contract. Permission: `offices:createAccessPass`
+
+```typescript
+listAccessPasses(payload?: ListAccessPassesParams): Promise<PaginatedResponse<AccessPass>>
+```
+List access passes for contracts the user manages. Active only by default; set `includeRevoked: true` for all. Ordered newest first. Permission: `offices:listAccessPasses`
+
+```typescript
+getAccessPass(payload: { id: number }): Promise<AccessPass>
+```
+Get an access pass by ID. Permission: `offices:getAccessPass`
+
+```typescript
+revokeAccessPass(payload: { id: number }): Promise<void>
+```
+Revoke an access pass. Cannot revoke an already-revoked pass. Permission: `offices:revokeAccessPass`
+
+---
+
+## Types
+
+```typescript
+type AccessPassStatus = 'active' | 'revoked';
+
+interface AccessPass {
+  id: number;
+  email: string;
+  firstName: string;
+  lastName: string;
+  status: AccessPassStatus;
+  membershipContract: number;
+  contractReference: string;
+  createdAt: string;
+  revokedAt: string | null;
+  updatedAt: string;
+}
+
+interface CreateAccessPassRequest {
+  email: string;
+  firstName: string;
+  lastName: string;
+  membershipContract: number;
+}
+
+interface ListAccessPassesParams {
+  limit?: number;
+  offset?: number;
+  includeRevoked?: boolean;
+}
+```
+
+---
+
+## Permissions (4)
+
+| Permission | Description |
+|---|---|
+| `offices:createAccessPass` | Create an access pass for a membership contract |
+| `offices:listAccessPasses` | List access passes for managed contracts (paginated) |
+| `offices:getAccessPass` | Retrieve an access pass by ID |
+| `offices:revokeAccessPass` | Revoke an access pass |

package/references/sdk/partnerships.md

@@ -0,0 +1,111 @@
+# Partnerships Module
+
+**Trigger keywords:** sponsor, partnership, partner, sponsorship, benefactor, supporter, patron
+
+Access via `sdk.getPartnerships()`. Manage sponsors and sponsor passes.
+
+---
+
+## Methods
+
+```typescript
+createSponsorPass(payload: CreateSponsorPassRequest): Promise<SponsorPass>
+```
+Create a new SponsorPass. Permission: `partnerships:createSponsorPass`
+
+```typescript
+listActiveSponsorPasses(payload?: ListSponsorPassesParams): Promise<PaginatedResponse<SponsorPass>>
+```
+List active (non-revoked) SponsorPasses, paginated. Permission: `partnerships:listActiveSponsorPasses`
+
+```typescript
+listAllSponsorPasses(payload?: ListAllSponsorPassesParams): Promise<PaginatedResponse<SponsorPass>>
+```
+List all SponsorPasses, optionally including revoked. Permission: `partnerships:listAllSponsorPasses`
+
+```typescript
+listSponsors(payload?: ListSponsorsParams): Promise<PaginatedResponse<Sponsor>>
+```
+List sponsors the user manages, paginated. Permission: `partnerships:listSponsors`
+
+```typescript
+getSponsor(payload: { id: number }): Promise<Sponsor>
+```
+Retrieve a Sponsor by ID. Permission: `partnerships:getSponsor`
+
+```typescript
+getSponsorPass(payload: { id: number }): Promise<SponsorPass>
+```
+Retrieve a SponsorPass by ID. Permission: `partnerships:getSponsorPass`
+
+```typescript
+revokeSponsorPass(payload: { id: number }): Promise<void>
+```
+Revoke (not delete) a SponsorPass. Permission: `partnerships:revokeSponsorPass`
+
+---
+
+## Types
+
+```typescript
+type SponsorPassStatus = 'active' | 'revoked';
+
+interface SponsorPass {
+  id: number;
+  sponsor: number;
+  sponsorName: string;
+  firstName: string;
+  lastName: string;
+  email: string;
+  status: SponsorPassStatus;
+  expiresAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+  revokedAt: string | null;
+}
+
+interface CreateSponsorPassRequest {
+  sponsor: number;
+  firstName: string;
+  lastName: string;
+  email: string;
+  expiresAt?: string;
+}
+
+interface ListSponsorPassesParams {
+  limit?: number;
+  offset?: number;
+}
+
+interface ListAllSponsorPassesParams extends ListSponsorPassesParams {
+  includeRevoked?: boolean;
+}
+
+interface Sponsor {
+  id: number;
+  name: string;
+  dailyRate: string;
+  notes: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface ListSponsorsParams {
+  limit?: number;
+  offset?: number;
+}
+```
+
+---
+
+## Permissions (7)
+
+| Permission | Description |
+|---|---|
+| `partnerships:listSponsors` | List sponsors you manage (paginated) |
+| `partnerships:getSponsor` | Retrieve a Sponsor by ID |
+| `partnerships:createSponsorPass` | Create a SponsorPass |
+| `partnerships:listActiveSponsorPasses` | List active SponsorPasses (paginated) |
+| `partnerships:listAllSponsorPasses` | List all SponsorPasses (paginated) |
+| `partnerships:getSponsorPass` | Retrieve a SponsorPass by ID |
+| `partnerships:revokeSponsorPass` | Revoke a SponsorPass |

package/references/sdk/storage.md

@@ -0,0 +1,44 @@
+# Storage Module
+
+**Trigger keywords:** storage, persist, save, preferences, settings, cache, remember, state, draft, favorites, bookmarks
+
+Access via `sdk.getStorage()`. Provides persistent key-value storage scoped to the app.
+
+---
+
+## Methods
+
+```typescript
+get<T = any>(key: string): Promise<T>
+```
+Read a value by key. Permission: `storage:get`
+
+```typescript
+set(key: string, value: any): Promise<void>
+```
+Write a value by key. Permission: `storage:set`
+
+```typescript
+remove(key: string): Promise<void>
+```
+Delete a key. Permission: `storage:remove`
+
+```typescript
+clear(): Promise<void>
+```
+Delete all keys. Permission: `storage:clear`
+
+## Types
+
+No additional types -- uses generic `T` for get, `any` for set.
+
+---
+
+## Permissions (4)
+
+| Permission | Description |
+|---|---|
+| `storage:get` | Read from persistent storage |
+| `storage:set` | Write to persistent storage |
+| `storage:remove` | Remove key from persistent storage |
+| `storage:clear` | Clear all persistent storage |