# @penta-b/penta-sdk

> a new sdk

Latest version **1.1.0** (published 2026-09-23) · ISC license · 0 weekly downloads

## Install

```sh
npm install @penta-b/penta-sdk
pnpm add @penta-b/penta-sdk
yarn add @penta-b/penta-sdk
bun add @penta-b/penta-sdk
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no esm support; large bundle.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2026-09-23 |
| First published | 2025-08-18 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 11 |
| Unpacked size | 145.4 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Penta-b Company |
| Maintainers | pentab, mohamedayman74 |
| Keywords | Penta-b, Penta-SDK, Maps, Navigation |

## Links

- npm: https://www.npmjs.com/package/@penta-b/penta-sdk
- npm.io page: https://npm.io/package/@penta-b/penta-sdk

## Dependencies (11)

- [wkt](https://npm.io/package/wkt.md) ^0.1.1
- [ol-ext](https://npm.io/package/ol-ext.md) ^4.0.21
- [i18next](https://npm.io/package/i18next.md) ^24.2.0
- [@turf/turf](https://npm.io/package/@turf/turf.md) ^7.0.0
- [raw-loader](https://npm.io/package/raw-loader.md) ^4.0.2
- [i18next-icu](https://npm.io/package/i18next-icu.md) ^2.3.0
- [@capacitor/core](https://npm.io/package/@capacitor/core.md) ^6.2.0
- [libtashkeel-wasm](https://npm.io/package/libtashkeel-wasm.md) ^1.6.4
- [intl-messageformat](https://npm.io/package/intl-messageformat.md) ^10.7.16
- [@capacitor/geolocation](https://npm.io/package/@capacitor/geolocation.md) ^6.1.0
- [@ionic-native/geolocation](https://npm.io/package/@ionic-native/geolocation.md) ^5.36.0

## Alternatives

- [express-promise-router](https://npm.io/package/express-promise-router.md) — 736.1K weekly downloads
- [next-usequerystate](https://npm.io/package/next-usequerystate.md) — 29.8K weekly downloads
- [@bitkyc08/opencodex](https://npm.io/package/@bitkyc08/opencodex.md) — 4.6K weekly downloads
- [lynkr](https://npm.io/package/lynkr.md) — 575 weekly downloads
- [baremetal.js](https://npm.io/package/baremetal.js.md) — 42 weekly downloads

## Recent versions

- 1.1.0 (latest) — 2026-09-23
- 1.0.0 — 2025-08-18

## README

# 🗺️ Penta SDK  

[![npm version](https://img.shields.io/npm/v/@penta-b/penta-sdk.svg)](https://www.npmjs.com/package/@penta-b/penta-sdk)
![JavaScript](https://img.shields.io/badge/JavaScript-ES6%2B-yellow)
![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)
![Ionic](https://img.shields.io/badge/Ionic-Android%20%7C%20iOS-blueviolet)
![Flutter](https://img.shields.io/badge/Flutter-Android%20%7C%20iOS%20%7C%20Windows-02569B?logo=flutter)
![iOS](https://img.shields.io/badge/iOS%20Native-Supported(Via%20%20Webview)-lightgrey?logo=apple)
![Android](https://img.shields.io/badge/Android%20Native-Supported(Via%20%20Webview)-green?logo=android)
![Web](https://img.shields.io/badge/Web%20%20Apps-Supported(Via%20%20Javascript)-orange?logo=google-chrome)

**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:

#### 1️⃣ 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`:

```ini
# 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:

```bash
npm install @penta-b/penta-sdk
```
- 📦 Import and use in your project:

```js
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()
```

#### 2️⃣ 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:

```js
<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)

```js
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

```java
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:
```java
externalLocationInstance.updateLocation([19.29046186247058, 27.28119575513182])
```
> Updates the current location (`longitude`, `latitude`).

- Return to track your location by use default location provider :

```java
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!  

---

## 👤 Ownership & Copyright  

**Penta SDK** is developed and maintained by **Penta-B**.  

© 2025 **Penta-B**. All rights reserved.  

You are free to use this SDK under the terms of the **MIT License** (see [LICENSE](./LICENSE) for details).  

---
## 📞 Support  

For issues or feature requests, please contact:  

📧 **info@penta-b.com**  
🌐 **https://penta-b.com**

---
_Source: https://npm.io/package/@penta-b/penta-sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._