1.1.0 • Published yesterday

@penta-b/penta-sdk

Licence

ISC

Version

1.1.0

Deps

Size

145.4 MB

Vulns

Weekly

Summary Dependency Versions

Penta SDK

Penta SDK is a JavaScript SDK designed to integrate maps, routing, and navigation into web or hybrid applications. It provides a simple, developer-friendly API to initialize maps, render routes, and handle navigation events seamlessly.

Features

Easy integration with OpenLayers-based maps.
Token-based authentication for secure API access.
Route calculation and rendering.
Configurable text-to-speech guidance Event callbacks for rerouting and navigation changes.
Works in web, Flutter, Ionic/Capacitor, and hybrid environments.

Installation & Usage

You can integrate Penta SDK in two ways:

Install via npm

Configure Authentication

You need to create a .npmrc file at the root of your project "the same directory where package.json is located" (If it deos not exist).

Declare the _authToken for @penta-b packages at .npmrc:

# For @penta-b packages
@penta-b:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=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

Note: The token may expire over time. If you encounter authentication issues, please update the token with a new valid one.

Run the following command to install:

npm install @penta-b/penta-sdk

Import and use in your project:

import { TokenManager, Navigation } from '@penta-b/penta-sdk';

// 1️⃣ Configure authentication
TokenManager.setConfig({
  PentaOrgId: pentaOrgId,
  PentaUserRole: pentaUserRole,
  token: token,
  locale: locale,
  baseURL: baseURL
})

// 2️⃣ Define your destination (Optional)
const distenationLocation = {
  name: "طريق 29 Fifth Sector,New Capital",
  longitude: 31.743205835,
  latitude: 30.010779961
}

// 3️⃣ Initialize navigation
const navigation = new Navigation({
  applicationName: applicationName,
  target: 'container',          // HTML container ID
  distenationLocation: undefined, // Or pass the actual destination object
  directNavigate: false,
  onArrive: this.onArrive
})

// 4️⃣ Render navigation UI
navigation.render()

Install via CDN by `<script>` tag

Get the sdk.bundle.js file and place it in the same directory as your app.
Add the script to your HTML file:

<html>

  <head>
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <script type="text/javascript" src="/sdk.bundle.js"></script>
  </head>

  <body style="display: flex; flex-direction: column; width: 100%; height: 100vh; margin: 0; padding: 0;">
    <div id="navigation" style="flex: 1;"></div>

    <script type="text/javascript">
      // 1️⃣ Configure authentication
      pentaSDK.TokenManager.setConfig({
        PentaOrgId: 'PentaOrgId',
        PentaUserRole: 'PentaUserRole',
        token: 'token',
        locale: 'locale',
        baseURL: 'baseURL'
      })


      // 2️⃣ Define your destination (Optional)
      const distenationLocation = {
        name: 'طريق 29 Fifth Sector, New Capital',
        longitude: 31.743205835,
        latitude: 30.010779961
      }

      // 3️⃣ Initialize navigation
      const navigation = new pentaSDK.Navigation({
        applicationName: 'applicationName',
        target: 'navigation',        // HTML container ID
        distenationLocation: null,   // Or pass the actual destination object
        directNavigate: false,
        onArrive: () => {
        // Your logic code as a Callback when arrived.
          }
      })

      // 4️⃣ Render navigation UI
      navigation.render()

      </script>
  </body>

</html>

External Location Usage

You can use external location provider instead of the navite location provider.

Set the initial location using external provider in two different ways:

Using NPM (Recommended for modern projects)

import { externalLocation, useExternalLocation } from '@penta-b/penta-sdk';

const externalLocationInstance = new externalLocation();
useExternalLocation(externalLocationInstance);
externalLocationInstance.updateLocation([31.6929005, 30.0277597]);

Sets the current location as a start point (longitude, latitude).

Using CDN by `<script>` tag

const externalLocationInstance = new pentaSDK.externalLocation();
pentaSDK.useExternalLocation(externalLocationInstance);
externalLocationInstance.updateLocation([31.6929005, 30.0277597]);

Sets the current location as a start point (longitude, latitude).

Update current location dynamically:

externalLocationInstance.updateLocation([19.29046186247058, 27.28119575513182])

Updates the current location (longitude, latitude).

Return to track your location by use default location provider :

externalLocationInstance.useDefaultLocation();

Note:

target should be the HTML container ID where the map/navigation will be rendered.

distenationLocation The coordinates for the destination. By sending this paramter with valid location, the SDK will be start from Directions step automatically. (Default is null).

directNavigate determines whether navigation starts immediately without user confirmation, Only when the distenationLocation is not null (Default is false).

onArrive is an optional callback executed when the destination is reached.

Authentication

The SDK uses token-based authentication. You must request a valid token from your backend or Penta API services before using any secured endpoints.

Authentication Parameters:

Constant Name	Description
`pentaOrgId`	Your organization ID
`pentaUserRole`	Your user role
`token`	Authorization token
`locale`	Language code (`'en'`, `'ar'`)
`baseURL`	Base URL of the backend
`applicationName`	Application name identifier

Important: You must update these values with your actual credentials and configuration before running or building the app, or it may fail to authenticate.

Supported Platforms

Web browsers
Ionic apps (Android & iOS)
Flutter apps (windows, Android & iOS)
Android apps (Via webview)
IOS apps (Via webview)

API Reference

Full API documentation coming soon!