Skip to content

Commit

Permalink
Added V2 client support and included auth helper (#13)
Browse files Browse the repository at this point in the history 
* Added V2 client support and included auth helper

* Improved the README after feedback

* Fixed some grammatical errors
  • Loading branch information
@cgalvan
cgalvan authored Oct 17, 2024
1 parent c4d7fd6 commit 36e5819
Show file tree
Hide file tree
Showing 8 changed files with 7,952 additions and 2,755 deletions.
18 changes: 18 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# 1.0.2

### ✨ Features and improvements

- Improved bundling
- Simplified import URL in usage documentation

# 1.0.1

### ✨ Features and improvements

- Updated documentation with usage examples

# 1.0.0

### ✨ Features and improvements

- Initial release
121 changes: 90 additions & 31 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Amazon Location JavaScript Client

This is a distribution of the [AWS SDK for JavaScript v3](https://github.com/aws/aws-sdk-js-v3) containing the [Amazon Location client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-location/) and [credential providers](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/) intended for use in browsers.
This is a distribution of the [AWS SDK for JavaScript v3](https://github.com/aws/aws-sdk-js-v3) containing the standalone [Maps](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-amzn-geomaps-client/), [Places](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-amzn-geoplaces-client/), and [Routes](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-amzn-georoutes-client/) SDKs, the [Location SDK](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-location/), our [authentication helper](https://github.com/aws-geospatial/amazon-location-utilities-auth-helper-js), and [credential providers](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/) intended for use in browsers.

## Installation

Expand All @@ -9,70 +9,129 @@ This is a distribution of the [AWS SDK for JavaScript v3](https://github.com/aws
Add the script to an HTML file for usage directly in the browser.

```html
<script src="https://www.unpkg.com/@aws/amazon-location-client@1"></script>
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-client@1"></script>
```

### Usage with modules

We recommend using [@aws-sdk/client-location](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-location/) and [@aws-sdk/credential-providers](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/) from the [AWS SDK for JavaScript v3](https://github.com/aws/aws-sdk-js-v3) if possible to get the full benefit of the modularized AWS SDK.
We recommend using [@amzn/geomaps-client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-amzn-geomaps-client/), [@amzn/geoplaces-client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-amzn-geoplaces-client/), [@amzn/georoutes-client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-amzn-georoutes-client/), [@aws-sdk/client-location](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-location/) and [@aws-sdk/credential-providers](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/) from the [AWS SDK for JavaScript v3](https://github.com/aws/aws-sdk-js-v3) if possible to get the full benefit of the modularized AWS SDK.

## Usage

All functions are available under the `amazonLocationClient` global.

This example uses the Amazon Location Client to make a request that authenticates using Amazon Cognito.
### API Key

This example uses the Amazon Location Client to make a request that authenticates using an API key.

```html
<!-- Import the Amazon Location Client -->
<script src="https://www.unpkg.com/@aws/amazon-location-client@1"></script>
<script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-client@1"></script>
```

```javascript
const identityPoolId = "<Identity Pool ID>";
// Create an authentication helper instance using an API key
const authHelper = await amazonLocationClient.withAPIKey("<API Key>");

const client = new amazonLocationClient.LocationClient({
const client = new amazonLocationClient.GeoRoutesClient({
region: "<Region>", // Region containing Amazon Location resource
...authHelper.getClientConfig(), // Provides credentials obtained via API key
});
const input = { ... };
const command = new amazonLocationClient.routes.CalculateRoutesCommand(input);
const response = await client.send(command);
```

### Cognito

This example uses the Amazon Location Client to make a request that authenticates using Amazon Cognito. For more information on setting up Amazon Cognito identity pools, please refer to this [guide](https://docs.aws.amazon.com/location/latest/developerguide/authenticating-using-cognito.html).

```javascript
// Create an authentication helper instance using credentials from Amazon Cognito
const authHelper = await amazonLocationClient.withIdentityPoolId("<Identity Pool ID>");

const client = new amazonLocationClient.GeoRoutesClient({
region: "<Region>", // region containing Amazon Location resources
credentials: amazonLocationClient.fromCognitoIdentityPool({
clientConfig: {
region: "<Region>", // region containing the Amazon Cognito Identity Pool
},
identityPoolId
})
...authHelper.getClientConfig(), // Provides credentials obtained via Amazon Cognito
});
const input = { ... };
const command = new amazonLocationClient.CalculateRouteCommand(input);
const command = new amazonLocationClient.routes.CalculateRoutesCommand(input);
const response = await client.send(command);
```

We can further simplify the authentication process by introducing the [Amazon Location authentication helper utility library](https://github.com/aws-geospatial/amazon-location-utilities-auth-helper-js)
## Documentation

```html
<!-- Import the Amazon Location Client -->
<script src="https://www.unpkg.com/@aws/amazon-location-client@1"></script>
<!-- Import the Amazon Location authentication helper utility library -->
<script src="https://www.unpkg.com/@aws/amazon-location-utilities-auth-helper@1"></script>
The APIs for the different client SDKs are grouped separately.

### [@amzn/geomaps-client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-amzn-geomaps-client/)

The standalone Maps SDK commands are grouped into a `maps` namespace. For example:

```javascript
// Create an authentication helper instance using an API key
const authHelper = await amazonLocationClient.withAPIKey("<API Key>");

const client = new amazonLocationClient.GeoMapsClient({
region: "<Region>", // Region containing Amazon Location resource
...authHelper.getClientConfig(), // Provides credentials obtained via API key
});
const input = { ... };
const command = new amazonLocationClient.maps.GetStaticMapCommand(input);
const response = await client.send(command);
```

### [@amzn/geoplaces-client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-amzn-geoplaces-client/)

The standalone Places SDK commands are grouped into a `places` namespace. For example:

```javascript
// Create an authentication helper instance using credentials from Cognito
const authHelper = await amazonLocationAuthHelper.withIdentityPoolId("<Identity Pool ID>");
// Create an authentication helper instance using an API key
const authHelper = await amazonLocationClient.withAPIKey("<API Key>");

const client = new amazonLocationClient.LocationClient({
const client = new amazonLocationClient.GeoPlacesClient({
region: "<Region>", // Region containing Amazon Location resource
...authHelper.getLocationClientConfig(), // Provides credentials obtained via Amazon Cognito
...authHelper.getClientConfig(), // Provides credentials obtained via API key
});
const input = { ... };
const command = new amazonLocationClient.CalculateRouteCommand(input);
const command = new amazonLocationClient.places.GetPlaceCommand(input);
const response = await client.send(command);
```

## Documentation
### [@amzn/georoutes-client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-amzn-georoutes-client/)

The standalone Routes SDK commands are grouped into a `routes` namespace. For example:

Refer to [@aws-sdk/client-location](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-location/) and [@aws-sdk/credential-providers](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/) for documentation.
```javascript
// Create an authentication helper instance using an API key
const authHelper = await amazonLocationClient.withAPIKey("<API Key>");

Prefix the class from the `@aws-sdk/client-location` documentation with `amazonLocationClient.` when using this Amazon Location Client library (or destructure imports to match).
const client = new amazonLocationClient.GeoRoutesClient({
region: "<Region>", // Region containing Amazon Location resource
...authHelper.getClientConfig(), // Provides credentials obtained via API key
});
const input = { ... };
const command = new amazonLocationClient.routes.CalculateRoutesCommand(input);
const response = await client.send(command);
```

### [@aws-sdk/client-location](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-location/)

The Location SDK commands are under the top-level namespace. For example:

```javascript
// Create an authentication helper instance using an API key
const authHelper = await amazonLocationClient.withAPIKey("<API Key>");

const client = new amazonLocationClient.LocationClient({
region: "<Region>", // Region containing Amazon Location resource
...authHelper.getClientConfig(), // Provides credentials obtained via API key
});
const input = { ... };
const command = new amazonLocationClient.ListGeofencesCommand(input);
const response = await client.send(command);
```

- For example, `const command = new CalculateRouteCommand(input);` corresponds to `const command = new amazonLocationClient.CalculateRouteCommand(input);`
Refer to [@amzn/geomaps-client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-amzn-geomaps-client/), [@amzn/geoplaces-client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-amzn-geoplaces-client/), [@amzn/georoutes-client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-amzn-georoutes-client/), [@aws-sdk/client-location](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-location/) and [@aws-sdk/credential-providers](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/) for further documentation.

## Getting Help

Expand All @@ -85,11 +144,11 @@ If you have a support plan with [AWS Support](https://aws.amazon.com/premiumsupp

Please make sure to check out the following resources before opening an issue:

- Our [Changelog](https://github.com/aws-geospatial/amazon-location-client-js/blob/master/CHANGELOG.md) for recent changes.
- Our [Changelog](CHANGELOG.md) for recent changes.

## Contributing

We welcome community contributions and pull requests. See [CONTRIBUTING.md](https://github.com/aws-geospatial/amazon-location-client-js/blob/master/CONTRIBUTING.md) for information on how to set up a development environment and submit code.
We welcome community contributions and pull requests. See [CONTRIBUTING.md](CONTRIBUTING.md) for information on how to set up a development environment and submit code.

## License

Expand Down
Loading

0 comments on commit 36e5819

Please sign in to comment.