From 827c0ed1f281953c2bc90f8cb54b3fa311bc78c3 Mon Sep 17 00:00:00 2001 From: Ajima Chukwuemeka <32770340+ajimae@users.noreply.github.com> Date: Tue, 4 Jan 2022 12:01:17 +0100 Subject: [PATCH] chore(README.md): update package README.md (#156) - update all package README.md file to use sdk-client-v2 - include usage examples and documentations - remove links related to old (nodejs) sdk-client --- README.md | 18 +-- packages/history-sdk/README.md | 130 ++++++++++++++++---- packages/importapi-sdk/README.md | 118 +++++++++++++++--- packages/ml-sdk/README.md | 127 +++++++++++++++++--- packages/platform-sdk/README.md | 139 +++++++++++++++++++--- packages/sdk-client/README.md | 197 ++++++++++++++++++++++++++++++- 6 files changed, 650 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index 17dc43b92..35b24f670 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,10 @@ This repository contains several SDK packages generated from the commercetools platform API reference. +## Documentation + +The full documentation and usage example for the TypeScript SDK can be found [here](https://commercetools.github.io/nodejs/sdk/api/typescriptSdk.html#typescript-sdk-client-v2) + ## Support If you have any urgent issues regarding this repository please create a support request over our [official support channel](http://support.commercetools.com). @@ -27,13 +31,13 @@ If you have any urgent issues regarding this repository please create a support ### SDK -| Package | Version | | -| ------------------------------------------ | --------------------------------------------------------------------- | ---- | -| [`platform-sdk`](/packages/platform-sdk) | [![platform-sdk Version][platform-sdk-icon]][platform-sdk-version] | | -| [`importapi-sdk`](/packages/importapi-sdk) | [![importapi-sdk Version][importapi-sdk-icon]][importapi-sdk-version] | | -| [`ml-sdk`](/packages/ml-sdk) | [![ml-sdk Version][ml-sdk-icon]][ml-sdk-version] | | -| [`history-sdk`](/packages/history-sdk) | [![history-sdk Version][history-sdk-icon]][history-sdk-version] | | -| [`sdk-client`](/packages/sdk-client) | [![client-sdk Version][sdk-client-icon]][sdk-client-version] | Beta | +| Package | Version | +| ------------------------------------------ | --------------------------------------------------------------------- | +| [`platform-sdk`](/packages/platform-sdk) | [![platform-sdk Version][platform-sdk-icon]][platform-sdk-version] | +| [`importapi-sdk`](/packages/importapi-sdk) | [![importapi-sdk Version][importapi-sdk-icon]][importapi-sdk-version] | +| [`ml-sdk`](/packages/ml-sdk) | [![ml-sdk Version][ml-sdk-icon]][ml-sdk-version] | +| [`history-sdk`](/packages/history-sdk) | [![history-sdk Version][history-sdk-icon]][history-sdk-version] | +| [`sdk-client-v2`](/packages/sdk-client) | [![client-sdk Version][sdk-client-icon]][sdk-client-version] | [platform-sdk-version]: https://www.npmjs.com/package/@commercetools/platform-sdk [platform-sdk-icon]: https://img.shields.io/npm/v/@commercetools/platform-sdk.svg?style=flat-square diff --git a/packages/history-sdk/README.md b/packages/history-sdk/README.md index f6ea64841..d9466a6a6 100644 --- a/packages/history-sdk/README.md +++ b/packages/history-sdk/README.md @@ -1,36 +1,126 @@ -# Typescript SDK for commercetools Audit log APIs. +# Typescript SDK for commercetools Audit log (history) APIs. -## Install +## Usage examples -```bash -npm install --save @commercetools/history-sdk -``` +### Browser environment -### Browser +```html + + +``` ```html - ``` -### Usage example +### Node environment + +```bash +npm install --save @commercetools/sdk-client-v2 +npm install --save @commercetools/history-sdk +``` ```ts -import { createAuthMiddlewareForClientCredentialsFlow } from '@commercetools/sdk-middleware-auth' -import { createHttpMiddleware } from '@commercetools/sdk-middleware-http' -import { createClient } from '@commercetools/sdk-client' +const { + ClientBuilder, + createAuthForClientCredentialsFlow, + createHttpClient, +} = require('@commercetools/sdk-client-v2') +const { createApiBuilderFromCtpClient } = require('@commercetools/history-sdk') +const fetch = require('node-fetch') + +const projectKey = 'mc-project-key' +const authMiddlewareOptions = { + host: 'https://auth.europe-west1.gcp.commercetools.com', + projectKey, + credentials: { + clientId: 'mc-client-id', + clientSecret: 'mc-client-secrets', + }, + oauthUri: 'https://auth.europe-west1.gcp.commercetools.com', + scopes: [`manage_project:${projectKey}`], + fetch, +} + +const httpMiddlewareOptions = { + host: 'https://history.europe-west1.gcp.commercetools.com', + fetch, +} + +const client = new ClientBuilder() + .withProjectKey(projectKey) + .withMiddleware(createAuthForClientCredentialsFlow(authMiddlewareOptions)) + .withMiddleware(createHttpClient(httpMiddlewareOptions)) + .withUserAgentMiddleware() + .build() + +// or +const client = new ClientBuilder() + .withProjectKey(projectKey) + .withClientCredentialsFlow(authMiddlewareOptions) + .withHttpMiddleware(httpMiddlewareOptions) + .withUserAgentMiddleware() + .build() + +const apiRoot = createApiBuilderFromCtpClient(client) + +// calling the history-sdk functions +// get project details +apiRoot + .withProjectKey({ projectKey }) + .recommendations() + .projectCategories() + .withProductId({ + productId: product.id, + }) + .get() + .execute() + .then((x) => { + /*...*/ + }) + +apiRoot + .withProjectKey({ projectKey }) + .imageSearch() + .post({ + queryArgs: { + limit: 20, + }, + body: image, + headers: { + 'Content-Type': 'image/jpeg', + }, + }) + .execute() + .then((x) => { + /*...*/ + }) + +// ----------------------------------------------------------------------- +// The sdk-client-v2 also has support for the old syntax import { - createApiBuilderFromCtpClient, - ApiRoot, -} from '@commercetools/history-sdk' + createClient, + createHttpClient, + createAuthForClientCredentialsFlow, +} from '@commercetools/sdk-client-v2' +import { createApiBuilderFromCtpClient } from '@commercetools/history-sdk' import fetch from 'node-fetch' const projectKey = 'some_project_key' -const authMiddleware = createAuthMiddlewareForClientCredentialsFlow({ - host: 'https://auth.europe-west1.gcp.commercetools.com/', +const authMiddleware = createAuthForClientCredentialsFlow({ + host: 'https://auth.europe-west1.gcp.commercetools.com', projectKey, credentials: { clientId: 'some_id', @@ -39,7 +129,7 @@ const authMiddleware = createAuthMiddlewareForClientCredentialsFlow({ fetch, }) -const httpMiddleware = createHttpMiddleware({ +const httpMiddleware = createHttpClient({ host: 'https://history.europe-west1.gcp.commercetools.com', fetch, }) @@ -48,10 +138,10 @@ const ctpClient = createClient({ middlewares: [authMiddleware, httpMiddleware], }) -const apiRoot: ApiRoot = createApiBuilderFromCtpClient(ctpClient) +const apiRoot = createApiBuilderFromCtpClient(ctpClient) apiRoot - .withProjectKeyValue({ projectKey }) + .withProjectKey({ projectKey }) .recommendations() .projectCategories() .withProductId({ diff --git a/packages/importapi-sdk/README.md b/packages/importapi-sdk/README.md index 8c71f3f84..bf042be61 100644 --- a/packages/importapi-sdk/README.md +++ b/packages/importapi-sdk/README.md @@ -1,36 +1,108 @@ # Typescript SDK for commercetools import API -## Install +## Usage examples -```bash -npm install --save @commercetools/importapi-sdk -``` +### Browser environment -### Browser +```html + + +``` ```html - ``` -### Usage example +### Node environment + +```bash +npm install --save @commercetools/sdk-client-v2 +npm install --save @commercetools/importapi-sdk +``` ```ts -import { createAuthMiddlewareForClientCredentialsFlow } from '@commercetools/sdk-middleware-auth' -import { createHttpMiddleware } from '@commercetools/sdk-middleware-http' -import { createClient } from '@commercetools/sdk-client' +const { + ClientBuilder, + createAuthForClientCredentialsFlow, + createHttpClient, +} = require('@commercetools/sdk-client-v2') +const { createApiBuilderFromCtpClient } = require('@commercetools/importapi-sdk') +const fetch = require('node-fetch') + +const projectKey = 'mc-project-key' +const authMiddlewareOptions = { + host: 'https://auth.europe-west1.gcp.commercetools.com', + projectKey, + credentials: { + clientId: 'mc-client-id', + clientSecret: 'mc-client-secrets', + }, + oauthUri: 'https://auth.europe-west1.gcp.commercetools.com', + scopes: [`manage_project:${projectKey}`], + fetch, +} + +const httpMiddlewareOptions = { + host: 'https://api.europe-west1.gcp.commercetools.com', + fetch, +} + +const client = new ClientBuilder() + .withProjectKey(projectKey) + .withMiddleware(createAuthForClientCredentialsFlow(authMiddlewareOptions)) + .withMiddleware(createHttpClient(httpMiddlewareOptions)) + .withUserAgentMiddleware() + .build() + +// or +const client = new ClientBuilder() + .withProjectKey(projectKey) + .withClientCredentialsFlow(authMiddlewareOptions) + .withHttpMiddleware(httpMiddlewareOptions) + .withUserAgentMiddleware() + .build() + + +const apiRoot = createApiBuilderFromCtpClient(client) + +// calling the importapi functions +// get project details +apiRoot + .withProjectKey({ + projectKey, + }) + .get() + .execute() + .then((x) => { + /*...*/ + }) + + +// ----------------------------------------------------------------------- +// The sdk-client-v2 also has support for the old syntax import { - createApiBuilderFromCtpClient, - ApiRoot, -} from '@commercetools/importapi-sdk' + createClient, + createHttpClient, + createAuthForClientCredentialsFlow, +} from '@commercetools/sdk-client-v2' +import { createApiBuilderFromCtpClient } from '@commercetools/importapi-sdk') import fetch from 'node-fetch' const projectKey = 'some_project_key' -const authMiddleware = createAuthMiddlewareForClientCredentialsFlow({ - host: 'https://auth.europe-west1.gcp.commercetools.com/', +const authMiddleware = createAuthForClientCredentialsFlow({ + host: 'https://auth.europe-west1.gcp.commercetools.com', projectKey, credentials: { clientId: 'some_id', @@ -39,7 +111,7 @@ const authMiddleware = createAuthMiddlewareForClientCredentialsFlow({ fetch, }) -const httpMiddleware = createHttpMiddleware({ +const httpMiddleware = createHttpClient({ host: 'https://import.europe-west1.gcp.commercetools.com', fetch, }) @@ -48,5 +120,15 @@ const ctpClient = createClient({ middlewares: [authMiddleware, httpMiddleware], }) -const apiRoot: ApiRoot = createApiBuilderFromCtpClient(ctpClient) +const apiRoot = createApiBuilderFromCtpClient(ctpClient) + +apiRoot + .withProjectKey({ + projectKey, + }) + .get() + .execute() + .then((x) => { + /*...*/ + }) ``` diff --git a/packages/ml-sdk/README.md b/packages/ml-sdk/README.md index 2952b980d..7f6239ba7 100644 --- a/packages/ml-sdk/README.md +++ b/packages/ml-sdk/README.md @@ -1,33 +1,128 @@ # Typescript SDK for commercetools machine learning API -## Install +## Usage examples -```bash -npm install --save @commercetools/ml-sdk -``` +### Browser environment -### Browser +```html + + +``` ```html - ``` -### Usage example +### Node environment + +```bash +npm install --save @commercetools/sdk-client-v2 +npm install --save @commercetools/ml-sdk +``` ```ts -import { createAuthMiddlewareForClientCredentialsFlow } from '@commercetools/sdk-middleware-auth' -import { createHttpMiddleware } from '@commercetools/sdk-middleware-http' -import { createClient } from '@commercetools/sdk-client' -import { createApiBuilderFromCtpClient, ApiRoot } from '@commercetools/ml-sdk' +const { + ClientBuilder, + createAuthForClientCredentialsFlow, + createHttpClient, +} = require('@commercetools/sdk-client-v2') +import { createApiBuilderFromCtpClient } from '@commercetools/ml-sdk' +const fetch = require('node-fetch') + +const projectKey = 'mc-project-key' +const authMiddlewareOptions = { + host: 'https://auth.europe-west1.gcp.commercetools.com', + projectKey, + credentials: { + clientId: 'mc-client-id', + clientSecret: 'mc-client-secrets', + }, + oauthUri: 'https://auth.europe-west1.gcp.commercetools.com', + scopes: [`manage_project:${projectKey}`], + fetch, +} + +const httpMiddlewareOptions = { + host: 'https://ml-eu.europe-west1.gcp.commercetools.com', + fetch, +} + +const client = new ClientBuilder() + .withProjectKey(projectKey) + .withMiddleware(createAuthForClientCredentialsFlow(authMiddlewareOptions)) + .withMiddleware(createHttpClient(httpMiddlewareOptions)) + .withUserAgentMiddleware() + .build() + +// or +const client = new ClientBuilder() + .withProjectKey(projectKey) + .withClientCredentialsFlow(authMiddlewareOptions) + .withHttpMiddleware(httpMiddlewareOptions) + .withUserAgentMiddleware() + .build() + + +const apiRoot = createApiBuilderFromCtpClient(client) + +// calling the ml-sdk functions +// get project details +apiRoot + .withProjectKey({ projectKey }) + .recommendations() + .projectCategories() + .withProductId({ + productId: product.id, + }) + .get() + .execute() + .then((x) => { + /*...*/ + }) + +apiRoot + .withProjectKey({ projectKey }) + .imageSearch() + .post({ + queryArgs: { + limit: 20, + }, + body: image, + headers: { + 'Content-Type': 'image/jpeg', + }, + }) + .execute() + .then((x) => { + /*...*/ + }) + + +// ----------------------------------------------------------------------- +// The sdk-client-v2 also has support for the old syntax +import { + createClient, + createHttpClient, + createAuthForClientCredentialsFlow, +} from '@commercetools/sdk-client-v2' +import { createApiBuilderFromCtpClient } from '@commercetools/ml-sdk') import fetch from 'node-fetch' const projectKey = 'some_project_key' -const authMiddleware = createAuthMiddlewareForClientCredentialsFlow({ - host: 'https://auth.europe-west1.gcp.commercetools.com/', +const authMiddleware = createAuthForClientCredentialsFlow({ + host: 'https://auth.europe-west1.gcp.commercetools.com', projectKey, credentials: { clientId: 'some_id', @@ -36,7 +131,7 @@ const authMiddleware = createAuthMiddlewareForClientCredentialsFlow({ fetch, }) -const httpMiddleware = createHttpMiddleware({ +const httpMiddleware = createHttpClient({ host: 'https://ml-eu.europe-west1.gcp.commercetools.com', fetch, }) @@ -45,7 +140,7 @@ const ctpClient = createClient({ middlewares: [authMiddleware, httpMiddleware], }) -const apiRoot: ApiRoot = createApiBuilderFromCtpClient(ctpClient) +const apiRoot = createApiBuilderFromCtpClient(ctpClient) apiRoot .withProjectKey({ projectKey }) diff --git a/packages/platform-sdk/README.md b/packages/platform-sdk/README.md index 03a3fd78f..165829b8d 100644 --- a/packages/platform-sdk/README.md +++ b/packages/platform-sdk/README.md @@ -1,35 +1,138 @@ # Typescript SDK for commercetools platform API -## Install +## Usage examples -```bash -npm install --save @commercetools/platform-sdk -``` +### Browser environment -### Browser +```html + + +``` ```html - ``` -### Usage example +See full usage example [here](https://github.com/commercetools/commercetools-sdk-typescript/blob/master/examples/browser/browser.html) + +### Node environment + +```bash +npm install --save @commercetools/sdk-client-v2 +npm install --save @commercetools/platform-sdk +``` ```ts -import { createAuthMiddlewareForClientCredentialsFlow } from '@commercetools/sdk-middleware-auth' -import { createHttpMiddleware } from '@commercetools/sdk-middleware-http' -import { createClient } from '@commercetools/sdk-client' +const { + ClientBuilder, + createAuthForClientCredentialsFlow, + createHttpClient, +} = require('@commercetools/sdk-client-v2') +const { createApiBuilderFromCtpClient } = require('@commercetools/platform-sdk') +const fetch = require('node-fetch') + +const projectKey = 'mc-project-key' +const authMiddlewareOptions = { + host: 'https://auth.europe-west1.gcp.commercetools.com', + projectKey, + credentials: { + clientId: 'mc-client-id', + clientSecret: 'mc-client-secrets', + }, + oauthUri: 'https://auth.europe-west1.gcp.commercetools.com', + scopes: [`manage_project:${projectKey}`], + fetch, +} + +const httpMiddlewareOptions = { + host: 'https://api.europe-west1.gcp.commercetools.com', + fetch, +} + +const client = new ClientBuilder() + .withProjectKey(projectKey) + .withMiddleware(createAuthForClientCredentialsFlow(authMiddlewareOptions)) + .withMiddleware(createHttpClient(httpMiddlewareOptions)) + .withUserAgentMiddleware() + .build() + +// or +const client = new ClientBuilder() + .withProjectKey(projectKey) + .withClientCredentialsFlow(authMiddlewareOptions) + .withHttpMiddleware(httpMiddlewareOptions) + .withUserAgentMiddleware() + .build() + +const apiRoot = createApiBuilderFromCtpClient(client) + +// calling the platform functions +// get project details +apiRoot + .withProjectKey({ + projectKey, + }) + .get() + .execute() + .then((x) => { + /*...*/ + }) + +// create a productType +apiRoot + .withProjectKey({ projectKey }) + .productTypes() + .post({ + body: { name: 'product-type-name', description: 'some description' }, + }) + .execute() + .then((x) => { + /*...*/ + }) + +// create a product +apiRoot + .withProjectKey({ projectKey }) + .products() + .post({ + body: { + name: { en: 'our-great-product-name' }, + productType: { + typeId: 'product-type', + id: 'some-product-type-id', + }, + slug: { en: 'some-slug' }, + }, + }) + .execute() + .then((x) => { + /*...*/ + }) + +// ----------------------------------------------------------------------- +// The sdk-client-v2 also has support for the old syntax import { - createApiBuilderFromCtpClient, - ApiRoot, -} from '@commercetools/platform-sdk' + createClient, + createHttpClient, + createAuthForClientCredentialsFlow, +} from '@commercetools/sdk-client-v2' +import { createApiBuilderFromCtpClient } from '@commercetools/platform-sdk' import fetch from 'node-fetch' const projectKey = 'some_project_key' -const authMiddleware = createAuthMiddlewareForClientCredentialsFlow({ +const authMiddleware = createAuthForClientCredentialsFlow({ host: 'https://auth.europe-west1.gcp.commercetools.com', projectKey, credentials: { @@ -39,7 +142,7 @@ const authMiddleware = createAuthMiddlewareForClientCredentialsFlow({ fetch, }) -const httpMiddleware = createHttpMiddleware({ +const httpMiddleware = createHttpClient({ host: 'https://api.europe-west1.gcp.commercetools.com', fetch, }) @@ -48,7 +151,7 @@ const ctpClient = createClient({ middlewares: [authMiddleware, httpMiddleware], }) -const apiRoot: ApiRoot = createApiBuilderFromCtpClient(ctpClient) +const apiRoot = createApiBuilderFromCtpClient(ctpClient) apiRoot .withProjectKey({ @@ -89,3 +192,5 @@ apiRoot /*...*/ }) ``` + +See full usage example [here](https://github.com/commercetools/commercetools-sdk-typescript/blob/master/examples/node/node.js) diff --git a/packages/sdk-client/README.md b/packages/sdk-client/README.md index 4001f3b84..d430005e8 100644 --- a/packages/sdk-client/README.md +++ b/packages/sdk-client/README.md @@ -1 +1,196 @@ -# `@commercetools/sdk-client-v2` +# Commercetools TypeScript SDK client. + +## Usage examples + +### Browser environment + +```html + + +``` + +```html + +``` + +See full usage example [here](https://github.com/commercetools/commercetools-sdk-typescript/blob/master/examples/browser/browser.html) + +### Node environment + +```bash +npm install --save @commercetools/sdk-client-v2 +npm install --save @commercetools/platform-sdk +``` + +```ts +const { + ClientBuilder, + createAuthForClientCredentialsFlow, + createHttpClient, +} = require('@commercetools/sdk-client-v2') +const { createApiBuilderFromCtpClient } = require('@commercetools/platform-sdk') +const fetch = require('node-fetch') + +const projectKey = 'mc-project-key' +const authMiddlewareOptions = { + host: 'https://auth.europe-west1.gcp.commercetools.com', + projectKey, + credentials: { + clientId: 'mc-client-id', + clientSecret: 'mc-client-secrets', + }, + oauthUri: 'https://auth.europe-west1.gcp.commercetools.com', + scopes: [`manage_project:${projectKey}`], + fetch, +} + +const httpMiddlewareOptions = { + host: 'https://api.europe-west1.gcp.commercetools.com', + fetch, +} + +const client = new ClientBuilder() + .withProjectKey(projectKey) + .withMiddleware(createAuthForClientCredentialsFlow(authMiddlewareOptions)) + .withMiddleware(createHttpClient(httpMiddlewareOptions)) + .withUserAgentMiddleware() + .build() + +// or +const client = new ClientBuilder() + .withProjectKey(projectKey) + .withClientCredentialsFlow(authMiddlewareOptions) + .withHttpMiddleware(httpMiddlewareOptions) + .withUserAgentMiddleware() + .build() + +const apiRoot = createApiBuilderFromCtpClient(client) + +// calling the platform functions +// get project details +apiRoot + .withProjectKey({ + projectKey, + }) + .get() + .execute() + .then((x) => { + /*...*/ + }) + +// create a productType +apiRoot + .withProjectKey({ projectKey }) + .productTypes() + .post({ + body: { name: 'product-type-name', description: 'some description' }, + }) + .execute() + .then((x) => { + /*...*/ + }) + +// create a product +apiRoot + .withProjectKey({ projectKey }) + .products() + .post({ + body: { + name: { en: 'our-great-product-name' }, + productType: { + typeId: 'product-type', + id: 'some-product-type-id', + }, + slug: { en: 'some-slug' }, + }, + }) + .execute() + .then((x) => { + /*...*/ + }) + +// ----------------------------------------------------------------------- +// The sdk-client-v2 also has support for the old syntax +import { + createClient, + createHttpClient, + createAuthForClientCredentialsFlow, +} from '@commercetools/sdk-client-v2' +import { createApiBuilderFromCtpClient } from '@commercetools/platform-sdk' +import fetch from 'node-fetch' + +const projectKey = 'some_project_key' + +const authMiddleware = createAuthForClientCredentialsFlow({ + host: 'https://auth.europe-west1.gcp.commercetools.com', + projectKey, + credentials: { + clientId: 'some_id', + clientSecret: 'some_secret', + }, + fetch, +}) + +const httpMiddleware = createHttpClient({ + host: 'https://api.europe-west1.gcp.commercetools.com', + fetch, +}) + +const ctpClient = createClient({ + middlewares: [authMiddleware, httpMiddleware], +}) + +const apiRoot = createApiBuilderFromCtpClient(ctpClient) + +apiRoot + .withProjectKey({ + projectKey, + }) + .get() + .execute() + .then((x) => { + /*...*/ + }) + +apiRoot + .withProjectKey({ projectKey }) + .productTypes() + .post({ + body: { name: 'product-type-name', description: 'some description' }, + }) + .execute() + .then((x) => { + /*...*/ + }) + +apiRoot + .withProjectKey({ projectKey }) + .products() + .post({ + body: { + name: { en: 'our-great-product-name' }, + productType: { + typeId: 'product-type', + id: 'some-product-type-id', + }, + slug: { en: 'some-slug' }, + }, + }) + .execute() + .then((x) => { + /*...*/ + }) +``` + +See full usage example [here](https://github.com/commercetools/commercetools-sdk-typescript/blob/master/examples/node/node.js)