@dotcms/client 0.0.1-alpha.5 → 0.0.1-alpha.50

package/README.md

@@ -1,6 +1,6 @@
-# @dotcms/client
+# DotCMS API Client - `@dotcms/client`
 
-`@dotcms/client` is the official dotCMS JavaScript library designed to simplify interactions with the DotCMS REST APIs.
+The `@dotcms/client` is a JavaScript/TypeScript library for interacting with a DotCMS instance. It allows you to easily fetch pages, content, and navigation information in JSON format, as well as to make complex queries on content collections.
 
 This client library provides a streamlined, promise-based interface to fetch pages and navigation API.
 
@@ -10,9 +10,11 @@ This client library provides a streamlined, promise-based interface to fetch pag
 -   Support for custom actions to communicate with the DotCMS page editor.
 -   Comprehensive TypeScript typings for better development experience.
 
+# DotCMS API Client
+
 ## Installation
 
-Install the package via npm:
+To get started, install the client via npm or yarn:
 
 ```bash
 npm install @dotcms/client
@@ -26,12 +28,24 @@ yarn add @dotcms/client
 
 ## Usage
 
-First, initialize the client with your DotCMS instance details.
+`@dotcms/client` supports both ES modules and CommonJS. You can import it using either syntax:
+
+### ES Modules
+
+```javascript
+import { DotCmsClient } from '@dotcms/client';
+```
+
+### CommonJS
 
 ```javascript
-import { dotcmsClient } from '@dotcms/client';
+const { DotCmsClient } = require('@dotcms/client');
+```
 
-const client = dotcmsClient.init({
+First, initialize the client with your DotCMS instance details.
+
+```javascript
+const client = DotCmsClient.init({
     dotcmsUrl: 'https://your-dotcms-instance.com',
     authToken: 'your-auth-token',
     siteId: 'your-site-id'
@@ -40,7 +54,7 @@ const client = dotcmsClient.init({
 
 ### Fetching a Page
 
-Retrieve the elements of any page in your DotCMS system in JSON format.
+You can retrieve the elements of any page in your DotCMS system in JSON format using the client.page.get() method.
 
 ```javascript
 const pageData = await client.page.get({
@@ -48,13 +62,11 @@ const pageData = await client.page.get({
     language_id: 1,
     personaId: 'optional-persona-id'
 });
-
-console.log(pageData);
 ```
 
 ### Fetching Navigation
 
-Retrieve information about the DotCMS file and folder tree.
+Retrieve the DotCMS file and folder tree to get information about the navigation structure.
 
 ```javascript
 const navData = await client.nav.get({
@@ -62,15 +74,137 @@ const navData = await client.nav.get({
     depth: 2,
     languageId: 1
 });
+```
+
+### Fetching a Collection of Content
+
+The `getCollection` method allows you to fetch a collection of content items using a builder pattern for complex queries.
+
+#### Basic Usage
+
+Here’s a simple example to fetch content from a collection:
+
+```typescript
+import { DotCmsClient } from '@dotcms/client';
+
+const client = DotCmsClient.init({
+    dotcmsUrl: 'https://your-dotcms-instance.com',
+    authToken: 'your-auth-token'
+});
+
+const collectionResponse = await client.content
+    .getCollection('Blog') // Collection name
+    .limit(10) // Limit results to 10 items
+    .page(1) // Fetch the first page
+    .fetch(); // Execute the query
+
+console.log(collectionResponse.contentlets);
+```
+
+#### Sorting Content
+
+You can sort the content by any field in ascending or descending order:
+
+```typescript
+const sortedResponse = await client.content
+    .getCollection('Blog')
+    .sortBy([{ field: 'title', order: 'asc' }]) // Sort by title in ascending order
+    .fetch();
+```
+
+#### Filtering by Language
+
+If you need to filter content by language, you can specify the `language` parameter:
 
-console.log(navData);
+```typescript
+const languageFilteredResponse = await client.content
+    .getCollection('Blog')
+    .language(2) // Filter by language ID (e.g., 2)
+    .fetch();
+```
+
+#### Using Complex Queries
+
+You can build more complex queries using the query builder. For example, filter by author and `title`:
+
+```typescript
+const complexQueryResponse = await client.content
+    .getCollection('Blog')
+    .query((qb) => qb.field('author').equals('John Doe').and().field('title').equals('Hello World'))
+    .fetch();
+```
+
+#### Fetching Draft Content
+
+To only fetch draft content, use the `draft()` method:
+
+```typescript
+const draftContentResponse = await client.content
+    .getCollection('Blog')
+    .draft() // Fetch only drafts content
+    .fetch();
+```
+
+#### Setting Depth for Relationships
+
+To fetch content with a specific relationship depth, use the `depth()` method:
+
+```typescript
+const depthResponse = await client.content
+    .getCollection('Blog')
+    .depth(2) // Fetch related content up to depth 2
+    .fetch();
+```
+
+#### Combining Multiple Methods
+
+You can combine multiple methods to build more complex queries. For example, limit results, sort them, and filter by author:
+
+```typescript
+const combinedResponse = await client.content
+    .getCollection('Blog')
+    .limit(5)
+    .page(2)
+    .sortBy([{ field: 'title', order: 'asc' }])
+    .query((qb) => qb.field('author').equals('John Doe'))
+    .depth(1)
+    .fetch();
+```
+
+## Error Handling Example
+
+To handle errors gracefully, you can use a `try-catch` block around your API calls. Here’s an example:
+
+```typescript
+try {
+    const pageData = await client.page.get({
+        path: '/your-page-path',
+        languageId: 1
+    });
+} catch (error) {
+    console.error('Failed to fetch page data:', error);
+}
+```
+
+This ensures that any errors that occur during the fetch (e.g., network issues, invalid paths, etc.) are caught and logged properly.
+
+## Pagination
+
+When fetching large collections of content, pagination is key to managing the number of results returned:
+
+```typescript
+const paginatedResponse = await client.content
+    .getCollection('Blog')
+    .limit(10) // Limit to 10 items per page
+    .page(2) // Get the second page of results
+    .fetch();
 ```
 
 ## API Reference
 
 Detailed documentation of the `@dotcms/client` methods, parameters, and types can be found below:
 
-### `dotcmsClient.init(config: ClientConfig): DotCmsClient`
+### `DotCmsClient.init(config: ClientConfig): DotCmsClient`
 
 Initializes the DotCMS client with the specified configuration.
 
@@ -82,6 +216,17 @@ Retrieves the specified page's elements from your DotCMS system in JSON format.
 
 Retrieves information about the DotCMS file and folder tree.
 
+### `DotCmsClient.content.getCollection(contentType: string): CollectionBuilder<T>`
+Creates a builder to filter and fetch a collection of content items for a specific content type.
+
+#### Parameters
+
+contentType (string): The content type to retrieve.
+
+#### Returns
+
+CollectionBuilder<T>: A builder instance for chaining filters and executing the query.
+
 ## Contributing
 
 GitHub pull requests are the preferred method to contribute code to dotCMS. Before any pull requests can be accepted, an automated tool will ask you to agree to the [dotCMS Contributor's Agreement](https://gist.github.com/wezell/85ef45298c48494b90d92755b583acb3).
@@ -105,7 +250,6 @@ Always refer to the official [DotCMS documentation](https://www.dotcms.com/docs/
 | Installation    | [Installation](https://dotcms.com/docs/latest/installation)         |
 | Documentation   | [Documentation](https://dotcms.com/docs/latest/table-of-contents)   |
 | Videos          | [Helpful Videos](http://dotcms.com/videos/)                         |
-| Code Examples   | [Codeshare](https://dotcms.com/codeshare/)                          |
 | Forums/Listserv | [via Google Groups](https://groups.google.com/forum/#!forum/dotCMS) |
 | Twitter         | @dotCMS                                                             |
-| Main Site       | [dotCMS.com](https://dotcms.com/)                                   |
+| Main Site       | [dotCMS.com](https://dotcms.com/)                                   |

package/index.cjs.d.ts

@@ -0,0 +1 @@
+export * from "./src/index";

package/index.cjs.default.js

@@ -0,0 +1 @@
+exports._default = require('./index.cjs.js').default;