Merge pull request #5 from stape-io/package-setup

Add GitHub Actions workflow for automated npm publishing

Author: giovaniortolani

.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to npm
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'package.json'
+      - 'server-gtm-sandboxed-apis.d.ts'
+      - 'web-gtm-sandboxed-apis.d.ts'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm install
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.npmignore

@@ -0,0 +1,5 @@
+.github/
+node_modules/
+dist/
+examples/
+*.log

README.md

@@ -2,85 +2,103 @@
 
 This guide explains how to use the provided TypeScript Declaration Files (`.d.ts`) to enable IntelliSense (autocompletion and hover-documentation) for Google Tag Manager's Sandboxed JavaScript APIs in your code editor.
 
-There are two files:
+There are two file definitions:
 - `server-gtm-sandboxed-apis.d.ts`: For **Server-side** GTM templates.
 - `web-gtm-sandboxed-apis.d.ts`: For **Web** GTM templates.
 
----
-
-## What Are These Files?
+## What Are These Definitions?
 
 Google Tag Manager's custom templates run in a "sandboxed" JavaScript environment that has a special set of APIs (like `copyFromDataLayer` or `sendHttpRequest`). Standard code editors don't know about these custom APIs, so they can't provide any help as you code.
 
-These `.d.ts` files act as a guide for your editor. They define the signatures, parameters, and documentation for every GTM API, effectively teaching your editor how the GTM environment works.
+These  files act as a guide for your editor. They define the signatures, parameters, and documentation for every GTM API, effectively teaching your editor how the GTM environment works.
 
 
 https://github.com/user-attachments/assets/868bbe2c-3e28-47b1-b195-cdfc509ec340
 
-
 ---
 
 ## How to Use
 
-Choose the file that corresponds to the environment you are developing for (Web or Server) and place it in your project folder. Then, choose one of the following methods to activate IntelliSense.
+1. Install the type definitions directly using a package manager like `npm` or `pnpm`:
+    ```bash
+    pnpm install -D stape-gtm-api-types
+    # or
+    npm install --save-dev stape-gtm-api-types
+    ```
+
+    This is the recommended way to keep your GTM API types up to date.
+
+2. After installing the package, you can reference the type definitions in your project as follows:
+
+    ### Method 1: Using a Triple-Slash Directive (File-by-File)
 
-### Method 1: Using a Triple-Slash Directive (File-by-File)
+    This method is useful if you prefer not to create a `jsconfig.json` file. You must add a special comment to the **very top** of each JavaScript file containing GTM Sandboxed API code where you want IntelliSense.
 
-This method is useful if you prefer not to create a `jsconfig.json` file. You must add a special comment to the **very top** of each JavaScript file where you want IntelliSense.
+    Add a special comment to the **very top** of each JavaScript file where you want IntelliSense.
+    Make sure to add it exactly as is (with triple slashes).
 
-1.  **Place the `.d.ts` file** in your project directory (e.g., in the same folder as your `.js` file).
-2.  **Add the following comment** to the first line of your `.js` file:
+    - For **Web** GTM Sandboxed APIs:
     ```javascript
-    /// <reference path="./web-gtm-sandboxed-apis.d.ts" />
+    /// <reference types="stape-gtm-api-types/web-gtm-sandboxed-apis" />
 
     // Your GTM template code starts here...
     const copyFromDataLayer = require('copyFromDataLayer');
     ```
-3.  **Adjust the path**: Make sure the `path` in the comment correctly points to the location of your `.d.ts` file relative to your `.js` file.
 
-### Method 2: Using `jsconfig.json`
+    - For **Server** GTM Sandboxed APIs:
+    ```javascript
+    /// <reference types="stape-gtm-api-types/server-gtm-sandboxed-apis" />
+
+    // Your GTM template code starts here...
+    const getAllEventData = require('getAllEventData');
+    ```
+
+    ### Method 2: Using `jsconfig.json`
 
-This is a modern and reliable method for any project, even if it's just a single file. It tells your editor to treat the entire folder as a JavaScript project.
+    Create a `jsconfig.json` containing the following content in your project's root directory where the code of your template is located.
 
-1.  **Place the `.d.ts` file** in your project's root directory.
-2.  **Create a `jsconfig.json` file** in the same root directory.
-3.  **Add the following content** to your `jsconfig.json`:
+    - For **Web** GTM Sandboxed APIs:
     ```json
     {
       "compilerOptions": {
-        "target": "esnext"
+        "paths": {
+          "*": ["./node_modules/stape-gtm-api-types/web-gtm-sandboxed-apis"]
+        }
       },
       "include": ["**/*"]
     }
     ```
-4.  **Reload Your Editor**: If IntelliSense doesn't appear immediately, restart your editor or use the "Reload Window" command.
 
-With this setup, the editor will automatically find and use the type definitions for all `.js` files in your project.
+    - For **Server** GTM Sandboxed APIs:
+    ```json
+    {
+      "compilerOptions": {
+        "paths": {
+          "*": ["./node_modules/stape-gtm-api-types/server-gtm-sandboxed-apis"]
+        }
+      },
+      "include": ["**/*"]
+    }
+    ```
+
+3. Reload your editor if IntelliSense does not appear immediately.
 
 ---
 
 ## Editor-Specific Instructions
 
+
 ### Visual Studio Code
 
-Both `jsconfig.json` and the triple-slash directive methods work perfectly. The `jsconfig.json` approach is generally more robust and requires less maintenance.
+Both methods work perfectly. The **Method 2** is recommended for easier updates and maintenance.
 
 ### JetBrains IDEs (WebStorm, IntelliJ IDEA, etc.)
 
-JetBrains IDEs offer the simplest setup:
-
-1.  **Place the `.d.ts` file** anywhere in your project directory.
-
-That's it. The IDE will automatically index the file and provide IntelliSense across the entire project without any additional configuration. You do not need a `jsconfig.json` file or triple-slash directives.
+JetBrains IDEs will automatically index type definitions from installed `npm` packages. No manual copying required.
 
 ### Other Editors (Sublime Text, Neovim, etc.)
 
-For other modern editors that use a Language Server Protocol (LSP) for JavaScript and TypeScript, the process is generally the same as for JetBrains:
-
-1.  **Ensure your editor has a TypeScript/JavaScript language server** installed and configured.
-2.  **Place the `.d.ts` file** in the root of your project folder.
-
-The language server should automatically detect and use the type definitions to provide IntelliSense.
+Other editors that support TypeScript/JavaScript language servers will automatically detect type definitions from `npm` packages.
 
 ---