@k34a/blog 0.0.1

package/README.md

@@ -0,0 +1,236 @@
+# @k34a/forms
+
+**Dynamic Form Builder & Handler for Next.js and Supabase**  
+Easily create, render, and manage dynamic forms directly from your admin panel.  
+Supports form validation, user-friendly UI (powered by Mantine), and built-in submission handling.
+
+## Features
+
+- **Dynamic form rendering** using JSON schema  
+- **Automatic form validation** with [Zod](https://github.com/colinhacks/zod)  
+- **Form schema management** from your Supabase database  
+- **Built-in notification hooks** for success, error, and validation feedback  
+- **Easy API integration** for form submission  
+- **Custom callback support** (e.g., Telegram notifications)
+
+## Installation
+
+```bash
+npm install @k34a/forms
+```
+
+### Required peer dependencies
+
+Make sure you already have these installed in your project:
+
+```bash
+npm install @mantine/core @mantine/dates @mantine/dropzone @mantine/notifications @supabase/supabase-js @tabler/icons-react react zod
+```
+
+**Required versions:**
+
+| Package | Version |
+|----------|----------|
+| `@mantine/core` | ≥ 8.0.0 |
+| `@mantine/dates` | ≥ 8.0.0 |
+| `@mantine/dropzone` | ≥ 8.0.0 |
+| `@mantine/notifications` | ≥ 8.0.0 |
+| `@supabase/supabase-js` | ≥ 2.52.0 |
+| `@tabler/icons-react` | ≥ 3.0.0 |
+| `react` | ≥ 19.1.0 |
+| `zod` | ≥ 4.0.0 |
+
+
+## ⚙️ API Setup
+
+You might need to create an **API route** in your application to handle form submissions.
+
+Example using Next.js **Route Handlers (`app/api/fill-me/[formType]/route.ts`)**:
+
+```ts
+import { adminPanelLink, ORG_ID } from "@/config/config";
+import { supabaseAdmin } from "@/lib/db/supabase";
+import { sendTelegramMessage } from "@/lib/telegram";
+import { FormFillingService } from "@k34a/forms";
+import { headers } from "next/headers";
+import { NextRequest, NextResponse } from "next/server";
+
+function isPlainObject(input: unknown): input is Record<string, any> {
+  return typeof input === "object" && input !== null && !Array.isArray(input);
+}
+
+async function getSourceDetails() {
+  const hdrs = await headers();
+  const userAgent = hdrs.get("user-agent") ?? null;
+  const xff = hdrs.get("x-forwarded-for");
+  const realIp = hdrs.get("x-real-ip");
+  const sourceIp = xff?.split(",")[0].trim() ?? realIp ?? null;
+  return { sourceIp, userAgent };
+}
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ formType: string }> },
+) {
+  const { formType } = await params;
+
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
+  }
+
+  if (!isPlainObject(body)) {
+    return NextResponse.json(
+      { error: "Invalid request format. Expected a key-value object." },
+      { status: 400 }
+    );
+  }
+
+  try {
+    const service = new FormFillingService(
+      adminPanelLink,
+      ORG_ID,
+      supabaseAdmin,
+      async (msg) => {
+        try {
+          await sendTelegramMessage(msg);
+        } catch (error) {
+          console.log(error);
+        }
+      },
+    );
+
+    const userDetails = await getSourceDetails();
+    const result = await service.fillForm(
+      formType,
+      body,
+      userDetails.sourceIp ?? "",
+      userDetails.userAgent ?? "",
+    );
+
+    return NextResponse.json(result);
+  } catch (err: any) {
+    return NextResponse.json({ error: err.message || "Internal Server Error" }, { status: 500 });
+  }
+}
+```
+
+
+### Explanation of Methods & Callbacks
+
+| Function / Callback | Description |
+|---------------------|-------------|
+| **`isPlainObject()`** | Ensures the incoming JSON body is a plain object (key-value pairs) and not an array or invalid input. |
+| **`getSourceDetails()`** | Extracts the client’s IP address and `User-Agent` from headers for logging or analytics. |
+| **`FormFillingService`** | Core service from `@k34a/forms` that handles form validation, storage, and notifications. |
+| **`fillForm(formType, body, ip, userAgent)`** | Saves and validates the submitted form data. It links the form type to the schema defined in your admin panel. |
+| **Telegram Callback (`async (msg) => { ... }`)** | Optional async callback triggered after a successful form submission. You can send notifications to Telegram, Slack, etc. |
+
+
+## Creating a Dynamic Form Component
+
+The simplest way to render a form dynamically is by using the `FormBuilder` component.
+
+```tsx
+"use client";
+
+import { FormBuilder, FormSchema } from "@k34a/forms";
+import z from "zod";
+import { notifications } from "@mantine/notifications";
+import { ORG_ID } from "@/config/config";
+
+interface FormProps {
+  schema: z.infer<typeof FormSchema>;
+  formType: string;
+}
+
+export const FillMe = (props: FormProps) => {
+  return (
+    <FormBuilder
+      mode="fill"
+      schema={props.schema}
+      formType={props.formType}
+      orgId={ORG_ID}
+      submissionAPIEndPoint={`/api/fill-me/${props.formType}`}
+      onSuccess={() =>
+        notifications.show({
+          title: "All Set!",
+          message:
+            "Your details were submitted successfully. Thank you for completing the form!",
+          color: "green",
+        })
+      }
+      onValidationError={() =>
+        notifications.show({
+          title: "Please Review Your Form",
+          message:
+            "Some information seems to be missing or incorrect. Check the highlighted fields and try again.",
+          color: "orange",
+        })
+      }
+      onError={() =>
+        notifications.show({
+          title: "Submission Failed",
+          message:
+            "Something went wrong while sending your details. Please try again later.",
+          color: "red",
+        })
+      }
+    />
+  );
+};
+```
+
+> 💡 **Tip:** Make sure to set your organization ID (`ORG_ID`) from your admin panel at [k34a.vercel.app](https://k34a.vercel.app).
+
+
+## Fetching the Form Schema from Supabase
+
+You can dynamically fetch a form schema from your Supabase database before rendering the form:
+
+```tsx
+import { FormFillingService } from "@k34a/forms";
+import { supabaseAdmin } from "@/lib/db/supabase";
+import { notFound } from "next/navigation";
+import { adminPanelLink, ORG_ID } from "@/config/config";
+import Partners from "@/components/partners/partners";
+
+export default async function PartnersPage() {
+  let schema;
+  const formType = "csr_partnership_inquiry";
+
+  try {
+    schema = await new FormFillingService(
+      adminPanelLink,
+      ORG_ID,
+      supabaseAdmin,
+    ).getFormSchema(formType);
+  } catch (err) {
+    console.error(err);
+    notFound();
+  }
+
+  return (
+    <main>
+      <Partners schema={schema} formType={formType} />
+    </main>
+  );
+}
+```
+
+
+## Summary
+
+| Step | Description |
+|------|--------------|
+| Install the package | `npm install @k34a/forms` |
+| Create API handler | Accepts and validates form submissions |
+| Use `FormBuilder` | To render and handle forms in your UI |
+| Fetch form schemas | From your Supabase database using `FormFillingService` |
+| Customize callbacks | (Success, ValidationError, Error) for better UX |
+
+## License
+
+MIT © 2025 — Built with ❤️ by [K34A](https://k34a.vercel.app)

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+import { ArticleService } from './services/articles';
+export { ArticleService };

package/dist/main.js

@@ -0,0 +1,4 @@
+import { ArticleService as c } from "./services/articles.js";
+export {
+  c as ArticleService
+};

package/dist/services/articles.d.ts

@@ -0,0 +1,52 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+import { articleQuerySchema } from './search-params';
+import { default as z } from 'zod';
+export interface ArticleDetails {
+    id: string;
+    title: string;
+    description: string;
+    slug: string;
+    created_at: Date;
+    updated_at: Date;
+    status: string;
+    banner_image: string | null;
+    metadata?: Record<string, any> | null;
+    tags: Array<string>;
+}
+export interface ArticleDetailsForListing {
+    id: string;
+    title: string;
+    description: string;
+    slug: string;
+    created_at: Date | string;
+    banner_image: string | null;
+}
+export interface PaginationArticleFilters {
+    limit: number;
+    offset: number;
+}
+export declare class ArticleService {
+    private db;
+    constructor(db: SupabaseClient);
+    /**
+     * Fetch a single article by slug.
+     * Includes its tags.
+     */
+    getBySlug(slug: string): Promise<ArticleDetails | null>;
+    /**
+     * Get total number of articles.
+     */
+    getCount(): Promise<number>;
+    /**
+     * Get all available tag names.
+     */
+    getTagNames(): Promise<string[]>;
+    /**
+     * Paginated list of articles with filters and sorting.
+     */
+    list(params: z.infer<typeof articleQuerySchema>): Promise<{
+        items: ArticleDetailsForListing[];
+        total: number;
+    }>;
+    getDescription(id: string): Promise<string | null>;
+}

package/dist/services/articles.js

@@ -0,0 +1,95 @@
+import { articleSortByVsQuery as _ } from "./search-params.js";
+import "zod";
+const p = 12;
+class q {
+  db;
+  constructor(r) {
+    this.db = r;
+  }
+  /**
+   * Fetch a single article by slug.
+   * Includes its tags.
+   */
+  async getBySlug(r) {
+    const { data: t, error: a } = await this.db.from("articles").select("*").eq("slug", r).eq("status", "Published").single();
+    if (a)
+      return console.error("Error fetching article details:", a.message), null;
+    const { data: c, error: s } = await this.db.from("tag_articles").select("tag_id").eq("article_id", t.id);
+    if (s)
+      return console.error(
+        "Error fetching article tag links:",
+        s.message
+      ), { ...t, tags: [] };
+    const o = c?.map((i) => i.tag_id) || [];
+    let e = [];
+    if (o.length > 0) {
+      const { data: i, error: n } = await this.db.from("tags").select("name").in("id", o);
+      n ? console.error(
+        "Error fetching article tag names:",
+        n.message
+      ) : e = i.map((l) => l.name);
+    }
+    return { ...t, tags: e };
+  }
+  /**
+   * Get total number of articles.
+   */
+  async getCount() {
+    const { data: r, error: t } = await this.db.rpc("get_table_row_count", {
+      arg_schema_name: "public",
+      arg_table_name: "articles"
+    }).single();
+    return t ? (console.error("Error fetching articles count:", t), 0) : r || 0;
+  }
+  /**
+   * Get all available tag names.
+   */
+  async getTagNames() {
+    const { data: r, error: t } = await this.db.from("tags").select("name");
+    return t ? (console.error("Error fetching tags:", t.message), []) : r?.map((a) => a.name) ?? [];
+  }
+  /**
+   * Paginated list of articles with filters and sorting.
+   */
+  async list(r) {
+    const { page: t, search: a, sortBy: c, tags: s } = r, o = _[c] ?? _.latest;
+    let e = this.db.from("articles").select("*", { count: "exact" }).eq("status", "Published");
+    if (a && (e = e.ilike("title", `%${a}%`)), s && s.length > 0) {
+      const { data: m, error: f } = await this.db.from("tags").select("id").in("name", s);
+      if (f || !m?.length)
+        return console.error("Error fetching tag IDs:", f?.message), { items: [], total: 0 };
+      const w = m.map((g) => g.id), { data: u, error: h } = await this.db.from("tag_articles").select("article_id").in("tag_id", w);
+      if (h || !u?.length)
+        return console.error(
+          "Error fetching articles by tags:",
+          h?.message
+        ), { items: [], total: 0 };
+      const b = Array.from(
+        new Set(u.map((g) => g.article_id))
+      );
+      if (b.length === 0)
+        return { items: [], total: 0 };
+      e = e.in("id", b);
+    }
+    e = e.order(o.column, { ascending: o.ascending });
+    const i = t * p, n = i + p - 1;
+    e = e.range(i, n);
+    const { data: l, error: d, count: E } = await e;
+    return d ? (console.error("Error fetching articles:", d), { items: [], total: 0 }) : {
+      items: l || [],
+      total: E || 0
+    };
+  }
+  async getDescription(r) {
+    const { data: t, error: a } = await this.db.storage.from("content").download(`articles/${r}/description.html`);
+    return a ? (console.error(
+      `Error fetching article description for article ID "${r}":`,
+      a.message
+    ), null) : t ? await t.text() : (console.warn(
+      `No article description file found for article ID: ${r}`
+    ), null);
+  }
+}
+export {
+  q as ArticleService
+};

package/dist/services/search-params.d.ts

@@ -0,0 +1,16 @@
+import { default as z } from 'zod';
+export declare const articleQuerySchema: z.ZodObject<{
+    search: z.ZodDefault<z.ZodString>;
+    page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    sortBy: z.ZodDefault<z.ZodEnum<{
+        latest: "latest";
+        oldest: "oldest";
+        "A-Z": "A-Z";
+        "Z-A": "Z-A";
+    }>>;
+    tags: z.ZodDefault<z.ZodPipe<z.ZodTransform<any[], unknown>, z.ZodArray<z.ZodString>>>;
+}, z.core.$strip>;
+export declare const articleSortByVsQuery: Record<z.infer<typeof articleQuerySchema>["sortBy"], {
+    column: string;
+    ascending: boolean;
+}>;

package/dist/services/search-params.js

@@ -0,0 +1,16 @@
+import e from "zod";
+const n = e.object({
+  search: e.string().default(""),
+  page: e.coerce.number().int().nonnegative().default(0),
+  sortBy: e.enum(["latest", "oldest", "A-Z", "Z-A"]).default("latest"),
+  tags: e.preprocess((t) => typeof t == "string" ? t.split(",").map((r) => r.trim()).filter(Boolean) : Array.isArray(t) ? t : [], e.array(e.string())).default([])
+}), s = {
+  latest: { column: "created_at", ascending: !1 },
+  oldest: { column: "created_at", ascending: !0 },
+  "A-Z": { column: "title", ascending: !0 },
+  "Z-A": { column: "title", ascending: !1 }
+};
+export {
+  n as articleQuerySchema,
+  s as articleSortByVsQuery
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@k34a/blog",
+  "description": "Create and share articles with your audience.",
+  "private": false,
+  "version": "0.0.1",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/lib/main.d.ts",
+      "default": "./dist/main.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --p ./tsconfig.lib.json --jsx react-jsx && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@mantine/core": ">=8.0.0",
+    "@mantine/dates": ">=8.0.0",
+    "@mantine/dropzone": ">=8.0.0",
+    "@mantine/notifications": ">=8.0.0",
+    "@supabase/supabase-js": ">=2.52.0",
+    "@tabler/icons-react": ">=3.0.0",
+    "react": ">=19.1.0",
+    "zod": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.36.0",
+    "@mantine/core": "^8.1.3",
+    "@mantine/dates": "^8.3.5",
+    "@mantine/dropzone": "^8.3.5",
+    "@mantine/notifications": "^8.3.5",
+    "@supabase/supabase-js": "^2.76.1",
+    "@tabler/icons-react": "^3.35.0",
+    "@types/node": "^24.6.0",
+    "@types/react": "^19.1.16",
+    "@types/react-dom": "^19.1.9",
+    "@vitejs/plugin-react": "^5.0.4",
+    "eslint": "^9.36.0",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.22",
+    "glob": "^11.0.3",
+    "globals": "^16.4.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "rollup-plugin-banner2": "^1.3.1",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.45.0",
+    "vite": "^7.1.7",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-plugin-lib-inject-css": "^2.2.2",
+    "zod": "^4.1.12"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ]
+}