feat: [epic] bridge integration

.gitignore

@@ -53,3 +53,8 @@ junit.xml
 .yarnrc.yml
 
 docker-compose.local.yml
+
+# Planning scratch files
+findings.md
+progress.md
+task_plan.md

DEV.md

@@ -153,6 +153,27 @@ make stop-frappe         # stop local Frappe
 
 Update your `dev-overrides.yaml` with local Frappe credentials if running locally.
 
+### Admin Panel API URL
+
+The Frappe Admin Panel uses the Frappe site config key `flash_admin_api_url` to
+call the Flash admin GraphQL API for pages such as `alert-users`.
+
+- **Local Docker Frappe:** use `http://host.docker.internal:4001/graphql` so the
+  Frappe container can reach the backend admin GraphQL server running on the
+  host machine. Compose maps that hostname with Docker's symbolic
+  `host-gateway`, and the value can be overridden locally with
+  `FRAPPE_FLASH_API` if a developer's Docker runtime needs a different host
+  route.
+- **Test / production Kubernetes:** do **not** use `host.docker.internal`. Set
+  `flash_admin_api_url` from the deployment config to the environment-specific
+  Kubernetes-reachable admin GraphQL endpoint, such as an internal service DNS
+  name or routed internal gateway URL. The endpoint should route to the admin
+  GraphQL server's `/graphql` path unless that environment explicitly rewrites a
+  different path.
+
+If a local full Frappe backup includes `site_config_backup.json`, treat this key
+as environment-specific and override it during deployment restore.
+
 ---
 
 ## Testing

dev/apollo-federation/supergraph.graphql

@@ -264,6 +264,159 @@ input BankAccountInput
   currency: String!
 }
 
+type BridgeAddExternalAccountPayload
+  @join__type(graph: PUBLIC)
+{
+  errors: [Error!]!
+  externalAccount: BridgeExternalAccountLink
+}
+
+input BridgeCancelWithdrawalRequestInput
+  @join__type(graph: PUBLIC)
+{
+  withdrawalId: ID!
+}
+
+type BridgeCancelWithdrawalRequestPayload
+  @join__type(graph: PUBLIC)
+{
+  errors: [Error!]!
+  withdrawal: BridgeWithdrawal
+}
+
+input BridgeCreateExternalAccountInput
+  @join__type(graph: PUBLIC)
+{
+  accountNumber: String!
+  accountOwnerName: String!
+  bankName: String!
+  checkingOrSavings: String = "checking"
+  city: String!
+  country: String!
+  postalCode: String!
+  routingNumber: String!
+  state: String!
+  streetLine1: String!
+}
+
+type BridgeCreateExternalAccountPayload
+  @join__type(graph: PUBLIC)
+{
+  errors: [Error!]!
+  externalAccount: BridgeExternalAccount
+}
+
+type BridgeCreateVirtualAccountPayload
+  @join__type(graph: PUBLIC)
+{
+  errors: [Error!]!
+  virtualAccount: BridgeVirtualAccount
+}
+
+type BridgeExternalAccount
+  @join__type(graph: PUBLIC)
+{
+  accountNumberLast4: String!
+  bankName: String!
+  id: ID!
+  status: String!
+}
+
+type BridgeExternalAccountLink
+  @join__type(graph: PUBLIC)
+{
+  expiresAt: String!
+  linkUrl: String!
+}
+
+input BridgeInitiateKycInput
+  @join__type(graph: PUBLIC)
+{
+  email: String
+  full_name: String
+  type: String
+}
+
+type BridgeInitiateKycPayload
+  @join__type(graph: PUBLIC)
+{
+  errors: [Error!]!
+  kycLink: BridgeKycLink
+}
+
+input BridgeInitiateWithdrawalInput
+  @join__type(graph: PUBLIC)
+{
+  withdrawalId: ID!
+}
+
+type BridgeInitiateWithdrawalPayload
+  @join__type(graph: PUBLIC)
+{
+  errors: [Error!]!
+  withdrawal: BridgeWithdrawal
+}
+
+type BridgeKycLink
+  @join__type(graph: PUBLIC)
+{
+  kycLink: String!
+  tosLink: String!
+}
+
+input BridgeRequestWithdrawalInput
+  @join__type(graph: PUBLIC)
+{
+  amount: String!
+  externalAccountId: ID!
+}
+
+type BridgeRequestWithdrawalPayload
+  @join__type(graph: PUBLIC)
+{
+  errors: [Error!]!
+  withdrawal: BridgeWithdrawal
+}
+
+type BridgeVirtualAccount
+  @join__type(graph: PUBLIC)
+{
+  accountNumber: String
+  accountNumberLast4: String
+  bankName: String
+  id: ID
+  kycLink: String
+  message: String
+  pending: Boolean
+  routingNumber: String
+  tosLink: String
+}
+
+type BridgeWithdrawal
+  @join__type(graph: PUBLIC)
+{
+  amount: String!
+  bridgeDeveloperFee: String
+  bridgeExchangeFee: String
+  bridgeTransferId: String
+  createdAt: String!
+  currency: String!
+  estimatedBridgeFee: String
+  estimatedBridgeFeePercent: String
+  estimatedCustomerFee: String
+  estimatedGasBuffer: String
+  externalAccountId: String
+  failureReason: String
+  finalAmount: String
+  flashFee: String
+  flashFeeIsEstimate: Boolean!
+  flashFeeNotice: String
+  flashFeePercent: String
+  id: ID!
+  status: String!
+  subtotalAmount: String
+}
+
 """
 A wallet belonging to an account which contains a BTC balance and a list of transactions.
 """
@@ -418,6 +571,29 @@ type CashoutOffer
   walletId: WalletId!
 }
 
+type CashWalletCutover
+  @join__type(graph: PUBLIC)
+{
+  completedAt: Timestamp
+  cutoverVersion: Int!
+  pauseReason: String
+  pausedAt: Timestamp
+  runId: String
+  scheduledAt: Timestamp
+  startedAt: Timestamp
+  state: CashWalletCutoverState!
+  updatedAt: Timestamp!
+  updatedBy: String
+}
+
+enum CashWalletCutoverState
+  @join__type(graph: PUBLIC)
+{
+  COMPLETE @join__enumValue(graph: PUBLIC)
+  IN_PROGRESS @join__enumValue(graph: PUBLIC)
+  PRE @join__enumValue(graph: PUBLIC)
+}
+
 """(Positive) Cent amount (1/100 of a dollar)"""
 scalar CentAmount
   @join__type(graph: PUBLIC)
@@ -985,6 +1161,22 @@ A bech32-encoded HTTPS/Onion URL that can be interacted with automatically by a
 scalar Lnurl
   @join__type(graph: PUBLIC)
 
+input LnurlPaymentSendInput
+  @join__type(graph: PUBLIC)
+{
+  """Amount to spend from the USD/USDT wallet, in USD cents."""
+  amount: FractionalCentAmount!
+
+  """LNURL-pay value to decode and pay."""
+  lnurl: Lnurl!
+
+  """Optional memo for the Lightning payment."""
+  memo: Memo
+
+  """Wallet ID with sufficient balance. Must belong to the current user."""
+  walletId: WalletId!
+}
+
 input LnUsdInvoiceCreateInput
   @join__type(graph: PUBLIC)
 {
@@ -1101,6 +1293,13 @@ type Mutation
   accountEnableNotificationChannel(input: AccountEnableNotificationChannelInput!): AccountUpdateNotificationSettingsPayload!
   accountUpdateDefaultWalletId(input: AccountUpdateDefaultWalletIdInput!): AccountUpdateDefaultWalletIdPayload!
   accountUpdateDisplayCurrency(input: AccountUpdateDisplayCurrencyInput!): AccountUpdateDisplayCurrencyPayload!
+  bridgeAddExternalAccount: BridgeAddExternalAccountPayload!
+  bridgeCancelWithdrawalRequest(input: BridgeCancelWithdrawalRequestInput!): BridgeCancelWithdrawalRequestPayload!
+  bridgeCreateExternalAccount(input: BridgeCreateExternalAccountInput!): BridgeCreateExternalAccountPayload!
+  bridgeCreateVirtualAccount: BridgeCreateVirtualAccountPayload!
+  bridgeInitiateKyc(input: BridgeInitiateKycInput!): BridgeInitiateKycPayload!
+  bridgeInitiateWithdrawal(input: BridgeInitiateWithdrawalInput!): BridgeInitiateWithdrawalPayload!
+  bridgeRequestWithdrawal(input: BridgeRequestWithdrawalInput!): BridgeRequestWithdrawalPayload!
   businessAccountUpgradeRequest(input: BusinessAccountUpgradeRequestInput!): AccountUpgradePayload!
   callbackEndpointAdd(input: CallbackEndpointAddInput!): CallbackEndpointAddPayload!
   callbackEndpointDelete(input: CallbackEndpointDeleteInput!): SuccessPayload!
@@ -1200,6 +1399,12 @@ type Mutation
   """
   lnUsdInvoiceCreateOnBehalfOfRecipient(input: LnUsdInvoiceCreateOnBehalfOfRecipientInput!): LnInvoicePayload!
   lnUsdInvoiceFeeProbe(input: LnUsdInvoiceFeeProbeInput!): CentAmountPayload!
+
+  """
+  Pay a LNURL-pay endpoint using a USD/USDT wallet balance.
+  The wallet amount is converted to whole-satoshi millisatoshis before calling IBEX.
+  """
+  lnurlPaymentSend(input: LnurlPaymentSendInput!): PaymentSendPayload!
   merchantMapSuggest(input: MerchantMapSuggestInput!): MerchantPayload!
   onChainAddressCreate(input: OnChainAddressCreateInput!): OnChainAddressPayload!
   onChainAddressCurrent(input: OnChainAddressCurrentInput!): OnChainAddressPayload!
@@ -1557,9 +1762,15 @@ type Query
   @join__type(graph: PUBLIC)
 {
   accountDefaultWallet(username: Username!, walletCurrency: WalletCurrency): PublicWallet!
+  bridgeExternalAccounts: [BridgeExternalAccount]
+  bridgeKycStatus: String
+  bridgeVirtualAccount: BridgeVirtualAccount
+  bridgeWithdrawalRequest(id: ID!): BridgeWithdrawal
+  bridgeWithdrawals: [BridgeWithdrawal]
   btcPrice(currency: DisplayCurrency! = "USD"): Price @deprecated(reason: "Deprecated in favor of realtimePrice")
   btcPriceList(range: PriceGraphRange!): [PricePoint]
   businessMapMarkers: [MapMarker!]!
+  cashWalletCutover: CashWalletCutover!
   currencyList: [Currency!]!
   globals: Globals
   isFlashNpub(input: IsFlashNpubInput!): IsFlashNpubPayload
@@ -1940,6 +2151,53 @@ type UpgradePayload
 scalar USDCents
   @join__type(graph: PUBLIC)
 
+"""
+A wallet belonging to an account which contains a USDT balance and a list of transactions.
+"""
+type UsdtWallet implements Wallet
+  @join__implements(graph: PUBLIC, interface: "Wallet")
+  @join__type(graph: PUBLIC)
+{
+  accountId: ID!
+  balance: FractionalCentAmount
+  id: ID!
+  isExternal: Boolean!
+  lnurlp: Lnurl
+
+  """An unconfirmed incoming onchain balance."""
+  pendingIncomingBalance: SignedAmount!
+  transactions(
+    """Returns the items in the list that come after the specified cursor."""
+    after: String
+
+    """Returns the items in the list that come before the specified cursor."""
+    before: String
+
+    """Returns the first n items from the list."""
+    first: Int
+
+    """Returns the last n items from the list."""
+    last: Int
+  ): TransactionConnection
+  transactionsByAddress(
+    """Returns the items that include this address."""
+    address: OnChainAddress!
+
+    """Returns the items in the list that come after the specified cursor."""
+    after: String
+
+    """Returns the items in the list that come before the specified cursor."""
+    before: String
+
+    """Returns the first n items from the list."""
+    first: Int
+
+    """Returns the last n items from the list."""
+    last: Int
+  ): TransactionConnection
+  walletCurrency: WalletCurrency!
+}
+
 """
 A wallet belonging to an account which contains a USD balance and a list of transactions.
 """
@@ -2333,6 +2591,7 @@ enum WalletCurrency
 {
   BTC @join__enumValue(graph: PUBLIC)
   USD @join__enumValue(graph: PUBLIC)
+  USDT @join__enumValue(graph: PUBLIC)
 }
 
 """Unique identifier of a wallet"""