@seyaq/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdulrahman Al Fuhaydi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# `@seyaq/sdk`
+
+Server-side TypeScript client for the [Seyaq Search API](https://seyaq.analfuhaydi.workers.dev). Do not put Seyaq API keys in browser bundles.
+
+## Install
+
+```sh
+npm install @seyaq/sdk
+```
+
+Node.js 18 or newer is supported. The package also works in runtimes that provide `fetch`, `crypto.randomUUID`, and `AbortSignal`, including Cloudflare Workers.
+
+## Search
+
+```ts
+import { Seyaq } from "@seyaq/sdk";
+
+const seyaq = new Seyaq({ apiKey: process.env.SEYAQ_API_KEY! });
+const response = await seyaq.search({
+  query: "renewable energy",
+  language: "en",
+  country: "US",
+  limit: 5,
+  safeSearch: "moderate",
+});
+
+for (const result of response.results) {
+  console.log(result.title, result.url);
+}
+```
+
+Seyaq trims the query, normalizes language and country casing, and rejects invalid input with `TypeError` before sending a request.
+
+## Handle API errors
+
+```ts
+import { Seyaq, SeyaqError } from "@seyaq/sdk";
+
+const seyaq = new Seyaq({ apiKey: process.env.SEYAQ_API_KEY! });
+
+try {
+  await seyaq.search({ query: "أخبار التقنية", language: "ar", country: "SA" });
+} catch (error) {
+  if (error instanceof SeyaqError) {
+    console.error(error.status, error.code, error.requestId, error.retryAt);
+  }
+  throw error;
+}
+```
+
+## Cancel a request
+
+```ts
+const controller = new AbortController();
+const request = seyaq.search(
+  { query: "climate policy", language: "en", country: "GB" },
+  { signal: controller.signal },
+);
+
+controller.abort();
+await request;
+```
+
+## Supply an idempotency key
+
+The SDK creates a random key for each request. Supply your own when you need to identify a request across retries. Reusing a processed key returns `409 REQUEST_ALREADY_PROCESSED`; Seyaq does not charge the daily quota twice.
+
+```ts
+await seyaq.search(
+  { query: "Saudi startup funding", language: "en", country: "SA" },
+  { idempotencyKey: "job-42-search-1" },
+);
+```
+
+## Use a different API endpoint
+
+```ts
+const seyaq = new Seyaq({
+  apiKey: process.env.SEYAQ_API_KEY!,
+  baseUrl: "https://example.internal",
+});
+```
+
+## Cloudflare Worker
+
+```ts
+import { Seyaq } from "@seyaq/sdk";
+
+interface Env {
+  SEYAQ_API_KEY: string;
+}
+
+export default {
+  async fetch(_request: Request, env: Env) {
+    const seyaq = new Seyaq({ apiKey: env.SEYAQ_API_KEY });
+    const response = await seyaq.search({
+      query: "الطاقة الشمسية",
+      language: "ar",
+      country: "SA",
+    });
+    return Response.json(response);
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+export declare const SEARCH_LANGUAGES: readonly ["ar", "bg", "bn", "ca", "cs", "da", "de", "el", "en", "es", "et", "eu", "fi", "fr", "gl", "gu", "he", "hi", "hr", "hu", "it", "ja", "kn", "ko", "lt", "lv", "ml", "mr", "ms", "nl", "no", "pl", "pt-br", "pt-pt", "ro", "ru", "sk", "sl", "sr", "sv", "ta", "te", "th", "tr", "uk", "vi", "zh-hans", "zh-hant"];
+export declare const SEARCH_COUNTRIES: readonly ["ALL", "AR", "AU", "AT", "BE", "BR", "CA", "CL", "DK", "FI", "FR", "DE", "HK", "IN", "ID", "IT", "JP", "KR", "MY", "MX", "NL", "NZ", "NO", "CN", "PL", "PT", "PH", "RU", "SA", "ZA", "ES", "SE", "CH", "TW", "TR", "GB", "US"];
+export declare const ERROR_CODES: readonly ["INVALID_REQUEST", "INVALID_API_KEY", "IDEMPOTENCY_CONFLICT", "REQUEST_IN_PROGRESS", "REQUEST_ALREADY_PROCESSED", "REQUEST_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "DAILY_LIMIT_EXCEEDED", "RATE_LIMITED", "SEARCH_PROVIDER_ERROR", "SEARCH_UNAVAILABLE", "SERVICE_CAPACITY_EXCEEDED", "SEARCH_TIMEOUT", "INTERNAL_ERROR"];
+export type SearchLanguage = (typeof SEARCH_LANGUAGES)[number];
+export type SearchCountry = (typeof SEARCH_COUNTRIES)[number];
+export type Freshness = "day" | "week" | "month" | "year";
+export type SafeSearch = "off" | "moderate" | "strict";
+export type ErrorCode = (typeof ERROR_CODES)[number];
+export interface SearchRequest {
+    query: string;
+    language: SearchLanguage;
+    country: SearchCountry;
+    limit?: number;
+    freshness?: Freshness;
+    safeSearch?: SafeSearch;
+}
+export interface SearchResult {
+    title: string;
+    url: string;
+    description: string;
+    publishedAt: string | null;
+}
+export interface Usage {
+    charged: boolean;
+    remaining: number;
+    dailyLimit: number;
+    resetsAt: string;
+}
+export interface SearchResponse {
+    requestId: string;
+    query: string;
+    results: SearchResult[];
+    usage: Usage;
+}
+export interface ErrorResponse {
+    requestId: string;
+    error: {
+        code: ErrorCode;
+        message: string;
+        retryAt?: string;
+        details?: unknown;
+    };
+}
+export interface SeyaqOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+export interface SearchOptions {
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+export declare class SeyaqError extends Error {
+    readonly status: number;
+    readonly code: ErrorCode | "INVALID_RESPONSE";
+    readonly requestId?: string | undefined;
+    readonly retryAt?: string | undefined;
+    constructor(message: string, status: number, code: ErrorCode | "INVALID_RESPONSE", requestId?: string | undefined, retryAt?: string | undefined);
+}
+export declare class Seyaq {
+    private readonly options;
+    private readonly baseUrl;
+    constructor(options: SeyaqOptions);
+    search(input: SearchRequest, options?: SearchOptions): Promise<SearchResponse>;
+}

package/dist/index.js

@@ -0,0 +1,240 @@
+export const SEARCH_LANGUAGES = [
+    "ar",
+    "bg",
+    "bn",
+    "ca",
+    "cs",
+    "da",
+    "de",
+    "el",
+    "en",
+    "es",
+    "et",
+    "eu",
+    "fi",
+    "fr",
+    "gl",
+    "gu",
+    "he",
+    "hi",
+    "hr",
+    "hu",
+    "it",
+    "ja",
+    "kn",
+    "ko",
+    "lt",
+    "lv",
+    "ml",
+    "mr",
+    "ms",
+    "nl",
+    "no",
+    "pl",
+    "pt-br",
+    "pt-pt",
+    "ro",
+    "ru",
+    "sk",
+    "sl",
+    "sr",
+    "sv",
+    "ta",
+    "te",
+    "th",
+    "tr",
+    "uk",
+    "vi",
+    "zh-hans",
+    "zh-hant",
+];
+export const SEARCH_COUNTRIES = [
+    "ALL",
+    "AR",
+    "AU",
+    "AT",
+    "BE",
+    "BR",
+    "CA",
+    "CL",
+    "DK",
+    "FI",
+    "FR",
+    "DE",
+    "HK",
+    "IN",
+    "ID",
+    "IT",
+    "JP",
+    "KR",
+    "MY",
+    "MX",
+    "NL",
+    "NZ",
+    "NO",
+    "CN",
+    "PL",
+    "PT",
+    "PH",
+    "RU",
+    "SA",
+    "ZA",
+    "ES",
+    "SE",
+    "CH",
+    "TW",
+    "TR",
+    "GB",
+    "US",
+];
+export const ERROR_CODES = [
+    "INVALID_REQUEST",
+    "INVALID_API_KEY",
+    "IDEMPOTENCY_CONFLICT",
+    "REQUEST_IN_PROGRESS",
+    "REQUEST_ALREADY_PROCESSED",
+    "REQUEST_TOO_LARGE",
+    "UNSUPPORTED_MEDIA_TYPE",
+    "DAILY_LIMIT_EXCEEDED",
+    "RATE_LIMITED",
+    "SEARCH_PROVIDER_ERROR",
+    "SEARCH_UNAVAILABLE",
+    "SERVICE_CAPACITY_EXCEEDED",
+    "SEARCH_TIMEOUT",
+    "INTERNAL_ERROR",
+];
+const languageSet = new Set(SEARCH_LANGUAGES);
+const countrySet = new Set(SEARCH_COUNTRIES);
+const freshnessSet = new Set(["day", "week", "month", "year"]);
+const safeSearchSet = new Set(["off", "moderate", "strict"]);
+const errorCodeSet = new Set(ERROR_CODES);
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const hasOnlyKeys = (value, keys) => Object.keys(value).every((key) => keys.includes(key));
+const isNonNegativeInteger = (value) => Number.isInteger(value) && Number(value) >= 0;
+function parseSearchRequest(input) {
+    if (!isObject(input) ||
+        !hasOnlyKeys(input, [
+            "query",
+            "language",
+            "country",
+            "limit",
+            "freshness",
+            "safeSearch",
+        ]))
+        throw new TypeError("Invalid search request");
+    const query = typeof input.query === "string" ? input.query.trim() : "";
+    const language = typeof input.language === "string" ? input.language.toLowerCase() : "";
+    const country = typeof input.country === "string" ? input.country.toUpperCase() : "";
+    if (query.length < 1 ||
+        query.length > 600 ||
+        !languageSet.has(language) ||
+        !countrySet.has(country))
+        throw new TypeError("Invalid search request");
+    if (input.limit !== undefined &&
+        (!Number.isInteger(input.limit) ||
+            Number(input.limit) < 1 ||
+            Number(input.limit) > 10))
+        throw new TypeError("Invalid search request");
+    if (input.freshness !== undefined &&
+        (typeof input.freshness !== "string" || !freshnessSet.has(input.freshness)))
+        throw new TypeError("Invalid search request");
+    if (input.safeSearch !== undefined &&
+        (typeof input.safeSearch !== "string" ||
+            !safeSearchSet.has(input.safeSearch)))
+        throw new TypeError("Invalid search request");
+    return {
+        query,
+        language: language,
+        country: country,
+        limit: input.limit === undefined ? 5 : Number(input.limit),
+        ...(input.freshness === undefined
+            ? {}
+            : { freshness: input.freshness }),
+        safeSearch: input.safeSearch === undefined
+            ? "moderate"
+            : input.safeSearch,
+    };
+}
+function parseErrorResponse(value) {
+    if (!isObject(value) ||
+        typeof value.requestId !== "string" ||
+        !isObject(value.error))
+        return;
+    const error = value.error;
+    if (typeof error.code !== "string" ||
+        !errorCodeSet.has(error.code) ||
+        typeof error.message !== "string" ||
+        (error.retryAt !== undefined && typeof error.retryAt !== "string"))
+        return;
+    return value;
+}
+function parseSearchResponse(value) {
+    if (!isObject(value) ||
+        typeof value.requestId !== "string" ||
+        typeof value.query !== "string" ||
+        !Array.isArray(value.results) ||
+        !isObject(value.usage))
+        return;
+    if (!value.results.every((result) => isObject(result) &&
+        typeof result.title === "string" &&
+        typeof result.url === "string" &&
+        typeof result.description === "string" &&
+        (result.publishedAt === null || typeof result.publishedAt === "string")))
+        return;
+    const usage = value.usage;
+    if (typeof usage.charged !== "boolean" ||
+        !isNonNegativeInteger(usage.remaining) ||
+        !Number.isInteger(usage.dailyLimit) ||
+        Number(usage.dailyLimit) <= 0 ||
+        typeof usage.resetsAt !== "string")
+        return;
+    return value;
+}
+export class SeyaqError extends Error {
+    status;
+    code;
+    requestId;
+    retryAt;
+    constructor(message, status, code, requestId, retryAt) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.requestId = requestId;
+        this.retryAt = retryAt;
+        this.name = "SeyaqError";
+    }
+}
+export class Seyaq {
+    options;
+    baseUrl;
+    constructor(options) {
+        this.options = options;
+        if (!options.apiKey)
+            throw new TypeError("apiKey is required");
+        this.baseUrl = (options.baseUrl ?? "https://seyaq.analfuhaydi.workers.dev").replace(/\/+$/, "");
+    }
+    async search(input, options = {}) {
+        const body = parseSearchRequest(input);
+        const response = await fetch(`${this.baseUrl}/v1/search`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.options.apiKey}`,
+                "Content-Type": "application/json",
+                "Idempotency-Key": options.idempotencyKey ?? crypto.randomUUID(),
+            },
+            body: JSON.stringify(body),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        const payload = await response.json().catch(() => undefined);
+        if (!response.ok) {
+            const error = parseErrorResponse(payload);
+            if (error)
+                throw new SeyaqError(error.error.message, response.status, error.error.code, error.requestId, error.error.retryAt);
+            throw new SeyaqError("Seyaq returned an invalid error response", response.status, "INVALID_RESPONSE", response.headers.get("X-Request-ID") ?? undefined);
+        }
+        const result = parseSearchResponse(payload);
+        if (result)
+            return result;
+        throw new SeyaqError("Seyaq returned an invalid response", response.status, "INVALID_RESPONSE", response.headers.get("X-Request-ID") ?? undefined);
+    }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@seyaq/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/analfuhaydi/seyaq.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://seyaq.analfuhaydi.workers.dev",
+  "bugs": {
+    "url": "https://github.com/analfuhaydi/seyaq/issues"
+  },
+  "keywords": [
+    "search",
+    "api",
+    "typescript",
+    "cloudflare-workers",
+    "seyaq"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "5.9.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc --noEmit",
+    "pack:check": "pnpm pack --pack-destination .packs"
+  }
+}