@gigya/fetch/README.md

Gigya API TypeScript Client with Hey API

# @gigya/api

TypeScript client for Gigya API using [Hey API](https://heyapi.dev/) with [ofetch](https://heyapi.dev/openapi-ts/clients/ofetch).

## Features

- ✅ **Type-safe** - Full TypeScript support from OpenAPI spec
- ✅ **Auto-parsing** - Automatic JSON response parsing (no `.json()`)
- ✅ **Transformers** - Automatic request/response transformation
- ✅ **Auth support** - Built-in authentication
- ✅ **Interceptors** - Request/response interceptors (use/eject/update)
- ✅ **SDKs** - Generated SDK functions for all endpoints
- ✅ **ofetch powered** - Works everywhere (Node, browser, workers)

## Installation

```bash
npm install @gigya/api @hey-api/client-ofetch ofetch
```

## Quick Start

```typescript
import { configureGigyaClient, gigyaClient } from '@gigya/api'

// Configure once at app startup
configureGigyaClient({
  baseUrl: 'https://accounts.gigya.com'
})

// Make type-safe requests (auto-parsed!)
const { data, error } = await gigyaClient.GET('/accounts.getAccountInfo', {
  query: { UID: 'user123' }
})

if (error) {
  console.error(error)
} else {
  console.log(data) // Fully typed and parsed!
}
```

## Using SDKs

```typescript
import { getAccountsGetAccountInfo, postAccountsSetAccountInfo } from '@gigya/api'

// Generated SDK functions (camelCase)
const response = await getAccountsGetAccountInfo({
  query: { UID: 'user123' }
})
```

## Authentication

```typescript
import { configureGigyaClient } from '@gigya/api'

configureGigyaClient({
  baseUrl: 'https://accounts.gigya.com',
  auth: () => getAccessToken(), // Function or string
})

// Or per-request
const { data } = await gigyaClient.GET('/accounts.getAccountInfo', {
  query: { UID: 'user123' },
  auth: 'Bearer my-token'
})
```

## Interceptors

Based on [Hey API interceptors](https://heyapi.dev/openapi-ts/clients/fetch#interceptors):

```typescript
import { gigyaClient } from '@gigya/api'

// Request interceptor
const reqId = gigyaClient.interceptors.request.use((request, options) => {
  console.log('→', request.url)
  request.headers.set('X-Request-ID', crypto.randomUUID())
  return request
})

// Response interceptor
const resId = gigyaClient.interceptors.response.use((response, options) => {
  console.log('←', response.status)
  return response
})

// Remove interceptors
gigyaClient.interceptors.request.eject(reqId)
gigyaClient.interceptors.response.eject(resId)
```

## ofetch Hooks

```typescript
configureGigyaClient({
  baseUrl: 'https://accounts.gigya.com',
  
  onRequest: ({ request, options }) => {
    // Modify request before sending
    options.headers.set('X-Custom', 'value')
  },
  
  onResponse: ({ response }) => {
    // Handle successful response
    console.log('Success:', response.status)
  },
  
  onRequestError: (ctx) => {
    // Handle request errors (network, CORS, etc.)
    console.error('Request failed:', ctx.error)
  },
  
  onResponseError: (ctx) => {
    // Handle response errors (4xx, 5xx)
    console.error('HTTP error:', ctx.response.status)
  }
})
```

## Error Handling

```typescript
const { data, error } = await gigyaClient.POST('/accounts.setAccountInfo', {
  query: {
    UID: 'user123',
    profile: { firstName: 'John' }
  }
})

if (error) {
  // error is typed based on OpenAPI error responses
  if (error.statusCode === 403) {
    console.error('Forbidden')
  }
  return
}

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

## Why Hey API + ofetch?

Based on the [official docs](https://heyapi.dev/openapi-ts/clients/ofetch):

- **Auto-parsing**: Response automatically parsed (no `.json()`)
- **Smart defaults**: Better than raw fetch
- **Universal**: Works in Node.js, browsers, workers
- **Type-safe**: Full TypeScript support
- **Zero config**: Works out of the box

## Documentation

- [Hey API Documentation](https://heyapi.dev/)
- [ofetch Client](https://heyapi.dev/openapi-ts/clients/ofetch)
- [Transformers Plugin](https://heyapi.dev/openapi-ts/plugins/transformers)
- [SDK Plugin](https://heyapi.dev/openapi-ts/plugins/sdk)

## License

MIT