@andev2005/movie-glu-sdk 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,167 @@
+# @andev2005/movie-glu-sdk
+
+SDK Node.js/TypeScript để gọi MovieGlu API (phim đang chiếu, phim sắp chiếu, rạp gần đây, chi tiết phim/rạp, lịch chiếu).
+
+## Cài đặt
+
+```bash
+pnpm add @andev2005/movie-glu-sdk
+```
+
+Hoặc:
+
+```bash
+npm i @andev2005/movie-glu-sdk
+```
+
+## Yêu cầu
+
+- Có `apiKey` của MovieGlu
+- Runtime có `fetch` (Node.js 18+) hoặc truyền `fetch` custom vào client
+
+## Sử dụng nhanh
+
+### TypeScript / JavaScript
+
+```ts
+import { createMovieGluClient } from '@andev2005/movie-glu-sdk';
+
+const movieGlu = createMovieGluClient({
+  apiKey: process.env.MOVIE_GLU_API_KEY!,
+});
+
+async function main() {
+  const nowShowing = await movieGlu.films.nowShowing({ limit: 10 });
+  console.log(nowShowing.films);
+
+  const comingSoon = await movieGlu.films.comingSoon({ limit: 10 });
+  console.log(comingSoon.films);
+
+  const cinemas = await movieGlu.cinemas.nearby({ limit: 5 });
+  console.log(cinemas.cinemas);
+}
+
+main().catch(console.error);
+```
+
+## Khởi tạo client
+
+```ts
+import { createMovieGluClient } from '@andev2005/movie-glu-sdk';
+
+const client = createMovieGluClient({
+  apiKey: 'your-api-key',
+  // Tuỳ chọn:
+  // baseUrl: 'https://api-gate2.movieglu.com',
+  // headers: { 'x-custom-header': 'value' },
+  // fetch: customFetch, // dùng khi môi trường không có global fetch
+});
+```
+
+## API hiện có
+
+### `films`
+
+```ts
+// Phim đang chiếu
+await client.films.nowShowing({ limit: 10 });
+
+// Phim sắp chiếu
+await client.films.comingSoon({ limit: 10 });
+
+// Chi tiết phim
+await client.films.details(12345);
+```
+
+### `cinemas`
+
+```ts
+// Rạp gần đây
+await client.cinemas.nearby({ limit: 10 });
+
+// Chi tiết rạp
+await client.cinemas.details(1001);
+
+// Lịch chiếu rạp theo ngày
+await client.cinemas.showTimes({
+  cinemaId: 1001,
+  date: '2026-02-25', // YYYY-MM-DD
+});
+```
+
+### Lọc lịch chiếu theo phim + sắp xếp
+
+```ts
+import { SORT_TYPE } from '@andev2005/movie-glu-sdk';
+
+await client.cinemas.showTimes({
+  cinemaId: 1001,
+  filmId: 12345,
+  date: '2026-02-25',
+  sort: SORT_TYPE.POPULARITY, // hoặc SORT_TYPE.ALPHABETICAL
+});
+```
+
+## Xử lý lỗi
+
+SDK sẽ throw `MovieGluError` nếu request thất bại (HTTP status không thành công).
+
+```ts
+import { MovieGluError } from '@andev2005/movie-glu-sdk';
+
+try {
+  const data = await client.films.nowShowing({ limit: 10 });
+  console.log(data);
+} catch (error) {
+  if (error instanceof MovieGluError) {
+    console.error('MovieGluError:', error.message);
+    console.error('status:', error.status);
+    console.error('details:', error.details);
+  } else {
+    console.error(error);
+  }
+}
+```
+
+## Validate tham số
+
+SDK có kiểm tra đầu vào và sẽ throw `TypeError` nếu:
+
+- `apiKey` bị thiếu/rỗng
+- `limit` không phải số nguyên dương
+- `id`, `cinemaId`, `filmId` không phải số nguyên dương
+- `date` không đúng định dạng `YYYY-MM-DD`
+
+## Utility build URL (tuỳ chọn)
+
+Nếu bạn chỉ muốn lấy URL endpoint (không gửi request), có thể dùng `MOVIE_GLU`:
+
+```ts
+import { MOVIE_GLU } from '@andev2005/movie-glu-sdk';
+
+const url = MOVIE_GLU.FILM_NOWSHOWING(10);
+console.log(url);
+```
+
+Các helper có sẵn:
+
+- `MOVIE_GLU.FILM_NOWSHOWING(limit)`
+- `MOVIE_GLU.CINEMA_NEARBY(limit)`
+- `MOVIE_GLU.FILMS_COMING_SOON(limit)`
+- `MOVIE_GLU.FILMS_DETAIL(id)`
+- `MOVIE_GLU.CINEMA_DETAIL(id)`
+- `MOVIE_GLU.CINEMA_SHOWTIME({ cinemaId, date, filmId?, sort? })`
+
+## Export chính
+
+- `createMovieGluClient`
+- `MOVIE_GLU`
+- `SORT_TYPE`
+- `MovieGluError`
+- Tất cả TypeScript types (`FilmDetailsResponse`, `CinemaShowTimesResponse`, ...)
+
+## Build package
+
+```bash
+npm run build
+```

package/dist/index.d.mts

@@ -22,12 +22,14 @@ type Client = {
     baseUrl: string;
     apiKey: string;
     headers?: Record<string, string>;
+    geolocation?: GeolocationInput;
     fetch?: FetchLike;
 };
 type MovieGluClientConfig = {
     apiKey: string;
     baseUrl?: string;
     headers?: Record<string, string>;
+    geolocation?: GeolocationInput;
     fetch?: FetchLike;
 };
 type CinemaShowTimesParams = {
@@ -39,6 +41,10 @@ type CinemaShowTimesParams = {
 type ListParams = {
     limit: number;
 };
+type GeolocationInput = string | UserLocation;
+type CinemasNearbyParams = ListParams;
+type CinemasNearbyRequestOptions = Pick<RequestOptions, 'headers'>;
+type CinemaDetailsRequestOptions = Pick<RequestOptions, 'headers'>;
 type MovieGluSdk = {
     films: {
         nowShowing(params: ListParams): Promise<FilmsNowShowing>;
@@ -46,8 +52,8 @@ type MovieGluSdk = {
         details(id: number): Promise<FilmDetailsResponse>;
     };
     cinemas: {
-        nearby(params: ListParams): Promise<CinemasNearbyResponse>;
-        details(id: number): Promise<CinemaDetailsResponse>;
+        nearby(params: CinemasNearbyParams, options?: CinemasNearbyRequestOptions): Promise<CinemasNearbyResponse>;
+        details(id: number, options?: CinemaDetailsRequestOptions): Promise<CinemaDetailsResponse>;
         showTimes(params: CinemaShowTimesParams): Promise<CinemaShowTimesResponse>;
     };
 };
@@ -310,4 +316,4 @@ declare const MOVIE_GLU: {
 };
 declare function createMovieGluClient(config: MovieGluClientConfig): MovieGluSdk;
 
-export { type AgeRating, type AlternateVersion, type Cast, type Cinema, type CinemaDetailsResponse, type CinemaShowTimesCinema, type CinemaShowTimesFilm, type CinemaShowTimesParams, type CinemaShowTimesResponse, type CinemasNearbyResponse, type Client, DEFAULT_BASE_URL, type Director, type FetchLike, type Film, type FilmComingSoon, type FilmDetailsResponse, type FilmImageSize, type FilmImages, type FilmShowTimesCinema, type FilmShowTimesFilm, type FilmShowTimesResponse, type FilmsComingSoonResponse, type FilmsNowShowing, type Genre, type KeyNumberObject, type ListParams, MOVIE_GLU, type MovieGluClientConfig, MovieGluError, type MovieGluSdk, type OtherTitles, type Poster, type Producer, type ReleaseDate, type RequestOptions, SORT_TYPE, type ShowDate, type Showings, type ShowtimeGroup, type ShowtimeTime, type SortType, type Status, type Still, type Trailer, type UserLocation, type Writer, createMovieGluClient };
+export { type AgeRating, type AlternateVersion, type Cast, type Cinema, type CinemaDetailsRequestOptions, type CinemaDetailsResponse, type CinemaShowTimesCinema, type CinemaShowTimesFilm, type CinemaShowTimesParams, type CinemaShowTimesResponse, type CinemasNearbyParams, type CinemasNearbyRequestOptions, type CinemasNearbyResponse, type Client, DEFAULT_BASE_URL, type Director, type FetchLike, type Film, type FilmComingSoon, type FilmDetailsResponse, type FilmImageSize, type FilmImages, type FilmShowTimesCinema, type FilmShowTimesFilm, type FilmShowTimesResponse, type FilmsComingSoonResponse, type FilmsNowShowing, type Genre, type GeolocationInput, type KeyNumberObject, type ListParams, MOVIE_GLU, type MovieGluClientConfig, MovieGluError, type MovieGluSdk, type OtherTitles, type Poster, type Producer, type ReleaseDate, type RequestOptions, SORT_TYPE, type ShowDate, type Showings, type ShowtimeGroup, type ShowtimeTime, type SortType, type Status, type Still, type Trailer, type UserLocation, type Writer, createMovieGluClient };

package/dist/index.d.ts

@@ -22,12 +22,14 @@ type Client = {
     baseUrl: string;
     apiKey: string;
     headers?: Record<string, string>;
+    geolocation?: GeolocationInput;
     fetch?: FetchLike;
 };
 type MovieGluClientConfig = {
     apiKey: string;
     baseUrl?: string;
     headers?: Record<string, string>;
+    geolocation?: GeolocationInput;
     fetch?: FetchLike;
 };
 type CinemaShowTimesParams = {
@@ -39,6 +41,10 @@ type CinemaShowTimesParams = {
 type ListParams = {
     limit: number;
 };
+type GeolocationInput = string | UserLocation;
+type CinemasNearbyParams = ListParams;
+type CinemasNearbyRequestOptions = Pick<RequestOptions, 'headers'>;
+type CinemaDetailsRequestOptions = Pick<RequestOptions, 'headers'>;
 type MovieGluSdk = {
     films: {
         nowShowing(params: ListParams): Promise<FilmsNowShowing>;
@@ -46,8 +52,8 @@ type MovieGluSdk = {
         details(id: number): Promise<FilmDetailsResponse>;
     };
     cinemas: {
-        nearby(params: ListParams): Promise<CinemasNearbyResponse>;
-        details(id: number): Promise<CinemaDetailsResponse>;
+        nearby(params: CinemasNearbyParams, options?: CinemasNearbyRequestOptions): Promise<CinemasNearbyResponse>;
+        details(id: number, options?: CinemaDetailsRequestOptions): Promise<CinemaDetailsResponse>;
         showTimes(params: CinemaShowTimesParams): Promise<CinemaShowTimesResponse>;
     };
 };
@@ -310,4 +316,4 @@ declare const MOVIE_GLU: {
 };
 declare function createMovieGluClient(config: MovieGluClientConfig): MovieGluSdk;
 
-export { type AgeRating, type AlternateVersion, type Cast, type Cinema, type CinemaDetailsResponse, type CinemaShowTimesCinema, type CinemaShowTimesFilm, type CinemaShowTimesParams, type CinemaShowTimesResponse, type CinemasNearbyResponse, type Client, DEFAULT_BASE_URL, type Director, type FetchLike, type Film, type FilmComingSoon, type FilmDetailsResponse, type FilmImageSize, type FilmImages, type FilmShowTimesCinema, type FilmShowTimesFilm, type FilmShowTimesResponse, type FilmsComingSoonResponse, type FilmsNowShowing, type Genre, type KeyNumberObject, type ListParams, MOVIE_GLU, type MovieGluClientConfig, MovieGluError, type MovieGluSdk, type OtherTitles, type Poster, type Producer, type ReleaseDate, type RequestOptions, SORT_TYPE, type ShowDate, type Showings, type ShowtimeGroup, type ShowtimeTime, type SortType, type Status, type Still, type Trailer, type UserLocation, type Writer, createMovieGluClient };
+export { type AgeRating, type AlternateVersion, type Cast, type Cinema, type CinemaDetailsRequestOptions, type CinemaDetailsResponse, type CinemaShowTimesCinema, type CinemaShowTimesFilm, type CinemaShowTimesParams, type CinemaShowTimesResponse, type CinemasNearbyParams, type CinemasNearbyRequestOptions, type CinemasNearbyResponse, type Client, DEFAULT_BASE_URL, type Director, type FetchLike, type Film, type FilmComingSoon, type FilmDetailsResponse, type FilmImageSize, type FilmImages, type FilmShowTimesCinema, type FilmShowTimesFilm, type FilmShowTimesResponse, type FilmsComingSoonResponse, type FilmsNowShowing, type Genre, type GeolocationInput, type KeyNumberObject, type ListParams, MOVIE_GLU, type MovieGluClientConfig, MovieGluError, type MovieGluSdk, type OtherTitles, type Poster, type Producer, type ReleaseDate, type RequestOptions, SORT_TYPE, type ShowDate, type Showings, type ShowtimeGroup, type ShowtimeTime, type SortType, type Status, type Still, type Trailer, type UserLocation, type Writer, createMovieGluClient };

package/dist/index.js

@@ -154,11 +154,28 @@ function assertPositiveInteger(value, name) {
     throw new TypeError(`${name} must be a positive integer`);
   }
 }
+function assertFiniteNumber(value, name) {
+  if (!Number.isFinite(value)) {
+    throw new TypeError(`${name} must be a finite number`);
+  }
+}
 function assertDateString(value, name) {
   if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
     throw new TypeError(`${name} must be in YYYY-MM-DD format`);
   }
 }
+function formatGeolocationHeader(geolocation) {
+  if (typeof geolocation === "string") {
+    const value = geolocation.trim();
+    if (!value) {
+      throw new TypeError("geolocation header must not be empty");
+    }
+    return value;
+  }
+  assertFiniteNumber(geolocation.lat, "geolocation.lat");
+  assertFiniteNumber(geolocation.lng, "geolocation.lng");
+  return `${geolocation.lat};${geolocation.lng}`;
+}
 function toListQuery(params) {
   assertPositiveInteger(params.limit, "limit");
   return { n: params.limit };
@@ -209,6 +226,7 @@ function createMovieGluClient(config) {
     baseUrl: normalizeBaseUrl(config.baseUrl ?? DEFAULT_BASE_URL),
     apiKey: config.apiKey,
     headers: config.headers,
+    geolocation: config.geolocation,
     fetch: config.fetch
   };
   return {
@@ -231,15 +249,33 @@ function createMovieGluClient(config) {
       }
     },
     cinemas: {
-      nearby(params) {
+      nearby(params, options) {
+        var _a;
+        const geolocationHeader = (_a = options == null ? void 0 : options.headers) == null ? void 0 : _a.geolocation;
+        const geolocation = geolocationHeader ?? client.geolocation;
+        if (!geolocation) {
+          throw new TypeError(
+            "geolocation header is required for cinemas.nearby. Pass nearby(..., { headers: { geolocation } }) or createMovieGluClient({ geolocation })."
+          );
+        }
         return httpRequest(client, ENDPOINT_PATH.CINEMA_NEARBY, {
-          queryParams: toListQuery(params)
+          queryParams: toListQuery(params),
+          headers: {
+            ...options == null ? void 0 : options.headers,
+            geolocation: formatGeolocationHeader(geolocation)
+          }
         });
       },
-      details(id) {
+      details(id, options) {
+        var _a;
         assertPositiveInteger(id, "id");
+        const geolocationHeader = (_a = options == null ? void 0 : options.headers) == null ? void 0 : _a.geolocation;
         return httpRequest(client, ENDPOINT_PATH.CINEMA_DETAIL, {
-          queryParams: { cinema_id: id }
+          queryParams: { cinema_id: id },
+          headers: {
+            ...options == null ? void 0 : options.headers,
+            ...geolocationHeader ? { geolocation: formatGeolocationHeader(geolocationHeader) } : {}
+          }
         });
       },
       showTimes(params) {

package/dist/index.mjs

@@ -125,11 +125,28 @@ function assertPositiveInteger(value, name) {
     throw new TypeError(`${name} must be a positive integer`);
   }
 }
+function assertFiniteNumber(value, name) {
+  if (!Number.isFinite(value)) {
+    throw new TypeError(`${name} must be a finite number`);
+  }
+}
 function assertDateString(value, name) {
   if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
     throw new TypeError(`${name} must be in YYYY-MM-DD format`);
   }
 }
+function formatGeolocationHeader(geolocation) {
+  if (typeof geolocation === "string") {
+    const value = geolocation.trim();
+    if (!value) {
+      throw new TypeError("geolocation header must not be empty");
+    }
+    return value;
+  }
+  assertFiniteNumber(geolocation.lat, "geolocation.lat");
+  assertFiniteNumber(geolocation.lng, "geolocation.lng");
+  return `${geolocation.lat};${geolocation.lng}`;
+}
 function toListQuery(params) {
   assertPositiveInteger(params.limit, "limit");
   return { n: params.limit };
@@ -180,6 +197,7 @@ function createMovieGluClient(config) {
     baseUrl: normalizeBaseUrl(config.baseUrl ?? DEFAULT_BASE_URL),
     apiKey: config.apiKey,
     headers: config.headers,
+    geolocation: config.geolocation,
     fetch: config.fetch
   };
   return {
@@ -202,15 +220,33 @@ function createMovieGluClient(config) {
       }
     },
     cinemas: {
-      nearby(params) {
+      nearby(params, options) {
+        var _a;
+        const geolocationHeader = (_a = options == null ? void 0 : options.headers) == null ? void 0 : _a.geolocation;
+        const geolocation = geolocationHeader ?? client.geolocation;
+        if (!geolocation) {
+          throw new TypeError(
+            "geolocation header is required for cinemas.nearby. Pass nearby(..., { headers: { geolocation } }) or createMovieGluClient({ geolocation })."
+          );
+        }
         return httpRequest(client, ENDPOINT_PATH.CINEMA_NEARBY, {
-          queryParams: toListQuery(params)
+          queryParams: toListQuery(params),
+          headers: {
+            ...options == null ? void 0 : options.headers,
+            geolocation: formatGeolocationHeader(geolocation)
+          }
         });
       },
-      details(id) {
+      details(id, options) {
+        var _a;
         assertPositiveInteger(id, "id");
+        const geolocationHeader = (_a = options == null ? void 0 : options.headers) == null ? void 0 : _a.geolocation;
         return httpRequest(client, ENDPOINT_PATH.CINEMA_DETAIL, {
-          queryParams: { cinema_id: id }
+          queryParams: { cinema_id: id },
+          headers: {
+            ...options == null ? void 0 : options.headers,
+            ...geolocationHeader ? { geolocation: formatGeolocationHeader(geolocationHeader) } : {}
+          }
         });
       },
       showTimes(params) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andev2005/movie-glu-sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/index.ts

@@ -1,12 +1,16 @@
 import { httpRequest } from './http';
 import type {
+  CinemaDetailsRequestOptions,
   CinemaShowTimesParams,
   CinemaShowTimesResponse,
   CinemaDetailsResponse,
+  CinemasNearbyParams,
+  CinemasNearbyRequestOptions,
   CinemasNearbyResponse,
   FilmDetailsResponse,
   FilmsComingSoonResponse,
   FilmsNowShowing,
+  GeolocationInput,
   ListParams,
   MovieGluClientConfig,
   MovieGluSdk,
@@ -52,12 +56,35 @@ function assertPositiveInteger(value: number, name: string): void {
   }
 }
 
+function assertFiniteNumber(value: number, name: string): void {
+  if (!Number.isFinite(value)) {
+    throw new TypeError(`${name} must be a finite number`);
+  }
+}
+
 function assertDateString(value: string, name: string): void {
   if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
     throw new TypeError(`${name} must be in YYYY-MM-DD format`);
   }
 }
 
+function formatGeolocationHeader(geolocation: GeolocationInput): string {
+  if (typeof geolocation === 'string') {
+    const value = geolocation.trim();
+    if (!value) {
+      throw new TypeError('geolocation header must not be empty');
+    }
+
+    return value;
+  }
+
+  assertFiniteNumber(geolocation.lat, 'geolocation.lat');
+  assertFiniteNumber(geolocation.lng, 'geolocation.lng');
+
+  // MovieGlu accepts geolocation in "lat;lng" format.
+  return `${geolocation.lat};${geolocation.lng}`;
+}
+
 function toListQuery(params: ListParams): { n: number } {
   assertPositiveInteger(params.limit, 'limit');
   return { n: params.limit };
@@ -119,6 +146,7 @@ export function createMovieGluClient(config: MovieGluClientConfig): MovieGluSdk
     baseUrl: normalizeBaseUrl(config.baseUrl ?? DEFAULT_BASE_URL),
     apiKey: config.apiKey,
     headers: config.headers,
+    geolocation: config.geolocation,
     fetch: config.fetch,
   };
 
@@ -142,15 +170,33 @@ export function createMovieGluClient(config: MovieGluClientConfig): MovieGluSdk
       },
     },
     cinemas: {
-      nearby(params: ListParams): Promise<CinemasNearbyResponse> {
+      nearby(params: CinemasNearbyParams, options?: CinemasNearbyRequestOptions): Promise<CinemasNearbyResponse> {
+        const geolocationHeader = options?.headers?.geolocation;
+        const geolocation = geolocationHeader ?? client.geolocation;
+        if (!geolocation) {
+          throw new TypeError(
+            'geolocation header is required for cinemas.nearby. Pass nearby(..., { headers: { geolocation } }) or createMovieGluClient({ geolocation }).',
+          );
+        }
+
         return httpRequest<CinemasNearbyResponse>(client, ENDPOINT_PATH.CINEMA_NEARBY, {
           queryParams: toListQuery(params),
+          headers: {
+            ...options?.headers,
+            geolocation: formatGeolocationHeader(geolocation),
+          },
         });
       },
-      details(id: number): Promise<CinemaDetailsResponse> {
+      details(id: number, options?: CinemaDetailsRequestOptions): Promise<CinemaDetailsResponse> {
         assertPositiveInteger(id, 'id');
+        const geolocationHeader = options?.headers?.geolocation;
+
         return httpRequest<CinemaDetailsResponse>(client, ENDPOINT_PATH.CINEMA_DETAIL, {
           queryParams: { cinema_id: id },
+          headers: {
+            ...options?.headers,
+            ...(geolocationHeader ? { geolocation: formatGeolocationHeader(geolocationHeader) } : {}),
+          },
         });
       },
       showTimes(params: CinemaShowTimesParams): Promise<CinemaShowTimesResponse> {

package/src/type.ts

@@ -27,6 +27,7 @@ export type Client = {
   baseUrl: string;
   apiKey: string;
   headers?: Record<string, string>;
+  geolocation?: GeolocationInput;
   fetch?: FetchLike;
 };
 
@@ -34,6 +35,7 @@ export type MovieGluClientConfig = {
   apiKey: string;
   baseUrl?: string;
   headers?: Record<string, string>;
+  geolocation?: GeolocationInput;
   fetch?: FetchLike;
 };
 
@@ -48,6 +50,13 @@ export type ListParams = {
   limit: number;
 };
 
+export type GeolocationInput = string | UserLocation;
+
+export type CinemasNearbyParams = ListParams;
+
+export type CinemasNearbyRequestOptions = Pick<RequestOptions, 'headers'>;
+export type CinemaDetailsRequestOptions = Pick<RequestOptions, 'headers'>;
+
 export type MovieGluSdk = {
   films: {
     nowShowing(params: ListParams): Promise<FilmsNowShowing>;
@@ -55,8 +64,8 @@ export type MovieGluSdk = {
     details(id: number): Promise<FilmDetailsResponse>;
   };
   cinemas: {
-    nearby(params: ListParams): Promise<CinemasNearbyResponse>;
-    details(id: number): Promise<CinemaDetailsResponse>;
+    nearby(params: CinemasNearbyParams, options?: CinemasNearbyRequestOptions): Promise<CinemasNearbyResponse>;
+    details(id: number, options?: CinemaDetailsRequestOptions): Promise<CinemaDetailsResponse>;
     showTimes(params: CinemaShowTimesParams): Promise<CinemaShowTimesResponse>;
   };
 };