From 21217c0e928f3e5eca1f0b98d6e78fb2870506db Mon Sep 17 00:00:00 2001 From: Hongbo Wu Date: Thu, 7 Mar 2024 18:01:49 +0800 Subject: [PATCH] update README --- README.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++++- src/client.ts | 44 ++++++++++----- src/graphql.ts | 26 +++++---- src/index.ts | 12 ++-- 4 files changed, 197 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 4314a4c..4c3cc8a 100644 --- 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:feedback@omnivore.app) us or join our [Discord server](https://discord.gg/h2z5rppzz9). diff --git a/src/client.ts b/src/client.ts index dc1175e..1348f52 100644 --- 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 => { + search: async ( + params: SearchItemParameters, + ): Promise => { 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 => { + updates: async ( + params: ItemUpdatesParameters, + ): Promise => { 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 => { + delete: async ( + params: DeleteItemParameters, + ): Promise => { 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 => { + params: SaveItemByUrlParameters, + ): Promise => { const { data, error } = await this.client .mutation(saveByURLMutation, { input: { diff --git a/src/graphql.ts b/src/graphql.ts index 564a2c3..cd2a6b8 100644 --- 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 index e685b95..ab3e0f5 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,6 +1,6 @@ export { ClientOptions, - DeleteResponse, + DeleteItemResponse as DeleteResponse, Highlight, HighlightType, Label, @@ -8,11 +8,11 @@ export { 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'