frontier-os-app-builder 1.1.0 → 1.2.0

package/references/sdk/thirdparty.md

@@ -0,0 +1,240 @@
+# ThirdParty Module
+
+**Trigger keywords:** developer, api key, webhook, app registration, app store, third party, integration, external, developer portal
+
+Access via `sdk.getThirdParty()`. Manage developer accounts, registered apps, and webhooks.
+
+---
+
+## Developer Methods
+
+```typescript
+listDevelopers(payload?: ListParams): Promise<PaginatedResponse<Developer>>
+```
+List developer accounts, paginated. Permission: `thirdParty:listDevelopers`
+
+```typescript
+getDeveloper(payload: { id: number }): Promise<Developer>
+```
+Get developer details by ID. Permission: `thirdParty:getDeveloper`
+
+```typescript
+updateDeveloper(payload: { id: number; data: UpdateDeveloperRequest }): Promise<Developer>
+```
+Update developer information. Permission: `thirdParty:updateDeveloper`
+
+```typescript
+rotateDeveloperApiKey(payload: { id: number }): Promise<RotateKeyResponse>
+```
+Rotate developer API key. New key is only shown once in the response. Permission: `thirdParty:rotateDeveloperApiKey`
+
+## App Methods
+
+```typescript
+listApps(payload?: ListAppsParams): Promise<PaginatedResponse<App>>
+```
+List registered apps, paginated. Optional `developerId` filter. Permission: `thirdParty:listApps`
+
+```typescript
+createApp(payload: CreateAppRequest): Promise<App>
+```
+Register a new app. Name, description, and icon are auto-fetched from URL metadata. Permission: `thirdParty:createApp`
+
+```typescript
+getApp(payload: { id: number }): Promise<App>
+```
+Get app details by ID. Permission: `thirdParty:getApp`
+
+```typescript
+updateApp(payload: { id: number; data: UpdateAppRequest }): Promise<App>
+```
+Update an app. Permission: `thirdParty:updateApp`
+
+```typescript
+deleteApp(payload: { id: number }): Promise<void>
+```
+Request app deactivation. Permission: `thirdParty:deleteApp`
+
+## Webhook Methods
+
+```typescript
+listWebhooks(payload?: ListWebhooksParams): Promise<PaginatedResponse<Webhook>>
+```
+List webhooks, paginated. Max 3 webhooks per developer. Optional `developerId` filter. Permission: `thirdParty:listWebhooks`
+
+```typescript
+createWebhook(payload: CreateWebhookRequest): Promise<Webhook>
+```
+Create a new webhook. Requires admin approval before going live. Permission: `thirdParty:createWebhook`
+
+```typescript
+getWebhook(payload: { id: number }): Promise<Webhook>
+```
+Get webhook details by ID. Permission: `thirdParty:getWebhook`
+
+```typescript
+updateWebhook(payload: { id: number; data: UpdateWebhookRequest }): Promise<Webhook>
+```
+Update a webhook. Config changes require admin re-approval. Permission: `thirdParty:updateWebhook`
+
+```typescript
+deleteWebhook(payload: { id: number }): Promise<void>
+```
+Delete a webhook. Permission: `thirdParty:deleteWebhook`
+
+```typescript
+rotateWebhookSigningKey(payload: { id: number }): Promise<RotateWebhookKeyResponse>
+```
+Rotate webhook signing key. New public key returned in response. Permission: `thirdParty:rotateWebhookSigningKey`
+
+---
+
+## Types
+
+```typescript
+interface Developer {
+  id: number;
+  name: string;
+  description: string;
+  email: string;
+  apiKey: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface UpdateDeveloperRequest {
+  name?: string;
+  description?: string;
+  email?: string;
+}
+
+interface RotateKeyResponse {
+  message: string;
+  developer: Developer;
+}
+
+type AppStatus =
+  | 'in_review'
+  | 'accepted'
+  | 'released'
+  | 'rejected'
+  | 'request_deactivation'
+  | 'deactivated';
+
+type AppPermission = string;
+
+interface App {
+  id: number;
+  developer: number;
+  icon: string | null;
+  name: string;
+  readableId: string;
+  description: string;
+  url: string;
+  cnameEntry: string;
+  txtEntry: string | null;
+  permissions: AppPermission[];
+  permissionDisclaimer: string;
+  status: AppStatus;
+  reviewNotes: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface CreateAppRequest {
+  developer: number;
+  url: string;
+  cnameEntry: string;
+  txtEntry?: string;
+  permissions: AppPermission[];
+  permissionDisclaimer: string;
+}
+
+interface UpdateAppRequest {
+  developer?: number;
+  url?: string;
+  cnameEntry?: string;
+  txtEntry?: string;
+  permissions?: AppPermission[];
+  permissionDisclaimer?: string;
+}
+
+type WebhookStatus = 'IN_REVIEW' | 'LIVE' | 'REJECTED';
+type WebhookEvent = string;
+type WebhookScope = Record<string, number[] | '*'>;
+
+interface WebhookConfig {
+  events: WebhookEvent[];
+  scope: WebhookScope;
+}
+
+interface Webhook {
+  id: number;
+  developer: number;
+  name: string;
+  description: string;
+  targetUrl: string;
+  config: WebhookConfig;
+  signingPublicKey: string;
+  status: WebhookStatus;
+  reviewNotes: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface CreateWebhookRequest {
+  developer: number;
+  name: string;
+  description: string;
+  targetUrl: string;
+  config: WebhookConfig;
+}
+
+interface UpdateWebhookRequest {
+  developer?: number;
+  name?: string;
+  description?: string;
+  targetUrl?: string;
+  config?: WebhookConfig;
+}
+
+interface RotateWebhookKeyResponse {
+  message: string;
+  webhook: Webhook;
+}
+
+interface ListParams {
+  limit?: number;
+  offset?: number;
+}
+
+interface ListAppsParams extends ListParams {
+  developerId?: number;
+}
+
+interface ListWebhooksParams extends ListParams {
+  developerId?: number;
+}
+```
+
+---
+
+## Permissions (15)
+
+| Permission | Description |
+|---|---|
+| `thirdParty:listDevelopers` | List developer accounts (paginated) |
+| `thirdParty:getDeveloper` | Get developer details by ID |
+| `thirdParty:updateDeveloper` | Update developer information |
+| `thirdParty:rotateDeveloperApiKey` | Rotate developer API key |
+| `thirdParty:listApps` | List registered apps (paginated) |
+| `thirdParty:createApp` | Register a new app |
+| `thirdParty:getApp` | Get app details by ID |
+| `thirdParty:updateApp` | Update an app |
+| `thirdParty:deleteApp` | Request app deactivation |
+| `thirdParty:listWebhooks` | List webhooks (paginated) |
+| `thirdParty:createWebhook` | Create a new webhook |
+| `thirdParty:getWebhook` | Get webhook details by ID |
+| `thirdParty:updateWebhook` | Update a webhook |
+| `thirdParty:deleteWebhook` | Delete a webhook |
+| `thirdParty:rotateWebhookSigningKey` | Rotate webhook signing key |

package/references/sdk/token-amount.md

@@ -0,0 +1,99 @@
+# Token Amounts (bigint base units)
+
+Frontier SDK v0.24.0 — imported from `@frontiertower/frontier-sdk` (the package root, **NOT** the `/ui-utils` subpath).
+
+Since v0.23 all FND amounts are **bigint base units**. This module is the canonical `bigint <-> display-string` bridge that every FND-handling app depends on: wallet balances, `transfer*`/`swap` amounts, and the events security-deposit token amounts are all bigint, and these helpers convert to/from the human-readable strings you show in the UI or read from an input field.
+
+## Exports (from the package root — `frontier-sdk/src/index.ts:26`)
+
+```ts
+import {
+  parseAmount,
+  formatAmount,
+  FND_DECIMALS,
+  InvalidAmountError,
+} from '@frontiertower/frontier-sdk';
+```
+
+| Export | Signature | Source |
+|---|---|---|
+| `FND_DECIMALS` | `const FND_DECIMALS: number` (= `6`) | `token-amount.ts:2` |
+| `parseAmount` | `parseAmount(value: string, decimals = FND_DECIMALS): bigint` | `token-amount.ts:19` |
+| `formatAmount` | `formatAmount(amount: bigint, decimals = FND_DECIMALS): string` | `token-amount.ts:40` |
+| `InvalidAmountError` | `class InvalidAmountError extends Error` | `token-amount.ts:5` |
+
+`FND_DECIMALS = 6` is the decimal precision of the Frontier Dollar (FND). Both helpers default to it, so for FND you never pass `decimals` explicitly; pass it only for non-FND tokens (read the on-chain `decimals` from chain config — see Notes).
+
+## `parseAmount(value, decimals = 6) -> bigint`
+
+Parses a plain decimal string into a bigint in base units.
+
+- `'75.5'` -> `75500000n`
+- `'100'` -> `100000000n`
+- `'0.000001'` -> `1n`
+
+Symbol-free and locale-free by design. It throws `InvalidAmountError` on:
+
+- currency symbols (`'$10'`)
+- thousands separators (`'1,000'`)
+- comma decimals (`'10,5'`)
+- empty / whitespace-only string
+- trailing dot (`'10.'`)
+- more fractional digits than `decimals` (e.g. `'1.1234567'` for 6-decimal FND)
+
+The validation regex is `/^-?\d+(\.\d+)?$/`, so **a leading minus IS permitted and negatives parse**: `'-5'` -> `-5000000n`. Guard against negative amounts yourself if your flow requires non-negative values. Normalize locale input (`','` -> `'.'`) before calling.
+
+```ts
+let amount: bigint;
+try {
+  amount = parseAmount(userInput);          // throws InvalidAmountError on bad input
+} catch (err) {
+  if (err instanceof InvalidAmountError) {
+    // surface a validation message to the user
+  }
+  throw err;
+}
+```
+
+## `formatAmount(amount, decimals = 6) -> string`
+
+Formats a bigint base-unit amount into an exact, symbol-free decimal string.
+
+- `75500000n` -> `'75.5'`
+- `100000000n` -> `'100'`
+- `1n` -> `'0.000001'`
+- `-5000000n` -> `'-5'`
+
+Full precision, trailing zeros trimmed, round-trips with `parseAmount`, negatives preserved. **The SDK never emits `'$'`** — display concerns (the `$` symbol, rounding, grouping separators) belong to the caller. Prepend the currency symbol yourself:
+
+```ts
+const display = `$${formatAmount(balance.fnd)}`;  // '$75.5'
+```
+
+## Canonical usage (read -> display, input -> write)
+
+```ts
+import {
+  FrontierSDK,
+  formatAmount,
+  parseAmount,
+} from '@frontiertower/frontier-sdk';
+
+const wallet = sdk.getWallet();
+
+// Read: getBalance() returns WalletBalance { total, fnd, internalFnd } — all bigint.
+const balance = await wallet.getBalance();
+const fndDisplay = formatAmount(balance.fnd);            // e.g. '75.5' for the UI
+
+// Write: parse the user's input to bigint, then pass it straight to the transfer.
+const amount = parseAmount(userInput);                   // throws InvalidAmountError
+await wallet.transferFrontierDollar(recipient, amount);
+```
+
+The same pattern applies to `transferInternalFrontierDollar`, `transferOverallFrontierDollar`, `swap`, and `quoteSwap` — all take `amount: bigint`. See `references/sdk/wallet.md`.
+
+## Notes
+
+- `getBalanceFormatted()` and the `WalletBalanceFormatted` interface were **REMOVED in v0.23** (along with the `wallet:getBalanceFormatted` permission). There is no SDK method that returns pre-formatted display strings — call `getBalance()` and format each bigint field locally with `formatAmount()`.
+- Base units, not display strings, cross the SDK boundary: a balance of `100_000000n` is `'100'` FND, and `1n` is the smallest representable amount (`0.000001` FND).
+- For **non-FND tokens** (e.g. the events deposit ERC-20 candidates), do not assume 6 decimals. The on-chain `decimals` come from chain config: `(await sdk.getChain().getCurrentChainConfig()).stableCoins[].decimals`. Pass that value as the `decimals` argument to `parseAmount`/`formatAmount`, or use the `baseUnits` string the SDK already provides (the events `DepositPreflightToken.baseUnits` is wrapped with `BigInt(...)` for `approveERC20`).

package/references/sdk/types.md

@@ -0,0 +1,27 @@
+# Shared SDK Types
+
+Types used across multiple SDK modules.
+
+---
+
+## Pagination
+
+```typescript
+interface PaginatedResponse<T> {
+  count: number;
+  results: T[];
+}
+
+interface PaginatedParams {
+  limit?: number;
+  offset?: number;
+}
+```
+
+Most list methods accept `PaginatedParams` (or a superset) and return `PaginatedResponse<T>`.
+
+---
+
+## Total Permissions Count
+
+85 permissions across 10 modules. See each module's reference file for its specific permissions.

package/references/sdk/ui-utils.md

@@ -0,0 +1,39 @@
+# UI Utilities
+
+Import from `@frontiertower/frontier-sdk/ui-utils`.
+
+---
+
+## Detection
+
+```typescript
+function isInFrontierApp(): boolean
+```
+Returns `true` if the window is embedded in an iframe (`window.self !== window.top`). Use to detect whether the app is running inside the Frontier Wallet host.
+
+```typescript
+function getParentOrigin(): string | null
+```
+Returns the origin of the parent window (via `document.referrer` or `window.parent.location.origin`). Returns `null` if not in an iframe or origin cannot be determined.
+
+## Standalone Fallback
+
+```typescript
+function renderStandaloneMessage(container: HTMLElement, appName?: string): void
+```
+Renders a styled "Frontier Wallet Required" message into the given container element. Default `appName` is `'Frontier App'`. Directs users to `os.frontiertower.io` to install the app.
+
+```typescript
+function createStandaloneHTML(appName?: string): string
+```
+Returns the same styled "Frontier Wallet Required" message as an HTML string (with gradient background). Default `appName` is `'Frontier App'`.
+
+## Allowed Origins Constant
+
+```typescript
+const ALLOWED_ORIGINS: string[] = [
+  'http://localhost:5173',
+  'https://sandbox.os.frontiertower.io',
+  'https://os.frontiertower.io',
+];
+```

package/references/sdk/user.md

@@ -0,0 +1,208 @@
+# User Module
+
+**Trigger keywords:** user, profile, account, member, membership, auth, login, referral, invite, refer, signup, register, kyc, verify, identity, access control, gate, permission, name, person
+
+Access via `sdk.getUser()`. Query user info, profiles, referrals, KYC, and access controls.
+
+---
+
+## Methods
+
+```typescript
+getDetails(): Promise<User>
+```
+Returns basic user info (id, email, name, active/superuser status). Permission: `user:getDetails`
+
+```typescript
+getProfile(): Promise<UserProfile>
+```
+Returns detailed profile (social handles, preferences, community, notification settings). Permission: `user:getProfile`
+
+```typescript
+getReferralOverview(): Promise<ReferralOverview>
+```
+Returns referral statistics (count, ranking, referral link/code). Permission: `user:getReferralOverview`
+
+```typescript
+getReferralDetails(page?: number): Promise<PaginatedResponse<ReferralDetails>>
+```
+Returns paginated referral details. Permission: `user:getReferralDetails`
+
+```typescript
+addUserContact(data: UserContactPayload): Promise<void>
+```
+Submit contact information for the current user. Permission: `user:addUserContact`
+
+```typescript
+getOrCreateKyc(redirectUri?: string): Promise<KycStatusResponse>
+```
+Get or initiate KYC verification. Returns status and a KYC link if verification has been started. Permission: `user:getOrCreateKyc`
+
+```typescript
+createSignupRequest(payload: CreateSignupRequestPayload): Promise<CreateSignupRequestResponse>
+```
+Submit a new membership signup request with crypto payment. Permission: `user:createSignupRequest`
+
+```typescript
+getVerifiedAccessControls(): Promise<AccessControlsPayload>
+```
+Returns cryptographically verified access controls signed by the Frontier API server. The SDK verifies an ECDSA secp256k1 signature against hardcoded per-environment public keys inside the iframe. **Use this for all access-gating decisions** -- unsigned data from other SDK methods should not be trusted for feature gating. Throws if signature verification fails. Permission: `user:getVerifiedAccessControls`
+
+---
+
+## Types
+
+```typescript
+interface User {
+  id: number;
+  email: string;
+  firstName: string;
+  lastName: string;
+  isActive: boolean;
+  dateJoined: string;
+  isSuperuser: boolean;
+}
+
+interface UserProfile {
+  id: number;
+  user: number;
+  firstName: string;
+  lastName: string;
+  nickname: string;
+  profilePicture: string;
+  phoneNumber: string;
+  community: string;
+  communityName: string;
+  organization: string;
+  organizationRole: string;
+  socialSite: string;
+  socialHandle: string;
+  githubHandle: string;
+  currentWork: string;
+  notableWork: string;
+  receiveUpdates: boolean;
+  notificationCommunityEvent: boolean;
+  notificationTowerEvent: boolean;
+  notificationUpcomingEvent: boolean;
+  notificationTweetPicked: boolean;
+  notifyEventInvites: boolean;
+  optInSms: boolean;
+  howDidYouHearAboutUs: string;
+  braggingStatement: string;
+  contributionStatement: string;
+  hasUsablePassword: string;
+}
+
+interface ReferralOverview {
+  referralCount: number;
+  ranking: number;
+  referralLink: string;
+  referralCode: string;
+  referredBy: string | null;
+}
+
+interface ReferralDetails {
+  name: string;
+  email: string;
+  referralDate: string;
+  reward: string;
+  status: string;
+}
+
+interface UserContact {
+  email: string;
+  phone: string;
+  name: string;
+}
+
+interface UserContactPayload {
+  contacts: UserContact[];
+}
+
+type KycStatus = 'not_started' | 'pending' | 'in_review' | 'approved' | 'rejected';
+type TosStatus = 'pending' | 'approved';
+
+interface KycStatusResponse {
+  status: KycStatus;
+  isApproved: boolean;
+  rejectionReason: string | null;
+  kycLinkId: string | null;
+  kycLink: string | null;
+  tosStatus: TosStatus | null;
+  tosLink: string | null;
+}
+
+interface CreateSignupRequestPayload {
+  subscriptionPlan: string;
+  subscriptionInterval: string;
+  firstName: string;
+  lastName: string;
+  email: string;
+  phoneNumber: string;
+  socialSite: string;
+  socialHandle: string;
+  currentWork: string;
+  howDidYouHearAboutUs: string;
+  braggingStatement: string;
+  contributionStatement: string;
+  billingFirstName: string;
+  billingLastName: string;
+  billingEmail: string;
+  billingPhoneNumber: string;
+  paymentProvider: 'crypto';
+  smartAccount: number;
+  community: string;
+  githubHandle?: string;
+  notableWork?: string;
+  referralCode?: string;
+  receiveUpdates?: boolean;
+  optInSms?: boolean;
+  organization?: string;
+  organizationRole?: string;
+}
+
+interface CreateSignupRequestResponse {
+  subscriptionUuid: string;
+  paymentProvider: string;
+}
+```
+
+### Access Controls Types
+
+```typescript
+interface AccessControlsPayload {
+  smartAccountAddress: string | null;
+  email: string;
+  isSuperuser: boolean;
+  subscriptionStatus: string | null;   // 'active' | 'canceled' | 'awaiting_approval' | null
+  subscriptionPlan: string | null;
+  subscriptionInterval: string | null;
+  subscriptionType: string | null;     // 'crypto' | 'stripe' | 'grant' | 'office' | 'internship' | null
+  addOns: string[];
+  communities: string[];
+  managedCommunities: string[];
+  timestamp: string;
+  kid: string;
+}
+
+interface SignedAccessControls {
+  accessControls: string;  // Base64-encoded canonical JSON payload
+  stage: string;           // API stage (e.g. 'production', 'sandbox')
+  signature: string;       // Hex-encoded ECDSA signature (r||s, 128 hex chars)
+}
+```
+
+---
+
+## Permissions (8)
+
+| Permission | Description |
+|---|---|
+| `user:getDetails` | Access current user details |
+| `user:getProfile` | Access current user profile |
+| `user:getReferralOverview` | Access referral statistics |
+| `user:getReferralDetails` | Access detailed referral information |
+| `user:addUserContact` | Add user contact information |
+| `user:getOrCreateKyc` | Get or create KYC verification status |
+| `user:createSignupRequest` | Submit membership signup request with crypto payment |
+| `user:getVerifiedAccessControls` | Get cryptographically verified access controls |