@xapp/stentor-service-google-places 1.70.0

package/README.md

@@ -0,0 +1,96 @@
+# Google Places Service
+
+Service for integrating with Google Places API, built on Stentor's FetchService.
+
+## Installation
+
+```bash
+npm install @xapp/stentor-service-google-places
+```
+
+## Usage
+
+### Basic Setup with API Key
+
+```typescript
+import { GooglePlacesService } from "@xapp/stentor-service-google-places";
+
+const service = new GooglePlacesService({
+    apiKey: "your-google-places-api-key"
+});
+```
+
+### Setup with Authentication Function
+
+```typescript
+import { GooglePlacesService } from "@xapp/stentor-service-google-places";
+
+const service = new GooglePlacesService({
+    authenticate: async () => {
+        // Your authentication logic here
+        return { apiKey: await getApiKeyFromSomewhere() };
+    }
+});
+```
+
+### Get Place Details
+
+```typescript
+// Get basic place details
+const placeDetails = await service.getPlaceDetails("ChIJN1t_tDeuEmsRUsoyG83frY4");
+
+// Get specific fields only
+const placeDetails = await service.getPlaceDetails(
+    "ChIJN1t_tDeuEmsRUsoyG83frY4",
+    ["name", "formatted_address", "geometry", "photos"]
+);
+```
+
+## API Reference
+
+### GooglePlacesService
+
+#### Constructor Options
+
+- `apiKey?: string` - Google Places API key
+- `authenticate?: () => Promise<{ apiKey: string }>` - Function that returns API key
+- `urlBase?: string` - Custom API base URL (defaults to Google Places API)
+
+#### Methods
+
+##### `getPlaceDetails(placeId: string, fields?: string[]): Promise<GooglePlaceDetails>`
+
+Retrieves detailed information about a place.
+
+**Parameters:**
+- `placeId` - The unique identifier for a place
+- `fields` - Optional array of fields to return (reduces API cost)
+
+**Returns:** Promise resolving to place details
+
+**Available Fields:**
+- Basic: `place_id`, `name`, `formatted_address`, `geometry`
+- Contact: `formatted_phone_number`, `international_phone_number`, `website`
+- Atmosphere: `photos`, `rating`, `user_ratings_total`, `reviews`, `price_level`
+- Details: `opening_hours`, `business_status`, `types`, `vicinity`
+
+## Error Handling
+
+The service throws descriptive errors for:
+- Missing API key or authentication function
+- HTTP errors (4xx/5xx status codes)
+- Google Places API errors (INVALID_REQUEST, OVER_QUERY_LIMIT, etc.)
+
+## Types
+
+All TypeScript interfaces are exported for use in your application:
+
+```typescript
+import { 
+    GooglePlaceDetails, 
+    GooglePlaceDetailsResponse,
+    GooglePlacesGeometry,
+    GooglePlacesPhoto,
+    GooglePlacesReview
+} from "@xapp/stentor-service-google-places";
+```

package/lib/GooglePlacesService.d.ts

@@ -0,0 +1,23 @@
+import { FetchService } from "stentor-service-fetch";
+import { GooglePlaceDetails } from "./models";
+export interface GooglePlacesAuthenticator {
+    (): Promise<{
+        apiKey: string;
+    }>;
+}
+export interface GooglePlacesServiceOptions {
+    apiKey?: string;
+    authenticate?: GooglePlacesAuthenticator;
+    urlBase?: string;
+}
+export interface GooglePlacesServiceInterface {
+    getPlaceDetails(placeId: string, fields?: string[]): Promise<GooglePlaceDetails>;
+}
+export declare class GooglePlacesService extends FetchService implements GooglePlacesServiceInterface {
+    private readonly apiKey?;
+    private readonly authenticate?;
+    private readonly urlBase;
+    constructor(options: GooglePlacesServiceOptions);
+    getPlaceDetails(placeId: string, fields?: string[]): Promise<GooglePlaceDetails>;
+    private getApiKey;
+}

package/lib/GooglePlacesService.js

@@ -0,0 +1,68 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GooglePlacesService = void 0;
+/*! Copyright (c) 2025, XAPPmedia */
+const stentor_constants_1 = require("stentor-constants");
+const stentor_service_fetch_1 = require("stentor-service-fetch");
+class GooglePlacesService extends stentor_service_fetch_1.FetchService {
+    constructor(options) {
+        super();
+        if (!options.apiKey && !options.authenticate) {
+            throw new Error("GooglePlacesService requires either apiKey or authenticate function");
+        }
+        this.apiKey = options.apiKey;
+        this.authenticate = options.authenticate;
+        this.urlBase = options.urlBase || "https://maps.googleapis.com/maps/api/place/details/json";
+    }
+    getPlaceDetails(placeId, fields) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const apiKey = yield this.getApiKey();
+            const url = new URL(this.urlBase);
+            url.searchParams.set("place_id", placeId);
+            url.searchParams.set("key", apiKey);
+            if (fields && fields.length > 0) {
+                url.searchParams.set("fields", fields.join(","));
+            }
+            let status;
+            return this.fetch(url.toString(), {
+                method: "GET"
+            })
+                .then(response => {
+                status = response.status;
+                if (status >= stentor_constants_1.HTTP_400_BAD_REQUEST) {
+                    throw new Error(`Google Places API request to ${url.toString()} returned status code ${status}`);
+                }
+                return response.json();
+            })
+                .then((response) => {
+                if (response.status !== "OK") {
+                    throw new Error(`Google Places API error: ${response.status}${response.error_message ? ` - ${response.error_message}` : ""}`);
+                }
+                return response.result;
+            });
+        });
+    }
+    getApiKey() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.apiKey) {
+                return this.apiKey;
+            }
+            if (this.authenticate) {
+                const auth = yield this.authenticate();
+                return auth.apiKey;
+            }
+            throw new Error("No API key available");
+        });
+    }
+}
+exports.GooglePlacesService = GooglePlacesService;
+//# sourceMappingURL=GooglePlacesService.js.map

package/lib/GooglePlacesService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GooglePlacesService.js","sourceRoot":"","sources":["../src/GooglePlacesService.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,oCAAoC;AACpC,yDAAyD;AACzD,iEAAqD;AAiBrD,MAAa,mBAAoB,SAAQ,oCAAY;IAKjD,YAAY,OAAmC;QAC3C,KAAK,EAAE,CAAC;QAER,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;QAC3F,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;QACzC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,yDAAyD,CAAC;IAChG,CAAC;IAEK,eAAe,CAAC,OAAe,EAAE,MAAiB;;YACpD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;YAEtC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAClC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;YAC1C,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAEpC,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC9B,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YACrD,CAAC;YAED,IAAI,MAAc,CAAC;YAEnB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE;gBAC9B,MAAM,EAAE,KAAK;aAChB,CAAC;iBACG,IAAI,CAAC,QAAQ,CAAC,EAAE;gBACb,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;gBAEzB,IAAI,MAAM,IAAI,wCAAoB,EAAE,CAAC;oBACjC,MAAM,IAAI,KAAK,CAAC,gCAAgC,GAAG,CAAC,QAAQ,EAAE,yBAAyB,MAAM,EAAE,CAAC,CAAC;gBACrG,CAAC;gBAED,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;YAC3B,CAAC,CAAC;iBACD,IAAI,CAAqB,CAAC,QAAoC,EAAE,EAAE;gBAC/D,IAAI,QAAQ,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;oBAC3B,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAClI,CAAC;gBAED,OAAO,QAAQ,CAAC,MAAM,CAAC;YAC3B,CAAC,CAAC,CAAC;QACX,CAAC;KAAA;IAEa,SAAS;;YACnB,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBACd,OAAO,IAAI,CAAC,MAAM,CAAC;YACvB,CAAC;YAED,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;gBACpB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;gBACvC,OAAO,IAAI,CAAC,MAAM,CAAC;YACvB,CAAC;YAED,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;QAC5C,CAAC;KAAA;CACJ;AA/DD,kDA+DC"}

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+/*! Copyright (c) 2025, XAPPmedia */
+export * from "./GooglePlacesService";
+export * from "./models";

package/lib/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/*! Copyright (c) 2025, XAPPmedia */
+__exportStar(require("./GooglePlacesService"), exports);
+__exportStar(require("./models"), exports);
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oCAAoC;AACpC,wDAAsC;AACtC,2CAAyB"}

package/lib/models.d.ts

@@ -0,0 +1,79 @@
+/*! Copyright (c) 2025, XAPPmedia */
+export interface GooglePlacesGeometry {
+    location: {
+        lat: number;
+        lng: number;
+    };
+    viewport: {
+        northeast: {
+            lat: number;
+            lng: number;
+        };
+        southwest: {
+            lat: number;
+            lng: number;
+        };
+    };
+}
+export interface GooglePlacesAddressComponent {
+    long_name: string;
+    short_name: string;
+    types: string[];
+}
+export interface GooglePlacesPhoto {
+    height: number;
+    html_attributions: string[];
+    photo_reference: string;
+    width: number;
+}
+export interface GooglePlacesOpeningHours {
+    open_now: boolean;
+    periods?: Array<{
+        close?: {
+            day: number;
+            time: string;
+        };
+        open: {
+            day: number;
+            time: string;
+        };
+    }>;
+    weekday_text?: string[];
+}
+export interface GooglePlacesReview {
+    author_name: string;
+    author_url?: string;
+    language: string;
+    profile_photo_url: string;
+    rating: number;
+    relative_time_description: string;
+    text: string;
+    time: number;
+}
+export interface GooglePlaceDetails {
+    place_id: string;
+    name?: string;
+    formatted_address?: string;
+    formatted_phone_number?: string;
+    international_phone_number?: string;
+    geometry?: GooglePlacesGeometry;
+    address_components?: GooglePlacesAddressComponent[];
+    photos?: GooglePlacesPhoto[];
+    rating?: number;
+    user_ratings_total?: number;
+    reviews?: GooglePlacesReview[];
+    opening_hours?: GooglePlacesOpeningHours;
+    website?: string;
+    url?: string;
+    business_status?: string;
+    price_level?: number;
+    types?: string[];
+    vicinity?: string;
+}
+export interface GooglePlaceDetailsResponse {
+    result: GooglePlaceDetails;
+    status: string;
+    error_message?: string;
+    info_messages?: string[];
+    html_attributions: string[];
+}

package/lib/models.js

@@ -0,0 +1,4 @@
+"use strict";
+/*! Copyright (c) 2025, XAPPmedia */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=models.js.map

package/lib/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":";AAAA,oCAAoC"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@xapp/stentor-service-google-places",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.70.0",
+  "description": "Service to integrate with Google Places API",
+  "types": "lib/index",
+  "main": "lib/index",
+  "files": [
+    "lib"
+  ],
+  "engines": {
+    "node": "^10 || ^12 || ^14 || ^16 || ^18 || ^20 || ^22"
+  },
+  "devDependencies": {
+    "@types/chai": "5.2.2",
+    "@xapp/config": "0.2.3",
+    "chai": "4.5.0",
+    "mocha": "11.7.1",
+    "stentor-logger": "1.61.10",
+    "stentor-models": "1.61.9",
+    "stentor-service-fetch": "1.61.9",
+    "ts-node": "10.9.2",
+    "typescript": "5.9.2"
+  },
+  "peerDependencies": {
+    "stentor-constants": "1.x",
+    "stentor-logger": "1.x",
+    "stentor-models": "1.x",
+    "stentor-service-fetch": "1.x"
+  },
+  "scripts": {
+    "build": "tsc -d true -p .",
+    "clean": "rm -rf ./lib/*",
+    "test": "exit 0"
+  },
+  "gitHead": "55afa51e5b8d8875d3e5f6ef23e57d4687dce2b8"
+}