### Install and Run Next.js App

Source: https://github.com/quiltt/quiltt-sdks/blob/main/examples/react-nextjs/README.md

Navigate to the example directory, install dependencies, and start the development server.

```bash
cd examples/react-nextjs
pnpm install
pnpm run dev
```

--------------------------------

### Install and Run Nuxt App

Source: https://github.com/quiltt/quiltt-sdks/blob/main/examples/vue-nuxt/README.md

Navigate to the example directory, install dependencies, and start the development server.

```bash
cd examples/vue-nuxt
pnpm install
pnpm run dev
```

--------------------------------

### Install Dependencies and Run Dev Server

Source: https://github.com/quiltt/quiltt-sdks/blob/main/examples/capacitor-react/README.md

Install project dependencies and start the development server.

```bash
cd examples/capacitor-react
pnpm install
pnpm run dev
```

--------------------------------

### Install Dependencies and Run Dev Server

Source: https://github.com/quiltt/quiltt-sdks/blob/main/examples/capacitor-vue/README.md

Install project dependencies and start the development server for the Capacitor Vue example.

```bash
cd examples/capacitor-vue
pnpm install
pnpm run dev
```

--------------------------------

### Install and Run Expo App

Source: https://github.com/quiltt/quiltt-sdks/blob/main/examples/react-native-expo/README.md

Commands to navigate to the example directory, set up environment variables, install dependencies, and start the development server.

```bash
cd examples/react-native-expo
cp .env.example .env
pnpm install
pnpm run dev
```

```bash
pnpm run start
```

--------------------------------

### Core Library Usage Example

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/core/README.md

An example demonstrating the import and potential usage of several core modules from @quiltt/core, including AuthAPI, JsonWebTokenParse, Observable, and Storage. This snippet serves as a starting point for integrating these modules.

```javascript
import { AuthAPI } from '@quiltt/core'
import { JsonWebTokenParse } from '@quiltt/core/auth'
import { Observable } from '@quiltt/core/observables'
import { Storage } from '@quiltt/core/storage'
import { Timeoutable } from '@quiltt/core/timing'

// Example usage of the library modules
// ...
```

--------------------------------

### Install SwiftLint

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/ios/README.md

Install SwiftLint using Homebrew for local linting. This is a prerequisite for development.

```sh
brew install swiftlint
```

--------------------------------

### Install and Build Dependencies

Source: https://github.com/quiltt/quiltt-sdks/blob/main/README.md

Installs project dependencies and builds all packages. Use this before running any other commands.

```bash
pnpm install

pnpm run build
```

--------------------------------

### Install @quiltt/react with npm

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/react/README.md

Install the @quiltt/react package using npm.

```shell
npm install @quiltt/react
```

--------------------------------

### Start Development Server

Source: https://github.com/quiltt/quiltt-sdks/blob/main/README.md

Starts the project in development mode, enabling hot-reloading and other development features.

```bash
pnpm run dev
```

--------------------------------

### Install @quiltt/react with yarn

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/react/README.md

Install the @quiltt/react package using yarn.

```shell
yarn add @quiltt/react
```

--------------------------------

### Install @quiltt/react with pnpm

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/react/README.md

Install the @quiltt/react package using pnpm.

```shell
pnpm add @quiltt/react
```

--------------------------------

### Install React Dependencies

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/capacitor/README.md

Install the necessary packages for React integration with Capacitor.

```shell
npm install @quiltt/capacitor @quiltt/react react react-dom
```

--------------------------------

### Install Snapshot Release by Dist-Tag

Source: https://github.com/quiltt/quiltt-sdks/blob/main/RELEASING.md

Install the latest snapshot available under a specific dist-tag. This is convenient for always getting the most recent test build for a given tag.

```bash
pnpm add @quiltt/core@next
```

--------------------------------

### Build Example App for iOS

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/ios/fastlane/README.md

Build the example application for iOS projects using Fastlane.

```sh
[bundle exec] fastlane ios build_example_app
```

--------------------------------

### Flutter SDK Example Integration Tests

Source: https://github.com/quiltt/quiltt-sdks/blob/main/docs/testing.md

Navigate to the Flutter SDK example directory and run integration tests using the Flutter test command.

```bash
cd packages/flutter/example
flutter test integration_test/app_test.dart
```

--------------------------------

### Install Xcode Command Line Tools

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/android/fastlane/README.md

Ensure the latest version of Xcode command line tools are installed before proceeding with Fastlane setup.

```sh
xcode-select --install
```

--------------------------------

### Capacitor Native Setup Commands

Source: https://github.com/quiltt/quiltt-sdks/blob/main/examples/capacitor-react/README.md

Build the project and add native iOS and Android platforms, then sync the project.

```bash
pnpm run build
pnpm run cap:add:ios
pnpm run cap:add:android
pnpm run cap:sync
```

--------------------------------

### Install @quiltt/capacitor

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/capacitor/README.md

Install the SDK using npm and sync with Capacitor. Ensure your app's URL scheme is configured correctly for OAuth callbacks.

```shell
npm install @quiltt/capacitor
npx cap sync
```

--------------------------------

### Run Android Build Example App Action

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/android/fastlane/README.md

Execute the Fastlane action to build the example application for Android.

```sh
[bundle exec] fastlane android build_example_app
```

--------------------------------

### Install @quiltt/vue and vue

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/vue/README.md

Install the @quiltt/vue package and its peer dependency, vue, using npm.

```shell
npm install @quiltt/vue vue
```

--------------------------------

### React Native Expo Example Commands

Source: https://github.com/quiltt/quiltt-sdks/blob/main/docs/testing.md

Navigate to the React Native Expo example directory to build and run tests for iOS and Android, or use Maestro for flow testing.

```bash
cd examples/react-native-expo
pnpm run test:ios:build
pnpm run test:ios:run:ci
pnpm run test:android:build
pnpm run test:android:run:ci
maestro test maestro/connector-flow.yaml
maestro test maestro/oauth-callback-flow.yaml
```

--------------------------------

### Run Fastlane Build Example App Action

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/flutter/fastlane/README.md

Executes the build_example_app action using Fastlane. The 'bundle exec' prefix is optional.

```shell
[bundle exec] fastlane build_example_app
```

--------------------------------

### Install Snapshot Release by Exact Version

Source: https://github.com/quiltt/quiltt-sdks/blob/main/RELEASING.md

Use this command to install a specific snapshot version of a package. This is useful for testing a precise build.

```bash
pnpm add @quiltt/core@0.0.0-next-20260303T141200Z
```

--------------------------------

### Create .env File for Local Testing

Source: https://github.com/quiltt/quiltt-sdks/blob/main/examples/capacitor-react/README.md

Copy the example environment file to create a .env file for local testing with real values.

```bash
cp .env.example .env
```

--------------------------------

### Example Changeset File

Source: https://github.com/quiltt/quiltt-sdks/blob/main/RELEASING.md

This is an example of a generated changeset file. It specifies the package to be bumped and the type of version bump, along with a user-friendly description of the changes.

```markdown
---
"@quiltt/react": minor
---

Add new useAccountBalance hook for real-time balance updates.
```

--------------------------------

### Install Playwright and Run E2E Tests

Source: https://github.com/quiltt/quiltt-sdks/blob/main/examples/capacitor-react/README.md

Install Playwright dependencies and run the end-to-end tests against the development server.

```bash
pnpm run playwright:install
pnpm run test:e2e
```

--------------------------------

### Run Flutter Example on Android Emulator

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/flutter/example/README.md

Command to run the Flutter example on a specified Android emulator.

```sh
flutter run -d <EMULATOR_ID>
```

--------------------------------

### Install Maestro CLI

Source: https://github.com/quiltt/quiltt-sdks/blob/main/examples/react-native-expo/README.md

Command to install the Maestro CLI using Homebrew, a prerequisite for running Maestro tests.

```bash
brew install maestro
```

--------------------------------

### Run Flutter Example on iOS Simulator

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/flutter/example/README.md

Command to run the Flutter example on a specified iOS simulator.

```sh
flutter run -d <SIMULATOR_ID>
```

--------------------------------

### Install Vue 3 Dependencies

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/capacitor/README.md

Install the necessary packages for Vue 3 integration with Capacitor.

```shell
npm install @quiltt/capacitor @quiltt/vue vue
```

--------------------------------

### Clean and Re-run Flutter Example

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/flutter/example/README.md

Commands to clean build artifacts and re-run the Flutter example on a specified device.

```sh
flutter clean
flutter run -d <DEVICE_ID>
```

--------------------------------

### Reconnection Example

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/vue/README.md

Demonstrates how to use the `connection-id` prop for reconnecting an existing connection and the `force-remount-on-connection-change` prop.

```APIDOC
## Reconnection

Pass `connection-id` to reconnect an existing connection:

```vue
<QuilttButton connection-id="YOUR_EXISTING_CONNECTION_ID" ... />
```

When `connection-id` changes, the component automatically updates the existing connector instance with the new connection details. To force a complete remount instead, use `force-remount-on-connection-change`:

```vue
<QuilttButton 
  connection-id="YOUR_EXISTING_CONNECTION_ID"
  force-remount-on-connection-change
  ...
/>
```
```

--------------------------------

### Install @quiltt/react-native with npm

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/react-native/README.md

Installs the @quiltt/react-native package and its required peer dependencies using npm.

```shell
npm install base-64 react-native-webview react-native-url-polyfill
npm install @quiltt/react-native
```

--------------------------------

### Launch Quiltt Connector Example

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/react-native/README.md

Example of how to launch the Quiltt Connector within your React Native application. Ensure you have a session token and a connector ID.

```tsx
import { QuilttProvider, QuilttConnector } from '@quiltt/react-native'
import type { ConnectorSDKCallbackMetadata } from '@quiltt/react-native'

export const App = () => {
  // See: https://www.quiltt.dev/authentication/issuing-session-tokens
  const sessionToken = 'YOUR_SESSION_TOKEN_FROM_SERVER'

  // Use a universal link (iOS) or app link (Android) to redirect back to your app
  const appLauncherUrl = 'https://myapp.com/my_universal_link'

  const handleExitSuccess = (metadata: ConnectorSDKCallbackMetadata) => {
    console.log('Successfully created connection!', {
      connectionId: metadata.connectionId,
    })
  }

  return (
    <QuilttProvider token={sessionToken}>
      <QuilttConnector
        connectorId="YOUR_CONNECTOR_ID"
        appLauncherUrl={appLauncherUrl}
        themeMode="auto"

        // See the JavaScript API docs for the full list of available callbacks...
        onExitSuccess={handleExitSuccess}
      />
    </QuilttProvider>
  )
}

export default App
```

--------------------------------

### Common Repository Commands

Source: https://github.com/quiltt/quiltt-sdks/blob/main/docs/testing.md

Run these commands from the repository root to install dependencies, lint, typecheck, and execute unit or E2E tests.

```bash
pnpm install
pnpm run lint
pnpm run typecheck
pnpm run test:unit
pnpm run test:e2e
```

--------------------------------

### Install @quiltt/react-native with yarn

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/react-native/README.md

Installs the @quiltt/react-native package and its required peer dependencies using yarn.

```shell
yarn add base-64 react-native-webview react-native-url-polyfill
yarn add @quiltt/react-native
```

--------------------------------

### Check Flutter Toolchain and Device Setup

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/flutter/example/README.md

Commands to diagnose the Flutter toolchain and connected devices.

```sh
flutter doctor -v
flutter devices
```

--------------------------------

### Install @quiltt/core with yarn

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/core/README.md

Use this command to add the @quiltt/core package to your project when using yarn.

```shell
yarn add @quiltt/core
```

--------------------------------

### Verify Flutter and Dart Versions

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/flutter/example/README.md

Commands to check the installation paths and versions of Flutter and Dart.

```sh
which flutter
flutter --version
```

--------------------------------

### Install @quiltt/core with npm

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/core/README.md

Use this command to add the @quiltt/core package to your project when using npm.

```shell
npm install @quiltt/core
```

--------------------------------

### Install @quiltt/core with pnpm

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/core/README.md

Use this command to add the @quiltt/core package to your project when using pnpm.

```shell
pnpm add @quiltt/core
```

--------------------------------

### Integrate Quiltt Connector in SwiftUI

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/ios/README.md

Example demonstrating how to use the QuilttConnector within a SwiftUI view. This includes setting up the WebView and handling connection events.

```swift
import SwiftUI
import QuilttConnector
import WebKit

struct ConnectorView: View {
    @Binding var showHomeView: Bool
    @Binding var connectionId: String
    var body: some View {
        WebView(showHomeView: $showHomeView, connectionId: $connectionId)
    }
}

struct WebView: UIViewRepresentable {
    @Binding var showHomeView: Bool
    @Binding var connectionId: String
    @State var config = QuilttConnectorConnectConfiguration(
        connectorId: "<CONNECTOR_ID>",
        appLauncherUrl: "<YOUR_HTTPS_UNIVERSAL_LINK>",
        themeMode: "auto"
    )

    func makeUIView(context: Context) -> WKWebView {
        let quilttConnector = QuilttConnector.init()
        quilttConnector.authenticate(token: "<SESSION_TOKEN>")
        let webview = quilttConnector.connect(config: config,
                                              onEvent: { eventType, metadata in
                                                print("onEvent \(eventType), \(metadata)")
                                              },
                                              onExitSuccess: { metadata in
                                                print("onExitSuccess \(metadata)")
                                                if let newConnectionId = metadata.connectionId {
                                                    connectionId = newConnectionId
                                                }
                                                showHomeView = true
                                              },
                                              onExitAbort: { metadata in
                                                print("onExitAbort \(metadata)")
                                                showHomeView = true
                                              },
                                              onExitError: { metadata in
                                                print("onExitError \(metadata)")
                                                showHomeView = true
                                              })
        return webview
    }

    func updateUIView(_ uiView: WKWebView, context: Context) {
        // Use this method to update the WKWebView with new configuration settings.
    }
}

#Preview {
    ConnectorView(showHomeView: .constant(false), connectionId: .constant("connectionId"))
}
```

--------------------------------

### Precache iOS Artifacts

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/flutter/example/README.md

Command to re-download iOS artifacts if the compiler fails to start.

```sh
flutter precache --ios
```

--------------------------------

### QuilttProvider Example

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/react/README.md

A provider component for passing Session and settings down to the rest of your application. Requires a session token obtained from the server.

```tsx
import { QuilttProvider } from '@quiltt/react'

const Layout = ({ children }) => {
  const sessionToken = 'YOUR_SESSION_TOKEN_FROM_SERVER'

  return <QuilttProvider token={sessionToken}>{children}</QuilttProvider>
}

export default Layout
```

--------------------------------

### Install @quiltt/react-native with pnpm

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/react-native/README.md

Installs the @quiltt/react-native package and its required peer dependencies using pnpm. Ensure 'node-linker=hoisted' is set in .npmrc for Expo apps.

```shell
# Make sure to add `node-linker=hoisted` to your .npmrc when using pnpm in an Expo app.
$ pnpm add base-64 react-native-webview react-native-url-polyfill
$ pnpm add @quiltt/react-native
```

--------------------------------

### Add Quiltt Connector to Flutter Project

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/flutter/README.md

Install the quiltt_connector package using the Flutter CLI.

```sh
flutter pub add quiltt_connector
```

--------------------------------

### QuilttButton Example

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/react/README.md

Launches the Quiltt Connector as a pop-out modal. Pass connectorId, handleExitSuccess callback, and any other props like className, style, or themeMode.

```tsx
import { useState } from 'react'
import { QuilttButton } from '@quiltt/react'
import type { ConnectorSDKCallbackMetadata } from '@quiltt/react'

export const App = () => {
  const [connectionId, setConnectionId] = useState<string>()
  const handleExitSuccess = (metadata: ConnectorSDKCallbackMetadata) => {
    setConnectionId(metadata?.connectionId)
  }

  return (
    <QuilttButton
      connectorId="YOUR_CONNECTOR_ID"
      onExitSuccess={handleExitSuccess}
      className="my-css-class"
      style={{ borderWidth: '2px' }}
      themeMode="auto"
      // ... other props to pass through to the button
    >
      Add Account
    </QuilttButton>
  )
}
export default App
```

--------------------------------

### Test App Links with ADB

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/android/README.md

Use ADB commands to test and verify App Links functionality. This includes starting a link to check if it opens the app and verifying the App Link configuration.

```bash
# Test App Link
adb shell am start \
  -W -a android.intent.action.VIEW \
  -d "https://your-app-domain.com/quiltt/oauth/test" \
  your.package.name
```

```bash
# Verify App Links
adb shell pm verify-app-links --re-verify your.package.name
```

```bash
# Check verification status
adb shell pm get-app-links your.package.name
```

--------------------------------

### Run on Android Emulator

Source: https://github.com/quiltt/quiltt-sdks/blob/main/examples/react-native-expo/README.md

Command to build and run the Expo app on an Android emulator. Requires Android Studio and emulator setup.

```bash
pnpm run android
```

--------------------------------

### QuilttContainer Example

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/react/README.md

Launches the Quiltt Connector inside a container. Pass connectorId, handleExitSuccess callback, and any other props like className, style, or themeMode.

```tsx
import { useState } from 'react'
import { QuilttContainer } from '@quiltt/react'
import type { ConnectorSDKCallbackMetadata } from '@quiltt/react'

export const App = () => {
  const [connectionId, setConnectionId] = useState<string>()
  const handleExitSuccess = (metadata: ConnectorSDKCallbackMetadata) => {
    setConnectionId(metadata?.connectionId)
  }

  return (
    <QuilttContainer
      connectorId="YOUR_CONNECTOR_ID"
      onExitSuccess={handleExitSuccess}
      className="my-css-class"
      style={{ height: '100%' }}
      themeMode="auto"
      // ... other props to pass through to the container
    />
  )
}

export default App
```

--------------------------------

### Flutter Deep Link Handling with app_links

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/flutter/README.md

Example of how to initialize and listen for deep links using the `app_links` package in Flutter. Handles both initial links on app launch and subsequent links while the app is running.

```dart
import 'package:app_links/app_links';

class _MyAppState extends State<MyApp> {
  late AppLinks _appLinks;
  StreamSubscription<Uri>? _linkSubscription;

  @override
  void initState() {
    super.initState();
    _initDeepLinks();
  }

  void _initDeepLinks() async {
    _appLinks = AppLinks();

    // Listen for incoming links when app is already running
    _linkSubscription = _appLinks.uriLinkStream.listen((uri) {
      debugPrint('Deep link received: $uri');
      _handleDeepLink(uri);
    });

    // Handle links when app is launched from a deep link
    final uri = await _appLinks.getInitialLink();
    if (uri != null) {
      debugPrint('App launched from deep link: $uri');
      _handleDeepLink(uri);
    }
  }

  void _handleDeepLink(Uri uri) {
    // Handle the OAuth redirect here
    // Extract any necessary parameters from the URI
    // Navigate to appropriate screen or trigger callbacks
  }

  @override
  void dispose() {
    _linkSubscription?.cancel();
    super.dispose();
  }
}
```

--------------------------------

### Run on iOS Simulator

Source: https://github.com/quiltt/quiltt-sdks/blob/main/examples/react-native-expo/README.md

Command to build and run the Expo app on an iOS simulator. Requires Xcode and native toolchain setup.

```bash
pnpm run ios
```

--------------------------------

### Run iOS E2E Tests (Detox)

Source: https://github.com/quiltt/quiltt-sdks/blob/main/examples/react-native-expo/README.md

Command to build and run smoke tests on iOS using Detox. Requires native toolchains and simulator setup.

```bash
pnpm run test:ios
```

--------------------------------

### Run Android E2E Tests (Detox)

Source: https://github.com/quiltt/quiltt-sdks/blob/main/examples/react-native-expo/README.md

Command to build and run smoke tests on Android using Detox. Requires native toolchains and emulator setup.

```bash
pnpm run test:android
```

--------------------------------

### Handle OAuth Deep Links with QuilttConnector

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/react-native/README.md

Example demonstrating how to handle deep links for OAuth callbacks, primarily for Android. The `ref` prop is required, and the deep link URL must match your `appLauncherUrl`.

```tsx
import { useEffect, useRef } from 'react'
import { Linking, View } from 'react-native'
import { QuilttProvider, QuilttConnector } from '@quiltt/react-native'
import type { ConnectorSDKCallbackMetadata, QuilttConnectorHandle } from '@quiltt/react-native'

export const ConnectorScreen = () => {
  const connectorRef = useRef<QuilttConnectorHandle>(null)

  const sessionToken = 'YOUR_SESSION_TOKEN_FROM_SERVER'
  const appLauncherUrl = 'https://myapp.com/quiltt/callback'

  // Listen for deep links and handle OAuth callbacks
  useEffect(() => {
    const subscription = Linking.addEventListener('url', (event) => {
      console.log('Deep link received:', event.url)

      // Check if this is an OAuth callback for Quiltt
      if (event.url.includes('quiltt-connect/callback') || event.url.includes('quiltt/callback')) {
        console.log('Processing Quiltt OAuth callback')
        connectorRef.current?.handleOAuthCallback(event.url)
      }
    })

    return () => subscription.remove()
  }, [])

  const handleExitSuccess = (metadata: ConnectorSDKCallbackMetadata) => {
    console.log('Successfully created connection!', {
      connectionId: metadata.connectionId,
    })
  }

  return (
    <QuilttProvider token={sessionToken}>
      <View style={{ flex: 1 }}>
        <QuilttConnector
          ref={connectorRef}
          connectorId="YOUR_CONNECTOR_ID"
          appLauncherUrl={appLauncherUrl}
          onExitSuccess={handleExitSuccess}
        />
      </View>
    </QuilttProvider>
  )
}

export default ConnectorScreen
```

--------------------------------

### Launch Connect Flow

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/android/README.md

Launches the connect flow and returns a configured WebView. Callbacks can be provided for various events.

```kotlin
fun connect(
    config: QuilttConnectorConnectConfiguration,
    onEvent: ConnectorSDKOnEventCallback? = null,
    onExit: ConnectorSDKOnEventExitCallback? = null,
    onExitSuccess: ConnectorSDKOnExitSuccessCallback? = null,
    onExitAbort: ConnectorSDKOnExitAbortCallback? = null,
    onExitError: ConnectorSDKOnExitErrorCallback? = null
): QuilttConnectorWebView
```

--------------------------------

### Run SwiftLint

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/ios/README.md

Execute SwiftLint from the packages/ios/ directory to enforce code style and quality.

```sh
swiftlint lint --strict
```

--------------------------------

### Run OAuth Handoff Simulation (Maestro)

Source: https://github.com/quiltt/quiltt-sdks/blob/main/examples/react-native-expo/README.md

Command to simulate the OAuth callback handoff process using Maestro.

```bash
pnpm run test:maestro:oauth
```

--------------------------------

### iOS ExampleSwiftUI UI Tests

Source: https://github.com/quiltt/quiltt-sdks/blob/main/docs/testing.md

Execute UI tests for the iOS ExampleSwiftUI project using xcodebuild, specifying the scheme and a simulator destination.

```bash
cd packages/ios/ExampleSwiftUI
xcodebuild test \
  -scheme ExampleSwiftUI \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro'
```

--------------------------------

### Open Native Projects

Source: https://github.com/quiltt/quiltt-sdks/blob/main/examples/capacitor-react/README.md

Open the native iOS and Android projects in their respective IDEs.

```bash
pnpm run cap:open:ios
pnpm run cap:open:android
```

--------------------------------

### Open iOS Simulator

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/flutter/example/README.md

Command to open the iOS simulator.

```sh
open -a Simulator
```

--------------------------------

### useQuilttSession Hook Example

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/react/README.md

Manage the lifecycle of Quiltt Sessions using the `useQuilttSession` hook. Import and revoke sessions as needed.

```tsx
import { useCallback, useEffect } from 'react'

import { useQuilttSession } from '@quiltt/react'

const App = () => {
  const { session, importSession, revokeSession } = useQuilttSession()

  useEffect(() => {
    // Import session from API call, local storage, query param, etc.
    importSession('{SESSION_TOKEN}')
  }, [importSession])

  const logOut = useCallback(() => {
    // Revoke and clear the Quiltt session
    revokeSession()

    // do other stuff!
  }, [revokeSession])

  if (session) {
    console.log('Session token: ', session.token)
  } else {
    console.log('No Session available')
  }

  return (
    <>
      <div>Hello world!</div>
      <button onClick={logOut}>Log Out</button>
    </>
  )
}

export default App
```

--------------------------------

### Create Digital Asset Links File

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/android/README.md

Host a Digital Asset Links file at the specified URL to verify the app's association with the domain. Replace placeholders with your app's package name and signing certificate fingerprint.

```json
[
{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.yourcompany.yourapp",
    "sha256_cert_fingerprints": ["YOUR_APP_SIGNING_CERTIFICATE_SHA256"]
  }
}]
```

--------------------------------

### useQuilttConnector Hook Example

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/react/README.md

Use the `useQuilttConnector` hook to manage the lifecycle of Quiltt Connector. Configure event handlers and theme mode.

```tsx
import { useQuilttConnector } from '@quiltt/react'

const App = () => {
  const { open } = useQuilttConnector('YOUR_CONNECTOR_ID', {
    onEvent: (type) => console.log(`Received Quiltt Event: ${type}`),
    onExitSuccess: (metadata) => console.log("Connector onExitSuccess", metadata.connectionId),
    themeMode: 'dark',
  })

  return(
    <button onClick={open}>
      Launch Connector
    </button>
  )
}
```

--------------------------------

### Create a Changeset for Release

Source: https://github.com/quiltt/quiltt-sdks/blob/main/README.md

Use this command to create a new changeset file. This is the primary step for contributors to initiate a release process for packages.

```bash
pnpm changeset
```

--------------------------------

### Connect Configuration

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/android/README.md

Defines the configuration for initiating a new connection. The institution parameter is optional.

```kotlin
data class QuilttConnectorConnectConfiguration(
    val connectorId: String,
    val appLauncherUrl: String,
    val institution: String? = null // Optional institution filter
)
```

--------------------------------

### Flutter SDK Usage: Connect Flow

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/flutter/README.md

Demonstrates how to initialize and launch the Quiltt Connect flow. Ensure you handle the various callback events for success, abort, and errors.

```dart
import 'package:quiltt_connector/quiltt_connector.dart';
import 'package:quiltt_connector/configuration.dart';

class _Example extends State {
  connect() {
    QuilttConnectorConfiguration config = QuilttConnectorConfiguration(
      connectorId: "<CONNECTOR_ID>",
      appLauncherUrl: "<YOUR_HTTPS_APP_LINK>",
      themeMode: "auto",
    );

    QuilttConnector quilttConnector = QuilttConnector();

    // Authenticate profile
    quilttConnector.authenticate(token);

    // Launch Connect Flow
    quilttConnector.connect(
      context,
      config,

      // Handle Callbacks
      onEvent: (event) {
        debugPrint("onEvent ${event.type}: ${event.eventMetadata}");
      },
      onExitSuccess: (event) {
        debugPrint("onExitSuccess: ${event.eventMetadata}");
        _setConnectionId(event.eventMetadata.connectionId!);
      },
      onExitAbort: (event) {
        debugPrint("onExitAbort: ${event.eventMetadata}");
      },
      onExitError: (event) {
        debugPrint("onExitError: ${event.eventMetadata}");
      }
    );
  }

  reconnect() {
    QuilttConnectorConfiguration config = QuilttConnectorConfiguration(
      connectorId: "<CONNECTOR_ID>",
      connectionId: "<CONNECTION_ID>", // To support the Reconnect Flow
      appLauncherUrl: "<YOUR_HTTPS_APP_LINK>"
    );

    QuilttConnector quilttConnector = QuilttConnector();

    // Authenticate profile
    quilttConnector.authenticate(token);

    // Launch Reconnect Flow
    quilttConnector.reconnect(
      context,
      config,

      // Handle Callbacks
      onEvent: (event) {
        debugPrint("onEvent: ${event.eventMetadata}");
      },
      onExit: (event) {
        debugPrint("onExit: ${event.eventMetadata}");
      },
      onExitSuccess: (event) {
        debugPrint("onExitSuccess: ${event.eventMetadata}");
        _setConnectionId(event.eventMetadata.connectionId!);
      },
      onExitAbort: (event) {
        debugPrint("onExitAbort: ${event.eventMetadata}");
      },
      onExitError: (event) {
        debugPrint("onExitError: ${event.eventMetadata}");
      }
    );
  }

  @override
  Widget build(BuildContext context) {
    return Container();
  }
}

```

--------------------------------

### Android SDK Package Tests

Source: https://github.com/quiltt/quiltt-sdks/blob/main/docs/testing.md

Change directory to the Android package and execute connected Android tests using Gradle.

```bash
cd packages/android
./gradlew app:connectedDebugAndroidTest
```

--------------------------------

### Auth API Client Usage

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/core/README.md

Demonstrates how to instantiate and use the AuthAPI client to check session token validity and revoke tokens. Ensure you have the AuthAPI imported.

```typescript
// Import Auth API client
import { AuthAPI } from '@quiltt/core'

// Set up client instance
const auth = new AuthAPI()

// Check if a Session token is valid
await auth.ping('{SESSION_TOKEN}')

// Revoke a Session token
await auth.revoke('{SESSION_TOKEN}')
```

--------------------------------

### Importing Core Modules

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/core/README.md

Shows how to import various modules from the @quiltt/core package, including AuthAPI, JsonWebTokenParse, Observable, Storage, and Timeoutable. Subpath imports are used for better tree-shaking.

```typescript
import { AuthAPI } from '@quiltt/core'
import { JsonWebTokenParse } from '@quiltt/core/auth'
import { Observable } from '@quiltt/core/observables'
import { Timeoutable } from '@quiltt/core/timing'
import { Storage } from '@quiltt/core/storage'
import { endpointAuth } from '@quiltt/core/config'
```

--------------------------------

### Initialize useQuilttConnector

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/vue/README.md

Import and initialize the useQuilttConnector composable with a connector ID and optional configuration like themeMode and onExitSuccess callbacks.

```typescript
import { useQuilttConnector } from '@quiltt/vue'

const { open } = useQuilttConnector('YOUR_CONNECTOR_ID', {
  onExitSuccess: (m) => console.log('Connected:', m.connectionId),
  themeMode: 'auto',
})
```

--------------------------------

### Handle App Links in Activity

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/android/README.md

Implement logic in your MainActivity to handle incoming App Links. This includes processing the intent action and data, and extracting OAuth parameters from the URI.

```kotlin
class MainActivity : AppCompatActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // Handle the incoming app link
        handleIntent(intent)
    }
    
    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        handleIntent(intent)
    }
    
    private fun handleIntent(intent: Intent) {
        val appLinkAction = intent.action
        val appLinkData = intent.data
        
        if (Intent.ACTION_VIEW == appLinkAction && appLinkData != null) {
            println("Received App Link: $appLinkData")
            handleOAuthRedirect(appLinkData)
        }
    }
    
    private fun handleOAuthRedirect(uri: Uri) {
        // Handle OAuth redirect
        // Extract parameters and process the redirect
        val code = uri.getQueryParameter("code")
        val state = uri.getQueryParameter("state")
        
        // Process OAuth callback
    }
}
```

--------------------------------

### Run on Web

Source: https://github.com/quiltt/quiltt-sdks/blob/main/examples/react-native-expo/README.md

Command to run the Expo app in a web browser.

```bash
pnpm run web
```

--------------------------------

### QuilttConnector.connect

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/android/README.md

Launches the connect flow for establishing a new connection. It returns a configured WebView for user interaction.

```APIDOC
## QuilttConnector.connect

### Description
Launches the connect flow and returns a configured WebView.

### Method
```kotlin
fun connect(
    config: QuilttConnectorConnectConfiguration,
    onEvent: ConnectorSDKOnEventCallback? = null,
    onExit: ConnectorSDKOnEventExitCallback? = null,
    onExitSuccess: ConnectorSDKOnExitSuccessCallback? = null,
    onExitAbort: ConnectorSDKOnExitAbortCallback? = null,
    onExitError: ConnectorSDKOnExitErrorCallback? = null
): QuilttConnectorWebView
```

### Parameters
#### Path Parameters
- **config** (QuilttConnectorConnectConfiguration) - Required - Configuration for the connect flow.
- **onEvent** (ConnectorSDKOnEventCallback?) - Optional - Callback for general events.
- **onExit** (ConnectorSDKOnEventExitCallback?) - Optional - Callback for exit events.
- **onExitSuccess** (ConnectorSDKOnExitSuccessCallback?) - Optional - Callback for successful exit.
- **onExitAbort** (ConnectorSDKOnExitAbortCallback?) - Optional - Callback for aborted exit.
- **onExitError** (ConnectorSDKOnExitErrorCallback?) - Optional - Callback for exit errors.

### Configuration Types
#### QuilttConnectorConnectConfiguration
```kotlin
data class QuilttConnectorConnectConfiguration(
    val connectorId: String,
    val appLauncherUrl: String,
    val institution: String? = null // Optional institution filter
)
```
```

--------------------------------

### Import useQuilttSession Hook

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/react/README.md

Import the `useQuilttSession` hook from the subpath for better tree-shaking.

```tsx
import { useQuilttSession } from '@quiltt/react/hooks'
```

--------------------------------

### Run Fastlane Check Publish Action

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/flutter/fastlane/README.md

Executes the check_publish action using Fastlane. The 'bundle exec' prefix is optional.

```shell
[bundle exec] fastlane check_publish
```

--------------------------------

### Run Platform-Specific Tests

Source: https://github.com/quiltt/quiltt-sdks/blob/main/README.md

Commands for running tests on native Android, Flutter, and iOS platforms. Ensure you are in the respective package directory before executing.

```bash
# Android — run from packages/android/
./gradlew connector:test

# Flutter — run from packages/flutter/
flutter test

# iOS — run from packages/ios/
swift test
```

--------------------------------

### Run All Maestro Flows

Source: https://github.com/quiltt/quiltt-sdks/blob/main/examples/react-native-expo/README.md

Command to execute all Maestro test flows defined in the folder.

```bash
pnpm run test:maestro
```

--------------------------------

### Initialize and Use useQuilttSession

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/vue/README.md

Initialize useQuilttSession with an optional environmentId. It provides reactive session state and methods to import, identify, authenticate, revoke, and forget sessions.

```typescript
import { useQuilttSession } from '@quiltt/vue'

const {
  session,             // Reactive session state
  importSession,       // Import an existing token
  identifySession,     // Start auth flow (email/phone)
  authenticateSession, // Complete auth (passcode)
  revokeSession,       // Invalidate session server-side
  forgetSession,       // Clear session locally
} = useQuilttSession('YOUR_ENVIRONMENT_ID') // environmentId is optional

await importSession('YOUR_SESSION_TOKEN')
console.log(session.value?.token)
```

--------------------------------

### List Flutter Devices

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/flutter/example/README.md

Command to list available Flutter devices, including simulators and emulators.

```sh
flutter devices
```

--------------------------------

### Capacitor Plugin Import

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/capacitor/README.md

Import the QuilttConnector from the `@quiltt/capacitor` package.

```typescript
import { QuilttConnector } from '@quiltt/capacitor'
```

--------------------------------

### Launch Reconnect Flow

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/android/README.md

Launches the reconnect flow for existing connections, returning a configured WebView. Callbacks can be provided for various events.

```kotlin
fun reconnect(
    config: QuilttConnectorReconnectConfiguration,
    onEvent: ConnectorSDKOnEventCallback? = null,
    onExit: ConnectorSDKOnEventExitCallback? = null,
    onExitSuccess: ConnectorSDKOnExitSuccessCallback? = null,
    onExitAbort: ConnectorSDKOnExitAbortCallback? = null,
    onExitError: ConnectorSDKOnExitErrorCallback? = null
): QuilttConnectorWebView
```

--------------------------------

### Basic Quiltt Connector Implementation (Kotlin)

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/android/README.md

Implement the Quiltt Connector in an Android Activity using a view-based approach. This involves authenticating with a session token and launching the Connect Flow with specified configurations. Remember to destroy the webView in onDestroy.

```kotlin
package app.quiltt.example

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.widget.Toast
import androidx.constraintlayout.widget.ConstraintLayout
import app.quiltt.connector.QuilttConnector
import app.quiltt.connector.QuilttConnectorConnectConfiguration
import app.quiltt.connector.QuilttConnectorWebView

class QuilttConnectorActivity : AppCompatActivity() {
    private lateinit var webView: QuilttConnectorWebView
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_quiltt_connector)

        val connectorLayout = findViewById<ConstraintLayout>(R.id.connector_layout)
        val quilttConnector = QuilttConnector(this)
        
        // Authenticate with session token
        quilttConnector.authenticate("<SESSION_TOKEN>")
        
        val config = QuilttConnectorConnectConfiguration(
            connectorId = "<CONNECTOR_ID>",
            appLauncherUrl = "<YOUR_HTTPS_APP_LINK>",
            themeMode = "auto"
        )

        // Launch Connect Flow
        webView = quilttConnector.connect(
            config = config,
            onEvent = { eventType, metadata ->
                println("onEvent $eventType: $metadata")
            },
            onExitSuccess = { metadata ->
                println("onExitSuccess: $metadata")
                Toast.makeText(this, "Connected: ${metadata.connectionId}", Toast.LENGTH_LONG).show()
                finish()
            },
            onExitAbort = { metadata ->
                println("onExitAbort: $metadata")
                finish()
            },
            onExitError = { metadata ->
                println("onExitError: $metadata")
                Toast.makeText(this, "Connection failed", Toast.LENGTH_LONG).show()
                finish()
            }
        )

        connectorLayout.addView(webView)
    }

    override fun onDestroy() {
        webView.destroy()
        super.onDestroy()
    }
}
```

--------------------------------

### Run Connector Flow Test (Maestro)

Source: https://github.com/quiltt/quiltt-sdks/blob/main/examples/react-native-expo/README.md

Command to execute the connector flow test using Maestro. Maestro tests are written in YAML.

```bash
pnpm run test:maestro:connector
```

--------------------------------

### Fixed Versions Configuration

Source: https://github.com/quiltt/quiltt-sdks/blob/main/RELEASING.md

This JSON array lists all packages that are configured to release together with the same fixed version.

```json
[
  "@quiltt/core",
  "@quiltt/react",
  "@quiltt/react-native",
  "@quiltt/vue",
  "@quiltt/capacitor",
  "@quiltt/android",
  "@quiltt/flutter",
  "@quiltt/ios"
]
```

--------------------------------

### Run All E2E Tests (Detox)

Source: https://github.com/quiltt/quiltt-sdks/blob/main/examples/react-native-expo/README.md

Command to execute smoke tests on both iOS and Android platforms using Detox.

```bash
pnpm run test:e2e
```

--------------------------------

### Import Plugin Utilities

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/vue/README.md

Import plugin utilities like QuilttPlugin, QuilttSessionKey, and QuilttSetSessionKey from the dedicated '@quiltt/vue/plugin' subpath.

```typescript
import { QuilttPlugin, QuilttSessionKey, QuilttSetSessionKey } from '@quiltt/vue/plugin'
```

--------------------------------

### Import QuilttButton from subpath

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/react/README.md

Import QuilttButton component from its subpath for better tree-shaking.

```tsx
import { QuilttButton } from '@quiltt/react/components'
```

--------------------------------

### Run Fastlane Release Minor Action

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/flutter/fastlane/README.md

Executes the release_minor action using Fastlane. The 'bundle exec' prefix is optional.

```shell
[bundle exec] fastlane release_minor
```

--------------------------------

### Build Swift Package for iOS

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/ios/fastlane/README.md

Build the Swift Package for iOS projects using Fastlane.

```sh
[bundle exec] fastlane ios build_swift_package
```

--------------------------------

### Native Plugin Methods

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/capacitor/README.md

This section details the methods available on the native Capacitor plugin for interacting with the Quiltt connector.

```APIDOC
## Native Plugin Methods

### `openUrl({ url })`

#### Description
Opens the provided URL in the system's default browser.

### Method
`openUrl`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **url** (string) - Required - The URL to open.

### Request Example
```typescript
await QuilttConnector.openUrl({ url: 'https://...' })
```

### Response
#### Success Response (200)
No specific response body is detailed, operation is typically asynchronous.

### `getAppLauncherUrl()`

#### Description
Returns the URL configured for launching the application, often used for Universal Links or App Links.

### Method
`getAppLauncherUrl`

### Parameters
None

### Response
#### Success Response (200)
- **appLauncherUrl** (string) - The application launcher URL.

### `addListener('deepLink', callback)`

#### Description
Listens for incoming deep link callbacks, typically used to handle OAuth redirects or other external app interactions.

### Method
`addListener`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters for addListener
- **eventName** (string) - Must be `'deepLink'`.
- **callback** (function) - A function that receives the deep link data.
  - **url** (string) - The deep link URL received.

### Request Example
```typescript
await QuilttConnector.addListener('deepLink', ({ url }) => {
  console.log('OAuth callback:', url)
})
```

### Response
#### Success Response (200)
No specific response body is detailed, operation is typically asynchronous.

### `removeAllListeners()`

#### Description
Removes all event listeners that have been registered with the plugin.

### Method
`removeAllListeners`

### Parameters
None

### Response
#### Success Response (200)
No specific response body is detailed, operation is typically asynchronous.
```

--------------------------------

### Run Fastlane Release Patch Action

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/flutter/fastlane/README.md

Executes the release_patch action using Fastlane. The 'bundle exec' prefix is optional.

```shell
[bundle exec] fastlane release_patch
```

--------------------------------

### Authenticate SDK with Token

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/android/README.md

Use this method to authenticate the SDK with a provided session token.

```kotlin
fun authenticate(token: String)
```

--------------------------------

### QuilttButton with Force Remount on Connection Change

Source: https://github.com/quiltt/quiltt-sdks/blob/main/packages/vue/README.md

Use `force-remount-on-connection-change` to force a complete remount when `connection-id` changes. This is useful as a fallback for ensuring a clean state.

```vue
<QuilttButton 
  connection-id="YOUR_EXISTING_CONNECTION_ID"
  force-remount-on-connection-change
  ...
/>
```