google-retail-api-client/README.md

Official TypeScript client for Google Retail API

# Google Retail API Client

A TypeScript client for the Google Retail API, providing easy access to search, recommendations, and predictions.

## Features

- 🔍 Full Retail Search API support
- 🎯 Product recommendations
- 🔮 Predictions
- 📦 TypeScript support
- 🔐 Service Account authentication
- 🚀 Promise-based API

## Installation

```bash
npm install google-retail-api-client
```

## Authentication

This library requires a Google Cloud Service Account with appropriate permissions for the Retail API.

### Getting Service Account Credentials

1. Go to the [Google Cloud Console](https://console.cloud.google.com)
2. Navigate to "IAM & Admin" > "Service Accounts"
3. Click "Create Service Account"
4. Grant the service account the following roles:
   - `roles/retail.admin` or appropriate Retail API roles
5. Create and download the JSON key file
6. The JSON file will contain your credentials in this format:

```json
{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "your-private-key-id",
  "private_key": "your-private-key",
  "client_email": "your-client-email",
  "client_id": "your-client-id"
}
```

## Usage

### Initializing the Client

```typescript
import { RetailClient } from "google-retail-api-client";
const client = new RetailClient({
  credentials: {
    // Your service account credentials
    type: "service_account",
    project_id: "your-project-id",
    private_key: "your-private-key",
    client_email: "your-client-email",
    // ... other credential fields
  },
  location: "global", // optional, defaults to "global"
  catalogId: "default_catalog", // optional, defaults to "default_catalog"
});
```

### Searching Products

```typescript
// Basic search
const results = await client.search({
  query: "blue jeans",
  pageSize: 10,
});
// Advanced search with filters
const filteredResults = await client.search({
  query: "t-shirt",
  filter: "price.value > 20 AND price.value < 50",
  pageSize: 20,
  offset: 0,
  orderBy: "price desc",
});
```

### Getting Recommendations

```typescript
// Get recommendations for a specific product
const recommendations = await client.getPredictions({
  productId: "product123",
  pageSize: 12,
  filter: "availability: IN_STOCK",
});
// Get general recommendations
const homePageRecommendations = await client.getPredictions({
  pageSize: 12,
  eventType: "home-page-view",
});
```

## Error Handling

The client throws `RetailApiError` for any API or authentication errors:

```typescript
try {
  const results = await client.search({ query: "shoes" });
} catch (error) {
  if (error instanceof RetailApiError) {
    console.error(error.message); // Error message
    console.error(error.code); // HTTP status code
    console.error(error.details); // Additional error details
  }
}
```

## Security Considerations

⚠️ **Important Security Notes:**

1. Never commit service account credentials to version control
2. Store credentials securely using environment variables or secret management systems
3. Follow the principle of least privilege when assigning roles to the service account
4. Regularly rotate service account keys
5. Never expose service account credentials in client-side/browser code

## API Reference

For detailed API documentation, please refer to the [Google Retail API Documentation](https://cloud.google.com/retail/docs/reference/rest).

## License

MIT