tgwidget 0.1.0

package/README.md

@@ -0,0 +1,75 @@
+# tgwidget
+
+Node.js SDK for [TeleWidget](https://tgwidget.github.io/) — beautiful Telegram Mini App widgets for bots.
+
+## Install
+
+```bash
+npm install tgwidget
+```
+
+## Usage
+
+### Generate widget URL
+
+```typescript
+import { tgwidget } from "tgwidget";
+
+// Date picker
+const url = tgwidget("your_bot").date({ mode: "datetime", format: "unix-s" }).url();
+
+// Color picker
+const url = tgwidget("your_bot").color({ format: "hex" }).url();
+
+// Schedule
+const url = tgwidget("your_bot").schedule().url();
+
+// With styling
+const url = tgwidget("your_bot")
+  .date({ mode: "date" })
+  .style({ colorScheme: "dark", accent: "#FF6600", adoptTgPalette: true })
+  .url();
+```
+
+### Parse results
+
+When a user completes the widget, the result comes back via deep link `t.me/your_bot?start=VALUE`. Parse the value:
+
+```typescript
+import { parseDate, parseColor, parseSchedule } from "tgwidget";
+
+// Date result
+const result = parseDate("2025-03-15", { mode: "date" });
+// { date: '2025-03-15' }
+
+// Unix timestamp
+const result = parseDate("1710460800_1718236800", { mode: "date-range", format: "unix-s" });
+// { timestamp: 1710460800, timestampEnd: 1718236800, date: '2025-03-15', ... }
+
+// Color
+const result = parseColor("FF6600", { format: "hex" });
+// { raw: 'FF6600', hex: '#FF6600' }
+
+// Schedule (56-char bunch format)
+const result = parseSchedule("09001800090018000000000009001800090018000000000000000000");
+// [{ enabled: true, start: '09:00', end: '18:00' }, ...]
+```
+
+## API
+
+### `tgwidget(botUsername)`
+
+Create a widget builder. Returns a chainable `TgWidget` instance.
+
+- `.date({ mode?, format?, order? })` — Date/time picker
+- `.color({ format? })` — Color picker
+- `.schedule()` — Weekly schedule
+- `.style({ colorScheme?, accent?, tint?, liquidGlass?, adaptTgTheme?, adoptTgPalette? })` — Styling
+- `.url(baseUrl?)` — Generate the final URL
+- `.payload()` — Get the raw payload object
+
+### Parsers
+
+- `parseDate(value, { mode?, format?, order? })` → `DateResult`
+- `parseColor(value, { format? })` → `ColorResult`
+- `parseSchedule(value)` → `ScheduleDay[]`

package/dist/builder.d.ts

@@ -0,0 +1,29 @@
+import type { DateMode, DateFormat, DateOrder, ColorFormat, ColorScheme } from "./types";
+export declare class TgWidget {
+    private _botUsername;
+    private _widget;
+    private _payload;
+    private _style;
+    constructor(botUsername: string);
+    date(opts?: {
+        mode?: DateMode;
+        format?: DateFormat;
+        order?: DateOrder;
+    }): this;
+    color(opts?: {
+        format?: ColorFormat;
+    }): this;
+    schedule(): this;
+    style(opts?: {
+        colorScheme?: ColorScheme;
+        accent?: string;
+        tint?: string;
+        liquidGlass?: boolean;
+        adaptTgTheme?: boolean;
+        adoptTgPalette?: boolean;
+    }): this;
+    private _buildPayload;
+    url(baseUrl?: string): string;
+    payload(): Record<string, unknown>;
+}
+export declare function tgwidget(botUsername: string): TgWidget;

package/dist/builder.js

@@ -0,0 +1,89 @@
+const BASE_URL = "https://tgwidget.github.io/";
+const HEX_RE = /^#?[0-9A-Fa-f]{6}$/;
+const VALID_DATE_MODES = new Set(["date", "time", "datetime", "date-range", "time-range"]);
+const VALID_DATE_FORMATS = new Set(["default", "unix-s", "unix-ms"]);
+const VALID_DATE_ORDERS = new Set(["ymd", "dmy", "mdy"]);
+const VALID_COLOR_FORMATS = new Set(["hex", "rgb", "hsl"]);
+const VALID_COLOR_SCHEMES = new Set(["light", "dark", "auto"]);
+function validateHex(color, name) {
+    if (!HEX_RE.test(color)) {
+        throw new Error(`${name} must be a valid hex color (e.g. '#FF0000'), got '${color}'`);
+    }
+    return color.startsWith("#") ? color : `#${color}`;
+}
+function toBase64(str) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(str).toString("base64");
+    }
+    return btoa(str);
+}
+export class TgWidget {
+    constructor(botUsername) {
+        this._widget = null;
+        this._payload = {};
+        this._style = {};
+        if (!botUsername)
+            throw new Error("botUsername is required");
+        this._botUsername = botUsername;
+    }
+    date(opts = {}) {
+        const { mode = "date", format = "default", order = "ymd" } = opts;
+        if (!VALID_DATE_MODES.has(mode))
+            throw new Error(`Invalid date mode '${mode}'`);
+        if (!VALID_DATE_FORMATS.has(format))
+            throw new Error(`Invalid date format '${format}'`);
+        if (!VALID_DATE_ORDERS.has(order))
+            throw new Error(`Invalid date order '${order}'`);
+        this._widget = "date";
+        this._payload = { mode, format, order };
+        return this;
+    }
+    color(opts = {}) {
+        const { format = "hex" } = opts;
+        if (!VALID_COLOR_FORMATS.has(format))
+            throw new Error(`Invalid color format '${format}'`);
+        this._widget = "color";
+        this._payload = { format };
+        return this;
+    }
+    schedule() {
+        this._widget = "schedule";
+        this._payload = { format: "bunch" };
+        return this;
+    }
+    style(opts = {}) {
+        const { colorScheme = "light", accent, tint, liquidGlass = false, adaptTgTheme = false, adoptTgPalette = false } = opts;
+        if (!VALID_COLOR_SCHEMES.has(colorScheme))
+            throw new Error(`Invalid colorScheme '${colorScheme}'`);
+        this._style = { colorScheme, liquidGlass, adaptTgTheme, adoptTgPalette };
+        if (accent)
+            this._style.accent = validateHex(accent, "accent");
+        if (tint)
+            this._style.tint = validateHex(tint, "tint");
+        return this;
+    }
+    _buildPayload() {
+        if (!this._widget)
+            throw new Error("No widget type set. Call .date(), .color(), or .schedule() first.");
+        const payload = {
+            widget: this._widget,
+            bot_username: this._botUsername,
+            ...this._payload,
+        };
+        if (Object.keys(this._style).length > 0) {
+            payload.style = this._style;
+        }
+        return payload;
+    }
+    url(baseUrl = BASE_URL) {
+        const payload = this._buildPayload();
+        const encoded = toBase64(JSON.stringify(payload));
+        return `${baseUrl}?p=${encoded}`;
+    }
+    payload() {
+        return this._buildPayload();
+    }
+}
+export function tgwidget(botUsername) {
+    return new TgWidget(botUsername);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { tgwidget, TgWidget } from "./builder";
+export { parseDate, parseColor, parseSchedule } from "./parser";
+export type { DateMode, DateFormat, DateOrder, ColorFormat, ColorScheme, WidgetStyle, DateResult, ColorResult, ScheduleDay, } from "./types";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { tgwidget, TgWidget } from "./builder";
+export { parseDate, parseColor, parseSchedule } from "./parser";

package/dist/parser.d.ts

@@ -0,0 +1,10 @@
+import type { DateMode, DateFormat, DateOrder, ColorFormat, DateResult, ColorResult, ScheduleDay } from "./types";
+export declare function parseDate(value: string, opts?: {
+    mode?: DateMode;
+    format?: DateFormat;
+    order?: DateOrder;
+}): DateResult;
+export declare function parseColor(value: string, opts?: {
+    format?: ColorFormat;
+}): ColorResult;
+export declare function parseSchedule(value: string): ScheduleDay[];

package/dist/parser.js

@@ -0,0 +1,97 @@
+function parseDateStr(value, order) {
+    const parts = value.split("-");
+    if (order === "ymd")
+        return `${parts[0]}-${parts[1]}-${parts[2]}`;
+    if (order === "dmy")
+        return `${parts[2]}-${parts[1]}-${parts[0]}`;
+    return `${parts[2]}-${parts[0]}-${parts[1]}`; // mdy
+}
+export function parseDate(value, opts = {}) {
+    const { mode = "date", format = "default", order = "ymd" } = opts;
+    const result = {};
+    if (format === "unix-s" || format === "unix-ms") {
+        const parts = value.split("_");
+        const mul = format === "unix-s" ? 1000 : 1;
+        const ts = parseInt(parts[0], 10);
+        result.timestamp = ts;
+        const dt = new Date(ts * mul);
+        result.date = dt.toISOString().slice(0, 10);
+        result.time = dt.toISOString().slice(11, 16);
+        if (parts.length > 1) {
+            const tsEnd = parseInt(parts[1], 10);
+            result.timestampEnd = tsEnd;
+            const dtEnd = new Date(tsEnd * mul);
+            result.dateEnd = dtEnd.toISOString().slice(0, 10);
+            result.timeEnd = dtEnd.toISOString().slice(11, 16);
+        }
+        return result;
+    }
+    switch (mode) {
+        case "date":
+            result.date = parseDateStr(value, order);
+            break;
+        case "time": {
+            const [h, m] = value.split("-");
+            result.time = `${h}:${m}`;
+            break;
+        }
+        case "datetime": {
+            const [datePart, timePart] = value.split("_");
+            result.date = parseDateStr(datePart, order);
+            const [h, m] = timePart.split("-");
+            result.time = `${h}:${m}`;
+            break;
+        }
+        case "date-range": {
+            const parts = value.split("_");
+            result.date = parseDateStr(parts[0], order);
+            result.dateEnd = parseDateStr(parts[1], order);
+            break;
+        }
+        case "time-range": {
+            const parts = value.split("_");
+            const [h1, m1] = parts[0].split("-");
+            const [h2, m2] = parts[1].split("-");
+            result.time = `${h1}:${m1}`;
+            result.timeEnd = `${h2}:${m2}`;
+            break;
+        }
+    }
+    return result;
+}
+export function parseColor(value, opts = {}) {
+    const { format = "hex" } = opts;
+    const result = { raw: value };
+    if (format === "hex") {
+        result.hex = `#${value}`;
+    }
+    else if (format === "rgb") {
+        const parts = value.split("_").map(Number);
+        result.rgb = [parts[0], parts[1], parts[2]];
+    }
+    else if (format === "hsl") {
+        const parts = value.split("_").map(Number);
+        result.hsl = [parts[0], parts[1], parts[2]];
+    }
+    return result;
+}
+export function parseSchedule(value) {
+    if (value.length !== 56) {
+        throw new Error(`Schedule bunch format must be 56 chars, got ${value.length}`);
+    }
+    const days = [];
+    for (let i = 0; i < 7; i++) {
+        const chunk = value.slice(i * 8, (i + 1) * 8);
+        if (chunk === "00000000") {
+            days.push({ enabled: false });
+        }
+        else {
+            days.push({
+                enabled: true,
+                start: `${chunk.slice(0, 2)}:${chunk.slice(2, 4)}`,
+                end: `${chunk.slice(4, 6)}:${chunk.slice(6, 8)}`,
+            });
+        }
+    }
+    return days;
+}

package/dist/types.d.ts

@@ -0,0 +1,32 @@
+export type DateMode = "date" | "time" | "datetime" | "date-range" | "time-range";
+export type DateFormat = "default" | "unix-s" | "unix-ms";
+export type DateOrder = "ymd" | "dmy" | "mdy";
+export type ColorFormat = "hex" | "rgb" | "hsl";
+export type ColorScheme = "light" | "dark" | "auto";
+export interface WidgetStyle {
+    colorScheme?: ColorScheme;
+    accent?: string;
+    tint?: string;
+    liquidGlass?: boolean;
+    adaptTgTheme?: boolean;
+    adoptTgPalette?: boolean;
+}
+export interface DateResult {
+    date?: string;
+    time?: string;
+    dateEnd?: string;
+    timeEnd?: string;
+    timestamp?: number;
+    timestampEnd?: number;
+}
+export interface ColorResult {
+    raw: string;
+    hex?: string;
+    rgb?: [number, number, number];
+    hsl?: [number, number, number];
+}
+export interface ScheduleDay {
+    enabled: boolean;
+    start?: string;
+    end?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "tgwidget",
+  "version": "0.1.0",
+  "description": "Node.js SDK for TeleWidget — Telegram Mini App widgets",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc"
+  },
+  "keywords": ["telegram", "mini-apps", "widget", "bot", "tgwidget"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tgwidget/tgwidget-node"
+  },
+  "homepage": "https://github.com/tgwidget/tgwidget-node",
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "typescript": "^5.0.0"
+  }
+}