fix: add missing types

microlinkhq · Sep 3, 2023 · 63c8970 · 63c8970
1 parent 3440e1e
commit 63c8970
Show file tree

Hide file tree

Showing 5 changed files with 219 additions and 106 deletions.
diff --git a/index.d.ts b/index.d.ts
@@ -1,111 +1,27 @@
-export type ColorScheme = | "dark" | "light";
+import { MqlPayload, MqlOptions, MicrolinkApiOptions  } from './lightweight/index.js'
 
-export type WaitUntilEvent = "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
-
-export type PixelUnit = string | number;
-
-export type ScreenshotOverlay = {
-  background?: string,
-  browser?: 'dark' | 'light'
-}
-
-export type MqlOptions = {
-  endpoint?: string;
-  apiKey?: string;
-  retry?: number;
-  cache?: Map<string, any>;
-}
-
-export type PdfMargin = {
-  top?: string | number;
-   bottom?: string | number;
-   left?: string | number;
-   right?: string | number;
-}
-
-export interface MqlQuery {
-  [field: string]: MqlQueryOptions;
-}
-
-export type MqlQueryOptions = {
-  attr?: string | string[] | MqlQuery;
-  evaluate?: string;
-  selector?: string | string[];
-  selectorAll?: string | string[];
-  type?: "audio" | "author" | "auto" | "boolean" | "date" | "description" | "email" | "image" | "ip" | "lang" | "logo" | "number" | "object" | "publisher" | "regexp" | "string" | "title" | "url" | "video";
-}
-
-export type PdfOptions = {
-  format?: string;
-  height?: PixelUnit;
-  landscape?: string;
-  margin?: string | PdfMargin;
-  pageRanges?: string;
-  scale?: number;
-  width?: PixelUnit;
-}
-
-export type ScreenshotOptions = {
-  codeScheme?: string;
-  omitBackground?: boolean;
-  type?: "jpeg" | "png";
-  element?: string;
-  fullPage?: boolean;
-  overlay?: ScreenshotOverlay
-}
-
-export type MicrolinkApiOptions = {
-  adblock?: boolean;
-  animations?: boolean;
-  audio?: boolean;
-  click?: string | string[];
-  colorScheme?: ColorScheme;
-  data?: MqlQuery;
-  device?: string;
-  embed?: string;
-  filename?: string;
-  filter?: string;
-  force?: boolean;
-  function?: string;
-  headers?: Record<string, string>;
-  iframe?: boolean | { maxWidth?: number, maxHeight?: number };
-  insights?: boolean | { lighthouse?: boolean | object, technologies?: boolean };
-  javascript?: boolean;
-  mediaType?: string;
-  meta?: boolean | { logo: { square: boolean } };
-  modules?: string | string[];
-  palette?: boolean;
-  pdf?: boolean | PdfOptions;
-  ping?: boolean | object;
-  prerender?: boolean | "auto";
-  proxy?: string | { countryCode?: string };
-  retry?: number;
-  screenshot?: boolean | ScreenshotOptions;
-  scripts?: string | string[];
-  scroll?: string;
-  styles?: string | string[];
-  staleTtl?: string | number;
-  timeout?: number;
-  ttl?: string | number;
-  video?: boolean;
-  viewport?: object;
-  waitForSelector?: string;
-  waitForTimeout?: number;
-  waitUntil?: WaitUntilEvent | WaitUntilEvent[];
+type MqlResponse = MqlPayload & {
+  response: {
+    url: string;
+    isFromCache?: boolean;
+    statusCode: number;
+    headers: { [key: string]: string };
+    body: MqlPayload
+  };
 }
 
 declare function mql(
   url: string,
   opts?: MqlOptions & MicrolinkApiOptions,
-  // TODO: gotOpts could be different depends the environment where the library is being used
-  // - Under Node.js context, types are from `got`
-  //   https://github.com/microlinkhq/mql/blob/fbb55f4758495fa42d35822867763f95ac5ae960/src/node.js#L5
-  //   https://github.com/DefinitelyTyped/DefinitelyTyped/blob/90a4ec8f0a9c76f33fdeeef0118f26c5d3df5cfa/types/got/index.d.ts#L212
-  //
-  // - Under brower context, types are from  `ky`
-  //   https://github.com/microlinkhq/mql/blob/fbb55f4758495fa42d35822867763f95ac5ae960/src/browser.js#L9
-  //   https://github.com/sindresorhus/ky/blob/main/source/types/options.ts#L30
   gotOpts?: object
-): Promise<object>;
+): Promise<MqlResponse>;
+
+declare namespace mql {
+  function stream(
+    url: string,
+    opts?: MqlOptions & MicrolinkApiOptions,
+    gotOpts?: object
+  ): NodeJS.ReadableStream;
+}
 
 export default mql;
diff --git a/lightweight/index.d.ts b/lightweight/index.d.ts
@@ -0,0 +1,172 @@
+type ColorScheme = | "dark" | "light";
+
+type WaitUntilEvent = "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
+
+type PixelUnit = string | number;
+
+type ScreenshotOverlay = {
+  background?: string,
+  browser?: 'dark' | 'light'
+}
+
+type PdfMargin = {
+  top?: string | number;
+   bottom?: string | number;
+   left?: string | number;
+   right?: string | number;
+}
+
+type PdfOptions = {
+  format?: string;
+  height?: PixelUnit;
+  landscape?: string;
+  margin?: string | PdfMargin;
+  pageRanges?: string;
+  scale?: number;
+  width?: PixelUnit;
+}
+
+type ScreenshotOptions = {
+  codeScheme?: string;
+  omitBackground?: boolean;
+  type?: "jpeg" | "png";
+  element?: string;
+  fullPage?: boolean;
+  overlay?: ScreenshotOverlay
+}
+
+export type MqlOptions = {
+  endpoint?: string;
+  apiKey?: string;
+  retry?: number;
+  cache?: Map<string, any>;
+}
+
+type MqlQuery = {
+  [field: string]: MqlQueryOptions;
+}
+
+type MqlQueryOptions = {
+  attr?: string | string[] | MqlQuery;
+  evaluate?: string;
+  selector?: string | string[];
+  selectorAll?: string | string[];
+  type?: "audio" | "author" | "auto" | "boolean" | "date" | "description" | "email" | "image" | "ip" | "lang" | "logo" | "number" | "object" | "publisher" | "regexp" | "string" | "title" | "url" | "video";
+}
+
+export type MicrolinkApiOptions = {
+  adblock?: boolean;
+  animations?: boolean;
+  audio?: boolean;
+  click?: string | string[];
+  colorScheme?: ColorScheme;
+  data?: MqlQuery;
+  device?: string;
+  embed?: string;
+  filename?: string;
+  filter?: string;
+  force?: boolean;
+  function?: string;
+  headers?: Record<string, string>;
+  iframe?: boolean | { maxWidth?: number, maxHeight?: number };
+  insights?: boolean | { lighthouse?: boolean | object, technologies?: boolean };
+  javascript?: boolean;
+  mediaType?: string;
+  meta?: boolean | { logo: { square: boolean } };
+  modules?: string | string[];
+  palette?: boolean;
+  pdf?: boolean | PdfOptions;
+  ping?: boolean | object;
+  prerender?: boolean | "auto";
+  proxy?: string | { countryCode?: string };
+  retry?: number;
+  screenshot?: boolean | ScreenshotOptions;
+  scripts?: string | string[];
+  scroll?: string;
+  styles?: string | string[];
+  staleTtl?: string | number;
+  timeout?: number;
+  ttl?: string | number;
+  video?: boolean;
+  viewport?: object;
+  waitForSelector?: string;
+  waitForTimeout?: number;
+  waitUntil?: WaitUntilEvent | WaitUntilEvent[];
+}
+
+type IframeInfo = {
+  html: string;
+  scripts: Record<string, unknown>;
+}
+
+type MediaInfo = {
+  type?: string;
+  palette?: string[];
+  background_color?: string;
+  color?: string;
+  alternative_color?: string;
+  width?: number;
+  height?: number;
+   duration?: number;
+   duration_pretty?: string;
+}
+
+type MqlResponseData = {
+  // A human-readable representation of the author's name.
+  author?: string | null;
+  // An ISO 8601 representation of the date the article was published.
+  date?: string | null;
+  // The publisher's chosen description of the article.
+  description?: string | null;
+  // An ISO 639-1 representation of the url content language.
+  lang?: string | null;
+  // An image URL that best represents the publisher brand.
+  logo?: MediaInfo | null;
+  // A human-readable representation of the publisher's name.
+  publisher?: string | null;
+  // The publisher's chosen title of the article.
+  title?: string | null;
+  // The URL of the article.
+  url?: string;
+  image?: MediaInfo | null;
+  screenshot?: MediaInfo | null;
+  video?: MediaInfo | null;
+  audio?: MediaInfo | null;
+  iframe?: IframeInfo | null;
+  function?: MqlFunctionResult;
+}
+
+type MqlFunctionResult = {
+  isFulfilled: boolean;
+  isRejected: boolean;
+  value: any;
+};
+
+type MqlStatus = "success" | "fail" | "error";
+
+export type MqlPayload = {
+  status: MqlStatus;
+  data: MqlResponseData;
+  statusCode: number;
+  headers: { [key: string]: string };
+  more?: string,
+  code?: string,
+  url?: string
+}
+
+type MqlResponse = MqlPayload & {
+  response: {
+    url: string;
+    statusCode: number;
+    headers: Headers;
+    body: MqlPayload
+  };
+}
+
+declare function mql(
+  url: string,
+  opts?: MqlOptions & MicrolinkApiOptions,
+  gotOpts?: object
+): Promise<MqlResponse>;
+
+export default mql;
diff --git a/lightweight/package.json b/lightweight/package.json
@@ -1,4 +1,4 @@
 {
   "main": "../src/browser.js",
-  "types": "../index.d.ts"
+  "types": "index.d.ts"
 }
diff --git a/test/index.test-d.ts → test/lightweight.test-d.ts b/test/index.test-d.ts → test/lightweight.test-d.ts
@@ -1,6 +1,4 @@
-// import { expectType } from 'tsd'
-
-import mql from '../index'
+import mql from '../lightweight'
 
 /** mql */
 mql('https://example.com', {
@@ -92,3 +90,18 @@ mql('https://example.com', {
   audio: true,
   video: true
 })
+
+/** response */
+
+const result = await mql('https://example.com', { meta: true })
+console.log(result.status)
+console.log(result.data)
+console.log(result.statusCode)
+console.log(result.headers)
+console.log(result.more)
+console.log(result.code)
+console.log(result.url)
+
+/** stream */
+
+// mql.stream('https://example.com', { meta: true })
diff --git a/test/node.test-d.ts b/test/node.test-d.ts
@@ -0,0 +1,12 @@
+// import { expectType } from 'tsd'
+
+import mql from '..'
+
+/** response */
+
+const result = await mql('https://example.com', { meta: true })
+console.log(result.response.isFromCache)
+
+/** stream */
+
+mql.stream('https://example.com', { meta: true })