@skawr/search 0.1.0

package/README.md

@@ -0,0 +1,90 @@
+# @skawr/search
+
+Official SKAWR browser search SDK — lightweight, search-only client safe for frontend use.
+
+## Installation
+
+```bash
+npm install @skawr/search
+```
+
+ESM only. ~1.7 KB minified. Zero runtime dependencies.
+
+## Quick Start
+
+```typescript
+import { SkawrSearch } from '@skawr/search';
+
+const search = new SkawrSearch({
+  publicKey: 'your-public-key',
+  baseUrl: 'https://api.skawr.com', // optional
+});
+```
+
+## Usage
+
+### Search
+
+```typescript
+const results = await search.search('laptop', {
+  filters: { category: 'electronics', min_price: 100 },
+  page: 1,
+  per_page: 20,
+  sort_by: 'relevance',
+});
+
+console.log(results.total_results);
+results.results.forEach((item) => {
+  console.log(item.title, item.price);
+});
+```
+
+### Suggestions
+
+```typescript
+const suggestions = await search.suggest('lap', {
+  include_trending: true,
+  limit: 10,
+});
+
+console.log(suggestions.query_completions); // ['laptop', 'laptop bag', ...]
+console.log(suggestions.trending_queries);  // ['phone', 'tablet', ...]
+```
+
+### Autocomplete
+
+```typescript
+const { suggestions } = await search.autocomplete('lap', { limit: 5 });
+console.log(suggestions); // ['laptop', 'laptop case', 'laptop stand']
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `publicKey` | `string` | *required* | Your SKAWR public/search key |
+| `baseUrl` | `string` | `https://api.skawr.com` | API base URL |
+| `timeout` | `number` | `10000` | Request timeout in ms |
+
+## Error Handling
+
+```typescript
+import { SearchError } from '@skawr/search';
+
+try {
+  await search.search('test');
+} catch (error) {
+  if (error instanceof SearchError) {
+    console.log(error.status); // HTTP status code
+    console.log(error.detail); // Error message from API
+  }
+}
+```
+
+## Browser Support
+
+Works in all modern browsers with native `fetch` support (Chrome 42+, Firefox 39+, Safari 10.1+, Edge 14+).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+interface SkawrSearchConfig {
+    publicKey: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+interface SearchFilters {
+    min_price?: number;
+    max_price?: number;
+    source?: string[];
+    category?: string;
+    custom_attributes?: Record<string, unknown>;
+    boost_fields?: Record<string, number>;
+}
+type SortBy = 'relevance' | 'price_asc' | 'price_desc' | 'date_desc';
+interface SearchOptions {
+    index?: string;
+    filters?: SearchFilters;
+    page?: number;
+    per_page?: number;
+    sort_by?: SortBy;
+    highlight_matches?: boolean;
+    result_format?: 'standard' | 'minimal' | 'detailed';
+}
+interface SearchResult {
+    id: string;
+    title: string;
+    description?: string;
+    price?: number;
+    currency?: string;
+    image_url?: string;
+    product_url?: string;
+    source?: string;
+    store_name?: string;
+    category?: string;
+    score?: number;
+    highlighted_title?: string;
+    highlighted_description?: string;
+    [key: string]: unknown;
+}
+interface FacetCount {
+    value: string;
+    count: number;
+}
+interface Facet {
+    field_name: string;
+    counts: FacetCount[];
+}
+interface SearchResponse {
+    results: SearchResult[];
+    total_results: number;
+    page: number;
+    per_page: number;
+    total_pages: number;
+    took_ms: number;
+    facets?: Facet[];
+    suggestions?: string[];
+    search_id: string;
+}
+interface SuggestOptions {
+    index?: string;
+    limit?: number;
+    include_trending?: boolean;
+}
+interface SuggestionsResponse {
+    query_completions: string[];
+    trending_queries?: string[];
+    category_suggestions?: string[];
+}
+interface AutocompleteOptions {
+    limit?: number;
+}
+interface AutocompleteResponse {
+    suggestions: string[];
+}
+
+declare class SkawrSearch {
+    private readonly baseUrl;
+    private readonly publicKey;
+    private readonly timeout;
+    constructor(config: SkawrSearchConfig);
+    search(query: string, options?: SearchOptions): Promise<SearchResponse>;
+    suggest(query: string, options?: SuggestOptions): Promise<SuggestionsResponse>;
+    autocomplete(query: string, options?: AutocompleteOptions): Promise<AutocompleteResponse>;
+    private get;
+    private post;
+    private request;
+}
+
+declare class SearchError extends Error {
+    readonly status: number;
+    readonly detail: string;
+    constructor(message: string, status: number, detail?: string);
+}
+
+export { type AutocompleteOptions, type AutocompleteResponse, type Facet, type FacetCount, SearchError, type SearchFilters, type SearchOptions, type SearchResponse, type SearchResult, SkawrSearch, type SkawrSearchConfig, type SortBy, type SuggestOptions, type SuggestionsResponse };

package/dist/index.js

@@ -0,0 +1,3 @@
+var n=class extends Error{status;detail;constructor(t,e,r){super(t),this.name="SearchError",this.status=e,this.detail=r??t;}};var u="https://api.skawr.com",g=1e4,a=class{baseUrl;publicKey;timeout;constructor(t){if(!t.publicKey)throw new Error("publicKey is required");this.baseUrl=(t.baseUrl??u).replace(/\/+$/,""),this.publicKey=t.publicKey,this.timeout=t.timeout??g;}async search(t,e){return this.post("/api/v1/search",{query:t,filters:e?.filters,page:e?.page,per_page:e?.per_page,sort_by:e?.sort_by,highlight_matches:e?.highlight_matches??true,result_format:e?.result_format})}async suggest(t,e){let r={q:t};return e?.limit!==void 0&&(r.limit=String(e.limit)),e?.include_trending!==void 0&&(r.include_trending=String(e.include_trending)),this.get("/api/v1/search/suggestions",r)}async autocomplete(t,e){let r={q:t};return e?.limit!==void 0&&(r.limit=String(e.limit)),this.get("/api/v1/autocomplete",r)}async get(t,e){let r=`${this.baseUrl}${t}`;if(e){let s=new URLSearchParams(e).toString();s&&(r+=`?${s}`);}return this.request(r,{method:"GET"})}async post(t,e){return this.request(`${this.baseUrl}${t}`,{method:"POST",body:JSON.stringify(e)})}async request(t,e){let r={"X-API-Key":this.publicKey,Accept:"application/json"};e.body&&(r["Content-Type"]="application/json");let s;try{s=await fetch(t,{...e,headers:r,signal:AbortSignal.timeout(this.timeout)});}catch(i){throw i instanceof DOMException&&i.name==="TimeoutError"?new n("Request timed out",0,"Request timed out"):i}if(!s.ok){let i=await s.text(),o;try{let c=JSON.parse(i);o=typeof c.detail=="string"?c.detail:i;}catch{o=i||s.statusText;}throw new n(o,s.status,o)}return await s.json()}};
+export{n as SearchError,a as SkawrSearch};//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/client.ts"],"names":["SearchError","message","status","detail","DEFAULT_BASE_URL","DEFAULT_TIMEOUT","SkawrSearch","config","query","options","params","path","url","qs","body","init","headers","response","error","text","parsed"],"mappings":"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","file":"index.js","sourcesContent":["export class SearchError extends Error {\n  readonly status: number;\n  readonly detail: string;\n\n  constructor(message: string, status: number, detail?: string) {\n    super(message);\n    this.name = 'SearchError';\n    this.status = status;\n    this.detail = detail ?? message;\n  }\n}\n","import { SearchError } from './errors.js';\nimport type {\n  SkawrSearchConfig,\n  SearchOptions,\n  SearchResponse,\n  SuggestOptions,\n  SuggestionsResponse,\n  AutocompleteOptions,\n  AutocompleteResponse,\n} from './types.js';\n\nconst DEFAULT_BASE_URL = 'https://api.skawr.com';\nconst DEFAULT_TIMEOUT = 10_000;\n\nexport class SkawrSearch {\n  private readonly baseUrl: string;\n  private readonly publicKey: string;\n  private readonly timeout: number;\n\n  constructor(config: SkawrSearchConfig) {\n    if (!config.publicKey) {\n      throw new Error('publicKey is required');\n    }\n\n    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, '');\n    this.publicKey = config.publicKey;\n    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;\n  }\n\n  async search(query: string, options?: SearchOptions): Promise<SearchResponse> {\n    return this.post<SearchResponse>('/api/v1/search', {\n      query,\n      filters: options?.filters,\n      page: options?.page,\n      per_page: options?.per_page,\n      sort_by: options?.sort_by,\n      highlight_matches: options?.highlight_matches ?? true,\n      result_format: options?.result_format,\n    });\n  }\n\n  async suggest(query: string, options?: SuggestOptions): Promise<SuggestionsResponse> {\n    const params: Record<string, string> = { q: query };\n    if (options?.limit !== undefined) params.limit = String(options.limit);\n    if (options?.include_trending !== undefined) params.include_trending = String(options.include_trending);\n\n    return this.get<SuggestionsResponse>('/api/v1/search/suggestions', params);\n  }\n\n  async autocomplete(query: string, options?: AutocompleteOptions): Promise<AutocompleteResponse> {\n    const params: Record<string, string> = { q: query };\n    if (options?.limit !== undefined) params.limit = String(options.limit);\n\n    return this.get<AutocompleteResponse>('/api/v1/autocomplete', params);\n  }\n\n  private async get<T>(path: string, params?: Record<string, string>): Promise<T> {\n    let url = `${this.baseUrl}${path}`;\n    if (params) {\n      const qs = new URLSearchParams(params).toString();\n      if (qs) url += `?${qs}`;\n    }\n\n    return this.request<T>(url, { method: 'GET' });\n  }\n\n  private async post<T>(path: string, body: unknown): Promise<T> {\n    return this.request<T>(`${this.baseUrl}${path}`, {\n      method: 'POST',\n      body: JSON.stringify(body),\n    });\n  }\n\n  private async request<T>(url: string, init: RequestInit): Promise<T> {\n    const headers: Record<string, string> = {\n      'X-API-Key': this.publicKey,\n      'Accept': 'application/json',\n    };\n\n    if (init.body) {\n      headers['Content-Type'] = 'application/json';\n    }\n\n    let response: Response;\n    try {\n      response = await fetch(url, {\n        ...init,\n        headers,\n        signal: AbortSignal.timeout(this.timeout),\n      });\n    } catch (error) {\n      if (error instanceof DOMException && error.name === 'TimeoutError') {\n        throw new SearchError('Request timed out', 0, 'Request timed out');\n      }\n      throw error;\n    }\n\n    if (!response.ok) {\n      const text = await response.text();\n      let detail: string;\n      try {\n        const parsed = JSON.parse(text);\n        detail = typeof parsed.detail === 'string' ? parsed.detail : text;\n      } catch {\n        detail = text || response.statusText;\n      }\n      throw new SearchError(detail, response.status, detail);\n    }\n\n    return (await response.json()) as T;\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@skawr/search",
+  "version": "0.1.0",
+  "description": "Official SKAWR browser search SDK — lightweight, search-only client",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "skawr",
+    "search",
+    "frontend",
+    "browser",
+    "autocomplete"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/skawr/skawr-sdk-search"
+  }
+}