Skip to main content

GL Dynamic Image

Version: 1.0.7
Package: @gift-card-market/gl-dynamic-image
Last Updated: June 5, 2026

A React library (with Web Component support) for rendering a dynamic business preview image using a business ID and partner JWT.

Table of Contents​

Features​

  • Render dynamic preview data from partner API by businessId + searchProvider.
  • Display business name, rating, review count, image, and provider-specific visual style.
  • Expose imperative methods via ref (reset, refresh).
  • Expose global controller helpers (reset, refresh) from package entry.
  • Emit custom DOM events for success/error handling (gl:previewLoaded, gl:error).
  • Responsive layout with auto-scaling behavior.
  • Publish bundled stylesheet at dist/style.css.

Requirements​

  • React: ^18.2.0 or compatible.
  • Install runtime dependencies in your app:
npm install react react-dom react-tooltip
  • Node 16+ is recommended.

Installation​

1. Configure GitHub Packages (if package is still hosted on GitHub)​

From package.json:

"publishConfig": {
  "registry": "https://npm.pkg.github.com/@Gift-Card-Market",
  "access": "public"
}

Configure npm auth:

  1. Create a GitHub Personal Access Token with read:packages.
  2. Run login:
npm login --registry=https://npm.pkg.github.com --scope=@gift-card-market

Or add to .npmrc:

@gift-card-market:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

2. Install package​

npm install @gift-card-market/gl-dynamic-image

3. Import CSS​

import '@gift-card-market/gl-dynamic-image/dist/style.css';

Quick Start with React​

Basic Example​

import { useRef } from 'react';
import { GlDynamicImage, type GlDynamicImageHandle } from '@gift-card-market/gl-dynamic-image';
import '@gift-card-market/gl-dynamic-image/dist/style.css';

export default function DynamicImagePage() {
  const ref = useRef<GlDynamicImageHandle | null>(null);

  return (
    <div>
      <button onClick={() => ref.current?.reset()}>Reset</button>
      <button onClick={() => ref.current?.refresh()}>Refresh</button>

      <GlDynamicImage
        ref={ref}
        data={{
          jwt: 'YOUR_JWT_TOKEN',
          businessId: 'YOUR_BUSINESS_ID',
          environment: 'production',
          searchProvider: 'yelp',
        }}
      />
    </div>
  );
}

Using Named Exports (without ref)​

import { reset, refresh } from '@gift-card-market/gl-dynamic-image';

reset();
refresh();

If no component instance is mounted, these calls do nothing.

Detailed API​

Props GlDynamicImage​

PropTypeRequiredDescription
dataGlDynamicImageData✅Input configuration for authentication, business lookup, and environment.

GlDynamicImageData​

Defined in src/types/gl-dynamic-image.ts:

export interface GlDynamicImageProps {
  data: {
    jwt: string;
    businessId: string;
    environment?: string;
    searchProvider?: string;
  };
}

Field behavior in current implementation:

  • jwt (required): Partner JWT used as Authorization: Bearer <token>.
  • businessId (required): Business identifier for lookup.
  • environment (optional): defaults to production if omitted.
  • searchProvider (optional): defaults to yelp in fetch flow if omitted.

Validation behavior:

  • If jwt or businessId is missing, component renders: Invalid token or business id.

GlDynamicImageHandle (ref API)​

Exposed by src/gl-dynamic-image.tsx:

export type GlDynamicImageHandle = {
  reset: () => void;
  refresh: () => void;
};

Methods:

  • reset(): clear loaded preview state.
  • refresh(): fetch latest business data with current businessId and searchProvider.

GlDynamicImageEvents (Event bus)​

Emitted on document:

  • gl:previewLoaded
    • Fired when API response is successful.
    • event.detail: { businessId, metadata }
  • gl:error
    • Fired when request fails or required params are missing.
    • event.detail: { error }

Example listener:

useEffect(() => {
  const onPreviewLoaded = (event: Event) => {
    const detail = (event as CustomEvent).detail;
    console.log('Preview loaded:', detail);
  };

  const onError = (event: Event) => {
    const detail = (event as CustomEvent).detail;
    console.error('Dynamic image error:', detail);
  };

  document.addEventListener('gl:previewLoaded', onPreviewLoaded);
  document.addEventListener('gl:error', onError);

  return () => {
    document.removeEventListener('gl:previewLoaded', onPreviewLoaded);
    document.removeEventListener('gl:error', onError);
  };
}, []);

Styling & Customization​

  • Import dist/style.css to apply component styles.
  • The preview automatically scales content based on container size.
  • You can wrap the component in your own container and control width/height externally.

Web Component Usage​

The package includes browser build support in this repository (src/web.ts, build:vite).

General embedding pattern:

<link rel="stylesheet" href="/path/to/@gift-card-market/gl-dynamic-image/dist/style.css" />
<script src="/path/to/@gift-card-market/gl-dynamic-image/dist/browser/gl-dynamic-image.global.js"></script>

Check your actual built output names under dist/ in your consuming environment.

API Endpoint​

Current fetch call:

  • Method: GET
  • Path: /partner/web-component/api/v1/business-detail
  • Query:
    • searchProvider
    • businessId
  • Headers:
    • Authorization: Bearer <jwt>
    • Content-Type: application/json

Base domain is resolved from environment:

  • production -> https://partnerapi.giftcardmarket.com
  • staging -> https://stagepartnerapi.giftcardmarket.com
  • qa -> https://qapartnerapi.giftcardmarket.com
  • development -> https://devpartnerapi.giftcardmarket.com

Development & Build​

Common scripts from package.json:

npm run dev
npm run build
npm run preview

Build command detail:

tsup
npx tailwindcss -i ./src/styles.css -o ./dist/style.css --minify

Project Layout (Summary)​

src/
  components/
  lib/
    controller.ts
  types/
    gl-dynamic-image.ts
    form-handle.ts
  utils/
    apiDomain.ts
  gl-dynamic-image.tsx
  index.ts
  styles.css
  web.ts

Troubleshooting​

IssueSuggestion
Invalid token or business idCheck data.jwt and data.businessId.
No preview loadedVerify JWT validity, API availability, and network/CORS.
No stylesEnsure dist/style.css is imported.
Unknown environment errorUse one of: production, staging, qa, development.

Contact​

Gift Card Market Development Team

License: ISC © Gift Card Market