<!-- source-hash: 6fc430d117cdf20c7781e51705df5734 -->
Composes fetch URLs for suggestion sections (FaqSection and RelatedContentSection) with a consistent query parameter shape, ensuring the two consumers never drift in their `entityType`/`entityId`/`count` parameter ordering.

## Key Components

### `SuggestionUrlOptions`
Configuration interface controlling URL construction:

| Property | Type | Description |
|---|---|---|
| `apiBaseUrl` | `string?` | Prefix for third-party embeds or reverse proxies; defaults to same-origin relative (`''`) |
| `entityType` | `string?` | Entity scope qualifier; must be paired with `entityId` |
| `entityId` | `number \| string?` | Entity scope qualifier; must be paired with `entityType` |
| `count` | `number?` | Maps to the server's `count` param; omitted when undefined (server default applies) |
| `extraParams` | `Record<string, string \| undefined>?` | Additional query params appended after the shared trio; empty/undefined values are skipped |

### `buildSuggestionUrl(path, opts)`
Pure, server-safe function that assembles the final URL string. Parameter ordering is fixed: `entityType` → `entityId` → `count` → `extraParams`. Both `entityType` and `entityId` must be non-empty to be included; a partial pair is silently dropped.

## Usage Example

```typescript
// Same-origin relative URL with entity scope
buildSuggestionUrl('/api/faqs', {
  entityType: 'article',
  entityId: 42,
  count: 5,
})
// → '/api/faqs?entityType=article&entityId=42&count=5'

// Absolute URL with extra params and no entity scope
buildSuggestionUrl('/api/related', {
  apiBaseUrl: 'https://api.example.com',
  count: 10,
  extraParams: { excludeTypes: 'video,file', draft: undefined }, // 'draft' skipped
})
// → 'https://api.example.com/api/related?count=10&excludeTypes=video%2Cfile'

// Bare path — no query string appended
buildSuggestionUrl('/api/faqs')
// → '/api/faqs'
```

## Source

[`suggestion-url.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/suggestion-url.ts)