@stackverify/forms 1.0.0

package/README.md

@@ -0,0 +1,319 @@
+# StackVerify Forms
+
+[![npm version](https://img.shields.io/npm/v/@stackverify/forms)](https://www.npmjs.com/package/@stackverify/forms)
+[![npm downloads](https://img.shields.io/npm/dm/@stackverify/forms)](https://www.npmjs.com/package/@stackverify/forms)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-3178C6?logo=typescript\&logoColor=white)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/npm/l/@stackverify/forms)](LICENSE)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@stackverify/forms)](https://bundlephobia.com/package/@stackverify/forms)
+
+A lightweight JavaScript and TypeScript SDK for submitting forms to StackVerify.
+
+Collect submissions from any website or application without building your own backend. Every submission is securely stored, delivered to your StackVerify dashboard, and can trigger email notifications, webhooks, WhatsApp workflows, and future automations.
+
+---
+
+## Why StackVerify Forms?
+
+Building and maintaining infrastructure for a simple contact form shouldn't slow down your product.
+
+StackVerify Forms gives you:
+
+* Instant form endpoints
+* Submission storage
+* Dashboard for managing responses
+* Email notifications
+* Webhook support
+* WhatsApp automation
+* TypeScript support
+* Framework-agnostic SDK
+* Zero runtime dependencies
+
+Instead of building APIs, databases, and notification systems, simply submit your data and let StackVerify handle the rest.
+
+---
+
+## Installation
+
+```bash
+npm install @stackverify/forms
+```
+
+```bash
+yarn add @stackverify/forms
+```
+
+```bash
+pnpm add @stackverify/forms
+```
+
+---
+
+# Quick Start
+
+Create a form from your StackVerify dashboard.
+
+You'll receive a unique Form ID.
+
+```ts
+import { submitForm } from "@stackverify/forms";
+
+await submitForm({
+    formId: "frm_xxxxxxxxx",
+    data: {
+        name: "Jane Doe",
+        email: "jane@example.com",
+        company: "Acme Inc.",
+        message: "I'd like to schedule a demo."
+    }
+});
+```
+
+Your submission is immediately available inside your StackVerify dashboard.
+
+---
+
+# React
+
+```tsx
+import { submitForm } from "@stackverify/forms";
+
+export default function ContactForm() {
+
+    async function handleSubmit(e) {
+        e.preventDefault();
+
+        const data = Object.fromEntries(
+            new FormData(e.target)
+        );
+
+        await submitForm({
+            formId: "frm_xxxxxxxxx",
+            data
+        });
+    }
+
+    return (
+        <form onSubmit={handleSubmit}>
+            <input name="name" />
+            <input name="email" />
+            <textarea name="message" />
+            <button>Send</button>
+        </form>
+    );
+}
+```
+
+---
+
+# Next.js
+
+```ts
+import { submitForm } from "@stackverify/forms";
+
+await submitForm({
+    formId: process.env.NEXT_PUBLIC_FORM_ID!,
+    data: {
+        email,
+        message
+    }
+});
+```
+
+---
+
+# Vue
+
+```ts
+import { submitForm } from "@stackverify/forms";
+
+await submitForm({
+    formId: "frm_xxxxxxxxx",
+    data: {
+        name,
+        email
+    }
+});
+```
+
+---
+
+# Svelte
+
+```ts
+import { submitForm } from "@stackverify/forms";
+
+await submitForm({
+    formId: "frm_xxxxxxxxx",
+    data
+});
+```
+
+---
+
+# Node.js
+
+```ts
+import { submitForm } from "@stackverify/forms";
+
+await submitForm({
+    formId: "frm_xxxxxxxxx",
+    data: {
+        userId: 123,
+        event: "signup"
+    }
+});
+```
+
+---
+
+# Vanilla JavaScript
+
+```js
+import { submitForm } from "@stackverify/forms";
+
+submitForm({
+    formId: "frm_xxxxxxxxx",
+    data: {
+        email: "john@example.com"
+    }
+});
+```
+
+---
+
+# HTML
+
+Every form automatically includes a public endpoint.
+
+```html
+<form action="https://stackverify.site/api/f/YOUR_FORM_ID" method="POST">
+
+    <input
+        name="name"
+        required>
+
+    <input
+        type="email"
+        name="email"
+        required>
+
+    <button type="submit">
+        Submit
+    </button>
+
+</form>
+```
+
+No backend required.
+
+---
+
+# API
+
+```ts
+submitForm({
+    formId,
+    data,
+    timeout,
+    baseUrl,
+    fetch
+});
+```
+
+| Option  | Type                | Description                 |
+| ------- | ------------------- | --------------------------- |
+| formId  | string              | StackVerify Form ID         |
+| data    | Record<string, any> | Form data                   |
+| timeout | number              | Request timeout             |
+| baseUrl | string              | Custom API URL              |
+| fetch   | Fetch               | Custom fetch implementation |
+
+---
+
+# TypeScript
+
+Built-in TypeScript definitions are included.
+
+```ts
+import type { SubmitOptions } from "@stackverify/forms";
+```
+
+---
+
+# Supported Frameworks
+
+| Frontend           | Backend            |
+| ------------------ | ------------------ |
+| React              | Node.js            |
+| Next.js            | Express            |
+| Vue                | Bun                |
+| Nuxt               | Deno               |
+| Angular            | Fastify            |
+| Svelte             | NestJS             |
+| SvelteKit          | Cloudflare Workers |
+| Astro              |                    |
+| Remix              |                    |
+| SolidJS            |                    |
+| Vite               |                    |
+| Vanilla JavaScript |                    |
+
+---
+
+# Typical Workflow
+
+```
+Application
+      │
+      ▼
+StackVerify Forms SDK
+      │
+      ▼
+StackVerify API
+      │
+      ├── Stores submissions
+      ├── Dashboard
+      ├── Email notifications
+      ├── Webhooks
+      └── Automation
+```
+
+---
+
+# Use Cases
+
+* Contact forms
+* Newsletter subscriptions
+* Lead generation
+* Landing pages
+* SaaS onboarding
+* Product orders
+* Event registration
+* Customer feedback
+* Internal business tools
+* Booking requests
+* Waitlists
+
+---
+
+# Why Use the SDK?
+
+You could send requests manually using `fetch`.
+
+The SDK provides:
+
+* Consistent API
+* TypeScript support
+* Validation
+* Better error handling
+* Cleaner code
+* Future compatibility as StackVerify evolves
+
+---
+
+# License
+
+MIT
+
+---
+
+Built for developers who want to ship forms, not infrastructure.

package/dist/index.cjs

@@ -0,0 +1,100 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  StackVerifyError: () => StackVerifyError,
+  submitForm: () => submitForm
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/utils.ts
+function toFormEncoded(data) {
+  const body = new URLSearchParams();
+  Object.entries(data).forEach(([k, v]) => {
+    if (v !== void 0 && v !== null) {
+      body.append(k, String(v));
+    }
+  });
+  return body;
+}
+
+// src/errors.ts
+var StackVerifyError = class extends Error {
+  constructor(message, options) {
+    super(message, { cause: options?.cause });
+    this.name = "StackVerifyError";
+    this.status = options?.status;
+    this.code = options?.code;
+    this.details = options?.details;
+  }
+};
+
+// src/submitForm.ts
+async function submitForm({
+  formId,
+  data,
+  baseUrl = "https://stackverify.site",
+  timeout = 1e4,
+  fetch: fetchImpl = fetch
+}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => {
+    controller.abort();
+  }, timeout);
+  try {
+    const response = await fetchImpl(
+      `${baseUrl}/api/f/${formId}`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded"
+        },
+        body: toFormEncoded(data),
+        signal: controller.signal
+      }
+    );
+    clearTimeout(timer);
+    const text = await response.text();
+    let dataResponse;
+    try {
+      dataResponse = JSON.parse(text);
+    } catch {
+      dataResponse = text;
+    }
+    if (!response.ok) {
+      throw new StackVerifyError(
+        dataResponse?.message || `Submission failed (${response.status})`
+      );
+    }
+    return dataResponse;
+  } catch (err) {
+    clearTimeout(timer);
+    if (err.name === "AbortError") {
+      throw new StackVerifyError("Request timeout");
+    }
+    throw err;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StackVerifyError,
+  submitForm
+});

package/dist/index.d.cts

@@ -0,0 +1,28 @@
+interface SubmitFormOptions {
+    formId: string;
+    data: Record<string, any>;
+    baseUrl?: string;
+    timeout?: number;
+    fetch?: typeof fetch;
+}
+declare function submitForm({ formId, data, baseUrl, timeout, fetch: fetchImpl }: SubmitFormOptions): Promise<any>;
+
+declare class StackVerifyError extends Error {
+    status?: number;
+    code?: string;
+    details?: any;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+        details?: any;
+        cause?: unknown;
+    });
+}
+
+interface SubmitOptions {
+    baseUrl?: string;
+    timeout?: number;
+    fetch?: typeof fetch;
+}
+
+export { StackVerifyError, type SubmitOptions, submitForm };

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+interface SubmitFormOptions {
+    formId: string;
+    data: Record<string, any>;
+    baseUrl?: string;
+    timeout?: number;
+    fetch?: typeof fetch;
+}
+declare function submitForm({ formId, data, baseUrl, timeout, fetch: fetchImpl }: SubmitFormOptions): Promise<any>;
+
+declare class StackVerifyError extends Error {
+    status?: number;
+    code?: string;
+    details?: any;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+        details?: any;
+        cause?: unknown;
+    });
+}
+
+interface SubmitOptions {
+    baseUrl?: string;
+    timeout?: number;
+    fetch?: typeof fetch;
+}
+
+export { StackVerifyError, type SubmitOptions, submitForm };

package/dist/index.js

@@ -0,0 +1,72 @@
+// src/utils.ts
+function toFormEncoded(data) {
+  const body = new URLSearchParams();
+  Object.entries(data).forEach(([k, v]) => {
+    if (v !== void 0 && v !== null) {
+      body.append(k, String(v));
+    }
+  });
+  return body;
+}
+
+// src/errors.ts
+var StackVerifyError = class extends Error {
+  constructor(message, options) {
+    super(message, { cause: options?.cause });
+    this.name = "StackVerifyError";
+    this.status = options?.status;
+    this.code = options?.code;
+    this.details = options?.details;
+  }
+};
+
+// src/submitForm.ts
+async function submitForm({
+  formId,
+  data,
+  baseUrl = "https://stackverify.site",
+  timeout = 1e4,
+  fetch: fetchImpl = fetch
+}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => {
+    controller.abort();
+  }, timeout);
+  try {
+    const response = await fetchImpl(
+      `${baseUrl}/api/f/${formId}`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded"
+        },
+        body: toFormEncoded(data),
+        signal: controller.signal
+      }
+    );
+    clearTimeout(timer);
+    const text = await response.text();
+    let dataResponse;
+    try {
+      dataResponse = JSON.parse(text);
+    } catch {
+      dataResponse = text;
+    }
+    if (!response.ok) {
+      throw new StackVerifyError(
+        dataResponse?.message || `Submission failed (${response.status})`
+      );
+    }
+    return dataResponse;
+  } catch (err) {
+    clearTimeout(timer);
+    if (err.name === "AbortError") {
+      throw new StackVerifyError("Request timeout");
+    }
+    throw err;
+  }
+}
+export {
+  StackVerifyError,
+  submitForm
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@stackverify/forms",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "API-first form, lead & order collection SDK. Works on Vercel, React, Next.js, and any frontend framework. No backend required.",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "forms",
+    "leads",
+    "orders",
+    "api",
+    "serverless",
+    "vercel",
+    "frontend",
+    "no-backend",
+    "saas",
+    "webhooks"
+  ],
+  "author": "StackVerify",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stackmorgan/stackmorgan-forms"
+  },
+  "homepage": "https://stackverify.site/forms",
+  "bugs": {
+    "url": "https://stackverify.site/contact"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@stackverify/forms": "file:stackverify-forms-1.0.0.tgz"
+  }
+}