@gigya/destination/README.md

Gigya API Client with SAP Cloud SDK Destination Support

# @gigya/destination

Gigya API client with SAP Cloud SDK destination support using [openapi-fetch](https://openapi-ts.dev/openapi-fetch/) middleware.

## Installation

```bash
npm install @gigya/destination openapi-fetch @sap-cloud-sdk/connectivity @sap-cloud-sdk/http-client
```

## Usage

### Basic Usage

```typescript
import { createGigyaDestination } from '@gigya/destination'

const client = createGigyaDestination({
  destination: 'GIGYA_DESTINATION'
})

// Type-safe API calls with SAP destination
const { data, error } = await client.GET('/accounts.getAccountInfo', {
  params: {
    query: { UID: 'user123' }
  }
})

if (error) {
  console.error(error)
} else {
  console.log(data)
}
```

### With Custom Headers

```typescript
const client = createGigyaDestination({
  destination: 'GIGYA_DESTINATION',
  headers: {
    'X-Custom-Header': 'value'
  }
})
```

### With Destination Object

```typescript
import { getDestination } from '@sap-cloud-sdk/connectivity'

const destination = await getDestination({
  destinationName: 'GIGYA_DESTINATION'
})

const client = createGigyaDestination({
  destination
})
```

### Advanced Middleware

```typescript
import { createClient, type Middleware } from 'openapi-fetch'
import type { paths } from '@gigya/destination/schema'

// Create client with custom middleware
const loggingMiddleware: Middleware = {
  async onRequest({ request }) {
    console.log('Request:', request.url)
    return request
  },
  async onResponse({ response }) {
    console.log('Response:', response.status)
    return response
  }
}

const client = createClient<paths>({
  baseUrl: 'https://accounts.gigya.com'
})

client.use(loggingMiddleware)
```

## SAP BTP Destination Configuration

Create a destination in SAP BTP Cockpit:

```properties
Name=GIGYA_DESTINATION
Type=HTTP
URL=https://accounts.gigya.com
ProxyType=Internet
Authentication=BasicAuthentication
User=<your-api-key>
Password=<your-secret-key>
```

## Type-Safe Requests

All requests are fully typed based on the OpenAPI schema:

```typescript
// TypeScript knows exact parameters and response types
const { data, error } = await client.POST('/accounts.setAccountInfo', {
  params: {
    query: {
      UID: 'user123',
      profile: {
        firstName: 'John',
        lastName: 'Doe'
      }
    }
  }
})

if (data) {
  // data is typed based on the OpenAPI response schema
  console.log(data)
}
```

## Error Handling

```typescript
const { data, error } = await client.GET('/accounts.getAccountInfo', {
  params: { query: { UID: 'user123' } }
})

if (error) {
  // error is typed based on possible error responses
  console.error('Request failed:', error)
  return
}

// TypeScript knows data is defined here
console.log(data)
```

## How It Works

This package uses [openapi-fetch](https://openapi-ts.dev/openapi-fetch/) with custom middleware to:

1. **Intercept requests** before they're sent
2. **Resolve SAP destination** (with caching)
3. **Replace base URL** with destination URL
4. **Add authentication** headers from destination
5. **Execute request** through SAP Cloud SDK

The middleware pattern from openapi-fetch provides:
- ✅ Type-safe requests and responses
- ✅ Zero runtime overhead
- ✅ Full control over request/response
- ✅ Easy to extend with custom middleware
- ✅ Compatible with SAP Cloud SDK

## Examples

### Cloud Foundry App

```typescript
import { createGigyaDestination } from '@gigya/destination'
import express from 'express'

const app = express()
const gigya = createGigyaDestination({
  destination: 'GIGYA_DESTINATION'
})

app.get('/account/:uid', async (req, res) => {
  const { data, error } = await gigya.GET('/accounts.getAccountInfo', {
    params: { query: { UID: req.params.uid } }
  })
  
  if (error) {
    return res.status(500).json({ error })
  }
  
  res.json(data)
})

app.listen(process.env.PORT || 3000)
```

### With Additional Middleware

```typescript
import { createGigyaDestination } from '@gigya/destination'
import type { Middleware } from 'openapi-fetch'

// Add custom middleware for request tracking
const trackingMiddleware: Middleware = {
  async onRequest({ request }) {
    request.headers.set('X-Request-ID', crypto.randomUUID())
    return request
  }
}

const client = createGigyaDestination({
  destination: 'GIGYA_DESTINATION'
})

// Add additional middleware
client.use(trackingMiddleware)
```

## Documentation

- [openapi-fetch Documentation](https://openapi-ts.dev/openapi-fetch/)
- [openapi-fetch Middleware](https://openapi-ts.dev/openapi-fetch/middleware-auth)
- [SAP Cloud SDK](https://sap.github.io/cloud-sdk/)
- [Gigya API Documentation](https://help.sap.com/docs/SAP_CUSTOMER_DATA_CLOUD)

## License

MIT