frontier-os-app-builder 1.0.0 → 1.2.0

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 |

package/references/sdk/wallet.md

@@ -0,0 +1,334 @@
+# Wallet Module
+
+**Trigger keywords:** payment, pay, charge, pos, checkout, purchase, buy, sell, transfer, send money, balance, funds, money, wallet, fnd, swap, exchange, convert, token, deposit, on-ramp, fund, withdraw, off-ramp, bank, fiat, subscription, billing, price, cost, fee, tip, donate, donation
+
+Access via `sdk.getWallet()`. All methods use the current chain from the chain manager. Write operations require biometric authentication.
+
+---
+
+## Methods
+
+```typescript
+getBalance(): Promise<WalletBalance>
+```
+Returns raw balance breakdown (bigint values). To display, format each bigint field with `formatAmount()` from `@frontiertower/frontier-sdk`. Permission: `wallet:getBalance`
+
+```typescript
+getAddress(): Promise<string>
+```
+Returns the smart account contract address for the current chain. Permission: `wallet:getAddress`
+
+```typescript
+getSmartAccount(): Promise<SmartAccount>
+```
+Returns detailed smart account info including deployment status. Permission: `wallet:getSmartAccount`
+
+```typescript
+transferERC20(
+  tokenAddress: string,
+  to: string,
+  amount: bigint,
+  overrides?: GasOverrides
+): Promise<UserOperationReceipt>
+```
+Transfer ERC20 tokens. Amount in token's smallest unit. Permission: `wallet:transferERC20`
+
+```typescript
+approveERC20(
+  tokenAddress: string,
+  spender: string,
+  amount: bigint,
+  overrides?: GasOverrides
+): Promise<UserOperationReceipt>
+```
+Approve a spender for ERC20 tokens. Permission: `wallet:approveERC20`
+
+```typescript
+transferNative(
+  to: string,
+  amount: bigint,
+  overrides?: GasOverrides
+): Promise<UserOperationReceipt>
+```
+Transfer native currency (ETH). Amount in wei. Permission: `wallet:transferNative`
+
+```typescript
+executeCall(
+  call: ExecuteCall,
+  overrides?: GasOverrides
+): Promise<UserOperationReceipt>
+```
+Execute an arbitrary contract call. Permission: `wallet:executeCall`
+
+```typescript
+executeBatchCall(
+  calls: ExecuteCall[],
+  overrides?: GasOverrides
+): Promise<UserOperationReceipt>
+```
+Execute multiple calls atomically in a single transaction. Permission: `wallet:executeBatchCall`
+
+```typescript
+transferFrontierDollar(
+  to: string,
+  amount: bigint,
+  overrides?: GasOverrides
+): Promise<UserOperationReceipt>
+```
+Transfer FND (Frontier Network Dollar). Amount in base units — build with `parseAmount('10.5')` from `@frontiertower/frontier-sdk`. Permission: `wallet:transferFrontierDollar`
+
+```typescript
+transferInternalFrontierDollar(
+  to: string,
+  amount: bigint,
+  overrides?: GasOverrides
+): Promise<UserOperationReceipt>
+```
+Transfer iFND (Internal Frontier Network Dollar). Amount in base units — build with `parseAmount('10.5')` from `@frontiertower/frontier-sdk`. Permission: `wallet:transferInternalFrontierDollar`
+
+```typescript
+transferOverallFrontierDollar(
+  to: string,
+  amount: bigint,
+  overrides?: GasOverrides
+): Promise<UserOperationReceipt>
+```
+Transfer using iFND first, falling back to FND for the remainder. Permission: `wallet:transferOverallFrontierDollar`
+
+```typescript
+getSupportedTokens(): Promise<string[]>
+```
+Returns token symbols supported for swaps on the current chain (e.g. `['FND', 'USDC', 'WETH']`). Permission: `wallet:getSupportedTokens`
+
+```typescript
+swap(
+  sourceToken: string,
+  targetToken: string,
+  sourceNetwork: string,
+  targetNetwork: string,
+  amount: bigint
+): Promise<SwapResult>
+```
+Execute a token swap (same-chain or cross-chain). Amount in base units — build with `parseAmount('10.5')` from `@frontiertower/frontier-sdk`. Permission: `wallet:swap`
+
+```typescript
+quoteSwap(
+  sourceToken: string,
+  targetToken: string,
+  sourceNetwork: string,
+  targetNetwork: string,
+  amount: bigint
+): Promise<SwapQuote>
+```
+Get a swap quote without executing. Permission: `wallet:quoteSwap`
+
+```typescript
+getUsdDepositInstructions(): Promise<OnRampResponse<UsdDepositInstructions>>
+```
+Get US bank details for fiat-to-crypto on-ramp. Requires approved KYC. Permission: `wallet:getUsdDepositInstructions`
+
+```typescript
+getEurDepositInstructions(): Promise<OnRampResponse<EurDepositInstructions>>
+```
+Get SEPA bank details for EUR fiat-to-crypto on-ramp. Requires approved KYC. Permission: `wallet:getEurDepositInstructions`
+
+```typescript
+getLinkedBanks(): Promise<LinkedBanksResponse>
+```
+Get all linked bank accounts for off-ramp withdrawals. Requires approved KYC. Permission: `wallet:getLinkedBanks`
+
+```typescript
+linkUsBankAccount(
+  accountOwnerName: string,
+  bankName: string,
+  routingNumber: string,
+  accountNumber: string,
+  checkingOrSavings: 'checking' | 'savings',
+  address: BillingAddress
+): Promise<LinkBankResponse>
+```
+Link a US bank account for USD withdrawals via ACH. Requires approved KYC. Permission: `wallet:linkUsBankAccount`
+
+```typescript
+linkEuroAccount(
+  accountOwnerName: string,
+  accountOwnerType: AccountOwnerType,
+  firstName: string,
+  lastName: string,
+  ibanAccountNumber: string,
+  bic?: string
+): Promise<LinkBankResponse>
+```
+Link a EUR/IBAN bank account for SEPA withdrawals. Requires approved KYC. Permission: `wallet:linkEuroAccount`
+
+```typescript
+deleteLinkedBank(bankId: string): Promise<void>
+```
+Delete a linked bank account. Permission: `wallet:deleteLinkedBank`
+
+```typescript
+getDeprecatedSmartAccounts(): Promise<DeprecatedSmartAccount[]>
+```
+Get deprecated smart accounts that still have active gas sponsorship. Permission: `wallet:getDeprecatedSmartAccounts`
+
+---
+
+## Types
+
+```typescript
+interface SmartAccount {
+  id: number;
+  ownerAddress: string;
+  contractAddress: string | null;
+  network: string;
+  status: string;
+  deploymentTransactionHash: string;
+  createdAt: string;
+}
+
+interface WalletBalance {
+  total: bigint;
+  fnd: bigint;
+  internalFnd: bigint;
+}
+
+interface UserOperationReceipt {
+  userOpHash: string;
+  transactionHash: string;
+  blockNumber: bigint;
+  success: boolean;
+}
+
+interface GasOverrides {
+  maxFeePerGas?: bigint;
+  maxPriorityFeePerGas?: bigint;
+  gasLimit?: bigint;
+}
+
+interface ExecuteCall {
+  target: string;
+  value?: bigint;
+  data: string;
+}
+
+interface SwapParams {
+  sourceToken: string;
+  targetToken: string;
+  sourceNetwork: string;
+  targetNetwork: string;
+  amount: bigint;
+}
+
+enum SwapResultStatus {
+  COMPLETED = 'COMPLETED',
+  SUBMITTED = 'SUBMITTED',
+}
+
+interface SwapResult {
+  sourceChain: object;
+  targetChain: object;
+  sourceToken: object;
+  targetToken: object;
+  status: SwapResultStatus;
+}
+
+interface SwapQuote {
+  sourceChain: object;
+  targetChain: object;
+  sourceToken: object;
+  targetToken: object;
+  expectedAmountOut: bigint;
+  minAmountOut: bigint;
+}
+
+interface UsdDepositInstructions {
+  currency: 'usd';
+  bankName: string;
+  bankAddress: string;
+  bankRoutingNumber: string;
+  bankAccountNumber: string;
+  bankBeneficiaryName: string;
+  paymentRail: string;
+}
+
+interface EurDepositInstructions {
+  currency: 'eur';
+  iban: string;
+  bic: string;
+  accountHolderName: string;
+}
+
+interface OnRampResponse<T = UsdDepositInstructions | EurDepositInstructions> {
+  currency: 'usd' | 'eur';
+  depositInstructions: T;
+  destinationAddress: string;
+  destinationNetwork: string;
+}
+
+interface LinkedBank {
+  id: string;
+  bankName: string;
+  last4: string;
+  withdrawalAddress: string;
+  network: string;
+}
+
+interface LinkedBanksResponse {
+  banks: LinkedBank[];
+}
+
+interface LinkBankResponse {
+  externalAccountId: string;
+  bankName: string;
+  withdrawalAddress: string;
+  network: string;
+}
+
+interface BillingAddress {
+  streetLine1: string;
+  streetLine2?: string;
+  city: string;
+  state: string;
+  postalCode: string;
+  country: string;
+}
+
+type AccountOwnerType = 'individual' | 'business';
+
+interface DeprecatedSmartAccount {
+  id: number;
+  ownerAddress: string;
+  contractAddress: string;
+  network: string;
+  deprecatedAt: string;
+  version: number;
+}
+```
+
+---
+
+## Permissions (21)
+
+| Permission | Description |
+|---|---|
+| `wallet:getBalance` | Access wallet balance (raw bigint) |
+| `wallet:getAddress` | Access wallet address |
+| `wallet:getSmartAccount` | Access smart account details |
+| `wallet:transferERC20` | Transfer ERC20 tokens |
+| `wallet:approveERC20` | Approve ERC20 token spending |
+| `wallet:transferNative` | Transfer native currency (ETH) |
+| `wallet:transferFrontierDollar` | Transfer FND (Frontier Network Dollar) |
+| `wallet:transferInternalFrontierDollar` | Transfer iFND (Internal Frontier Network Dollar) |
+| `wallet:transferOverallFrontierDollar` | Transfer using iFND first, fallback to FND |
+| `wallet:executeCall` | Execute arbitrary contract call |
+| `wallet:executeBatchCall` | Execute multiple contract calls atomically |
+| `wallet:getSupportedTokens` | Get supported token symbols for swaps |
+| `wallet:swap` | Execute token swap (same-chain or cross-chain) |
+| `wallet:quoteSwap` | Get swap quote without executing |
+| `wallet:getUsdDepositInstructions` | Get USD bank deposit instructions (on-ramp) |
+| `wallet:getEurDepositInstructions` | Get EUR/SEPA deposit instructions (on-ramp) |
+| `wallet:getLinkedBanks` | Get linked bank accounts (off-ramp) |
+| `wallet:linkUsBankAccount` | Link US bank account for USD withdrawals |
+| `wallet:linkEuroAccount` | Link EUR/IBAN bank account for EUR withdrawals |
+| `wallet:deleteLinkedBank` | Delete a linked bank account |
+| `wallet:getDeprecatedSmartAccounts` | Get deprecated smart accounts with active gas sponsorship |