@screenly/edge-apps 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Screenly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# @screenly/edge-apps
+
+A TypeScript library for interfacing with the Screenly Edge Apps API.
+
+## Installation
+
+> [!IMPORTANT]
+> This package requires [Bun](https://bun.sh). The `edge-apps-scripts` CLI will not work with `npm` or `node` at this time.
+
+```bash
+bun add @screenly/edge-apps
+```
+
+### Local Development Setup
+
+When developing Edge Apps locally using the library from this repository, you should link the package.
+
+First, in the root of this repository:
+
+```bash
+bun link
+```
+
+Then in your Edge App directory:
+
+```bash
+cd /path/to/your-edge-app
+bun link @screenly/edge-apps
+```
+
+To unlink the package when you're done with local development, run the following in your Edge App directory:
+
+```bash
+bun install --force
+```
+
+Then in the root of this repository:
+
+```bash
+bun unlink
+```
+
+## Quick Start
+
+```typescript
+import { setupTheme, signalReady, getMetadata } from '@screenly/edge-apps'
+
+setupTheme()
+const metadata = getMetadata()
+signalReady()
+```
+
+## Core Functions
+
+### Theme & Branding
+
+- `setupTheme()` - Apply theme colors to CSS custom properties
+- `setupBrandingLogo()` - Fetch and process branding logo
+- `setupBranding()` - Setup complete branding (colors and logo)
+
+### Settings
+
+- `getSettings()` - Get all settings
+- `getSetting<T>(key)` - Get specific setting with type safety
+- `getSettingWithDefault<T>(key, default)` - Get setting with fallback
+- `signalReady()` - Signal app is ready for display
+
+### Metadata
+
+- `getMetadata()` - Get all screen metadata
+- `getScreenName()`, `getHostname()`, `getLocation()`, `getScreenlyVersion()`, `getTags()`, `hasTag(tag)`, `getFormattedCoordinates()`
+- `getHardware()` - Get hardware type as `Hardware` enum (`Anywhere`, `RaspberryPi`, or `ScreenlyPlayerMax`)
+
+### Location & Localization
+
+- `getTimeZone()` - Get timezone from GPS coordinates
+- `getLocale()` - Get locale from location
+- `formatCoordinates(coords)` - Format coordinates as string
+- `formatLocalizedDate(date, locale)` - Format date for locale
+- `formatTime(date, locale, timezone)` - Format time for locale
+- `getLocalizedDayNames(locale)` - Get day names for locale
+- `getLocalizedMonthNames(locale)` - Get month names for locale
+- `detectHourFormat(locale)` - Detect 12h/24h format for locale
+
+### UTM Tracking
+
+- `addUTMParams(url, params?)` - Add UTM parameters to URL
+- `addUTMParamsIf(url, enabled, params?)` - Conditionally add UTM parameters
+
+## Edge Apps Scripts CLI
+
+This package provides the `edge-apps-scripts` CLI tool for running shared development commands across all Edge Apps. It includes centralized ESLint configuration to avoid duplication.
+
+### Available Commands
+
+#### Development Server
+
+Start the Vite development server with mock data from `screenly.yml` and `mock-data.yml`:
+
+```bash
+bun run dev
+```
+
+#### Building
+
+```bash
+bun run build
+```
+
+#### Linting
+
+To lint your Edge App:
+
+```bash
+bun run lint
+```
+
+To lint and automatically fix issues:
+
+```bash
+bun run lint -- --fix
+```
+
+#### Type Checking
+
+Run TypeScript type checking:
+
+```bash
+bun run type-check
+```
+
+### Command-Line Utilities for Edge Apps
+
+- This library provides utilities to help with common Edge App tasks.
+- The CLI uses the shared ESLint configuration from `@screenly/edge-apps`, so you don't need to maintain your own `eslint.config.ts`
+- The build commands assume your Edge App has `index.html` as the entry point
+- Build output will be generated in the `dist/` directory
+
+It is recommended to add the following scripts to your Edge App's `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "edge-apps-scripts dev",
+    "build": "edge-apps-scripts build",
+    "build:dev": "edge-apps-scripts build:dev",
+    "lint": "edge-apps-scripts lint",
+    "type-check": "edge-apps-scripts type-check",
+    "deploy": "bun run build && screenly edge-app deploy --path=dist/"
+  }
+}
+```
+
+> [!NOTE]
+> Feel free to customize the scripts as needed for your Edge App. You could also define your own configs like `eslint.config.ts`, `tsconfig.json`, or `vite.config.ts` if you need more control.
+
+## Testing
+
+```typescript
+import { setupScreenlyMock, resetScreenlyMock } from '@screenly/edge-apps/test'
+
+beforeEach(() => {
+  setupScreenlyMock({ screen_name: 'Test Screen' }, { theme: 'dark' })
+})
+
+afterEach(() => {
+  resetScreenlyMock()
+})
+```
+
+## Types
+
+```typescript
+import type {
+  Hardware,
+  ScreenlyMetadata,
+  ScreenlySettings,
+  ScreenlyObject,
+  ThemeColors,
+  BrandingConfig,
+  UTMParams,
+} from '@screenly/edge-apps'
+```
+
+## Development
+
+```bash
+bun install      # Install dependencies
+bun test         # Run tests
+bun run build    # Build library
+```

package/bin/edge-apps-scripts.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env bun
+/**
+ * Edge Apps Scripts CLI
+ * Wrapper around build tools for Edge Apps
+ */
+
+import { run } from '../scripts/cli'
+
+run()

package/configs/playwright.ts

@@ -0,0 +1,44 @@
+import path from 'path'
+import { createRequire } from 'module'
+import { fileURLToPath } from 'url'
+
+const PREVIEW_PORT = 4173
+
+// Resolve @playwright/test from the calling app's node_modules, not the library's
+const appRequire = createRequire(path.join(process.cwd(), 'package.json'))
+
+let defineConfig: typeof import('@playwright/test').defineConfig
+let devices: typeof import('@playwright/test').devices
+
+try {
+  const playwrightTest = appRequire('@playwright/test')
+  defineConfig = playwrightTest.defineConfig
+  devices = playwrightTest.devices
+} catch {
+  throw new Error(
+    "Failed to resolve '@playwright/test' from the application. " +
+      "Please install it in your app (e.g. 'bun add -d @playwright/test') " +
+      'and try again.',
+  )
+}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const libraryRoot = path.dirname(__dirname)
+const viteBin = path.resolve(libraryRoot, 'node_modules', '.bin', 'vite')
+const viteConfig = path.resolve(libraryRoot, 'vite.config.ts')
+
+export default defineConfig({
+  testDir: path.join(process.cwd(), 'e2e'),
+  use: {
+    baseURL: `http://localhost:${PREVIEW_PORT}`,
+    ...devices['Desktop Chrome'],
+  },
+  webServer: {
+    // Invoke vite directly so it always runs from the library's node_modules,
+    // ensuring packages like tailwindcss resolve correctly regardless of the app.
+    command: `"${viteBin}" build --config "${viteConfig}" && "${viteBin}" preview --config "${viteConfig}" --port ${PREVIEW_PORT} --strictPort`,
+    cwd: process.cwd(),
+    port: PREVIEW_PORT,
+    reuseExistingServer: false,
+  },
+})

package/eslint.config.ts

@@ -0,0 +1,43 @@
+import eslint from '@eslint/js'
+import { defineConfig, globalIgnores } from 'eslint/config'
+import tseslint from 'typescript-eslint'
+
+export default defineConfig(
+  eslint.configs.recommended,
+  tseslint.configs.recommended,
+  globalIgnores([
+    'dist/',
+    'node_modules/',
+    'static/js/',
+    'build/',
+    'tailwind.config.js',
+  ]),
+  {
+    rules: {
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+        },
+      ],
+      'complexity': ['error', { max: 20 }],
+      'max-lines-per-function': ['error', {
+        max: 70,
+        skipBlankLines: true,
+        skipComments: true,
+      }],
+      'max-lines': ['error', {
+        max: 300,
+        skipBlankLines: true,
+        skipComments: true,
+      }],
+    },
+  },
+  {
+    files: ['**/*.test.ts', '**/*.spec.ts'],
+    rules: {
+      'max-lines': 'off',
+    },
+  },
+)

package/package.json

@@ -0,0 +1,111 @@
+{
+  "name": "@screenly/edge-apps",
+  "version": "0.0.1",
+  "description": "A TypeScript library for interfacing with Screenly Edge Apps API",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "edge-apps-scripts": "./bin/edge-apps-scripts.ts"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./components": {
+      "import": "./dist/components/index.js",
+      "types": "./dist/components/index.d.ts"
+    },
+    "./core": {
+      "import": "./dist/core/index.js",
+      "types": "./dist/core/index.d.ts"
+    },
+    "./styles": "./src/styles/index.css",
+    "./styles/*": "./src/styles/*",
+    "./utils": {
+      "import": "./dist/utils/index.js",
+      "types": "./dist/utils/index.d.ts"
+    },
+    "./types": {
+      "import": "./dist/types/index.js",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./test": {
+      "import": "./dist/test/index.js",
+      "types": "./dist/test/index.d.ts"
+    },
+    "./test/screenshots": {
+      "import": "./dist/test/screenshots.js",
+      "types": "./dist/test/screenshots.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "configs",
+    "scripts",
+    "eslint.config.ts",
+    "src/styles",
+    "src/assets"
+  ],
+  "scripts": {
+    "prebuild": "bun run type-check",
+    "build": "bun build:types && bun run copy:assets",
+    "build:types": "tsc",
+    "copy:assets": "bun run scripts/copy-assets.ts",
+    "test": "bun test --parallel",
+    "test:unit": "bun test --parallel",
+    "test:coverage": "bun test --coverage --parallel",
+    "lint": "eslint . --fix",
+    "format": "prettier --write src/ scripts/ vite-plugins/ README.md index.html",
+    "format:check": "prettier --check src/ scripts/ vite-plugins/ README.md index.html",
+    "type-check": "tsc --noEmit"
+  },
+  "prettier": "./.prettierrc.json",
+  "keywords": [
+    "screenly",
+    "edge-apps",
+    "digital-signage"
+  ],
+  "author": "Screenly",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@photostructure/tz-lookup": "^11.5.0",
+    "dayjs": "^1.11.19",
+    "@tailwindcss/vite": "^4.2.1",
+    "country-locale-map": "^1.9.12",
+    "offline-geocode-city": "^1.0.2",
+    "panic-overlay": "^1.0.51",
+    "sharp": "^0.34.5",
+    "tailwindcss": "^4.2.1"
+  },
+  "peerDependencies": {
+    "@playwright/test": "^1.58.0"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/bun": "^1.3.10",
+    "@types/jsdom": "^28.0.0",
+    "@types/node": "^25.4.0",
+    "@types/sharp": "^0.32.0",
+    "bun-types": "^1.3.10",
+    "eslint": "^10.0.3",
+    "jiti": "^2.6.1",
+    "jsdom": "^28.1.0",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.57.0",
+    "vite": "^7.3.1",
+    "yaml": "^2.8.2"
+  }
+}