feat(sdk): single and collection query functions

feat(sdk): single and collection query functions

Author: Convly

README.md

@@ -1,173 +1,218 @@
-<h1 align="center">sdk-js</h1>
-<h3 align="center">An SDK you can use to easily interface with Strapi from your JavaScript and TypeScript projects</h3>
+<p style="text-align: center">
+  <a href="https://strapi.io/#gh-light-mode-only">
+    <img src="https://strapi.io/assets/strapi-logo-dark.svg" width="318px" alt="Strapi logo" />
+  </a>
+  <a href="https://strapi.io/#gh-dark-mode-only">
+    <img src="https://strapi.io/assets/strapi-logo-light.svg" width="318px" alt="Strapi logo" />
+  </a>
+</p>
 
+<h2 style="text-align: center">Manage Your Strapi Content From Anywhere 🚀</h2>
+<p style="text-align: center">Connect your JavaScript/TypeScript apps to a flexible and fully customizable Strapi backend with ease.</p>
+<p style="text-align: center"><a href="https://github.com/strapi/strapi">CMS Repository</a> - <a href="https://strapi.io">Website</a></p>
 <br />
 
-<p align="center">
-  <a href="https://www.npmjs.com/package/@strapi/sdk-js" target="_blank">
-   <img src="https://img.shields.io/npm/v/@strapi/sdk-js" alt="NPM version" />
+<p style="text-align: center">
+  <a href="https://www.npmjs.org/package/@strapi/sdk-js">
+    <img src="https://img.shields.io/npm/v/@strapi/sdk-js/latest.svg" alt="NPM Version" />
   </a>
   <a href="https://www.npmjs.com/package/@strapi/sdk-js" target="_blank">
    <img src="https://img.shields.io/npm/dm/@strapi/sdk-js" alt="NPM downloads" />
   </a>
-  <a href="https://discord.gg/strapi" target="_blank">
-    <img src="https://img.shields.io/discord/811989166782021633?style=flat&colorA=4945ff&colorB=4945ff&label=discord&logo=discord&logoColor=f0f0ff" alt="Chat on Discord" />
+  <a href="https://github.com/strapi/sdk-js/actions/workflows/tests.yml">
+    <img src="https://github.com/strapi/sdk-js/actions/workflows/tests.yml/badge.svg?branch=main" alt="Tests" />
+  </a>
+  <a href="https://discord.strapi.io">
+    <img src="https://img.shields.io/discord/811989166782021633?label=Discord" alt="Strapi on Discord" />
   </a>
 </p>
 
-<br />
-
-sdk-js is an SDK you can use to easily interface with Strapi from your JavaScript or TypeScript project.
-
-## Getting Started With Strapi
-
-If you're brand new to Strapi development, it is recommended to follow the [Strapi Quick Start Guide](https://docs.strapi.io/dev-docs/quick-start)
-
-sdk-js is compatible with Strapi v5+ and interfaces with Strapi's REST API. You can read the API docs [here](https://docs.strapi.io/dev-docs/api/rest)
-
-## SDK Purpose
-
-sdk-js is the recommended and easiest way to interface with Strapi from your JavaScript and TypeScript projects.
-It allows you to easily create, read, update, and delete Strapi content through strongly typed methods.
-
-<!-- TODO confirm whether this is done in MVP -->
-
-If working with javascript, sdk-js can still help to ease your development workflow through queries based on content type UID's.
+<br>
+
+## 📖 Table of contents
+
+1. [Getting Started](#-getting-started)
+   - [Prerequisites](#pre-requisites)
+   - [Installation](#installation)
+2. [Creating and Configuring an SDK Instance](#-creating-and-configuring-the-sdk-instance)
+   - [Basic Configuration](#basic-configuration)
+   - [Authentication](#authentication)
+     - [API Token Authentication](#api-token-authentication)
+3. [API Reference](#-api-reference)
+4. [Resource Managers](#-resource-managers)
+   - [`.collection()`](#collectionresource)
+   - [`.single()`](#singleresource)
+5. [Examples](#-examples)
+
+## 🛠 Getting started
+### Pre-Requisites
+Before you begin, ensure you have the following:
+- A Strapi backend up and running: [quick start guide](https://docs.strapi.io/dev-docs/quick-start).
+- The API URL of your Strapi instance: for example, `http://localhost:1337/api`.
+- A recent version of [Node.js](https://nodejs.org/en/download/package-manager) installed.
+
+### Installation
+Install the SDK as a dependency in your project:
+
+**NPM**
+```bash
+npm install @strapi/sdk-js
+```
 
-## Getting Started With "@strapi/sdk-js"
+**Yarn**
+```bash
+yarn add @strapi/sdk-js
+```
 
-In its simplest form, "@strapi/sdk-js" works by being connected to the URL of your Strapi instance and provided auth if required.
+**pnpm**
+```bash
+pnpm add @strapi/sdk-js
+```
 
-<!-- TODO confirm examples -->
+## ⚙️ Creating and configuring the SDK Instance
+### Basic configuration
 
-### Importing the SDK
+To interact with your Strapi backend, initialize the SDK with your Strapi API base URL:
 
-```js
-import { createStrapiSDK } from '@strapi/sdk-js'; // ES Modules
-// const { createStrapiSDK } = require("@strapi/sdk-js"); CommonJS
+``` typescript
+import { createStrapiSDK } from '@strapi/sdk-js';
 
-const strapiSDK = createStrapiSDK({
-  baseURL: 'http://localhost:1337',
-});
+const sdk = createStrapiSDK({ baseURL: 'http://localhost:1337/api' });
 ```
 
-### Script tag example
+Alternatively, use a `<script>` tag in a browser environment:
 
-```html
+``` html
 <script src="https://cdn.jsdelivr.net/npm/@strapi/sdk-js"></script>
+
 <script>
-  const strapiSDK = createStrapiSDK({
-    baseURL: 'http://localhost:1337',
-  });
+  const sdk = createStrapiSDK({ baseURL: 'http://localhost:1337/api' });
 </script>
 ```
 
-## Generate the SDK based on your content type schema
+### Authentication
+The SDK supports multiple authentication strategies for accessing authenticated content in your Strapi backend.
 
-sdk-js becomes most powerful when you generate the SDK based on your content type schema. This allows you access to strongly typed methods for creating, reading, updating and deleting content.
+#### API-Token authentication
 
-There are multiple ways to do this:
+If your Strapi instance uses API tokens, configure the SDK like this:
 
-### Using the CLI
+``` typescript
+const sdk = createStrapiSDK({
+  baseURL: 'http://localhost:1337/api',
+  auth: {
+    strategy: 'api-token',
+    options: { token: 'your-api-token-here' },
+  },
+});
+```
 
-sdk-js provides a CLI command to generate the SDK based on your Strapi app content schema.
+## 📚 API Reference
 
-<!-- TODO should we provide an output path option to the CLI? -->
+The Strapi SDK instance provides key properties and utility methods for content and API interaction:
+- **`baseURL`**: base URL of your Strapi backend.
+- **`fetch`**: perform generic requests to the Strapi Content API using fetch-like syntax.
+- **`.collection(resource: string)`**: get a manager instance for handling collection-type resources.
+- **`.single(resource: string)`**: get a manager instance for handling single-type resources.
 
-```sh
-# Run this in the root of your Strapi app
-npx @strapi/sdk-js@latest generate
+## 📁 Resource Managers
+### `.collection(resource)`
 
-# You can optionally provide the path to strapi app and run the command from elsewhere
-npx @strapi/sdk-js@latest generate --path ../strapi-app
+The `.collection()` method provides a manager for working with collection-type resources,
+which can have multiple entries.
 
-```
+**Note**: the `resource` corresponds to the plural name of your collection type, as defined in the Strapi model.
 
-As opposed to importing the SDK from a CDN or NPM, the generated asset can then be imported and used as per the examples above.
+#### Available Methods:
 
-### Providing the SDK with a Strapi Schema
+1. **`find(queryParams?)`**: fetch multiple entries.
+2. **`findOne(documentID, queryParams?)`**: fetch a single entry by its ID.
+3. **`create(data, queryParams?)`**: create a new entry.
+4. **`update(documentID, data, queryParams?)`**: update an existing entry.
+5. **`delete(documentID, queryParams?)`**: remove an entry.
 
-Alternatively, you can use the SDK from a CDN or NPM, but provide the SDK with a Strapi schema.
+#### Examples:
 
-```js
-import { createStrapiSDK } from '@strapi/sdk-js';
-// TODO clarify where this comes from and how to generate it
-import strapiAppSchema from '../path/to/strapi-app-schema.json';
+``` typescript
+const articles = sdk.collection('articles');
 
-const strapiSDK = createStrapiSDK({
-  baseURL: 'http://localhost:1337',
-  schema: strapiAppSchema,
+// Fetch all english articles sorted by title
+const allArticles = await articles.find({
+  locale: 'en',
+  sort: 'title',
 });
-```
 
-## Interacting with Strapi
+// Fetch a single article
+const singleArticle = await articles.findOne('article-document-id');
 
-### Fetch
-
-The SDK provides a `fetch` method that allows you to make requests relative to the Strapi Content API.
-
-The params accepted by the `fetch` method are the same as those accepted by the native `fetch` [API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch). With the first param being a relative path to the Strapi Content API.
+// Create a new article
+const newArticle = await articles.create({ title: 'New Article', content: '...' });
 
-You can refer to the documentation for the [Strapi Content API](https://docs.strapi.io/dev-docs/api/rest) for more information on the available endpoints and their required params.
+// Update an existing article
+const updatedArticle = await articles.update('article-document-id', { title: 'Updated Title' });
 
-```js
-// Create a new article
-const response = await strapiSDK.fetch('/articles', {
-  method: 'POST',
-  body: {
-    title: 'My first article',
-  },
-});
+// Delete an article
+await articles.delete('article-id');
 ```
+### `.single(resource)`
 
-### Query
+The `.single()` method provides a manager for working with collection-type resources, which have only one entry.
 
-The SDK also allows you to query your content types based on their UID via the `strapiSdk.query` method.
+**Note**: the `resource` corresponds to the singular name of your collection type, as defined in the Strapi model.
 
-`strapiSdk.query` provides a few different use cases:
+#### Available Methods:
 
-```js
-query<T = AnySchema>(uid: string): T {
-  return result as T;
-}
-```
+1. **`find(queryParams?)`**: fetch the document.
+2. **`update(data, queryParams?)`**: update the document.
+3. **`delete(queryParams?)`**: remove the document.
 
-#### Usage as a javascript developer
+#### Examples:
+``` typescript
+const homepage = sdk.single('homepage');
 
-```js
-// Here the developer will get basic intellisense based on the AnySchema type.
-const jsResult = jsSdk.query('uid');
-```
+// Fetch the default version of the homepage
+const homepageContent = await homepage.find();
 
-#### Usage as a TypeScript developer without a generated SDK
+// Fetch the spanish version of the homepage
+const homepageContent = await homepage.find({ locale: 'es' });
 
-The developer will manually provide a content type schema to correctly type the inputs and outputs of `sdk.query`.
+// Update the homepage draft content
+const updatedHomepage = await homepage.update({ title: 'Updated Homepage Title' }, { status: 'draft' });
 
-```js
-const tsResult = tsSdk.query < ManuallyProvidedSchema > 'uid';
+// Delete the homepage content
+await homepage.delete();
 ```
 
-#### Usage in TypeScript with generated SDK
-
-Assuming the SDK is generated with full type information, the developer will get full autocomplete for the returned data.
+## 💡 Examples
 
-```js
-const generatedResult = generatedSdk.query('uid'); // Full autocomplete
-```
+Here’s how to combine `.collection()` and `.single()` methods in a real-world scenario:
 
-### Generated Query API's
+``` typescript
+const sdk = createStrapiSDK({
+  baseURL: 'http://localhost:1337/api',
+  auth: {
+    strategy: 'api-token',
+    options: { token: 'your-api-token-here' },
+  },
+});
 
-When you generate the SDK based on your Strapi app schema, the SDK will also generate methods for querying your content types.
+async function main() {
+  // Work with collections
+  const articles = sdk.collection('articles');
+  const newArticle = await articles.create({ title: 'Hello World', content: '...' });
+  console.log('Created Article:', newArticle);
 
-These methods are strongly typed and allow you to query your content types based on their UID.
+  const allArticles = await articles.find({ sort: 'createdAt:desc' });
+  console.log('All Articles:', allArticles);
 
-They are available on the SDK instance as `sdk.queries[contentTypePluralName][method]`.
+  // Work with single types
+  const homepage = sdk.single('homepage');
+  const homepageContent = await homepage.find();
+  console.log('Homepage Content:', homepageContent);
 
-For example, if you have a content type with the plural name of `articles`, the available methods will be `find`, `findOne`, `create`, `update`, and `delete`.
+  const updatedHomepage = await homepage.update({ title: 'Welcome to the New Homepage' });
+  console.log('Updated Homepage:', updatedHomepage);
+}
 
-```js
-// Find all articles
-const articles = await strapiSDK.queries.articles.findMany();
+main();
 ```
-
-<!-- TODO refer to docs elsewhere for params accepted for filtering and sorting etc -->

package.json

@@ -55,6 +55,8 @@
     "@commitlint/cli": "19.6.0",
     "@commitlint/config-conventional": "19.6.0",
     "@commitlint/types": "19.5.0",
+    "@rollup/plugin-commonjs": "^28.0.1",
+    "@rollup/plugin-node-resolve": "^15.3.0",
     "@rollup/plugin-typescript": "12.1.1",
     "@strapi/eslint-config": "0.2.1",
     "@types/jest": "^29.5.14",
@@ -75,5 +77,6 @@
   "engines": {
     "node": ">=18.0.0 <=22.x.x",
     "npm": ">=6.0.0"
-  }
+  },
+  "dependencies": {}
 }