Merge pull request #108 from ButterCMS/2549-add-v2-typings-to-js-sdk

Add V2 Typings to JS SDK

README.md

@@ -38,14 +38,14 @@ Using ES6 or Typescript:
 
 ```js
 import Butter from "buttercms";
-const butter = Butter("api_token_567abe");
+const butter = Butter("your_api_token");
 ```
 
 Using CDN:
 
 ```html
 <script>
-  const butter = Butter("api_token_567abe");
+  const butter = Butter("your_api_token");
 </script>
 ```
 

lib/butter.d.ts

@@ -61,6 +61,13 @@ export namespace Butter {
     count: number;
   }
 
+  interface Methods {
+    /**
+     * Cancels the ongoing fetch request by aborting the associated AbortController
+     */
+    cancelRequest(): void;
+  }
+
   interface Response<Data extends object | string = any> {
     data?: Data;
     status?: number;
@@ -78,12 +85,14 @@ export namespace Butter {
   }
 
   interface PostListParams<AuthorSlug extends string = string> {
-    preview?: 1 | 0;
+    author_slug?: AuthorSlug;
+    category_slug?: string;
     exclude_body?: boolean;
+    limit?: number;
+    offset?: number;
     page?: number;
     page_size?: number;
-    author_slug?: AuthorSlug;
-    category_slug?: string;
+    preview?: 1 | 0;
     tag_slug?: string;
   }
 
@@ -96,28 +105,35 @@ export namespace Butter {
     AuthorSlug extends string = string,
     PostSlug extends string = string
   > {
-    status: "published" | "draft";
-    created: Date;
-    updated: Date;
-    published: Date;
-    title: string;
+    author: Omit<Author<AuthorSlug>, "recent_posts">;
+    body?: string;
+    categories: Category[];
+    created: string;
+    featured_image: string | null;
+    featured_image_alt: string;
+    meta_description: string;
+    published: string | null;
+    scheduled: string | null;
+    seo_title: string;
     slug: PostSlug;
+    status: "published" | "draft" | "scheduled";
     summary: string;
-    seo_title: string;
-    meta_description: string;
-    featured_image: string;
-    featured_image_alt: string;
-    url: string;
-    author: Omit<Author<AuthorSlug>, "recent_posts">;
     tags: Tag[];
-    categories: Category[];
-    body?: string;
+    title: string;
+    updated: string | null;
+    url: string;
+  }
+
+  interface PostMeta  {
+    next_post: object | null;
+    previous_post: object | null;
   }
 
   interface PostRetrieveResponse<
     AuthorSlug extends string = string,
     PostSlug extends string = string
   > {
+    meta: PostMeta;
     data: Post<AuthorSlug, PostSlug>;
   }
 
@@ -134,7 +150,7 @@ export namespace Butter {
     data: Post[];
   }
 
-  interface PostMethods {
+  interface PostMethods extends Methods {
     /**
      * Retrieve a post
      * @param slug The post's slug
@@ -195,7 +211,7 @@ export namespace Butter {
     data: Category[];
   }
 
-  interface CategoryMethods {
+  interface CategoryMethods extends Methods {
     /**
      * Retrieve a category
      * @param slug The category's slug
@@ -242,7 +258,7 @@ export namespace Butter {
     data: Tag[];
   }
 
-  interface TagMethods {
+  interface TagMethods extends Methods {
     /**
      * Retrieve a tag
      * @param slug The tag's slug
@@ -299,7 +315,7 @@ export namespace Butter {
     data: Author[];
   }
 
-  interface AuthorMethods {
+  interface AuthorMethods extends Methods {
     /**
      * Retrieve an author
      * @param slug The author's slug
@@ -332,7 +348,7 @@ export namespace Butter {
     tag_slug?: string;
   }
 
-  interface FeedMethods {
+  interface FeedMethods extends Methods {
     /**
      * Get a feed
      * @param feedType The type of feed
@@ -353,38 +369,44 @@ export namespace Butter {
   //////////
 
   interface PageRetrieveParams {
-    preview?: 0 | 1;
     levels?: number;
+    locale?: string;
+    preview?: 0 | 1;
   }
 
   type PageListParams<PageModel extends object = object> =
     WithFieldsPrefix<PageModel> & {
-      preview?: 0 | 1;
       levels?: number;
-      order?: `${"-" | ""}${"published" | "updated"}`;
+      limit?: number;
+      locale?: string;
+      offset?: number;
       page?: number;
       page_size?: number;
+      preview?: 0 | 1;
     };
 
   interface PageSearchParams<PageType extends string = string> {
-    page_type?: PageType;
-    locale?: string;
     levels?: number;
+    limit?: number;
+    locale?: string;
+    offset?: number;
     page?: number;
     page_size?: number;
+    page_type?: PageType;
   }
 
   interface Page<
     PageModel extends object = object,
     PageType extends string = string,
     PageSlug extends string = string
   > {
+    fields: PageModel;
+    name: string;
     page_type: PageType;
+    published: string | null;
     slug: PageSlug;
-    name: string;
-    published: Date;
-    updated: Date;
-    fields: PageModel;
+    status: "published" | "draft" | "scheduled";
+    updated: string | null;
   }
 
   interface PageRetrieveResponse<
@@ -411,7 +433,7 @@ export namespace Butter {
     data: Page<PageModel, PageType>[];
   }
 
-  interface PageMethods {
+  interface PageMethods extends Methods {
     /**
      * Retrieve a single page
      * @param page_type The page type
@@ -468,19 +490,20 @@ export namespace Butter {
 
   type ContentParams<ContentModel extends object = object> =
     WithFieldsPrefix<ContentModel> & {
-      test?: 0 | 1;
+      levels?: number;
+      locale?: string;
       order?: keyof OrderParam<ContentModel>;
       page?: number;
       page_size?: number;
-      levels?: number;
+      preview?: 0 | 1;
     };
 
   interface ContentResponse<ContentModels extends object = object> {
     meta: Meta;
     data: ContentArrays<ContentModels>;
   }
 
-  interface ContentMethods {
+  interface ContentMethods extends Methods {
     /**
      * Retrieve content
      * @param keys An array of the keys of the content to retrieve
@@ -500,26 +523,36 @@ export namespace Butter {
 }
 
 export class ButterStatic {
-  post: Butter.PostMethods;
-  category: Butter.CategoryMethods;
-  tag: Butter.TagMethods;
   author: Butter.AuthorMethods;
+  category: Butter.CategoryMethods;
+  content: Butter.ContentMethods;
   feed: Butter.FeedMethods;
   page: Butter.PageMethods;
-  content: Butter.ContentMethods;
+  post: Butter.PostMethods;
+  tag: Butter.TagMethods;
   constructor(
     apiToken: string,
-    testMode?: boolean,
-    timeout?: number,
-    axiosHook?: (axios: AxiosInstance) => unknown
+    options: {
+      cache?: string
+      onError?: ((errors: any[], params?: object) => void) | null
+      onRequest?: ((apiEndpoint: string, params?: object) => void) | null
+      onResponse?: ((response: Response, params?: object) => void) | null
+      testMode?: boolean
+      timeout?: number
+    }
   );
 }
 
 export const Butter: (
   apiToken: string,
-  testMode?: boolean,
-  timeout?: number,
-  axiosHook?: (axios: AxiosInstance) => unknown
+  options?: {
+    cache?: string
+    onError?: ((errors: any[], params?: object) => void) | null
+    onRequest?: ((apiEndpoint: string, params?: object) => void) | null
+    onResponse?: ((response: Response, params?: object) => void) | null
+    testMode?: boolean
+    timeout?: number
+  }
 ) => ButterStatic;
 
 export default Butter;