@recursyve/deeplinks-client/README.md

Node.js client for Recursyve's Deeplinks API

# Deeplinks Node.js Client

A TypeScript/JavaScript client for the Deeplinks API built with axios.

## Installation

```bash
npm install
npm run build
```

## Usage

### Basic Setup

```typescript
import { DeeplinksClient } from "./dist";

// Create a client instance
const client = new DeeplinksClient({
    baseURL: "http://localhost:3000",
    apiKey: "your-api-key-here", // You need to provide an API key
    timeout: 30000,
});
```

### Applications

```typescript
// Create an Android application
const androidApp = await client.createApplication({
    name: "My Android App",
    platform: "android",
    android: {
        bundleId: "com.example.myapp",
        certSHA256: ["sha256:..."],
    },
});

// Create an iOS application
const iosApp = await client.createApplication({
    name: "My iOS App",
    platform: "ios",
    ios: {
        bundleId: "com.example.myapp",
        appId: "123456789",
        teamId: "TEAM123",
    },
});

// Update an application
await client.updateApplication(androidApp.id, {
    name: "Updated App Name",
    android: {
        certSHA256: {
            add: ["sha256:newcert"],
            remove: ["sha256:oldcert"],
        },
    },
});
```

### Domains

```typescript
// Create a new domain
const domain = await client.createDomain({
    domain: "example.com",
});
```

### Dynamic Links

```typescript
// Create a dynamic link
const dynamicLink = await client.createDynamicLink({
    domain: "example.com",
    urlSuffix: "product/123",
    deepLinkUrl: "myapp://product/123",
    name: "Product Link",
    android: {
        bundleId: "com.example.myapp",
        fallbackTo: "store",
    },
    ios: {
        bundleId: "com.example.myapp",
        fallbackTo: "url",
        fallbackUrl: "https://example.com/fallback",
    },
});

// Fetch link details
const linkDetails = await client.fetchLinkDetails(dynamicLink.code, {
    domain: "example.com",
});
```

### Error Handling

```typescript
try {
    const application = await client.createApplication({
        name: "My App",
        platform: "android",
        android: {
            bundleId: "com.example.myapp",
        },
    });
} catch (error) {
    if (error.status === 400) {
        console.error("Bad request:", error.message);
    } else if (error.status === 401) {
        console.error("Unauthorized - check your API key");
    } else if (error.status === 404) {
        console.error("Resource not found");
    } else {
        console.error("Unexpected error:", error.message);
    }
}
```

### Custom Requests

```typescript
// Make a custom request
const response = await client.request({
    method: "GET",
    url: "/custom-endpoint",
    params: { custom: "param" },
});
```

## API Reference

### Constructor Options

- `apiKey` (string): **Required** API key for authentication
- `baseURL` (string): Base URL for the API (default: "http://localhost:3000")
- `timeout` (number): Request timeout in milliseconds (default: 30000)
- `headers` (object): Additional headers to include in requests

### Methods

#### Applications

- `createApplication(data)`: Create a new application
- `updateApplication(id, data)`: Update an application by ID

#### Domains

- `createDomain(data)`: Create a new domain

#### Dynamic Links

- `createDynamicLink(data)`: Create a new dynamic link
- `fetchLinkDetails(code, params)`: Fetch dynamic link details by code

#### Utility

- `request(config)`: Make a custom request with full control

## Development

### Code Quality

This project uses the latest ESLint (v9) and Prettier for code quality and formatting:

- **ESLint v9**: Latest version with TypeScript support and modern rules
- **Prettier**: Code formatting with consistent style
- **4 spaces**: Indentation using spaces
- **Double quotes**: String literals use double quotes
- **Semicolons**: Always required
- **Trailing commas**: Required in multiline structures
- **Modern TypeScript**: ES2024 target with strict type checking

### Development Commands

```bash
# Install dependencies
npm install

# Build the project
npm run build

# Watch for changes during development
npm run dev

# Run tests
npm test

# Lint code (ESLint v9)
npm run lint

# Fix linting issues automatically
npm run lint:fix

# Format code with Prettier
npm run format

# Check code formatting
npm run format:check

# Run all checks (lint, format, build)
npm run check
```

### Code Style

The project follows these coding standards:

- **Indentation**: 4 spaces
- **Quotes**: Double quotes for strings
- **Semicolons**: Always required
- **Trailing commas**: Required in multiline structures
- **Line length**: 100 characters maximum
- **Function spacing**: Space before function parentheses for anonymous functions and arrow functions
- **Modern JavaScript**: ES2024 features and best practices
- **TypeScript**: Strict type checking with latest features

### Configuration Files

- `.eslintrc.js`: ESLint v9 configuration with TypeScript support
- `.eslintignore`: ESLint ignore patterns
- `.prettierrc`: Prettier configuration matching ESLint rules
- `tsconfig.json`: TypeScript compiler configuration (ES2024)

### ESLint Features

The latest ESLint configuration includes:

- **Modern TypeScript rules**: Latest TypeScript ESLint plugin
- **Promise handling**: Automatic detection of unhandled promises
- **Nullish coalescing**: Prefer `??` over `||` for null/undefined checks
- **Optional chaining**: Prefer `?.` over manual null checks
- **Arrow functions**: Prefer arrow functions where appropriate
- **Template literals**: Prefer template literals over string concatenation
- **Object shorthand**: Use object property shorthand when possible

## Types

The client includes full TypeScript support with comprehensive type definitions for all API requests and responses. See the `src/types/index.ts` file for complete type definitions.