update README

omnivore-app · Mar 7, 2024 · 21217c0 · 21217c0
1 parent 308dc53
commit 21217c0
Show file tree

Hide file tree

Showing 4 changed files with 197 additions and 34 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Omnivore API
 
-Omnivore API Client Library for Node.js
+[Omnivore](https://omnivore.app) API Client Library for Node.js
 
 ![Build status](https://github.com/omnivore-app/omnivore-api/actions/workflows/ci.yml/badge.svg)
 
@@ -12,7 +12,9 @@ npm install @omnivore/api
 
 ## Usage
 
-Import the `Omnivore` class and create a new instance with your `authToken` and `baseUrl`. Then you can use the instance to make requests to the Omnivore API.
+> Create an [API key](https://omnivore.app/settings/api) and use it to authenticate requests to the Omnivore API.
+
+Import the `Omnivore` class and create a new instance with your **API Key** and **Base URL**. Then you can use the instance to make requests to the Omnivore API.
 
 ```javascript
 import { Omnivore } from '@omnivore/api'
@@ -27,6 +29,123 @@ const items = await omnivore.items.search({
 })
 ```
 
+## API
+
+Currently, the library supports the following API methods:
+
+### `items.search`
+
+Search for items.
+
+### Request
+
+```typescript
+interface SearchItemParameters {
+  after?: string
+  first?: number
+  format?: string
+  includeContent?: boolean
+  query?: string
+}
+```
+
+### Response
+
+```typescript
+export interface SearchItemResponse {
+  edges: {
+    node: Node
+  }[]
+  pageInfo: PageInfo
+}
+```
+
+### `items.updates`
+
+Get updates for items.
+
+### Request
+
+```typescript
+export interface ItemUpdatesRequest {
+  since: string
+}
+```
+
+### Response
+
+```typescript
+export interface ItemUpdatesResponse {
+  edges: {
+    itemID: string
+    updateReason: 'CREATED' | 'UPDATED' | 'DELETED'
+    node: Node | null
+  }[]
+  pageInfo: PageInfo
+}
+```
+
+### `items.saveByUrl`
+
+Save an item by URL.
+
+### Request
+
+```typescript
+export interface SaveItemByUrlParameters {
+  url: string
+  clientRequestId?: string
+  source?: string
+  state?:
+    | 'DELETED'
+    | 'ARCHIVED'
+    | 'CONTENT_NOT_FETCHED'
+    | 'FAILED'
+    | 'PROCESSING'
+    | 'SUCCEEDED'
+  timezone?: string
+  locale?: string
+  folder?: string
+  labels?: {
+    name: string
+    color?: string
+    description?: string
+  }[]
+  publishedAt: string
+  savedAt: string
+}
+```
+
+### Response
+
+```typescript
+export interface SaveItemByUrlResponse {
+  id: string
+}
+```
+
+### `items.delete`
+
+Delete an item.
+
+### Request
+
+```typescript
+export interface DeleteItemParameters {
+  id: string
+}
+```
+
+### Response
+
+```typescript
+export interface DeleteItemResponse {
+  id: string
+}
+```
+
+> For more API methods, check the [API documentation](https://docs.omnivore.app/integrations/api.html).
+
 ## Error handling
 
 The library will throw an error if the request fails. You can catch the error and handle it as needed.
@@ -49,3 +168,29 @@ try {
   }
 }
 ```
+
+## Client options
+
+The `Omnivore` class accepts an options object with the following properties:
+
+| Option      | Default value                     | Type     | Description                                                                          |
+| ----------- | --------------------------------- | -------- | ------------------------------------------------------------------------------------ |
+| `authToken` | `undefined`                       | `string` | API key required for authentication.                                                 |
+| `baseUrl`   | `"https://api-prod.omnivore.app"` | `string` | The base URL for sending API requests. This can be changed to a local-hosted server. |
+| `timeoutMs` | `0`                               | `number` | Number of milliseconds to wait before timeout.                                       |
+
+## Requirements
+
+- Node.js 16 or later
+
+## License
+
+This library is licensed under BSD-3-Clause. See [LICENSE](LICENSE) for more details.
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
+
+## Support
+
+For support, please open an issue in this repository, [email](mailto:[email protected]) us or join our [Discord server](https://discord.gg/h2z5rppzz9).
diff --git a/src/client.ts b/src/client.ts
@@ -77,22 +77,26 @@ export interface PageInfo {
   totalCount: number | null
 }
 
-export interface SearchParameters {
+export interface SearchItemParameters {
   after?: string
   first?: number
-  format?: string
+  format?: 'html' | 'markdown'
   includeContent?: boolean
   query?: string
 }
 
-export interface SearchResponse {
+export interface SearchItemResponse {
   edges: {
     node: Node
   }[]
   pageInfo: PageInfo
 }
 
-export interface UpdatesSinceResponse {
+export interface ItemUpdatesParameters {
+  since: string
+}
+
+export interface ItemUpdatesResponse {
   edges: {
     itemID: string
     updateReason: 'CREATED' | 'UPDATED' | 'DELETED'
@@ -101,7 +105,7 @@ export interface UpdatesSinceResponse {
   pageInfo: PageInfo
 }
 
-export interface SaveByURLParameters {
+export interface SaveItemByUrlParameters {
   url: string
   clientRequestId?: string
   source?: string
@@ -124,11 +128,15 @@ export interface SaveByURLParameters {
   savedAt: string
 }
 
-export interface DeleteResponse {
+export interface SaveItemByUrlResponse {
+  id: string
+}
+
+export interface DeleteItemParameters {
   id: string
 }
 
-export interface SaveByURLResponse {
+export interface DeleteItemResponse {
   id: string
 }
 
@@ -151,7 +159,9 @@ export class Omnivore {
   // Omnivore API methods
   public readonly items = {
     // search for items
-    search: async (params: SearchParameters): Promise<SearchResponse> => {
+    search: async (
+      params: SearchItemParameters,
+    ): Promise<SearchItemResponse> => {
       const { data, error } = await this.client
         .query(SearchQuery, params)
         .toPromise()
@@ -167,9 +177,11 @@ export class Omnivore {
     },
 
     // get updates since a given date
-    updates: async (since: string): Promise<UpdatesSinceResponse> => {
+    updates: async (
+      params: ItemUpdatesParameters,
+    ): Promise<ItemUpdatesResponse> => {
       const { data, error } = await this.client
-        .query(UpdatesSinceQuery, { since })
+        .query(UpdatesSinceQuery, params)
         .toPromise()
 
       const updatesSince = data?.updatesSince
@@ -187,9 +199,13 @@ export class Omnivore {
     },
 
     // delete an item
-    delete: async (id: string): Promise<DeleteResponse> => {
+    delete: async (
+      params: DeleteItemParameters,
+    ): Promise<DeleteItemResponse> => {
       const { data, error } = await this.client
-        .mutation(DeleteMutation, { input: { articleID: id, bookmark: false } })
+        .mutation(DeleteMutation, {
+          input: { articleID: params.id, bookmark: false },
+        })
         .toPromise()
 
       const deleteArticle = data?.setBookmarkArticle
@@ -208,8 +224,8 @@ export class Omnivore {
 
     // save an item by URL
     saveByUrl: async (
-      params: SaveByURLParameters,
-    ): Promise<SaveByURLResponse> => {
+      params: SaveItemByUrlParameters,
+    ): Promise<SaveItemByUrlResponse> => {
       const { data, error } = await this.client
         .mutation(saveByURLMutation, {
           input: {

diff --git a/src/graphql.ts b/src/graphql.ts
@@ -11,6 +11,16 @@ const graphql = initGraphQLTada<{
   }
 }>()
 
+const PageInfoFragment = graphql(`
+  fragment PageInfoFragment on PageInfo @_unmask {
+    hasNextPage
+    hasPreviousPage
+    startCursor
+    endCursor
+    totalCount
+  }
+`)
+
 const LabelFragment = graphql(`
   fragment LabelFragment on Label @_unmask {
     name
@@ -104,11 +114,7 @@ export const SearchQuery = graphql(
             }
           }
           pageInfo {
-            hasNextPage
-            hasPreviousPage
-            startCursor
-            endCursor
-            totalCount
+            ...PageInfoFragment
           }
         }
         ... on SearchError {
@@ -117,7 +123,7 @@ export const SearchQuery = graphql(
       }
     }
   `,
-  [SearchItemFragment],
+  [SearchItemFragment, PageInfoFragment],
 )
 
 export const UpdatesSinceQuery = graphql(
@@ -134,11 +140,7 @@ export const UpdatesSinceQuery = graphql(
             }
           }
           pageInfo {
-            hasNextPage
-            hasPreviousPage
-            startCursor
-            endCursor
-            totalCount
+            ...PageInfoFragment
           }
         }
         ... on UpdatesSinceError {
@@ -147,7 +149,7 @@ export const UpdatesSinceQuery = graphql(
       }
     }
   `,
-  [SearchItemFragment],
+  [SearchItemFragment, PageInfoFragment],
 )
 
 export const DeleteMutation = graphql(`

diff --git a/src/index.ts b/src/index.ts
@@ -1,18 +1,18 @@
 export {
   ClientOptions,
-  DeleteResponse,
+  DeleteItemResponse as DeleteResponse,
   Highlight,
   HighlightType,
   Label,
   Node,
   Omnivore,
   PageInfo,
   PageType,
-  SaveByURLParameters,
-  SaveByURLResponse,
-  SearchParameters,
-  SearchResponse,
-  UpdatesSinceResponse,
+  SaveItemByUrlParameters as SaveByURLParameters,
+  SaveItemByUrlResponse as SaveByURLResponse,
+  SearchItemParameters as SearchParameters,
+  SearchItemResponse as SearchResponse,
+  ItemUpdatesResponse as UpdatesSinceResponse,
 } from './client'
 
 export { OmnivoreError, OmnivoreErrorCode, isOmnivoreError } from './errors'