chore(javascript): update READMEs (#3829)

algolia · Sep 25, 2024 · 847ce77 · 847ce77
1 parent 007fbe1
commit 847ce77
Show file tree

Hide file tree

Showing 12 changed files with 67 additions and 33 deletions.
diff --git 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 <head> of your website:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/algoliasearch/dist/algoliasearch.umd.min.js"></script>
+// for the full client
+<script src="https://cdn.jsdelivr.net/npm/algoliasearch/dist/algoliasearch.umd.js"></script>
+
+// for the lite client
+<script src="https://cdn.jsdelivr.net/npm/algoliasearch/dist/lite/builds/browser.umd.js"></script>
 ```
 
 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
@@ -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
@@ -32,45 +32,65 @@
 
 ## 💡 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 <head> of your website:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/algoliasearch/dist/{{packageName}}.umd.min.js"></script>
+{{#isAlgoliasearchClient}}
+// for the full client
+<script src="https://cdn.jsdelivr.net/npm/algoliasearch@{{{packageVersion}}}/dist/algoliasearch.umd.js"></script>
+
+// for the lite client
+<script src="https://cdn.jsdelivr.net/npm/algoliasearch@{{{packageVersion}}}/dist/lite/builds/browser.umd.js"></script>
+{{/isAlgoliasearchClient}}
+{{^isAlgoliasearchClient}}
+<script src="https://cdn.jsdelivr.net/npm/{{{npmPackageName}}}@{{{packageVersion}}}/dist/builds/browser.umd.js"></script>
+{{/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}}';
 
 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
@@ -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
@@ -1,9 +1,9 @@
 // {{{generationBanner}}}
 
-export type {{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}} = ReturnType<typeof create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}>;
+export type {{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}} = ReturnType<typeof create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}>;
 
 {{> 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
@@ -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
@@ -1,10 +1,10 @@
 // {{{generationBanner}}}
 
-export type {{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}} = ReturnType<typeof create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}>{{#nodeSearchHelpers}} & SearchClientNodeHelpers{{/nodeSearchHelpers}};
+export type {{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}} = ReturnType<typeof create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}>{{#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
@@ -1,9 +1,9 @@
 // {{{generationBanner}}}
 
-export type {{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}} = ReturnType<typeof create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}>;
+export type {{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}} = ReturnType<typeof create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}>;
 
 {{> 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
@@ -1,10 +1,10 @@
 // {{{generationBanner}}}
 
-export type {{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}} = ReturnType<typeof create{{#lambda.titlecase}}{{apiName}}{{/lambda.titlecase}}>{{#nodeSearchHelpers}} & SearchClientNodeHelpers{{/nodeSearchHelpers}};
+export type {{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}} = ReturnType<typeof create{{#lambda.titlecase}}{{clientName}}{{/lambda.titlecase}}>{{#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
@@ -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
@@ -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
@@ -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