From 847ce7753f9bd80d2b91b96580a017525137ef8b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Vannicatte?= Date: Wed, 25 Sep 2024 11:55:19 +0200 Subject: [PATCH] chore(javascript): update READMEs (#3829) --- .../algoliasearch-client-javascript/README.md | 8 +++- .../codegen/AlgoliaJavascriptGenerator.java | 18 +++++++-- templates/javascript/clients/README.mustache | 40 ++++++++++++++----- .../javascript/clients/api-single.mustache | 2 +- .../clients/client/builds/browser.mustache | 4 +- .../clients/client/builds/definition.mustache | 10 ++--- .../clients/client/builds/fetch.mustache | 4 +- .../clients/client/builds/liteNode.mustache | 4 +- .../clients/client/builds/node.mustache | 4 +- .../javascript/clients/rollup.config.mustache | 2 +- .../javascript/clients/tsup.config.mustache | 2 +- templates/kotlin/README.mustache | 2 +- 12 files changed, 67 insertions(+), 33 deletions(-) diff --git a/clients/algoliasearch-client-javascript/README.md b/clients/algoliasearch-client-javascript/README.md index a3f52d4afe..33e9f9c912 100644 --- a/clients/algoliasearch-client-javascript/README.md +++ b/clients/algoliasearch-client-javascript/README.md @@ -47,7 +47,11 @@ Without a package manager Add the following JavaScript snippet to the of your website: ```html - +// for the full client + + +// for the lite client + ``` You can now import the Algolia API client in your project and play with it. @@ -63,7 +67,7 @@ import { liteClient } from 'algoliasearch/lite'; const client = liteClient('YOUR_APP_ID', 'YOUR_API_KEY'); ``` -For full documentation, visit the **[Algolia JavaScript API Client](https://www.algolia.com/doc/libraries/javascript/)**. +For full documentation, visit the **[Algolia JavaScript API Client](https://www.algolia.com/doc/libraries/javascript/v5/methods/search/)**. ## ❓ Troubleshooting diff --git a/generators/src/main/java/com/algolia/codegen/AlgoliaJavascriptGenerator.java b/generators/src/main/java/com/algolia/codegen/AlgoliaJavascriptGenerator.java index 4ed4856663..79bad9b646 100644 --- a/generators/src/main/java/com/algolia/codegen/AlgoliaJavascriptGenerator.java +++ b/generators/src/main/java/com/algolia/codegen/AlgoliaJavascriptGenerator.java @@ -148,14 +148,23 @@ public static String getPackageName(String client) throws ConfigException { /** Set default generator options */ private void setDefaultGeneratorOptions() { - String apiName = CLIENT + Helpers.API_SUFFIX; + String clientName = CLIENT + Helpers.API_SUFFIX; String packageName = getPackageName((String) additionalProperties.get("client")); - additionalProperties.put("apiName", apiName); + additionalProperties.put("apiName", CLIENT); + additionalProperties.put("clientName", clientName); additionalProperties.put("algoliaAgent", Helpers.capitalize(CLIENT)); additionalProperties.put("isSearchClient", CLIENT.equals("search") || isAlgoliasearchClient); additionalProperties.put("isIngestionClient", CLIENT.equals("ingestion")); additionalProperties.put("isAlgoliasearchClient", isAlgoliasearchClient); + additionalProperties.put( + "isAvailableInAlgoliasearch", + CLIENT.equals("search") || + CLIENT.equals("recommend") || + CLIENT.equals("personalization") || + CLIENT.equals("analytics") || + CLIENT.equals("abtesting") + ); additionalProperties.put("packageVersion", Helpers.getPackageJsonVersion(packageName)); additionalProperties.put("packageName", packageName); additionalProperties.put("npmPackageName", isAlgoliasearchClient ? packageName : "@algolia/" + packageName); @@ -170,8 +179,9 @@ private void setDefaultGeneratorOptions() { additionalProperties.put("recommendVersion", Helpers.getPackageJsonVersion("recommend")); // Files used to generate the `lite` client - apiName = "lite" + Helpers.API_SUFFIX; - additionalProperties.put("apiName", apiName); + clientName = "lite" + Helpers.API_SUFFIX; + additionalProperties.put("apiName", "search"); + additionalProperties.put("clientName", clientName); additionalProperties.put("algoliaAgent", "Lite"); } } diff --git a/templates/javascript/clients/README.mustache b/templates/javascript/clients/README.mustache index 6d28116090..5c1a25f2a0 100644 --- a/templates/javascript/clients/README.mustache +++ b/templates/javascript/clients/README.mustache @@ -32,31 +32,51 @@ ## 💡 Getting Started -To get started, you first need to install {{npmPackageName}} (or any other available API client package). +{{#isAvailableInAlgoliasearch}} +> [!TIP] +> This API client is already a dependency of [the algoliasearch client](https://www.npmjs.com/package/algoliasearch), you don't need to manually install `{{{npmPackageName}}}` if you already have `algoliasearch` installed. +{{/isAvailableInAlgoliasearch}} +To get started, you first need to install {{npmPackageName}} (or any other available API client package). All of our clients comes with type definition, and are available for both browser and node environments. +### With a package manager + + ```bash -yarn add {{npmPackageName}} +yarn add {{npmPackageName}}@{{{packageVersion}}} +# or +npm install {{npmPackageName}}@{{{packageVersion}}} # or -npm install {{npmPackageName}} +pnpm add {{npmPackageName}}@{{{packageVersion}}} ``` -Without a package manager +### Without a package manager Add the following JavaScript snippet to the of your website: ```html - +{{#isAlgoliasearchClient}} +// for the full client + + +// for the lite client + +{{/isAlgoliasearchClient}} +{{^isAlgoliasearchClient}} + +{{/isAlgoliasearchClient}} ``` +### Usage + You can now import the Algolia API client in your project and play with it. ```js {{^isAlgoliasearchClient}} -import { {{apiName}} } from '{{npmPackageName}}'; +import { {{clientName}} } from '{{npmPackageName}}'; -const client = {{apiName}}('YOUR_APP_ID', 'YOUR_API_KEY'); +const client = {{clientName}}('YOUR_APP_ID', 'YOUR_API_KEY'); {{/isAlgoliasearchClient}} {{#isAlgoliasearchClient}} import { algoliasearch } from '{{npmPackageName}}'; @@ -64,13 +84,13 @@ import { algoliasearch } from '{{npmPackageName}}'; const client = algoliasearch('YOUR_APP_ID', 'YOUR_API_KEY'); // or with the lite client -import { {{apiName}} } from '{{npmPackageName}}/lite'; +import { {{clientName}} } from '{{npmPackageName}}/lite'; -const client = {{apiName}}('YOUR_APP_ID', 'YOUR_API_KEY'); +const client = {{clientName}}('YOUR_APP_ID', 'YOUR_API_KEY'); {{/isAlgoliasearchClient}} ``` -For full documentation, visit the **[Algolia JavaScript API Client](https://www.algolia.com/doc/libraries/javascript/)**. +For full documentation, visit the **[Algolia JavaScript API Client](https://www.algolia.com/doc/libraries/javascript/v5/methods/{{#lambda.kebabcase}}{{apiName}}{{/lambda.kebabcase}}/)**. ## ❓ Troubleshooting diff --git a/templates/javascript/clients/api-single.mustache b/templates/javascript/clients/api-single.mustache index 009c970509..34b77e4e12 100644 --- a/templates/javascript/clients/api-single.mustache +++ b/templates/javascript/clients/api-single.mustache @@ -13,7 +13,7 @@ export const apiClientVersion = '{{packageVersion}}'; {{/isIngestionClient}} // eslint-disable-next-line @typescript-eslint/explicit-function-return-type -export function create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}({ +export function create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}({ appId: appIdOption, apiKey: apiKeyOption, authMode, diff --git a/templates/javascript/clients/client/builds/browser.mustache b/templates/javascript/clients/client/builds/browser.mustache index 7b7dc3109c..675766aec7 100644 --- a/templates/javascript/clients/client/builds/browser.mustache +++ b/templates/javascript/clients/client/builds/browser.mustache @@ -1,9 +1,9 @@ // {{{generationBanner}}} -export type {{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}} = ReturnType; +export type {{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}} = ReturnType; {{> client/builds/definition}} - return create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}({ + return create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}({ appId, apiKey,{{#hasRegionalHost}}region,{{/hasRegionalHost}} timeouts: { diff --git a/templates/javascript/clients/client/builds/definition.mustache b/templates/javascript/clients/client/builds/definition.mustache index ad06d653b0..377af27981 100644 --- a/templates/javascript/clients/client/builds/definition.mustache +++ b/templates/javascript/clients/client/builds/definition.mustache @@ -3,10 +3,10 @@ import { createHttpRequester } from '@algolia/requester-node-http'; import { createFetchRequester } from '@algolia/requester-fetch'; import { createNullLogger, createMemoryCache, createFallbackableCache, createBrowserLocalStorageCache, createNullCache, ClientOptions, serializeQueryParameters, DEFAULT_CONNECT_TIMEOUT_NODE, DEFAULT_READ_TIMEOUT_NODE, DEFAULT_WRITE_TIMEOUT_NODE, DEFAULT_CONNECT_TIMEOUT_BROWSER, DEFAULT_READ_TIMEOUT_BROWSER, DEFAULT_WRITE_TIMEOUT_BROWSER } from '@algolia/client-common'; -import { create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}, apiClientVersion } from '../src/{{apiName}}'; +import { create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}, apiClientVersion } from '../src/{{clientName}}'; {{#hasRegionalHost}} -import { Region, REGIONS } from '../src/{{apiName}}'; +import { Region, REGIONS } from '../src/{{clientName}}'; {{/hasRegionalHost}} {{! We don't use `export *` to prevent exposing the factory, to avoid confusion for the user }} @@ -20,7 +20,7 @@ export { isScheduleTrigger, isSubscriptionTrigger, {{/isIngestionClient}} -} from '../src/{{apiName}}'; +} from '../src/{{clientName}}'; export * from '../model'; {{#isSearchClient}} @@ -32,11 +32,11 @@ import {createHmac} from 'node:crypto'; {{/nodeSearchHelpers}} // eslint-disable-next-line @typescript-eslint/explicit-function-return-type -export function {{apiName}}( +export function {{clientName}}( appId: string, apiKey: string,{{#hasRegionalHost}}region{{#fallbackToAliasHost}}?{{/fallbackToAliasHost}}: Region,{{/hasRegionalHost}} options?: ClientOptions -): {{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}} { +): {{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}} { if (!appId || typeof appId !== 'string') { throw new Error("`appId` is missing."); } diff --git a/templates/javascript/clients/client/builds/fetch.mustache b/templates/javascript/clients/client/builds/fetch.mustache index 37184ead23..4f13bd222b 100644 --- a/templates/javascript/clients/client/builds/fetch.mustache +++ b/templates/javascript/clients/client/builds/fetch.mustache @@ -1,10 +1,10 @@ // {{{generationBanner}}} -export type {{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}} = ReturnType{{#nodeSearchHelpers}} & SearchClientNodeHelpers{{/nodeSearchHelpers}}; +export type {{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}} = ReturnType{{#nodeSearchHelpers}} & SearchClientNodeHelpers{{/nodeSearchHelpers}}; {{> client/builds/definition}} return { - ...create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}({ + ...create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}({ appId, apiKey,{{#hasRegionalHost}}region,{{/hasRegionalHost}} timeouts: { diff --git a/templates/javascript/clients/client/builds/liteNode.mustache b/templates/javascript/clients/client/builds/liteNode.mustache index e98d62f3e4..c9ed291a21 100644 --- a/templates/javascript/clients/client/builds/liteNode.mustache +++ b/templates/javascript/clients/client/builds/liteNode.mustache @@ -1,9 +1,9 @@ // {{{generationBanner}}} -export type {{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}} = ReturnType; +export type {{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}} = ReturnType; {{> client/builds/definition}} - return create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}({ + return create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}({ appId, apiKey,{{#hasRegionalHost}}region,{{/hasRegionalHost}} timeouts: { diff --git a/templates/javascript/clients/client/builds/node.mustache b/templates/javascript/clients/client/builds/node.mustache index 3773ace508..279ae6f6fc 100644 --- a/templates/javascript/clients/client/builds/node.mustache +++ b/templates/javascript/clients/client/builds/node.mustache @@ -1,10 +1,10 @@ // {{{generationBanner}}} -export type {{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}} = ReturnType{{#nodeSearchHelpers}} & SearchClientNodeHelpers{{/nodeSearchHelpers}}; +export type {{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}} = ReturnType{{#nodeSearchHelpers}} & SearchClientNodeHelpers{{/nodeSearchHelpers}}; {{> client/builds/definition}} return { - ...create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}({ + ...create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}({ appId, apiKey,{{#hasRegionalHost}}region,{{/hasRegionalHost}} timeouts: { diff --git a/templates/javascript/clients/rollup.config.mustache b/templates/javascript/clients/rollup.config.mustache index 61c674432c..727635c703 100644 --- a/templates/javascript/clients/rollup.config.mustache +++ b/templates/javascript/clients/rollup.config.mustache @@ -18,7 +18,7 @@ export default [ ['lite']: 'lite', {{/isAlgoliasearchClient}} {{^isAlgoliasearchClient}} - ['{{apiName}}']: '{{apiName}}', + ['{{clientName}}']: '{{clientName}}', {{/isAlgoliasearchClient}} }, }, diff --git a/templates/javascript/clients/tsup.config.mustache b/templates/javascript/clients/tsup.config.mustache index 48031a8a50..450cc1a613 100644 --- a/templates/javascript/clients/tsup.config.mustache +++ b/templates/javascript/clients/tsup.config.mustache @@ -67,7 +67,7 @@ const nodeConfigs: Options[] = [ const browserOptions: Options = { ...getBaseBrowserOptions(pkg, __dirname), {{^isAlgoliasearchClient}} - globalName: '{{apiName}}', + globalName: '{{clientName}}', {{/isAlgoliasearchClient}} {{#isAlgoliasearchClient}} globalName: 'lite', diff --git a/templates/kotlin/README.mustache b/templates/kotlin/README.mustache index 00329f17d5..07aae83862 100644 --- a/templates/kotlin/README.mustache +++ b/templates/kotlin/README.mustache @@ -114,7 +114,7 @@ var response = client.search( println(response) ``` -For full documentation, visit the **[Algolia Kotlin API Client](https://www.algolia.com/doc/libraries/kotlin/)**. +For full documentation, visit the **[Algolia Kotlin API Client](https://www.algolia.com/doc/libraries/kotlin/v3/)**. ## ❓ Troubleshooting