@circlesac/mack 0.0.0 → 26.2.0

package/.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      env:
+        type: choice
+        description: Environment
+        default: production
+        options:
+          - production
+          - dev
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "lts/*"
+      - uses: oven-sh/setup-bun@v2
+
+      - run: bun install --frozen-lockfile
+      - run: bun test
+
+      - run: npm install -g @circlesac/oneup
+      - run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          oneup version
+
+      - uses: actions/setup-node@v4
+        with:
+          registry-url: "https://registry.npmjs.org"
+      - run: npm publish --tag ${{ inputs.env == 'production' && 'latest' || inputs.env }}
+
+      - run: git push origin master --follow-tags

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Instantish, Inc.
+
+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,69 @@
+# Mack: Markdown to Slack Message Blocks
+
+> Convert Markdown and GitHub Flavoured Markdown to Slack BlockKit Blocks
+
+[![Node.js CI](https://github.com/circlesac/mack/actions/workflows/ci.yml/badge.svg)](https://github.com/circlesac/mack/actions/workflows/ci.yml)
+Mack is a Markdown parser to convert any Markdown content to Slack BlockKit block objects.
+
+Text is truncated to fit within the Slack API's limits.
+
+### Supported Markdown Elements
+
+- All inline elements (italics, bold, strikethrough, inline code, hyperlinks)
+- Lists (ordered, unordered, checkboxes)
+- All headers
+- Code blocks
+- Block quotes (with some limitations)
+- Images
+- Thematic Breaks / Dividers
+- Tables (alignment not preserved)
+
+### Not Yet Supported Markdown Elements
+
+- Block quotes (limited functionality; does not support lists, headings, or images within the block quote)
+
+## Installation
+
+```
+bun add @circlesac/mack
+```
+
+## Usage
+
+```ts
+import { markdownToBlocks } from "@circlesac/mack"
+
+const blocks = markdownToBlocks(`
+# Hello world
+
+* bulleted item 1
+* bulleted item 2
+
+abc _123_
+
+![cat](https://images.unsplash.com/photo-1574158622682-e40e69881006)
+`)
+```
+
+The `blocks` object now results in [this](https://app.slack.com/block-kit-builder/T01BFUV9UPJ#%7B%22blocks%22:%5B%7B%22text%22:%7B%22text%22:%22Hello%20world%22,%22type%22:%22plain_text%22%7D,%22type%22:%22header%22%7D,%7B%22text%22:%7B%22text%22:%22•%20bulleted%20item%201%5Cn•%20bulleted%20item%202%22,%22type%22:%22mrkdwn%22%7D,%22type%22:%22section%22%7D,%7B%22text%22:%7B%22text%22:%22abc%20_123_%22,%22type%22:%22mrkdwn%22%7D,%22type%22:%22section%22%7D,%7B%22alt_text%22:%22cat%22,%22image_url%22:%22https://images.unsplash.com/photo-1574158622682-e40e69881006?w=640%22,%22type%22:%22image%22%7D%5D%7D) payload.
+
+## API
+
+`function markdownToBlocks(text: string, options: ParsingOptions): KnownBlock[]`
+
+- `text`: the content to parse
+- `options`: the options to use when parsing.
+
+### Parsing Options
+
+```ts
+interface ParsingOptions {
+  // Configure how lists are displayed
+  lists?: ListOptions
+}
+
+interface ListOptions {
+  // Configure how checkbox list items are displayed. By default, they are prefixed with '* '
+  checkboxPrefix?: (checked: boolean) => string
+}
+```

package/build/src/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Custom error types for Mack parser
+ */
+export declare class MackError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+export declare class ValidationError extends MackError {
+    constructor(message: string);
+}
+export declare class ParseError extends MackError {
+    readonly tokenType?: string;
+    constructor(message: string, tokenType?: string);
+}
+export declare class BlockLimitError extends MackError {
+    readonly blockCount: number;
+    readonly maxBlocks: number;
+    constructor(blockCount: number, maxBlocks: number);
+}
+export declare class SecurityError extends MackError {
+    constructor(message: string);
+}

package/build/src/errors.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Custom error types for Mack parser
+ */
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+exports.__esModule = true;
+exports.SecurityError = exports.BlockLimitError = exports.ParseError = exports.ValidationError = exports.MackError = void 0;
+var MackError = /** @class */ (function (_super) {
+    __extends(MackError, _super);
+    function MackError(message, code) {
+        var _this = _super.call(this, message) || this;
+        _this.code = code;
+        _this.name = "MackError";
+        Object.setPrototypeOf(_this, MackError.prototype);
+        return _this;
+    }
+    return MackError;
+}(Error));
+exports.MackError = MackError;
+var ValidationError = /** @class */ (function (_super) {
+    __extends(ValidationError, _super);
+    function ValidationError(message) {
+        var _this = _super.call(this, message, "VALIDATION_ERROR") || this;
+        _this.name = "ValidationError";
+        Object.setPrototypeOf(_this, ValidationError.prototype);
+        return _this;
+    }
+    return ValidationError;
+}(MackError));
+exports.ValidationError = ValidationError;
+var ParseError = /** @class */ (function (_super) {
+    __extends(ParseError, _super);
+    function ParseError(message, tokenType) {
+        var _this = _super.call(this, message, "PARSE_ERROR") || this;
+        _this.tokenType = tokenType;
+        _this.name = "ParseError";
+        Object.setPrototypeOf(_this, ParseError.prototype);
+        return _this;
+    }
+    return ParseError;
+}(MackError));
+exports.ParseError = ParseError;
+var BlockLimitError = /** @class */ (function (_super) {
+    __extends(BlockLimitError, _super);
+    function BlockLimitError(blockCount, maxBlocks) {
+        var _this = _super.call(this, "Block limit exceeded: ".concat(blockCount, " blocks exceeds maximum of ").concat(maxBlocks), "BLOCK_LIMIT_EXCEEDED") || this;
+        _this.blockCount = blockCount;
+        _this.maxBlocks = maxBlocks;
+        _this.name = "BlockLimitError";
+        Object.setPrototypeOf(_this, BlockLimitError.prototype);
+        return _this;
+    }
+    return BlockLimitError;
+}(MackError));
+exports.BlockLimitError = BlockLimitError;
+var SecurityError = /** @class */ (function (_super) {
+    __extends(SecurityError, _super);
+    function SecurityError(message) {
+        var _this = _super.call(this, message, "SECURITY_ERROR") || this;
+        _this.name = "SecurityError";
+        Object.setPrototypeOf(_this, SecurityError.prototype);
+        return _this;
+    }
+    return SecurityError;
+}(MackError));
+exports.SecurityError = SecurityError;

package/build/src/index.d.ts

@@ -0,0 +1,23 @@
+import type { KnownBlock } from "@slack/types";
+import type { RichTextBlock, TableBlock, VideoBlock } from "./slack";
+import type { ParsingOptions } from "./types";
+export { BlockLimitError, MackError, ParseError, SecurityError, ValidationError } from "./errors";
+export type { ColumnSetting, RichTextBlock, RichTextBroadcastElement, RichTextChannelElement, RichTextDateElement, RichTextElement, RichTextEmojiElement, RichTextLinkElement, RichTextListElement, RichTextPreformattedElement, RichTextQuoteElement, RichTextSectionElement, RichTextStyle, RichTextTextElement, RichTextUserElement, RichTextUsergroupElement, TableBlock, TableCell, TableRow, VideoBlock, VideoBlockOptions } from "./slack";
+export type { ListOptions, ParsingOptions } from "./types";
+/**
+ * Parses Markdown content into Slack BlockKit Blocks.
+ * - Supports headings (all Markdown heading levels are treated as the single Slack header block)
+ * - Supports numbered lists, bulleted lists, to-do lists (as rich_text_list blocks)
+ * - Supports italics, bold, strikethrough, inline code, hyperlinks
+ * - Supports images
+ * - Supports thematic breaks / dividers
+ * - Supports code blocks (as rich_text_preformatted blocks)
+ * - Supports blockquotes (as rich_text_quote blocks for simple quotes)
+ * - Supports native table blocks with rich text formatting and column alignment
+ *
+ * Supports GitHub-flavoured Markdown.
+ *
+ * @param body any Markdown or GFM content
+ * @param options options to configure the parser
+ */
+export declare function markdownToBlocks(body: string, options?: ParsingOptions): Promise<(KnownBlock | TableBlock | RichTextBlock | VideoBlock)[]>;

package/build/src/index.js

@@ -0,0 +1,109 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+exports.__esModule = true;
+exports.markdownToBlocks = exports.ValidationError = exports.SecurityError = exports.ParseError = exports.MackError = exports.BlockLimitError = void 0;
+var marked_1 = require("marked");
+var internal_1 = require("./parser/internal");
+var validation_1 = require("./validation");
+var errors_1 = require("./errors");
+__createBinding(exports, errors_1, "BlockLimitError");
+__createBinding(exports, errors_1, "MackError");
+__createBinding(exports, errors_1, "ParseError");
+__createBinding(exports, errors_1, "SecurityError");
+__createBinding(exports, errors_1, "ValidationError");
+/**
+ * Parses Markdown content into Slack BlockKit Blocks.
+ * - Supports headings (all Markdown heading levels are treated as the single Slack header block)
+ * - Supports numbered lists, bulleted lists, to-do lists (as rich_text_list blocks)
+ * - Supports italics, bold, strikethrough, inline code, hyperlinks
+ * - Supports images
+ * - Supports thematic breaks / dividers
+ * - Supports code blocks (as rich_text_preformatted blocks)
+ * - Supports blockquotes (as rich_text_quote blocks for simple quotes)
+ * - Supports native table blocks with rich text formatting and column alignment
+ *
+ * Supports GitHub-flavoured Markdown.
+ *
+ * @param body any Markdown or GFM content
+ * @param options options to configure the parser
+ */
+function markdownToBlocks(body, options) {
+    if (options === void 0) { options = {}; }
+    return __awaiter(this, void 0, void 0, function () {
+        var replacements, lexer, tokenizer, origInlineText, tokens, blocks;
+        return __generator(this, function (_a) {
+            (0, validation_1.validateInput)(body);
+            replacements = {
+                "&": "&amp;",
+                "<": "&lt;",
+                ">": "&gt;"
+            };
+            lexer = new marked_1.marked.Lexer();
+            tokenizer = lexer.tokenizer;
+            origInlineText = tokenizer.inlineText;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            tokenizer.inlineText = function (src) {
+                var cap = this.rules.inline.text.exec(src);
+                if (!cap) {
+                    return undefined;
+                }
+                var raw = cap[0];
+                var text = raw.replace(/[&<>]/g, function (char) { return replacements[char]; });
+                return { type: "text", raw: raw, text: text };
+            };
+            tokens = lexer.lex(body);
+            // Restore the original inlineText to avoid polluting marked.defaults
+            tokenizer.inlineText = origInlineText;
+            blocks = (0, internal_1.parseBlocks)(tokens, options);
+            (0, validation_1.validateBlockCount)(blocks.length, validation_1.MAX_BLOCKS);
+            return [2 /*return*/, blocks];
+        });
+    });
+}
+exports.markdownToBlocks = markdownToBlocks;

package/build/src/parser/internal.d.ts

@@ -0,0 +1,5 @@
+import { KnownBlock } from "@slack/types";
+import { marked } from "marked";
+import { RichTextBlock, TableBlock, VideoBlock } from "../slack";
+import { ParsingOptions } from "../types";
+export declare function parseBlocks(tokens: marked.TokensList, options?: ParsingOptions): (KnownBlock | TableBlock | RichTextBlock | VideoBlock)[];