Merge branch 'master' into patch-2025.01.2

.github/ISSUE_TEMPLATE/----channel-request.yml

@@ -0,0 +1,30 @@
+name: ✍️ Channel Request
+description: Request to add a channel to the guide
+labels: ['channel request']
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please fill out the request as much as possible so we can efficiently process your request.
+
+  - type: input
+    attributes:
+      label: Site
+      description: The name of the site
+      placeholder: 'guidatv.sky.it'
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Channels
+      description: List of channels to be added
+      placeholder: 'BBC One'
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Notes
+      description: Anything else we should know?

.github/workflows/check.yml

@@ -20,7 +20,7 @@ jobs:
           files_yaml: |
             js:
               - tests/**/*.{js,ts}
-              - scripts/**/*.{js,ts}
+              - scripts/**/*.{js,mts,ts}
               - sites/**/*.{js,ts}
             channels:
               - sites/**/*.channels.xml
@@ -39,4 +39,6 @@ jobs:
       - name: check changed *.channels.xml
         if: steps.files.outputs.channels_any_changed == 'true'
         run: |
-          npm run channels:lint -- ${{ steps.files.outputs.channels_all_changed_files }}
+          npm run channels:lint -- ${{ steps.files.outputs.channels_all_changed_files }}
+          npm run postinstall
+          npm run channels:validate -- ${{ steps.files.outputs.channels_all_changed_files }}

.github/workflows/update.yml

@@ -36,13 +36,15 @@ jobs:
         run: npm run sites:update
       - run: git status
       - name: commit changes to sites.md
-        run: |
-          git add SITES.md
-          git status
-          git commit --allow-empty -m "[Bot] Update SITES.md" -m "Committed by [iptv-bot](https://github.com/apps/iptv-bot) via [update](https://github.com/iptv-org/epg/actions/runs/${{ github.run_id }}) workflow." --no-verify
-      - name: push all changes to the repository
         if: ${{ !env.ACT && github.ref == 'refs/heads/master' }}
-        run: git push
+        run: |
+          SITE=SITES.md
+          CHANGED=$(git diff ${SITE})
+          if [ -n "${CHANGED}" ]; then
+            git add ${SITE}
+            git commit -m "[Bot] Update ${SITE}" -m "Committed by [iptv-bot](https://github.com/apps/iptv-bot) via [update](https://github.com/iptv-org/epg/actions/runs/${{ github.run_id }}) workflow." --no-verify
+            git push
+          fi
       - name: generate .api/guides.json
         run: npm run api:generate
       - run: git status

CONTRIBUTING.md

@@ -8,12 +8,16 @@
 
 ### How to add a channel to the guide?
 
-Open the [/sites](/sites) folder and select the source that you know has the guide for the channel you want.
+First, select a site from the [SITES.md](SITES.md) that you know has a guide for the channel you need. Then go to the folder with its config and open the file `*.channels.xml`.
 
-Then in the selected folder open the file `*.channels.xml` and add to it:
+Make sure that the desired channel is not already in the list. If it is not, simply add its description to the end of the list as shown here:
 
 ```xml
-<channel site="SITE" lang="LANGUAGE_CODE" xmltv_id="CHANNEL_ID" site_id="SITE_ID">CHANNEL_NAME</channel>
+<?xml version="1.0" encoding="UTF-8"?>
+<channels>
+  ...
+  <channel site="SITE" lang="LANGUAGE_CODE" xmltv_id="CHANNEL_ID" site_id="SITE_ID">CHANNEL_NAME</channel>
+</channels>
 ```
 
 | Attribute     | Description                                                                                                                                                        | Example       |
@@ -22,28 +26,56 @@ Then in the selected folder open the file `*.channels.xml` and add to it:
 | LANGUAGE_CODE | Language of the guide ([ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) code).                                                                   | `en`          |
 | CHANNEL_ID    | Channel ID from [iptv-org/database](https://github.com/iptv-org/database). A complete list of supported channels can also be found at https://iptv-org.github.io/. | `BBCOne.uk`   |
 | SITE_ID       | Unique ID of the channel used in the source.                                                                                                                       | `bbc1`        |
-| CHANNEL_NAME  | Name of the channel used in the source.                                                                                                                            | `BBC 1`       |
+| CHANNEL_NAME  | Name of the channel used in the source.                                                                                                                            | `BBC One`     |
+
+After that just [commit](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits) all changes and send a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).
+
+### How to map the channels?
+
+In order for the guides to be linked with playlists from [iptv-org/iptv](https://github.com/iptv-org/iptv) and also with our other projects, each channel must have the same ID in the description as in our [iptv-org/database](https://github.com/iptv-org/database).
 
-After that just commit all changes and send a pull request.
+To check this, select one of the sites in the [SITES.md](SITES.md), open its `*.channels.xml` file and check that all channels have a valid `xmltv_id`. If it is missing somewhere, just copy the matching ID from the [iptv-org.github.io](https://iptv-org.github.io/). If the channel is not in our database yet, you can add it to it through this [form](https://github.com/iptv-org/database/issues/new?assignees=&labels=channels%3Aadd&projects=&template=__channels_add.yml&title=Add%3A+).
+
+If the `*.channels.xml` file contains many channels without `xmltv_id`, you can speed up the process by running the command in the [Console](https://en.wikipedia.org/wiki/Windows_Console) (or [Terminal](<https://en.wikipedia.org/wiki/Terminal_(macOS)>) if you have macOS):
+
+```sh
+npm run channels:edit path/to/channels.xml
+```
+
+This way, you can map channels by simply selecting the proper ID from the list:
+
+```sh
+? Select xmltv_id for "BBC One" (bbc1): (Use arrow keys)
+❯ BBC One (BBC1, BBC Television, BBC Television Service) | BBCOne.uk
+  BBC One HD | BBCOneHD.uk
+  Type...
+  Skip
+```
+
+Once complete, [commit](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits) all changes and send a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).
 
 ### How to add a new source to the repository?
 
-To do this, you must create a new folder in the [/sites](/sites) with at least 3 files:
+To do this, you will need to create a new folder in the [/sites](/sites) directory with at least 4 files:
 
 <details>
 <summary>example.com.config.js</summary>
 <br>
 
-This file describes what kind of request we need to send to get the guide for a particular channel on a certain date. It also describes how to parse the response.
+This file describes what kind of request we need to send to get the guide for a particular channel on a certain date and how to parse the response.
 
 ```js
 module.exports = {
   site: 'example.com',
-  url: function ({ channel, date }) {
+  url({ channel, date }) {
     return `https://example.com/api/${channel.site_id}/${date.format('YYYY-MM-DD')}`
   },
-  parser: function ({ content }) {
-    return JSON.parse(content)
+  parser({ content }) {
+    try {
+      return JSON.parse(content)
+    } catch {
+      return []
+    }
   }
 }
 ```
@@ -59,39 +91,51 @@ More detailed instructions for this file can be found here: https://github.com/f
 With this file we can test the previously created config and make sure it works as you expect.
 
 ```js
-const { url, parser } = require('./example.com.config.js')
+const { parser, url } = require('./example.com.config.js')
 const dayjs = require('dayjs')
 const utc = require('dayjs/plugin/utc')
+const customParseFormat = require('dayjs/plugin/customParseFormat')
+dayjs.extend(customParseFormat)
 dayjs.extend(utc)
 
-const date = dayjs.utc('2022-11-18', 'YYYY-MM-DD').startOf('d')
-const channel = { site_id: 'bbc1', xmltv_id: 'BBCOne.uk', lang: 'en' }
+const date = dayjs.utc('2025-01-12', 'YYYY-MM-DD').startOf('d')
+const channel = { site_id: 'bbc1', xmltv_id: 'BBCOne.uk' }
 
 it('can generate valid url', () => {
-  expect(url({ channel, date })).toBe('https://example.com/api/bbc1/2022-11-18')
+  expect(url({ channel, date })).toBe('https://example.com/api/bbc1/2025-01-12')
 })
 
 it('can parse response', () => {
-  const content = `[{"start":"2022-11-18T01:30:00.000Z","stop":"2022-11-18T02:00:00.000Z","title":"Program 1"}]`
+  const content =
+    '[{"title":"Program 1","start":"2025-01-12T00:00:00.000Z","stop":"2025-01-12T00:30:00.000Z"},{"title":"Program 2","start":"2025-01-12T00:30:00.000Z","stop":"2025-01-12T01:00:00.000Z"}]'
+
   const results = parser({ content })
 
-  expect(results).toMatchObject([
-    {
-      start: '2022-11-18T01:30:00.000Z',
-      stop: '2022-11-18T02:00:00.000Z',
-      title: 'Program 1'
-    }
-  ])
+  expect(results.length).toBe(2)
+  expect(results[0]).toMatchObject({
+    title: 'Program 1',
+    start: '2025-01-12T00:00:00.000Z',
+    stop: '2025-01-12T00:30:00.000Z'
+  })
+  expect(results[1]).toMatchObject({
+    title: 'Program 2',
+    start: '2025-01-12T00:30:00.000Z',
+    stop: '2025-01-12T01:00:00.000Z'
+  })
 })
 
 it('can handle empty guide', () => {
-  const results = parser({ content: '' })
+  const result = parser({
+    date,
+    channel,
+    content: ''
+  })
 
-  expect(results).toMatchObject([])
+  expect(result).toMatchObject([])
 })
 ```
 
-To run the tests you can use the following command:
+To run all of these tests use the following command:
 
 ```sh
 npm test --- example.com
@@ -110,21 +154,45 @@ This file contains a list of channels available at the source.
 ```xml
 <?xml version="1.0" encoding="UTF-8" ?>
 <channels>
- <channel site="example.com" lang="en" xmltv_id="BBCOne.uk" site_id="bbc1">BBC 1</channel>
+  <channel site="example.com" lang="en" xmltv_id="BBCOne.uk" site_id="bbc1">BBC One</channel>
 </channels>
 ```
 
 </details>
 
-After creating all the files we can make sure that the guide loads correctly and has no errors using the command:
+<details>
+<summary>readme.md</summary>
+<br>
+
+This file contains instructions on how to use this config.
+
+````
+# example.com
+
+https://example.com
+
+### Download the guide
 
 ```sh
 npm run grab --- --site=example.com
 ```
 
-If the download is successful, the `guide.xml` file with the ready to use program should appear in the root directory.
+### Test
+
+```sh
+npm test --- example.com
+```
+````
+
+</details>
+
+The fastest way to create all these files is to use the command:
+
+```sh
+npm run sites:init --- example.com
+```
 
-After that, all that remains is to commit all the changes and send a pull request.
+Once you are done working on the config make sure the tests pass, the guide downloads correctly, [commit](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits) all changes and send us a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).
 
 ## Project Structure
 
@@ -153,8 +221,9 @@ To run scripts use the `npm run <script-name>` command.
 - `api:generate`: generates a JSON file with all channels for the [iptv-org/api](https://github.com/iptv-org/api) repository.
 - `channels:lint`: сhecks the channel lists for syntax errors.
 - `channels:parse`: generates a list of channels based on the site configuration.
-- `channels:editor`: utility for quick channels markup.
+- `channels:edit`: utility for quick channels mapping.
 - `channels:validate`: checks the description of channels for errors.
+- `sites:init`: creates a new site config from the template.
 - `sites:update`: updates the list of sites and their status in [SITES.md](SITES.md).
 - `grab`: downloads a program from a specified source.
 - `serve`: starts the [web server](https://github.com/vercel/serve).