API ডকুমেন্টেশন

declare function GM_log(message: string, level?: GMTypes.LoggerLevel): void;

declare namespace GMTypes {
  type LoggerLevel = "debug" | "info" | "warn" | "error";
}

// ডেটা যোগ করুন — মনে রাখবেন ডেটা শুধুমাত্র bool/string/number/object-এর একটি হতে পারে; আপনি একটি ক্লাস ইনস্ট্যান্স সংরক্ষণ করতে পারবেন না
declare function GM_setValue(name: string, value: any): void;
// ডেটা পান
declare function GM_getValue(name: string, defaultValue?: any): any | undefined;
// ডেটা মুছুন; আবার পেতে চাইলে undefined বা defaultValue ফেরত আসে
declare function GM_deleteValue(name: string): void;

declare function GM_listValues(): string[];

// একাধিক মান সেট করে; values একটি অবজেক্ট যার কীগুলো মানের নাম এবং যার মানগুলো মানের বিষয়বস্তু
declare function GM_setValues(values: { [key: string]: any }): void;
// একাধিক মান পায়; keysOrDefaults একটি অবজেক্ট হলে, এর মানগুলো ডিফল্ট হিসেবে ব্যবহৃত হয়
declare function GM_getValues(keysOrDefaults: { [key: string]: any } | string[] | null | undefined): { [key: string]: any };
// একাধিক মান মুছে দেয়; names স্ট্রিংয়ের একটি অ্যারে
declare function GM_deleteValues(names: string[]): void;

// tabid শুধুমাত্র তখনই থাকে যখন ব্যাকগ্রাউন্ড স্ক্রিপ্ট থেকে শোনা হয়
type ValueChangeListener = (
  name: string,
  oldValue: any,
  newValue: any,
  remote: boolean,
  tabid?: number
) => any;

declare function GM_addValueChangeListener(
  name: string,
  listener: GMTypes.ValueChangeListener
): number;

declare function GM_removeValueChangeListener(listenerId: number): void;

// GM_getResourceText রিসোর্সের টেক্সট ডেটা পায়; ছবির মতো বাইট-টাইপ ডেটা একটি খালি স্ট্রিং ফেরত দেয় — সেগুলোর জন্য পরিবর্তে GM_getResourceURL ব্যবহার করুন
declare function GM_getResourceText(name: string): string | undefined;
// GM_getResourceURL base64-এনকোডেড ডেটা পায়; দ্বিতীয় প্যারামিটারের মাধ্যমে একটি ব্লব URL-ও পাওয়া যায়
declare function GM_getResourceURL(name: string, isBlobUrl?: boolean): string | undefined;

declare function GM_addElement(tag: string, attributes: any): HTMLElement;
declare function GM_addElement(parentNode: Element, tag: string, attrs: any): HTMLElement;

declare function GM_addStyle(css: string): HTMLElement;

declare function GM_openInTab(url: string, options: GMTypes.OpenTabOptions): GMTypes.Tab;
declare function GM_openInTab(url: string, loadInBackground: boolean): GMTypes.Tab;
declare function GM_openInTab(url: string): GMTypes.Tab;

declare namespace GMTypes {
  interface OpenTabOptions {
    /**
     * নতুন ট্যাবটি খোলার সময় ফোকাস পাবে কিনা তা নির্ধারণ করে।
     *
     * - `true` → নতুন ট্যাবটি অবিলম্বে ফোরগ্রাউন্ডে চলে যায়।
     * - `false` → নতুন ট্যাবটি ব্যাকগ্রাউন্ডে খোলে, বর্তমান পেজ থেকে ফোকাস চুরি করে না।
     *
     * ডিফল্ট: true
     */
    active?: boolean;

    /**
     * নতুন ট্যাবটি কোথায় সন্নিবেশ করা হবে তা নির্ধারণ করে।
     *
     * - যদি একটি `boolean` হয়:
     *   - `true` → বর্তমান ট্যাবের ঠিক পরে সন্নিবেশ করা হয়।
     *   - `false` → উইন্ডোর শেষে সন্নিবেশ করা হয়।
     * - যদি একটি `number` হয়:
     *   - `0` → বর্তমান ট্যাবের এক অবস্থান আগে সন্নিবেশ করা হয়।
     *   - `1` → বর্তমান ট্যাবের এক অবস্থান পরে সন্নিবেশ করা হয়।
     *
     * ডিফল্ট: true
     */
    insert?: boolean | number;

    /**
     * প্যারেন্ট ট্যাব (অর্থাৎ `openerTabId`) সেট করা হবে কিনা তা নির্ধারণ করে।
     *
     * - `true` → ব্রাউজার ট্র্যাক করতে পারে কোন ট্যাব শিশু ট্যাবটি খুলেছে,
     *   যা কিছু এক্সটেনশনকে (যেমন ট্যাব-ট্রি ম্যানেজার) প্যারেন্ট/শিশু সম্পর্ক সনাক্ত করতে সাহায্য করে।
     *
     * ডিফল্ট: true
     */
    setParent?: boolean;

    /**
     * ট্যাবটি একটি প্রাইভেট (ইনকগনিটো) উইন্ডোতে খোলা হবে কিনা।
     *
     * নোট: ScriptCat-এর manifest.json-এ `"incognito": "split"` সেট করা আছে,
     * তাই সাধারণ উইন্ডোতে চলার সময় tabId/windowId উপলব্ধ হবে না,
     * এবং শুধুমাত্র "নতুন ট্যাব খোলা" কাজটি করা যাবে।
     *
     * ডিফল্ট: false
     */
    incognito?: boolean;

    /**
     * লিগ্যাসি সামঞ্জস্য ফিল্ড, শুধুমাত্র Tampermonkey দ্বারা সমর্থিত।
     * এর অর্থ `active`-এর **বিপরীত**:
     *
     * - `true` → `active = false`-এর সমতুল্য (ব্যাকগ্রাউন্ডে লোড হয়)।
     * - `false` → `active = true`-এর সমতুল্য (ফোরগ্রাউন্ডে লোড হয়)।
     *
     * ⚠️ সুপারিশ করা হয় না: `active`-এর সাথে ওভারল্যাপ করে এবং বিভ্রান্ত করা সহজ।
     *
     * ডিফল্ট: false
     * @deprecated পরিবর্তে `active` ব্যবহার করুন
     */
    loadInBackground?: boolean;

    /**
     * নতুন ট্যাবটি ব্রাউজারের ট্যাব বারের বাম পাশে পিন করা হবে কিনা।
     *
     * - `true` → নতুন ট্যাবটি পিন করা হয়।
     * - `false` → একটি সাধারণ ট্যাব।
     *
     * ডিফল্ট: false
     */
    pinned?: boolean;

    /**
     * `chrome.tabs.create`-এর পরিবর্তে নতুন ট্যাব খুলতে `window.open` ব্যবহার করে।
     * নির্দিষ্ট বিশেষ প্রোটোকলসহ লিংক খোলার সময় কার্যকর, যেমন `vscode://`, `m3u8dl://`।
     * এই খোলার পদ্ধতি ব্যবহার করলে অন্যান্য প্যারামিটারের কোনো প্রভাব থাকে না।
     *
     * সম্পর্কিত: Issue #178 #1043
     * ডিফল্ট: false
     */
    useOpen?: boolean;
  }

  interface Tab {
    close(): void;
    onclose?: () => void;
    closed?: boolean;
    name?: string;
  }
}

declare function GM_closeInTab(tabId: string): void;

// ট্যাব ডেটা পান
declare function GM_getTab(callback: (obj: object) => void): void;
// ট্যাব ডেটা সংরক্ষণ করুন
declare function GM_saveTab(obj: object): void;
// সব ট্যাবের ডেটা পান
declare function GM_getTabs(callback: (objs: { [key: number]: object }) => void): void;

function GM_registerMenuCommand(
  name: string,
  listener?: (inputValue?: any) => void,
  options_or_accessKey?:
    | {
        id?: number | string;
        accessKey?: string;
        autoClose?: boolean; // ScriptCat-নির্দিষ্ট বিকল্প; ডিফল্ট true, এবং false ক্লিক করার পর পপআপ মেনু পেজটি খোলা রাখে
        nested?: boolean; // ScriptCat-নির্দিষ্ট বিকল্প; ডিফল্ট true, এবং false ব্রাউজারের রাইট-ক্লিক মেনু আইটেমটিকে তৃতীয়-স্তরের থেকে দ্বিতীয়-স্তরের মেনুতে উন্নীত করে
        individual?: boolean; // ScriptCat-নির্দিষ্ট বিকল্প; ডিফল্ট false, এবং true মানে অভিন্ন মেনু আইটেমগুলো একত্রিত করা হয় না
      }
    | string
): number;

declare function GM_unregisterMenuCommand(id: number): void;

declare function GM_notification(
  details: GMTypes.NotificationDetails,
  ondone?: GMTypes.NotificationOnDone
): void;
declare function GM_notification(
  text: string,
  title: string,
  image: string,
  onclick: GMTypes.NotificationOnClick
): void;
declare function GM_closeNotification(id: string): void;
declare function GM_updateNotification(id: string, details: GMTypes.NotificationDetails): void;

declare namespace GMTypes {
  interface NotificationDetails {
    text?: string;
    title?: string;
    tag?: string;
    image?: string;
    highlight?: boolean;
    silent?: boolean;
    timeout?: number;
    url?: string;
    onclick?: NotificationOnClick;
    ondone?: NotificationOnDone;
    progress?: number;
    oncreate?: NotificationOnClick;
    // সর্বোচ্চ ২টি থাকতে পারে
    buttons?: NotificationButton[];
  }

  interface NotificationThis extends NotificationDetails {
    id: string;
  }

  type NotificationOnClickEvent = {
    event: "click" | "buttonClick";
    id: string;
    isButtonClick: boolean;
    buttonClickIndex: number | undefined;
    byUser: boolean | undefined;
    preventDefault: () => void;
    highlight: NotificationDetails["highlight"];
    image: NotificationDetails["image"];
    silent: NotificationDetails["silent"];
    tag: NotificationDetails["tag"];
    text: NotificationDetails["tag"];
    timeout: NotificationDetails["timeout"];
    title: NotificationDetails["title"];
    url: NotificationDetails["url"];
  };
  type NotificationOnClick = (this: NotificationThis, event: NotificationOnClickEvent) => unknown;
  type NotificationOnDone = (this: NotificationThis, user?: boolean) => unknown;

  interface NotificationButton {
    title: string;
    iconUrl?: string;
  }

}

declare function GM_setClipboard(
  data: string,
  info?: string | { type?: string; mimetype?: string }
): void;

declare function GM_xmlhttpRequest(details: GMTypes.XHRDetails): GMTypes.AbortHandle<void>;

declare namespace GMTypes {
  interface XHRResponse {
    finalUrl?: string;
    readyState?: 0 | 1 | 2 | 3 | 4;
    responseHeaders?: string;
    status?: number;
    statusText?: string;
    response?: any;
    responseText?: string;
    responseXML?: Document | null;
  }

  interface XHRProgress extends XHRResponse {
    done: number;
    lengthComputable: boolean;
    loaded: number;
    position: number;
    total: number;
    totalSize: number;
  }

  type Listener<OBJ> = (event: OBJ) => any;

  interface XHRDetails {
    method?: "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
    url: string;
    headers?: { [key: string]: string };
    data?: string | FormData;
    cookie?: string;
    binary?: boolean;
    timeout?: number;
    responseType?: "text" | "arraybuffer" | "blob" | "json" | "document" | "stream"; // stream is a fairly basic implementation in the current version
    overrideMimeType?: string;
    anonymous?: boolean;
    fetch?: boolean;
    user?: string;
    password?: string;
    nocache?: boolean;
    redirect?: "follow" | "error" | "manual"; // to stay consistent with Tampermonkey, maxRedirects was deprecated after v0.17.0 in favor of redirect, which forces fetch mode
    
    onload?: Listener<XHRResponse>;
    onloadstart?: Listener<XHRResponse>;
    onloadend?: Listener<XHRResponse>;
    onprogress?: Listener<XHRProgress>;
    onreadystatechange?: Listener<XHRResponse>;
    ontimeout?: () => void;
    onabort?: () => void;
    onerror?: (err: string) => void;
  }
}

declare function GM_download(details: GMTypes.DownloadDetails): GMTypes.AbortHandle<boolean>;
declare function GM_download(url: string, filename: string): GMTypes.AbortHandle<boolean>;

declare namespace GMTypes {
  interface DownloadError {
    error:
      | "not_enabled"
      | "not_whitelisted"
      | "not_permitted"
      | "not_supported"
      | "not_succeeded"
      | "unknown";
    details?: string;
  }

  interface DownloadDetails {
    method?: "GET" | "POST";
    downloadMode?: "native" | "browser";
    url: string;
    name: string;
    headers?: { [key: string]: string };
    saveAs?: boolean;
    timeout?: number;
    cookie?: string;
    anonymous?: boolean;

    onerror?: Listener<DownloadError>;
    ontimeout?: () => void;
    onload?: Listener<object>;
    onprogress?: Listener<XHRProgress>;
  }
}

// name এবং domain দুটোই খালি হতে পারে না
declare function GM_cookie(
  action: GMTypes.CookieAction,
  details: GMTypes.CookieDetails,
  ondone: (cookie: GMTypes.Cookie[], error: unknown | undefined) => void
): void;

declare namespace GMTypes {
  type CookieAction = "list" | "delete" | "set";
  interface CookieDetails {
    url?: string;
    name?: string;
    value?: string;
    domain?: string;
    path?: string;
    secure?: boolean;
    session?: boolean;
    httpOnly?: boolean;
    expirationDate?: number;
    partitionKey?: CookieDetailsPartitionKeyType;
  }
  interface Cookie {
    domain: string;
    name: string;
    value: string;
    session: boolean;
    hostOnly: boolean;
    expirationDate?: number;
    path: string;
    httpOnly: boolean;
    secure: boolean;
  }
}

// Callback form
GM_cookie("list", { url: "https://example.com" }, (cookies) => {
  console.log(cookies);
  GM_cookie("set", {
    name: "foo",
    value: "bar",
    domain: "example.com"
  }, (result) => {
    console.log(result);
    GM_cookie("delete", { name: "foo", domain: "example.com" }, (result) => {
      console.log(result);
    });
  });
});

// Promise form
const cookies = await GM.cookie.list({ url: "https://example.com" });
await GM.cookie.set({ name: "foo", value: "bar", domain: "example.com" });
await GM.cookie.delete("foo", { domain: "example.com" });