native-fn/README.md

# Native.App API Reference

## Overview
Native.App provides a unified interface for opening native applications across different platforms with cross-platform compatibility.

---

## Interface

### App
Main interface for native app operations.

```typescript
interface App {
  open: (options: AppOpenOptions, target?: WindowProxy) => Promise<AppOpenState>;
  messenger: Messenger;
}
```

---

## Methods

### `Native.App.open()`

Opens a native application with platform-specific configurations.

#### Syntax
```typescript
Native.App.open(options: AppOpenOptions, target?: WindowProxy): Promise<AppOpenState>
```

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `options` | `AppOpenOptions` | ✅ | Platform-specific app configuration |
| `target` | `WindowProxy` | ❌ | Target window (default: current window) |

#### Platform Options

Each platform requires different configuration parameters:

##### Android
```typescript
{
  [Native.Constant.OS.Android]: {
    scheme: string;      // App URL scheme
    packageName: string; // Android package name
  }
}
```

##### iOS
```typescript
{
  [Native.Constant.OS.iOS]: {
    scheme: string;      // App URL scheme
    packageName: string; // Bundle ID
    trackId?: string;    // App Store track ID (optional)
  }
}
```

##### Windows
```typescript
{
  [Native.Constant.OS.Windows]: {
    scheme: string;    // App URL scheme
    productId: string; // Microsoft Store product ID
  }
}
```

##### macOS
```typescript
{
  [Native.Constant.OS.MacOS]: {
    scheme: string;      // App URL scheme
    packageName: string; // Bundle ID
    trackId?: string;    // App Store track ID (optional)
  }
}
```

---

## Examples

### Basic Usage

Open Microsoft Excel across all platforms:

```typescript
// Create a new tab for the app to open in
const newTab: WindowProxy = window.open("about:blank");

// Configure Excel for all platforms
const excelConfig = {
  [Native.Constant.OS.Android]: {
    scheme: "excel://",
    packageName: "com.microsoft.office.excel",
  },
  [Native.Constant.OS.iOS]: {
    scheme: "excel://",
    packageName: "com.microsoft.Office.Excel",
    // trackId: "586683407", // Uncomment if needed
  },
  [Native.Constant.OS.Windows]: {
    scheme: "excel://",
    productId: "cfq7ttc0k5bf",
  },
  [Native.Constant.OS.MacOS]: {
    scheme: "excel://",
    packageName: "com.microsoft.Excel",
    // trackId: "462058435", // Uncomment if needed
  }
};

// Open Excel
try {
  const result = await Native.App.open(excelConfig, newTab);
  console.log('Excel opened successfully:', result);
} catch (error) {
  console.error('Failed to open Excel:', error);
}
```

### Single Platform Example

Open an app on a specific platform:

```typescript
// Android only
const androidConfig = {
  [Native.Constant.OS.Android]: {
    scheme: "myapp://",
    packageName: "com.example.myapp",
  }
};

await Native.App.open(androidConfig);
```

---

## Return Value

Returns `Promise<AppOpenState>` with information about the app opening state.

---

## Error Handling

The method may reject with errors in the following cases:
- App is not installed on the device
- Invalid configuration parameters
- Platform not supported
- Network connectivity issues

```typescript
try {
  await Native.App.open(config);
} catch (error) {
  if (error.code === 'APP_NOT_FOUND') {
    // Handle app not installed
  } else if (error.code === 'INVALID_CONFIG') {
    // Handle configuration error
  }
}
```

---

## Best Practices

### ✅ Do
- Always provide configurations for all target platforms
- Use `window.open("about:blank")` for better user experience
- Handle errors gracefully with try-catch blocks
- Test on all target platforms

### ❌ Don't
- Hardcode platform detection in your application logic
- Ignore error handling
- Use deprecated package names or schemes

---

## Platform-Specific Notes

### Android
- Package names follow reverse domain notation
- Ensure the app supports the specified URL scheme

### iOS
- Bundle IDs are case-sensitive
- Track IDs are optional but recommended for App Store linking

### Windows
- Product IDs can be found in the Microsoft Store URL
- Some apps may require additional permissions

### macOS
- Bundle IDs should match the app's Info.plist
- Track IDs link to Mac App Store entries